@zudojs/container 0.0.1 → 1.0.0

package/dist/containerResolution/containerResolution.error.d.ts

@@ -1,8 +1,73 @@
 /**
  * @zudojs/container/containerResolution/containerResolution.error
  *
- * Error classes re-exported from @zudojs/errors.
- * Token description helpers live in containerToken.type.ts.
+ * Resolution error classes local to this package. They extend the published
+ * `ContainerError` base from @zudojs/errors; the published package does not
+ * yet ship dedicated classes for these failure modes.
  */
-export {};
+import { ContainerError, ProviderResolutionError } from "@zudojs/errors";
+/**
+ * Thrown when a SCOPED registration is resolved without a scope
+ * (i.e. directly from the root container).
+ */
+export declare class ScopedResolutionError extends ContainerError {
+    readonly chain: readonly string[];
+    constructor(token: string, chain?: readonly string[]);
+}
+/**
+ * Thrown when a longer-lived consumer (a SINGLETON) would capture a
+ * shorter-lived SCOPED dependency, freezing it beyond its scope's lifetime.
+ */
+export declare class CaptiveDependencyError extends ContainerError {
+    readonly consumer: string;
+    readonly dependency: string;
+    readonly chain: readonly string[];
+    constructor(consumer: string, dependency: string, chain?: readonly string[]);
+}
+/**
+ * Thrown when a resolution chain exceeds `maxResolutionDepth`.
+ */
+export declare class MaxResolutionDepthError extends ContainerError {
+    readonly depth: number;
+    readonly maxDepth: number;
+    readonly chain: readonly string[];
+    constructor(token: string, depth: number, maxDepth: number, chain?: readonly string[]);
+}
+/**
+ * Thrown when a provider fails while resolving a token. Extends the published
+ * `ProviderResolutionError` with the resolution chain that led to the failing
+ * token (outermost request first) so callers can inspect it programmatically
+ * instead of parsing the message.
+ */
+export declare class DependencyResolutionError extends ProviderResolutionError {
+    readonly chain: readonly string[];
+    constructor(token: string, cause: unknown, chain?: readonly string[]);
+    toJSON(): {
+        name: string;
+        message: string;
+        code: string;
+        category: import("@zudojs/errors").ErrorCategory;
+        severity: import("@zudojs/errors").ErrorSeverity;
+        statusCode: number;
+        expose: boolean;
+        isOperational: boolean;
+        metadata: Readonly<import("@zudojs/errors").ErrorMetadata>;
+        stack?: string;
+        cause?: import("@zudojs/errors").SerializedBaseError | unknown;
+        token?: string | undefined;
+        chain: readonly string[];
+    };
+}
+/**
+ * Thrown when a factory registered as SINGLETON or SCOPED returns a Promise.
+ *
+ * The container is synchronous: it would otherwise cache the Promise itself
+ * as the instance and the eventual value would never be disposal-tracked.
+ * Await the resource before registering it (e.g. `registerValue`), or use a
+ * TRANSIENT registration whose callers await the result themselves.
+ */
+export declare class AsyncProviderError extends ContainerError {
+    readonly scope: string;
+    constructor(token: string, scope: string);
+}
 //# sourceMappingURL=containerResolution.error.d.ts.map

package/dist/containerResolution/containerResolution.error.js

@@ -1,8 +1,112 @@
 /**
  * @zudojs/container/containerResolution/containerResolution.error
  *
- * Error classes re-exported from @zudojs/errors.
- * Token description helpers live in containerToken.type.ts.
+ * Resolution error classes local to this package. They extend the published
+ * `ContainerError` base from @zudojs/errors; the published package does not
+ * yet ship dedicated classes for these failure modes.
  */
