@djodjonx/neo-syringe 1.1.5 → 1.2.2

package/src/analyzer/types.ts

@@ -1,87 +1,93 @@
 import type { Symbol, Node } from 'typescript';
 
-export type TokenId = string; // Unique identifier for the token (Interface Name or Class Name)
+/**
+ * Unique identifier for a token (interface name or class name).
+ */
+export type TokenId = string;
 
+/**
+ * How a service was registered in the container.
+ * - `explicit`: Provider was explicitly specified.
+ * - `autowire`: Token is both the token and provider (self-binding).
+ * - `parent`: Inherited from parent container.
+ * - `factory`: Provider is a factory function.
+ */
 export type RegistrationType = 'explicit' | 'autowire' | 'parent' | 'factory';
 
+/**
+ * Represents a single service definition in the dependency graph.
+ */
 export interface ServiceDefinition {
+  /** Unique identifier for this service token. */
   tokenId: TokenId;
+
   /**
-   * The symbol of the concrete class implementation.
+   * The TypeScript symbol of the concrete class implementation.
    * Undefined if the provider is a factory function.
    */
   implementationSymbol?: Symbol;
 
   /**
-   * The symbol of the token (if it is a Class/Value).
-   * Undefined if the token is a Virtual Interface ID.
+   * The TypeScript symbol of the token (if it is a Class/Value).
+   * Undefined if the token is a virtual interface ID.
    */
   tokenSymbol?: Symbol;
 
-  /**
-   * The source node where the registration happened (for error reporting).
-   */
+  /** The source node where the registration happened (for error reporting). */
   registrationNode: Node;
 
+  /** How this service was registered. */
   type: RegistrationType;
-  scope: 'singleton' | 'transient';
 
-  /**
-   * True if the token is an Interface (requires string literal key).
-   * False if the token is a Class (requires reference key).
-   */
+  /** Lifecycle of the service instance. */
+  lifecycle: 'singleton' | 'transient';
+
+  /** True if the token is an interface (requires string literal key). */
   isInterfaceToken?: boolean;
 
-  /**
-   * True if the token is a Value Token (useToken<T>('name')).
-   * Used for primitive values like string, number, boolean.
-   */
+  /** True if the token is a value token for primitives. */
   isValueToken?: boolean;
 
-  /**
-   * True if the provider is a factory function.
-   */
+  /** True if the provider is a factory function. */
   isFactory?: boolean;
 
-  /**
-   * The raw source text of the factory function (for code generation).
-   */
+  /** The raw source text of the factory function (for code generation). */
   factorySource?: string;
+
+  /** True if this injection is scoped to the local container. */
+  isScoped?: boolean;
 }
 
+/**
+ * A node in the dependency graph representing a service and its dependencies.
+ */
 export interface DependencyNode {
+  /** The service definition. */
   service: ServiceDefinition;
-  /**
-   * The dependencies required by this service's constructor.
-   * Maps parameter index to the TokenId it depends on.
-   */
+
+  /** Token IDs of dependencies required by this service's constructor. */
   dependencies: TokenId[];
 }
 
+/**
+ * Complete dependency graph for a container configuration.
+ */
 export interface DependencyGraph {
+  /** All service nodes indexed by their token ID. */
   nodes: Map<TokenId, DependencyNode>;
-  /**
-   * The root services that are explicitly requested or exported.
-   */
+
+  /** Root services that are explicitly requested or exported. */
   roots: TokenId[];
-  /**
-   * Arguments passed to the .build() method call.
-   * Captured as raw source text to be injected into the generated constructor.
-   */
+
+  /** Arguments passed to the .build() method call (raw source text). */
   buildArguments?: string[];
-    /**
-     * The optional name of the container for debugging.
-     */
-    containerName?: string;
-
-    /**
-     * List of legacy container variable names to delegate to.
-     */
-    legacyContainers?: string[];
-
-    /**
-     * Tokens provided by the parent container (useContainer).
-     * Used for validation - these tokens don't need local bindings.
-     */
-    parentProvidedTokens?: Set<TokenId>;
-  }
+
+  /** Optional container name for debugging. */
+  containerName?: string;
+
+  /** Legacy container variable names to delegate to. */
+  legacyContainers?: string[];
+
+  /** Tokens provided by the parent container (used for validation). */
+  parentProvidedTokens?: Set<TokenId>;
+}

