# 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

| 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';
```

> [!NOTE]
> The framework package `@venizia/ignis` re-exports DI-specific symbols (`Binding`, `BindingKeys`, `BindingScopes`, `BindingValueTypes`, `IProvider`, `isClass`, `isClassProvider`, `isClassConstructor`, `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.

## Creating an Instance

`Container` extends `BaseHelper`, providing a named scope for debugging context.

```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.

Basic binding example:

```typescript
import { Container, BindingScopes } from '@venizia/ignis-inversion';

const container = new Container({ scope: 'MyApp' });

// Bind a class (container instantiates with DI)
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

Three resolver strategies are available via the fluent `Binding` API:

```typescript
// Class -- container instantiates with DI
container.bind<UserService>({ key: 'services.UserService' })
  .toClass(UserService);

// Value -- return directly
container.bind<string>({ key: 'APP_NAME' })
  .toValue('MyApp');

// 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';

const binding = Binding.bind<IHealthCheckOptions>({
  key: 'options.healthCheck',
}).toValue({ restOptions: { path: '/health' } });

// Register it on a container later
container.set({ binding });
```

### Constructor Injection

This is the recommended approach -- dependencies are explicit and available at instantiation.

```typescript
import { inject, injectable, BindingScopes } from '@venizia/ignis-inversion';

@injectable({ scope: BindingScopes.SINGLETON })
class UserService {
  constructor(
    @inject({ key: 'repositories.UserRepository' })
    private userRepo: UserRepository,

    @inject({ key: 'services.Logger', isOptional: true })
    private logger?: Logger,
  ) {}
}
```

The container reads `@inject` metadata during `instantiate()`, sorts by parameter index, resolves each dependency, and passes them as constructor arguments.

### Property Injection

```typescript
import { inject, injectable } from '@venizia/ignis-inversion';

@injectable({})
class UserService {
  @inject({ key: 'repositories.UserRepository' })
  private userRepo: UserRepository;

  @inject({ key: 'services.Logger', isOptional: true })
  private logger?: Logger;
}
```

> [!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, sorts by parameter index, 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 |

```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'
```

### 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

```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 {
  // ...
}
```

### 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

Lightweight console logger (debug output requires `process.env.DEBUG`):

```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
```

## 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

```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>>;
function isClassConstructor(fn: Function): boolean;
```

## 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' })`.

### "@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

- **Other Helpers:**
  - [Helpers Index](../index) - All available helpers

- **References:**
  - [Dependency Injection API](/references/base/dependency-injection) - Complete DI reference

- **Best Practices:**
  - [Architectural Patterns](/best-practices/architectural-patterns) - DI patterns