@cleverbrush/di 0.0.0-beta-20260410162047

package/dist/ServiceCollection.d.ts

@@ -0,0 +1,274 @@
+import type { FunctionSchemaBuilder, InferType, SchemaBuilder } from '@cleverbrush/schema';
+import { ServiceProvider } from './ServiceProvider.js';
+import type { ServiceFactory, ServiceRegistrationOptions } from './types.js';
+/**
+ * Options for building a {@link ServiceProvider} from a {@link ServiceCollection}.
+ *
+ * @see {@link ServiceCollection.buildServiceProvider}
+ */
+export interface ServiceProviderOptions {
+    /**
+     * When `true`, resolving a {@link ServiceLifetime.Scoped | Scoped} service
+     * from the root provider (outside of a scope) throws an error. This helps
+     * catch accidental singleton captures of scoped services.
+     *
+     * Recommended for development. Matches .NET's `ValidateScopes` behaviour.
+     *
+     * @defaultValue `true`
+     */
+    validateScopes?: boolean;
+}
+/**
+ * A mutable collection of service registrations. Build up the collection by
+ * calling {@link addSingleton}, {@link addScoped}, or {@link addTransient},
+ * then call {@link buildServiceProvider} to create an immutable
+ * {@link ServiceProvider}.
+ *
+ * Schema instances act as service keys via reference equality — the same
+ * schema object used during registration must be used during resolution.
+ *
+ * @example Basic registration and resolution
+ * ```ts
+ * import { ServiceCollection } from '@cleverbrush/di';
+ * import { object, string, number, func } from '@cleverbrush/schema';
+ *
+ * const IConfig = object({ port: number(), host: string() });
+ * const ILogger = object({ info: func() });
+ *
+ * const services = new ServiceCollection();
+ * services.addSingleton(IConfig, { port: 3000, host: 'localhost' });
+ * services.addSingleton(ILogger, () => ({ info: console.log }));
+ *
+ * const provider = services.buildServiceProvider();
+ * const config = provider.get(IConfig); // { port: number; host: string }
+ * ```
+ *
+ * @example Function-schema-driven registration
+ * ```ts
+ * const IGreeter = object({ greet: func() });
+ * const greeterFactory = func()
+ *     .addParameter(IConfig)
+ *     .addParameter(ILogger);
+ *
+ * services.addSingletonFromSchema(
+ *     IGreeter,
+ *     greeterFactory,
+ *     (config, logger) => ({
+ *         greet() { logger.info(`Hello from ${config.host}`); }
+ *     })
+ * );
+ * ```
+ *
+ * @see {@link ServiceProvider}
+ * @see {@link ServiceLifetime}
+ */
+export declare class ServiceCollection {
+    #private;
+    /**
+     * Registers a service with {@link ServiceLifetime.Singleton | Singleton}
+     * lifetime. The factory (or value) is called at most once; every
+     * subsequent resolution returns the same instance.
+     *
+     * @param schema - The schema used as the service identifier.
+     * @param factoryOrValue - Either a {@link ServiceFactory} function that
+     *   receives the provider, or a plain value (which is wrapped in a
+     *   factory automatically).
+     * @param options - Optional {@link ServiceRegistrationOptions}.
+     * @returns `this` for chaining.
+     *
+     * @example Factory registration
+     * ```ts
+     * services.addSingleton(ILogger, (provider) => {
+     *     const config = provider.get(IConfig);
+     *     return new ConsoleLogger(config.logLevel);
+     * });
+     * ```
+     *
+     * @example Value shorthand
+     * ```ts
+     * services.addSingleton(IConfig, { port: 3000, host: 'localhost' });
+     * ```
+     *
+     * @see {@link addScoped}
+     * @see {@link addTransient}
+     */
+    addSingleton<TSchema extends SchemaBuilder<any, any, any, any, any>>(schema: TSchema, factoryOrValue: ServiceFactory<InferType<TSchema>> | InferType<TSchema>, options?: ServiceRegistrationOptions): this;
+    /**
+     * Registers a service with {@link ServiceLifetime.Scoped | Scoped}
+     * lifetime. One instance is created per {@link ServiceScope}; within a
+     * scope every resolution returns the same instance.
+     *
+     * @param schema - The schema used as the service identifier.
+     * @param factory - A {@link ServiceFactory} function that creates the
+     *   service instance. Unlike {@link addSingleton}, a plain value is
+     *   **not** accepted because scoped services must be freshly created
+     *   per scope.
+     * @param options - Optional {@link ServiceRegistrationOptions}.
+     * @returns `this` for chaining.
+     *
+     * @example
+     * ```ts
+     * const IDbContext = object({ query: func() });
+     *
+     * services.addScoped(IDbContext, (provider) => {
+     *     const config = provider.get(IConfig);
+     *     return new DbContext(config.connectionString);
+     * });
+     * ```
+     *
+     * @see {@link addSingleton}
+     * @see {@link addTransient}
+     */
+    addScoped<TSchema extends SchemaBuilder<any, any, any, any, any>>(schema: TSchema, factory: ServiceFactory<InferType<TSchema>>, options?: ServiceRegistrationOptions): this;
+    /**
+     * Registers a service with {@link ServiceLifetime.Transient | Transient}
+     * lifetime. A new instance is created on every resolution.
+     *
+     * @param schema - The schema used as the service identifier.
+     * @param factory - A {@link ServiceFactory} function that creates the
+     *   service instance.
+     * @param options - Optional {@link ServiceRegistrationOptions}.
+     * @returns `this` for chaining.
+     *
+     * @example
+     * ```ts
+     * const IRequestId = object({ id: string() });
+     *
+     * services.addTransient(IRequestId, () => ({
+     *     id: crypto.randomUUID()
+     * }));
+     * ```
+     *
+     * @see {@link addSingleton}
+     * @see {@link addScoped}
+     */
+    addTransient<TSchema extends SchemaBuilder<any, any, any, any, any>>(schema: TSchema, factory: ServiceFactory<InferType<TSchema>>, options?: ServiceRegistrationOptions): this;
+    /**
+     * Registers a pre-created instance as a {@link ServiceLifetime.Singleton | Singleton}.
+     * Unlike {@link addSingleton}, the second argument is always treated as the
+     * service value — never as a factory function. This makes it safe to
+     * register a function-typed service (e.g. a schema backed by `func()`)
+     * without the container accidentally invoking it as a factory.
+     *
+     * @param schema - The schema used as the service identifier.
+     * @param instance - The pre-created value to register. Can be any type
+     *   including a function.
+     * @param options - Optional {@link ServiceRegistrationOptions}.
+     * @returns `this` for chaining.
+     *
+     * @example Register a plain object instance
+     * ```ts
+     * const config = { port: 3000, host: 'localhost' };
+     * services.addSingletonInstance(IConfig, config);
+     * ```
+     *
+     * @example Register a function value (impossible with {@link addSingleton})
+     * ```ts
+     * const IHandler = func();
+     * const myHandler = (req: Request) => new Response('ok');
+     * services.addSingletonInstance(IHandler, myHandler);
+     * ```
+     *
+     * @see {@link addSingleton}
+     */
+    addSingletonInstance<TSchema extends SchemaBuilder<any, any, any, any, any>>(schema: TSchema, instance: InferType<TSchema>, options?: ServiceRegistrationOptions): this;
+    /**
+     * Registers a {@link ServiceLifetime.Singleton | Singleton} service whose
+     * dependencies are described by a {@link FunctionSchemaBuilder}. The
+     * container resolves each parameter schema from the registry and passes
+     * the resolved values to `implementation`.
+     *
+     * @param targetSchema - The schema used as the service identifier for the
+     *   created service.
+     * @param funcSchema - A {@link FunctionSchemaBuilder} whose
+     *   `introspect().parameters` list the dependency schemas.
+     * @param implementation - A function whose parameters match the
+     *   `funcSchema` parameter schemas (in order) and returns the service
+     *   instance.
+     * @param options - Optional {@link ServiceRegistrationOptions}.
+     * @returns `this` for chaining.
+     *
+     * @example
+     * ```ts
+     * const IGreeter = object({ greet: func() });
+     *
+     * const greeterDeps = func()
+     *     .addParameter(IConfig)
+     *     .addParameter(ILogger);
+     *
+     * services.addSingletonFromSchema(
+     *     IGreeter,
+     *     greeterDeps,
+     *     (config, logger) => ({
+     *         greet() { logger.info(`Hello from ${config.host}`); }
+     *     })
+     * );
+     * ```
+     *
+     * @see {@link addScopedFromSchema}
+     * @see {@link addTransientFromSchema}
+     */
+    addSingletonFromSchema<TTargetSchema extends SchemaBuilder<any, any, any, any, any>, TFuncSchema extends FunctionSchemaBuilder<any, any, any, any, any, any>>(targetSchema: TTargetSchema, funcSchema: TFuncSchema, implementation: (...args: FuncSchemaParameters<TFuncSchema>) => InferType<TTargetSchema>, options?: ServiceRegistrationOptions): this;
+    /**
+     * Registers a {@link ServiceLifetime.Scoped | Scoped} service whose
+     * dependencies are described by a {@link FunctionSchemaBuilder}.
+     *
+     * @param targetSchema - The schema used as the service identifier.
+     * @param funcSchema - A {@link FunctionSchemaBuilder} describing the
+     *   dependency schemas via its parameters.
+     * @param implementation - A function receiving the resolved dependencies
+     *   and returning the service instance.
+     * @param options - Optional {@link ServiceRegistrationOptions}.
+     * @returns `this` for chaining.
+     *
+     * @see {@link addSingletonFromSchema}
+     * @see {@link addTransientFromSchema}
+     */
+    addScopedFromSchema<TTargetSchema extends SchemaBuilder<any, any, any, any, any>, TFuncSchema extends FunctionSchemaBuilder<any, any, any, any, any, any>>(targetSchema: TTargetSchema, funcSchema: TFuncSchema, implementation: (...args: FuncSchemaParameters<TFuncSchema>) => InferType<TTargetSchema>, options?: ServiceRegistrationOptions): this;
+    /**
+     * Registers a {@link ServiceLifetime.Transient | Transient} service whose
+     * dependencies are described by a {@link FunctionSchemaBuilder}.
+     *
+     * @param targetSchema - The schema used as the service identifier.
+     * @param funcSchema - A {@link FunctionSchemaBuilder} describing the
+     *   dependency schemas via its parameters.
+     * @param implementation - A function receiving the resolved dependencies
+     *   and returning the service instance.
+     * @param options - Optional {@link ServiceRegistrationOptions}.
+     * @returns `this` for chaining.
+     *
+     * @see {@link addSingletonFromSchema}
+     * @see {@link addScopedFromSchema}
+     */
+    addTransientFromSchema<TTargetSchema extends SchemaBuilder<any, any, any, any, any>, TFuncSchema extends FunctionSchemaBuilder<any, any, any, any, any, any>>(targetSchema: TTargetSchema, funcSchema: TFuncSchema, implementation: (...args: FuncSchemaParameters<TFuncSchema>) => InferType<TTargetSchema>, options?: ServiceRegistrationOptions): this;
+    /**
+     * Creates a new {@link ServiceProvider} from the registrations currently
+     * contained in this collection.
+     *
+     * @param options - Optional {@link ServiceProviderOptions} to control
+     *   provider behaviour (e.g. scope validation).
+     * @returns A new {@link ServiceProvider} instance.
+     *
+     * @example
+     * ```ts
+     * const provider = services.buildServiceProvider();
+     * const logger = provider.get(ILogger);
+     * ```
+     *
+     * @example With scope validation disabled
+     * ```ts
+     * const provider = services.buildServiceProvider({
+     *     validateScopes: false
+     * });
+     * ```
+     */
+    buildServiceProvider(options?: ServiceProviderOptions): ServiceProvider;
+}
+/**
+ * Extracts the parameter types from a {@link FunctionSchemaBuilder} as a tuple.
+ * Used internally to type-check `addSingletonFromSchema`-style registrations.
+ */
+type FuncSchemaParameters<T extends FunctionSchemaBuilder<any, any, any, any, any, any>> = T extends FunctionSchemaBuilder<any, any, any, any, any, infer TParams extends SchemaBuilder<any, any, any, any, any>[]> ? {
+    [K in keyof TParams]: InferType<TParams[K]>;
+} : never;
+export {};

