ts-ioc-container 72.1.0 → 72.2.0

package/lib/utils/errorHandler.ts

@@ -0,0 +1,34 @@
+import { resolveConstructor } from '../metadata/target';
+
+/** Receives the error with the class and method it came from. */
+export type HandleErrorParams = (error: unknown, context: { target: string; method: string }) => void;
+
+/** Method decorator: routes a rejection of the async method to `errorHandler` instead of throwing. */
+export const handleAsyncError =
+  (errorHandler: HandleErrorParams): MethodDecorator =>
+  (target, propertyKey, descriptor: PropertyDescriptor) => {
+    const originalMethod = descriptor.value;
+    descriptor.value = async function (...args: unknown[]) {
+      try {
+        return await originalMethod.apply(this, args);
+      } catch (e) {
+        errorHandler(e, { target: resolveConstructor(target).name, method: propertyKey as string });
+      }
+    };
+    return descriptor;
+  };
+
+/** Method decorator: routes a throw of the method to `errorHandler` instead of throwing. */
+export const handleError =
+  (errorHandler: HandleErrorParams): MethodDecorator =>
+  (target, propertyKey, descriptor: PropertyDescriptor) => {
+    const originalMethod = descriptor.value;
+    descriptor.value = function (...args: unknown[]) {
+      try {
+        return originalMethod.apply(this, args);
+      } catch (e) {
+        errorHandler(e, { target: resolveConstructor(target).name, method: propertyKey as string });
+      }
+    };
+    return descriptor;
+  };

package/lib/utils/fp.ts

@@ -0,0 +1,86 @@
+/** A one-argument transform. */
+export type MapFn<A, B = A> = (value: A) => B;
+
+// Overloads for fp function to support up to 10 transformations
+/**
+ * Composes functions left to right. With `by(...)` it maps an injected value.
+ *
+ * @example
+ * @inject(pipe(by(ConfigToken), (config) => config.apiUrl))
+ */
+export function pipe<A>(fn1: MapFn<A>): MapFn<A>;
+export function pipe<A, B>(fn1: MapFn<A, B>): MapFn<A, B>;
+export function pipe<A, B, C>(fn1: MapFn<A, B>, fn2: MapFn<B, C>): MapFn<A, C>;
+export function pipe<A, B, C, D>(fn1: MapFn<A, B>, fn2: MapFn<B, C>, fn3: MapFn<C, D>): MapFn<A, D>;
+export function pipe<A, B, C, D, E>(
+  fn1: MapFn<A, B>,
+  fn2: MapFn<B, C>,
+  fn3: MapFn<C, D>,
+  fn4: MapFn<D, E>,
+): MapFn<A, E>;
+export function pipe<A, B, C, D, E, F>(
+  fn1: MapFn<A, B>,
+  fn2: MapFn<B, C>,
+  fn3: MapFn<C, D>,
+  fn4: MapFn<D, E>,
+  fn5: MapFn<E, F>,
+): MapFn<A, F>;
+export function pipe<A, B, C, D, E, F, G>(
+  fn1: MapFn<A, B>,
+  fn2: MapFn<B, C>,
+  fn3: MapFn<C, D>,
+  fn4: MapFn<D, E>,
+  fn5: MapFn<E, F>,
+  fn6: MapFn<F, G>,
+): MapFn<A, G>;
+export function pipe<A, B, C, D, E, F, G, H>(
+  fn1: MapFn<A, B>,
+  fn2: MapFn<B, C>,
+  fn3: MapFn<C, D>,
+  fn4: MapFn<D, E>,
+  fn5: MapFn<E, F>,
+  fn6: MapFn<F, G>,
+  fn7: MapFn<G, H>,
+): MapFn<A, H>;
+export function pipe<A, B, C, D, E, F, G, H, I>(
+  fn1: MapFn<A, B>,
+  fn2: MapFn<B, C>,
+  fn3: MapFn<C, D>,
+  fn4: MapFn<D, E>,
+  fn5: MapFn<E, F>,
+  fn6: MapFn<F, G>,
+  fn7: MapFn<G, H>,
+  fn8: MapFn<H, I>,
+): MapFn<A, I>;
+export function pipe<A, B, C, D, E, F, G, H, I, J>(
+  fn1: MapFn<A, B>,
+  fn2: MapFn<B, C>,
+  fn3: MapFn<C, D>,
+  fn4: MapFn<D, E>,
+  fn5: MapFn<E, F>,
+  fn6: MapFn<F, G>,
+  fn7: MapFn<G, H>,
+  fn8: MapFn<H, I>,
+  fn9: MapFn<I, J>,
+): MapFn<A, J>;
+export function pipe<A, B, C, D, E, F, G, H, I, J, K>(
+  fn1: MapFn<A, B>,
+  fn2: MapFn<B, C>,
+  fn3: MapFn<C, D>,
+  fn4: MapFn<D, E>,
+  fn5: MapFn<E, F>,
+  fn6: MapFn<F, G>,
+  fn7: MapFn<G, H>,
+  fn8: MapFn<H, I>,
+  fn9: MapFn<I, J>,
+  fn10: MapFn<J, K>,
+): MapFn<A, K>;
+// Fallback for cases where pipes are used with spreads or variable length (same type)
+
+export function pipe<T>(...mappers: MapFn<T>[]): MapFn<T>;
+// Implementation
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function pipe(...mappers: MapFn<any, any>[]): MapFn<any, any> {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return (value: any) => mappers.reduce((acc, current) => current(acc), value);
+}

