@djodjonx/neo-syringe 1.1.5 → 1.2.2

package/docs/api/functions.md

@@ -0,0 +1,291 @@
+# Functions
+
+API functions exported by Neo-Syringe.
+
+## defineBuilderConfig
+
+```typescript
+function defineBuilderConfig(config: BuilderConfig): Container
+```
+
+Define a container configuration. At runtime without the build plugin, this throws an error. At build time, it's replaced with the generated container.
+
+### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `config` | `BuilderConfig` | Container configuration |
+
+### Returns
+
+`Container` - The generated container (after build)
+
+### Example
+
+```typescript
+import { defineBuilderConfig, useInterface } from '@djodjonx/neo-syringe';
+
+export const container = defineBuilderConfig({
+  name: 'AppContainer',
+  injections: [
+    { token: useInterface<ILogger>(), provider: ConsoleLogger },
+    { token: UserService }
+  ]
+});
+```
+
+---
+
+## definePartialConfig
+
+```typescript
+function definePartialConfig(config: PartialConfig): PartialConfig
+```
+
+Define a reusable partial configuration that can be extended.
+
+### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `config` | `PartialConfig` | Partial configuration |
+
+### Returns
+
+`PartialConfig` - The partial configuration
+
+### Example
+
+```typescript
+import { definePartialConfig, useInterface } from '@djodjonx/neo-syringe';
+
+export const loggingPartial = definePartialConfig({
+  injections: [
+    { token: useInterface<ILogger>(), provider: ConsoleLogger }
+  ]
+});
+
+// Use in main config
+export const container = defineBuilderConfig({
+  extends: [loggingPartial],
+  injections: [
+    { token: UserService }
+  ]
+});
+```
+
+---
+
+## useInterface
+
+```typescript
+function useInterface<T>(): InterfaceToken<T>
+```
+
+Create a token for an interface. At compile time, this generates a unique string ID.
+
+### Type Parameters
+
+| Name | Description |
+|------|-------------|
+| `T` | The interface type |
+
+### Returns
+
+`InterfaceToken<T>` - A token representing the interface
+
+### Example
+
+```typescript
+import { useInterface } from '@djodjonx/neo-syringe';
+
+interface ILogger {
+  log(msg: string): void;
+}
+
+interface IDatabase {
+  query(sql: string): any[];
+}
+
+// In configuration
+{
+  injections: [
+    { token: useInterface<ILogger>(), provider: ConsoleLogger },
+    { token: useInterface<IDatabase>(), provider: PostgresDatabase }
+  ]
+}
+
+// Resolution
+const logger = container.resolve(useInterface<ILogger>());
+```
+
+---
+
+## useProperty
+
+```typescript
+function useProperty<T, C = unknown>(
+  targetClass: Constructor<C>,
+  paramName: string
+): PropertyToken<T, C>
+```
+
+Create a token for a primitive constructor parameter.
+
+### Type Parameters
+
+| Name | Description |
+|------|-------------|
+| `T` | The primitive type (string, number, boolean) |
+| `C` | The class type |
+
+### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `targetClass` | `Constructor<C>` | The class that has this parameter |
+| `paramName` | `string` | The parameter name |
+
+### Returns
+
+`PropertyToken<T, C>` - A token for the primitive
+
+### Example
+
+```typescript
+import { useProperty } from '@djodjonx/neo-syringe';
+
+class ApiService {
+  constructor(
+    private apiUrl: string,
+    private timeout: number
+  ) {}
+}
+
+const apiUrl = useProperty<string>(ApiService, 'apiUrl');
+const timeout = useProperty<number>(ApiService, 'timeout');
+
+// In configuration
+{
+  injections: [
+    { token: apiUrl, provider: () => 'https://api.example.com' },
+    { token: timeout, provider: () => 5000 },
+    { token: ApiService }
+  ]
+}
+```
+
+---
+
+## declareContainerTokens
+
+```typescript
+function declareContainerTokens<T>(container: any): any
+```
+
+Declare tokens provided by a legacy container for type-safety and validation.
+
+### Type Parameters
+
+| Name | Description |
+|------|-------------|
+| `T` | Object type mapping token names to types |
+
+### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `container` | `any` | The legacy container instance |
+
+### Returns
+
+The container with declared types
+
+### Example
+
+```typescript
+import { declareContainerTokens } from '@djodjonx/neo-syringe';
+import { container as tsyringeContainer } from 'tsyringe';
+
+// Declare what tsyringe provides
+const legacy = declareContainerTokens<{
+  AuthService: AuthService;
+  UserRepository: UserRepository;
+}>(tsyringeContainer);
+
+// Use in configuration
+export const container = defineBuilderConfig({
+  useContainer: legacy,
+  injections: [
+    { token: NewService }  // Can depend on AuthService, UserRepository
+  ]
+});
+```
+
+---
+
+## Container.resolve
+
+```typescript
+resolve<T>(token: Token<T>): T
+```
+
+Resolve a service from the container.
+
+### Type Parameters
+
+| Name | Description |
+|------|-------------|
+| `T` | The service type |
+
+### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `token` | `Token<T>` | Class, interface token, or property token |
+
+### Returns
+
+`T` - The resolved instance
+
+### Throws
+
+`Error` - If the service is not found
+
+### Example
+
+```typescript
+// By class
+const userService = container.resolve(UserService);
+
+// By interface
+const logger = container.resolve(useInterface<ILogger>());
+
+// By property (unusual, but possible)
+const apiUrl = container.resolve(useProperty<string>(ApiService, 'apiUrl'));
+```
+
+---
+
+## Container.createChildContainer
+
+```typescript
+createChildContainer(): Container
+```
+
+Create a child container that inherits from this one.
+
+### Returns
+
+`Container` - A new child container
+
+### Example
+
+```typescript
+const parent = container;
+const child = parent.createChildContainer();
+
+// Child can resolve parent's services
+const logger = child.resolve(useInterface<ILogger>());
+```
+

