@lppedd/di-wise-neo 0.3.0 → 0.3.2

package/src/container.ts

@@ -1,292 +0,0 @@
-import { DefaultContainer } from "./defaultContainer";
-import type { ClassProvider, ExistingProvider, FactoryProvider, ValueProvider } from "./provider";
-import { Scope } from "./scope";
-import type { Constructor, Token } from "./token";
-import type { RegistrationOptions, TokenRegistry } from "./tokenRegistry";
-
-/**
- * Container creation options.
- */
-export interface ContainerOptions {
-  /**
-   * Whether to automatically register an unregistered class when resolving it as a token.
-   *
-   * @defaultValue false
-   */
-  readonly autoRegister: boolean;
-
-  /**
-   * The default scope for registrations.
-   *
-   * @defaultValue Scope.Inherited
-   */
-  readonly defaultScope: Scope;
-}
-
-/**
- * Container API.
- */
-export interface Container {
-  /**
-   * @internal
-   */
-  api?: Readonly<Container>;
-
-  /**
-   * @internal
-   */
-  readonly registry: TokenRegistry;
-
-  /**
-   * The options used to create this container.
-   */
-  readonly options: ContainerOptions;
-
-  /**
-   * The parent container, or `undefined` if this is the root container.
-   */
-  readonly parent: Container | undefined;
-
-  /**
-   * Whether this container is disposed.
-   */
-  readonly isDisposed: boolean;
-
-  /**
-   * Creates a new child container that inherits this container's options.
-   *
-   * You can pass specific options to override the inherited ones.
-   */
-  createChild(options?: Partial<ContainerOptions>): Container;
-
-  /**
-   * Clears and returns all distinct cached values from this container's internal registry.
-   * Values from {@link ValueProvider} registrations are not included, as they are never cached.
-   *
-   * Note that only this container is affected. Parent containers, if any, remain unchanged.
-   */
-  clearCache(): unknown[];
-
-  /**
-   * Returns the cached value from the most recent registration of the token,
-   * or `undefined` if no value has been cached yet (the token has not been resolved yet).
-   *
-   * If the token has at least one registration in this container,
-   * the cached value is taken from the most recent of those registrations.
-   * Otherwise, it may be retrieved from parent containers, if any.
-   *
-   * Values are never cached for tokens with _transient_ or _resolution_ scope,
-   * or for {@link ValueProvider} registrations.
-   */
-  getCached<Value>(token: Token<Value>): Value | undefined;
-
-  /**
-   * Returns all cached values associated with registrations of the token,
-   * in the order they were registered, or an empty array if none have been cached.
-   *
-   * If the token has at least one registration in the current container,
-   * cached values are taken from those registrations.
-   * Otherwise, cached values may be retrieved from parent containers, if any.
-   *
-   * Values are never cached for tokens with _transient_ or _resolution_ scope,
-   * or for {@link ValueProvider} registrations.
-   */
-  getAllCached<Value>(token: Token<Value>): Value[];
-
-  /**
-   * Removes all registrations from this container's internal registry.
-   *
-   * Returns an array of distinct cached values that were stored within the removed registrations.
-   * Values from {@link ValueProvider} registrations are not included, as they are not cached.
-   *
-   * Note that only this container is affected. Parent containers, if any, remain unchanged.
-   */
-  resetRegistry(): unknown[];
-
-  /**
-   * Returns whether the token is registered in this container or in parent containers, if any.
-   */
-  isRegistered(token: Token): boolean;
-
-  /**
-   * Registers a {@link ClassProvider}, using the class itself as its token.
-   *
-   * Tokens provided to the {@link Injectable} decorator applied to the class
-   * are also registered as aliases. The scope is determined by the {@link Scoped}
-   * decorator, if present.
-   */
-  register<Instance extends object>(Class: Constructor<Instance>): this;
-
-  /**
-   * Registers a {@link ClassProvider} with a token.
-   */
-  register<Instance extends object, ProviderInstance extends Instance>(
-    token: Token<Instance>,
-    provider: ClassProvider<ProviderInstance>,
-    options?: RegistrationOptions,
-  ): this;
-
-  /**
-   * Registers a {@link FactoryProvider} with a token.
-   */
-  register<Value, ProviderValue extends Value>(
-    token: Token<Value>,
-    provider: FactoryProvider<ProviderValue>,
-    options?: RegistrationOptions,
-  ): this;
-
-  /**
-   * Registers an {@link ExistingProvider} with a token.
-   *
-   * The token will alias the one set in `useExisting`.
-   */
-  register<Value, ProviderValue extends Value>(
-    token: Token<Value>,
-    provider: ExistingProvider<ProviderValue>,
-  ): this;
-
-  /**
-   * Registers a {@link ValueProvider} with a token.
-   *
-   * Values provided via `useValue` are never cached (scopes do not apply)
-   * and are simply returned as-is.
-   */
-  register<Value, ProviderValue extends Value>(
-    token: Token<Value>,
-    provider: ValueProvider<ProviderValue>,
-  ): this;
-
-  /**
-   * Removes all registrations for the given token from the container's internal registry.
-   *
-   * Returns an array of distinct cached values that were stored within the removed registrations.
-   * Values from {@link ValueProvider} registrations are not included, as they are not cached.
-   *
-   * Note that only this container is affected. Parent containers, if any, remain unchanged.
-   */
-  unregister<Value>(token: Token<Value>): Value[];
-
-  /**
-   * Resolves the given class to the instance associated with it.
-   *
-   * If the class is registered in this container or any of its parent containers,
-   * an instance is created using the most recent registration.
-   *
-   * If the class is not registered, but it is decorated with {@link AutoRegister},
-   * or {@link ContainerOptions.autoRegister} is true, the class is registered automatically.
-   * Otherwise, resolution fails.
-   * The scope for the automatic registration is determined by either
-   * the {@link Scoped} decorator on the class, or {@link ContainerOptions.defaultScope}.
-   *
-   * If `optional` is false or is not passed and the class is not registered in the container
-   * (and could not be auto-registered), an error is thrown.
-   * Otherwise, if `optional` is true, `undefined` is returned.
-   *
-   * The resolution behavior depends on the {@link Provider} used during registration:
-   * - For {@link ValueProvider}, the explicitly provided instance is returned.
-   * - For {@link FactoryProvider}, the factory function is invoked to create the instance.
-   * - For {@link ClassProvider}, a new instance of the class is created according to its scope.
-   * - For {@link ExistingProvider}, the instance is resolved by referring to another registered token.
-   *
-   * If the class is registered with _container_ scope, the resolved instance is cached
-   * in the container's internal registry.
-   */
-  resolve<Instance extends object>(Class: Constructor<Instance>, optional?: false): Instance;
-  resolve<Instance extends object>(Class: Constructor<Instance>, optional: true): Instance | undefined;
-  resolve<Instance extends object>(Class: Constructor<Instance>, optional: boolean): Instance | undefined;
-
-  /**
-   * Resolves the given token to the value associated with it.
-   *
-   * If the token is registered in this container or any of its parent containers,
-   * its value is resolved using the most recent registration.
-   *
-   * If `optional` is false or not passed and the token is not registered in the container,
-   * an error is thrown. Otherwise, if `optional` is true, `undefined` is returned.
-   *
-   * The resolution behavior depends on the {@link Provider} used during registration:
-   * - For {@link ValueProvider}, the explicitly provided value is returned.
-   * - For {@link FactoryProvider}, the factory function is invoked to create the value.
-   * - For {@link ClassProvider}, a new instance of the class is created according to its scope.
-   * - For {@link ExistingProvider}, the value is resolved by referring to another registered token.
-   *
-   * If the token is registered with _container_ scope, the resolved value is cached
-   * in the container's internal registry.
-   */
-  resolve<Value>(token: Token<Value>, optional?: false): Value;
-  resolve<Value>(token: Token<Value>, optional: true): Value | undefined;
-  resolve<Value>(token: Token<Value>, optional: boolean): Value | undefined;
-
-  /**
-   * Resolves the given class to all instances provided by the registrations associated with it.
-   *
-   * If the class is not registered, but it is decorated with {@link AutoRegister},
-   * or {@link ContainerOptions.autoRegister} is true, the class is registered automatically.
-   * Otherwise, resolution fails.
-   * The scope for the automatic registration is determined by either
-   * the {@link Scoped} decorator on the class, or {@link ContainerOptions.defaultScope}.
-   *
-   * If `optional` is false or is not passed and the class is not registered in the container
-   * (and could not be auto-registered), an error is thrown.
-   * Otherwise, if `optional` is true, an empty array is returned.
-   *
-   * The resolution behavior depends on the {@link Provider} used during registration:
-   * - For {@link ValueProvider}, the explicitly provided instance is returned.
-   * - For {@link FactoryProvider}, the factory function is invoked to create the instance.
-   * - For {@link ClassProvider}, a new instance of the class is created according to its scope.
-   * - For {@link ExistingProvider}, the instance is resolved by referring to another registered token.
-   *
-   * If the class is registered with _container_ scope, the resolved instances are cached
-   * in the container's internal registry.
-   *
-   * A separate instance of the class is created for each provider.
-   *
-   * @see The documentation for `resolve(Class: Constructor)`
-   */
-  resolveAll<Instance extends object>(Class: Constructor<Instance>, optional?: false): Instance[];
-  resolveAll<Instance extends object>(Class: Constructor<Instance>, optional: true): Instance[];
-  resolveAll<Instance extends object>(Class: Constructor<Instance>, optional: boolean): Instance[];
-
-  /**
-   * Resolves the given token to all values provided by the registrations associated with it.
-   *
-   * If `optional` is false or not passed and the token is not registered in the container,
-   * an error is thrown. Otherwise, if `optional` is true, an empty array is returned.
-   *
-   * The resolution behavior depends on the {@link Provider} used during registration:
-   * - For {@link ValueProvider}, the explicitly provided value is returned.
-   * - For {@link FactoryProvider}, the factory function is invoked to create the value.
-   * - For {@link ClassProvider}, a new instance of the class is created according to its scope.
-   * - For {@link ExistingProvider}, the value is resolved by referring to another registered token.
-   *
-   * If the token is registered with _container_ scope, the resolved values are cached
-   * in the container's internal registry.
-   *
-   * @see The documentation for `resolve(token: Token)`
-   */
-  resolveAll<Value>(token: Token<Value>, optional?: false): NonNullable<Value>[];
-  resolveAll<Value>(token: Token<Value>, optional: true): NonNullable<Value>[];
-  resolveAll<Value>(token: Token<Value>, optional: boolean): NonNullable<Value>[];
-
-  /**
-   * Disposes this container and all its cached values.
-   *
-   * Token values implementing a `Disposable` interface (e.g., objects with a `dispose()` function)
-   * are automatically disposed during this process.
-   *
-   * Note that children containers are disposed first, in creation order.
-   */
-  dispose(): void;
-}
-
-/**
- * Creates a new container.
- */
-export function createContainer(
-  options: Partial<ContainerOptions> = {
-    autoRegister: false,
-    defaultScope: Scope.Inherited,
-  },
-): Container {
-  return new DefaultContainer(undefined, options);
-}

