ts-ioc-container 68.1.0 → 69.0.0

package/README.md

@@ -1774,13 +1774,16 @@ Sometimes you want to bind some arguments to provider.
 - `provider(appendArgsFn((container) => [container.resolve(Logger), 'someValue']))`
 - `Provider.fromClass(Logger).pipe(appendArgs('someArgument'))`
 
-### Token as argument
+### Dependencies as arguments
 
-When you pass an `InjectionToken` via `token.args(...)`, the container resolves it before the value reaches the constructor. Bare constructors are **not** auto-resolved — wrap a class in `ClassToken` to opt into resolution.
+Args are passed to the constructor **as-is** — the library never resolves an `InjectionToken` (or a bare constructor) it finds in the args list. Resolve it at the call site with `argsFn`:
 
-- `ServiceToken.args(ValueToken)` — `ValueToken` is resolved from the container, its value is passed as arg
-- `ServiceToken.args(new ClassToken(SomeService))` — `SomeService` is constructed by the container
+- `ServiceToken.argsFn((scope) => [ValueToken.resolve(scope)])` — `ValueToken` is resolved from the container, its value is passed as arg
+- `ServiceToken.argsFn((scope) => [scope.resolve(SomeService)])` — `SomeService` is constructed by the container
 - `ServiceToken.args('literal')` — literal value passed directly
+- `ServiceToken.args(ValueToken)` — the token object itself is passed as arg
+
+`argToToken(value)` is the helper for a call site that wants "resolve tokens, pass literals through": it returns an `InjectionToken` as-is and wraps anything else in a `ConstantToken`, so `@inject((scope, { args = [] }) => argToToken(args[0]).resolve(scope))` accepts either.
 
 ### Positional arg injection with `arg(index)`, `args`, and `argsFn`
 
