@djodjonx/neo-syringe 1.1.5 → 1.2.2

package/docs/guide/what-is-neo-syringe.md

@@ -0,0 +1,162 @@
+# What is Neo-Syringe?
+
+Neo-Syringe is a **next-generation dependency injection system** for TypeScript that shifts resolution from **runtime** to **build-time**.
+
+## The Problem with Traditional DI
+
+Traditional DI containers (InversifyJS, tsyringe, Awilix) all work the same way:
+
+```typescript
+// Traditional approach
+@injectable()
+class UserService {
+  constructor(@inject(TYPES.ILogger) private logger: ILogger) {}
+}
+
+// At runtime
+container.resolve(UserService); // ← Resolution happens HERE
+```
+
+This approach has several drawbacks:
+
+| Issue | Impact |
+|-------|--------|
+| **Runtime overhead** | DI container code shipped to production |
+| **Reflection required** | Need `reflect-metadata` and decorators |
+| **Interface erasure** | Must use Symbols or string tokens manually |
+| **Late errors** | Missing bindings only discovered at runtime |
+| **Framework coupling** | Classes polluted with DI decorators |
+
+## The Neo-Syringe Solution
+
+Neo-Syringe works as a **compiler plugin** that analyzes your configuration and generates optimized code:
+
+```typescript
+// Your code (pure TypeScript!)
+interface ILogger {
+  log(msg: string): void;
+}
+
+class UserService {
+  constructor(private logger: ILogger) {}
+}
+
+// Configuration
+export const container = defineBuilderConfig({
+  injections: [
+    { token: useInterface<ILogger>(), provider: ConsoleLogger },
+    { token: UserService }
+  ]
+});
+```
+
+At build time, this becomes:
+
+```typescript
+// Generated code (no DI library!)
+function create_UserService(container) {
+  return new UserService(container.resolve("ILogger"));
+}
+
+class NeoContainer {
+  resolve(token) {
+    if (token === "ILogger") return new ConsoleLogger();
+    if (token === UserService) return create_UserService(this);
+  }
+}
+
+export const container = new NeoContainer();
+```
+
+## Key Advantages
+
+### 🚀 Zero Runtime Overhead
+
+No DI library shipped to production. Just pure factory functions that create instances directly.
+
+### ✨ Native Interface Support
+
+Use `useInterface<ILogger>()` instead of managing Symbols. The compiler generates unique IDs automatically.
+
+### 🛡️ Compile-Time Safety
+
+Errors are detected in your IDE before you even save the file:
+
+- Circular dependencies
+- Missing bindings
+- Duplicate registrations
+- Type mismatches
+
+### 📦 Pure Classes
+
+Your business classes have **zero DI dependencies**:
+
+```typescript
+// ✅ Pure TypeScript class
+class UserService {
+  constructor(private logger: ILogger) {}
+}
+
+// ❌ Traditional approach (polluted)
+@injectable()
+class UserService {
+  constructor(@inject(TYPES.ILogger) private logger: ILogger) {}
+}
+```
+
+### 🔄 Gradual Migration
+
+Bridge existing containers while migrating:
+
+```typescript
+export const container = defineBuilderConfig({
+  useContainer: legacyTsyringeContainer, // ← Delegate to legacy
+  injections: [
+    { token: NewService } // New services in Neo-Syringe
+  ]
+});
+```
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      BUILD TIME                              │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  1. defineBuilderConfig({...})                              │
+│              │                                               │
+│              ▼                                               │
+│  2. TypeScript Plugin analyzes configuration                │
+│              │                                               │
+│              ▼                                               │
+│  3. Generates optimized NeoContainer class                  │
+│              │                                               │
+│              ▼                                               │
+│  4. Replaces defineBuilderConfig with generated code        │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+                           │
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│                       RUNTIME                                │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  container.resolve(UserService)                             │
+│              │                                               │
+│              ▼                                               │
+│  Direct new UserService(new ConsoleLogger())                │
+│                                                              │
+│  ✅ No reflection                                            │
+│  ✅ No container lookup                                      │
+│  ✅ Just function calls                                      │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Next Steps
+
+- [Getting Started](/guide/getting-started) - Install and configure Neo-Syringe
+- [Basic Usage](/guide/basic-usage) - Learn the core concepts
+- [Why Neo-Syringe?](/guide/why-neo-syringe) - Detailed comparison with alternatives
+

