ts-ioc-container 60.3.0 → 62.0.0

package/README.md

@@ -18,7 +18,7 @@ provider pipelines, aliases, and custom injector strategies.
 - clean API for classes, keys, tokens, aliases, and scopes
 - no global container object; pass containers and scopes explicitly
 - supports tagged application, request, transaction, page, and widget scopes
-- decorator support with `@register`, `@inject`, `@onConstruct`, and `@onContainerDisposed`
+- decorator support with `@register`, `@inject`, `@onConstruct`, and `@onScopeDisposed`
 - can [inject properties](#inject-property)
 - can inject [lazy dependencies](#lazy)
 - composable provider and registration pipelines
@@ -54,9 +54,9 @@ provider pipelines, aliases, and custom injector strategies.
   - [Scope](#scope) `scope`
 - [Module](#module)
 - [Hook](#hook) `@hook`
+  - [Hook domains](#hook-domains) `ScopeHook` `InjectorHook` `ProviderHook`
   - [OnConstruct](#onconstruct) `@onConstruct`
-  - [OnConstructAsync](#onconstructasync) `@onConstructAsync`
-  - [OnContainerDisposed](#oncontainerdisposed) `@onContainerDisposed`
+  - [OnScopeDisposed](#onscopedisposed) `@onScopeDisposed`
   - [Inject Property](#inject-property)
   - [Inject Method](#inject-method)
 - [Mock](#mock)
@@ -107,7 +107,7 @@ bundlers tree-shake unused exports.
 
 > [!NOTE]
 > The default `MetadataInjector` (and the `@inject` / `@onConstruct` /
-> `@onContainerDisposed` decorators) rely on `reflect-metadata`. It is declared as an
+> `@onScopeDisposed` decorators) rely on `reflect-metadata`. It is declared as an
 > optional peer dependency — install it and import it once at your entrypoint.
 > `SimpleInjector` and `ProxyInjector` do not need it.
 
@@ -454,7 +454,7 @@ describe('Instances', function () {
 Sometimes you want to dispose a container or scope. For example, when a request, page, widget, or other local lifecycle ends.
 
 - container can be disposed
-- when container is disposed then it runs its `onContainerDisposed` hooks, unregisters its providers, removes its local instances, and detaches from its parent
+- when container is disposed then it runs its `onScopeDisposed` hooks, unregisters its providers, removes its local instances, and detaches from its parent
 
 > [!IMPORTANT]
 > Dispose is local to the container being disposed. Child scopes are not disposed automatically; dispose them explicitly when their own lifecycle ends.
@@ -473,7 +473,7 @@ import { bindTo, Container, ContainerDisposedError, register, Registration as R,
  * - Cache entries cleared
  *
  * The container.dispose() method:
- * 1. Executes all onContainerDisposed hooks
+ * 1. Executes all onScopeDisposed hooks
  * 2. Clears all instances and registrations
  * 3. Detaches from parent scope
  * 4. Prevents further resolution
@@ -2379,7 +2379,7 @@ describe('Decorator Pattern', () => {
 
 ### On resolve
 
-Sometimes you don't want to change the dependency, only to react to it. Use the `onResolve(...)` pipe — it appends a `DependencyHook` that receives the resolved dependency and the resolving scope.
+Sometimes you don't want to change the dependency, only to react to it. Use the `onResolve(...)` pipe — it appends a `ProviderHook` that receives the resolved dependency and the resolving scope.
 
 - `provider(onResolve((instance, scope) => tracker.track(instance)))`
 
@@ -2828,16 +2828,78 @@ Decorators are applied bottom-up, so `authorize` runs first, then `validate` and
 `(...prev) => [...prev].reverse()` to reorder, or `() => [onlyThisOne]` to
 replace the accumulated hooks.
 
-`@onConstruct`, `@onConstructAsync` and `@onContainerDisposed` keep their
-variadic signature and compensate for the bottom-up application order, so
-stacked decorators run in declaration order: `@onConstruct(h1) @onConstruct(h2)`
-runs `h1` before `h2`.
+`@onConstruct` and `@onScopeDisposed` keep their variadic signature and
+compensate for the bottom-up application order, so stacked decorators run in
+declaration order: `@onConstruct(h1) @onConstruct(h2)` runs `h1` before `h2`.
+
+Every hook may be sync or async — one decorator and one module take both, so
+there is no separate async form to reach for. A `HooksRunner` runs a hook chain
+eagerly and stays synchronous until a hook returns a promise, then awaits the
+rest of that chain. Sync hooks therefore finish before `resolve` (or `dispose`)
+returns, exactly as before; async ones are started there and settle afterwards,
+so `resolve` returns before they finish. Instances that must expose readiness
+should publish it themselves, for example by storing the pending promise on the
+instance.
+
+`HooksRunner.execute` mirrors that: it returns `undefined` when nothing went
+async and a promise otherwise, so a caller running its own hooks can `await` the
+result either way.
+
+Every module takes an optional `onException` handler, and it catches both kinds
+of failure — what a sync hook threw and what an async hook rejected with.
+Without one, a sync hook throws out of the call and an async hook surfaces as an
+unhandled promise rejection.
+
+### Hook domains
+
+The decorators above declare hook *metadata* on a class. The imperative side —
+the callbacks the container machinery runs — is registered on whichever
+abstraction raises the event, one hook type per domain:
+
+| Domain       | Registered on | Type            | Methods                                                  |
+| ------------ | ------------- | --------------- | -------------------------------------------------------- |
+| **Scope**    | `IContainer`  | `ScopeHook`     | `onScopeCreated(...)`, `onScopeDisposed(...)`            |
+| **Scope**    | `IContainer`  | `RegisteredHook`| `onRegistered(...)`                                      |
+| **Injector** | `IInjector`   | `InjectorHook`  | `onConstructed(...)`                                     |
+| **Provider** | `IProvider`   | `ProviderHook`  | `onResolved(...)`, or the [`onResolve`](#on-resolve) pipe |
+
+A container never hands its injector out — the injector is configured first and
+passed in at construction:
+
+```typescript
+// Construction is the injector's event, not a scope's
+const injector = new MetadataInjector().onConstructed((instance, scope) => metrics.built(instance, scope));
+
+const container = new Container({ injector, tags: ['application'] })
+  .onScopeCreated((scope) => audit.scopeOpened(scope))
+  .onScopeDisposed((scope) => audit.scopeClosed(scope))
+  .onRegistered((provider, key) => audit.registered(key));
+```
+
+A container passes its injector to every scope it creates, so **one injector**
+backs the whole scope tree and an `onConstructed` hook covers all of it, whenever
+it was added. Scope hooks, by contrast, are copied into a child at `createScope`
+time, so a child inherits what its parent held then and later additions to either
+stay local.
+
+The built-in modules follow the same split. `OnConstructModule` is an
+**injector** module (`IInjectorModule`), applied with `injector.useModule(...)`:
+
+```typescript
+const injector = new MetadataInjector().useModule(new OnConstructModule());
+const container = new Container({ injector });
+```
+
+`OnDisposeModule` is a container module hooking `onScopeDisposed`, and
+`OnResolvedModule` is a container module reaching every provider through
+`onRegistered`.
 
 ### OnConstruct
 
 ```typescript
 import 'reflect-metadata';
 import {
+  MetadataInjector,
   OnConstructModule,
   Container,
   type ExecutionContext,
@@ -2852,6 +2914,10 @@ const execute: HookFn = (ctx) => {
   ctx.invokeMethod({ args: ctx.resolveArgs() });
 };
 
+const executeAsync: HookFn = async (ctx) => {
+  await ctx.invokeMethod({ args: ctx.resolveArgs() });
+};
+
 describe('onConstruct', function () {
   it('should run initialization method after dependencies are resolved', function () {
     class DatabaseConnection {
@@ -2865,9 +2931,9 @@ describe('onConstruct', function () {
       }
     }
 
-    const container = new Container()
-      .useModule(new OnConstructModule())
-      .addRegistration(R.fromValue('postgres://localhost:5432').bindTo('ConnectionString'));
+    const container = new Container({
+      injector: new MetadataInjector().useModule(new OnConstructModule()),
+    }).addRegistration(R.fromValue('postgres://localhost:5432').bindTo('ConnectionString'));
 
     const db = container.resolve(DatabaseConnection);
 
@@ -2886,11 +2952,13 @@ describe('onConstruct', function () {
     }
 
     let captured: { ex: unknown; context: ExecutionContext } | undefined;
-    const container = new Container().useModule(
-      new OnConstructModule((ex, context) => {
-        captured = { ex, context };
-      }),
-    );
+    const container = new Container({
+      injector: new MetadataInjector().useModule(
+        new OnConstructModule((ex, context) => {
+          captured = { ex, context };
+        }),
+      ),
+    });
 
     expect(() => container.resolve(BrokenService)).not.toThrow();
     expect(captured?.ex).toBe(failure);
@@ -2907,7 +2975,7 @@ describe('onConstruct', function () {
       init() {}
     }
 
-    const container = new Container().useModule(new OnConstructModule());
+    const container = new Container({ injector: new MetadataInjector().useModule(new OnConstructModule()) });
 
     expect(() => container.resolve(BrokenService)).toThrow(failure);
   });
@@ -2921,44 +2989,20 @@ describe('onConstruct', function () {
     }
 
     let scope: IContainer | undefined;
-    const container = new Container().useModule(
-      new OnConstructModule((_ex, context) => {
-        scope = context.scope;
-      }),
-    );
+    const container = new Container({
+      injector: new MetadataInjector().useModule(
+        new OnConstructModule((_ex, context) => {
+          scope = context.scope;
+        }),
+      ),
+    });
     const child = container.createScope();
 
     child.resolve(BrokenService);
 
     expect(scope).toBe(child);
   });
-});
-
-```
-
-### OnConstructAsync
-
-`@onConstructAsync` runs promise-returning initialization. Resolution stays
-synchronous: `OnConstructAsyncModule` starts the hooks when the instance
-is created and they settle afterwards, so `resolve` returns before they finish.
-
-```typescript
-import 'reflect-metadata';
-import {
-  OnConstructAsyncModule,
-  Container,
-  type ExecutionContext,
-  type HookFn,
-  inject,
-  onConstructAsync,
-  Registration as R,
-} from 'ts-ioc-container';
-
-const execute: HookFn = async (ctx) => {
-  await ctx.invokeMethod({ args: ctx.resolveArgs() });
-};
 
-describe('onConstructAsync', function () {
   it('should run an async initialization method after the instance is created', async function () {
     class DatabaseConnection {
       isConnected = false;
@@ -2973,7 +3017,7 @@ describe('onConstructAsync', function () {
         });
       }
 
-      @onConstructAsync(execute)
+      @onConstruct(executeAsync)
       async connect(@inject('ConnectionString') connectionString: string) {
         await Promise.resolve();
         this.connectionString = connectionString;
@@ -2982,9 +3026,9 @@ describe('onConstructAsync', function () {
       }
     }
 
-    const container = new Container()
-      .useModule(new OnConstructAsyncModule())
-      .addRegistration(R.fromValue('postgres://localhost:5432').bindTo('ConnectionString'));
+    const container = new Container({
+      injector: new MetadataInjector().useModule(new OnConstructModule()),
+    }).addRegistration(R.fromValue('postgres://localhost:5432').bindTo('ConnectionString'));
 
     const db = container.resolve(DatabaseConnection);
 
@@ -3001,16 +3045,18 @@ describe('onConstructAsync', function () {
     const failure = new Error('boom');
 
     class BrokenService {
-      @onConstructAsync(() => Promise.reject(failure))
+      @onConstruct(() => Promise.reject(failure))
       init() {}
     }
 
     let captured: { ex: unknown; context: ExecutionContext } | undefined;
-    const container = new Container().useModule(
-      new OnConstructAsyncModule((ex, context) => {
-        captured = { ex, context };
-      }),
-    );
+    const container = new Container({
+      injector: new MetadataInjector().useModule(
+        new OnConstructModule((ex, context) => {
+          captured = { ex, context };
+        }),
+      ),
+    });
 
     const child = container.createScope();
     child.resolve(BrokenService);
@@ -3024,7 +3070,7 @@ describe('onConstructAsync', function () {
 
 ```
 
-### OnContainerDisposed
+### OnScopeDisposed
 
 ```typescript
 import 'reflect-metadata';
@@ -3034,7 +3080,7 @@ import {
   Container,
   type HookFn,
   inject,
-  onContainerDisposed,
+  onScopeDisposed,
   register,
   Registration as R,
   singleton,
@@ -3063,13 +3109,13 @@ class Logger {
     this.messages.push(message);
   }
 
-  @onContainerDisposed(execute)
+  @onScopeDisposed(execute)
   save() {
     this.logsRepo.saveLogs(this.messages);
   }
 }
 
-describe('onContainerDisposed', function () {
+describe('onScopeDisposed', function () {
   it('should invoke hooks on all instances when container is disposed', function () {
     const container = new Container()
       .useModule(new OnDisposeModule())

package/cjm/container/Container.js

@@ -19,10 +19,9 @@ class Container {
     providers = new Map();
     aliases = new AliasMap_1.AliasMap();
     injector;
-    onConstructHookList = [];
-    onDisposeHookList = [];
     onScopeCreatedHookList = [];
-    onProviderRegisteredHookList = [];
+    onScopeDisposedHookList = [];
+    onRegisteredHookList = [];
     constructor(options = {}) {
         this.injector = options.injector ?? new MetadataInjector_1.MetadataInjector();
         this.parent = options.parent ?? new EmptyContainer_1.EmptyContainer();
@@ -32,8 +31,8 @@ class Container {
         this.validateContainer();
         this.providers.set(key, provider);
         this.aliases.setAliasesByKey(key, aliases);
-        for (const onProviderRegistered of this.onProviderRegisteredHookList) {
-            onProviderRegistered(provider, key, this);
+        for (const onRegistered of this.onRegisteredHookList) {
+            onRegistered(provider, key, this);
         }
         return this;
     }
@@ -78,10 +77,9 @@ class Container {
     createScope({ tags } = {}) {
         this.validateContainer();
         const scope = new Container({ injector: this.injector, parent: this, tags })
-            .onConstruct(...this.onConstructHookList)
-            .onInstanceDisposed(...this.onDisposeHookList)
             .onScopeCreated(...this.onScopeCreatedHookList)
-            .onProviderRegistered(...this.onProviderRegisteredHookList);
+            .onScopeDisposed(...this.onScopeDisposedHookList)
+            .onRegistered(...this.onRegisteredHookList);
         for (const registration of this.getRegistrations()) {
             registration.applyTo(scope);
         }
@@ -103,8 +101,8 @@ class Container {
     dispose() {
         this.validateContainer();
         this.isDisposed = true;
-        for (const hook of this.onDisposeHookList) {
-            hook(this);
+        for (const onScopeDisposed of this.onScopeDisposedHookList) {
+            onScopeDisposed(this);
         }
         this.parent.removeScope(this);
         this.parent = new EmptyContainer_1.EmptyContainer();
@@ -115,10 +113,9 @@ class Container {
         this.aliases.destroy();
         this.instances.clear();
         this.registrations = [];
-        this.onConstructHookList.length = 0;
-        this.onDisposeHookList.length = 0;
         this.onScopeCreatedHookList.length = 0;
-        this.onProviderRegisteredHookList.length = 0;
+        this.onScopeDisposedHookList.length = 0;
+        this.onRegisteredHookList.length = 0;
     }
     addRegistration(registration) {
         this.registrations.push(registration);
@@ -131,27 +128,20 @@ class Container {
     hasRegistration(key) {
         return this.registrations.some((r) => r.getKeyOrFail() === key) || this.parent.hasRegistration(key);
     }
-    onConstruct(...hooks) {
-        this.onConstructHookList.push(...hooks);
-        return this;
-    }
-    onInstanceDisposed(...hooks) {
-        this.onDisposeHookList.push(...hooks);
-        return this;
-    }
     onScopeCreated(...hooks) {
         this.onScopeCreatedHookList.push(...hooks);
         return this;
     }
-    onProviderRegistered(...hooks) {
-        this.onProviderRegisteredHookList.push(...hooks);
+    onScopeDisposed(...hooks) {
+        this.onScopeDisposedHookList.push(...hooks);
+        return this;
+    }
+    onRegistered(...hooks) {
+        this.onRegisteredHookList.push(...hooks);
         return this;
     }
     addInstance(instance) {
         this.instances.add(instance);
-        for (const onConstruct of this.onConstructHookList) {
-            onConstruct(instance, this);
-        }
     }
     getScopes() {
         return [...this.scopes];

package/cjm/container/EmptyContainer.js

@@ -60,16 +60,13 @@ class EmptyContainer {
     resolveOneByAlias(alias, options) {
         throw new DependencyNotFoundError_1.DependencyNotFoundError(`Cannot find alias ${alias.toString()}`);
     }
-    onInstanceDisposed(...hooks) {
-        throw new MethodNotImplementedError_1.MethodNotImplementedError();
-    }
-    onConstruct(...hooks) {
+    onScopeCreated(...hooks) {
         throw new MethodNotImplementedError_1.MethodNotImplementedError();
     }
-    onScopeCreated(...hooks) {
+    onScopeDisposed(...hooks) {
         throw new MethodNotImplementedError_1.MethodNotImplementedError();
     }
-    onProviderRegistered(...hooks) {
+    onRegistered(...hooks) {
         throw new MethodNotImplementedError_1.MethodNotImplementedError();
     }
 }

package/cjm/hooks/HooksRunner.js

@@ -1,10 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HooksRunner = void 0;
+exports.runHooks = exports.HooksRunner = void 0;
 const HookContext_1 = require("./HookContext");
 const hook_1 = require("./hook");
-const UnexpectedHookResultError_1 = require("../errors/UnexpectedHookResultError");
-const promise_1 = require("../utils/promise");
+const runFrom = (fns, index, context) => {
+    for (let i = index; i < fns.length; i++) {
+        const result = fns[i](context);
+        if (result instanceof Promise) {
+            return result.then(() => runFrom(fns, i + 1, context));
+        }
+    }
+};
 class HooksRunner {
     key;
     constructor(key) {
@@ -15,28 +21,30 @@ class HooksRunner {
     }
     execute(target, { scope, createContext = HookContext_1.createHookContext, mapContext = (context) => context, predicate = () => true, }) {
         const hooks = Array.from((0, hook_1.getHooks)(target, this.key).entries()).filter(([methodName]) => predicate(methodName));
-        const runMethodHooks = (methodName, executions) => {
-            const context = mapContext(createContext(target, scope, methodName));
-            for (const execute of executions) {
-                const result = execute(context);
-                if (result instanceof Promise) {
-                    throw new UnexpectedHookResultError_1.UnexpectedHookResultError(`Hook ${methodName} returned a promise, use runHooksAsync instead`);
-                }
-            }
-        };
+        const pending = [];
         for (const [methodName, executions] of hooks) {
-            runMethodHooks(methodName, executions.map(hook_1.toHookFn));
-        }
-    }
-    async executeAsync(target, { scope, createContext = HookContext_1.createHookContext, mapContext = (context) => context, predicate = () => true, }) {
-        const hooks = Array.from((0, hook_1.getHooks)(target, this.key).entries()).filter(([methodName]) => predicate(methodName));
-        const runMethodHooks = async (methodName, executions) => {
             const context = mapContext(createContext(target, scope, methodName));
-            for (const execute of executions) {
-                await (0, promise_1.promisify)(execute(context));
+            const result = runFrom(executions.map(hook_1.toHookFn), 0, context);
+            if (result) {
+                pending.push(result);
             }
-        };
-        return Promise.all(hooks.map(([methodName, executions]) => runMethodHooks(methodName, executions.map(hook_1.toHookFn))));
+        }
+        return pending.length > 0 ? Promise.all(pending).then(() => undefined) : undefined;
     }
 }
 exports.HooksRunner = HooksRunner;
+const runHooks = (runner, target, scope, onException) => {
+    const report = (ex) => {
+        if (!onException) {
+            throw ex;
+        }
+        onException(ex, { scope });
+    };
+    try {
+        runner.execute(target, { scope })?.catch(report);
+    }
+    catch (ex) {
+        report(ex);
+    }
+};
+exports.runHooks = runHooks;

package/cjm/hooks/onConstruct.js

@@ -11,17 +11,9 @@ class OnConstructModule {
     constructor(onException) {
         this.onException = onException;
     }
-    applyTo(container) {
-        container.onConstruct((instance, scope) => {
-            try {
-                exports.onConstructHooksRunner.execute(instance, { scope });
-            }
-            catch (ex) {
-                if (!this.onException) {
-                    throw ex;
-                }
-                this.onException(ex, { scope });
-            }
+    applyTo(injector) {
+        injector.onConstructed((instance, scope) => {
+            (0, HooksRunner_1.runHooks)(exports.onConstructHooksRunner, instance, scope, this.onException);
         });
     }
 }

package/cjm/hooks/onResolved.js

@@ -7,14 +7,18 @@ const resolveHooks_1 = require("./resolveHooks");
 exports.onResolvedHooksRunner = new HooksRunner_1.HooksRunner('onResolved');
 exports.onResolved = (0, resolveHooks_1.resolvedHook)('onResolved');
 exports.onceResolved = (0, resolveHooks_1.onceResolvedHook)('onResolved');
-const runHooks = (0, resolveHooks_1.forEachResolvedObject)((0, resolveHooks_1.executeHooks)(exports.onResolvedHooksRunner));
+const runHooks = (onException) => (0, resolveHooks_1.forEachResolvedObject)((0, resolveHooks_1.executeHooks)(exports.onResolvedHooksRunner, onException));
 class OnResolvedModule {
+    runHooks;
+    constructor(onException) {
+        this.runHooks = runHooks(onException);
+    }
     applyTo(container) {
-        container.onProviderRegistered((provider) => {
-            provider.onResolve(runHooks);
+        container.onRegistered((provider) => {
+            provider.onResolved(this.runHooks);
         });
     }
 }
 exports.OnResolvedModule = OnResolvedModule;
-const resolved = () => (0, IRegistration_1.registerPipe)((p) => p.onResolve(runHooks));
+const resolved = (onException) => (0, IRegistration_1.registerPipe)((p) => p.onResolved(runHooks(onException)));
 exports.resolved = resolved;

package/cjm/hooks/onScopeDisposed.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OnDisposeModule = exports.onScopeDisposed = exports.onScopeDisposedHooksRunner = void 0;
+const hook_1 = require("./hook");
+const HooksRunner_1 = require("./HooksRunner");
+exports.onScopeDisposedHooksRunner = new HooksRunner_1.HooksRunner('onScopeDisposed');
+const onScopeDisposed = (...fns) => (0, hook_1.hook)('onScopeDisposed', (0, hook_1.prependHooks)(...fns));
+exports.onScopeDisposed = onScopeDisposed;
+class OnDisposeModule {
+    onException;
+    constructor(onException) {
+        this.onException = onException;
+    }
+    applyTo(container) {
+        container.onScopeDisposed((scope) => {
+            for (const instance of scope.getInstances()) {
+                (0, HooksRunner_1.runHooks)(exports.onScopeDisposedHooksRunner, instance, scope, this.onException);
+            }
+        });
+    }
+}
+exports.OnDisposeModule = OnDisposeModule;

package/cjm/hooks/resolveHooks.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.executeHooksAsync = exports.executeHooks = exports.forEachResolvedObject = exports.onceResolvedHook = exports.resolvedHook = exports.invokeMethod = void 0;
+exports.executeHooks = exports.forEachResolvedObject = exports.onceResolvedHook = exports.resolvedHook = exports.invokeMethod = void 0;
+const HooksRunner_1 = require("./HooksRunner");
 const hook_1 = require("./hook");
 const basic_1 = require("../utils/basic");
 const invokeMethod = (context) => {
@@ -28,17 +29,5 @@ const forEachResolvedObject = (run) => (dependency, scope) => {
     }
 };
 exports.forEachResolvedObject = forEachResolvedObject;
-const executeHooks = (runner) => (dependency, scope) => runner.execute(dependency, { scope });
+const executeHooks = (runner, onException) => (dependency, scope) => (0, HooksRunner_1.runHooks)(runner, dependency, scope, onException);
 exports.executeHooks = executeHooks;
-const executeHooksAsync = (runner, onException) => (dependency, scope) => {
-    if (!runner.hasHooks(dependency)) {
-        return;
-    }
-    runner.executeAsync(dependency, { scope }).catch((ex) => {
-        if (!onException) {
-            throw ex;
-        }
-        onException(ex, { scope });
-    });
-};
-exports.executeHooksAsync = executeHooksAsync;