@venizia/ignis-docs 0.2.0 → 0.2.1-0

package/content/extensions/helpers/inversion/index.md

@@ -1,616 +1,125 @@
-# Inversion (DI)
-
-Standalone IoC container with decorator-based injection, fluent binding API, and singleton/transient scoping -- the foundation layer for all IGNIS packages.
-
-## Quick Reference
+---
+title: Inversion (DI)
+description: Standalone IoC container with decorator-based injection and a fluent binding API
+difficulty: intermediate
+---
 
-| Item | Value |
-|------|-------|
-| **Package** | `@venizia/ignis-inversion` |
-| **Classes** | `Container`, `Binding`, `MetadataRegistry` |
-| **Decorators** | `@inject`, `@injectable` |
-| **Runtimes** | Both (Bun and Node.js) |
-
-#### Import Paths
-
-```typescript
-import {
-  Container,
-  Binding,
-  MetadataRegistry,
-  metadataRegistry,
-  inject,
-  injectable,
-  BindingKeys,
-  BindingScopes,
-  BindingValueTypes,
-  MetadataKeys,
-  BaseHelper,
-  ApplicationError,
-  getError,
-  ErrorSchema,
-  Logger,
-} from '@venizia/ignis-inversion';
-
-import type {
-  TNullable,
-  ValueOrPromise,
-  ValueOf,
-  TClass,
-  TConstructor,
-  TAbstractConstructor,
-  TConstValue,
-  TBindingScope,
-  TBindingValueType,
-  IProvider,
-  IInjectMetadata,
-  IPropertyMetadata,
-  IInjectableMetadata,
-} from '@venizia/ignis-inversion';
-```
+# Inversion (DI)
 
-> [!NOTE]
-> The framework package `@venizia/ignis` re-exports DI-specific symbols (`Binding`, `BindingKeys`, `BindingScopes`, `BindingValueTypes`, `IProvider`, `isClass`, `isClassProvider`, `TBindingScope`, `TBindingValueType`, `IBindingTag`) from `@venizia/ignis-inversion` and adds higher-level helpers (`app.controller()`, `app.service()`, etc.). All types from inversion are also available via type-only re-exports.
+`@venizia/ignis-inversion` is the standalone IoC container - decorator-based injection, a fluent binding API, and singleton/transient scoping - that every other IGNIS package builds on.
 
-## Creating an Instance
+## In one example
 
-`Container` extends `BaseHelper`, providing a named scope for debugging context.
+The smallest real use: bind a class with constructor injection, then resolve it through the container.
 
 ```typescript
-import { Container } from '@venizia/ignis-inversion';
-
-const container = new Container({ scope: 'MyApp' });
-```
-
-The `scope` parameter is optional and defaults to `'Container'`. It is used for logging and error context only.
+import { Container, inject, BindingScopes } from '@venizia/ignis-inversion';
 
-Basic binding example:
-
-```typescript
-import { Container, BindingScopes } from '@venizia/ignis-inversion';
+class UserService {
+  constructor(@inject({ key: 'config.appName' }) private appName: string) {}
+}
 
 const container = new Container({ scope: 'MyApp' });
 
-// Bind a class (container instantiates with DI)
+container.bind<string>({ key: 'config.appName' }).toValue('MyApp');
 container.bind<UserService>({ key: 'services.UserService' })
   .toClass(UserService)
   .setScope(BindingScopes.SINGLETON);
 
-// Resolve the dependency
 const userService = container.get<UserService>({ key: 'services.UserService' });
 ```
 
-## Usage
-
-### Binding Values
+A class needs no decorator to be bindable - the binding is always created explicitly with `container.bind()`, and scope is set on the binding via `setScope()`. The framework layer (`@venizia/ignis`) creates these bindings for you for controllers, services, and repositories via `app.controller()` / `app.service()` / `@repository`.
 
-Three resolver strategies are available via the fluent `Binding` API:
+## How it works
 
