@djodjonx/neo-syringe 1.2.0 → 1.2.2

package/docs/guide/basic-usage.md

@@ -0,0 +1,267 @@
+# Basic Usage
+
+Learn the fundamental concepts and injection patterns in Neo-Syringe.
+
+## Container Configuration
+
+All configuration is done through `defineBuilderConfig`:
+
+```typescript
+import { defineBuilderConfig } from '@djodjonx/neo-syringe';
+
+export const container = defineBuilderConfig({
+  name: 'MyContainer',      // Optional: container name for debugging
+  injections: [             // Required: list of injections
+    // ... your injections
+  ],
+  extends: [],              // Optional: inherit from partials
+  useContainer: undefined   // Optional: parent container
+});
+```
+
+## Injection Types
+
+### Class Token (Autowire)
+
+The simplest form - register a class and let Neo-Syringe resolve its dependencies:
+
+```typescript
+class UserRepository {
+  findAll() { return []; }
+}
+
+class UserService {
+  constructor(private repo: UserRepository) {}
+}
+
+export const container = defineBuilderConfig({
+  injections: [
+    { token: UserRepository },
+    { token: UserService }  // Dependencies auto-resolved
+  ]
+});
+```
+
+### Interface Token
+
+Use `useInterface<T>()` to bind interfaces to implementations:
+
+```typescript
+import { useInterface } from '@djodjonx/neo-syringe';
+
+interface ILogger {
+  log(msg: string): void;
+}
+
+class ConsoleLogger implements ILogger {
+  log(msg: string) { console.log(msg); }
+}
+
+class FileLogger implements ILogger {
+  log(msg: string) { /* write to file */ }
+}
+
+export const container = defineBuilderConfig({
+  injections: [
+    { token: useInterface<ILogger>(), provider: ConsoleLogger }
+  ]
+});
+
+// Resolve by interface
+const logger = container.resolve(useInterface<ILogger>());
+```
+
+::: tip Automatic ID Generation
+`useInterface<ILogger>()` generates a unique string ID at compile-time. You don't need to manage Symbols manually!
+:::
+
+### Explicit Provider
+
+Override the default implementation:
+
+```typescript
+class UserService {
+  // ...
+}
+
+class MockUserService extends UserService {
+  // Test implementation
+}
+
+export const container = defineBuilderConfig({
+  injections: [
+    { token: UserService, provider: MockUserService }
+  ]
+});
+```
+
+### Factory Provider
+
+Use factory functions for dynamic instantiation:
+
+```typescript
+// Arrow functions are auto-detected as factories
+{ 
+  token: useInterface<IConfig>(), 
+  provider: (container) => ({
+    apiUrl: process.env.API_URL ?? 'http://localhost',
+    timeout: 5000
+  })
+}
+
+// Factory with dependencies
+{ 
+  token: useInterface<IService>(), 
+  provider: (container) => {
+    const logger = container.resolve(useInterface<ILogger>());
+    const config = container.resolve(useInterface<IConfig>());
+    return new MyService(logger, config);
+  }
+}
+
+// Explicit factory flag (for non-arrow functions)
+{ 
+  token: useInterface<IDatabase>(), 
+  provider: createDatabaseConnection,
+  useFactory: true
+}
+```
+
+### Property Token
+
+Inject primitive values (string, number, boolean) while keeping classes pure:
+
+```typescript
+import { useProperty } from '@djodjonx/neo-syringe';
+
+// Pure class - no DI imports!
+class ApiService {
+  constructor(
+    private apiUrl: string,
+    private timeout: number,
+    private debug: boolean
+  ) {}
+}
+
+// Define property tokens
+const apiUrl = useProperty<string>(ApiService, 'apiUrl');
+const timeout = useProperty<number>(ApiService, 'timeout');
+const debug = useProperty<boolean>(ApiService, 'debug');
+
+export const container = defineBuilderConfig({
+  injections: [
+    { token: apiUrl, provider: () => process.env.API_URL ?? 'http://localhost' },
+    { token: timeout, provider: () => 5000 },
+    { token: debug, provider: () => process.env.NODE_ENV === 'development' },
+    { token: ApiService }  // Primitives auto-wired!
+  ]
+});
+```
+
+::: info Type Safety
+`useProperty(ApiService, 'apiUrl')` creates a unique token scoped to that specific class parameter. This means `useProperty(ServiceA, 'url')` ≠ `useProperty(ServiceB, 'url')`.
+:::
+
+## Resolving Services
+
+```typescript
+import { container } from './container';
+import { UserService } from './services/user.service';
+import { useInterface } from '@djodjonx/neo-syringe';
+import type { ILogger } from './services/logger';
+
+// Resolve by class
+const userService = container.resolve(UserService);
+
+// Resolve by interface
+const logger = container.resolve(useInterface<ILogger>());
+```
+
+## Partials (Modular Configuration)
+
+Split configuration into reusable modules:
+
+```typescript
+// logging.partial.ts
+import { definePartialConfig, useInterface } from '@djodjonx/neo-syringe';
+
+export const loggingConfig = definePartialConfig({
+  injections: [
+    { token: useInterface<ILogger>(), provider: ConsoleLogger }
+  ]
+});
+
+// database.partial.ts
+export const databaseConfig = definePartialConfig({
+  injections: [
+    { token: useInterface<IDatabase>(), provider: PostgresDatabase }
+  ]
+});
+
+// container.ts
+export const container = defineBuilderConfig({
+  extends: [loggingConfig, databaseConfig], // Inherit injections
+  injections: [
+    { token: UserService },
+    { token: OrderService }
+  ]
+});
+```
+
+## Complete Example
+
+```typescript
+// interfaces.ts
+export interface ILogger {
+  log(msg: string): void;
+}
+
+export interface IUserRepository {
+  findById(id: string): User | null;
+}
+
+// implementations.ts
+export class ConsoleLogger implements ILogger {
+  log(msg: string) { console.log(`[LOG] ${msg}`); }
+}
+
+export class InMemoryUserRepository implements IUserRepository {
+  private users = new Map<string, User>();
+  
+  findById(id: string) {
+    return this.users.get(id) ?? null;
+  }
+}
+
+// services.ts
+export class UserService {
+  constructor(
+    private logger: ILogger,
+    private repo: IUserRepository
+  ) {}
+
+  getUser(id: string) {
+    this.logger.log(`Fetching user ${id}`);
+    return this.repo.findById(id);
+  }
+}
+
+// container.ts
+import { defineBuilderConfig, useInterface } from '@djodjonx/neo-syringe';
+
+export const container = defineBuilderConfig({
+  name: 'AppContainer',
+  injections: [
+    { token: useInterface<ILogger>(), provider: ConsoleLogger },
+    { token: useInterface<IUserRepository>(), provider: InMemoryUserRepository },
+    { token: UserService }
+  ]
+});
+
+// main.ts
+import { container } from './container';
+
+const userService = container.resolve(UserService);
+const user = userService.getUser('123');
+```
+

