ditox 3.1.0 → 3.3.0

package/dist/{browser/index.d.ts → index.d.ts}

@@ -1,21 +1,22 @@
+//#region src/tokens.d.ts
 /**
  * @ignore
  * Binding token for mandatory value
  */
 type RequiredToken<T> = {
-    symbol: symbol;
-    type?: T;
-    isOptional?: false;
+  symbol: symbol;
+  type?: T;
+  isOptional?: false;
 };
 /**
  * @ignore
  * Binding token for optional value
  */
 type OptionalToken<T> = {
-    symbol: symbol;
-    type?: T;
-    isOptional: true;
-    optionalValue: T;
+  symbol: symbol;
+  type?: T;
+  isOptional: true;
+  optionalValue: T;
 };
 /**
  * Binding token
@@ -25,17 +26,14 @@ type Token<T> = RequiredToken<T> | OptionalToken<T>;
  * Token options
  */
 type TokenOptions = {
-    /**
-     * Key for token's symbol. It allows to create shareable tokens.
-     */
-    key: string;
-    /** @ignore */
-    description?: undefined;
+  /**
+   * Key for token's symbol. It allows to create shareable tokens.
+   */
+  key: string; /** @ignore */
+  description?: undefined;
 } | {
-    /** Description for better error messages */
-    description?: string;
-    /** @ignore */
-    key?: undefined;
+  /** Description for better error messages */description?: string; /** @ignore */
+  key?: undefined;
 };
 /**
  * Creates a new binding token.
@@ -45,7 +43,8 @@ declare function token<T>(description?: string): Token<T>;
 /**
  * Creates a new binding token.
  * @param options - Token description for better error messages.
- */ declare function token<T>(options?: TokenOptions): Token<T>;
+ */
+declare function token<T>(options?: TokenOptions): Token<T>;
 /**
  * Decorate a token with an optional value.
  * This value is be used as default value in case a container does not have registered token.
@@ -54,12 +53,13 @@ declare function token<T>(description?: string): Token<T>;
  */
 declare function optional<T>(token: Token<T>, optionalValue: T): OptionalToken<T>;
 declare function optional<T>(token: Token<T>): OptionalToken<T | undefined>;
-
+//#endregion
+//#region src/container.d.ts
 /**
  * ResolverError is thrown by the resolver when a token is not found in a container.
  */
 declare class ResolverError extends Error {
-    constructor(message: string);
+  constructor(message: string);
 }
 /**
  * @see https://github.com/mnasyrov/ditox#factory-lifetimes
@@ -76,44 +76,49 @@ type FactoryScope = 'scoped' | 'singleton' | 'transient';
  * `scoped` and `singleton` scopes can have `onRemoved` callback. It is called when a token is removed from the container.
  */
 type FactoryOptions<T> = {
-    scope?: 'scoped' | 'singleton';
-    onRemoved?: (value: T) => void;
+  scope?: 'scoped' | 'singleton';
+  onRemoved?: (value: T) => void;
 } | {
-    scope: 'transient';
+  scope: 'transient';
 };
 /**
  * Dependency container.
  */
 type Container = {
-    /**
-     * Binds a value for the token
-     */
-    bindValue<T>(token: Token<T>, value: T): void;
-    /**
-     * Binds a factory for the token.
-     */
-    bindFactory<T>(token: Token<T>, factory: (container: Container) => T, options?: FactoryOptions<T>): void;
-    /**
-     * Checks if the token is registered in the container hierarchy.
-     */
-    hasToken(token: Token<unknown>): boolean;
-    /**
-     * Returns a resolved value by the token, or returns `undefined` in case the token is not found.
-     */
-    get<T>(token: Token<T>): T | undefined;
-    /**
-     * Returns a resolved value by the token or throws `ResolverError` in case the token is not found.
-     */
-    resolve<T>(token: Token<T>): T;
-    /**
-     * Removes a binding for the token.
-     */
-    remove<T>(token: Token<T>): void;
-    /**
-     * Removes all bindings in the container.
-     */
-    removeAll(): void;
+  /**
+   * Binds a value for the token
+   */
+  bindValue<T>(token: Token<T>, value: T): void;
+  /**
+   * Binds a factory for the token.
+   */
+  bindFactory<T>(token: Token<T>, factory: (container: Container) => T, options?: FactoryOptions<T>): void;
+  /**
+   * Checks if the token is registered in the container hierarchy.
+   */
+  hasToken(token: Token<unknown>): boolean;
+  /**
+   * Returns a resolved value by the token, or returns `undefined` in case the token is not found.
+   */
+  get<T>(token: Token<T>): T | undefined;
+  /**
+   * Returns a resolved value by the token or throws `ResolverError` in case the token is not found.
+   */
+  resolve<T>(token: Token<T>): T;
+  /**
+   * Removes a binding for the token.
+   */
+  remove<T>(token: Token<T>): void;
+  /**
+   * Removes all bindings in the container.
+   */
+  removeAll(): void;
 };
