@fougere/container 0.8.3-alpha.0 → 0.9.0-alpha.0

package/dist/container.d.ts

@@ -1,14 +1,15 @@
-/**
- * A class constructor with any arguments.
- */
 export type Constructor<T = unknown> = new (...args: any[]) => T;
-/**
- * Registration options.
- */
 export interface RegisterOptions {
-    /** Lifetime of the resolved value. */
+    /**
+     * `'singleton'` builds once per scope and the container disposes it; `'transient'`
+     * builds per `resolve` and the caller closes it. Absent means `'transient'`.
+     */
     lifetime?: 'singleton' | 'transient';
-    /** Dependency type names for type-based resolution (from AST scan). */
+    /**
+     * The TYPE names of the constructor's parameters, resolved in this scope in order —
+     * `constructor(private users: UserRepository, private log: Logger)` is
+     * `deps: ['UserRepository', 'Logger']`.
+     */
     deps?: string[];
 }
 /** Anything holding a resource can say so, and disposing the container says it back. */
@@ -17,19 +18,19 @@ export interface Disposable {
 }
 /** DI container interface — the only thing application code sees. */
 export interface Container {
-    /** Register a class by name. Its `deps` are resolved from this container. */
+    /** The container builds it: `register('UserService', UserService, { deps: ['UserRepository'] })`. */
     register<T>(name: string, ctor: Constructor<T>, options?: RegisterOptions): void;
-    /** Register a pre-built value by name. */
+    /** Already built, so never disposed here — `registerValue('Logger', new Logger('app'))`, a scope, a config. */
     registerValue<T>(name: string, value: T): void;
-    /** Resolve a dependency by name. */
+    /** Throws when nothing answers the name; `has` asks without throwing. */
     resolve<T>(name: string): T;
-    /** Check if a name is registered (including parent scopes). */
+    /** Answers for this scope and its parents, and builds nothing. */
     has(name: string): boolean;
     /** A resolver of last resort, consulted when no scope holds the name. */
     setFallback?(resolve: (name: string) => unknown): void;
-    /** Create a child scope. Inherits parent registrations. */
+    /** The child reads every registration above it; the parent closes it. */
     createScope(): Container;
-    /** Dispose the container. */
+    /** Children first, then what this scope built, in reverse — refusals travel as one `AggregateError`. */
     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;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,sCAAsC;IACtC,QAAQ,CAAC,EAAE,WAAW,GAAG,WAAW,CAAC;IACrC,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,wFAAwF;AACxF,MAAM,WAAW,UAAU;IACzB,OAAO,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjC;AAED,qEAAqE;AACrE,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,yEAAyE;IACzE,WAAW,CAAC,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI,CAAC;IAEvD,2DAA2D;IAC3D,WAAW,IAAI,SAAS,CAAC;IAEzB,6BAA6B;IAC7B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B"}
+{"version":3,"file":"container.d.ts","sourceRoot":"","sources":["../src/container.ts"],"names":[],"mappings":"AACA,MAAM,MAAM,WAAW,CAAC,CAAC,GAAG,OAAO,IAAI,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;AAEjE,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,QAAQ,CAAC,EAAE,WAAW,GAAG,WAAW,CAAC;IAErC;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,wFAAwF;AACxF,MAAM,WAAW,UAAU;IACzB,OAAO,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjC;AAED,qEAAqE;AACrE,MAAM,WAAW,SAAS;IACxB,qGAAqG;IACrG,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;IAEjF,+GAA+G;IAC/G,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IAE/C,yEAAyE;IACzE,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC;IAE5B,kEAAkE;IAClE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAE3B,yEAAyE;IACzE,WAAW,CAAC,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI,CAAC;IAEvD,yEAAyE;IACzE,WAAW,IAAI,SAAS,CAAC;IAEzB,wGAAwG;IACxG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B"}

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;AAiJ1F,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;AA4I1F,wBAAgB,eAAe,IAAI,SAAS,CAE3C"}

package/dist/create.js

@@ -2,14 +2,11 @@ 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.
+    // In construction order: a thing built later may hold one built earlier, so disposal
+    // walks this backwards.
     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.
+    // Closed by this container, and before `built` — a child may hold what this scope built,
+    // never the other way round.
     const children = [];
     let fallback;
     const remember = (value) => {
@@ -36,8 +33,8 @@ function createScope(parent) {
             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.
+            // Nobody holds it. A frond declared in `remotes` registers nothing here, so its
+            // façade is fabricated by the fallback rather than found.
             if (!entry) {
                 const made = container._getFallback()?.(name);
                 if (made !== undefined) {
@@ -49,9 +46,8 @@ function createScope(parent) {
             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.
+            // The container disposes what it KEEPS: a transient is handed over and forgotten,
+            // and its caller is the one who knows when it is done.
             if (entry.lifetime === 'singleton') {
                 entry.instance = value;
                 remember(value);
@@ -67,15 +63,14 @@ function createScope(parent) {
             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.
+            // Everything is told before anything throws, then the failures travel together.
+            // Dropped from the parent first: a scope that closes itself leaves a reference the
+            // parent would hold for the life of the process.
             parent?._forget(container);
             const failures = [];
-            for (const child of children.reverse()) {
+            // A copy: closing a child splices it out of `children`, so walking the array
+            // itself stepped over every second sibling.
+            for (const child of [...children].reverse()) {
                 try {
                     await child.dispose();
                 }

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/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { type Container, type RegisterOptions, type Constructor, type Disposable, } from './container.js';
+export { type Container, type Constructor, } 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,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,UAAU,GAChB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,SAAS,EACd,KAAK,WAAW,GACjB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fougere/container",
-  "version": "0.8.3-alpha.0",
+  "version": "0.9.0-alpha.0",
   "description": "Fougere's DI container: resolution by type, wired from the AST scan. Zero dependencies.",
   "keywords": [
     "fougere",

package/src/container.ts

@@ -1,16 +1,18 @@
-/**
- * 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. */
+  /**
+   * `'singleton'` builds once per scope and the container disposes it; `'transient'`
+   * builds per `resolve` and the caller closes it. Absent means `'transient'`.
+   */
   lifetime?: 'singleton' | 'transient';
-  /** Dependency type names for type-based resolution (from AST scan). */
+
+  /**
+   * The TYPE names of the constructor's parameters, resolved in this scope in order —
+   * `constructor(private users: UserRepository, private log: Logger)` is
+   * `deps: ['UserRepository', 'Logger']`.
+   */
   deps?: string[];
 }
 
@@ -21,24 +23,24 @@ export interface Disposable {
 
 /** DI container interface — the only thing application code sees. */
 export interface Container {
-  /** Register a class by name. Its `deps` are resolved from this container. */
+  /** The container builds it: `register('UserService', UserService, { deps: ['UserRepository'] })`. */
   register<T>(name: string, ctor: Constructor<T>, options?: RegisterOptions): void;
 
-  /** Register a pre-built value by name. */
+  /** Already built, so never disposed here — `registerValue('Logger', new Logger('app'))`, a scope, a config. */
   registerValue<T>(name: string, value: T): void;
 
-  /** Resolve a dependency by name. */
+  /** Throws when nothing answers the name; `has` asks without throwing. */
   resolve<T>(name: string): T;
 
-  /** Check if a name is registered (including parent scopes). */
+  /** Answers for this scope and its parents, and builds nothing. */
   has(name: string): boolean;
 
   /** A resolver of last resort, consulted when no scope holds the name. */
   setFallback?(resolve: (name: string) => unknown): void;
 
-  /** Create a child scope. Inherits parent registrations. */
+  /** The child reads every registration above it; the parent closes it. */
   createScope(): Container;
 
-  /** Dispose the container. */
+  /** Children first, then what this scope built, in reverse — refusals travel as one `AggregateError`. */
   dispose(): Promise<void>;
 }

package/src/create.ts

@@ -18,14 +18,11 @@ const isDisposable = (value: unknown): value is Disposable =>
 
 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.
+  // In construction order: a thing built later may hold one built earlier, so disposal
+  // walks this backwards.
   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.
+  // Closed by this container, and before `built` — a child may hold what this scope built,
+  // never the other way round.
   const children: ScopeContainer[] = [];
   let fallback: ((name: string) => unknown) | undefined;
 
@@ -57,8 +54,8 @@ function createScope(parent?: ScopeContainer): ScopeContainer {
         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.
+      // Nobody holds it. A frond declared in `remotes` registers nothing here, so its
+      // façade is fabricated by the fallback rather than found.
       if (!entry) {
         const made = container._getFallback()?.(name);
         if (made !== undefined) {
@@ -70,9 +67,8 @@ function createScope(parent?: ScopeContainer): ScopeContainer {
 
       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.
+      // The container disposes what it KEEPS: a transient is handed over and forgotten,
+      // and its caller is the one who knows when it is done.
       if (entry.lifetime === 'singleton') {
         entry.instance = value;
         remember(value);
@@ -91,15 +87,14 @@ function createScope(parent?: ScopeContainer): ScopeContainer {
     },
 
     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.
+      // Everything is told before anything throws, then the failures travel together.
+      // Dropped from the parent first: a scope that closes itself leaves a reference the
+      // parent would hold for the life of the process.
       parent?._forget(container);
       const failures: unknown[] = [];
-      for (const child of children.reverse()) {
+      // A copy: closing a child splices it out of `children`, so walking the array
+      // itself stepped over every second sibling.
+      for (const child of [...children].reverse()) {
         try {
           await child.dispose();
         } catch (error) {

package/src/index.ts

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