@praxisjs/di 0.2.3 → 1.1.0

package/src/__tests__/decorators.test.ts

@@ -1,191 +1,281 @@
 import "reflect-metadata";
 import { describe, it, expect, vi } from "vitest";
 
-import { Container, token } from "../container";
+import { Container, container, token } from "../container";
 import {
   Injectable,
   Inject,
   InjectContainer,
-  useService,
-  createScope,
+  Scope,
 } from "../decorators";
 
-// ── Injectable ────────────────────────────────────────────────────────────────
+function makeFieldCtx(name: string) {
+  const initializers: Array<(this: unknown) => void> = [];
+  return {
+    ctx: {
+      name,
+      kind: "field" as const,
+      addInitializer(fn: (this: unknown) => void) { initializers.push(fn); },
+    } as ClassFieldDecoratorContext,
+    run(instance: unknown) { initializers.forEach((fn) => { fn.call(instance); }); },
+  };
+}
+
+// ── @Injectable ───────────────────────────────────────────────────────────────
 
 describe("Injectable", () => {
+  it("with no arguments — defaults to singleton scope", () => {
+    class SingletonByDefault {}
+    Injectable()(SingletonByDefault, {} as ClassDecoratorContext);
+    const a = container.resolve(SingletonByDefault);
+    const b = container.resolve(SingletonByDefault);
+    expect(a).toBe(b);
+  });
+
   it("registers the class in the global container", () => {
-    // We test via useService resolving without throwing
     class MyService {
-      greet() {
-        return "hello";
-      }
+      greet() { return "hello"; }
     }
     Injectable()(MyService, {} as ClassDecoratorContext);
-    const instance = useService(MyService);
-    expect(instance).toBeInstanceOf(MyService);
-    expect(instance.greet()).toBe("hello");
+    expect(container.resolve(MyService)).toBeInstanceOf(MyService);
+    expect(container.resolve(MyService).greet()).toBe("hello");
   });
 
-  it("registers with transient scope", () => {
+  it("registers with transient scope — each resolve returns a new instance", () => {
     class TmpService {}
     Injectable({ scope: "transient" })(TmpService, {} as ClassDecoratorContext);
-    const a = useService(TmpService);
-    const b = useService(TmpService);
-    expect(a).not.toBe(b);
+    expect(container.resolve(TmpService)).not.toBe(container.resolve(TmpService));
   });
 });
 
-// ── Inject ────────────────────────────────────────────────────────────────────
+// ── @Inject ───────────────────────────────────────────────────────────────────
 
 describe("Inject", () => {
   it("injects a registered service via property", () => {
     class Logger {
-      log(msg: string) {
-        return msg;
-      }
+      log(msg: string) { return msg; }
     }
     Injectable()(Logger, {} as ClassDecoratorContext);
 
-    const initializers: Array<(this: unknown) => void> = [];
-    const ctx = {
-      name: "logger",
-      kind: "field" as const,
-      addInitializer(fn: (this: unknown) => void) {
-        initializers.push(fn);
-      },
-    } as ClassFieldDecoratorContext;
-
+    const { ctx, run } = makeFieldCtx("logger");
     Inject(Logger)(undefined, ctx);
-
     const instance: Record<string, unknown> = {};
-    initializers.forEach((fn) => {
-      fn.call(instance);
-    });
-
+    run(instance);
     expect(instance.logger).toBeInstanceOf(Logger);
+    // second access covers the cache-hit branch (line 62: !cache.has(this) === false)
+    expect(instance.logger).toBe(instance.logger);
   });
 
   it("throws a descriptive error when dep is not registered", () => {
     class UnknownDep {}
-
-    const initializers: Array<(this: unknown) => void> = [];
-    const ctx = {
-      name: "dep",
-      kind: "field" as const,
-      addInitializer(fn: (this: unknown) => void) {
-        initializers.push(fn);
-      },
-    } as ClassFieldDecoratorContext;
-
+    const { ctx, run } = makeFieldCtx("dep");
     Inject(UnknownDep)(undefined, ctx);
-
-    class MyClass {
-      constructor() {}
-    }
+    class MyClass {}
     const instance = new MyClass() as Record<string, unknown>;
-    initializers.forEach((fn) => {
-      fn.call(instance);
-    });
-
+    run(instance);
     expect(() => instance.dep).toThrow("[Inject]");
   });
 
   it("warns on direct assignment in non-production", () => {
     class Dep2 {}
     Injectable()(Dep2, {} as ClassDecoratorContext);
-
-    const initializers: Array<(this: unknown) => void> = [];
-    const ctx = {
-      name: "dep2",
-      kind: "field" as const,
-      addInitializer(fn: (this: unknown) => void) {
-        initializers.push(fn);
-      },
-    } as ClassFieldDecoratorContext;
-
+    const { ctx, run } = makeFieldCtx("dep2");
     Inject(Dep2)(undefined, ctx);
     const instance: Record<string, unknown> = {};
-    initializers.forEach((fn) => {
-      fn.call(instance);
-    });
-
+    run(instance);
     const spy = vi.spyOn(console, "warn").mockImplementation(() => {});
     instance.dep2 = "override";
     expect(spy).toHaveBeenCalledWith(expect.stringContaining("[Inject]"));
     spy.mockRestore();
   });
+
+  it("returns cached value on second access (cache hit)", () => {
+    class CachedService {
+      id = Math.random();
+    }
+    Injectable()(CachedService, {} as ClassDecoratorContext);
+
+    const { ctx, run } = makeFieldCtx("svc");
+    Inject(CachedService)(undefined, ctx);
+    const instance: Record<string, unknown> = {};
+    run(instance);
+
+    const first = instance.svc;
+    const second = instance.svc;
+    expect(first).toBe(second); // same cached instance
+  });
+
+  it("does not warn on direct assignment in production mode", () => {
+    class ProdDep {}
+    Injectable()(ProdDep, {} as ClassDecoratorContext);
+    const { ctx, run } = makeFieldCtx("dep");
+    Inject(ProdDep)(undefined, ctx);
+    const instance: Record<string, unknown> = {};
+    run(instance);
+
+    const spy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    vi.stubEnv("NODE_ENV", "production");
+    instance.dep = "override";
+    expect(spy).not.toHaveBeenCalled();
+
+    vi.unstubAllEnvs();
+    spy.mockRestore();
+  });
+
+  it("includes the Token description in the error when resolution fails", () => {
+    const MY_TOKEN = token<string>("MY_SERVICE");
+    const { ctx, run } = makeFieldCtx("svc");
+    Inject(MY_TOKEN)(undefined, ctx);
+    class Consumer {}
+    const instance = new Consumer() as Record<string, unknown>;
+    run(instance);
+    expect(() => instance.svc).toThrow("MY_SERVICE");
+  });
+
+  it("@Inject on an anonymous class — error message uses token description instead of empty class name", () => {
+    const ANON_TOKEN = token<string>("ANON_TOKEN");
+    const { ctx, run } = makeFieldCtx("val");
+    Inject(ANON_TOKEN)(undefined, ctx);
+    const instance: Record<string, unknown> = {};
+    run(instance);
+    expect(() => instance.val).toThrow("ANON_TOKEN");
+  });
 });
 
-// ── InjectContainer ───────────────────────────────────────────────────────────
+// ── @InjectContainer ──────────────────────────────────────────────────────────
 
 describe("InjectContainer", () => {
-  it("injects the global container instance", () => {
-    const initializers: Array<(this: unknown) => void> = [];
-    const ctx = {
-      name: "container",
-      kind: "field" as const,
-      addInitializer(fn: (this: unknown) => void) {
-        initializers.push(fn);
-      },
-    } as ClassFieldDecoratorContext;
-
+  it("injects the global container on an unscoped class", () => {
+    const { ctx, run } = makeFieldCtx("c");
     InjectContainer()(undefined, ctx);
     const instance: Record<string, unknown> = {};
-    initializers.forEach((fn) => {
-      fn.call(instance);
-    });
+    run(instance);
+    expect(instance.c).toBeInstanceOf(Container);
+    expect(instance.c).toBe(container);
+  });
 
-    expect(instance.container).toBeInstanceOf(Container);
+  it("called multiple times on same instance — returns same container instance (cached)", () => {
+    const { ctx, run } = makeFieldCtx("c");
+    InjectContainer()(undefined, ctx);
+    const instance: Record<string, unknown> = {};
+    run(instance);
+    const first = instance.c;
+    const second = instance.c;
+    expect(first).toBe(second);
   });
 });
 
-// ── useService ────────────────────────────────────────────────────────────────
+// ── @Scope ────────────────────────────────────────────────────────────────────
+
+describe("Scope", () => {
+  it("creates a child container per instance", () => {
+    @Scope()
+    class Widget {}
+    const { ctx, run } = makeFieldCtx("c");
+    InjectContainer()(undefined, ctx);
+
+    const a = new Widget() as Record<string, unknown>;
+    run(a);
+    const b = new Widget() as Record<string, unknown>;
+    run(b);
+
+    expect(a.c).toBeInstanceOf(Container);
+    expect(b.c).toBeInstanceOf(Container);
+    expect(a.c).not.toBe(b.c); // each instance gets its own scope
+    expect(a.c).not.toBe(container); // it's a child, not the root
+  });
+
+  it("services registered in configure are resolvable within the scope", () => {
+    const DB_URL = token<string>("DB_URL");
+
+    @Scope((c) => { c.registerValue(DB_URL, "postgres://localhost"); })
+    class DataModule {}
 
-describe("useService", () => {
-  it("resolves by Token", () => {
+    const { ctx, run } = makeFieldCtx("db");
+    Inject(DB_URL)(undefined, ctx);
+
+    const instance = new DataModule() as Record<string, unknown>;
+    run(instance);
+
+    expect(instance.db).toBe("postgres://localhost");
+  });
+
+  it("@Inject resolves from the scoped container, not the global one", () => {
+    class ScopedRepo {}
+    // NOT registered in global container
     const VERSION = token<string>("VERSION");
-    const c = createScope((sc) => sc.registerValue(VERSION, "1.0.0"));
-    // useService uses global container — test via token on a fresh child
-    expect(c.resolve(VERSION)).toBe("1.0.0");
+
+    @Scope((c) => {
+      c.register(ScopedRepo);
+      c.registerValue(VERSION, "2.0");
+    })
+    class App {}
+
+    const { ctx: repoCtx, run: runRepo } = makeFieldCtx("repo");
+    Inject(ScopedRepo)(undefined, repoCtx);
+    const { ctx: verCtx, run: runVer } = makeFieldCtx("version");
+    Inject(VERSION)(undefined, verCtx);
+
+    const instance = new App() as Record<string, unknown>;
+    runRepo(instance);
+    runVer(instance);
+
+    expect(instance.repo).toBeInstanceOf(ScopedRepo);
+    expect(instance.version).toBe("2.0");
   });
-});
 
-// ── createScope ───────────────────────────────────────────────────────────────
+  it("@InjectContainer returns the scoped child container", () => {
+    @Scope((c) => { c.registerValue(token<number>("X"), 42); })
+    class Service {}
+
+    const { ctx, run } = makeFieldCtx("container");
+    InjectContainer()(undefined, ctx);
+
+    const instance = new Service() as Record<string, unknown>;
+    run(instance);
 
-describe("createScope", () => {
-  it("creates a child container without configure fn", () => {
-    const child = createScope();
-    expect(child).toBeInstanceOf(Container);
+    expect(instance.container).toBeInstanceOf(Container);
+    expect(instance.container).not.toBe(container);
   });
 
-  it("applies the configure callback", () => {
-    const DB = token<string>("DB");
-    const child = createScope((c) =>
-      c.registerValue(DB, "postgres://localhost"),
-    );
-    expect(child.resolve(DB)).toBe("postgres://localhost");
+  it("child container inherits registrations from the parent", () => {
+    class GlobalService {}
+    Injectable()(GlobalService, {} as ClassDecoratorContext);
+
+    @Scope()
+    class Child {}
+
+    const { ctx, run } = makeFieldCtx("svc");
+    Inject(GlobalService)(undefined, ctx);
+    const instance = new Child() as Record<string, unknown>;
+    run(instance);
+
+    expect(instance.svc).toBeInstanceOf(GlobalService);
   });
-});
 
-// ── Inject — Token in error message ──────────────────────────────────────────
+  it("@Scope on child class that inherits from @Scope parent — child gets own container", () => {
+    const PARENT_TOKEN = token<string>("PARENT_VAL");
+    const CHILD_TOKEN = token<string>("CHILD_VAL");
 
-describe("Inject — Token error display", () => {
-  it("includes the Token description in the error message when resolution fails", () => {
-    const MY_TOKEN = token<string>("MY_SERVICE");
+    @Scope((c) => { c.registerValue(PARENT_TOKEN, "parent"); })
+    class Parent {}
 
-    const initializers: Array<(this: unknown) => void> = [];
-    const ctx = {
-      name: "svc",
-      kind: "field" as const,
-      addInitializer(fn: (this: unknown) => void) { initializers.push(fn); },
-    } as ClassFieldDecoratorContext;
+    @Scope((c) => { c.registerValue(CHILD_TOKEN, "child"); })
+    class Child extends (Parent as unknown as new () => object) {}
 
-    Inject(MY_TOKEN)(undefined, ctx);
+    const { ctx: ctxC, run: runC } = makeFieldCtx("c");
+    InjectContainer()(undefined, ctxC);
 
-    class Consumer { constructor() {} }
-    const instance = new Consumer() as Record<string, unknown>;
-    initializers.forEach((fn) => { fn.call(instance); });
+    const parentInstance = new Parent() as Record<string, unknown>;
+    runC(parentInstance);
 
-    expect(() => instance.svc).toThrow("MY_SERVICE");
+    const childInstance = new Child() as Record<string, unknown>;
+    runC(childInstance);
+
+    expect(parentInstance.c).toBeInstanceOf(Container);
+    expect(childInstance.c).toBeInstanceOf(Container);
+    // child has its own scoped container, different from the parent's
+    expect(childInstance.c).not.toBe(parentInstance.c);
+    expect(childInstance.c).not.toBe(container);
   });
 });

package/src/container.ts

@@ -10,7 +10,8 @@ export interface ServiceDescriptor {
   instance?: unknown;
 }
 
-export type Constructor<T = unknown> = new (...args: unknown[]) => T;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type Constructor<T = unknown> = new (...args: any[]) => T;
 
 export class Token<_T> {
   readonly description: string;
@@ -58,38 +59,70 @@ export class Container {
     return this;
   }
 
-  resolve<T>(target: Constructor<T> | Token<T>): T {
-    const entry = this.services.get(target as Constructor | Token<unknown>);
-
-    if (target instanceof Token) {
-      if (entry !== undefined) return entry as T;
-      if (this.parent) return this.parent.resolve(target);
-      throw new Error(`[DI] Token not registered: ${target.toString()}`);
-    }
-
-    if (!entry) {
-      if (this.parent) return this.parent.resolve(target);
-      throw new Error(
-        `[DI] Service not registered: ${(target as Constructor).name}`,
-      );
+  resolve<T>(
+    target: Constructor<T> | Token<T>,
+    resolutionStack = new Set<Constructor | Token<unknown>>(),
+  ): T {
+    const key = target as Constructor | Token<unknown>;
+
+    if (resolutionStack.has(key)) {
+      const chain = [...resolutionStack, key]
+        .map((k) =>
+          k instanceof Token ? k.toString() : (k).name,
+        )
+        .join(" → ");
+      throw new Error(`[DI] Circular dependency detected: ${chain}`);
     }
 
-    const descriptor = entry as ServiceDescriptor;
-
-    if (descriptor.scope === "singleton") {
-      descriptor.instance ??= this.instantiate(descriptor.target);
-      return descriptor.instance as T;
+    resolutionStack.add(key);
+    try {
+      const entry = this.services.get(key);
+
+      if (target instanceof Token) {
+        if (entry !== undefined) return entry as T;
+        if (this.parent) return this.parent.resolve(target);
+        throw new Error(`[DI] Token not registered: ${target.toString()}`);
+      }
+
+      if (!entry) {
+        if (this.parent) return this.parent.resolve(target);
+        throw new Error(
+          `[DI] Service not registered: ${(target as Constructor).name}`,
+        );
+      }
+
+      const descriptor = entry as ServiceDescriptor;
+
+      if (descriptor.scope === "singleton") {
+        descriptor.instance ??= this.instantiate(descriptor.target, resolutionStack);
+        return descriptor.instance as T;
+      }
+
+      return this.instantiate(descriptor.target, resolutionStack) as T;
+    } finally {
+      resolutionStack.delete(key);
     }
-
-    return this.instantiate(descriptor.target) as T;
   }
 
-  private instantiate<T>(target: Constructor<T>): T {
+  private instantiate<T>(
+    target: Constructor<T>,
+    resolutionStack = new Set<Constructor | Token<unknown>>(),
+  ): T {
     const deps: Array<Constructor | Token<unknown>> =
       (Reflect.getMetadata("di:inject", target) as Array<Constructor | Token<unknown>> | undefined) ?? [];
 
-    const resolvedDeps = deps.map((dep) => this.resolve(dep as Constructor));
-    const instance = new target(...resolvedDeps);
+    const resolvedDeps = deps.map((dep) =>
+      this.resolve(dep as Constructor, resolutionStack),
+    );
+    let instance: T;
+    try {
+      instance = new target(...resolvedDeps);
+    } catch (err) {
+      if (err instanceof Error && err.message.startsWith("[DI]")) throw err;
+      throw new Error(
+        `[DI] Failed to instantiate "${target.name}": ${(err as Error).message}`,
+      );
+    }
 
     const rawPropInjections: unknown = Reflect.getMetadata("di:props", target.prototype as object);
     const propInjections =
@@ -98,6 +131,7 @@ export class Container {
     for (const [prop, dep] of propInjections) {
       (instance as Record<string, unknown>)[prop] = this.resolve(
         dep as Constructor,
+        resolutionStack,
       );
     }