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

package/src/binding.ts

@@ -0,0 +1,281 @@
+import type {
+  ActivationHandler,
+  BindingIdentifier,
+  BindingScope,
+  BindingTag,
+  Constructor,
+  DeactivationHandler,
+  DependencyKey,
+  ResolutionContext,
+  TokenValue,
+  ConstraintContext,
+} from "#/types";
+import type { Token } from "#/token";
+import type { InjectionDescriptor } from "#/decorators/inject";
+
+// ── BindingSlot ───────────────────────────────────────────────────────────────────
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface BindingSlot {
+  readonly name: string | undefined;
+  readonly tags: ReadonlyArray<BindingTag>;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function bindingSlotEquals(left: BindingSlot, right: BindingSlot): boolean {
+  if (left.name !== right.name) {
+    return false;
+  }
+  if (left.tags.length !== right.tags.length) {
+    return false;
+  }
+  for (const [tagKey, tagValue] of left.tags) {
+    if (
+      !right.tags.some(
+        ([otherKey, otherValue]) => otherKey === tagKey && Object.is(otherValue, tagValue),
+      )
+    ) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export const DEFAULT_BINDING_SLOT = { name: undefined, tags: [] } satisfies BindingSlot;
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function bindingSlotToString(slot: BindingSlot): string {
+  if (slot.name === undefined && slot.tags.length === 0) {
+    return "default";
+  }
+  const parts: Array<string> = [];
+  if (slot.name !== undefined) {
+    parts.push(`name:${slot.name}`);
+  }
+  for (const [tagKey, tagValue] of slot.tags) {
+    parts.push(`tag:${tagKey}=${String(tagValue)}`);
+  }
+  return parts.join(",");
+}
+
+// ── BindingBase ───────────────────────────────────────────────────────────────
+
+interface BindingBase<Value> {
+  readonly id: BindingIdentifier;
+  readonly token: Token<Value> | Constructor<Value>;
+  readonly slot: BindingSlot;
+  readonly predicate?: (ctx: ConstraintContext) => boolean;
+}
+
+type BindingBaseKeys = keyof BindingBase<unknown>;
+
+// ── Binding kinds ─────────────────────────────────────────────────────────────
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface ClassBinding<Value> extends BindingBase<Value> {
+  readonly kind: "class";
+  readonly target: Constructor<Value>;
+  readonly scope: BindingScope;
+  readonly onActivation?: ActivationHandler<Value>;
+  readonly onDeactivation?: DeactivationHandler<Value>;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface DynamicBinding<Value> extends BindingBase<Value> {
+  readonly kind: "dynamic";
+  readonly factory: (ctx: ResolutionContext) => Value;
+  readonly scope: BindingScope;
+  readonly onActivation?: ActivationHandler<Value>;
+  readonly onDeactivation?: DeactivationHandler<Value>;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface DynamicAsyncBinding<Value> extends BindingBase<Value> {
+  readonly kind: "dynamic-async";
+  readonly factory: (ctx: ResolutionContext) => Promise<Value>;
+  readonly scope: BindingScope;
+  readonly onActivation?: ActivationHandler<Value>;
+  readonly onDeactivation?: DeactivationHandler<Value>;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface ResolvedBinding<Value> extends BindingBase<Value> {
+  readonly kind: "resolved";
+  readonly factory: (...args: Array<unknown>) => Value;
+  readonly deps: ReadonlyArray<InjectionDescriptor>;
+  readonly scope: BindingScope;
+  readonly onActivation?: ActivationHandler<Value>;
+  readonly onDeactivation?: DeactivationHandler<Value>;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface ResolvedAsyncBinding<Value> extends BindingBase<Value> {
+  readonly kind: "resolved-async";
+  readonly factory: (...args: Array<unknown>) => Promise<Value>;
+  readonly deps: ReadonlyArray<InjectionDescriptor>;
+  readonly scope: BindingScope;
+  readonly onActivation?: ActivationHandler<Value>;
+  readonly onDeactivation?: DeactivationHandler<Value>;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface ConstantBinding<Value> extends BindingBase<Value> {
+  readonly kind: "constant";
+  readonly value: Value;
+  readonly scope: "singleton";
+  readonly onActivation?: ActivationHandler<Value>;
+  readonly onDeactivation?: DeactivationHandler<Value>;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface AliasBinding<Value> extends BindingBase<Value> {
+  readonly kind: "alias";
+  readonly target: Token<Value> | Constructor<Value>;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export type Binding<Value = unknown> =
+  | ClassBinding<Value>
+  | DynamicBinding<Value>
+  | DynamicAsyncBinding<Value>
+  | ResolvedBinding<Value>
+  | ResolvedAsyncBinding<Value>
+  | ConstantBinding<Value>
+  | AliasBinding<Value>;
+
+/**
+ * Builder-only payload before `id`, `token`, `slot`, and `predicate` are applied.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type PartialBinding<Value> =
+  | Omit<ClassBinding<Value>, BindingBaseKeys>
+  | Omit<DynamicBinding<Value>, BindingBaseKeys>
+  | Omit<DynamicAsyncBinding<Value>, BindingBaseKeys>
+  | Omit<ResolvedBinding<Value>, BindingBaseKeys>
+  | Omit<ResolvedAsyncBinding<Value>, BindingBaseKeys>
+  | Omit<ConstantBinding<Value>, BindingBaseKeys>
+  | Omit<AliasBinding<Value>, BindingBaseKeys>;
+
+// ── ID generation ─────────────────────────────────────────────────────────────
+
+let _idCounter = 0;
+/**
+ * @since 0.3.16-canary.0
+ */
+export function generateBindingId(): BindingIdentifier {
+  return String(++_idCounter) as BindingIdentifier;
+}
+
+// ── Builder interfaces ────────────────────────────────────────────────────────
+
+/**
+ * Common slot-constraint + id methods shared by all concrete binding builders.
+ *
+ * @since 0.3.16-canary.0
+ */
+export interface SlotConstrainedBuilder {
+  when(predicate: (ctx: ConstraintContext) => boolean): this;
+  whenNamed(name: string): this;
+  whenTagged(tag: string, value: unknown): this;
+  whenDefault(): this;
+  id(): BindingIdentifier;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface BindToBuilder<Value> {
+  to(type: Constructor<Value>): BindingBuilder<Value>;
+  toSelf(): BindingBuilder<Value>;
+  toConstantValue(value: Value): ConstantBindingBuilder<Value>;
+  toDynamic(factory: (ctx: ResolutionContext) => Value): BindingBuilder<Value>;
+  toDynamicAsync(factory: (ctx: ResolutionContext) => Promise<Value>): BindingBuilder<Value>;
+  toResolved<const Deps extends ReadonlyArray<DependencyKey>>(
+    factory: (...args: { [K in keyof Deps]: TokenValue<NoInfer<Deps>[K]> }) => Value,
+    deps: Deps,
+  ): BindingBuilder<Value>;
+  toResolvedAsync<const Deps extends ReadonlyArray<DependencyKey>>(
+    factory: (...args: { [K in keyof Deps]: TokenValue<NoInfer<Deps>[K]> }) => Promise<Value>,
+    deps: Deps,
+  ): BindingBuilder<Value>;
+  toAlias(target: Token<Value> | Constructor<Value>): AliasBindingBuilder;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface BindingBuilder<Value> extends SlotConstrainedBuilder {
+  singleton(): SingletonBindingBuilder<Value>;
+  transient(): TransientBindingBuilder<Value>;
+  scoped(): ScopedBindingBuilder<Value>;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface ConstantBindingBuilder<Value> extends SlotConstrainedBuilder {
+  onActivation(fn: ActivationHandler<Value>): SingletonLifecycleBuilder<Value>;
+  onDeactivation(fn: DeactivationHandler<Value>): SingletonLifecycleBuilder<Value>;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface AliasBindingBuilder extends SlotConstrainedBuilder {}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface SingletonBindingBuilder<Value> {
+  onActivation(fn: ActivationHandler<Value>): this;
+  onDeactivation(fn: DeactivationHandler<Value>): this;
+  id(): BindingIdentifier;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface TransientBindingBuilder<Value> {
+  onActivation(fn: ActivationHandler<Value>): this;
+  id(): BindingIdentifier;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface ScopedBindingBuilder<Value> extends TransientBindingBuilder<Value> {}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface SingletonLifecycleBuilder<Value> {
+  onActivation(fn: ActivationHandler<Value>): this;
+  onDeactivation(fn: DeactivationHandler<Value>): this;
+  id(): BindingIdentifier;
+}

package/src/constraints.ts

@@ -0,0 +1,149 @@
+import type { BindingTag, ConstraintContext, Constructor } from "#/types";
+import type { Token } from "#/token";
+import { tokenName } from "#/token";
+
+function tokenNameOf(token: Token<unknown> | Constructor): string {
+  return tokenName(token);
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function whenParentIs(
+  token: Token<unknown> | Constructor,
+): (constraintContext: ConstraintContext) => boolean {
+  const tokenDisplayName = tokenNameOf(token);
+  return (constraintContext) =>
+    constraintContext.parent !== undefined &&
+    constraintContext.parent.tokenName === tokenDisplayName;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function whenNoParentIs(
+  token: Token<unknown> | Constructor,
+): (constraintContext: ConstraintContext) => boolean {
+  const tokenDisplayName = tokenNameOf(token);
+  return (constraintContext) =>
+    constraintContext.parent === undefined ||
+    constraintContext.parent.tokenName !== tokenDisplayName;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function whenAnyAncestorIs(
+  token: Token<unknown> | Constructor,
+): (constraintContext: ConstraintContext) => boolean {
+  const tokenDisplayName = tokenNameOf(token);
+  return (constraintContext) =>
+    constraintContext.ancestors.some(
+      (ancestorFrame) => ancestorFrame.tokenName === tokenDisplayName,
+    );
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function whenNoAncestorIs(
+  token: Token<unknown> | Constructor,
+): (constraintContext: ConstraintContext) => boolean {
+  const tokenDisplayName = tokenNameOf(token);
+  return (constraintContext) =>
+    constraintContext.ancestors.every(
+      (ancestorFrame) => ancestorFrame.tokenName !== tokenDisplayName,
+    );
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function whenParentNamed(name: string): (constraintContext: ConstraintContext) => boolean {
+  return (constraintContext) =>
+    constraintContext.parent !== undefined && constraintContext.parent.slot.name === name;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function whenAnyAncestorNamed(
+  name: string,
+): (constraintContext: ConstraintContext) => boolean {
+  return (constraintContext) =>
+    constraintContext.ancestors.some((ancestorFrame) => ancestorFrame.slot.name === name);
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function whenParentTagged(
+  tag: string,
+  value: unknown,
+): (constraintContext: ConstraintContext) => boolean {
+  return (constraintContext) =>
+    constraintContext.parent !== undefined &&
+    constraintContext.parent.slot.tags.some(
+      ([tagKey, tagValue]) => tagKey === tag && Object.is(tagValue, value),
+    );
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function whenAnyAncestorTagged(
+  tag: string,
+  value: unknown,
+): (constraintContext: ConstraintContext) => boolean {
+  return (constraintContext) =>
+    constraintContext.ancestors.some((ancestorFrame) =>
+      ancestorFrame.slot.tags.some(
+        ([tagKey, tagValue]) => tagKey === tag && Object.is(tagValue, value),
+      ),
+    );
+}
+
+/**
+ * Matches when the direct parent slot carries **all** of the given tag pairs.
+ * Equivalent to AND-composing multiple `whenParentTagged` calls but evaluates
+ * in a single predicate invocation — no intermediate closure allocations.
+ *
+ * @since 0.3.16-canary.1
+ */
+export function whenParentTaggedAll(
+  tags: ReadonlyArray<BindingTag>,
+): (constraintContext: ConstraintContext) => boolean {
+  return (constraintContext) => {
+    const { parent } = constraintContext;
+    if (parent === undefined) {
+      return false;
+    }
+    const { tags: parentTags } = parent.slot;
+    return tags.every(([tagKey, tagValue]) =>
+      parentTags.some(
+        ([otherKey, otherValue]) => otherKey === tagKey && Object.is(otherValue, tagValue),
+      ),
+    );
+  };
+}
+
+/**
+ * Matches when at least one ancestor slot carries **all** of the given tag pairs.
+ * Equivalent to AND-composing multiple `whenAnyAncestorTagged` calls but evaluates
+ * in a single predicate invocation — no intermediate closure allocations.
+ *
+ * @since 0.3.16-canary.1
+ */
+export function whenAnyAncestorTaggedAll(
+  tags: ReadonlyArray<BindingTag>,
+): (constraintContext: ConstraintContext) => boolean {
+  return (constraintContext) =>
+    constraintContext.ancestors.some((frame) => {
+      const { tags: frameTags } = frame.slot;
+      return tags.every(([tagKey, tagValue]) =>
+        frameTags.some(
+          ([otherKey, otherValue]) => otherKey === tagKey && Object.is(otherValue, tagValue),
+        ),
+      );
+    });
+}

package/src/constructor-type.ts

@@ -0,0 +1,19 @@
+/**
+ * A class (newable) that produces `Value`. Rest parameters are `never[]` so
+ * real classes with typed constructors remain assignable under
+ * `strictFunctionTypes` (unlike `unknown[]`, which is not assignable from
+ * narrower parameter types). Runtime construction still uses the real shape;
+ * this alias is the DI “class token” surface only.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type Constructor<Value = unknown> = new (...args: Array<never>) => Value;
+
+/**
+ * Class constructor as invoked by the resolver after metadata-driven
+ * resolution of `unknown[]` dependencies — separate from {@link Constructor},
+ * which is the public assignable class token.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type ConstructorInvocation = new (...args: Array<unknown>) => unknown;