di-craft 0.0.9 → 0.0.11

package/README.md

@@ -1,18 +1,375 @@
 # di-craft
 
-A tiny TypeScript dependency injection container.
+A tiny, type-safe dependency injection container for TypeScript.
+
+## Contents
+
+- [Quick start](#quick-start)
+- [Philosophy](#philosophy)
+- [Features](#features)
+- [Install](#install)
+- [Core concepts](#core-concepts)
+  - [Tokens](#tokens)
+  - [Providers](#providers)
+  - [Container](#container)
+  - [Scopes](#scopes)
+  - [Disposal](#disposal)
+  - [Child containers](#child-containers)
+  - [Cycle detection](#cycle-detection)
+- [Example: per-request container](#example-per-request-container)
+- [Error handling](#error-handling)
+- [API reference](#api-reference)
+- [License](#license)
+
+## Quick start
+
+Declare typed tokens, describe how each one is built with a provider, then create
+a container and resolve from it. Dependencies are wired explicitly through the
+`deps` map and resolved for you.
+
+```ts
+import {
+  createContainer,
+  createToken,
+  provideFactory,
+  provideValue,
+  type Provider,
+} from "di-craft";
+
+const CONFIG = createToken<Config>("config");
+const LOGGER = createToken<Logger>("logger");
+const USERS = createToken<UserService>("users");
+
+const providers: Provider[] = [
+  provideValue(CONFIG, loadConfig()),
+  provideFactory(LOGGER, {
+    deps: { config: CONFIG },
+    useFactory: ({ config }) => new Logger(config.level),
+  }),
+  provideFactory(USERS, {
+    deps: { logger: LOGGER },
+    useFactory: ({ logger }) => new UserService(logger),
+  }),
+];
+
+const container = createContainer(providers);
+
+const users = container.get(USERS); // UserService, fully typed
+```
+
+## Philosophy
+
+Dependency injection without the magic — no decorators, no `reflect-metadata`, no
+framework coupling. You work with just **tokens**, **providers**, a **container**,
+**scopes**, and **cycle detection**.
 
 ## Features
 
 - Zero runtime dependencies
-- No decorators
-- No reflect-metadata
-- Type-safe tokens
-- Explicit factories
-- Singleton and transient scopes
+- Type-safe tokens and factories
+- Singleton, transient, and scoped lifetimes
+- Hierarchical child containers
+- Deterministic disposal with `onDispose` hooks
+- Circular dependency detection
+- Tree-shakable, tiny bundle size
+- Ships both ESM and CommonJS builds
 
 ## Install
 
 ```bash
 bun add di-craft
+npm install di-craft
+pnpm add di-craft
+yarn add di-craft
+```
+
+Requires Node.js `>= 20`.
+
+## Core concepts
+
+### Tokens
+
+A token is a unique, type-carrying key. Identity is based on an internal `symbol`, **not** on the name — two tokens with the same name are still different.
+
+```ts
+const PORT = createToken<number>("port");
+
+PORT.name; // "port" — used only for error messages
+```
+
+The type argument flows everywhere: providers must produce a matching value, and `container.get(PORT)` returns `number`.
+
+### Providers
+
+A provider tells the container how to produce the value for a token.
+
+`provideValue` — register an existing value:
+
+```ts
+provideValue(PORT, 3000);
+```
+
+`provideFactory` — build the value lazily, with optional dependencies and scope:
+
+```ts
+provideFactory(HTTP, {
+  deps: { config: CONFIG },         // optional, keyed map of tokens
+  scope: "singleton",                // optional, defaults to "singleton"
+  useFactory: ({ config }) => new HttpClient(config.apiUrl),
+});
+```
+
+The keys in `deps` become the keys of the object passed to `useFactory`, each resolved to its token's type.
+
+### Container
+
+The container holds your providers and resolves values on demand. Create one
+from a list of providers (all optional), then add more, check, resolve, and
+dispose:
+
+- `register(provider, options?)` — add a provider at any time.
+- `has(token)` — whether a provider for the token is registered.
+- `get(token)` — resolve the value, building and caching it as its scope dictates.
+- `dispose()` — run `onDispose` hooks and release resolved instances.
+
+```ts
+const container = createContainer(providers); // providers are optional
+
+container.register(provideValue(PORT, 3000)); // register more at any time
+container.has(PORT);                           // true
+container.get(PORT);                           // 3000
+await container.dispose();                     // release resolved singletons
+```
+
+Registering the same token twice throws `DuplicateProviderError`. To replace an
+existing provider on purpose (handy for tests, mocks, and environment-specific
+overrides), pass `{ allowOverride: true }`:
+
+```ts
+container.register(provideValue(API, fakeApi), { allowOverride: true });
+```
+
+Overriding a token whose value was already resolved as a singleton drops the
+cached instance, so the next `get` rebuilds it from the new provider.
+
+### Scopes
+
+| Scope                  | Behavior                                                         |
+| ---------------------- | ---------------------------------------------------------------- |
+| `singleton` (default)  | The factory runs once; the same instance is returned every time. |
+| `transient`            | The factory runs on every `get`, producing a fresh instance.     |
+| `scoped`               | One instance per container. In a child container each child gets its own instance, while the provider can still be declared once on the parent. |
+
+Use the `Scopes` helper for autocompletion, or pass the plain string — both work:
+
+```ts
+import { Scopes, provideFactory } from "di-craft";
+
+provideFactory(ID, {
+  scope: Scopes.Transient, // or scope: "transient"
+  useFactory: () => crypto.randomUUID(),
+});
+
+container.get(ID) !== container.get(ID); // true
+```
+
+A transient provider that depends on a singleton still reuses the shared singleton instance.
+
+### Disposal
+
+Factory providers can declare an `onDispose` hook to release resources (database
+pools, sockets, timers, subscriptions). Calling `container.dispose()` runs the
+hooks for every resolved singleton and clears the cache:
+
+```ts
+const DB = createToken<Pool>("db");
+
+const container = createContainer([
+  provideFactory(DB, {
+    useFactory: () => createPool(url),
+    onDispose: (pool) => pool.end(), // may be sync or async
+  }),
+]);
+
+container.get(DB);
+
+await container.dispose(); // awaits async hooks, then clears instances
 ```
+
+Details:
+
+- Hooks run in reverse creation order (dependents before their dependencies).
+- `dispose()` returns a promise and awaits async hooks.
+- It is idempotent — calling it again is a no-op.
+- Only resolved singletons are disposed; transient and never-resolved instances are not tracked.
+
+### Child containers
+
+`createChildContainer(parent, providers?)` creates a child that inherits
+everything from its parent but can add or override providers locally. This is the
+typical pattern for per-request isolation on a server: shared services live on
+the root, request-specific values live on a short-lived child.
+
+```ts
+const root = createContainer([
+  provideFactory(LOGGER, { useFactory: () => console }), // singleton, shared
+  provideFactory(HANDLER, {
+    scope: Scopes.Scoped, // one instance per child
+    deps: { request: REQUEST },
+    useFactory: ({ request }) => createHandler(request),
+  }),
+]);
+
+function handle(request: Request) {
+  const child = createChildContainer(root, [provideValue(REQUEST, request)]);
+
+  child.get(LOGGER); // same logger as the root and every other child
+  child.get(HANDLER); // a fresh handler, unique to this child
+
+  return child.dispose(); // release only this child's instances
+}
+```
+
+How resolution works across the chain:
+
+- A token is looked up in the child first, then walks up to the parent.
+- `singleton` is cached on the container that **owns** the provider, so it is shared by the whole subtree.
+- `scoped` is cached on the **requesting** child, so each child gets its own instance — even when the provider is declared once on the parent.
+- A `scoped` provider resolves its dependencies from the requesting child, so it can depend on values registered only in that child (like `REQUEST`).
+- `dispose()` only releases the container it is called on; it does not cascade to parents or children.
+
+### Cycle detection
+
+If providers form a dependency cycle, resolution throws `CircularDependencyError` with the full path instead of overflowing the stack.
+
+```ts
+// A -> B -> A
+container.get(A); // throws: Circular dependency detected: A -> B -> A
+```
+
+## Example: per-request container
+
+A common server pattern: build one **root** container at startup with the
+long-lived singletons (a database pool, clients, config), then fork a
+short-lived **child** per request for request-specific state. `scoped` providers
+give each request its own instance, and `dispose()` releases them once the
+response is sent.
+
+```ts
+import Fastify, { type FastifyRequest } from "fastify";
+import {
+  type Container,
+  createContainer,
+  createChildContainer,
+  createToken,
+  provideValue,
+  provideFactory,
+  Scopes,
+} from "di-craft";
+
+const DB = createToken<Pool>("db");
+const REQUEST = createToken<FastifyRequest>("request");
+const REQUEST_ID = createToken<string>("request-id");
+const USERS = createToken<UserService>("users");
+
+const app = Fastify({ logger: true });
+
+// Built once, shared by every request.
+const root = createContainer([
+  provideFactory(DB, {
+    useFactory: () => createPool(process.env.DATABASE_URL),
+    onDispose: (pool) => pool.end(), // closed only on shutdown
+  }),
+  provideFactory(REQUEST_ID, {
+    scope: Scopes.Scoped, // one id per request
+    deps: { request: REQUEST }, // resolves the value registered on the child
+    useFactory: ({ request }) => request.id, // Fastify's built-in request id
+  }),
+  provideFactory(USERS, {
+    scope: Scopes.Scoped, // one service per request...
+    deps: { db: DB }, // ...but reuses the shared pool
+    useFactory: ({ db }) => new UserService(db),
+  }),
+]);
+
+// Keep each request's child container without patching Fastify's types.
+const containers = new WeakMap<FastifyRequest, Container>();
+
+app.addHook("onRequest", async (request) => {
+  // A fresh child per request, seeded with the request object.
+  containers.set(request, createChildContainer(root, [provideValue(REQUEST, request)]));
+});
+
+app.addHook("onResponse", async (request) => {
+  // Release this request's scoped instances once the response is sent.
+  await containers.get(request)?.dispose();
+});
+
+app.get<{ Params: { id: string } }>("/users/:id", async (request) => {
+  const container = containers.get(request)!;
+  const users = container.get(USERS);
+  const id = container.get(REQUEST_ID); // unique to this request
+
+  return users.findById(request.params.id, { traceId: id });
+});
+
+// On shutdown, dispose the root to close the shared pool.
+app.addHook("onClose", async () => {
+  await root.dispose();
+});
+
+await app.listen({ port: 3000 });
+```
+
+What each scope buys you here:
+
+- `DB` is a **singleton** — created once on the root and reused by every request, so you don't open a new pool per call.
+- `REQUEST_ID` and `USERS` are **scoped** — a new instance per child, so each request gets isolated state even though the providers are declared once on the root.
+- `REQUEST` is a per-request **value** registered on the child, and the scoped `REQUEST_ID` resolves it from that same child.
+- The child's `dispose()` releases only that request's scoped instances; the shared pool stays open until `root.dispose()` runs on `onClose`.
+
+## Error handling
+
+All errors extend the shared `DiError` base class, so you can catch any container error with a single check:
+
+```ts
+import { DiError, MissingProviderError } from "di-craft";
+
+try {
+  container.get(SOME_TOKEN);
+} catch (error) {
+  if (error instanceof MissingProviderError) {
+    // a specific failure
+  }
+
+  if (error instanceof DiError) {
+    // any di-craft error
+  }
+}
+```
+
+| Error                      | Thrown when                                              |
+| -------------------------- | -------------------------------------------------------- |
+| `MissingProviderError`     | A token is resolved but no provider is registered.       |
+| `DuplicateProviderError`   | A token is registered more than once.                    |
+| `CircularDependencyError`  | Providers form a dependency cycle.                       |
+| `InvalidDependencyError`   | A declared dependency token is missing/undefined.        |
+
+## API reference
+
+| Export                  | Description                                                |
+| ----------------------- | ---------------------------------------------------------- |
+| `createToken<T>(name)`  | Create a unique, typed token.                              |
+| `provideValue(token, value)` | Provider that returns an existing value.              |
+| `provideFactory(token, options)` | Provider that builds a value via a factory.       |
+| `createContainer(providers?)` | Create a container, optionally seeded with providers. |
+| `createChildContainer(parent, providers?)` | Create a child container that inherits from `parent`. |
+| `Scopes`                | Object of scope values (`Scopes.Singleton`, `Scopes.Transient`, `Scopes.Scoped`). |
+
+Exported types: `Container`, `Token`, `Provider`, `ValueProvider`, `FactoryProvider`, `Scope`, `DisposeHook`, `RegisterOptions`.
+
+Exported errors: `DiError`, `MissingProviderError`, `DuplicateProviderError`, `CircularDependencyError`, `InvalidDependencyError`.
+
+## License
+
+[MIT](./LICENSE)

package/dist/index.cjs

@@ -1,4 +1,221 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/error/error.ts
+var DiError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "DiError";
+		if (Error.captureStackTrace) Error.captureStackTrace(this, this.constructor);
+	}
+};
+//#endregion
+//#region src/registry/errors.ts
+var DuplicateProviderError = class extends DiError {
+	constructor(tokenName) {
+		super(`Provider for token "${tokenName}" is already registered`);
+		this.name = "DuplicateProviderError";
+	}
+};
+//#endregion
+//#region src/registry/registry.ts
+var RegistryClass = class {
+	providers = /* @__PURE__ */ new Map();
+	register(provider, options) {
+		if (!options?.allowOverride && this.providers.has(provider.provide.id)) throw new DuplicateProviderError(provider.provide.name);
+		this.providers.set(provider.provide.id, provider);
+	}
+	get(token) {
+		return this.providers.get(token.id);
+	}
+	has(token) {
+		return this.providers.has(token.id);
+	}
+};
+const createRegistry = () => new RegistryClass();
+//#endregion
+//#region src/resolver/errors.ts
+var MissingProviderError = class extends DiError {
+	constructor(tokenName) {
+		super(`Provider for token "${tokenName}" is not registered`);
+		this.name = "MissingProviderError";
+	}
+};
+var InvalidDependencyError = class extends DiError {
+	constructor(dependencyKey) {
+		super(`Invalid dependency "${dependencyKey}"`);
+		this.name = "InvalidDependencyError";
+	}
+};
+var CircularDependencyError = class extends DiError {
+	constructor(tokenNames) {
+		super(`Circular dependency detected: ${tokenNames.join(" -> ")}`);
+		this.name = "CircularDependencyError";
+	}
+};
+//#endregion
+//#region src/scope/scope.ts
+const Scopes = {
+	Singleton: "singleton",
+	Transient: "transient",
+	Scoped: "scoped"
+};
+//#endregion
+//#region src/provider/provider.ts
+const provideValue = (token, useValue) => ({
+	provide: token,
+	useValue
+});
+const provideFactory = (token, options) => {
+	return {
+		provide: token,
+		useFactory: options.useFactory,
+		scope: options.scope ?? Scopes.Singleton,
+		...options.deps ? { deps: options.deps } : {},
+		...options.onDispose ? { onDispose: options.onDispose } : {}
+	};
+};
+const isValueProvider = (provider) => {
+	return "useValue" in provider;
+};
+const isFactoryProvider = (provider) => {
+	return "useFactory" in provider;
+};
+//#endregion
+//#region src/store/store.ts
+var StoreClass = class {
+	instances = /* @__PURE__ */ new Map();
+	get(token) {
+		return this.instances.get(token.id);
+	}
+	set(token, record) {
+		this.instances.set(token.id, record);
+	}
+	delete(token) {
+		this.instances.delete(token.id);
+	}
+	async dispose() {
+		const records = [...this.instances.values()].reverse();
+		this.instances.clear();
+		for (const record of records) if (record.onDispose) await record.onDispose(record.value);
+	}
+};
+const createStore = () => new StoreClass();
+//#endregion
+//#region src/resolver/context.ts
+var ResolutionContext = class {
+	resolving = /* @__PURE__ */ new Set();
+	path = [];
+	enter(token) {
+		if (this.resolving.has(token.id)) {
+			const cycleStartIndex = this.path.findIndex((pathToken) => pathToken.id === token.id);
+			throw new CircularDependencyError([...this.path.slice(cycleStartIndex), token].map((cycleToken) => cycleToken.name));
+		}
+		this.resolving.add(token.id);
+		this.path.push(token);
+	}
+	exit(token) {
+		this.path.pop();
+		this.resolving.delete(token.id);
+	}
+};
+//#endregion
+//#region src/resolver/resolver.ts
+var ResolverClass = class {
+	registry;
+	store = createStore();
+	parent;
+	constructor(registry, parent) {
+		this.registry = registry;
+		this.parent = parent;
+	}
+	resolve(token) {
+		return this.resolveToken(token, new ResolutionContext());
+	}
+	invalidate(token) {
+		this.store.delete(token);
+	}
+	dispose() {
+		return this.store.dispose();
+	}
+	resolveToken(token, context) {
+		const owner = this.findOwner(token);
+		if (!owner) throw new MissingProviderError(token.name);
+		const provider = owner.registry.get(token);
+		if (!provider) throw new MissingProviderError(token.name);
+		if (isValueProvider(provider)) return provider.useValue;
+		if (isFactoryProvider(provider)) {
+			const host = this.selectHost(provider.scope, owner);
+			if (host) {
+				const cached = host.store.get(token);
+				if (cached) return cached.value;
+			}
+			context.enter(token);
+			try {
+				const deps = (host ?? this).resolveDeps(provider.deps, context);
+				const value = provider.useFactory(deps);
+				if (host) host.store.set(token, {
+					value,
+					...provider.onDispose ? { onDispose: provider.onDispose } : {}
+				});
+				return value;
+			} finally {
+				context.exit(token);
+			}
+		}
+		throw new MissingProviderError(token.name);
+	}
+	findOwner(token) {
+		let resolver = this;
+		while (resolver) {
+			if (resolver.registry.has(token)) return resolver;
+			resolver = resolver.parent;
+		}
+	}
+	selectHost(scope, owner) {
+		if (scope === Scopes.Transient) return;
+		if (scope === Scopes.Scoped) return this;
+		return owner;
+	}
+	resolveDeps(deps, context) {
+		if (!deps) return {};
+		const resolvedDeps = {};
+		for (const key of Object.keys(deps)) {
+			const token = deps[key];
+			if (token === void 0) throw new InvalidDependencyError(String(key));
+			resolvedDeps[key] = this.resolveToken(token, context);
+		}
+		return resolvedDeps;
+	}
+};
+const createResolver = (registry, parent) => new ResolverClass(registry, parent);
+//#endregion
+//#region src/container/container.ts
+var ContainerClass = class {
+	registry;
+	resolver;
+	parent;
+	constructor(providers = [], parent) {
+		this.parent = parent;
+		this.registry = createRegistry();
+		for (const provider of providers) this.registry.register(provider);
+		this.resolver = createResolver(this.registry, parent?.resolver);
+	}
+	register(provider, options) {
+		this.registry.register(provider, options);
+		if (options?.allowOverride) this.resolver.invalidate(provider.provide);
+	}
+	get(token) {
+		return this.resolver.resolve(token);
+	}
+	has(token) {
+		return this.registry.has(token) || (this.parent?.has(token) ?? false);
+	}
+	dispose() {
+		return this.resolver.dispose();
+	}
+};
+const createContainer = (providers = []) => new ContainerClass(providers);
+const createChildContainer = (parent, providers = []) => new ContainerClass(providers, parent);
+//#endregion
 //#region src/token/token.ts
 var TokenClass = class {
 	name;
@@ -10,4 +227,14 @@ var TokenClass = class {
 };
 const createToken = (name) => new TokenClass(name);
 //#endregion
+exports.CircularDependencyError = CircularDependencyError;
+exports.DiError = DiError;
+exports.DuplicateProviderError = DuplicateProviderError;
+exports.InvalidDependencyError = InvalidDependencyError;
+exports.MissingProviderError = MissingProviderError;
+exports.Scopes = Scopes;
+exports.createChildContainer = createChildContainer;
+exports.createContainer = createContainer;
 exports.createToken = createToken;
+exports.provideFactory = provideFactory;
+exports.provideValue = provideValue;

package/dist/index.d.cts

@@ -1,3 +1,11 @@
+//#region src/scope/scope.d.ts
+declare const Scopes: {
+  readonly Singleton: "singleton";
+  readonly Transient: "transient";
+  readonly Scoped: "scoped";
+};
+type Scope = (typeof Scopes)[keyof typeof Scopes];
+//#endregion
 //#region src/token/types.d.ts
 type Token<T> = {
   readonly id: symbol;
@@ -8,4 +16,71 @@ type Token<T> = {
 //#region src/token/token.d.ts
 declare const createToken: <T>(name: string) => Token<T>;
 //#endregion
-export { type Token, createToken };
+//#region src/provider/types.d.ts
+type DepsMap = Record<string, Token<unknown>>;
+type TokenValue<TToken> = TToken extends Token<infer TValue> ? TValue : never;
+type ResolveDeps<TDeps extends DepsMap> = { readonly [TKey in keyof TDeps]: TokenValue<TDeps[TKey]> };
+type Factory<T, TDeps extends DepsMap> = (deps: ResolveDeps<TDeps>) => T;
+type DisposeHook<T> = (instance: T) => void | Promise<void>;
+type ValueProvider<T> = {
+  readonly provide: Token<T>;
+  readonly useValue: T;
+};
+type FactoryProvider<T, TDeps extends DepsMap = Record<never, never>> = {
+  readonly provide: Token<T>;
+  readonly deps?: TDeps;
+  readonly scope?: Scope;
+  readonly useFactory: Factory<T, TDeps>;
+  readonly onDispose?: DisposeHook<T>;
+};
+type AnyFactoryProvider = FactoryProvider<any, any>;
+type Provider = ValueProvider<unknown> | AnyFactoryProvider;
+//#endregion
+//#region src/provider/provider.d.ts
+declare const provideValue: <T>(token: Token<T>, useValue: T) => ValueProvider<T>;
+declare const provideFactory: <T, TDeps extends DepsMap = Record<never, never>>(token: Token<T>, options: {
+  readonly deps?: TDeps;
+  readonly scope?: Scope;
+  readonly useFactory: Factory<T, TDeps>;
+  readonly onDispose?: DisposeHook<T>;
+}) => FactoryProvider<T, TDeps>;
+//#endregion
+//#region src/error/error.d.ts
+declare class DiError extends Error {
+  constructor(message: string);
+}
+//#endregion
+//#region src/registry/errors.d.ts
+declare class DuplicateProviderError extends DiError {
+  constructor(tokenName: string);
+}
+//#endregion
+//#region src/registry/types.d.ts
+type RegisterOptions = {
+  readonly allowOverride?: boolean;
+};
+//#endregion
+//#region src/container/types.d.ts
+type Container = {
+  register(provider: Provider, options?: RegisterOptions): void;
+  get<T>(token: Token<T>): T;
+  has(token: Token<unknown>): boolean;
+  dispose(): Promise<void>;
+};
+//#endregion
+//#region src/container/container.d.ts
+declare const createContainer: (providers?: readonly Provider[]) => Container;
+declare const createChildContainer: (parent: Container, providers?: readonly Provider[]) => Container;
+//#endregion
+//#region src/resolver/errors.d.ts
+declare class MissingProviderError extends DiError {
+  constructor(tokenName: string);
+}
+declare class InvalidDependencyError extends DiError {
+  constructor(dependencyKey: string);
+}
+declare class CircularDependencyError extends DiError {
+  constructor(tokenNames: string[]);
+}
+//#endregion
+export { CircularDependencyError, type Container, DiError, type DisposeHook, DuplicateProviderError, type FactoryProvider, InvalidDependencyError, MissingProviderError, type Provider, type RegisterOptions, type Scope, Scopes, type Token, type ValueProvider, createChildContainer, createContainer, createToken, provideFactory, provideValue };

package/dist/index.d.mts

@@ -1,3 +1,11 @@
+//#region src/scope/scope.d.ts
+declare const Scopes: {
+  readonly Singleton: "singleton";
+  readonly Transient: "transient";
+  readonly Scoped: "scoped";
+};
+type Scope = (typeof Scopes)[keyof typeof Scopes];
+//#endregion
 //#region src/token/types.d.ts
 type Token<T> = {
   readonly id: symbol;
@@ -8,4 +16,71 @@ type Token<T> = {
 //#region src/token/token.d.ts
 declare const createToken: <T>(name: string) => Token<T>;
 //#endregion
-export { type Token, createToken };
+//#region src/provider/types.d.ts
+type DepsMap = Record<string, Token<unknown>>;
+type TokenValue<TToken> = TToken extends Token<infer TValue> ? TValue : never;
+type ResolveDeps<TDeps extends DepsMap> = { readonly [TKey in keyof TDeps]: TokenValue<TDeps[TKey]> };
+type Factory<T, TDeps extends DepsMap> = (deps: ResolveDeps<TDeps>) => T;
+type DisposeHook<T> = (instance: T) => void | Promise<void>;
+type ValueProvider<T> = {
+  readonly provide: Token<T>;
+  readonly useValue: T;
+};
+type FactoryProvider<T, TDeps extends DepsMap = Record<never, never>> = {
+  readonly provide: Token<T>;
+  readonly deps?: TDeps;
+  readonly scope?: Scope;
+  readonly useFactory: Factory<T, TDeps>;
+  readonly onDispose?: DisposeHook<T>;
+};
+type AnyFactoryProvider = FactoryProvider<any, any>;
+type Provider = ValueProvider<unknown> | AnyFactoryProvider;
+//#endregion
+//#region src/provider/provider.d.ts
+declare const provideValue: <T>(token: Token<T>, useValue: T) => ValueProvider<T>;
+declare const provideFactory: <T, TDeps extends DepsMap = Record<never, never>>(token: Token<T>, options: {
+  readonly deps?: TDeps;
+  readonly scope?: Scope;
+  readonly useFactory: Factory<T, TDeps>;
+  readonly onDispose?: DisposeHook<T>;
+}) => FactoryProvider<T, TDeps>;
+//#endregion
+//#region src/error/error.d.ts
+declare class DiError extends Error {
+  constructor(message: string);
+}
+//#endregion
+//#region src/registry/errors.d.ts
+declare class DuplicateProviderError extends DiError {
+  constructor(tokenName: string);
+}
+//#endregion
+//#region src/registry/types.d.ts
+type RegisterOptions = {
+  readonly allowOverride?: boolean;
+};
+//#endregion
+//#region src/container/types.d.ts
+type Container = {
+  register(provider: Provider, options?: RegisterOptions): void;
+  get<T>(token: Token<T>): T;
+  has(token: Token<unknown>): boolean;
+  dispose(): Promise<void>;
+};
+//#endregion
+//#region src/container/container.d.ts
+declare const createContainer: (providers?: readonly Provider[]) => Container;
+declare const createChildContainer: (parent: Container, providers?: readonly Provider[]) => Container;
+//#endregion
+//#region src/resolver/errors.d.ts
+declare class MissingProviderError extends DiError {
+  constructor(tokenName: string);
+}
+declare class InvalidDependencyError extends DiError {
+  constructor(dependencyKey: string);
+}
+declare class CircularDependencyError extends DiError {
+  constructor(tokenNames: string[]);
+}
+//#endregion
+export { CircularDependencyError, type Container, DiError, type DisposeHook, DuplicateProviderError, type FactoryProvider, InvalidDependencyError, MissingProviderError, type Provider, type RegisterOptions, type Scope, Scopes, type Token, type ValueProvider, createChildContainer, createContainer, createToken, provideFactory, provideValue };

package/dist/index.mjs

@@ -1,3 +1,220 @@
+//#region src/error/error.ts
+var DiError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "DiError";
+		if (Error.captureStackTrace) Error.captureStackTrace(this, this.constructor);
+	}
+};
+//#endregion
+//#region src/registry/errors.ts
+var DuplicateProviderError = class extends DiError {
+	constructor(tokenName) {
+		super(`Provider for token "${tokenName}" is already registered`);
+		this.name = "DuplicateProviderError";
+	}
+};
+//#endregion
+//#region src/registry/registry.ts
+var RegistryClass = class {
+	providers = /* @__PURE__ */ new Map();
+	register(provider, options) {
+		if (!options?.allowOverride && this.providers.has(provider.provide.id)) throw new DuplicateProviderError(provider.provide.name);
+		this.providers.set(provider.provide.id, provider);
+	}
+	get(token) {
+		return this.providers.get(token.id);
+	}
+	has(token) {
+		return this.providers.has(token.id);
+	}
+};
+const createRegistry = () => new RegistryClass();
+//#endregion
+//#region src/resolver/errors.ts
+var MissingProviderError = class extends DiError {
+	constructor(tokenName) {
+		super(`Provider for token "${tokenName}" is not registered`);
+		this.name = "MissingProviderError";
+	}
+};
+var InvalidDependencyError = class extends DiError {
+	constructor(dependencyKey) {
+		super(`Invalid dependency "${dependencyKey}"`);
+		this.name = "InvalidDependencyError";
+	}
+};
+var CircularDependencyError = class extends DiError {
+	constructor(tokenNames) {
+		super(`Circular dependency detected: ${tokenNames.join(" -> ")}`);
+		this.name = "CircularDependencyError";
+	}
+};
+//#endregion
+//#region src/scope/scope.ts
+const Scopes = {
+	Singleton: "singleton",
+	Transient: "transient",
+	Scoped: "scoped"
+};
+//#endregion
+//#region src/provider/provider.ts
+const provideValue = (token, useValue) => ({
+	provide: token,
+	useValue
+});
+const provideFactory = (token, options) => {
+	return {
+		provide: token,
+		useFactory: options.useFactory,
+		scope: options.scope ?? Scopes.Singleton,
+		...options.deps ? { deps: options.deps } : {},
+		...options.onDispose ? { onDispose: options.onDispose } : {}
+	};
+};
+const isValueProvider = (provider) => {
+	return "useValue" in provider;
+};
+const isFactoryProvider = (provider) => {
+	return "useFactory" in provider;
+};
+//#endregion
+//#region src/store/store.ts
+var StoreClass = class {
+	instances = /* @__PURE__ */ new Map();
+	get(token) {
+		return this.instances.get(token.id);
+	}
+	set(token, record) {
+		this.instances.set(token.id, record);
+	}
+	delete(token) {
+		this.instances.delete(token.id);
+	}
+	async dispose() {
+		const records = [...this.instances.values()].reverse();
+		this.instances.clear();
+		for (const record of records) if (record.onDispose) await record.onDispose(record.value);
+	}
+};
+const createStore = () => new StoreClass();
+//#endregion
+//#region src/resolver/context.ts
+var ResolutionContext = class {
+	resolving = /* @__PURE__ */ new Set();
+	path = [];
+	enter(token) {
+		if (this.resolving.has(token.id)) {
+			const cycleStartIndex = this.path.findIndex((pathToken) => pathToken.id === token.id);
+			throw new CircularDependencyError([...this.path.slice(cycleStartIndex), token].map((cycleToken) => cycleToken.name));
+		}
+		this.resolving.add(token.id);
+		this.path.push(token);
+	}
+	exit(token) {
+		this.path.pop();
+		this.resolving.delete(token.id);
+	}
+};
+//#endregion
+//#region src/resolver/resolver.ts
+var ResolverClass = class {
+	registry;
+	store = createStore();
+	parent;
+	constructor(registry, parent) {
+		this.registry = registry;
+		this.parent = parent;
+	}
+	resolve(token) {
+		return this.resolveToken(token, new ResolutionContext());
+	}
+	invalidate(token) {
+		this.store.delete(token);
+	}
+	dispose() {
+		return this.store.dispose();
+	}
+	resolveToken(token, context) {
+		const owner = this.findOwner(token);
+		if (!owner) throw new MissingProviderError(token.name);
+		const provider = owner.registry.get(token);
+		if (!provider) throw new MissingProviderError(token.name);
+		if (isValueProvider(provider)) return provider.useValue;
+		if (isFactoryProvider(provider)) {
+			const host = this.selectHost(provider.scope, owner);
+			if (host) {
+				const cached = host.store.get(token);
+				if (cached) return cached.value;
+			}
+			context.enter(token);
+			try {
+				const deps = (host ?? this).resolveDeps(provider.deps, context);
+				const value = provider.useFactory(deps);
+				if (host) host.store.set(token, {
+					value,
+					...provider.onDispose ? { onDispose: provider.onDispose } : {}
+				});
+				return value;
+			} finally {
+				context.exit(token);
+			}
+		}
+		throw new MissingProviderError(token.name);
+	}
+	findOwner(token) {
+		let resolver = this;
+		while (resolver) {
+			if (resolver.registry.has(token)) return resolver;
+			resolver = resolver.parent;
+		}
+	}
+	selectHost(scope, owner) {
+		if (scope === Scopes.Transient) return;
+		if (scope === Scopes.Scoped) return this;
+		return owner;
+	}
+	resolveDeps(deps, context) {
+		if (!deps) return {};
+		const resolvedDeps = {};
+		for (const key of Object.keys(deps)) {
+			const token = deps[key];
+			if (token === void 0) throw new InvalidDependencyError(String(key));
+			resolvedDeps[key] = this.resolveToken(token, context);
+		}
+		return resolvedDeps;
+	}
+};
+const createResolver = (registry, parent) => new ResolverClass(registry, parent);
+//#endregion
+//#region src/container/container.ts
+var ContainerClass = class {
+	registry;
+	resolver;
+	parent;
+	constructor(providers = [], parent) {
+		this.parent = parent;
+		this.registry = createRegistry();
+		for (const provider of providers) this.registry.register(provider);
+		this.resolver = createResolver(this.registry, parent?.resolver);
+	}
+	register(provider, options) {
+		this.registry.register(provider, options);
+		if (options?.allowOverride) this.resolver.invalidate(provider.provide);
+	}
+	get(token) {
+		return this.resolver.resolve(token);
+	}
+	has(token) {
+		return this.registry.has(token) || (this.parent?.has(token) ?? false);
+	}
+	dispose() {
+		return this.resolver.dispose();
+	}
+};
+const createContainer = (providers = []) => new ContainerClass(providers);
+const createChildContainer = (parent, providers = []) => new ContainerClass(providers, parent);
+//#endregion
 //#region src/token/token.ts
 var TokenClass = class {
 	name;
@@ -9,4 +226,4 @@ var TokenClass = class {
 };
 const createToken = (name) => new TokenClass(name);
 //#endregion
-export { createToken };
+export { CircularDependencyError, DiError, DuplicateProviderError, InvalidDependencyError, MissingProviderError, Scopes, createChildContainer, createContainer, createToken, provideFactory, provideValue };

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "di-craft",
-	"version": "0.0.9",
-	"description": "A tiny TypeScript dependency injection container",
+	"version": "0.0.11",
+	"description": "A tiny, type-safe dependency injection container for TypeScript",
 	"license": "MIT",
 	"author": {
 		"name": "Egor Bezmen",