ts-ioc-container 65.0.0 → 66.0.0

package/README.md

@@ -2385,6 +2385,8 @@ Sometimes you don't want to change the dependency, only to react to it. Use the
 
 Hooks run after the whole `decorate(...)` chain, so they always observe the fully decorated dependency, and their return value is ignored — `onResolve` can never swap the dependency out. They fire per resolution, which means a `singleton()` provider runs them only on the resolve that fills the cache.
 
+This — or the `@onResolved` decorator over the same provider event — is the recommended way to react to a dependency; see [OnConstruct](#onconstruct) for why `@onConstruct` is the narrower tool.
+
 ```typescript
 import 'reflect-metadata';
 import { Container, type IContainer, onResolve, register, Registration as R, singleton } from 'ts-ioc-container';
@@ -2845,10 +2847,14 @@ strategy decides the order, what is awaited, and where a failure goes
 | `SequentialAsync` | one after another           | in order, or all at once (`methodStrategy`) | yes    |
 | `ParallelAsync`   | all at once                 | in order, or all at once (`methodStrategy`) | yes    |
 
+The async strategies require `methodStrategy` (`'sequential'` or `'parallel'`):
+how the hooks of one member relate is named at the construction site rather
+than left to a default.
+
 ```typescript
 const container = new Container()
   .useModule(new OnConstructModule(new SequentialSync({ key: 'onConstruct' })))
-  .useModule(new OnDisposeModule(new ParallelAsync({ key: 'onScopeDisposed' })));
+  .useModule(new OnDisposeModule(new ParallelAsync({ key: 'onScopeDisposed', methodStrategy: 'parallel' })));
 ```
 
 Resolution and disposal stay synchronous under every strategy: a run stays
@@ -2915,6 +2921,17 @@ and `OnResolvedModule` reaches every provider through `registered`.
 
 ### OnConstruct
 
+> **Prefer `@onResolved` — or the [`onResolve`](#on-resolve) pipe — over
+> `@onConstruct`.** Construction is the *injector's* event, so `@onConstruct`
+> fires only for dependencies the injector builds: a `fromValue` constant or a
+> factory registration never triggers it. It also observes the instance before
+> the provider's `decorate(...)` chain wraps it, so a hook sees the bare
+> instance rather than what the caller receives. `@onResolved` runs on every
+> dependency leaving a provider, after the whole decorate chain — the same
+> ordering, awaiting and error handling, on what the caller actually gets.
+> Reach for `@onConstruct` only when you mean "this class was just constructed"
+> specifically.
+
 ```typescript
 import 'reflect-metadata';
 import {
@@ -3039,7 +3056,7 @@ describe('onConstruct', function () {
 
     // An async strategy awaits the hooks; resolution itself still does not wait for them.
     const container = new Container()
-      .useModule(new OnConstructModule(new SequentialAsync({ key: 'onConstruct' })))
+      .useModule(new OnConstructModule(new SequentialAsync({ key: 'onConstruct', methodStrategy: 'sequential' })))
       .addRegistration(R.fromValue('postgres://localhost:5432').bindTo('ConnectionString'));
 
     const db = container.resolve(DatabaseConnection);
@@ -3066,6 +3083,7 @@ describe('onConstruct', function () {
       new OnConstructModule(
         new SequentialAsync({
           key: 'onConstruct',
+          methodStrategy: 'sequential',
           onError: (scope) => (ex) => {
             captured = { ex, scope };
           },

package/cjm/hooks/AsyncHookExecutionStrategy.js

@@ -4,7 +4,7 @@ exports.AsyncHookExecutionStrategy = void 0;
 const HookExecutionStrategy_1 = require("./HookExecutionStrategy");
 class AsyncHookExecutionStrategy extends HookExecutionStrategy_1.HookExecutionStrategy {
     methodStrategy;
-    constructor({ methodStrategy = 'sequential', ...props }) {
+    constructor({ methodStrategy, ...props }) {
         super(props);
         this.methodStrategy = methodStrategy;
     }

package/esm/hooks/AsyncHookExecutionStrategy.js

@@ -1,7 +1,7 @@
 import { HookExecutionStrategy, runAtOnce, runInOrder, } from './HookExecutionStrategy.js';
 export class AsyncHookExecutionStrategy extends HookExecutionStrategy {
     methodStrategy;
-    constructor({ methodStrategy = 'sequential', ...props }) {
+    constructor({ methodStrategy, ...props }) {
         super(props);
         this.methodStrategy = methodStrategy;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-ioc-container",
-  "version": "65.0.0",
+  "version": "66.0.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/AsyncHookExecutionStrategy.d.ts

@@ -1,7 +1,7 @@
 import { HookExecutionStrategy, type HookExecutionStrategyProps, type MemberHooks } from './HookExecutionStrategy.js';
 export type MethodStrategy = 'sequential' | 'parallel';
 export type AsyncHookExecutionStrategyProps = HookExecutionStrategyProps & {
-    methodStrategy?: MethodStrategy;
+    methodStrategy: MethodStrategy;
 };
 export declare abstract class AsyncHookExecutionStrategy extends HookExecutionStrategy {
     private readonly methodStrategy;