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

package/src/decorators/inject.ts

@@ -0,0 +1,233 @@
+import type { BindingTag, Constructor } from "#/types";
+import type { Token } from "#/token";
+import { INJECT_ACCESSOR_KEY } from "#/metadata/metadata-keys";
+import { InternalError, MissingContainerContextError } from "#/errors";
+import { getActiveContainer } from "#/environment";
+import { injectionSlotToResolveOptions } from "#/resolve-options";
+
+// ── InjectionDescriptor ───────────────────────────────────────────────────────
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface InjectOptions {
+  name?: string;
+  tags?: ReadonlyArray<BindingTag>;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface InjectionDescriptor<Value = unknown> {
+  readonly token: Token<Value> | Constructor<Value>;
+  readonly optional: boolean;
+  readonly multi: boolean;
+  readonly name?: string;
+  readonly tags?: ReadonlyArray<BindingTag>;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export type InjectableDependency<Value = unknown> =
+  | Token<Value>
+  | Constructor<Value>
+  | InjectionDescriptor<Value>;
+
+/**
+ * @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 as Token<unknown> | Constructor, 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<unknown>, "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;
+  const explicitTags = 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;
+}
+
+function withOptions<DescValue>(
+  base: Pick<InjectionDescriptor<DescValue>, "token" | "optional" | "multi">,
+  options: InjectOptions | undefined,
+): InjectionDescriptor<DescValue> {
+  if (options?.name !== undefined && options.tags !== undefined) {
+    return { ...base, name: options.name, tags: options.tags };
+  }
+  if (options?.name !== undefined) {
+    return { ...base, name: options.name };
+  }
+  if (options?.tags !== undefined) {
+    return { ...base, tags: options.tags };
+  }
+  return base;
+}
+
+function buildInjectionDescriptor<const Value>(
+  token: Token<Value> | Constructor<Value>,
+  options?: InjectOptions,
+): InjectionDescriptor<Value> {
+  return withOptions({ token, optional: false, multi: false }, options);
+}
+
+// ── inject() — dual-role ──────────────────────────────────────────────────────
+
+type ClassAccessorDecorator<This, Value> = (
+  target: ClassAccessorDecoratorTarget<This, Value>,
+  context: ClassAccessorDecoratorContext<This, Value>,
+) => ClassAccessorDecoratorResult<This, Value> | void;
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function inject<const Value>(
+  token: Token<Value> | Constructor<Value>,
+  options?: InjectOptions,
+): InjectionDescriptor<Value> & ClassAccessorDecorator<unknown, Value> {
+  const descriptor = buildInjectionDescriptor(token, options);
+
+  const decoratorFn = (
+    _target: ClassAccessorDecoratorTarget<unknown, Value>,
+    context: ClassAccessorDecoratorContext<unknown, Value>,
+  ): ClassAccessorDecoratorResult<unknown, Value> => {
+    if (context.static === true) {
+      throw new InternalError(
+        "@inject() on static accessors is not supported; only instance accessors participate in runWithContainer-based property injection.",
+      );
+    }
+    const meta = context.metadata as Record<string | symbol, unknown>;
+    if (!Array.isArray(meta[INJECT_ACCESSOR_KEY])) {
+      meta[INJECT_ACCESSOR_KEY] = [];
+    }
+    (
+      meta[INJECT_ACCESSOR_KEY] as Array<{ key: string | symbol; descriptor: InjectionDescriptor }>
+    ).push({
+      key: context.name,
+      descriptor,
+    });
+
+    context.addInitializer(function (this: unknown) {
+      const container = getActiveContainer();
+      if (container === undefined) {
+        throw new MissingContainerContextError(String(context.name));
+      }
+      const hint =
+        options === undefined
+          ? undefined
+          : injectionSlotToResolveOptions({
+              ...(options.name !== undefined ? { name: options.name } : {}),
+              ...(options.tags !== undefined ? { tags: options.tags } : {}),
+            });
+      const value = descriptor.optional
+        ? container.resolveOptional(token, hint)
+        : container.resolve(token, hint);
+      context.access.set(this, value as Value);
+    });
+
+    return {};
+  };
+
+  // Use defineProperties to handle read-only `name` property of functions
+  const props: PropertyDescriptorMap = {};
+  for (const key of Object.keys(descriptor) as Array<keyof typeof descriptor>) {
+    props[key] = { value: descriptor[key], writable: true, enumerable: true, configurable: true };
+  }
+  Object.defineProperties(decoratorFn, props);
+
+  return decoratorFn as unknown as InjectionDescriptor<Value> &
+    ClassAccessorDecorator<unknown, Value>;
+}
+
+// ── optional() ────────────────────────────────────────────────────────────────
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function optional<const 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,
+  );
+}
+
+// ── injectAll() ───────────────────────────────────────────────────────────────
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function injectAll<const 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/decorators/injectable.ts

@@ -0,0 +1,85 @@
+import type { BindingScope, Constructor } from "#/types";
+import type { ParamMetadata } from "#/metadata/metadata-types";
+import type { InjectableDependency } from "#/decorators/inject";
+import { normalizeToDescriptor } from "#/decorators/inject";
+import { INJECTABLE_KEY } from "#/metadata/metadata-keys";
+
+// ── AutoRegisterRegistry ──────────────────────────────────────────────────────
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface AutoRegisterRegistry {
+  register(target: Constructor, scope: BindingScope): void;
+  entries(): ReadonlyArray<{ target: Constructor; scope: BindingScope }>;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function createAutoRegisterRegistry(): AutoRegisterRegistry {
+  const _registeredEntries: Array<{ target: Constructor; scope: BindingScope }> = [];
+  return {
+    register(target: Constructor, scope: BindingScope): void {
+      _registeredEntries.push({ target, scope });
+    },
+    entries(): ReadonlyArray<{ target: Constructor; scope: BindingScope }> {
+      return _registeredEntries;
+    },
+  };
+}
+
+// ── InjectableOptions ─────────────────────────────────────────────────────────
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface InjectableOptions {
+  autoRegister?: AutoRegisterRegistry;
+  scope?: BindingScope;
+}
+
+// ── @injectable() ─────────────────────────────────────────────────────────────
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function injectable(
+  deps?: ReadonlyArray<InjectableDependency>,
+  options?: InjectableOptions,
+): (target: unknown, context: ClassDecoratorContext) => void {
+  return function (target: unknown, context: ClassDecoratorContext): void {
+    const parameterMetadataList: Array<ParamMetadata> = (deps ?? []).map((dependency, index) => {
+      const descriptor = normalizeToDescriptor(dependency);
+      const baseParameterMetadata: Pick<ParamMetadata, "index" | "token" | "optional" | "multi"> = {
+        index,
+        token: descriptor.token,
+        optional: descriptor.optional,
+        multi: descriptor.multi,
+      };
+      if (descriptor.name !== undefined && descriptor.tags !== undefined) {
+        return { ...baseParameterMetadata, name: descriptor.name, tags: descriptor.tags };
+      }
+      if (descriptor.name !== undefined) {
+        return { ...baseParameterMetadata, name: descriptor.name };
+      }
+      if (descriptor.tags !== undefined) {
+        return { ...baseParameterMetadata, tags: descriptor.tags };
+      }
+      return baseParameterMetadata;
+    });
+
+    // Field decorators run before the class decorator — accessor @inject entries are
+    // already on context.metadata by the time this runs.
+    (context.metadata as Record<string | symbol, unknown>)[INJECTABLE_KEY] = {
+      params: parameterMetadataList,
+    };
+
+    if (options?.autoRegister !== undefined) {
+      const scope: BindingScope = options.scope ?? "transient";
+      options.autoRegister.register(target as Constructor, scope);
+    }
+  };
+}
+
+export type { InjectableDependency };

package/src/decorators/lifecycle-decorators.ts

@@ -0,0 +1,55 @@
+import type { MutableLifecycleMetadata } from "#/metadata/metadata-types";
+import { InternalError } from "#/errors";
+import { LIFECYCLE_KEY } from "#/metadata/metadata-keys";
+
+function appendUniqueMethod(
+  metadata: MutableLifecycleMetadata,
+  phase: "postConstruct" | "preDestroy",
+  methodName: string,
+): void {
+  if (!metadata[phase].includes(methodName)) {
+    metadata[phase].push(methodName);
+  }
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function postConstruct(): (target: unknown, context: ClassMethodDecoratorContext) => void {
+  return function (target: unknown, context: ClassMethodDecoratorContext): void {
+    if (context.static === true) {
+      throw new InternalError(
+        "@postConstruct() applies to instance methods only; static methods are not invoked during instance lifecycle.",
+      );
+    }
+    const methodName = String(context.name);
+    const meta = context.metadata as Record<string | symbol, unknown>;
+    if (!meta[LIFECYCLE_KEY]) {
+      meta[LIFECYCLE_KEY] = { postConstruct: [], preDestroy: [] };
+    }
+    appendUniqueMethod(
+      meta[LIFECYCLE_KEY] as MutableLifecycleMetadata,
+      "postConstruct",
+      methodName,
+    );
+  };
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function preDestroy(): (target: unknown, context: ClassMethodDecoratorContext) => void {
+  return function (target: unknown, context: ClassMethodDecoratorContext): void {
+    if (context.static === true) {
+      throw new InternalError(
+        "@preDestroy() applies to instance methods only; static methods are not invoked during instance teardown.",
+      );
+    }
+    const methodName = String(context.name);
+    const meta = context.metadata as Record<string | symbol, unknown>;
+    if (!meta[LIFECYCLE_KEY]) {
+      meta[LIFECYCLE_KEY] = { postConstruct: [], preDestroy: [] };
+    }
+    appendUniqueMethod(meta[LIFECYCLE_KEY] as MutableLifecycleMetadata, "preDestroy", methodName);
+  };
+}

package/src/dependency-graph.ts

@@ -0,0 +1,116 @@
+import type { BindingRegistry } from "#/registry";
+import type { MetadataReader } from "#/metadata/metadata-types";
+import type { BindingScope, Constructor } from "#/types";
+import { tokenName } from "#/token";
+import { effectiveBindingScope } from "#/binding-scope";
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface GraphNode {
+  readonly id: string;
+  readonly tokenName: string;
+  readonly kind: string;
+  readonly scope: BindingScope;
+  readonly fromParent: boolean;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface GraphEdge {
+  readonly from: string;
+  readonly to: string;
+  readonly label?: string;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface ContainerGraphJson {
+  readonly nodes: ReadonlyArray<GraphNode>;
+  readonly edges: ReadonlyArray<GraphEdge>;
+  readonly includesParent: boolean;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface GraphOptions {
+  readonly includeParent?: boolean;
+}
+
+// ── Builder ───────────────────────────────────────────────────────────────────
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function buildDependencyGraph(
+  registry: BindingRegistry,
+  metadataReader: MetadataReader,
+  options: GraphOptions | undefined,
+  parentRegistry?: BindingRegistry,
+): ContainerGraphJson {
+  const nodes: Array<GraphNode> = [];
+  const edges: Array<GraphEdge> = [];
+  const includesParent = options?.includeParent === true;
+
+  const addBindings = (sourceRegistry: BindingRegistry, fromParent: boolean): void => {
+    for (const binding of sourceRegistry.allBindings()) {
+      const scope = effectiveBindingScope(binding);
+      nodes.push({
+        id: binding.id,
+        tokenName: tokenName(binding.token),
+        kind: binding.kind,
+        scope,
+        fromParent,
+      });
+
+      // Build edges
+      if (binding.kind === "class") {
+        const meta = metadataReader.getConstructorMetadata(binding.target as Constructor);
+        if (meta !== undefined) {
+          for (let index = 0; index < meta.params.length; index += 1) {
+            const param = meta.params[index]!;
+            const dependencyBinding = sourceRegistry.getAll(param.token as Constructor)[0];
+            if (dependencyBinding !== undefined) {
+              edges.push({
+                from: binding.id,
+                to: dependencyBinding.id,
+                label: `[${index}]`,
+              });
+            }
+          }
+        }
+      } else if (binding.kind === "resolved" || binding.kind === "resolved-async") {
+        for (let index = 0; index < binding.deps.length; index += 1) {
+          const dependency = binding.deps[index]!;
+          const dependencyBindings = sourceRegistry.getAll(dependency.token as Constructor);
+          if (dependencyBindings.length > 0 && dependencyBindings[0] !== undefined) {
+            const label =
+              dependency.name !== undefined
+                ? `name:${dependency.name}`
+                : dependency.tags !== undefined && dependency.tags.length > 0
+                  ? `tag:${dependency.tags[0]?.[0]}=${String(dependency.tags[0]?.[1])}`
+                  : `[${index}]`;
+            edges.push({ from: binding.id, to: dependencyBindings[0].id, label });
+          }
+        }
+      } else if (binding.kind === "alias") {
+        const targetBindings = sourceRegistry.getAll(binding.target as Constructor);
+        if (targetBindings.length > 0 && targetBindings[0] !== undefined) {
+          edges.push({ from: binding.id, to: targetBindings[0].id, label: "alias" });
+        }
+      }
+    }
+  };
+
+  addBindings(registry, false);
+  if (includesParent && parentRegistry !== undefined) {
+    addBindings(parentRegistry, true);
+  }
+
+  return { nodes, edges, includesParent };
+}