package/lib/utils/getConstructorChain.ts

@@ -0,0 +1,17 @@
+/**
+ * Walks a constructor's prototype chain, most-derived first, and collects each
+ * class in it: `[Derived, Base, ...]`, stopping before `Function.prototype`.
+ *
+ * Reading own metadata off each entry in turn is how a class inherits what its
+ * ancestors declared — `Reflect.getOwnMetadata` never looks up the chain itself.
+ * Anything which is not a function yields an empty chain.
+ */
+export const getConstructorChain = (ctor: unknown): object[] => {
+  const chain: object[] = [];
+  let current = ctor;
+  while (typeof current === 'function' && current !== Function.prototype) {
+    chain.push(current);
+    current = Object.getPrototypeOf(current);
+  }
+  return chain;
+};

package/lib/utils/memoize.ts

@@ -0,0 +1,24 @@
+/**
+ * Wraps a two-argument function so each `(target, key)` pair is computed once
+ * and reused. `target` is held weakly, so memoizing against a class or an
+ * instance keeps nothing alive.
+ *
+ * ```typescript
+ * const hooksOf = memoize((Target: constructor<unknown>, key: string | symbol) => merge(Target, key));
+ * ```
+ */
+export const memoize = <T extends object, K, R>(fn: (target: T, key: K) => R): ((target: T, key: K) => R) => {
+  const cache = new WeakMap<T, Map<K, R>>();
+
+  return (target, key) => {
+    let byKey = cache.get(target);
+    if (!byKey) {
+      byKey = new Map();
+      cache.set(target, byKey);
+    }
+    if (!byKey.has(key)) {
+      byKey.set(key, fn(target, key));
+    }
+    return byKey.get(key) as R;
+  };
+};

package/lib/utils/once.ts

@@ -0,0 +1,24 @@
+type RepeatOptions = {
+  index: number;
+  args: unknown[];
+};
+
+/** Method decorator: runs the method once per instance and returns the cached result afterwards. */
+export const once =
+  ({ onRepeat }: { onRepeat?: (options: RepeatOptions) => void } = {}): MethodDecorator =>
+  (target, propertyKey, descriptor: PropertyDescriptor) => {
+    const originalMethod = descriptor.value;
+    const cacheMap = new WeakMap<object, unknown>();
+    let index = 0;
+    descriptor.value = function (...args: unknown[]) {
+      index++;
+      if (cacheMap.has(this)) {
+        onRepeat?.({ index: index - 1, args });
+        return cacheMap.get(this);
+      }
+      const result = originalMethod.apply(this, args);
+      cacheMap.set(this, result);
+      return result;
+    };
+    return descriptor;
+  };

