@lppedd/di-wise-neo 0.3.0

package/src/injectionContext.ts

@@ -0,0 +1,46 @@
+import type { Container } from "./container";
+import { assert } from "./errors";
+import type { Provider } from "./provider";
+import type { Scope } from "./scope";
+import { createInjectionContext } from "./utils/context";
+import { KeyedStack } from "./utils/keyedStack";
+import { WeakRefMap } from "./utils/weakRefMap";
+import type { ValueRef } from "./valueRef";
+
+// @internal
+export interface ResolutionFrame {
+  readonly scope: Exclude<Scope, typeof Scope.Inherited>;
+  readonly provider: Provider;
+}
+
+// @internal
+export interface Resolution {
+  readonly stack: KeyedStack<Provider, ResolutionFrame>;
+  readonly values: WeakRefMap<Provider, ValueRef>;
+  readonly dependents: WeakRefMap<Provider, ValueRef>;
+}
+
+// @internal
+export interface InjectionContext {
+  readonly container: Container;
+  readonly resolution: Resolution;
+}
+
+// @internal
+export function createResolution(): Resolution {
+  return {
+    stack: new KeyedStack(),
+    values: new WeakRefMap(),
+    dependents: new WeakRefMap(),
+  };
+}
+
+// @internal
+export const [provideInjectionContext, useInjectionContext] = createInjectionContext<InjectionContext>();
+
+// @internal
+export function ensureInjectionContext(fn: Function): InjectionContext {
+  const context = useInjectionContext();
+  assert(context, `${fn.name}() can only be invoked within an injection context`);
+  return context;
+}

package/src/injector.ts

@@ -0,0 +1,117 @@
+import { inject } from "./inject";
+import { injectAll } from "./injectAll";
+import { ensureInjectionContext, provideInjectionContext, useInjectionContext } from "./injectionContext";
+import { optional } from "./optional";
+import { optionalAll } from "./optionalAll";
+import type { Constructor, Token, Type } from "./token";
+import { Build } from "./tokenRegistry";
+
+/**
+ * Injector API.
+ */
+export interface Injector {
+  /**
+   * Injects the instance associated with the given class.
+   *
+   * Throws an error if the class is not registered in the container.
+   */
+  inject<Instance extends object>(Class: Constructor<Instance>): Instance;
+
+  /**
+   * Injects the value associated with the given token.
+   *
+   * Throws an error if the token is not registered in the container.
+   */
+  inject<Value>(token: Token<Value>): Value;
+
+  /**
+   * Injects all instances provided by the registrations associated with the given class.
+   *
+   * Throws an error if the class is not registered in the container.
+   */
+  injectAll<Instance extends object>(Class: Constructor<Instance>): Instance[];
+
+  /**
+   * Injects all values provided by the registrations associated with the given token.
+   *
+   * Throws an error if the token is not registered in the container.
+   */
+  injectAll<Value>(token: Token<Value>): NonNullable<Value>[];
+
+  /**
+   * Injects the instance associated with the given class,
+   * or `undefined` if the class is not registered in the container.
+   */
+  optional<Instance extends object>(Class: Constructor<Instance>): Instance | undefined;
+
+  /**
+   * Injects the value associated with the given token,
+   * or `undefined` if the token is not registered in the container.
+   */
+  optional<Value>(token: Token<Value>): Value | undefined;
+
+  /**
+   * 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.
+   */
+  optionalAll<Instance extends object>(Class: Constructor<Instance>): Instance[];
+
+  /**
+   * 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.
+   */
+  optionalAll<Value>(token: Token<Value>): NonNullable<Value>[];
+}
+
+/**
+ * Injector token for dynamic injections.
+ *
+ * @example
+ * ```ts
+ * class Wizard {
+ *   private injector = inject(Injector);
+ *   private wand?: Wand;
+ *
+ *   getWand(): Wand {
+ *     return (this.wand ??= this.injector.inject(Wand));
+ *   }
+ * }
+ *
+ * const wizard = container.resolve(Wizard);
+ * wizard.getWand(); // => Wand
+ * ```
+ */
+export const Injector: Type<Injector> = /*@__PURE__*/ Build(function Injector() {
+  const context = ensureInjectionContext(Injector);
+  const resolution = context.resolution;
+
+  const dependentFrame = resolution.stack.peek();
+  const dependentRef = dependentFrame && resolution.dependents.get(dependentFrame.provider);
+
+  function withCurrentContext<R>(fn: () => R): R {
+    if (useInjectionContext()) {
+      return fn();
+    }
+
+    const cleanups = [
+      provideInjectionContext(context),
+      dependentFrame && resolution.stack.push(dependentFrame.provider, dependentFrame),
+      dependentRef && resolution.dependents.set(dependentFrame.provider, dependentRef),
+    ];
+
+    try {
+      return fn();
+    } finally {
+      for (const cleanup of cleanups) {
+        cleanup?.();
+      }
+    }
+  }
+
+  return {
+    inject: <T>(token: Token<T>) => withCurrentContext(() => inject(token)),
+    injectAll: <T>(token: Token<T>) => withCurrentContext(() => injectAll(token)),
+    optional: <T>(token: Token<T>) => withCurrentContext(() => optional(token)),
+    optionalAll: <T>(token: Token<T>) => withCurrentContext(() => optionalAll(token)),
+  };
+});

