@decohere/crucible 0.0.1-dev.19 → 0.0.1-dev.20261105.103

package/es6/src/services/container.js

@@ -0,0 +1,197 @@
+import { getMeta, isArrayType, isConstructable, ReflectionMeta } from "@decohere/core/reflection";
+import { ContainerMeta, LifetimeScopeToken, Scopes } from "../const.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 Container {
+    key;
+    instances = new Map();
+    serviceRegistry;
+    parent;
+    rootScope;
+    scopes = new Map();
+    isDisposed = false;
+    constructor(options){
+        this.key = options?.key;
+        this.serviceRegistry = new ServiceRegistry(options?.serviceRegistry);
+        this.registerLifetimeScope();
+        this.parent = options?.parent;
+        this.rootScope = options?.parent?.rootScope ?? this;
+    }
+    resolveMany(resolveRequest) {
+        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 (registrations.length > 1) {
+            throw new ResolveError(`There are multiple services registered with key ${describeKey(key)}. Use resolveMany to resolve all implementations.`);
+        }
+        return this.resolveRegistration(registrations[0], path);
+    }
+    beginScope(name) {
+        if (this.isDisposed) {
+            throw new Error("This container has been disposed");
+        }
+        if (name != null && this.scopes.has(name)) {
+            throw new DuplicateScopeError(`Cannot create duplicate scope. Scope with ${name} is already created and has not been disposed.`);
+        }
+        const scope = new Container({
+            key: name,
+            serviceRegistry: this.serviceRegistry,
+            parent: this
+        });
+        if (name != null) {
+            this.scopes.set(name, scope);
+        }
+        return scope;
+    }
+    [Symbol.dispose]() {
+        if (this.isDisposed) {
+            return;
+        }
+        this.disposeSync();
+    }
+    async [Symbol.asyncDispose]() {
+        if (this.isDisposed) {
+            return;
+        }
+        await this.disposeAsync();
+    }
+    disposeSync() {
+        if (this.isDisposed) {
+            return;
+        }
+        this.isDisposed = true;
+        this.parent?.releaseScope(this.key);
+        this.scopes.clear();
+        // Reverse creation order: dependents are cleaned up before what they depend on.
+        for (const inst of [
+            ...this.instances.values()
+        ].reverse()){
+            if (inst === this) {
+                continue;
+            }
+            inst[Symbol.dispose]?.();
+        }
+    }
+    async disposeAsync() {
+        if (this.isDisposed) {
+            return;
+        }
+        this.isDisposed = true;
+        this.parent?.releaseScope(this.key);
+        this.scopes.clear();
+        // Reverse creation order: dependents are cleaned up before what they depend on.
+        for (const inst of [
+            ...this.instances.values()
+        ].reverse()){
+            if (inst === this) {
+                continue;
+            }
+            if (Symbol.asyncDispose in inst) {
+                await inst[Symbol.asyncDispose]();
+            } else {
+                inst[Symbol.dispose]?.();
+            }
+        }
+    }
+    resolveRegistration(registration, path) {
+        this.assertNoCycle(registration, path);
+        this.assertNotCaptive(registration, path);
+        const { scope } = registration;
+        switch(scope){
+            case Scopes.transient:
+                return this.createInstance(registration, path);
+            case Scopes.singleton:
+                return this.rootScope.getOrCreateInstance(registration, path);
+            case Scopes.request:
+                return this.getOrCreateInstance(registration, path);
+        }
+    }
+    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");
+        }
+        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;
+        }
+        const instance = isInstance ? type : this.createInstance(registration, path);
+        this.instances.set(cacheKey, instance);
+        return instance;
+    }
+    createInstance(registration, path) {
+        const type = registration.type;
+        const canConstruct = isConstructable(type);
+        const deps = this.resolveDependencies(type, [
+            ...path,
+            registration
+        ]);
+        const inst = canConstruct ? new type(...deps) : type();
+        return inst;
+    }
+    resolveDependencies(type, path) {
+        const params = getMeta(ReflectionMeta.paramtypes, type) ?? [];
+        const injectTokens = getMeta(ContainerMeta.injecttoken, type) ?? new Map();
+        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) {
+            return;
+        }
+        this.scopes.delete(name);
+    }
+    registerLifetimeScope() {
+        this.serviceRegistry.replaceType(Scopes.request, {
+            typeOrKey: LifetimeScopeToken,
+            typeOrInstance: this
+        });
+    }
+}

