@codefast/di 0.7.1 → 0.8.1

package/src/core/types.ts

@@ -1,149 +0,0 @@
-import type { Constructor } from "#/core/constructor-type";
-import type { BindingTag, TagKeyMask } from "#/core/tag";
-import type { Token } from "#/core/token";
-
-// Re-export for consumers that import from `#/types`
-export type { Constructor } from "#/core/constructor-type";
-export type { BindingTag, TagKey, TagKeyMask } from "#/core/tag";
-
-/**
- * Token or class constructor used as a binding / injection / resolve key.
- *
- * @since 0.3.16-canary.0
- */
-export type DependencyKey = Token<unknown> | Constructor;
-
-// ── BindingScope ─────────────────────────────────────────────────────────────────────────────────────────────────────
-
-/**
- * The lifetime a binding's instances are cached under.
- *
- * @since 0.3.16-canary.0
- */
-export type BindingScope = "singleton" | "transient" | "scoped";
-
-// ── BindingIdentifier ────────────────────────────────────────────────────────────────────────────────────────────────
-
-declare const BINDING_ID_BRAND: unique symbol;
-/**
- * A branded string that uniquely identifies one binding.
- *
- * @since 0.3.16-canary.0
- */
-export type BindingIdentifier = string & { readonly [BINDING_ID_BRAND]: true };
-
-// ── BindingKind ──────────────────────────────────────────────────────────────────────────────────────────────────────
-
-/**
- * The strategy a binding produces values with, set by the `to*()` call that created it.
- *
- * @since 0.3.16-canary.0
- */
-export type BindingKind = "class" | "dynamic" | "dynamic-async" | "resolved" | "resolved-async" | "constant" | "alias";
-
-// ── Handlers ─────────────────────────────────────────────────────────────────────────────────────────────────────────
-
-/**
- * A hook that runs after an instance is created and returns the instance to hand out.
- *
- * @since 0.3.16-canary.0
- */
-export type ActivationHandler<Value> = (ctx: ResolutionContext, instance: Value) => Value | Promise<Value>;
-
-/**
- * A hook that runs when a cached instance is released from its scope.
- *
- * @since 0.3.16-canary.0
- */
-export type DeactivationHandler<Value> = (instance: Value) => void | Promise<void>;
-
-// ── ResolveOptions ───────────────────────────────────────────────────────────────────────────────────────────────────
-
-/**
- * Slot-selection criteria — a name and tags — that narrow which binding a resolve call matches.
- *
- * @since 0.3.16-canary.0
- */
-export interface ResolveOptions {
-  name?: string | undefined;
-  /**
-   * Single-tag shorthand, equivalent to listing the one pair in `tags`.
-   *
-   * @remarks Reaches the same tagged index, so choosing it costs nothing. `InjectOptions` accepts it
-   * too and folds it into `tags`. Only `tags` expresses a request for more than one tag.
-   */
-  tag?: BindingTag | undefined;
-  tags?: ReadonlyArray<BindingTag> | undefined;
-}
-
-// ── ResolutionFrame ──────────────────────────────────────────────────────────────────────────────────────────────────
-
-/**
- * One entry of the resolution stack: the token, scope, binding, and slot being resolved.
- *
- * @since 0.3.16-canary.0
- */
-export interface ResolutionFrame {
-  readonly tokenName: string;
-  readonly scope: BindingScope;
-  readonly bindingId: BindingIdentifier;
-  readonly kind: BindingKind;
-  readonly slot: {
-    readonly name: string | undefined;
-    readonly tags: ReadonlyArray<BindingTag>;
-    readonly keyMask: TagKeyMask;
-  };
-}
-
-// ── ConstraintContext ────────────────────────────────────────────────────────────────────────────────────────────────
-
-/**
- * The resolution-time view — path, stack, parent, and ancestors — a `BindingConstraint` inspects.
- *
- * @since 0.3.16-canary.0
- */
-export interface ConstraintContext {
-  readonly resolutionPath: ReadonlyArray<string>;
-  readonly resolutionStack: ReadonlyArray<ResolutionFrame>;
-  readonly parent: ResolutionFrame | undefined;
-  readonly ancestors: ReadonlyArray<ResolutionFrame>;
-  /** Readonly because one frozen object answers every resolve of a slot — a write would throw. */
-  readonly currentResolveOptions: Readonly<ResolveOptions> | undefined;
-}
-
-/**
- * The predicate `when()` selects a binding by, and the shape every `when*` helper returns.
- *
- * @since 0.6.0
- */
-export type BindingConstraint = (ctx: ConstraintContext) => boolean;
-
-// ── ResolutionContext ────────────────────────────────────────────────────────────────────────────────────────────────
-
-/**
- * The container view a dynamic factory or activation handler resolves further dependencies through.
- *
- * @since 0.3.16-canary.0
- */
-export interface ResolutionContext {
-  resolve<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value;
-  resolveAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value>;
-  resolveOptional<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value | undefined;
-  resolveOptionalAsync<Value>(
-    token: Token<Value> | Constructor<Value>,
-    options?: ResolveOptions,
-  ): Promise<Value | undefined>;
-  resolveAll<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Array<Value>;
-  resolveAllAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Array<Value>>;
-  readonly graph: ConstraintContext;
-}
-
-// ── TokenValue ───────────────────────────────────────────────────────────────────────────────────────────────────────
-
-/**
- * The value type a token or class constructor resolves to.
- *
- * @since 0.3.16-canary.0
- */
-export type TokenValue<Type> =
-  Type extends Token<infer Value> ? Value : Type extends Constructor<infer Value> ? Value : never;