package/src/metadata.ts

@@ -0,0 +1,41 @@
+import type { ClassProvider } from "./provider";
+import type { Scope } from "./scope";
+import type { Constructor } from "./token";
+import type { Dependencies } from "./tokenRegistry";
+import type { TokensRef } from "./tokensRef";
+
+// @internal
+export interface Metadata<This extends object = any> {
+  autoRegister?: boolean;
+  scope?: Scope;
+  tokensRef: TokensRef<This>;
+  provider: ClassProvider<This>;
+  dependencies: Dependencies;
+}
+
+// @internal
+export function getMetadata<T extends object>(Class: Constructor<T>): Metadata<T> {
+  let metadata = metadataMap.get(Class);
+
+  if (!metadata) {
+    metadataMap.set(
+      Class,
+      (metadata = {
+        tokensRef: {
+          getRefTokens: () => new Set(),
+        },
+        provider: {
+          useClass: Class,
+        },
+        dependencies: {
+          constructor: [],
+          methods: new Map(),
+        },
+      }),
+    );
+  }
+
+  return metadata;
+}
+
+const metadataMap = new WeakMap<Constructor<object>, Metadata>();

package/src/middleware.ts

@@ -0,0 +1,85 @@
+import type { Container } from "./container";
+
+/**
+ * Composer API for middleware functions.
+ */
+export interface MiddlewareComposer {
+  /**
+   * Add a middleware function to the composer.
+   */
+  use<MethodKey extends keyof Container>(
+    key: MethodKey,
+    wrap: Container[MethodKey] extends Function
+      ? (next: Container[MethodKey]) => Container[MethodKey]
+      : never,
+  ): MiddlewareComposer;
+}
+
+/**
+ * Middleware function that can be used to extend the container.
+ *
+ * @example
+ * ```ts
+ * const logger: Middleware = (composer, _api) => {
+ *   composer
+ *     .use("resolve", (next) => (...args) => {
+ *       console.log("resolve", args);
+ *       return next(...args);
+ *     })
+ *     .use("resolveAll", (next) => (...args) => {
+ *       console.log("resolveAll", args);
+ *       return next(...args);
+ *     });
+ * };
+ * ```
+ */
+export interface Middleware {
+  (composer: MiddlewareComposer, api: Readonly<Container>): void;
+}
+
+/**
+ * Apply middleware functions to a container.
+ *
+ * Middlewares are applied in array order, but execute in reverse order.
+ *
+ * @example
+ * ```ts
+ * const container = applyMiddleware(
+ *   createContainer(),
+ *   [A, B],
+ * );
+ * ```
+ *
+ * The execution order will be:
+ *
+ * 1. B before
+ * 2. A before
+ * 3. original function
+ * 4. A after
+ * 5. B after
+ *
+ * This allows outer middlewares to wrap and control the behavior of inner middlewares.
+ */
+export function applyMiddleware(container: Container, middlewares: Middleware[]): Container {
+  const composer: MiddlewareComposer = {
+    use(key, wrap): MiddlewareComposer {
+      // We need to bind the 'this' context of the function to the container
+      // before passing it to the middleware wrapper.
+      //
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access,@typescript-eslint/no-unsafe-call
+      const fn = (container[key] as any).bind(container);
+
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+      container[key] = wrap(fn);
+      return composer;
+    },
+  };
+
+  const api = (container.api ||= { ...container });
+
+  for (const middleware of middlewares) {
+    middleware(composer, api);
+  }
+
+  return container;
+}