package/dist/ServiceProvider.d.ts

@@ -0,0 +1,164 @@
+import type { FunctionSchemaBuilder, InferType, SchemaBuilder } from '@cleverbrush/schema';
+import type { ServiceProviderOptions } from './ServiceCollection.js';
+import { ServiceScope } from './ServiceScope.js';
+import type { IServiceProvider, ServiceDescriptor } from './types.js';
+/**
+ * An immutable service provider that resolves services from a frozen set of
+ * {@link ServiceDescriptor | descriptors}. Obtain an instance by calling
+ * {@link ServiceCollection.buildServiceProvider}.
+ *
+ * Supports three service lifetimes:
+ * - **Singleton** — one instance per provider, cached after first resolution.
+ * - **Scoped** — one instance per {@link ServiceScope}, created via
+ *   {@link createScope}.
+ * - **Transient** — a new instance on every call to {@link get}.
+ *
+ * @example Resolving services
+ * ```ts
+ * const provider = services.buildServiceProvider();
+ *
+ * // Typed via the schema — no explicit generic needed
+ * const config = provider.get(IConfig);
+ * config.port; // number
+ *
+ * // Optional resolution (returns undefined if not registered)
+ * const maybeMail = provider.getOptional(IMailer);
+ * ```
+ *
+ * @example Using scopes
+ * ```ts
+ * // Per-request scope (e.g. in an HTTP handler)
+ * using scope = provider.createScope();
+ * const db = scope.serviceProvider.get(IDbContext);
+ * // db is disposed when scope exits
+ * ```
+ *
+ * @example Function injection
+ * ```ts
+ * const handlerSchema = func()
+ *     .addParameter(ILogger)
+ *     .addParameter(IDbContext)
+ *     .hasReturnType(string());
+ *
+ * const result = provider.invoke(handlerSchema, (logger, db) => {
+ *     logger.info('Handling request');
+ *     return db.query('SELECT 1');
+ * });
+ * ```
+ *
+ * @see {@link ServiceCollection}
+ * @see {@link ServiceScope}
+ */
+export declare class ServiceProvider implements IServiceProvider {
+    #private;
+    /**
+     * @hidden
+     */
+    constructor(descriptors: Map<SchemaBuilder<any, any, any, any, any>, ServiceDescriptor>, options?: ServiceProviderOptions);
+    /**
+     * Resolves a service by its schema key.
+     *
+     * - **Singleton**: returns the cached instance, or creates and caches it.
+     * - **Scoped**: throws if called from the root provider when
+     *   `validateScopes` is `true` (default). Use
+     *   {@link createScope} to obtain a scoped provider.
+     * - **Transient**: creates a new instance on every call.
+     *
+     * @param schema - The schema instance used as the service identifier.
+     *   Must be the same reference used during registration.
+     * @returns The resolved service, typed as `InferType<typeof schema>`.
+     * @throws {Error} If the schema is not registered.
+     * @throws {Error} If a scoped service is resolved from the root provider
+     *   with `validateScopes` enabled.
+     * @throws {Error} If a circular dependency is detected.
+     *
+     * @example
+     * ```ts
+     * const logger = provider.get(ILogger);
+     * logger.info('Hello'); // fully typed
+     * ```
+     */
+    get<TSchema extends SchemaBuilder<any, any, any, any, any>>(schema: TSchema): InferType<TSchema>;
+    /**
+     * Resolves a service by its schema key, or returns `undefined` if the
+     * schema is not registered.
+     *
+     * Unlike {@link get}, this method does **not** throw for unregistered
+     * schemas. All other behaviour (lifetime, scope validation, circular
+     * dependency detection) is the same.
+     *
+     * @param schema - The schema instance used as the service identifier.
+     * @returns The resolved service or `undefined`.
+     *
+     * @example
+     * ```ts
+     * const mailer = provider.getOptional(IMailer);
+     * if (mailer) {
+     *     mailer.send('test@example.com', 'Hello');
+     * }
+     * ```
+     */
+    getOptional<TSchema extends SchemaBuilder<any, any, any, any, any>>(schema: TSchema): InferType<TSchema> | undefined;
+    /**
+     * Creates a new {@link ServiceScope}. Scoped services resolved from the
+     * scope's {@link ServiceScope.serviceProvider | serviceProvider} are
+     * cached per-scope and disposed when the scope is disposed.
+     *
+     * The returned scope implements both `Symbol.dispose` and
+     * `Symbol.asyncDispose`, so it works with the `using` keyword:
+     *
+     * @returns A new {@link ServiceScope}.
+     *
+     * @example
+     * ```ts
+     * // Sync disposal
+     * using scope = provider.createScope();
+     * const db = scope.serviceProvider.get(IDbContext);
+     *
+     * // Async disposal
+     * await using scope = provider.createScope();
+     * const db = scope.serviceProvider.get(IDbContext);
+     * ```
+     */
+    createScope(): ServiceScope;
+    /**
+     * Resolves the dependencies described by a {@link FunctionSchemaBuilder}
+     * and calls `implementation` with the resolved values.
+     *
+     * Each parameter schema in `funcSchema.introspect().parameters` is
+     * resolved from this provider. The implementation receives the resolved
+     * values in the same order as the parameter schemas.
+     *
+     * @param funcSchema - A {@link FunctionSchemaBuilder} whose parameters
+     *   describe the services to inject.
+     * @param implementation - A function whose parameters match the
+     *   `funcSchema` parameter types and whose return type matches the
+     *   `funcSchema` return type.
+     * @returns The return value of `implementation`.
+     *
+     * @example
+     * ```ts
+     * const handler = func()
+     *     .addParameter(ILogger)
+     *     .addParameter(IConfig)
+     *     .hasReturnType(string());
+     *
+     * const result = provider.invoke(handler, (logger, config) => {
+     *     logger.info(`Running on port ${config.port}`);
+     *     return 'ok';
+     * });
+     * // result: string
+     * ```
+     *
+     * @see {@link FunctionSchemaBuilder.addParameter}
+     * @see {@link FunctionSchemaBuilder.hasReturnType}
+     */
+    invoke<TFuncSchema extends FunctionSchemaBuilder<any, any, any, any, any, any>>(funcSchema: TFuncSchema, implementation: InferType<TFuncSchema>): ReturnType<InferType<TFuncSchema>>;
+    /**
+     * Resolves a service within a scope context. Called by
+     * {@link ScopedServiceProvider}.
+     *
+     * @hidden
+     */
+    resolveScoped(schema: SchemaBuilder<any, any, any, any, any>, resolutionStack: Set<SchemaBuilder<any, any, any, any, any>>, scopedCache: Map<SchemaBuilder<any, any, any, any, any>, any>, trackDisposable: (instance: any) => void): any;
+}

package/dist/ServiceScope.d.ts