package/docs/guide/why-neo-syringe.md

@@ -0,0 +1,219 @@
+# Why Neo-Syringe?
+
+A detailed comparison with other dependency injection solutions.
+
+## Comparison Table
+
+| Feature | Neo-Syringe | tsyringe | InversifyJS | Awilix |
+|---------|:-----------:|:--------:|:-----------:|:------:|
+| **Zero runtime overhead** | ✅ | ❌ | ❌ | ❌ |
+| **No decorators needed** | ✅ | ❌ | ❌ | ✅ |
+| **No reflect-metadata** | ✅ | ❌ | ❌ | ✅ |
+| **Interface as tokens** | ✅ | ❌ | ❌ | ❌ |
+| **Compile-time validation** | ✅ | ❌ | ❌ | ❌ |
+| **IDE error detection** | ✅ | ❌ | ❌ | ❌ |
+| **Tree-shakeable** | ✅ | ❌ | ❌ | ❌ |
+| **Works in Edge/Workers** | ✅ | ⚠️ | ⚠️ | ✅ |
+
+## The Cost of Runtime DI
+
+Traditional DI containers add significant overhead:
+
+### Bundle Size
+
+| Library | Min+Gzip |
+|---------|----------|
+| InversifyJS | ~11 KB |
+| tsyringe | ~4 KB |
+| Awilix | ~8 KB |
+| **Neo-Syringe** | **~0 KB** (generated) |
+
+### Runtime Performance
+
+```typescript
+// Traditional (tsyringe) - Runtime resolution
+container.resolve(UserService);
+// 1. Look up token in registry
+// 2. Check if singleton exists
+// 3. Resolve all dependencies recursively
+// 4. Create instance with reflection
+// 5. Store singleton reference
+
+// Neo-Syringe - Direct instantiation
+container.resolve(UserService);
+// 1. Call generated factory function
+// That's it!
+```
+
+## Code Quality Comparison
+
+### Traditional Approach (tsyringe)
+
+```typescript
+import 'reflect-metadata';
+import { injectable, inject } from 'tsyringe';
+
+// Must define symbols manually
+const TYPES = {
+  ILogger: Symbol.for('ILogger'),
+  IDatabase: Symbol.for('IDatabase'),
+};
+
+// Classes polluted with decorators
+@injectable()
+class UserService {
+  constructor(
+    @inject(TYPES.ILogger) private logger: ILogger,
+    @inject(TYPES.IDatabase) private db: IDatabase
+  ) {}
+}
+
+// Registration
+container.register(TYPES.ILogger, { useClass: ConsoleLogger });
+container.register(TYPES.IDatabase, { useClass: PostgresDatabase });
+container.register(UserService, { useClass: UserService });
+```
+
+### Neo-Syringe Approach
+
+```typescript
+import { defineBuilderConfig, useInterface } from '@djodjonx/neo-syringe';
+
+// Pure class - no DI imports!
+class UserService {
+  constructor(
+    private logger: ILogger,
+    private db: IDatabase
+  ) {}
+}
+
+// Clean configuration
+export const container = defineBuilderConfig({
+  injections: [
+    { token: useInterface<ILogger>(), provider: ConsoleLogger },
+    { token: useInterface<IDatabase>(), provider: PostgresDatabase },
+    { token: UserService }
+  ]
+});
+```
+
+## Error Detection
+
+### Traditional: Runtime Errors
+
+```typescript
+// tsyringe - Error at RUNTIME
+container.resolve(UserService);
+// Error: Attempted to resolve unregistered dependency token: "ILogger"
+// 💥 App crashes in production!
+```
+
+### Neo-Syringe: Compile-Time Errors
+
+```typescript
+// Neo-Syringe - Error in IDE instantly
+export const container = defineBuilderConfig({
+  injections: [
+    { token: UserService } // UserService needs ILogger
+  ]
+});
+// 🔴 [Neo-Syringe] Missing binding: 'UserService' depends on 'ILogger'
+// ✅ Fixed before you even save the file!
+```
+
+## Testing
+
+### Traditional: Complex Mocking (tsyringe example)
+
+```typescript
+// ❌ tsyringe requires manual container reset and re-registration
+import { container } from 'tsyringe';
+
+beforeEach(() => {
+  container.reset();  // tsyringe API, NOT Neo-Syringe!
+  container.register(TYPES.ILogger, { useClass: MockLogger });
+  container.register(TYPES.IDatabase, { useClass: MockDatabase });
+  container.register(UserService, { useClass: UserService });
+});
+```
+
+### Neo-Syringe: Natural Overrides
+
+```typescript
+// ✅ Neo-Syringe - Create a test container that overrides production services
+import { defineBuilderConfig, useInterface } from '@djodjonx/neo-syringe';
+import { productionContainer } from './container';
+
+// Test container inherits from production but overrides specific services
+const testContainer = defineBuilderConfig({
+  useContainer: productionContainer,
+  injections: [
+    { token: useInterface<ILogger>(), provider: MockLogger, scoped: true },
+    { token: useInterface<IDatabase>(), provider: MockDatabase, scoped: true }
+  ]
+});
+
+// No reset needed - each test file can have its own container!
+const userService = testContainer.resolve(UserService);
+```
+
+## Edge Computing / Workers
+
+Traditional DI often fails in edge environments:
+
+```typescript
+// ❌ tsyringe in Cloudflare Workers
+// Error: reflect-metadata requires global Reflect object
+
+// ❌ InversifyJS in Vercel Edge
+// Error: Cannot use decorators in Edge Runtime
+```
+
+Neo-Syringe works everywhere:
+
+```typescript
+// ✅ Neo-Syringe in any environment
+// Generated code is pure JavaScript
+export class NeoContainer {
+  resolve(token) {
+    if (token === "ILogger") return new ConsoleLogger();
+    // ... pure function calls
+  }
+}
+```
+
+## Migration Path
+
+You don't have to migrate everything at once:
+
+```typescript
+// Bridge legacy container
+import { legacyContainer } from './legacy-tsyringe';
+import { declareContainerTokens } from '@djodjonx/neo-syringe';
+
+const legacy = declareContainerTokens<{
+  AuthService: AuthService;
+  UserRepository: UserRepository;
+}>(legacyContainer);
+
+// New services use Neo-Syringe
+export const container = defineBuilderConfig({
+  useContainer: legacy, // Delegate to legacy
+  injections: [
+    { token: NewService },
+    { token: AnotherNewService }
+  ]
+});
+```
+
+## Summary
+
+| Aspect | Traditional DI | Neo-Syringe |
+|--------|---------------|-------------|
+| **When errors occur** | Runtime | Compile-time |
+| **Bundle impact** | 4-11 KB | 0 KB |
+| **Class purity** | Polluted with decorators | 100% pure |
+| **Interface support** | Manual Symbols | Automatic |
+| **Edge compatibility** | Limited | Full |
+| **Performance** | Map lookups + reflection | Direct calls |
+

