better-effect 0.6.0 → 0.7.0

package/dist/index.mjs

@@ -1,9 +1,15 @@
-import { a as ServiceTagCollisionError, i as LayerRegistrationError, n as LayerDisposeError, o as ServiceNotFoundError, r as LayerGeneratorYieldError, s as ServiceRuntimeNotConfiguredError, t as DuplicateServiceError } from "./errors-GR3K_nRu.mjs";
+import { a as LayerRegistrationError, c as ServiceAcquisitionError, i as LayerGeneratorYieldError, l as ServiceNotFoundError, n as DuplicateServiceError, o as ServiceTagCollisionError, r as LayerDisposeError, s as CircularDependencyError, u as ServiceRuntimeNotConfiguredError } from "./internal-identity-Cm4-KIUj.mjs";
+import { a as runRuntimeContext, c as RuntimeContextNotConfiguredError, i as makeRuntimeContext, n as currentRuntimeContext, o as setDefaultRuntimeContextStorage, r as getRuntimeContext, t as activeRuntimeContextStorage } from "./context-B4yO5LaH.mjs";
+import { nodeRuntimeContextStorage } from "./runtime/node.mjs";
+import { t as MapLayerBackend } from "./map-layer-backend-BodcEeNA.mjs";
 import { t as isPromiseLike } from "./runtime-CDcCF5cb.mjs";
-import { AsyncLocalStorage } from "node:async_hooks";
 import { Result, TaggedError } from "better-result";
+//#region src/runtime/default.ts
+/** The Node/Bun storage used by the main Runtime entrypoint. */
+const defaultRuntimeContextStorage = nodeRuntimeContextStorage;
+setDefaultRuntimeContextStorage(defaultRuntimeContextStorage);
+//#endregion
 //#region src/service/runtime.ts