-```typescript
-// Class -- container instantiates with DI
-container.bind<UserService>({ key: 'services.UserService' })
-  .toClass(UserService);
+- **Three ways to resolve a binding.** `toClass` (container instantiates with DI), `toValue` (returned as-is), `toProvider` (factory function or `IProvider` class). All `Binding` setters return `this`, so calls chain.
+- **Instantiation is two-phase.** Constructor injection runs first, reading `@inject` metadata by parameter index and passing resolved values as constructor args; property injection runs second, assigning each `@inject`-decorated property on the built instance. `container.resolve(cls)` and `container.instantiate(cls)` are the same method - `resolve` is an alias.
+- **Every constructor parameter must carry `@inject`.** The metadata array is index-keyed - an undecorated parameter leaves a hole the container has no way to fill. `instantiate()` refuses the class by name and parameter index rather than passing `undefined`.
+- **Namespaces auto-tag bindings.** A key like `services.UserService` tags the binding `services` automatically; `setTags()` adds more. `findByTag()` queries by tag, with an `exclude` list.
+- **Keys** can be a `string`, a `symbol`, or `{ namespace, key }` (built into a dotted string via `BindingKeys.build`).
 
-// Value -- return directly
-container.bind<string>({ key: 'APP_NAME' })
-  .toValue('MyApp');
+**Scopes**
 
-// Provider -- factory function
-container.bind<DatabaseConnection>({ key: 'db.connection' })
-  .toProvider((container) => {
-    const config = container.get<Config>({ key: 'config.database' });
-    return new DatabaseConnection(config);
-  });
-```
-
-#### Class-based Provider
-
-For complex creation logic, implement the `IProvider<T>` interface:
-
-```typescript
-import { IProvider, Container } from '@venizia/ignis-inversion';
-
-class DatabaseConnectionProvider implements IProvider<DatabaseConnection> {
-  value(container: Container): DatabaseConnection {
-    const config = container.get<Config>({ key: 'config.database' });
-    return new DatabaseConnection(config);
-  }
-}
-
-container.bind<DatabaseConnection>({ key: 'db.connection' })
-  .toProvider(DatabaseConnectionProvider);
-```
-
-When `toProvider` receives a class with a `value()` method on its prototype, the container instantiates the class (with full DI support) and then calls `value(container)` to produce the final value.
-
-#### Fluent Chaining
-
-All `Binding` setter methods return `this` for chaining:
-
-```typescript
-container.bind<CacheService>({ key: 'services.CacheService' })
-  .toClass(CacheService)
-  .setScope(BindingScopes.SINGLETON)
-  .setTags('infrastructure', 'cache');
-```
-
-#### Static Factory
-
-`Binding` also exposes a static factory for creating bindings outside a container:
-
-```typescript
-import { Binding, BindingScopes } from '@venizia/ignis-inversion';
+| Scope | Constant | Behavior |
+|-------|----------|----------|
+| Transient | `BindingScopes.TRANSIENT` | New instance on every resolution (default) |
+| Singleton | `BindingScopes.SINGLETON` | Cached on the `Binding` after first resolution |
 
-const binding = Binding.bind<IHealthCheckOptions>({
-  key: 'options.healthCheck',
-}).toValue({ restOptions: { path: '/health' } });
+> [!IMPORTANT]
+> Singleton caching lives on the `Binding` object, not the container. Rebinding a key creates a fresh `Binding` with its own cache; a `Binding` reference you hold onto keeps its own cache independent of `container.clear()`/`reset()` on a different `Binding` for the same key.
 
-// Register it on a container later
-container.set({ binding });
-```
+Property-injected classes only get their `@inject` properties populated when built through the container (`container.resolve()`/`instantiate()`) - `new MyClass()` leaves them `undefined`. The [Full reference](/extensions/helpers/inversion/reference) covers `MetadataRegistry`, `gets()`, key formats, `IProvider`, and every error message in detail.
 
-### Constructor Injection
+## Common tasks
 