package/src/decorators/inject.ts

@@ -1,101 +0,0 @@
-import { getActiveContainer, getAmbientResolution } from "#/ambient/active-container";
-/** `@inject` — the accessor-decorator channel, resolving from the ambient container. */
-import type { Token } from "#/core/token";
-import type { Constructor } from "#/core/types";
-import { MissingContainerContextError, StaticMemberDecoratorError } from "#/errors/errors";
-import type { InjectionDescriptor, InjectOptions } from "#/injection/descriptor";
-import { buildInjectionDescriptor } from "#/injection/descriptor";
-import { injectionSlotToResolveOptions } from "#/injection/resolve-options";
-import { INJECT_ACCESSOR_KEY } from "#/metadata/metadata-keys";
-
-/**
- * The name of the class being constructed, or `undefined` when there is none to report.
- *
- * @remarks Two ways there is none: an anonymous class expression has an empty `name`, and an
- * instance whose prototype chain answers no `constructor` has nothing to read. Narrowed rather than
- * asserted — the value arrives as `unknown` and the platform makes no promise about it.
- */
-function classNameOf(instance: unknown): string | undefined {
-  if (typeof instance !== "object" || instance === null) {
-    return undefined;
-  }
-  const constructor: unknown = Reflect.get(instance, "constructor");
-  if (typeof constructor !== "function" || constructor.name === "") {
-    return undefined;
-  }
-
-  return constructor.name;
-}
-
-// ── inject() — dual-role ─────────────────────────────────────────────────────────────────────────────────────────────
-
-type ClassAccessorDecorator<This, Value> = (
-  target: ClassAccessorDecoratorTarget<This, Value>,
-  context: ClassAccessorDecoratorContext<This, Value>,
-) => ClassAccessorDecoratorResult<This, Value> | void;
-
-/**
- * Creates a dual-role value: an injection descriptor that also works as a class accessor decorator.
- *
- * @since 0.3.16-canary.0
- */
-export function inject<Value>(
-  token: Token<Value> | Constructor<Value>,
-  options?: InjectOptions,
-): InjectionDescriptor<Value> & ClassAccessorDecorator<unknown, Value> {
-  const descriptor = buildInjectionDescriptor(token, options);
-  // Derived from the descriptor, not from `options`: the descriptor is where the tag shorthand has
-  // already been folded. Built once here rather than per constructed instance.
-  const resolveOptions = injectionSlotToResolveOptions(descriptor);
-
-  const decoratorFn = (
-    _target: ClassAccessorDecoratorTarget<unknown, Value>,
-    context: ClassAccessorDecoratorContext<unknown, Value>,
-  ): ClassAccessorDecoratorResult<unknown, Value> => {
-    if (context.static) {
-      throw new StaticMemberDecoratorError("inject", String(context.name));
-    }
-    const meta = context.metadata as Record<string | symbol, unknown>;
-    // Own bucket only: the metadata record inherits the base class's, and pushing into an inherited
-    // array would register this accessor on the base class instead.
-    if (!Object.hasOwn(meta, INJECT_ACCESSOR_KEY) || !Array.isArray(meta[INJECT_ACCESSOR_KEY])) {
-      meta[INJECT_ACCESSOR_KEY] = [];
-    }
-    (meta[INJECT_ACCESSOR_KEY] as Array<{ key: string | symbol; descriptor: InjectionDescriptor }>).push({
-      key: context.name,
-      descriptor,
-    });
-
-    context.addInitializer(function (this: unknown) {
-      // Prefer the engine's path-continuing resolver: it keeps this accessor's dependencies on the
-      // live resolution path, so a cycle through an accessor is detected instead of recursing.
-      const ambient = getAmbientResolution();
-      if (ambient !== undefined) {
-        const value = descriptor.optional
-          ? ambient.resolveOptional(token, resolveOptions)
-          : ambient.resolve(token, resolveOptions);
-        context.access.set(this, value as Value);
-        return;
-      }
-      const container = getActiveContainer();
-      if (container === undefined) {
-        throw new MissingContainerContextError(classNameOf(this), context.name);
-      }
-      const value = descriptor.optional
-        ? container.resolveOptional(token, resolveOptions)
-        : container.resolve(token, resolveOptions);
-      context.access.set(this, value as Value);
-    });
-
-    return {};
-  };
-
-  // Use defineProperties to handle read-only `name` property of functions
-  const props: PropertyDescriptorMap = {};
-  for (const key of Object.keys(descriptor) as Array<keyof typeof descriptor>) {
-    props[key] = { value: descriptor[key], writable: true, enumerable: true, configurable: true };
-  }
-  Object.defineProperties(decoratorFn, props);
-
-  return decoratorFn as InjectionDescriptor<Value> & ClassAccessorDecorator<unknown, Value>;
-}