package/src/cli/index.ts

@@ -1,8 +1,23 @@
 #!/usr/bin/env node
+/**
+ * Neo-Syringe CLI
+ *
+ * Validates the dependency graph for a TypeScript project.
+ * Detects circular dependencies, missing bindings, and duplicate registrations.
+ *
+ * @example
+ * ```bash
+ * npx neo-syringe
+ * ```
+ */
 import * as ts from 'typescript';
 import { Analyzer } from '../analyzer/Analyzer';
 import { GraphValidator } from '../generator/GraphValidator';
 
+/**
+ * CLI entry point.
+ * Reads tsconfig.json, analyzes the project, and validates the dependency graph.
+ */
 function main() {
   const cwd = process.cwd();
   const configPath = ts.findConfigFile(cwd, ts.sys.fileExists, 'tsconfig.json');

package/src/generator/Generator.ts

@@ -2,11 +2,24 @@ import * as ts from 'typescript';
 import { DependencyGraph, TokenId } from '../analyzer/types';
 
 /**
- * Generates the TypeScript code for the dependency injection container.
+ * Generates TypeScript code for the dependency injection container.
+ *
+ * Takes a validated dependency graph and produces:
+ * - Import statements for all dependencies
+ * - Factory functions for each service
+ * - A NeoContainer class with resolve logic
  */
 export class Generator {
+  /**
+   * Creates a new Generator.
+   * @param graph - The validated dependency graph to generate code from.
+   */
   constructor(private graph: DependencyGraph) {}
 
+  /**
+   * Generates the complete container code as a string.
+   * @returns TypeScript source code for the generated container.
+   */
   public generate(): string {
     const sorted = this.topologicalSort();
     const imports = new Map<string, string>(); // filePath -> importAliasPrefix
@@ -78,7 +91,7 @@ function ${factoryId}(container: NeoContainer) {
       }
 
       // 2. Generate Resolve Switch Case
-      const isTransient = node.service.scope === 'transient';
+      const isTransient = node.service.lifecycle === 'transient';
 
       // Determine key for instances Map and token check
       let tokenKey: string;
@@ -196,6 +209,10 @@ export const container = new NeoContainer(${containerArgs});
 `;
   }
 
+  /**
+   * Sorts services in topological order (dependencies before dependents).
+   * @returns Array of TokenIds in dependency order.
+   */
   private topologicalSort(): TokenId[] {
     const visited = new Set<TokenId>();
     const sorted: TokenId[] = [];
@@ -220,6 +237,11 @@ export const container = new NeoContainer(${containerArgs});
     return sorted;
   }
 
+  /**
+   * Creates a valid JavaScript function name from a token ID.
+   * @param tokenId - The token identifier.
+   * @returns A sanitized factory function name.
+   */
   private getFactoryName(tokenId: TokenId): string {
     return `create_${tokenId.replace(/[^a-zA-Z0-9]/g, '_')}`;
   }

package/src/generator/GraphValidator.ts

@@ -19,11 +19,15 @@ export class GraphValidator {
     const parentTokens = graph.parentProvidedTokens ?? new Set<TokenId>();
 
     // 1. Check for Duplicate Registrations (local token already in parent)
-    for (const nodeId of graph.nodes.keys()) {
+    for (const [nodeId, node] of graph.nodes) {
         if (parentTokens.has(nodeId)) {
+            // Allow if scoped: true (intentional override)
+            if (node.service.isScoped) {
+                continue;
+            }
             throw new Error(
                 `Duplicate registration: '${nodeId}' is already registered in the parent container. ` +
-                `Remove the local registration or use a different token.`
+                `Use 'scoped: true' to override the parent's registration intentionally.`
             );
         }
     }

package/src/types.ts

@@ -2,14 +2,14 @@
  * Represents a generic class constructor.
  * @template T - The type of the instance created by the constructor.
  */