-This is the recommended approach -- dependencies are explicit and available at instantiation.
+### Bind a class with constructor injection
 
 ```typescript
-import { inject, injectable, BindingScopes } from '@venizia/ignis-inversion';
-
-@injectable({ scope: BindingScopes.SINGLETON })
-class UserService {
+class OrderService {
   constructor(
-    @inject({ key: 'repositories.UserRepository' })
-    private userRepository: UserRepository,
-
-    @inject({ key: 'services.Logger', isOptional: true })
-    private logger?: Logger,
+    @inject({ key: 'repositories.OrderRepository' }) private orderRepository: OrderRepository,
+    @inject({ key: 'services.Logger', isOptional: true }) private logger?: Logger,
   ) {}
 }
 ```
 
-The container reads `@inject` metadata during `instantiate()` by constructor index (the `Reflect`-stored array is already index-keyed - no sort is performed), resolves each dependency, and passes them as constructor arguments.
-
-> [!IMPORTANT]
-> Every constructor parameter of a container-instantiated class must carry `@inject`. Mixing decorated and undecorated parameters is refused: an undecorated parameter leaves a hole in the index-keyed metadata array, and there is no channel through which the container could supply it anyway. `instantiate()` throws `[ClassName] Constructor parameter N has no @inject | Every parameter of a container-instantiated class must be decorated - the container cannot supply an undecorated one`.
-
-### Property Injection
+### Bind a value or a provider
 
 ```typescript
-import { inject, injectable } from '@venizia/ignis-inversion';
-
-@injectable({})
-class UserService {
-  @inject({ key: 'repositories.UserRepository' })
-  private userRepository: UserRepository;
+container.bind<string>({ key: 'APP_NAME' }).toValue('MyApp');
 
-  @inject({ key: 'services.Logger', isOptional: true })
-  private logger?: Logger;
-}
+container.bind<DatabaseConnection>({ key: 'db.connection' })
+  .toProvider((container) => {
+    const config = container.get<Config>({ key: 'config.database' });
+    return new DatabaseConnection(config);
+  });
 ```
 
-> [!WARNING]
-> Property-injected classes must be instantiated through the container (`container.resolve()` or `container.instantiate()`). Using `new MyClass()` directly will leave `@inject` properties as `undefined`.
-
-The instantiation algorithm is two-phase:
-1. **Constructor injection** -- reads `@inject` metadata on the constructor by parameter index (no sort - the metadata is already index-keyed), resolves from container
-2. **Property injection** -- reads property metadata, resolves and assigns each dependency to the instance
-
-### Scopes (Singleton / Transient)
-
-| Scope | Constant | Behavior |
-|-------|----------|----------|
-| Transient | `BindingScopes.TRANSIENT` | New instance every resolution (default) |
-| Singleton | `BindingScopes.SINGLETON` | Cached after first resolution, reused thereafter |
+### Set the scope
 
 ```typescript
-import { BindingScopes } from '@venizia/ignis-inversion';
-
-// Singleton -- one instance shared across all resolutions
 container.bind({ key: 'services.CacheService' })
   .toClass(CacheService)
-  .setScope(BindingScopes.SINGLETON);
-
-// Transient (default) -- new instance every time
-container.bind({ key: 'services.RequestHandler' })
-  .toClass(RequestHandler)
-  .setScope(BindingScopes.TRANSIENT);
-```
-
-> [!IMPORTANT]
-> Singleton caching is per-`Binding` object, not per-Container. If you rebind the same key, the old `Binding` retains its cache independently.
-
-#### Cache Management
-
-```typescript
-// Clear all singleton caches (bindings stay registered)
-container.clear();
-
-// Remove all bindings entirely (full reset)
-container.reset();
-
-// Clear cache for a single binding
-const binding = container.getBinding({ key: 'services.CacheService' });
-binding?.clearCache();
-```
-
-### Namespaces and Tags
-
-Bindings with namespaced keys (e.g., `services.UserService`) are automatically tagged with the namespace portion (`services`). You can also add custom tags manually.
-
-```typescript
-container.bind({ key: 'workers.EmailWorker' })
-  .toClass(EmailWorker)
-  .setTags('background', 'email');
-// This binding now has tags: ['workers', 'background', 'email']
-
-// Find all bindings tagged 'services'
-const serviceBindings = container.findByTag({ tag: 'services' });
-
-// Exclude specific keys
-const filtered = container.findByTag({
-  tag: 'services',
-  exclude: ['services.InternalService'],
-});
-```
-
-#### Building Namespaced Keys
-
-```typescript
-import { BindingKeys } from '@venizia/ignis-inversion';
-
-BindingKeys.build({ namespace: 'services', key: 'UserService' });
-// => 'services.UserService'
-
-// The key parameter is required; an empty key throws an error
-BindingKeys.build({ namespace: '', key: 'UserService' });
-// => 'UserService'
+  .setScope(BindingScopes.SINGLETON); // default is TRANSIENT if omitted
 ```
 
