platform/packages/mirrors/README.md

Platform Reflection

A powerful cross-platform reflection system for Dart that serves as a drop-in replacement for dart:mirrors. This implementation offers a carefully balanced approach between functionality and performance, providing reflection capabilities with AOT compilation support.

Table of Contents

• Features
• Installation
• Usage
• API Reference
• Performance Considerations
• Limitations
• Migration from dart:mirrors
• Contributing
• License

Features

• ✅ Platform independent reflection system
• ✅ AOT compilation support
• ✅ No dependency on dart:mirrors
• ✅ Class reflection with inheritance
• ✅ Method invocation with named parameters
• ✅ Property access and mutation
• ✅ Constructor resolution and invocation
• ✅ Type introspection and relationships
• ✅ Explicit registration for performance
• ✅ Basic generic type support
• ✅ Comprehensive error handling

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  platform_reflection: ^0.1.0

Usage

Registration

Unlike dart:mirrors, Platform Reflection requires explicit registration of classes and their members. This enables AOT compilation support and fine-grained control over reflection.

@reflectable
class User {
  String name;
  int age;
  final String id;
  List<String> tags;

  User(this.name, this.age, {required this.id, List<String>? tags})
      : tags = tags ?? [];

  String greet() => "Hi $name!";
  
  void addTag(String tag) {
    tags.add(tag);
  }

  String getName() => name;
}

void registerUser() {
  Reflector.register(User);
  Reflector.registerProperty(User, 'name', String);
  Reflector.registerProperty(User, 'age', int);
  Reflector.registerProperty(User, 'id', String, isWritable: false);
  Reflector.registerProperty(User, 'tags', List<String>, isWritable: false);
  
  Reflector.registerMethod(User, 'greet', [], false);
  Reflector.registerMethod(User, 'addTag', [String], true);
  Reflector.registerMethod(User, 'getName', [], false);
  
  Reflector.registerConstructor(
    User,
    '',
    parameterTypes: [String, int, String, List<String>],
    parameterNames: ['name', 'age', 'id', 'tags'],
    isRequired: [true, true, true, false],
    isNamed: [false, false, true, true],
  );
}

Reflection Operations

void demonstrateReflection() {
  final reflector = RuntimeReflector.instance;
  
  // Create instance
  final user = reflector.createInstance(
    User,
    positionalArgs: ['John Doe', 30],
    namedArgs: {'id': 'user1', 'tags': ['admin', 'user']},
  ) as User;
  
  // Get mirror
  final mirror = reflector.reflect(user);
  
  // Property access
  final name = mirror.getField(const Symbol('name')).reflectee as String;
  
  // Property modification
  mirror.setField(const Symbol('age'), 25);
  
  // Method invocation
  final greeting = mirror.invoke(const Symbol('greet'), []).reflectee as String;
  
  // Type information
  final classMirror = reflector.reflectClass(User);
  print('Type name: ${classMirror.name}');
  
  // Type relationships
  final entityType = reflector.reflectType(Entity);
  print('User is subtype of Entity: ${classMirror.isSubclassOf(entityType)}');
}

API Reference

Core Classes

• Reflector: Static class for registration and metadata management
• RuntimeReflector: Runtime reflection operations

Mirrors

• InstanceMirror: Instance reflection
• ClassMirror: Class reflection
• MethodMirror: Method reflection
• LibraryMirror: Library reflection
• TypeMirror: Type reflection

Metadata

• TypeMetadata: Type information
• PropertyMetadata: Property information
• MethodMetadata: Method information
• ConstructorMetadata: Constructor information

Exceptions

• ReflectionException: Base exception for reflection errors
• NotReflectableException: Thrown when attempting to reflect on an unregistered type

Performance Considerations

• Explicit registration adds startup cost but improves runtime performance
• Cached class mirrors for efficient repeated use
• Minimal metadata storage for reduced memory footprint
• AOT compilation support allows for better optimization

Limitations

• Requires explicit registration of reflectable types and members
• Limited support for complex generic types
• No support for extension methods
• No cross-package private member access

Migration from dart:mirrors

To migrate from dart:mirrors to Platform Reflection:

1. Replace import 'dart:mirrors' with import 'package:platform_reflection/mirrors.dart'.
2. Add @reflectable annotation to classes you want to reflect on.
3. Implement a registration function for each reflectable class.
4. Call registration functions at the start of your application.
5. Replace MirrorSystem.reflect() with RuntimeReflector.instance.reflect().
6. Update any code that relies on automatic discovery of classes or members.

Contributing

Contributions are welcome! Please see our Contributing Guidelines for more details.

License

This project is licensed under the MIT License - see the LICENSE file for details.