package/docs/index.md

@@ -0,0 +1,138 @@
+---
+layout: home
+
+hero:
+  name: Neo-Syringe
+  text: Compile-Time DI
+  tagline: Zero-overhead dependency injection that shifts resolution from Runtime to Build-Time. No reflection, no decorators, just pure TypeScript.
+  image:
+    src: /logo.png
+    alt: Neo-Syringe
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /guide/getting-started
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/djodjonx/neo-syringe
+
+features:
+  - icon: ✨
+    title: Interface as Tokens
+    details: Native support for useInterface<ILogger>() without manual Symbols. TypeScript interfaces work seamlessly.
+    
+  - icon: 🚀
+    title: Zero Runtime Overhead
+    details: No reflection, no reflect-metadata. Just pure factory functions generated at build time.
+    
+  - icon: 🛡️
+    title: Compile-Time Safety
+    details: Detect circular dependencies, missing bindings, and type mismatches instantly in your IDE.
+    
+  - icon: 🔄
+    title: Gradual Migration
+    details: Bridge existing containers like tsyringe or InversifyJS with useContainer while migrating.
+    
+  - icon: 📦
+    title: Pure Classes
+    details: Your business classes stay 100% pure - no decorators, no DI imports, no framework coupling.
+    
+  - icon: 🤖
+    title: CI Validation
+    details: Standalone CLI to verify your dependency graph before deployment.
+---
+
+<style>
+:root {
+  --vp-home-hero-name-color: transparent;
+  --vp-home-hero-name-background: linear-gradient(135deg, #0d9488 0%, #f97316 100%);
+}
+</style>
+
+## Why Choose Neo-Syringe?
+
+Traditional DI containers like InversifyJS and tsyringe rely on **runtime resolution**:
+
+- ❌ Ship DI container logic to the browser
+- ❌ Errors happen at runtime
+- ❌ Interfaces are erased, requiring manual Symbols
+- ❌ Need decorators and reflect-metadata
+
+**Neo-Syringe is different.** It works as a **compiler plugin**:
+
+- ✅ Generate optimized factories at build time
+- ✅ Errors detected in your IDE
+- ✅ Automatic interface IDs
+- ✅ Pure TypeScript, no decorators
+
+## Quick Example
+
+```typescript
+// Pure TypeScript - no decorators!
+interface ILogger {
+  log(msg: string): void;
+}
+
+class ConsoleLogger implements ILogger {
+  log(msg: string) { console.log(msg); }
+}
+
+class UserService {
+  constructor(private logger: ILogger) {}
+}
+
+// Configure the container
+import { defineBuilderConfig, useInterface } from '@djodjonx/neo-syringe';
+
+export const container = defineBuilderConfig({
+  name: 'AppContainer',
+  injections: [
+    { token: useInterface<ILogger>(), provider: ConsoleLogger },
+    { token: UserService }
+  ]
+});
+
+// Use it
+const userService = container.resolve(UserService);
+```
+
+## Generated Output
+
+The build plugin transforms your configuration into optimized code:
+
+```typescript
+// Generated at build time
+function create_ILogger() {
+  return new ConsoleLogger();
+}
+
+function create_UserService(container) {
+  return new UserService(container.resolve("ILogger"));
+}
+
+export class NeoContainer {
+  resolve(token) {
+    if (token === "ILogger") return this.getInstance("ILogger", create_ILogger);
+    if (token === UserService) return this.getInstance(UserService, create_UserService);
+    throw new Error(`Service not found: ${token}`);
+  }
+}
+```
+
+**Zero DI library shipped to production!**
+
+<div style="text-align: center; margin-top: 3rem;">
+  <a href="./guide/getting-started" style="
+    display: inline-block;
+    padding: 12px 24px;
+    background: linear-gradient(135deg, #0d9488 0%, #14b8a6 100%);
+    color: white;
+    text-decoration: none;
+    border-radius: 8px;
+    font-weight: 600;
+    transition: transform 0.2s;
+  ">
+    Get Started →
+  </a>
+</div>
+

package/package.json

@@ -1,29 +1,30 @@
 {
   "name": "@djodjonx/neo-syringe",
-  "version": "1.1.5",
+  "version": "1.2.2",
   "description": "Zero-Overhead, Compile-Time Dependency Injection for TypeScript",
   "type": "module",
-  "main": "dist/index.js",
+  "main": "dist/index.cjs",
   "module": "dist/index.mjs",
-  "types": "dist/index.d.ts",
+  "types": "dist/index.d.mts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
+      "types": "./dist/index.d.mts",
       "import": "./dist/index.mjs",
-      "require": "./dist/index.js"
+      "require": "./dist/index.cjs"
     },
     "./plugin": {
-      "types": "./dist/unplugin/index.d.ts",
+      "types": "./dist/unplugin/index.d.mts",
       "import": "./dist/unplugin/index.mjs",
-      "require": "./dist/unplugin/index.js"
+      "require": "./dist/unplugin/index.cjs"
     },
     "./lsp": {
-      "types": "./dist/lsp/index.d.ts",
-      "require": "./dist/lsp/index.js"
+      "types": "./dist/lsp/index.d.mts",
+      "import": "./dist/lsp/index.mjs",
+      "require": "./dist/lsp/index.cjs"
     }
   },
   "bin": {
-    "neo-syringe": "./dist/cli/index.js"
+    "neo-syringe": "./dist/cli/index.mjs"
   },
   "scripts": {
     "build": "tsdown",
@@ -35,7 +36,9 @@
     "validate": "pnpm lint && pnpm typecheck && pnpm test",
     "prebuild": "pnpm validate",
     "prepublishOnly": "pnpm build",
-    "docs": "typedoc",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs",
     "release": "pnpm validate && standard-version",
     "release:dry": "standard-version --dry-run",
     "prepare": "husky"
@@ -65,9 +68,9 @@
     "standard-version": "^9.5.0",
     "tsdown": "0.20.0-beta.3",
     "tsyringe": "^4.10.0",
-    "typedoc": "^0.28.16",
     "typescript": "^5.9.3",
     "unplugin": "^2.3.11",
+    "vitepress": "^1.6.4",
     "vitest": "^4.0.17"
   }
 }

