@zudojs/container 1.1.2 → 1.2.0

package/README.md

@@ -47,6 +47,21 @@ container.registerFactory(API, (db) => new Api(db), [DB]); // deps via inject li
 container.registerExisting("db-alias", DB); // alias to another token
 ```
 
+A factory's parameters are typed from its `inject` list, in order: with
+`DB = createToken<Db>("Db")`, `(db) => new Api(db)` receives `db: Db`, and a
+factory whose parameters do not match the tokens is a compile error. Class
+tokens type the same way; plain string and symbol tokens give `unknown`.
+`factoryProvider(factory, inject)` and `provideFactory(token, factory,
+inject)` infer the same way.
+
+```typescript
+container.registerFactory(
+  REPORT,
+  (db, clock) => new Report(db, clock), // db: Db, clock: Clock
+  [DB, Clock],
+);
+```
+
 ## Tokens
 
 Tokens can be strings, symbols, classes, or `InjectionToken`s from
@@ -58,6 +73,9 @@ Tokens can be strings, symbols, classes, or `InjectionToken`s from
 - `createGlobalToken(key)` uses `Symbol.for(key)`: any other call with the
   same key anywhere in the process yields the **same** token. That is by
   design for cross-package sharing; namespace your keys (e.g. `"myapp:db"`).
+- Error messages and default registration names show a symbol token by its
+  description: `createToken<Db>("Database")` appears as `Database`, not
+  `Symbol(Database)` (`describeToken(token)` returns the same string).
 
 ## Lifetimes (`scope` option)
 
@@ -185,7 +203,13 @@ const container = createContainer({
   registers it on the fly as `TRANSIENT`. When registrations are frozen the
   class is instantiated _ephemerally_ without being registered. Set to
   `false` to require explicit registration (`canResolve`/`resolveOptional`
-  respect this).
+  respect this). Only a class whose constructor declares no required
+  parameters (`Class.length === 0`) is auto-registered: auto-registration
+  has no inject list, so `resolve(NeedsDep)` for
+  `constructor(dep: Dep)` throws `RegistrationNotFoundError` naming the
+  class and telling you to register it with an `inject` list, instead of
+  building it with `dep = undefined`. Parameters with defaults do not
+  count.
 - `detectCircularDependencies` — circular chains throw
   `CircularDependencyError` with the full chain. When disabled,
   `maxResolutionDepth` still stops runaway recursion.

package/dist/containerCore/containerCore.core.d.ts

@@ -12,7 +12,7 @@
  * - TRANSIENT instances are never cached and never tracked — callers own
  *   their disposal.
  */
-import type { ContainerProvider, ProviderToken } from "../containerProvider/containerProvider.core.js";
+import type { ContainerProvider, InjectedFactory, ProviderToken } from "../containerProvider/containerProvider.core.js";
 import type { ContainerRegistration, CreateRegistrationOptions, RegistrationToken, ResolvedTokens } from "../containerRegistration/containerRegistration.core.js";
 import type { ResolutionCache, ResolutionResult } from "../containerResolution/containerResolution.type.js";
 import type { ContainerOptions, ResolvedContainerOptions } from "../containerOptions/containerOptions.type.js";
@@ -51,7 +51,14 @@ export declare class Container implements ContainerLike {
      * any other lifetime would be misleading.
      */
     registerValue<T>(token: RegistrationToken<T>, value: T, options?: CreateRegistrationOptions): ContainerRegistration<T>;
-    registerFactory<T>(token: RegistrationToken<T>, factory: (...deps: unknown[]) => T, inject?: readonly ProviderToken[], options?: CreateRegistrationOptions): ContainerRegistration<T>;
+    /**
+     * Registers a factory. Its parameters are typed from the `inject` tokens,
+     * in order: `registerFactory(API, (db) => new Api(db), [DB])` types `db`
+     * as `Db` when `DB` is a `createToken<Db>()` or class token, and rejects a
+     * factory whose parameters do not match. String/symbol tokens give
+     * `unknown`.
+     */
+    registerFactory<T, const Deps extends readonly ProviderToken[] = readonly []>(token: RegistrationToken<T>, factory: InjectedFactory<T, Deps>, inject?: Deps, options?: CreateRegistrationOptions): ContainerRegistration<T>;
     registerExisting<T>(token: RegistrationToken<T>, existing: ProviderToken<T>, options?: CreateRegistrationOptions): ContainerRegistration<T>;
     /**
      * Resolves a dependency at the container root.

package/dist/containerCore/containerCore.core.js

@@ -87,6 +87,13 @@ export class Container {
             scope: Scope.SINGLETON,
         });
     }
+    /**
+     * Registers a factory. Its parameters are typed from the `inject` tokens,
+     * in order: `registerFactory(API, (db) => new Api(db), [DB])` types `db`
+     * as `Db` when `DB` is a `createToken<Db>()` or class token, and rejects a
+     * factory whose parameters do not match. String/symbol tokens give
+     * `unknown`.
+     */
     registerFactory(token, factory, inject = [], options = {}) {
         return this.register(token, factoryProvider(factory, inject), options);
     }

package/dist/containerProvider/containerProvider.core.d.ts

@@ -4,6 +4,17 @@
  */
 import type { Constructor, InjectionToken, Token } from "../containerToken/containerToken.type.js";
 export type ProviderToken<T = unknown> = Token<T> | InjectionToken<T>;
+/**
+ * The parameter list a factory receives for an `inject` list: each token is
+ * mapped to the type it resolves to, so `[DB, Clock]` gives `[Db, Clock]`.
+ * Untyped string/symbol tokens map to `unknown`, and a non-tuple
+ * `readonly ProviderToken[]` gives `unknown[]`, as before.
+ */
+export type InjectedDependencies<Deps extends readonly ProviderToken[]> = {
+    -readonly [K in keyof Deps]: Deps[K] extends ProviderToken<infer U> ? U : never;
+};
+/** A factory whose parameters are typed from its `inject` list. */
+export type InjectedFactory<T, Deps extends readonly ProviderToken[]> = (...dependencies: InjectedDependencies<Deps>) => T;
 export interface ClassProvider<T> {
     readonly useClass: Constructor<T>;
     /**
@@ -55,11 +66,19 @@ export declare function hasInjectedDependencies<T = unknown>(provider: Provider<
     readonly inject: readonly ProviderToken[];
 };
 export declare function classProvider<T>(useClass: Constructor<T>, inject?: readonly ProviderToken[]): ClassProvider<T>;
-export declare function factoryProvider<T>(useFactory: (...dependencies: unknown[]) => T, inject?: readonly ProviderToken[]): FactoryProvider<T>;
+/**
+ * Builds a factory provider. The factory's parameters are inferred from the
+ * `inject` tokens, in order.
+ */
+export declare function factoryProvider<T, const Deps extends readonly ProviderToken[] = readonly []>(useFactory: InjectedFactory<T, Deps>, inject?: Deps): FactoryProvider<T>;
 export declare function valueProvider<T>(useValue: T): ValueProvider<T>;
 export declare function existingProvider<T>(useExisting: ProviderToken<T>): ExistingProvider<T>;
 export declare function provideClass<T>(provide: ProviderToken<T>, useClass: Constructor<T>, inject?: readonly ProviderToken[]): ClassRegistration<T>;
-export declare function provideFactory<T>(provide: ProviderToken<T>, useFactory: (...dependencies: unknown[]) => T, inject?: readonly ProviderToken[]): FactoryRegistration<T>;
+/**
+ * Builds a factory registration. The factory's parameters are inferred from
+ * the `inject` tokens, in order.
+ */
+export declare function provideFactory<T, const Deps extends readonly ProviderToken[] = readonly []>(provide: ProviderToken<T>, useFactory: InjectedFactory<T, Deps>, inject?: Deps): FactoryRegistration<T>;
 export declare function provideValue<T>(provide: ProviderToken<T>, useValue: T): ValueRegistration<T>;
 export declare function provideExisting<T>(provide: ProviderToken<T>, useExisting: ProviderToken<T>): ExistingRegistration<T>;
 export declare function getProviderToken<T>(provider: ContainerProvider<T>): ProviderToken<T> | undefined;

package/dist/containerProvider/containerProvider.core.js

@@ -25,8 +25,15 @@ export function hasInjectedDependencies(provider) {
 export function classProvider(useClass, inject = []) {
     return Object.freeze({ useClass, inject: Object.freeze([...inject]) });
 }
+/**
+ * Builds a factory provider. The factory's parameters are inferred from the
+ * `inject` tokens, in order.
+ */
 export function factoryProvider(useFactory, inject = []) {
-    return Object.freeze({ useFactory, inject: Object.freeze([...inject]) });
+    return Object.freeze({
+        useFactory: useFactory,
+        inject: Object.freeze([...inject]),
+    });
 }
 export function valueProvider(useValue) {
     return Object.freeze({ useValue });
@@ -41,10 +48,14 @@ export function provideClass(provide, useClass, inject = []) {
         inject: Object.freeze([...inject]),
     });
 }
+/**
+ * Builds a factory registration. The factory's parameters are inferred from
+ * the `inject` tokens, in order.
+ */
 export function provideFactory(provide, useFactory, inject = []) {
     return Object.freeze({
         provide,
-        useFactory,
+        useFactory: useFactory,
         inject: Object.freeze([...inject]),
     });
 }

package/dist/containerResolution/containerResolution.autoRegister.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @zudojs/container/containerResolution/containerResolution.autoRegister
+ *
+ * Guards for `autoRegisterClasses`: resolving an unregistered class builds
+ * it with no arguments, which is only correct for a constructor that
+ * declares none.
+ */
+/**
+ * Whether an unregistered token may be auto-registered: a class whose
+ * constructor declares no required parameters (`Class.length === 0`).
+ *
+ * Parameters with a default value do not count, so
+ * `constructor(value = 7)` still qualifies.
+ */
+export declare function isAutoRegistrable(token: unknown): boolean;
+/**
+ * Throws when a class cannot be auto-registered because its constructor
+ * declares parameters. Auto-registration has no inject list, so building
+ * it would pass `undefined` for every dependency.
+ *
+ * @throws {RegistrationNotFoundError} naming the class and how to
+ *   register it.
+ */
+export declare function assertAutoRegistrable(token: {
+    readonly length: number;
+}): void;
+//# sourceMappingURL=containerResolution.autoRegister.d.ts.map

package/dist/containerResolution/containerResolution.autoRegister.js

@@ -0,0 +1,40 @@
+/**
+ * @zudojs/container/containerResolution/containerResolution.autoRegister
+ *
+ * Guards for `autoRegisterClasses`: resolving an unregistered class builds
+ * it with no arguments, which is only correct for a constructor that
+ * declares none.
+ */
+import { RegistrationNotFoundError } from "@zudojs/errors";
+import { describeToken } from "../containerToken/containerToken.type.js";
+/**
+ * Whether an unregistered token may be auto-registered: a class whose
+ * constructor declares no required parameters (`Class.length === 0`).
+ *
+ * Parameters with a default value do not count, so
+ * `constructor(value = 7)` still qualifies.
+ */
+export function isAutoRegistrable(token) {
+    return typeof token === "function" && token.length === 0;
+}
+/**
+ * Throws when a class cannot be auto-registered because its constructor
+ * declares parameters. Auto-registration has no inject list, so building
+ * it would pass `undefined` for every dependency.
+ *
+ * @throws {RegistrationNotFoundError} naming the class and how to
+ *   register it.
+ */
+export function assertAutoRegistrable(token) {
+    if (isAutoRegistrable(token))
+        return;
+    const name = describeToken(token);
+    const count = token.length;
+    throw new RegistrationNotFoundError(name, `Cannot auto-register class "${name}": its constructor declares ` +
+        `${count} parameter${count === 1 ? "" : "s"} and no inject list is ` +
+        `registered, so it would be built with undefined dependencies. ` +
+        `Register it with container.registerClass(${name}, ${name}, ` +
+        `{ inject: [/* one token per parameter */] }) or ` +
+        `container.registerFactory(${name}, (...deps) => new ${name}(...deps), [/* tokens */]).`);
+}
+//# sourceMappingURL=containerResolution.autoRegister.js.map

package/dist/containerResolution/containerResolution.core.js

@@ -35,6 +35,7 @@ import { unwrapToken } from "../containerToken/containerToken.type.js";
 import { CircularDependencyError, ContainerError, ProviderResolutionError, RegistrationNotFoundError, } from "@zudojs/errors";
 import { AsyncProviderError, CaptiveDependencyError, DependencyResolutionError, MaxResolutionDepthError, ScopedResolutionError, } from "./containerResolution.error.js";
 import { describeToken } from "../containerToken/containerToken.type.js";
+import { assertAutoRegistrable, isAutoRegistrable, } from "./containerResolution.autoRegister.js";
 import { DependentIndex } from "./containerResolution.dependents.js";
 /**
  * Scope cache that falls back to its parent scope's cache for lookups while
@@ -124,6 +125,7 @@ export class ContainerResolver {
         let registration = this.registry.get(token);
         if (!registration) {
             if (state.autoRegisterClasses && typeof token === "function") {
+                assertAutoRegistrable(token);
                 if (state.allowRegistration) {
                     registration = this.registry.register(token, { useClass: token }, { scope: Scope.TRANSIENT });
                 }
@@ -214,7 +216,7 @@ export class ContainerResolver {
             if (isExistingProvider(provider)) {
                 const target = unwrapToken(provider.useExisting);
                 if (!this.registry.has(target) &&
-                    !(state.autoRegisterClasses && typeof target === "function")) {
+                    !(state.autoRegisterClasses && isAutoRegistrable(target))) {
                     throw new ContainerError(`useExisting target "${describeToken(target)}" for token ` +
                         `"${describeToken(token)}" is not registered.`, { token: describeToken(token) });
                 }
@@ -283,7 +285,7 @@ export class ContainerResolver {
     }
     canResolve(token, autoRegisterClasses = true) {
         const t = unwrapToken(token);
-        return (this.registry.has(t) || (autoRegisterClasses && typeof t === "function"));
+        return (this.registry.has(t) || (autoRegisterClasses && isAutoRegistrable(t)));
     }
     handleRegistryChange(event) {
         switch (event.operation) {

package/dist/containerToken/containerToken.type.d.ts

@@ -44,5 +44,13 @@ export declare function isInjectionToken<T = unknown>(value: unknown): value is
 export declare function isConstructorToken<T = unknown>(token: Token<T>): token is Constructor<T>;
 export declare function isSymbolToken<T = unknown>(token: Token<T>): token is symbol;
 export declare function isStringToken<T = unknown>(token: Token<T>): token is string;
+/**
+ * Returns a human-readable name for a token, used in error messages and as
+ * the default registration name.
+ *
+ * A symbol token (including every `createToken`/`createGlobalToken` token)
+ * is shown by its description, so errors read `MissingService` rather than
+ * `Symbol(MissingService)`. A symbol without a description is `Symbol()`.
+ */
 export declare function describeToken<T>(token: Token<T> | InjectionToken<T>): string;
 //# sourceMappingURL=containerToken.type.d.ts.map

package/dist/containerToken/containerToken.type.js

@@ -48,14 +48,20 @@ export function isSymbolToken(token) {
 export function isStringToken(token) {
     return typeof token === "string";
 }
+/**
+ * Returns a human-readable name for a token, used in error messages and as
+ * the default registration name.
+ *
+ * A symbol token (including every `createToken`/`createGlobalToken` token)
+ * is shown by its description, so errors read `MissingService` rather than
+ * `Symbol(MissingService)`. A symbol without a description is `Symbol()`.
+ */
 export function describeToken(token) {
     const resolved = unwrapToken(token);
     if (typeof resolved === "string")
         return resolved;
     if (typeof resolved === "symbol")
-        return resolved.description
-            ? `Symbol(${resolved.description})`
-            : "Symbol()";
+        return resolved.description ? resolved.description : "Symbol()";
     if (typeof resolved === "function")
         return resolved.name || "AnonymousConstructor";
     return "UnknownToken";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/container",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "Token-based dependency injection container for managing application dependencies and service lifetimes.",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,11 +18,11 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.2.0"
+    "@zudojs/errors": "1.3.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.1"
   },
   "license": "MIT",
   "author": {
@@ -41,7 +41,7 @@
     "dependency-injection",
     "container"
   ],
-  "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "homepage": "https://zudojs.oyinlola.site/docs/packages-container",
   "bugs": {
     "url": "https://github.com/oyinlola-tech/zudo/issues"
   },