@mudah-cli/container 0.1.0

package/dist/container.d.ts

@@ -0,0 +1,48 @@
+import type { Abstract, Constructor, Factory } from './types.js';
+/**
+ * True for class declarations and function declarations (values with their
+ * own `prototype.constructor`), false for arrow functions and plain objects.
+ * This is what separates an injectable class from a factory function.
+ */
+export declare function isClassLike(value: unknown): value is Constructor;
+/**
+ * High-performance IoC service container.
+ *
+ * - `bind` / `singleton` register factories (arrow functions) or injectable classes.
+ * - `instance` registers a pre-built value.
+ * - `when` registers contextual bindings: an alternative factory that applies
+ *   only when the dependency is injected into a specific context.
+ * - Classes declaring `static dependencies` get constructor auto-injection.
+ */
+export declare class Container {
+    private readonly bindings;
+    private readonly instances;
+    private readonly contextual;
+    private readonly resolvingStack;
+    /** Register a binding. A fresh instance is produced on every `make`. */
+    bind<T>(abstract: Abstract<T>, factory: Factory<T> | Constructor<T>): this;
+    /** Register a shared binding. The instance is resolved once, then cached. */
+    singleton<T>(abstract: Abstract<T>, factory: Factory<T> | Constructor<T>): this;
+    /** Register a pre-built value under an abstract. */
+    instance<T>(abstract: Abstract<T>, value: T): this;
+    /** Make `abstract` an alias of `target` (resolves to the same instance). */
+    alias(abstract: Abstract, target: Abstract): this;
+    /**
+     * Contextual binding: when `abstract` is injected into `context`, resolve it
+     * with `factory` instead of its global binding.
+     */
+    when<TContext extends object, TDep>(context: Constructor<TContext>, abstract: Abstract<TDep>, factory: Factory<TDep> | Constructor<TDep>): this;
+    /** Whether the abstract is bound, or is a constructible class. */
+    has(abstract: Abstract): boolean;
+    /** Resolve an abstract to an instance. */
+    make<T>(abstract: Abstract<T>): T;
+    /** Alias for {@link make}. */
+    get<T>(abstract: Abstract<T>): T;
+    /** Forget all cached singleton instances (bindings are kept). */
+    flush(): void;
+    private sharedInstance;
+    private materialize;
+    private instantiate;
+    private resolveDependency;
+    private withResolving;
+}

package/dist/container.js