-### Key Formats
-
-The `get`, `getBinding`, and `gets` methods accept three key formats:
-
-```typescript
-// String key
-container.get<UserService>({ key: 'services.UserService' });
-
-// Symbol key
-container.get<UserService>({ key: Symbol.for('services.UserService') });
-
-// Namespaced object (built via BindingKeys.build internally)
-container.get<UserService>({ key: { namespace: 'services', key: 'UserService' } });
-```
-
-### Optional Dependencies
-
-```typescript
-// Returns undefined instead of throwing if not bound
-const maybeSvc = container.get<MyService>({
-  key: 'services.Optional',
-  isOptional: true,
-});
-
-// In decorators
-@inject({ key: 'services.Logger', isOptional: true })
-private logger?: Logger;
-```
-
-### Resolving Multiple Dependencies
-
-```typescript
-const [svcA, svcB] = container.gets<[ServiceA, ServiceB]>({
-  bindings: [
-    { key: 'services.ServiceA' },
-    { key: 'services.ServiceB', isOptional: true },
-  ],
-});
-```
-
-> [!NOTE]
-> `gets()` internally calls `get()` with `isOptional: true` for each entry. Unresolved bindings return `undefined` rather than throwing.
-
-### Instantiate Without Binding
-
-```typescript
-// Create an instance with full DI resolution but don't register it
-const instance = container.resolve<MyClass>(MyClass);
-// or equivalently:
-const instance2 = container.instantiate<MyClass>(MyClass);
-```
-
-Both methods perform the same two-phase instantiation (constructor injection, then property injection). `resolve()` is an alias for `instantiate()`.
-
-### Checking and Removing Bindings
+### Inject into a property instead of the constructor
 
 ```typescript
-// Check if a key is registered
-container.isBound({ key: 'services.UserService' }); // true or false
-
-// Remove a binding
-container.unbind({ key: 'services.UserService' }); // returns true if removed, false if not found
-```
-
-### MetadataRegistry
-
-The `MetadataRegistry` is a singleton that stores all decorator metadata using `reflect-metadata`. Both `@inject` and `@injectable` delegate to it. You typically will not interact with the registry directly.
-
-```typescript
-import { MetadataKeys, metadataRegistry } from '@venizia/ignis-inversion';
-
-// Well-known metadata keys
-MetadataKeys.PROPERTIES  // Symbol.for('ignis:properties')
-MetadataKeys.INJECT      // Symbol.for('ignis:inject')
-MetadataKeys.INJECTABLE  // Symbol.for('ignis:injectable')
-
-// Access via container
-const registry = container.getMetadataRegistry();
-```
-
-The registry also supports generic metadata operations for storing arbitrary metadata on any object:
-
-```typescript
-metadataRegistry.define({ target: myObj, key: 'custom:flag', value: true });
-metadataRegistry.get({ target: myObj, key: 'custom:flag' }); // true
-metadataRegistry.has({ target: myObj, key: 'custom:flag' }); // true
-metadataRegistry.delete({ target: myObj, key: 'custom:flag' }); // true
-```
-
-### @injectable Decorator
-
-Marks a class with DI metadata (scope and tags). Used by the framework layer to configure bindings automatically.
-
-```typescript
-@injectable({
-  scope: BindingScopes.SINGLETON,
-  tags: { category: 'infrastructure' },
-})
-class CacheService {
-  // ...
+class UserService {
+  @inject({ key: 'repositories.UserRepository' })
+  private userRepository: UserRepository;
 }
 ```
 