package/src/decorators/injectable.ts

@@ -1,134 +0,0 @@
-import type { BindingScope, Constructor } from "#/core/types";
-import type { InjectableDependency, ResolvedDependencyValue } from "#/injection/descriptor";
-import { normalizeToDescriptor } from "#/injection/descriptor";
-import { INJECTABLE_KEY } from "#/metadata/metadata-keys";
-import type { ParamMetadata } from "#/metadata/metadata-types";
-
-// ── AutoRegisterRegistry ─────────────────────────────────────────────────────────────────────────────────────────────
-
-/**
- * The collector `@injectable` registers a class into, for a container to bind later.
- *
- * @since 0.3.16-canary.0
- */
-export interface AutoRegisterRegistry {
-  register(target: Constructor, scope: BindingScope): void;
-  entries(): ReadonlyArray<{ target: Constructor; scope: BindingScope }>;
-}
-
-/**
- * Creates an empty auto-register registry.
- *
- * @since 0.3.16-canary.0
- */
-export function createAutoRegisterRegistry(): AutoRegisterRegistry {
-  const registeredEntries: Array<{ target: Constructor; scope: BindingScope }> = [];
-  return {
-    register(target: Constructor, scope: BindingScope): void {
-      registeredEntries.push({ target, scope });
-    },
-    entries(): ReadonlyArray<{ target: Constructor; scope: BindingScope }> {
-      return registeredEntries;
-    },
-  };
-}
-
-// ── InjectableOptions ────────────────────────────────────────────────────────────────────────────────────────────────
-
-/**
- * Auto-registration options `@injectable` accepts alongside its deps list.
- *
- * @since 0.3.16-canary.0
- */
-export interface InjectableOptions {
-  autoRegister?: AutoRegisterRegistry | undefined;
-  scope?: BindingScope | undefined;
-}
-
-// ── @injectable() ────────────────────────────────────────────────────────────────────────────────────────────────────
-
-/**
- * The parameters a constructor is handed, given what its `deps` declare.
- *
- * @remarks Reuses the same reading a `toResolved` factory gets, so `injectAll` arrives as an array
- * and `optional` as possibly undefined in both places.
- */
-type InjectedParameters<Deps extends ReadonlyArray<InjectableDependency>> = {
-  -readonly [Index in keyof Deps]: ResolvedDependencyValue<Deps[Index]>;
-};
-
-/**
- * Declare a class injectable, and what its constructor is to be handed.
- *
- * @since 0.3.16-canary.0
- */
-export function injectable(): (target: unknown, context: ClassDecoratorContext) => void;
-
-/**
- * @remarks Declaring dependencies constrains the class: the decorator only accepts one whose
- * constructor takes exactly what `deps` resolve to, in that order — including arity, so a literal
- * deps list longer than the constructor is a compile error rather than a resolved-and-discarded
- * value. Optional trailing parameters admit every arity they declare, and a rest parameter admits
- * any list. A deps *array* — one whose length the compiler cannot know — skips the arity check,
- * which is also the deliberate spelling for declaring more dependencies than the constructor
- * takes, e.g. for the dependency graph's edges.
- *
- * @since 0.3.16-canary.0
- */
-export function injectable<const Deps extends ReadonlyArray<InjectableDependency>>(
-  deps: Deps,
-  options?: InjectableOptions,
-): <Target extends abstract new (...args: InjectedParameters<Deps>) => unknown>(
-  target: Target &
-    (number extends Deps["length"]
-      ? unknown
-      : Deps["length"] extends ConstructorParameters<Target>["length"]
-        ? unknown
-        : never),
-  context: ClassDecoratorContext,
-) => void;
-
-/**
- * Writes the declared dependencies into the class's metadata and optionally auto-registers it.
- *
- * @since 0.6.0
- */
-export function injectable(
-  deps?: ReadonlyArray<InjectableDependency>,
-  options?: InjectableOptions,
-): (target: never, context: ClassDecoratorContext) => void {
-  return function (target: never, context: ClassDecoratorContext): void {
-    const parameterMetadataList: Array<ParamMetadata> = (deps ?? []).map((dependency, index) => {
-      const descriptor = normalizeToDescriptor(dependency);
-      const baseParameterMetadata: Pick<ParamMetadata, "index" | "token" | "optional" | "multi"> = {
-        index,
-        token: descriptor.token,
-        optional: descriptor.optional,
-        multi: descriptor.multi,
-      };
-      if (descriptor.name !== undefined && descriptor.tags !== undefined) {
-        return { ...baseParameterMetadata, name: descriptor.name, tags: descriptor.tags };
-      }
-      if (descriptor.name !== undefined) {
-        return { ...baseParameterMetadata, name: descriptor.name };
-      }
-      if (descriptor.tags !== undefined) {
-        return { ...baseParameterMetadata, tags: descriptor.tags };
-      }
-      return baseParameterMetadata;
-    });
-
-    // Field decorators run before the class decorator — accessor @inject entries are
-    // already on context.metadata by the time this runs.
-    (context.metadata as Record<string | symbol, unknown>)[INJECTABLE_KEY] = {
-      params: parameterMetadataList,
-    };
-
-    if (options?.autoRegister !== undefined) {
-      const scope: BindingScope = options.scope ?? "transient";
-      options.autoRegister.register(target as Constructor, scope);
-    }
-  };
-}
-
-export type { InjectableDependency };

