@illuma/core Guidelines

General

Define services as classes marked with @Service (root-scoped singleton, shared across the container tree) or @Scoped (node-scoped, resolved within the container that provides it). Prefer these over the lower-level @NodeInjectable({ singleton: true | false }) form. Use makeService / makeScoped in decorator-free environments. Factory functions work but are uncommon.
Before using decorators, verify they are enabled in the project; otherwise use makeService / makeScoped.
Inject dependencies with nodeInject on class fields. Injection only works inside an injection context (during instantiation).
Constructor injection is not supported. Inject through nodeInject in the class body.
All injected fields must be private readonly.
For transient instances, inject Injector and call this._injector.produce(MyService) or produce(() => { ... }) to run a factory in injection context.
Use NodeToken for injectable tokens and MultiNodeToken for multi-providers. Define them in tokens.ts.
Circular dependencies are not allowed. Use injectDefer only when you cannot refactor the cycle away.

For async/lazy patterns, see async-injection.md. For testing, see testing.md. For error codes, see errors.md.