@djodjonx/neo-syringe 1.1.5 → 1.2.2

package/docs/guide/legacy-migration.md

@@ -0,0 +1,333 @@
+# Legacy Migration
+
+Bridge existing DI containers (tsyringe, InversifyJS) while migrating to Neo-Syringe.
+
+## Overview
+
+You don't have to migrate everything at once. Neo-Syringe can delegate resolution to any container that has a `resolve()` method.
+
+```typescript
+// Bridge your existing container
+export const container = defineBuilderConfig({
+  useContainer: legacyContainer,  // Delegate to legacy
+  injections: [
+    { token: NewService }  // New services in Neo-Syringe
+  ]
+});
+```
+
+## With tsyringe
+
+### Step 1: Keep Your Existing Setup
+
+```typescript
+// legacy-container.ts (existing tsyringe code)
+import 'reflect-metadata';
+import { container, injectable } from 'tsyringe';
+
+@injectable()
+export class AuthService {
+  validateToken(token: string) { return true; }
+}
+
+@injectable()
+export class LegacyUserRepository {
+  findById(id: string) { return { id, name: 'John' }; }
+}
+
+// Register in tsyringe
+container.registerSingleton(AuthService);
+container.registerSingleton(LegacyUserRepository);
+
+export { container as legacyContainer };
+```
+
+### Step 2: Declare Legacy Tokens
+
+Use `declareContainerTokens` for type-safety:
+
+```typescript
+// container.ts
+import { defineBuilderConfig, declareContainerTokens, useInterface } from '@djodjonx/neo-syringe';
+import { legacyContainer, AuthService, LegacyUserRepository } from './legacy-container';
+
+// Declare what the legacy container provides
+const legacy = declareContainerTokens<{
+  AuthService: AuthService;
+  LegacyUserRepository: LegacyUserRepository;
+}>(legacyContainer);
+```
+
+### Step 3: Bridge and Extend
+
+```typescript
+// New services using Neo-Syringe
+interface ILogger {
+  log(msg: string): void;
+}
+
+class ConsoleLogger implements ILogger {
+  log(msg: string) { console.log(msg); }
+}
+
+class UserService {
+  constructor(
+    private auth: AuthService,           // From legacy!
+    private repo: LegacyUserRepository,  // From legacy!
+    private logger: ILogger              // From neo-syringe
+  ) {}
+}
+
+export const appContainer = defineBuilderConfig({
+  name: 'AppContainer',
+  useContainer: legacy,  // 👈 Bridge to legacy
+  injections: [
+    { token: useInterface<ILogger>(), provider: ConsoleLogger },
+    { token: UserService }
+  ]
+});
+```
+
+### Step 4: Use It
+
+```typescript
+// main.ts
+import { appContainer } from './container';
+
+const userService = appContainer.resolve(UserService);
+// ✅ AuthService and LegacyUserRepository come from tsyringe
+// ✅ ILogger comes from neo-syringe
+```
+
+## With InversifyJS
+
+```typescript
+// legacy-inversify.ts
+import 'reflect-metadata';
+import { Container, injectable } from 'inversify';
+
+@injectable()
+class DatabaseConnection {
+  query(sql: string) { return []; }
+}
+
+const inversifyContainer = new Container();
+inversifyContainer.bind(DatabaseConnection).toSelf().inSingletonScope();
+
+export { inversifyContainer, DatabaseConnection };
+```
+
+```typescript
+// container.ts
+import { defineBuilderConfig, declareContainerTokens } from '@djodjonx/neo-syringe';
+import { inversifyContainer, DatabaseConnection } from './legacy-inversify';
+
+const legacy = declareContainerTokens<{
+  DatabaseConnection: DatabaseConnection;
+}>(inversifyContainer);
+
+class ReportService {
+  constructor(private db: DatabaseConnection) {}
+}
+
+export const container = defineBuilderConfig({
+  useContainer: legacy,
+  injections: [
+    { token: ReportService }
+  ]
+});
+```
+
+## With Awilix
+
+```typescript
+// legacy-awilix.ts
+import { createContainer, asClass } from 'awilix';
+
+class EmailService {
+  send(to: string, subject: string) { /* ... */ }
+}
+
+const awilixContainer = createContainer();
+awilixContainer.register({
+  emailService: asClass(EmailService).singleton()
+});
+
+// Awilix uses different API, create wrapper
+export const legacyContainer = {
+  resolve(token: any) {
+    return awilixContainer.resolve(token.name ?? token);
+  }
+};
+```
+
+```typescript
+// container.ts
+import { defineBuilderConfig, declareContainerTokens } from '@djodjonx/neo-syringe';
+import { legacyContainer, EmailService } from './legacy-awilix';
+
+const legacy = declareContainerTokens<{
+  EmailService: EmailService;
+}>(legacyContainer);
+
+export const container = defineBuilderConfig({
+  useContainer: legacy,
+  injections: [
+    { token: NotificationService }  // Uses EmailService from Awilix
+  ]
+});
+```
+
+## How It Works
+
+### At Compile-Time
+
+1. `declareContainerTokens<T>()` is analyzed
+2. Type `T` properties are extracted (e.g., `{ AuthService, UserRepo }`)
+3. These tokens are added to `parentProvidedTokens`
+4. GraphValidator accepts them as valid dependencies
+5. Generator outputs: `new NeoContainer(undefined, [legacyContainer])`
+
+### At Runtime
+
+```typescript
+// Generated code (simplified)
+class NeoContainer {
+  constructor(
+    private parent?: any,
+    private legacy?: any[]  // ← Your tsyringe/inversify container
+  ) {}
+
+  resolve(token: any): any {
+    // 1. Try local resolution
+    const local = this.resolveLocal(token);
+    if (local !== undefined) return local;
+
+    // 2. Delegate to parent (Neo-Syringe container)
+    if (this.parent) {
+      try { return this.parent.resolve(token); }
+      catch { /* continue */ }
+    }
+
+    // 3. Delegate to legacy containers
+    if (this.legacy) {
+      for (const container of this.legacy) {
+        try { return container.resolve(token); }  // ← Calls tsyringe!
+        catch { /* try next */ }
+      }
+    }
+
+    throw new Error(`Service not found: ${token}`);
+  }
+}
+```
+
+## Validation
+
+Neo-Syringe validates legacy bindings at compile-time:
+
+| Check | Description |
+|-------|-------------|
+| ✅ Missing binding | Error if dependency not in local OR legacy container |
+| ✅ Duplicate detection | Error if token already registered in legacy |
+| ✅ Type safety | `declareContainerTokens<T>()` provides TypeScript types |
+
+## Migration Strategy
+
+### Phase 1: Bridge Everything
+
+```typescript
+const legacy = declareContainerTokens<{
+  ServiceA: ServiceA;
+  ServiceB: ServiceB;
+  ServiceC: ServiceC;
+  // ... all services
+}>(tsyringeContainer);
+
+export const container = defineBuilderConfig({
+  useContainer: legacy,
+  injections: []  // Nothing new yet
+});
+```
+
+### Phase 2: New Services in Neo-Syringe
+
+```typescript
+export const container = defineBuilderConfig({
+  useContainer: legacy,
+  injections: [
+    { token: NewServiceD },
+    { token: NewServiceE }
+  ]
+});
+```
+
+### Phase 3: Migrate One at a Time
+
+```typescript
+// Remove ServiceA from legacy declaration
+const legacy = declareContainerTokens<{
+  ServiceB: ServiceB;
+  ServiceC: ServiceC;
+}>(tsyringeContainer);
+
+// Add to Neo-Syringe
+export const container = defineBuilderConfig({
+  useContainer: legacy,
+  injections: [
+    { token: ServiceA },  // Migrated!
+    { token: NewServiceD },
+    { token: NewServiceE }
+  ]
+});
+```
+
+### Phase 4: Complete Migration
+
+```typescript
+// No more legacy!
+export const container = defineBuilderConfig({
+  injections: [
+    { token: ServiceA },
+    { token: ServiceB },
+    { token: ServiceC },
+    { token: NewServiceD },
+    { token: NewServiceE }
+  ]
+});
+```
+
+## Tips
+
+### Keep Legacy Container Isolated
+
+Put legacy code in a separate file that you can eventually delete:
+
+```
+src/
+├── legacy/
+│   └── container.ts      # Will be deleted later
+├── container.ts          # Neo-Syringe
+└── services/
+    ├── legacy/           # To be migrated
+    └── new/              # Pure TypeScript
+```
+
+### Test Both Paths
+
+Ensure services work whether resolved from legacy or Neo-Syringe:
+
+```typescript
+describe('UserService', () => {
+  it('works from legacy container', () => {
+    const service = legacyContainer.resolve(UserService);
+    expect(service).toBeDefined();
+  });
+  
+  it('works from neo-syringe container', () => {
+    const service = container.resolve(UserService);
+    expect(service).toBeDefined();
+  });
+});
+```
+