package/src/decorators/lifecycle-decorators.ts

@@ -1,43 +0,0 @@
-import { StaticMemberDecoratorError } from "#/errors/errors";
-import { LIFECYCLE_KEY } from "#/metadata/metadata-keys";
-import type { MutableLifecycleMetadata } from "#/metadata/metadata-types";
-
-type MethodDecorator = (target: unknown, context: ClassMethodDecoratorContext) => void;
-
-/** Records the decorated method under one lifecycle phase; both decorators differ only in that phase. */
-function recordLifecycleMethod(phase: "postConstruct" | "preDestroy"): MethodDecorator {
-  return function (target: unknown, context: ClassMethodDecoratorContext): void {
-    if (context.static) {
-      throw new StaticMemberDecoratorError(phase, String(context.name));
-    }
-    const meta = context.metadata as Record<string | symbol, unknown>;
-    // Own bucket only: `context.metadata` inherits the base class's record, and writing through an
-    // inherited bucket would register this hook on the base class instead.
-    if (!Object.hasOwn(meta, LIFECYCLE_KEY)) {
-      meta[LIFECYCLE_KEY] = { postConstruct: [], preDestroy: [] };
-    }
-    const lifecycle = meta[LIFECYCLE_KEY] as MutableLifecycleMetadata;
-    const methodName = String(context.name);
-    if (!lifecycle[phase].includes(methodName)) {
-      lifecycle[phase].push(methodName);
-    }
-  };
-}
-
-/**
- * Marks an instance method to run after the container constructs and wires the instance.
- *
- * @since 0.3.16-canary.0
- */
-export function postConstruct(): MethodDecorator {
-  return recordLifecycleMethod("postConstruct");
-}
-
-/**
- * Marks an instance method to run when the instance's container or scope is disposed.
- *
- * @since 0.3.16-canary.0
- */
-export function preDestroy(): MethodDecorator {
-  return recordLifecycleMethod("preDestroy");
-}

