better-effect 0.10.0 → 0.11.0

package/dist/runtime-DnMn0X0X.mjs

@@ -0,0 +1,613 @@
+import { a as ServiceTagCollisionError, c as ServiceNotFoundError, i as LayerRegistrationError, n as LayerDisposeError, o as CircularDependencyError, s as ServiceAcquisitionError, t as DuplicateServiceError } from "./errors-Dnjhzbt0.mjs";
+import { i as getRuntimeContext, l as makeRuntimeContext, u as runRuntimeContext } from "./context-BUEf1qjL.mjs";
+import { f as defaultRuntimeContextStorage, n as linkAbortSignals } from "./signal-B97cs85Z.mjs";
+import { n as runScoped, r as ScopeRuntime, t as Scope } from "./scope-GGnmTQck.mjs";
+import { t as assertServiceCompatibility } from "./internal-identity-DmUpBeeL.mjs";
+import { Err } from "better-result";
+//#region src/layer/map-layer-backend.ts
+/** Native map-backed Layer backend used by Runtime when no adapter is supplied. */
+var MapLayerBackend = class {
+	providers = /* @__PURE__ */ new Map();
+	instances = /* @__PURE__ */ new Map();
+	pending = /* @__PURE__ */ new Map();
+	/** Register a provider, rejecting duplicate or colliding Service tags. */
+	register(registration) {
+		const tag = registration.service.serviceTag;
+		const existing = this.providers.get(tag);
+		if (existing) {
+			if (existing.service !== registration.service) throw new ServiceTagCollisionError(existing.service, registration.service);
+			throw new DuplicateServiceError(registration.service);
+		}
+		this.providers.set(tag, registration);
+	}
+	/** Resolve and cache a provider instance by Service tag. */
+	async resolve(token) {
+		const tag = token.serviceTag;
+		const provider = this.providers.get(tag);
+		if (!provider) throw new ServiceNotFoundError(token);
+		const validate = (instance) => {
+			assertServiceCompatibility(token, provider.service, instance);
+			return instance;
+		};
+		const cached = this.instances.get(tag);
+		if (cached !== void 0) return validate(cached);
+		const pending = this.pending.get(tag);
+		if (pending) return validate(await pending);
+		const acquisition = Promise.resolve().then(() => provider.acquire()).then((instance) => {
+			validate(instance);
+			this.instances.set(tag, instance);
+			return instance;
+		}).finally(() => {
+			this.pending.delete(tag);
+		});
+		this.pending.set(tag, acquisition);
+		return validate(await acquisition);
+	}
+	/** Clear pending acquisitions, cached instances, and provider registrations. */
+	async disposeAll(options) {
+		const acquisitions = [...this.pending.values()];
+		if (acquisitions.length > 0) {
+			const observePending = options?.onPendingAcquisitions;
+			if (observePending) await observePending(acquisitions);
+			await Promise.allSettled(acquisitions);
+		}
+		this.instances.clear();
+		this.pending.clear();
+		this.providers.clear();
+	}
+};
+//#endregion
+//#region src/runtime/outcome.ts
+/** Classify only a nominal better-result Err as a failed Runtime outcome. */
+const classifyRuntimeOutcome = (value) => {
+	if (value instanceof Err) return {
+		status: "failure",
+		cause: value.error
+	};
+	return { status: "success" };
+};
+//#endregion
+//#region src/runtime/observer.ts
+/** Compose best-effort Runtime observers into one observer. */
+const RuntimeObserver = { compose: (...observers) => ({
+	onServiceResolve: (event) => {
+		notifyRuntimeObservers(observers, (observer) => observer.onServiceResolve, event);
+	},
+	onServiceAcquire: (event) => {
+		notifyRuntimeObservers(observers, (observer) => observer.onServiceAcquire, event);
+	},
+	onExecutionStart: (event) => {
+		notifyRuntimeObservers(observers, (observer) => observer.onExecutionStart, event);
+	},
+	onExecutionEnd: (event) => {
+		notifyRuntimeObservers(observers, (observer) => observer.onExecutionEnd, event);
+	},
+	onResourceRelease: (event) => {
+		notifyRuntimeObservers(observers, (observer) => observer.onResourceRelease, event);
+	}
+}) };
+const notifyRuntimeObservers = (observers, select, event) => {
+	for (const observer of observers) {
+		const callback = select(observer);
+		if (!callback) continue;
+		try {
+			Promise.resolve(callback(event)).catch(() => {});
+		} catch {}
+	}
+};
+//#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, observers = []) => {
+	const wrapped = { async resolve(token) {
+		const context = getRuntimeContext(storage);
+		const path = context?.resolutionPath ?? [];
+		const cycleStart = findCycleStart(path, token);
+		const resolutionPath = [...path, token];
+		const notifyResolve = (outcome) => {
+			notifyRuntimeObservers(observers, (observer) => observer.onServiceResolve, {
+				service: token,
+				resolutionPath,
+				outcome
+			});
+		};
+		if (cycleStart >= 0) {
+			const error = new CircularDependencyError([...path.slice(cycleStart), token]);
+			notifyResolve({
+				status: "failure",
+				cause: error
+			});
+			throw error;
+		}
+		const nextContext = makeRuntimeContext(wrapped, context?.scope, resolutionPath, context?.signal, context);
+		return await runRuntimeContext(storage, nextContext, async () => {
+			try {
+				const instance = await resolver.resolve(token);
+				notifyResolve({ status: "success" });
+				return instance;
+			} catch (cause) {
+				if (shouldPreserve(cause)) {
+					notifyResolve({
+						status: "failure",
+						cause
+					});
+					throw cause;
+				}
+				const error = new ServiceAcquisitionError(token, resolutionPath, cause);
+				notifyResolve({
+					status: "failure",
+					cause: error
+				});
+				throw error;
+			}
+		});
+	} };
+	return wrapped;
+};
+//#endregion
+//#region src/layer/runtime.ts
+const SCOPE_SUCCESS = Object.freeze({ status: "success" });
+var RuntimeHandleDisposedError = class extends Error {
+	constructor() {
+		super("Cannot run a program using a disposed Layer");
+		this.name = "RuntimeHandleDisposedError";
+	}
+};
+const normalizeDisposeCauses = (cause) => {
+	if (cause instanceof AggregateError) return [...cause.errors];
+	return [cause];
+};
+const isScopeOutcome = (input) => input !== void 0 && "status" in input;
+const validateDisposeOptions = (options) => {
+	const { gracePeriod } = options;
+	if (gracePeriod !== void 0 && (!Number.isFinite(gracePeriod) || gracePeriod < 0)) throw new RangeError("Runtime dispose gracePeriod must be a finite non-negative number");
+};
+const notifyShutdownFailure = async (observer, diagnostic) => {
+	if (!observer) return;
+	try {
+		await observer(diagnostic);
+	} catch {}
+};
+const releaseLayerResource = async (service, release, outcome, observers) => {
+	try {
+		await release(outcome);
+		notifyRuntimeObservers(observers, (observer) => observer.onResourceRelease, {
+			service,
+			outcome
+		});
+	} catch (cause) {
+		notifyRuntimeObservers(observers, (observer) => observer.onResourceRelease, {
+			service,
+			outcome,
+			error: cause
+		});
+		throw cause;
+	}
+};
+const bindProviderToScope = (provider, scope, contextStorage, resolver, observers) => ({
+	service: provider.service,
+	acquire: () => {
+		const current = getRuntimeContext(contextStorage);
+		const context = makeRuntimeContext(resolver, scope, current?.resolutionPath ?? [], current?.signal, current);
+		return runRuntimeContext(contextStorage, context, () => ScopeRuntime.run(scope, async () => {
+			const resolutionPath = current?.resolutionPath ?? [provider.service];
+			try {
+				const instance = provider.acquireWithRelease ? (await scope.acquire(provider.acquireWithRelease, (acquired, outcome) => releaseLayerResource(provider.service, acquired.release, outcome, observers))).instance : provider.release ? await scope.acquire(() => provider.acquire(), (resource, outcome) => releaseLayerResource(provider.service, (releaseOutcome) => provider.release(resource, releaseOutcome), outcome, observers)) : await provider.acquire();
+				notifyRuntimeObservers(observers, (observer) => observer.onServiceAcquire, {
+					service: provider.service,
+					resolutionPath,
+					outcome: SCOPE_SUCCESS
+				});
+				return instance;
+			} catch (cause) {
+				notifyRuntimeObservers(observers, (observer) => observer.onServiceAcquire, {
+					service: provider.service,
+					resolutionPath,
+					outcome: {
+						status: "failure",
+						cause
+					}
+				});
+				throw cause;
+			}
+		}, contextStorage));
+	}
+});
+/** Resolve request-local providers first, then fall back to the Runtime root. */
+var ExecutionLayerBackend = class {
+	local;
+	root;
+	localTags = /* @__PURE__ */ new Set();
+	constructor(local, root) {
+		this.local = local;
+		this.root = root;
+	}
+	register(registration) {
+		this.localTags.add(registration.service.serviceTag);
+		this.local.register(registration);
+	}
+	async resolve(token) {
+		if (this.localTags.has(token.serviceTag)) return await this.local.resolve(token);
+		return await this.root.resolve(token);
+	}
+	async disposeAll() {
+		await this.local.disposeAll();
+		this.localTags.clear();
+	}
+};
+var RuntimeHandleImpl = class {
+	backend;
+	resolver;
+	rootScope;
+	onCleanupFailure;
+	contextStorage;
+	signal;
+	observers;
+	services;
+	disposePromise;
+	warmupPromise;
+	executions = /* @__PURE__ */ new Set();
+	shutdownController = new AbortController();
+	state = "active";
+	constructor(backend, resolver, rootScope, onCleanupFailure, contextStorage, signal, observers, services) {
+		this.backend = backend;
+		this.resolver = resolver;
+		this.rootScope = rootScope;
+		this.onCleanupFailure = onCleanupFailure;
+		this.contextStorage = contextStorage;
+		this.signal = signal;
+		this.observers = observers;
+		this.services = services;
+	}
+	run(program, options) {
+		this.assertActive();
+		const executionScope = this.rootScope.fork();
+		const signalLink = linkAbortSignals(this.signal, options?.signal, this.shutdownController.signal);
+		return this.startExecution(signalLink, () => this.runExecution(executionScope, program, this.resolver, signalLink.signal));
+	}
+	runWith(layer, program, options) {
+		this.assertActive();
+		const executionScope = this.rootScope.fork();
+		const localBackend = new MapLayerBackend();
+		const backend = new ExecutionLayerBackend(localBackend, this.backend);
+		const resolver = createResolutionResolver(backend, this.contextStorage, this.observers);
+		const signalLink = linkAbortSignals(this.signal, options?.signal, this.shutdownController.signal);
+		return this.startExecution(signalLink, async () => {
+			try {
+				return await this.runExecution(executionScope, async () => {
+					for (const provider of layer.providers) backend.register(bindProviderToScope(provider, executionScope, this.contextStorage, resolver, this.observers));
+					return await program();
+				}, resolver, signalLink.signal);
+			} finally {
+				await localBackend.disposeAll();
+			}
+		});
+	}
+	warmup() {
+		this.assertActive();
+		if (this.warmupPromise) return this.warmupPromise;
+		const warmup = runRuntimeContext(this.contextStorage, makeRuntimeContext(this.resolver, this.rootScope, [], this.signal), async () => {
+			for (const service of this.services) await this.resolver.resolve(service);
+		});
+		this.warmupPromise = warmup;
+		warmup.then(() => {
+			if (this.warmupPromise === warmup) this.warmupPromise = void 0;
+		}, () => {
+			if (this.warmupPromise === warmup) this.warmupPromise = void 0;
+		});
+		return warmup;
+	}
+	startExecution(signalLink, run) {
+		let resolveExecution;
+		let rejectExecution;
+		const execution = new Promise((resolve, reject) => {
+			resolveExecution = resolve;
+			rejectExecution = reject;
+		});
+		const activeExecution = { promise: execution };
+		this.executions.add(activeExecution);
+		execution.then(() => {
+			this.executions.delete(activeExecution);
+			signalLink.dispose();
+		}, () => {
+			this.executions.delete(activeExecution);
+			signalLink.dispose();
+		});
+		try {
+			run().then((value) => {
+				resolveExecution(value);
+			}, (cause) => {
+				rejectExecution(cause);
+			});
+		} catch (cause) {
+			rejectExecution(cause);
+		}
+		return execution;
+	}
+	runExecution(executionScope, program, resolver = this.resolver, signal = this.shutdownController.signal) {
+		let outcome;
+		const onOutcome = (determinedOutcome) => {
+			outcome = determinedOutcome;
+		};
+		const runOptions = this.onCleanupFailure ? {
+			classify: classifyRuntimeOutcome,
+			onOutcome,
+			onCleanupFailure: this.onCleanupFailure
+		} : {
+			classify: classifyRuntimeOutcome,
+			onOutcome
+		};
+		notifyRuntimeObservers(this.observers, (observer) => observer.onExecutionStart, { scope: executionScope });
+		return runScoped(executionScope, program, {
+			...runOptions,
+			contextStorage: this.contextStorage,
+			context: makeRuntimeContext(resolver, executionScope, [], signal)
+		}).then((value) => {
+			notifyRuntimeObservers(this.observers, (observer) => observer.onExecutionEnd, {
+				scope: executionScope,
+				outcome
+			});
+			return value;
+		}, (cause) => {
+			notifyRuntimeObservers(this.observers, (observer) => observer.onExecutionEnd, {
+				scope: executionScope,
+				outcome
+			});
+			throw cause;
+		});
+	}
+	dispose(input) {
+		if (this.disposePromise) return this.disposePromise;
+		const outcome = isScopeOutcome(input) || input === void 0 ? input ?? SCOPE_SUCCESS : SCOPE_SUCCESS;
+		const options = isScopeOutcome(input) || input === void 0 ? {} : input;
+		validateDisposeOptions(options);
+		this.state = "disposing";
+		const executions = [...this.executions];
+		this.disposePromise = this.performDispose(executions, outcome, options);
+		return this.disposePromise;
+	}
+	async performDispose(executions, outcome, options) {
+		const failures = [];
+		await Promise.allSettled(this.warmupPromise ? [this.warmupPromise] : []);
+		await this.waitForExecutions(executions, options);
+		try {
+			const signalLink = linkAbortSignals(this.signal, this.shutdownController.signal);
+			try {
+				await runRuntimeContext(this.contextStorage, makeRuntimeContext(this.resolver, this.rootScope, [], signalLink.signal), () => this.rootScope.close(outcome));
+			} finally {
+				signalLink.dispose();
+			}
+		} catch (cause) {
+			failures.push(cause);
+		}
+		try {
+			await this.backend.disposeAll();
+		} catch (cause) {
+			failures.push(cause);
+		}
+		this.state = "disposed";
+		if (failures.length > 0) {
+			const error = new LayerDisposeError(failures.flatMap(normalizeDisposeCauses));
+			await notifyShutdownFailure(this.onCleanupFailure, {
+				outcome,
+				error
+			});
+			throw error;
+		}
+	}
+	async waitForExecutions(executions, options) {
+		const settled = Promise.allSettled(executions.map((execution) => execution.promise));
+		if (options.abortAfterGracePeriod !== true || executions.length === 0) {
+			await settled;
+			return;
+		}
+		const gracePeriod = options.gracePeriod ?? 0;
+		let timer;
+		const timedOut = await Promise.race([settled.then(() => false), new Promise((resolve) => {
+			timer = setTimeout(() => resolve(true), gracePeriod);
+		})]);
+		if (timer !== void 0) clearTimeout(timer);
+		if (timedOut && !this.shutdownController.signal.aborted) this.shutdownController.abort(/* @__PURE__ */ new Error("Runtime shutdown grace period exceeded"));
+		await settled;
+	}
+	assertActive() {
+		if (this.state !== "active") throw new RuntimeHandleDisposedError();
+	}
+};
+/** 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 observers = options.observers ?? [];
+	const resolver = createResolutionResolver(backend, contextStorage, observers);
+	ScopeRuntime.bind(rootScope, contextStorage);
+	let current;
+	try {
+		for (const provider of layer.providers) {
+			current = provider;
+			await backend.register(bindProviderToScope(provider, rootScope, contextStorage, resolver, observers));
+		}
+	} catch (registrationCause) {
+		const outcome = {
+			status: "failure",
+			cause: registrationCause
+		};
+		const cleanupCauses = [];
+		try {
+			await runRuntimeContext(contextStorage, makeRuntimeContext(resolver, rootScope, [], options.signal), () => rootScope.close(outcome));
+		} catch (cause) {
+			cleanupCauses.push(cause);
+		}
+		try {
+			await backend.disposeAll();
+		} catch (cause) {
+			cleanupCauses.push(cause);
+		}
+		if (cleanupCauses.length > 0) {
+			const shutdownError = new LayerDisposeError(cleanupCauses.flatMap(normalizeDisposeCauses));
+			await notifyShutdownFailure(options.onCleanupFailure, {
+				outcome,
+				error: shutdownError
+			});
+		}
+		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, resolver, rootScope, options.onCleanupFailure, contextStorage, options.signal, observers, layer.providers.map((provider) => provider.service));
+};
+//#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.
+*
+* A Runtime owns Layer resources until `dispose()` is called. Each `run()` is
+* isolated in a child Scope, while Layer-scoped resources remain shared.
+*
+* @example
+* ```ts
+* const runtime = await Runtime.make(AppLive)
+* const result = await runtime.run(loadUser('u1'))
+* await runtime.dispose()
+* ```
+*
+* @typeParam Provided The branded Service instances supplied by the Layer.
+*/
+var Runtime = class Runtime {
+	handle;
+	constructor(handle) {
+		this.handle = handle;
+	}
+	static async make(layer, backendOrOptions, legacyOptions) {
+		const { backend, options } = resolveRuntimeConfig(backendOrOptions, legacyOptions);
+		const handle = await createRuntimeHandle(layer, backend, options);
+		const runtime = new Runtime(handle);
+		if (options.warmup) await runtime.warmup();
+		return runtime;
+	}
+	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);
+		let programOutcome;
+		const outcomeObserver = { onExecutionEnd: ({ outcome }) => {
+			programOutcome = outcome;
+		} };
+		const runtimeOptions = {
+			...config.options,
+			observers: [outcomeObserver, ...config.options.observers ?? []]
+		};
+		const runtime = await Runtime.make(layer, config.backend, runtimeOptions);
+		let value;
+		let executionFailed = false;
+		let executionFailure;
+		try {
+			value = await runtime.runUnchecked(program);
+		} catch (cause) {
+			executionFailed = true;
+			executionFailure = 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;
+	}
+	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;
+	}
+	/** Resolve every Layer provider and dispose the Runtime if warmup fails. */
+	async warmup() {
+		try {
+			await this.handle.warmup();
+		} catch (cause) {
+			try {
+				await this.handle.dispose({
+					status: "failure",
+					cause
+				});
+			} catch {}
+			throw cause;
+		}
+	}
+	/** Run one execution in this Runtime's child Scope. */
+	run(program, options) {
+		return this.handle.run(program, options);
+	}
+	/** Run one execution with a Layer owned by that execution's child Scope. */
+	runWith(layer, program, options) {
+		return this.handle.runWith(layer, program, options);
+	}
+	runUnchecked(program) {
+		return this.handle.run(program);
+	}
+	dispose(optionsOrOutcome) {
+		return this.handle.dispose(optionsOrOutcome);
+	}
+	/** 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 { MapLayerBackend as i, RuntimeObserver as n, classifyRuntimeOutcome as r, Runtime as t };
+
+//# sourceMappingURL=runtime-DnMn0X0X.mjs.map