@@ -0,0 +1,201 @@
+import type { FunctionSchemaBuilder, InferType, SchemaBuilder } from '@cleverbrush/schema';
+import type { IServiceProvider, ServiceDescriptor } from './types.js';
+/**
+ * A scoped service container that caches {@link ServiceLifetime.Scoped | Scoped}
+ * services for the duration of its lifetime. Obtain instances via
+ * {@link ServiceProvider.createScope}.
+ *
+ * The scope tracks all created scoped services that implement `Disposable` or
+ * `AsyncDisposable` and disposes them in reverse creation order (LIFO) when the
+ * scope is disposed. This matches .NET's scope disposal semantics.
+ *
+ * Supports the `using` keyword via `Symbol.dispose` and `Symbol.asyncDispose`:
+ *
+ * @example Synchronous disposal
+ * ```ts
+ * using scope = provider.createScope();
+ * const db = scope.serviceProvider.get(IDbContext);
+ * // db is automatically disposed when the block exits
+ * ```
+ *
+ * @example Asynchronous disposal
+ * ```ts
+ * await using scope = provider.createScope();
+ * const db = scope.serviceProvider.get(IDbContext);
+ * // db is asynchronously disposed when the block exits
+ * ```
+ *
+ * @example Manual disposal
+ * ```ts
+ * const scope = provider.createScope();
+ * try {
+ *     const db = scope.serviceProvider.get(IDbContext);
+ *     // use db...
+ * } finally {
+ *     await scope.asyncDispose();
+ * }
+ * ```
+ *
+ * @see {@link ServiceProvider.createScope}
+ * @see {@link ServiceLifetime.Scoped}
+ */
+export declare class ServiceScope implements Disposable, AsyncDisposable {
+    #private;
+    /**
+     * A child {@link IServiceProvider} that resolves services within this scope.
+     *
+     * - **Singleton** services are resolved from the root provider's cache.
+     * - **Scoped** services are resolved from this scope's cache (created on
+     *   first access, reused within the scope).
+     * - **Transient** services create a new instance on every call.
+     *
+     * @example
+     * ```ts
+     * const scope = provider.createScope();
+     * const db = scope.serviceProvider.get(IDbContext); // scoped
+     * const logger = scope.serviceProvider.get(ILogger); // singleton from root
+     * ```
+     */
+    readonly serviceProvider: ScopedServiceProvider;
+    /**
+     * @hidden
+     */
+    constructor(descriptors: Map<SchemaBuilder<any, any, any, any, any>, ServiceDescriptor>, singletonCache: Map<SchemaBuilder<any, any, any, any, any>, any>);
+    /**
+     * Synchronously disposes all scoped services that implement
+     * `Symbol.dispose`, in reverse creation order (LIFO).
+     *
+     * Services that only implement `Symbol.asyncDispose` are skipped during
+     * synchronous disposal. Use {@link asyncDispose} to properly dispose all
+     * services including async ones.
+     *
+     * @throws Re-throws the first error encountered during disposal, but
+     *   still attempts to dispose remaining services.
+     */
+    dispose(): void;
+    /**
+     * Asynchronously disposes all scoped services that implement
+     * `Symbol.asyncDispose` or `Symbol.dispose`, in reverse creation order
+     * (LIFO).
+     *
+     * For each service:
+     * - If it implements `Symbol.asyncDispose`, that method is awaited.
+     * - Otherwise, if it implements `Symbol.dispose`, that method is called
+     *   synchronously.
+     *
+     * @throws Re-throws the first error encountered during disposal, but
+     *   still attempts to dispose remaining services.
+     */
+    asyncDispose(): Promise<void>;
+    /**
+     * Implements the synchronous `Disposable` protocol. Delegates to
+     * {@link dispose}.
+     *
+     * @example
+     * ```ts
+     * using scope = provider.createScope();
+     * ```
+     */
+    [Symbol.dispose](): void;
+    /**
+     * Implements the asynchronous `AsyncDisposable` protocol. Delegates to
+     * {@link asyncDispose}.
+     *
+     * @example
+     * ```ts
+     * await using scope = provider.createScope();
+     * ```
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * @hidden
+     */
+    getDescriptors(): Map<SchemaBuilder<any, any, any, any, any>, ServiceDescriptor>;
+    /**
+     * @hidden
+     */
+    getSingletonCache(): Map<SchemaBuilder<any, any, any, any, any>, any>;
+    /**
+     * @hidden
+     */
+    getScopedCache(): Map<SchemaBuilder<any, any, any, any, any>, any>;
+    /**
+     * @hidden
+     */
+    trackDisposable(instance: any): void;
+}
+/**
+ * A service provider scoped to a {@link ServiceScope}. Resolves scoped
+ * services from the scope's cache and singletons from the root cache.
+ *
+ * This class is not instantiated directly — obtain it via
+ * `scope.serviceProvider`.
+ *
+ * @see {@link ServiceScope}
+ */
+export declare class ScopedServiceProvider implements IServiceProvider {
+    #private;
+    /**
+     * @hidden
+     */
+    constructor(scope: ServiceScope);
+    /**
+     * Resolves a service within this scope.
+     *
+     * - **Singleton** services are resolved from the root provider's cache.
+     * - **Scoped** services are created once per scope and cached.
+     * - **Transient** services are created fresh on every call.
+     *
+     * @param schema - The schema instance used as the service identifier.
+     * @returns The resolved service, typed as `InferType<typeof schema>`.
+     * @throws {Error} If the schema is not registered.
+     * @throws {Error} If a circular dependency is detected.
+     *
+     * @example
+     * ```ts
+     * using scope = provider.createScope();
+     * const db = scope.serviceProvider.get(IDbContext);
+     * ```
+     */
+    get<TSchema extends SchemaBuilder<any, any, any, any, any>>(schema: TSchema): InferType<TSchema>;
+    /**
+     * Resolves a service within this scope, or returns `undefined` if not
+     * registered.
+     *
+     * @param schema - The schema instance used as the service identifier.
+     * @returns The resolved service or `undefined`.
+     */
+    getOptional<TSchema extends SchemaBuilder<any, any, any, any, any>>(schema: TSchema): InferType<TSchema> | undefined;
+    /**
+     * Resolves the dependencies described by a {@link FunctionSchemaBuilder}
+     * and calls `implementation` with the resolved values. Scoped services
+     * are resolved within this scope.
+     *
+     * @param funcSchema - A {@link FunctionSchemaBuilder} whose parameters
+     *   describe the services to inject.
+     * @param implementation - A function whose parameters match the
+     *   `funcSchema` parameter types.
+     * @returns The return value of `implementation`.
+     *
+     * @example
+     * ```ts
+     * using scope = provider.createScope();
+     * const result = scope.serviceProvider.invoke(handler, (logger, db) => {
+     *     logger.info('Handling request');
+     *     return db.query('SELECT 1');
+     * });
+     * ```
+     *
+     * @see {@link ServiceProvider.invoke}
+     */
+    invoke<TFuncSchema extends FunctionSchemaBuilder<any, any, any, any, any, any>>(funcSchema: TFuncSchema, implementation: InferType<TFuncSchema>): ReturnType<InferType<TFuncSchema>>;
+    /**
+     * Internal resolution entry point that reuses an existing resolution
+     * stack. Called by {@link ScopedResolverProxy} to propagate the stack
+     * across factory-to-factory calls, enabling circular dependency
+     * detection across the full chain.
+     *
+     * @hidden
+     */
+    resolveWithStack(schema: SchemaBuilder<any, any, any, any, any>, resolutionStack: Set<SchemaBuilder<any, any, any, any, any>>): any;
+}

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @cleverbrush/di — .NET-style dependency injection for TypeScript.
+ *
+ * Uses `@cleverbrush/schema` instances as service keys for type-safe
+ * registration and resolution. Supports singleton, scoped, and transient
+ * lifetimes, function injection via {@link FunctionSchemaBuilder}, and
+ * automatic disposal of scoped services.
+ *
+ * @example Quick start
+ * ```ts
+ * import { ServiceCollection } from '@cleverbrush/di';
+ * import { object, string, number, func } from '@cleverbrush/schema';
+ *
+ * // Define service contracts as schemas
+ * const IConfig = object({ port: number(), host: string() });
+ * const ILogger = object({ info: func().addParameter(string()) });
+ *
+ * // Register services
+ * const services = new ServiceCollection();
+ * services.addSingleton(IConfig, { port: 3000, host: 'localhost' });
+ * services.addSingleton(ILogger, () => ({ info: console.log }));
+ *
+ * // Build the provider
+ * const provider = services.buildServiceProvider();
+ *
+ * // Resolve — fully typed, no generics needed
+ * const config = provider.get(IConfig);
+ * config.port; // number
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { ServiceCollection, type ServiceProviderOptions } from './ServiceCollection.js';
+export { ServiceProvider } from './ServiceProvider.js';
+export { ScopedServiceProvider, ServiceScope } from './ServiceScope.js';
+export { type IServiceProvider, isAsyncDisposable, isDisposable, type ServiceDescriptor, type ServiceFactory, ServiceLifetime, type ServiceRegistrationOptions } from './types.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+var l=(a=>(a.Transient="Transient",a.Scoped="Scoped",a.Singleton="Singleton",a))(l||{});function s(y){return y!=null&&typeof y=="object"&&Symbol.dispose in y&&typeof y[Symbol.dispose]=="function"}function d(y){return y!=null&&typeof y=="object"&&Symbol.asyncDispose in y&&typeof y[Symbol.asyncDispose]=="function"}var o=class{#e;#n;#r=new Map;#a=[];#i=!1;serviceProvider;constructor(e,n){this.#e=e,this.#n=n,this.serviceProvider=new S(this)}dispose(){if(this.#i)return;this.#i=!0;let e;for(let n=this.#a.length-1;n>=0;n--){let a=this.#a[n];try{s(a)&&a[Symbol.dispose]()}catch(r){e||(e=r)}}if(this.#r.clear(),e)throw e}async asyncDispose(){if(this.#i)return;this.#i=!0;let e;for(let n=this.#a.length-1;n>=0;n--){let a=this.#a[n];try{d(a)?await a[Symbol.asyncDispose]():s(a)&&a[Symbol.dispose]()}catch(r){e||(e=r)}}if(this.#r.clear(),e)throw e}[Symbol.dispose](){this.dispose()}async[Symbol.asyncDispose](){await this.asyncDispose()}getDescriptors(){return this.#e}getSingletonCache(){return this.#n}getScopedCache(){return this.#r}trackDisposable(e){(s(e)||d(e))&&this.#a.push(e)}},S=class{#e;constructor(e){this.#e=e}get(e){return this.#n(e,new Set)}getOptional(e){if(this.#e.getDescriptors().has(e))return this.#n(e,new Set)}invoke(e,n){let a=e.introspect().parameters,r=new Set,i=a.map(t=>this.#n(t,r));return n.apply(null,i)}#n(e,n){let r=this.#e.getDescriptors().get(e);if(!r)throw new Error("Service not registered. The schema passed to get() was not registered in the ServiceCollection. Ensure you are using the same schema reference for registration and resolution.");if(n.has(e)){let i=[...n].map(t=>t.introspect().type??"(anonymous)").join(" \u2192 ");throw new Error(`Circular dependency detected: ${i} \u2192 ${r.schema.introspect().type??"(anonymous)"}`)}switch(r.lifetime){case"Singleton":{let i=this.#e.getSingletonCache();if(i.has(e))return i.get(e);n.add(e);let t=this.#r(r,n);return n.delete(e),i.set(e,t),t}case"Scoped":{let i=this.#e.getScopedCache();if(i.has(e))return i.get(e);n.add(e);let t=this.#r(r,n);return n.delete(e),i.set(e,t),this.#e.trackDisposable(t),t}case"Transient":{n.add(e);let i=this.#r(r,n);return n.delete(e),i}}}resolveWithStack(e,n){return this.#n(e,n)}#r(e,n){let a=new u(this,n),r=e.factory(a);if(e.validate){let i=e.schema.validate(r);if(!i.valid){let t=i.errors?.map(c=>c.message).join("; ")??"unknown error";throw new Error(`Service validation failed for schema type "${e.schema.introspect().type??"(anonymous)"}": ${t}`)}}return r}},u=class{#e;#n;constructor(e,n){this.#e=e,this.#n=n}get(e){return this.#e.resolveWithStack(e,this.#n)}getOptional(e){return this.#e.getOptional(e)}};var h=class{#e;#n=new Map;#r;constructor(e,n){this.#e=e,this.#r=n?.validateScopes??!0}get(e){return this.#a(e,new Set)}getOptional(e){if(this.#e.has(e))return this.#a(e,new Set)}createScope(){return new o(this.#e,this.#n)}invoke(e,n){let a=e.introspect().parameters,r=new Set,i=a.map(t=>this.#a(t,r));return n.apply(null,i)}#a(e,n,a,r){let i=this.#e.get(e);if(!i)throw new Error("Service not registered. The schema passed to get() was not registered in the ServiceCollection. Ensure you are using the same schema reference for registration and resolution.");if(n.has(e)){let t=[...n].map(c=>c.introspect().type??"(anonymous)").join(" \u2192 ");throw new Error(`Circular dependency detected: ${t} \u2192 ${i.schema.introspect().type??"(anonymous)"}`)}switch(i.lifetime){case"Singleton":{if(this.#n.has(e))return this.#n.get(e);n.add(e);let t=this.#i(i,n,a,r);return n.delete(e),this.#n.set(e,t),t}case"Scoped":{if(!a){if(this.#r)throw new Error("Cannot resolve scoped service from the root provider. Create a scope first with provider.createScope(). If this is intentional, set validateScopes: false in buildServiceProvider() options.");n.add(e);let c=this.#i(i,n,a,r);return n.delete(e),c}if(a.has(e))return a.get(e);n.add(e);let t=this.#i(i,n,a,r);return n.delete(e),a.set(e,t),r&&r(t),t}case"Transient":{n.add(e);let t=this.#i(i,n,a,r);return n.delete(e),t}}}#i(e,n,a,r){let i=new T(this,n,a,r),t=e.factory(i);if(e.validate){let c=e.schema.validate(t);if(!c.valid){let p=c.errors?.map(m=>m.message).join("; ")??"unknown error";throw new Error(`Service validation failed for schema type "${e.schema.introspect().type??"(anonymous)"}": ${p}`)}}return t}resolveScoped(e,n,a,r){return this.#a(e,n,a,r)}},T=class{#e;#n;#r;#a;constructor(e,n,a,r){this.#e=e,this.#n=n,this.#r=a,this.#a=r}get(e){return this.#e.resolveScoped(e,this.#n,this.#r??new Map,this.#a??(()=>{}))}getOptional(e){try{return this.get(e)}catch{return}}};var v=class{#e=new Map;addSingleton(e,n,a){return this.#n(e,"Singleton",n,a)}addScoped(e,n,a){return this.#n(e,"Scoped",n,a)}addTransient(e,n,a){return this.#n(e,"Transient",n,a)}addSingletonInstance(e,n,a){return this.#r(e,n,a)}addSingletonFromSchema(e,n,a,r){return this.#a(e,n,a,"Singleton",r)}addScopedFromSchema(e,n,a,r){return this.#a(e,n,a,"Scoped",r)}addTransientFromSchema(e,n,a,r){return this.#a(e,n,a,"Transient",r)}buildServiceProvider(e){let n=new Map(this.#e);return new h(n,e)}#n(e,n,a,r){let i=typeof a=="function"?a:()=>a;return this.#e.set(e,{schema:e,lifetime:n,factory:i,validate:r?.validate??!1}),this}#r(e,n,a){let r=()=>n;return this.#e.set(e,{schema:e,lifetime:"Singleton",factory:r,validate:a?.validate??!1}),this}#a(e,n,a,r,i){let t=n.introspect().parameters,c=p=>{let m=t.map(f=>p.get(f));return a.apply(null,m)};return this.#e.set(e,{schema:e,lifetime:r,factory:c,validate:i?.validate??!1}),this}};export{S as ScopedServiceProvider,v as ServiceCollection,l as ServiceLifetime,h as ServiceProvider,o as ServiceScope,d as isAsyncDisposable,s as isDisposable};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts","../src/ServiceScope.ts","../src/ServiceProvider.ts","../src/ServiceCollection.ts"],"sourcesContent":["import type { InferType, SchemaBuilder } from '@cleverbrush/schema';\n\n/**\n * Defines the lifetime of a service within the dependency injection container.\n *\n * The lifetime determines when a new instance is created versus when a cached\n * instance is returned.\n *\n * @example\n * ```ts\n * import { ServiceCollection, ServiceLifetime } from '@cleverbrush/di';\n * import { object, string } from '@cleverbrush/schema';\n *\n * const ILogger = object({ info: func() });\n *\n * const services = new ServiceCollection();\n * // Equivalent to services.addSingleton(ILogger, ...)\n * services.add(ILogger, () => console, ServiceLifetime.Singleton);\n * ```\n *\n * @see {@link ServiceCollection}\n */\nexport enum ServiceLifetime {\n    /**\n     * A new instance is created every time the service is resolved.\n     *\n     * Use for lightweight, stateless services.\n     */\n    Transient = 'Transient',\n\n    /**\n     * One instance is created per {@link ServiceScope}. The same instance is\n     * returned for every resolution within that scope.\n     *\n     * Use for services that should be shared within a single unit of work\n     * (e.g. an HTTP request) but isolated between units.\n     */\n    Scoped = 'Scoped',\n\n    /**\n     * One instance is created for the entire lifetime of the\n     * {@link ServiceProvider}. All subsequent resolutions return the same instance.\n     *\n     * Use for expensive-to-create or truly global services (loggers,\n     * configuration, connection pools).\n     */\n    Singleton = 'Singleton'\n}\n\n/**\n * A factory function that creates a service instance, optionally resolving\n * other services from the provided {@link ServiceProvider}.\n *\n * @typeParam T - The type of the service instance the factory creates.\n *\n * @example\n * ```ts\n * const loggerFactory: ServiceFactory<Logger> = (provider) => {\n *     const config = provider.get(IConfig);\n *     return new Logger(config.logLevel);\n * };\n * ```\n *\n * @see {@link ServiceCollection}\n */\nexport type ServiceFactory<T> = (provider: IServiceProvider) => T;\n\n/**\n * Describes a registered service: its schema key, lifetime, factory, and\n * optional runtime validation flag.\n *\n * @typeParam T - The type of the service instance.\n *\n * @see {@link ServiceCollection}\n * @see {@link ServiceLifetime}\n */\nexport interface ServiceDescriptor<T = any> {\n    /** The schema used as the service identifier (reference equality). */\n    readonly schema: SchemaBuilder<T, any, any, any, any>;\n\n    /** The lifetime of the service. */\n    readonly lifetime: ServiceLifetime;\n\n    /** The factory function that creates the service instance. */\n    readonly factory: ServiceFactory<T>;\n\n    /**\n     * When `true`, the container validates the factory's return value against\n     * the schema at resolution time using `schema.validate()`.\n     *\n     * @defaultValue `false`\n     */\n    readonly validate: boolean;\n}\n\n/**\n * Options for service registration.\n *\n * @see {@link ServiceCollection.addSingleton}\n * @see {@link ServiceCollection.addScoped}\n * @see {@link ServiceCollection.addTransient}\n */\nexport interface ServiceRegistrationOptions {\n    /**\n     * When `true`, the resolved value is validated against the schema at\n     * resolution time. Useful for development/debugging. Has a performance\n     * cost proportional to the schema complexity.\n     *\n     * @defaultValue `false`\n     */\n    validate?: boolean;\n}\n\n/**\n * Minimal interface for the service provider, used to avoid circular\n * dependencies between modules.\n *\n * @see {@link ServiceProvider}\n */\nexport interface IServiceProvider {\n    /**\n     * Resolves a service by its schema key.\n     * @param schema - The schema instance used as the service identifier.\n     * @throws If the service is not registered.\n     */\n    get<TSchema extends SchemaBuilder<any, any, any, any, any>>(\n        schema: TSchema\n    ): InferType<TSchema>;\n\n    /**\n     * Resolves a service by its schema key, or returns `undefined` if not registered.\n     * @param schema - The schema instance used as the service identifier.\n     */\n    getOptional<TSchema extends SchemaBuilder<any, any, any, any, any>>(\n        schema: TSchema\n    ): InferType<TSchema> | undefined;\n}\n\n/**\n * Checks whether a value implements the synchronous `Disposable` protocol\n * (`Symbol.dispose`).\n *\n * @param value - The value to check.\n * @returns `true` if `value` has a `Symbol.dispose` method.\n *\n * @example\n * ```ts\n * const resource = {\n *     [Symbol.dispose]() { console.log('disposed'); }\n * };\n * isDisposable(resource); // true\n * isDisposable({});       // false\n * ```\n */\nexport function isDisposable(value: unknown): value is Disposable {\n    return (\n        value != null &&\n        typeof value === 'object' &&\n        Symbol.dispose in (value as object) &&\n        typeof (value as Record<symbol, unknown>)[Symbol.dispose] === 'function'\n    );\n}\n\n/**\n * Checks whether a value implements the asynchronous `Disposable` protocol\n * (`Symbol.asyncDispose`).\n *\n * @param value - The value to check.\n * @returns `true` if `value` has a `Symbol.asyncDispose` method.\n *\n * @example\n * ```ts\n * const connection = {\n *     async [Symbol.asyncDispose]() { await db.close(); }\n * };\n * isAsyncDisposable(connection); // true\n * isAsyncDisposable({});         // false\n * ```\n */\nexport function isAsyncDisposable(value: unknown): value is AsyncDisposable {\n    return (\n        value != null &&\n        typeof value === 'object' &&\n        Symbol.asyncDispose in (value as object) &&\n        typeof (value as Record<symbol, unknown>)[Symbol.asyncDispose] ===\n            'function'\n    );\n}\n","import type {\n    FunctionSchemaBuilder,\n    InferType,\n    SchemaBuilder\n} from '@cleverbrush/schema';\nimport type { ServiceProvider } from './ServiceProvider.js';\nimport type { IServiceProvider, ServiceDescriptor } from './types.js';\nimport { isAsyncDisposable, isDisposable, ServiceLifetime } from './types.js';\n\n/**\n * A scoped service container that caches {@link ServiceLifetime.Scoped | Scoped}\n * services for the duration of its lifetime. Obtain instances via\n * {@link ServiceProvider.createScope}.\n *\n * The scope tracks all created scoped services that implement `Disposable` or\n * `AsyncDisposable` and disposes them in reverse creation order (LIFO) when the\n * scope is disposed. This matches .NET's scope disposal semantics.\n *\n * Supports the `using` keyword via `Symbol.dispose` and `Symbol.asyncDispose`:\n *\n * @example Synchronous disposal\n * ```ts\n * using scope = provider.createScope();\n * const db = scope.serviceProvider.get(IDbContext);\n * // db is automatically disposed when the block exits\n * ```\n *\n * @example Asynchronous disposal\n * ```ts\n * await using scope = provider.createScope();\n * const db = scope.serviceProvider.get(IDbContext);\n * // db is asynchronously disposed when the block exits\n * ```\n *\n * @example Manual disposal\n * ```ts\n * const scope = provider.createScope();\n * try {\n *     const db = scope.serviceProvider.get(IDbContext);\n *     // use db...\n * } finally {\n *     await scope.asyncDispose();\n * }\n * ```\n *\n * @see {@link ServiceProvider.createScope}\n * @see {@link ServiceLifetime.Scoped}\n */\nexport class ServiceScope implements Disposable, AsyncDisposable {\n    readonly #descriptors: Map<\n        SchemaBuilder<any, any, any, any, any>,\n        ServiceDescriptor\n    >;\n    readonly #singletonCache: Map<SchemaBuilder<any, any, any, any, any>, any>;\n    readonly #scopedCache: Map<SchemaBuilder<any, any, any, any, any>, any> =\n        new Map();\n    readonly #disposables: any[] = [];\n    #disposed = false;\n\n    /**\n     * A child {@link IServiceProvider} that resolves services within this scope.\n     *\n     * - **Singleton** services are resolved from the root provider's cache.\n     * - **Scoped** services are resolved from this scope's cache (created on\n     *   first access, reused within the scope).\n     * - **Transient** services create a new instance on every call.\n     *\n     * @example\n     * ```ts\n     * const scope = provider.createScope();\n     * const db = scope.serviceProvider.get(IDbContext); // scoped\n     * const logger = scope.serviceProvider.get(ILogger); // singleton from root\n     * ```\n     */\n    public readonly serviceProvider: ScopedServiceProvider;\n\n    /**\n     * @hidden\n     */\n    constructor(\n        descriptors: Map<\n            SchemaBuilder<any, any, any, any, any>,\n            ServiceDescriptor\n        >,\n        singletonCache: Map<SchemaBuilder<any, any, any, any, any>, any>\n    ) {\n        this.#descriptors = descriptors;\n        this.#singletonCache = singletonCache;\n        this.serviceProvider = new ScopedServiceProvider(this);\n    }\n\n    /**\n     * Synchronously disposes all scoped services that implement\n     * `Symbol.dispose`, in reverse creation order (LIFO).\n     *\n     * Services that only implement `Symbol.asyncDispose` are skipped during\n     * synchronous disposal. Use {@link asyncDispose} to properly dispose all\n     * services including async ones.\n     *\n     * @throws Re-throws the first error encountered during disposal, but\n     *   still attempts to dispose remaining services.\n     */\n    public dispose(): void {\n        if (this.#disposed) return;\n        this.#disposed = true;\n\n        let firstError: unknown;\n\n        // Dispose in reverse order (LIFO)\n        for (let i = this.#disposables.length - 1; i >= 0; i--) {\n            const instance = this.#disposables[i];\n            try {\n                if (isDisposable(instance)) {\n                    instance[Symbol.dispose]();\n                }\n                // async-only disposables are skipped during sync disposal —\n                // use asyncDispose() to properly clean up async resources.\n            } catch (err) {\n                if (!firstError) firstError = err;\n            }\n        }\n\n        this.#scopedCache.clear();\n\n        if (firstError) throw firstError;\n    }\n\n    /**\n     * Asynchronously disposes all scoped services that implement\n     * `Symbol.asyncDispose` or `Symbol.dispose`, in reverse creation order\n     * (LIFO).\n     *\n     * For each service:\n     * - If it implements `Symbol.asyncDispose`, that method is awaited.\n     * - Otherwise, if it implements `Symbol.dispose`, that method is called\n     *   synchronously.\n     *\n     * @throws Re-throws the first error encountered during disposal, but\n     *   still attempts to dispose remaining services.\n     */\n    public async asyncDispose(): Promise<void> {\n        if (this.#disposed) return;\n        this.#disposed = true;\n\n        let firstError: unknown;\n\n        // Dispose in reverse order (LIFO)\n        for (let i = this.#disposables.length - 1; i >= 0; i--) {\n            const instance = this.#disposables[i];\n            try {\n                if (isAsyncDisposable(instance)) {\n                    await instance[Symbol.asyncDispose]();\n                } else if (isDisposable(instance)) {\n                    instance[Symbol.dispose]();\n                }\n            } catch (err) {\n                if (!firstError) firstError = err;\n            }\n        }\n\n        this.#scopedCache.clear();\n\n        if (firstError) throw firstError;\n    }\n\n    /**\n     * Implements the synchronous `Disposable` protocol. Delegates to\n     * {@link dispose}.\n     *\n     * @example\n     * ```ts\n     * using scope = provider.createScope();\n     * ```\n     */\n    [Symbol.dispose](): void {\n        this.dispose();\n    }\n\n    /**\n     * Implements the asynchronous `AsyncDisposable` protocol. Delegates to\n     * {@link asyncDispose}.\n     *\n     * @example\n     * ```ts\n     * await using scope = provider.createScope();\n     * ```\n     */\n    async [Symbol.asyncDispose](): Promise<void> {\n        await this.asyncDispose();\n    }\n\n    /**\n     * @hidden\n     */\n    getDescriptors(): Map<\n        SchemaBuilder<any, any, any, any, any>,\n        ServiceDescriptor\n    > {\n        return this.#descriptors;\n    }\n\n    /**\n     * @hidden\n     */\n    getSingletonCache(): Map<SchemaBuilder<any, any, any, any, any>, any> {\n        return this.#singletonCache;\n    }\n\n    /**\n     * @hidden\n     */\n    getScopedCache(): Map<SchemaBuilder<any, any, any, any, any>, any> {\n        return this.#scopedCache;\n    }\n\n    /**\n     * @hidden\n     */\n    trackDisposable(instance: any): void {\n        if (isDisposable(instance) || isAsyncDisposable(instance)) {\n            this.#disposables.push(instance);\n        }\n    }\n}\n\n/**\n * A service provider scoped to a {@link ServiceScope}. Resolves scoped\n * services from the scope's cache and singletons from the root cache.\n *\n * This class is not instantiated directly — obtain it via\n * `scope.serviceProvider`.\n *\n * @see {@link ServiceScope}\n */\nexport class ScopedServiceProvider implements IServiceProvider {\n    readonly #scope: ServiceScope;\n\n    /**\n     * @hidden\n     */\n    constructor(scope: ServiceScope) {\n        this.#scope = scope;\n    }\n\n    /**\n     * Resolves a service within this scope.\n     *\n     * - **Singleton** services are resolved from the root provider's cache.\n     * - **Scoped** services are created once per scope and cached.\n     * - **Transient** services are created fresh on every call.\n     *\n     * @param schema - The schema instance used as the service identifier.\n     * @returns The resolved service, typed as `InferType<typeof schema>`.\n     * @throws {Error} If the schema is not registered.\n     * @throws {Error} If a circular dependency is detected.\n     *\n     * @example\n     * ```ts\n     * using scope = provider.createScope();\n     * const db = scope.serviceProvider.get(IDbContext);\n     * ```\n     */\n    public get<TSchema extends SchemaBuilder<any, any, any, any, any>>(\n        schema: TSchema\n    ): InferType<TSchema> {\n        return this.#resolve(schema, new Set());\n    }\n\n    /**\n     * Resolves a service within this scope, or returns `undefined` if not\n     * registered.\n     *\n     * @param schema - The schema instance used as the service identifier.\n     * @returns The resolved service or `undefined`.\n     */\n    public getOptional<TSchema extends SchemaBuilder<any, any, any, any, any>>(\n        schema: TSchema\n    ): InferType<TSchema> | undefined {\n        if (!this.#scope.getDescriptors().has(schema)) {\n            return undefined;\n        }\n        return this.#resolve(schema, new Set());\n    }\n\n    /**\n     * Resolves the dependencies described by a {@link FunctionSchemaBuilder}\n     * and calls `implementation` with the resolved values. Scoped services\n     * are resolved within this scope.\n     *\n     * @param funcSchema - A {@link FunctionSchemaBuilder} whose parameters\n     *   describe the services to inject.\n     * @param implementation - A function whose parameters match the\n     *   `funcSchema` parameter types.\n     * @returns The return value of `implementation`.\n     *\n     * @example\n     * ```ts\n     * using scope = provider.createScope();\n     * const result = scope.serviceProvider.invoke(handler, (logger, db) => {\n     *     logger.info('Handling request');\n     *     return db.query('SELECT 1');\n     * });\n     * ```\n     *\n     * @see {@link ServiceProvider.invoke}\n     */\n    public invoke<\n        TFuncSchema extends FunctionSchemaBuilder<any, any, any, any, any, any>\n    >(\n        funcSchema: TFuncSchema,\n        implementation: InferType<TFuncSchema>\n    ): ReturnType<InferType<TFuncSchema>> {\n        const parameterSchemas = funcSchema.introspect().parameters;\n        const resolutionStack = new Set<\n            SchemaBuilder<any, any, any, any, any>\n        >();\n        const args = parameterSchemas.map(paramSchema =>\n            this.#resolve(paramSchema, resolutionStack)\n        );\n        return (implementation as Function).apply(null, args);\n    }\n\n    #resolve(\n        schema: SchemaBuilder<any, any, any, any, any>,\n        resolutionStack: Set<SchemaBuilder<any, any, any, any, any>>\n    ): any {\n        const descriptors = this.#scope.getDescriptors();\n        const descriptor = descriptors.get(schema);\n        if (!descriptor) {\n            throw new Error(\n                `Service not registered. The schema passed to get() was not ` +\n                    `registered in the ServiceCollection. Ensure you are ` +\n                    `using the same schema reference for registration and ` +\n                    `resolution.`\n            );\n        }\n\n        // Circular dependency detection\n        if (resolutionStack.has(schema)) {\n            const chain = [...resolutionStack]\n                .map(s => s.introspect().type ?? '(anonymous)')\n                .join(' → ');\n            throw new Error(\n                `Circular dependency detected: ${chain} → ${descriptor.schema.introspect().type ?? '(anonymous)'}`\n            );\n        }\n\n        switch (descriptor.lifetime) {\n            case ServiceLifetime.Singleton: {\n                const singletonCache = this.#scope.getSingletonCache();\n                if (singletonCache.has(schema)) {\n                    return singletonCache.get(schema);\n                }\n                resolutionStack.add(schema);\n                const instance = this.#createAndValidate(\n                    descriptor,\n                    resolutionStack\n                );\n                resolutionStack.delete(schema);\n                singletonCache.set(schema, instance);\n                return instance;\n            }\n\n            case ServiceLifetime.Scoped: {\n                const scopedCache = this.#scope.getScopedCache();\n                if (scopedCache.has(schema)) {\n                    return scopedCache.get(schema);\n                }\n                resolutionStack.add(schema);\n                const instance = this.#createAndValidate(\n                    descriptor,\n                    resolutionStack\n                );\n                resolutionStack.delete(schema);\n                scopedCache.set(schema, instance);\n                this.#scope.trackDisposable(instance);\n                return instance;\n            }\n\n            case ServiceLifetime.Transient: {\n                resolutionStack.add(schema);\n                const instance = this.#createAndValidate(\n                    descriptor,\n                    resolutionStack\n                );\n                resolutionStack.delete(schema);\n                return instance;\n            }\n        }\n    }\n\n    /**\n     * Internal resolution entry point that reuses an existing resolution\n     * stack. Called by {@link ScopedResolverProxy} to propagate the stack\n     * across factory-to-factory calls, enabling circular dependency\n     * detection across the full chain.\n     *\n     * @hidden\n     */\n    resolveWithStack(\n        schema: SchemaBuilder<any, any, any, any, any>,\n        resolutionStack: Set<SchemaBuilder<any, any, any, any, any>>\n    ): any {\n        return this.#resolve(schema, resolutionStack);\n    }\n\n    #createAndValidate(\n        descriptor: ServiceDescriptor,\n        resolutionStack: Set<SchemaBuilder<any, any, any, any, any>>\n    ): any {\n        const childProxy = new ScopedResolverProxy(this, resolutionStack);\n        const instance = descriptor.factory(childProxy);\n\n        if (descriptor.validate) {\n            const result = descriptor.schema.validate(instance);\n            if (!result.valid) {\n                const messages =\n                    result.errors?.map(e => e.message).join('; ') ??\n                    'unknown error';\n                throw new Error(\n                    `Service validation failed for schema type ` +\n                        `\"${descriptor.schema.introspect().type ?? '(anonymous)'}\": ${messages}`\n                );\n            }\n        }\n\n        return instance;\n    }\n}\n\n/**\n * Internal proxy used during factory invocation within a scope.\n * Routes resolution back through the ScopedServiceProvider with the current\n * resolution stack for circular dependency detection.\n *\n * @hidden\n */\nclass ScopedResolverProxy implements IServiceProvider {\n    readonly #provider: ScopedServiceProvider;\n    readonly #resolutionStack: Set<SchemaBuilder<any, any, any, any, any>>;\n\n    constructor(\n        provider: ScopedServiceProvider,\n        resolutionStack: Set<SchemaBuilder<any, any, any, any, any>>\n    ) {\n        this.#provider = provider;\n        this.#resolutionStack = resolutionStack;\n    }\n\n    get<TSchema extends SchemaBuilder<any, any, any, any, any>>(\n        schema: TSchema\n    ): InferType<TSchema> {\n        return this.#provider.resolveWithStack(schema, this.#resolutionStack);\n    }\n\n    getOptional<TSchema extends SchemaBuilder<any, any, any, any, any>>(\n        schema: TSchema\n    ): InferType<TSchema> | undefined {\n        return this.#provider.getOptional(schema);\n    }\n}\n","import type {\n    FunctionSchemaBuilder,\n    InferType,\n    SchemaBuilder\n} from '@cleverbrush/schema';\nimport type { ServiceProviderOptions } from './ServiceCollection.js';\nimport { ServiceScope } from './ServiceScope.js';\nimport type { IServiceProvider, ServiceDescriptor } from './types.js';\nimport { ServiceLifetime } from './types.js';\n\n/**\n * An immutable service provider that resolves services from a frozen set of\n * {@link ServiceDescriptor | descriptors}. Obtain an instance by calling\n * {@link ServiceCollection.buildServiceProvider}.\n *\n * Supports three service lifetimes:\n * - **Singleton** — one instance per provider, cached after first resolution.\n * - **Scoped** — one instance per {@link ServiceScope}, created via\n *   {@link createScope}.\n * - **Transient** — a new instance on every call to {@link get}.\n *\n * @example Resolving services\n * ```ts\n * const provider = services.buildServiceProvider();\n *\n * // Typed via the schema — no explicit generic needed\n * const config = provider.get(IConfig);\n * config.port; // number\n *\n * // Optional resolution (returns undefined if not registered)\n * const maybeMail = provider.getOptional(IMailer);\n * ```\n *\n * @example Using scopes\n * ```ts\n * // Per-request scope (e.g. in an HTTP handler)\n * using scope = provider.createScope();\n * const db = scope.serviceProvider.get(IDbContext);\n * // db is disposed when scope exits\n * ```\n *\n * @example Function injection\n * ```ts\n * const handlerSchema = func()\n *     .addParameter(ILogger)\n *     .addParameter(IDbContext)\n *     .hasReturnType(string());\n *\n * const result = provider.invoke(handlerSchema, (logger, db) => {\n *     logger.info('Handling request');\n *     return db.query('SELECT 1');\n * });\n * ```\n *\n * @see {@link ServiceCollection}\n * @see {@link ServiceScope}\n */\nexport class ServiceProvider implements IServiceProvider {\n    readonly #descriptors: Map<\n        SchemaBuilder<any, any, any, any, any>,\n        ServiceDescriptor\n    >;\n    readonly #singletonCache: Map<SchemaBuilder<any, any, any, any, any>, any> =\n        new Map();\n    readonly #validateScopes: boolean;\n\n    /**\n     * @hidden\n     */\n    constructor(\n        descriptors: Map<\n            SchemaBuilder<any, any, any, any, any>,\n            ServiceDescriptor\n        >,\n        options?: ServiceProviderOptions\n    ) {\n        this.#descriptors = descriptors;\n        this.#validateScopes = options?.validateScopes ?? true;\n    }\n\n    /**\n     * Resolves a service by its schema key.\n     *\n     * - **Singleton**: returns the cached instance, or creates and caches it.\n     * - **Scoped**: throws if called from the root provider when\n     *   `validateScopes` is `true` (default). Use\n     *   {@link createScope} to obtain a scoped provider.\n     * - **Transient**: creates a new instance on every call.\n     *\n     * @param schema - The schema instance used as the service identifier.\n     *   Must be the same reference used during registration.\n     * @returns The resolved service, typed as `InferType<typeof schema>`.\n     * @throws {Error} If the schema is not registered.\n     * @throws {Error} If a scoped service is resolved from the root provider\n     *   with `validateScopes` enabled.\n     * @throws {Error} If a circular dependency is detected.\n     *\n     * @example\n     * ```ts\n     * const logger = provider.get(ILogger);\n     * logger.info('Hello'); // fully typed\n     * ```\n     */\n    public get<TSchema extends SchemaBuilder<any, any, any, any, any>>(\n        schema: TSchema\n    ): InferType<TSchema> {\n        return this.#resolve(schema, new Set());\n    }\n\n    /**\n     * Resolves a service by its schema key, or returns `undefined` if the\n     * schema is not registered.\n     *\n     * Unlike {@link get}, this method does **not** throw for unregistered\n     * schemas. All other behaviour (lifetime, scope validation, circular\n     * dependency detection) is the same.\n     *\n     * @param schema - The schema instance used as the service identifier.\n     * @returns The resolved service or `undefined`.\n     *\n     * @example\n     * ```ts\n     * const mailer = provider.getOptional(IMailer);\n     * if (mailer) {\n     *     mailer.send('test@example.com', 'Hello');\n     * }\n     * ```\n     */\n    public getOptional<TSchema extends SchemaBuilder<any, any, any, any, any>>(\n        schema: TSchema\n    ): InferType<TSchema> | undefined {\n        if (!this.#descriptors.has(schema)) {\n            return undefined;\n        }\n        return this.#resolve(schema, new Set());\n    }\n\n    /**\n     * Creates a new {@link ServiceScope}. Scoped services resolved from the\n     * scope's {@link ServiceScope.serviceProvider | serviceProvider} are\n     * cached per-scope and disposed when the scope is disposed.\n     *\n     * The returned scope implements both `Symbol.dispose` and\n     * `Symbol.asyncDispose`, so it works with the `using` keyword:\n     *\n     * @returns A new {@link ServiceScope}.\n     *\n     * @example\n     * ```ts\n     * // Sync disposal\n     * using scope = provider.createScope();\n     * const db = scope.serviceProvider.get(IDbContext);\n     *\n     * // Async disposal\n     * await using scope = provider.createScope();\n     * const db = scope.serviceProvider.get(IDbContext);\n     * ```\n     */\n    public createScope(): ServiceScope {\n        return new ServiceScope(this.#descriptors, this.#singletonCache);\n    }\n\n    /**\n     * Resolves the dependencies described by a {@link FunctionSchemaBuilder}\n     * and calls `implementation` with the resolved values.\n     *\n     * Each parameter schema in `funcSchema.introspect().parameters` is\n     * resolved from this provider. The implementation receives the resolved\n     * values in the same order as the parameter schemas.\n     *\n     * @param funcSchema - A {@link FunctionSchemaBuilder} whose parameters\n     *   describe the services to inject.\n     * @param implementation - A function whose parameters match the\n     *   `funcSchema` parameter types and whose return type matches the\n     *   `funcSchema` return type.\n     * @returns The return value of `implementation`.\n     *\n     * @example\n     * ```ts\n     * const handler = func()\n     *     .addParameter(ILogger)\n     *     .addParameter(IConfig)\n     *     .hasReturnType(string());\n     *\n     * const result = provider.invoke(handler, (logger, config) => {\n     *     logger.info(`Running on port ${config.port}`);\n     *     return 'ok';\n     * });\n     * // result: string\n     * ```\n     *\n     * @see {@link FunctionSchemaBuilder.addParameter}\n     * @see {@link FunctionSchemaBuilder.hasReturnType}\n     */\n    public invoke<\n        TFuncSchema extends FunctionSchemaBuilder<any, any, any, any, any, any>\n    >(\n        funcSchema: TFuncSchema,\n        implementation: InferType<TFuncSchema>\n    ): ReturnType<InferType<TFuncSchema>> {\n        const parameterSchemas = funcSchema.introspect().parameters;\n        const resolutionStack = new Set<\n            SchemaBuilder<any, any, any, any, any>\n        >();\n        const args = parameterSchemas.map(paramSchema =>\n            this.#resolve(paramSchema, resolutionStack)\n        );\n        return (implementation as Function).apply(null, args);\n    }\n\n    /**\n     * Internal resolution method shared between root and scoped providers.\n     * Handles singleton caching and transient creation. Scoped resolution is\n     * handled by {@link ScopedServiceProvider}.\n     *\n     * @hidden\n     */\n    #resolve(\n        schema: SchemaBuilder<any, any, any, any, any>,\n        resolutionStack: Set<SchemaBuilder<any, any, any, any, any>>,\n        scopedCache?: Map<SchemaBuilder<any, any, any, any, any>, any>,\n        trackDisposable?: (instance: any) => void\n    ): any {\n        const descriptor = this.#descriptors.get(schema);\n        if (!descriptor) {\n            throw new Error(\n                `Service not registered. The schema passed to get() was not ` +\n                    `registered in the ServiceCollection. Ensure you are ` +\n                    `using the same schema reference for registration and ` +\n                    `resolution.`\n            );\n        }\n\n        // Circular dependency detection\n        if (resolutionStack.has(schema)) {\n            const chain = [...resolutionStack]\n                .map(s => s.introspect().type ?? '(anonymous)')\n                .join(' → ');\n            throw new Error(\n                `Circular dependency detected: ${chain} → ${descriptor.schema.introspect().type ?? '(anonymous)'}`\n            );\n        }\n\n        switch (descriptor.lifetime) {\n            case ServiceLifetime.Singleton: {\n                if (this.#singletonCache.has(schema)) {\n                    return this.#singletonCache.get(schema);\n                }\n                resolutionStack.add(schema);\n                const instance = this.#createAndValidate(\n                    descriptor,\n                    resolutionStack,\n                    scopedCache,\n                    trackDisposable\n                );\n                resolutionStack.delete(schema);\n                this.#singletonCache.set(schema, instance);\n                return instance;\n            }\n\n            case ServiceLifetime.Scoped: {\n                if (!scopedCache) {\n                    if (this.#validateScopes) {\n                        throw new Error(\n                            `Cannot resolve scoped service from the root ` +\n                                `provider. Create a scope first with ` +\n                                `provider.createScope(). If this is ` +\n                                `intentional, set validateScopes: false in ` +\n                                `buildServiceProvider() options.`\n                        );\n                    }\n                    // If validateScopes is false, treat as transient from root\n                    resolutionStack.add(schema);\n                    const instance = this.#createAndValidate(\n                        descriptor,\n                        resolutionStack,\n                        scopedCache,\n                        trackDisposable\n                    );\n                    resolutionStack.delete(schema);\n                    return instance;\n                }\n                if (scopedCache.has(schema)) {\n                    return scopedCache.get(schema);\n                }\n                resolutionStack.add(schema);\n                const instance = this.#createAndValidate(\n                    descriptor,\n                    resolutionStack,\n                    scopedCache,\n                    trackDisposable\n                );\n                resolutionStack.delete(schema);\n                scopedCache.set(schema, instance);\n                if (trackDisposable) {\n                    trackDisposable(instance);\n                }\n                return instance;\n            }\n\n            case ServiceLifetime.Transient: {\n                resolutionStack.add(schema);\n                const instance = this.#createAndValidate(\n                    descriptor,\n                    resolutionStack,\n                    scopedCache,\n                    trackDisposable\n                );\n                resolutionStack.delete(schema);\n                return instance;\n            }\n        }\n    }\n\n    #createAndValidate(\n        descriptor: ServiceDescriptor,\n        resolutionStack: Set<SchemaBuilder<any, any, any, any, any>>,\n        scopedCache?: Map<SchemaBuilder<any, any, any, any, any>, any>,\n        trackDisposable?: (instance: any) => void\n    ): any {\n        const childProvider = new ScopedResolverProxy(\n            this,\n            resolutionStack,\n            scopedCache,\n            trackDisposable\n        );\n        const instance = descriptor.factory(childProvider);\n\n        if (descriptor.validate) {\n            const result = descriptor.schema.validate(instance);\n            if (!result.valid) {\n                const messages =\n                    result.errors?.map(e => e.message).join('; ') ??\n                    'unknown error';\n                throw new Error(\n                    `Service validation failed for schema type ` +\n                        `\"${descriptor.schema.introspect().type ?? '(anonymous)'}\": ${messages}`\n                );\n            }\n        }\n\n        return instance;\n    }\n\n    /**\n     * Resolves a service within a scope context. Called by\n     * {@link ScopedServiceProvider}.\n     *\n     * @hidden\n     */\n    resolveScoped(\n        schema: SchemaBuilder<any, any, any, any, any>,\n        resolutionStack: Set<SchemaBuilder<any, any, any, any, any>>,\n        scopedCache: Map<SchemaBuilder<any, any, any, any, any>, any>,\n        trackDisposable: (instance: any) => void\n    ): any {\n        return this.#resolve(\n            schema,\n            resolutionStack,\n            scopedCache,\n            trackDisposable\n        );\n    }\n}\n\n/**\n * Internal proxy used during factory invocation to enable factories to resolve\n * other services. Routes resolution back through the ServiceProvider with the\n * current resolution stack for circular dependency detection.\n *\n * @hidden\n */\nclass ScopedResolverProxy implements IServiceProvider {\n    readonly #provider: ServiceProvider;\n    readonly #resolutionStack: Set<SchemaBuilder<any, any, any, any, any>>;\n    readonly #scopedCache?: Map<SchemaBuilder<any, any, any, any, any>, any>;\n    readonly #trackDisposable?: (instance: any) => void;\n\n    constructor(\n        provider: ServiceProvider,\n        resolutionStack: Set<SchemaBuilder<any, any, any, any, any>>,\n        scopedCache?: Map<SchemaBuilder<any, any, any, any, any>, any>,\n        trackDisposable?: (instance: any) => void\n    ) {\n        this.#provider = provider;\n        this.#resolutionStack = resolutionStack;\n        this.#scopedCache = scopedCache;\n        this.#trackDisposable = trackDisposable;\n    }\n\n    get<TSchema extends SchemaBuilder<any, any, any, any, any>>(\n        schema: TSchema\n    ): InferType<TSchema> {\n        return this.#provider.resolveScoped(\n            schema,\n            this.#resolutionStack,\n            this.#scopedCache ?? new Map(),\n            this.#trackDisposable ?? (() => {})\n        );\n    }\n\n    getOptional<TSchema extends SchemaBuilder<any, any, any, any, any>>(\n        schema: TSchema\n    ): InferType<TSchema> | undefined {\n        try {\n            return this.get(schema);\n        } catch {\n            return undefined;\n        }\n    }\n}\n","import type {\n    FunctionSchemaBuilder,\n    InferType,\n    SchemaBuilder\n} from '@cleverbrush/schema';\nimport { ServiceProvider } from './ServiceProvider.js';\nimport type {\n    ServiceDescriptor,\n    ServiceFactory,\n    ServiceRegistrationOptions\n} from './types.js';\nimport { ServiceLifetime } from './types.js';\n\n/**\n * Options for building a {@link ServiceProvider} from a {@link ServiceCollection}.\n *\n * @see {@link ServiceCollection.buildServiceProvider}\n */\nexport interface ServiceProviderOptions {\n    /**\n     * When `true`, resolving a {@link ServiceLifetime.Scoped | Scoped} service\n     * from the root provider (outside of a scope) throws an error. This helps\n     * catch accidental singleton captures of scoped services.\n     *\n     * Recommended for development. Matches .NET's `ValidateScopes` behaviour.\n     *\n     * @defaultValue `true`\n     */\n    validateScopes?: boolean;\n}\n\n/**\n * A mutable collection of service registrations. Build up the collection by\n * calling {@link addSingleton}, {@link addScoped}, or {@link addTransient},\n * then call {@link buildServiceProvider} to create an immutable\n * {@link ServiceProvider}.\n *\n * Schema instances act as service keys via reference equality — the same\n * schema object used during registration must be used during resolution.\n *\n * @example Basic registration and resolution\n * ```ts\n * import { ServiceCollection } from '@cleverbrush/di';\n * import { object, string, number, func } from '@cleverbrush/schema';\n *\n * const IConfig = object({ port: number(), host: string() });\n * const ILogger = object({ info: func() });\n *\n * const services = new ServiceCollection();\n * services.addSingleton(IConfig, { port: 3000, host: 'localhost' });\n * services.addSingleton(ILogger, () => ({ info: console.log }));\n *\n * const provider = services.buildServiceProvider();\n * const config = provider.get(IConfig); // { port: number; host: string }\n * ```\n *\n * @example Function-schema-driven registration\n * ```ts\n * const IGreeter = object({ greet: func() });\n * const greeterFactory = func()\n *     .addParameter(IConfig)\n *     .addParameter(ILogger);\n *\n * services.addSingletonFromSchema(\n *     IGreeter,\n *     greeterFactory,\n *     (config, logger) => ({\n *         greet() { logger.info(`Hello from ${config.host}`); }\n *     })\n * );\n * ```\n *\n * @see {@link ServiceProvider}\n * @see {@link ServiceLifetime}\n */\nexport class ServiceCollection {\n    readonly #descriptors: Map<\n        SchemaBuilder<any, any, any, any, any>,\n        ServiceDescriptor\n    > = new Map();\n\n    /**\n     * Registers a service with {@link ServiceLifetime.Singleton | Singleton}\n     * lifetime. The factory (or value) is called at most once; every\n     * subsequent resolution returns the same instance.\n     *\n     * @param schema - The schema used as the service identifier.\n     * @param factoryOrValue - Either a {@link ServiceFactory} function that\n     *   receives the provider, or a plain value (which is wrapped in a\n     *   factory automatically).\n     * @param options - Optional {@link ServiceRegistrationOptions}.\n     * @returns `this` for chaining.\n     *\n     * @example Factory registration\n     * ```ts\n     * services.addSingleton(ILogger, (provider) => {\n     *     const config = provider.get(IConfig);\n     *     return new ConsoleLogger(config.logLevel);\n     * });\n     * ```\n     *\n     * @example Value shorthand\n     * ```ts\n     * services.addSingleton(IConfig, { port: 3000, host: 'localhost' });\n     * ```\n     *\n     * @see {@link addScoped}\n     * @see {@link addTransient}\n     */\n    public addSingleton<TSchema extends SchemaBuilder<any, any, any, any, any>>(\n        schema: TSchema,\n        factoryOrValue: ServiceFactory<InferType<TSchema>> | InferType<TSchema>,\n        options?: ServiceRegistrationOptions\n    ): this {\n        return this.#add(\n            schema,\n            ServiceLifetime.Singleton,\n            factoryOrValue,\n            options\n        );\n    }\n\n    /**\n     * Registers a service with {@link ServiceLifetime.Scoped | Scoped}\n     * lifetime. One instance is created per {@link ServiceScope}; within a\n     * scope every resolution returns the same instance.\n     *\n     * @param schema - The schema used as the service identifier.\n     * @param factory - A {@link ServiceFactory} function that creates the\n     *   service instance. Unlike {@link addSingleton}, a plain value is\n     *   **not** accepted because scoped services must be freshly created\n     *   per scope.\n     * @param options - Optional {@link ServiceRegistrationOptions}.\n     * @returns `this` for chaining.\n     *\n     * @example\n     * ```ts\n     * const IDbContext = object({ query: func() });\n     *\n     * services.addScoped(IDbContext, (provider) => {\n     *     const config = provider.get(IConfig);\n     *     return new DbContext(config.connectionString);\n     * });\n     * ```\n     *\n     * @see {@link addSingleton}\n     * @see {@link addTransient}\n     */\n    public addScoped<TSchema extends SchemaBuilder<any, any, any, any, any>>(\n        schema: TSchema,\n        factory: ServiceFactory<InferType<TSchema>>,\n        options?: ServiceRegistrationOptions\n    ): this {\n        return this.#add(schema, ServiceLifetime.Scoped, factory, options);\n    }\n\n    /**\n     * Registers a service with {@link ServiceLifetime.Transient | Transient}\n     * lifetime. A new instance is created on every resolution.\n     *\n     * @param schema - The schema used as the service identifier.\n     * @param factory - A {@link ServiceFactory} function that creates the\n     *   service instance.\n     * @param options - Optional {@link ServiceRegistrationOptions}.\n     * @returns `this` for chaining.\n     *\n     * @example\n     * ```ts\n     * const IRequestId = object({ id: string() });\n     *\n     * services.addTransient(IRequestId, () => ({\n     *     id: crypto.randomUUID()\n     * }));\n     * ```\n     *\n     * @see {@link addSingleton}\n     * @see {@link addScoped}\n     */\n    public addTransient<TSchema extends SchemaBuilder<any, any, any, any, any>>(\n        schema: TSchema,\n        factory: ServiceFactory<InferType<TSchema>>,\n        options?: ServiceRegistrationOptions\n    ): this {\n        return this.#add(schema, ServiceLifetime.Transient, factory, options);\n    }\n\n    /**\n     * Registers a pre-created instance as a {@link ServiceLifetime.Singleton | Singleton}.\n     * Unlike {@link addSingleton}, the second argument is always treated as the\n     * service value — never as a factory function. This makes it safe to\n     * register a function-typed service (e.g. a schema backed by `func()`)\n     * without the container accidentally invoking it as a factory.\n     *\n     * @param schema - The schema used as the service identifier.\n     * @param instance - The pre-created value to register. Can be any type\n     *   including a function.\n     * @param options - Optional {@link ServiceRegistrationOptions}.\n     * @returns `this` for chaining.\n     *\n     * @example Register a plain object instance\n     * ```ts\n     * const config = { port: 3000, host: 'localhost' };\n     * services.addSingletonInstance(IConfig, config);\n     * ```\n     *\n     * @example Register a function value (impossible with {@link addSingleton})\n     * ```ts\n     * const IHandler = func();\n     * const myHandler = (req: Request) => new Response('ok');\n     * services.addSingletonInstance(IHandler, myHandler);\n     * ```\n     *\n     * @see {@link addSingleton}\n     */\n    public addSingletonInstance<\n        TSchema extends SchemaBuilder<any, any, any, any, any>\n    >(\n        schema: TSchema,\n        instance: InferType<TSchema>,\n        options?: ServiceRegistrationOptions\n    ): this {\n        return this.#addInstance(schema, instance, options);\n    }\n\n    /**\n     * Registers a {@link ServiceLifetime.Singleton | Singleton} service whose\n     * dependencies are described by a {@link FunctionSchemaBuilder}. The\n     * container resolves each parameter schema from the registry and passes\n     * the resolved values to `implementation`.\n     *\n     * @param targetSchema - The schema used as the service identifier for the\n     *   created service.\n     * @param funcSchema - A {@link FunctionSchemaBuilder} whose\n     *   `introspect().parameters` list the dependency schemas.\n     * @param implementation - A function whose parameters match the\n     *   `funcSchema` parameter schemas (in order) and returns the service\n     *   instance.\n     * @param options - Optional {@link ServiceRegistrationOptions}.\n     * @returns `this` for chaining.\n     *\n     * @example\n     * ```ts\n     * const IGreeter = object({ greet: func() });\n     *\n     * const greeterDeps = func()\n     *     .addParameter(IConfig)\n     *     .addParameter(ILogger);\n     *\n     * services.addSingletonFromSchema(\n     *     IGreeter,\n     *     greeterDeps,\n     *     (config, logger) => ({\n     *         greet() { logger.info(`Hello from ${config.host}`); }\n     *     })\n     * );\n     * ```\n     *\n     * @see {@link addScopedFromSchema}\n     * @see {@link addTransientFromSchema}\n     */\n    public addSingletonFromSchema<\n        TTargetSchema extends SchemaBuilder<any, any, any, any, any>,\n        TFuncSchema extends FunctionSchemaBuilder<any, any, any, any, any, any>\n    >(\n        targetSchema: TTargetSchema,\n        funcSchema: TFuncSchema,\n        implementation: (\n            ...args: FuncSchemaParameters<TFuncSchema>\n        ) => InferType<TTargetSchema>,\n        options?: ServiceRegistrationOptions\n    ): this {\n        return this.#addFromSchema(\n            targetSchema,\n            funcSchema,\n            implementation,\n            ServiceLifetime.Singleton,\n            options\n        );\n    }\n\n    /**\n     * Registers a {@link ServiceLifetime.Scoped | Scoped} service whose\n     * dependencies are described by a {@link FunctionSchemaBuilder}.\n     *\n     * @param targetSchema - The schema used as the service identifier.\n     * @param funcSchema - A {@link FunctionSchemaBuilder} describing the\n     *   dependency schemas via its parameters.\n     * @param implementation - A function receiving the resolved dependencies\n     *   and returning the service instance.\n     * @param options - Optional {@link ServiceRegistrationOptions}.\n     * @returns `this` for chaining.\n     *\n     * @see {@link addSingletonFromSchema}\n     * @see {@link addTransientFromSchema}\n     */\n    public addScopedFromSchema<\n        TTargetSchema extends SchemaBuilder<any, any, any, any, any>,\n        TFuncSchema extends FunctionSchemaBuilder<any, any, any, any, any, any>\n    >(\n        targetSchema: TTargetSchema,\n        funcSchema: TFuncSchema,\n        implementation: (\n            ...args: FuncSchemaParameters<TFuncSchema>\n        ) => InferType<TTargetSchema>,\n        options?: ServiceRegistrationOptions\n    ): this {\n        return this.#addFromSchema(\n            targetSchema,\n            funcSchema,\n            implementation,\n            ServiceLifetime.Scoped,\n            options\n        );\n    }\n\n    /**\n     * Registers a {@link ServiceLifetime.Transient | Transient} service whose\n     * dependencies are described by a {@link FunctionSchemaBuilder}.\n     *\n     * @param targetSchema - The schema used as the service identifier.\n     * @param funcSchema - A {@link FunctionSchemaBuilder} describing the\n     *   dependency schemas via its parameters.\n     * @param implementation - A function receiving the resolved dependencies\n     *   and returning the service instance.\n     * @param options - Optional {@link ServiceRegistrationOptions}.\n     * @returns `this` for chaining.\n     *\n     * @see {@link addSingletonFromSchema}\n     * @see {@link addScopedFromSchema}\n     */\n    public addTransientFromSchema<\n        TTargetSchema extends SchemaBuilder<any, any, any, any, any>,\n        TFuncSchema extends FunctionSchemaBuilder<any, any, any, any, any, any>\n    >(\n        targetSchema: TTargetSchema,\n        funcSchema: TFuncSchema,\n        implementation: (\n            ...args: FuncSchemaParameters<TFuncSchema>\n        ) => InferType<TTargetSchema>,\n        options?: ServiceRegistrationOptions\n    ): this {\n        return this.#addFromSchema(\n            targetSchema,\n            funcSchema,\n            implementation,\n            ServiceLifetime.Transient,\n            options\n        );\n    }\n\n    /**\n     * Creates a new {@link ServiceProvider} from the registrations currently\n     * contained in this collection.\n     *\n     * @param options - Optional {@link ServiceProviderOptions} to control\n     *   provider behaviour (e.g. scope validation).\n     * @returns A new {@link ServiceProvider} instance.\n     *\n     * @example\n     * ```ts\n     * const provider = services.buildServiceProvider();\n     * const logger = provider.get(ILogger);\n     * ```\n     *\n     * @example With scope validation disabled\n     * ```ts\n     * const provider = services.buildServiceProvider({\n     *     validateScopes: false\n     * });\n     * ```\n     */\n    public buildServiceProvider(\n        options?: ServiceProviderOptions\n    ): ServiceProvider {\n        const descriptors = new Map(this.#descriptors);\n        return new ServiceProvider(descriptors, options);\n    }\n\n    #add<TSchema extends SchemaBuilder<any, any, any, any, any>>(\n        schema: TSchema,\n        lifetime: ServiceLifetime,\n        factoryOrValue: ServiceFactory<InferType<TSchema>> | InferType<TSchema>,\n        options?: ServiceRegistrationOptions\n    ): this {\n        const factory: ServiceFactory<InferType<TSchema>> =\n            typeof factoryOrValue === 'function'\n                ? (factoryOrValue as ServiceFactory<InferType<TSchema>>)\n                : () => factoryOrValue;\n\n        this.#descriptors.set(schema, {\n            schema,\n            lifetime,\n            factory,\n            validate: options?.validate ?? false\n        });\n\n        return this;\n    }\n\n    #addInstance<TSchema extends SchemaBuilder<any, any, any, any, any>>(\n        schema: TSchema,\n        instance: InferType<TSchema>,\n        options?: ServiceRegistrationOptions\n    ): this {\n        const factory: ServiceFactory<InferType<TSchema>> = () => instance;\n\n        this.#descriptors.set(schema, {\n            schema,\n            lifetime: ServiceLifetime.Singleton,\n            factory,\n            validate: options?.validate ?? false\n        });\n\n        return this;\n    }\n\n    #addFromSchema<\n        TTargetSchema extends SchemaBuilder<any, any, any, any, any>,\n        TFuncSchema extends FunctionSchemaBuilder<any, any, any, any, any, any>\n    >(\n        targetSchema: TTargetSchema,\n        funcSchema: TFuncSchema,\n        implementation: (\n            ...args: FuncSchemaParameters<TFuncSchema>\n        ) => InferType<TTargetSchema>,\n        lifetime: ServiceLifetime,\n        options?: ServiceRegistrationOptions\n    ): this {\n        const parameterSchemas = funcSchema.introspect().parameters;\n\n        const factory: ServiceFactory<InferType<TTargetSchema>> = provider => {\n            const args = parameterSchemas.map(paramSchema =>\n                provider.get(paramSchema)\n            );\n            return (implementation as Function).apply(null, args);\n        };\n\n        this.#descriptors.set(targetSchema, {\n            schema: targetSchema,\n            lifetime,\n            factory,\n            validate: options?.validate ?? false\n        });\n\n        return this;\n    }\n}\n\n/**\n * Extracts the parameter types from a {@link FunctionSchemaBuilder} as a tuple.\n * Used internally to type-check `addSingletonFromSchema`-style registrations.\n */\ntype FuncSchemaParameters<\n    T extends FunctionSchemaBuilder<any, any, any, any, any, any>\n> =\n    T extends FunctionSchemaBuilder<\n        any,\n        any,\n        any,\n        any,\n        any,\n        infer TParams extends SchemaBuilder<any, any, any, any, any>[]\n    >\n        ? { [K in keyof TParams]: InferType<TParams[K]> }\n        : never;\n"],"mappings":"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","names":["ServiceLifetime","isDisposable","value","isAsyncDisposable","ServiceScope","#descriptors","#singletonCache","#scopedCache","#disposables","#disposed","descriptors","singletonCache","ScopedServiceProvider","firstError","i","instance","isDisposable","err","isAsyncDisposable","#scope","scope","schema","#resolve","funcSchema","implementation","parameterSchemas","resolutionStack","args","paramSchema","descriptor","chain","s","#createAndValidate","scopedCache","childProxy","ScopedResolverProxy","result","messages","e","#provider","#resolutionStack","provider","ServiceProvider","#descriptors","#singletonCache","#validateScopes","descriptors","options","schema","#resolve","ServiceScope","funcSchema","implementation","parameterSchemas","resolutionStack","args","paramSchema","scopedCache","trackDisposable","descriptor","chain","s","instance","#createAndValidate","childProvider","ScopedResolverProxy","result","messages","e","#provider","#resolutionStack","#scopedCache","#trackDisposable","provider","ServiceCollection","#descriptors","schema","factoryOrValue","options","#add","factory","instance","#addInstance","targetSchema","funcSchema","implementation","#addFromSchema","descriptors","ServiceProvider","lifetime","parameterSchemas","provider","args","paramSchema"]}