@@ -1788,12 +1791,73 @@ Constructor parameters that should pick up positional args from `ProviderOptions
 
 - `@inject(arg(0))` — resolves the first element of the `args` array passed at resolution time
 - `@inject(args)` — resolves the whole runtime `args` array
-- Works together with `token.args(...)` to pass typed dependencies through the args context
+- Works together with `token.args(...)` / `token.argsFn(...)` to pass typed dependencies through the args context
 
 `argsFn(predicate)` is the general form: it iterates the runtime `args` array and returns the **first argument matching** `predicate(value, index)` — think `args.find(predicate)`. `arg(index)` is just a shortcut for matching by position: `arg(0)` is `argsFn((value, index) => index === 0)`. `args` is `(scope, options) => options.args`, i.e. it returns the runtime args array as-is. Every `InjectFn` receives `(scope, options)`, where `options.args` is the runtime args array.
 
 `findOrFail(predicate)` is the strict, variadic counterpart for places that take the raw args list — `singleton(findOrFail(isUserId))` keys a per-argument singleton, for example. It returns the first argument matching `predicate(value)` and throws `ArgumentNotFoundError` when none does, instead of silently handing out `undefined`.
 
+### Runtime args flow through tokens
+
+Every container-backed token (`SingleToken`, `ClassToken`, `SingleAliasToken`, `GroupAliasToken`, `FunctionToken`) forwards the `args` of its own `resolve` call to the provider, exactly like `container.resolve(key, { args })` does. `token.args(...)` and `token.argsFn(...)` **append after** the runtime args, so `token.args('x').resolve(container, { args: ['r'] })` hands the provider `['r', 'x']`.
+
+Because `@inject(token)` parameters are resolved with the args of the class being constructed, those args **cascade** into every injected dependency: they reach the dependency's provider, its `@inject(arg(index))` parameters, its `scopeAccess` rule and its `singleton()` cache key. That is what lets a per-user `UserService` share a per-user `UserRepository` without passing the id along by hand:
+
+```typescript
+import {
+  arg,
+  bindTo,
+  Container,
+  findOrFail,
+  inject,
+  register,
+  Registration as R,
+  singleton,
+  SingleToken,
+} from 'ts-ioc-container';
+
+interface IUserRepository {
+  userId: string;
+}
+
+const IUserRepositoryKey = new SingleToken<IUserRepository>('IUserRepository');
+const isUserId = (value: unknown): value is string => typeof value === 'string';
+
+// one repository per user id - the id is the singleton cache key
+@register(bindTo(IUserRepositoryKey), singleton(findOrFail<string>(isUserId)))
+class UserRepository implements IUserRepository {
+  constructor(@inject(arg(0)) public userId: string) {}
+}
+
+class UserService {
+  constructor(@inject(IUserRepositoryKey) public repository: IUserRepository) {}
+}
+
+describe('Token Runtime Arguments', function () {
+  it('should forward runtime args to the provider behind the token', function () {
+    const container = new Container().addRegistration(R.fromClass(UserRepository));
+
+    expect(IUserRepositoryKey.resolve(container, { args: ['user-1'] }).userId).toBe('user-1');
+  });
+
+  it('should cascade the runtime args of a class into its injected dependencies', function () {
+    const container = new Container().addRegistration(R.fromClass(UserRepository));
+
+    const service = container.resolve(UserService, { args: ['user-1'] });
+    const sameUser = container.resolve(UserService, { args: ['user-1'] });
+    const otherUser = container.resolve(UserService, { args: ['user-2'] });
+
+    expect(service.repository.userId).toBe('user-1');
+    expect(sameUser.repository).toBe(service.repository);
+    expect(otherUser.repository.userId).toBe('user-2');
+  });
+});
+
+```
+
+> [!IMPORTANT]
+> Runtime args come first. A dependency that reads `@inject(arg(0))` sees the *caller's* first runtime arg whenever the caller was resolved with args, even if its token was specialized with `token.args(...)`. Pick args by shape (`argsFn(predicate)`, `findOrFail(predicate)`) rather than by position when a class can be resolved with runtime args and its dependencies are specialized with `token.args(...)`.
+
 ### Immutable token chaining
 
 `token.args(...)`, `token.argsFn(...)`, and `token.lazy()` all return **new token instances** — the parent token is never mutated. This allows the same token to be specialized in multiple independent ways (one-way linked list: parent → many children).
@@ -1951,14 +2015,16 @@ describe('IProvider', function () {
     }
 
     // EntityManager is generic - it works with ANY repository.
-    // The repository is the first arg passed via `EntityManagerToken.args(...)`.
-    // `@inject(arg(0))` reads it; the container auto-resolves InjectionToken args
-    // before they reach the constructor.
+    // The repository is the first arg; `@inject(arg(0))` reads it. Args are
+    // passed through as-is, so the call site resolves the repository token
+    // itself with `argsFn` before it reaches the constructor.
     const EntityManagerToken = new SingleToken<EntityManager>('EntityManager');
+    const withRepository = (token: SingleToken<IRepository>) =>
+      EntityManagerToken.argsFn((scope) => [token.resolve(scope)]);
 
     @register(
       bindTo(EntityManagerToken),
-      singleton((arg1) => (arg1 as SingleToken).token), // Cache unique instance per repository type
+      singleton((repository) => (repository as IRepository).name), // Cache unique instance per repository type
     )
     class EntityManager {
       constructor(@inject(arg(0)) public repository: IRepository) {}
@@ -1967,11 +2033,11 @@ describe('IProvider', function () {
     class App {
       constructor(
         // Inject EntityManager configured for Users
-        @inject(EntityManagerToken.args(UserRepositoryToken))
+        @inject(withRepository(UserRepositoryToken))
         public userManager: EntityManager,
 
         // Inject EntityManager configured for Todos
-        @inject(EntityManagerToken.args(TodoRepositoryToken))
+        @inject(withRepository(TodoRepositoryToken))
         public todoManager: EntityManager,
       ) {}
     }
@@ -1995,14 +2061,14 @@ describe('IProvider', function () {
         .addRegistration(R.fromClass(TodoRepository));
 
       // Resolve user manager twice
-      const userManager1 = EntityManagerToken.args(UserRepositoryToken).resolve(root);
-      const userManager2 = EntityManagerToken.args(UserRepositoryToken).resolve(root);
+      const userManager1 = withRepository(UserRepositoryToken).resolve(root);
+      const userManager2 = withRepository(UserRepositoryToken).resolve(root);
 
       // Should be same instance (cached)
       expect(userManager1).toBe(userManager2);
 
       // Resolve todo manager
-      const todoManager = EntityManagerToken.args(TodoRepositoryToken).resolve(root);
+      const todoManager = withRepository(TodoRepositoryToken).resolve(root);
 
       // Should be different from user manager
       expect(todoManager).not.toBe(userManager1);

package/cjm/injector/MetadataInjector.js

@@ -27,6 +27,6 @@ const args = (c, { args = [] }) => args;
 exports.args = args;
 const resolveArgs = (target, methodName) => {
     const tokens = (0, parameter_1.getParamMeta)(hookMetaKey(methodName), target);
-    return (scope, { args = [], lazy }) => tokens.map((fn) => fn.resolve(scope, { args: args.map(toToken_1.argToToken).map((t) => t.resolve(scope)), lazy }));
+    return (scope, { args = [], lazy }) => tokens.map((fn) => fn.resolve(scope, { args, lazy }));
 };
 exports.resolveArgs = resolveArgs;

package/cjm/token/ClassToken.js

@@ -6,7 +6,7 @@ class ClassToken extends InjectionToken_1.InjectionToken {
     target;
     _getArgsFn;
     _isLazy;
-    constructor(target, { getArgsFn = () => [], isLazy = false } = {}) {
+    constructor(target, { getArgsFn = InjectionToken_1.forwardArgs, isLazy = false } = {}) {
         super();
         this.target = target;
         this._getArgsFn = getArgsFn;

package/cjm/token/FunctionToken.js

@@ -6,7 +6,7 @@ class FunctionToken extends InjectionToken_1.InjectionToken {
     fn;
     _getArgsFn;
     _isLazy;
-    constructor(fn, { getArgsFn = (_, { args = [] } = {}) => args, isLazy = false } = {}) {
+    constructor(fn, { getArgsFn = InjectionToken_1.forwardArgs, isLazy = false } = {}) {
         super();
         this.fn = fn;
         this._getArgsFn = getArgsFn;

package/cjm/token/GroupAliasToken.js

@@ -6,7 +6,7 @@ class GroupAliasToken extends InjectionToken_1.InjectionToken {
     token;
     _getArgsFn;
     _isLazy;
-    constructor(token, { getArgsFn = () => [], isLazy = false } = {}) {
+    constructor(token, { getArgsFn = InjectionToken_1.forwardArgs, isLazy = false } = {}) {
         super();
         this.token = token;
         this._getArgsFn = getArgsFn;

package/cjm/token/InjectionToken.js

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.InjectionToken = void 0;
+exports.InjectionToken = exports.forwardArgs = void 0;
 exports.isInjectionToken = isInjectionToken;
 const basic_1 = require("../utils/basic");
+const forwardArgs = (_, { args = [] } = {}) => args;
+exports.forwardArgs = forwardArgs;
 class InjectionToken {
 }
 exports.InjectionToken = InjectionToken;

package/cjm/token/SingleAliasToken.js

@@ -6,7 +6,7 @@ class SingleAliasToken extends InjectionToken_1.InjectionToken {
     token;
     _getArgsFn;
     _isLazy;
-    constructor(token, { getArgsFn = () => [], isLazy = false } = {}) {
+    constructor(token, { getArgsFn = InjectionToken_1.forwardArgs, isLazy = false } = {}) {
         super();
         this.token = token;
         this._getArgsFn = getArgsFn;

package/cjm/token/SingleToken.js

@@ -6,7 +6,7 @@ class SingleToken extends InjectionToken_1.InjectionToken {
     token;
     _getArgsFn;
     _isLazy;
-    constructor(token, { getArgsFn = () => [], isLazy = false } = {}) {
+    constructor(token, { getArgsFn = InjectionToken_1.forwardArgs, isLazy = false } = {}) {
         super();
         this.token = token;
         this._getArgsFn = getArgsFn;

package/esm/injector/MetadataInjector.js

@@ -1,7 +1,7 @@
 import { Injector } from './IInjector.js';
 import { resolveConstructor } from '../metadata/target.js';
-import { getParamMeta, addParamMeta } from '../metadata/parameter.js';
-import { argToToken, toMappedToken } from '../token/toToken.js';
+import { addParamMeta, getParamMeta } from '../metadata/parameter.js';
+import { toMappedToken } from '../token/toToken.js';
 export class MetadataInjector extends Injector {
     createInstance(scope, Target, { args: deps = [] } = {}) {
         const args = resolveArgs(Target)(scope, { args: deps });
@@ -19,5 +19,5 @@ export const arg = (index) => argsFn((value, i) => i === index);
 export const args = (c, { args = [] }) => args;
 export const resolveArgs = (target, methodName) => {
     const tokens = getParamMeta(hookMetaKey(methodName), target);
-    return (scope, { args = [], lazy }) => tokens.map((fn) => fn.resolve(scope, { args: args.map(argToToken).map((t) => t.resolve(scope)), lazy }));
+    return (scope, { args = [], lazy }) => tokens.map((fn) => fn.resolve(scope, { args, lazy }));
 };

package/esm/token/ClassToken.js

@@ -1,9 +1,9 @@
-import { InjectionToken } from './InjectionToken.js';
+import { forwardArgs, InjectionToken } from './InjectionToken.js';
 export class ClassToken extends InjectionToken {
     target;
     _getArgsFn;
     _isLazy;
-    constructor(target, { getArgsFn = () => [], isLazy = false } = {}) {
+    constructor(target, { getArgsFn = forwardArgs, isLazy = false } = {}) {
         super();
         this.target = target;
         this._getArgsFn = getArgsFn;

package/esm/token/FunctionToken.js

@@ -1,9 +1,9 @@
-import { InjectionToken } from './InjectionToken.js';
+import { forwardArgs, InjectionToken } from './InjectionToken.js';
 export class FunctionToken extends InjectionToken {
     fn;
     _getArgsFn;
     _isLazy;
-    constructor(fn, { getArgsFn = (_, { args = [] } = {}) => args, isLazy = false } = {}) {
+    constructor(fn, { getArgsFn = forwardArgs, isLazy = false } = {}) {
         super();
         this.fn = fn;
         this._getArgsFn = getArgsFn;

package/esm/token/GroupAliasToken.js

@@ -1,9 +1,9 @@
-import { InjectionToken } from './InjectionToken.js';
+import { forwardArgs, InjectionToken } from './InjectionToken.js';
 export class GroupAliasToken extends InjectionToken {
     token;
     _getArgsFn;
     _isLazy;
-    constructor(token, { getArgsFn = () => [], isLazy = false } = {}) {
+    constructor(token, { getArgsFn = forwardArgs, isLazy = false } = {}) {
         super();
         this.token = token;
         this._getArgsFn = getArgsFn;

package/esm/token/InjectionToken.js

@@ -1,4 +1,5 @@
 import { Is } from '../utils/basic.js';
+export const forwardArgs = (_, { args = [] } = {}) => args;
 export class InjectionToken {
 }
 export function isInjectionToken(target) {

package/esm/token/SingleAliasToken.js

@@ -1,9 +1,9 @@
-import { InjectionToken } from './InjectionToken.js';
+import { forwardArgs, InjectionToken } from './InjectionToken.js';
 export class SingleAliasToken extends InjectionToken {
     token;
     _getArgsFn;
     _isLazy;
-    constructor(token, { getArgsFn = () => [], isLazy = false } = {}) {
+    constructor(token, { getArgsFn = forwardArgs, isLazy = false } = {}) {
         super();
         this.token = token;
         this._getArgsFn = getArgsFn;

package/esm/token/SingleToken.js

@@ -1,9 +1,9 @@
-import { InjectionToken } from './InjectionToken.js';
+import { forwardArgs, InjectionToken } from './InjectionToken.js';
 export class SingleToken extends InjectionToken {
     token;
     _getArgsFn;
     _isLazy;
-    constructor(token, { getArgsFn = () => [], isLazy = false } = {}) {
+    constructor(token, { getArgsFn = forwardArgs, isLazy = false } = {}) {
         super();
         this.token = token;
         this._getArgsFn = getArgsFn;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-ioc-container",
-  "version": "68.1.0",
+  "version": "69.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/token/InjectionToken.d.ts

@@ -1,5 +1,6 @@
 import { type IContainer } from '../container/IContainer.js';
-import { ProviderOptions } from '../provider/IProvider.js';
+import { ArgsFn, ProviderOptions } from '../provider/IProvider.js';
+export declare const forwardArgs: ArgsFn;
 export declare abstract class InjectionToken<T = any> {
     abstract resolve(s: IContainer, options?: ProviderOptions): T;
     abstract args(...deps: unknown[]): InjectionToken<T>;