@@ -0,0 +1,137 @@
+import { BindingResolutionException, CircularDependencyException } from './exceptions.js';
+/**
+ * True for class declarations and function declarations (values with their
+ * own `prototype.constructor`), false for arrow functions and plain objects.
+ * This is what separates an injectable class from a factory function.
+ */
+export function isClassLike(value) {
+    if (typeof value !== 'function')
+        return false;
+    const proto = value.prototype;
+    return proto !== null && typeof proto === 'object' && Object.prototype.hasOwnProperty.call(proto, 'constructor');
+}
+/**
+ * High-performance IoC service container.
+ *
+ * - `bind` / `singleton` register factories (arrow functions) or injectable classes.
+ * - `instance` registers a pre-built value.
+ * - `when` registers contextual bindings: an alternative factory that applies
+ *   only when the dependency is injected into a specific context.
+ * - Classes declaring `static dependencies` get constructor auto-injection.
+ */
+export class Container {
+    bindings = new Map();
+    instances = new Map();
+    contextual = new Map();
+    resolvingStack = [];
+    /** Register a binding. A fresh instance is produced on every `make`. */
+    bind(abstract, factory) {
+        this.bindings.set(abstract, { factory, shared: false });
+        this.instances.delete(abstract);
+        return this;
+    }
+    /** Register a shared binding. The instance is resolved once, then cached. */
+    singleton(abstract, factory) {
+        this.bindings.set(abstract, { factory, shared: true });
+        this.instances.delete(abstract);
+        return this;
+    }
+    /** Register a pre-built value under an abstract. */
+    instance(abstract, value) {
+        this.bindings.set(abstract, { factory: () => value, shared: true });
+        this.instances.set(abstract, value);
+        return this;
+    }
+    /** Make `abstract` an alias of `target` (resolves to the same instance). */
+    alias(abstract, target) {
+        this.bind(abstract, (container) => container.make(target));
+        return this;
+    }
+    /**
+     * Contextual binding: when `abstract` is injected into `context`, resolve it
+     * with `factory` instead of its global binding.
+     */
+    when(context, abstract, factory) {
+        let map = this.contextual.get(context);
+        if (!map) {
+            map = new Map();
+            this.contextual.set(context, map);
+        }
+        map.set(abstract, factory);
+        return this;
+    }
+    /** Whether the abstract is bound, or is a constructible class. */
+    has(abstract) {
+        return this.bindings.has(abstract) || isClassLike(abstract);
+    }
+    /** Resolve an abstract to an instance. */
+    make(abstract) {
+        if (this.instances.has(abstract)) {
+            return this.instances.get(abstract);
+        }
+        const binding = this.bindings.get(abstract);
+        if (binding) {
+            return binding.shared
+                ? this.sharedInstance(abstract, () => this.materialize(abstract, binding.factory, undefined))
+                : this.withResolving(abstract, () => this.materialize(abstract, binding.factory, undefined));
+        }
+        if (isClassLike(abstract)) {
+            return this.withResolving(abstract, () => this.instantiate(abstract, undefined));
+        }
+        throw new BindingResolutionException(abstract);
+    }
+    /** Alias for {@link make}. */
+    get(abstract) {
+        return this.make(abstract);
+    }
+    /** Forget all cached singleton instances (bindings are kept). */
+    flush() {
+        this.instances.clear();
+    }
+    sharedInstance(abstract, producer) {
+        if (this.instances.has(abstract)) {
+            return this.instances.get(abstract);
+        }
+        return this.withResolving(abstract, () => {
+            const value = producer();
+            this.instances.set(abstract, value);
+            return value;
+        });
+    }
+    materialize(abstract, factory, context) {
+        if (isClassLike(factory)) {
+            return this.instantiate(factory, context);
+        }
+        return factory(this);
+    }
+    instantiate(ctor, context) {
+        // Contextual bindings resolve against the class currently being
+        // constructed (the immediate context), matching standard merge semantics.
+        const immediate = context ?? ctor;
+        const deps = ctor.dependencies ?? [];
+        const args = deps.map((dep) => this.resolveDependency(dep, immediate));
+        return new ctor(...args);
+    }
+    resolveDependency(dep, context) {
+        if (context) {
+            const override = this.contextual.get(context)?.get(dep);
+            if (override !== undefined) {
+                return this.withResolving(dep, () => this.materialize(dep, override, context));
+            }
+        }
+        return this.make(dep);
+    }
+    withResolving(abstract, fn) {
+        if (this.resolvingStack.includes(abstract)) {
+            throw new CircularDependencyException(abstract, this.resolvingStack);
+        }
+        this.resolvingStack.push(abstract);
+        try {
+            return fn();
+        }
+        finally {
+            this.resolvingStack.pop();
+        }
+    }
+}
+//# sourceMappingURL=container.js.map