package/es6/src/services/index.js

@@ -1,4 +1,2 @@
-export * from "./crucible.js";
-export * from "./crucible-builder.js";
-
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbIi9ob21lL3J1bm5lci93b3JrL2RlY29oZXJlL2RlY29oZXJlL3Byb2plY3RzL2NydWNpYmxlL3NyYy9zZXJ2aWNlcy9pbmRleC50cyJdLCJzb3VyY2VzQ29udGVudCI6WyJleHBvcnQgKiBmcm9tIFwiLi9jcnVjaWJsZS5qc1wiO1xuZXhwb3J0ICogZnJvbSBcIi4vY3J1Y2libGUtYnVpbGRlci5qc1wiO1xuIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsZ0JBQWdCO0FBQzlCLGNBQWMsd0JBQXdCIn0=
+export * from "./container.js";
+export * from "./service-container-builder.js";

package/es6/src/services/service-container-builder.js

@@ -0,0 +1,57 @@
+import { Scopes } from "../const.js";
+import { Container } from "./container.js";
+import { ServiceRegistry } from "./service-registry.js";
+export class ServiceContainerBuilder {
+    serviceRegistry;
+    constructor(options){
+        this.serviceRegistry = options?.serviceRegistry ?? new ServiceRegistry();
+    }
+    get override() {
+        return this.createRegistrar(true);
+    }
+    registerType(type, scope = Scopes.transient) {
+        return this.register(false)(scope)(type, type);
+    }
+    registerTypes(scopeOrType, ...types) {
+        return this.registerMany(false, scopeOrType, types);
+    }
+    registerTransient(typeOrKey, type) {
+        return this.register(false)(Scopes.transient)(typeOrKey, type);
+    }
+    registerSingleton(typeOrKey, typeOrInstance) {
+        return this.register(false)(Scopes.singleton)(typeOrKey, typeOrInstance);
+    }
+    registerRequestScoped(typeOrKey, type) {
+        return this.register(false)(Scopes.request)(typeOrKey, type);
+    }
+    build() {
+        return new Container({
+            serviceRegistry: this.serviceRegistry
+        });
+    }
+    register = (override)=>(scope)=>(typeOrKey, typeOrInstance)=>this.serviceRegistry.registerType(scope, {
+                    typeOrKey,
+                    typeOrInstance,
+                    override
+                });
+    registerMany(override, scopeOrType, types) {
+        const bind = this.register(override);
+        const isScope = typeof scopeOrType !== "function";
+        const scope = isScope ? scopeOrType : Scopes.transient;
+        const allTypes = isScope ? types : [
+            scopeOrType,
+            ...types
+        ];
+        return allTypes.map((type)=>bind(scope)(type, type));
+    }
+    createRegistrar(override) {
+        const bind = this.register(override);
+        return {
+            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),
+            registerRequestScoped: (typeOrKey, type)=>bind(Scopes.request)(typeOrKey, type)
+        };
+    }
+}

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

@@ -1,40 +1,51 @@
-import { RegistrationKey } from "../models/registration-key.model.js";
+import { describeKey } from "../models/service-key.js";
 import { ServiceRegistration } from "../models/service-registration.model.js";
