platform/incubation/reflection/doc/capabilities.md

Platform Reflection Capabilities

Core Reflection Features

1. Library Reflection

// Library reflection support
final library = LibraryMirrorImpl.withDeclarations(
  name: 'my_library',
  uri: Uri.parse('package:my_package/my_library.dart'),
);

// Access top-level members
final greeting = library.getField(const Symbol('greeting')).reflectee;
final sum = library.invoke(
  const Symbol('add'),
  [1, 2],
).reflectee;

2. Isolate Support

// Current isolate reflection
final current = IsolateMirrorImpl.current(rootLibrary);

// Other isolate reflection
final other = IsolateMirrorImpl.other(
  isolate,
  'worker',
  rootLibrary,
);

// Isolate control
await other.pause();
await other.resume();
await other.kill();

// Error handling
other.addErrorListener((error, stack) {
  print('Error in isolate: $error\n$stack');
});

// Exit handling
other.addExitListener((message) {
  print('Isolate exited with: $message');
});

3. Type System

// Special types
final voidType = VoidType.instance;
final dynamicType = DynamicType.instance;
final neverType = NeverType.instance;

// Type checking
final isVoid = type.isVoid;
final isDynamic = type.isDynamic;
final isNever = type.isNever;

4. Metadata System

// Parameter metadata
final param = ParameterMetadata(
  name: 'id',
  type: int,
  isRequired: true,
  isNamed: false,
  defaultValue: 0,
  attributes: [deprecated],
);

// Property metadata
final prop = PropertyMetadata(
  name: 'name',
  type: String,
  isReadable: true,
  isWritable: true,
  attributes: [override],
);

// Method metadata
final method = MethodMetadata(
  name: 'calculate',
  parameterTypes: [int, double],
  parameters: [...],
  isStatic: false,
  returnsVoid: false,
  attributes: [deprecated],
);

5. Constructor Support

// Constructor metadata
final ctor = ConstructorMetadata(
  name: 'named',
  parameterTypes: [String, int],
  parameters: [...],
  parameterNames: ['name', 'age'],
  attributes: [...],
);

// Validation
final valid = ctor.validateArguments(['John', 42]);

6. Type Metadata

// Full type information
final type = TypeMetadata(
  type: User,
  name: 'User',
  properties: {...},
  methods: {...},
  constructors: [...],
  supertype: Person,
  interfaces: [Comparable],
  attributes: [serializable],
);

// Member access
final prop = type.getProperty('name');
final method = type.getMethod('greet');
final ctor = type.getConstructor('guest');

Advanced Features

1. Library Dependencies

final deps = library.libraryDependencies;
for (var dep in deps) {
  if (dep.isImport) {
    print('Imports: ${dep.targetLibrary?.uri}');
  }
}

2. Declaration Access

final decls = library.declarations;
for (var decl in decls.values) {
  if (decl is MethodMirror) {
    print('Method: ${decl.simpleName}');
  } else if (decl is VariableMirror) {
    print('Variable: ${decl.simpleName}');
  }
}

3. Function Metadata

final func = FunctionMetadata(
  parameters: [...],
  returnsVoid: false,
  returnType: int,
);

final valid = func.validateArguments([1, 2.0]);

4. Reflection Registry

// Type registration
ReflectionRegistry.registerType(User);

// Member registration
ReflectionRegistry.registerProperty(
  User,
  'name',
  String,
  isReadable: true,
  isWritable: true,
);

ReflectionRegistry.registerMethod(
  User,
  'greet',
  [String],
  false,
);

ReflectionRegistry.registerConstructor(
  User,
  'guest',
  factory,
);

Error Handling

try {
  // Reflection operations
} on MemberNotFoundException catch (e) {
  print('Member not found: ${e.memberName} on ${e.type}');
} on InvalidArgumentsException catch (e) {
  print('Invalid arguments for ${e.memberName}');
} on ReflectionException catch (e) {
  print('Reflection error: ${e.message}');
}

Platform Support

• ✅ VM (Full support)
• ✅ Web (Full support)
• ✅ Flutter (Full support)
• ✅ AOT compilation (Full support)

Performance Considerations

1. Registration Impact

   • One-time registration cost
   • Optimized runtime performance
   • Minimal memory overhead

2. Metadata Caching

   • Efficient metadata storage
   • Fast lookup mechanisms
   • Memory-conscious design

3. Cross-isolate Performance

   • Minimal serialization overhead
   • Efficient isolate communication
   • Controlled resource usage

Security Features

1. Access Control

   • Controlled reflection surface
   • Explicit registration required
   • Member visibility respect

2. Type Safety

   • Strong type checking
   • Argument validation
   • Return type verification

3. Isolate Safety

   • Controlled isolate access
   • Error propagation
   • Resource cleanup

Best Practices

1. Registration

   // Register early
   void main() {
     registerTypes();
     runApp();
   }
   

2. Metadata Usage

   // Cache metadata
   final metadata = Reflector.getTypeMetadata(User);
   final properties = metadata.properties;
   final methods = metadata.methods;
   

3. Error Handling

   // Comprehensive error handling
   try {
     final result = mirror.invoke(name, args);
   } on ReflectionException catch (e) {
     handleError(e);
   }
   

4. Isolate Management

   // Proper cleanup
   final isolate = IsolateMirrorImpl.other(...);
   try {
     await doWork(isolate);
   } finally {
     await isolate.kill();
   }
   

This document provides a comprehensive overview of the Platform Reflection library's capabilities. For detailed API documentation, see the API Reference.