package/dist/container.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"container.js","sourceRoot":"","sources":["../src/container.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,MAAM,iBAAiB,CAAC;AAY1F;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,IAAI,OAAO,KAAK,KAAK,UAAU;QAAE,OAAO,KAAK,CAAC;IAC9C,MAAM,KAAK,GAAI,KAAqB,CAAC,SAAS,CAAC;IAC/C,OAAO,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;AACnH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,OAAO,SAAS;IACH,QAAQ,GAAG,IAAI,GAAG,EAAqB,CAAC;IACxC,SAAS,GAAG,IAAI,GAAG,EAAqB,CAAC;IACzC,UAAU,GAAG,IAAI,GAAG,EAAqD,CAAC;IAC1E,cAAc,GAAe,EAAE,CAAC;IAEjD,wEAAwE;IACxE,IAAI,CAAI,QAAqB,EAAE,OAAoC;QACjE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;QACxD,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,6EAA6E;IAC7E,SAAS,CAAI,QAAqB,EAAE,OAAoC;QACtE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;QACvD,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,oDAAoD;IACpD,QAAQ,CAAI,QAAqB,EAAE,KAAQ;QACzC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;QACpE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QACpC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,4EAA4E;IAC5E,KAAK,CAAC,QAAkB,EAAE,MAAgB;QACxC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,SAAoB,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;QACtE,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;OAGG;IACH,IAAI,CACF,OAA8B,EAC9B,QAAwB,EACxB,OAA0C;QAE1C,IAAI,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACvC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;YAChB,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QACpC,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC3B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,kEAAkE;IAClE,GAAG,CAAC,QAAkB;QACpB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC9D,CAAC;IAED,0CAA0C;IAC1C,IAAI,CAAI,QAAqB;QAC3B,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YACjC,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAM,CAAC;QAC3C,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC5C,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,OAAO,CAAC,MAAM;gBACnB,CAAC,CAAE,IAAI,CAAC,cAAc,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,OAAO,CAAC,OAAO,EAAE,SAAS,CAAC,CAAO;gBACpG,CAAC,CAAE,IAAI,CAAC,aAAa,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,OAAO,CAAC,OAAO,EAAE,SAAS,CAAC,CAAO,CAAC;QACxG,CAAC;QAED,IAAI,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC1B,OAAO,IAAI,CAAC,aAAa,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,QAAmC,EAAE,SAAS,CAAC,CAAM,CAAC;QACnH,CAAC;QAED,MAAM,IAAI,0BAA0B,CAAC,QAAQ,CAAC,CAAC;IACjD,CAAC;IAED,8BAA8B;IAC9B,GAAG,CAAI,QAAqB;QAC1B,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC7B,CAAC;IAED,iEAAiE;IACjE,KAAK;QACH,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;IAEO,cAAc,CAAC,QAAkB,EAAE,QAAuB;QAChE,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YACjC,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACtC,CAAC;QACD,OAAO,IAAI,CAAC,aAAa,CAAC,QAAQ,EAAE,GAAG,EAAE;YACvC,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC;YACzB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;YACpC,OAAO,KAAK,CAAC;QACf,CAAC,CAAC,CAAC;IACL,CAAC;IAEO,WAAW,CAAC,QAAkB,EAAE,OAA8B,EAAE,OAAgC;QACtG,IAAI,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC,WAAW,CAAC,OAAkC,EAAE,OAAO,CAAC,CAAC;QACvE,CAAC;QACD,OAAQ,OAAmB,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC;IAEO,WAAW,CAAC,IAA6B,EAAE,OAAgC;QACjF,gEAAgE;QAChE,0EAA0E;QAC1E,MAAM,SAAS,GAAG,OAAO,IAAI,IAAI,CAAC;QAClC,MAAM,IAAI,GAAI,IAA8B,CAAC,YAAY,IAAI,EAAE,CAAC;QAChE,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,iBAAiB,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC;QACvE,OAAO,IAAK,IAAoB,CAAC,GAAG,IAAI,CAAC,CAAC;IAC5C,CAAC;IAEO,iBAAiB,CAAC,GAAa,EAAE,OAAgC;QACvE,IAAI,OAAO,EAAE,CAAC;YACZ,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;YACxD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;gBAC3B,OAAO,IAAI,CAAC,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;YACjF,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IAEO,aAAa,CAAC,QAAkB,EAAE,EAAiB;QACzD,IAAI,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC3C,MAAM,IAAI,2BAA2B,CAAC,QAAQ,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;QACvE,CAAC;QACD,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACnC,IAAI,CAAC;YACH,OAAO,EAAE,EAAE,CAAC;QACd,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,cAAc,CAAC,GAAG,EAAE,CAAC;QAC5B,CAAC;IACH,CAAC;CACF"}