-export class ServiceRegistry {
-    registrations;
+import { RegistrationError } from "../types/errors.js";
+/**
+ * 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);
-        const existingRegistration = this.getRegistrations(registration.key)?.filter((reg)=>!reg.isEqual(registration)) ?? [];
-        this.setRegistration(registration.key, [
-            registration,
-            ...existingRegistration
+        // Override means "this key now resolves to this", e.g. a test fake: replace every binding.
+        if (options.override) {
+            this.#registrations.set(registration.key, [
+                registration
+            ]);
+            return registration;
+        }
+        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 ${describeKey(registration.key)}. Use builder.override.registerSingleton() (or the matching register* method) to replace it.`);
+        }
+        this.#registrations.set(registration.key, [
+            ...existing,
+            registration
         ]);
         return registration;
     }
-    getRegistration(key) {
-        const keyVal = new RegistrationKey(key).value;
-        const registration = this.registrations.get(keyVal);
+    replaceType(scope, options) {
+        const registration = this.createRegistrationFrom(scope, options);
+        this.#registrations.set(registration.key, [
+            registration
+        ]);
         return registration;
     }
+    getRegistration(key) {
+        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);
     }
 }
-
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbIi9ob21lL3J1bm5lci93b3JrL2RlY29oZXJlL2RlY29oZXJlL3Byb2plY3RzL2NydWNpYmxlL3NyYy9zZXJ2aWNlcy9zZXJ2aWNlLXJlZ2lzdHJ5LnRzIl0sInNvdXJjZXNDb250ZW50IjpbImltcG9ydCB0eXBlIHsgQ29uc3RydWN0YWJsZSwgRnVuY3Rpb25UeXBlIH0gZnJvbSBcIkBkZWNvaGVyZS9uZXh1cy9yZWZsZWN0aW9uXCI7XG5pbXBvcnQgeyBSZWdpc3RyYXRpb25LZXkgfSBmcm9tIFwiLi4vbW9kZWxzL3JlZ2lzdHJhdGlvbi1rZXkubW9kZWwuanNcIjtcbmltcG9ydCB7IFNlcnZpY2VSZWdpc3RyYXRpb24gfSBmcm9tIFwiLi4vbW9kZWxzL3NlcnZpY2UtcmVnaXN0cmF0aW9uLm1vZGVsLmpzXCI7XG5pbXBvcnQgdHlwZSB7IFNjb3BlIH0gZnJvbSBcIi4uL3R5cGVzL3R5cGVzLmpzXCI7XG5cbmV4cG9ydCB0eXBlIFJlZ2lzdGVyVHlwZU9wdGlvbnMgPSB7XG5cdHR5cGVPcktleTogc3RyaW5nIHwgc3ltYm9sIHwgQ29uc3RydWN0YWJsZSB8IEZ1bmN0aW9uVHlwZTtcblx0dHlwZU9ySW5zdGFuY2U/OiBDb25zdHJ1Y3RhYmxlIHwgRnVuY3Rpb25UeXBlIHwgb2JqZWN0O1xufTtcblxuZXhwb3J0IGNsYXNzIFNlcnZpY2VSZWdpc3RyeSB7XG5cdHByaXZhdGUgcmVhZG9ubHkgcmVnaXN0cmF0aW9uczogTWFwPHN0cmluZywgU2VydmljZVJlZ2lzdHJhdGlvbltdPjtcblx0cHVibGljIGNvbnN0cnVjdG9yKHBhcmVudD86IFNlcnZpY2VSZWdpc3RyeSkge1xuXHRcdHRoaXMucmVnaXN0cmF0aW9ucyA9IG5ldyBNYXAocGFyZW50Py5yZWdpc3RyYXRpb25zKTtcblx0fVxuXG5cdHB1YmxpYyByZWdpc3RlclR5cGUoc2NvcGU6IFNjb3BlLCBvcHRpb25zOiBSZWdpc3RlclR5cGVPcHRpb25zKSB7XG5cdFx0Y29uc3QgcmVnaXN0cmF0aW9uID0gdGhpcy5jcmVhdGVSZWdpc3RyYXRpb25Gcm9tKHNjb3BlLCBvcHRpb25zKTtcblx0XHRjb25zdCBleGlzdGluZ1JlZ2lzdHJhdGlvbiA9XG5cdFx0XHR0aGlzLmdldFJlZ2lzdHJhdGlvbnMocmVnaXN0cmF0aW9uLmtleSk/LmZpbHRlcigocmVnKSA9PiAhcmVnLmlzRXF1YWwocmVnaXN0cmF0aW9uKSkgPz9cblx0XHRcdFtdO1xuXG5cdFx0dGhpcy5zZXRSZWdpc3RyYXRpb24ocmVnaXN0cmF0aW9uLmtleSwgW3JlZ2lzdHJhdGlvbiwgLi4uZXhpc3RpbmdSZWdpc3RyYXRpb25dKTtcblx0XHRyZXR1cm4gcmVnaXN0cmF0aW9uO1xuXHR9XG5cblx0cHVibGljIGdldFJlZ2lzdHJhdGlvbihrZXk6IHN0cmluZyB8IHN5bWJvbCB8IENvbnN0cnVjdGFibGUpOiBTZXJ2aWNlUmVnaXN0cmF0aW9uW10ge1xuXHRcdGNvbnN0IGtleVZhbCA9IG5ldyBSZWdpc3RyYXRpb25LZXkoa2V5KS52YWx1ZTtcblx0XHRjb25zdCByZWdpc3RyYXRpb24gPSB0aGlzLnJlZ2lzdHJhdGlvbnMuZ2V0KGtleVZhbCk7XG5cdFx0cmV0dXJuIHJlZ2lzdHJhdGlvbjtcblx0fVxuXG5cdHByaXZhdGUgY3JlYXRlUmVnaXN0cmF0aW9uRnJvbShzY29wZTogU2NvcGUsIG9wdGlvbnM6IFJlZ2lzdGVyVHlwZU9wdGlvbnMpIHtcblx0XHRjb25zdCB7IHR5cGVPcktleSwgdHlwZU9ySW5zdGFuY2UgfSA9IG9wdGlvbnM7XG5cdFx0Y29uc3QgaXNLZXkgPSB0eXBlb2YgdHlwZU9yS2V5ID09PSBcInN0cmluZ1wiIHx8IHR5cGVvZiB0eXBlT3JLZXkgPT09IFwic3ltYm9sXCI7XG5cdFx0Y29uc3QgaXNJbnN0YW5jZSA9IHR5cGVvZiB0eXBlT3JJbnN0YW5jZSA9PT0gXCJvYmplY3RcIjtcblx0XHRjb25zdCBrZXkgPSBuZXcgUmVnaXN0cmF0aW9uS2V5KCFpc0tleSA/IHR5cGVPcktleS5uYW1lIDogdHlwZU9yS2V5KTtcblx0XHRjb25zdCB0eXBlID0gaXNJbnN0YW5jZSA/IHR5cGVPckluc3RhbmNlIDogaXNLZXkgPyB0eXBlT3JJbnN0YW5jZSA6IHR5cGVPcktleTtcblx0XHRjb25zdCByZWdpc3RyYXRpb24gPSBuZXcgU2VydmljZVJlZ2lzdHJhdGlvbihrZXksIHR5cGUsIHNjb3BlLCBpc0luc3RhbmNlKTtcblx0XHRyZXR1cm4gcmVnaXN0cmF0aW9uO1xuXHR9XG5cblx0cHJpdmF0ZSBnZXRSZWdpc3RyYXRpb25zKGtleTogUmVnaXN0cmF0aW9uS2V5KSB7XG5cdFx0Y29uc3QgdmFsdWUgPSBrZXkudmFsdWU7XG5cdFx0cmV0dXJuIHRoaXMucmVnaXN0cmF0aW9ucy5nZXQodmFsdWUpO1xuXHR9XG5cblx0cHJpdmF0ZSBzZXRSZWdpc3RyYXRpb24oa2V5OiBSZWdpc3RyYXRpb25LZXksIHJlZ2lzdHJhdGlvbnM6IFNlcnZpY2VSZWdpc3RyYXRpb25bXSkge1xuXHRcdHRoaXMucmVnaXN0cmF0aW9ucy5zZXQoa2V5LnZhbHVlLCByZWdpc3RyYXRpb25zKTtcblx0fVxufVxuIl0sIm5hbWVzIjpbIlJlZ2lzdHJhdGlvbktleSIsIlNlcnZpY2VSZWdpc3RyYXRpb24iLCJTZXJ2aWNlUmVnaXN0cnkiLCJyZWdpc3RyYXRpb25zIiwicGFyZW50IiwiTWFwIiwicmVnaXN0ZXJUeXBlIiwic2NvcGUiLCJvcHRpb25zIiwicmVnaXN0cmF0aW9uIiwiY3JlYXRlUmVnaXN0cmF0aW9uRnJvbSIsImV4aXN0aW5nUmVnaXN0cmF0aW9uIiwiZ2V0UmVnaXN0cmF0aW9ucyIsImtleSIsImZpbHRlciIsInJlZyIsImlzRXF1YWwiLCJzZXRSZWdpc3RyYXRpb24iLCJnZXRSZWdpc3RyYXRpb24iLCJrZXlWYWwiLCJ2YWx1ZSIsImdldCIsInR5cGVPcktleSIsInR5cGVPckluc3RhbmNlIiwiaXNLZXkiLCJpc0luc3RhbmNlIiwibmFtZSIsInR5cGUiLCJzZXQiXSwibWFwcGluZ3MiOiJBQUNBLFNBQVNBLGVBQWUsUUFBUSxzQ0FBc0M7QUFDdEUsU0FBU0MsbUJBQW1CLFFBQVEsMENBQTBDO0FBUTlFLE9BQU8sTUFBTUM7SUFDS0MsY0FBa0Q7SUFDbkUsWUFBbUJDLE1BQXdCLENBQUU7UUFDNUMsSUFBSSxDQUFDRCxhQUFhLEdBQUcsSUFBSUUsSUFBSUQsUUFBUUQ7SUFDdEM7SUFFT0csYUFBYUMsS0FBWSxFQUFFQyxPQUE0QixFQUFFO1FBQy9ELE1BQU1DLGVBQWUsSUFBSSxDQUFDQyxzQkFBc0IsQ0FBQ0gsT0FBT0M7UUFDeEQsTUFBTUcsdUJBQ0wsSUFBSSxDQUFDQyxnQkFBZ0IsQ0FBQ0gsYUFBYUksR0FBRyxHQUFHQyxPQUFPLENBQUNDLE1BQVEsQ0FBQ0EsSUFBSUMsT0FBTyxDQUFDUCxrQkFDdEUsRUFBRTtRQUVILElBQUksQ0FBQ1EsZUFBZSxDQUFDUixhQUFhSSxHQUFHLEVBQUU7WUFBQ0o7ZUFBaUJFO1NBQXFCO1FBQzlFLE9BQU9GO0lBQ1I7SUFFT1MsZ0JBQWdCTCxHQUFvQyxFQUF5QjtRQUNuRixNQUFNTSxTQUFTLElBQUluQixnQkFBZ0JhLEtBQUtPLEtBQUs7UUFDN0MsTUFBTVgsZUFBZSxJQUFJLENBQUNOLGFBQWEsQ0FBQ2tCLEdBQUcsQ0FBQ0Y7UUFDNUMsT0FBT1Y7SUFDUjtJQUVRQyx1QkFBdUJILEtBQVksRUFBRUMsT0FBNEIsRUFBRTtRQUMxRSxNQUFNLEVBQUVjLFNBQVMsRUFBRUMsY0FBYyxFQUFFLEdBQUdmO1FBQ3RDLE1BQU1nQixRQUFRLE9BQU9GLGNBQWMsWUFBWSxPQUFPQSxjQUFjO1FBQ3BFLE1BQU1HLGFBQWEsT0FBT0YsbUJBQW1CO1FBQzdDLE1BQU1WLE1BQU0sSUFBSWIsZ0JBQWdCLENBQUN3QixRQUFRRixVQUFVSSxJQUFJLEdBQUdKO1FBQzFELE1BQU1LLE9BQU9GLGFBQWFGLGlCQUFpQkMsUUFBUUQsaUJBQWlCRDtRQUNwRSxNQUFNYixlQUFlLElBQUlSLG9CQUFvQlksS0FBS2MsTUFBTXBCLE9BQU9rQjtRQUMvRCxPQUFPaEI7SUFDUjtJQUVRRyxpQkFBaUJDLEdBQW9CLEVBQUU7UUFDOUMsTUFBTU8sUUFBUVAsSUFBSU8sS0FBSztRQUN2QixPQUFPLElBQUksQ0FBQ2pCLGFBQWEsQ0FBQ2tCLEdBQUcsQ0FBQ0Q7SUFDL0I7SUFFUUgsZ0JBQWdCSixHQUFvQixFQUFFVixhQUFvQyxFQUFFO1FBQ25GLElBQUksQ0FBQ0EsYUFBYSxDQUFDeUIsR0FBRyxDQUFDZixJQUFJTyxLQUFLLEVBQUVqQjtJQUNuQztBQUNEIn0=

package/es6/src/types/errors.js

@@ -4,5 +4,3 @@ export class DuplicateScopeError extends Error {
 }
 export class RegistrationError extends Error {
 }
-
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbIi9ob21lL3J1bm5lci93b3JrL2RlY29oZXJlL2RlY29oZXJlL3Byb2plY3RzL2NydWNpYmxlL3NyYy90eXBlcy9lcnJvcnMudHMiXSwic291cmNlc0NvbnRlbnQiOlsiZXhwb3J0IGNsYXNzIFJlc29sdmVFcnJvciBleHRlbmRzIEVycm9yIHt9XG5leHBvcnQgY2xhc3MgRHVwbGljYXRlU2NvcGVFcnJvciBleHRlbmRzIEVycm9yIHt9XG5leHBvcnQgY2xhc3MgUmVnaXN0cmF0aW9uRXJyb3IgZXh0ZW5kcyBFcnJvciB7fVxuIl0sIm5hbWVzIjpbIlJlc29sdmVFcnJvciIsIkVycm9yIiwiRHVwbGljYXRlU2NvcGVFcnJvciIsIlJlZ2lzdHJhdGlvbkVycm9yIl0sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLE1BQU1BLHFCQUFxQkM7QUFBTztBQUN6QyxPQUFPLE1BQU1DLDRCQUE0QkQ7QUFBTztBQUNoRCxPQUFPLE1BQU1FLDBCQUEwQkY7QUFBTyJ9

package/es6/src/types/index.js

@@ -1,3 +1,2 @@
+export * from "./errors.js";
 export * from "./types.js";
-
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbIi9ob21lL3J1bm5lci93b3JrL2RlY29oZXJlL2RlY29oZXJlL3Byb2plY3RzL2NydWNpYmxlL3NyYy90eXBlcy9pbmRleC50cyJdLCJzb3VyY2VzQ29udGVudCI6WyJleHBvcnQgKiBmcm9tIFwiLi90eXBlcy5qc1wiO1xuIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsYUFBYSJ9

package/es6/src/types/types.js

@@ -1,3 +1 @@
 export { };
-
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbIi9ob21lL3J1bm5lci93b3JrL2RlY29oZXJlL2RlY29oZXJlL3Byb2plY3RzL2NydWNpYmxlL3NyYy90eXBlcy90eXBlcy50cyJdLCJzb3VyY2VzQ29udGVudCI6WyJleHBvcnQgdHlwZSB7XG5cdENvbnRhaW5lckJ1aWxkZXIsXG5cdElDb250YWluZXIsXG5cdExpZmV0aW1lU2NvcGUsXG5cdFJlc29sdmVSZXF1ZXN0LFxuXHRTY29wZSxcblx0U2VydmljZVByb3ZpZGVyLFxufSBmcm9tIFwiQGRlY29oZXJlL25leHVzL2NvbXBvc2l0aW9uXCI7XG4iXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsV0FPcUMifQ==

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decohere/crucible",
-  "version": "0.0.1-dev.19",
+  "version": "0.0.1-dev.20261105.103",
   "description": "Lightweight dependency injection container with decorator-based wiring",
   "keywords": [
     "typescript",
@@ -10,6 +10,15 @@
     "decorators",
     "decohere"
   ],
+  "homepage": "https://github.com/typesmiths/decohere/tree/main/projects/crucible#readme",
+  "bugs": {
+    "url": "https://github.com/typesmiths/decohere/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/typesmiths/decohere.git",
+    "directory": "projects/crucible"
+  },
   "license": "ISC",
   "author": "Typesmiths",
   "type": "module",
@@ -17,21 +26,18 @@
   "exports": {
     ".": {
       "types": "./types/src/index.d.ts",
-      "import": "./es6/src/index.js",
-      "require": "./commonjs/src/index.js"
+      "import": "./es6/src/index.js"
     },
     "./decorators": {
       "types": "./types/src/decorators/index.d.ts",
-      "import": "./es6/src/decorators/index.js",
-      "require": "./commonjs/src/decorators/index.js"
+      "import": "./es6/src/decorators/index.js"
     }
   },
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "dependencies": {
-    "@decohere/nexus": "0.0.1-dev.19",
-    "@decohere/scribe": "0.0.1-dev.19"
+    "@decohere/core": "0.0.1-dev.20261105.103"
   },
   "devDependencies": {}
 }

package/types/src/const.d.ts

@@ -1,5 +1,5 @@
 export declare const LifetimeScopeToken: unique symbol;
-export declare const CrucibleMeta: {
+export declare const ContainerMeta: {
     injecttoken: string;
 };
 export declare const Scopes: {

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

@@ -1,5 +1,20 @@
+import type { ServiceKey } from "../models/service-key.js";
 export type InjectionMetadata = Map<number, InjectionToken>;
 export type InjectionToken = {
-    key: string | symbol;
+    /** 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;
 };
-export declare function inject(key: string | symbol): (target: object, _propertyKey: string | symbol | undefined, idx: number) => void;
+/**
+ * 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: 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/core/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,11 +1,12 @@
-import type { Constructable, FunctionType } from "@decohere/nexus/reflection";
+import type { Constructable, FunctionType } from "@decohere/core/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 → container.d.ts}

@@ -2,30 +2,41 @@ import type { IContainer, ResolveRequest } from "../types/types.js";
 import { ServiceRegistry } from "./service-registry.js";
 type CrucibleOptions = {
     key?: string;
-    rootScope?: Crucible;
+    parent?: Container;
     serviceRegistry: ServiceRegistry;
 };
-export declare class Crucible implements IContainer {
+export declare class Container implements IContainer {
     key: string;
     protected instances: Map<unknown, object>;
     private serviceRegistry;
+    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;
-    beginScope(name?: string): Crucible;
+    private resolveAll;
+    private resolveOne;
+    beginScope(name?: string): Container;
     [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;
+    private releaseScope;
     private registerLifetimeScope;
 }
 export {};

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

@@ -1,2 +1,2 @@
-export * from "./crucible.js";
-export * from "./crucible-builder.js";
+export * from "./container.js";
+export * from "./service-container-builder.js";

package/types/src/services/{crucible-builder.d.ts → service-container-builder.d.ts}

@@ -1,14 +1,15 @@
-import type { Constructable, FunctionType } from "@decohere/nexus/reflection";
+import type { Constructable, FunctionType } from "@decohere/core/reflection";
 import type { ServiceRegistration } from "../models/service-registration.model.js";
-import type { ContainerBuilder, Scope } from "../types/types.js";
-import { Crucible } from "./crucible.js";
+import type { ContainerBuilder, ContainerRegistrar, Scope } from "../types/types.js";
+import { Container } from "./container.js";
 import { ServiceRegistry } from "./service-registry.js";
 type ContainerBuilderOptions = {
     serviceRegistry: ServiceRegistry;
 };
-export declare class CrucibleBuilder implements ContainerBuilder {
+export declare class ServiceContainerBuilder implements ContainerBuilder {
     private serviceRegistry;
     constructor(options?: ContainerBuilderOptions);
+    get override(): ContainerRegistrar;
     registerType(type: Constructable, scope?: Scope): ServiceRegistration;
     registerTypes(...types: Constructable[]): ServiceRegistration[];
     registerTypes(scope: Scope, ...types: Constructable[]): ServiceRegistration[];
@@ -21,6 +22,9 @@ export declare class CrucibleBuilder implements ContainerBuilder {
     registerRequestScoped<T>(key: string | symbol, type: () => T): ServiceRegistration;
     registerRequestScoped(key: string | symbol, type: Constructable): ServiceRegistration;
     registerRequestScoped(type: Constructable): ServiceRegistration;
-    build(): Crucible;
+    build(): Container;
+    private register;
+    private registerMany;
+    private createRegistrar;
 }
 export {};

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

@@ -1,16 +1,22 @@
-import type { Constructable, FunctionType } from "@decohere/nexus/reflection";
+import type { Constructable, FunctionType } from "@decohere/core/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;
-    getRegistration(key: string | symbol | Constructable): ServiceRegistration[];
+    replaceType(scope: Scope, options: RegisterTypeOptions): ServiceRegistration;
+    getRegistration(key: ServiceKey): ServiceRegistration[] | undefined;
     private createRegistrationFrom;
-    private getRegistrations;
-    private setRegistration;
 }

package/types/src/types/index.d.ts

@@ -1 +1,2 @@
+export * from "./errors.js";
 export * from "./types.js";

package/types/src/types/types.d.ts

@@ -1 +1 @@
-export type { ContainerBuilder, IContainer, LifetimeScope, ResolveRequest, Scope, ServiceProvider, } from "@decohere/nexus/composition";
+export type { ContainerBuilder, ContainerRegistrar, IContainer, LifetimeScope, ResolveRequest, Scope, ServiceProvider, } from "@decohere/core/composition";

package/commonjs/src/const.js

@@ -1,33 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", {
-    value: true
-});
-function _export(target, all) {
-    for(var name in all)Object.defineProperty(target, name, {
-        enumerable: true,
-        get: Object.getOwnPropertyDescriptor(all, name).get
-    });
-}
-_export(exports, {
-    get CrucibleMeta () {
-        return CrucibleMeta;
-    },
-    get LifetimeScopeToken () {
-        return LifetimeScopeToken;
-    },
-    get Scopes () {
-        return Scopes;
-    }
-});
-const Crucible = "Crucible";
-const LifetimeScopeToken = Symbol("LifetimeScope");
-const CrucibleMeta = {
-    injecttoken: `${Crucible}:injecttoken`
-};
-const Scopes = {
-    request: "request",
-    singleton: "single-instance",
-    transient: "transient"
-};
-
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbIi9ob21lL3J1bm5lci93b3JrL2RlY29oZXJlL2RlY29oZXJlL3Byb2plY3RzL2NydWNpYmxlL3NyYy9jb25zdC50cyJdLCJzb3VyY2VzQ29udGVudCI6WyJpbXBvcnQgdHlwZSB7IFNjb3BlIH0gZnJvbSBcIi4vdHlwZXMvdHlwZXMuanNcIjtcblxuY29uc3QgQ3J1Y2libGUgPSBcIkNydWNpYmxlXCI7XG50eXBlIENydWNpYmxlTWV0YSA9IFwiaW5qZWN0dG9rZW5cIjtcblxuZXhwb3J0IGNvbnN0IExpZmV0aW1lU2NvcGVUb2tlbiA9IFN5bWJvbChcIkxpZmV0aW1lU2NvcGVcIik7XG5cbmV4cG9ydCBjb25zdCBDcnVjaWJsZU1ldGEgPSB7XG5cdGluamVjdHRva2VuOiBgJHtDcnVjaWJsZX06aW5qZWN0dG9rZW5gLFxufSBzYXRpc2ZpZXMgUmVjb3JkPENydWNpYmxlTWV0YSwgc3RyaW5nPjtcblxuZXhwb3J0IGNvbnN0IFNjb3BlcyA9IHtcblx0cmVxdWVzdDogXCJyZXF1ZXN0XCIsXG5cdHNpbmdsZXRvbjogXCJzaW5nbGUtaW5zdGFuY2VcIixcblx0dHJhbnNpZW50OiBcInRyYW5zaWVudFwiLFxufSBzYXRpc2ZpZXMgUmVjb3JkPHN0cmluZywgU2NvcGU+O1xuIl0sIm5hbWVzIjpbIkNydWNpYmxlTWV0YSIsIkxpZmV0aW1lU2NvcGVUb2tlbiIsIlNjb3BlcyIsIkNydWNpYmxlIiwiU3ltYm9sIiwiaW5qZWN0dG9rZW4iLCJyZXF1ZXN0Iiwic2luZ2xldG9uIiwidHJhbnNpZW50Il0sIm1hcHBpbmdzIjoiOzs7Ozs7Ozs7OztRQU9hQTtlQUFBQTs7UUFGQUM7ZUFBQUE7O1FBTUFDO2VBQUFBOzs7QUFUYixNQUFNQyxXQUFXO0FBR1YsTUFBTUYscUJBQXFCRyxPQUFPO0FBRWxDLE1BQU1KLGVBQWU7SUFDM0JLLGFBQWEsR0FBR0YsU0FBUyxZQUFZLENBQUM7QUFDdkM7QUFFTyxNQUFNRCxTQUFTO0lBQ3JCSSxTQUFTO0lBQ1RDLFdBQVc7SUFDWEMsV0FBVztBQUNaIn0=