@nextrush/di 3.0.6 → 4.0.0-beta.0

package/README.md

@@ -1,481 +1,397 @@
 # @nextrush/di
 
-Lightweight dependency injection container for NextRush v3.
+> A lightweight dependency-injection container for NextRush — decorator-driven constructor injection over `tsyringe`, with singleton / transient / request scopes and errors that tell you how to fix them.
+
+[![npm version](https://img.shields.io/npm/v/@nextrush/di.svg)](https://www.npmjs.com/package/@nextrush/di)
+[![downloads](https://img.shields.io/npm/dm/@nextrush/di.svg)](https://www.npmjs.com/package/@nextrush/di)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/@nextrush/di.svg)](https://bundlephobia.com/package/@nextrush/di)
+[![types](https://img.shields.io/npm/types/@nextrush/di.svg)](https://www.npmjs.com/package/@nextrush/di)
+[![ESM only](https://img.shields.io/badge/module-ESM--only-blue.svg)](https://nodejs.org/api/esm.html)
+[![license](https://img.shields.io/npm/l/@nextrush/di.svg)](https://github.com/0xTanzim/nextRush/blob/main/LICENSE)
+
+|  |  |
+| --- | --- |
+| **Purpose** | Decorator-driven dependency injection for NextRush — mark a class `@Service()`, declare dependencies in its constructor, and `container.resolve()` wires the graph |
+| **Package type** | Core |
+| **Status** | Stable ✅ |
+| **Included in `nextrush`?** | Partially — `Service`, `Repository`, `container`, `createContainer`, `inject`, and the `Container` type are re-exported through [`nextrush/class`](../class). Install `@nextrush/di` directly to use `@Config`, `@Injectable`, `@Optional`, `delay`, the DI error classes, or the metadata readers. |
+| **Support tier** | Public — core (stable, semver-guarded) — see [ADR-0005](https://github.com/0xTanzim/nextRush/blob/main/docs/adr/ADR-0005-package-tiers-sealed-surface-deprecation.md) |
+| **Maintenance** | Active |
+| **Runtime** | Universal — Node · Bun · Deno · Edge |
+| **Requires** | Node `>=22` · ESM-only · TypeScript `>=5.x` |
+| **Introduced** | `v3.0.0` |
+
+## Highlights
+
+- 🧩 **Decorator-driven** — `@Service()` / `@Repository()` + constructor parameters; no manual wiring for the common case
+- 🔁 **Three scopes** — `singleton` (default), `transient`, and `request` (per-request child container)
+- 🧭 **Actionable errors** — circular dependencies and unregistered tokens throw messages that name the cycle and list fixes
+- 📦 **Peer-depends on `tsyringe` + `reflect-metadata`** — this is the one core package with runtime dependencies (a sanctioned exception; the container wraps `tsyringe`)
+- ✅ **ESM-only**, side-effect-free, **fully typed** — strict TypeScript, zero `any`
+
+<details>
+<summary><strong>Table of contents</strong></summary>
+
+[The problem](#the-problem) · [When to use](#when-to-use) · [Installation](#installation) · [Quick start](#quick-start) · [Capabilities](#capabilities) · [Mental model](#mental-model) · [Common tasks](#common-tasks) · [API overview](#api-overview) · [Options](#options) · [Compatibility](#compatibility) · [Troubleshooting](#troubleshooting) · [FAQ](#faq) · [Package relationships](#package-relationships) · [Architecture](#architecture) · [Resources](#resources)
+
+</details>
+
+---
+
+## The problem
+
+Wiring dependencies by hand starts simple and rots fast. A service needs a repository, which needs a database client, which needs config — and every construction site has to know the whole chain and build it in the right order. Swapping an implementation (a real repository for a fake in a test) means threading the change through every caller.
+
+```ts
+// TODAY, without a container — every call site rebuilds the whole graph by hand,
+// in the right order, and a swapped implementation ripples everywhere:
+const config = new DatabaseConfig();
+const db = new DatabaseClient(config);
+const userRepo = new UserRepository(db);
+const userService = new UserService(userRepo);
+// …and the next module that needs UserService does all of this again.
+```
 
-## Features
+As the graph grows, ordering bugs and duplicated construction multiply, and a single shared instance (a connection pool) can be built twice by accident. `@nextrush/di` inverts this: a class declares *what it needs* in its constructor and *how it should be shared* with a decorator, and the container resolves the graph once, in order, memoizing singletons.
 
-- **Constructor Injection** — Automatic dependency resolution via TypeScript metadata
-- **Singleton & Transient Scopes** — Control instance lifecycle per service
-- **Circular Dependency Detection** — O(1) Set-based detection with cycle visualization, catches tsyringe-internal chains
-- **Production-Grade Errors** — Actionable messages with fix suggestions (`@Service()`, `@Repository()`, `@Config()` hints)
-- **Optional Dependencies** — `@Optional()` decorator for graceful handling of missing services
-- **Test-Friendly** — Isolated containers and instance clearing for test setup
+## When to use
 
-## Development
+`@nextrush/di` is the DI container behind NextRush's class-based runtime. If you use `@Controller` / `@Service` through [`nextrush/class`](../class), you are already using it. Reach for it **directly** when you want the container on its own, or the parts `nextrush/class` does not re-export.
 
-For the best development experience with full decorator and DI support, use **`@nextrush/dev`**.
+**Use `@nextrush/di` if:**
 
-```bash
-pnpm add -D @nextrush/dev
-```
+- ✓ You want constructor injection with decorators (`@Service`, `@Repository`) and automatic dependency resolution
+- ✓ You need lifecycle control — one shared instance (`singleton`), a fresh one each resolve (`transient`), or one per request (`request`)
+- ✓ You want circular-dependency and missing-dependency errors that explain how to fix them
+- ✓ You need the pieces beyond the `nextrush/class` re-export: `@Config`, `@Injectable`, `@Optional`, `delay()`, or the DI error classes
 
-Then in your `package.json`:
+**Reach for something else if:**
 
-```json
-{
-  "scripts": {
-    "dev": "nextrush dev"
-  }
-}
-```
-
-### Why?
-
-TypeScript's `emitDecoratorMetadata` option emits runtime type information that allows the DI container to automatically resolve constructor dependencies. Most modern fast runners (`tsx`, `esbuild`, `node --experimental-strip-types`) strip types but **do not** emit this metadata, causing errors like:
-
-```
-TypeInfo not known for "UserService"
-```
+- ✗ You only need controllers, guards, and request scope wired for you → use [`nextrush/class`](../class), which re-exports the common surface and drives the container for you
+- ✗ You have a two-object graph you construct once — a container is more machinery than a `new` call needs
 
-| Runtime           | Decorator Metadata | Recommended      |
-| ----------------- | ------------------ | ---------------- |
-| **nextrush dev**  | Full Support       | Yes              |
-| **tsc + node**    | Full Support       | Yes (Production) |
-| **tsx / esbuild** | Not Supported      | No               |
-| **ts-node --esm** | Issues             | No               |
+---
 
 ## Installation
 
 ```bash
 pnpm add @nextrush/di
+# npm i @nextrush/di · yarn add @nextrush/di · bun add @nextrush/di
 ```
 
-> If you use the `nextrush` meta-package, `reflect-metadata` is auto-imported. Otherwise, install it separately: `pnpm add reflect-metadata` and add `import 'reflect-metadata'` at your entry point.
+> [!NOTE]
+> Already using `nextrush`? `Service`, `Repository`, `container`, `createContainer`, and `inject`
+> are re-exported from [`nextrush/class`](../class) — `import { Service, container } from 'nextrush/class'`
+> works without installing this directly. Install `@nextrush/di` when you need `@Config`,
+> `@Injectable`, `@Optional`, `delay`, the DI error classes, or the metadata readers.
 
-## TypeScript Configuration
+> [!IMPORTANT]
+> Decorators need `reflect-metadata` loaded once before any decorated class is defined, and your
+> `tsconfig.json` needs `"experimentalDecorators": true` and `"emitDecoratorMetadata": true`.
+> Importing `@nextrush/di` (or `nextrush/class`) loads `reflect-metadata` for you.
 
-**Required** `tsconfig.json` settings:
+## Quick start
 
-```json
-{
-  "compilerOptions": {
-    "experimentalDecorators": true,
-    "emitDecoratorMetadata": true
-  }
-}
-```
-
-## Quick Start
-
-```typescript
-import 'reflect-metadata'; // Required when NOT using the nextrush meta-package
+```ts
 import { Service, Repository, container } from '@nextrush/di';
 
 @Repository()
 class UserRepository {
   findAll() {
-    return [{ id: 1, name: 'Alice' }];
+    return [{ id: 1, name: 'Ada' }];
   }
 }
 
 @Service()
 class UserService {
-  constructor(private repo: UserRepository) {}
+  constructor(private readonly repo: UserRepository) {}
 
   getUsers() {
     return this.repo.findAll();
   }
 }
 
-const userService = container.resolve(UserService);
-console.log(userService.getUsers()); // [{ id: 1, name: 'Alice' }]
+// Resolve the whole graph — UserRepository is constructed and injected automatically.
+const users = container.resolve(UserService);
+console.log(users.getUsers()); // [{ id: 1, name: 'Ada' }]
 ```
 
-## API Reference
+You never construct `UserRepository` yourself. `@Service()` marks `UserService` as resolvable, the constructor declares what it needs, and `container.resolve()` builds the graph in dependency order — memoizing each singleton so the second resolve returns the same instances.
 
-### Decorators
+## Capabilities
 
-#### `@Service(options?)`
+**Injection**
+- **Constructor injection** — declare dependencies as constructor parameters; the container resolves them by type
+- **`@inject(token)`** — inject by string/symbol token or interface when the type can't be inferred at runtime
+- **`@Optional()`** — an unresolved optional dependency is injected as `undefined` instead of throwing
+- **`delay(() => Class)`** — lazily resolve a dependency to break a circular reference
 
-Mark a class as an injectable service. Singletons by default.
+**Scopes** (the canonical reference — see [Mental model](#mental-model))
+- **`singleton`** (default) — one shared instance for the process lifetime
+- **`transient`** — a fresh instance on every resolve
+- **`request`** — one instance per request, shared within it, via a per-request child container
 
-```typescript
-@Service()
-class MyService {}
+**Providers**
+- **`useClass`** — construct a class (honoring its declared scope)
+- **`useValue`** — register a constant (config object, pre-built client)
+- **`useFactory`** — build lazily, optionally injecting other tokens; async factories are awaited by `bootstrap()`
 
-// Transient (new instance each time)
-@Service({ scope: 'transient' })
-class RequestLogger {}
-```
-
-**`ServiceOptions`:**
-
-| Property | Type                         | Default       | Description        |
-| -------- | ---------------------------- | ------------- | ------------------ |
-| `scope`  | `'singleton' \| 'transient'` | `'singleton'` | Instance lifecycle |
+**Safety & developer experience**
+- **Circular-dependency detection** — an O(1) resolution-stack guard throws a `CircularDependencyError` that names the cycle *before* the call stack overflows
+- **Actionable errors** — `DependencyResolutionError` lists concrete fixes; `InvalidProviderError` shows the valid provider shapes
+- **Fully typed** — strict TypeScript, zero `any`; the container contract is shared through `@nextrush/types`
 
-#### `@Repository(options?)`
+## Mental model
 
-Semantic alias for `@Service()`. Sets metadata type to `'repository'` instead of `'service'`. Use for data access layers.
+A class declares **what it needs** (constructor parameters) and **how it should be shared** (its scope). The container owns the *when* and *how many* — it resolves the graph in order and memoizes according to scope.
 
-```typescript
-@Repository()
-class UserRepository {
-  findById(id: string) {
-    return db.users.find(id);
-  }
-}
+```text
+@Service() / @Repository()  --->  container.register(token, { useClass }, { scope })
+class + constructor deps                    |   singleton | transient | request
+                                            v
+container.resolve(token)     --->  tsyringe constructs, injecting resolved deps
+        |
+        +-- cycle detected?  --->  CircularDependencyError (names the cycle, before the stack blows)
+        +-- token missing?   --->  DependencyResolutionError (lists the fixes)
 ```
 
-#### `@inject(token)`
+**Rule:** the class's declared scope — not the call site — decides singleton vs transient; an explicit `register(..., { scope })` only overrides it deliberately.
 
-Explicitly inject a dependency by token. Use for interfaces, string tokens, or symbol tokens.
+> [!TIP]
+> The resolution sequence, the request-scoped child container, and the instance lifecycle per
+> scope (with Mermaid diagrams) are in [`ARCHITECTURE.md`](./ARCHITECTURE.md).
 
-```typescript
-const DATABASE_TOKEN = Symbol('Database');
+---
 
-@Service()
-class UserService {
-  constructor(
-    @inject(DATABASE_TOKEN) private db: IDatabase,
-    @inject('API_KEY') private apiKey: string
-  ) {}
-}
-```
+## Common tasks
 
-#### `@AutoInjectable()`
+### Mark a service and inject it
 
-Mark a class as injectable in the container. Sets service type metadata to `'service'`.
+```ts
+import { Service } from '@nextrush/di';
 
-```typescript
-@AutoInjectable()
-class FeatureService {
-  constructor(private logger: Logger) {}
+@Service() // singleton by default — one shared instance
+class Logger {
+  info(msg: string) { console.log(msg); }
 }
 
-// Resolve through the container
-const service = container.resolve(FeatureService);
+@Service()
+class OrderService {
+  constructor(private readonly logger: Logger) {} // injected automatically
+}
 ```
 
-> **Note:** Despite the name, `@AutoInjectable()` does not enable dependency injection via `new`. The current implementation uses tsyringe's `injectable()` decorator internally. Dependencies are resolved only through `container.resolve()`.
+### Choose a scope
 
-#### `delay(tokenFactory)`
+```ts
+import { Service } from '@nextrush/di';
 
-Defer resolution to break circular dependencies. Returns a lazy token for use with `@inject()`.
+@Service()                        // singleton — one shared instance
+class ConfigService {}
 
-```typescript
-import { delay, inject, Service } from '@nextrush/di';
+@Service({ scope: 'transient' })  // a fresh instance on every resolve
+class Formatter {}
 
-@Service()
-class ServiceA {
-  constructor(@inject(delay(() => ServiceB)) private b: ServiceB) {}
-}
-
-@Service()
-class ServiceB {
-  constructor(@inject(delay(() => ServiceA)) private a: ServiceA) {}
+@Service({ scope: 'request' })    // one instance per request, shared within it
+class RequestId {
+  readonly id = crypto.randomUUID();
 }
 ```
 
-#### `@Optional()`
+`request` scope only takes effect when the service is resolved from a per-request child container — the class-based runtime does this for you (see [`nextrush/class`](../class)); to do it manually, `container.createChild()` per request and resolve from the child.
 
-Mark a constructor parameter as optional. When the dependency is not registered, the container injects `undefined` instead of throwing.
+### Inject by token, or make a dependency optional
 
-```typescript
-import { Service, Optional, inject } from '@nextrush/di';
+```ts
+import { Service, inject, Optional } from '@nextrush/di';
 
 @Service()
 class NotificationService {
   constructor(
-    @Optional() private emailService?: EmailService,
-    @inject('SLACK_TOKEN') @Optional() private slackToken?: string
+    @inject('MAILER') private readonly mailer: Mailer,          // by string token
+    @Optional() @inject('SMS') private readonly sms?: SmsClient, // undefined if unregistered
   ) {}
-
-  notify(message: string) {
-    if (this.emailService) {
-      this.emailService.send(message);
-    }
-    if (this.slackToken) {
-      // send to Slack
-    }
-  }
 }
 ```
 
-#### `isParameterOptional(target, parameterIndex)`
-
-Check if a specific constructor parameter is marked as optional.
+### Register a value or a factory manually
 
-```typescript
-import { isParameterOptional, Optional, Service } from '@nextrush/di';
+```ts
+import { container } from '@nextrush/di';
 
-@Service()
-class MyService {
-  constructor(@Optional() private dep?: SomeDep) {}
-}
+container.register('CONFIG', { useValue: { port: 8080 } });
+container.register('CLOCK', { useFactory: () => new Date() });
 
-isParameterOptional(MyService, 0); // true
-isParameterOptional(MyService, 1); // false
+// Factory with injected dependencies + an async factory awaited by bootstrap()
+container.register('DB', {
+  useFactory: (url: string) => connect(url),
+  inject: ['DATABASE_URL'],
+});
+await container.bootstrap(); // resolves and caches async factory results
 ```
 
-#### `getOptionalParams(target)`
-
-Get all optional parameter indices for a class. Returns a `ReadonlySet<number>`.
+### Isolate a container for tests
 
-```typescript
-import { getOptionalParams } from '@nextrush/di';
+```ts
+import { createContainer } from '@nextrush/di';
 
-const optionals = getOptionalParams(MyService);
-// Set { 0 }
+const testContainer = createContainer(); // fresh, isolated child container
+testContainer.register(UserRepository, { useClass: FakeUserRepository });
+const service = testContainer.resolve(UserService); // uses the fake
 ```
 
-### Utility Functions
+## API overview
 
-#### `hasServiceMetadata(target)`
+The sealed public surface (ADR-0005), grouped by role.
 
-Check if a class has DI metadata (decorated with `@Service()` or `@Repository()`).
+| Export | Signature | Since | Stability | Description |
+| ------ | --------- | ----- | --------- | ----------- |
+| `container` | `Container` | `3.0.0` | Stable ✅ | The default DI container instance. |
+| `createContainer` | `() => Container` | `3.0.0` | Stable ✅ | Create a fresh, isolated container (testing / scoping). |
+| `Service` | `(options?: ServiceOptions) => ClassDecorator` | `3.0.0` | Stable ✅ | Mark a class injectable (singleton by default). |
+| `Repository` | `(options?: ServiceOptions) => ClassDecorator` | `3.0.0` | Stable ✅ | Same as `Service`, semantically a data-access class. |
+| `Config` | `(options?: ConfigOptions) => ClassDecorator` | `3.0.0` | Stable ✅ | Mark a configuration holder — always a singleton. |
+| `Injectable` | `() => ClassDecorator` | `3.0.0` | Stable ✅ | Make a class resolvable without service metadata (transient). |
+| `inject` | `(token: unknown) => ParameterDecorator` | `3.0.0` | Stable ✅ | Inject a dependency by class/string/symbol token. |
+| `Optional` | `() => ParameterDecorator` | `3.0.0` | Stable ✅ | Inject `undefined` for an unresolved dependency instead of throwing. |
+| `delay` | `(factory: () => Constructor) => unknown` | `3.0.0` | Stable ✅ | Lazily resolve a token to break a circular dependency. |
+| `markInjectable` | `(target: Constructor) => void` | `3.0.0` | Stable ✅ | Make a class resolvable without service metadata (used by `@Controller`). |
+| `hasServiceMetadata` · `getServiceType` · `getServiceScope` · `getConfigPrefix` | `(target) => …` | `3.0.0` | Stable ✅ | Metadata readers for discovery / diagnostics. |
+| `getOptionalParams` · `isParameterOptional` | `(target[, index]) => …` | `3.0.0` | Stable ✅ | Read `@Optional()` parameter markers. |
+| `DIError` · `DependencyResolutionError` · `CircularDependencyError` · `InvalidProviderError` | `class` | `3.0.0` | Stable ✅ | The DI error hierarchy. |
+| `METADATA_KEYS` | `Readonly<Record<string, string>>` | `3.0.0` | Stable ✅ | The metadata key constants decorators write under. |
+| `type Container` · `Scope` · `Token` · `Provider` · `ClassProvider` · `FactoryProvider` · `ValueProvider` · `RegisterOptions` · `ServiceOptions` · `ConfigOptions` · `Constructor` | — | `3.0.0` | Stable ✅ | Public contracts (re-exported from `@nextrush/types`). |
 
-```typescript
-import { hasServiceMetadata, Service } from '@nextrush/di';
+The `Container` interface exposes: `register`, `resolve`, `resolveAsync`, `bootstrap`, `resolveAll`, `isRegistered`, `clearInstances`, `reset`, and `createChild`.
 
-@Service()
-class MyService {}
+## Options
 
-hasServiceMetadata(MyService); // true
-```
+`@nextrush/di` is decorator- and API-driven; the configurable inputs are the decorator/registration option bags.
 
-#### `getServiceType(target)`
+| Option | Type | Required | Default | Security-sensitive | Description |
+| ------ | ---- | -------- | ------- | ------------------ | ----------- |
+| `ServiceOptions.scope` | `'singleton' \| 'transient' \| 'request'` | No | `'singleton'` | — | Lifecycle for `@Service()` / `@Repository()`. |
+| `RegisterOptions.scope` | `'singleton' \| 'transient' \| 'request'` | No | class's declared scope (else `'singleton'` for a decorated class) | — | Per-`register()` override; an explicit scope wins over the class's declared scope. |
+| `ConfigOptions.prefix` | `string` | No | `undefined` | — | Environment-variable prefix recorded on a `@Config()` class (documents the `PREFIX_*` vars it reads). |
 
-Get the service type from a decorated class. Returns `'service'`, `'repository'`, or `undefined`.
+## Compatibility
 
-#### `getServiceScope(target)`
+**Requirements**
 
-Get the scope from a decorated class. Returns `'singleton'`, `'transient'`, or `undefined`.
+| Requirement | Version |
+| ----------- | ------- |
+| NextRush | `3.x` |
+| Node.js | `>=22` |
+| TypeScript | `>=5.x` (with `experimentalDecorators` + `emitDecoratorMetadata`) |
 
-### Container
+**Runtimes**
 
-#### `container.register(token, provider)`
+| Runtime | Supported | Notes |
+| ------- | --------- | ----- |
+| Node.js `>=22` | ✅ | ESM-only |
+| Bun / Deno / Edge | ✅ / ✅ / ✅ | Uses only `tsyringe` + `reflect-metadata` — no `node:*` APIs — so behavior is identical across runtimes |
 
-Register a dependency with the container.
+**Integration**
+- **Peer dependencies:** `tsyringe@^4.10.0` and `reflect-metadata@^0.2.2` (runtime), plus `@nextrush/types` (contract, types erased at build).
+- **Works with:** [`nextrush/class`](../class) (re-exports the common surface and drives the container per request), [`@nextrush/core`](../core) (each `Application` may own a container).
+- **Incompatible with:** none.
 
-```typescript
-// Class provider
-container.register(UserService, { useClass: UserService });
+> [!IMPORTANT]
+> NextRush is **ESM-only, permanently** — no CommonJS build. On Node `>=22`, CommonJS consumers can
+> `require()` this ESM package natively. See the
+> [Module Format Policy](https://github.com/0xTanzim/nextRush#module-format-policy).
 
-// Value provider
-container.register('CONFIG', { useValue: { port: 3000 } });
+---
 
-// Factory provider — receives the container for nested resolution
-container.register(Logger, {
-  useFactory: (c) => new Logger(c.resolve('CONFIG')),
-});
-```
+## Troubleshooting
 
-#### `container.resolve(token)`
+<details>
+<summary><strong><code>DependencyResolutionError</code>: a token is "not registered in the container"</strong></summary>
 
-Resolve a dependency from the container.
+**Cause:** the class you're resolving depends on a token nothing registered — usually a missing `@Service()` / `@Repository()` decorator, an interface injected without `@inject('TOKEN')`, or a module imported after `resolve()` ran. **Fix:** decorate the class, inject interface/string tokens explicitly, or register it manually.
 
-```typescript
-const service = container.resolve(UserService);
-const config = container.resolve<Config>('CONFIG');
+```ts
+container.register(UserRepository, { useClass: UserRepository });
+// or add @Repository() to the class, or @inject('IUserRepository') on the parameter
 ```
 
-#### `container.resolveAll(token)`
-
-Resolve all dependencies registered under a token. Returns an empty array if none are registered.
+</details>
 
-```typescript
-container.register('Plugin', { useValue: pluginA });
-container.register('Plugin', { useValue: pluginB });
+<details>
+<summary><strong><code>CircularDependencyError</code>: "circular dependency detected"</strong></summary>
 
-const plugins = container.resolveAll<Plugin>('Plugin');
-```
+**Cause:** two (or more) classes depend on each other, so neither can be constructed first. The container detects the cycle and names it before the call stack overflows. **Fix:** break the cycle — extract shared logic into a third service, or lazily resolve one side with `delay()`.
 
-#### `container.isRegistered(token)`
+```ts
+import { inject, delay, Service } from '@nextrush/di';
 
-Check if a token is registered.
-
-```typescript
-if (container.isRegistered(UserService)) {
-  // ...
+@Service()
+class A {
+  constructor(@inject(delay(() => B)) private readonly b: B) {}
 }
 ```
 
-#### `container.clearInstances()`
+</details>
 
-Clear cached singleton instances. Registrations remain — the next `resolve()` creates fresh instances.
+<details>
+<summary><strong>Decorators throw <code>Reflect.getMetadata is not a function</code> or types don't inject</strong></summary>
 
-```typescript
-beforeEach(() => {
-  container.clearInstances();
-});
-```
+**Cause:** `reflect-metadata` wasn't loaded, or `emitDecoratorMetadata` is off, so no constructor type information exists. **Fix:** ensure `reflect-metadata` is imported once at your entry point (importing `@nextrush/di` / `nextrush/class` does this), and enable `experimentalDecorators` + `emitDecoratorMetadata` in `tsconfig.json`.
 
-#### `container.reset()`
+</details>
 
-Reset the container completely, removing all registrations and instances.
+<details>
+<summary><strong>A <code>request</code>-scoped service behaves like a singleton</strong></summary>
 
-#### `container.createChild()`
+**Cause:** `request` scope only yields a per-request instance when resolved from a per-request **child** container. Resolving from the root container shares one instance. **Fix:** resolve from `container.createChild()` per request — the [`nextrush/class`](../class) runtime does this automatically for request-scoped controllers and their dependencies.
 
-Create a child container. The child inherits parent registrations but can override them independently.
+</details>
 
-#### `createContainer()`
+## FAQ
 
-Create a new isolated container with no inherited registrations.
+**Can I use `@nextrush/di` without the rest of NextRush?**
+Yes. The container, decorators, and errors are standalone — they depend on `tsyringe`, `reflect-metadata`, and the types-only `@nextrush/types`. Nothing ties them to the HTTP layer.
 
-```typescript
-const testContainer = createContainer();
-testContainer.register(UserService, { useClass: MockUserService });
-```
+**Why ESM-only?**
+See the [Module Format Policy](https://github.com/0xTanzim/nextRush#module-format-policy).
 
-## Error Handling
-
-All errors extend `DIError` and include actionable messages:
-
-```typescript
-import {
-  DIError,
-  DependencyResolutionError,
-  CircularDependencyError,
-  TypeInferenceError,
-  MissingDependencyError,
-  InvalidProviderError,
-  ContainerDisposedError,
-} from '@nextrush/di';
-
-try {
-  container.resolve(UnregisteredService);
-} catch (error) {
-  if (error instanceof DependencyResolutionError) {
-    console.log(error.missingDependency); // token name
-    console.log(error.chain); // resolution path
-  }
-  if (error instanceof CircularDependencyError) {
-    console.log(error.cycle); // ['ServiceA', 'ServiceB', ...]
-  }
-}
-```
+**Does it work on Bun, Deno, and Edge?**
+Yes. The package uses only `tsyringe` and `reflect-metadata` (no `node:*` APIs), so resolution behaves identically across every supported runtime.
 
-| Error                       | Cause                                                                                         |
-| --------------------------- | --------------------------------------------------------------------------------------------- |
-| `DependencyResolutionError` | Token not registered — includes fix suggestions (`@Service()`, import order, manual register) |
-| `CircularDependencyError`   | Circular dependency detected (wrapper-level + tsyringe-internal chains)                       |
-| `MissingDependencyError`    | _(Deprecated)_ Use `DependencyResolutionError` instead                                        |
-| `InvalidProviderError`      | Provider missing `useClass`, `useValue`, or `useFactory`                                      |
-| `TypeInferenceError`        | Constructor parameter type not available at runtime                                           |
-| `ContainerDisposedError`    | Container has been reset or disposed                                                          |
-
-## TypeScript Exports
-
-```typescript
-// Container
-import { container, createContainer } from '@nextrush/di';
-
-// Decorators
-import { Service, Repository, AutoInjectable, Optional, inject, delay } from '@nextrush/di';
-
-// Utility functions
-import {
-  hasServiceMetadata,
-  getServiceType,
-  getServiceScope,
-  isParameterOptional,
-  getOptionalParams,
-} from '@nextrush/di';
-
-// Metadata keys
-import { METADATA_KEYS } from '@nextrush/di';
-
-// Error classes
-import {
-  DIError,
-  DependencyResolutionError,
-  CircularDependencyError,
-  MissingDependencyError,
-  InvalidProviderError,
-  TypeInferenceError,
-  ContainerDisposedError,
-} from '@nextrush/di';
-
-// Types
-import type {
-  ContainerInterface,
-  Provider,
-  ClassProvider,
-  ValueProvider,
-  FactoryProvider,
-  Token,
-  Constructor,
-  Scope,
-  ServiceOptions,
-} from '@nextrush/di';
-```
+**How is `request` scope different from `transient`?**
+`transient` builds a fresh instance on *every* resolve; `request` builds one instance per request and shares it across every collaborator resolved within that request's child container. Two services that both depend on a `request`-scoped value receive the *same* value within one request.
 
-## Integration with Guards
+---
 
-Class-based guards implementing `CanActivate` are resolved from the DI container:
+## Package relationships
 
-```typescript
-import { Service } from '@nextrush/di';
-import type { CanActivate, GuardContext } from '@nextrush/decorators';
-
-@Service()
-class AuthGuard implements CanActivate {
-  constructor(private authService: AuthService) {}
-
-  async canActivate(ctx: GuardContext): Promise<boolean> {
-    const token = ctx.get('authorization');
-    if (!token) return false;
-
-    const user = await this.authService.verify(token);
-    ctx.state.user = user;
-    return Boolean(user);
-  }
-}
+```text
+                depends on         @nextrush/types  (Container / Scope / Provider contract, types only)
+@nextrush/di ---------------->     tsyringe · reflect-metadata  (runtime — the container wraps tsyringe)
+                re-exported by     @nextrush/class  (Service, Repository, container, createContainer, inject)
+                used by            @nextrush/class  (resolves controllers, guards, interceptors, filters)
 ```
 
-The `@nextrush/controllers` plugin automatically detects class guards and resolves them from the container.
-
-## Troubleshooting
+- **Depends on:** [`@nextrush/types`](../types) — the shared `Container` / `Scope` / `Provider` / `Token` contracts (types, erased at build) · `tsyringe` + `reflect-metadata` (runtime).
+- **Re-exported by:** [`nextrush/class`](../class) — `Service`, `Repository`, `container`, `createContainer`, `inject`, and the `Container` type reach users through the class runtime.
+- **Used by:** [`@nextrush/class`](../class) — resolves controllers, guards, interceptors, and exception filters from the container, and drives request scope.
+- **Alternative:** none within NextRush — this is the framework's DI container.
 
-### Error: "TypeInfo not known for X"
+## Architecture
 
-**Cause**: `emitDecoratorMetadata` is not being emitted at runtime.
-
-**Fix**: Use `@nextrush/dev` for development. It automatically handles metadata emission.
-
-```bash
-# ❌ Doesn't work (no decorator metadata)
-npx tsx src/index.ts
-
-# ✅ Works (full decorator support)
-nextrush dev
-```
+Maintaining or contributing to this package? The internal design — how the container wraps `tsyringe`,
+the scope-to-lifecycle mapping, the per-request child container behind `request` scope, circular- and
+missing-dependency detection, the architectural invariants, and the decisions and trade-offs behind
+them (with diagrams) — is in **[`ARCHITECTURE.md`](./ARCHITECTURE.md)**. Design history:
+[ADR-0005 (package tiers & sealed surface)](https://github.com/0xTanzim/nextRush/blob/main/docs/adr/ADR-0005-package-tiers-sealed-surface-deprecation.md).
 
-### Error: "reflect-metadata not found"
+## Resources
 
-**Cause**: `reflect-metadata` must be imported before decorators.
-
-**Fix**: Import it first in your entry point:
-
-```typescript
-import 'reflect-metadata'; // MUST be first!
-import { Service } from '@nextrush/di';
-```
-
-### Constructor parameters not injected
-
-**Cause**: Class is missing `@Service()` decorator.
-
-**Fix**: Add the decorator:
-
-```typescript
-@Service() // Required for DI!
-class MyService {
-  constructor(private dep: SomeDependency) {}
-}
-```
+- 📖 **Learn** — [Documentation](https://0xtanzim.github.io/nextRush/docs) · [Architecture](./ARCHITECTURE.md) · [RFCs](https://github.com/0xTanzim/nextRush/tree/main/docs/RFC)
+- 📝 **Changelog** — [CHANGELOG.md](./CHANGELOG.md)
+- 🐛 **Report an issue** — [GitHub Issues](https://github.com/0xTanzim/nextRush/issues)
+- 🤝 **Contribute** — [CONTRIBUTING.md](https://github.com/0xTanzim/nextRush/blob/main/CONTRIBUTING.md)
 
-## License
+---
 
-MIT
+MIT © [Tanzim Hossain](https://github.com/0xTanzim)