@decohere/crucible 0.0.1-dev.98 → 0.0.1-dev.99

package/README.md

@@ -0,0 +1,351 @@
+# @decohere/crucible
+
+Lightweight dependency injection for Decohere. Register classes (or tokens) on a `CrucibleBuilder`, `build()` a container, then `resolve()` graphs of constructor-injected services.
+
+Higher layers (for example Cortex `Builder.withServices`) register on a `CrucibleBuilder`. You can also build and resolve from a container yourself.
+
+## When to use
+
+| Use Crucible | Do not use Crucible |
+|---|---|
+| Constructor-injected services and controllers | Replacing Cortex / Protocol / Codex — those compose *on top of* Crucible |
+| Tokens for interfaces, config objects, and “many of this kind” | Auto-scanning folders or Nest-style modules (not in this package) |
+| Request / singleton / transient lifetimes and `using` disposal | Throwing on a missing dependency (unregistered keys resolve to `null`) |
+
+## Install
+
+```bash
+pnpm add @decohere/crucible
+```
+
+```ts
+import { CrucibleBuilder, LifetimeScopeToken, Scopes } from "@decohere/crucible";
+import { inject, injectable } from "@decohere/crucible/decorators";
+```
+
+Decorator metadata is required. Enable it in `tsconfig.json` (the Decohere scaffold and this repo already do):
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  }
+}
+```
+
+`@decohere/nexus/reflection` loads `reflect-metadata`. Import Crucible (or Nexus) before constructing decorated classes.
+
+---
+
+## Constructor injection — `@inject` is usually unnecessary
+
+If the constructor parameter is a **concrete class**, Crucible reads `design:paramtypes` and resolves by the class name. Mark the *consumer* `@injectable()` so TypeScript/SWC emit that metadata. Do **not** add `@inject` for that parameter.
+
+```ts
+import { injectable } from "@decohere/crucible/decorators";
+import { SampleService } from "./sample.service.js";
+
+@injectable()
+export class HelloController {
+  public constructor(private readonly sample: SampleService) {}
+}
+```
+
+```ts
+import { CrucibleBuilder } from "@decohere/crucible";
+
+const builder = new CrucibleBuilder();
+builder.registerSingleton(SampleService);
+builder.registerRequestScoped(HelloController);
+const container = builder.build();
+
+using scope = container.beginScope("req");
+const hello = scope.resolve(HelloController);
+```
+
+`@injectable()` is an empty class decorator. Its job is to force `design:paramtypes` onto the constructor. Any other class decorator (`@Controller()`, `@Trace`, …) also does that; `@injectable()` is the one to use when there is nothing else.
+
+### Do not `import type` injected classes
+
+`import type` is erased at compile time. `emitDecoratorMetadata` then records `Object` (or nothing) instead of the constructor. Crucible looks up `"Object"`, finds no registration, and **returns `null`**. The first method call on that dependency throws (`Cannot read properties of null`).
+
+```ts
+// Wrong — SampleService does not exist at runtime, paramtypes collapse to Object
+import type { SampleService } from "./sample.service.js";
+
+// Right — value import keeps the constructor for reflect-metadata
+import { SampleService } from "./sample.service.js";
+```
+
+`import type` is correct for **interfaces** and type-only helpers. Those have no runtime constructor; pair them with `@inject(token)` (see below).
+
+Linters that prefer type-only imports (`import type` / `import { type X }`) will flag a class that appears unused except as a constructor type. Keep the value import and suppress that rule locally — for example with oxlint (or Biome, or ESLint):
+
+```ts
+// oxlint-disable-next-line typescript/consistent-type-imports -- constructor injection needs the class at runtime
+import { Workspace } from "@decohere/mesh";
+```
+
+That pattern is used throughout Forge (`Build`, `Clean`, …). Same idea applies to ESLint `consistent-type-imports` or equivalent.
+
+---
+
+## When you *do* need `@inject`
+
+`@inject(key)` overrides the paramtypes lookup with an explicit key: a class constructor, string, or symbol. Use it when there is no useful constructor in `design:paramtypes`.
+
+| Situation | Why `@inject` |
+|---|---|
+| Interface or type alias (`ISampleStore`) | No runtime class; paramtypes is `Object` |
+| String / symbol token | Registration key is not the class name |
+| Array of implementations (`Transformer[]`) | Paramtypes is `Array`; without a token, Crucible would `resolveMany("Array")` |
+| Paramtypes collapsed to `Object` (circular import, decorate-before-init) | Explicit token still resolves |
+
+```ts
+import { inject, injectable } from "@decohere/crucible/decorators";
+
+export const SampleStoreToken = Symbol("SampleStore");
+
+export interface ISampleStore {
+  get(id: string): Promise<unknown>;
+}
+
+@injectable()
+export class SampleService {
+  public constructor(
+    @inject(SampleStoreToken) private readonly store: ISampleStore,
+  ) {}
+}
+```
+
+Keep tokens in a `const.ts` (or next to the interface). Register against the same token:
+
+```ts
+builder.registerSingleton(SampleStoreToken, PostgresSampleStore);
+// or an already-built instance:
+builder.registerSingleton(SampleStoreToken, store);
+```
+
+`@inject` takes `string | symbol | Constructable`. Prefer `@inject(SampleService)` over `@inject("SampleService")` — the class tracks renames. There is no `@inject({ many, optional })` yet — arrays use `resolveMany` automatically when the reflected type is `Array`, and missing keys are `null` (see [Optional / missing](#optional--missing-dependencies)).
+
+---
+
+## Registration and lifetimes
+
+Keys are the class **name**, a string, or a symbol’s **description**. `resolve(SampleService)`, `resolve("SampleService")`, `@inject(SampleService)`, and `@inject("SampleService")` hit the same registration.
+
+Registering the same class (or the same type on a token) twice **throws** `RegistrationError` — silent last-wins hides accidental double-registers. Replace it explicitly:
+
+```ts
+builder.override.registerSingleton(SampleService);
+builder.override.registerTransient(SampleService);
+```
+
+`builder.override` is a registrar with replace already bound — the builder itself is not mutated. Two different types on one token is still multi-bind: `resolve` throws `ResolveError`, `resolveMany` returns both.
+
+| Lifetime | Cached |
+|---|---|
+| Singleton | On the root container — shared with every nested scope |
+| Request | On the current scope — new instance per `beginScope` |
+| Transient | Never — new instance every `resolve` |
+
+```ts
+builder.registerSingleton(SampleService);
+builder.registerSingleton(Token, SampleService);
+builder.registerSingleton(Token, existingInstance);
+
+builder.registerRequestScoped(HelloController);
+builder.registerRequestScoped(Token, HelloController);
+builder.registerRequestScoped(Token, () => createConnection());
+
+builder.registerTransient(Helper);
+builder.registerTransient(Token, Helper);
+```
+
+`registerType(type, scope?)` and `registerTypes(...)` are the same registrations without the lifetime in the method name (default **transient**). `Scopes.singleton` is the string `"single-instance"`.
+
+Cortex HTTP: controllers are **request-scoped** (one per request). Services are usually **singletons**.
+
+`registerSingleton(Class, instance)` binds an existing object under the class name. Terminal does this for the workspace:
+
+```ts
+builder.registerSingleton(workspace.constructor, workspace);
+```
+
+---
+
+## Recipes
+
+### Many implementations of one token
+
+Register several types under the same token. Inject them as an array with `@inject(Token)`.
+
+```ts
+export const TransformerKey = Symbol("TransformerKey");
+
+builder.registerSingleton(TransformerKey, SwcTranspiler);
+builder.registerSingleton(TransformerKey, TypeEmitter);
+```
+
+```ts
+@injectable()
+export class Build {
+  public constructor(
+    @inject(TransformerKey) private readonly transformers: Transformer[],
+  ) {}
+}
+```
+
+`resolve(TransformerKey)` **throws** `ResolveError` when more than one registration exists. Use `resolveMany(TransformerKey)` or constructor injection of an array.
+
+### Request scopes and disposal
+
+```ts
+builder.registerRequestScoped(UnitOfWork);
+builder.registerSingleton(Clock);
+const container = builder.build();
+
+{
+  using scope = container.beginScope("req-1");
+  const uow = scope.resolve(UnitOfWork); // per-scope
+  const clock = scope.resolve(Clock); // same singleton as the root
+} // scope[Symbol.dispose]() — request-scoped instances are disposed
+
+await using scope = container.beginScope("req-2");
+// async teardown via Symbol.asyncDispose if the instance implements it
+```
+
+- Child scopes copy the parent **registry** when created; they do not share the request-instance cache.
+- Nested `beginScope` is allowed; each level has its own request instances.
+- Named scopes: a live duplicate name throws `DuplicateScopeError`. After dispose, the name can be reused. Unnamed scopes do not collide.
+- Disposing a parent does **not** dispose child scopes. Dispose the scope you created.
+- Singletons are cached on the root container and shared with nested scopes. Resolving a singleton after the root is disposed throws.
+
+Cortex `App.dispose` (Flux HMR / SIGINT) disposes the **root** container, then Scribe. Implement `Symbol.asyncDispose` (or `Symbol.dispose`) on long-lived services — sockets, pools, timers. Only **constructed** instances are disposed (resolve them at boot; transients are not cached). `export default app` is the composition-root contract; do not wrap it for extra teardown.
+
+The current scope is always registered as `LifetimeScopeToken`:
+
+```ts
+import { type LifetimeScope, LifetimeScopeToken } from "@decohere/crucible";
+import { inject, injectable } from "@decohere/crucible/decorators";
+
+@injectable()
+export class ExceptionFilterHost {
+  public constructor(
+    @inject(LifetimeScopeToken) private readonly scope: LifetimeScope,
+  ) {}
+}
+```
+
+### Factories
+
+```ts
+builder.registerRequestScoped("connection", () => createConnection());
+const connection = container.resolve("connection");
+```
+
+Arrow factories are called as functions (not `new`). Use them when construction needs arguments Crucible should not know about.
+
+### Optional / missing dependencies
+
+Unregistered keys do **not** throw. `resolve` returns `null` and logs a warning. Optional constructor params (`dep?: Foo`) still go through resolution — you get `null` if nothing is registered.
+
+```ts
+@injectable()
+export class App {
+  public constructor(
+    @inject(HttpProviderToken) private readonly http?: HttpProvider,
+  ) {}
+}
+```
+
+If a concrete class parameter is `null` at runtime, the usual cause is metadata loss (`import type`, missing `@injectable()`, or paramtypes `Object`) — not an optional registration.
+
+### Cortex HTTP apps
+
+```ts
+import { Builder } from "@decohere/cortex";
+import { FastifyProvider } from "@decohere/cortex/providers";
+import { SampleService } from "./services/sample.service.js";
+import { HelloController } from "./controllers/hello.controller.js";
+
+await Builder.create()
+  .withHttp(FastifyProvider)
+  .withControllers(HelloController)
+  .withServices((cb) => {
+    cb.registerSingleton(SampleService);
+  })
+  .buildAndStart();
+```
+
+`withHttp` / `withControllers` already register the HTTP stack (router, controllers as request-scoped, …). Application services go in `withServices`.
+
+### Tests
+
+Prefer constructing the subject with explicit fakes when you do not need the container. Use `CrucibleBuilder` when the test *is* the wiring (scopes, tokens, many-implementations).
+
+```ts
+const builder = new CrucibleBuilder();
+builder.registerSingleton(SampleService, fakeSample);
+builder.registerRequestScoped(HelloController);
+const container = builder.build();
+using scope = container.beginScope("test");
+const hello = scope.resolve(HelloController);
+```
+
+To assert constructor arguments under DI, use `spyOnConstructor` from `@decohere/nexus/testing` — a bare `vi.spyOn` / `vi.fn` constructor drops `design:paramtypes`. See [Asserting DI constructor arguments](../../docs/testing/how-tos/vitest-constructor-spy-with-crucible-di.md).
+
+---
+
+## Public API
+
+### `@decohere/crucible`
+
+| Export | Role |
+|---|---|
+| `CrucibleBuilder` | Fluent registration; `build()` → `Crucible` |
+| `Crucible` | Container: `resolve`, `resolveMany`, `beginScope`, `Symbol.dispose` / `Symbol.asyncDispose` |
+| `IContainer` / `LifetimeScope` / `ContainerBuilder` / `ServiceProvider` | Composition interfaces |
+| `Scopes` | `{ request, singleton: "single-instance", transient }` |
+| `LifetimeScopeToken` | Symbol for the current scope |
+| `ResolveError` | `resolve` when multiple registrations share a key |
+| `DuplicateScopeError` | `beginScope` with a live duplicate name |
+| `RegistrationError` | Same type registered twice without `builder.override` |
+
+### `@decohere/crucible/decorators`
+
+| Export | Role |
+|---|---|
+| `injectable()` | Empty class decorator; emit `design:paramtypes` |
+| `inject(key)` | Parameter decorator; resolve by string or symbol instead of the reflected class name |
+
+---
+
+## Pitfalls
+
+1. **`import type` on an injected class** — paramtypes become `Object` → `resolve` returns `null`. Use a value import.
+2. **Missing `@injectable()` (or any decorator) on the consumer** — no paramtypes, constructor is called with zero arguments.
+3. **`resolve` of a multi-bound token** — throws; use `resolveMany` or inject `T[]` with `@inject(token)`.
+4. **Same type registered twice** — throws `RegistrationError`. Use `builder.override.registerSingleton(...)` (tests, plugin replacements).
+5. **Missing registration** — `null`, not an exception. Null-deref on first use is the symptom.
+6. **Symbol keys** — the lookup key is `symbol.description`. Keep descriptions unique and stable.
+7. **Renaming a class** without a token — the registration key is `Class.name`. Tokens isolate you from renames.
+
+---
+
+## Non-goals
+
+- Folder scanning / “declare a module and everything is registered”
+- Property or setter injection (constructors only)
+- `@inject({ many, optional })` metadata (not implemented; arrays and `null` cover the current cases)
+- Compile-time graph checking
+
+## Dependencies
+
+| Package | Role |
+|---|---|
+| [`@decohere/nexus`](../nexus) | Reflection helpers for `design:paramtypes` (`getMeta`, `isConstructable`, …) |
+| [`@decohere/scribe`](../scribe/README.md) | Logger facade |
+
+Layering: [architecture](../../docs/architecture/).

package/commonjs/src/services/crucible.js

@@ -139,8 +139,9 @@ class Crucible {
         if (this.isDisposed) {
             throw new Error("This container has been disposed");
         }
-        const { key, type, isInstance } = registration;
-        const cacheKey = isInstance ? key.value : type;
+        const { type, isInstance } = registration;
+        // One cache entry per registration: an instance registration is its own entry.
+        const cacheKey = type;
         const existingInstance = this.instances.get(cacheKey);
         if (existingInstance != null) {
             return existingInstance;

package/commonjs/src/services/service-registry.js

@@ -31,8 +31,8 @@ class ServiceRegistry {
             throw new _errors.RegistrationError(`A service is already registered for key ${registration.key}. Use builder.override.registerSingleton() (or the matching register* method) to replace it.`);
         }
         this.setRegistration(registration.key, [
-            registration,
-            ...existing
+            ...existing,
+            registration
         ]);
         return registration;
     }

package/es6/src/services/crucible.js

@@ -129,8 +129,9 @@ export class Crucible {
         if (this.isDisposed) {
             throw new Error("This container has been disposed");
         }
-        const { key, type, isInstance } = registration;
-        const cacheKey = isInstance ? key.value : type;
+        const { type, isInstance } = registration;
+        // One cache entry per registration: an instance registration is its own entry.
+        const cacheKey = type;
         const existingInstance = this.instances.get(cacheKey);
         if (existingInstance != null) {
             return existingInstance;

package/es6/src/services/service-registry.js

@@ -21,8 +21,8 @@ export class ServiceRegistry {
             throw new RegistrationError(`A service is already registered for key ${registration.key}. Use builder.override.registerSingleton() (or the matching register* method) to replace it.`);
         }
         this.setRegistration(registration.key, [
-            registration,
-            ...existing
+            ...existing,
+            registration
         ]);
         return registration;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decohere/crucible",
-  "version": "0.0.1-dev.98",
+  "version": "0.0.1-dev.99",
   "description": "Lightweight dependency injection container with decorator-based wiring",
   "keywords": [
     "typescript",
@@ -30,8 +30,8 @@
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "dependencies": {
-    "@decohere/nexus": "0.0.1-dev.98",
-    "@decohere/scribe": "0.0.1-dev.98"
+    "@decohere/nexus": "0.0.1-dev.99",
+    "@decohere/scribe": "0.0.1-dev.99"
   },
   "devDependencies": {}
 }