@praxisjs/di 0.2.2 → 1.0.0

package/src/__tests__/decorators.test.ts

@@ -1,173 +1,228 @@
 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";
 
-// Each test group uses a fresh container to avoid state pollution
-function makeScope() {
-  return new Container();
+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 ────────────────────────────────────────────────────────────────
+// ── @Injectable ───────────────────────────────────────────────────────────────
 
 describe("Injectable", () => {
   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");
+  });
 });
 
-// ── 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);
-    });
-
-    expect(instance.container).toBeInstanceOf(Container);
+    run(instance);
+    expect(instance.c).toBeInstanceOf(Container);
+    expect(instance.c).toBe(container);
   });
 });
 
-// ── 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 {}
+
+    const { ctx, run } = makeFieldCtx("db");
+    Inject(DB_URL)(undefined, ctx);
+
+    const instance = new DataModule() as Record<string, unknown>;
+    run(instance);
 
-describe("useService", () => {
-  it("resolves by Token", () => {
+    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 {}
 
-describe("createScope", () => {
-  it("creates a child container without configure fn", () => {
-    const child = createScope();
-    expect(child).toBeInstanceOf(Container);
+    const { ctx, run } = makeFieldCtx("container");
+    InjectContainer()(undefined, ctx);
+
+    const instance = new Service() as Record<string, unknown>;
+    run(instance);
+
+    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);
   });
 });

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;

package/src/decorators.ts

@@ -1,4 +1,15 @@
-import { container, type Container, Token, type Constructor, type InjectableOptions  } from "./container";
+import { createFieldDecorator, type FieldBinding } from "@praxisjs/decorators";
+
+import { container, type Container, Token, type Constructor, type InjectableOptions } from "./container";
+
+// Maps instances to their scoped child containers (set by @Scope).
+const scopedContainers = new WeakMap<object, Container>();
+
+function resolveFrom(instance: object) {
+  return scopedContainers.get(instance) ?? container;
+}
+
+// ── @Injectable ───────────────────────────────────────────────────────────────
 
 export function Injectable(options: InjectableOptions = {}) {
   return function (value: Constructor, _context: ClassDecoratorContext): void {
@@ -6,67 +17,95 @@ export function Injectable(options: InjectableOptions = {}) {
   };
 }
 
+// ── @Scope ────────────────────────────────────────────────────────────────────
+
+/**
+ * Creates a child DI container scoped to each instance of the decorated class.
+ * Services registered in the configure callback are available within the scope,
+ * and @Inject / @InjectContainer will resolve from it automatically.
+ *
+ * @Scope((c) => {
+ *   c.register(UserRepository);
+ *   c.registerValue(AuthToken, 'abc');
+ * })
+ * class UserModule extends StatefulComponent {
+ *   @Inject(UserRepository) repo!: UserRepository;
+ * }
+ */
+export function Scope(configure?: (c: Container) => void) {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return function(cls: new (...args: any[]) => any, _ctx: ClassDecoratorContext): any {
+     
+    return class extends cls {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      constructor(...args: any[]) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+        super(...args);
+        const child = container.createChild();
+        configure?.(child);
+        scopedContainers.set(this as object, child);
+      }
+    };
+  };
+}
+
+// ── @Inject ───────────────────────────────────────────────────────────────────
+
 export function Inject<T>(dep: Constructor<T> | Token<T>) {
-  return function (_value: undefined, context: ClassFieldDecoratorContext): void {
-    const cache = new WeakMap<object, T>();
-    const propertyKey = String(context.name);
+  const cache = new WeakMap<object, T>();
 
-    context.addInitializer(function (this: unknown) {
-      Object.defineProperty(this, context.name, {
-        get(this: object): T {
-          if (!cache.has(this)) {
-            let resolved: T;
-            try {
-              resolved = container.resolve(dep as Constructor<T>);
-            } catch (err) {
-              throw new Error(
-                `[Inject] Failed to resolve "${
-                  dep instanceof Token
-                    ? dep.toString()
-                    : (dep as Constructor).name
-                }" in "${(this as { constructor: { name: string } }).constructor.name}.${propertyKey}": ${(err as Error).message}`,
+  return createFieldDecorator({
+    bind(_instance, name, _initialValue): FieldBinding {
+      return {
+        descriptor: {
+          get(this: object): T {
+            if (!cache.has(this)) {
+              const c = resolveFrom(this);
+              let resolved: T;
+              try {
+                resolved = c.resolve(dep as Constructor<T>);
+              } catch (err) {
+                throw new Error(
+                  `[Inject] Failed to resolve "${
+                    dep instanceof Token
+                      ? dep.toString()
+                      : (dep as Constructor).name
+                  }" in "${(this as { constructor: { name: string } }).constructor.name}.${name}": ${(err as Error).message}`,
+                );
+              }
+              cache.set(this, resolved);
+            }
+            return cache.get(this) as T;
+          },
+          set(_value: unknown): void {
+            if (process.env.NODE_ENV !== "production") {
+              console.warn(
+                `[Inject] "${name}" is managed by the DI container and cannot be assigned directly.`,
               );
             }
-            cache.set(this, resolved);
-          }
-          return cache.get(this) as T;
+          },
         },
-
-        set(_value: unknown): void {
-          if (process.env.NODE_ENV !== "production") {
-            console.warn(
-              `[Inject] "${propertyKey}" is managed by the DI container and cannot be assigned directly.`,
-            );
-          }
-        },
-
-        enumerable: true,
-        configurable: true,
-      });
-    });
-  };
+      };
+    },
+  // DI decorators work on any class, not just StatefulComponent
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  }) as unknown as (_value: undefined, context: ClassFieldDecoratorContext<any>) => void;
 }
 
+// ── @InjectContainer ──────────────────────────────────────────────────────────
+
 export function InjectContainer() {
-  return function (_value: undefined, context: ClassFieldDecoratorContext): void {
-    context.addInitializer(function (this: unknown) {
-      Object.defineProperty(this, context.name, {
-        get() {
-          return container;
+  return createFieldDecorator({
+    bind(_instance, _name, _initialValue): FieldBinding {
+      return {
+        descriptor: {
+          get(this: object) {
+            return resolveFrom(this);
+          },
         },
-        enumerable: true,
-        configurable: true,
-      });
-    });
-  };
-}
-
-export function useService<T>(dep: Constructor<T> | Token<T>): T {
-  return container.resolve(dep as Constructor<T>);
-}
-
-export function createScope(configure?: (c: Container) => void): Container {
-  const child = container.createChild();
-  configure?.(child);
-  return child;
+      };
+    },
+  // DI decorators work on any class, not just StatefulComponent
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  }) as unknown as (_value: undefined, context: ClassFieldDecoratorContext<any>) => void;
 }

package/src/index.ts

@@ -4,12 +4,11 @@ export {
   Injectable,
   Inject,
   InjectContainer,
-  useService,
-  createScope,
+  Scope,
 } from "./decorators";
 export { Container, container, Token, token } from "./container";
 export type {
-  Scope,
+  Scope as ScopeType,
   InjectableOptions,
   Constructor,
   ServiceDescriptor,