-### Utilities
-
-#### ApplicationError and getError
-
-Error factory used internally and available for consumers:
-
-```typescript
-import { ApplicationError, getError, ErrorSchema } from '@venizia/ignis-inversion';
-
-// Factory function
-throw getError({ message: 'Something failed', statusCode: 500, messageCode: 'ERR_INTERNAL' });
-
-// Direct construction (defaults to statusCode 400)
-throw new ApplicationError({ message: 'Not found', statusCode: 404 });
-
-// Zod schema for validation
-ErrorSchema.parse({ message: 'test', statusCode: 400 });
-```
-
-#### Logger
+### Resolve an optional dependency
 
-Lightweight console logger (debug output requires `process.env.DEBUG`):
+`isOptional: true` returns `undefined` instead of throwing when the key is unbound - on the constructor and via `container.get()`. `gets()` resolves several keys at once, always treating each as optional.
 
 ```typescript
-import { Logger } from '@venizia/ignis-inversion';
-
-Logger.info('Server started on port %d', 3000);
-Logger.warn('Deprecation warning');
-Logger.error('Connection failed: %s', err.message);
-Logger.debug('Resolved binding: %s', key); // Only prints when DEBUG env var is set
+const maybeService = container.get<MyService>({ key: 'services.Optional', isOptional: true });
 ```
 