package/src/decorators/autoRegister.ts

@@ -1,24 +0,0 @@
-import { getMetadata } from "../metadata";
-import type { Constructor } from "../token";
-
-/**
- * Class decorator for enabling auto-registration of an unregistered class
- * when first resolving it from the container.
- *
- * @example
- * ```ts
- * @AutoRegister()
- * class Wizard {}
- *
- * const wizard = container.resolve(Wizard);
- * container.isRegistered(Wizard); // => true
- * ```
- *
- * @__NO_SIDE_EFFECTS__
- */
-export function AutoRegister(enable: boolean = true): ClassDecorator {
-  return function (Class) {
-    const metadata = getMetadata(Class as any as Constructor<any>);
-    metadata.autoRegister = enable;
-  };
-}

package/src/decorators/decorators.ts

@@ -1,47 +0,0 @@
-import { assert } from "../errors";
-import { getMetadata } from "../metadata";
-import type { Constructor, Token } from "../token";
-import type { Decorator } from "../tokenRegistry";
-import { forwardRef, isTokenRef, type TokenRef } from "../tokensRef";
-
-export function processDecoratedParameter(
-  decorator: Decorator,
-  token: Token | TokenRef,
-  target: object,
-  propertyKey: string | symbol | undefined,
-  parameterIndex: number,
-): void {
-  // Error out immediately if the decorator has been applied
-  // to a static property or a static method
-  if (propertyKey !== undefined && typeof target === "function") {
-    assert(false, `@${decorator} cannot be used on static member ${target.name}.${String(propertyKey)}`);
-  }
-
-  const tokenRef = isTokenRef(token) ? token : forwardRef(() => token);
-
-  if (propertyKey === undefined) {
-    // Constructor
-    const metadata = getMetadata(target as Constructor<any>);
-    metadata.dependencies.constructor.push({
-      decorator: decorator,
-      tokenRef: tokenRef,
-      index: parameterIndex,
-    });
-  } else {
-    // Normal instance method
-    const metadata = getMetadata(target.constructor as Constructor<any>);
-    const methods = metadata.dependencies.methods;
-    let dep = methods.get(propertyKey);
-
-    if (dep === undefined) {
-      dep = [];
-      methods.set(propertyKey, dep);
-    }
-
-    dep.push({
-      decorator: decorator,
-      tokenRef: tokenRef,
-      index: parameterIndex,
-    });
-  }
-}

