Class ServiceCollection

A mutable collection of service registrations. Build up the collection by calling addSingleton, addScoped, or addTransient, then call buildServiceProvider to create an immutable 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

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

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

Index

Constructors

constructor

Methods

addScoped addScopedFromSchema addSingleton addSingletonFromSchema addSingletonInstance addTransient addTransientFromSchema buildServiceProvider

Constructors

constructor

new ServiceCollection(): ServiceCollection
Returns ServiceCollection

Methods

addScoped

addScoped<TSchema extends SchemaBuilder<any, any, any, any, any>>(
    schema: TSchema,
    factory: ServiceFactory<InferType<TSchema>>,
    options?: ServiceRegistrationOptions,
): this
Registers a service with Scoped lifetime. One instance is created per ServiceScope; within a scope every resolution returns the same instance.
Type Parameters
- TSchema extends SchemaBuilder<any, any, any, any, any>
Parameters
- schema: TSchema
  The schema used as the service identifier.
- factory: ServiceFactory<InferType<TSchema>>
  A ServiceFactory function that creates the service instance. Unlike addSingleton, a plain value is not accepted because scoped services must be freshly created per scope.
- Optionaloptions: ServiceRegistrationOptions
  Optional ServiceRegistrationOptions.
Returns this
this for chaining.
Example
```
const IDbContext = object({ query: func() });

services.addScoped(IDbContext, (provider) => {
    const config = provider.get(IConfig);
    return new DbContext(config.connectionString);
});
```
See
- addSingleton
- addTransient
- Defined in ServiceCollection.ts:149

addScopedFromSchema

addScopedFromSchema<
    TTargetSchema extends SchemaBuilder<any, any, any, any, any>,
    TFuncSchema extends
        FunctionSchemaBuilder<any, any, any, any, any, any, undefined, any>,
>(
    targetSchema: TTargetSchema,
    funcSchema: TFuncSchema,
    implementation: (
        ...args: FuncSchemaParameters<TFuncSchema>,
    ) => InferType<TTargetSchema>,
    options?: ServiceRegistrationOptions,
): this
Registers a Scoped service whose dependencies are described by a FunctionSchemaBuilder.
Type Parameters
- TTargetSchema extends SchemaBuilder<any, any, any, any, any>
- TFuncSchema extends FunctionSchemaBuilder<any, any, any, any, any, any, undefined, any>
Parameters
- targetSchema: TTargetSchema
  The schema used as the service identifier.
- funcSchema: TFuncSchema
  A FunctionSchemaBuilder describing the dependency schemas via its parameters.
- implementation: (...args: FuncSchemaParameters<TFuncSchema>) => InferType<TTargetSchema>
  A function receiving the resolved dependencies and returning the service instance.
- Optionaloptions: ServiceRegistrationOptions
  Optional ServiceRegistrationOptions.
Returns this
this for chaining.
See
- addSingletonFromSchema
- addTransientFromSchema
- Defined in ServiceCollection.ts:296

addSingleton

addSingleton<TSchema extends SchemaBuilder<any, any, any, any, any>>(
    schema: TSchema,
    factoryOrValue: InferType<TSchema> | ServiceFactory<InferType<TSchema>>,
    options?: ServiceRegistrationOptions,
): this
Registers a service with Singleton lifetime. The factory (or value) is called at most once; every subsequent resolution returns the same instance.
Type Parameters
- TSchema extends SchemaBuilder<any, any, any, any, any>
Parameters
- schema: TSchema
  The schema used as the service identifier.
- factoryOrValue: InferType<TSchema> | ServiceFactory<InferType<TSchema>>
  Either a ServiceFactory function that receives the provider, or a plain value (which is wrapped in a factory automatically).
- Optionaloptions: ServiceRegistrationOptions
  Optional ServiceRegistrationOptions.
Returns this
this for chaining.
Example: Factory registration
```
services.addSingleton(ILogger, (provider) => {
    const config = provider.get(IConfig);
    return new ConsoleLogger(config.logLevel);
});
```
Example: Value shorthand
```
services.addSingleton(IConfig, { port: 3000, host: 'localhost' });
```
See
- addScoped
- addTransient
- Defined in ServiceCollection.ts:110

addSingletonFromSchema

addSingletonFromSchema<
    TTargetSchema extends SchemaBuilder<any, any, any, any, any>,
    TFuncSchema extends
        FunctionSchemaBuilder<any, any, any, any, any, any, undefined, any>,
>(
    targetSchema: TTargetSchema,
    funcSchema: TFuncSchema,
    implementation: (
        ...args: FuncSchemaParameters<TFuncSchema>,
    ) => InferType<TTargetSchema>,
    options?: ServiceRegistrationOptions,
): this
Registers a Singleton service whose dependencies are described by a FunctionSchemaBuilder. The container resolves each parameter schema from the registry and passes the resolved values to implementation.
Type Parameters
- TTargetSchema extends SchemaBuilder<any, any, any, any, any>
- TFuncSchema extends FunctionSchemaBuilder<any, any, any, any, any, any, undefined, any>
Parameters
- targetSchema: TTargetSchema
  The schema used as the service identifier for the created service.
- funcSchema: TFuncSchema
  A FunctionSchemaBuilder whose introspect().parameters list the dependency schemas.