-export {};
+import { ContainerError, ProviderResolutionError } from "@zudojs/errors";
+function formatChain(chain) {
+    return chain.join(" -> ");
+}
+/**
+ * Thrown when a SCOPED registration is resolved without a scope
+ * (i.e. directly from the root container).
+ */
+export class ScopedResolutionError extends ContainerError {
+    chain;
+    constructor(token, chain = []) {
+        const suffix = chain.length > 1 ? ` (chain: ${formatChain(chain)})` : "";
+        super(`Scoped token ${token} cannot be resolved outside a scope. ` +
+            `Create one with container.createScope() and resolve through it.${suffix}`, {
+            code: "CONTAINER_SCOPED_OUTSIDE_SCOPE",
+            token,
+            statusCode: 500,
+            expose: false,
+        });
+        this.chain = chain;
+    }
+}
+/**
+ * Thrown when a longer-lived consumer (a SINGLETON) would capture a
+ * shorter-lived SCOPED dependency, freezing it beyond its scope's lifetime.
+ */
+export class CaptiveDependencyError extends ContainerError {
+    consumer;
+    dependency;
+    chain;
+    constructor(consumer, dependency, chain = []) {
+        const suffix = chain.length > 1 ? ` (chain: ${formatChain(chain)})` : "";
+        super(`Captive dependency: singleton "${consumer}" depends on scoped "${dependency}". ` +
+            `A longer-lived consumer cannot capture a shorter-lived dependency.${suffix}`, {
+            code: "CONTAINER_CAPTIVE_DEPENDENCY",
+            token: dependency,
+            statusCode: 500,
+            expose: false,
+        });
+        this.consumer = consumer;
+        this.dependency = dependency;
+        this.chain = chain;
+    }
+}
+/**
+ * Thrown when a resolution chain exceeds `maxResolutionDepth`.
+ */
+export class MaxResolutionDepthError extends ContainerError {
+    depth;
+    maxDepth;
+    chain;
+    constructor(token, depth, maxDepth, chain = []) {
+        super(`Maximum resolution depth of ${maxDepth} exceeded while resolving ` +
+            `token ${token} at depth ${depth}.`, {
+            code: "CONTAINER_MAX_RESOLUTION_DEPTH",
+            token,
+            statusCode: 500,
+            expose: false,
+        });
+        this.depth = depth;
+        this.maxDepth = maxDepth;
+        this.chain = chain;
+    }
+}
+/**
+ * Thrown when a provider fails while resolving a token. Extends the published
+ * `ProviderResolutionError` with the resolution chain that led to the failing
+ * token (outermost request first) so callers can inspect it programmatically
+ * instead of parsing the message.
+ */
+export class DependencyResolutionError extends ProviderResolutionError {
+    chain;
+    constructor(token, cause, chain = []) {
+        const detail = cause instanceof Error ? cause.message : String(cause);
+        const suffix = chain.length > 0 ? ` (chain: ${formatChain(chain)})` : "";
+        super(token, `Failed to resolve ${token}: ${detail}${suffix}`, cause);
+        this.chain = Object.freeze([...chain]);
+    }
+    toJSON() {
+        return { ...super.toJSON(), chain: this.chain };
+    }
+}
+/**
+ * Thrown when a factory registered as SINGLETON or SCOPED returns a Promise.
+ *
+ * The container is synchronous: it would otherwise cache the Promise itself
+ * as the instance and the eventual value would never be disposal-tracked.
+ * Await the resource before registering it (e.g. `registerValue`), or use a
+ * TRANSIENT registration whose callers await the result themselves.
+ */
+export class AsyncProviderError extends ContainerError {
+    scope;
+    constructor(token, scope) {
+        super(`Factory for ${scope} token ${token} returned a Promise. Async factories ` +
+            `are not supported for cached (singleton/scoped) registrations: ` +
+            `await the value before registering it, or register it as TRANSIENT.`, {
+            code: "CONTAINER_ASYNC_PROVIDER_UNSUPPORTED",
+            token,
+            statusCode: 500,
+            expose: false,
+        });
+        this.scope = scope;
+    }
+}
 //# sourceMappingURL=containerResolution.error.js.map

package/dist/containerResolution/containerResolution.type.d.ts

@@ -6,8 +6,17 @@ import type { ContainerScope } from "../containerScope/containerScope.type.js";
 import type { Token } from "../containerToken/containerToken.type.js";
 /**
  * A cache containing resolved dependency instances.
+ *
+ * A plain `Map` satisfies this interface; scope caches created by the
+ * resolver additionally fall back to their parent scope's cache for lookups
+ * (see {@link ContainerResolver.createScope}).
  */
-export type ResolutionCache = Map<Token<unknown>, unknown>;
+export interface ResolutionCache {
+    has(token: Token<unknown>): boolean;
+    get(token: Token<unknown>): unknown;
+    set(token: Token<unknown>, value: unknown): void;
+    clear(): void;
+}
 /**
  * Dependency resolution path.
  * Used for diagnostics and circular dependency detection.
@@ -17,12 +26,35 @@ export type ResolutionPath = readonly Token<unknown>[];
  * Options controlling dependency resolution.
  */
 export interface ResolutionOptions {
-    /** Existing cache for the current resolution scope. */
+    /**
+     * Scope cache for SCOPED instances. When absent the resolution is a root
+     * resolution and SCOPED registrations throw. SINGLETON instances always
+     * live in the resolver's own singleton cache, never in this cache.
+     */
     readonly cache?: ResolutionCache;
     /** Current dependency resolution path. Normally managed internally. */
     readonly path?: ResolutionPath;
-    /** Whether to allow resolving unregistered classes directly from their constructors. Defaults to true. */
+    /** Whether unregistered class tokens may be resolved. Defaults to true. */
     readonly autoRegisterClasses?: boolean;
+    /**
+     * Whether auto-resolved class tokens may be added to the registry.
+     * When false (e.g. registrations are frozen) unregistered classes are
+     * instantiated ephemerally without being registered. Defaults to true.
+     */
+    readonly allowRegistration?: boolean;
+    /** Whether circular dependencies are detected. Defaults to true. */
+    readonly detectCircularDependencies?: boolean;
+    /**
+     * Maximum resolution chain depth before resolution aborts with a
+     * MaxResolutionDepthError. Defaults to 100.
+     */
+    readonly maxResolutionDepth?: number;
+    /**
+     * Invoked for every instance the resolver creates during this resolution
+     * (never for cache hits), in creation order — dependencies are reported
+     * before their dependents. Owners use it to track instances for disposal.
+     */
+    readonly onInstanceCreated?: (result: ResolutionResult<unknown>) => void;
 }
 /**
  * Resolution result containing the resolved value and diagnostic information.

package/dist/containerResolution/index.d.ts

@@ -4,5 +4,6 @@
  * Dependency resolution and injection.
  */
 export * from "./containerResolution.type.js";