+/**
+ * A subset of Container interface that provides read-only access to dependency resolution.
+ * This type is used for parent containers to allow token resolution without exposing mutation methods.
+ */
+type ContainerResolver = Pick<Container, 'hasToken' | 'get' | 'resolve'>;
 /**
  * Creates a new dependency container.
  *
@@ -121,14 +126,132 @@ type Container = {
  *
  * @param parentArg - Optional parent container or an array of containers.
  */
-declare function createContainer(parentArg?: Container | ReadonlyArray<Container>): Container;
-
-type ValuesProps = {
-    [key: string]: unknown;
+declare function createContainer(parentArg?: ContainerResolver | ReadonlyArray<ContainerResolver>): Container;
+//#endregion
+//#region src/modules.d.ts
+type AnyObject = Record<string, any>;
+type EmptyObject = Record<string, never>;
+type ModuleController = {
+  /** Dispose the module and clean its resources */destroy?: () => void;
 };
-type TokenProps<Props extends ValuesProps> = {
-    [K in keyof Props]: Token<Props[K]>;
+/**
+ * Dependency module
+ *
+ * @example
+ * ```ts
+ * type LoggerModule = Module<{
+ *   logger: Logger;
+ * }>;
+ * ```
+ */
+type Module<ModuleProps extends AnyObject = EmptyObject> = ModuleController & ModuleProps;
+type GetModuleProps<T> = T extends Module<infer Props> ? Props : never;
+/**
+ * Description how to bind the module in declarative way.
+ *
+ * @example
+ * ```ts
+ * const LOGGER_MODULE: ModuleDeclaration<LoggerModule> = {
+ *   token: LOGGER_MODULE_TOKEN,
+ *   factory: (container) => {
+ *     const transport = container.resolve(TRANSPORT_TOKEN).open();
+ *     return {
+ *       logger: { log: (message) => transport.write(message) },
+ *       destroy: () => transport.close(),
+ *     }
+ *   },
+ *   exports: {
+ *     logger: LOGGER_TOKEN,
+ *   },
+ * };
+ * ```
+ */
+type ModuleDeclaration<T extends Module<AnyObject>> = {
+  /** Token for the module */token: Token<T>; /** Modules for binding  */
+  imports?: ReadonlyArray<ModuleBindingEntry>; /** Factory of the module */
+  factory: (container: Container) => T; /** Dictionary of module properties which are bound to tokens. */
+  exports?: { [K in keyof GetModuleProps<T>]?: Token<GetModuleProps<T>[K]> }; /** Callback could be used to prepare an environment. It is called before binding the module. */
+  beforeBinding?: (container: Container) => void; /** Callback could be used to export complex dependencies from the module. It is called after binding the module.  */
+  afterBinding?: (container: Container) => void;
+  /**
+   * Strategy for executing the factory:
+   *   - `lazy` - **This is the default**. The factory is called when the module is resolved.
+   *   - `eager` - The factory is called immediately after the module is bound to the container.
+   */
+  strategy?: 'eager' | 'lazy';
 };
+type AnyModuleDeclaration = ModuleDeclaration<Module<AnyObject>>;
+/**
+ * Options for module binding.
+ *
+ * `scope` types:
+ *   - `singleton` - **This is the default**. The value is created and cached by the most distant parent container which owns the factory function.
+ *   - `scoped` - The value is created and cached by the nearest container which owns the factory function.
+ */
+type BindModuleOptions = {
+  scope?: 'scoped' | 'singleton';
+};
+type ModuleDeclarationWithOptions = {
+  module: ModuleDeclaration<AnyObject>;
+  options: BindModuleOptions;
+};
+type ModuleBindingEntry = ModuleDeclaration<AnyObject> | ModuleDeclarationWithOptions;
+/**
+ * Binds the dependency module to the container
+ * @param container - Dependency container.
+ * @param moduleDeclaration - Declaration of the dependency module.
+ * @param options - Options for module binding.
+ *
+ * @example
+ * ```ts
+ * bindModule(container, LOGGER_MODULE);
+ * ```
+ */
+declare function bindModule<T extends Module<AnyObject>>(container: Container, moduleDeclaration: ModuleDeclaration<T>, options?: BindModuleOptions): void;
+/**
+ * Binds dependency modules to the container
+ *
+ * @param container - Dependency container for binding
+ * @param modules - Array of module binding entries: module declaration or `{module: ModuleDeclaration, options: BindModuleOptions}` objects.
+ */
+declare function bindModules(container: Container, modules: ReadonlyArray<ModuleBindingEntry>): void;
+/**
+ * Declares a module binding
+ *
+ * @param declaration - a module declaration
+ * @param declaration.token - optional field
+ *
+ *  @example
+ * ```ts
+ * const LOGGER_MODULE = declareModule<LoggerModule>({
+ *   factory: (container) => {
+ *     const transport = container.resolve(TRANSPORT_TOKEN).open();
+ *     return {
+ *       logger: { log: (message) => transport.write(message) },
+ *       destroy: () => transport.close(),
+ *     }
+ *   },
+ *   exports: {
+ *     logger: LOGGER_TOKEN,
+ *   },
+ * });
+ * ```
+ */
+declare function declareModule<T extends Module<AnyObject>>(declaration: Omit<ModuleDeclaration<T>, 'token'> & Partial<Pick<ModuleDeclaration<T>, 'token'>>): ModuleDeclaration<T>;
+/**
+ * @deprecated Use `declareModule` instead
+ *
+ * Declares bindings of several modules
+ *
+ * @param modules - module declaration entries
+ */
+declare function declareModuleBindings(modules: ReadonlyArray<ModuleBindingEntry>): ModuleDeclaration<Module>;
+//#endregion
+//#region src/utils.d.ts
+type ValuesProps = {
+  [key: string]: unknown;
+};
+type TokenProps<Props extends ValuesProps> = { [K in keyof Props]: Token<Props[K]> };
 /**
  * Checks if a value is the token
  */
@@ -158,8 +281,8 @@ declare function bindMultiValue<T>(container: Container, token: Token<ReadonlyAr
  * ```
  */
 declare function tryResolveValue<Tokens extends Token<unknown> | {
-    [key: string]: Token<unknown>;
-}, Values extends Tokens extends Token<infer V> ? V | undefined : Tokens extends TokenProps<infer Props> ? Partial<Props> : never>(container: Container, token: Tokens): Values;
+  [key: string]: Token<unknown>;
+}, Values extends (Tokens extends Token<infer V> ? V | undefined : Tokens extends TokenProps<infer Props> ? Partial<Props> : never)>(container: Container, token: Tokens): Values;
 /**
  * Returns an array of resolved values or objects with resolved values.
  *
@@ -178,10 +301,8 @@ declare function tryResolveValue<Tokens extends Token<unknown> | {
  * ```
  */
 declare function tryResolveValues<Tokens extends (Token<unknown> | {
-    [key: string]: Token<unknown>;
-})[], Values extends {
-    [K in keyof Tokens]: Tokens[K] extends Token<infer V> ? V | undefined : Tokens[K] extends TokenProps<infer Props> ? Partial<Props> : never;
-}>(container: Container, ...tokens: Tokens): Values;
+  [key: string]: Token<unknown>;
+})[], Values extends { [K in keyof Tokens]: Tokens[K] extends Token<infer V> ? V | undefined : Tokens[K] extends TokenProps<infer Props> ? Partial<Props> : never }>(container: Container, ...tokens: Tokens): Values;
 /**
  * Resolves a value by the provided token.
  *
@@ -200,8 +321,8 @@ declare function tryResolveValues<Tokens extends (Token<unknown> | {
  * ```
  */
 declare function resolveValue<Tokens extends Token<unknown> | {
-    [key: string]: Token<unknown>;
-}, Values extends Tokens extends Token<infer V> ? V : Tokens extends TokenProps<infer Props> ? Props : never>(container: Container, token: Tokens): Values;
+  [key: string]: Token<unknown>;
+}, Values extends (Tokens extends Token<infer V> ? V : Tokens extends TokenProps<infer Props> ? Props : never)>(container: Container, token: Tokens): Values;
 /**
  * Returns an array of resolved values or objects with resolved values.
  *
@@ -220,10 +341,8 @@ declare function resolveValue<Tokens extends Token<unknown> | {
  * ```
  */
 declare function resolveValues<Tokens extends (Token<unknown> | {
-    [key: string]: Token<unknown>;
-})[], Values extends {
-    [K in keyof Tokens]: Tokens[K] extends Token<infer V> ? V : Tokens[K] extends TokenProps<infer Props> ? Props : never;
-}>(container: Container, ...tokens: Tokens): Values;
+  [key: string]: Token<unknown>;
+})[], Values extends { [K in keyof Tokens]: Tokens[K] extends Token<infer V> ? V : Tokens[K] extends TokenProps<infer Props> ? Props : never }>(container: Container, ...tokens: Tokens): Values;
 /**
  * Decorates a factory by passing resolved values as factory arguments.
  *
@@ -236,10 +355,8 @@ declare function resolveValues<Tokens extends (Token<unknown> | {
  * @return Decorated factory which takes a dependency container as a single argument.
  */
 declare function injectable<Tokens extends (Token<unknown> | {
-    [key: string]: Token<unknown>;
-})[], Values extends {
-    [K in keyof Tokens]: Tokens[K] extends Token<infer V> ? V : Tokens[K] extends TokenProps<infer Props> ? Props : never;
-}, Result>(this: unknown, factory: (...params: Values) => Result, ...tokens: Tokens): (container: Container) => Result;
+  [key: string]: Token<unknown>;
+})[], Values extends { [K in keyof Tokens]: Tokens[K] extends Token<infer V> ? V : Tokens[K] extends TokenProps<infer Props> ? Props : never }, Result>(this: unknown, factory: (...params: Values) => Result, ...tokens: Tokens): (container: Container) => Result;
 /**
  * Decorates a class by passing resolved values as arguments to its constructor.
  *
@@ -253,127 +370,8 @@ declare function injectable<Tokens extends (Token<unknown> | {
  * and returns a new created class.
  */
 declare function injectableClass<Tokens extends (Token<unknown> | {
-    [key: string]: Token<unknown>;
-})[], Values extends {
-    [K in keyof Tokens]: Tokens[K] extends Token<infer V> ? V : Tokens[K] extends TokenProps<infer Props> ? Props : never;
-}, Result>(this: unknown, constructor: new (...params: Values) => Result, ...tokens: Tokens): (container: Container) => Result;
-
-type AnyObject = Record<string, any>;
-type EmptyObject = Record<string, never>;
-type ModuleController = {
-    /** Dispose the module and clean its resources */
-    destroy?: () => void;
-};
-/**
- * Dependency module
- *
- * @example
- * ```ts
- * type LoggerModule = Module<{
- *   logger: Logger;
- * }>;
- * ```
- */
-type Module<ModuleProps extends AnyObject = EmptyObject> = ModuleController & ModuleProps;
-type GetModuleProps<T> = T extends Module<infer Props> ? Props : never;
-/**
- * Description how to bind the module in declarative way.
- *
- * @example
- * ```ts
- * const LOGGER_MODULE: ModuleDeclaration<LoggerModule> = {
- *   token: LOGGER_MODULE_TOKEN,
- *   factory: (container) => {
- *     const transport = container.resolve(TRANSPORT_TOKEN).open();
- *     return {
- *       logger: { log: (message) => transport.write(message) },
- *       destroy: () => transport.close(),
- *     }
- *   },
- *   exports: {
- *     logger: LOGGER_TOKEN,
- *   },
- * };
- * ```
- */
-type ModuleDeclaration<T extends Module<AnyObject>> = {
-    /** Token for the module */
-    token: Token<T>;
-    /** Modules for binding  */
-    imports?: ReadonlyArray<ModuleBindingEntry>;
-    /** Factory of the module */
-    factory: (container: Container) => T;
-    /** Dictionary of module properties which are bound to tokens. */
-    exports?: {
-        [K in keyof GetModuleProps<T>]?: Token<GetModuleProps<T>[K]>;
-    };
-    /** Callback could be used to prepare an environment. It is called before binding the module. */
-    beforeBinding?: (container: Container) => void;
-    /** Callback could be used to export complex dependencies from the module. It is called after binding the module.  */
-    afterBinding?: (container: Container) => void;
-};
-/**
- * Options for module binding.
- *
- * `scope` types:
- *   - `singleton` - **This is the default**. The value is created and cached by the most distant parent container which owns the factory function.
- *   - `scoped` - The value is created and cached by the nearest container which owns the factory function.
- */
-type BindModuleOptions = {
-    scope?: 'scoped' | 'singleton';
-};
-type ModuleDeclarationWithOptions = {
-    module: ModuleDeclaration<AnyObject>;
-    options: BindModuleOptions;
-};
-type ModuleBindingEntry = ModuleDeclaration<AnyObject> | ModuleDeclarationWithOptions;
-/**
- * Binds the dependency module to the container
- * @param container - Dependency container.
- * @param moduleDeclaration - Declaration of the dependency module.
- * @param options - Options for module binding.
- *
- * @example
- * ```ts
- * bindModule(container, LOGGER_MODULE);
- * ```
- */
-declare function bindModule<T extends Module<AnyObject>>(container: Container, moduleDeclaration: ModuleDeclaration<T>, options?: BindModuleOptions): void;
-/**
- * Binds dependency modules to the container
- *
- * @param container - Dependency container for binding
- * @param modules - Array of module binding entries: module declaration or `{module: ModuleDeclaration, options: BindModuleOptions}` objects.
- */
-declare function bindModules(container: Container, modules: ReadonlyArray<ModuleBindingEntry>): void;
-/**
- * Declares a module binding
- *
- * @param declaration - a module declaration
- * @param declaration.token - optional field
- *
- *  @example
- * ```ts
- * const LOGGER_MODULE = declareModule<LoggerModule>({
- *   factory: (container) => {
- *     const transport = container.resolve(TRANSPORT_TOKEN).open();
- *     return {
- *       logger: { log: (message) => transport.write(message) },
- *       destroy: () => transport.close(),
- *     }
- *   },
- *   exports: {
- *     logger: LOGGER_TOKEN,
- *   },
- * });
- * ```
- */
-declare function declareModule<T extends Module<AnyObject>>(declaration: Omit<ModuleDeclaration<T>, 'token'> & Partial<Pick<ModuleDeclaration<T>, 'token'>>): ModuleDeclaration<T>;
-/**
- * Declares bindings of several modules
- *
- * @param modules - module declaration entries
- */
-declare function declareModuleBindings(modules: ReadonlyArray<ModuleBindingEntry>): ModuleDeclaration<Module>;
-
-export { BindModuleOptions, Container, FactoryOptions, FactoryScope, Module, ModuleBindingEntry, ModuleDeclaration, OptionalToken, RequiredToken, ResolverError, Token, bindModule, bindModules, bindMultiValue, createContainer, declareModule, declareModuleBindings, injectable, injectableClass, isToken, optional, resolveValue, resolveValues, token, tryResolveValue, tryResolveValues };
+  [key: string]: Token<unknown>;
+})[], Values extends { [K in keyof Tokens]: Tokens[K] extends Token<infer V> ? V : Tokens[K] extends TokenProps<infer Props> ? Props : never }, Result>(this: unknown, constructor: new (...params: Values) => Result, ...tokens: Tokens): (container: Container) => Result;
+//#endregion
+export { type AnyModuleDeclaration, type BindModuleOptions, type Container, type ContainerResolver, type FactoryOptions, type FactoryScope, type Module, type ModuleBindingEntry, type ModuleDeclaration, type OptionalToken, type RequiredToken, ResolverError, type Token, bindModule, bindModules, bindMultiValue, createContainer, declareModule, declareModuleBindings, injectable, injectableClass, isToken, optional, resolveValue, resolveValues, token, tryResolveValue, tryResolveValues };
+//# sourceMappingURL=index.d.ts.map