package/lib/utils/shallowCache.ts

@@ -0,0 +1,22 @@
+/** Method decorator: caches results per instance by the key `getKeyByArgs` returns. */
+export const shallowCache =
+  (getKeyByArgs: (...args: unknown[]) => unknown): MethodDecorator =>
+  (target, propertyKey, descriptor: PropertyDescriptor) => {
+    const originalMethod = descriptor.value;
+    const cacheMap = new WeakMap<object, Map<unknown, unknown>>();
+    descriptor.value = function (...args: unknown[]) {
+      let cache = cacheMap.get(this);
+      if (cache === undefined) {
+        cache = new Map();
+        cacheMap.set(this, cache);
+      }
+      const key = getKeyByArgs(...args);
+      if (cache.has(key)) {
+        return cache.get(key);
+      }
+      const result = originalMethod.apply(this, args);
+      cache.set(key, result);
+      return result;
+    };
+    return descriptor;
+  };

package/lib/utils/task.ts

@@ -0,0 +1,33 @@
+/**
+ * A unit of work which may or may not go async: the sync-until-async shape the
+ * hook machinery is built on (ADR 0013).
+ */
+export type Task = () => void | Promise<void>;
+
+/**
+ * Runs `tasks` in order, staying synchronous until one returns a promise and
+ * awaiting the rest from that point. `undefined` when none went async.
+ */
+export const runInOrder = (tasks: Task[], from = 0): void | Promise<void> => {
+  for (let i = from; i < tasks.length; i++) {
+    const result = tasks[i]();
+    if (result instanceof Promise) {
+      return result.then(() => runInOrder(tasks, i + 1));
+    }
+  }
+};
+
+/**
+ * Starts every task at once. Settles once all have; `undefined` when none went
+ * async, so a fully synchronous run hands back no promise.
+ */
+export const runAtOnce = (tasks: Task[]): void | Promise<void> => {
+  const pending: Promise<void>[] = [];
+  for (const task of tasks) {
+    const result = task();
+    if (result instanceof Promise) {
+      pending.push(result);
+    }
+  }
+  return pending.length > 0 ? Promise.all(pending).then(() => undefined) : undefined;
+};

package/lib/utils/throttle.ts

@@ -0,0 +1,17 @@
+/** Method decorator: ignores calls within `ms` of the last accepted one (per instance). */
+export const throttle =
+  (ms: number): MethodDecorator =>
+  (target, propertyKey, descriptor: PropertyDescriptor) => {
+    const originalMethod = descriptor.value;
+    const lastCalledMap = new WeakMap<object, number>();
+    descriptor.value = function (...args: unknown[]) {
+      const now = Date.now();
+      const lastCalled = lastCalledMap.get(this) ?? -Infinity;
+      if (now - lastCalled < ms) {
+        return undefined;
+      }
+      lastCalledMap.set(this, now);
+      return originalMethod.apply(this, args);
+    };
+    return descriptor;
+  };

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "ts-ioc-container",
-  "version": "72.1.0",
+  "version": "72.2.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",
     "registry": "https://registry.npmjs.org/"
   },
   "author": "ibabkin <igba14@gmail.com>",
-  "homepage": "https://igorbabkin.github.io/ts-ioc-container",
+  "homepage": "https://github.com/IgorBabkin/ts-ioc-container/tree/main/packages/ts-ioc-container#readme",
   "license": "ISC",
   "sideEffects": false,
   "main": "cjm/index.js",
