@fougere/container 0.3.0-alpha.0 → 0.5.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fougere/container",
-  "version": "0.3.0-alpha.0",
+  "version": "0.5.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';