Getting Started

This guide sets up a minimal composition root with typed tokens, scoped resolution, and deterministic cleanup.

Installation

npm

bash copy npm install @elsikora/cladi

yarn

bash copy yarn add @elsikora/cladi

pnpm

bash copy pnpm add @elsikora/cladi

bun

bash copy bun add @elsikora/cladi

For test suites in ClaDI-based apps, add the companion testing package:


npm install -D @elsikora/cladi-testing

First Composition Root

src/bootstrap.ts


import { createDIContainer, createLazyProvider, createToken, EDependencyLifecycle } from "@elsikora/cladi";
 
const ConfigToken = createToken<{ apiUrl: string }>("Config");
const HttpToken = createToken<{ get(path: string): Promise<unknown> }>("Http");
const LazyHttpToken = createToken<() => Promise<{ get(path: string): Promise<unknown> }>>("LazyHttp");
 
const container = createDIContainer({ scopeName: "root" });
 
container.register({
	provide: ConfigToken,
	useValue: { apiUrl: "https://api.example.com" },
});
 
container.register({
	provide: HttpToken,
	lifecycle: EDependencyLifecycle.SCOPED,
	deps: [ConfigToken],
	useFactory: (config) => ({
		get: async (path: string) => fetch(`${config.apiUrl}${path}`).then((response) => response.json()),
	}),
});
 
container.register(createLazyProvider(LazyHttpToken, HttpToken));
container.validate();

Request/Job Scope Pattern

src/runner.ts


const scope = container.createScope("request");
 
try {
	const lazyHttp = scope.resolve(LazyHttpToken);
	const http = await lazyHttp();
	await http.get("/health");
} finally {
	await scope.dispose();
}

For service startup/shutdown boundaries:

src/main.ts


try {
	// start application
} finally {
	await container.dispose();
}