add: adding package docs
This commit is contained in:
Patrick Stewart
parent
c13657e88c
commit
3cb8feb43e
8 changed files with 2119 additions and 133 deletions
|
|
@ -1,40 +1,167 @@
|
|||
# Platform Reflection
|
||||
|
||||
A lightweight, cross-platform reflection system for Dart that provides runtime type introspection and manipulation with an API similar to `dart:mirrors` but without its limitations.
|
||||
A powerful cross-platform reflection system for Dart that provides runtime type introspection and manipulation. This implementation offers a carefully balanced approach between functionality and performance, providing reflection capabilities without the limitations of `dart:mirrors`.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Features](#features)
|
||||
- [Architecture](#architecture)
|
||||
- [Installation](#installation)
|
||||
- [Core Components](#core-components)
|
||||
- [Usage Guide](#usage-guide)
|
||||
- [Advanced Usage](#advanced-usage)
|
||||
- [Performance Considerations](#performance-considerations)
|
||||
- [Migration Guide](#migration-guide)
|
||||
- [API Reference](#api-reference)
|
||||
- [Limitations](#limitations)
|
||||
- [Contributing](#contributing)
|
||||
- [License](#license)
|
||||
|
||||
## Features
|
||||
|
||||
- ✅ Works on all platforms (Web, Mobile, Desktop)
|
||||
### Core Features
|
||||
- ✅ Platform independent reflection system
|
||||
- ✅ No dependency on `dart:mirrors`
|
||||
- ✅ Pure runtime reflection
|
||||
- ✅ No code generation required
|
||||
- ✅ No manual registration needed
|
||||
- ✅ Complete mirror-based API
|
||||
- ✅ Type-safe property access
|
||||
- ✅ Method invocation with argument validation
|
||||
- ✅ Constructor invocation support
|
||||
- ✅ Library and isolate reflection
|
||||
- ✅ Full MirrorSystem implementation
|
||||
- ✅ Explicit registration for performance
|
||||
- ✅ Type-safe operations
|
||||
- ✅ Comprehensive error handling
|
||||
|
||||
## Installation
|
||||
### Reflection Capabilities
|
||||
- ✅ Class reflection
|
||||
- ✅ Method invocation
|
||||
- ✅ Property access/mutation
|
||||
- ✅ Constructor invocation
|
||||
- ✅ Type introspection
|
||||
- ✅ Basic metadata support
|
||||
- ✅ Parameter inspection
|
||||
- ✅ Type relationship checking
|
||||
|
||||
Add this to your package's `pubspec.yaml` file:
|
||||
### Performance Features
|
||||
- ✅ Optimized metadata storage
|
||||
- ✅ Efficient lookup mechanisms
|
||||
- ✅ Minimal runtime overhead
|
||||
- ✅ Memory-efficient design
|
||||
- ✅ Lazy initialization support
|
||||
|
||||
## Architecture
|
||||
|
||||
### Core Components
|
||||
|
||||
```
|
||||
platform_reflection/
|
||||
├── core/
|
||||
│ ├── reflector.dart # Central reflection management
|
||||
│ ├── scanner.dart # Type scanning and analysis
|
||||
│ └── runtime_reflector.dart # Runtime reflection implementation
|
||||
├── metadata/
|
||||
│ ├── type_metadata.dart # Type information storage
|
||||
│ ├── method_metadata.dart # Method metadata handling
|
||||
│ └── property_metadata.dart # Property metadata handling
|
||||
├── mirrors/
|
||||
│ ├── class_mirror.dart # Class reflection implementation
|
||||
│ ├── instance_mirror.dart # Instance reflection handling
|
||||
│ └── method_mirror.dart # Method reflection support
|
||||
└── exceptions/
|
||||
└── reflection_exceptions.dart # Error handling
|
||||
```
|
||||
|
||||
### Design Principles
|
||||
|
||||
1. **Explicit Registration**
|
||||
- Clear registration of reflectable types
|
||||
- Controlled reflection surface
|
||||
- Optimized runtime performance
|
||||
|
||||
2. **Type Safety**
|
||||
- Strong type checking
|
||||
- Compile-time validations
|
||||
- Runtime type verification
|
||||
|
||||
3. **Performance First**
|
||||
- Minimal runtime overhead
|
||||
- Efficient metadata storage
|
||||
- Optimized lookup mechanisms
|
||||
|
||||
4. **Platform Independence**
|
||||
- Cross-platform compatibility
|
||||
- No platform-specific dependencies
|
||||
- Consistent behavior
|
||||
|
||||
## Installation
|
||||
|
||||
```yaml
|
||||
dependencies:
|
||||
platform_reflection: ^0.1.0
|
||||
```
|
||||
|
||||
## Usage
|
||||
## Core Components
|
||||
|
||||
### Basic Reflection
|
||||
### Reflector
|
||||
|
||||
Simply mark your class with `@reflectable`:
|
||||
Central management class for reflection operations:
|
||||
|
||||
```dart
|
||||
import 'package:platform_reflection/reflection.dart';
|
||||
class Reflector {
|
||||
// Type registration
|
||||
static void register(Type type);
|
||||
static void registerProperty(Type type, String name, Type propertyType);
|
||||
static void registerMethod(Type type, String name, List<Type> parameterTypes);
|
||||
static void registerConstructor(Type type, String name, {Function? creator});
|
||||
|
||||
// Metadata access
|
||||
static TypeMetadata? getTypeMetadata(Type type);
|
||||
static Map<String, PropertyMetadata>? getPropertyMetadata(Type type);
|
||||
static Map<String, MethodMetadata>? getMethodMetadata(Type type);
|
||||
|
||||
// Utility methods
|
||||
static void reset();
|
||||
static bool isReflectable(Type type);
|
||||
}
|
||||
```
|
||||
|
||||
### Scanner
|
||||
|
||||
Automatic metadata extraction and analysis:
|
||||
|
||||
```dart
|
||||
class Scanner {
|
||||
// Scanning operations
|
||||
static void scanType(Type type);
|
||||
static TypeMetadata getTypeMetadata(Type type);
|
||||
|
||||
// Analysis methods
|
||||
static TypeInfo analyze(Type type);
|
||||
static List<PropertyInfo> analyzeProperties(Type type);
|
||||
static List<MethodInfo> analyzeMethods(Type type);
|
||||
}
|
||||
```
|
||||
|
||||
### RuntimeReflector
|
||||
|
||||
Runtime reflection implementation:
|
||||
|
||||
```dart
|
||||
class RuntimeReflector {
|
||||
// Instance creation
|
||||
InstanceMirror createInstance(Type type, {
|
||||
List<dynamic>? positionalArgs,
|
||||
Map<Symbol, dynamic>? namedArgs,
|
||||
String? constructorName,
|
||||
});
|
||||
|
||||
// Reflection operations
|
||||
InstanceMirror reflect(Object object);
|
||||
ClassMirror reflectClass(Type type);
|
||||
TypeMirror reflectType(Type type);
|
||||
}
|
||||
```
|
||||
|
||||
## Usage Guide
|
||||
|
||||
### Basic Registration
|
||||
|
||||
```dart
|
||||
@reflectable
|
||||
class User {
|
||||
String name;
|
||||
|
|
@ -48,146 +175,334 @@ class User {
|
|||
}
|
||||
|
||||
String greet(String greeting) {
|
||||
return '$greeting, $name!';
|
||||
return '$greeting $name!';
|
||||
}
|
||||
}
|
||||
|
||||
// Register class and members
|
||||
void registerUser() {
|
||||
Reflector.register(User);
|
||||
|
||||
// Register properties
|
||||
Reflector.registerProperty(User, 'name', String);
|
||||
Reflector.registerProperty(User, 'age', int);
|
||||
Reflector.registerProperty(User, 'id', String, isWritable: false);
|
||||
|
||||
// Register methods
|
||||
Reflector.registerMethod(
|
||||
User,
|
||||
'birthday',
|
||||
[],
|
||||
true,
|
||||
parameterNames: [],
|
||||
isRequired: [],
|
||||
);
|
||||
|
||||
Reflector.registerMethod(
|
||||
User,
|
||||
'greet',
|
||||
[String],
|
||||
false,
|
||||
parameterNames: ['greeting'],
|
||||
isRequired: [true],
|
||||
);
|
||||
|
||||
// Register constructor
|
||||
Reflector.registerConstructor(
|
||||
User,
|
||||
'',
|
||||
parameterTypes: [String, int, String],
|
||||
parameterNames: ['name', 'age', 'id'],
|
||||
isRequired: [true, true, true],
|
||||
isNamed: [false, false, true],
|
||||
creator: (String name, int age, {required String id}) =>
|
||||
User(name, age, id: id),
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Instance Manipulation
|
||||
|
||||
```dart
|
||||
void manipulateInstance() {
|
||||
final reflector = RuntimeReflector.instance;
|
||||
|
||||
// Create instance
|
||||
final user = reflector.createInstance(
|
||||
User,
|
||||
positionalArgs: ['John', 30],
|
||||
namedArgs: {const Symbol('id'): '123'},
|
||||
) as User;
|
||||
|
||||
// Get mirror
|
||||
final mirror = reflector.reflect(user);
|
||||
|
||||
// Property access
|
||||
final name = mirror.getField(const Symbol('name')).reflectee as String;
|
||||
final age = mirror.getField(const Symbol('age')).reflectee as int;
|
||||
|
||||
// Property modification
|
||||
mirror.setField(const Symbol('name'), 'Jane');
|
||||
mirror.setField(const Symbol('age'), 31);
|
||||
|
||||
// Method invocation
|
||||
mirror.invoke(const Symbol('birthday'), []);
|
||||
final greeting = mirror.invoke(
|
||||
const Symbol('greet'),
|
||||
['Hello'],
|
||||
).reflectee as String;
|
||||
}
|
||||
```
|
||||
|
||||
### Type Introspection
|
||||
|
||||
```dart
|
||||
void inspectType() {
|
||||
final metadata = Reflector.getTypeMetadata(User);
|
||||
|
||||
// Property inspection
|
||||
for (var property in metadata.properties.values) {
|
||||
print('Property: ${property.name}');
|
||||
print(' Type: ${property.type}');
|
||||
print(' Writable: ${property.isWritable}');
|
||||
print(' Static: ${property.isStatic}');
|
||||
}
|
||||
|
||||
// Method inspection
|
||||
for (var method in metadata.methods.values) {
|
||||
print('Method: ${method.name}');
|
||||
print(' Return type: ${method.returnType}');
|
||||
print(' Parameters:');
|
||||
for (var param in method.parameters) {
|
||||
print(' ${param.name}: ${param.type}');
|
||||
print(' Required: ${param.isRequired}');
|
||||
print(' Named: ${param.isNamed}');
|
||||
}
|
||||
}
|
||||
|
||||
// Constructor inspection
|
||||
for (var ctor in metadata.constructors) {
|
||||
print('Constructor: ${ctor.name}');
|
||||
print(' Parameters:');
|
||||
for (var param in ctor.parameters) {
|
||||
print(' ${param.name}: ${param.type}');
|
||||
print(' Required: ${param.isRequired}');
|
||||
print(' Named: ${param.isNamed}');
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Then use reflection directly:
|
||||
### Scanner Usage
|
||||
|
||||
```dart
|
||||
// Get the reflector instance
|
||||
final reflector = RuntimeReflector.instance;
|
||||
|
||||
// Create instance using reflection
|
||||
final user = reflector.createInstance(
|
||||
User,
|
||||
positionalArgs: ['John', 30],
|
||||
namedArgs: {'id': '123'},
|
||||
) as User;
|
||||
|
||||
// Get instance mirror
|
||||
final mirror = reflector.reflect(user);
|
||||
|
||||
// Access properties
|
||||
print(mirror.getField(const Symbol('name')).reflectee); // John
|
||||
print(mirror.getField(const Symbol('age')).reflectee); // 30
|
||||
|
||||
// Modify properties
|
||||
mirror.setField(const Symbol('name'), 'Jane');
|
||||
mirror.setField(const Symbol('age'), 25);
|
||||
|
||||
// Invoke methods
|
||||
mirror.invoke(const Symbol('birthday'), []);
|
||||
final greeting = mirror.invoke(const Symbol('greet'), ['Hello']).reflectee;
|
||||
print(greeting); // Hello, Jane!
|
||||
```
|
||||
|
||||
### Type Information
|
||||
|
||||
```dart
|
||||
// Get mirror system
|
||||
final mirrors = reflector.currentMirrorSystem;
|
||||
|
||||
// Get type mirror
|
||||
final typeMirror = mirrors.reflectType(User);
|
||||
|
||||
// Access type information
|
||||
print(typeMirror.name); // User
|
||||
print(typeMirror.properties); // {name: PropertyMetadata(...), age: PropertyMetadata(...)}
|
||||
print(typeMirror.methods); // {birthday: MethodMetadata(...), greet: MethodMetadata(...)}
|
||||
|
||||
// Check type relationships
|
||||
if (typeMirror.isSubtypeOf(otherType)) {
|
||||
print('User is a subtype');
|
||||
}
|
||||
|
||||
// Get declarations
|
||||
final declarations = typeMirror.declarations;
|
||||
for (var member in declarations.values) {
|
||||
if (member is MethodMirror) {
|
||||
print('Method: ${member.simpleName}');
|
||||
} else if (member is VariableMirror) {
|
||||
print('Variable: ${member.simpleName}');
|
||||
void useScannerFeatures() {
|
||||
// Scan type
|
||||
Scanner.scanType(User);
|
||||
|
||||
// Get scanned metadata
|
||||
final metadata = Scanner.getTypeMetadata(User);
|
||||
|
||||
// Analyze type structure
|
||||
final typeInfo = Scanner.analyze(User);
|
||||
|
||||
// Property analysis
|
||||
final properties = typeInfo.properties;
|
||||
for (var prop in properties) {
|
||||
print('Property: ${prop.name}');
|
||||
print(' Type: ${prop.type}');
|
||||
print(' Final: ${prop.isFinal}');
|
||||
}
|
||||
}
|
||||
|
||||
// Access special types
|
||||
print(mirrors.dynamicType.name); // dynamic
|
||||
print(mirrors.voidType.name); // void
|
||||
print(mirrors.neverType.name); // Never
|
||||
```
|
||||
|
||||
### Library Reflection
|
||||
|
||||
```dart
|
||||
// Get a library
|
||||
final library = mirrors.findLibrary(const Symbol('package:myapp/src/models.dart'));
|
||||
|
||||
// Access library members
|
||||
final declarations = library.declarations;
|
||||
for (var decl in declarations.values) {
|
||||
print('Declaration: ${decl.simpleName}');
|
||||
}
|
||||
|
||||
// Check imports
|
||||
for (var dep in library.libraryDependencies) {
|
||||
if (dep.isImport) {
|
||||
print('Imports: ${dep.targetLibrary?.uri}');
|
||||
|
||||
// Method analysis
|
||||
final methods = typeInfo.methods;
|
||||
for (var method in methods) {
|
||||
print('Method: ${method.name}');
|
||||
print(' Return type: ${method.returnType}');
|
||||
print(' Static: ${method.isStatic}');
|
||||
print(' Parameters: ${method.parameters}');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Isolate Reflection
|
||||
## Advanced Usage
|
||||
|
||||
### Generic Type Handling
|
||||
|
||||
```dart
|
||||
// Get current isolate
|
||||
final currentIsolate = mirrors.isolate;
|
||||
print('Current isolate: ${currentIsolate.debugName}');
|
||||
@reflectable
|
||||
class Container<T> {
|
||||
T value;
|
||||
Container(this.value);
|
||||
}
|
||||
|
||||
// Reflect on another isolate
|
||||
final isolate = await Isolate.spawn(workerFunction, message);
|
||||
final isolateMirror = reflector.reflectIsolate(isolate, 'worker');
|
||||
|
||||
// Control isolate
|
||||
await isolateMirror.pause();
|
||||
await isolateMirror.resume();
|
||||
await isolateMirror.kill();
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
The package provides specific exceptions for different error cases:
|
||||
|
||||
- `NotReflectableException`: Thrown when attempting to reflect on a non-reflectable type
|
||||
- `ReflectionException`: Base class for reflection-related errors
|
||||
- `InvalidArgumentsException`: Thrown when providing invalid arguments to a method or constructor
|
||||
- `MemberNotFoundException`: Thrown when a property or method is not found
|
||||
|
||||
```dart
|
||||
try {
|
||||
reflect(NonReflectableClass());
|
||||
} catch (e) {
|
||||
print(e); // NotReflectableException: Type NonReflectableClass is not reflectable
|
||||
void handleGenericType() {
|
||||
Reflector.register(Container);
|
||||
|
||||
// Register with specific type
|
||||
final stringContainer = reflector.createInstance(
|
||||
Container,
|
||||
positionalArgs: ['Hello'],
|
||||
) as Container<String>;
|
||||
|
||||
final mirror = reflector.reflect(stringContainer);
|
||||
final value = mirror.getField(const Symbol('value')).reflectee as String;
|
||||
}
|
||||
```
|
||||
|
||||
## Design Philosophy
|
||||
### Error Handling
|
||||
|
||||
This package provides a reflection API that closely mirrors the design of `dart:mirrors` while being:
|
||||
```dart
|
||||
void demonstrateErrorHandling() {
|
||||
try {
|
||||
// Attempt to reflect unregistered type
|
||||
reflector.reflect(UnregisteredClass());
|
||||
} on NotReflectableException catch (e) {
|
||||
print('Type not registered: $e');
|
||||
}
|
||||
|
||||
try {
|
||||
// Attempt to access non-existent member
|
||||
final mirror = reflector.reflect(user);
|
||||
mirror.getField(const Symbol('nonexistent'));
|
||||
} on MemberNotFoundException catch (e) {
|
||||
print('Member not found: $e');
|
||||
}
|
||||
|
||||
try {
|
||||
// Attempt invalid method invocation
|
||||
final mirror = reflector.reflect(user);
|
||||
mirror.invoke(const Symbol('greet'), [42]); // Wrong argument type
|
||||
} on InvalidArgumentsException catch (e) {
|
||||
print('Invalid arguments: $e');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- Platform independent
|
||||
- Lightweight
|
||||
- Type-safe
|
||||
- Performant
|
||||
- Easy to use
|
||||
## Performance Considerations
|
||||
|
||||
The implementation uses pure Dart runtime scanning to provide reflection capabilities across all platforms without requiring code generation or manual registration.
|
||||
### Registration Impact
|
||||
|
||||
- Explicit registration adds startup cost
|
||||
- Improved runtime performance
|
||||
- Reduced memory usage
|
||||
- Controlled reflection surface
|
||||
|
||||
### Optimization Techniques
|
||||
|
||||
1. **Lazy Loading**
|
||||
```dart
|
||||
// Only register when needed
|
||||
if (Reflector.getTypeMetadata(User) == null) {
|
||||
registerUser();
|
||||
}
|
||||
```
|
||||
|
||||
2. **Metadata Caching**
|
||||
```dart
|
||||
// Cache metadata access
|
||||
final metadata = Reflector.getTypeMetadata(User);
|
||||
final properties = metadata.properties;
|
||||
final methods = metadata.methods;
|
||||
```
|
||||
|
||||
3. **Instance Reuse**
|
||||
```dart
|
||||
// Reuse instance mirrors
|
||||
final mirror = reflector.reflect(user);
|
||||
// Store mirror for repeated use
|
||||
```
|
||||
|
||||
### Memory Management
|
||||
|
||||
- Metadata storage optimization
|
||||
- Instance mirror lifecycle management
|
||||
- Cache invalidation strategies
|
||||
|
||||
## Migration Guide
|
||||
|
||||
### From dart:mirrors
|
||||
|
||||
```dart
|
||||
// Old dart:mirrors code
|
||||
import 'dart:mirrors';
|
||||
|
||||
final mirror = reflect(instance);
|
||||
final value = mirror.getField(#propertyName).reflectee;
|
||||
|
||||
// New platform_reflection code
|
||||
import 'package:platform_reflection/reflection.dart';
|
||||
|
||||
final mirror = reflector.reflect(instance);
|
||||
final value = mirror.getField(const Symbol('propertyName')).reflectee;
|
||||
```
|
||||
|
||||
### Registration Requirements
|
||||
|
||||
```dart
|
||||
// Add registration code
|
||||
void registerTypes() {
|
||||
Reflector.register(MyClass);
|
||||
Reflector.registerProperty(MyClass, 'property', String);
|
||||
Reflector.registerMethod(MyClass, 'method', [int]);
|
||||
}
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
### Core Classes
|
||||
|
||||
- `Reflector`: Central reflection management
|
||||
- `Scanner`: Metadata extraction
|
||||
- `RuntimeReflector`: Runtime reflection operations
|
||||
|
||||
### Mirrors
|
||||
|
||||
- `InstanceMirror`: Instance reflection
|
||||
- `ClassMirror`: Class reflection
|
||||
- `MethodMirror`: Method reflection
|
||||
|
||||
### Metadata
|
||||
|
||||
- `TypeMetadata`: Type information
|
||||
- `PropertyMetadata`: Property information
|
||||
- `MethodMetadata`: Method information
|
||||
|
||||
### Exceptions
|
||||
|
||||
- `NotReflectableException`
|
||||
- `ReflectionException`
|
||||
- `InvalidArgumentsException`
|
||||
- `MemberNotFoundException`
|
||||
|
||||
## Limitations
|
||||
|
||||
Current Implementation Gaps:
|
||||
|
||||
1. **Type System**
|
||||
- Limited generic support
|
||||
- No variance handling
|
||||
- Basic type relationship checking
|
||||
|
||||
2. **Reflection Features**
|
||||
- No cross-isolate reflection
|
||||
- No source location tracking
|
||||
- Limited metadata capabilities
|
||||
|
||||
3. **Language Features**
|
||||
- No extension method support
|
||||
- No mixin composition
|
||||
- No operator overloading reflection
|
||||
|
||||
4. **Advanced Features**
|
||||
- No dynamic proxy generation
|
||||
- No attribute-based reflection
|
||||
- Limited annotation processing
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are welcome! Please read our [contributing guidelines](CONTRIBUTING.md) before submitting pull requests.
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines.
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
||||
MIT License - see [LICENSE](LICENSE) for details.
|
||||
|
|
|
|||
287
packages/reflection/doc/capabilities.md
Normal file
287
packages/reflection/doc/capabilities.md
Normal file
|
|
@ -0,0 +1,287 @@
|
|||
# Platform Reflection Capabilities
|
||||
|
||||
## Core Reflection Features
|
||||
|
||||
### 1. Library Reflection
|
||||
```dart
|
||||
// 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
|
||||
```dart
|
||||
// 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
|
||||
```dart
|
||||
// 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
|
||||
```dart
|
||||
// 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
|
||||
```dart
|
||||
// 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
|
||||
```dart
|
||||
// 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
|
||||
```dart
|
||||
final deps = library.libraryDependencies;
|
||||
for (var dep in deps) {
|
||||
if (dep.isImport) {
|
||||
print('Imports: ${dep.targetLibrary?.uri}');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Declaration Access
|
||||
```dart
|
||||
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
|
||||
```dart
|
||||
final func = FunctionMetadata(
|
||||
parameters: [...],
|
||||
returnsVoid: false,
|
||||
returnType: int,
|
||||
);
|
||||
|
||||
final valid = func.validateArguments([1, 2.0]);
|
||||
```
|
||||
|
||||
### 4. Reflection Registry
|
||||
```dart
|
||||
// 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
|
||||
|
||||
```dart
|
||||
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**
|
||||
```dart
|
||||
// Register early
|
||||
void main() {
|
||||
registerTypes();
|
||||
runApp();
|
||||
}
|
||||
```
|
||||
|
||||
2. **Metadata Usage**
|
||||
```dart
|
||||
// Cache metadata
|
||||
final metadata = Reflector.getTypeMetadata(User);
|
||||
final properties = metadata.properties;
|
||||
final methods = metadata.methods;
|
||||
```
|
||||
|
||||
3. **Error Handling**
|
||||
```dart
|
||||
// Comprehensive error handling
|
||||
try {
|
||||
final result = mirror.invoke(name, args);
|
||||
} on ReflectionException catch (e) {
|
||||
handleError(e);
|
||||
}
|
||||
```
|
||||
|
||||
4. **Isolate Management**
|
||||
```dart
|
||||
// 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](../README.md#api-reference).
|
||||
109
packages/reflection/doc/index.md
Normal file
109
packages/reflection/doc/index.md
Normal file
|
|
@ -0,0 +1,109 @@
|
|||
# Platform Reflection Documentation
|
||||
|
||||
## Overview
|
||||
Platform Reflection is a modern reflection system for Dart that provides runtime type introspection and manipulation capabilities across all platforms.
|
||||
|
||||
## Documentation Structure
|
||||
|
||||
### Core Documentation
|
||||
- [README](../README.md) - Overview, installation, and basic usage
|
||||
- [Quick Start Guide](quick_start.md) - Get started quickly with common use cases
|
||||
- [Technical Specification](technical_specification.md) - Detailed implementation details
|
||||
- [Mirrors Comparison](mirrors_comparison.md) - Feature comparison with dart:mirrors
|
||||
- [Development Roadmap](roadmap.md) - Future plans and development direction
|
||||
|
||||
### API Documentation
|
||||
- [API Reference](../README.md#api-reference) - Complete API documentation
|
||||
- [Core Components](technical_specification.md#core-components) - Core system components
|
||||
- [Implementation Details](technical_specification.md#implementation-details) - Implementation specifics
|
||||
|
||||
### Guides
|
||||
1. Basic Usage
|
||||
- [Installation](../README.md#installation)
|
||||
- [Basic Reflection](quick_start.md#basic-usage)
|
||||
- [Property Access](quick_start.md#2-property-access)
|
||||
- [Method Invocation](quick_start.md#3-method-invocation)
|
||||
|
||||
2. Advanced Usage
|
||||
- [Type Information](quick_start.md#5-type-information)
|
||||
- [Error Handling](quick_start.md#6-error-handling)
|
||||
- [Common Patterns](quick_start.md#common-patterns)
|
||||
- [Best Practices](quick_start.md#best-practices)
|
||||
|
||||
3. Performance
|
||||
- [Optimization Techniques](technical_specification.md#performance-optimizations)
|
||||
- [Performance Tips](quick_start.md#performance-tips)
|
||||
- [Memory Management](technical_specification.md#memory-management)
|
||||
|
||||
### Implementation Status
|
||||
|
||||
#### Current Features
|
||||
✅ Basic reflection system
|
||||
✅ Property access/mutation
|
||||
✅ Method invocation
|
||||
✅ Constructor handling
|
||||
✅ Type introspection
|
||||
✅ Basic metadata support
|
||||
✅ Error handling
|
||||
✅ Cross-platform support
|
||||
|
||||
#### Known Limitations
|
||||
❌ No cross-isolate reflection
|
||||
❌ Limited generic support
|
||||
❌ No source location tracking
|
||||
❌ No extension method support
|
||||
❌ No mixin composition
|
||||
❌ Limited metadata capabilities
|
||||
❌ No dynamic proxy generation
|
||||
❌ No attribute-based reflection
|
||||
|
||||
### Development
|
||||
|
||||
1. Contributing
|
||||
- [Getting Started](roadmap.md#getting-started)
|
||||
- [Priority Areas](roadmap.md#priority-areas)
|
||||
- [Development Process](roadmap.md#development-process)
|
||||
|
||||
2. Future Plans
|
||||
- [Short-term Goals](roadmap.md#short-term-goals-v020)
|
||||
- [Medium-term Goals](roadmap.md#medium-term-goals-v030)
|
||||
- [Long-term Goals](roadmap.md#long-term-goals-v100)
|
||||
|
||||
### Support
|
||||
|
||||
1. Help Resources
|
||||
- [Common Issues](quick_start.md#common-issues)
|
||||
- [Best Practices](quick_start.md#best-practices)
|
||||
- [Performance Tips](quick_start.md#performance-tips)
|
||||
|
||||
2. Version Support
|
||||
- [Support Matrix](roadmap.md#version-support-matrix)
|
||||
- [Breaking Changes](roadmap.md#breaking-changes)
|
||||
- [Migration Support](roadmap.md#migration-support)
|
||||
|
||||
## Quick Links
|
||||
|
||||
### For New Users
|
||||
1. Start with the [README](../README.md)
|
||||
2. Follow the [Quick Start Guide](quick_start.md)
|
||||
3. Review [Common Issues](quick_start.md#common-issues)
|
||||
4. Check [Best Practices](quick_start.md#best-practices)
|
||||
|
||||
### For Contributors
|
||||
1. Review the [Technical Specification](technical_specification.md)
|
||||
2. Check the [Development Roadmap](roadmap.md)
|
||||
3. See [Priority Areas](roadmap.md#priority-areas)
|
||||
4. Read [Contributing Guidelines](../CONTRIBUTING.md)
|
||||
|
||||
### For Framework Developers
|
||||
1. Study the [Mirrors Comparison](mirrors_comparison.md)
|
||||
2. Review [Implementation Details](technical_specification.md#implementation-details)
|
||||
3. Check [Framework Integration](roadmap.md#framework-integration)
|
||||
4. See [Enterprise Features](roadmap.md#enterprise-features)
|
||||
|
||||
## Document Updates
|
||||
|
||||
This documentation is continuously updated to reflect the latest changes and improvements in the Platform Reflection library. Check the [Development Roadmap](roadmap.md) for upcoming changes and new features.
|
||||
|
||||
Last Updated: 2024-01
|
||||
Version: 0.1.0
|
||||
209
packages/reflection/doc/mirrors_comparison.md
Normal file
209
packages/reflection/doc/mirrors_comparison.md
Normal file
|
|
@ -0,0 +1,209 @@
|
|||
# Dart Mirrors vs Platform Reflection Comparison
|
||||
|
||||
## Core Features Comparison
|
||||
|
||||
| Feature | dart:mirrors | Platform Reflection | Notes |
|
||||
|---------|-------------|-------------------|--------|
|
||||
| **Library Reflection** |
|
||||
| Top-level functions | ✅ Full | ✅ Full | Complete parity |
|
||||
| Top-level variables | ✅ Full | ✅ Full | Complete parity |
|
||||
| Library dependencies | ✅ Full | ✅ Full | Complete parity |
|
||||
| URI resolution | ✅ Full | ✅ Full | Complete parity |
|
||||
|
||||
| Feature | dart:mirrors | Platform Reflection | Notes |
|
||||
|---------|-------------|-------------------|--------|
|
||||
| **Isolate Support** |
|
||||
| Current isolate | ✅ Full | ✅ Full | Complete parity |
|
||||
| Other isolates | ✅ Full | ✅ Full | Complete parity |
|
||||
| Isolate control | ✅ Full | ✅ Full | Pause/Resume/Kill |
|
||||
| Error handling | ✅ Full | ✅ Full | Error/Exit listeners |
|
||||
|
||||
| Feature | dart:mirrors | Platform Reflection | Notes |
|
||||
|---------|-------------|-------------------|--------|
|
||||
| **Type System** |
|
||||
| Special types | ✅ Full | ✅ Full | void/dynamic/never |
|
||||
| Type relationships | ✅ Full | ✅ Full | Complete type checking |
|
||||
| Generic types | ✅ Full | ⚠️ Limited | Basic generic support |
|
||||
| Type parameters | ✅ Full | ⚠️ Limited | Basic parameter support |
|
||||
|
||||
| Feature | dart:mirrors | Platform Reflection | Notes |
|
||||
|---------|-------------|-------------------|--------|
|
||||
| **Metadata System** |
|
||||
| Class metadata | ✅ Full | ✅ Full | Complete parity |
|
||||
| Method metadata | ✅ Full | ✅ Full | Complete parity |
|
||||
| Property metadata | ✅ Full | ✅ Full | Complete parity |
|
||||
| Parameter metadata | ✅ Full | ✅ Full | Complete parity |
|
||||
| Custom attributes | ✅ Full | ✅ Full | Complete parity |
|
||||
|
||||
## Implementation Differences
|
||||
|
||||
### Registration System
|
||||
|
||||
```dart
|
||||
// dart:mirrors
|
||||
// No registration needed
|
||||
@reflectable
|
||||
class MyClass {}
|
||||
|
||||
// Platform Reflection
|
||||
@reflectable
|
||||
class MyClass {}
|
||||
|
||||
// Requires explicit registration
|
||||
Reflector.register(MyClass);
|
||||
Reflector.registerProperty(MyClass, 'prop', String);
|
||||
Reflector.registerMethod(MyClass, 'method', [int]);
|
||||
```
|
||||
|
||||
### Library Access
|
||||
|
||||
```dart
|
||||
// dart:mirrors
|
||||
final lib = MirrorSystem.findLibrary('my_lib');
|
||||
|
||||
// Platform Reflection
|
||||
final lib = LibraryMirrorImpl.withDeclarations(
|
||||
name: 'my_lib',
|
||||
uri: Uri.parse('package:my_package/my_lib.dart'),
|
||||
);
|
||||
```
|
||||
|
||||
### Isolate Handling
|
||||
|
||||
```dart
|
||||
// dart:mirrors
|
||||
final mirror = reflect(isolate);
|
||||
await mirror.invoke(#method, []);
|
||||
|
||||
// Platform Reflection
|
||||
final mirror = IsolateMirrorImpl.other(isolate, 'name', lib);
|
||||
mirror.addErrorListener((error, stack) {
|
||||
// Handle error
|
||||
});
|
||||
```
|
||||
|
||||
### Type System
|
||||
|
||||
```dart
|
||||
// dart:mirrors
|
||||
final type = reflectType(MyClass);
|
||||
final isSubtype = type.isSubtypeOf(otherType);
|
||||
|
||||
// Platform Reflection
|
||||
final type = TypeMetadata(
|
||||
type: MyClass,
|
||||
name: 'MyClass',
|
||||
// ...
|
||||
);
|
||||
final isSubtype = type.supertype == otherType;
|
||||
```
|
||||
|
||||
## Performance Characteristics
|
||||
|
||||
| Aspect | dart:mirrors | Platform Reflection | Winner |
|
||||
|--------|-------------|-------------------|---------|
|
||||
| Startup time | ❌ Slower | ✅ Faster | Platform Reflection |
|
||||
| Runtime performance | ❌ Slower | ✅ Faster | Platform Reflection |
|
||||
| Memory usage | ❌ Higher | ✅ Lower | Platform Reflection |
|
||||
| Tree shaking | ❌ Poor | ✅ Good | Platform Reflection |
|
||||
|
||||
## Platform Support
|
||||
|
||||
| Platform | dart:mirrors | Platform Reflection | Winner |
|
||||
|----------|-------------|-------------------|---------|
|
||||
| VM | ✅ Yes | ✅ Yes | Tie |
|
||||
| Web | ❌ No | ✅ Yes | Platform Reflection |
|
||||
| Flutter | ❌ No | ✅ Yes | Platform Reflection |
|
||||
| AOT | ❌ No | ✅ Yes | Platform Reflection |
|
||||
|
||||
## Use Cases
|
||||
|
||||
| Use Case | dart:mirrors | Platform Reflection | Better Choice |
|
||||
|----------|-------------|-------------------|---------------|
|
||||
| Dependency injection | ✅ Simpler | ⚠️ More setup | dart:mirrors |
|
||||
| Serialization | ✅ Simpler | ⚠️ More setup | dart:mirrors |
|
||||
| Testing/Mocking | ✅ More flexible | ✅ More controlled | Depends on needs |
|
||||
| Production apps | ❌ Limited platforms | ✅ All platforms | Platform Reflection |
|
||||
|
||||
## Migration Path
|
||||
|
||||
### From dart:mirrors
|
||||
|
||||
1. Add registration:
|
||||
```dart
|
||||
// Before
|
||||
@reflectable
|
||||
class MyClass {}
|
||||
|
||||
// After
|
||||
@reflectable
|
||||
class MyClass {}
|
||||
|
||||
void register() {
|
||||
Reflector.register(MyClass);
|
||||
// Register members...
|
||||
}
|
||||
```
|
||||
|
||||
2. Update reflection calls:
|
||||
```dart
|
||||
// Before
|
||||
final mirror = reflect(instance);
|
||||
final value = mirror.getField(#prop);
|
||||
|
||||
// After
|
||||
final mirror = reflector.reflect(instance);
|
||||
final value = mirror.getField(const Symbol('prop'));
|
||||
```
|
||||
|
||||
3. Handle libraries:
|
||||
```dart
|
||||
// Before
|
||||
final lib = MirrorSystem.findLibrary('my_lib');
|
||||
|
||||
// After
|
||||
final lib = LibraryMirrorImpl.withDeclarations(
|
||||
name: 'my_lib',
|
||||
uri: uri,
|
||||
);
|
||||
```
|
||||
|
||||
## Trade-offs
|
||||
|
||||
### Advantages of Platform Reflection
|
||||
1. Works everywhere
|
||||
2. Better performance
|
||||
3. Smaller code size
|
||||
4. Better tree shaking
|
||||
5. Full isolate support
|
||||
6. Production-ready
|
||||
|
||||
### Advantages of dart:mirrors
|
||||
1. No registration needed
|
||||
2. Simpler API
|
||||
3. More dynamic capabilities
|
||||
4. Better for development tools
|
||||
5. More flexible
|
||||
|
||||
## Conclusion
|
||||
|
||||
Platform Reflection offers a more production-ready alternative to dart:mirrors with:
|
||||
- Full cross-platform support
|
||||
- Better performance characteristics
|
||||
- More controlled reflection surface
|
||||
- Full isolate support
|
||||
- Production-ready features
|
||||
|
||||
The main trade-off is the need for explicit registration, but this brings benefits in terms of performance, code size, and tree shaking.
|
||||
|
||||
Choose Platform Reflection when:
|
||||
- You need cross-platform support
|
||||
- Performance is critical
|
||||
- Code size matters
|
||||
- You want production-ready reflection
|
||||
|
||||
Choose dart:mirrors when:
|
||||
- You're only targeting the VM
|
||||
- Development time is critical
|
||||
- You need maximum flexibility
|
||||
- You're building development tools
|
||||
369
packages/reflection/doc/quick_start.md
Normal file
369
packages/reflection/doc/quick_start.md
Normal file
|
|
@ -0,0 +1,369 @@
|
|||
# Platform Reflection Quick Start Guide
|
||||
|
||||
This guide covers the most common use cases for Platform Reflection to help you get started quickly.
|
||||
|
||||
## Installation
|
||||
|
||||
```yaml
|
||||
dependencies:
|
||||
platform_reflection: ^0.1.0
|
||||
```
|
||||
|
||||
## Basic Usage
|
||||
|
||||
### 1. Simple Class Reflection
|
||||
|
||||
```dart
|
||||
import 'package:platform_reflection/reflection.dart';
|
||||
|
||||
// 1. Define your class
|
||||
@reflectable
|
||||
class User {
|
||||
String name;
|
||||
int age;
|
||||
|
||||
User(this.name, this.age);
|
||||
|
||||
void birthday() => age++;
|
||||
}
|
||||
|
||||
// 2. Register for reflection
|
||||
void main() {
|
||||
// Register class
|
||||
Reflector.register(User);
|
||||
|
||||
// Register properties
|
||||
Reflector.registerProperty(User, 'name', String);
|
||||
Reflector.registerProperty(User, 'age', int);
|
||||
|
||||
// Register methods
|
||||
Reflector.registerMethod(
|
||||
User,
|
||||
'birthday',
|
||||
[],
|
||||
true,
|
||||
);
|
||||
|
||||
// Register constructor
|
||||
Reflector.registerConstructor(
|
||||
User,
|
||||
'',
|
||||
parameterTypes: [String, int],
|
||||
parameterNames: ['name', 'age'],
|
||||
creator: (String name, int age) => User(name, age),
|
||||
);
|
||||
|
||||
// Use reflection
|
||||
final user = reflector.createInstance(
|
||||
User,
|
||||
positionalArgs: ['John', 30],
|
||||
) as User;
|
||||
|
||||
final mirror = reflector.reflect(user);
|
||||
print(mirror.getField(const Symbol('name')).reflectee); // John
|
||||
mirror.invoke(const Symbol('birthday'), []);
|
||||
print(mirror.getField(const Symbol('age')).reflectee); // 31
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Property Access
|
||||
|
||||
```dart
|
||||
// Get property value
|
||||
final mirror = reflector.reflect(instance);
|
||||
final name = mirror.getField(const Symbol('name')).reflectee as String;
|
||||
|
||||
// Set property value
|
||||
mirror.setField(const Symbol('name'), 'Jane');
|
||||
|
||||
// Check if property exists
|
||||
final metadata = Reflector.getPropertyMetadata(User);
|
||||
if (metadata?.containsKey('name') ?? false) {
|
||||
// Property exists
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Method Invocation
|
||||
|
||||
```dart
|
||||
// Invoke method without arguments
|
||||
mirror.invoke(const Symbol('birthday'), []);
|
||||
|
||||
// Invoke method with arguments
|
||||
final result = mirror.invoke(
|
||||
const Symbol('greet'),
|
||||
['Hello'],
|
||||
).reflectee as String;
|
||||
|
||||
// Invoke method with named arguments
|
||||
final result = mirror.invoke(
|
||||
const Symbol('update'),
|
||||
[],
|
||||
{const Symbol('value'): 42},
|
||||
).reflectee;
|
||||
```
|
||||
|
||||
### 4. Constructor Usage
|
||||
|
||||
```dart
|
||||
// Default constructor
|
||||
final instance = reflector.createInstance(
|
||||
User,
|
||||
positionalArgs: ['John', 30],
|
||||
) as User;
|
||||
|
||||
// Named constructor
|
||||
final instance = reflector.createInstance(
|
||||
User,
|
||||
constructorName: 'guest',
|
||||
) as User;
|
||||
|
||||
// Constructor with named arguments
|
||||
final instance = reflector.createInstance(
|
||||
User,
|
||||
positionalArgs: ['John'],
|
||||
namedArgs: {const Symbol('age'): 30},
|
||||
) as User;
|
||||
```
|
||||
|
||||
### 5. Type Information
|
||||
|
||||
```dart
|
||||
// Get type metadata
|
||||
final metadata = Reflector.getTypeMetadata(User);
|
||||
|
||||
// Check properties
|
||||
for (var property in metadata.properties.values) {
|
||||
print('${property.name}: ${property.type}');
|
||||
}
|
||||
|
||||
// Check methods
|
||||
for (var method in metadata.methods.values) {
|
||||
print('${method.name}(${method.parameterTypes.join(', ')})');
|
||||
}
|
||||
```
|
||||
|
||||
### 6. Error Handling
|
||||
|
||||
```dart
|
||||
try {
|
||||
// Attempt reflection
|
||||
final mirror = reflector.reflect(instance);
|
||||
mirror.invoke(const Symbol('method'), []);
|
||||
} on NotReflectableException catch (e) {
|
||||
print('Type not registered: $e');
|
||||
} on MemberNotFoundException catch (e) {
|
||||
print('Member not found: $e');
|
||||
} on InvalidArgumentsException catch (e) {
|
||||
print('Invalid arguments: $e');
|
||||
} on ReflectionException catch (e) {
|
||||
print('Reflection error: $e');
|
||||
}
|
||||
```
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### 1. Registration Helper
|
||||
|
||||
```dart
|
||||
void registerType<T>(Type type) {
|
||||
Reflector.register(type);
|
||||
|
||||
final scanner = Scanner();
|
||||
final metadata = scanner.scanType(type);
|
||||
|
||||
// Register properties
|
||||
for (var property in metadata.properties.values) {
|
||||
Reflector.registerProperty(
|
||||
type,
|
||||
property.name,
|
||||
property.type,
|
||||
isWritable: property.isWritable,
|
||||
);
|
||||
}
|
||||
|
||||
// Register methods
|
||||
for (var method in metadata.methods.values) {
|
||||
Reflector.registerMethod(
|
||||
type,
|
||||
method.name,
|
||||
method.parameterTypes,
|
||||
method.returnsVoid,
|
||||
parameterNames: method.parameters.map((p) => p.name).toList(),
|
||||
isRequired: method.parameters.map((p) => p.isRequired).toList(),
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Property Observer
|
||||
|
||||
```dart
|
||||
class PropertyObserver {
|
||||
final InstanceMirror mirror;
|
||||
final Symbol propertyName;
|
||||
final void Function(dynamic oldValue, dynamic newValue) onChange;
|
||||
|
||||
PropertyObserver(this.mirror, this.propertyName, this.onChange);
|
||||
|
||||
void observe() {
|
||||
var lastValue = mirror.getField(propertyName).reflectee;
|
||||
|
||||
Timer.periodic(Duration(milliseconds: 100), (_) {
|
||||
final currentValue = mirror.getField(propertyName).reflectee;
|
||||
if (currentValue != lastValue) {
|
||||
onChange(lastValue, currentValue);
|
||||
lastValue = currentValue;
|
||||
}
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Method Interceptor
|
||||
|
||||
```dart
|
||||
class MethodInterceptor {
|
||||
final InstanceMirror mirror;
|
||||
final Symbol methodName;
|
||||
final void Function(List args, Map<Symbol, dynamic> named) beforeInvoke;
|
||||
final void Function(dynamic result) afterInvoke;
|
||||
|
||||
MethodInterceptor(
|
||||
this.mirror,
|
||||
this.methodName,
|
||||
{this.beforeInvoke = _noOp,
|
||||
this.afterInvoke = _noOp});
|
||||
|
||||
static void _noOp([dynamic _]) {}
|
||||
|
||||
dynamic invoke(List args, [Map<Symbol, dynamic>? named]) {
|
||||
beforeInvoke(args, named ?? {});
|
||||
final result = mirror.invoke(methodName, args, named).reflectee;
|
||||
afterInvoke(result);
|
||||
return result;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Register Early**
|
||||
```dart
|
||||
void main() {
|
||||
// Register all types at startup
|
||||
registerType<User>();
|
||||
registerType<Order>();
|
||||
registerType<Product>();
|
||||
|
||||
// Start application
|
||||
runApp();
|
||||
}
|
||||
```
|
||||
|
||||
2. **Cache Mirrors**
|
||||
```dart
|
||||
class UserService {
|
||||
final Map<User, InstanceMirror> _mirrors = {};
|
||||
|
||||
InstanceMirror getMirror(User user) {
|
||||
return _mirrors.putIfAbsent(
|
||||
user,
|
||||
() => reflector.reflect(user),
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. **Handle Errors**
|
||||
```dart
|
||||
T reflectSafely<T>(Function() operation, T defaultValue) {
|
||||
try {
|
||||
return operation() as T;
|
||||
} on ReflectionException catch (e) {
|
||||
print('Reflection failed: $e');
|
||||
return defaultValue;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
4. **Validate Registration**
|
||||
```dart
|
||||
bool isFullyRegistered(Type type) {
|
||||
final metadata = Reflector.getTypeMetadata(type);
|
||||
if (metadata == null) return false;
|
||||
|
||||
// Check properties
|
||||
if (metadata.properties.isEmpty) return false;
|
||||
|
||||
// Check methods
|
||||
if (metadata.methods.isEmpty) return false;
|
||||
|
||||
// Check constructors
|
||||
if (metadata.constructors.isEmpty) return false;
|
||||
|
||||
return true;
|
||||
}
|
||||
```
|
||||
|
||||
## Common Issues
|
||||
|
||||
1. **Type Not Registered**
|
||||
```dart
|
||||
// Wrong
|
||||
reflector.reflect(unregisteredInstance);
|
||||
|
||||
// Right
|
||||
Reflector.register(UnregisteredType);
|
||||
reflector.reflect(instance);
|
||||
```
|
||||
|
||||
2. **Missing Property/Method Registration**
|
||||
```dart
|
||||
// Wrong
|
||||
Reflector.register(User);
|
||||
|
||||
// Right
|
||||
Reflector.register(User);
|
||||
Reflector.registerProperty(User, 'name', String);
|
||||
Reflector.registerMethod(User, 'greet', [String]);
|
||||
```
|
||||
|
||||
3. **Wrong Argument Types**
|
||||
```dart
|
||||
// Wrong
|
||||
mirror.invoke(const Symbol('greet'), [42]);
|
||||
|
||||
// Right
|
||||
mirror.invoke(const Symbol('greet'), ['Hello']);
|
||||
```
|
||||
|
||||
## Performance Tips
|
||||
|
||||
1. **Cache Metadata**
|
||||
```dart
|
||||
final metadata = Reflector.getTypeMetadata(User);
|
||||
final properties = metadata.properties;
|
||||
final methods = metadata.methods;
|
||||
```
|
||||
|
||||
2. **Reuse Mirrors**
|
||||
```dart
|
||||
final mirror = reflector.reflect(instance);
|
||||
// Reuse mirror for multiple operations
|
||||
```
|
||||
|
||||
3. **Batch Registration**
|
||||
```dart
|
||||
void registerAll() {
|
||||
for (var type in types) {
|
||||
registerType(type);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Read the [Technical Specification](technical_specification.md) for detailed implementation information
|
||||
- Check the [API Reference](../README.md#api-reference) for complete API documentation
|
||||
- See the [Mirrors Comparison](mirrors_comparison.md) for differences from dart:mirrors
|
||||
294
packages/reflection/doc/roadmap.md
Normal file
294
packages/reflection/doc/roadmap.md
Normal file
|
|
@ -0,0 +1,294 @@
|
|||
# Platform Reflection Roadmap
|
||||
|
||||
This document outlines the planned improvements and future direction of the Platform Reflection library.
|
||||
|
||||
## Current Status (v0.1.0)
|
||||
|
||||
### Implemented Features
|
||||
✅ Basic reflection system
|
||||
✅ Property access/mutation
|
||||
✅ Method invocation
|
||||
✅ Constructor handling
|
||||
✅ Type introspection
|
||||
✅ Basic metadata support
|
||||
✅ Error handling
|
||||
✅ Cross-platform support
|
||||
|
||||
### Known Limitations
|
||||
❌ No cross-isolate reflection
|
||||
❌ Limited generic support
|
||||
❌ No source location tracking
|
||||
❌ No extension method support
|
||||
❌ No mixin composition
|
||||
❌ Limited metadata capabilities
|
||||
❌ No dynamic proxy generation
|
||||
❌ No attribute-based reflection
|
||||
|
||||
## Short-term Goals (v0.2.0)
|
||||
|
||||
### 1. Enhanced Generic Support
|
||||
- [ ] Better generic type handling
|
||||
- [ ] Generic type argument preservation
|
||||
- [ ] Generic method support
|
||||
- [ ] Generic constructor support
|
||||
- [ ] Type parameter constraints
|
||||
|
||||
### 2. Improved Type System
|
||||
- [ ] Better type relationship checking
|
||||
- [ ] Variance handling
|
||||
- [ ] Type erasure handling
|
||||
- [ ] Generic type instantiation
|
||||
- [ ] Type parameter bounds
|
||||
|
||||
### 3. Metadata Enhancements
|
||||
- [ ] Rich metadata API
|
||||
- [ ] Metadata inheritance
|
||||
- [ ] Custom metadata providers
|
||||
- [ ] Metadata validation
|
||||
- [ ] Compile-time metadata
|
||||
|
||||
### 4. Performance Optimizations
|
||||
- [ ] Faster lookup mechanisms
|
||||
- [ ] Better memory usage
|
||||
- [ ] Optimized registration
|
||||
- [ ] Improved caching
|
||||
- [ ] Reduced startup time
|
||||
|
||||
## Medium-term Goals (v0.3.0)
|
||||
|
||||
### 1. Dynamic Features
|
||||
- [ ] Dynamic proxy generation
|
||||
- [ ] Method interception
|
||||
- [ ] Property interception
|
||||
- [ ] Dynamic interface implementation
|
||||
- [ ] Runtime mixin application
|
||||
|
||||
### 2. Advanced Type Features
|
||||
- [ ] Extension method support
|
||||
- [ ] Operator overloading
|
||||
- [ ] Mixin composition
|
||||
- [ ] Type alias support
|
||||
- [ ] Named constructor factories
|
||||
|
||||
### 3. Tooling Support
|
||||
- [ ] VS Code extension
|
||||
- [ ] Dart analyzer plugin
|
||||
- [ ] Documentation generator
|
||||
- [ ] Migration tools
|
||||
- [ ] Debug tools
|
||||
|
||||
### 4. Framework Integration
|
||||
- [ ] Flutter integration
|
||||
- [ ] Built Value integration
|
||||
- [ ] JSON serialization
|
||||
- [ ] Database mapping
|
||||
- [ ] Dependency injection
|
||||
|
||||
## Long-term Goals (v1.0.0)
|
||||
|
||||
### 1. Advanced Reflection
|
||||
- [ ] Cross-isolate reflection
|
||||
- [ ] Source location tracking
|
||||
- [ ] Dynamic loading
|
||||
- [ ] Code generation
|
||||
- [ ] Hot reload support
|
||||
|
||||
### 2. Language Features
|
||||
- [ ] Pattern matching
|
||||
- [ ] Records support
|
||||
- [ ] Sealed classes
|
||||
- [ ] Enhanced enums
|
||||
- [ ] Extension types
|
||||
|
||||
### 3. Enterprise Features
|
||||
- [ ] Aspect-oriented programming
|
||||
- [ ] Dependency injection
|
||||
- [ ] Object-relational mapping
|
||||
- [ ] Serialization framework
|
||||
- [ ] Validation framework
|
||||
|
||||
### 4. Security Features
|
||||
- [ ] Access control
|
||||
- [ ] Reflection policies
|
||||
- [ ] Sandboxing
|
||||
- [ ] Audit logging
|
||||
- [ ] Security annotations
|
||||
|
||||
## Implementation Priorities
|
||||
|
||||
### Phase 1: Foundation (Current)
|
||||
1. Core reflection system
|
||||
2. Basic type support
|
||||
3. Essential operations
|
||||
4. Error handling
|
||||
5. Documentation
|
||||
|
||||
### Phase 2: Enhancement (Next)
|
||||
1. Generic support
|
||||
2. Type system improvements
|
||||
3. Metadata enhancements
|
||||
4. Performance optimizations
|
||||
5. Framework integration
|
||||
|
||||
### Phase 3: Advanced Features
|
||||
1. Dynamic capabilities
|
||||
2. Language feature support
|
||||
3. Tooling integration
|
||||
4. Security features
|
||||
5. Enterprise features
|
||||
|
||||
## Breaking Changes
|
||||
|
||||
### Planned for v0.2.0
|
||||
- API refinements for generic support
|
||||
- Enhanced metadata system
|
||||
- Improved type handling
|
||||
- Registration system updates
|
||||
|
||||
### Planned for v0.3.0
|
||||
- Dynamic proxy API
|
||||
- Advanced type features
|
||||
- Framework integration APIs
|
||||
- Security system
|
||||
|
||||
### Planned for v1.0.0
|
||||
- Stable API finalization
|
||||
- Enterprise feature integration
|
||||
- Cross-isolate capabilities
|
||||
- Advanced language features
|
||||
|
||||
## Migration Support
|
||||
|
||||
### For Each Major Version
|
||||
- Migration guides
|
||||
- Breaking change documentation
|
||||
- Upgrade tools
|
||||
- Code modification scripts
|
||||
- Support period
|
||||
|
||||
## Community Feedback Areas
|
||||
|
||||
### Current Focus
|
||||
1. Generic type handling
|
||||
2. Performance optimization
|
||||
3. Framework integration
|
||||
4. API usability
|
||||
5. Documentation quality
|
||||
|
||||
### Future Considerations
|
||||
1. Enterprise features
|
||||
2. Security requirements
|
||||
3. Framework support
|
||||
4. Language feature support
|
||||
5. Tool integration
|
||||
|
||||
## Development Process
|
||||
|
||||
### 1. Feature Development
|
||||
```mermaid
|
||||
graph LR
|
||||
A[Proposal] --> B[Design]
|
||||
B --> C[Implementation]
|
||||
C --> D[Testing]
|
||||
D --> E[Documentation]
|
||||
E --> F[Release]
|
||||
```
|
||||
|
||||
### 2. Release Cycle
|
||||
- Major versions: Significant features/breaking changes
|
||||
- Minor versions: New features/non-breaking changes
|
||||
- Patch versions: Bug fixes/performance improvements
|
||||
|
||||
### 3. Testing Strategy
|
||||
- Unit tests
|
||||
- Integration tests
|
||||
- Performance tests
|
||||
- Platform compatibility tests
|
||||
- Framework integration tests
|
||||
|
||||
## Contributing
|
||||
|
||||
### Priority Areas
|
||||
1. Generic type support
|
||||
2. Performance improvements
|
||||
3. Framework integration
|
||||
4. Documentation
|
||||
5. Testing
|
||||
|
||||
### Getting Started
|
||||
1. Review current limitations
|
||||
2. Check roadmap priorities
|
||||
3. Read contribution guidelines
|
||||
4. Submit proposals
|
||||
5. Implement features
|
||||
|
||||
## Support
|
||||
|
||||
### Long-term Support (LTS)
|
||||
- v1.0.0 and later
|
||||
- Security updates
|
||||
- Critical bug fixes
|
||||
- Performance improvements
|
||||
- Documentation updates
|
||||
|
||||
### Version Support Matrix
|
||||
| Version | Status | Support Until |
|
||||
|---------|---------|--------------|
|
||||
| 0.1.x | Current | 6 months |
|
||||
| 0.2.x | Planned | 1 year |
|
||||
| 0.3.x | Planned | 1 year |
|
||||
| 1.0.x | Planned | 2 years |
|
||||
|
||||
## Success Metrics
|
||||
|
||||
### Technical Metrics
|
||||
- Performance benchmarks
|
||||
- Memory usage
|
||||
- API coverage
|
||||
- Test coverage
|
||||
- Documentation coverage
|
||||
|
||||
### Community Metrics
|
||||
- Adoption rate
|
||||
- Issue resolution time
|
||||
- Community contributions
|
||||
- User satisfaction
|
||||
- Framework adoption
|
||||
|
||||
## Get Involved
|
||||
|
||||
### Ways to Contribute
|
||||
1. Submit bug reports
|
||||
2. Propose features
|
||||
3. Improve documentation
|
||||
4. Add test cases
|
||||
5. Implement features
|
||||
|
||||
### Communication Channels
|
||||
- GitHub Issues
|
||||
- Pull Requests
|
||||
- Discord Server
|
||||
- Stack Overflow
|
||||
- Email Support
|
||||
|
||||
## Timeline
|
||||
|
||||
### 2024 Q1-Q2
|
||||
- Enhanced generic support
|
||||
- Improved type system
|
||||
- Performance optimizations
|
||||
- Documentation improvements
|
||||
|
||||
### 2024 Q3-Q4
|
||||
- Dynamic features
|
||||
- Framework integration
|
||||
- Tool support
|
||||
- Security features
|
||||
|
||||
### 2025
|
||||
- Cross-isolate reflection
|
||||
- Enterprise features
|
||||
- Language feature support
|
||||
- 1.0.0 release
|
||||
|
||||
Note: This roadmap is subject to change based on community feedback and evolving requirements.
|
||||
403
packages/reflection/doc/technical_specification.md
Normal file
403
packages/reflection/doc/technical_specification.md
Normal file
|
|
@ -0,0 +1,403 @@
|
|||
# Platform Reflection Technical Specification
|
||||
|
||||
## System Architecture
|
||||
|
||||
### Core Components
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Reflector] --> B[Scanner]
|
||||
A --> C[RuntimeReflector]
|
||||
B --> D[TypeAnalyzer]
|
||||
C --> E[MirrorSystem]
|
||||
E --> F[Mirrors]
|
||||
F --> G[ClassMirror]
|
||||
F --> H[InstanceMirror]
|
||||
F --> I[MethodMirror]
|
||||
```
|
||||
|
||||
### Component Responsibilities
|
||||
|
||||
#### 1. Reflector
|
||||
- Central registration point
|
||||
- Metadata management
|
||||
- Type registration validation
|
||||
- Cache management
|
||||
|
||||
```dart
|
||||
class Reflector {
|
||||
static final Map<Type, TypeMetadata> _typeCache;
|
||||
static final Map<Type, Map<String, PropertyMetadata>> _propertyMetadata;
|
||||
static final Map<Type, Map<String, MethodMetadata>> _methodMetadata;
|
||||
static final Map<Type, List<ConstructorMetadata>> _constructorMetadata;
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. Scanner
|
||||
- Type analysis
|
||||
- Metadata extraction
|
||||
- Registration validation
|
||||
- Type relationship analysis
|
||||
|
||||
```dart
|
||||
class Scanner {
|
||||
static final Map<Type, TypeInfo> _typeInfoCache;
|
||||
|
||||
static TypeInfo analyze(Type type) {
|
||||
// Analyze class structure
|
||||
// Extract metadata
|
||||
// Build type relationships
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. RuntimeReflector
|
||||
- Instance creation
|
||||
- Method invocation
|
||||
- Property access
|
||||
- Type reflection
|
||||
|
||||
```dart
|
||||
class RuntimeReflector {
|
||||
InstanceMirror reflect(Object object) {
|
||||
// Create instance mirror
|
||||
// Setup metadata access
|
||||
// Configure invocation handling
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Metadata System
|
||||
|
||||
#### Type Metadata
|
||||
```dart
|
||||
class TypeMetadata {
|
||||
final Type type;
|
||||
final String name;
|
||||
final Map<String, PropertyMetadata> properties;
|
||||
final Map<String, MethodMetadata> methods;
|
||||
final List<ConstructorMetadata> constructors;
|
||||
final bool isAbstract;
|
||||
final bool isEnum;
|
||||
}
|
||||
```
|
||||
|
||||
#### Method Metadata
|
||||
```dart
|
||||
class MethodMetadata {
|
||||
final String name;
|
||||
final List<Type> parameterTypes;
|
||||
final List<ParameterMetadata> parameters;
|
||||
final bool returnsVoid;
|
||||
final bool isStatic;
|
||||
final bool isAbstract;
|
||||
}
|
||||
```
|
||||
|
||||
#### Property Metadata
|
||||
```dart
|
||||
class PropertyMetadata {
|
||||
final String name;
|
||||
final Type type;
|
||||
final bool isReadable;
|
||||
final bool isWritable;
|
||||
final bool isStatic;
|
||||
}
|
||||
```
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### Registration Process
|
||||
|
||||
1. Type Registration
|
||||
```dart
|
||||
static void register(Type type) {
|
||||
// Validate type
|
||||
if (_typeCache.containsKey(type)) return;
|
||||
|
||||
// Create metadata
|
||||
final metadata = TypeMetadata(
|
||||
type: type,
|
||||
name: type.toString(),
|
||||
properties: {},
|
||||
methods: {},
|
||||
constructors: [],
|
||||
);
|
||||
|
||||
// Cache metadata
|
||||
_typeCache[type] = metadata;
|
||||
}
|
||||
```
|
||||
|
||||
2. Property Registration
|
||||
```dart
|
||||
static void registerProperty(
|
||||
Type type,
|
||||
String name,
|
||||
Type propertyType, {
|
||||
bool isReadable = true,
|
||||
bool isWritable = true,
|
||||
}) {
|
||||
// Validate type registration
|
||||
if (!isRegistered(type)) {
|
||||
throw NotReflectableException(type);
|
||||
}
|
||||
|
||||
// Create property metadata
|
||||
final metadata = PropertyMetadata(
|
||||
name: name,
|
||||
type: propertyType,
|
||||
isReadable: isReadable,
|
||||
isWritable: isWritable,
|
||||
);
|
||||
|
||||
// Cache metadata
|
||||
_propertyMetadata
|
||||
.putIfAbsent(type, () => {})
|
||||
[name] = metadata;
|
||||
}
|
||||
```
|
||||
|
||||
3. Method Registration
|
||||
```dart
|
||||
static void registerMethod(
|
||||
Type type,
|
||||
String name,
|
||||
List<Type> parameterTypes,
|
||||
bool returnsVoid, {
|
||||
List<String>? parameterNames,
|
||||
List<bool>? isRequired,
|
||||
}) {
|
||||
// Validate type registration
|
||||
if (!isRegistered(type)) {
|
||||
throw NotReflectableException(type);
|
||||
}
|
||||
|
||||
// Create method metadata
|
||||
final metadata = MethodMetadata(
|
||||
name: name,
|
||||
parameterTypes: parameterTypes,
|
||||
parameters: _createParameters(
|
||||
parameterTypes,
|
||||
parameterNames,
|
||||
isRequired,
|
||||
),
|
||||
returnsVoid: returnsVoid,
|
||||
);
|
||||
|
||||
// Cache metadata
|
||||
_methodMetadata
|
||||
.putIfAbsent(type, () => {})
|
||||
[name] = metadata;
|
||||
}
|
||||
```
|
||||
|
||||
### Instance Creation
|
||||
|
||||
```dart
|
||||
InstanceMirror createInstance(
|
||||
Type type, {
|
||||
List<dynamic>? positionalArgs,
|
||||
Map<Symbol, dynamic>? namedArgs,
|
||||
String? constructorName,
|
||||
}) {
|
||||
// Get constructor metadata
|
||||
final constructors = Reflector.getConstructorMetadata(type);
|
||||
if (constructors == null) {
|
||||
throw ReflectionException('No constructors found');
|
||||
}
|
||||
|
||||
// Find matching constructor
|
||||
final constructor = constructors.firstWhere(
|
||||
(c) => c.name == (constructorName ?? ''),
|
||||
orElse: () => throw ReflectionException('Constructor not found'),
|
||||
);
|
||||
|
||||
// Validate arguments
|
||||
_validateArguments(
|
||||
constructor,
|
||||
positionalArgs,
|
||||
namedArgs,
|
||||
);
|
||||
|
||||
// Create instance
|
||||
final instance = constructor.creator!(
|
||||
positionalArgs,
|
||||
namedArgs,
|
||||
);
|
||||
|
||||
// Return mirror
|
||||
return InstanceMirror(
|
||||
instance,
|
||||
type,
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Method Invocation
|
||||
|
||||
```dart
|
||||
InstanceMirror invoke(
|
||||
Symbol methodName,
|
||||
List<dynamic> positionalArguments, [
|
||||
Map<Symbol, dynamic>? namedArguments,
|
||||
]) {
|
||||
// Get method metadata
|
||||
final method = _getMethodMetadata(methodName);
|
||||
if (method == null) {
|
||||
throw ReflectionException('Method not found');
|
||||
}
|
||||
|
||||
// Validate arguments
|
||||
_validateMethodArguments(
|
||||
method,
|
||||
positionalArguments,
|
||||
namedArguments,
|
||||
);
|
||||
|
||||
// Invoke method
|
||||
final result = method.invoke(
|
||||
instance,
|
||||
positionalArguments,
|
||||
namedArguments,
|
||||
);
|
||||
|
||||
// Return result mirror
|
||||
return InstanceMirror(
|
||||
result,
|
||||
result.runtimeType,
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## Performance Optimizations
|
||||
|
||||
### 1. Metadata Caching
|
||||
- Type metadata cached on registration
|
||||
- Method metadata cached on registration
|
||||
- Property metadata cached on registration
|
||||
|
||||
### 2. Lookup Optimization
|
||||
- O(1) type lookup
|
||||
- O(1) method lookup
|
||||
- O(1) property lookup
|
||||
|
||||
### 3. Memory Management
|
||||
- Weak references for type cache
|
||||
- Lazy initialization of metadata
|
||||
- Minimal metadata storage
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Exception Hierarchy
|
||||
```dart
|
||||
abstract class ReflectionException implements Exception {
|
||||
final String message;
|
||||
final StackTrace? stackTrace;
|
||||
}
|
||||
|
||||
class NotReflectableException extends ReflectionException {
|
||||
final Type type;
|
||||
}
|
||||
|
||||
class InvalidArgumentsException extends ReflectionException {
|
||||
final String memberName;
|
||||
final Type type;
|
||||
}
|
||||
|
||||
class MemberNotFoundException extends ReflectionException {
|
||||
final String memberName;
|
||||
final Type type;
|
||||
}
|
||||
```
|
||||
|
||||
### Validation Points
|
||||
1. Registration validation
|
||||
2. Argument validation
|
||||
3. Type validation
|
||||
4. Access validation
|
||||
|
||||
## Platform Considerations
|
||||
|
||||
### Web Support
|
||||
- No dart:mirrors dependency
|
||||
- Tree-shaking friendly
|
||||
- Minimal runtime overhead
|
||||
|
||||
### Flutter Support
|
||||
- AOT compilation compatible
|
||||
- No code generation required
|
||||
- Performance optimized
|
||||
|
||||
### Native Support
|
||||
- Cross-platform compatible
|
||||
- No platform-specific code
|
||||
- Consistent behavior
|
||||
|
||||
## Limitations and Constraints
|
||||
|
||||
### Technical Limitations
|
||||
1. No cross-isolate reflection
|
||||
2. No source location support
|
||||
3. Limited generic support
|
||||
4. No extension method support
|
||||
|
||||
### Design Decisions
|
||||
1. Explicit registration required
|
||||
2. No private member access
|
||||
3. No dynamic loading
|
||||
4. No proxy generation
|
||||
|
||||
## Future Considerations
|
||||
|
||||
### Planned Improvements
|
||||
1. Enhanced generic support
|
||||
2. Better type relationship handling
|
||||
3. Improved metadata capabilities
|
||||
4. Performance optimizations
|
||||
|
||||
### Potential Features
|
||||
1. Attribute-based reflection
|
||||
2. Dynamic proxy generation
|
||||
3. Enhanced type analysis
|
||||
4. Improved error reporting
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Access Control
|
||||
- No private member access
|
||||
- Controlled reflection surface
|
||||
- Explicit registration required
|
||||
|
||||
### Type Safety
|
||||
- Strong type checking
|
||||
- Runtime validation
|
||||
- Safe method invocation
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Unit Tests
|
||||
1. Registration tests
|
||||
2. Reflection tests
|
||||
3. Error handling tests
|
||||
4. Performance tests
|
||||
|
||||
### Integration Tests
|
||||
1. Platform compatibility
|
||||
2. Framework integration
|
||||
3. Real-world scenarios
|
||||
4. Edge cases
|
||||
|
||||
## Documentation Requirements
|
||||
|
||||
### API Documentation
|
||||
1. Public API documentation
|
||||
2. Usage examples
|
||||
3. Best practices
|
||||
4. Migration guides
|
||||
|
||||
### Technical Documentation
|
||||
1. Architecture overview
|
||||
2. Implementation details
|
||||
3. Performance considerations
|
||||
4. Security guidelines
|
||||
Loading…
Reference in a new issue