injectus 0.1.1-alpha.0 → 0.2.0

package/README.md

@@ -1,3 +1,322 @@
 # Injectus
 
-High-performant, decorator-free IoC container for Node.js — sync inject(), explicit lifetimes, TC39-native disposal.
+[![npm](https://img.shields.io/npm/v/injectus.svg?maxAge=1000)](https://www.npmjs.com/package/injectus)
+[![CI](https://github.com/hossam7amdy/injectus/actions/workflows/ci.yaml/badge.svg)](https://github.com/hossam7amdy/injectus/actions/workflows/ci.yaml)
+[![coveralls](https://coveralls.io/repos/github/hossam7amdy/injectus/badge.svg)](https://coveralls.io/github/hossam7amdy/injectus)
+[![npm](https://img.shields.io/npm/l/injectus.svg?maxAge=1000)](https://github.com/hossam7amdy/injectus/blob/main/LICENSE)
+[![node](https://img.shields.io/node/v/injectus.svg?maxAge=1000)](https://www.npmjs.com/package/injectus)
+
+Zero-dependency, decorator-free IoC container for Node.js.
+
+```ts
+import { Injector, inject, Lifetime, InjectionToken } from "injectus";
+
+const DB_URL = new InjectionToken<string>("DB_URL");
+
+class Database {
+  url = inject(DB_URL);
+}
+
+class UserService {
+  db = inject(Database);
+  findAll() {
+    return this.db.url;
+  }
+}
+
+const injector = Injector.create({
+  providers: [
+    { provide: DB_URL, useValue: "postgres://localhost/app" },
+    Database,
+    UserService,
+  ],
+});
+
+injector.resolve(UserService).findAll();
+
+await injector.dispose();
+```
+
+## Install
+
+```sh
+npm install injectus
+```
+
+```sh
+pnpm add injectus
+```
+
+```sh
+yarn add injectus
+```
+
+**Requires Node.js ≥ 22.6.0.** The library uses `Symbol.asyncDispose` (TC39 Explicit Resource Management) and ships as native ESM. No browser support — designed for server-side use where synchronous resolution is a guarantee.
+
+> **`await using` requires Node.js ≥ 24.** The `await using` syntax is a parse-time feature unavailable on Node 22.x. On Node 22 use the equivalent manual form: `const injector = Injector.create(...)` followed by `await injector.dispose()`.
+
+> **Design note:** The functional `inject()` API is directly inspired by Angular's modern DI (v14+). Everything else is stripped for the backend: no zone.js, no component trees, no async factories — just plain injectors, explicit lifetimes, and safe disposal.
+
+---
+
+## Providers
+
+Five registration forms, all accepted in the `providers` array:
+
+```ts
+// Bare class — sugar for { provide: C, useClass: C, lifetime: Singleton }
+providers: [MyService]
+
+// Construct a class (inject() works in field initializers)
+{ provide: Cache, useClass: RedisCache, lifetime: Lifetime.Singleton }
+
+// Factory function (inject() works inside the body)
+{ provide: Config, useFactory: () => loadConfig() }
+
+// Pre-built value — the injector never disposes it
+{ provide: DB_URL, useValue: "postgres://localhost/app" }
+
+// Alias — re-dispatches through the calling injector, so child overrides apply
+{ provide: ICache, useExisting: RedisCache }
+```
+
+Last registration for a token wins — child injectors shadow parent bindings.
+
+---
+
+## Tokens
+
+Classes are their own tokens. For interfaces, primitives, and config use `InjectionToken`:
+
+```ts
+import { InjectionToken } from "injectus";
+
+const PORT = new InjectionToken<number>("PORT");
+const DB_URL = new InjectionToken<string>("DB_URL");
+abstract class Cache {
+  abstract get(k: string): string | null;
+}
+```
+
+Two tokens with the same description are **distinct keys** — identity, not name, is the key.
+
+---
+
+## Lifetimes
+
+| Lifetime                | Behaviour                                                                       |
+| ----------------------- | ------------------------------------------------------------------------------- |
+| `Singleton` _(default)_ | One instance per owning injector. Cached.                                       |
+| `Scoped`                | One instance per child injector.                                                |
+| `Transient`             | Fresh instance on every `resolve()` / `inject()`. Never cached, never disposed. |
+
+```ts
+import { Lifetime } from "injectus";
+
+{ provide: Logger,    useClass: Logger,    lifetime: Lifetime.Singleton  }
+{ provide: Session,   useClass: Session,   lifetime: Lifetime.Scoped     }
+{ provide: RequestId, useFactory: () => crypto.randomUUID(),
+                                           lifetime: Lifetime.Transient  }
+```
+
+**Captive dependency detection.** Resolving a `Singleton` that depends — directly or transitively — on a `Scoped` throws `CaptiveDependencyError` at resolve time, not silently in production. This is a deliberate safety guarantee that most DI libraries skip.
+
+---
+
+## Hierarchy
+
+Child injectors inherit all parent bindings and own their `Scoped` instances independently. This maps naturally to HTTP request lifecycles.
+
+```ts
+const app = Injector.create({
+  name: "app",
+  providers: [Database, UserService],
+});
+
+// per-request child
+const req = Injector.create({
+  name: "request",
+  parent: app,
+  providers: [
+    {
+      provide: REQUEST_ID,
+      useFactory: () => crypto.randomUUID(),
+      lifetime: Lifetime.Scoped,
+    },
+    {
+      provide: RequestLogger,
+      useClass: RequestLogger,
+      lifetime: Lifetime.Scoped,
+    },
+  ],
+});
+
+req.resolve(UserService); // Database comes from app
+req.resolve(RequestLogger); // owned and cached by req
+```
+
+Each injector disposes only what it constructed — disposing `req` never touches `app`'s instances.
+
+---
+
+## inject()
+
+Resolves a token through the **active injection context** — the injector currently constructing an instance. Valid only synchronously inside a `useFactory` body or a class field initializer.
+
+```ts
+class Mailer {
+  smtp = inject(SmtpClient);
+  audit = inject(AuditService, { optional: true }); // null if not registered
+}
+```
+
+Calling `inject()` outside a construction context throws `InjectionContextError`. It does not work across async boundaries (`await`, `setTimeout`, `Promise`) — all wiring must be synchronous.
+
+---
+
+## withInjector()
+
+Runs a function under a given injector's context. `inject()` calls inside `fn` resolve through `injector`. Useful for manual wiring and test setup.
+
+```ts
+import { withInjector } from "injectus";
+
+const svc = withInjector(injector, () => new MyService());
+```
+
+---
+
+## Disposal
+
+Injectors implement TC39 Explicit Resource Management. Instances with `Symbol.dispose` or `Symbol.asyncDispose` are tracked and called in **reverse construction order (LIFO)** on `dispose()`.
+
+```ts
+class DbPool {
+  async [Symbol.asyncDispose]() { await this.pool.end(); }
+}
+
+// Manual
+await injector.dispose();
+
+// Automatic with `await using`
+{
+  await using injector = Injector.create({ providers: [...] });
+  // injector.dispose() is called at block exit, even on throw
+}
+```
+
+**Rules:**
+
+- Each injector disposes only what it constructed. Parents and children are independent.
+- `useValue` providers are **never disposed** — the caller owns them.
+- `Transient` instances are **never tracked** — manage their lifecycle at the call site.
+- `dispose()` is idempotent. Concurrent calls share one run.
+- Multiple failing disposers are collected into a single `AggregateError`.
+
+---
+
+## Testing
+
+**Unit — swap real deps with values:**
+
+```ts
+import { Injector, inject, withInjector } from "injectus";
+
+class UserService {
+  db = inject(Database);
+  logger = inject(Logger);
+}
+
+const injector = Injector.create({
+  providers: [
+    { provide: Database, useValue: mockDb },
+    { provide: Logger, useValue: mockLogger },
+    UserService,
+  ],
+});
+
+const svc = injector.resolve(UserService);
+// svc.db === mockDb, svc.logger === mockLogger
+```
+
+**Integration — shadow a single binding in production config:**
+
+```ts
+const injector = Injector.create({
+  providers: [
+    ...productionProviders,
+    { provide: Database, useValue: testDb }, // shadows the real Database
+  ],
+});
+```
+
+---
+
+## Error reference
+
+| Error                     | When                                                           |
+| ------------------------- | -------------------------------------------------------------- |
+| `TokenNotFoundError`      | No provider registered for the token                           |
+| `CircularDependencyError` | Cycle in the dependency graph (`A → B → A`)                    |
+| `CaptiveDependencyError`  | Singleton holds a Scoped dependency (directly or transitively) |
+| `InjectionContextError`   | `inject()` called outside a factory or field initializer       |
+| `InjectorDisposedError`   | Resolved from a disposed injector, or ancestor was disposed    |
+
+`CircularDependencyError` and `CaptiveDependencyError` extend `DependencyPathError`, which exposes the full dependency path root-to-leaf as `path: readonly Token[]` (also rendered in `message`).
+
+---
+
+## API reference
+
+### `Injector.create(options)`
+
+| Option            | Type         | Default                       | Description                            |
+| ----------------- | ------------ | ----------------------------- | -------------------------------------- |
+| `providers`       | `Provider[]` | required                      | Bindings for this injector             |
+| `parent`          | `Injector`   | —                             | Parent injector; omit for root         |
+| `name`            | `string`     | `"root"` / `"<parent>.child"` | Debug label, appears in error messages |
+| `defaultLifetime` | `Lifetime`   | `Lifetime.Singleton`          | Lifetime when a provider omits one     |
+
+### `injector.resolve(token, options?)`
+
+Resolves synchronously. Pass `{ optional: true }` to get `null` instead of throwing on a missing token.
+
+### `inject(token, options?)`
+
+Functional injection. Must be called synchronously during provider construction. Mirrors `injector.resolve()` through the active context.
+
+### `withInjector(injector, fn)`
+
+Runs `fn` with `injector` as the active context. Returns `fn`'s return value.
+
+### `Injector` properties
+
+| Property                | Type                  | Description                         |
+| ----------------------- | --------------------- | ----------------------------------- |
+| `parent`                | `Injector \| null`    | Parent injector, or `null` for root |
+| `name`                  | `string`              | Debug label                         |
+| `disposed`              | `boolean`             | `true` after `dispose()` is called  |
+| `dispose()`             | `() => Promise<void>` | Dispose tracked instances LIFO      |
+| `[Symbol.asyncDispose]` | `() => Promise<void>` | Alias — enables `await using`       |
+
+### `InjectionToken<T>`
+
+```ts
+const TOKEN = new InjectionToken<T>("description");
+token.description; // string
+token.toString(); // "InjectionToken(description)"
+```
+
+### `Lifetime`
+
+```ts
+Lifetime.Singleton; // "singleton"
+Lifetime.Scoped; // "scoped"
+Lifetime.Transient; // "transient"
+```
+
+---
+
+## Author
+
+[Hossam Hamdy](https://github.com/hossam7amdy) · [Issues](https://github.com/hossam7amdy/injectus/issues)

package/dist/binding.d.ts

@@ -0,0 +1,18 @@
+import type { InjectOptions } from "./context.ts";
+import type { Lifetime } from "./lifetime.ts";
+/** No cached value yet. */
+export declare const EMPTY: unique symbol;
+export type Empty = typeof EMPTY;
+/** Hydration in progress — cycle marker. */
+export declare const CIRCULAR: unique symbol;
+export type Circular = typeof CIRCULAR;
+/**
+ * Fixed field order across all bindings keeps V8's hidden class
+ * monomorphic on the hot resolve path — always go through `makeBinding`.
+ */
+export interface Binding<T = unknown> {
+    factory: ((options?: InjectOptions) => T | null) | undefined;
+    value: T | Empty | Circular;
+    lifetime: Lifetime;
+}
+export declare function makeBinding<T>(factory: ((options?: InjectOptions) => T | null) | undefined, value: T | Empty | Circular, lifetime: Lifetime): Binding<T>;

package/dist/binding.js

@@ -0,0 +1,7 @@
+/** No cached value yet. */
+export const EMPTY = Symbol("EMPTY");
+/** Hydration in progress — cycle marker. */
+export const CIRCULAR = Symbol("CIRCULAR");
+export function makeBinding(factory, value, lifetime) {
+    return { factory, value, lifetime };
+}

package/dist/context.d.ts

@@ -0,0 +1,50 @@
+import type { Lifetime } from "./lifetime.ts";
+import type { Token } from "./token.ts";
+/** Options for `injector.resolve()`. */
+export interface InjectOptions {
+    /** Return `null` instead of throwing when the token has no provider. */
+    optional?: boolean;
+}
+/** @internal Resolve-facing view of `Injector` consumed by the injection context. */
+export interface Injector {
+    resolve<T>(token: Token<T>): T;
+    resolve<T>(token: Token<T>, options: {
+        optional: true;
+    }): T | null;
+    resolve<T>(token: Token<T>, options?: InjectOptions): T | null;
+}
+export interface InjectionContext {
+    injector: Injector;
+    /** Strictest lifetime seen so far. Lets `hydrate()` detect captive dependencies in O(1). */
+    effectiveLifetime: Lifetime | undefined;
+}
+export declare function getInjectionContext(): InjectionContext | undefined;
+/** @internal Set current context, return previous. Always restore in a `finally`. */
+export declare function setInjectionContext(ctx: InjectionContext | undefined): InjectionContext | undefined;
+/**
+ * Resolve a token through the active injection context.
+ *
+ * Valid only synchronously inside a factory or class field initializer
+ * invoked by an `Injector`. Throws `InjectionContextError` elsewhere.
+ *
+ * @example
+ * class UserService {
+ *   db     = inject(Database);
+ *   config = inject(CONFIG, { optional: true }); // null when missing
+ * }
+ */
+export declare function inject<T>(token: Token<T>): T;
+export declare function inject<T>(token: Token<T>, options: {
+    optional: true;
+}): T | null;
+export declare function inject<T>(token: Token<T>, options?: InjectOptions): T | null;
+/**
+ * Run `fn` under `injector`'s injection context.
+ *
+ * `inject()` calls inside `fn` resolve through `injector`.
+ * Useful for manual wiring and test setup.
+ *
+ * @example
+ * const svc = withInjector(injector, () => new MyService());
+ */
+export declare function withInjector<R>(injector: Injector, fn: () => R): R;

package/dist/context.js

@@ -0,0 +1,39 @@
+import { InjectionContextError } from "./errors.js";
+let currentContext;
+export function getInjectionContext() {
+    return currentContext;
+}
+/** @internal Set current context, return previous. Always restore in a `finally`. */
+export function setInjectionContext(ctx) {
+    const prev = currentContext;
+    currentContext = ctx;
+    return prev;
+}
+export function inject(token, options) {
+    const ctx = currentContext;
+    if (ctx === undefined) {
+        throw new InjectionContextError(token);
+    }
+    return ctx.injector.resolve(token, options);
+}
+/**
+ * Run `fn` under `injector`'s injection context.
+ *
+ * `inject()` calls inside `fn` resolve through `injector`.
+ * Useful for manual wiring and test setup.
+ *
+ * @example
+ * const svc = withInjector(injector, () => new MyService());
+ */
+export function withInjector(injector, fn) {
+    const prev = setInjectionContext({
+        injector,
+        effectiveLifetime: currentContext?.effectiveLifetime,
+    });
+    try {
+        return fn();
+    }
+    finally {
+        setInjectionContext(prev);
+    }
+}

package/dist/disposable.d.ts

@@ -0,0 +1,10 @@
+/** Any object implementing TC39 Explicit Resource Management (`Symbol.dispose` or `Symbol.asyncDispose`). */
+export type DisposableLike = {
+    [Symbol.dispose](): void;
+} | {
+    [Symbol.asyncDispose](): Promise<void>;
+};
+/** @internal */
+export declare function isDisposable(value: unknown): value is DisposableLike;
+/** @internal Invoke the disposer. May return a Promise. */
+export declare function disposerOf(value: any): void | Promise<void>;

package/dist/disposable.js

@@ -0,0 +1,14 @@
+/** @internal */
+export function isDisposable(value) {
+    if (value == null)
+        return false;
+    return (typeof value[Symbol.asyncDispose] === "function" ||
+        typeof value[Symbol.dispose] === "function");
+}
+/** @internal Invoke the disposer. May return a Promise. */
+export function disposerOf(value) {
+    if (typeof value[Symbol.asyncDispose] === "function") {
+        return value[Symbol.asyncDispose]();
+    }
+    return value[Symbol.dispose]();
+}

package/dist/errors.d.ts

@@ -0,0 +1,41 @@
+import { type Token } from "./token.ts";
+/**
+ * Base for errors that accumulate a dependency path as the exception
+ * unwinds through nested `hydrate()` frames.
+ */
+export declare abstract class DependencyPathError extends Error {
+    #private;
+    constructor(leaf: Token);
+    /** Full dependency path, root-to-leaf. */
+    get path(): readonly Token[];
+    /** Prepend `token` to `error`'s path as the exception unwinds one frame. */
+    static prepend(error: DependencyPathError, token: Token): void;
+}
+/** Thrown when a cycle is detected in the dependency graph. The message renders the full path root-to-leaf. */
+export declare class CircularDependencyError extends DependencyPathError {
+    readonly name = "CircularDependencyError";
+    get message(): string;
+}
+/**
+ * Thrown when a singleton holds — directly or transitively — a scoped dependency.
+ * The message labels the scoped dependency and renders the full path root-to-leaf.
+ */
+export declare class CaptiveDependencyError extends DependencyPathError {
+    readonly name = "CaptiveDependencyError";
+    get message(): string;
+}
+/** Thrown when no provider is registered for a token. */
+export declare class TokenNotFoundError extends Error {
+    readonly name = "TokenNotFoundError";
+    constructor(token: Token, name: string);
+}
+/** Thrown when `inject()` is called outside an active injection context. */
+export declare class InjectionContextError extends Error {
+    readonly name = "InjectionContextError";
+    constructor(token: Token);
+}
+/** Thrown when an operation is attempted on a disposed injector. */
+export declare class InjectorDisposedError extends Error {
+    readonly name = "InjectorDisposedError";
+    constructor(name: string);
+}

package/dist/errors.js

@@ -0,0 +1,62 @@
+import { tokenName } from "./token.js";
+/**
+ * Base for errors that accumulate a dependency path as the exception
+ * unwinds through nested `hydrate()` frames.
+ */
+export class DependencyPathError extends Error {
+    #path;
+    constructor(leaf) {
+        super();
+        this.#path = [leaf];
+    }
+    /** Full dependency path, root-to-leaf. */
+    get path() {
+        return this.#path;
+    }
+    /** Prepend `token` to `error`'s path as the exception unwinds one frame. */
+    static prepend(error, token) {
+        error.#path.unshift(token);
+    }
+}
+/** Thrown when a cycle is detected in the dependency graph. The message renders the full path root-to-leaf. */
+export class CircularDependencyError extends DependencyPathError {
+    name = "CircularDependencyError";
+    get message() {
+        return `Circular dependency: ${this.path.map(tokenName).join(" -> ")}.`;
+    }
+}
+/**
+ * Thrown when a singleton holds — directly or transitively — a scoped dependency.
+ * The message labels the scoped dependency and renders the full path root-to-leaf.
+ */
+export class CaptiveDependencyError extends DependencyPathError {
+    name = "CaptiveDependencyError";
+    get message() {
+        const path = this.path;
+        const scoped = tokenName(path[path.length - 1]);
+        return (`Captive dependency: ${scoped} (scoped) cannot live inside a singleton. ` +
+            `Chain: ${path.map(tokenName).join(" -> ")}.`);
+    }
+}
+/** Thrown when no provider is registered for a token. */
+export class TokenNotFoundError extends Error {
+    name = "TokenNotFoundError";
+    constructor(token, name) {
+        super(`No provider registered for ${tokenName(token)} (Injector: "${name}").`);
+    }
+}
+/** Thrown when `inject()` is called outside an active injection context. */
+export class InjectionContextError extends Error {
+    name = "InjectionContextError";
+    constructor(token) {
+        super(`inject(${tokenName(token)}) called outside an injection context. ` +
+            `inject() may only run synchronously inside a factory or class field initializer invoked by an Injector.`);
+    }
+}
+/** Thrown when an operation is attempted on a disposed injector. */
+export class InjectorDisposedError extends Error {
+    name = "InjectorDisposedError";
+    constructor(name) {
+        super(`Injector "${name}" has been disposed.`);
+    }
+}

package/dist/index.d.ts

@@ -1 +1,6 @@
-export {};
+export { type InjectOptions, inject, withInjector, } from "./context.ts";
+export { CaptiveDependencyError, CircularDependencyError, DependencyPathError, InjectionContextError, InjectorDisposedError, TokenNotFoundError, } from "./errors.ts";
+export { Injector, type InjectorOptions, } from "./injector.ts";
+export { Lifetime } from "./lifetime.ts";
+export type { ClassProvider, ExistingProvider, FactoryProvider, Provider, ValueProvider, } from "./provider.ts";
+export { type Constructor, InjectionToken, type Token } from "./token.ts";

package/dist/index.js

@@ -1 +1,10 @@
-export {};
+// Injection context
+export { inject, withInjector, } from "./context.js";
+// Errors
+export { CaptiveDependencyError, CircularDependencyError, DependencyPathError, InjectionContextError, InjectorDisposedError, TokenNotFoundError, } from "./errors.js";
+// Injector
+export { Injector, } from "./injector.js";
+// Lifetimes
+export { Lifetime } from "./lifetime.js";
+// Tokens
+export { InjectionToken } from "./token.js";

package/dist/injector.d.ts

@@ -0,0 +1,69 @@
+import { type Injector as ContextInjector, type InjectOptions } from "./context.ts";
+import { Lifetime } from "./lifetime.ts";
+import type { Provider } from "./provider.ts";
+import type { Token } from "./token.ts";
+/** Options passed to `Injector.create()`. */
+export interface InjectorOptions {
+    /** Provider registrations for this injector. */
+    providers: Provider[];
+    /** Debug label. Defaults to `"root"` for root injectors and `"<parent>.child"` for children. */
+    name?: string;
+    /** Parent injector. Omit to create a root; supply to create a child. */
+    parent?: Injector;
+    /** Lifetime applied when a provider omits `lifetime`. @default Lifetime.Singleton */
+    defaultLifetime?: Lifetime;
+}
+/**
+ * IoC container. Holds provider bindings, caches instances by lifetime,
+ * and disposes tracked instances in reverse construction order on `dispose()`.
+ *
+ * Root injectors own singletons. Child injectors (via `parent`) own scoped
+ * instances and inherit every parent binding. Each injector disposes only what
+ * it constructed — parents and children are independent.
+ *
+ * @example
+ * const root  = Injector.create({ providers: [Database] });
+ * const child = Injector.create({ providers: [RequestLogger], parent: root });
+ * child.resolve(RequestLogger); // gets Database from root
+ */
+export declare class Injector implements ContextInjector, AsyncDisposable {
+    #private;
+    /** Parent injector, or `null` for root injectors. */
+    readonly parent: Injector | null;
+    /** Debug label assigned at creation. Appears in error messages. */
+    readonly name: string;
+    /** @internal Prefer `Injector.create()`. */
+    constructor(providers: Provider[], name: string, parent: Injector | null, defaultLifetime: Lifetime);
+    /**
+     * Create a root injector, or a child injector when `options.parent` is supplied.
+     *
+     * @example
+     * const injector = Injector.create({
+     *   providers: [Database, UserService],
+     * });
+     */
+    static create(options: InjectorOptions): Injector;
+    /**
+     * Resolve a token synchronously.
+     *
+     * Walks the injector chain, respects lifetimes, and detects captive dependencies.
+     * Throws `TokenNotFoundError` unless `{ optional: true }` is passed.
+     */
+    resolve<T>(token: Token<T>): T;
+    resolve<T>(token: Token<T>, options: {
+        optional: true;
+    }): T | null;
+    resolve<T>(token: Token<T>, options?: InjectOptions): T | null;
+    private findBinding;
+    private hydrate;
+    /**
+     * Dispose all tracked instances in reverse construction order (LIFO), sequentially.
+     * Idempotent — concurrent calls share one run.
+     * On failure: a single error is rethrown as-is; multiple are wrapped in `AggregateError`.
+     */
+    dispose(): Promise<void>;
+    /** Alias for `dispose()` — enables `await using injector = Injector.create(...)`. */
+    [Symbol.asyncDispose](): Promise<void>;
+    /** `true` after `dispose()` has been called, even if disposal threw. */
+    get disposed(): boolean;
+}

package/dist/injector.js

@@ -0,0 +1,198 @@
+import { CIRCULAR, EMPTY, makeBinding } from "./binding.js";
+import { getInjectionContext, inject, setInjectionContext, } from "./context.js";
+import { disposerOf, isDisposable } from "./disposable.js";
+import { CaptiveDependencyError, CircularDependencyError, DependencyPathError, InjectorDisposedError, TokenNotFoundError, } from "./errors.js";
+import { Lifetime, minLifetime } from "./lifetime.js";
+/**
+ * IoC container. Holds provider bindings, caches instances by lifetime,
+ * and disposes tracked instances in reverse construction order on `dispose()`.
+ *
+ * Root injectors own singletons. Child injectors (via `parent`) own scoped
+ * instances and inherit every parent binding. Each injector disposes only what
+ * it constructed — parents and children are independent.
+ *
+ * @example
+ * const root  = Injector.create({ providers: [Database] });
+ * const child = Injector.create({ providers: [RequestLogger], parent: root });
+ * child.resolve(RequestLogger); // gets Database from root
+ */
+export class Injector {
+    #bindings;
+    #disposers;
+    /** Parent injector, or `null` for root injectors. */
+    parent;
+    /** Debug label assigned at creation. Appears in error messages. */
+    name;
+    #disposing;
+    /** @internal Prefer `Injector.create()`. */
+    constructor(providers, name, parent, defaultLifetime) {
+        if (parent != null)
+            throwIfDisposed(parent);
+        this.#bindings = new Map();
+        this.#disposers = [];
+        this.parent = parent;
+        this.name = name;
+        this.#disposing = null;
+        for (const provider of providers) {
+            const token = typeof provider === "function" ? provider : provider.provide;
+            this.#bindings.set(token, providerToBinding(provider, defaultLifetime));
+        }
+    }
+    /**
+     * Create a root injector, or a child injector when `options.parent` is supplied.
+     *
+     * @example
+     * const injector = Injector.create({
+     *   providers: [Database, UserService],
+     * });
+     */
+    static create(options) {
+        const parent = options.parent ?? null;
+        const defaultLifetime = options.defaultLifetime ?? Lifetime.Singleton;
+        const name = options.name ?? (parent ? `${parent.name}.child` : "root");
+        return new Injector(options.providers, name, parent, defaultLifetime);
+    }
+    resolve(token, options) {
+        const found = this.findBinding(token);
+        if (!found) {
+            if (options?.optional)
+                return null;
+            throw new TokenNotFoundError(token, this.name);
+        }
+        const { binding, injector } = found;
+        const prev = getInjectionContext();
+        // Singleton caches on owner; factory must run under owner's chain or child shadow poisons parent cache
+        const owner = binding.lifetime === Lifetime.Singleton && injector !== this
+            ? injector
+            : this;
+        const prevInjectContext = setInjectionContext({
+            injector: owner,
+            effectiveLifetime: minLifetime(binding.lifetime, prev?.effectiveLifetime),
+        });
+        try {
+            if (binding.lifetime === Lifetime.Scoped && injector !== this) {
+                const scopedBinding = makeBinding(binding.factory, EMPTY, Lifetime.Scoped);
+                this.#bindings.set(token, scopedBinding);
+                return this.hydrate(token, scopedBinding, options);
+            }
+            return injector.hydrate(token, binding, options);
+        }
+        finally {
+            setInjectionContext(prevInjectContext);
+        }
+    }
+    findBinding(token) {
+        let s = this;
+        while (s !== null) {
+            throwIfDisposed(s);
+            const b = s.#bindings.get(token);
+            if (b !== undefined) {
+                return { binding: b, injector: s };
+            }
+            s = s.parent;
+        }
+        return null;
+    }
+    hydrate(token, binding, options) {
+        if (binding.value === CIRCULAR) {
+            throw new CircularDependencyError(token);
+        }
+        if (binding.value !== EMPTY) {
+            return binding.value;
+        }
+        const lifetime = binding.lifetime;
+        const ctx = getInjectionContext();
+        if (lifetime === Lifetime.Scoped &&
+            ctx.effectiveLifetime === Lifetime.Singleton) {
+            throw new CaptiveDependencyError(token);
+        }
+        binding.value = CIRCULAR;
+        let instance;
+        try {
+            instance = binding.factory(options);
+        }
+        catch (e) {
+            binding.value = EMPTY;
+            if (e instanceof DependencyPathError) {
+                DependencyPathError.prepend(e, token);
+            }
+            throw e;
+        }
+        if (lifetime === Lifetime.Transient) {
+            binding.value = EMPTY;
+        }
+        else {
+            binding.value = instance;
+            if (isDisposable(instance)) {
+                this.#disposers.push(() => disposerOf(instance));
+            }
+        }
+        return instance;
+    }
+    /**
+     * Dispose all tracked instances in reverse construction order (LIFO), sequentially.
+     * Idempotent — concurrent calls share one run.
+     * On failure: a single error is rethrown as-is; multiple are wrapped in `AggregateError`.
+     */
+    dispose() {
+        if (this.#disposing)
+            return this.#disposing;
+        this.#disposing = (async () => {
+            const errors = [];
+            // LIFO so consumers dispose before their deps.
+            for (let i = this.#disposers.length - 1; i >= 0; i--) {
+                try {
+                    await this.#disposers[i]();
+                }
+                catch (e) {
+                    errors.push(e);
+                }
+            }
+            this.#disposers.length = 0;
+            this.#bindings.clear();
+            if (errors.length === 1)
+                throw errors[0];
+            if (errors.length > 1) {
+                throw new AggregateError(errors, `Dispose errors in injector "${this.name}"`);
+            }
+        })();
+        return this.#disposing;
+    }
+    /** Alias for `dispose()` — enables `await using injector = Injector.create(...)`. */
+    [Symbol.asyncDispose]() {
+        return this.dispose();
+    }
+    /** `true` after `dispose()` has been called, even if disposal threw. */
+    get disposed() {
+        return this.#disposing !== null;
+    }
+}
+function providerToBinding(provider, defaultLifetime) {
+    let binding;
+    if (typeof provider === "function")
+        binding = makeBinding(() => new provider(), // class provider shorthand
+        EMPTY, defaultLifetime);
+    else if ("useValue" in provider)
+        binding = makeBinding(undefined, // hydrated immediately
+        provider.useValue, Lifetime.Singleton);
+    else if ("useFactory" in provider &&
+        typeof provider.useFactory === "function")
+        binding = makeBinding(provider.useFactory, EMPTY, provider.lifetime ?? defaultLifetime);
+    else if ("useClass" in provider && typeof provider.useClass === "function")
+        binding = makeBinding(() => new provider.useClass(), EMPTY, provider.lifetime ?? defaultLifetime);
+    else if ("useExisting" in provider && provider.useExisting != null)
+        binding = makeBinding((options) => inject(provider.useExisting, options), EMPTY, 
+        // Alias re-dispatches every time; target's binding owns caching.
+        Lifetime.Transient);
+    else {
+        throw new TypeError(`Unknown provider type.`, {
+            cause: provider,
+        });
+    }
+    return binding;
+}
+function throwIfDisposed(injector) {
+    if (injector.disposed) {
+        throw new InjectorDisposedError(injector.name);
+    }
+}

package/dist/lifetime.d.ts

@@ -0,0 +1,15 @@
+/**
+ * How long a resolved instance lives within its owning injector.
+ * Default when omitted from a provider: `Singleton`.
+ */
+export declare const Lifetime: Readonly<{
+    /** Cached on the owning injector. One instance per binding site. */
+    Singleton: "singleton";
+    /** Cached per resolving child injector. One instance per child. */
+    Scoped: "scoped";
+    /** Fresh on every `resolve()` / `inject()`. Never cached, never disposed. */
+    Transient: "transient";
+}>;
+export type Lifetime = (typeof Lifetime)[keyof typeof Lifetime];
+/** @internal Strictest of two lifetimes (Singleton < Scoped < Transient). */
+export declare function minLifetime(a: Lifetime, b: Lifetime | undefined): Lifetime;

package/dist/lifetime.js

@@ -0,0 +1,23 @@
+/**
+ * How long a resolved instance lives within its owning injector.
+ * Default when omitted from a provider: `Singleton`.
+ */
+export const Lifetime = Object.freeze({
+    /** Cached on the owning injector. One instance per binding site. */
+    Singleton: "singleton",
+    /** Cached per resolving child injector. One instance per child. */
+    Scoped: "scoped",
+    /** Fresh on every `resolve()` / `inject()`. Never cached, never disposed. */
+    Transient: "transient",
+});
+const RANK = {
+    singleton: 0,
+    scoped: 1,
+    transient: 2,
+};
+/** @internal Strictest of two lifetimes (Singleton < Scoped < Transient). */
+export function minLifetime(a, b) {
+    if (b === undefined)
+        return a;
+    return RANK[a] < RANK[b] ? a : b;
+}

package/dist/provider.d.ts

@@ -0,0 +1,29 @@
+import type { Lifetime } from "./lifetime.ts";
+import type { Constructor, Token } from "./token.ts";
+/** Provide a pre-existing value. The injector never disposes it — the caller owns it. */
+export interface ValueProvider<T = unknown> {
+    provide: Token<T>;
+    useValue: T;
+}
+/** Provide via a zero-arg factory. `inject()` is active inside the factory body. */
+export interface FactoryProvider<T = unknown> {
+    provide: Token<T>;
+    useFactory: () => T;
+    lifetime?: Lifetime;
+}
+/** Provide by constructing a class. `inject()` is active in field initializers and the constructor. */
+export interface ClassProvider<T = unknown> {
+    provide: Token<T>;
+    useClass: Constructor<T>;
+    lifetime?: Lifetime;
+}
+/**
+ * Alias: re-dispatch `provide` as `useExisting`.
+ * Resolution always goes through the calling injector, so child overrides are respected.
+ * Caching is owned by the target's binding.
+ */
+export interface ExistingProvider<T = unknown> {
+    provide: Token<T>;
+    useExisting: Token<T>;
+}
+export type Provider<T = unknown> = Constructor<T> | ValueProvider<T> | ClassProvider<T> | FactoryProvider<T> | ExistingProvider<T>;

package/dist/provider.js

@@ -0,0 +1 @@
+export {};

package/dist/token.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Typed DI key for non-class dependencies — interfaces, primitives, config objects.
+ * Unique by identity: two tokens with the same description are distinct keys.
+ *
+ * @example
+ * const API_URL  = new InjectionToken<string>("API_URL");
+ * const TIMEOUT  = new InjectionToken<number>("TIMEOUT");
+ * abstract class Cache { abstract get(k: string): string | null; }
+ */
+export declare class InjectionToken<T> {
+    readonly __type: T;
+    readonly description: string;
+    constructor(description: string);
+    toString(): string;
+}
+/** A concrete class constructor. */
+export interface Constructor<T = unknown> {
+    new (...args: never[]): T;
+}
+/** A class or abstract class reference. */
+export type AbstractClass<T = unknown> = abstract new (...args: never[]) => T;
+/** Anything that can be used as a DI key. */
+export type Token<T = unknown> = Constructor<T> | InjectionToken<T> | AbstractClass<T>;
+/** @internal Returns a human-readable name for a token. */
+export declare function tokenName(token: Token): string;

package/dist/token.js

@@ -0,0 +1,24 @@
+/**
+ * Typed DI key for non-class dependencies — interfaces, primitives, config objects.
+ * Unique by identity: two tokens with the same description are distinct keys.
+ *
+ * @example
+ * const API_URL  = new InjectionToken<string>("API_URL");
+ * const TIMEOUT  = new InjectionToken<number>("TIMEOUT");
+ * abstract class Cache { abstract get(k: string): string | null; }
+ */
+export class InjectionToken {
+    description;
+    constructor(description) {
+        this.description = description;
+    }
+    toString() {
+        return `InjectionToken(${this.description})`;
+    }
+}
+/** @internal Returns a human-readable name for a token. */
+export function tokenName(token) {
+    if (token instanceof InjectionToken)
+        return token.toString();
+    return token.name || String(token);
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "injectus",
-  "version": "0.1.1-alpha.0",
+  "version": "0.2.0",
   "type": "module",
-  "description": "High-performant, decorator-free IoC container for Node.js — sync inject(), explicit lifetimes, TC39-native disposal.",
+  "description": "High-performance, decorator-free IoC container for Node.js — sync inject(), explicit lifetimes, TC39-native disposal.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -20,6 +20,21 @@
   "engines": {
     "node": ">=22.6.0"
   },
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": ">=24.16.0"
+    }
+  },
+  "keywords": [
+    "dependency-injection",
+    "ioc-container",
+    "inversion-of-control",
+    "container",
+    "injector",
+    "inject",
+    "service-locator"
+  ],
   "license": "ISC",
   "author": "Hossam Hamdy <hossamhamdy117@gmail.com> (https://github.com/hossam7amdy)",
   "repository": {
@@ -42,6 +57,7 @@
   "devDependencies": {
     "@biomejs/biome": "^2.4.16",
     "@types/node": "^25.9.1",
+    "lefthook": "^2.1.9",
     "prettier": "^3.8.3",
     "typescript": "^6.0.3"
   },
@@ -49,9 +65,10 @@
     "clean": "rm -rf dist",
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json",
-    "test": "node --import=tsx --test src/__tests__/*.test.ts",
-    "test:watch": "node --import=tsx --test --watch src/__tests__/*.test.ts",
-    "test:cov": "node --import=tsx --test --experimental-test-coverage --test-coverage-exclude='src/__tests__/*' --test-coverage-lines=100 --test-coverage-functions=100 --test-coverage-branches=100 src/__tests__/*.test.ts",
+    "test": "node --test src/__tests__/*.test.ts",
+    "test:watch": "node --test --watch src/__tests__/*.test.ts",
+    "test:cov:node22": "node --test --experimental-test-coverage --test-coverage-exclude='src/__tests__/*' --test-coverage-lines=100 --test-coverage-functions=100 --test-coverage-branches=100 \"src/__tests__/!(*.esnext).test.ts\"",
+    "test:cov": "node --test --experimental-test-coverage --test-coverage-exclude='src/__tests__/*' --test-coverage-lines=100 --test-coverage-functions=100 --test-coverage-branches=100 --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=lcov.info src/__tests__/*.test.ts",
     "preversion": "pnpm clean && pnpm build && pnpm check && pnpm typecheck && pnpm test:cov",
     "check": "biome check . && prettier --check \"**/*.{md,yaml}\"",
     "check:fix": "biome check . --write && prettier --write \"**/*.{md,yaml}\"",