ts-ioc-container 55.6.0 → 55.7.0

package/README.md

@@ -53,6 +53,7 @@ provider pipelines, aliases, and custom injector strategies.
 - [Module](#module)
 - [Hook](#hook) `@hook`
   - [OnConstruct](#onconstruct) `@onConstruct`
+  - [OnConstructAsync](#onconstructasync) `@onConstructAsync`
   - [OnContainerDisposed](#oncontainerdisposed) `@onContainerDisposed`
   - [Inject Property](#inject-property)
   - [Inject Method](#inject-method)
@@ -2584,6 +2585,94 @@ describe('onConstruct', function () {
 
 ```
 
+### OnConstructAsync
+
+`@onConstructAsync` runs promise-returning initialization. Resolution stays
+synchronous: `AddOnConstructAsyncHookModule` starts the hooks when the instance
+is created and they settle afterwards, so `resolve` returns before they finish.
+
+```typescript
+import 'reflect-metadata';
+import {
+  AddOnConstructAsyncHookModule,
+  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;
+      connectionString = '';
+      readonly ready: Promise<void>;
+
+      private markReady!: () => void;
+
+      constructor() {
+        this.ready = new Promise((resolve) => {
+          this.markReady = resolve;
+        });
+      }
+
+      @onConstructAsync(execute)
+      async connect(@inject('ConnectionString') connectionString: string) {
+        await Promise.resolve();
+        this.connectionString = connectionString;
+        this.isConnected = true;
+        this.markReady();
+      }
+    }
+
+    const container = new Container()
+      .useModule(new AddOnConstructAsyncHookModule())
+      .addRegistration(R.fromValue('postgres://localhost:5432').bindTo('ConnectionString'));
+
+    const db = container.resolve(DatabaseConnection);
+
+    // resolution does not wait for async hooks
+    expect(db.isConnected).toBe(false);
+
+    await db.ready;
+
+    expect(db.isConnected).toBe(true);
+    expect(db.connectionString).toBe('postgres://localhost:5432');
+  });
+
+  it('should forward rejected hooks to the onException handler with the execution context', async function () {
+    const failure = new Error('boom');
+
+    class BrokenService {
+      @onConstructAsync(() => Promise.reject(failure))
+      init() {}
+    }
+
+    let captured: { ex: unknown; context: ExecutionContext } | undefined;
+    const container = new Container().useModule(
+      new AddOnConstructAsyncHookModule((ex, context) => {
+        captured = { ex, context };
+      }),
+    );
+
+    const child = container.createScope();
+    child.resolve(BrokenService);
+
+    await vi.waitFor(() => expect(captured).toBeDefined());
+
+    expect(captured?.ex).toBe(failure);
+    expect(captured?.context.scope).toBe(child);
+  });
+});
+
+```
+
 ### OnContainerDisposed
 
 ```typescript

package/cjm/hooks/onConstructAsync.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AddOnConstructAsyncHookModule = exports.onConstructAsync = exports.onConstructAsyncHooksRunner = void 0;
+const hook_1 = require("./hook");
+const HooksRunner_1 = require("./HooksRunner");
+exports.onConstructAsyncHooksRunner = new HooksRunner_1.HooksRunner('onConstructAsync');
+const onConstructAsync = (...fns) => (0, hook_1.hook)('onConstructAsync', ...fns);
+exports.onConstructAsync = onConstructAsync;
+class AddOnConstructAsyncHookModule {
+    onException;
+    constructor(onException) {
+        this.onException = onException;
+    }
+    applyTo(container) {
+        container.addOnConstructHook((instance, scope) => {
+            if (!exports.onConstructAsyncHooksRunner.hasHooks(instance)) {
+                return;
+            }
+            exports.onConstructAsyncHooksRunner.executeAsync(instance, { scope }).catch((ex) => {
+                if (!this.onException) {
+                    throw ex;
+                }
+                this.onException(ex, { scope });
+            });
+        });
+    }
+}
+exports.AddOnConstructAsyncHookModule = AddOnConstructAsyncHookModule;

package/cjm/index.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ClassToken = exports.toSingleAlias = exports.SingleAliasToken = exports.toGroupAlias = exports.GroupAliasToken = exports.InjectionToken = exports.HooksRunner = exports.AddOnDisposeHookModule = exports.onContainerDisposed = exports.onContainerDisposedHooksRunner = exports.AddOnConstructHookModule = exports.onConstruct = exports.onConstructHooksRunner = exports.injectProp = exports.createHookContext = exports.createHookContextFactory = exports.HookContext = exports.hasHooks = exports.hook = exports.getHooks = exports.CannonSingletonApplyTwiceError = exports.UnexpectedHookResultError = exports.ProviderDisposedError = exports.ContainerDisposedError = exports.MethodNotImplementedError = exports.DependencyMissingKeyError = exports.ContainerNotFoundError = exports.DependencyNotFoundError = exports.Registration = exports.appendArgsFn = exports.appendArgs = exports.decorate = exports.singleton = exports.lazy = exports.scopeAccess = exports.scope = exports.bindTo = exports.register = exports.Provider = exports.ProxyInjector = exports.SimpleInjector = exports.resolveArgs = exports.argsFn = exports.args = exports.inject = exports.MetadataInjector = exports.Injector = exports.EmptyContainer = exports.Container = exports.isDependencyKey = void 0;
-exports.resolveConstructor = exports.Is = exports.pipe = exports.select = exports.once = exports.shallowCache = exports.debounce = exports.throttle = exports.handleAsyncError = exports.handleError = exports.getMethodTags = exports.addMethodTag = exports.getMethodLabels = exports.addMethodLabel = exports.getMethodMeta = exports.addMethodMeta = exports.getParamTags = exports.addParamTag = exports.getParamLabels = exports.addParamLabel = exports.getParamMeta = exports.addParamMeta = exports.getClassTags = exports.addClassTag = exports.getClassLabels = exports.addClassLabel = exports.getClassMeta = exports.addClassMeta = exports.GroupInstanceToken = exports.ConstantToken = exports.FunctionToken = exports.SingleToken = void 0;
+exports.toGroupAlias = exports.GroupAliasToken = exports.InjectionToken = exports.HooksRunner = exports.AddOnDisposeHookModule = exports.onContainerDisposed = exports.onContainerDisposedHooksRunner = exports.AddOnConstructAsyncHookModule = exports.onConstructAsync = exports.onConstructAsyncHooksRunner = exports.AddOnConstructHookModule = exports.onConstruct = exports.onConstructHooksRunner = exports.injectProp = exports.createHookContext = exports.createHookContextFactory = exports.HookContext = exports.hasHooks = exports.hook = exports.getHooks = exports.CannonSingletonApplyTwiceError = exports.UnexpectedHookResultError = exports.ProviderDisposedError = exports.ContainerDisposedError = exports.MethodNotImplementedError = exports.DependencyMissingKeyError = exports.ContainerNotFoundError = exports.DependencyNotFoundError = exports.Registration = exports.appendArgsFn = exports.appendArgs = exports.decorate = exports.singleton = exports.lazy = exports.scopeAccess = exports.scope = exports.bindTo = exports.register = exports.Provider = exports.ProxyInjector = exports.SimpleInjector = exports.resolveArgs = exports.argsFn = exports.args = exports.inject = exports.MetadataInjector = exports.Injector = exports.EmptyContainer = exports.Container = exports.isDependencyKey = void 0;
+exports.resolveConstructor = exports.Is = exports.pipe = exports.select = exports.once = exports.shallowCache = exports.debounce = exports.throttle = exports.handleAsyncError = exports.handleError = exports.getMethodTags = exports.addMethodTag = exports.getMethodLabels = exports.addMethodLabel = exports.getMethodMeta = exports.addMethodMeta = exports.getParamTags = exports.addParamTag = exports.getParamLabels = exports.addParamLabel = exports.getParamMeta = exports.addParamMeta = exports.getClassTags = exports.addClassTag = exports.getClassLabels = exports.addClassLabel = exports.getClassMeta = exports.addClassMeta = exports.GroupInstanceToken = exports.ConstantToken = exports.FunctionToken = exports.SingleToken = exports.ClassToken = exports.toSingleAlias = exports.SingleAliasToken = void 0;
 var IContainer_1 = require("./container/IContainer");
 Object.defineProperty(exports, "isDependencyKey", { enumerable: true, get: function () { return IContainer_1.isDependencyKey; } });
 var Container_1 = require("./container/Container");
@@ -64,6 +64,10 @@ var onConstruct_1 = require("./hooks/onConstruct");
 Object.defineProperty(exports, "onConstructHooksRunner", { enumerable: true, get: function () { return onConstruct_1.onConstructHooksRunner; } });
 Object.defineProperty(exports, "onConstruct", { enumerable: true, get: function () { return onConstruct_1.onConstruct; } });
 Object.defineProperty(exports, "AddOnConstructHookModule", { enumerable: true, get: function () { return onConstruct_1.AddOnConstructHookModule; } });
+var onConstructAsync_1 = require("./hooks/onConstructAsync");
+Object.defineProperty(exports, "onConstructAsyncHooksRunner", { enumerable: true, get: function () { return onConstructAsync_1.onConstructAsyncHooksRunner; } });
+Object.defineProperty(exports, "onConstructAsync", { enumerable: true, get: function () { return onConstructAsync_1.onConstructAsync; } });
+Object.defineProperty(exports, "AddOnConstructAsyncHookModule", { enumerable: true, get: function () { return onConstructAsync_1.AddOnConstructAsyncHookModule; } });
 var onContainerDisposed_1 = require("./hooks/onContainerDisposed");
 Object.defineProperty(exports, "onContainerDisposedHooksRunner", { enumerable: true, get: function () { return onContainerDisposed_1.onContainerDisposedHooksRunner; } });
 Object.defineProperty(exports, "onContainerDisposed", { enumerable: true, get: function () { return onContainerDisposed_1.onContainerDisposed; } });

package/esm/hooks/onConstructAsync.js

@@ -0,0 +1,23 @@
+import { hook } from './hook.js';
+import { HooksRunner } from './HooksRunner.js';
+export const onConstructAsyncHooksRunner = new HooksRunner('onConstructAsync');
+export const onConstructAsync = (...fns) => hook('onConstructAsync', ...fns);
+export class AddOnConstructAsyncHookModule {
+    onException;
+    constructor(onException) {
+        this.onException = onException;
+    }
+    applyTo(container) {
+        container.addOnConstructHook((instance, scope) => {
+            if (!onConstructAsyncHooksRunner.hasHooks(instance)) {
+                return;
+            }
+            onConstructAsyncHooksRunner.executeAsync(instance, { scope }).catch((ex) => {
+                if (!this.onException) {
+                    throw ex;
+                }
+                this.onException(ex, { scope });
+            });
+        });
+    }
+}

package/esm/index.js

@@ -20,6 +20,7 @@ export { getHooks, hook, hasHooks } from './hooks/hook.js';
 export { HookContext, createHookContextFactory, createHookContext } from './hooks/HookContext.js';
 export { injectProp } from './hooks/injectProp.js';
 export { onConstructHooksRunner, onConstruct, AddOnConstructHookModule, } from './hooks/onConstruct.js';
+export { onConstructAsyncHooksRunner, onConstructAsync, AddOnConstructAsyncHookModule } from './hooks/onConstructAsync.js';
 export { onContainerDisposedHooksRunner, onContainerDisposed, AddOnDisposeHookModule, } from './hooks/onContainerDisposed.js';
 export { HooksRunner } from './hooks/HooksRunner.js';
 export { InjectionToken } from './token/InjectionToken.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-ioc-container",
-  "version": "55.6.0",
+  "version": "55.7.0",
   "description": "Fast, lightweight TypeScript dependency injection container with a clean API, scoped lifecycles, decorators, tokens, hooks, lazy injection, customizable providers, and no global container objects.",
   "publishConfig": {
     "access": "public",

package/typings/hooks/onConstructAsync.d.ts

@@ -0,0 +1,12 @@
+import { HookClass, HookFn } from './hook.js';
+import type { IContainer, IContainerModule } from '../container/IContainer.js';
+import { constructor } from '../utils/basic.js';
+import { HooksRunner } from './HooksRunner.js';
+import type { OnExceptionHandler } from './onConstruct.js';
+export declare const onConstructAsyncHooksRunner: HooksRunner;
+export declare const onConstructAsync: (...fns: (HookFn | constructor<HookClass>)[]) => (target: object, propertyKey: string | symbol) => void;
+export declare class AddOnConstructAsyncHookModule implements IContainerModule {
+    private readonly onException?;
+    constructor(onException?: OnExceptionHandler | undefined);
+    applyTo(container: IContainer): void;
+}

package/typings/index.d.ts

@@ -21,6 +21,7 @@ export { getHooks, hook, hasHooks, type HookFn, type HookClass, type InjectFn, t
 export { HookContext, createHookContextFactory, createHookContext, type IHookContext } from './hooks/HookContext.js';
 export { injectProp } from './hooks/injectProp.js';
 export { onConstructHooksRunner, onConstruct, AddOnConstructHookModule, type OnExceptionHandler, } from './hooks/onConstruct.js';
+export { onConstructAsyncHooksRunner, onConstructAsync, AddOnConstructAsyncHookModule } from './hooks/onConstructAsync.js';
 export { onContainerDisposedHooksRunner, onContainerDisposed, AddOnDisposeHookModule, } from './hooks/onContainerDisposed.js';
 export { HooksRunner, type HooksRunnerContext, type MapHookContext } from './hooks/HooksRunner.js';
 export { InjectionToken } from './token/InjectionToken.js';