@djodjonx/neo-syringe 1.1.5 → 1.2.2

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
+```
+

package/docs/guide/getting-started.md

@@ -0,0 +1,171 @@
+# Getting Started
+
+This guide will help you install Neo-Syringe and create your first container in 5 minutes.
+
+## Installation
+
+::: code-group
+
+```bash [pnpm]
+pnpm add @djodjonx/neo-syringe
+pnpm add -D unplugin
+```
+
+```bash [npm]
+npm install @djodjonx/neo-syringe
+npm install -D unplugin
+```
+
+```bash [yarn]
+yarn add @djodjonx/neo-syringe
+yarn add -D unplugin
+```
+
+:::
+
+::: info Peer Dependencies
+- `typescript` >= 5.0.0
+- `unplugin` (required for build plugin)
+:::
+
+## Configure Your Bundler
+
+Neo-Syringe works with all major bundlers through `unplugin`.
+
+::: code-group
+
+```typescript [Vite]
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { neoSyringePlugin } from '@djodjonx/neo-syringe/plugin';
+
+export default defineConfig({
+  plugins: [neoSyringePlugin.vite()]
+});
+```
+
+```typescript [Rollup]
+// rollup.config.js
+import { neoSyringePlugin } from '@djodjonx/neo-syringe/plugin';
+
+export default {
+  plugins: [neoSyringePlugin.rollup()]
+};
+```
+
+```javascript [Webpack]
+// webpack.config.js
+module.exports = {
+  plugins: [require('@djodjonx/neo-syringe/plugin').webpack()]
+};
+```
+
+```typescript [esbuild]
+// esbuild.config.js
+import { neoSyringePlugin } from '@djodjonx/neo-syringe/plugin';
+
+await esbuild.build({
+  plugins: [neoSyringePlugin.esbuild()]
+});
+```
+
+:::
+
+## Create Your First Container
+
+### Step 1: Define Your Services
+
+Create pure TypeScript classes and interfaces. **No decorators needed!**
+
+```typescript
+// services/logger.ts
+export interface ILogger {
+  log(msg: string): void;
+}
+
+export class ConsoleLogger implements ILogger {
+  log(msg: string) {
+    console.log(`[LOG] ${msg}`);
+  }
+}
+```
+
+```typescript
+// services/user.service.ts
+import type { ILogger } from './logger';
+
+export class UserService {
+  constructor(private logger: ILogger) {}
+
+  createUser(name: string) {
+    this.logger.log(`Creating user: ${name}`);
+    return { id: crypto.randomUUID(), name };
+  }
+}
+```
+
+### Step 2: Configure the Container
+
+::: tip Best Practice
+Put your container configuration in a **dedicated file** (e.g., `container.ts`). The plugin replaces the entire file content with generated code.
+:::
+
+```typescript
+// container.ts
+import { defineBuilderConfig, useInterface } from '@djodjonx/neo-syringe';
+import { ILogger, ConsoleLogger } from './services/logger';
+import { UserService } from './services/user.service';
+
+export const container = defineBuilderConfig({
+  name: 'AppContainer',
+  injections: [
+    // Bind interface to implementation
+    { token: useInterface<ILogger>(), provider: ConsoleLogger },
+    
+    // Autowire class (dependencies resolved automatically)
+    { token: UserService }
+  ]
+});
+```
+
+### Step 3: Use the Container
+
+```typescript
+// main.ts
+import { container } from './container';
+import { UserService } from './services/user.service';
+
+// Resolve and use
+const userService = container.resolve(UserService);
+const user = userService.createUser('John Doe');
+
+console.log(user); // { id: 'xxx-xxx', name: 'John Doe' }
+```
+
+## Project Structure
+
+Recommended project structure:
+
+```
+src/
+├── container.ts          # ✅ Container configuration
+├── services/
+│   ├── logger.ts         # Pure service
+│   ├── user.service.ts   # Pure service
+│   └── index.ts          # Barrel exports
+└── main.ts               # Application entry
+```
+
+## Development Mode
+
+✅ **The plugin works in dev mode** with full HMR support!
+
+The `transform` hook is called on every file change, so your container is regenerated instantly during development.
+
+## What's Next?
+
+- [Basic Usage](/guide/basic-usage) - Learn all injection types
+- [Lifecycle](/guide/lifecycle) - Singleton vs Transient
+- [Scoped Injections](/guide/scoped-injections) - Override parent tokens
+- [IDE Plugin](/guide/ide-plugin) - Real-time error detection
+