package/dist/exceptions.d.ts

@@ -0,0 +1,9 @@
+import type { Abstract } from './types.js';
+/** Thrown when an abstract has no binding and is not a constructible class. */
+export declare class BindingResolutionException extends Error {
+    constructor(abstract: Abstract);
+}
+/** Thrown when resolving a binding requires itself, directly or transitively. */
+export declare class CircularDependencyException extends Error {
+    constructor(abstract: Abstract, chain: readonly Abstract[]);
+}

package/dist/exceptions.js

@@ -0,0 +1,22 @@
+function describe(abstract) {
+    if (typeof abstract === 'string')
+        return abstract;
+    if (typeof abstract === 'symbol')
+        return abstract.description ?? String(abstract);
+    return abstract.name || '<anonymous class>';
+}
+/** Thrown when an abstract has no binding and is not a constructible class. */
+export class BindingResolutionException extends Error {
+    constructor(abstract) {
+        super(`[container] Unable to resolve "${describe(abstract)}": no binding is registered and it is not a constructible class.`);
+        this.name = 'BindingResolutionException';
+    }
+}
+/** Thrown when resolving a binding requires itself, directly or transitively. */
+export class CircularDependencyException extends Error {
+    constructor(abstract, chain) {
+        super(`[container] Circular dependency detected: ${[...chain, abstract].map(describe).join(' -> ')}`);
+        this.name = 'CircularDependencyException';
+    }
+}
+//# sourceMappingURL=exceptions.js.map

package/dist/exceptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exceptions.js","sourceRoot":"","sources":["../src/exceptions.ts"],"names":[],"mappings":"AAEA,SAAS,QAAQ,CAAC,QAAkB;IAClC,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAClD,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAC,WAAW,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC;IAClF,OAAO,QAAQ,CAAC,IAAI,IAAI,mBAAmB,CAAC;AAC9C,CAAC;AAED,+EAA+E;AAC/E,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IACnD,YAAY,QAAkB;QAC5B,KAAK,CACH,kCAAkC,QAAQ,CAAC,QAAQ,CAAC,kEAAkE,CACvH,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF;AAED,iFAAiF;AACjF,MAAM,OAAO,2BAA4B,SAAQ,KAAK;IACpD,YAAY,QAAkB,EAAE,KAA0B;QACxD,KAAK,CAAC,6CAA6C,CAAC,GAAG,KAAK,EAAE,QAAQ,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACtG,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAC;IAC5C,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { Container, isClassLike } from './container.js';
+export { BindingResolutionException, CircularDependencyException } from './exceptions.js';
+export type { Abstract, Constructor, Factory, Injectable } from './types.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { Container, isClassLike } from './container.js';
+export { BindingResolutionException, CircularDependencyException } from './exceptions.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,18 @@
+import type { Container } from './container.js';
+/** A class constructor that can be bound or resolved. */
+export type Constructor<T = unknown> = new (...args: any[]) => T;
+/** Anything the container can resolve: a string/symbol key or a concrete class. */
+export type Abstract<T = unknown> = string | symbol | Constructor<T>;
+/**
+ * A factory that produces an instance. Receives the container so it can
+ * resolve nested dependencies. Use an arrow function for factories —
+ * class values are treated as injectable constructors instead.
+ */
+export type Factory<T = unknown> = (container: Container) => T;
+/**
+ * Optional contract for classes the container should instantiate with
+ * constructor auto-injection. List the abstracts to inject, in order.
+ */
+export interface Injectable {
+    readonly dependencies?: readonly Abstract[];
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@mudah-cli/container",
+  "version": "0.1.0",
+  "description": "High-performance IoC service container with constructor auto-injection.",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=26"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}