-export type Constructor<T = unknown> = new (...args: unknown[]) => T;
+export type Constructor<T = any> = new (...args: any[]) => 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/src/unplugin/index.ts

@@ -5,46 +5,35 @@ import { GraphValidator } from '../generator/GraphValidator';
 import { Generator } from '../generator/Generator';
 
 /**
- * The Unplugin factory for Neo-Syringe.
+ * Neo-Syringe build plugin for Vite, Rollup, Webpack, and other bundlers.
  *
- * This plugin integrates with Vite, Rollup, Webpack, etc.
- * It intercepts files containing `createContainer` calls, analyzes them,
- * and replaces the runtime configuration code with the generated dependency graph.
+ * Intercepts files containing `defineBuilderConfig` calls, analyzes the
+ * dependency graph, validates it, and replaces the configuration with
+ * generated factory code.
  *
  * @example
+ * ```typescript
  * // vite.config.ts
  * import { neoSyringePlugin } from '@djodjonx/neo-syringe/plugin';
  *
  * export default defineConfig({
- *   plugins: [neoSyringePlugin.vite()],
+ *   plugins: [neoSyringePlugin.vite()]
  * });
+ * ```
  */
-export const neoSyringePlugin = createUnplugin((_options) => {
+export const neoSyringePlugin = createUnplugin(() => {
   return {
     name: 'neo-syringe-plugin',
-    /**
-     * Includes .ts and .tsx files for transformation.
-     * @param id - The file path.
-     */
+
     transformInclude(id) {
       return id.endsWith('.ts') || id.endsWith('.tsx');
     },
-    /**
-     * Transforms the code by replacing container definitions with generated factories.
-     * @param code - The source code.
-     * @param id - The file path.
-     */
+
     transform(code, id) {
       if (!code.includes('defineBuilderConfig')) return;
 
-      // naive check, but saves performance.
-
-      // We need to parse this file to see if it really defines a container.
-      // We need a full Program to resolve types across files.
-      // Using existing tsconfig if possible.
-
       const configFile = ts.findConfigFile(process.cwd(), ts.sys.fileExists, 'tsconfig.json');
-      if (!configFile) return; // Cannot work without tsconfig
+      if (!configFile) return;
 
       const { config } = ts.readConfigFile(configFile, ts.sys.readFile);
       const { options: compilerOptions } = ts.parseJsonConfigFileContent(config, ts.sys, process.cwd());
@@ -53,30 +42,13 @@ export const neoSyringePlugin = createUnplugin((_options) => {
       const analyzer = new Analyzer(program);
       const graph = analyzer.extract();
 
-      if (graph.nodes.size === 0) return; // No container found
+      if (graph.nodes.size === 0) return;
 
-      // Validate
       const validator = new GraphValidator();
       validator.validate(graph);
 
-      // Generate
       const generator = new Generator(graph);
-      const generatedCode = generator.generate();
-
-      // We need to replace the export.
-      // Strategy: Use the generated code AS the content of this file?
-      // If the file *only* exports the container, yes.
-      // But if it exports other things, we might break them.
-
-      // Safer strategy:
-      // Replace the `createContainer()...build()` expression with the object literal from generated code.
-      // But the generated code includes imports. Imports must be at top level.
-
-      // So we must REPLACE the whole file content with the generated code.
-      // This implies the user should put the container in a dedicated file.
-      // We can warn or document this.
-
-      return generatedCode;
+      return generator.generate();
     },
   };
 });

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/AnalyzerDeclarative.test.ts

@@ -80,7 +80,7 @@ describe('Analyzer - Declarative Config (defineBuilderConfig)', () => {
 
     // Since we don't know the ID yet, let's iterate.
     const nodes = Array.from(graph.nodes.values());
-    const loggerNode = nodes.find(n => n.service.implementationSymbol.getName() === 'ConsoleLogger');
+    const loggerNode = nodes.find(n => n.service.implementationSymbol?.getName() === 'ConsoleLogger');
 
     expect(loggerNode).toBeDefined();
     expect(loggerNode?.service.type).toBe('explicit');

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', () => {