@codefast/di 0.5.0 → 0.6.0

package/src/index.ts

@@ -1,6 +1,7 @@
 // Foundation types
 export type {
   ActivationHandler,
+  BindingConstraint,
   BindingIdentifier,
   BindingKind,
   BindingScope,
@@ -13,11 +14,15 @@ export type {
   ResolveOptions,
   ResolutionContext,
   TokenValue,
-} from "#/types";
+} from "#/core/types";
 
 // Token
-export { token, tokenName, isToken } from "#/token";
-export type { Token } from "#/token";
+export { token, tokenName } from "#/core/token";
+export type { Token } from "#/core/token";
+
+// Tag — the interned slot criteria a `whenTagged` and a resolve both take
+export { coversTagKeys, NO_TAG_KEYS, tag, tagKeyMaskOf } from "#/core/tag";
+export type { TagKey, TagKeyMask } from "#/core/tag";
 
 // Binding builders — types only
 export type {
@@ -30,15 +35,24 @@ export type {
   SingletonLifecycleBuilder,
   SlotConstrainedBuilder,
   TransientBindingBuilder,
-} from "#/binding";
+} from "#/core/binding";
 
 // Container
 export { Container } from "#/container/container";
-export type { Container as ContainerInterface, ContainerStatic } from "#/container/container";
+export type { Container as ContainerInterface, ContainerOptions, ContainerStatic } from "#/container/container";
+
+// Ambient container — the context an `@inject` accessor initializer resolves from. `resolution/context`
+// stays internal: it hands out resolver callbacks, not public values.
+export { getActiveContainer, runWithContainer } from "#/ambient/active-container";
 
 // `effectiveBindingScope` is deliberately absent: it reads a `Binding`, which is internal, and no
 // public API hands one out. `BindingSnapshot.scope` and `GraphNode.scope` are the public answers.
-export { injectionSlotToResolveOptions, bindingSlotToResolveOptions } from "#/resolution/resolve-options";
+export {
+  bindingSlotToResolveOptions,
+  injectionSlotToResolveOptions,
+  resolveOptionsForSlot,
+} from "#/injection/resolve-options";
+export type { DependencySlot } from "#/injection/resolve-options";
 
 // Introspection types
 export type { BindingSnapshot, ContainerSnapshot } from "#/introspection/inspector";
@@ -47,12 +61,13 @@ export type { BindingSnapshot, ContainerSnapshot } from "#/introspection/inspect
 export type { ContainerGraphJson, GraphEdge, GraphNode, GraphOptions } from "#/introspection/dependency-graph";
 
 // Module
-export { AsyncModule, isSyncModule, Module, SyncModule } from "#/module";
-export type { AsyncModuleBuilder, ModuleBuilder } from "#/module";
+export { AsyncModule, isSyncModule, Module, SyncModule } from "#/core/module";
+export type { AsyncModuleBuilder, ModuleBuilder } from "#/core/module";
 
 // Decorators
-export { inject, injectAll, isInjectionDescriptor, optional } from "#/decorators/inject";
-export type { InjectionDescriptor, InjectOptions } from "#/decorators/inject";
+export { inject } from "#/decorators/inject";
+export { injectAll, isInjectionDescriptor, optional } from "#/injection/descriptor";
+export type { InjectionDescriptor, InjectOptions } from "#/injection/descriptor";
 export { injectable } from "#/decorators/injectable";
 export type { InjectableDependency, InjectableOptions } from "#/decorators/injectable";
 export { postConstruct, preDestroy } from "#/decorators/lifecycle-decorators";
@@ -61,9 +76,16 @@ export { postConstruct, preDestroy } from "#/decorators/lifecycle-decorators";
 export { createAutoRegisterRegistry } from "#/decorators/injectable";
 export type { AutoRegisterRegistry } from "#/decorators/injectable";
 
-// MetadataReader
+// MetadataReader — everything a consumer needs to write one and pass it to Container.create()
 export { MetadataReaderToken } from "#/metadata/metadata-reader-token";
