di-craft 0.0.10 → 0.0.11

package/README.md

@@ -2,6 +2,31 @@
 
 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,
@@ -34,23 +59,17 @@ const users = container.get(USERS); // UserService, fully typed
 
 ## Philosophy
 
-`di-craft` is a small DI container with no magic.
-
-- No decorators
-- No `reflect-metadata`
-- No framework dependencies
-
-Just **tokens**, **providers**, a **container**, **scopes**, and **cycle detection**.
+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`
-- Framework agnostic
-- 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
@@ -104,15 +123,34 @@ The keys in `deps` become the keys of the object passed to `useFactory`, each re
 
 ### 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 });
 ```
 
-Registering the same token twice throws `DuplicateProviderError`.
+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
 
@@ -120,10 +158,15 @@ Registering the same token twice throws `DuplicateProviderError`.
 | ---------------------- | ---------------------------------------------------------------- |
 | `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: "transient",
+  scope: Scopes.Transient, // or scope: "transient"
   useFactory: () => crypto.randomUUID(),
 });
 
@@ -132,6 +175,69 @@ 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.
@@ -141,6 +247,87 @@ If providers form a dependency cycle, resolution throws `CircularDependencyError
 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:
@@ -176,8 +363,10 @@ try {
 | `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`.
+Exported types: `Container`, `Token`, `Provider`, `ValueProvider`, `FactoryProvider`, `Scope`, `DisposeHook`, `RegisterOptions`.
 
 Exported errors: `DiError`, `MissingProviderError`, `DuplicateProviderError`, `CircularDependencyError`, `InvalidDependencyError`.
 

package/dist/index.cjs

@@ -19,8 +19,8 @@ var DuplicateProviderError = class extends DiError {
 //#region src/registry/registry.ts
 var RegistryClass = class {
 	providers = /* @__PURE__ */ new Map();
-	register(provider) {
-		if (this.providers.has(provider.provide.id)) throw new DuplicateProviderError(provider.provide.name);
+	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) {
@@ -52,6 +52,13 @@ var CircularDependencyError = class extends DiError {
 	}
 };
 //#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,
@@ -61,8 +68,9 @@ const provideFactory = (token, options) => {
 	return {
 		provide: token,
 		useFactory: options.useFactory,
+		scope: options.scope ?? Scopes.Singleton,
 		...options.deps ? { deps: options.deps } : {},
-		...options.scope ? { scope: options.scope } : {}
+		...options.onDispose ? { onDispose: options.onDispose } : {}
 	};
 };
 const isValueProvider = (provider) => {
@@ -72,44 +80,101 @@ 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;
-	instances = /* @__PURE__ */ new Map();
-	constructor(registry) {
+	store = createStore();
+	parent;
+	constructor(registry, parent) {
 		this.registry = registry;
+		this.parent = parent;
 	}
 	resolve(token) {
-		return this.resolveToken(token, {
-			resolving: /* @__PURE__ */ new Set(),
-			path: []
-		});
+		return this.resolveToken(token, new ResolutionContext());
+	}
+	invalidate(token) {
+		this.store.delete(token);
+	}
+	dispose() {
+		return this.store.dispose();
 	}
 	resolveToken(token, context) {
-		const provider = this.registry.get(token);
+		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 scope = provider.scope ?? "singleton";
-			if (scope === "singleton" && this.instances.has(token.id)) return this.instances.get(token.id);
-			if (context.resolving.has(token.id)) {
-				const cycleStartIndex = context.path.findIndex((pathToken) => pathToken.id === token.id);
-				throw new CircularDependencyError([...context.path.slice(cycleStartIndex), token].map((cycleToken) => cycleToken.name));
+			const host = this.selectHost(provider.scope, owner);
+			if (host) {
+				const cached = host.store.get(token);
+				if (cached) return cached.value;
 			}
-			context.resolving.add(token.id);
-			context.path.push(token);
+			context.enter(token);
 			try {
-				const deps = this.resolveDeps(provider.deps, context);
+				const deps = (host ?? this).resolveDeps(provider.deps, context);
 				const value = provider.useFactory(deps);
-				if (scope === "singleton") this.instances.set(token.id, value);
+				if (host) host.store.set(token, {
+					value,
+					...provider.onDispose ? { onDispose: provider.onDispose } : {}
+				});
 				return value;
 			} finally {
-				context.path.pop();
-				context.resolving.delete(token.id);
+				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 = {};
@@ -121,28 +186,35 @@ var ResolverClass = class {
 		return resolvedDeps;
 	}
 };
-const createResolver = (registry) => new ResolverClass(registry);
+const createResolver = (registry, parent) => new ResolverClass(registry, parent);
 //#endregion
 //#region src/container/container.ts
 var ContainerClass = class {
 	registry;
 	resolver;
-	constructor(providers = []) {
+	parent;
+	constructor(providers = [], parent) {
+		this.parent = parent;
 		this.registry = createRegistry();
 		for (const provider of providers) this.registry.register(provider);
-		this.resolver = createResolver(this.registry);
+		this.resolver = createResolver(this.registry, parent?.resolver);
 	}
-	register(provider) {
-		this.registry.register(provider);
+	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);
+		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 {
@@ -160,6 +232,8 @@ 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;

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;
@@ -13,6 +21,7 @@ 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;
@@ -22,10 +31,10 @@ type FactoryProvider<T, TDeps extends DepsMap = Record<never, never>> = {
   readonly deps?: TDeps;
   readonly scope?: Scope;
   readonly useFactory: Factory<T, TDeps>;
+  readonly onDispose?: DisposeHook<T>;
 };
-type AnyFactoryProvider = FactoryProvider<unknown, any>;
+type AnyFactoryProvider = FactoryProvider<any, any>;
 type Provider = ValueProvider<unknown> | AnyFactoryProvider;
-type Scope = "singleton" | "transient";
 //#endregion
 //#region src/provider/provider.d.ts
 declare const provideValue: <T>(token: Token<T>, useValue: T) => ValueProvider<T>;
@@ -33,18 +42,9 @@ declare const provideFactory: <T, TDeps extends DepsMap = Record<never, never>>(
   readonly deps?: TDeps;
   readonly scope?: Scope;
   readonly useFactory: Factory<T, TDeps>;
+  readonly onDispose?: DisposeHook<T>;
 }) => FactoryProvider<T, TDeps>;
 //#endregion
-//#region src/container/types.d.ts
-type Container = {
-  register(provider: Provider): void;
-  get<T>(token: Token<T>): T;
-  has(token: Token<unknown>): boolean;
-};
-//#endregion
-//#region src/container/container.d.ts
-declare const createContainer: (providers?: readonly Provider[]) => Container;
-//#endregion
 //#region src/error/error.d.ts
 declare class DiError extends Error {
   constructor(message: string);
@@ -55,6 +55,23 @@ 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);
@@ -66,4 +83,4 @@ declare class CircularDependencyError extends DiError {
   constructor(tokenNames: string[]);
 }
 //#endregion
-export { CircularDependencyError, type Container, DiError, DuplicateProviderError, type FactoryProvider, InvalidDependencyError, MissingProviderError, type Provider, type Scope, type Token, type ValueProvider, createContainer, createToken, provideFactory, provideValue };
+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;
@@ -13,6 +21,7 @@ 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;
@@ -22,10 +31,10 @@ type FactoryProvider<T, TDeps extends DepsMap = Record<never, never>> = {
   readonly deps?: TDeps;
   readonly scope?: Scope;
   readonly useFactory: Factory<T, TDeps>;
+  readonly onDispose?: DisposeHook<T>;
 };
-type AnyFactoryProvider = FactoryProvider<unknown, any>;
+type AnyFactoryProvider = FactoryProvider<any, any>;
 type Provider = ValueProvider<unknown> | AnyFactoryProvider;
-type Scope = "singleton" | "transient";
 //#endregion
 //#region src/provider/provider.d.ts
 declare const provideValue: <T>(token: Token<T>, useValue: T) => ValueProvider<T>;
@@ -33,18 +42,9 @@ declare const provideFactory: <T, TDeps extends DepsMap = Record<never, never>>(
   readonly deps?: TDeps;
   readonly scope?: Scope;
   readonly useFactory: Factory<T, TDeps>;
+  readonly onDispose?: DisposeHook<T>;
 }) => FactoryProvider<T, TDeps>;
 //#endregion
-//#region src/container/types.d.ts
-type Container = {
-  register(provider: Provider): void;
-  get<T>(token: Token<T>): T;
-  has(token: Token<unknown>): boolean;
-};
-//#endregion
-//#region src/container/container.d.ts
-declare const createContainer: (providers?: readonly Provider[]) => Container;
-//#endregion
 //#region src/error/error.d.ts
 declare class DiError extends Error {
   constructor(message: string);
@@ -55,6 +55,23 @@ 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);
@@ -66,4 +83,4 @@ declare class CircularDependencyError extends DiError {
   constructor(tokenNames: string[]);
 }
 //#endregion
-export { CircularDependencyError, type Container, DiError, DuplicateProviderError, type FactoryProvider, InvalidDependencyError, MissingProviderError, type Provider, type Scope, type Token, type ValueProvider, createContainer, createToken, provideFactory, provideValue };
+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

@@ -18,8 +18,8 @@ var DuplicateProviderError = class extends DiError {
 //#region src/registry/registry.ts
 var RegistryClass = class {
 	providers = /* @__PURE__ */ new Map();
-	register(provider) {
-		if (this.providers.has(provider.provide.id)) throw new DuplicateProviderError(provider.provide.name);
+	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) {
@@ -51,6 +51,13 @@ var CircularDependencyError = class extends DiError {
 	}
 };
 //#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,
@@ -60,8 +67,9 @@ const provideFactory = (token, options) => {
 	return {
 		provide: token,
 		useFactory: options.useFactory,
+		scope: options.scope ?? Scopes.Singleton,
 		...options.deps ? { deps: options.deps } : {},
-		...options.scope ? { scope: options.scope } : {}
+		...options.onDispose ? { onDispose: options.onDispose } : {}
 	};
 };
 const isValueProvider = (provider) => {
@@ -71,44 +79,101 @@ 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;
-	instances = /* @__PURE__ */ new Map();
-	constructor(registry) {
+	store = createStore();
+	parent;
+	constructor(registry, parent) {
 		this.registry = registry;
+		this.parent = parent;
 	}
 	resolve(token) {
-		return this.resolveToken(token, {
-			resolving: /* @__PURE__ */ new Set(),
-			path: []
-		});
+		return this.resolveToken(token, new ResolutionContext());
+	}
+	invalidate(token) {
+		this.store.delete(token);
+	}
+	dispose() {
+		return this.store.dispose();
 	}
 	resolveToken(token, context) {
-		const provider = this.registry.get(token);
+		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 scope = provider.scope ?? "singleton";
-			if (scope === "singleton" && this.instances.has(token.id)) return this.instances.get(token.id);
-			if (context.resolving.has(token.id)) {
-				const cycleStartIndex = context.path.findIndex((pathToken) => pathToken.id === token.id);
-				throw new CircularDependencyError([...context.path.slice(cycleStartIndex), token].map((cycleToken) => cycleToken.name));
+			const host = this.selectHost(provider.scope, owner);
+			if (host) {
+				const cached = host.store.get(token);
+				if (cached) return cached.value;
 			}
-			context.resolving.add(token.id);
-			context.path.push(token);
+			context.enter(token);
 			try {
-				const deps = this.resolveDeps(provider.deps, context);
+				const deps = (host ?? this).resolveDeps(provider.deps, context);
 				const value = provider.useFactory(deps);
-				if (scope === "singleton") this.instances.set(token.id, value);
+				if (host) host.store.set(token, {
+					value,
+					...provider.onDispose ? { onDispose: provider.onDispose } : {}
+				});
 				return value;
 			} finally {
-				context.path.pop();
-				context.resolving.delete(token.id);
+				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 = {};
@@ -120,28 +185,35 @@ var ResolverClass = class {
 		return resolvedDeps;
 	}
 };
-const createResolver = (registry) => new ResolverClass(registry);
+const createResolver = (registry, parent) => new ResolverClass(registry, parent);
 //#endregion
 //#region src/container/container.ts
 var ContainerClass = class {
 	registry;
 	resolver;
-	constructor(providers = []) {
+	parent;
+	constructor(providers = [], parent) {
+		this.parent = parent;
 		this.registry = createRegistry();
 		for (const provider of providers) this.registry.register(provider);
-		this.resolver = createResolver(this.registry);
+		this.resolver = createResolver(this.registry, parent?.resolver);
 	}
-	register(provider) {
-		this.registry.register(provider);
+	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);
+		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 {
@@ -154,4 +226,4 @@ var TokenClass = class {
 };
 const createToken = (name) => new TokenClass(name);
 //#endregion
-export { CircularDependencyError, DiError, DuplicateProviderError, InvalidDependencyError, MissingProviderError, createContainer, createToken, provideFactory, provideValue };
+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.10",
-	"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",