angel3_container_generator 10.0.0
angel3_container_generator: ^10.0.0 copied to clipboard
Generates the reflection data Angel3's container needs to construct @injectable classes, so it works without dart:mirrors (e.g. in AOT-compiled apps).
Angel3 Container Generator #
Generates the reflection data that package:angel3_container and Angel3 need, so dependency injection, @Expose controllers and @Hooks/@Middleware annotations work without dart:mirrors, including in AOT-compiled apps (dart compile exe), obfuscated or not.
Installation #
In your pubspec.yaml:
dependencies:
angel3_container: ^10.0.0
dev_dependencies:
angel3_container_generator: ^10.0.0
build_runner: ^2.4.0
Usage #
-
Add
angel3_containertodependencies, andangel3_container_generatorandbuild_runnertodev_dependencies. -
Annotate the classes the container should construct with
@injectable, and add apartdirective:import 'package:angel3_container/angel3_container.dart'; part 'services.g.dart'; @injectable class Greeter { final Config config; Greeter(this.config, {Logger? log}); } -
Run
dart run build_runner build. Each library gets one variable named after its file, hereservicesReflection. -
Build the container's reflector from the generated data:
var container = Container(StaticReflector.combine([servicesReflection])); var greeter = container.make<Greeter>();
With Angel3, pass the reflector to the app: Angel(reflector: StaticReflector.combine([...])). Mark with @injectable:
- Controllers, so their
@Exposemethods are routed (seeexample/controller.dart), and services with@Hooksor@Middleware. The generated data lists each class's annotations and the public instance methods it declares, with their parameters (including annotations such as@Query) and annotations. - Models whose members are read by name, as in a Jael template with
angel3_jael: the generated data reads each class's public instance fields, getters and methods, declared or inherited, throughStaticReflectedInstance.getField, which throws aReflectionExceptionfor any other name. - Top-level functions used as handlers, so
@Middlewareon them applies andioc(handler)can inject their parameters.
The generated code calls each class's unnamed constructor without dart:mirrors. A constructor with optional parameters is called with Function.apply and symbol literals (which keep working when the app is obfuscated), passing only the arguments the container resolved, so every other parameter keeps its default value, including a default inherited through super.x. this.x/super.x parameters and import prefixes are supported.
Limitations #
- Only the unnamed constructor is used. An abstract class can be constructed only through a
factoryunnamed constructor. - Generic and private classes are not supported.
- The library must import
package:angel3_container/angel3_container.dartwithout a prefix, as the generated code uses its names. - A parameter type the library cannot name (for example a
super.xparameter whose type only the superclass's library imports) fails the build with an error; import that type, or declare the parameter's type. - Closures cannot be described, so
ioc((Foo foo) => ...)needs an explicitinjection:(or a named,@injectabletop-level function). - Only the methods a class declares are listed (as
MirrorsReflectorlists a controller's), so@Hooksor@Middlewareon a service method that the class inherits without overriding is not seen;MirrorsReflectordoes see it. To use one, override the method in the class and annotate the override. - Annotations are copied from the source. One that names a static member of its class without the class name is qualified with it; other names must be in scope in the library, as they are for the annotation itself.
Development #
The output for test/fixtures and example is checked in. Regenerate it with dart run build_runner build after changing them or the generator.
Migrating from 9.x to 10.0.0 #
The breaking changes of each release are listed in the CHANGELOG. Those of 10.0.0 that may need changes in an app:
The generator is rewritten: it generates reflection data for @injectable classes and top-level functions, used through StaticReflector, and no longer depends on reflectable. GeneratedReflector, ContainedReflectable and contained are removed. To migrate:
-
Replace
@containedwith@injectable, frompackage:angel3_container/angel3_container.dart, and addpart '<file>.g.dart';to each library with such classes. -
Replace
reflectable_builderwithangel3_container_generatorandbuild_runnerindev_dependencies, and rundart run build_runner build. -
Replace
GeneratedReflector()withStaticReflector.combine([...]), passing each library's generated variable:// 9.x var app = Angel(reflector: GeneratedReflector()); // 10.0.0, with the data of services.dart and controllers.dart var app = Angel( reflector: StaticReflector.combine([servicesReflection, controllersReflection]), );
Closures cannot be described, so ioc on a closure needs an explicit injection:, or a named, @injectable top-level function.