@zudojs/container 0.0.1 → 1.0.0

package/README.md

@@ -11,23 +11,220 @@ npm install @zudojs/container
 ## Quick Start
 
 ```typescript
-import { createContainer } from "@zudojs/container";
+import {
+  createContainer,
+  createToken,
+  ContainerScope,
+} from "@zudojs/container";
 
 const container = createContainer();
 
-container.register("logger", () => createLogger({ name: "app" }), {
-  lifetime: "singleton",
+const LOGGER = createToken<Logger>("logger");
+
+// Registration takes a provider object plus options:
+container.register(
+  LOGGER,
+  { useFactory: () => createLogger({ name: "app" }) },
+  { scope: ContainerScope.SINGLETON },
+);
+
+const logger = container.resolve(LOGGER);
+const [log, db] = container.resolveMany([LOGGER, DB]); // typed [Logger, Db]
+```
+
+Convenience helpers wrap the provider-object form:
+
+```typescript
+container.registerValue("config", { port: 3000 }); // always SINGLETON
+container.registerClass(DB, PostgresDb, { scope: ContainerScope.SINGLETON });
+container.registerFactory(API, (db) => new Api(db), [DB]); // deps via inject list
+container.registerExisting("db-alias", DB); // alias to another token
+```
+
+## Tokens
+
+Tokens can be strings, symbols, classes, or `InjectionToken`s from
+`createToken<T>()` / `createGlobalToken<T>()`.
+
+- Plain string/symbol tokens are **untyped casts** — the compiler cannot
+  verify that what you registered under `"logger"` matches the type you
+  request later. Prefer `InjectionToken`s or class tokens.
+- `createGlobalToken(key)` uses `Symbol.for(key)`: any other call with the
+  same key anywhere in the process yields the **same** token. That is by
+  design for cross-package sharing; namespace your keys (e.g. `"myapp:db"`).
+
+## Lifetimes (`scope` option)
+
+The default scope is **`ContainerScope.TRANSIENT`**.
+
+| Scope       | Cache                                                                                                         | Disposal                                                                         |
+| ----------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `SINGLETON` | One instance in the container's root cache — the same instance is returned at the root and inside every scope | Disposed by `container.dispose()` (or when its registration is replaced/removed) |
+| `SCOPED`    | One instance per scope created with `container.createScope()` (nested scopes see their ancestors' instances)  | Disposed by `scope.dispose()`                                                    |
+| `TRANSIENT` | Never cached — a new instance per resolution                                                                  | **Never tracked — the caller owns disposal**                                     |
+
+Resolving a `SCOPED` token at the container root **throws** a
+`ScopedResolutionError` ("Scoped token X cannot be resolved outside a
+scope"). A `SINGLETON` whose dependency chain contains a `SCOPED`
+registration throws a `CaptiveDependencyError` — a longer-lived consumer must
+not capture a shorter-lived dependency.
+
+`registerValue()` always registers as `SINGLETON`, overriding any
+`options.scope` you pass — a value provider can only ever return the one
+instance you gave it.
+
+Tracking covers **every** `SINGLETON`/`SCOPED` instance the container
+creates — including ones created transitively as dependencies of another
+resolution — not just the value returned by the `resolve()` call.
+
+### Async factories are not supported for cached lifetimes
+
+The container is synchronous. A factory registered as `SINGLETON` or
+`SCOPED` that returns a `Promise` throws an `AsyncProviderError` — otherwise
+the Promise itself would be cached as "the instance" and the eventual value
+would never be disposal-tracked. Await the resource first and register the
+result (`registerValue`), or make the registration `TRANSIENT` and let
+callers await it themselves. There is no `resolveAsync`.
+
+## Scopes
+
+```typescript
+const scope = container.createScope({ name: "request-42" });
+const service = scope.resolve(REQUEST_SERVICE); // SCOPED: cached per scope
+await scope.dispose(); // disposes SCOPED instances only
+```
+
+- Singletons resolved through a scope come from (and stay owned by) the
+  container; `scope.dispose()` never touches them.
+- `scope.createScope()` creates a **nested child** scope:
+  - the child sees `SCOPED` instances already created by its ancestors
+    (lookups chain upward), while instances it creates itself are private to
+    the child and disposed with it;
+  - disposing a scope disposes its children first (most recent first);
+  - `child.getParent()` returns the parent scope (`getParent()` on a
+    top-level scope returns the container); `getContainer()` always returns
+    the container.
+- The container keeps track of its live scopes: `container.dispose()`
+  disposes them (and their children) first, and resolving from any scope
+  after it or one of its ancestors is disposed throws.
+
+## Constructor and factory injection
+
+Providers declare dependencies with an `inject` token list:
+
+```typescript
+class Api {
+  constructor(
+    private db: Db,
+    private logger: Logger,
+  ) {}
+}
+
+container.registerClass(API, Api, { inject: [DB, LOGGER] });
+// or
+container.register(API, { useClass: Api, inject: [DB, LOGGER] });
+container.register(API, {
+  useFactory: (db, log) => new Api(db, log),
+  inject: [DB, LOGGER],
 });
+```
+
+Classes without an `inject` list are constructed with zero arguments. There
+is no reflection/decorator magic — dependencies are exactly the tokens you
+list, resolved in order.
+
+## Duplicate registrations
+
+Registering a token twice throws `DuplicateRegistrationError` unless the
+container was created with `{ registry: { allowDuplicates: true } }`, in
+which case the later registration wins. Use `container.replace()` to
+intentionally swap a registration.
+
+Replacing or removing a registration **evicts and disposes** its cached
+singleton, so the next `resolve()` uses the new provider.
+
+## Resolution options
+
+```typescript
+const container = createContainer({
+  resolution: {
+    autoRegisterClasses: true, // default
+    detectCircularDependencies: true, // default
+    maxResolutionDepth: 100, // default
+  },
+});
+```
+
+- `autoRegisterClasses` — resolving an unregistered **class** token
+  registers it on the fly as `TRANSIENT`. When registrations are frozen the
+  class is instantiated _ephemerally_ without being registered. Set to
+  `false` to require explicit registration (`canResolve`/`resolveOptional`
+  respect this).
+- `detectCircularDependencies` — circular chains throw
+  `CircularDependencyError` with the full chain. When disabled,
+  `maxResolutionDepth` still stops runaway recursion.
+- `maxResolutionDepth` — chains deeper than this throw
+  `MaxResolutionDepthError` naming the token and depth.
 
-const logger = container.resolve("logger");
+Resolution failures are wrapped in `DependencyResolutionError` (a subclass of
+`ProviderResolutionError` from `@zudojs/errors`) carrying the failing
+`token`, the resolution `chain`, and the original error as `cause`. The
+message includes all three:
+`Failed to resolve db: connect ECONNREFUSED (chain: api -> repo -> db)`.
+
+`resolveOptional(token)` returns `undefined` when the token has no
+registration; other failures (broken factories, missing dependencies of a
+registered token, captive dependencies) still throw.
+
+## Start semantics
+
+`container.start()` is optional — the first `resolve()`/`createScope()`
+auto-starts the container. With `freezeRegistrations: true`, starting
+(including that implicit start) freezes the registration set: `register`,
+`replace`, `remove`, `clearRegistrations`, and `restoreSnapshot` throw from
+then on.
+
+## Disposal
+
+```typescript
+await container.dispose();
+```
+
+- Disposes all live scopes, then all tracked singletons in **reverse
+  creation order** (a dependency is created before its dependents, so it is
+  disposed after them). Instances are disposable if they
+  have a `dispose()` method or implement `Symbol.dispose` /
+  `Symbol.asyncDispose`.
+- `TRANSIENT` instances are never tracked; dispose them yourself.
+- With `autoDispose: false`, `dispose()` releases tracked references
+  **without disposing them** — disposal becomes your responsibility.
+- Disposal is terminal: the container is marked disposed even if some
+  instances fail to dispose, and every failure is reported in the thrown
+  `AggregateError`. `dispose()` is idempotent; any use after disposal throws.
+- `clearSingletons()` evicts and disposes cached singletons without
+  disposing the container.
+
+## Snapshots (testing)
+
+`snapshot()` captures the current **registrations** (not instances);
+`restoreSnapshot(snap)` wholesale-replaces the registration set with a
+snapshot, evicting and disposing cached singletons from the old set. Both are
+refused once registrations are frozen or the container is disposed.
+
+```typescript
+const snap = container.snapshot();
+container.replace(DB, { useValue: fakeDb });
+// ... test ...
+container.restoreSnapshot(snap);
 ```
 
 ## Features
 
-- Token-based registration (string, symbol, class)
-- Singleton, scoped, and transient lifetimes
-- Automatic dependency resolution
-- Circular dependency detection
+- Token-based registration (string, symbol, class, `InjectionToken`)
+- Singleton, scoped, and transient lifetimes with strict cache coherence
+- Explicit dependency injection via `inject` lists (classes and factories)
+- Circular dependency detection and resolution depth limiting
+- Lifecycle tracking with deterministic reverse-order disposal
 - Container snapshots for testing
 
 ## Use Cases

package/dist/containerCore/containerCore.core.d.ts

@@ -1,48 +1,139 @@
 /**
  * Core dependency injection container for Zudojs.
+ *
+ * Lifetime and disposal model:
+ * - SINGLETON instances are cached in the container's root singleton cache
+ *   and tracked by the container lifecycle — including singletons created
+ *   transitively as dependencies of another resolution; they are disposed
+ *   when the container is disposed (or when their registration is
+ *   replaced/removed).
+ * - SCOPED instances only exist inside a scope created with `createScope()`;
+ *   resolving a SCOPED token at the root throws.
+ * - TRANSIENT instances are never cached and never tracked — callers own
+ *   their disposal.
  */
 import type { ContainerProvider, ProviderToken } from "../containerProvider/containerProvider.core.js";
-import type { ContainerRegistration, CreateRegistrationOptions, RegistrationToken } from "../containerRegistration/containerRegistration.core.js";
-import { ContainerRegistry } from "../containerRegistry/containerRegistry.core.js";
-import { ContainerResolver } from "../containerResolution/containerResolution.core.js";
-import { ContainerLifecycle } from "../containerLifecycle/containerLifecycle.core.js";
+import type { ContainerRegistration, CreateRegistrationOptions, RegistrationToken, ResolvedTokens } from "../containerRegistration/containerRegistration.core.js";
+import type { ResolutionCache, ResolutionResult } from "../containerResolution/containerResolution.type.js";
 import type { ContainerOptions, ResolvedContainerOptions } from "../containerOptions/containerOptions.type.js";
-import type { ContainerScopeOptions } from "./containerCore.type.js";
+import type { Constructor, Token } from "../containerToken/containerToken.type.js";
+import type { ContainerLike, ContainerScopeOptions } from "./containerCore.type.js";
 import { ContainerScopeContext } from "./containerCore.scope.js";
-export declare class Container {
+/** Options accepted by {@link Container.registerClass}. */
+export interface RegisterClassOptions extends CreateRegistrationOptions {
+    /**
+     * Tokens resolved and passed to the constructor, in order.
+     * Omit for zero-argument constructors.
+     */
+    readonly inject?: readonly ProviderToken[];
+}
+export declare class Container implements ContainerLike {
+    #private;
     readonly name: string;
     readonly options: ResolvedContainerOptions;
-    readonly registry: ContainerRegistry;
-    readonly resolver: ContainerResolver;
-    readonly lifecycle: ContainerLifecycle;
-    private started;
-    private disposed;
     constructor(options?: ContainerOptions);
+    /**
+     * Marks the container as started.
+     *
+     * Calling `start()` explicitly is optional: `resolve()` (and
+     * `createScope()`) auto-start the container on first use. Note that with
+     * `freezeRegistrations: true`, starting — including the implicit start
+     * performed by the first `resolve()` — freezes the registration set.
+     */
     start(): this;
     register<T>(token: RegistrationToken<T>, provider: ContainerProvider<T>, options?: CreateRegistrationOptions): ContainerRegistration<T>;
-    registerClass<T>(token: RegistrationToken<T>, ctor: new (...args: unknown[]) => T, options?: CreateRegistrationOptions): ContainerRegistration<T>;
+    registerClass<T>(token: RegistrationToken<T>, ctor: Constructor<T>, options?: RegisterClassOptions): ContainerRegistration<T>;
+    /**
+     * Registers a pre-built value.
+     *
+     * Note: the scope is forcibly set to SINGLETON (overriding any
+     * `options.scope`) — a value provider always returns the same instance, so
+     * any other lifetime would be misleading.
+     */
     registerValue<T>(token: RegistrationToken<T>, value: T, options?: CreateRegistrationOptions): ContainerRegistration<T>;
     registerFactory<T>(token: RegistrationToken<T>, factory: (...deps: unknown[]) => T, inject?: readonly ProviderToken[], options?: CreateRegistrationOptions): ContainerRegistration<T>;
     registerExisting<T>(token: RegistrationToken<T>, existing: ProviderToken<T>, options?: CreateRegistrationOptions): ContainerRegistration<T>;
+    /**
+     * Resolves a dependency at the container root.
+     *
+     * Auto-starts the container on first use. SCOPED registrations cannot be
+     * resolved here — create a scope with {@link createScope} instead.
+     */
     resolve<T>(token: RegistrationToken<T>): T;
-    resolveMany<T>(tokens: readonly RegistrationToken<T>[]): T[];
+    /**
+     * Resolves several tokens at once. The result is a tuple typed per token,
+     * so heterogeneous token lists keep their individual types.
+     */
+    resolveMany<const Tokens extends readonly RegistrationToken[]>(tokens: Tokens): ResolvedTokens<Tokens>;
+    /**
+     * Like {@link resolve} but returns `undefined` when the token has no
+     * registration (and cannot be auto-registered). Other resolution failures
+     * — broken factories, missing dependencies, captive dependencies — still
+     * throw.
+     */
     resolveOptional<T>(token: RegistrationToken<T>): T | undefined;
     canResolve<T>(token: RegistrationToken<T>): boolean;
     has<T>(token: RegistrationToken<T>): boolean;
     getRegistration<T>(token: RegistrationToken<T>): ContainerRegistration<T> | undefined;
+    replace<T>(token: RegistrationToken<T>, provider: ContainerProvider<T>, options?: CreateRegistrationOptions): ContainerRegistration<T>;
     remove<T>(token: RegistrationToken<T>): boolean;
+    /** Removes every registration (evicting and disposing cached singletons). */
+    clearRegistrations(): void;
     createScope(options?: ContainerScopeOptions): ContainerScopeContext;
     getRegistrations(): readonly ContainerRegistration[];
+    getTokens(): readonly Token<unknown>[];
     get registrationCount(): number;
+    /**
+     * Returns an immutable snapshot of the current registrations, suitable for
+     * later {@link restoreSnapshot}. Cached instances are NOT part of the
+     * snapshot — only the registrations.
+     */
+    snapshot(): readonly ContainerRegistration[];
+    /**
+     * Wholesale-replaces the registration set with a previous snapshot.
+     * Entries are validated, cached singletons for the old set are evicted and
+     * disposed, and the operation is refused when registrations are frozen.
+     */
+    restoreSnapshot(registrations: readonly ContainerRegistration[]): void;
     isStarted(): boolean;
     isDisposed(): boolean;
-    clearSingletons(): void;
+    /**
+     * Evicts all cached singleton instances and disposes the tracked ones.
+     * Fails with an AggregateError listing every disposal failure.
+     */
+    clearSingletons(): Promise<void>;
+    /**
+     * Disposes the container: all live scopes first, then (with
+     * `autoDispose: true`, the default) every tracked singleton in reverse
+     * creation order.
+     *
+     * With `autoDispose: false` tracked instances are NOT disposed — their
+     * references are simply released and disposal becomes the caller's
+     * responsibility.
+     *
+     * Disposal is terminal: the container is marked disposed even when some
+     * instances fail to dispose; every failure is reported in the thrown
+     * AggregateError. Idempotent.
+     */
     dispose(): Promise<void>;
     get resolutionOptions(): {
         autoRegisterClasses: boolean;
         detectCircularDependencies: boolean;
         maxResolutionDepth: number;
     };
+    /** @internal Creates a fresh scoped-instance cache for a scope. */
+    createScopeCache(parent?: ResolutionCache): ResolutionCache;
+    /** @internal Resolves on behalf of a scope, tracking singleton results. */
+    resolveInScope<T>(token: RegistrationToken<T>, cache: ResolutionCache, onInstanceCreated?: (result: ResolutionResult<unknown>) => void): ResolutionResult<T>;
+    /** @internal Unregisters a top-level scope from the live-scope set. */
+    releaseScope(scope: ContainerScopeContext): void;
+    private buildResolutionOptions;
+    /**
+     * Tracks every freshly created SINGLETON instance — top-level results and
+     * transitively created dependencies alike — in the container lifecycle.
+     * SCOPED instances are owned by scopes and TRANSIENT ones by callers.
+     */
+    private trackCreated;
     private ensureActive;
     private ensureNotDisposed;
     private ensureMutable;