package/src/analyzer/Analyzer.ts

@@ -283,11 +283,12 @@ export class Analyzer {
   }
 
   private parseInjectionObject(obj: ts.ObjectLiteralExpression, graph: DependencyGraph): void {
-      // Extract properties: token, provider, scope, useFactory
+      // Extract properties: token, provider, lifecycle, useFactory, scoped
       let tokenNode: ts.Expression | undefined;
       let providerNode: ts.Expression | undefined;
-      let scope: 'singleton' | 'transient' = 'singleton';
+      let lifecycle: 'singleton' | 'transient' = 'singleton';
       let useFactory = false;
+      let isScoped = false;
 
       for (const prop of obj.properties) {
           if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name)) continue;
@@ -296,13 +297,18 @@ export class Analyzer {
               tokenNode = prop.initializer;
           } else if (prop.name.text === 'provider') {
               providerNode = prop.initializer;
-          } else if (prop.name.text === 'scope' && ts.isStringLiteral(prop.initializer)) {
-              if (prop.initializer.text === 'transient') scope = 'transient';
+          } else if (prop.name.text === 'lifecycle' && ts.isStringLiteral(prop.initializer)) {
+              if (prop.initializer.text === 'transient') lifecycle = 'transient';
           } else if (prop.name.text === 'useFactory') {
               // Check if useFactory: true
               if (prop.initializer.kind === ts.SyntaxKind.TrueKeyword) {
                   useFactory = true;
               }
+          } else if (prop.name.text === 'scoped') {
+              // Check if scoped: true
+              if (prop.initializer.kind === ts.SyntaxKind.TrueKeyword) {
+                  isScoped = true;
+              }
           }
       }
 