package/docs/guide/cli.md

@@ -0,0 +1,174 @@
+# CLI Validator
+
+Validate your dependency graph in CI/CD pipelines.
+
+## Installation
+
+The CLI is included with the main package:
+
+```bash
+npx neo-syringe
+# or
+pnpm exec neo-syringe
+```
+
+## Usage
+
+Run in your project root (where `tsconfig.json` is located):
+
+```bash
+neo-syringe
+```
+
+### Options
+
+```bash
+neo-syringe [options]
+
+Options:
+  -p, --project <path>   Path to tsconfig.json (default: "./tsconfig.json")
+  -h, --help             Display help
+  -v, --version          Display version
+```
+
+## Output
+
+### Success
+
+```
+🔍 Analyzing project: /path/to/tsconfig.json
+   Found 45 services.
+🛡️  Validating graph...
+✅ Validation passed! No circular dependencies or missing bindings found.
+```
+
+### Circular Dependency Detected
+
+```
+🔍 Analyzing project: /path/to/tsconfig.json
+   Found 12 services.
+🛡️  Validating graph...
+❌ Validation failed!
+
+Error: Circular dependency detected: A -> B -> C -> A
+```
+
+### Missing Binding
+
+```
+🔍 Analyzing project: /path/to/tsconfig.json
+   Found 8 services.
+🛡️  Validating graph...
+❌ Validation failed!
+
+Error: Missing binding: 'UserService' depends on 'ILogger', but no provider registered.
+```
+
+### Duplicate Registration
+
+```
+🔍 Analyzing project: /path/to/tsconfig.json
+   Found 15 services.
+🛡️  Validating graph...
+❌ Validation failed!
+
+Error: Duplicate registration: 'ILogger' is already registered in the parent container.
+Use 'scoped: true' to override the parent's registration intentionally.
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Validation passed |
+| 1 | Validation failed |
+| 2 | Configuration error |
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - uses: pnpm/action-setup@v4
+      
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+      
+      - run: pnpm install --frozen-lockfile
+      
+      - name: Validate DI Graph
+        run: pnpm exec neo-syringe
+```
+
+### GitLab CI
+
+```yaml
+# .gitlab-ci.yml
+validate:
+  stage: test
+  script:
+    - pnpm install
+    - pnpm exec neo-syringe
+```
+
+### npm scripts
+
+Add to `package.json`:
+
+```json
+{
+  "scripts": {
+    "validate": "neo-syringe",
+    "prebuild": "neo-syringe",
+    "ci": "pnpm lint && pnpm validate && pnpm test"
+  }
+}
+```
+
+## Best Practices
+
+### Run Before Build
+
+Validate before building to catch errors early:
+
+```json
+{
+  "scripts": {
+    "prebuild": "neo-syringe",
+    "build": "vite build"
+  }
+}
+```
+
+### Run in PR Checks
+
+Add validation to your PR workflow:
+
+```yaml
+- name: Validate Dependencies
+  run: pnpm exec neo-syringe
+  # Fails the PR if validation fails
+```
+
+### Use with Husky
+
+Validate on pre-push:
+
+```bash
+# .husky/pre-push
+pnpm exec neo-syringe
+```
+

