@djodjonx/neo-syringe 1.1.5 → 1.2.0

package/src/types.ts

@@ -5,11 +5,11 @@
 export type Constructor<T = unknown> = new (...args: unknown[]) => T;
 
 /**
- * Defines the lifecycle scope of a service.
+ * Defines the lifecycle of a service.
  * - `singleton`: One instance per container.
  * - `transient`: A new instance every time it is resolved.
  */
-export type Scope = 'singleton' | 'transient';
+export type Lifecycle = 'singleton' | 'transient';
 
 /**
  * The dependency injection container interface.
@@ -86,7 +86,33 @@ export interface Injection<T = any> {
    * Required when provider is a function, not a class.
    */
   useFactory?: boolean;
-  scope?: Scope;
+  /**
+   * Lifecycle of the service.
+   * - `singleton`: One instance per container (default).
+   * - `transient`: A new instance every time it is resolved.
+   */
+  lifecycle?: Lifecycle;
+  /**
+   * If true, this injection is scoped to this container only.
+   * Allows overriding a token from a parent container without causing a duplicate error.
+   * The local instance will be used instead of delegating to the parent.
+   *
+   * @example
+   * ```typescript
+   * const parent = defineBuilderConfig({
+   *   injections: [{ token: useInterface<ILogger>(), provider: ConsoleLogger }]
+   * });
+   *
+   * const child = defineBuilderConfig({
+   *   useContainer: parent,
+   *   injections: [
+   *     // Override parent's ILogger with a local FileLogger
+   *     { token: useInterface<ILogger>(), provider: FileLogger, scoped: true }
+   *   ]
+   * });
+   * ```
+   */
+  scoped?: boolean;
 }
 
 /**

package/tests/analyzer/Analyzer.test.ts

@@ -49,8 +49,8 @@ describe('Analyzer', () => {
         class B {}
         export const container = defineBuilderConfig({
           injections: [
-            { token: A, scope: 'transient' },
-            { token: B, scope: 'singleton' }
+            { token: A, lifecycle: 'transient' },
+            { token: B, lifecycle: 'singleton' }
           ]
         });
       `;
@@ -69,7 +69,7 @@ describe('Analyzer', () => {
       const analyzer = new Analyzer(program);
       const graph = analyzer.extract();
 
-      expect(graph.nodes.get('A')?.service.scope).toBe('transient');
-      expect(graph.nodes.get('B')?.service.scope).toBe('singleton');
+      expect(graph.nodes.get('A')?.service.lifecycle).toBe('transient');
+      expect(graph.nodes.get('B')?.service.lifecycle).toBe('singleton');
   });
 });

package/tests/analyzer/Factory.test.ts

@@ -151,7 +151,7 @@ describe('Analyzer - Factory Support', () => {
           {
             token: useInterface<IRequest>(),
             provider: () => ({ id: ++counter }),
-            scope: 'transient'
+            lifecycle: 'transient'
           }
         ]
       });
@@ -163,7 +163,7 @@ describe('Analyzer - Factory Support', () => {
 
     const node = findNodeByName(graph, 'IRequest');
     expect(node?.service.isFactory).toBe(true);
-    expect(node?.service.scope).toBe('transient');
+    expect(node?.service.lifecycle).toBe('transient');
   });
 
   it('should not treat class as factory', () => {

package/tests/analyzer/Scoped.test.ts

@@ -0,0 +1,434 @@
+/**
+ * Tests for scoped: true functionality
+ *
+ * Allows overriding a token from a parent container
+ * without causing a duplicate registration error.
+ */
+import { describe, it, expect } from 'vitest';
+import * as ts from 'typescript';
+import { Analyzer } from '../../src/analyzer/Analyzer';
+import { GraphValidator } from '../../src/generator/GraphValidator';
+import { Generator } from '../../src/generator/Generator';
+
+describe('Scoped Injection', () => {
+  const createProgram = (fileName: string, fileContent: string) => {
+    const compilerHost = ts.createCompilerHost({});
+    const originalGetSourceFile = compilerHost.getSourceFile;
+
+    compilerHost.getSourceFile = (name, languageVersion) => {
+      if (name === fileName) {
+        return ts.createSourceFile(fileName, fileContent, languageVersion);
+      }
+      return originalGetSourceFile(name, languageVersion);
+    };
+
+    return ts.createProgram([fileName], {}, compilerHost);
+  };
+
+  describe('Analyzer - scoped detection', () => {
+    it('should detect scoped: true in injection', () => {
+      const program = createProgram('scoped.ts', `
+        function defineBuilderConfig(config: any) { return config; }
+        function useInterface<T>(): any { return null; }
+
+        interface ILogger {}
+        class FileLogger implements ILogger {}
+
+        export const c = defineBuilderConfig({
+          injections: [
+            { token: useInterface<ILogger>(), provider: FileLogger, scoped: true }
+          ]
+        });
+      `);
+
+      const analyzer = new Analyzer(program);
+      const graph = analyzer.extract();
+
+      // Find node containing ILogger (may have filename prefix)
+      const node = Array.from(graph.nodes.values()).find(n =>
+        n.service.tokenId.includes('ILogger')
+      );
+      expect(node).toBeDefined();
+      expect(node!.service.isScoped).toBe(true);
+    });
+
+    it('should detect scoped: false (default) when not specified', () => {
+      const program = createProgram('not-scoped.ts', `
+        function defineBuilderConfig(config: any) { return config; }
+        function useInterface<T>(): any { return null; }
+
+        interface ILogger {}
+        class ConsoleLogger implements ILogger {}
+
+        export const c = defineBuilderConfig({
+          injections: [
+            { token: useInterface<ILogger>(), provider: ConsoleLogger }
+          ]
+        });
+      `);
+
+      const analyzer = new Analyzer(program);
+      const graph = analyzer.extract();
+
+      // Find node containing ILogger (may have filename prefix)
+      const node = Array.from(graph.nodes.values()).find(n =>
+        n.service.tokenId.includes('ILogger')
+      );
+      expect(node).toBeDefined();
+      expect(node!.service.isScoped).toBeFalsy();
+    });
+
+    it('should allow duplicate registration when scoped: true in same container', () => {
+      const program = createProgram('scoped-same.ts', `
+        function defineBuilderConfig(config: any) { return config; }
+        function useInterface<T>(): any { return null; }
+
+        interface ILogger {}
+        class FileLogger implements ILogger {}
+
+        export const c = defineBuilderConfig({
+          injections: [
+            { token: useInterface<ILogger>(), provider: FileLogger, scoped: true },
+            { token: useInterface<ILogger>(), provider: FileLogger, scoped: true }
+          ]
+        });
+      `);
+
+      const analyzer = new Analyzer(program);
+      // Should not throw - second scoped: true overrides the first
+      expect(() => analyzer.extract()).not.toThrow();
+    });
+  });
+
+  describe('GraphValidator - scoped with parent', () => {
+    it('should throw duplicate error without scoped: true', () => {
+      const program = createProgram('duplicate.ts', `
+        function defineBuilderConfig(config: any) { return config; }
+        function useInterface<T>(): any { return null; }
+
+        interface ILogger {}
+        class ConsoleLogger implements ILogger {}
+        class FileLogger implements ILogger {}
+
+        const parent = defineBuilderConfig({
+          injections: [{ token: useInterface<ILogger>(), provider: ConsoleLogger }]
+        });
+
+        export const c = defineBuilderConfig({
+          useContainer: parent,
+          injections: [
+            { token: useInterface<ILogger>(), provider: FileLogger }
+          ]
+        });
+      `);
+
+      const analyzer = new Analyzer(program);
+      const graph = analyzer.extract();
+      const validator = new GraphValidator();
+
+      expect(() => validator.validate(graph)).toThrow(/Duplicate registration.*ILogger.*parent/);
+    });
+
+    it('should NOT throw duplicate error with scoped: true', () => {
+      const program = createProgram('scoped-override.ts', `
+        function defineBuilderConfig(config: any) { return config; }
+        function useInterface<T>(): any { return null; }
+
+        interface ILogger {}
+        class ConsoleLogger implements ILogger {}
+        class FileLogger implements ILogger {}
+
+        const parent = defineBuilderConfig({
+          injections: [{ token: useInterface<ILogger>(), provider: ConsoleLogger }]
+        });
+
+        export const c = defineBuilderConfig({
+          useContainer: parent,
+          injections: [
+            { token: useInterface<ILogger>(), provider: FileLogger, scoped: true }
+          ]
+        });
+      `);
+
+      const analyzer = new Analyzer(program);
+      const graph = analyzer.extract();
+      const validator = new GraphValidator();
+
+      expect(() => validator.validate(graph)).not.toThrow();
+    });
+
+    it('should suggest scoped: true in error message', () => {
+      const program = createProgram('suggest-scoped.ts', `
+        function defineBuilderConfig(config: any) { return config; }
+        function useInterface<T>(): any { return null; }
+
+        interface ICache {}
+        class RedisCache implements ICache {}
+        class MemoryCache implements ICache {}
+
+        const parent = defineBuilderConfig({
+          injections: [{ token: useInterface<ICache>(), provider: RedisCache }]
+        });
+
+        export const c = defineBuilderConfig({
+          useContainer: parent,
+          injections: [
+            { token: useInterface<ICache>(), provider: MemoryCache }
+          ]
+        });
+      `);
+
+      const analyzer = new Analyzer(program);
+      const graph = analyzer.extract();
+      const validator = new GraphValidator();
+
+      try {
+        validator.validate(graph);
+        expect.fail('Should have thrown');
+      } catch (e: any) {
+        expect(e.message).toContain('scoped: true');
+      }
+    });
+  });
+
+  describe('Generator - scoped code generation', () => {
+    it('should generate local factory for scoped token', () => {
+      const program = createProgram('gen-scoped.ts', `
+        function defineBuilderConfig(config: any) { return config; }
+        function useInterface<T>(): any { return null; }
+
+        interface ILogger {}
+        class ConsoleLogger implements ILogger {}
+        class FileLogger implements ILogger {}
+
+        const parent = defineBuilderConfig({
+          injections: [{ token: useInterface<ILogger>(), provider: ConsoleLogger }]
+        });
+
+        export const c = defineBuilderConfig({
+          name: 'ChildContainer',
+          useContainer: parent,
+          injections: [
+            { token: useInterface<ILogger>(), provider: FileLogger, scoped: true }
+          ]
+        });
+      `);
+
+      const analyzer = new Analyzer(program);
+      const graph = analyzer.extract();
+
+      // Skip validation for this test (it would throw duplicate without scoped handling in validator)
+      // The generator should include the scoped token factory
+      const generator = new Generator(graph);
+      const code = generator.generate();
+
+      // Should have a factory for ILogger (locally) - may have filename prefix
+      expect(code).toMatch(/create_.*ILogger/);
+      expect(code).toContain('FileLogger');
+    });
+
+    it('should resolve scoped token locally before parent', () => {
+      const program = createProgram('resolve-local.ts', `
+        function defineBuilderConfig(config: any) { return config; }
+        function useInterface<T>(): any { return null; }
+
+        interface ILogger {}
+        class ConsoleLogger implements ILogger {}
+        class FileLogger implements ILogger {}
+
+        const parent = defineBuilderConfig({
+          injections: [{ token: useInterface<ILogger>(), provider: ConsoleLogger }]
+        });
+
+        class UserService {
+          constructor(logger: ILogger) {}
+        }
+
+        export const c = defineBuilderConfig({
+          name: 'ChildContainer',
+          useContainer: parent,
+          injections: [
+            { token: useInterface<ILogger>(), provider: FileLogger, scoped: true },
+            { token: UserService }
+          ]
+        });
+      `);
+
+      const analyzer = new Analyzer(program);
+      const graph = analyzer.extract();
+      const generator = new Generator(graph);
+      const code = generator.generate();
+
+      // UserService should resolve ILogger from local container
+      expect(code).toContain('create_UserService');
+      expect(code).toContain('container.resolve');
+    });
+  });
+
+  describe('Scoped with different scopes (singleton/transient)', () => {
+    it('should allow scoped + transient', () => {
+      const program = createProgram('scoped-transient.ts', `
+        function defineBuilderConfig(config: any) { return config; }
+        function useInterface<T>(): any { return null; }
+
+        interface ILogger {}
+        class ConsoleLogger implements ILogger {}
+        class FileLogger implements ILogger {}
+
+        const parent = defineBuilderConfig({
+          injections: [{ token: useInterface<ILogger>(), provider: ConsoleLogger, lifecycle: 'singleton' }]
+        });
+
+        export const c = defineBuilderConfig({
+          useContainer: parent,
+          injections: [
+            {
+              token: useInterface<ILogger>(),
+              provider: FileLogger,
+              lifecycle: 'transient',  // Different scope than parent!
+              scoped: true
+            }
+          ]
+        });
+      `);
+
+      const analyzer = new Analyzer(program);
+      const graph = analyzer.extract();
+
+      // Find node containing ILogger (may have filename prefix)
+      const node = Array.from(graph.nodes.values()).find(n =>
+        n.service.tokenId.includes('ILogger')
+      );
+      expect(node).toBeDefined();
+      expect(node!.service.lifecycle).toBe('transient');
+      expect(node!.service.isScoped).toBe(true);
+    });
+
+    it('should generate transient code for scoped transient token', () => {
+      const program = createProgram('gen-scoped-transient.ts', `
+        function defineBuilderConfig(config: any) { return config; }
+        function useInterface<T>(): any { return null; }
+
+        interface IRequest {}
+        class RequestImpl implements IRequest {}
+
+        const parent = defineBuilderConfig({
+          injections: [{ token: useInterface<IRequest>(), provider: RequestImpl, lifecycle: 'singleton' }]
+        });
+
+        export const c = defineBuilderConfig({
+          name: 'RequestScope',
+          useContainer: parent,
+          injections: [
+            {
+              token: useInterface<IRequest>(),
+              provider: RequestImpl,
+              lifecycle: 'transient',
+              scoped: true
+            }
+          ]
+        });
+      `);
+
+      const analyzer = new Analyzer(program);
+      const graph = analyzer.extract();
+      const generator = new Generator(graph);
+      const code = generator.generate();
+
+      // Transient should NOT use instances cache
+      expect(code).toMatch(/create_.*IRequest/);
+      // The transient resolution should return directly without caching
+      expect(code).toMatch(/if \(token === ".*IRequest"\) \{\s*return create_/);
+    });
+  });
+
+  describe('Complex scenarios', () => {
+    it('should work with multi-level hierarchy', () => {
+      const program = createProgram('multi-level.ts', `
+        function defineBuilderConfig(config: any) { return config; }
+        function useInterface<T>(): any { return null; }
+
+        interface ILogger {}
+        class ConsoleLogger implements ILogger {}
+        class FileLogger implements ILogger {}
+        class MockLogger implements ILogger {}
+
+        // Level 1: Infrastructure
+        const infrastructure = defineBuilderConfig({
+          name: 'Infrastructure',
+          injections: [{ token: useInterface<ILogger>(), provider: ConsoleLogger }]
+        });
+
+        // Level 2: Domain (uses parent's logger)
+        const domain = defineBuilderConfig({
+          name: 'Domain',
+          useContainer: infrastructure,
+          injections: []
+        });
+
+        // Level 3: Test (overrides logger)
+        export const testModule = defineBuilderConfig({
+          name: 'TestModule',
+          useContainer: domain,
+          injections: [
+            { token: useInterface<ILogger>(), provider: MockLogger, scoped: true }
+          ]
+        });
+      `);
+
+      const analyzer = new Analyzer(program);
+      const graph = analyzer.extract();
+      const validator = new GraphValidator();
+
+      expect(() => validator.validate(graph)).not.toThrow();
+
+      // Find the ILogger node (may have filename prefix)
+      const loggerNode = Array.from(graph.nodes.values()).find(n =>
+        n.service.tokenId.includes('ILogger')
+      );
+      expect(loggerNode?.service.isScoped).toBe(true);
+    });
+
+    it('should work with factory + scoped', () => {
+      const program = createProgram('factory-scoped.ts', `
+        function defineBuilderConfig(config: any) { return config; }
+        function useInterface<T>(): any { return null; }
+
+        interface IConfig { env: string; }
+
+        const parent = defineBuilderConfig({
+          injections: [{
+            token: useInterface<IConfig>(),
+            provider: () => ({ env: 'production' })
+          }]
+        });
+
+        export const c = defineBuilderConfig({
+          useContainer: parent,
+          injections: [
+            {
+              token: useInterface<IConfig>(),
+              provider: () => ({ env: 'test' }),
+              scoped: true
+            }
+          ]
+        });
+      `);
+
+const analyzer = new Analyzer(program);
+      const graph = analyzer.extract();
+      const validator = new GraphValidator();
+
+      expect(() => validator.validate(graph)).not.toThrow();
+
+      // Find the node by checking all nodes for IConfig
+      const configNode = Array.from(graph.nodes.values()).find(n =>
+        n.service.tokenId.includes('IConfig')
+      );
+      expect(configNode).toBeDefined();
+      expect(configNode!.service.isScoped).toBe(true);
+      expect(configNode!.service.isFactory).toBe(true);
+    });
+  });
+});
+

package/tests/cli/cli.test.ts

@@ -225,5 +225,96 @@ describe('CLI - Validation Logic', () => {
       expect(() => validator.validate(graph)).toThrow(/Circular/);
     });
   });