-## API Summary
-
-### Container
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `bind` | `bind<T>(opts: { key: string \| symbol }): Binding<T>` | Create and register a new binding |
-| `get` | `get<T>(opts: { key: string \| symbol \| { namespace, key }, isOptional?: boolean }): T` | Resolve a dependency by key; throws if not found and `isOptional` is `false` |
-| `gets` | `gets<T>(opts: { bindings: Array<{ key, isOptional? }> }): T[]` | Resolve multiple dependencies at once (all treated as optional) |
-| `getBinding` | `getBinding<T>(opts: { key: string \| symbol \| { namespace, key } }): Binding<T> \| undefined` | Retrieve the raw `Binding` without resolving |
-| `set` | `set<T>(opts: { binding: Binding<T> }): void` | Register an externally-created binding |
-| `isBound` | `isBound(opts: { key: string \| symbol }): boolean` | Check if a key is registered |
-| `unbind` | `unbind(opts: { key: string \| symbol }): boolean` | Remove a binding; returns `true` if removed |
-| `resolve` | `resolve<T>(cls: TClass<T>): T` | Alias for `instantiate` |
-| `instantiate` | `instantiate<T>(cls: TClass<T>): T` | Create instance with full DI (constructor + property injection) |
-| `findByTag` | `findByTag<T>(opts: { tag: string, exclude?: string[] \| Set<string> }): Binding<T>[]` | Find all bindings matching a tag, optionally excluding keys |
-| `clear` | `clear(): void` | Clear all singleton caches (bindings remain) |
-| `reset` | `reset(): void` | Remove all bindings entirely |
-| `getMetadataRegistry` | `getMetadataRegistry(): MetadataRegistry` | Access the shared MetadataRegistry singleton |
-
-### Binding
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `toClass` | `toClass(value: TClass<T>): this` | Container instantiates the class with DI |
-| `toValue` | `toValue(value: T): this` | Return value directly |
-| `toProvider` | `toProvider(value: ((container) => T) \| TClass<IProvider<T>>): this` | Factory function or `IProvider` class |
-| `setScope` | `setScope(scope: TBindingScope): this` | Set to `'singleton'` or `'transient'` (default) |
-| `setTags` | `setTags(...tags: string[]): this` | Add string tags (namespace auto-tagged from key) |
-| `hasTag` | `hasTag(tag: string): boolean` | Check if binding has a specific tag |
-| `getTags` | `getTags(): string[]` | Get all tags as array |
-| `getScope` | `getScope(): TBindingScope` | Get current scope |
-| `getValue` | `getValue(container?: Container): T` | Resolve the bound value (respects scope caching) |
-| `getBindingMeta` | `getBindingMeta(opts: { type: TBindingValueType }): any` | Get raw resolver value; throws if type does not match |
-| `clearCache` | `clearCache(): void` | Clear singleton cache for this binding |
-| `bind` (static) | `static bind<T>(opts: { key: string }): Binding<T>` | Static factory to create a Binding outside a container |
-
-### MetadataRegistry
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `define` | `define<Target, Value>(opts: { target: Target, key: string \| symbol, value: Value }): void` | Store arbitrary metadata on a target |
-| `get` | `get<Target, Value>(opts: { target: Target, key: string \| symbol }): Value \| undefined` | Retrieve metadata by key |
-| `has` | `has<Target>(opts: { target: Target, key: string \| symbol }): boolean` | Check if metadata exists |
-| `delete` | `delete<Target>(opts: { target: Target, key: string \| symbol }): boolean` | Remove metadata by key |
-| `getKeys` | `getKeys<Target>(opts: { target: Target }): (string \| symbol)[]` | List all metadata keys on a target |
-| `getMethodNames` | `getMethodNames<T>(opts: { target: TClass<T> }): string[]` | List non-constructor method names on a class prototype |
-| `clearMetadata` | `clearMetadata<T>(opts: { target: T }): void` | Remove all metadata from a target |
-| `setInjectMetadata` | `setInjectMetadata<T>(opts: { target: T, index: number, metadata: IInjectMetadata }): void` | Store constructor `@inject` metadata at parameter index |
-| `getInjectMetadata` | `getInjectMetadata<T>(opts: { target: T }): IInjectMetadata[] \| undefined` | Get all constructor injection metadata |
-| `setPropertyMetadata` | `setPropertyMetadata<T>(opts: { target: T, propertyName: string \| symbol, metadata: IPropertyMetadata }): void` | Store property `@inject` metadata |
-| `getPropertiesMetadata` | `getPropertiesMetadata<T>(opts: { target: T }): Map<string \| symbol, IPropertyMetadata> \| undefined` | Get all property injection metadata |
-| `getPropertyMetadata` | `getPropertyMetadata<T>(opts: { target: T, propertyName: string \| symbol }): IPropertyMetadata \| undefined` | Get single property injection metadata |
-| `setInjectableMetadata` | `setInjectableMetadata<T>(opts: { target: T, metadata: IInjectableMetadata }): void` | Store `@injectable` metadata |
-| `getInjectableMetadata` | `getInjectableMetadata<T>(opts: { target: T }): IInjectableMetadata \| undefined` | Get `@injectable` metadata |
-
-### Decorators
-
-| Decorator | Signature | Description |
-|-----------|-----------|-------------|
-| `@inject` | `inject(opts: { key: string \| symbol, isOptional?: boolean, registry?: MetadataRegistry })` | Marks a constructor parameter or property for dependency injection |
-| `@injectable` | `injectable(metadata: { scope?: TBindingScope, tags?: Record<string, any> }, registry?: MetadataRegistry)` | Marks a class with DI metadata (scope and tags) |
-
-### Constants
-
-| Constant | Values | Description |
-|----------|--------|-------------|
-| `BindingScopes.SINGLETON` | `'singleton'` | Cached after first resolution |
-| `BindingScopes.TRANSIENT` | `'transient'` | New instance each resolution |
-| `BindingValueTypes.CLASS` | `'class'` | Container instantiates with DI |
-| `BindingValueTypes.VALUE` | `'value'` | Direct value return |
-| `BindingValueTypes.PROVIDER` | `'provider'` | Factory function or IProvider class |
-| `MetadataKeys.PROPERTIES` | `Symbol.for('ignis:properties')` | Property injection metadata key |
-| `MetadataKeys.INJECT` | `Symbol.for('ignis:inject')` | Constructor injection metadata key |
-| `MetadataKeys.INJECTABLE` | `Symbol.for('ignis:injectable')` | Injectable class metadata key |
-
-### Exported Types
+### Instantiate a class without registering it
 
 ```typescript
-type TNullable<T> = T | undefined | null;
-type ValueOrPromise<T> = T | Promise<T>;
-type ValueOf<T> = T[keyof T];
-type TConstructor<T> = new (...args: any[]) => T;
-type TAbstractConstructor<T> = abstract new (...args: any[]) => T;
-type TClass<T> = TConstructor<T> & { [property: string]: any };
-type TConstValue<T extends TClass<any>> = Extract<ValueOf<T>, string | number>;
-type TBindingScope = 'singleton' | 'transient';
-type TBindingValueType = 'class' | 'value' | 'provider';
-
-interface IProvider<T> {
-  value(container: Container): T;
-}
-
-interface IInjectMetadata {
-  key: string | symbol;
-  index: number;
-  isOptional?: boolean;
-}
-
-interface IPropertyMetadata {
-  bindingKey: string | symbol;
-  isOptional?: boolean;
-  [key: string]: any;
-}
-
-interface IInjectableMetadata {
-  scope?: TBindingScope;
-  tags?: Record<string, any>;
-}
-
-// Type guards
-function isClass<T>(target: any): target is TClass<T>;
-function isClassProvider<T>(target: any): target is TClass<IProvider<T>>;
+const instance = container.resolve<MyClass>(MyClass); // full DI, not bound to a key
 ```
 
