inwire 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,387 @@
+/**
+ * A factory function that receives the container and returns an instance.
+ *
+ * @example
+ * ```typescript
+ * const factory: Factory<MyService> = (c) => new MyService(c.db);
+ * ```
+ */
+type Factory<T = any> = (container: any) => T;
+/**
+ * An object of factory functions — the definition of a container.
+ * Each key maps to a factory that produces the dependency.
+ *
+ * @example
+ * ```typescript
+ * const deps: DepsDefinition = {
+ *   logger: () => new LoggerService(),
+ *   db: () => new Database(process.env.DB_URL!),
+ *   userRepo: (c) => new PgUserRepo(c.db),
+ * };
+ * ```
+ */
+type DepsDefinition = Record<string, Factory>;
+/**
+ * Extracts the resolved types from a deps definition.
+ * Maps each key to the return type of its factory function.
+ *
+ * @example
+ * ```typescript
+ * type Resolved = ResolvedDeps<{ logger: () => LoggerService }>;
+ * // { logger: LoggerService }
+ * ```
+ */
+type ResolvedDeps<T extends DepsDefinition> = {
+    readonly [K in keyof T]: ReturnType<T[K]>;
+};
+/**
+ * Options for creating a scoped container.
+ */
+interface ScopeOptions {
+    /** Optional name for the scope, useful for debugging and introspection. */
+    name?: string;
+}
+/**
+ * Full container type exposed to the user.
+ * Combines resolved dependencies with container methods.
+ *
+ * @example
+ * ```typescript
+ * const container: Container<{ logger: LoggerService }> = createContainer({
+ *   logger: () => new LoggerService(),
+ * });
+ * container.logger; // LoggerService
+ * container.inspect(); // ContainerGraph
+ * ```
+ */
+type Container<T extends Record<string, any> = Record<string, any>> = T & IContainer<T>;
+/**
+ * Container methods interface. Defines the API available on every container.
+ */
+interface IContainer<T extends Record<string, any> = Record<string, any>> {
+    /**
+     * Creates a child container with additional dependencies.
+     * Child inherits all parent singletons and can add/override deps.
+     *
+     * @example
+     * ```typescript
+     * const request = app.scope({
+     *   requestId: () => crypto.randomUUID(),
+     *   currentUser: () => extractUser(req),
+     * });
+     * request.requestId; // scoped singleton
+     * request.logger;    // inherited from parent
+     * ```
+     */
+    scope<E extends DepsDefinition>(extra: E, options?: ScopeOptions): Container<T & ResolvedDeps<E>>;
+    /**
+     * Returns a new container with additional dependencies.
+     * Existing singletons are shared. The original container is not modified.
+     *
+     * @example
+     * ```typescript
+     * const appWithAuth = app.extend(authDeps);
+     * ```
+     */
+    extend<E extends DepsDefinition>(extra: E): Container<T & ResolvedDeps<E>>;
+    /**
+     * Pre-resolves dependencies (warm-up).
+     * Call with specific keys to resolve only those, or without arguments to resolve all.
+     *
+     * @example
+     * ```typescript
+     * await container.preload('db', 'cache'); // specific deps
+     * await container.preload();              // all deps
+     * ```
+     */
+    preload(...keys: (keyof T)[]): Promise<void>;
+    /**
+     * Returns the full dependency graph as a serializable JSON object.
+     * Useful for AI analysis of the architecture.
+     *
+     * @example
+     * ```typescript
+     * container.inspect();
+     * // { providers: { logger: { key: 'logger', resolved: true, deps: [], scope: 'singleton' } } }
+     * ```
+     */
+    inspect(): ContainerGraph;
+    /**
+     * Returns detailed information about a specific provider.
+     *
+     * @example
+     * ```typescript
+     * container.describe('userService');
+     * // { key: 'userService', resolved: true, deps: ['userRepo', 'logger'], scope: 'singleton' }
+     * ```
+     */
+    describe(key: keyof T): ProviderInfo;
+    /**
+     * Returns container health status and warnings.
+     *
+     * @example
+     * ```typescript
+     * container.health();
+     * // { totalProviders: 12, resolved: ['db', 'logger'], unresolved: ['cache'], warnings: [] }
+     * ```
+     */
+    health(): ContainerHealth;
+    /**
+     * Invalidates cached singletons, forcing re-creation on next access.
+     * Does not affect parent scopes.
+     *
+     * @example
+     * ```typescript
+     * container.reset('db');       // reset one
+     * container.reset('db', 'cache'); // reset multiple
+     * ```
+     */
+    reset(...keys: (keyof T)[]): void;
+    /**
+     * Disposes the container. Calls `onDestroy()` on all resolved instances
+     * that implement it, in reverse resolution order.
+     *
+     * @example
+     * ```typescript
+     * await container.dispose();
+     * ```
+     */
+    dispose(): Promise<void>;
+}
+/**
+ * Full dependency graph of the container.
+ */
+interface ContainerGraph {
+    name?: string;
+    providers: Record<string, ProviderInfo>;
+}
+/**
+ * Detailed information about a single provider/dependency.
+ */
+interface ProviderInfo {
+    key: string;
+    resolved: boolean;
+    deps: string[];
+    scope: 'singleton' | 'transient';
+}
+/**
+ * Container health status with warnings.
+ */
+interface ContainerHealth {
+    totalProviders: number;
+    resolved: string[];
+    unresolved: string[];
+    warnings: ContainerWarning[];
+}
+/**
+ * A warning detected by the container's runtime analysis.
+ */
+interface ContainerWarning {
+    type: 'scope_mismatch' | 'duplicate_key';
+    message: string;
+    details: Record<string, unknown>;
+}
+
+/**
+ * Base class for all container errors.
+ * Every error includes a human-readable `hint` and structured `details`
+ * so that AI tools and developers can auto-correct issues.
+ *
+ * @example
+ * ```typescript
+ * try { container.userService; }
+ * catch (e) {
+ *   if (e instanceof ContainerError) {
+ *     console.log(e.hint);    // actionable fix
+ *     console.log(e.details); // structured context
+ *   }
+ * }
+ * ```
+ */
+declare abstract class ContainerError extends Error {
+    abstract readonly hint: string;
+    abstract readonly details: Record<string, unknown>;
+    constructor(message: string);
+}
+/**
+ * Thrown when a non-function value is passed in the deps definition.
+ *
+ * @example
+ * ```typescript
+ * createContainer({ apiKey: 'sk-123' });
+ * // ContainerConfigError: 'apiKey' must be a factory function, got string.
+ * // hint: "Wrap it: apiKey: () => 'sk-123'"
+ * ```
+ */
+declare class ContainerConfigError extends ContainerError {
+    readonly hint: string;
+    readonly details: Record<string, unknown>;
+    constructor(key: string, actualType: string);
+}
+/**
+ * Thrown when a reserved container method name is used as a dependency key.
+ *
+ * @example
+ * ```typescript
+ * createContainer({ inspect: () => 'foo' });
+ * // ReservedKeyError: 'inspect' is a reserved container method.
+ * // hint: "Rename this dependency, e.g. 'inspectService' or 'dataInspector'."
+ * ```
+ */
+declare class ReservedKeyError extends ContainerError {
+    readonly hint: string;
+    readonly details: Record<string, unknown>;
+    constructor(key: string, reserved: readonly string[]);
+}
+/**
+ * Thrown when a dependency cannot be found during resolution.
+ * Includes fuzzy suggestion if a similar key exists.
+ *
+ * @example
+ * ```typescript
+ * container.userService;
+ * // ProviderNotFoundError: Cannot resolve 'userService': dependency 'userRepo' not found.
+ * // hint: "Did you mean 'userRepository'?"
+ * ```
+ */
+declare class ProviderNotFoundError extends ContainerError {
+    readonly hint: string;
+    readonly details: Record<string, unknown>;
+    constructor(key: string, chain: string[], registered: string[], suggestion?: string);
+}
+/**
+ * Thrown when a circular dependency is detected.
+ *
+ * @example
+ * ```typescript
+ * // CircularDependencyError: Circular dependency detected while resolving 'authService'.
+ * // Cycle: authService -> userService -> authService
+ * ```
+ */
+declare class CircularDependencyError extends ContainerError {
+    readonly hint: string;
+    readonly details: Record<string, unknown>;
+    constructor(key: string, chain: string[]);
+}
+/**
+ * Thrown when a factory function returns `undefined`.
+ *
+ * @example
+ * ```typescript
+ * container.db;
+ * // UndefinedReturnError: Factory 'db' returned undefined.
+ * // hint: "Did you forget a return statement?"
+ * ```
+ */
+declare class UndefinedReturnError extends ContainerError {
+    readonly hint: string;
+    readonly details: Record<string, unknown>;
+    constructor(key: string, chain: string[]);
+}
+/**
+ * Thrown when a factory function throws an error during resolution.
+ * Wraps the original error with resolution context.
+ *
+ * @example
+ * ```typescript
+ * container.db;
+ * // FactoryError: Factory 'db' threw an error: "Connection refused"
+ * ```
+ */
+declare class FactoryError extends ContainerError {
+    readonly hint: string;
+    readonly details: Record<string, unknown>;
+    readonly originalError: unknown;
+    constructor(key: string, chain: string[], originalError: unknown);
+}
+/**
+ * Warning emitted when a singleton depends on a transient dependency.
+ * The transient value gets frozen inside the singleton — almost always a bug.
+ *
+ * @example
+ * ```typescript
+ * // ScopeMismatchWarning: Singleton 'userService' depends on transient 'requestId'.
+ * ```
+ */
+declare class ScopeMismatchWarning {
+    readonly type: "scope_mismatch";
+    readonly message: string;
+    readonly hint: string;
+    readonly details: Record<string, unknown>;
+    constructor(singletonKey: string, transientKey: string);
+}
+
+/**
+ * Creates a dependency injection container from an object of factory functions.
+ * Each factory receives the container and returns an instance.
+ * Dependencies are resolved lazily and cached as singletons by default.
+ *
+ * @example
+ * ```typescript
+ * const container = createContainer({
+ *   logger: () => new LoggerService(),
+ *   db: () => new Database(process.env.DB_URL!),
+ *   userRepo: (c): UserRepository => new PgUserRepo(c.db),
+ *   userService: (c) => new UserService(c.userRepo, c.logger),
+ * });
+ *
+ * container.userService; // type: UserService — lazy, singleton, fully resolved
+ * ```
+ */
+declare function createContainer<T extends DepsDefinition>(defs: T): Container<ResolvedDeps<T>>;
+
+/**
+ * Wraps a factory function to produce a new instance on every access,
+ * instead of the default singleton behavior.
+ *
+ * @example
+ * ```typescript
+ * import { createContainer, transient } from 'inwire';
+ *
+ * const container = createContainer({
+ *   logger: () => new LoggerService(),                  // singleton (default)
+ *   requestId: transient(() => crypto.randomUUID()),   // new instance every access
+ * });
+ *
+ * container.requestId; // 'abc-123'
+ * container.requestId; // 'def-456' (different!)
+ * ```
+ */
+declare function transient<T>(factory: Factory<T>): Factory<T>;
+
+/**
+ * Implement this interface (or just add an `onInit` method) to run
+ * initialization logic when the dependency is first resolved.
+ *
+ * @example
+ * ```typescript
+ * class Database implements OnInit {
+ *   async onInit() { await this.connect(); }
+ * }
+ * ```
+ */
+interface OnInit {
+    onInit(): void | Promise<void>;
+}
+/**
+ * Implement this interface (or just add an `onDestroy` method) to run
+ * cleanup logic when `container.dispose()` is called.
+ *
+ * @example
+ * ```typescript
+ * class Database implements OnDestroy {
+ *   async onDestroy() { await this.disconnect(); }
+ * }
+ * ```
+ */
+interface OnDestroy {
+    onDestroy(): void | Promise<void>;
+}
+
+/**
+ * Detects duplicate keys across multiple modules (spread objects).
+ * Returns an array of keys that appear in more than one source.
+ */
+declare function detectDuplicateKeys(...modules: Record<string, unknown>[]): string[];
+
+export { CircularDependencyError, type Container, ContainerConfigError, ContainerError, type ContainerGraph, type ContainerHealth, type ContainerWarning, type DepsDefinition, type Factory, FactoryError, type IContainer, type OnDestroy, type OnInit, type ProviderInfo, ProviderNotFoundError, ReservedKeyError, type ResolvedDeps, ScopeMismatchWarning, type ScopeOptions, UndefinedReturnError, createContainer, detectDuplicateKeys, transient };