Tom Reflection

Runtime reflection support for Dart based on code generation, using capabilities to specify which operations to support.

This package is a fork of the reflectable package with modifications to better suit the Tom framework's needs and bug fixes.

Features

Introspection: Examine object structure at runtime (class members, types, metadata)
Dynamic invocation: Call methods and access properties by name
Capability-based: Only include the reflection support you need, minimizing code size
Code generation: Generates efficient reflection data at build time

Getting Started

Prerequisites

Dart SDK ^3.9.0
tom_build_tools package for code generation

Installation

Add to your pubspec.yaml:

dependencies:
  tom_reflection: ^1.0.0

dev_dependencies:
  build_runner: ^2.4.0
  tom_build:
    path: ../tom_build  # or git/pub reference
  tom_build_tools:
    path: ../tom_build_tools  # or git/pub reference

Add a build.yaml to configure which files to generate reflection for:

targets:
  $default:
    builders:
      tom_build:reflection_generator:
        generate_for:
          - lib/main.dart
          - example/*.dart
        options:
          formatted: true

Usage

1. Define a Reflector

Create a class extending Reflection with the capabilities you need:

import 'package:tom_reflection/tom_reflection.dart';

class MyReflector extends Reflection {
  const MyReflector()
      : super(
          invokingCapability,
          declarationsCapability,
        );
}

const myReflector = MyReflector();

2. Annotate Classes

Mark classes for reflection with your reflector:

@myReflector
class Person {
  final String name;
  final int age;

  Person(this.name, this.age);

  String greet() => 'Hello, I am $name!';
}

3. Generate Reflection Data

Run build_runner to generate the reflection code:

dart run build_runner build

Or use the standalone generator directly:

dart run tom_build_tools:reflection_generator lib/main.dart

4. Use Reflection

import 'main.reflection.dart';

void main() {
  initializeReflection();

  final person = Person('Alice', 30);
  final mirror = myReflector.reflect(person);

  // Get member names
  final classMirror = mirror.type;
  print('Class: ${classMirror.simpleName}');

  // Invoke method dynamically
  final greeting = mirror.invoke('greet', []);
  print(greeting); // Hello, I am Alice!
}

Capabilities

Capabilities control what reflection operations are available:

Capability	Description
`invokingCapability`	Invoke methods and constructors
`declarationsCapability`	Access class declarations
`typeRelationsCapability`	Access superclass/interface info
`metadataCapability`	Access metadata annotations
`reflectedTypeCapability`	Access `reflectedType` on mirrors

License

BSD 3-Clause License. See LICENSE for details.

This package is a fork of reflectable and maintains the same open-source license.

Additional Information

Part of the Tom Framework
Based on reflectable
See example/ for complete examples