-## Troubleshooting
-
-### "Binding key: X is not bounded in context!"
-
-**Cause:** The dependency was never registered with the container, or the key string does not match exactly.
-
-**Fix:**
-1. Verify the binding exists: `container.isBound({ key: 'services.UserService' })`.
-2. Check for typos in the key passed to `@inject({ key: '...' })` vs the key used in `container.bind({ key: '...' })`.
-3. If the dependency is optional, use `@inject({ key: '...', isOptional: true })` or `container.get({ key: '...', isOptional: true })`.
-
-### "[getValue] Invalid context/container to instantiate class"
-
-**Cause:** A `Binding` configured with `toClass()` was resolved without a `Container` reference. This happens when calling `binding.getValue()` directly without passing a container.
-
-**Fix:** Always resolve class bindings through the container via `container.get({ key })` rather than calling `binding.getValue()` without arguments.
-
-### "[getValue] Invalid context/container to get provider value"
-
-**Cause:** A `Binding` configured with `toProvider()` was resolved without a `Container` reference.
-
-**Fix:** Same as above -- resolve provider bindings through the container via `container.get({ key })`.
-
-### "[getBindingMeta] Invalid resolver type"
-
-**Cause:** Called `getBindingMeta({ type })` with a type that does not match the binding's actual resolver type (e.g., asking for `'class'` on a value binding).
-
-**Fix:** Ensure the `type` parameter matches the binding's resolver. Check what was used: `toClass()` = `'class'`, `toValue()` = `'value'`, `toProvider()` = `'provider'`.
-
-### "[getBinding] Invalid binding key type"
-
-**Cause:** The key passed to `getBinding()` is not a `string`, `symbol`, or `{ namespace, key }` object.
-
-**Fix:** Use one of the three supported key formats: a string, a symbol, or an object with `namespace` and `key` properties.
-
-### "[BindingKeys][build] Invalid key to build"
-
-**Cause:** Called `BindingKeys.build()` with an empty `key` value.
-
-**Fix:** Provide a non-empty `key` string: `BindingKeys.build({ namespace: 'services', key: 'UserService' })`.
-
-### "[ClassName] Constructor parameter N has no @inject"
-
-**Cause:** A container-instantiated class has a constructor with a mix of decorated and undecorated parameters. `@inject` stores its metadata at the parameter's index, so an undecorated parameter leaves a hole in that index-keyed array; there is no channel through which the container could supply it anyway. `instantiate()` refuses the shape by name and index rather than passing `undefined`.
-
-**Fix:** Decorate every constructor parameter of the class with `@inject`. There is no partial-injection escape hatch - if a value does not come from the container (e.g. a plain `scope: string`), pass it through a factory/provider instead of a bare constructor parameter, or have the subclass forward it via its own `@inject`-decorated parameter.
-
-### "@inject decorator can only be used on class properties or constructor parameters"
-
-**Cause:** The `@inject` decorator was applied to something other than a class property or constructor parameter.
-
-**Fix:** Only use `@inject` on constructor parameters or class properties.
-
-### "Property injection returns undefined"
-
-**Cause:** The class was instantiated with `new MyClass()` directly instead of going through the container.
-
-**Fix:** Always use `container.resolve(MyClass)` or `container.instantiate(MyClass)` to create instances. Only the container reads `@inject` metadata and populates injected properties.
-
-### "getInjectMetadata returns undefined"
-
-**Cause:** `reflect-metadata` was not imported before decorators were evaluated, or `experimentalDecorators` / `emitDecoratorMetadata` are not enabled in `tsconfig.json`.
-
-**Fix:**
-1. Ensure `import 'reflect-metadata'` is at the top of your entry point (or rely on `@venizia/ignis-inversion` which imports it automatically).
-2. Verify your `tsconfig.json` includes:
-   ```json
-   {
-     "compilerOptions": {
-       "experimentalDecorators": true,
-       "emitDecoratorMetadata": true
-     }
-   }
-   ```
-
-### "Singleton returns stale instance after rebinding"
-
-**Cause:** Singleton caching is per-`Binding` object. If you hold a direct reference to an old `Binding` (e.g., from `getBinding()`), its cache is independent of the container.
-
-**Fix:**
-1. Always resolve via `container.get()` rather than caching `Binding` references.
-2. Call `container.clear()` to clear all singleton caches without removing bindings.
-3. Call `container.reset()` to remove all bindings entirely.
-
-## See Also
-
-- **Guides:**
-  - [Dependency Injection Guide](/guides/core-concepts/dependency-injection) - DI fundamentals
-  - [Application](/guides/core-concepts/application/) - Application extends Container
+## See also
 
