@decohere/crucible 0.0.1-dev.112 → 0.0.1-dev.113

package/README.md

@@ -10,7 +10,7 @@ Higher layers (for example Cortex `Builder.withServices`) register on a `Crucibl
 |---|---|
 | 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`) |
+| Request / singleton / transient lifetimes and `using` disposal | Compile-time graph checking (the graph is checked when a service is first resolved) |
 
 ## Install
 
@@ -40,7 +40,7 @@ Decorator metadata is required. Enable it in `tsconfig.json` (the Decohere scaff
 
 ## 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.
+If the constructor parameter is a **concrete class**, Crucible reads `design:paramtypes` and resolves that class. Mark the *consumer* `@injectable()` so TypeScript/SWC emit that metadata. Do **not** add `@inject` for that parameter.
 
 ```ts
 import { injectable } from "@decohere/crucible/decorators";
@@ -68,7 +68,7 @@ const hello = scope.resolve(HelloController);
 
 ### 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`).
+`import type` is erased at compile time. `emitDecoratorMetadata` then records `Object` (or nothing) instead of the constructor. Crucible cannot tell what to inject and **throws `ResolveError`** when the consumer is resolved, naming the parameter and telling you to add `@inject`.
 
 ```ts
 // Wrong — SampleService does not exist at runtime, paramtypes collapse to Object
@@ -98,9 +98,9 @@ That pattern is used throughout Forge (`Build`, `Clean`, …). Same idea applies
 | 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 |
+| String / symbol token | The service is registered under the token, not the class |
+| Array of implementations (`Transformer[]`) | Paramtypes is `Array`, which says nothing about the element type |
+| Paramtypes collapsed to `Object` (the class's import was dropped) | `@inject(TheClass)` uses the class as a value, so its import is kept |
 
 ```ts
 import { inject, injectable } from "@decohere/crucible/decorators";
@@ -127,13 +127,13 @@ builder.registerSingleton(SampleStoreToken, PostgresSampleStore);
 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)).
