@codefast/di 0.3.16-canary.2 → 0.4.0-canary.4

package/src/errors.ts

@@ -0,0 +1,260 @@
+import type { BindingIdentifier, BindingScope, ResolveOptions } from "#/types";
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export abstract class DiError extends Error {
+  abstract readonly code: string;
+
+  constructor(message: string) {
+    super(message);
+    this.name = this.constructor.name;
+  }
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export class InternalError extends DiError {
+  readonly code = "INTERNAL_ERROR";
+
+  constructor(message: string) {
+    super(message);
+  }
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export class TokenNotBoundError extends DiError {
+  readonly code = "TOKEN_NOT_BOUND";
+  readonly tokenName: string;
+
+  constructor(tokenName: string) {
+    super(`No binding found for token '${tokenName}'. Did you forget container.bind(${tokenName})?`);
+    this.tokenName = tokenName;
+  }
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export class NoMatchingBindingError extends DiError {
+  readonly code = "NO_MATCHING_BINDING";
+  readonly tokenName: string;
+  readonly hint: ResolveOptions;
+  readonly availableSlots: Array<string>;
+
+  constructor(tokenName: string, hint: ResolveOptions, availableSlots: Array<string>) {
+    const hintStr = JSON.stringify(hint);
+    const slotsStr = availableSlots.join(", ");
+    super(`No binding for '${tokenName}' matching ${hintStr}. Available slots: [${slotsStr}].`);
+    this.tokenName = tokenName;
+    this.hint = hint;
+    this.availableSlots = availableSlots;
+  }
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export class AmbiguousBindingError extends DiError {
+  readonly code = "AMBIGUOUS_BINDING";
+  readonly tokenName: string;
+  readonly candidateIds: ReadonlyArray<BindingIdentifier>;
+
+  constructor(tokenName: string, candidateIds: ReadonlyArray<BindingIdentifier>) {
+    super(
+      `Multiple bindings for '${tokenName}' matched without a clear winner. Candidates: [${candidateIds.join(", ")}]. Ensure when() predicates are mutually exclusive.`,
+    );
+    this.tokenName = tokenName;
+    this.candidateIds = candidateIds;
+  }
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export class CircularDependencyError extends DiError {
+  readonly code = "CIRCULAR_DEPENDENCY";
+  readonly cycle: Array<string>;
+
+  constructor(cycle: Array<string>) {
+    super(`Circular dependency detected: ${cycle.join(" → ")}`);
+    this.cycle = cycle;
+  }
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export class AsyncResolutionError extends DiError {
+  readonly code = "ASYNC_RESOLUTION";
+  readonly tokenName: string;
+  readonly asyncSourceToken: string;
+
+  constructor(tokenName: string, asyncSourceToken: string) {
+    super(
+      `Token '${tokenName}' requires async resolution because '${asyncSourceToken}' in its dependency chain has an async factory. Use container.resolveAsync(${tokenName}).`,
+    );
+    this.tokenName = tokenName;
+    this.asyncSourceToken = asyncSourceToken;
+  }
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export class AsyncDeactivationError extends DiError {
+  readonly code = "ASYNC_DEACTIVATION";
+  readonly tokenName: string;
+
+  constructor(tokenName: string) {
+    super(`Token '${tokenName}' has an async onDeactivation handler. Use unbindAsync() instead.`);
+    this.tokenName = tokenName;
+  }
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface ScopeViolationDetails {
+  readonly consumerToken: string;
+  readonly consumerScope: BindingScope;
+  readonly dependencyToken: string;
+  readonly dependencyScope: BindingScope;
+  readonly path: Array<string>;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export class ScopeViolationError extends DiError {
+  readonly code = "SCOPE_VIOLATION";
+  readonly details: ScopeViolationDetails;
+
+  constructor(details: ScopeViolationDetails) {
+    super(
+      `Scope violation: '${details.consumerToken}' (${details.consumerScope}) depends on '${details.dependencyToken}' (${details.dependencyScope}). Path: ${details.path.join(" → ")}`,
+    );
+    this.details = details;
+  }
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export class MissingMetadataError extends DiError {
+  readonly code = "MISSING_METADATA";
+  readonly targetName: string;
+
+  constructor(targetName: string) {
+    super(
+      `Class '${targetName}' is missing @injectable() decorator. Add @injectable([...deps]) or use toDynamic()/toResolved() instead.`,
+    );
+    this.targetName = targetName;
+  }
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export class AsyncModuleLoadError extends DiError {
+  readonly code = "ASYNC_MODULE_LOAD";
+  readonly moduleName: string;
+
+  constructor(moduleName: string) {
+    super(`Module '${moduleName}' is async. Use container.loadAsync() instead.`);
+    this.moduleName = moduleName;
+  }
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export class SyncDisposalNotSupportedError extends DiError {
+  readonly code = "SYNC_DISPOSAL_NOT_SUPPORTED";
+
+  constructor() {
+    super(
+      "Container cannot be disposed synchronously because onDeactivation handlers may be async. Use `await using` or call container.dispose() explicitly.",
+    );
+  }
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export class MissingScopeContextError extends DiError {
+  readonly code = "MISSING_SCOPE_CONTEXT";
+  readonly tokenName: string;
+
+  constructor(tokenName: string) {
+    super(
+      `Token '${tokenName}' is scoped but was resolved from a container without a child scope context. Use container.createChild() to create a scoped context.`,
+    );
+    this.tokenName = tokenName;
+  }
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export class MissingContainerContextError extends DiError {
+  readonly code = "MISSING_CONTAINER_CONTEXT";
+  readonly targetName: string;
+
+  constructor(targetName: string) {
+    super(
+      `Class '${targetName}' has @inject accessor fields but was instantiated outside a container context. Resolve it via container.resolve(${targetName}) instead.`,
+    );
+    this.targetName = targetName;
+  }
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export class RebindUnboundTokenError extends DiError {
+  readonly code = "REBIND_UNBOUND_TOKEN";
+  readonly tokenName: string;
+
+  constructor(tokenName: string) {
+    super(
+      `Cannot rebind token '${tokenName}' because it has no own binding in this container. Use container.bind(${tokenName}) to create a new binding instead.`,
+    );
+    this.tokenName = tokenName;
+  }
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export class DisposedContainerError extends DiError {
+  readonly code = "DISPOSED_CONTAINER";
+
+  constructor() {
+    super("Cannot perform operations on a disposed container.");
+  }
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export class AsyncActivationError extends DiError {
+  readonly code = "ASYNC_ACTIVATION";
+  readonly tokenName: string;
+  readonly hookKind: "postConstruct" | "onActivation";
+  readonly methodName: string | undefined;
+
+  constructor(tokenName: string, hookKind: "postConstruct" | "onActivation", methodName?: string) {
+    const detail =
+      hookKind === "postConstruct"
+        ? `@postConstruct method '${methodName ?? ""}' returned a Promise`
+        : `onActivation for '${tokenName}' returned a Promise`;
+    super(`${detail}. Use resolveAsync() instead.`);
+    this.tokenName = tokenName;
+    this.hookKind = hookKind;
+    this.methodName = methodName;
+  }
+}

package/src/graph-adapters/cytoscape.ts

@@ -0,0 +1,64 @@
+import type { ContainerGraphJson } from "#/dependency-graph";
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface CytoscapeNode {
+  readonly data: {
+    readonly id: string;
+    readonly label: string;
+    readonly kind: string;
+    readonly scope: string;
+    readonly fromParent: boolean;
+  };
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface CytoscapeEdge {
+  readonly data: {
+    readonly id: string;
+    readonly source: string;
+    readonly target: string;
+    readonly label?: string;
+  };
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export type CytoscapeElements = ReadonlyArray<CytoscapeNode | CytoscapeEdge>;
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function toCytoscapeGraph(graph: ContainerGraphJson): CytoscapeElements {
+  const elements: Array<CytoscapeNode | CytoscapeEdge> = [];
+
+  for (const node of graph.nodes) {
+    elements.push({
+      data: {
+        id: node.id,
+        label: node.tokenName,
+        kind: node.kind,
+        scope: node.scope,
+        fromParent: node.fromParent,
+      },
+    });
+  }
+
+  for (let idx = 0; idx < graph.edges.length; idx += 1) {
+    const edge = graph.edges[idx]!;
+    elements.push({
+      data: {
+        id: `edge-${idx}`,
+        source: edge.from,
+        target: edge.to,
+        ...(edge.label !== undefined ? { label: edge.label } : {}),
+      },
+    });
+  }
+
+  return elements;
+}

package/src/graph-adapters/dot.ts

@@ -0,0 +1,22 @@
+import type { ContainerGraphJson } from "#/dependency-graph";
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function toDotGraph(graph: ContainerGraphJson): string {
+  const lines: Array<string> = ["digraph DI {", "  rankdir=TB;"];
+
+  for (const node of graph.nodes) {
+    const label = `${node.tokenName}\\n[${node.kind}/${node.scope}]`;
+    const style = node.fromParent ? ' style="dashed"' : "";
+    lines.push(`  "${node.id}" [label="${label}"${style}];`);
+  }
+
+  for (const edge of graph.edges) {
+    const label = edge.label !== undefined ? ` [label="${edge.label}"]` : "";
+    lines.push(`  "${edge.from}" -> "${edge.to}"${label};`);
+  }
+
+  lines.push("}");
+  return lines.join("\n");
+}

package/src/graph-adapters/reactflow.ts

@@ -0,0 +1,58 @@
+import type { ContainerGraphJson } from "#/dependency-graph";
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface ReactFlowNode {
+  readonly id: string;
+  readonly data: {
+    readonly label: string;
+    readonly kind: string;
+    readonly scope: string;
+    readonly fromParent: boolean;
+  };
+  readonly position: { readonly x: number; readonly y: number };
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface ReactFlowEdge {
+  readonly id: string;
+  readonly source: string;
+  readonly target: string;
+  readonly label?: string;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface ReactFlowGraph {
+  readonly nodes: ReadonlyArray<ReactFlowNode>;
+  readonly edges: ReadonlyArray<ReactFlowEdge>;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function toReactFlowGraph(graph: ContainerGraphJson): ReactFlowGraph {
+  const nodes: Array<ReactFlowNode> = graph.nodes.map((node, idx) => ({
+    id: node.id,
+    data: {
+      label: node.tokenName,
+      kind: node.kind,
+      scope: node.scope,
+      fromParent: node.fromParent,
+    },
+    position: { x: (idx % 5) * 200, y: Math.floor(idx / 5) * 100 },
+  }));
+
+  const edges: Array<ReactFlowEdge> = graph.edges.map((edge, idx) => ({
+    id: `edge-${idx}`,
+    source: edge.from,
+    target: edge.to,
+    ...(edge.label !== undefined ? { label: edge.label } : {}),
+  }));
+
+  return { nodes, edges };
+}

package/src/index.ts

@@ -0,0 +1,101 @@
+// Foundation types
+export type {
+  ActivationHandler,
+  BindingIdentifier,
+  BindingKind,
+  BindingScope,
+  BindingTag,
+  ConstraintContext,
+  Constructor,
+  DependencyKey,
+  DeactivationHandler,
+  ResolutionFrame,
+  ResolveOptions,
+  ResolutionContext,
+  TokenValue,
+} from "#/types";
+
+// Token
+export { token, tokenName, isToken } from "#/token";
+export type { Token } from "#/token";
+
+// Binding builders — types only
+export type {
+  AliasBindingBuilder,
+  BindToBuilder,
+  BindingBuilder,
+  ConstantBindingBuilder,
+  ScopedBindingBuilder,
+  SingletonBindingBuilder,
+  SingletonLifecycleBuilder,
+  SlotConstrainedBuilder,
+  TransientBindingBuilder,
+} from "#/binding";
+
+// Container
+export { Container } from "#/container";
+export type { Container as ContainerInterface, ContainerStatic } from "#/container";
+
+export { effectiveBindingScope } from "#/binding-scope";
+export { injectionSlotToResolveOptions, bindingSlotToResolveOptions } from "#/resolve-options";
+
+// Introspection types
+export type { BindingSnapshot, ContainerSnapshot } from "#/inspector";
+
+// Graph types
+export type { ContainerGraphJson, GraphEdge, GraphNode, GraphOptions } from "#/dependency-graph";
+
+// Module
+export { AsyncModule, isSyncModule, Module, SyncModule } from "#/module";
+export type { AsyncModuleBuilder, ModuleBuilder } from "#/module";
+
+// Decorators
+export { inject, injectAll, isInjectionDescriptor, optional } from "#/decorators/inject";
+export type { InjectionDescriptor, InjectOptions } from "#/decorators/inject";
+export { injectable } from "#/decorators/injectable";
+export type { InjectableDependency, InjectableOptions } from "#/decorators/injectable";
+export { postConstruct, preDestroy } from "#/decorators/lifecycle-decorators";
+
+// Auto-register
+export { createAutoRegisterRegistry } from "#/decorators/injectable";
+export type { AutoRegisterRegistry } from "#/decorators/injectable";
+
+// MetadataReader
+export { MetadataReaderToken } from "#/metadata/metadata-reader-token";
+export type { MetadataReader, MutableLifecycleMetadata } from "#/metadata/metadata-types";
+
+// Constraints — contextual injection predicates for .when()
+export {
+  whenAnyAncestorIs,
+  whenAnyAncestorNamed,
+  whenAnyAncestorTagged,
+  whenAnyAncestorTaggedAll,
+  whenNoAncestorIs,
+  whenNoParentIs,
+  whenParentIs,
+  whenParentNamed,
+  whenParentTagged,
+  whenParentTaggedAll,
+} from "#/constraints";
+
+// Errors
+export {
+  AmbiguousBindingError,
+  AsyncActivationError,
+  AsyncDeactivationError,
+  AsyncModuleLoadError,
+  AsyncResolutionError,
+  CircularDependencyError,
+  DiError,
+  DisposedContainerError,
+  InternalError,
+  MissingContainerContextError,
+  MissingMetadataError,
+  MissingScopeContextError,
+  NoMatchingBindingError,
+  RebindUnboundTokenError,
+  ScopeViolationError,
+  SyncDisposalNotSupportedError,
+  TokenNotBoundError,
+} from "#/errors";
+export type { ScopeViolationDetails } from "#/errors";

package/src/inspector.ts

@@ -0,0 +1,125 @@
+import type { Binding } from "#/binding";
+import { effectiveBindingScope } from "#/binding-scope";
+import { selectBinding } from "#/binding-select";
+import type { BindingRegistry } from "#/registry";
+import type { ScopeManager } from "#/scope";
+import type { Token } from "#/token";
+import { tokenName } from "#/token";
+import type {
+  BindingIdentifier,
+  BindingKind,
+  BindingScope,
+  BindingTag,
+  ConstraintContext,
+  Constructor,
+  ResolveOptions,
+} from "#/types";
+
+// ── Public types ──────────────────────────────────────────────────────────────
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface BindingSnapshot {
+  readonly tokenName: string;
+  readonly kind: BindingKind;
+  readonly scope: BindingScope;
+  readonly slot: {
+    readonly name?: string;
+    readonly tags: ReadonlyArray<BindingTag>;
+  };
+  readonly id: BindingIdentifier;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface ContainerSnapshot {
+  readonly ownBindings: ReadonlyArray<BindingSnapshot>;
+  readonly cachedSingletonCount: number;
+  readonly hasParent: boolean;
+  readonly isDisposed: boolean;
+}
+
+// ── Inspector ─────────────────────────────────────────────────────────────────
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export class Inspector {
+  constructor(
+    private readonly _registry: BindingRegistry,
+    private readonly _scope: ScopeManager,
+    private readonly _hasParent: boolean,
+    private readonly _isDisposed: () => boolean,
+  ) {}
+
+  inspect(): ContainerSnapshot {
+    const snapshots = this.allBindingSnapshots();
+    return {
+      ownBindings: snapshots,
+      cachedSingletonCount: this._scope.getAllSingletons().size,
+      hasParent: this._hasParent,
+      isDisposed: this._isDisposed(),
+    };
+  }
+
+  lookupBindings<Value>(token: Token<Value> | Constructor<Value>): ReadonlyArray<BindingSnapshot> {
+    const bindings = this._registry.getAll(token);
+    return bindings.map((binding) => this._toSnapshot(binding));
+  }
+
+  has(token: Token<unknown> | Constructor, hint?: ResolveOptions, parentHas?: () => boolean): boolean {
+    const bindings = this._registry.getAll(token);
+    if (bindings.length > 0) {
+      if (hint !== undefined) {
+        if (selectBinding(bindings, hint, this._makeHintContext(hint), tokenName(token)) !== undefined) {
+          return true;
+        }
+      } else {
+        return true;
+      }
+    }
+    return parentHas?.() ?? false;
+  }
+
+  hasOwn(token: Token<unknown> | Constructor, hint?: ResolveOptions): boolean {
+    const bindings = this._registry.getAll(token);
+    if (bindings.length === 0) {
+      return false;
+    }
+    if (hint !== undefined) {
+      return selectBinding(bindings, hint, this._makeHintContext(hint), tokenName(token)) !== undefined;
+    }
+    return true;
+  }
+
+  private _makeHintContext(hint: ResolveOptions): ConstraintContext {
+    return {
+      resolutionPath: [],
+      resolutionStack: [],
+      parent: undefined,
+      ancestors: [],
+      currentResolveHint: hint,
+    };
+  }
+
+  private allBindingSnapshots(): ReadonlyArray<BindingSnapshot> {
+    return this._registry.allBindings().map((binding) => this._toSnapshot(binding));
+  }
+
+  private _toSnapshot(binding: Binding): BindingSnapshot {
+    const scope = effectiveBindingScope(binding);
+    const slot: BindingSnapshot["slot"] =
+      binding.slot.name !== undefined
+        ? { name: binding.slot.name, tags: binding.slot.tags }
+        : { tags: binding.slot.tags };
+    return {
+      tokenName: tokenName(binding.token),
+      kind: binding.kind,
+      scope,
+      slot,
+      id: binding.id,
+    };
+  }
+}