@djodjonx/neo-syringe 1.2.0 → 1.2.2

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
@@ -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/types.ts

@@ -2,7 +2,7 @@
  * 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 of a service.

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/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/e2e/container-integration.test.ts

@@ -74,7 +74,7 @@ describe('E2E - Container Integration', () => {
       const container = new NeoContainer();
       container.registerFactory(SimpleService, () => new SimpleService());
 
-      const service = container.resolve(SimpleService);
+      const service = container.resolve<any>(SimpleService);
       expect(service.getValue()).toBe(42);
     });
 
@@ -96,7 +96,7 @@ describe('E2E - Container Integration', () => {
       container.registerFactory(Logger, () => new Logger());
       container.registerFactory(UserService, (c) => new UserService(c.resolve(Logger)));
 
-      const userService = container.resolve(UserService);
+      const userService = container.resolve<any>(UserService);
       expect(userService.greet('World')).toBe('Hello World');
     });
   });
@@ -111,8 +111,8 @@ describe('E2E - Container Integration', () => {
       const container = new NeoContainer();
       container.registerFactory(Counter, () => new Counter(), 'singleton');
 
-      const c1 = container.resolve(Counter);
-      const c2 = container.resolve(Counter);
+      const c1 = container.resolve<any>(Counter);
+      const c2 = container.resolve<any>(Counter);
 
       expect(c1).toBe(c2);
       expect(c1.increment()).toBe(1);
@@ -131,8 +131,8 @@ describe('E2E - Container Integration', () => {
       const container = new NeoContainer();
       container.registerFactory(Transient, () => new Transient(), 'transient');
 
-      const t1 = container.resolve(Transient);
-      const t2 = container.resolve(Transient);
+      const t1 = container.resolve<any>(Transient);
+      const t2 = container.resolve<any>(Transient);
 
       expect(t1).not.toBe(t2);
       expect(t1.id).not.toBe(t2.id);
@@ -163,11 +163,11 @@ describe('E2E - Container Integration', () => {
       container.registerFactory(UserRepo, (c) => new UserRepo(c.resolve(Database)));
       container.registerFactory(UserService, (c) => new UserService(c.resolve(UserRepo), c.resolve(Logger)));
 
-      const userService = container.resolve(UserService);
+      const userService = container.resolve<any>(UserService);
       expect(userService.getDbUrl()).toBe('postgres://localhost');
 
       // Verify singleton behavior
-      const logger1 = container.resolve(Logger);
+      const logger1 = container.resolve<any>(Logger);
       const logger2 = userService.logger;
       expect(logger1).toBe(logger2);
     });
@@ -181,7 +181,7 @@ describe('E2E - Container Integration', () => {
       const container = new NeoContainer(undefined, undefined, 'MyApp');
       container.registerFactory(Registered, () => new Registered());
 
-      expect(() => container.resolve(NotRegistered)).toThrow(/MyApp.*not found/);
+      expect(() => container.resolve<any>(NotRegistered)).toThrow(/MyApp.*not found/);
     });
   });
 
@@ -198,7 +198,7 @@ describe('E2E - Container Integration', () => {
       container.registerFactory(Right, (c) => new Right(c.resolve(Shared)));
       container.registerFactory(Top, (c) => new Top(c.resolve(Left), c.resolve(Right)));
 
-      const top = container.resolve(Top);
+      const top = container.resolve<any>(Top);
 
       // Both Left and Right should share the same Shared instance
       expect(top.left.shared).toBe(top.right.shared);
@@ -217,7 +217,7 @@ describe('E2E - Container Integration', () => {
       const child = new NeoContainer(parent, undefined, 'Child');
       child.registerFactory(ChildService, (c) => new ChildService(c.resolve(SharedService)));
 
-      const service = child.resolve(ChildService);
+      const service = child.resolve<any>(ChildService);
       expect(service.shared.value).toBe('shared');
     });
 
@@ -230,7 +230,7 @@ describe('E2E - Container Integration', () => {
       const child = new NeoContainer(parent);
       child.registerFactory(Service, () => new Service('child'));
 
-      expect(child.resolve(Service).value).toBe('child');
+      expect(child.resolve<any>(Service).value).toBe('child');
     });
   });
 
@@ -248,7 +248,7 @@ describe('E2E - Container Integration', () => {
 
       const container = new NeoContainer(undefined, [legacyContainer], 'App');
 
-      const service = container.resolve(LegacyService);
+      const service = container.resolve<any>(LegacyService);
       expect(service.fromLegacy).toBe(true);
     });
 
@@ -262,7 +262,7 @@ describe('E2E - Container Integration', () => {
       const container = new NeoContainer(undefined, [legacyContainer]);
       container.registerFactory(Service, () => new Service('local'));
 
-      expect(container.resolve(Service).source).toBe('local');
+      expect(container.resolve<any>(Service).source).toBe('local');
     });
   });
 
@@ -291,7 +291,7 @@ describe('E2E - Container Integration', () => {
       container.registerFactory(ILOGGER, () => new ConsoleLogger());
       container.registerFactory(UserService, (c) => new UserService(c.resolve(ILOGGER)));
 
-      const service = container.resolve(UserService);
+      const service = container.resolve<any>(UserService);
       expect(service.logger.log('hi')).toBe('hi');
     });
   });
@@ -305,11 +305,11 @@ describe('E2E - Container Integration', () => {
 
       const API_URL_TOKEN = 'ApiUrl';
       container.registerFactory(API_URL_TOKEN, (c) => {
-        const config = c.resolve(Config);
+        const config = c.resolve<Config>(Config);
         return `https://api.${config.env}.example.com`;
       });
 
-      expect(container.resolve(API_URL_TOKEN)).toBe('https://api.test.example.com');
+      expect(container.resolve<any>(API_URL_TOKEN)).toBe('https://api.test.example.com');
     });
   });
 
@@ -324,7 +324,7 @@ describe('E2E - Container Integration', () => {
 
       const start = Date.now();
       for (let i = 0; i < 100; i++) {
-        container.resolve(HeavyService);
+        container.resolve<any>(HeavyService);
       }
       const duration = Date.now() - start;
 
@@ -348,7 +348,7 @@ describe('E2E - Container Integration', () => {
       }
 
       const start = Date.now();
-      container.resolve(prevClass);
+      container.resolve<any>(prevClass);
       const duration = Date.now() - start;
 
       expect(duration).toBeLessThan(100); // 100ms max for 20 levels

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

@@ -926,7 +926,7 @@ it('should generate PropertyToken resolution', () => {
       );
 
       // Should parse without syntax errors
-      const syntaxErrors = sourceFile.parseDiagnostics || [];
+      const syntaxErrors = (sourceFile as any).parseDiagnostics || [];
       expect(syntaxErrors.length).toBe(0);
     });
 
@@ -948,7 +948,7 @@ it('should generate PropertyToken resolution', () => {
         ts.ScriptTarget.Latest,
         true
       );
-      const syntaxErrors = sourceFile.parseDiagnostics || [];
+      const syntaxErrors = (sourceFile as any).parseDiagnostics || [];
       expect(syntaxErrors.length).toBe(0);
     });
   });

package/tsconfig.json

@@ -10,5 +10,6 @@
     "declaration": true,
     "outDir": "./dist"
   },
-  "include": ["src"]
+  "include": ["src", "tests"],
+  "exclude": ["docs"]
 }

package/typedoc.json

@@ -1,5 +0,0 @@
-{
-  "entryPoints": ["src/index.ts"],
-  "out": "docs",
-  "hideGenerator": true
-}