package/src/decorators/index.ts

@@ -1,7 +0,0 @@
-export { AutoRegister } from "./autoRegister";
-export { Inject } from "./inject";
-export { Injectable } from "./injectable";
-export { InjectAll } from "./injectAll";
-export { Optional } from "./optional";
-export { OptionalAll } from "./optionalAll";
-export { Scoped } from "./scoped";

package/src/decorators/inject.ts

@@ -1,42 +0,0 @@
-import type { Constructor, Token } from "../token";
-import type { TokenRef } from "../tokensRef";
-import { processDecoratedParameter } from "./decorators";
-
-/**
- * Parameter decorator that injects the instance associated with the given class.
- *
- * Throws an error if the class is not registered in the container.
- */
-export function Inject<Instance extends object>(Class: Constructor<Instance>): ParameterDecorator;
-
-/**
- * Parameter decorator that injects the value associated with the given token.
- *
- * Throws an error if the token is not registered in the container.
- */
-export function Inject<Value>(token: Token<Value>): ParameterDecorator;
-
-/**
- * Parameter decorator that injects the value associated with the given token.
- *
- * Allows referencing a token that is declared later in the file by using
- * the {@link forwardRef} helper function.
- *
- * Throws an error if the token is not registered in the container.
- *
- * @example
- * ```ts
- * class Wizard {
- *   constructor(@Inject(forwardRef(() => Wand)) readonly wand: Wand) {}
- * }
- * // Other code...
- * class Wand {}
- * ```
- */
-export function Inject<Value>(tokens: TokenRef<Value>): ParameterDecorator;
-
-export function Inject<T>(token: Token<T> | TokenRef<T>): ParameterDecorator {
-  return function (target, propertyKey, parameterIndex: number): void {
-    processDecoratedParameter("Inject", token, target, propertyKey, parameterIndex);
-  };
-}

