better-effect 0.2.0 → 0.4.0

package/dist/index.mjs

@@ -1,14 +1,14 @@
-import { a as LayerRegistrationError, i as LayerGeneratorYieldError, n as DuplicateServiceError, o as ServiceNotFoundError, r as LayerDisposeError, s as ServiceRuntimeNotConfiguredError, t as BuiltLayerDisposedError } from "./errors-CnvKqBpb.mjs";
+import { a as LayerRegistrationError, i as LayerGeneratorYieldError, n as DuplicateServiceError, o as ServiceNotFoundError, r as LayerDisposeError, s as ServiceRuntimeNotConfiguredError, t as BuiltLayerDisposedError } from "./errors-DlHCwICc.mjs";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { Result, TaggedError } from "better-result";
 //#region src/service/runtime.ts
-const storage = new AsyncLocalStorage();
+const storage$1 = new AsyncLocalStorage();
 var ServiceRuntime = class ServiceRuntime {
 	static run(resolver, program) {
-		return storage.run(resolver, program);
+		return storage$1.run(resolver, program);
 	}
 	static current() {
-		const resolver = storage.getStore();
+		const resolver = storage$1.getStore();
 		if (!resolver) throw new ServiceRuntimeNotConfiguredError();
 		return resolver;
 	}
@@ -53,6 +53,12 @@ var Layer = class Layer {
 	static succeed(service, instance) {
 		return Layer.make(service, () => instance);
 	}
+	/**
+	* Define a dependency-free provider with Runtime-root cleanup.
+	*
+	* The release callback intentionally keeps its compatibility-friendly
+	* one-argument shape. Use `scopedGen` when cleanup needs `ScopeOutcome`.
+	*/
 	static scoped(service, acquire, release) {
 		return new Layer([{
 			service,
@@ -60,6 +66,14 @@ var Layer = class Layer {
 			release: (instance) => release(instance)
 		}]);
 	}
+	/** Define a contextual provider with Runtime-root, outcome-aware cleanup. */
+	static scopedGen(service, factory, release) {
+		return new Layer([{
+			service,
+			acquire: () => runLayerGenerator(service, factory),
+			release: (instance, outcome) => release(instance, outcome)
+		}]);
+	}
 	static gen(service, factory) {
 		return Layer.make(service, () => runLayerGenerator(service, factory));
 	}
@@ -80,64 +94,448 @@ var Layer = class Layer {
 	}
 };
 //#endregion
+//#region src/scope/errors.ts
+var ScopeRuntimeNotConfiguredError = class extends Error {
+	constructor() {
+		super("No Scope is available in the current execution context");
+		this.name = "ScopeRuntimeNotConfiguredError";
+	}
+};
+var ScopeClosedError = class extends Error {
+	constructor() {
+		super("Cannot add resources or finalizers to a closed Scope");
+		this.name = "ScopeClosedError";
+	}
+};
+var ScopeCloseError = class extends Error {
+	causes;
+	constructor(causes) {
+		super(`Failed to close Scope (${causes.length} finalizer${causes.length === 1 ? "" : "s"} failed)`);
+		this.causes = causes;
+		this.name = "ScopeCloseError";
+	}
+};
+var ResourceNotDisposableError = class extends Error {
+	constructor() {
+		super("Resource does not implement Symbol.dispose or Symbol.asyncDispose");
+		this.name = "ResourceNotDisposableError";
+	}
+};
+//#endregion
+//#region src/scope/disposable.ts
+const SCOPE_SUCCESS$2 = { status: "success" };
+const getDisposeFinalizer = (resource) => {
+	const candidate = Object(resource);
+	const asyncDispose = candidate[Symbol.asyncDispose];
+	if (typeof asyncDispose === "function") return () => asyncDispose.call(resource);
+	const dispose = candidate[Symbol.dispose];
+	if (typeof dispose === "function") return () => dispose.call(resource);
+};
+const disposeResource = (resource) => {
+	return getDisposeFinalizer(resource)?.(SCOPE_SUCCESS$2);
+};
+//#endregion
+//#region src/scope/runtime.ts
+const storage = new AsyncLocalStorage();
+var ScopeRuntime = class {
+	static run(scope, program) {
+		return storage.run(scope, program);
+	}
+	static current() {
+		const scope = storage.getStore();
+		if (!scope) throw new ScopeRuntimeNotConfiguredError();
+		return scope;
+	}
+};
+//#endregion
+//#region src/scope/internal.ts
+const notifyCleanupFailure = async (observer, diagnostic) => {
+	if (!observer) return;
+	try {
+		await observer(diagnostic);
+	} catch {}
+};
+const runScoped = async (scope, program, options) => {
+	let value;
+	let programFailed = false;
+	let programFailure;
+	try {
+		value = await ScopeRuntime.run(scope, program);
+	} catch (cause) {
+		programFailed = true;
+		programFailure = cause;
+	}
+	const outcome = programFailed ? {
+		status: "failure",
+		cause: programFailure
+	} : options.classify(value);
+	let cleanupFailed = false;
+	let cleanupFailure;
+	try {
+		await scope.close(outcome);
+	} catch (cause) {
+		cleanupFailed = true;
+		cleanupFailure = cause;
+	}
+	if (cleanupFailed) {
+		const error = cleanupFailure instanceof ScopeCloseError ? cleanupFailure : new ScopeCloseError([cleanupFailure]);
+		await notifyCleanupFailure(options.onCleanupFailure, {
+			outcome,
+			error
+		});
+		cleanupFailure = error;
+	}
+	if (programFailed) throw programFailure;
+	if (outcome.status === "failure") return value;
+	if (cleanupFailed) throw cleanupFailure;
+	return value;
+};
+//#endregion
+//#region src/scope/scope.ts
+const SCOPE_SUCCESS$1 = Object.freeze({ status: "success" });
+var ScopeImpl = class ScopeImpl {
+	parent;
+	children = /* @__PURE__ */ new Set();
+	finalizers = [];
+	closePromise;
+	closeOutcome;
+	constructor(parent) {
+		this.parent = parent;
+	}
+	fork() {
+		this.assertOpen();
+		const child = new ScopeImpl(this);
+		this.children.add(child);
+		return child;
+	}
+	addFinalizer(finalizer) {
+		this.assertOpen();
+		this.finalizers.push(finalizer);
+	}
+	async acquire(acquire, release) {
+		this.assertOpen();
+		const resource = await acquire();
+		try {
+			this.addFinalizer((outcome) => release(resource, outcome));
+			return resource;
+		} catch (scopeFailure) {
+			try {
+				await release(resource, this.closeOutcome ?? SCOPE_SUCCESS$1);
+			} catch (releaseFailure) {
+				throw new AggregateError([scopeFailure, releaseFailure], "Scope closed while acquiring a resource and immediate cleanup also failed");
+			}
+			throw scopeFailure;
+		}
+	}
+	async add(resource) {
+		const finalizer = getDisposeFinalizer(resource);
+		if (!finalizer) throw new ResourceNotDisposableError();
+		try {
+			this.addFinalizer(finalizer);
+			return resource;
+		} catch (scopeFailure) {
+			try {
+				await finalizer(this.closeOutcome ?? SCOPE_SUCCESS$1);
+			} catch (releaseFailure) {
+				throw new AggregateError([scopeFailure, releaseFailure], "Scope closed while adding a disposable resource and cleanup also failed");
+			}
+			throw scopeFailure;
+		}
+	}
+	close(outcome = SCOPE_SUCCESS$1) {
+		if (this.closePromise) return this.closePromise;
+		this.closeOutcome = outcome;
+		this.closePromise = ScopeRuntime.run(this, () => this.closeInternal(outcome));
+		return this.closePromise;
+	}
+	async closeInternal(outcome) {
+		const failures = [];
+		const children = [...this.children];
+		this.children.clear();
+		for (let index = children.length - 1; index >= 0; index--) {
+			const child = children[index];
+			if (!child) continue;
+			try {
+				await child.close(outcome);
+			} catch (cause) {
+				if (cause instanceof ScopeCloseError) failures.push(...cause.causes);
+				else failures.push(cause);
+			}
+		}
+		for (let index = this.finalizers.length - 1; index >= 0; index--) {
+			const finalizer = this.finalizers[index];
+			if (!finalizer) continue;
+			try {
+				await finalizer(outcome);
+			} catch (cause) {
+				failures.push(cause);
+			}
+		}
+		this.finalizers.length = 0;
+		this.detach();
+		if (failures.length > 0) throw new ScopeCloseError(failures);
+	}
+	detach() {
+		const parent = this.parent;
+		if (!parent) return;
+		parent.children.delete(this);
+		this.parent = void 0;
+	}
+	assertOpen() {
+		if (this.closePromise) throw new ScopeClosedError();
+	}
+};
+const Scope = {
+	make() {
+		return new ScopeImpl();
+	},
+	current() {
+		return ScopeRuntime.current();
+	},
+	provide(scope, program) {
+		return ScopeRuntime.run(scope, program);
+	},
+	*[Symbol.iterator]() {
+		return ScopeRuntime.current();
+	},
+	/**
+	* Run a program in a newly owned Scope.
+	*
+	* Scope is independent from `better-result`, so returned values—including
+	* `Result.err`—close this Scope with a successful outcome. Result-aware
+	* outcome classification belongs to `Runtime.run`.
+	*/
+	run(program) {
+		const scope = new ScopeImpl();
+		return runScoped(scope, () => program(scope), { classify: () => SCOPE_SUCCESS$1 });
+	}
+};
+//#endregion
+//#region src/runtime/outcome.ts
+const isResultLike = (value) => typeof value === "object" && value !== null && "status" in value && (value.status === "ok" || value.status === "error");
+const classifyRuntimeOutcome = (value) => {
+	if (isResultLike(value) && Result.isError(value)) return {
+		status: "failure",
+		cause: value.error
+	};
+	return { status: "success" };
+};
+//#endregion
 //#region src/layer/runtime.ts
+const SCOPE_SUCCESS = Object.freeze({ status: "success" });
 const normalizeDisposeCauses = (cause) => {
 	if (cause instanceof AggregateError) return [...cause.errors];
 	return [cause];
 };
+const notifyShutdownFailure = async (observer, diagnostic) => {
+	if (!observer) return;
+	try {
+		await observer(diagnostic);
+	} catch {}
+};
+const bindProviderToScope = (provider, rootScope) => ({
+	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));
+	})
+});
 var BuiltLayerImpl = class {
 	backend;
+	rootScope;
+	onCleanupFailure;
 	disposePromise;
-	disposed = false;
-	constructor(backend) {
+	executions = /* @__PURE__ */ new Set();
+	state = "active";
+	constructor(backend, rootScope, onCleanupFailure) {
 		this.backend = backend;
+		this.rootScope = rootScope;
+		this.onCleanupFailure = onCleanupFailure;
 	}
 	run(program) {
-		if (this.disposed || this.disposePromise) throw new BuiltLayerDisposedError();
-		return ServiceRuntime.run(this.backend, program);
+		this.assertActive();
+		const executionScope = this.rootScope.fork();
+		let resolveExecution;
+		let rejectExecution;
+		const execution = new Promise((resolve, reject) => {
+			resolveExecution = resolve;
+			rejectExecution = reject;
+		});
+		this.executions.add(execution);
+		execution.then(() => {
+			this.executions.delete(execution);
+		}, () => {
+			this.executions.delete(execution);
+		});
+		try {
+			this.runExecution(executionScope, program).then((value) => {
+				resolveExecution(value);
+			}, (cause) => {
+				rejectExecution(cause);
+			});
+		} catch (cause) {
+			rejectExecution(cause);
+		}
+		return execution;
 	}
-	dispose() {
+	runExecution(executionScope, program) {
+		const options = this.onCleanupFailure ? {
+			classify: classifyRuntimeOutcome,
+			onCleanupFailure: this.onCleanupFailure
+		} : { classify: classifyRuntimeOutcome };
+		return runScoped(executionScope, () => ServiceRuntime.run(this.backend, program), options);
+	}
+	dispose(outcome = SCOPE_SUCCESS) {
 		if (this.disposePromise) return this.disposePromise;
-		this.disposePromise = this.performDispose();
+		this.state = "disposing";
+		const executions = [...this.executions];
+		this.disposePromise = this.performDispose(executions, outcome);
 		return this.disposePromise;
 	}
-	async performDispose() {
+	async performDispose(executions, outcome) {
+		const failures = [];
+		await Promise.allSettled(executions);
+		try {
+			await ServiceRuntime.run(this.backend, () => this.rootScope.close(outcome));
+		} catch (cause) {
+			failures.push(cause);
+		}
 		try {
 			await this.backend.disposeAll();
 		} catch (cause) {
-			throw new LayerDisposeError(normalizeDisposeCauses(cause));
-		} finally {
-			this.disposed = true;
+			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;
 		}
 	}
+	assertActive() {
+		if (this.state !== "active") throw new BuiltLayerDisposedError();
+	}
 };
-const buildLayer = async (layer, backend) => {
+/**
+* Build a low-level Layer handle.
+*
+* @deprecated Prefer `Runtime.make()` for application code.
+*/
+const buildLayer = async (layer, backend, options = {}) => {
+	const rootScope = Scope.make();
 	let current;
 	try {
 		for (const provider of layer.providers) {
 			current = provider;
-			await backend.register(provider);
+			await backend.register(bindProviderToScope(provider, rootScope));
 		}
 	} catch (registrationCause) {
-		let cleanupCause;
+		const outcome = {
+			status: "failure",
+			cause: registrationCause
+		};
+		const cleanupCauses = [];
+		try {
+			await ServiceRuntime.run(backend, () => rootScope.close(outcome));
+		} catch (cause) {
+			cleanupCauses.push(cause);
+		}
 		try {
 			await backend.disposeAll();
 		} catch (cause) {
-			cleanupCause = cause;
+			cleanupCauses.push(cause);
+		}
+		if (cleanupCauses.length > 0) {
+			const shutdownError = new LayerDisposeError(cleanupCauses.flatMap(normalizeDisposeCauses));
+			await notifyShutdownFailure(options.onCleanupFailure, {
+				outcome,
+				error: shutdownError
+			});
 		}
+		let cleanupCause;
+		if (cleanupCauses.length === 1) cleanupCause = cleanupCauses[0];
+		else if (cleanupCauses.length > 1) cleanupCause = new LayerDisposeError(cleanupCauses.flatMap(normalizeDisposeCauses));
 		throw new LayerRegistrationError(current?.service, registrationCause, cleanupCause);
 	}
-	return new BuiltLayerImpl(backend);
+	return new BuiltLayerImpl(backend, rootScope, options.onCleanupFailure);
 };
 //#endregion
+//#region src/effect/combinators.ts
+const isPromiseLike = (value) => {
+	if (typeof value !== "object" && typeof value !== "function" || value === null) return false;
+	return "then" in value && typeof value.then === "function";
+};
+const mapResult = (result, fn) => Result.map(result, fn);
+const mapErrorResult = (result, fn) => Result.mapError(result, fn);
+const andThenResult = (result, next) => {
+	const chained = Result.andThen(result, next);
+	if (!isPromiseLike(chained)) return chained;
+	return Result.andThenAsync(result, () => Promise.resolve(chained));
+};
+function map(first, second) {
+	if (typeof first === "function" && second === void 0) return (effect) => map(effect, first);
+	const fn = second;
+	if (isPromiseLike(first)) return Promise.resolve(first).then((result) => mapResult(result, fn));
+	return mapResult(first, fn);
+}
+function mapError(first, second) {
+	if (typeof first === "function" && second === void 0) return (effect) => mapError(effect, first);
+	const fn = second;
+	if (isPromiseLike(first)) return Promise.resolve(first).then((result) => mapErrorResult(result, fn));
+	return mapErrorResult(first, fn);
+}
+function andThen(first, second) {
+	if (typeof first === "function" && second === void 0) return (effect) => andThen(effect, first);
+	const next = second;
+	if (isPromiseLike(first)) return Promise.resolve(first).then((result) => andThenResult(result, next));
+	return andThenResult(first, next);
+}
+//#endregion
+//#region src/effect/effect.ts
+function gen(body) {
+	return Result.gen(body);
+}
+/**
+* Acquire a resource in the current Scope and register its release callback.
+*
+* Acquisition failures are represented in the Effect Result error channel;
+* release failures remain owned by Scope cleanup.
+*/
+function acquireRelease(acquire, release) {
+	const scope = Scope.current();
+	return Result.await(Result.tryPromise(() => scope.acquire(acquire, release)));
+}
+/**
+* Register an already-acquired disposable resource in the current Scope.
+*
+* Registration failures are represented in the Effect Result error channel;
+* disposal failures remain owned by Scope cleanup.
+*/
+function add(resource) {
+	const scope = Scope.current();
+	return Result.await(Result.tryPromise(() => scope.add(resource)));
+}
+const Effect = {
+	gen,
+	acquireRelease,
+	add,
+	map,
+	mapError,
+	andThen
+};
+//#endregion
+//#region src/function/pipe.ts
+function pipe(value, ...operations) {
+	return operations.reduce((current, operation) => operation(current), value);
+}
+//#endregion
 //#region src/resource/errors.ts
 var ResourceReleaseFailure = class extends TaggedError("ResourceReleaseFailure") {};
 //#endregion
 //#region src/resource/internal.ts
-const disposeResource = (resource) => {
-	const candidate = Object(resource);
-	return (candidate[Symbol.asyncDispose] ?? candidate[Symbol.dispose])?.call(candidate);
-};
 const toReleaseFailure = (resource, cause) => new ResourceReleaseFailure({
 	resource,
 	cause,
@@ -177,8 +575,13 @@ const combineUseAndRelease = async (used, released, onReleaseFailure) => {
 //#region src/resource/resource.ts
 const acquireUseRelease = ({ name, acquire, use, release = disposeResource, onReleaseFailure }) => Result.gen(async function* () {
 	const resource = yield* Result.await(runResult(acquire));
+	const scope = Scope.make();
+	let released = Result.ok();
+	scope.addFinalizer(async () => {
+		released = await runRelease(name, resource, release);
+	});
 	const used = await runResult(() => use(resource));
-	const released = await runRelease(name, resource, release);
+	await scope.close();
 	return await combineUseAndRelease(used, released, onReleaseFailure);
 });
 const Resource = { acquireUseRelease };
@@ -189,26 +592,64 @@ var Runtime = class Runtime {
 	constructor(built) {
 		this.built = built;
 	}
-	static async make(layer, backend) {
-		const built = await buildLayer(layer, backend);
+	/** Create a long-lived Runtime that owns its Layer resources. */
+	static async make(layer, backend, options = {}) {
+		const built = await buildLayer(layer, backend, options);
 		return new Runtime(built);
 	}
-	static async run(layer, backend, program) {
-		const runtime = await Runtime.make(layer, backend);
+	/** Run one program and dispose its Layer resources before resolving. */
+	static async run(layer, backend, program, options = {}) {
+		const runtime = await Runtime.make(layer, backend, options);
+		let value;
+		let executionFailed = false;
+		let executionFailure;
+		let programOutcome;
 		try {
-			return await runtime.run(program);
-		} finally {
-			await runtime.dispose();
+			value = await runtime.runUnchecked(async () => {
+				try {
+					const programValue = await program();
+					programOutcome = classifyRuntimeOutcome(programValue);
+					return programValue;
+				} catch (cause) {
+					programOutcome = {
+						status: "failure",
+						cause
+					};
+					throw cause;
+				}
+			});
+		} 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;
 	}
+	/** Run one execution in this Runtime's child Scope. */
 	run(program) {
 		return this.built.run(program);
 	}
+	runUnchecked(program) {
+		return this.built.run(program);
+	}
+	/** Stop new executions and release the Runtime's Layer resources. */
 	dispose() {
 		return this.built.dispose();
 	}
+	disposeWithOutcome(outcome) {
+		return this.built.dispose(outcome);
+	}
 };
 //#endregion
-export { BuiltLayerDisposedError, DuplicateServiceError, Layer, LayerDisposeError, LayerGeneratorYieldError, LayerRegistrationError, Resource, ResourceReleaseFailure, Runtime, Service, ServiceNotFoundError, ServiceRuntime, ServiceRuntimeNotConfiguredError, buildLayer };
+export { BuiltLayerDisposedError, DuplicateServiceError, Effect, Layer, LayerDisposeError, LayerGeneratorYieldError, LayerRegistrationError, Resource, ResourceNotDisposableError, ResourceReleaseFailure, Runtime, Scope, ScopeCloseError, ScopeClosedError, ScopeRuntimeNotConfiguredError, Service, ServiceNotFoundError, ServiceRuntime, ServiceRuntimeNotConfiguredError, pipe };
 
 //# sourceMappingURL=index.mjs.map