-- **Other Helpers:**
-  - [Helpers Index](../index) - All available helpers
+- [Full reference](/extensions/helpers/inversion/reference) - every method, `MetadataRegistry`, error message, and edge case
+- [Dependency Injection Guide](/guides/core-concepts/dependency-injection) - DI fundamentals in the framework layer
+- [Application](/guides/core-concepts/application/) - `Application` extends `Container`
+- [Dependency Injection API](/references/base/dependency-injection) - the framework-layer DI reference
+- [Helpers Overview](/extensions/helpers/) - all available helpers
+- [Architectural Patterns](/best-practices/architectural-patterns) - DI patterns
 
-- **References:**
-  - [Dependency Injection API](/references/base/dependency-injection) - Complete DI reference
+**Files:**
 
-- **Best Practices:**
-  - [Architectural Patterns](/best-practices/architectural-patterns) - DI patterns
+- [`packages/inversion/src/modules/container/container.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/inversion/src/modules/container/container.ts) - `Container`, two-phase `instantiate()`
+- [`packages/inversion/src/modules/container/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/inversion/src/modules/container/base.ts) - `BaseContainer`, binding storage
+- [`packages/inversion/src/modules/binding/binding.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/inversion/src/modules/binding/binding.ts) - `Binding`
+- [`packages/inversion/src/modules/metadata/injectors.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/inversion/src/modules/metadata/injectors.ts) - `@inject`
+- [`packages/inversion/src/modules/registry/registry.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/inversion/src/modules/registry/registry.ts) - `MetadataRegistry`