@djodjonx/neo-syringe 1.2.0 → 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,6 +1,6 @@
 {
   "name": "@djodjonx/neo-syringe",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Zero-Overhead, Compile-Time Dependency Injection for TypeScript",
   "type": "module",
   "main": "dist/index.cjs",
@@ -36,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"
@@ -66,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/types.ts

@@ -1,93 +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;
+
+  /** Lifecycle of the service instance. */
   lifecycle: 'singleton' | 'transient';
 
-  /**
-   * True if the token is an Interface (requires string literal key).
-   * False if the token is a Class (requires reference key).
-   */
+  /** 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.
-   * Allows overriding a token from a parent container without duplicate error.
-   */
+  /** 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>;
+}