@codefast/di 0.5.0-canary.6 → 0.5.0-canary.8

package/src/decorators/inject.ts

@@ -1,9 +1,9 @@
-import { getActiveContainer } from "#/environment";
 import { InternalError, MissingContainerContextError } from "#/errors";
 import { INJECT_ACCESSOR_KEY } from "#/metadata/metadata-keys";
-import { injectionSlotToResolveOptions } from "#/resolve-options";
+import { getActiveContainer } from "#/resolution/environment";
+import { injectionSlotToResolveOptions } from "#/resolution/resolve-options";
 import type { Token } from "#/token";
-import type { BindingTag, Constructor } from "#/types";
+import type { BindingTag, Constructor, TokenValue } from "#/types";
 
 // ── InjectionDescriptor ───────────────────────────────────────────────────────
 
@@ -31,6 +31,17 @@ export interface InjectionDescriptor<Value = unknown> {
  */
 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 InjectionDescriptor<infer Value> ? Value : TokenValue<Dependency>;
+
 /**
  * @since 0.3.16-canary.0
  */
@@ -182,7 +193,7 @@ export function inject<const Value>(
   }
   Object.defineProperties(decoratorFn, props);
 
-  return decoratorFn as unknown as InjectionDescriptor<Value> & ClassAccessorDecorator<unknown, Value>;
+  return decoratorFn as InjectionDescriptor<Value> & ClassAccessorDecorator<unknown, Value>;
 }
 
 // ── optional() ────────────────────────────────────────────────────────────────

package/src/decorators/injectable.ts

@@ -18,13 +18,13 @@ export interface AutoRegisterRegistry {
  * @since 0.3.16-canary.0
  */
 export function createAutoRegisterRegistry(): AutoRegisterRegistry {
-  const _registeredEntries: Array<{ target: Constructor; scope: BindingScope }> = [];
+  const registeredEntries: Array<{ target: Constructor; scope: BindingScope }> = [];
   return {
     register(target: Constructor, scope: BindingScope): void {
-      _registeredEntries.push({ target, scope });
+      registeredEntries.push({ target, scope });
     },
     entries(): ReadonlyArray<{ target: Constructor; scope: BindingScope }> {
-      return _registeredEntries;
+      return registeredEntries;
     },
   };
 }

package/src/errors.ts

@@ -212,6 +212,27 @@ export class MissingContainerContextError extends DiError {
   }
 }
 
+/**
+ * A fluent chain was refined before a `to*()` call gave it a binding to refine.
+ *
+ * @remarks The builder types make this unreachable from TypeScript — `bind()` returns
+ * `BindToBuilder`, which exposes only `to*()`. It exists for JavaScript callers and for anyone who
+ * casts past the types, so the misuse fails loudly instead of mutating nothing.
+ *
+ * @since 0.5.0-canary.8
+ */
+export class ChainNotRegisteredError extends DiError {
+  readonly code = "CHAIN_NOT_REGISTERED";
+  readonly tokenName: string;
+
+  constructor(tokenName: string) {
+    super(
+      `Cannot refine the binding for token '${tokenName}' before choosing a target. Call a to*() method first — for example .to(SomeClass), .toConstantValue(value) or .toDynamic(factory).`,
+    );
+    this.tokenName = tokenName;
+  }
+}
+
 /**
  * @since 0.3.16-canary.0
  */

package/src/index.ts

@@ -33,17 +33,17 @@ export type {
 } from "#/binding";
 
 // Container
-export { Container } from "#/container";
-export type { Container as ContainerInterface, ContainerStatic } from "#/container";
+export { Container } from "#/container/container";
+export type { Container as ContainerInterface, ContainerStatic } from "#/container/container";
 
-export { effectiveBindingScope } from "#/binding-scope";
-export { injectionSlotToResolveOptions, bindingSlotToResolveOptions } from "#/resolve-options";
+export { effectiveBindingScope } from "#/resolution/binding-scope";
+export { injectionSlotToResolveOptions, bindingSlotToResolveOptions } from "#/resolution/resolve-options";
 
 // Introspection types