@@ -54,7 +54,9 @@
   "files": [
     "cjm/**/*",
     "esm/**/*",
-    "typings/**/*"
+    "typings/**/*",
+    "lib/**/*",
+    "AGENTS.md"
   ],
   "repository": {
     "type": "git",

package/typings/ExecutionContext.d.ts

@@ -1,4 +1,6 @@
 import type { IContainer } from './container/IContainer.js';
+/** General execution context passed to callbacks that run within a scope. */
 export interface ExecutionContext {
     scope: IContainer;
 }
+//# sourceMappingURL=ExecutionContext.d.ts.map

package/typings/ExecutionContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExecutionContext.d.ts","sourceRoot":"","sources":["../lib/ExecutionContext.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEzD,6EAA6E;AAC7E,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,UAAU,CAAC;CACnB"}

package/typings/container/AliasMap.d.ts

@@ -6,3 +6,4 @@ export declare class AliasMap {
     setAliasesByKey(key: DependencyKey, aliases: DependencyKey[]): void;
     destroy(): void;
 }
+//# sourceMappingURL=AliasMap.d.ts.map

package/typings/container/AliasMap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AliasMap.d.ts","sourceRoot":"","sources":["../../lib/container/AliasMap.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,MAAM,MAAM,KAAK,GAAG,aAAa,CAAC;AAElC,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAwC;IAEtE,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,aAAa,EAAE;IAIrD,eAAe,CAAC,GAAG,EAAE,aAAa,EAAE,OAAO,EAAE,aAAa,EAAE,GAAG,IAAI;IAenE,OAAO,IAAI,IAAI;CAGhB"}

package/typings/container/AutoResolveModule.d.ts

@@ -1,6 +1,22 @@
 import { type AutoResolveOptions, type IContainer, type IContainerModule } from './IContainer.js';
+/**
+ * Enables eager resolution of providers marked with the `autoResolve()` pipe.
+ *
+ * Every scope created after this module is applied resolves its own
+ * auto-resolvable providers as part of `createScope`, so the instances exist
+ * before anyone asks for them. Child scopes inherit the behaviour, so a single
+ * `useModule` call on the root covers the whole scope tree.
+ *
+ * `options.args` are forwarded to every eagerly resolved provider of every such
+ * scope. Pass a per-scope value by calling `scope.autoResolve({ args })`
+ * directly instead.
+ *
+ * The container the module is applied to is not a created scope — call
+ * `container.autoResolve()` explicitly to eagerly resolve its own providers.
+ */
 export declare class AutoResolveModule implements IContainerModule {
     private readonly options;
     constructor(options?: AutoResolveOptions);
     applyTo(container: IContainer): void;
 }
+//# sourceMappingURL=AutoResolveModule.d.ts.map

package/typings/container/AutoResolveModule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AutoResolveModule.d.ts","sourceRoot":"","sources":["../../lib/container/AutoResolveModule.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,kBAAkB,EAAE,KAAK,UAAU,EAAE,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAE/F;;;;;;;;;;;;;;GAcG;AACH,qBAAa,iBAAkB,YAAW,gBAAgB;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,GAAE,kBAAuB;IAE7D,OAAO,CAAC,SAAS,EAAE,UAAU,GAAG,IAAI;CAGrC"}

package/typings/container/Container.d.ts

@@ -4,6 +4,22 @@ import { type IProvider } from '../provider/IProvider.js';
 import { type IRegistration } from '../registration/IRegistration.js';
 import { constructor, Instance } from '../utils/basic.js';
 import { type ITypedEvent } from '../utils/TypedEvent.js';
+/**
+ * A dependency injection scope. Each container is a node in a parent chain:
+ * a key not found here (or denied by `scopeAccess`) is resolved from the parent,
+ * and the root's parent is an {@link EmptyContainer} that throws
+ * `DependencyNotFoundError`. Child scopes come from `createScope({ tags })`,
+ * which copies the matching registrations into the child at that moment.
+ *
+ * @example
+ * const app = new Container({ tags: ['application'] })
+ *   .addRegistration(Registration.fromClass(Logger))
+ *   .addRegistration(Registration.fromValue(config).bindTo('Config'));
+ *
+ * const request = app.createScope({ tags: ['request'] });
+ * const logger = ILoggerToken.resolve(request);
+ * request.dispose();
+ */
 export declare class Container implements IContainer {
     isDisposed: boolean;
     private parent;
@@ -25,12 +41,40 @@ export declare class Container implements IContainer {
         parent?: IContainer;
         tags?: Tag[];
     });
+    /**
+     * @throws {ContainerDisposedError} when the container has already been disposed.
+     */
     register(key: DependencyKey, provider: IProvider, { aliases }?: RegisterOptions): this;
+    /**
+     * @throws {ContainerDisposedError} when the container has already been disposed.
+     * @throws {DependencyNotFoundError} when `target` cannot be resolved in this container or any parent scope.
+     */
     resolve<T>(target: constructor<T> | DependencyKey, { args, child, lazy }?: ResolveOneOptions): T;
+    /**
+     * @throws {ContainerDisposedError} when the container has already been disposed.
+     * @throws {DependencyNotFoundError} when a key registered under `alias` has no matching provider.
+     */
     resolveByAlias<T>(alias: DependencyKey, { args, child, lazy, excludedKeys }?: ResolveManyOptions): T[];
+    /**
+     * @throws {ContainerDisposedError} when the container has already been disposed.
+     * @throws {DependencyNotFoundError} when `alias` cannot be resolved in this container or any parent scope.
+     */
     resolveOneByAlias<T>(alias: DependencyKey, { args, child, lazy }?: ResolveOneOptions): T;
+    /**
+     * @throws {ContainerDisposedError} when the container has already been disposed.
+     */
     createScope({ tags }?: CreateScopeOptions): IContainer;
+    /**
+     * Eagerly resolves every provider of this scope which was marked with `autoResolve()`.
+     *
+     * `args` are forwarded to each of those providers, exactly as `resolve` forwards them.
+     *
+     * @throws {ContainerDisposedError} when the container has already been disposed.
+     */
     autoResolve({ args }?: AutoResolveOptions): this;
+    /**
+     * @throws {ContainerDisposedError} when the container has already been disposed.
+     */
     dispose(): void;
     addRegistration(registration: IRegistration): this;
     getRegistrations(): IRegistration[];
@@ -38,6 +82,15 @@ export declare class Container implements IContainer {
     hasRegistration(key: DependencyKey): boolean;
     addInstance(instance: Instance): void;
     getScopes(): IContainer[];
+    /**
+     * Whether this scope created `instance`.
+     *
+     * A proxy stands for the object behind it, so it is unwrapped before the
+     * lookup - the container tracks real instances, and a caller asking about a
+     * proxy is asking about its target. Resolving a lazy proxy's target is what
+     * makes that answer possible, so a still-unresolved lazy proxy is resolved
+     * here.
+     */
     hasInstance(instance: Instance): boolean;
     removeScope(child: IContainer): void;
     useModule(module: IContainerModule): this;
@@ -45,6 +98,13 @@ export declare class Container implements IContainer {
     getInstances(cascade?: boolean): Instance[];
     hasTag(tag: Tag): boolean;
     addTags(...tags: Tag[]): void;
+    /**
+     * @throws {ContainerDisposedError} when the container has already been disposed.
+     */
     private validateContainer;
+    /**
+     * @throws {DependencyNotFoundError} when no provider is registered under `key` in this container.
+     */
     private findProviderByKeyOrFail;
 }
+//# sourceMappingURL=Container.d.ts.map

package/typings/container/Container.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Container.d.ts","sourceRoot":"","sources":["../../lib/container/Container.ts"],"names":[],"mappings":"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"}

package/typings/container/EmptyContainer.d.ts

@@ -4,29 +4,80 @@ import { type IRegistration } from '../registration/IRegistration.js';
 import { type constructor, type Instance } from '../utils/basic.js';
 import { type IInjector } from '../injector/IInjector.js';
 import { type ITypedEvent } from '../utils/TypedEvent.js';
+/**
+ * Terminates the parent chain of every root {@link Container}: `resolve` throws
+ * `DependencyNotFoundError`, alias lookups return nothing, and every other
+ * method throws `MethodNotImplementedError`. You rarely use it directly.
+ */
 export declare class EmptyContainer implements IContainer {
+    /**
+     * @throws {MethodNotImplementedError} always — the empty container has no disposal state.
+     */
     get isDisposed(): boolean;
     addInstance(instance: Instance): void;
     getParent(): undefined;
     getScopes(): never[];
     getInstances(): never[];
     hasInstance(instance: Instance): boolean;
+    /**
+     * @throws {MethodNotImplementedError} always — the empty container cannot create scopes.
+     */
     createScope(): IContainer;
+    /**
+     * @throws {MethodNotImplementedError} always — the empty container constructs nothing, so it has no injector.
+     */
     getInjector(): IInjector;
+    /**
+     * @throws {MethodNotImplementedError} always — the empty container holds no providers to resolve.
+     */
     autoResolve(options?: AutoResolveOptions): this;
+    /**
+     * @throws {MethodNotImplementedError} always — the empty container cannot be disposed.
+     */
     dispose(): void;
+    /**
+     * @throws {MethodNotImplementedError} always — the empty container cannot hold registrations.
+     */
     register(key: DependencyKey, value: IProvider): this;
+    /**
+     * @throws {MethodNotImplementedError} always — the empty container has no tags.
+     */
     hasTag(tag: Tag): boolean;
+    /**
+     * @throws {MethodNotImplementedError} always — the empty container has no tags.
+     */
     addTags(...tags: Tag[]): void;
     getRegistrations(): never[];
     hasRegistration(key: DependencyKey): boolean;
     removeScope(): void;
+    /**
+     * @throws {MethodNotImplementedError} always — the empty container cannot use modules.
+     */
     useModule(module: IContainerModule): this;
+    /**
+     * @throws {MethodNotImplementedError} always — the empty container cannot hold registrations.
+     */
     addRegistration(registration: IRegistration): this;
+    /**
+     * @throws {DependencyNotFoundError} always — reaching the empty container means `key` was not found in any scope.
+     */
     resolve<T>(key: constructor<T> | DependencyKey, options?: ResolveOneOptions): T;
     resolveByAlias<T>(alias: DependencyKey, options?: ResolveManyOptions): T[];
+    /**
+     * @throws {DependencyNotFoundError} always — reaching the empty container means `alias` was not found in any scope.
+     */
     resolveOneByAlias<T>(alias: DependencyKey, options?: ResolveOneOptions): T;
+    /**
+     * @throws {MethodNotImplementedError} always — the empty container cannot hold hooks.
+     */
     get scopeCreated(): ITypedEvent<[IContainer]>;
+    /**
+     * @throws {MethodNotImplementedError} always — the empty container cannot hold hooks.
+     */
     get scopeDisposed(): ITypedEvent<[IContainer]>;
+    /**
+     * @throws {MethodNotImplementedError} always — the empty container cannot hold hooks.
+     */
     get registered(): ITypedEvent<[IProvider, DependencyKey, IContainer]>;
 }
+//# sourceMappingURL=EmptyContainer.d.ts.map

package/typings/container/EmptyContainer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EmptyContainer.d.ts","sourceRoot":"","sources":["../../lib/container/EmptyContainer.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,GAAG,EACT,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACjE,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD;;;;GAIG;AACH,qBAAa,cAAe,YAAW,UAAU;IAC/C;;OAEG;IACH,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,WAAW,CAAC,QAAQ,EAAE,QAAQ;IAE9B,SAAS;IAIT,SAAS;IAIT,YAAY;IAIZ,WAAW,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO;IAIxC;;OAEG;IACH,WAAW,IAAI,UAAU;IAIzB;;OAEG;IACH,WAAW,IAAI,SAAS;IAIxB;;OAEG;IACH,WAAW,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,IAAI;IAI/C;;OAEG;IACH,OAAO,IAAI,IAAI;IAIf;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI;IAIpD;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO;IAIzB;;OAEG;IACH,OAAO,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI;IAI7B,gBAAgB;IAIhB,eAAe,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO;IAI5C,WAAW,IAAI,IAAI;IAEnB;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI;IAIzC;;OAEG;IACH,eAAe,CAAC,YAAY,EAAE,aAAa,GAAG,IAAI;IAIlD;;OAEG;IACH,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,aAAa,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,CAAC;IAQ/E,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,CAAC,EAAE;IAI1E;;OAEG;IACH,iBAAiB,CAAC,CAAC,EAAE,KAAK,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,CAAC;IAM1E;;OAEG;IACH,IAAI,YAAY,IAAI,WAAW,CAAC,CAAC,UAAU,CAAC,CAAC,CAE5C;IAED;;OAEG;IACH,IAAI,aAAa,IAAI,WAAW,CAAC,CAAC,UAAU,CAAC,CAAC,CAE7C;IAED;;OAEG;IACH,IAAI,UAAU,IAAI,WAAW,CAAC,CAAC,SAAS,EAAE,aAAa,EAAE,UAAU,CAAC,CAAC,CAEpE;CACF"}

package/typings/container/IContainer.d.ts

@@ -3,8 +3,11 @@ import { type IRegistration } from '../registration/IRegistration.js';
 import { IInjector, type WithArgs } from '../injector/IInjector.js';
 import { type constructor, Instance } from '../utils/basic.js';
 import { type ITypedEvent } from '../utils/TypedEvent.js';
+/** A registration key: a string or a symbol. */
 export type DependencyKey = string | symbol;
+/** Narrows `target` to a {@link DependencyKey}. */
 export declare function isDependencyKey(target: unknown): target is DependencyKey;
+/** A scope label (`'application'`, `'request'`, ...) matched by `scope(...)` rules. */
 export type Tag = string;
 type WithTags = {
     tags: Tag[];
@@ -15,47 +18,119 @@ type WithChild = {
 type WithExcludedKeys = {
     excludedKeys: DependencyKey[];
 };
+/** Something carrying tags: a scope or a token. */
 export interface Tagged {
     hasTag(tag: Tag): boolean;
     addTags(...tags: Tag[]): void;
 }
+/** Options of `resolve`: runtime `args`, `lazy`, and the invoking `child` scope. */
 export type ResolveOneOptions = ResolveOptions & Partial<WithChild>;
+/** Options of `resolveByAlias`: like {@link ResolveOneOptions}, plus keys to exclude. */
 export type ResolveManyOptions = ResolveOneOptions & Partial<WithExcludedKeys>;
+/** Something that resolves a key or a class. */
 export interface Resolvable {
     resolve<T>(key: constructor<T> | DependencyKey, options?: ResolveOneOptions): T;
 }
+/**
+ * A reusable bundle of registrations or event subscriptions applied with
+ * `container.useModule(module)`. A plain object with `applyTo` is enough.
+ *
+ * @example
+ * const loggingModule: IContainerModule = {
+ *   applyTo: (container) => container.addRegistration(Registration.fromClass(Logger)),
+ * };
+ */
 export interface IContainerModule {
     applyTo(container: IContainer): void;
 }
+/** Options of `createScope`: the child scope's `tags`. */
 export type CreateScopeOptions = Partial<WithTags>;
 export type AutoResolveOptions = Partial<WithArgs>;
 export type RegisterOptions = {
     aliases?: DependencyKey[];
 };
+/**
+ * Scope event hooks - the container's own domain: a scope was created, a scope
+ * was disposed. The listener type of `IContainer.scopeCreated` / `scopeDisposed`.
+ *
+ * The other two hook domains live with the abstraction which raises them:
+ * injector hooks on `IInjector` (`InjectorHook`), provider hooks on
+ * {@link IProvider} (`ProviderHook`). An injector is configured before it is
+ * passed to a container's constructor, so a container never hands its injector
+ * out.
+ */
 export type ScopeHook = (scope: IContainer) => void;
+/**
+ * Scope event hook for a registration landing in a scope: a provider entered
+ * the provider map under `key`. Registration is always of a provider, so the
+ * name says only what varies. The listener type of `IContainer.registered`.
+ */
 export type RegisteredHook = (provider: IProvider, key: DependencyKey, scope: IContainer) => void;
+/** A dependency injection scope. See {@link Container}. */
 export interface IContainer extends Tagged {
     readonly isDisposed: boolean;
+    /**
+     * Raised once a scope this container created is fully registered and attached.
+     * The subscriber's side only - a container raises its own scope events.
+     */
     readonly scopeCreated: ITypedEvent<[IContainer]>;
+    /**
+     * Raised by this container as it disposes, before its providers and instances go.
+     */
     readonly scopeDisposed: ITypedEvent<[IContainer]>;
+    /**
+     * Raised once a provider is registered here under a resolvable key.
+     */
     readonly registered: ITypedEvent<[IProvider, DependencyKey, IContainer]>;
+    /** Low-level: puts `value` under `key` in this scope only. Prefer `addRegistration`. */
     register(key: DependencyKey, value: IProvider, options?: RegisterOptions): this;
+    /** Registers here if the registration's scope rules match, and remembers it for future child scopes. */
     addRegistration(registration: IRegistration): this;
+    /** Registrations added to this scope and its parents - what `createScope` copies. */
     getRegistrations(): IRegistration[];
+    /** Whether a provider is registered under `key` in this scope (parents are not checked). */
     hasRegistration(key: DependencyKey): boolean;
+    /**
+     * Resolves a key, or constructs a class with the injector. Takes a key or a
+     * class, not a token: for a token call `token.resolve(scope)`.
+     *
+     * @example
+     * scope.resolve<ILogger>('ILogger');
+     * scope.resolve(App, { args: ['tenant-1'] });
+     */
     resolve<T>(target: constructor<T> | DependencyKey, options?: ResolveOneOptions): T;
+    /** Resolves every accessible dependency registered under `alias`, in this scope and its parents. */
     resolveByAlias<T>(alias: DependencyKey, options?: ResolveManyOptions): T[];
+    /** Resolves one dependency registered under `alias`, looking here first and then in parents. */
     resolveOneByAlias<T>(alias: DependencyKey, options?: ResolveOneOptions): T;
+    /**
+     * Creates a child scope and copies into it the registrations whose scope
+     * rules match its tags. Registrations added later are not copied into it.
+     *
+     * @example
+     * const request = app.createScope({ tags: ['request'] });
+     */
     createScope(options?: CreateScopeOptions): IContainer;
+    /** Resolves every provider marked with `autoResolve()`. */
     autoResolve(options?: AutoResolveOptions): this;
+    /** Direct child scopes that are still alive. */
     getScopes(): IContainer[];
+    /** Detaches a child scope; called by the child on dispose. */
     removeScope(child: IContainer): void;
+    /** Applies a module to this scope. */
     useModule(module: IContainerModule): this;
+    /** The parent scope, if any. */
     getParent(): IContainer | undefined;
+    /** Instances constructed in this scope, and in child scopes when `cascade` is true. */
     getInstances(cascade?: boolean): Instance[];
+    /** Whether this scope tracks `instance`. */
     hasInstance(instance: Instance): boolean;
+    /** Raises `scopeDisposed`, drops providers and instances, and detaches from the parent. Child scopes are not disposed. */
     dispose(): void;
+    /** Tracks an instance in this scope; called by the injector. */
     addInstance(instance: Instance): void;
+    /** The injector shared by this scope tree, e.g. to subscribe to `onConstructed`. */
     getInjector(): IInjector;
 }
 export {};
+//# sourceMappingURL=IContainer.d.ts.map