package/docs/guide/generated-code.md

@@ -0,0 +1,284 @@
+# Generated Code
+
+Understand what the compiler produces.
+
+## Overview
+
+Neo-Syringe transforms your configuration into optimized TypeScript at build time. This page shows what your code looks like before and after compilation.
+
+## Before (Your Configuration)
+
+```typescript
+// container.ts
+import { defineBuilderConfig, useInterface, useProperty } from '@djodjonx/neo-syringe';
+
+interface ILogger {
+  log(msg: string): void;
+}
+
+class ConsoleLogger implements ILogger {
+  log(msg: string) { console.log(msg); }
+}
+
+class ApiService {
+  constructor(
+    private logger: ILogger,
+    private apiUrl: string
+  ) {}
+}
+
+const apiUrl = useProperty<string>(ApiService, 'apiUrl');
+
+export const container = defineBuilderConfig({
+  name: 'AppContainer',
+  injections: [
+    { token: useInterface<ILogger>(), provider: ConsoleLogger },
+    { token: apiUrl, provider: () => process.env.API_URL ?? 'http://localhost' },
+    { token: ApiService }
+  ]
+});
+```
+
+## After (Generated Code)
+
+The build plugin replaces the entire file:
+
+```typescript
+// container.ts (after build)
+import * as Import_0 from './container';
+
+// -- Factories --
+
+function create_ILogger(container: NeoContainer) {
+  return new Import_0.ConsoleLogger();
+}
+
+function create_ApiService_apiUrl(container: NeoContainer) {
+  const userFactory = () => process.env.API_URL ?? 'http://localhost';
+  return userFactory(container);
+}
+
+function create_ApiService(container: NeoContainer) {
+  return new Import_0.ApiService(
+    container.resolve("ILogger"),
+    container.resolve("PropertyToken:ApiService.apiUrl")
+  );
+}
+
+// -- Container --
+
+export class NeoContainer {
+  private instances = new Map<any, any>();
+
+  constructor(
+    private parent?: any,
+    private legacy?: any[],
+    private name: string = 'AppContainer'
+  ) {}
+
+  public resolve(token: any): any {
+    // 1. Try local resolution
+    const result = this.resolveLocal(token);
+    if (result !== undefined) return result;
+
+    // 2. Delegate to parent
+    if (this.parent) {
+      try {
+        return this.parent.resolve(token);
+      } catch (e) {
+        // Continue to legacy
+      }
+    }
+
+    // 3. Delegate to legacy containers
+    if (this.legacy) {
+      for (const legacyContainer of this.legacy) {
+        try {
+          if (legacyContainer.resolve) {
+            return legacyContainer.resolve(token);
+          }
+        } catch (e) {
+          // Try next
+        }
+      }
+    }
+
+    throw new Error(`[${this.name}] Service not found: ${token}`);
+  }
+
+  private resolveLocal(token: any): any {
+    // Interface token (string-based)
+    if (token === "ILogger") {
+      if (!this.instances.has("ILogger")) {
+        this.instances.set("ILogger", create_ILogger(this));
+      }
+      return this.instances.get("ILogger");
+    }
+
+    // Property token (string-based)
+    if (token === "PropertyToken:ApiService.apiUrl") {
+      if (!this.instances.has("PropertyToken:ApiService.apiUrl")) {
+        this.instances.set("PropertyToken:ApiService.apiUrl", create_ApiService_apiUrl(this));
+      }
+      return this.instances.get("PropertyToken:ApiService.apiUrl");
+    }
+
+    // Class token (reference-based)
+    if (token === Import_0.ApiService) {
+      if (!this.instances.has(Import_0.ApiService)) {
+        this.instances.set(Import_0.ApiService, create_ApiService(this));
+      }
+      return this.instances.get(Import_0.ApiService);
+    }
+
+    return undefined;
+  }
+
+  public createChildContainer(): NeoContainer {
+    return new NeoContainer(this, this.legacy, `Child of ${this.name}`);
+  }
+
+  // For debugging
+  public get _graph() {
+    return ["ILogger", "PropertyToken:ApiService.apiUrl", "ApiService"];
+  }
+}
+
+export const container = new NeoContainer();
+```
+
+## Key Observations
+
+### Token Resolution
+
+| Token Type | Resolution Method | Example |
+|------------|-------------------|---------|
+| Interface | String comparison | `token === "ILogger"` |
+| Class | Reference comparison | `token === Import_0.ApiService` |
+| Property | String comparison | `token === "PropertyToken:ApiService.apiUrl"` |
+
+### Singleton Pattern
+
+Singletons use the `instances` Map:
+
+```typescript
+if (!this.instances.has("ILogger")) {
+  this.instances.set("ILogger", create_ILogger(this));
+}
+return this.instances.get("ILogger");
+```
+
+### Transient Pattern
+
+Transients return directly without caching:
+
+```typescript
+if (token === "RequestContext") {
+  return create_RequestContext(this);  // No caching!
+}
+```
+
+### Dependency Injection
+
+Dependencies are resolved recursively:
+
+```typescript
+function create_ApiService(container: NeoContainer) {
+  return new Import_0.ApiService(
+    container.resolve("ILogger"),          // Resolves ILogger first
+    container.resolve("PropertyToken:...")  // Resolves property
+  );
+}
+```
+
+## With Parent Container
+
+When using `useContainer`:
+
+```typescript
+// Configuration
+const child = defineBuilderConfig({
+  useContainer: parent,
+  injections: [{ token: UserService }]
+});
+```
+
+```typescript
+// Generated
+import { parent } from './parent-container';
+
+export class NeoContainer {
+  constructor(
+    private parent: typeof parent = parent,  // 👈 Parent reference
+    // ...
+  ) {}
+
+  resolve(token: any): any {
+    const local = this.resolveLocal(token);
+    if (local !== undefined) return local;
+
+    // Delegate to parent
+    if (this.parent) {
+      return this.parent.resolve(token);
+    }
+    
+    throw new Error('...');
+  }
+}
+
+export const child = new NeoContainer(parent);
+```
+
+## With Factory Provider
+
+```typescript
+// Configuration
+{
+  token: useInterface<IDatabase>(),
+  provider: (container) => {
+    const config = container.resolve(useInterface<IConfig>());
+    return new PostgresDatabase(config.connectionString);
+  }
+}
+```
+
+```typescript
+// Generated
+function create_IDatabase(container: NeoContainer) {
+  const userFactory = (container) => {
+    const config = container.resolve("IConfig");
+    return new PostgresDatabase(config.connectionString);
+  };
+  return userFactory(container);
+}
+```
+
+## Bundle Size Impact
+
+| Aspect | Traditional DI | Neo-Syringe |
+|--------|---------------|-------------|
+| Container library | 4-11 KB | 0 KB |
+| reflect-metadata | ~3 KB | 0 KB |
+| Generated code | N/A | ~50-200 lines |
+| **Total** | **7-14 KB** | **< 1 KB** |
+
+The generated code is:
+- ✅ Tree-shakeable (unused services removed)
+- ✅ Minifiable (standard JavaScript)
+- ✅ No external dependencies
+
+## Debugging
+
+The generated container includes a `_graph` getter for inspection:
+
+```typescript
+console.log(container._graph);
+// ["ILogger", "PropertyToken:ApiService.apiUrl", "ApiService"]
+```
+
+Each container also has a `name` for error messages:
+
+```typescript
+// Error: [AppContainer] Service not found: UnknownToken
+```
+