+
+  describe('Scoped Injections', () => {
+    it('should pass validation with scoped: true override', () => {
+      const program = createProgram('scoped-valid.ts', `
+        function defineBuilderConfig(config: any) { return config; }
+        function useInterface<T>(): any { return null; }
+
+        interface ILogger {}
+        class ConsoleLogger implements ILogger {}
+        class FileLogger implements ILogger {}
+
+        const parent = defineBuilderConfig({
+          injections: [{ token: useInterface<ILogger>(), provider: ConsoleLogger }]
+        });
+
+        export const c = defineBuilderConfig({
+          useContainer: parent,
+          injections: [
+            { token: useInterface<ILogger>(), provider: FileLogger, scoped: true }
+          ]
+        });
+      `);
+
+      const analyzer = new Analyzer(program);
+      const graph = analyzer.extract();
+      const validator = new GraphValidator();
+
+      expect(() => validator.validate(graph)).not.toThrow();
+    });
+
+    it('should fail validation without scoped: true', () => {
+      const program = createProgram('scoped-invalid.ts', `
+        function defineBuilderConfig(config: any) { return config; }
+        function useInterface<T>(): any { return null; }
+
+        interface ILogger {}
+        class ConsoleLogger implements ILogger {}
+        class FileLogger implements ILogger {}
+
+        const parent = defineBuilderConfig({
+          injections: [{ token: useInterface<ILogger>(), provider: ConsoleLogger }]
+        });
+
+        export const c = defineBuilderConfig({
+          useContainer: parent,
+          injections: [
+            { token: useInterface<ILogger>(), provider: FileLogger }
+          ]
+        });
+      `);
+
+      const analyzer = new Analyzer(program);
+      const graph = analyzer.extract();
+      const validator = new GraphValidator();
+
+      expect(() => validator.validate(graph)).toThrow(/Duplicate registration.*ILogger/);
+    });
+
+    it('should suggest scoped: true in error message', () => {
+      const program = createProgram('scoped-suggest.ts', `
+        function defineBuilderConfig(config: any) { return config; }
+        function useInterface<T>(): any { return null; }
+
+        interface ICache {}
+        class RedisCache implements ICache {}
+        class MemoryCache implements ICache {}
+
+        const parent = defineBuilderConfig({
+          injections: [{ token: useInterface<ICache>(), provider: RedisCache }]
+        });
+
+        export const c = defineBuilderConfig({
+          useContainer: parent,
+          injections: [
+            { token: useInterface<ICache>(), provider: MemoryCache }
+          ]
+        });
+      `);
+
+      const analyzer = new Analyzer(program);
+      const graph = analyzer.extract();
+      const validator = new GraphValidator();
+
+      try {
+        validator.validate(graph);
+        expect.fail('Should have thrown');
+      } catch (e: any) {
+        expect(e.message).toContain("scoped: true");
+      }
+    });
+  });
 });
 

