@codefast/di 0.3.13-canary.4

package/CHANGELOG.md

@@ -0,0 +1,59 @@
+# @codefast/di
+
+## 0.3.13-canary.4
+
+### Patch Changes
+
+- [`93b7399`](https://github.com/codefastlabs/codefast/commit/93b7399737eb2220866338da31023f95665021a0) Thanks [@thevuong](https://github.com/thevuong)! - feat(cli): enhance CLI structure and update dependencies
+
+- [`78d25cd`](https://github.com/codefastlabs/codefast/commit/78d25cd2bacd37f623ceeceb211375d2daf93541) Thanks [@thevuong](https://github.com/thevuong)! - docs(di): update README.md for clarity and structure
+
+- [`0542867`](https://github.com/codefastlabs/codefast/commit/054286713c242d3aa75eb7b6ad259693e266faed) Thanks [@thevuong](https://github.com/thevuong)! - feat(cli): add architecture graph and refine dependency injection
+
+- [`c458ff9`](https://github.com/codefastlabs/codefast/commit/c458ff9806426dd664ebfbc71dc387973f2aa2ef) Thanks [@thevuong](https://github.com/thevuong)! - test(di): add comprehensive unit tests for binding-select, binding, constraints, and dependency-graph modules
+
+- [`3d25484`](https://github.com/codefastlabs/codefast/commit/3d254841f2aad4e00d9e18da62369c659bdd88d6) Thanks [@thevuong](https://github.com/thevuong)! - refactor(di): enhance dependency graph generation and binding builder types
+
+- [`c5727bb`](https://github.com/codefastlabs/codefast/commit/c5727bb3d739bb68a829a550471cfb9fb6152da8) Thanks [@thevuong](https://github.com/thevuong)! - feat(di): add unit tests for DefaultContainer and ScopeManager
+
+- [`2ba60d2`](https://github.com/codefastlabs/codefast/commit/2ba60d256c93b2590984f3992d35b3d71c40d472) Thanks [@thevuong](https://github.com/thevuong)! - chore(knip): add knip configuration for dependency management
+
+- [`45426cf`](https://github.com/codefastlabs/codefast/commit/45426cf610c09764d2a0fbae394f8b997d0a3312) Thanks [@thevuong](https://github.com/thevuong)! - refactor(di): enhance type safety in dependency resolution
+
+- [`142cfbc`](https://github.com/codefastlabs/codefast/commit/142cfbc6a8e882824eacc14cbe84877a1c7c7d23) Thanks [@thevuong](https://github.com/thevuong)! - docs(di): expand examples in README.md for clarity and practical guidance
+
+- [`733dafa`](https://github.com/codefastlabs/codefast/commit/733dafadff88e32a82f00d44599efbb0771b7b6a) Thanks [@thevuong](https://github.com/thevuong)! - refactor(cli): reorganize imports for clarity and consistency
+
+- [`b8a9cca`](https://github.com/codefastlabs/codefast/commit/b8a9cca27306e0ce68bee5b47b61a49e568296ec) Thanks [@thevuong](https://github.com/thevuong)! - feat(di): introduce dependency injection package with core functionality
+
+- [`5c5c103`](https://github.com/codefastlabs/codefast/commit/5c5c10374fdfbd480047111fc0e6b90c027f7c8d) Thanks [@thevuong](https://github.com/thevuong)! - refactor(di): enhance documentation and type annotations for clarity
+
+- [`4248d75`](https://github.com/codefastlabs/codefast/commit/4248d75f2d547247dde937c322c2ed48d484f9e0) Thanks [@thevuong](https://github.com/thevuong)! - chore(tests): streamline test coverage commands and configurations
+
+- [`fa53c0b`](https://github.com/codefastlabs/codefast/commit/fa53c0b361200eadf6238d633c8b181fd165acec) Thanks [@thevuong](https://github.com/thevuong)! - test(cli): add integration tests for arrange, mirror, and tag modules
+
+- [`77c7b9c`](https://github.com/codefastlabs/codefast/commit/77c7b9c35960e7a3038185c7b9dfc2736e2868a9) Thanks [@thevuong](https://github.com/thevuong)! - refactor(di): rename DefaultContainer to Container and enhance validation logic
+
+- [`cf7055c`](https://github.com/codefastlabs/codefast/commit/cf7055c916ea7c630a41c13a0398a00bbaa12fd5) Thanks [@thevuong](https://github.com/thevuong)! - refactor(di): improve variable naming for clarity and consistency
+
+- [`2dd4641`](https://github.com/codefastlabs/codefast/commit/2dd464127708066e900deb42d88d6d38bd7849b2) Thanks [@thevuong](https://github.com/thevuong)! - refactor(di): replace DiError with InternalError for internal consistency
+
+- [`453bc2e`](https://github.com/codefastlabs/codefast/commit/453bc2ec63f65fe03cb77bdcc36ccbf8ef8cb3d0) Thanks [@thevuong](https://github.com/thevuong)! - refactor(di): enhance binding builder and module API for clarity and consistency
+
+- [`a626eb5`](https://github.com/codefastlabs/codefast/commit/a626eb58a56a73aab2e5cf79fba92e68d4080274) Thanks [@thevuong](https://github.com/thevuong)! - test(di): add comprehensive unit tests for Container and Module functionalities
+
+- [`2340231`](https://github.com/codefastlabs/codefast/commit/23402311084871d238ec50aa23061afd4b14e61e) Thanks [@thevuong](https://github.com/thevuong)! - refactor(imports): standardize import paths across applications and benchmarks
+
+- [`e0f6065`](https://github.com/codefastlabs/codefast/commit/e0f6065323255e2c1aa2c1e8f9c28a4b4c6e0ac2) Thanks [@thevuong](https://github.com/thevuong)! - refactor(di): standardize tag handling to use string keys only
+
+- [`35329d5`](https://github.com/codefastlabs/codefast/commit/35329d5f17682542e3ef0907d4936fa513346a72) Thanks [@thevuong](https://github.com/thevuong)! - feat(tsconfig): enforce module detection in TypeScript configuration
+
+- [`2fbf6a0`](https://github.com/codefastlabs/codefast/commit/2fbf6a07da06fd9383ab7c97fb69640a472fda19) Thanks [@thevuong](https://github.com/thevuong)! - refactor(di): improve error handling and serialization in dependency resolution
+
+- [`2c156bb`](https://github.com/codefastlabs/codefast/commit/2c156bbef480aa1c7f312289f25c7dd19bb971d1) Thanks [@thevuong](https://github.com/thevuong)! - refactor(di): simplify binding API and enhance type definitions
+
+- [`8120fd0`](https://github.com/codefastlabs/codefast/commit/8120fd034761f456e0706439172a7f50b4abfe1e) Thanks [@thevuong](https://github.com/thevuong)! - chore(di): update package.json and tsconfig.build.json for improved module resolution and type definitions
+
+- [`1a66f91`](https://github.com/codefastlabs/codefast/commit/1a66f911632ed23bd9a6fb3f178909ef23e44ea6) Thanks [@thevuong](https://github.com/thevuong)! - refactor(di): enhance index file with additional exports and type definitions
+
+- [`dea6bbc`](https://github.com/codefastlabs/codefast/commit/dea6bbcebaaecc09808c42b3f93e0fbf2296eb5b) Thanks [@thevuong](https://github.com/thevuong)! - refactor(di, theme): streamline imports and remove unused files

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 CodeFast Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,572 @@
+# @codefast/di
+
+Lightweight, type-safe dependency injection for TypeScript — powered by TC39 Stage 3 decorators and zero runtime reflection.
+
+[![CI](https://github.com/codefastlabs/codefast/actions/workflows/release.yml/badge.svg)](https://github.com/codefastlabs/codefast/actions/workflows/release.yml)
+[![npm version](https://img.shields.io/npm/v/@codefast/di.svg)](https://www.npmjs.com/package/@codefast/di)
+[![npm downloads](https://img.shields.io/npm/dm/@codefast/di.svg)](https://www.npmjs.com/package/@codefast/di)
+[![license](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Requirements](#requirements)
+- [Core Concepts](#core-concepts)
+- [Quick Start](#quick-start)
+- [Tokens](#tokens)
+- [Binding API](#binding-api)
+  - [Binding strategies](#binding-strategies)
+  - [Scopes](#scopes)
+  - [Lifecycle hooks](#lifecycle-hooks)
+  - [Constraints](#constraints)
+- [Decorators](#decorators)
+- [Container API](#container-api)
+  - [Resolution](#resolution)
+  - [Async resolution](#async-resolution)
+  - [Child containers](#child-containers)
+  - [Validation](#validation)
+  - [Introspection](#introspection)
+  - [Disposable resources](#disposable-resources)
+- [Modules](#modules)
+- [Error handling](#error-handling)
+- [Package exports](#package-exports)
+- [Contributing](#contributing)
+- [License](#license)
+- [Changelog](#changelog)
+
+---
+
+## Overview
+
+`@codefast/di` is a small **ESM-only** IoC container for TypeScript applications.
+
+**Key features:**
+
+- **Type-safe tokens** — `Token<Value>` ensures `resolve()` returns the exact type you registered; no accidental `get<WrongType>(…)` at compile time.
+- **TC39 Stage 3 decorators** — `@injectable`, `@inject`, `@optional`, `@singleton`, `@scoped` write metadata via `Symbol.metadata`. No `reflect-metadata`, no `experimentalDecorators`.
+- **Fluent binding API** — constants, classes, sync and async factories, scopes, tags, named hints, constraint predicates, and lifecycle hooks.
+- **Module system** — organize registrations into reusable `Module` / `AsyncModule` units.
+- **Scope safety** — detects singleton → transient/scoped captive dependencies in development.
+- **Async-first** — parallel inflight deduplication for async singleton initialization.
+- **Tree-shakeable subpaths** — import only the surface you need.
+
+---
+
+## Installation
+
+```bash
+# pnpm
+pnpm add @codefast/di
+
+# npm
+npm install @codefast/di
+```
+
+---
+
+## Requirements
+
+| Dependency | Version                       |
+| ---------- | ----------------------------- |
+| Node.js    | `>= 22.0.0`                   |
+| TypeScript | `>= 5.2` (Stage 3 decorators) |
+
+Enable native decorators in `tsconfig.json` (do **not** enable `experimentalDecorators`):
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "moduleResolution": "bundler"
+  }
+}
+```
+
+---
+
+## Core Concepts
+
+| Concept                | Description                                                                                                                                       |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Token**              | Branded key that pairs a name string with a TypeScript type. Tokens use reference equality — pass the same object to `bind` and `inject`.         |
+| **Binding**            | Associates a token (or constructor) with a value strategy (constant, class, factory, alias) and optional scope, constraints, and lifecycle hooks. |
+| **Container**          | Stores bindings in a `BindingRegistry` and resolves them on demand via a `DependencyResolver`.                                                    |
+| **Module**             | An immutable bundle of bindings. Loaded into any container and unloaded cleanly.                                                                  |
+| **Scope**              | Controls instance lifetime: `singleton` (one per container), `scoped` (one per child), or `transient` (new each time).                            |
+| **Decorator metadata** | `@injectable([…])` writes constructor dependency descriptors into `Symbol.metadata`, which the container reads at resolution time.                |
+
+---
+
+## Quick Start
+
+```typescript
+import { Container, inject, injectable, token } from "@codefast/di";
+
+// 1. Define an interface and a token for it
+interface Logger {
+  log(message: string): void;
+}
+
+const LoggerToken = token<Logger>("Logger");
+
+// 2. Implement and annotate the class
+@injectable([inject(LoggerToken)])
+class AppService {
+  constructor(private readonly logger: Logger) {}
+
+  run(): void {
+    this.logger.log("App started");
+  }
+}
+
+// 3. Create a container and register bindings
+const container = Container.create();
+
+container.bind(LoggerToken).toConstantValue({ log: console.log });
+container.bind(AppService).toSelf().singleton();
+
+// 4. Resolve and use
+const app = container.resolve(AppService);
+app.run(); // "App started"
+```
+
+---
+
+## Tokens
+
+A `Token<Value>` is a branded object that acts as a type-safe registry key.
+
+```typescript
+import { token } from "@codefast/di";
+
+const DbToken = token<Database>("Database");
+const CacheToken = token<Cache>("Cache");
+```
+
+The type parameter flows through the binding and resolution chain — `container.resolve(DbToken)` returns `Database`, not `unknown`.
+
+> **Token identity** — tokens use reference equality. Always import and reuse the same `const` value for both `bind()` and `inject()`. Creating two tokens with the same name produces two distinct keys.
+
+You can also use a constructor directly as a key:
+
+```typescript
+container.bind(MyService).toSelf();
+container.resolve(MyService); // returns MyService
+```
+
+---
+
+## Binding API
+
+### Binding strategies
+
+Start a binding with `container.bind(key)` and chain a strategy method:
+
+| Method                       | Description                                                            |
+| ---------------------------- | ---------------------------------------------------------------------- |
+| `.toConstantValue(value)`    | Bind to a fixed value. Always treated as singleton.                    |
+| `.toSelf()`                  | Bind a constructor to itself. Reads `@injectable()` metadata.          |
+| `.to(Constructor)`           | Bind a token to a class constructor.                                   |
+| `.toDynamic(factory)`        | Bind to a synchronous factory `(ctx: ResolutionContext) => Value`.     |
+| `.toDynamicAsync(factory)`   | Bind to an async factory `(ctx: ResolutionContext) => Promise<Value>`. |
+| `.toResolved(factory, deps)` | Bind to a factory with an explicit typed dependency array.             |
+| `.toAlias(targetToken)`      | Redirect this token to another token.                                  |
+
+```typescript
+// Constant
+container.bind(AppConfigToken).toConstantValue({ port: 3000 });
+
+// Class
+container.bind(UserRepository).toSelf().singleton();
+container.bind(UserServiceToken).to(UserService).transient();
+
+// Factory — receive resolution context to resolve nested deps
+container.bind(DbToken).toDynamic((ctx) => {
+  const config = ctx.resolve(AppConfigToken);
+  return new Database(config.dbUrl);
+});
+
+// Async factory
+container.bind(DbToken).toDynamicAsync(async (ctx) => {
+  const config = ctx.resolve(AppConfigToken);
+  const db = new Database(config.dbUrl);
+  await db.connect();
+  return db;
+});
+
+// Alias
+container.bind(LegacyServiceToken).toAlias(NewServiceToken);
+```
+
+### Scopes
+
+After setting the strategy, chain a scope method:
+
+| Method         | Lifetime                                                                    |
+| -------------- | --------------------------------------------------------------------------- |
+| `.singleton()` | One instance per container. Created once, reused forever.                   |
+| `.transient()` | New instance on every `resolve()`. Default for most bindings.               |
+| `.scoped()`    | One instance per child container scope. Useful for request-scoped services. |
+
+```typescript
+container.bind(DatabaseToken).toDynamic(createDb).singleton();
+container.bind(RequestContextToken).toSelf().scoped();
+container.bind(QueryBuilderToken).toSelf().transient();
+```
+
+### Lifecycle hooks
+
+Attach activation and deactivation callbacks to any binding:
+
+```typescript
+container
+  .bind(DbToken)
+  .toDynamicAsync(async (ctx) => new Database(ctx.resolve(ConfigToken)))
+  .singleton()
+  .onActivation(async (instance, ctx) => {
+    await instance.connect();
+    return instance; // must return the instance
+  })
+  .onDeactivation(async (instance) => {
+    await instance.disconnect();
+  });
+```
+
+`onActivation` runs after the instance is created. It must return the (optionally modified) instance.
+`onDeactivation` runs when `container.dispose()` is called.
+
+### Constraints
+
+Constraints let multiple bindings share the same token and select one based on resolution context.
+
+**Named bindings** — disambiguate with a string name:
+
+```typescript
+container.bind(LoggerToken).toConstantValue(fileLogger).whenNamed("file");
+container.bind(LoggerToken).toConstantValue(consoleLogger).whenNamed("console");
+
+// Resolve by name
+container.resolve(LoggerToken, { name: "file" });
+```
+
+**Tagged bindings** — disambiguate with a tag + value pair:
+
+```typescript
+container.bind(StorageToken).to(S3Storage).whenTagged("provider", "s3");
+container.bind(StorageToken).to(LocalStorage).whenTagged("provider", "local");
+
+container.resolve(StorageToken, { tag: "provider", tagValue: "s3" });
+```
+
+**Custom predicate** — inspect the full resolution context:
+
+```typescript
+import { whenParentIs } from "@codefast/di";
+
+container.bind(LoggerToken).toConstantValue(verboseLogger).when(whenParentIs(DiagnosticsService));
+```
+
+Built-in predicate helpers:
+
+| Helper                         | Description                                                        |
+| ------------------------------ | ------------------------------------------------------------------ |
+| `whenParentIs(key)`            | Matches when the direct parent binding is for the given key.       |
+| `whenAnyAncestorIs(key)`       | Matches when any ancestor binding is for the given key.            |
+| `whenTargetTagged(tag, value)` | Matches when the immediate parent was injected with the given tag. |
+
+---
+
+## Decorators
+
+Decorators use TC39 Stage 3 syntax and write metadata to `Symbol.metadata`.
+
+### `@injectable(deps)`
+
+Registers constructor dependency metadata. Every dependency must be listed.
+
+```typescript
+import { inject, injectable, optional, token } from "@codefast/di";
+
+const ConfigToken = token<AppConfig>("AppConfig");
+const CacheToken = token<Cache>("Cache");
+
+@injectable([inject(ConfigToken), optional(CacheToken)])
+class AppService {
+  constructor(
+    private readonly config: AppConfig,
+    private readonly cache?: Cache,
+  ) {}
+}
+```
+
+- `inject(token, options?)` — required dependency. Throws `TokenNotBoundError` if absent.
+- `optional(token, options?)` — optional dependency. Resolves to `undefined` if not bound.
+
+Both accept `InjectOptions` for named or tagged resolution hints:
+
+```typescript
+inject(LoggerToken, { name: "console" });
+inject(StorageToken, { tag: "provider", tagValue: "s3" });
+```
+
+### `@singleton()` and `@scoped()`
+
+Scope hints on the class itself. The container reads these when you call `.to(Constructor)` without chaining an explicit scope method.
+
+```typescript
+@singleton()
+@injectable([inject(DbToken)])
+class UserRepository {
+  constructor(private readonly db: Database) {}
+}
+
+// No .singleton() needed — decorator provides the hint
+container.bind(UserRepository).toSelf();
+```
+
+`@singleton()` and `@scoped()` cannot be combined on the same class.
+
+---
+
+## Container API
+
+### Resolution
+
+```typescript
+const container = Container.create();
+
+// Single binding
+const service = container.resolve(ServiceToken);
+
+// Named or tagged hint
+const logger = container.resolve(LoggerToken, { name: "console" });
+
+// All matching bindings
+const handlers = container.resolveAll(HandlerToken);
+
+// Optional — returns undefined if not bound
+const cache = container.resolveOptional(CacheToken);
+```
+
+Check binding existence before resolving:
+
+```typescript
+if (container.has(CacheToken)) {
+  const cache = container.resolve(CacheToken);
+}
+```
+
+### Async resolution
+
+Use `resolveAsync` / `resolveAllAsync` / `resolveOptionalAsync` when any dependency in the chain uses `toDynamicAsync`:
+
+```typescript
+const db = await container.resolveAsync(DbToken);
+const handlers = await container.resolveAllAsync(HandlerToken);
+```
+
+### Rebinding and unbinding
+
+```typescript
+// Replace all bindings for a token
+container.rebind(LoggerToken).toConstantValue(testLogger);
+
+// Remove bindings (sync)
+container.unbind(CacheToken);
+
+// Remove with deactivation hooks (async)
+await container.unbindAsync(CacheToken);
+```
+
+### Child containers
+
+Child containers share the parent's singleton cache but maintain an isolated scoped cache — ideal for per-request isolation.
+
+```typescript
+const requestContainer = container.createChild();
+
+requestContainer.bind(RequestContextToken).toConstantValue(req).scoped();
+
+const service = requestContainer.resolve(RequestScopedService);
+
+// Clean up scoped instances
+await requestContainer.dispose();
+```
+
+### Validation
+
+`validate()` checks for captive dependency violations (a singleton depending on a transient or scoped binding). In development and test environments this runs automatically after `load()` and the first `resolve()`.
+
+```typescript
+container.validate(); // throws ScopeViolationError if invalid
+```
+
+### Introspection
+
+```typescript
+// Snapshot of all registered bindings
+const snapshot = container.inspect();
+
+// Graphviz DOT format for dependency graph visualization
+const dot = container.generateDependencyGraphDot({ hideInternals: true });
+
+// JSON format
+const graph = container.generateDependencyGraphJson();
+```
+
+### Disposable resources
+
+`Container` implements `AsyncDisposable`, enabling `await using` syntax:
+
+```typescript
+{
+  await using container = Container.create();
+  container.bind(DbToken).toDynamicAsync(connectDb).singleton().onDeactivation(disconnectDb);
+
+  const db = await container.resolveAsync(DbToken);
+  // ...
+} // container.dispose() called automatically — runs all deactivation hooks
+```
+
+Or call explicitly:
+
+```typescript
+await container.dispose();
+```
+
+---
+
+## Modules
+
+Modules group related bindings into reusable, composable units.
+
+### Synchronous modules
+
+```typescript
+import { Module } from "@codefast/di";
+
+const InfraModule = Module.create("Infra", (api) => {
+  api.bind(LoggerToken).toConstantValue(console);
+  api.bind(ConfigToken).toConstantValue(loadConfig());
+});
+
+const AppModule = Module.create("App", (api) => {
+  api.import(InfraModule); // load dependency module
+  api.bind(UserRepository).toSelf().singleton();
+  api.bind(UserServiceToken).to(UserService).transient();
+});
+
+const container = Container.fromModules(AppModule);
+```
+
+### Async modules
+
+```typescript
+import { Module } from "@codefast/di";
+
+const DbModule = Module.createAsync("Database", async (api) => {
+  const config = await fetchRemoteConfig();
+  api.bind(DbToken).toConstantValue(await Database.connect(config.dbUrl));
+});
+
+const container = await Container.fromModulesAsync(DbModule, AppModule);
+```
+
+`Module.createAsync` returns an `AsyncModule`. Use `Container.fromModulesAsync` (or `container.loadAsync`) to load async modules.
+
+### Loading and unloading
+
+```typescript
+// Load into existing container
+container.load(InfraModule, AppModule);
+await container.loadAsync(DbModule);
+
+// Remove and run deactivation hooks
+container.unload(AppModule);
+await container.unloadAsync(DbModule);
+```
+
+---
+
+## Error handling
+
+All errors extend `DiError` and expose a stable `code` property for `switch` / `instanceof` checks.
+
+| Error class               | `code`                  | When thrown                                         |
+| ------------------------- | ----------------------- | --------------------------------------------------- |
+| `TokenNotBoundError`      | `"TOKEN_NOT_BOUND"`     | `resolve()` called for an unregistered token        |
+| `NoMatchingBindingError`  | `"NO_MATCHING_BINDING"` | Name/tag hint matches no binding                    |
+| `CircularDependencyError` | `"CIRCULAR_DEPENDENCY"` | Circular dependency detected during resolution      |
+| `MissingMetadataError`    | `"MISSING_METADATA"`    | Class binding lacks `@injectable()` metadata        |
+| `AsyncModuleLoadError`    | `"ASYNC_MODULE_LOAD"`   | `load()` (sync) called with an `AsyncModule`        |
+| `AsyncResolutionError`    | `"ASYNC_RESOLUTION"`    | Async dependency encountered during sync resolution |
+| `ScopeViolationError`     | `"SCOPE_VIOLATION"`     | Singleton depends on transient/scoped binding       |
+
+```typescript
+import { DiError, TokenNotBoundError, ScopeViolationError } from "@codefast/di";
+
+try {
+  const service = container.resolve(ServiceToken);
+} catch (error) {
+  if (error instanceof TokenNotBoundError) {
+    console.error(`Not registered: ${error.tokenName}`);
+  } else if (error instanceof DiError) {
+    console.error(`DI error [${error.code}]: ${error.message}`);
+  }
+}
+```
+
+---
+
+## Package exports
+
+The root entry `@codefast/di` re-exports the complete public API. Subpath exports are available for fine-grained imports and tree-shaking:
+
+| Subpath                              | Contents                                                     |
+| ------------------------------------ | ------------------------------------------------------------ |
+| `@codefast/di`                       | Full public façade — everything below, combined              |
+| `@codefast/di/container`             | `Container` interface, `DefaultContainer`, and related types |
+| `@codefast/di/token`                 | `token()`, `Token<Value>`, `TokenValue`                      |
+| `@codefast/di/binding`               | `BindingBuilder`, `bind()`, binding type definitions         |
+| `@codefast/di/binding-select`        | `filterMatchingBindings`, `selectBindingForRegistry`         |
+| `@codefast/di/module`                | `Module`, `AsyncModule`, module builder types                |
+| `@codefast/di/decorators`            | `@injectable`, `@singleton`, `@scoped`, `inject`, `optional` |
+| `@codefast/di/decorators/inject`     | `inject`, `optional`, `isInjectionDescriptor`                |
+| `@codefast/di/decorators/injectable` | `@injectable`                                                |
+| `@codefast/di/decorators/singleton`  | `@singleton`                                                 |
+| `@codefast/di/decorators/scoped`     | `@scoped`                                                    |
+| `@codefast/di/registry`              | `BindingRegistry`, `registryKeyLabel`                        |
+| `@codefast/di/resolver`              | Resolution internals                                         |
+| `@codefast/di/scope`                 | `ScopeManager`, scope cache management                       |
+| `@codefast/di/scope-validation`      | `validateScopeRules`                                         |
+| `@codefast/di/lifecycle`             | `runActivation`, `runActivationAsync`, activation types      |
+| `@codefast/di/constraints`           | `whenParentIs`, `whenAnyAncestorIs`, `whenTargetTagged`      |
+| `@codefast/di/dependency-graph`      | `collectStaticDependencyEdges`, `listResolvedDependencies`   |
+| `@codefast/di/inspector`             | `ContainerInspector`, `ContainerSnapshot`                    |
+| `@codefast/di/errors`                | Complete `DiError` hierarchy                                 |
+| `@codefast/di/environment`           | `isDevelopmentOrTestEnvironment`, `isProductionEnvironment`  |
+
+See `package.json → exports` for the authoritative list.
+
+---
+
+## Contributing
+
+This package lives in the [Codefast monorepo](https://github.com/codefastlabs/codefast). From the repo root:
+
+```bash
+pnpm --filter @codefast/di build
+pnpm --filter @codefast/di test
+```
+
+---
+
+## License
+
+[MIT](https://opensource.org/licenses/MIT) — see `license` in [`package.json`](./package.json).
+
+## Changelog
+
+Version history is published on [npm](https://www.npmjs.com/package/@codefast/di?activeTab=versions) with each release.

package/dist/binding-select.d.mts

@@ -0,0 +1,22 @@
+import { Token } from "./token.mjs";
+import { RegistryKey } from "./registry.mjs";
+import { Binding, ConstraintContext, Constructor, ResolveHint } from "./binding.mjs";
+
+//#region src/binding-select.d.ts
+/** Returns a human-readable label for a token or constructor (used in error messages and graph output). */
+declare function registryKeyLabel(key: Token<unknown> | Constructor<unknown>): string;
+/**
+ * Applies resolve hints and optional constraint predicates to a binding list.
+ */
+declare function filterMatchingBindings(bindings: readonly Binding<unknown>[], hint: ResolveHint | undefined, constraintCtx: ConstraintContext | undefined): Binding<unknown>[];
+/**
+ * Picks the binding that would be used for resolution with the given hint (same rules as {@link DependencyResolver}).
+ * When `constraintCtx` is set, bindings with a {@link BindingBuilder.when} predicate must pass it.
+ */
+declare function selectBindingForRegistry(bindings: readonly Binding<unknown>[], hint: ResolveHint | undefined, tokenLabel: string, pathLabels: readonly string[], constraintCtx: ConstraintContext | undefined): Binding<unknown>;
+/**
+ * Resolves the effective binding for a registry key using the default (no-hint) selection rules.
+ */
+declare function selectDefaultBindingForKey(lookup: (key: RegistryKey) => readonly Binding<unknown>[] | undefined, key: RegistryKey, pathPrefix: readonly string[]): Binding<unknown>;
+//#endregion
+export { filterMatchingBindings, registryKeyLabel, selectBindingForRegistry, selectDefaultBindingForKey };