@djodjonx/neo-syringe 1.2.0 → 1.2.2

package/docs/api/configuration.md

@@ -0,0 +1,274 @@
+# Configuration
+
+Configure Neo-Syringe in your project.
+
+## Build Plugin
+
+### Vite
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { neoSyringePlugin } from '@djodjonx/neo-syringe/plugin';
+
+export default defineConfig({
+  plugins: [neoSyringePlugin.vite()]
+});
+```
+
+### Rollup
+
+```typescript
+// rollup.config.js
+import { neoSyringePlugin } from '@djodjonx/neo-syringe/plugin';
+
+export default {
+  input: 'src/main.ts',
+  output: {
+    file: 'dist/bundle.js',
+    format: 'esm'
+  },
+  plugins: [neoSyringePlugin.rollup()]
+};
+```
+
+### Webpack
+
+```javascript
+// webpack.config.js
+const { webpack } = require('@djodjonx/neo-syringe/plugin');
+
+module.exports = {
+  plugins: [webpack()]
+};
+```
+
+### esbuild
+
+```typescript
+// esbuild.config.js
+import { neoSyringePlugin } from '@djodjonx/neo-syringe/plugin';
+import esbuild from 'esbuild';
+
+await esbuild.build({
+  entryPoints: ['src/main.ts'],
+  bundle: true,
+  outfile: 'dist/bundle.js',
+  plugins: [neoSyringePlugin.esbuild()]
+});
+```
+
+### Rspack
+
+```javascript
+// rspack.config.js
+const { rspack } = require('@djodjonx/neo-syringe/plugin');
+
+module.exports = {
+  plugins: [rspack()]
+};
+```
+
+## TypeScript LSP Plugin
+
+Add to `tsconfig.json` for IDE error detection:
+
+```json
+{
+  "compilerOptions": {
+    "plugins": [
+      { "name": "@djodjonx/neo-syringe/lsp" }
+    ]
+  }
+}
+```
+
+::: tip VS Code
+Remember to select "Use Workspace Version" for TypeScript.
+:::
+
+## BuilderConfig Options
+
+```typescript
+defineBuilderConfig({
+  // Container name (for debugging)
+  name: 'AppContainer',
+  
+  // List of injections
+  injections: [
+    { token: UserService },
+    { token: useInterface<ILogger>(), provider: ConsoleLogger }
+  ],
+  
+  // Inherit from partial configs
+  extends: [loggingPartial, databasePartial],
+  
+  // Parent container (Neo-Syringe or legacy)
+  useContainer: parentContainer
+});
+```
+
+### name
+
+Type: `string`
+
+Optional. The container name appears in error messages.
+
+```typescript
+defineBuilderConfig({
+  name: 'UserModule'
+});
+
+// Error: [UserModule] Service not found: XYZ
+```
+
+### injections
+
+Type: `Injection[]`
+
+Required. List of services to register.
+
+```typescript
+defineBuilderConfig({
+  injections: [
+    // Class autowiring
+    { token: UserService },
+    
+    // Interface binding
+    { token: useInterface<ILogger>(), provider: ConsoleLogger },
+    
+    // Explicit provider
+    { token: BaseService, provider: ConcreteService },
+    
+    // Factory
+    { token: useInterface<IConfig>(), provider: () => loadConfig() },
+    
+    // Property token
+    { token: useProperty<string>(ApiService, 'apiUrl'), provider: () => 'http://...' },
+    
+    // With lifecycle
+    { token: RequestContext, lifecycle: 'transient' },
+    
+    // Scoped override
+    { token: useInterface<ILogger>(), provider: MockLogger, scoped: true }
+  ]
+});
+```
+
+### extends
+
+Type: `PartialConfig[]`
+
+Optional. Inherit injections from partial configs.
+
+```typescript
+const loggingPartial = definePartialConfig({
+  injections: [
+    { token: useInterface<ILogger>(), provider: ConsoleLogger }
+  ]
+});
+
+defineBuilderConfig({
+  extends: [loggingPartial],
+  injections: [
+    { token: UserService }  // Can use ILogger
+  ]
+});
+```
+
+### useContainer
+
+Type: `Container | any`
+
+Optional. Parent container for delegation.
+
+```typescript
+// Neo-Syringe parent
+defineBuilderConfig({
+  useContainer: sharedKernel,
+  injections: [...]
+});
+
+// Legacy container (tsyringe, etc.)
+const legacy = declareContainerTokens<{...}>(tsyringeContainer);
+defineBuilderConfig({
+  useContainer: legacy,
+  injections: [...]
+});
+```
+
+## Injection Options
+
+```typescript
+interface Injection<T> {
+  token: Token<T>;
+  provider?: Provider<T>;
+  useFactory?: boolean;
+  lifecycle?: 'singleton' | 'transient';
+  scoped?: boolean;
+}
+```
+
+### token
+
+Type: `Token<T>` (required)
+
+What to register. Can be:
+
+- Class constructor: `UserService`
+- Interface token: `useInterface<ILogger>()`
+- Property token: `useProperty<string>(ApiService, 'apiUrl')`
+
+### provider
+
+Type: `Provider<T>`
+
+What provides the instance. Can be:
+
+- Class constructor: `ConsoleLogger`
+- Factory function: `(container) => new Service()`
+
+If omitted, the token itself is used (autowiring).
+
+### useFactory
+
+Type: `boolean`
+
+Force treating the provider as a factory function.
+
+```typescript
+// Auto-detected (arrow function)
+{ provider: () => createService() }
+
+// Explicit (regular function)
+{ provider: createService, useFactory: true }
+```
+
+### lifecycle
+
+Type: `'singleton' | 'transient'`
+
+Default: `'singleton'`
+
+How instances are managed.
+
+```typescript
+{ token: UserService, lifecycle: 'singleton' }  // One instance
+{ token: RequestContext, lifecycle: 'transient' }  // New each time
+```
+
+### scoped
+
+Type: `boolean`
+
+Default: `false`
+
+If `true`, resolve locally instead of delegating to parent.
+
+```typescript
+// Override parent's ILogger with local MockLogger
+{ token: useInterface<ILogger>(), provider: MockLogger, scoped: true }
+```
+
+See [Scoped Injections](/guide/scoped-injections) for details.
+

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