package/src/decorators/injectAll.ts

@@ -1,45 +0,0 @@
-import type { Constructor, Token } from "../token";
-import type { TokenRef } from "../tokensRef";
-import { processDecoratedParameter } from "./decorators";
-
-/**
- * Parameter decorator that injects all instances provided by the registrations
- * associated with the given class.
- *
- * Throws an error if the class is not registered in the container.
- */
-export function InjectAll<Instance extends object>(Class: Constructor<Instance>): ParameterDecorator;
-
-/**
- * Parameter decorator that injects all values provided by the registrations
- * associated with the given token.
- *
- * Throws an error if the token is not registered in the container.
- */
-export function InjectAll<Value>(token: Token<Value>): ParameterDecorator;
-
-/**
- * Parameter decorator that injects all values provided by the registrations
- * associated with the given token.
- *
- * Allows referencing a token that is declared later in the file by using
- * the {@link forwardRef} helper function.
- *
- * Throws an error if the token is not registered in the container.
- *
- * @example
- * ```ts
- * class Wizard {
- *   constructor(@InjectAll(forwardRef(() => Wand)) readonly wands: Wand[]) {}
- * }
- * // Other code...
- * class Wand {}
- * ```
- */
-export function InjectAll<Value>(tokens: TokenRef<Value>): ParameterDecorator;
-
-export function InjectAll<T>(token: Token<T> | TokenRef<T>): ParameterDecorator {
-  return function (target, propertyKey, parameterIndex: number): void {
-    processDecoratedParameter("InjectAll", token, target, propertyKey, parameterIndex);
-  };
-}

