@codefast/di 0.3.16-canary.2 → 0.3.16-canary.3

package/src/module.ts

@@ -0,0 +1,93 @@
+import type { BindToBuilder } from "#/binding";
+import type { Constructor } from "#/types";
+import type { Token } from "#/token";
+
+// ── Branded types (runtime symbols for branding) ─────────────────────────────
+
+const SYNC_MODULE_BRAND: unique symbol = Symbol("di:sync-module");
+const ASYNC_MODULE_BRAND: unique symbol = Symbol("di:async-module");
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface SyncModule {
+  readonly name: string;
+  readonly [SYNC_MODULE_BRAND]: true;
+  readonly _setup: (builder: ModuleBuilder) => void;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface AsyncModule {
+  readonly name: string;
+  readonly [ASYNC_MODULE_BRAND]: true;
+  readonly _setup: (builder: AsyncModuleBuilder) => Promise<void>;
+}
+
+// ── Builder interfaces ────────────────────────────────────────────────────────
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface ModuleBuilder {
+  bind<const Value>(token: Token<Value> | Constructor<Value>): BindToBuilder<Value>;
+  import(...modules: Array<SyncModule>): void;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface AsyncModuleBuilder {
+  bind<const Value>(token: Token<Value> | Constructor<Value>): BindToBuilder<Value>;
+  import(...modules: Array<SyncModule | AsyncModule>): void;
+}
+
+// ── Static factories ──────────────────────────────────────────────────────────
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export const SyncModule = {
+  create(name: string, setup: (builder: ModuleBuilder) => void): SyncModule {
+    return {
+      name,
+      [SYNC_MODULE_BRAND]: true as const,
+      _setup: setup,
+    } as SyncModule;
+  },
+};
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export const AsyncModule = {
+  create(name: string, setup: (builder: AsyncModuleBuilder) => Promise<void>): AsyncModule {
+    return {
+      name,
+      [ASYNC_MODULE_BRAND]: true as const,
+      _setup: setup,
+    } as AsyncModule;
+  },
+};
+
+// ── Module — unified API ──────────────────────────────────────────────────────
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export const Module = {
+  create(name: string, setup: (builder: ModuleBuilder) => void): SyncModule {
+    return SyncModule.create(name, setup);
+  },
+  createAsync(name: string, setup: (builder: AsyncModuleBuilder) => Promise<void>): AsyncModule {
+    return AsyncModule.create(name, setup);
+  },
+};
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function isSyncModule(module: SyncModule | AsyncModule): module is SyncModule {
+  return (module as SyncModule)[SYNC_MODULE_BRAND] === true;
+}

package/src/registry.ts

@@ -0,0 +1,241 @@
+import type { Binding } from "#/binding";
+import type { BindingIdentifier, Constructor, DependencyKey } from "#/types";
+import type { Token } from "#/token";
+import { bindingSlotEquals, bindingSlotToString } from "#/binding";
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export class BindingRegistry {
+  // Map from token key -> array of bindings (order matters for last-wins)
+  private readonly _bindings = new Map<DependencyKey, Array<Binding>>();
+  // Fast lookup by binding ID
+  private readonly _byId = new Map<BindingIdentifier, Binding>();
+  // Fast lookup for slot { name, tags: [] }
+  private readonly _simpleNamed = new Map<DependencyKey, Map<string, Binding>>();
+  // Fast path for one default slot binding with no predicate
+  private readonly _fastDefault = new Map<DependencyKey, Binding>();
+  // Fast lookup for slot { name: undefined, tags: [[key, value]] } with no predicate
+  private readonly _simpleTagged = new Map<DependencyKey, Map<string, Map<unknown, Binding>>>();
+
+  /** Add or replace binding using slot-aware last-wins. */
+  add(binding: Binding): void {
+    const key = binding.token as DependencyKey;
+    // ✓ TS6.0: Map.getOrInsert (ES2025) replaces the manual get+check+set upsert
+    const bindingsForToken = this._bindings.getOrInsert(key, []);
+
+    // Only apply last-wins for slot-based bindings (not predicate-only)
+    if (!this._isPurePredicateBinding(binding)) {
+      const existingIndex = bindingsForToken.findIndex(
+        (candidate) =>
+          !this._isPurePredicateBinding(candidate) &&
+          bindingSlotEquals(candidate.slot, binding.slot),
+      );
+      if (existingIndex !== -1) {
+        const replacedBinding = bindingsForToken[existingIndex]!;
+        this._byId.delete(replacedBinding.id);
+        bindingsForToken.splice(existingIndex, 1);
+      }
+    }
+
+    bindingsForToken.push(binding);
+    this._byId.set(binding.id, binding);
+    this._indexSimpleNamedBinding(key, binding);
+    this._indexSimpleTaggedBinding(key, binding);
+    this._refreshFastDefaultForToken(key);
+  }
+
+  /** Remove all bindings for a token. Returns removed bindings. */
+  removeByToken(token: Token<unknown> | Constructor): Array<Binding> {
+    const key = token as DependencyKey;
+    const bindingsForToken = this._bindings.get(key) ?? [];
+    this._bindings.delete(key);
+    this._simpleNamed.delete(key);
+    this._simpleTagged.delete(key);
+    this._fastDefault.delete(key);
+    for (const binding of bindingsForToken) {
+      this._byId.delete(binding.id);
+    }
+    return bindingsForToken;
+  }
+
+  /** Remove a specific binding by ID. Returns the removed binding or undefined. */
+  removeById(id: BindingIdentifier): Binding | undefined {
+    const binding = this._byId.get(id);
+    if (binding === undefined) {
+      return undefined;
+    }
+    this._byId.delete(id);
+    const key = binding.token as DependencyKey;
+    const bindingsForToken = this._bindings.get(key);
+    if (bindingsForToken !== undefined) {
+      const bindingIndex = bindingsForToken.findIndex((candidate) => candidate.id === id);
+      if (bindingIndex !== -1) {
+        bindingsForToken.splice(bindingIndex, 1);
+      }
+      this._deindexSimpleNamedBinding(key, binding);
+      this._deindexSimpleTaggedBinding(key, binding);
+      if (bindingsForToken.length === 0) {
+        this._bindings.delete(key);
+        this._simpleNamed.delete(key);
+        this._simpleTagged.delete(key);
+        this._fastDefault.delete(key);
+      } else {
+        this._refreshFastDefaultForToken(key);
+      }
+    }
+    return binding;
+  }
+
+  /** Get all bindings for a token. */
+  getAll(token: Token<unknown> | Constructor): ReadonlyArray<Binding> {
+    return this._bindings.get(token as DependencyKey) ?? [];
+  }
+
+  /** Get binding by ID. */
+  getById(id: BindingIdentifier): Binding | undefined {
+    return this._byId.get(id);
+  }
+
+  /** Check if any binding exists for token. */
+  has(token: Token<unknown> | Constructor): boolean {
+    const key = token as DependencyKey;
+    const list = this._bindings.get(key);
+    return list !== undefined && list.length > 0;
+  }
+
+  /** All bindings in the registry. */
+  allBindings(): ReadonlyArray<Binding> {
+    const allBindings: Array<Binding> = [];
+    for (const bindingsForToken of this._bindings.values()) {
+      allBindings.push(...bindingsForToken);
+    }
+    return allBindings;
+  }
+
+  /** Remove all bindings. Returns all removed. */
+  clear(): ReadonlyArray<Binding> {
+    const all = this.allBindings();
+    this._bindings.clear();
+    this._byId.clear();
+    this._simpleNamed.clear();
+    this._simpleTagged.clear();
+    this._fastDefault.clear();
+    return all;
+  }
+
+  getSimpleNamed(token: Token<unknown> | Constructor, name: string): Binding | undefined {
+    return this._simpleNamed.get(token as DependencyKey)?.get(name);
+  }
+
+  getSimpleTagged(
+    token: Token<unknown> | Constructor,
+    tagKey: string,
+    tagValue: unknown,
+  ): Binding | undefined {
+    return this._simpleTagged
+      .get(token as DependencyKey)
+      ?.get(tagKey)
+      ?.get(tagValue);
+  }
+
+  getFastDefault(token: Token<unknown> | Constructor): Binding | undefined {
+    return this._fastDefault.get(token as DependencyKey);
+  }
+
+  /** Summarize available slot strings for a token (for error messages). */
+  availableSlotStrings(token: Token<unknown> | Constructor): Array<string> {
+    const bindingsForToken = this._bindings.get(token as DependencyKey) ?? [];
+    return bindingsForToken.map((binding) => bindingSlotToString(binding.slot));
+  }
+
+  private _indexSimpleTaggedBinding(tokenKey: DependencyKey, binding: Binding): void {
+    const slot = binding.slot;
+    if (slot.name !== undefined || slot.tags.length !== 1 || binding.predicate !== undefined) {
+      return;
+    }
+    const [tagKey, tagValue] = slot.tags[0]!;
+    const byTagKey = this._simpleTagged.getOrInsert(
+      tokenKey,
+      new Map<string, Map<unknown, Binding>>(),
+    );
+    const byTagValue = byTagKey.getOrInsert(tagKey, new Map<unknown, Binding>());
+    byTagValue.set(tagValue, binding);
+  }
+
+  private _deindexSimpleTaggedBinding(tokenKey: DependencyKey, binding: Binding): void {
+    const slot = binding.slot;
+    if (slot.name !== undefined || slot.tags.length !== 1 || binding.predicate !== undefined) {
+      return;
+    }
+    const [tagKey, tagValue] = slot.tags[0]!;
+    const byTagKey = this._simpleTagged.get(tokenKey);
+    if (byTagKey === undefined) {
+      return;
+    }
+    const byTagValue = byTagKey.get(tagKey);
+    if (byTagValue === undefined) {
+      return;
+    }
+    const current = byTagValue.get(tagValue);
+    if (current?.id === binding.id) {
+      byTagValue.delete(tagValue);
+      if (byTagValue.size === 0) {
+        byTagKey.delete(tagKey);
+        if (byTagKey.size === 0) {
+          this._simpleTagged.delete(tokenKey);
+        }
+      }
+    }
+  }
+
+  private _isPurePredicateBinding(binding: Binding): boolean {
+    const slot = binding.slot;
+    const hasPredicate = binding.predicate !== undefined;
+    const hasConstraint = slot.name !== undefined || slot.tags.length > 0;
+    // Pure predicate = has predicate but no slot constraint (name/tags)
+    return hasPredicate && !hasConstraint;
+  }
+
+  private _indexSimpleNamedBinding(tokenKey: DependencyKey, binding: Binding): void {
+    const slot = binding.slot;
+    if (slot.name === undefined || slot.tags.length > 0) {
+      return;
+    }
+    const bindingsByName = this._simpleNamed.getOrInsert(tokenKey, new Map<string, Binding>());
+    bindingsByName.set(slot.name, binding);
+  }
+
+  private _deindexSimpleNamedBinding(tokenKey: DependencyKey, binding: Binding): void {
+    const slot = binding.slot;
+    if (slot.name === undefined || slot.tags.length > 0) {
+      return;
+    }
+    const bindingsByName = this._simpleNamed.get(tokenKey);
+    if (bindingsByName === undefined) {
+      return;
+    }
+    const currentBinding = bindingsByName.get(slot.name);
+    if (currentBinding?.id === binding.id) {
+      bindingsByName.delete(slot.name);
+      if (bindingsByName.size === 0) {
+        this._simpleNamed.delete(tokenKey);
+      }
+    }
+  }
+
+  private _refreshFastDefaultForToken(tokenKey: DependencyKey): void {
+    const bindingsForToken = this._bindings.get(tokenKey);
+    if (bindingsForToken === undefined || bindingsForToken.length !== 1) {
+      this._fastDefault.delete(tokenKey);
+      return;
+    }
+    const onlyBinding = bindingsForToken[0]!;
+    const isDefaultSlot = onlyBinding.slot.name === undefined && onlyBinding.slot.tags.length === 0;
+    if (!isDefaultSlot || onlyBinding.predicate !== undefined) {
+      this._fastDefault.delete(tokenKey);
+      return;
+    }
+    this._fastDefault.set(tokenKey, onlyBinding);
+  }
+}

package/src/resolve-options.ts

@@ -0,0 +1,42 @@
+import type { BindingSlot } from "#/binding";
+import type { BindingTag, ResolveOptions } from "#/types";
+
+/** 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: {
+  readonly name?: string;
+  readonly tags?: ReadonlyArray<BindingTag>;
+}): ResolveOptions | undefined {
+  return buildOptions(injectionSlot.name, injectionSlot.tags);
+}
+
+/**
+ * Hint from a binding {@link BindingSlot} (tags may be empty; omits when nothing to match).
+ *
+ * @since 0.3.16-canary.0
+ */
+export function bindingSlotToResolveOptions(bindingSlot: BindingSlot): ResolveOptions | undefined {
+  return buildOptions(bindingSlot.name, bindingSlot.tags.length > 0 ? bindingSlot.tags : undefined);
+}