+`@inject` takes `string | symbol | Constructable`. To inject a class, pass the class: `@inject("SampleService")` does **not** find `SampleService` (see [Keys](#registration-and-lifetimes)). Arrays use `resolveMany` automatically when the reflected type is `Array`. For a dependency that may be absent, add `@optional()` (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.
+Keys match by **identity** ([ADR 0013](../../docs/adr/0013-crucible-keys-and-lifetimes.md)): a class matches only itself, a symbol only itself, a string only an equal string. So `resolve("SampleService")` does not find `registerSingleton(SampleService)`, `Symbol("TokenService")` does not collide with a class `TokenService`, two classes with the same name in different modules stay apart, and minified class names still work.
 
 Registering the same class (or the same type on a token) twice **throws** `RegistrationError` — silent last-wins hides accidental double-registers. Replace it explicitly:
 
@@ -150,6 +150,10 @@ builder.override.registerTransient(SampleService);
 | Request | On the current scope — new instance per `beginScope` |
 | Transient | Never — new instance every `resolve` |
 
+A singleton may not depend on a request-scoped service, directly or through transients: it would keep the first request's instance forever (a "captive dependency", e.g. one database connection for the life of the process). Resolving one throws `ResolveError` naming the chain. Make the consumer request-scoped, or inject `LifetimeScopeToken` and resolve the request-scoped service per request. `LifetimeScopeToken` itself is allowed: a singleton gets the root container.
+
+A dependency cycle (`A → B → A`) throws `ResolveError` listing the cycle.
+
 ```ts
 builder.registerSingleton(SampleService);
 builder.registerSingleton(Token, SampleService);
@@ -167,7 +171,7 @@ builder.registerTransient(Token, Helper);
 
 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:
+`registerSingleton(Class, instance)` binds an existing object under the class. The CLI does this for the workspace:
 
 ```ts
 builder.registerSingleton(workspace.constructor, workspace);
@@ -216,7 +220,7 @@ 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.
+- Child scopes look registrations up in their parent (nothing is copied, so `beginScope` costs the same however many services are registered); 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.
@@ -249,19 +253,19 @@ Arrow factories are called as functions (not `new`). Use them when construction
 
 ### 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.
+A missing registration **throws** `ResolveError`, naming the chain that needed it (`App → Router → Symbol(AuthorizationService)`). `resolveMany` returns `[]` instead. A `?` on the parameter type does not make it optional to the container; add `@optional()`, and the container passes `undefined` (so a default value applies):
 
 ```ts
+import { inject, injectable, optional } from "@decohere/crucible/decorators";
+
 @injectable()
 export class App {
   public constructor(
-    @inject(HttpProviderToken) private readonly http?: HttpProvider,
+    @inject(HttpProviderToken) @optional() 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
@@ -309,7 +313,7 @@ To assert constructor arguments under DI, use `spyOnConstructor` from `@decohere
 | `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 |
+| `ResolveError` | Nothing registered, several registrations for `resolve`, a cycle, a captive dependency, or a parameter with no usable type |
 | `DuplicateScopeError` | `beginScope` with a live duplicate name |
 | `RegistrationError` | Same type registered twice without `builder.override` |
 
@@ -318,19 +322,20 @@ To assert constructor arguments under DI, use `spyOnConstructor` from `@decohere
 | Export | Role |
 |---|---|
 | `injectable()` | Empty class decorator; emit `design:paramtypes` |
-| `inject(key)` | Parameter decorator; resolve by string or symbol instead of the reflected class name |
+| `inject(key)` | Parameter decorator; resolve this key instead of the reflected type |
+| `optional()` | Parameter decorator; pass `undefined` when nothing is registered instead of throwing |
 
 ---
 
 ## Pitfalls
 
-1. **`import type` on an injected class** — paramtypes become `Object` → `resolve` returns `null`. Use a value import.
+1. **`import type` on an injected class** — paramtypes become `Object` → `ResolveError` asking for `@inject`. Use a value import, or `@inject(TheClass)`.
 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.
+5. **A string key for a class** — `@inject("SampleService")` does not find `SampleService`. Pass the class.
+6. **Two copies of a package** — the class from one copy is not the class from the other, so a service registered with one is not found with the other. Install each package once.
+7. **A singleton depending on a request-scoped service** — throws; see [lifetimes](#registration-and-lifetimes).
 
 ---
 
@@ -338,7 +343,6 @@ To assert constructor arguments under DI, use `spyOnConstructor` from `@decohere
 
 - 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
@@ -346,6 +350,5 @@ To assert constructor arguments under DI, use `spyOnConstructor` from `@decohere
 | 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/decorators/inject.decorator.js

@@ -2,24 +2,39 @@
 Object.defineProperty(exports, "__esModule", {
     value: true
 });
-Object.defineProperty(exports, "inject", {
-    enumerable: true,
-    get: function() {
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get inject () {
         return inject;
+    },
+    get optional () {
+        return optional;
     }
 });
 const _reflection = require("@decohere/nexus/reflection");
 const _const = require("../const.js");
 function inject(key) {
-    return (target, _propertyKey, idx)=>{
-        const metadata = getExistingMeta(target);
-        metadata.set(idx, {
+    return updateToken((token)=>({
+            ...token,
             key
-        });
+        }));
+}
+function optional() {
+    return updateToken((token)=>({
+            ...token,
+            optional: true
+        }));
+}
+function updateToken(update) {
+    return (target, _propertyKey, idx)=>{
+        // Copy: the metadata can be inherited from a base class, which must not change.
+        const metadata = new Map((0, _reflection.getMeta)(_const.CrucibleMeta.injecttoken, target));
+        metadata.set(idx, update(metadata.get(idx)));
         (0, _reflection.defineMeta)(_const.CrucibleMeta.injecttoken, metadata, target);
     };
 }
-function getExistingMeta(target) {
-    const meta = (0, _reflection.getMeta)(_const.CrucibleMeta.injecttoken, target) ?? new Map();
-    return meta;
-}

package/commonjs/src/models/service-key.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "describeKey", {
+    enumerable: true,
+    get: function() {
+        return describeKey;
+    }
+});
+function describeKey(key) {
+    switch(typeof key){
+        case "string":
+            return `"${key}"`;
+        case "symbol":
+            return key.toString();
+        default:
+            return key.name || "(anonymous factory)";
+    }
+}

package/commonjs/src/services/crucible-builder.js

@@ -20,7 +20,7 @@ class CrucibleBuilder {
         return this.createRegistrar(true);
     }
     registerType(type, scope = _const.Scopes.transient) {
-        return this.register(false)(scope)(type.name, type);
+        return this.register(false)(scope)(type, type);
     }
     registerTypes(scopeOrType, ...types) {
         return this.registerMany(false, scopeOrType, types);
@@ -52,12 +52,12 @@ class CrucibleBuilder {
             scopeOrType,
             ...types
         ];
-        return allTypes.map((type)=>bind(scope)(type.name, type));
+        return allTypes.map((type)=>bind(scope)(type, type));
     }
     createRegistrar(override) {
         const bind = this.register(override);
         return {
-            registerType: (type, scope = _const.Scopes.transient)=>bind(scope)(type.name, type),
+            registerType: (type, scope = _const.Scopes.transient)=>bind(scope)(type, type),
             registerTypes: (scopeOrType, ...types)=>this.registerMany(override, scopeOrType, types),
             registerTransient: (typeOrKey, type)=>bind(_const.Scopes.transient)(typeOrKey, type),
             registerSingleton: (typeOrKey, typeOrInstance)=>bind(_const.Scopes.singleton)(typeOrKey, typeOrInstance),

package/commonjs/src/services/crucible.js

@@ -9,11 +9,19 @@ Object.defineProperty(exports, "Crucible", {
     }
 });
 const _reflection = require("@decohere/nexus/reflection");
-const _scribe = require("@decohere/scribe");
 const _const = require("../const.js");
-const _registrationkeymodel = require("../models/registration-key.model.js");
+const _servicekey = require("../models/service-key.js");
 const _errors = require("../types/errors.js");
 const _serviceregistry = require("./service-registry.js");
+function describePath(path, last) {
+    const keys = path.map((registration)=>registration.key);
+    return [
+        ...keys,
+        ...last == null ? [] : [
+            last
+        ]
+    ].map(_servicekey.describeKey).join(" → ");
+}
 class Crucible {
     key;
     instances = new Map();
@@ -21,7 +29,6 @@ class Crucible {
     parent;
     rootScope;
     scopes = new Map();
-    logger = _scribe.scribe.logger(Crucible.name);
     isDisposed = false;
     constructor(options){
         this.key = options?.key;
@@ -31,27 +38,26 @@ class Crucible {
         this.rootScope = options?.parent?.rootScope ?? this;
     }
     resolveMany(resolveRequest) {
-        const key = new _registrationkeymodel.RegistrationKey(resolveRequest);
-        const registrations = this.getRegistrationFrom(key) ?? [];
-        const services = Array.of();
-        for (const registration of registrations){
-            const service = this.resolveRegistration(registration);
-            services.push(service);
-        }
-        return services;
-    }
-    resolve(resolveRequest) {
-        const key = new _registrationkeymodel.RegistrationKey(resolveRequest);
-        const registration = this.getRegistrationFrom(key);
-        if (registration == null) {
-            this.logger.warn(`Cannot resolve dependency ${key.toString()}`);
-            return null;
+        return this.resolveAll(resolveRequest, []);
+    }
+    /** Throws {@link ResolveError} when nothing is registered for the key. */ resolve(resolveRequest) {
+        return this.resolveOne(resolveRequest, [], false);
+    }
+    resolveAll(key, path) {
+        const registrations = this.serviceRegistry.getRegistration(key) ?? [];
+        return registrations.map((registration)=>this.resolveRegistration(registration, path));
+    }
+    resolveOne(key, path, optional) {
+        const registrations = this.serviceRegistry.getRegistration(key);
+        if (registrations == null || registrations.length === 0) {
+            if (optional) return undefined;
+            const requiredBy = path.length === 0 ? "" : ` (required by ${describePath(path, key)})`;
+            throw new _errors.ResolveError(`Nothing is registered for ${(0, _servicekey.describeKey)(key)}${requiredBy}. Register it, or mark the parameter @optional().`);
         }
-        if (registration.length > 1) {
-            throw new _errors.ResolveError(`There are multiple services registered with key ${key.toString()}. Use resolveMany to resolve all implementations.`);
+        if (registrations.length > 1) {
+            throw new _errors.ResolveError(`There are multiple services registered with key ${(0, _servicekey.describeKey)(key)}. Use resolveMany to resolve all implementations.`);
         }
-        const service = this.resolveRegistration(registration[0]);
-        return service;
+        return this.resolveRegistration(registrations[0], path);
     }
     beginScope(name) {
         if (this.isDisposed) {
@@ -120,22 +126,35 @@ class Crucible {
             }
         }
     }
-    getRegistrationFrom(key) {
-        const registration = this.serviceRegistry.getRegistration(key.value);
-        return registration;
-    }
-    resolveRegistration(registration) {
+    resolveRegistration(registration, path) {
+        this.assertNoCycle(registration, path);
+        this.assertNotCaptive(registration, path);
         const { scope } = registration;
         switch(scope){
             case _const.Scopes.transient:
-                return this.createInstance(registration);
+                return this.createInstance(registration, path);
             case _const.Scopes.singleton:
-                return this.rootScope.getOrCreateInstance(registration);
+                return this.rootScope.getOrCreateInstance(registration, path);
             case _const.Scopes.request:
-                return this.getOrCreateInstance(registration);
+                return this.getOrCreateInstance(registration, path);
         }
     }
-    getOrCreateInstance(registration) {
+    assertNoCycle(registration, path) {
+        if (!path.includes(registration)) return;
+        throw new _errors.ResolveError(`Circular dependency: ${describePath(path, registration.key)}. Break the cycle, e.g. by resolving one side lazily from the LifetimeScope.`);
+    }
+    /**
+	 * A singleton lives for the whole process, so a request-scoped service it depends on (directly
+	 * or through transients) would be created once and then shared by every request, e.g. one
+	 * QueryRunner for the life of the process. The container's own lifetime scope is exempt: a
+	 * singleton asking for it gets the root, which is the scope it lives in.
+	 */ assertNotCaptive(registration, path) {
+        if (registration.scope !== _const.Scopes.request || registration.key === _const.LifetimeScopeToken) return;
+        const singleton = path.find((owner)=>owner.scope === _const.Scopes.singleton);
+        if (singleton == null) return;
+        throw new _errors.ResolveError(`Singleton ${(0, _servicekey.describeKey)(singleton.key)} depends on request-scoped ${(0, _servicekey.describeKey)(registration.key)} (${describePath(path, registration.key)}). A singleton would keep the first request's instance forever: make ${(0, _servicekey.describeKey)(singleton.key)} request-scoped, or resolve ${(0, _servicekey.describeKey)(registration.key)} per request from the LifetimeScope.`);
+    }
+    getOrCreateInstance(registration, path) {
         if (this.isDisposed) {
             throw new Error("This container has been disposed");
         }
@@ -146,31 +165,32 @@ class Crucible {
         if (existingInstance != null) {
             return existingInstance;
         }
-        const instance = isInstance ? type : this.createInstance(registration);
+        const instance = isInstance ? type : this.createInstance(registration, path);
         this.instances.set(cacheKey, instance);
         return instance;
     }
-    createInstance(registration) {
+    createInstance(registration, path) {
         const type = registration.type;
         const canConstruct = (0, _reflection.isConstructable)(type);
-        const deps = this.resolveDependencies(type);
+        const deps = this.resolveDependencies(type, [
+            ...path,
+            registration
+        ]);
         const inst = canConstruct ? new type(...deps) : type();
         return inst;
     }
-    resolveDependencies(type) {
+    resolveDependencies(type, path) {
         const params = (0, _reflection.getMeta)(_reflection.ReflectionMeta.paramtypes, type) ?? [];
         const injectTokens = (0, _reflection.getMeta)(_const.CrucibleMeta.injecttoken, type) ?? new Map();
-        //TODO: put a try catch here so we can throw the name of the service
-        let resolved = [];
-        for(let i = 0; i < params.length; i++){
-            const token = injectTokens.get(i)?.key ?? params[i].name;
-            const dep = (0, _reflection.isArrayType)(params[i]) ? this.resolveMany(token) : this.resolve(token);
-            resolved = [
-                ...resolved,
-                dep
-            ];
-        }
-        return resolved;
+        return params.map((param, index)=>{
+            const token = injectTokens.get(index);
+            const key = token?.key ?? param;
+            if (key == null || key === Object || token?.key == null && (0, _reflection.isArrayType)(param)) {
+                if (token?.optional) return undefined;
+                throw new _errors.ResolveError(`Cannot tell what to inject for constructor parameter ${index} of ${describePath(path)}: its type is not a class at run time (an interface, an array, or a type-only import). Add @inject(token) to the parameter.`);
+            }
+            return (0, _reflection.isArrayType)(param) ? this.resolveAll(key, path) : this.resolveOne(key, path, token?.optional === true);
+        });
     }
     releaseScope(name) {
         if (name == null) {

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

@@ -8,29 +8,30 @@ Object.defineProperty(exports, "ServiceRegistry", {
         return ServiceRegistry;
     }
 });
-const _registrationkeymodel = require("../models/registration-key.model.js");
+const _servicekey = require("../models/service-key.js");
 const _serviceregistrationmodel = require("../models/service-registration.model.js");
 const _errors = require("../types/errors.js");
 class ServiceRegistry {
-    registrations;
+    #registrations = new Map();
+    #parent;
     constructor(parent){
-        this.registrations = new Map(parent?.registrations);
+        this.#parent = parent;
     }
     registerType(scope, options) {
         const registration = this.createRegistrationFrom(scope, options);
         // Override means "this key now resolves to this", e.g. a test fake: replace every binding.
         if (options.override) {
-            this.setRegistration(registration.key, [
+            this.#registrations.set(registration.key, [
                 registration
             ]);
             return registration;
         }
-        const existing = this.getRegistrations(registration.key) ?? [];
+        const existing = this.getRegistration(registration.key) ?? [];
         const duplicate = existing.find((reg)=>reg.isEqual(registration));
         if (duplicate != null) {
-            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.`);
+            throw new _errors.RegistrationError(`A service is already registered for key ${(0, _servicekey.describeKey)(registration.key)}. Use builder.override.registerSingleton() (or the matching register* method) to replace it.`);
         }
-        this.setRegistration(registration.key, [
+        this.#registrations.set(registration.key, [
             ...existing,
             registration
         ]);
@@ -38,30 +39,19 @@ class ServiceRegistry {
     }
     replaceType(scope, options) {
         const registration = this.createRegistrationFrom(scope, options);
-        this.setRegistration(registration.key, [
+        this.#registrations.set(registration.key, [
             registration
         ]);
         return registration;
     }
     getRegistration(key) {
-        const keyVal = new _registrationkeymodel.RegistrationKey(key).value;
-        const registration = this.registrations.get(keyVal);
-        return registration;
+        return this.#registrations.get(key) ?? this.#parent?.getRegistration(key);
     }
     createRegistrationFrom(scope, options) {
         const { typeOrKey, typeOrInstance } = options;
         const isKey = typeof typeOrKey === "string" || typeof typeOrKey === "symbol";
         const isInstance = typeof typeOrInstance === "object";
-        const key = new _registrationkeymodel.RegistrationKey(!isKey ? typeOrKey.name : typeOrKey);
         const type = isInstance ? typeOrInstance : isKey ? typeOrInstance : typeOrKey;
-        const registration = new _serviceregistrationmodel.ServiceRegistration(key, type, scope, isInstance);
-        return registration;
-    }
-    getRegistrations(key) {
-        const value = key.value;
-        return this.registrations.get(value);
-    }
-    setRegistration(key, registrations) {
-        this.registrations.set(key.value, registrations);
+        return new _serviceregistrationmodel.ServiceRegistration(typeOrKey, type, scope, isInstance);
     }
 }

package/es6/src/decorators/inject.decorator.js

@@ -1,19 +1,30 @@
 import { defineMeta, getMeta } from "@decohere/nexus/reflection";
 import { CrucibleMeta } from "../const.js";
 /**
- * Bind a constructor parameter to a registration key.
- * A class uses `Class.name` (same key as `registerSingleton(Class)`).
- * Prefer the class over a name string. Use a symbol or string when the key is not the class name.
+ * Bind a constructor parameter to a registration key. Keys match by identity: a class matches only
+ * itself (not a string of its name), and a symbol only itself. Prefer the class; use a symbol for an
+ * interface or several implementations. `@inject(SomeClass)` also keeps SomeClass's import, which
+ * a parameter used only as a type can lose (its run-time type then collapses to `Object`).
  */ export function inject(key) {
-    return (target, _propertyKey, idx)=>{
-        const metadata = getExistingMeta(target);
-        metadata.set(idx, {
+    return updateToken((token)=>({
+            ...token,
             key
-        });
+        }));
+}
+/**
+ * Mark a constructor parameter as optional: when nothing is registered for it, the container
+ * passes `undefined` (so a default value applies) instead of throwing.
+ */ export function optional() {
+    return updateToken((token)=>({
+            ...token,
+            optional: true
+        }));
+}
+function updateToken(update) {
+    return (target, _propertyKey, idx)=>{
+        // Copy: the metadata can be inherited from a base class, which must not change.
+        const metadata = new Map(getMeta(CrucibleMeta.injecttoken, target));
+        metadata.set(idx, update(metadata.get(idx)));
         defineMeta(CrucibleMeta.injecttoken, metadata, target);
     };
 }
-function getExistingMeta(target) {
-    const meta = getMeta(CrucibleMeta.injecttoken, target) ?? new Map();
-    return meta;
-}

package/es6/src/models/service-key.js

@@ -0,0 +1,10 @@
+/** A readable name for a key, for error messages. */ export function describeKey(key) {
+    switch(typeof key){
+        case "string":
+            return `"${key}"`;
+        case "symbol":
+            return key.toString();
+        default:
+            return key.name || "(anonymous factory)";
+    }
+}

package/es6/src/services/crucible-builder.js

@@ -10,7 +10,7 @@ export class CrucibleBuilder {
         return this.createRegistrar(true);
     }
     registerType(type, scope = Scopes.transient) {
-        return this.register(false)(scope)(type.name, type);
+        return this.register(false)(scope)(type, type);
     }
     registerTypes(scopeOrType, ...types) {
         return this.registerMany(false, scopeOrType, types);
@@ -42,12 +42,12 @@ export class CrucibleBuilder {
             scopeOrType,
             ...types
         ];
-        return allTypes.map((type)=>bind(scope)(type.name, type));
+        return allTypes.map((type)=>bind(scope)(type, type));
     }
     createRegistrar(override) {
         const bind = this.register(override);
         return {
-            registerType: (type, scope = Scopes.transient)=>bind(scope)(type.name, type),
+            registerType: (type, scope = Scopes.transient)=>bind(scope)(type, type),
             registerTypes: (scopeOrType, ...types)=>this.registerMany(override, scopeOrType, types),
             registerTransient: (typeOrKey, type)=>bind(Scopes.transient)(typeOrKey, type),
             registerSingleton: (typeOrKey, typeOrInstance)=>bind(Scopes.singleton)(typeOrKey, typeOrInstance),

package/es6/src/services/crucible.js

@@ -1,9 +1,17 @@
 import { getMeta, isArrayType, isConstructable, ReflectionMeta } from "@decohere/nexus/reflection";
-import { scribe } from "@decohere/scribe";
 import { CrucibleMeta, LifetimeScopeToken, Scopes } from "../const.js";
-import { RegistrationKey } from "../models/registration-key.model.js";
+import { describeKey } from "../models/service-key.js";
 import { DuplicateScopeError, ResolveError } from "../types/errors.js";
 import { ServiceRegistry } from "./service-registry.js";
+function describePath(path, last) {
+    const keys = path.map((registration)=>registration.key);
+    return [
+        ...keys,
+        ...last == null ? [] : [
+            last
+        ]
+    ].map(describeKey).join(" → ");
+}
 export class Crucible {
     key;
     instances = new Map();
@@ -11,7 +19,6 @@ export class Crucible {
     parent;
     rootScope;
     scopes = new Map();
-    logger = scribe.logger(Crucible.name);
     isDisposed = false;
     constructor(options){
         this.key = options?.key;
@@ -21,27 +28,26 @@ export class Crucible {
         this.rootScope = options?.parent?.rootScope ?? this;
     }
     resolveMany(resolveRequest) {
-        const key = new RegistrationKey(resolveRequest);
-        const registrations = this.getRegistrationFrom(key) ?? [];
-        const services = Array.of();
-        for (const registration of registrations){
-            const service = this.resolveRegistration(registration);
-            services.push(service);
-        }
-        return services;
-    }
-    resolve(resolveRequest) {
-        const key = new RegistrationKey(resolveRequest);
-        const registration = this.getRegistrationFrom(key);
-        if (registration == null) {
-            this.logger.warn(`Cannot resolve dependency ${key.toString()}`);
-            return null;
+        return this.resolveAll(resolveRequest, []);
+    }
+    /** Throws {@link ResolveError} when nothing is registered for the key. */ resolve(resolveRequest) {
+        return this.resolveOne(resolveRequest, [], false);
+    }
+    resolveAll(key, path) {
+        const registrations = this.serviceRegistry.getRegistration(key) ?? [];
+        return registrations.map((registration)=>this.resolveRegistration(registration, path));
+    }
+    resolveOne(key, path, optional) {
+        const registrations = this.serviceRegistry.getRegistration(key);
+        if (registrations == null || registrations.length === 0) {
+            if (optional) return undefined;
+            const requiredBy = path.length === 0 ? "" : ` (required by ${describePath(path, key)})`;
+            throw new ResolveError(`Nothing is registered for ${describeKey(key)}${requiredBy}. Register it, or mark the parameter @optional().`);
         }
-        if (registration.length > 1) {
-            throw new ResolveError(`There are multiple services registered with key ${key.toString()}. Use resolveMany to resolve all implementations.`);
+        if (registrations.length > 1) {
+            throw new ResolveError(`There are multiple services registered with key ${describeKey(key)}. Use resolveMany to resolve all implementations.`);
         }
-        const service = this.resolveRegistration(registration[0]);
-        return service;
+        return this.resolveRegistration(registrations[0], path);
     }
     beginScope(name) {
         if (this.isDisposed) {
@@ -110,22 +116,35 @@ export class Crucible {
             }
         }
     }
-    getRegistrationFrom(key) {
-        const registration = this.serviceRegistry.getRegistration(key.value);
-        return registration;
-    }
-    resolveRegistration(registration) {
+    resolveRegistration(registration, path) {
+        this.assertNoCycle(registration, path);
+        this.assertNotCaptive(registration, path);
         const { scope } = registration;
         switch(scope){
             case Scopes.transient:
-                return this.createInstance(registration);
+                return this.createInstance(registration, path);
             case Scopes.singleton:
-                return this.rootScope.getOrCreateInstance(registration);
+                return this.rootScope.getOrCreateInstance(registration, path);
             case Scopes.request:
-                return this.getOrCreateInstance(registration);
+                return this.getOrCreateInstance(registration, path);
         }
     }
-    getOrCreateInstance(registration) {
+    assertNoCycle(registration, path) {
+        if (!path.includes(registration)) return;
+        throw new ResolveError(`Circular dependency: ${describePath(path, registration.key)}. Break the cycle, e.g. by resolving one side lazily from the LifetimeScope.`);
+    }
+    /**
+	 * A singleton lives for the whole process, so a request-scoped service it depends on (directly
+	 * or through transients) would be created once and then shared by every request, e.g. one
+	 * QueryRunner for the life of the process. The container's own lifetime scope is exempt: a
+	 * singleton asking for it gets the root, which is the scope it lives in.
+	 */ assertNotCaptive(registration, path) {
+        if (registration.scope !== Scopes.request || registration.key === LifetimeScopeToken) return;
+        const singleton = path.find((owner)=>owner.scope === Scopes.singleton);
+        if (singleton == null) return;
+        throw new ResolveError(`Singleton ${describeKey(singleton.key)} depends on request-scoped ${describeKey(registration.key)} (${describePath(path, registration.key)}). A singleton would keep the first request's instance forever: make ${describeKey(singleton.key)} request-scoped, or resolve ${describeKey(registration.key)} per request from the LifetimeScope.`);
+    }
+    getOrCreateInstance(registration, path) {
         if (this.isDisposed) {
             throw new Error("This container has been disposed");
         }
@@ -136,31 +155,32 @@ export class Crucible {
         if (existingInstance != null) {
             return existingInstance;
         }
-        const instance = isInstance ? type : this.createInstance(registration);
+        const instance = isInstance ? type : this.createInstance(registration, path);
         this.instances.set(cacheKey, instance);
         return instance;
     }
-    createInstance(registration) {
+    createInstance(registration, path) {
         const type = registration.type;
         const canConstruct = isConstructable(type);
-        const deps = this.resolveDependencies(type);
+        const deps = this.resolveDependencies(type, [
+            ...path,
+            registration
+        ]);
         const inst = canConstruct ? new type(...deps) : type();
         return inst;
     }
-    resolveDependencies(type) {
+    resolveDependencies(type, path) {
         const params = getMeta(ReflectionMeta.paramtypes, type) ?? [];
         const injectTokens = getMeta(CrucibleMeta.injecttoken, type) ?? new Map();
-        //TODO: put a try catch here so we can throw the name of the service
-        let resolved = [];
-        for(let i = 0; i < params.length; i++){
-            const token = injectTokens.get(i)?.key ?? params[i].name;
-            const dep = isArrayType(params[i]) ? this.resolveMany(token) : this.resolve(token);
-            resolved = [
-                ...resolved,
-                dep
-            ];
-        }
-        return resolved;
+        return params.map((param, index)=>{
+            const token = injectTokens.get(index);
+            const key = token?.key ?? param;
+            if (key == null || key === Object || token?.key == null && isArrayType(param)) {
+                if (token?.optional) return undefined;
+                throw new ResolveError(`Cannot tell what to inject for constructor parameter ${index} of ${describePath(path)}: its type is not a class at run time (an interface, an array, or a type-only import). Add @inject(token) to the parameter.`);
+            }
+            return isArrayType(param) ? this.resolveAll(key, path) : this.resolveOne(key, path, token?.optional === true);
+        });
     }
     releaseScope(name) {
         if (name == null) {

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

@@ -1,26 +1,31 @@
-import { RegistrationKey } from "../models/registration-key.model.js";
+import { describeKey } from "../models/service-key.js";
 import { ServiceRegistration } from "../models/service-registration.model.js";
 import { RegistrationError } from "../types/errors.js";
-export class ServiceRegistry {
-    registrations;
+/**
+ * Registrations by key. A scope's registry holds only what the scope adds (its own lifetime
+ * scope) and looks everything else up in its parent, so beginning a scope costs the same however
+ * many services are registered.
+ */ export class ServiceRegistry {
+    #registrations = new Map();
+    #parent;
     constructor(parent){
-        this.registrations = new Map(parent?.registrations);
+        this.#parent = parent;
     }
     registerType(scope, options) {
         const registration = this.createRegistrationFrom(scope, options);
         // Override means "this key now resolves to this", e.g. a test fake: replace every binding.
         if (options.override) {
-            this.setRegistration(registration.key, [
+            this.#registrations.set(registration.key, [
                 registration
             ]);
             return registration;
         }
-        const existing = this.getRegistrations(registration.key) ?? [];
+        const existing = this.getRegistration(registration.key) ?? [];
         const duplicate = existing.find((reg)=>reg.isEqual(registration));
         if (duplicate != null) {
-            throw new RegistrationError(`A service is already registered for key ${registration.key}. Use builder.override.registerSingleton() (or the matching register* method) to replace it.`);
+            throw new RegistrationError(`A service is already registered for key ${describeKey(registration.key)}. Use builder.override.registerSingleton() (or the matching register* method) to replace it.`);
         }
-        this.setRegistration(registration.key, [
+        this.#registrations.set(registration.key, [
             ...existing,
             registration
         ]);
@@ -28,30 +33,19 @@ export class ServiceRegistry {
     }
     replaceType(scope, options) {
         const registration = this.createRegistrationFrom(scope, options);
-        this.setRegistration(registration.key, [
+        this.#registrations.set(registration.key, [
             registration
         ]);
         return registration;
     }
     getRegistration(key) {
-        const keyVal = new RegistrationKey(key).value;
-        const registration = this.registrations.get(keyVal);
-        return registration;
+        return this.#registrations.get(key) ?? this.#parent?.getRegistration(key);
     }
     createRegistrationFrom(scope, options) {
         const { typeOrKey, typeOrInstance } = options;
         const isKey = typeof typeOrKey === "string" || typeof typeOrKey === "symbol";
         const isInstance = typeof typeOrInstance === "object";
-        const key = new RegistrationKey(!isKey ? typeOrKey.name : typeOrKey);
         const type = isInstance ? typeOrInstance : isKey ? typeOrInstance : typeOrKey;
-        const registration = new ServiceRegistration(key, type, scope, isInstance);
-        return registration;
-    }
-    getRegistrations(key) {
-        const value = key.value;
-        return this.registrations.get(value);
-    }
-    setRegistration(key, registrations) {
-        this.registrations.set(key.value, registrations);
+        return new ServiceRegistration(typeOrKey, type, scope, isInstance);
     }
 }

package/package.json

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

package/types/src/decorators/inject.decorator.d.ts

@@ -1,11 +1,20 @@
-import { type Constructable } from "@decohere/nexus/reflection";
+import type { ServiceKey } from "../models/service-key.js";
 export type InjectionMetadata = Map<number, InjectionToken>;
 export type InjectionToken = {
-    key: string | symbol | Constructable;
+    /** The key to resolve; without one, the parameter's type is the key. */
+    key?: ServiceKey;
+    /** Pass `undefined` instead of throwing when nothing is registered for the key. */
+    optional?: boolean;
 };
 /**
- * Bind a constructor parameter to a registration key.
- * A class uses `Class.name` (same key as `registerSingleton(Class)`).
- * Prefer the class over a name string. Use a symbol or string when the key is not the class name.
+ * Bind a constructor parameter to a registration key. Keys match by identity: a class matches only
+ * itself (not a string of its name), and a symbol only itself. Prefer the class; use a symbol for an
+ * interface or several implementations. `@inject(SomeClass)` also keeps SomeClass's import, which
+ * a parameter used only as a type can lose (its run-time type then collapses to `Object`).
  */
-export declare function inject(key: string | symbol | Constructable): (target: object, _propertyKey: string | symbol | undefined, idx: number) => void;
+export declare function inject(key: ServiceKey): (target: object, _propertyKey: string | symbol | undefined, idx: number) => void;
+/**
+ * Mark a constructor parameter as optional: when nothing is registered for it, the container
+ * passes `undefined` (so a default value applies) instead of throwing.
+ */
+export declare function optional(): (target: object, _propertyKey: string | symbol | undefined, idx: number) => void;

package/types/src/models/service-key.d.ts

@@ -0,0 +1,9 @@
+import type { Constructable, FunctionType } from "@decohere/nexus/reflection";
+/**
+ * What a service is registered and resolved under, compared by identity: the class (or factory)
+ * itself, a symbol, or a string. A string never matches a class with that name, and two symbols
+ * with the same description are different keys.
+ */
+export type ServiceKey = string | symbol | Constructable | FunctionType;
+/** A readable name for a key, for error messages. */
+export declare function describeKey(key: ServiceKey): string;

package/types/src/models/service-registration.model.d.ts

@@ -1,12 +1,12 @@
 import type { Constructable, FunctionType } from "@decohere/nexus/reflection";
 import type { Scope } from "../types/types.js";
-import type { RegistrationKey } from "./registration-key.model.js";
+import type { ServiceKey } from "./service-key.js";
 export declare class ServiceRegistration {
-    key: RegistrationKey;
+    key: ServiceKey;
     scope: Scope;
     type: Constructable | FunctionType | object;
     isInstance: boolean;
-    constructor(key: RegistrationKey, type: Constructable | FunctionType | object, scope: Scope, isInstance: boolean);
+    constructor(key: ServiceKey, type: Constructable | FunctionType | object, scope: Scope, isInstance: boolean);
     /** Same class, or the same instance object. */
     isEqual(other: ServiceRegistration): boolean;
 }

package/types/src/services/crucible.d.ts

@@ -12,18 +12,27 @@ export declare class Crucible implements IContainer {
     private parent?;
     private rootScope;
     private scopes;
-    private logger;
     private isDisposed;
     constructor(options?: CrucibleOptions);
     resolveMany<T extends object = object>(resolveRequest: ResolveRequest<T>): T[];
+    /** Throws {@link ResolveError} when nothing is registered for the key. */
     resolve<T extends object | object[]>(resolveRequest: ResolveRequest<T>): T;
+    private resolveAll;
+    private resolveOne;
     beginScope(name?: string): Crucible;
     [Symbol.dispose](): void;
     [Symbol.asyncDispose](): Promise<void>;
     private disposeSync;
     private disposeAsync;
-    private getRegistrationFrom;
     private resolveRegistration;
+    private assertNoCycle;
+    /**
+     * A singleton lives for the whole process, so a request-scoped service it depends on (directly
+     * or through transients) would be created once and then shared by every request, e.g. one
+     * QueryRunner for the life of the process. The container's own lifetime scope is exempt: a
+     * singleton asking for it gets the root, which is the scope it lives in.
+     */
+    private assertNotCaptive;
     private getOrCreateInstance;
     private createInstance;
     private resolveDependencies;

package/types/src/services/service-registry.d.ts

@@ -1,18 +1,22 @@
 import type { Constructable, FunctionType } from "@decohere/nexus/reflection";
+import { type ServiceKey } from "../models/service-key.js";
 import { ServiceRegistration } from "../models/service-registration.model.js";
 import type { Scope } from "../types/types.js";
 export type RegisterTypeOptions = {
-    typeOrKey: string | symbol | Constructable | FunctionType;
+    typeOrKey: ServiceKey;
     typeOrInstance?: Constructable | FunctionType | object;
     override?: boolean;
 };
+/**
+ * Registrations by key. A scope's registry holds only what the scope adds (its own lifetime
+ * scope) and looks everything else up in its parent, so beginning a scope costs the same however
+ * many services are registered.
+ */
 export declare class ServiceRegistry {
-    private readonly registrations;
+    #private;
     constructor(parent?: ServiceRegistry);
     registerType(scope: Scope, options: RegisterTypeOptions): ServiceRegistration;
     replaceType(scope: Scope, options: RegisterTypeOptions): ServiceRegistration;
-    getRegistration(key: string | symbol | Constructable): ServiceRegistration[];
+    getRegistration(key: ServiceKey): ServiceRegistration[] | undefined;
     private createRegistrationFrom;
-    private getRegistrations;
-    private setRegistration;
 }

package/commonjs/src/models/registration-key.model.js

@@ -1,29 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", {
-    value: true
-});
-Object.defineProperty(exports, "RegistrationKey", {
-    enumerable: true,
-    get: function() {
-        return RegistrationKey;
-    }
-});
-class RegistrationKey {
-    constructor(key){
-        this.value = this.getValue(key);
-    }
-    value;
-    getValue(key) {
-        switch(typeof key){
-            case "string":
-                return key;
-            case "symbol":
-                return key.valueOf().description;
-            default:
-                return key.name;
-        }
-    }
-    toString() {
-        return this.value;
-    }
-}

package/es6/src/models/registration-key.model.js

@@ -1,19 +0,0 @@
-export class RegistrationKey {
-    constructor(key){
-        this.value = this.getValue(key);
-    }
-    value;
-    getValue(key) {
-        switch(typeof key){
-            case "string":
-                return key;
-            case "symbol":
-                return key.valueOf().description;
-            default:
-                return key.name;
-        }
-    }
-    toString() {
-        return this.value;
-    }
-}

package/types/src/models/registration-key.model.d.ts

@@ -1,7 +0,0 @@
-import type { Constructable } from "@decohere/nexus/reflection";
-export declare class RegistrationKey {
-    constructor(key: string | symbol | Constructable);
-    value: string;
-    private getValue;
-    toString(): string;
-}