-export type { MetadataReader, MutableLifecycleMetadata } from "#/metadata/metadata-types";
+export type {
+  ConstructorMetadata,
+  LifecycleMetadata,
+  MetadataReader,
+  MutableLifecycleMetadata,
+  ParamMetadata,
+} from "#/metadata/metadata-types";
+export { defaultMetadataReader, SymbolMetadataReader } from "#/metadata/symbol-metadata-reader";
 
 // Constraints — contextual injection predicates for .when()
 export {
@@ -77,7 +99,7 @@ export {
   whenParentNamed,
   whenParentTagged,
   whenParentTaggedAll,
-} from "#/resolution/constraints";
+} from "#/resolution/select/constraints";
 
 // Errors
 export {
@@ -91,6 +113,7 @@ export {
   DiError,
   DisposedContainerError,
   InternalError,
+  InvalidMetadataError,
   MissingContainerContextError,
   MissingMetadataError,
   MissingScopeContextError,
@@ -98,10 +121,14 @@ export {
   RebindUnboundTokenError,
   ScopeViolationError,
   SelfBindingRequiresClassError,
+  StaticMemberDecoratorError,
   SyncDisposalNotSupportedError,
+  EmptyTagCriteriaError,
   TokenNotBoundError,
-} from "#/errors";
-export type { ScopeViolationDetails } from "#/errors";
+  UnreachableConstraintError,
+  UnreachableLifecycleHookError,
+} from "#/errors/errors";
+export type { ScopeViolationDetails } from "#/errors/errors";
 
 // Graph adapters — render `generateDependencyGraph()` output for common viewers
 export { toDotGraph } from "#/introspection/graph-adapters/dot";
@@ -109,3 +136,4 @@ export { toCytoscapeGraph } from "#/introspection/graph-adapters/cytoscape";
 export type { CytoscapeEdge, CytoscapeElements, CytoscapeNode } from "#/introspection/graph-adapters/cytoscape";
 export { toReactFlowGraph } from "#/introspection/graph-adapters/reactflow";
 export type { ReactFlowEdge, ReactFlowGraph, ReactFlowNode } from "#/introspection/graph-adapters/reactflow";
+export { toMermaidGraph } from "#/introspection/graph-adapters/mermaid";

package/src/injection/descriptor.ts

@@ -0,0 +1,206 @@
+/** The one shape every declared dependency is normalised to, whatever channel declared it. */
+import type { Token } from "#/core/token";
+import type { BindingTag, Constructor, TokenValue } from "#/core/types";
+import type { DependencySlot } from "#/injection/resolve-options";
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface InjectOptions {
+  name?: string | undefined;
+  /**
+   * Single-tag shorthand, equivalent to listing the one pair in `tags`.
+   *
+   * @remarks Folded into `tags` when the descriptor is built, so nothing downstream sees two
+   * spellings of one request. Giving both is a request for every pair across the two.
+   */
+  tag?: BindingTag | undefined;
+  tags?: ReadonlyArray<BindingTag> | undefined;
+}
+
+/**
+ * One dependency a `toResolved` factory or an `@inject` accessor declares.
+ *
+ * @remarks Extends {@link DependencySlot} so the two dependency sources stay literally one shape,
+ * narrowing only `token` to carry the value type a factory's parameter is checked against.
+ *
+ * @since 0.3.16-canary.0
+ */
+export interface InjectionDescriptor<out Value = unknown> extends DependencySlot {
+  readonly token: Token<Value> | Constructor<Value>;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export type InjectableDependency<Value = unknown> = Token<Value> | Constructor<Value> | InjectionDescriptor<Value>;
+
+/**
+ * The value a factory receives for one declared dependency.
+ *
+ * @remarks `optional()` and `injectAll()` fold their effect into the descriptor's own type
+ * parameter, so reading it back is enough; bare tokens fall through to {@link TokenValue}.
+ *
+ * @since 0.5.0-canary.7
+ */
+export type ResolvedDependencyValue<Dependency> = Dependency extends { readonly multi: true }
+  ? Array<DescribedValue<Dependency>>
+  : Dependency extends { readonly optional: true }
+    ? DescribedValue<Dependency> | undefined
+    : DescribedValue<Dependency>;
+
+/**
+ * The value a dependency's own type parameter carries, before its flags are read.
+ *
+ * @remarks Split out because a hand-written descriptor states its flags and its value type
+ * separately, and only the flags are load-bearing: `{ token: Plugin, multi: true }` says `Plugin`
+ * and delivers `Array<Plugin>`. `injectAll()` and `optional()` already fold their effect in, so the
+ * flags find an array or an optional there and leave it alone.
+ */
+type DescribedValue<Dependency> = Dependency extends InjectionDescriptor<infer Value> ? Value : TokenValue<Dependency>;
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function isInjectionDescriptor(value: unknown): value is InjectionDescriptor {
+  if (value === null || value === undefined) {
+    return false;
+  }
+  const type = typeof value;
+  // inject() returns a function (dual-role), so must check both object and function
+  if (type !== "object" && type !== "function") {
+    return false;
+  }
+  return (
+    "token" in (value as object) &&
+    "optional" in (value as object) &&
+    "multi" in (value as object) &&
+    typeof (value as InjectionDescriptor).optional === "boolean" &&
+    typeof (value as InjectionDescriptor).multi === "boolean"
+  );
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function normalizeToDescriptor(dependency: InjectableDependency): InjectionDescriptor {
+  if (isInjectionDescriptor(dependency)) {
+    return materializeInjectionDescriptor(dependency);
+  }
+  return { token: dependency, optional: false, multi: false };
+}
+
+/**
+ * Dual-role `inject()` values are functions: [[Function]].name must not be treated as a DI slot name.
+ * Only enumerable own `name` / `tags` from `Object.defineProperties` are real injection options.
+ */
+function materializeInjectionDescriptor(dependency: InjectionDescriptor): InjectionDescriptor {
+  if (typeof dependency !== "function") {
+    return dependency;
+  }
+  const dualRole = dependency as InjectionDescriptor & ((...args: Array<unknown>) => unknown);
+  const base: Pick<InjectionDescriptor, "token" | "optional" | "multi"> = {
+    token: dualRole.token,
+    optional: dualRole.optional,
+    multi: dualRole.multi,
+  };
+  const nameDesc = Object.getOwnPropertyDescriptor(dualRole, "name");
+  const tagsDesc = Object.getOwnPropertyDescriptor(dualRole, "tags");
+  const explicitName = nameDesc?.enumerable === true && typeof nameDesc.value === "string" ? nameDesc.value : undefined;
+  // Annotated because `PropertyDescriptor.value` is `any`, and an `any` reaching the cast below
+  // would make it look checked when nothing checked it.
+  const explicitTags: unknown = tagsDesc?.enumerable === true ? tagsDesc.value : undefined;
+
+  if (explicitName !== undefined && explicitTags !== undefined) {
+    return {
+      ...base,
+      name: explicitName,
+      tags: explicitTags as NonNullable<InjectionDescriptor["tags"]>,
+    };
+  }
+  if (explicitName !== undefined) {
+    return { ...base, name: explicitName };
+  }
+  if (explicitTags !== undefined) {
+    return { ...base, tags: explicitTags as NonNullable<InjectionDescriptor["tags"]> };
+  }
+  return base;
+}
+
+/**
+ * The one tag list a request carries, with the single-tag shorthand folded in.
+ *
+ * @remarks Folding here is what keeps `tag` from reaching `InjectionDescriptor` and everything
+ * derived from it, so one request never has two spellings past this point.
+ */
+function requestedTagsOf(options: InjectOptions | undefined): ReadonlyArray<BindingTag> | undefined {
+  const shorthand = options?.tag;
+  const listed = options?.tags;
+  if (shorthand === undefined) {
+    return listed;
+  }
+  return listed === undefined || listed.length === 0 ? [shorthand] : [shorthand, ...listed];
+}
+
+function withOptions<DescValue>(
+  base: Pick<InjectionDescriptor<DescValue>, "token" | "optional" | "multi">,
+  options: InjectOptions | undefined,
+): InjectionDescriptor<DescValue> {
+  const tags = requestedTagsOf(options);
+  if (options?.name !== undefined && tags !== undefined) {
+    return { ...base, name: options.name, tags };
+  }
+  if (options?.name !== undefined) {
+    return { ...base, name: options.name };
+  }
+  if (tags !== undefined) {
+    return { ...base, tags };
+  }
+  return base;
+}
+
+/**
+ * The descriptor half of `inject()`, shared with the accessor decorator that wraps it.
+ *
+ * @since 0.6.0
+ */
+export function buildInjectionDescriptor<Value>(
+  token: Token<Value> | Constructor<Value>,
+  options?: InjectOptions,
+): InjectionDescriptor<Value> {
+  return withOptions({ token, optional: false, multi: false }, options);
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function optional<Value>(
+  token: Token<Value> | Constructor<Value>,
+  options?: InjectOptions,
+): InjectionDescriptor<Value | undefined> {
+  return withOptions(
+    {
+      token: token as Token<Value | undefined> | Constructor<Value | undefined>,
+      optional: true,
+      multi: false,
+    },
+    options,
+  );
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function injectAll<Value>(
+  token: Token<Value> | Constructor<Value>,
+  options?: InjectOptions,
+): InjectionDescriptor<Array<Value>> {
+  return withOptions(
+    {
+      token: token as Token<Array<Value>> | Constructor<Array<Value>>,
+      optional: false,
+      multi: true,
+    },
+    options,
+  );
+}

package/src/injection/resolve-options.ts

@@ -0,0 +1,144 @@
+import type { BindingTag } from "#/core/tag";
+import type { Token } from "#/core/token";
+import type { Constructor, ResolveOptions } from "#/core/types";
+
+/**
+ * What one resolvable dependency declares.
+ *
+ * @remarks Both dependency sources — a constructor's `ParamMetadata` and a `toResolved`
+ * `InjectionDescriptor` — are this shape, which is why one resolve routine serves both.
+ *
+ * @since 0.5.0-canary.9
+ */
+export interface DependencySlot {
+  readonly token: Token<unknown> | Constructor;
+  readonly optional: boolean;
+  readonly multi: boolean;
+  readonly name?: string | undefined;
+  readonly tags?: ReadonlyArray<BindingTag> | undefined;
+}
+
+/**
+ * A request whose only criterion is a name — the shape the registry has a direct index for.
+ *
+ * @since 0.5.0-canary.9
+ */
+export function isNameOnlyOptions(options: ResolveOptions): options is ResolveOptions & { name: string } {
+  return (
+    options.name !== undefined && options.tag === undefined && (options.tags === undefined || options.tags.length === 0)
+  );
+}
+
+/**
+ * The lone tag of a request that asks for exactly one, written either way — the shape the registry
+ * has a direct tag index for.
+ *
+ * @remarks Both spellings answer here, so the index is not something one of them silently misses.
+ *
+ * @since 0.5.0-canary.9
+ */
+export function singleTagOnlyOf(options: ResolveOptions): BindingTag | undefined {
+  if (options.name !== undefined) {
+    return undefined;
+  }
+  const listed = options.tags;
+  const shorthand = options.tag;
+  if (shorthand !== undefined) {
+    // Both sources present means the request carries two tags, which no single-tag index can answer.
+    return listed === undefined || listed.length === 0 ? shorthand : undefined;
+  }
+  return listed !== undefined && listed.length === 1 ? listed[0] : undefined;
+}
+
+/** Shared core: build a ResolveOptions from already-normalised name + tags. */
+function buildOptions(
+  name: string | undefined,
+  tags: ReadonlyArray<BindingTag> | undefined,
+): ResolveOptions | undefined {
+  if (name === undefined && tags === undefined) {
+    return undefined;
+  }
+  const options: ResolveOptions = {};
+  if (name !== undefined) {
+    options.name = name;
+  }
+  if (tags !== undefined) {
+    options.tags = tags;
+  }
+  return options;
+}
+
+/**
+ * Builds a {@link ResolveOptions} safe for `exactOptionalPropertyTypes`:
+ * omits keys instead of assigning `undefined`.
+ *
+ * @since 0.3.16-canary.0
+ */
+export function injectionSlotToResolveOptions(
+  injectionSlot: Pick<DependencySlot, "name" | "tags">,
+): ResolveOptions | undefined {
+  return buildOptions(injectionSlot.name, injectionSlot.tags);
+}
+
+/** Where a slot's derived options are memoized, so the same object is handed out every resolve. */
+const MEMOIZED_RESOLVE_OPTIONS: unique symbol = Symbol("di:resolve-options");
+
+interface SlotWithMemoizedOptions {
+  [MEMOIZED_RESOLVE_OPTIONS]?: ResolveOptions;
+}
+
+/**
+ * The options a dependency resolves with — one object per slot, since a slot's criteria are fixed
+ * when it is declared.
+ *
+ * @remarks A slot carrying no criterion answers from its two fields, so the common shape never
+ * reaches the memo.
+ *
+ * @since 0.6.0
+ */
+export function resolveOptionsForSlot(injectionSlot: DependencySlot): ResolveOptions | undefined {
+  const { name, tags } = injectionSlot;
+  if (name === undefined && tags === undefined) {
+    return undefined;
+  }
+  const slot = injectionSlot as SlotWithMemoizedOptions;
+  const memoized = slot[MEMOIZED_RESOLVE_OPTIONS];
+  return memoized ?? memoizeResolveOptions(slot, name, tags);
+}
+
+/**
+ * Builds, freezes and stores a slot's options on first use.
+ *
+ * @remarks Frozen because one object answers every resolve of the slot and a constraint predicate is
+ * handed it. Split out for the `try`: in the caller it would cost the early return its inlining.
+ */
+function memoizeResolveOptions(
+  slot: SlotWithMemoizedOptions,
+  name: string | undefined,
+  tags: ReadonlyArray<BindingTag> | undefined,
+): ResolveOptions {
+  const built = Object.freeze(buildOptions(name, tags) as ResolveOptions);
+  try {
+    slot[MEMOIZED_RESOLVE_OPTIONS] = built;
+  } catch {
+    // A frozen slot rebuilds on every hop rather than throwing.
+  }
+  return built;
+}
+
+/**
+ * Resolve options derived from a binding slot (tags may be empty; omits when nothing to match).
+ *
+ * @remarks Takes the slot structurally rather than as `BindingSlot`, so the slot on a public
+ * `BindingSnapshot` — where `name` is an optional property, not a required one holding `undefined` —
+ * is accepted by the same call.
+ *
+ * @since 0.3.16-canary.0
+ */
+export function bindingSlotToResolveOptions(bindingSlot: {
+  readonly name?: string | undefined;
+  readonly tags?: ReadonlyArray<BindingTag> | undefined;
+}): ResolveOptions | undefined {
+  const tags = bindingSlot.tags;
+  return buildOptions(bindingSlot.name, tags !== undefined && tags.length > 0 ? tags : undefined);
+}