package/src/optional.ts

@@ -0,0 +1,65 @@
+import { ensureInjectionContext } from "./injectionContext";
+import type { Constructor, Token } from "./token";
+
+/**
+ * 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>): Instance | undefined;
+
+/**
+ * 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>): Value | undefined;
+
+export function optional<T>(token: Token<T>): T | undefined {
+  const context = ensureInjectionContext(optional);
+  return context.container.resolve(token, true);
+}
+
+/**
+ * Injects the instance associated with the given class,
+ * or `undefined` if the class is not registered in the container.
+ *
+ * Compared to {@link optional}, `optionalBy` accepts a `thisArg` argument
+ * (the containing class) which is used to resolve circular dependencies.
+ *
+ * @param thisArg - The containing instance, used to help resolve circular dependencies.
+ * @param Class - The class to resolve.
+ */
+export function optionalBy<Instance extends object>(
+  thisArg: any,
+  Class: Constructor<Instance>,
+): Instance | undefined;
+
+/**
+ * Injects the value associated with the given token,
+ * or `undefined` if the token is not registered in the container.
+ *
+ * Compared to {@link optional}, `optionalBy` accepts a `thisArg` argument
+ * (the containing class) which is used to resolve circular dependencies.
+ *
+ * @param thisArg - The containing instance, used to help resolve circular dependencies.
+ * @param token - The token to resolve.
+ */
+export function optionalBy<Value>(thisArg: any, token: Token<Value>): Value | undefined;
+
+export function optionalBy<T>(thisArg: any, token: Token<T>): T | undefined {
+  const context = ensureInjectionContext(optionalBy);
+  const resolution = context.resolution;
+  const currentFrame = resolution.stack.peek();
+
+  if (!currentFrame) {
+    return optional(token);
+  }
+
+  const currentRef = { current: thisArg };
+  const cleanup = resolution.dependents.set(currentFrame.provider, currentRef);
+
+  try {
+    return optional(token);
+  } finally {
+    cleanup();
+  }
+}

package/src/optionalAll.ts

@@ -0,0 +1,19 @@
+import { ensureInjectionContext } from "./injectionContext";
+import type { Constructor, Token } from "./token";
+
+/**
+ * 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>): Instance[];
+
+/**
+ * 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>): NonNullable<Value>[];
+
+export function optionalAll<T>(token: Token<T>): NonNullable<T>[] {
+  const context = ensureInjectionContext(optionalAll);
+  return context.container.resolveAll(token, true);
+}

package/src/provider.ts

@@ -0,0 +1,61 @@
+import type { Constructor, Token } from "./token";
+
+/**
+ * Provides a class instance for a token via a class constructor.
+ */
+export interface ClassProvider<Instance extends object> {
+  readonly useClass: Constructor<Instance>;
+}
+
+/**
+ * Provides a value for a token via another existing token.
+ */
+export interface ExistingProvider<Value> {
+  readonly useExisting: Token<Value>;
+}
+
+/**
+ * Provides a value for a token via a factory function.
+ *
+ * The factory function runs inside the injection context
+ * and can thus access dependencies via {@link inject}.
+ */
+export interface FactoryProvider<Value> {
+  readonly useFactory: (...args: []) => Value;
+}
+
+/**
+ * Provides a direct - already constructed - value for a token.
+ */
+export interface ValueProvider<T> {
+  readonly useValue: T;
+}
+
+/**
+ * A token provider.
+ */
+export type Provider<Value = any> =
+  | ClassProvider<Value & object>
+  | ExistingProvider<Value>
+  | FactoryProvider<Value>
+  | ValueProvider<Value>;
+
+// @internal
+export function isClassProvider<T>(provider: Provider<T>): provider is ClassProvider<T & object> {
+  return "useClass" in provider;
+}
+
+// @internal
+export function isExistingProvider<T>(provider: Provider<T>): provider is ExistingProvider<T> {
+  return "useExisting" in provider;
+}
+
+// @internal
+export function isFactoryProvider<T>(provider: Provider<T>): provider is FactoryProvider<T> {
+  return "useFactory" in provider;
+}
+
+// @internal
+export function isValueProvider<T>(provider: Provider<T>): provider is ValueProvider<T> {
+  return "useValue" in provider;
+}

