@fougere/container 0.1.0-alpha.0 → 0.2.0-alpha.0

package/README.md

@@ -1,7 +1,12 @@
 # @fougere/container
-> The DI container interface
-The interface alone, with no implementation and no dependency — enough to write code
-that resolves its dependencies without marrying one particular container.
+> Fougere's DI container
+Resolution **by type**, never by parameter name: the AST scan reads the constructor
+signature and wires what it asks for. Nested scopes, one per frond. Zero dependencies.
+
+It is small on purpose. The scan already knows the graph — every class and every
+dependency is read from source before boot — so there is almost nothing left to bind
+late: a Map with a parent chain, a scope, and a resolver of last resort for a frond
+that lives in another process.
 
 ## Installation
 ```bash

package/dist/container.d.ts

@@ -1,30 +1,50 @@
 /**
- * Resolver function — receives the container to resolve dependencies.
+ * A class constructor with any arguments.
  */
-export type ResolverFn<T = unknown> = (container: Container) => T;
+export type Constructor<T = unknown> = new (...args: any[]) => T;
 /**
  * Registration options.
  */
 export interface RegisterOptions {
-    /** Lifetime of the resolved value. Default: 'transient'. */
-    lifetime?: 'singleton' | 'scoped' | 'transient';
+    /**
+     * Lifetime of the resolved value. Default: 'transient'.
+     *
+     * Two words, because two are used: `Config` is a singleton, every handler,
+     * presenter, collector and provider is transient — a fresh instance per
+     * resolution, which is what keeps one call's state out of the next. A third,
+     * `'scoped'`, was declared and never passed by any caller: {@link Container.createScope}
+     * already answers "one instance per frond, per surface", and two mechanisms for
+     * one need is one too many.
+     */
+    lifetime?: 'singleton' | 'transient';
     /** Dependency type names for type-based resolution (from AST scan). */
     deps?: string[];
 }
 /**
- * A class constructor with any arguments.
- */
-export type Constructor<T = unknown> = new (...args: any[]) => T;
-/**
- * What can be registered: a class or a resolver function.
+ * Anything holding a resource can say so, and disposing the container says it back.
+ *
+ * Not an interface a class implements — a shape a class happens to have. A handler
+ * that opens nothing declares nothing.
  */
-export type Registration<T = unknown> = Constructor<T> | ResolverFn<T>;
+export interface Disposable {
+    dispose(): void | Promise<void>;
+}
 /**
  * DI container interface — the only thing application code sees.
+ *
+ * It is deliberately small, and the reason is that the scan already knows the graph:
+ * every class and every dependency is read from source before boot, so there is
+ * almost nothing left to bind late. What remains is a Map with a parent chain, plus
+ * the two gestures the scan cannot cover — {@link createScope} for isolation, and
+ * {@link setFallback} for a frond that lives in another process.
+ *
+ * Resolution is by name, and the names are TYPE names produced by the AST scan.
+ * The container never sees a type; "DI by type" is realized upstream, in the
+ * scanner, which is why this file mentions neither.
  */
 export interface Container {
-    /** Register a value by name. */
-    register<T>(name: string, registration: Registration<T>, options?: RegisterOptions): void;
+    /** Register a class by name. Its `deps` are resolved from this container. */
+    register<T>(name: string, ctor: Constructor<T>, options?: RegisterOptions): void;
     /** Register a pre-built value by name. */
     registerValue<T>(name: string, value: T): void;
     /** Resolve a dependency by name. */
@@ -44,7 +64,20 @@ export interface Container {
     setFallback?(resolve: (name: string) => unknown): void;
     /** Create a child scope. Inherits parent registrations. */
     createScope(): Container;
-    /** Dispose the container and its scoped singletons. */
+    /**
+     * Dispose the container: every instance it KEPT — the singletons — that has a
+     * `dispose` method is told, most recent first, and awaited. A failure does not
+     * silence the rest; they travel out together in an `AggregateError`.
+     *
+     * This used to clear the registry and nothing else, while the doc above it promised
+     * disposal — so `await using app` (which routes here through `app[Symbol.asyncDispose]`)
+     * announced a cleanup that never happened. A container that holds instances is the
+     * only thing that knows they exist; if it stays silent, nobody else can speak.
+     *
+     * What it does NOT dispose: a transient, handed over and forgotten in the same
+     * breath, whose caller is the one who knows when it is done; and a value passed to
+     * {@link registerValue}, which the container did not build.
+     */
     dispose(): Promise<void>;
 }
 //# sourceMappingURL=container.d.ts.map

package/dist/container.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"container.d.ts","sourceRoot":"","sources":["../src/container.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,SAAS,EAAE,SAAS,KAAK,CAAC,CAAC;AAElE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;IAChD,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;GAEG;AAEH,MAAM,MAAM,WAAW,CAAC,CAAC,GAAG,OAAO,IAAI,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;AAEjE;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,GAAG,OAAO,IAAI,WAAW,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;AAEvE;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,gCAAgC;IAChC,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;IAE1F,0CAA0C;IAC1C,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IAE/C,oCAAoC;IACpC,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC;IAE5B,+DAA+D;IAC/D,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAE3B;;;;;;;;;OASG;IACH,WAAW,CAAC,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI,CAAC;IAEvD,2DAA2D;IAC3D,WAAW,IAAI,SAAS,CAAC;IAEzB,uDAAuD;IACvD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B"}
+{"version":3,"file":"container.d.ts","sourceRoot":"","sources":["../src/container.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,MAAM,WAAW,CAAC,CAAC,GAAG,OAAO,IAAI,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,WAAW,GAAG,WAAW,CAAC;IACrC,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,SAAS;IACxB,6EAA6E;IAC7E,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;IAEjF,0CAA0C;IAC1C,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IAE/C,oCAAoC;IACpC,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC;IAE5B,+DAA+D;IAC/D,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAE3B;;;;;;;;;OASG;IACH,WAAW,CAAC,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI,CAAC;IAEvD,2DAA2D;IAC3D,WAAW,IAAI,SAAS,CAAC;IAEzB;;;;;;;;;;;;;OAaG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B"}

package/dist/create.d.ts

@@ -0,0 +1,3 @@
+import type { Container } from './container.js';
+export declare function createContainer(): Container;
+//# sourceMappingURL=create.d.ts.map

package/dist/create.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../src/create.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAA4C,MAAM,gBAAgB,CAAC;AAsH1F,wBAAgB,eAAe,IAAI,SAAS,CAE3C"}

package/dist/create.js

@@ -0,0 +1,95 @@
+const isDisposable = (value) => typeof value === 'object' && value !== null &&
+    typeof value.dispose === 'function';
+function createScope(parent) {
+    const registry = new Map();
+    // Construction order, so disposal can run in reverse: a thing built later may
+    // hold something built earlier.
+    const built = [];
+    let fallback;
+    const remember = (value) => {
+        if (isDisposable(value))
+            built.push(value);
+        return value;
+    };
+    const container = {
+        register(name, ctor, options) {
+            const lifetime = options?.lifetime ?? 'transient';
+            const deps = options?.deps ?? [];
+            registry.set(name, {
+                factory: (c) => new ctor(...deps.map((d) => c.resolve(d))),
+                lifetime,
+            });
+        },
+        registerValue(name, value) {
+            // A value the container did not build is not the container's to dispose.
+            registry.set(name, { factory: () => value, lifetime: 'singleton', instance: value });
+        },
+        resolve(name) {
+            let entry = registry.get(name);
+            // Not found locally — the parent holds it, and holds its instance too.
+            if (!entry && parent && parent._getEntry(name)) {
+                return parent.resolve(name);
+            }
+            // Nobody holds it. Before failing, ask whoever set a last resort — a frond declared
+            // in `remotes` registers nothing here, so its façade is fabricated rather than found.
+            if (!entry) {
+                const made = container._getFallback()?.(name);
+                if (made !== undefined) {
+                    registry.set(name, { factory: () => made, lifetime: 'singleton', instance: made });
+                    return made;
+                }
+                throw new Error(`[container] '${name}' is not registered`);
+            }
+            if (entry.instance !== undefined)
+                return entry.instance;
+            const value = entry.factory(container);
+            // The container disposes what it KEEPS. A transient is handed over and
+            // forgotten in the same breath — remembering it would be a leak that grows
+            // once per call, and its caller is the one who knows when it is done.
+            if (entry.lifetime === 'singleton') {
+                entry.instance = value;
+                remember(value);
+            }
+            return value;
+        },
+        has(name) {
+            return registry.has(name) || (parent?.has(name) ?? false);
+        },
+        createScope() {
+            return createScope(container);
+        },
+        async dispose() {
+            // Reverse order, and one failure must not silence the rest: everything gets
+            // told, then the errors travel together.
+            const failures = [];
+            for (const value of built.reverse()) {
+                try {
+                    await value.dispose();
+                }
+                catch (error) {
+                    failures.push(error);
+                }
+            }
+            built.length = 0;
+            registry.clear();
+            if (failures.length > 0) {
+                throw new AggregateError(failures, '[container] one or more disposals failed');
+            }
+        },
+        setFallback(resolve) {
+            fallback = resolve;
+        },
+        _getEntry(name) {
+            return registry.get(name) ?? parent?._getEntry(name);
+        },
+        /** Set on the root, honoured from any scope — a scope inherits it by asking upward. */
+        _getFallback() {
+            return fallback ?? parent?._getFallback();
+        },
+    };
+    return container;
+}
+export function createContainer() {
+    return createScope();
+}
+//# sourceMappingURL=create.js.map

package/dist/create.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.js","sourceRoot":"","sources":["../src/create.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
-export { type Container, type Registration, type RegisterOptions, type ResolverFn, type Constructor, } from './container.js';
+export { type Container, type RegisterOptions, type Constructor, type Disposable, } from './container.js';
+export { createContainer } from './create.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,WAAW,GACjB,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,UAAU,GAChB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,2 +1,2 @@
-export {};
+export { createContainer } from './create.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}

package/package.json

@@ -1,7 +1,14 @@
 {
   "name": "@fougere/container",
-  "version": "0.1.0-alpha.0",
-  "description": "Fougere's DI container interface. Zero dependencies.",
+  "version": "0.2.0-alpha.0",
+  "description": "Fougere's DI container: resolution by type, wired from the AST scan. Zero dependencies.",
+  "keywords": [
+    "fougere",
+    "typescript",
+    "dependency-injection",
+    "ioc",
+    "container"
+  ],
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -21,11 +28,16 @@
   "files": [
     "dist"
   ],
+  "devDependencies": {
+    "vitest": "^4.1.0"
+  },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
     "build": "rm -rf dist && tsc",
-    "typecheck": "tsc --noEmit"
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit -p tsconfig.test.json"
   }
 }