package/docs/api/types.md

@@ -0,0 +1,158 @@
+# Types
+
+Type definitions for Neo-Syringe.
+
+## Lifecycle
+
+```typescript
+type Lifecycle = 'singleton' | 'transient';
+```
+
+Defines how instances are managed:
+
+| Value | Description |
+|-------|-------------|
+| `singleton` | One instance per container (default) |
+| `transient` | New instance on every `resolve()` |
+
+## Constructor
+
+```typescript
+type Constructor<T = unknown> = new (...args: unknown[]) => T;
+```
+
+Represents any class constructor.
+
+## Token
+
+```typescript
+type Token<T = any> = Constructor<T> | InterfaceToken<T> | PropertyToken<T, any>;
+```
+
+A token that can be resolved by the container:
+
+- **Constructor**: A class reference (e.g., `UserService`)
+- **InterfaceToken**: Created by `useInterface<T>()`
+- **PropertyToken**: Created by `useProperty<T>(Class, 'param')`
+
+## InterfaceToken
+
+```typescript
+type InterfaceToken<T> = {
+  __brand: 'InterfaceToken';
+  __type: T;
+};
+```
+
+A compile-time token for interfaces. Created by `useInterface<T>()`.
+
+::: warning Internal Type
+You don't create this directly. Use `useInterface<T>()` instead.
+:::
+
+## PropertyToken
+
+```typescript
+type PropertyToken<T, C = unknown> = {
+  __brand: 'PropertyToken';
+  __type: T;
+  __class: C;
+  __name: string;
+};
+```
+
+A token for primitive values bound to a specific class parameter. Created by `useProperty<T>(Class, 'param')`.
+
+## Provider
+
+```typescript
+type Provider<T> = Constructor<T> | Factory<T>;
+```
+
+What creates instances:
+
+- **Constructor**: A class to instantiate
+- **Factory**: A function that creates the instance
+
+## Factory
+
+```typescript
+type Factory<T> = (container: Container) => T;
+```
+
+A function that receives the container and returns an instance.
+
+```typescript
+const myFactory: Factory<IConfig> = (container) => ({
+  apiUrl: process.env.API_URL,
+  logger: container.resolve(useInterface<ILogger>())
+});
+```
+
+## Injection
+
+```typescript
+interface Injection<T = any> {
+  token: Token<T>;
+  provider?: Provider<T>;
+  useFactory?: boolean;
+  lifecycle?: Lifecycle;
+  scoped?: boolean;
+}
+```
+
+A single injection definition:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `token` | `Token<T>` | **Required**. What to register |
+| `provider` | `Provider<T>` | Optional. What provides the instance |
+| `useFactory` | `boolean` | Explicit factory flag |
+| `lifecycle` | `Lifecycle` | `'singleton'` (default) or `'transient'` |
+| `scoped` | `boolean` | If `true`, resolve locally (override parent) |
+
+## PartialConfig
+
+```typescript
+interface PartialConfig {
+  injections?: Injection[];
+}
+```
+
+A reusable configuration block.
+
+## BuilderConfig
+
+```typescript
+interface BuilderConfig extends PartialConfig {
+  name?: string;
+  extends?: PartialConfig[];
+  useContainer?: any;
+}
+```
+
+Main configuration for a container:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | `string` | Container name (for debugging) |
+| `injections` | `Injection[]` | List of injections |
+| `extends` | `PartialConfig[]` | Inherit from partials |
+| `useContainer` | `any` | Parent container |
+
+## Container
+
+```typescript
+interface Container {
+  resolve<T>(token: Token<T>): T;
+  createChildContainer(): Container;
+}
+```
+
+The generated container interface:
+
+| Method | Description |
+|--------|-------------|
+| `resolve<T>(token)` | Resolve a service by token |
+| `createChildContainer()` | Create a child container |
+

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');
+```
+