+export * from "./containerResolution.error.js";
 export * from "./containerResolution.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/containerResolution/index.js

@@ -4,5 +4,6 @@
  * Dependency resolution and injection.
  */
 export * from "./containerResolution.type.js";
+export * from "./containerResolution.error.js";
 export * from "./containerResolution.core.js";
 //# sourceMappingURL=index.js.map

package/dist/containerToken/containerToken.type.d.ts

@@ -2,8 +2,15 @@
  * Dependency injection token definitions for Zudojs.
  * Tokens identify dependencies within the container.
  */
+/**
+ * A class constructor usable as a token or provider implementation.
+ *
+ * The parameter list is intentionally loose (`any[]`) so classes with typed
+ * constructor parameters are accepted; the container supplies arguments via
+ * the provider's `inject` list (or none for zero-arg constructors).
+ */
 export interface Constructor<T = unknown> {
-    new (...args: unknown[]): T;
+    new (...args: any[]): T;
 }
 export type TokenSymbol = symbol;
 export type TokenString = string;
@@ -12,7 +19,25 @@ export interface InjectionToken<T = unknown> {
     readonly token: Token<T>;
     readonly description?: string;
 }
+/**
+ * Creates a unique, typed injection token backed by a fresh `Symbol`.
+ *
+ * Note on typing: plain string and symbol tokens are *untyped casts* — the
+ * container cannot verify at compile time that the value registered under a
+ * string/symbol actually has type `T`. Prefer `InjectionToken`s created here
+ * (or constructor tokens) so the association between token and type lives in
+ * one place.
+ */
 export declare function createToken<T>(description: string): InjectionToken<T>;
+/**
+ * Creates a typed injection token backed by `Symbol.for(key)`.
+ *
+ * Because `Symbol.for` uses the process-wide global symbol registry, two
+ * independent calls (even from different packages) with the same `key`
+ * produce the SAME token and will collide in the container — this is by
+ * design for cross-package sharing, but means keys must be namespaced
+ * (e.g. `"myapp:db"`). Use {@link createToken} for collision-free tokens.
+ */
 export declare function createGlobalToken<T>(key: string): InjectionToken<T>;
 export declare function unwrapToken<T>(token: Token<T> | InjectionToken<T>): Token<T>;
 export declare function isInjectionToken<T = unknown>(value: unknown): value is InjectionToken<T>;

package/dist/containerToken/containerToken.type.js

@@ -2,9 +2,27 @@
  * Dependency injection token definitions for Zudojs.
  * Tokens identify dependencies within the container.
  */
+/**
+ * Creates a unique, typed injection token backed by a fresh `Symbol`.
+ *
+ * Note on typing: plain string and symbol tokens are *untyped casts* — the
+ * container cannot verify at compile time that the value registered under a
+ * string/symbol actually has type `T`. Prefer `InjectionToken`s created here
+ * (or constructor tokens) so the association between token and type lives in
+ * one place.
+ */
 export function createToken(description) {
     return Object.freeze({ token: Symbol(description), description });
 }
+/**
+ * Creates a typed injection token backed by `Symbol.for(key)`.
+ *
+ * Because `Symbol.for` uses the process-wide global symbol registry, two
+ * independent calls (even from different packages) with the same `key`
+ * produce the SAME token and will collide in the container — this is by
+ * design for cross-package sharing, but means keys must be namespaced
+ * (e.g. `"myapp:db"`). Use {@link createToken} for collision-free tokens.
+ */
 export function createGlobalToken(key) {
     return Object.freeze({ token: Symbol.for(key), description: key });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/container",
-  "version": "0.0.1",
+  "version": "1.0.0",
   "description": "Token-based dependency injection container for managing application dependencies and service lifetimes.",
   "type": "module",
   "main": "./dist/index.js",
@@ -12,13 +12,17 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "!dist/**/*.map",
+    "!dist/**/*.tsbuildinfo",
+    "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "0.0.1"
+    "@zudojs/errors": "1.0.0"
   },
   "devDependencies": {
-    "typescript": "^7.0.2"
+    "typescript": "7.0.2",
+    "vitest": "^4.1.11"
   },
   "license": "MIT",
   "publishConfig": {
@@ -27,7 +31,6 @@
   "engines": {
     "node": ">=24.0.0"
   },
-  "module": "./dist/index.js",
   "keywords": [
     "zudojs",
     "di",
@@ -35,13 +38,19 @@
     "container"
   ],
   "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "bugs": {
+    "url": "https://github.com/oyinlola-tech/zudo/issues"
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/oyinlola-tech/zudo"
+    "url": "https://github.com/oyinlola-tech/zudo",
+    "directory": "packages/container"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "clean": "tsc -p tsconfig.json --clean"
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
 }