package/src/decorators/injectable.ts

@@ -1,61 +0,0 @@
-import { getMetadata } from "../metadata";
-import type { Constructor, Tokens } from "../token";
-import { forwardRef, isTokensRef, type TokenRef, type TokensRef } from "../tokensRef";
-
-/**
- * Class decorator for registering additional aliasing tokens for the decorated type
- * when registering it.
- *
- * The container uses {@link ExistingProvider} under the hood.
- *
- * @example
- * ```ts
- * @Injectable(Weapon)
- * class Wand {}
- * ```
- */
-export function Injectable<This extends object, Value extends This>(...tokens: Tokens<Value>): ClassDecorator;
-
-/**
- * Class decorator for registering additional aliasing tokens for the decorated type
- * when registering it.
- *
- * The container uses {@link ExistingProvider} under the hood.
- *
- * Allows referencing tokens that are declared later in the file by using
- * the {@link forwardRef} helper function.
- *
- * @example
- * ```ts
- * @Injectable(forwardRef() => Weapon) // Weapon is declared after Wand
- * class Wizard {}
- * // Other code...
- * class Weapon {}
- * ```
- */
-export function Injectable<This extends object, Value extends This>(
-  tokens: TokenRef<Value> | TokensRef<Value>,
-): ClassDecorator;
-
-/**
- * @__NO_SIDE_EFFECTS__
- */
-export function Injectable(...args: unknown[]): ClassDecorator {
-  return function (Class): void {
-    const metadata = getMetadata(Class as any as Constructor<any>);
-    const arg0 = args[0];
-    const tokensRef = isTokensRef(arg0) ? arg0 : forwardRef(() => args as Tokens);
-    const existingTokensRef = metadata.tokensRef;
-    metadata.tokensRef = {
-      getRefTokens: () => {
-        const existingTokens = existingTokensRef.getRefTokens();
-
-        for (const token of tokensRef.getRefTokens()) {
-          existingTokens.add(token);
-        }
-
-        return existingTokens;
-      },
-    };
-  };
-}

package/src/decorators/optional.ts