package/tests/e2e/container-integration.test.ts

@@ -22,8 +22,8 @@ describe('E2E - Container Integration', () => {
 
     private factories = new Map<any, (container: NeoContainer) => any>();
 
-    registerFactory(token: any, factory: (container: NeoContainer) => any, scope: 'singleton' | 'transient' = 'singleton') {
-      if (scope === 'transient') {
+    registerFactory(token: any, factory: (container: NeoContainer) => any, lifecycle: 'singleton' | 'transient' = 'singleton') {
+      if (lifecycle === 'transient') {
         this.factories.set(token, (c) => factory(c));
       } else {
         this.factories.set(token, (c) => {

package/tests/e2e/generated-code.test.ts

@@ -202,7 +202,7 @@ it('should resolve class dependencies on interfaces', () => {
         function defineBuilderConfig(config: any) { return config; }
         class SingletonService {}
         export const c = defineBuilderConfig({
-          injections: [{ token: SingletonService, scope: 'singleton' }]
+          injections: [{ token: SingletonService, lifecycle: 'singleton' }]
         });
       `);
 
@@ -217,7 +217,7 @@ it('should resolve class dependencies on interfaces', () => {
         function defineBuilderConfig(config: any) { return config; }
         class TransientService {}
         export const c = defineBuilderConfig({
-          injections: [{ token: TransientService, scope: 'transient' }]
+          injections: [{ token: TransientService, lifecycle: 'transient' }]
         });
       `);
 
@@ -652,10 +652,10 @@ it('should generate PropertyToken resolution', () => {
 
         export const c = defineBuilderConfig({
           injections: [
-            { token: SingletonA, scope: 'singleton' },
+            { token: SingletonA, lifecycle: 'singleton' },
             { token: SingletonB },  // Default singleton
-            { token: TransientA, scope: 'transient' },
-            { token: TransientB, scope: 'transient' }
+            { token: TransientA, lifecycle: 'transient' },
+            { token: TransientB, lifecycle: 'transient' }
           ]
         });
       `);