package/src/errors/diagnostics.ts

@@ -1,45 +0,0 @@
-/**
- * Internal seam letting tests assert that an optimization is *active*, not merely that the result
- * is correct.
- *
- * @remarks Timing belongs in the benchmark, which needs a quiet machine and twenty minutes; these
- * are structural counts, so CI can hold the invariants that make the benchmark fast. Reached
- * through a symbol from a module the package does not publish, so it is not public API.
- */
-
-/**
- * Key for the diagnostics accessor on a container.
- *
- * @remarks A symbol rather than a method name, so it cannot collide with the public surface or be
- * reached by anyone who has not imported this module.
- *
- * @since 0.5.0-canary.8
- */
-export const RESOLUTION_DIAGNOSTICS: unique symbol = Symbol("di:resolution-diagnostics");
-
-/**
- * Structural facts about a container's resolution caches.
- *
- * @since 0.5.0-canary.8
- */
-export interface ResolutionDiagnostics {
-  /** Bindings with a compiled instantiation plan. */
-  readonly compiledPlanCount: number;
-  /** Bindings with a compiled async instantiation plan. */
-  readonly compiledAsyncPlanCount: number;
-  /** Contexts held by the depth-indexed sync pool. */
-  readonly syncContextPoolSize: number;
-  /** Scoped instances currently cached by this container's scope manager. */
-  readonly scopedInstanceCount: number;
-  /** Deferred collaborators this container has had to build. */
-  readonly builtSubsystems: ReadonlyArray<string>;
-}
-
-/**
- * A container that can report on its resolution caches.
- *
- * @since 0.5.0-canary.8
- */
-export interface DiagnosableContainer {
-  [RESOLUTION_DIAGNOSTICS](): ResolutionDiagnostics;
-}