@@ -1,39 +0,0 @@
-import type { Constructor, Token } from "../token";
-import type { TokenRef } from "../tokensRef";
-import { processDecoratedParameter } from "./decorators";
-
-/**
- * Parameter decorator that injects the instance associated with the given class,
- * or `undefined` if the class is not registered in the container.
- */
-export function Optional<Instance extends object>(Class: Constructor<Instance>): ParameterDecorator;
-
-/**
- * Parameter decorator that injects the value associated with the given token,
- * or `undefined` if the token is not registered in the container.
- */
-export function Optional<Value>(token: Token<Value>): ParameterDecorator;
-
-/**
- * Parameter decorator that injects the value associated with the given token,
- * or `undefined` if the token is not registered in the container.
- *
- * Allows referencing a token that is declared later in the file by using
- * the {@link forwardRef} helper function.
- *
- * @example
- * ```ts
- * class Wizard {
- *   constructor(@Optional(forwardRef(() => Wand)) readonly wand: Wand | undefined) {}
- * }
- * // Other code...
- * class Wand {}
- * ```
- */
-export function Optional<Value>(tokens: TokenRef<Value>): ParameterDecorator;
-
-export function Optional<T>(token: Token<T> | TokenRef<T>): ParameterDecorator {
-  return function (target, propertyKey, parameterIndex: number): void {
-    processDecoratedParameter("Optional", token, target, propertyKey, parameterIndex);
-  };
-}

package/src/decorators/optionalAll.ts

@@ -1,42 +0,0 @@
-import type { Constructor, Token } from "../token";
-import type { TokenRef } from "../tokensRef";
-import { processDecoratedParameter } from "./decorators";
-
-/**
- * Parameter decorator that injects all instances provided by the registrations
- * associated with the given class, or an empty array if the class is not registered
- * in the container.
- */
-export function OptionalAll<Instance extends object>(Class: Constructor<Instance>): ParameterDecorator;
-
-/**
- * Parameter decorator that injects all values provided by the registrations
- * associated with the given token, or an empty array if the token is not registered
- * in the container.
- */
-export function OptionalAll<Value>(token: Token<Value>): ParameterDecorator;
-
-/**
- * Parameter decorator that injects all values provided by the registrations
- * associated with the given token, or an empty array if the token is not registered
- * in the container.
- *
- * Allows referencing a token that is declared later in the file by using
- * the {@link forwardRef} helper function.
- *
- * @example
- * ```ts
- * class Wizard {
- *   constructor(@OptionalAll(forwardRef(() => Wand)) readonly wands: Wand[]) {}
- * }
- * // Other code...
- * class Wand {}
- * ```
- */
-export function OptionalAll<Value>(tokens: TokenRef<Value>): ParameterDecorator;
-
-export function OptionalAll<T>(token: Token<T> | TokenRef<T>): ParameterDecorator {
-  return function (target, propertyKey, parameterIndex: number): void {
-    processDecoratedParameter("OptionalAll", token, target, propertyKey, parameterIndex);
-  };
-}

package/src/decorators/scoped.ts

@@ -1,32 +0,0 @@
-import { getMetadata } from "../metadata";
-import type { Scope } from "../scope";
-import type { Constructor } from "../token";
-
-/**
- * Class decorator for setting the scope of the decorated type when registering it.
- *
- * The scope set by this decorator can be overridden by explicit registration options, if provided.
- *
- * @example
- * ```ts
- * @Scoped(Scope.Container)
- * class Wizard {}
- *
- * container.register(Wizard);
- *
- * // Under the hood
- * container.register(
- *   Wizard,
- *   { useClass: Wizard },
- *   { scope: Scope.Container },
- * );
- * ```
- *
- * @__NO_SIDE_EFFECTS__
- */
-export function Scoped(scope: Scope): ClassDecorator {
-  return function (Class): void {
-    const metadata = getMetadata(Class as any as Constructor<any>);
-    metadata.scope = scope;
-  };
-}