package/dist/types.d.ts

@@ -0,0 +1,156 @@
+import type { InferType, SchemaBuilder } from '@cleverbrush/schema';
+/**
+ * Defines the lifetime of a service within the dependency injection container.
+ *
+ * The lifetime determines when a new instance is created versus when a cached
+ * instance is returned.
+ *
+ * @example
+ * ```ts
+ * import { ServiceCollection, ServiceLifetime } from '@cleverbrush/di';
+ * import { object, string } from '@cleverbrush/schema';
+ *
+ * const ILogger = object({ info: func() });
+ *
+ * const services = new ServiceCollection();
+ * // Equivalent to services.addSingleton(ILogger, ...)
+ * services.add(ILogger, () => console, ServiceLifetime.Singleton);
+ * ```
+ *
+ * @see {@link ServiceCollection}
+ */
+export declare enum ServiceLifetime {
+    /**
+     * A new instance is created every time the service is resolved.
+     *
+     * Use for lightweight, stateless services.
+     */
+    Transient = "Transient",
+    /**
+     * One instance is created per {@link ServiceScope}. The same instance is
+     * returned for every resolution within that scope.
+     *
+     * Use for services that should be shared within a single unit of work
+     * (e.g. an HTTP request) but isolated between units.
+     */
+    Scoped = "Scoped",
+    /**
+     * One instance is created for the entire lifetime of the
+     * {@link ServiceProvider}. All subsequent resolutions return the same instance.
+     *
+     * Use for expensive-to-create or truly global services (loggers,
+     * configuration, connection pools).
+     */
+    Singleton = "Singleton"
+}
+/**
+ * A factory function that creates a service instance, optionally resolving
+ * other services from the provided {@link ServiceProvider}.
+ *
+ * @typeParam T - The type of the service instance the factory creates.
+ *
+ * @example
+ * ```ts
+ * const loggerFactory: ServiceFactory<Logger> = (provider) => {
+ *     const config = provider.get(IConfig);
+ *     return new Logger(config.logLevel);
+ * };
+ * ```
+ *
+ * @see {@link ServiceCollection}
+ */
+export type ServiceFactory<T> = (provider: IServiceProvider) => T;
+/**
+ * Describes a registered service: its schema key, lifetime, factory, and
+ * optional runtime validation flag.
+ *
+ * @typeParam T - The type of the service instance.
+ *
+ * @see {@link ServiceCollection}
+ * @see {@link ServiceLifetime}
+ */
+export interface ServiceDescriptor<T = any> {
+    /** The schema used as the service identifier (reference equality). */
+    readonly schema: SchemaBuilder<T, any, any, any, any>;
+    /** The lifetime of the service. */
+    readonly lifetime: ServiceLifetime;
+    /** The factory function that creates the service instance. */
+    readonly factory: ServiceFactory<T>;
+    /**
+     * When `true`, the container validates the factory's return value against
+     * the schema at resolution time using `schema.validate()`.
+     *
+     * @defaultValue `false`
+     */
+    readonly validate: boolean;
+}
+/**
+ * Options for service registration.
+ *
+ * @see {@link ServiceCollection.addSingleton}
+ * @see {@link ServiceCollection.addScoped}
+ * @see {@link ServiceCollection.addTransient}
+ */
+export interface ServiceRegistrationOptions {
+    /**
+     * When `true`, the resolved value is validated against the schema at
+     * resolution time. Useful for development/debugging. Has a performance
+     * cost proportional to the schema complexity.
+     *
+     * @defaultValue `false`
+     */
+    validate?: boolean;
+}
+/**
+ * Minimal interface for the service provider, used to avoid circular
+ * dependencies between modules.
+ *
+ * @see {@link ServiceProvider}
+ */
+export interface IServiceProvider {
+    /**
+     * Resolves a service by its schema key.
+     * @param schema - The schema instance used as the service identifier.
+     * @throws If the service is not registered.
+     */
+    get<TSchema extends SchemaBuilder<any, any, any, any, any>>(schema: TSchema): InferType<TSchema>;
+    /**
+     * Resolves a service by its schema key, or returns `undefined` if not registered.
+     * @param schema - The schema instance used as the service identifier.
+     */
+    getOptional<TSchema extends SchemaBuilder<any, any, any, any, any>>(schema: TSchema): InferType<TSchema> | undefined;
+}
+/**
+ * Checks whether a value implements the synchronous `Disposable` protocol
+ * (`Symbol.dispose`).
+ *
+ * @param value - The value to check.
+ * @returns `true` if `value` has a `Symbol.dispose` method.
+ *
+ * @example
+ * ```ts
+ * const resource = {
+ *     [Symbol.dispose]() { console.log('disposed'); }
+ * };
+ * isDisposable(resource); // true
+ * isDisposable({});       // false
+ * ```
+ */
+export declare function isDisposable(value: unknown): value is Disposable;
+/**
+ * Checks whether a value implements the asynchronous `Disposable` protocol
+ * (`Symbol.asyncDispose`).
+ *
+ * @param value - The value to check.
+ * @returns `true` if `value` has a `Symbol.asyncDispose` method.
+ *
+ * @example
+ * ```ts
+ * const connection = {
+ *     async [Symbol.asyncDispose]() { await db.close(); }
+ * };
+ * isAsyncDisposable(connection); // true
+ * isAsyncDisposable({});         // false
+ * ```
+ */
+export declare function isAsyncDisposable(value: unknown): value is AsyncDisposable;