package/docs/guide/lifecycle.md

@@ -0,0 +1,223 @@
+# Lifecycle
+
+Control how instances are created and managed.
+
+## Overview
+
+Neo-Syringe supports two lifecycle modes:
+
+| Lifecycle | Behavior | Default |
+|-----------|----------|---------|
+| `singleton` | One instance per container | ✅ Yes |
+| `transient` | New instance every `resolve()` | No |
+
+## Singleton (Default)
+
+By default, all services are **singletons**. The container creates one instance and reuses it.
+
+```typescript
+export const container = defineBuilderConfig({
+  injections: [
+    { token: UserService }  // Singleton by default
+  ]
+});
+
+const a = container.resolve(UserService);
+const b = container.resolve(UserService);
+
+console.log(a === b); // true - same instance!
+```
+
+### When to Use Singleton
+
+- ✅ Stateless services (most services)
+- ✅ Database connections
+- ✅ Configuration objects
+- ✅ Loggers
+- ✅ HTTP clients
+
+## Transient
+
+Use `lifecycle: 'transient'` for a new instance on every resolution.
+
+```typescript
+export const container = defineBuilderConfig({
+  injections: [
+    { token: RequestContext, lifecycle: 'transient' }
+  ]
+});
+
+const a = container.resolve(RequestContext);
+const b = container.resolve(RequestContext);
+
+console.log(a === b); // false - different instances!
+```
+
+### When to Use Transient
+
+- ✅ Request-scoped objects
+- ✅ Stateful objects that should be isolated
+- ✅ Objects with unique IDs
+- ✅ Builder/Factory patterns
+
+## Examples
+
+### Request Context
+
+```typescript
+class RequestContext {
+  readonly id = crypto.randomUUID();
+  readonly timestamp = new Date();
+}
+
+export const container = defineBuilderConfig({
+  injections: [
+    { token: RequestContext, lifecycle: 'transient' }
+  ]
+});
+
+// Each request gets its own context
+app.use((req, res, next) => {
+  req.context = container.resolve(RequestContext);
+  next();
+});
+```
+
+### Factory with Transient
+
+```typescript
+{
+  token: useInterface<IRequest>(),
+  provider: () => ({
+    id: crypto.randomUUID(),
+    timestamp: Date.now()
+  }),
+  lifecycle: 'transient'
+}
+```
+
+### Mixed Lifecycles
+
+```typescript
+class Logger {
+  // Singleton - shared across all services
+}
+
+class UserService {
+  constructor(private logger: Logger) {}
+  // Singleton - one instance
+}
+
+class RequestHandler {
+  constructor(private userService: UserService) {}
+  // Transient - new instance per request
+}
+
+export const container = defineBuilderConfig({
+  injections: [
+    { token: Logger },                                    // singleton
+    { token: UserService },                               // singleton
+    { token: RequestHandler, lifecycle: 'transient' }     // transient
+  ]
+});
+
+// RequestHandler is new each time, but shares the same UserService
+const handler1 = container.resolve(RequestHandler);
+const handler2 = container.resolve(RequestHandler);
+
+console.log(handler1 === handler2); // false
+console.log(handler1.userService === handler2.userService); // true
+```
+
+## Generated Code
+
+Understanding how lifecycle affects the generated code:
+
+### Singleton
+
+```typescript
+// Generated for singleton
+private resolveLocal(token: any): any {
+  if (token === UserService) {
+    if (!this.instances.has(UserService)) {
+      this.instances.set(UserService, create_UserService(this));
+    }
+    return this.instances.get(UserService);
+  }
+}
+```
+
+### Transient
+
+```typescript
+// Generated for transient
+private resolveLocal(token: any): any {
+  if (token === RequestContext) {
+    return create_RequestContext(this);  // No caching!
+  }
+}
+```
+
+## Scoped Lifecycle with Parent Containers
+
+When using `scoped: true`, you can define a **different lifecycle** than the parent:
+
+```typescript
+// Parent: ILogger is singleton
+const parent = defineBuilderConfig({
+  injections: [
+    { token: useInterface<ILogger>(), provider: ConsoleLogger, lifecycle: 'singleton' }
+  ]
+});
+
+// Child: Override with transient lifecycle
+const child = defineBuilderConfig({
+  useContainer: parent,
+  injections: [
+    { 
+      token: useInterface<ILogger>(), 
+      provider: FileLogger,
+      lifecycle: 'transient',  // Different from parent!
+      scoped: true
+    }
+  ]
+});
+
+// In parent: same logger instance
+const a = parent.resolve(useInterface<ILogger>());
+const b = parent.resolve(useInterface<ILogger>());
+console.log(a === b); // true
+
+// In child: new instance each time
+const c = child.resolve(useInterface<ILogger>());
+const d = child.resolve(useInterface<ILogger>());
+console.log(c === d); // false
+```
+
+## Best Practices
+
+### 1. Default to Singleton
+
+Most services should be singletons. Only use transient when you have a specific reason.
+
+### 2. Transient for Stateful Objects
+
+If an object holds request-specific state, make it transient:
+
+```typescript
+class ShoppingCart {
+  items: CartItem[] = [];
+  
+  addItem(item: CartItem) {
+    this.items.push(item);
+  }
+}
+
+// Each user gets their own cart
+{ token: ShoppingCart, lifecycle: 'transient' }
+```
+
+### 3. Consider Memory
+
+Transient objects are not cached, which can increase memory churn. Profile your application if you're creating many transient instances.
+