@@ -362,7 +368,8 @@ export class Analyzer {
           type = 'factory';
 
           if (tokenId) {
-              if (graph.nodes.has(tokenId)) {
+              // Check for duplicate - allow if scoped: true (intentional override)
+              if (graph.nodes.has(tokenId) && !isScoped) {
                   throw new Error(`Duplicate registration: '${tokenId}' is already registered.`);
               }
 
@@ -371,11 +378,12 @@ export class Analyzer {
                   tokenSymbol: tokenSymbol ? this.resolveSymbol(tokenSymbol) : undefined,
                   registrationNode: obj,
                   type: 'factory',
-                  scope: scope,
+                  lifecycle: lifecycle,
                   isInterfaceToken,
                   isValueToken,
                   isFactory: true,
-                  factorySource
+                  factorySource,
+                  isScoped
               };
               graph.nodes.set(tokenId, { service: definition, dependencies: [] });
           }
@@ -406,7 +414,8 @@ export class Analyzer {
       }
 
       if (tokenId && implementationSymbol) {
-         if (graph.nodes.has(tokenId)) {
+         // Check for duplicate - allow if scoped: true (intentional override)
+         if (graph.nodes.has(tokenId) && !isScoped) {
               throw new Error(`Duplicate registration: '${tokenId}' is already registered.`);
          }
 
@@ -416,8 +425,9 @@ export class Analyzer {
              tokenSymbol: tokenSymbol ? this.resolveSymbol(tokenSymbol) : undefined,
              registrationNode: obj,
              type: type,
-             scope: scope,
-             isInterfaceToken: isInterfaceToken || (ts.isCallExpression(tokenNode) && this.isUseInterfaceCall(tokenNode))
+             lifecycle: lifecycle,
+             isInterfaceToken: isInterfaceToken || (ts.isCallExpression(tokenNode) && this.isUseInterfaceCall(tokenNode)),
+             isScoped
          };
          graph.nodes.set(tokenId, { service: definition, dependencies: [] });
       }