-const storage$1 = new AsyncLocalStorage();
 /** Provides the resolver context used by Service tokens during execution. */
 var ServiceRuntime = class ServiceRuntime {
 	/**
@@ -18,14 +24,21 @@ var ServiceRuntime = class ServiceRuntime {
 	* })
 	* ```
 	*/
-	static run(resolver, program) {
-		return storage$1.run(resolver, program);
+	static run(resolver, program, storage = defaultRuntimeContextStorage) {
+		const current = getRuntimeContext(storage);
+		const context = makeRuntimeContext(resolver, current?.scope, current?.resolver === resolver ? current.resolutionPath : [], current?.signal);
+		return runRuntimeContext(storage, context, program);
 	}
 	/** Return the resolver active in the current execution context. */
 	static current() {
-		const resolver = storage$1.getStore();
-		if (!resolver) throw new ServiceRuntimeNotConfiguredError();
-		return resolver;
+		let context;
+		try {
+			context = currentRuntimeContext();
+		} catch {
+			throw new ServiceRuntimeNotConfiguredError();
+		}
+		if (!context.resolver) throw new ServiceRuntimeNotConfiguredError();
+		return context.resolver;
 	}
 	/** Resolve a Service token using the active resolver. */
 	static async resolve(token) {
@@ -156,8 +169,8 @@ var Layer = class Layer {
 		return new Layer([{
 			service,
 			acquire: normalizeAcquire(acquire),
-			release: (instance) => {
-				return release(instance);
+			release: (instance, outcome) => {
+				return release(instance, outcome);
 			}
 		}]);
 	}
@@ -192,6 +205,10 @@ var Layer = class Layer {
 		}
 		return new Layer([...providers.values()]);
 	}
+	/** Mark a Layer composition root as complete without changing its runtime value. */
+	static complete(layer) {
+		return layer;
+	}
 	/** Replace providers in a base Layer, using tag identity and compatible contracts. */
 	static override(base, ...overrides) {
 		const providers = /* @__PURE__ */ new Map();
@@ -252,18 +269,30 @@ const disposeResource = (resource) => {
 };
 //#endregion
 //#region src/scope/runtime.ts
-const storage = new AsyncLocalStorage();
+const scopeStorages = /* @__PURE__ */ new WeakMap();
 /** Bridges the current Scope through async execution context. */
 var ScopeRuntime = class {
 	/** Supply a Scope while invoking a callback. */
-	static run(scope, program) {
-		return storage.run(scope, program);
+	static run(scope, program, storage = scopeStorages.get(scope) ?? activeRuntimeContextStorage()) {
+		scopeStorages.set(scope, storage);
+		const current = getRuntimeContext(storage);
+		const context = makeRuntimeContext(current?.resolver, scope, current?.resolutionPath ?? [], current?.signal);
+		return runRuntimeContext(storage, context, program);
 	}
 	/** Return the Scope active in the current execution context. */
 	static current() {
-		const scope = storage.getStore();
-		if (!scope) throw new ScopeRuntimeNotConfiguredError();
-		return scope;
+		let context;
+		try {
+			context = currentRuntimeContext();
+		} catch {
+			throw new ScopeRuntimeNotConfiguredError();
+		}
+		if (!context.scope) throw new ScopeRuntimeNotConfiguredError();
+		return context.scope;
+	}
+	/** Associate a Runtime-owned Scope with its context storage. */
+	static bind(scope, storage) {
+		scopeStorages.set(scope, storage);
 	}
 };
 //#endregion
@@ -279,7 +308,8 @@ const runScoped = async (scope, program, options) => {
 	let programFailed = false;
 	let programFailure;
 	try {
-		value = await ScopeRuntime.run(scope, program);
+		const run = () => ScopeRuntime.run(scope, program, options.contextStorage);
+		value = await (options.context && options.contextStorage ? runRuntimeContext(options.contextStorage, options.context, run) : run());
 	} catch (cause) {
 		programFailed = true;
 		programFailure = cause;
@@ -509,10 +539,14 @@ function andThenAsync(first, second) {
 }
 //#endregion
 //#region src/effect/effect.ts
+const runResultGenerator = Result.gen;
 function gen(body) {
-	const runResultGenerator = Result.gen;
 	return runResultGenerator(body);
 }
+function fn(body) {
+	const program = () => runResultGenerator(body);
+	return program;
+}
 /**
 * Acquire a resource in the current Scope and register its release callback.
 *
@@ -557,6 +591,8 @@ function add(resource) {
 const Effect = {
 	/** Compose a generator-based Effect program. */
 	gen,
+	/** Build a lazy Program from a generator. */
+	fn,
 	/** Acquire and register a resource in the current Scope. */
 	acquireRelease,
 	/** Register an already-acquired disposable in the current Scope. */
@@ -666,6 +702,30 @@ const classifyRuntimeOutcome = (value) => {
 	return { status: "success" };
 };
 //#endregion
+//#region src/layer/resolution.ts
+const findCycleStart = (path, token) => path.findIndex((current) => current.serviceTag === token.serviceTag);
+const shouldPreserve = (cause) => cause instanceof CircularDependencyError || cause instanceof ServiceAcquisitionError || cause instanceof ServiceNotFoundError || cause instanceof ServiceTagCollisionError;
+/** Wrap a backend with Runtime-local resolution paths and acquisition errors. */
+const createResolutionResolver = (resolver, storage = defaultRuntimeContextStorage) => {
+	const wrapped = { async resolve(token) {
+		const context = getRuntimeContext(storage);
+		const path = context?.resolver === wrapped ? context.resolutionPath : [];
+		const cycleStart = findCycleStart(path, token);
+		if (cycleStart >= 0) throw new CircularDependencyError([...path.slice(cycleStart), token]);
+		const resolutionPath = [...path, token];
+		const nextContext = makeRuntimeContext(wrapped, context?.scope, resolutionPath, context?.signal);
+		return await runRuntimeContext(storage, nextContext, async () => {
+			try {
+				return await resolver.resolve(token);
+			} catch (cause) {
+				if (shouldPreserve(cause)) throw cause;
+				throw new ServiceAcquisitionError(token, resolutionPath, cause);
+			}
+		});
+	} };
+	return wrapped;
+};
+//#endregion
 //#region src/layer/runtime.ts
 const SCOPE_SUCCESS = Object.freeze({ status: "success" });
 var RuntimeHandleDisposedError = class extends Error {
@@ -684,24 +744,30 @@ const notifyShutdownFailure = async (observer, diagnostic) => {
 		await observer(diagnostic);
 	} catch {}
 };
-const bindProviderToScope = (provider, rootScope) => ({
+const bindProviderToScope = (provider, rootScope, contextStorage) => ({
 	service: provider.service,
 	acquire: () => ScopeRuntime.run(rootScope, async () => {
 		if (!provider.release) return await provider.acquire();
 		return await rootScope.acquire(() => provider.acquire(), (resource, outcome) => provider.release(resource, outcome));
-	})
+	}, contextStorage)
 });
 var RuntimeHandleImpl = class {
 	backend;
+	resolver;
 	rootScope;
 	onCleanupFailure;
+	contextStorage;
+	signal;
 	disposePromise;
 	executions = /* @__PURE__ */ new Set();
 	state = "active";
-	constructor(backend, rootScope, onCleanupFailure) {
+	constructor(backend, resolver, rootScope, onCleanupFailure, contextStorage, signal) {
 		this.backend = backend;
+		this.resolver = resolver;
 		this.rootScope = rootScope;
 		this.onCleanupFailure = onCleanupFailure;
+		this.contextStorage = contextStorage;
+		this.signal = signal;
 	}
 	run(program) {
 		this.assertActive();
@@ -734,7 +800,11 @@ var RuntimeHandleImpl = class {
 			classify: classifyRuntimeOutcome,
 			onCleanupFailure: this.onCleanupFailure
 		} : { classify: classifyRuntimeOutcome };
-		return runScoped(executionScope, () => ServiceRuntime.run(this.backend, program), options);
+		return runScoped(executionScope, program, {
+			...options,
+			contextStorage: this.contextStorage,
+			context: makeRuntimeContext(this.resolver, executionScope, [], this.signal)
+		});
 	}
 	dispose(outcome = SCOPE_SUCCESS) {
 		if (this.disposePromise) return this.disposePromise;
@@ -747,7 +817,7 @@ var RuntimeHandleImpl = class {
 		const failures = [];
 		await Promise.allSettled(executions);
 		try {
-			await ServiceRuntime.run(this.backend, () => this.rootScope.close(outcome));
+			await runRuntimeContext(this.contextStorage, makeRuntimeContext(this.resolver, this.rootScope, [], this.signal), () => this.rootScope.close(outcome));
 		} catch (cause) {
 			failures.push(cause);
 		}
@@ -773,11 +843,14 @@ var RuntimeHandleImpl = class {
 /** Build a Runtime handle for a complete Layer and register its providers. */
 const createRuntimeHandle = async (layer, backend, options = {}) => {
 	const rootScope = Scope.make();
+	const contextStorage = options.contextStorage ?? defaultRuntimeContextStorage;
+	const resolver = createResolutionResolver(backend, contextStorage);
+	ScopeRuntime.bind(rootScope, contextStorage);
 	let current;
 	try {
 		for (const provider of layer.providers) {
 			current = provider;
-			await backend.register(bindProviderToScope(provider, rootScope));
+			await backend.register(bindProviderToScope(provider, rootScope, contextStorage));
 		}
 	} catch (registrationCause) {
 		const outcome = {
@@ -786,7 +859,7 @@ const createRuntimeHandle = async (layer, backend, options = {}) => {
 		};
 		const cleanupCauses = [];
 		try {
-			await ServiceRuntime.run(backend, () => rootScope.close(outcome));
+			await runRuntimeContext(contextStorage, makeRuntimeContext(resolver, rootScope, [], options.signal), () => rootScope.close(outcome));
 		} catch (cause) {
 			cleanupCauses.push(cause);
 		}
@@ -805,10 +878,22 @@ const createRuntimeHandle = async (layer, backend, options = {}) => {
 		const cleanupCause = cleanupCauses.length === 1 ? cleanupCauses[0] : cleanupCauses.length > 1 ? new LayerDisposeError(cleanupCauses.flatMap(normalizeDisposeCauses)) : void 0;
 		throw new LayerRegistrationError(current?.service, registrationCause, cleanupCause);
 	}
-	return new RuntimeHandleImpl(backend, rootScope, options.onCleanupFailure);
+	return new RuntimeHandleImpl(backend, resolver, rootScope, options.onCleanupFailure, contextStorage, options.signal);
 };
 //#endregion
 //#region src/runtime/runtime.ts
+const isLayerBackend = (value) => value !== void 0 && "register" in value && "resolve" in value && "disposeAll" in value;
+const resolveRuntimeConfig = (backendOrOptions, legacyOptions) => {
+	if (isLayerBackend(backendOrOptions)) return {
+		backend: backendOrOptions,
+		options: legacyOptions ?? {}
+	};
+	const options = backendOrOptions ?? {};
+	return {
+		backend: options.backend ?? new MapLayerBackend(),
+		options
+	};
+};
 /**
 * Long-lived execution environment backed by a complete Layer.
 *
@@ -817,7 +902,7 @@ const createRuntimeHandle = async (layer, backend, options = {}) => {
 *
 * @example
 * ```ts
-* const runtime = await Runtime.make(AppLive, new MemoryLayerBackend())
+* const runtime = await Runtime.make(AppLive)
 * const result = await runtime.run(loadUser('u1'))
 * await runtime.dispose()
 * ```
@@ -829,28 +914,26 @@ var Runtime = class Runtime {
 	constructor(handle) {
 		this.handle = handle;
 	}
-	/**
-	* Create a long-lived Runtime that owns its Layer resources.
-	*
-	* @example
-	* ```ts
-	* const runtime = await Runtime.make(AppLive, backend)
-	* const result = await runtime.run(program)
-	* await runtime.dispose()
-	* ```
-	*/
-	static async make(layer, backend, options = {}) {
+	static async make(layer, backendOrOptions, legacyOptions) {
+		const { backend, options } = resolveRuntimeConfig(backendOrOptions, legacyOptions);
 		const handle = await createRuntimeHandle(layer, backend, options);
 		return new Runtime(handle);
 	}
-	/**
-	* Run one program and dispose its Layer resources before resolving.
-	*
-	* This is convenient for request-style or command-style execution where a
-	* Runtime should not outlive the operation.
-	*/
-	static async run(layer, backend, program, options = {}) {
-		const runtime = await Runtime.make(layer, backend, options);
+	static async run(layer, backendOrProgramOrOptions, programOrOptions, legacyOptions) {
+		let program;
+		let backendOrOptions;
+		let options;
+		if (typeof backendOrProgramOrOptions === "function") {
+			program = backendOrProgramOrOptions;
+			backendOrOptions = programOrOptions;
+			options = void 0;
+		} else {
+			backendOrOptions = backendOrProgramOrOptions;
+			program = programOrOptions;
+			options = legacyOptions;
+		}
+		const config = resolveRuntimeConfig(backendOrOptions, options);
+		const runtime = await Runtime.make(layer, config.backend, config.options);
 		let value;
 		let executionFailed = false;
 		let executionFailure;
@@ -885,6 +968,35 @@ var Runtime = class Runtime {
 		if (executionFailed) throw executionFailure;
 		return value;
 	}
+	static async use(layer, use, options) {
+		const runtime = await Runtime.make(layer, options);
+		let value;
+		let executionFailed = false;
+		let executionFailure;
+		let programOutcome;
+		try {
+			value = await use(runtime);
+			programOutcome = classifyRuntimeOutcome(value);
+		} catch (cause) {
+			executionFailed = true;
+			executionFailure = cause;
+			programOutcome = {
+				status: "failure",
+				cause
+			};
+		}
+		const outcome = programOutcome ?? {
+			status: "failure",
+			cause: executionFailure
+		};
+		try {
+			await runtime.disposeWithOutcome(outcome);
+		} catch (shutdownFailure) {
+			if (!executionFailed && outcome.status === "success") throw shutdownFailure;
+		}
+		if (executionFailed) throw executionFailure;
+		return value;
+	}
 	/** Run one execution in this Runtime's child Scope. */
 	run(program) {
 		return this.handle.run(program);
@@ -896,11 +1008,15 @@ var Runtime = class Runtime {
 	dispose() {
 		return this.handle.dispose();
 	}
+	/** Release Runtime-owned resources through JavaScript's async disposal protocol. */
+	async [Symbol.asyncDispose]() {
+		await this.dispose();
+	}
 	disposeWithOutcome(outcome) {
 		return this.handle.dispose(outcome);
 	}
 };
 //#endregion
-export { DuplicateServiceError, Effect, Layer, LayerDisposeError, LayerGeneratorYieldError, LayerRegistrationError, Resource, ResourceNotDisposableError, ResourceReleaseFailure, Runtime, Scope, ScopeCloseError, ScopeClosedError, ScopeRuntimeNotConfiguredError, Service, ServiceNotFoundError, ServiceRuntime, ServiceRuntimeNotConfiguredError, ServiceTagCollisionError, pipe };
+export { CircularDependencyError, DuplicateServiceError, Effect, Layer, LayerDisposeError, LayerGeneratorYieldError, LayerRegistrationError, MapLayerBackend, Resource, ResourceNotDisposableError, ResourceReleaseFailure, Runtime, RuntimeContextNotConfiguredError, Scope, ScopeCloseError, ScopeClosedError, ScopeRuntimeNotConfiguredError, Service, ServiceAcquisitionError, ServiceNotFoundError, ServiceRuntime, ServiceRuntimeNotConfiguredError, ServiceTagCollisionError, pipe };
 
 //# sourceMappingURL=index.mjs.map