-export type { BindingSnapshot, ContainerSnapshot } from "#/inspector";
+export type { BindingSnapshot, ContainerSnapshot } from "#/introspection/inspector";
 
 // Graph types
-export type { ContainerGraphJson, GraphEdge, GraphNode, GraphOptions } from "#/dependency-graph";
+export type { ContainerGraphJson, GraphEdge, GraphNode, GraphOptions } from "#/introspection/dependency-graph";
 
 // Module
 export { AsyncModule, isSyncModule, Module, SyncModule } from "#/module";
@@ -76,7 +76,7 @@ export {
   whenParentNamed,
   whenParentTagged,
   whenParentTaggedAll,
-} from "#/constraints";
+} from "#/resolution/constraints";
 
 // Errors
 export {
@@ -85,6 +85,7 @@ export {
   AsyncDeactivationError,
   AsyncModuleLoadError,
   AsyncResolutionError,
+  ChainNotRegisteredError,
   CircularDependencyError,
   DiError,
   DisposedContainerError,
@@ -99,3 +100,10 @@ export {
   TokenNotBoundError,
 } from "#/errors";
 export type { ScopeViolationDetails } from "#/errors";
+
+// Graph adapters — render `generateDependencyGraph()` output for common viewers
+export { toDotGraph } from "#/introspection/graph-adapters/dot";
+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";

package/src/{dependency-graph.ts → introspection/dependency-graph.ts}

@@ -1,6 +1,6 @@
-import { effectiveBindingScope } from "#/binding-scope";
 import type { MetadataReader } from "#/metadata/metadata-types";
 import type { BindingRegistry } from "#/registry";
+import { effectiveBindingScope } from "#/resolution/binding-scope";
 import { tokenName } from "#/token";
 import type { BindingScope, Constructor } from "#/types";
 

package/src/{graph-adapters → introspection/graph-adapters}/cytoscape.ts

@@ -1,4 +1,4 @@
-import type { ContainerGraphJson } from "#/dependency-graph";
+import type { ContainerGraphJson } from "#/introspection/dependency-graph";
 
 /**
  * @since 0.3.16-canary.0

package/src/{graph-adapters → introspection/graph-adapters}/dot.ts

@@ -1,4 +1,4 @@
-import type { ContainerGraphJson } from "#/dependency-graph";
+import type { ContainerGraphJson } from "#/introspection/dependency-graph";
 
 /**
  * @since 0.3.16-canary.0

package/src/{graph-adapters → introspection/graph-adapters}/reactflow.ts

@@ -1,4 +1,4 @@
-import type { ContainerGraphJson } from "#/dependency-graph";
+import type { ContainerGraphJson } from "#/introspection/dependency-graph";
 
 /**
  * @since 0.3.16-canary.0
@@ -35,6 +35,14 @@ export interface ReactFlowGraph {
 /**
  * @since 0.3.16-canary.0
  */
+// Initial grid layout: React Flow expects concrete positions; viewers re-layout anyway.
+const GRID_COLUMN_COUNT = 5;
+const GRID_CELL_WIDTH_PX = 200;
+const GRID_CELL_HEIGHT_PX = 100;
+
+/**
+ * @since 0.5.0-canary.7
+ */
 export function toReactFlowGraph(graph: ContainerGraphJson): ReactFlowGraph {
   const nodes: Array<ReactFlowNode> = graph.nodes.map((node, idx) => ({
     id: node.id,
@@ -44,7 +52,10 @@ export function toReactFlowGraph(graph: ContainerGraphJson): ReactFlowGraph {
       scope: node.scope,
       fromParent: node.fromParent,
     },
-    position: { x: (idx % 5) * 200, y: Math.floor(idx / 5) * 100 },
+    position: {
+      x: (idx % GRID_COLUMN_COUNT) * GRID_CELL_WIDTH_PX,
+      y: Math.floor(idx / GRID_COLUMN_COUNT) * GRID_CELL_HEIGHT_PX,
+    },
   }));
 
   const edges: Array<ReactFlowEdge> = graph.edges.map((edge, idx) => ({

package/src/{inspector.ts → introspection/inspector.ts}

@@ -1,8 +1,8 @@
 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 { effectiveBindingScope } from "#/resolution/binding-scope";
+import { selectBinding } from "#/resolution/binding-select";
+import type { ScopeManager } from "#/resolution/scope";
 import type { Token } from "#/token";
 import { tokenName } from "#/token";
 import type {
@@ -47,33 +47,38 @@ export interface ContainerSnapshot {
  * @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,
-  ) {}
+  readonly #registry: BindingRegistry;
+  readonly #scope: ScopeManager;
+  readonly #hasParent: boolean;
+  readonly #isDisposed: () => boolean;
+
+  constructor(registry: BindingRegistry, scope: ScopeManager, hasParent: boolean, isDisposed: () => boolean) {
+    this.#registry = registry;
+    this.#scope = scope;
+    this.#hasParent = hasParent;
+    this.#isDisposed = isDisposed;
+  }
 
   inspect(): ContainerSnapshot {
     const snapshots = this.allBindingSnapshots();
     return {
       ownBindings: snapshots,
-      cachedSingletonCount: this._scope.getAllSingletons().size,
-      hasParent: this._hasParent,
-      isDisposed: this._isDisposed(),
+      cachedSingletonCount: this.#scope.cachedSingletons().length,
+      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));
+    const bindings = this.#registry.getAll(token);
+    return bindings.map((binding) => this.#toSnapshot(binding));
   }
 
   has(token: Token<unknown> | Constructor, options?: ResolveOptions, parentHas?: () => boolean): boolean {
-    const bindings = this._registry.getAll(token);
+    const bindings = this.#registry.getAll(token);
     if (bindings.length > 0) {
       if (options !== undefined) {
-        if (selectBinding(bindings, options, this._makeConstraintContext(options), tokenName(token)) !== undefined) {
+        if (selectBinding(bindings, options, this.#makeConstraintContext(options), tokenName(token)) !== undefined) {
           return true;
         }
       } else {
@@ -84,17 +89,17 @@ export class Inspector {
   }
 
   hasOwn(token: Token<unknown> | Constructor, options?: ResolveOptions): boolean {
-    const bindings = this._registry.getAll(token);
+    const bindings = this.#registry.getAll(token);
     if (bindings.length === 0) {
       return false;
     }
     if (options !== undefined) {
-      return selectBinding(bindings, options, this._makeConstraintContext(options), tokenName(token)) !== undefined;
+      return selectBinding(bindings, options, this.#makeConstraintContext(options), tokenName(token)) !== undefined;
     }
     return true;
   }
 
-  private _makeConstraintContext(options: ResolveOptions): ConstraintContext {
+  #makeConstraintContext(options: ResolveOptions): ConstraintContext {
     return {
       resolutionPath: [],
       resolutionStack: [],
@@ -105,10 +110,10 @@ export class Inspector {
   }
 
   private allBindingSnapshots(): ReadonlyArray<BindingSnapshot> {
-    return this._registry.allBindings().map((binding) => this._toSnapshot(binding));
+    return this.#registry.allBindings().map((binding) => this.#toSnapshot(binding));
   }
 
-  private _toSnapshot(binding: Binding): BindingSnapshot {
+  #toSnapshot(binding: Binding): BindingSnapshot {
     const scope = effectiveBindingScope(binding);
     const slot: BindingSnapshot["slot"] =
       binding.slot.name !== undefined

package/src/metadata/metadata-keys.ts

@@ -12,13 +12,10 @@ export const LIFECYCLE_KEY: unique symbol = Symbol("di:lifecycle");
 export const INJECT_ACCESSOR_KEY: unique symbol = Symbol("di:inject-accessor");
 
 /**
- * The well-known symbol used by TC39 Stage 3 decorator transforms to store class metadata.
+ * The symbol TC39 Stage 3 decorator transforms store class metadata under.
  *
- * `Symbol.metadata` is defined natively once the runtime ships the full TC39 decorator
- * proposal.  Until then (current Node.js / browsers), Babel and esbuild both fall back to
- * `Symbol.for("Symbol.metadata")` — a global-registry symbol with the same string key.
- * Resolving it here once keeps the reader and the decorator transforms in sync regardless
- * of which path is taken.
+ * @remarks Falls back to the global-registry symbol, which is what Babel and esbuild emit until
+ * a runtime ships `Symbol.metadata` natively.
  *
  * @since 0.3.16-canary.0
  */

package/src/metadata/symbol-metadata-reader.ts

@@ -7,7 +7,7 @@ import type { Constructor } from "#/types";
  * @since 0.3.16-canary.0
  */
 export class SymbolMetadataReader implements MetadataReader {
-  private _getMetadataRecord(target: Constructor, key: string | symbol): Record<string | symbol, unknown> | undefined {
+  #getMetadataRecord(target: Constructor, key: string | symbol): Record<string | symbol, unknown> | undefined {
     const descriptor = Object.getOwnPropertyDescriptor(target, METADATA_SYMBOL);
     if (descriptor === undefined) {
       return undefined;
@@ -20,19 +20,19 @@ export class SymbolMetadataReader implements MetadataReader {
   }
 
   getConstructorMetadata(target: Constructor): ConstructorMetadata | undefined {
-    const record = this._getMetadataRecord(target, INJECTABLE_KEY);
+    const record = this.#getMetadataRecord(target, INJECTABLE_KEY);
     return record?.[INJECTABLE_KEY] as ConstructorMetadata | undefined;
   }
 
   getLifecycleMetadata(target: Constructor): LifecycleMetadata | undefined {
-    const record = this._getMetadataRecord(target, LIFECYCLE_KEY);
+    const record = this.#getMetadataRecord(target, LIFECYCLE_KEY);
     return record?.[LIFECYCLE_KEY] as LifecycleMetadata | undefined;
   }
 
   getAccessorMetadata(
     target: Constructor,
   ): Array<{ key: string | symbol; descriptor: InjectionDescriptor }> | undefined {
-    const record = this._getMetadataRecord(target, INJECT_ACCESSOR_KEY);
+    const record = this.#getMetadataRecord(target, INJECT_ACCESSOR_KEY);
     return record?.[INJECT_ACCESSOR_KEY] as
       | Array<{ key: string | symbol; descriptor: InjectionDescriptor }>
       | undefined;

package/src/module.ts

@@ -7,13 +7,21 @@ import type { Constructor } from "#/types";
 const SYNC_MODULE_BRAND: unique symbol = Symbol("di:sync-module");
 const ASYNC_MODULE_BRAND: unique symbol = Symbol("di:async-module");
 
+/**
+ * Key for the module's setup callback. A symbol (not exported from the package root)
+ * keeps the container-only member out of consumer-facing autocomplete entirely.
+ *
+ * @since 0.5.0-canary.7
+ */
+export const MODULE_SETUP: unique symbol = Symbol("di:module-setup");
+
 /**
  * @since 0.3.16-canary.0
  */
 export interface SyncModule {
   readonly name: string;
   readonly [SYNC_MODULE_BRAND]: true;
-  readonly _setup: (builder: ModuleBuilder) => void;
+  readonly [MODULE_SETUP]: (builder: ModuleBuilder) => void;
 }
 
 /**
@@ -22,7 +30,7 @@ export interface SyncModule {
 export interface AsyncModule {
   readonly name: string;
   readonly [ASYNC_MODULE_BRAND]: true;
-  readonly _setup: (builder: AsyncModuleBuilder) => Promise<void>;
+  readonly [MODULE_SETUP]: (builder: AsyncModuleBuilder) => Promise<void>;
 }
 
 // ── Builder interfaces ────────────────────────────────────────────────────────
@@ -53,8 +61,8 @@ export const SyncModule = {
     return {
       name,
       [SYNC_MODULE_BRAND]: true as const,
-      _setup: setup,
-    } as SyncModule;
+      [MODULE_SETUP]: setup,
+    };
   },
 };
 
@@ -66,8 +74,8 @@ export const AsyncModule = {
     return {
       name,
       [ASYNC_MODULE_BRAND]: true as const,
-      _setup: setup,
-    } as AsyncModule;
+      [MODULE_SETUP]: setup,
+    };
   },
 };