@fougere/container 0.2.0-alpha.2 → 0.4.0-alpha.0

package/README.md

@@ -17,4 +17,4 @@ pnpm add @fougere/container
 
 Part of [Fougere](https://github.com/chok/fougere) — one schema, a gradient from
 monolith to distributed, the same user code.
-Reference documentation: [the site](https://chok.github.io/fougere/) (en/fr).
+Reference documentation: [the site](https://fougere.dev/) (en/fr).

package/dist/create.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../src/create.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAA4C,MAAM,gBAAgB,CAAC;AAiJ1F,wBAAgB,eAAe,IAAI,SAAS,CAE3C"}

package/dist/create.js

@@ -5,6 +5,12 @@ function createScope(parent) {
     // Construction order, so disposal can run in reverse: a thing built later may
     // hold something built earlier.
     const built = [];
+    // The scopes opened from this one. A child is built BY this container, so it is this
+    // container's to close — and it is closed first, because it may hold what the parent
+    // built while the parent holds nothing of its. Without this a frond's scope, which is
+    // where every provider lives, was never disposed at all: it is registered as a VALUE
+    // under `frond:<name>`, and a value is not the container's to dispose.
+    const children = [];
     let fallback;
     const remember = (value) => {
         if (isDisposable(value))
@@ -56,12 +62,28 @@ function createScope(parent) {
             return registry.has(name) || (parent?.has(name) ?? false);
         },
         createScope() {
-            return createScope(container);
+            const child = createScope(container);
+            children.push(child);
+            return child;
         },
         async dispose() {
             // Reverse order, and one failure must not silence the rest: everything gets
             // told, then the errors travel together.
+            // Its parent kept a reference so it could close this scope; the scope closing itself
+            // makes that reference garbage. Nothing created a scope at RUN time until frames did,
+            // so the list only ever grew at boot and stayed bounded — one per request, or one per
+            // transaction, and it grows for the life of the process.
+            parent?._forget(container);
             const failures = [];
+            for (const child of children.reverse()) {
+                try {
+                    await child.dispose();
+                }
+                catch (error) {
+                    failures.push(error);
+                }
+            }
+            children.length = 0;
             for (const value of built.reverse()) {
                 try {
                     await value.dispose();
@@ -82,6 +104,11 @@ function createScope(parent) {
         _getEntry(name) {
             return registry.get(name) ?? parent?._getEntry(name);
         },
+        _forget(child) {
+            const at = children.indexOf(child);
+            if (at !== -1)
+                children.splice(at, 1);
+        },
         /** Set on the root, honoured from any scope — a scope inherits it by asking upward. */
         _getFallback() {
             return fallback ?? parent?._getFallback();

package/dist/create.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fougere/container",
-  "version": "0.2.0-alpha.2",
+  "version": "0.4.0-alpha.0",
   "description": "Fougere's DI container: resolution by type, wired from the AST scan. Zero dependencies.",
   "keywords": [
     "fougere",
@@ -26,7 +26,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "devDependencies": {
     "vitest": "^4.1.0"

package/src/container.ts

@@ -0,0 +1,92 @@
+/**
+ * A class constructor with any arguments.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type Constructor<T = unknown> = new (...args: any[]) => T;
+
+/**
+ * Registration options.
+ */
+export interface RegisterOptions {
+  /**
+   * 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[];
+}
+
+/**
+ * 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 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 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. */
+  resolve<T>(name: string): T;
+
+  /** Check if a name is registered (including parent scopes). */
+  has(name: string): boolean;
+
+  /**
+   * A resolver of last resort, consulted when no scope holds the name.
+   *
+   * It exists for one reason: a frond declared in `remotes` registers nothing locally,
+   * so its façade cannot be *found* — it has to be fabricated. Set on the root, inherited
+   * by every scope. Returning `undefined` means "I don't know either", and the miss
+   * throws as before.
+   *
+   * Optional: a container without one behaves exactly as it did.
+   */
+  setFallback?(resolve: (name: string) => unknown): void;
+
+  /** Create a child scope. Inherits parent registrations. */
+  createScope(): Container;
+
+  /**
+   * 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>;
+}

package/src/create.ts

@@ -0,0 +1,148 @@
+import type { Container, RegisterOptions, Constructor, Disposable } from './container.js';
+
+interface Entry {
+  factory: (container: Container) => unknown;
+  lifetime: 'singleton' | 'transient';
+  instance?: unknown;
+}
+
+interface ScopeContainer extends Container {
+  _getEntry(name: string): Entry | undefined;
+  _getFallback(): ((name: string) => unknown) | undefined;
+  _forget(child: ScopeContainer): void;
+}
+
+const isDisposable = (value: unknown): value is Disposable =>
+  typeof value === 'object' && value !== null &&
+  typeof (value as Disposable).dispose === 'function';
+
+function createScope(parent?: ScopeContainer): ScopeContainer {
+  const registry = new Map<string, Entry>();
+  // Construction order, so disposal can run in reverse: a thing built later may
+  // hold something built earlier.
+  const built: unknown[] = [];
+  // The scopes opened from this one. A child is built BY this container, so it is this
+  // container's to close — and it is closed first, because it may hold what the parent
+  // built while the parent holds nothing of its. Without this a frond's scope, which is
+  // where every provider lives, was never disposed at all: it is registered as a VALUE
+  // under `frond:<name>`, and a value is not the container's to dispose.
+  const children: ScopeContainer[] = [];
+  let fallback: ((name: string) => unknown) | undefined;
+
+  const remember = <T>(value: T): T => {
+    if (isDisposable(value)) built.push(value);
+    return value;
+  };
+
+  const container: ScopeContainer = {
+    register<T>(name: string, ctor: Constructor<T>, options?: RegisterOptions) {
+      const lifetime = options?.lifetime ?? 'transient';
+      const deps = options?.deps ?? [];
+      registry.set(name, {
+        factory: (c) => new ctor(...deps.map((d) => c.resolve(d))),
+        lifetime,
+      });
+    },
+
+    registerValue<T>(name: string, value: T) {
+      // A value the container did not build is not the container's to dispose.
+      registry.set(name, { factory: () => value, lifetime: 'singleton', instance: value });
+    },
+
+    resolve<T>(name: string): T {
+      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<T>(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 as T;
+        }
+        throw new Error(`[container] '${name}' is not registered`);
+      }
+
+      if (entry.instance !== undefined) return entry.instance as T;
+      const value = entry.factory(container) as T;
+      // 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: string): boolean {
+      return registry.has(name) || (parent?.has(name) ?? false);
+    },
+
+    createScope(): Container {
+      const child = createScope(container);
+      children.push(child);
+      return child;
+    },
+
+    async dispose(): Promise<void> {
+      // Reverse order, and one failure must not silence the rest: everything gets
+      // told, then the errors travel together.
+      // Its parent kept a reference so it could close this scope; the scope closing itself
+      // makes that reference garbage. Nothing created a scope at RUN time until frames did,
+      // so the list only ever grew at boot and stayed bounded — one per request, or one per
+      // transaction, and it grows for the life of the process.
+      parent?._forget(container);
+      const failures: unknown[] = [];
+      for (const child of children.reverse()) {
+        try {
+          await child.dispose();
+        } catch (error) {
+          failures.push(error);
+        }
+      }
+      children.length = 0;
+      for (const value of built.reverse()) {
+        try {
+          await (value as Disposable).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: (name: string) => unknown) {
+      fallback = resolve;
+    },
+
+    _getEntry(name: string): Entry | undefined {
+      return registry.get(name) ?? parent?._getEntry(name);
+    },
+
+    _forget(child: ScopeContainer) {
+      const at = children.indexOf(child);
+      if (at !== -1) children.splice(at, 1);
+    },
+
+    /** 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(): Container {
+  return createScope();
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export {
+  type Container,
+  type RegisterOptions,
+  type Constructor,
+  type Disposable,
+} from './container.js';
+export { createContainer } from './create.js';