package/package.json

@@ -0,0 +1,47 @@
+{
+    "author": "Andrew Zolotukhin <andrew_zol@cleverbrush.com>",
+    "bugs": {
+        "url": "https://github.com/cleverbrush/framework/issues",
+        "email": "andrew_zol@cleverbrush.com"
+    },
+    "dependencies": {
+        "@cleverbrush/schema": "0.0.0-beta-20260410162047"
+    },
+    "description": ".NET-style dependency injection container for TypeScript — schema-driven service registration, three lifetimes, function injection",
+    "files": [
+        "dist"
+    ],
+    "homepage": "https://docs.cleverbrush.com/di",
+    "keywords": [
+        "dependency injection",
+        "di",
+        "ioc",
+        "service container",
+        "typescript",
+        "schema",
+        "cleverbrush"
+    ],
+    "license": "BSD 3-Clause",
+    "main": "./dist/index.js",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        }
+    },
+    "sideEffects": false,
+    "name": "@cleverbrush/di",
+    "readme": "https://github.com/cleverbrush/framework/tree/master/libs/di#readme",
+    "repository": {
+        "type": "git",
+        "url": "github:cleverbrush/framework"
+    },
+    "scripts": {
+        "watch": "tsc --build tsconfig.build.json --watch",
+        "build": "tsup && tsc --project tsconfig.build.json --emitDeclarationOnly",
+        "clean": "rm -rf dist tsconfig.build.tsbuildinfo"
+    },
+    "type": "module",
+    "types": "./dist/index.d.ts",
+    "version": "0.0.0-beta-20260410162047"
+}