package/src/scope.ts

@@ -0,0 +1,8 @@
+export const Scope = {
+  Inherited: "Inherited",
+  Transient: "Transient",
+  Resolution: "Resolution",
+  Container: "Container",
+} as const;
+
+export type Scope = (typeof Scope)[keyof typeof Scope];

package/src/token.ts

@@ -0,0 +1,84 @@
+/**
+ * Type API.
+ */
+export interface Type<A> {
+  /**
+   * Name of the type.
+   */
+  readonly name: string;
+
+  /**
+   * Create an intersection type from another type.
+   *
+   * @example
+   * ```ts
+   * const A = Type<A>("A");
+   * const B = Type<B>("B");
+   *
+   * A.inter("I", B); // => Type<A & B>
+   * ```
+   */
+  inter<B>(typeName: string, B: Type<B>): Type<A & B>;
+
+  /**
+   * Create a union type from another type.
+   *
+   * @example
+   * ```ts
+   * const A = Type<A>("A");
+   * const B = Type<B>("B");
+   *
+   * A.union("U", B); // => Type<A | B>
+   * ```
+   */
+  union<B>(typeName: string, B: Type<B>): Type<A | B>;
+}
+
+/**
+ * Constructor type.
+ */
+export interface Constructor<Instance extends object> {
+  new (...args: any[]): Instance;
+  readonly name: string;
+  readonly length: number;
+}
+
+/**
+ * Token type.
+ */
+export type Token<Value = any> = [Value] extends [object] // Avoids distributive union behavior
+  ? Type<Value> | Constructor<Value>
+  : Type<Value>;
+
+/**
+ * Describes a {@link Token} array with at least one element.
+ */
+export type Tokens<Value = any> = [Token<Value>, ...Token<Value>[]];
+
+/**
+ * Create a type token.
+ *
+ * @example
+ * ```ts
+ * const Spell = Type<Spell>("Spell");
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export function Type<T>(typeName: string): Type<T> {
+  const type = {
+    name: `Type<${typeName}>`,
+    inter: Type,
+    union: Type,
+    toString(): string {
+      return type.name;
+    },
+  };
+
+  return type;
+}
+
+// @internal
+export function isConstructor<T>(token: Type<T> | Constructor<T & object>): token is Constructor<T & object> {
+  return typeof token == "function";
+}

package/src/tokenRegistry.ts

@@ -0,0 +1,165 @@
+import { assert } from "./errors";
+import type { FactoryProvider, Provider } from "./provider";
+import { Scope } from "./scope";
+import { type Constructor, type Token, Type } from "./token";
+import type { TokenRef } from "./tokensRef";
+import { getTypeName } from "./utils/typeName";
+import type { ValueRef } from "./valueRef";
+
+/**
+ * Token registration options.
+ */
+export interface RegistrationOptions {
+  /**
+   * The scope of the registration.
+   */
+  readonly scope?: Scope;
+}
+
+// @internal
+export type Decorator = "Inject" | "InjectAll" | "Optional" | "OptionalAll";
+
+// @internal
+export interface MethodDependency {
+  readonly decorator: Decorator;
+  readonly tokenRef: TokenRef;
+
+  // The index of the annotated parameter (zero-based)
+  readonly index: number;
+}
+
+// @internal
+export interface Dependencies {
+  readonly constructor: MethodDependency[];
+  readonly methods: Map<string | symbol, MethodDependency[]>;
+}
+
+// @internal
+export interface Registration<T = any> {
+  value?: ValueRef<T>;
+  readonly provider: Provider<T>;
+  readonly options?: RegistrationOptions;
+  readonly dependencies?: Dependencies;
+}
+
+// @internal
+export class TokenRegistry {
+  private readonly myMap = new Map<Token, Registration[]>();
+
+  constructor(private readonly parent: TokenRegistry | undefined) {}
+
+  get<T>(token: Token<T>): Registration<T> | undefined {
+    // To clarify, at(-1) means we take the last added registration for this token
+    return this.getAll(token)?.at(-1);
+  }
+
+  getAll<T>(token: Token<T>): Registration<T>[] | undefined {
+    const internal = internals.get(token);
+    return (internal && [internal]) || this.getAllFromParent(token);
+  }
+
+  //
+  // set(...) overloads added because of TS distributive conditional types.
+  //
+  // TODO(Edoardo): is there a better way? Maybe refactor the Token<T> type
+  //  into two types, TokenObject<T extends object> | Token<T>
+  //
+
+  set<T extends object>(token: Type<T> | Constructor<T>, registration: Registration<T>): void;
+  set<T>(token: Token<T>, registration: Registration<T>): void;
+  set<T>(token: Token<T>, registration: Registration<T>): void {
+    assert(!internals.has(token), `cannot register reserved token ${token.name}`);
+
+    let registrations = this.myMap.get(token);
+
+    if (!registrations) {
+      this.myMap.set(token, (registrations = []));
+    }
+
+    registrations.push(registration);
+  }
+
+  delete<T>(token: Token<T>): Registration<T>[] | undefined {
+    const registrations = this.myMap.get(token);
+    this.myMap.delete(token);
+    return registrations;
+  }
+
+  deleteAll(): [Token[], Registration[]] {
+    const tokens = Array.from(this.myMap.keys());
+    const registrations = Array.from(this.myMap.values()).flat();
+    this.myMap.clear();
+    return [tokens, registrations];
+  }
+
+  clearRegistrations(): unknown[] {
+    const values = new Set<unknown>();
+
+    for (const registrations of this.myMap.values()) {
+      for (let i = 0; i < registrations.length; i++) {
+        const registration = registrations[i]!;
+        const value = registration.value;
+
+        if (value) {
+          values.add(value.current);
+        }
+
+        registrations[i] = {
+          ...registration,
+          value: undefined,
+        };
+      }
+    }
+
+    return Array.from(values);
+  }
+
+  private getAllFromParent<T>(token: Token<T>): Registration<T>[] | undefined {
+    const registrations = this.myMap.get(token);
+    return registrations || this.parent?.getAllFromParent(token);
+  }
+}
+
+// @internal
+export function isBuilder(provider: Provider): boolean {
+  return builders.has(provider);
+}
+
+/**
+ * Create a one-off type token from a factory function.
+ *
+ * @example
+ * ```ts
+ * class Wizard {
+ *   wand = inject(
+ *     Build(() => {
+ *       const wand = inject(Wand);
+ *       wand.owner = this;
+ *       // ...
+ *       return wand;
+ *     }),
+ *   );
+ * }
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export function Build<Value>(factory: (...args: []) => Value): Type<Value> {
+  const token = Type<Value>(`Build<${getTypeName(factory)}>`);
+  const provider: FactoryProvider<Value> = {
+    useFactory: factory,
+  };
+
+  internals.set(token, {
+    provider: provider,
+    options: {
+      scope: Scope.Transient,
+    },
+  });
+
+  builders.add(provider);
+  return token;
+}
+
+const internals = new WeakMap<Token, Registration>();
+const builders = new WeakSet<Provider>();