- implementation: (...args: FuncSchemaParameters<TFuncSchema>) => InferType<TTargetSchema>
  A function whose parameters match the funcSchema parameter schemas (in order) and returns the service instance.
- Optionaloptions: ServiceRegistrationOptions
  Optional ServiceRegistrationOptions.
Returns this
this for chaining.
Example
```
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
- addScopedFromSchema
- addTransientFromSchema
- Defined in ServiceCollection.ts:261

addSingletonInstance

addSingletonInstance<TSchema extends SchemaBuilder<any, any, any, any, any>>(
    schema: TSchema,
    instance: InferType<TSchema>,
    options?: ServiceRegistrationOptions,
): this
Registers a pre-created instance as a Singleton. Unlike 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.
Type Parameters
- TSchema extends SchemaBuilder<any, any, any, any, any>
Parameters
- schema: TSchema
  The schema used as the service identifier.
- instance: InferType<TSchema>
  The pre-created value to register. Can be any type including a function.
- Optionaloptions: ServiceRegistrationOptions
  Optional ServiceRegistrationOptions.
Returns this
this for chaining.
Example: Register a plain object instance
```
const config = { port: 3000, host: 'localhost' };
services.addSingletonInstance(IConfig, config);
```
Example: Register a function value (impossible with {@link addSingleton})
```
const IHandler = func();
const myHandler = (req: Request) => new Response('ok');
services.addSingletonInstance(IHandler, myHandler);
```
See
addSingleton
- Defined in ServiceCollection.ts:215

addTransient

addTransient<TSchema extends SchemaBuilder<any, any, any, any, any>>(
    schema: TSchema,
    factory: ServiceFactory<InferType<TSchema>>,
    options?: ServiceRegistrationOptions,
): this
Registers a service with Transient lifetime. A new instance is created on every resolution.
Type Parameters
- TSchema extends SchemaBuilder<any, any, any, any, any>
Parameters
- schema: TSchema
  The schema used as the service identifier.
- factory: ServiceFactory<InferType<TSchema>>
  A ServiceFactory function that creates the service instance.
- Optionaloptions: ServiceRegistrationOptions
  Optional ServiceRegistrationOptions.
Returns this
this for chaining.
Example
```
const IRequestId = object({ id: string() });

services.addTransient(IRequestId, () => ({
    id: crypto.randomUUID()
}));
```
See
- addSingleton
- addScoped
- Defined in ServiceCollection.ts:179

addTransientFromSchema

addTransientFromSchema<
    TTargetSchema extends SchemaBuilder<any, any, any, any, any>,
    TFuncSchema extends
        FunctionSchemaBuilder<any, any, any, any, any, any, undefined, any>,
>(
    targetSchema: TTargetSchema,
    funcSchema: TFuncSchema,
    implementation: (
        ...args: FuncSchemaParameters<TFuncSchema>,
    ) => InferType<TTargetSchema>,
    options?: ServiceRegistrationOptions,
): this
Registers a Transient service whose dependencies are described by a FunctionSchemaBuilder.
Type Parameters
- TTargetSchema extends SchemaBuilder<any, any, any, any, any>
- TFuncSchema extends FunctionSchemaBuilder<any, any, any, any, any, any, undefined, any>
Parameters
- targetSchema: TTargetSchema
  The schema used as the service identifier.
- funcSchema: TFuncSchema
  A FunctionSchemaBuilder describing the dependency schemas via its parameters.
- implementation: (...args: FuncSchemaParameters<TFuncSchema>) => InferType<TTargetSchema>
  A function receiving the resolved dependencies and returning the service instance.
- Optionaloptions: ServiceRegistrationOptions
  Optional ServiceRegistrationOptions.
Returns this
this for chaining.
See
- addSingletonFromSchema
- addScopedFromSchema
- Defined in ServiceCollection.ts:331

buildServiceProvider

buildServiceProvider(options?: ServiceProviderOptions): ServiceProvider
Creates a new ServiceProvider from the registrations currently contained in this collection.
Parameters
- Optionaloptions: ServiceProviderOptions
  Optional ServiceProviderOptions to control provider behaviour (e.g. scope validation).
Returns ServiceProvider
A new ServiceProvider instance.
Example
```
const provider = services.buildServiceProvider();
const logger = provider.get(ILogger);
```
Example: With scope validation disabled
```
const provider = services.buildServiceProvider({
    validateScopes: false
});
```
- Defined in ServiceCollection.ts:372

Class ServiceCollection

Example: Basic registration and resolution

Example: Function-schema-driven registration

See

Index

Constructors

Methods

Constructors

constructor

Returns ServiceCollection

Methods

addScoped

Type Parameters

Parameters

Returns this

Example

See

addScopedFromSchema

Type Parameters

Parameters

Returns this

See

addSingleton

Type Parameters

Parameters

Returns this

Example: Factory registration

Example: Value shorthand

See

addSingletonFromSchema

Type Parameters

Parameters

Returns this

Example

See

addSingletonInstance

Type Parameters

Parameters

Returns this

Example: Register a plain object instance

Example: Register a function value (impossible with {@link addSingleton})

See

addTransient

Type Parameters

Parameters

Returns this

Example

See

addTransientFromSchema

Type Parameters

Parameters

Returns this

See

buildServiceProvider

Parameters

Returns ServiceProvider

Example

Example: With scope validation disabled

Settings

On This Page