better-effect 0.9.2 → 0.9.31

package/README.md

@@ -188,6 +188,78 @@ const result = await runtime.runWith(RequestLive, handleRequest)
 The request Layer may use root Services, while its scoped providers are closed
 with the execution Scope and never change the shared Runtime environment.
 
+### Hono request boundaries
+
+The optional `better-effect/hono` entrypoint runs one Runtime execution and
+Scope around each request. Handlers can yield Services directly; the adapter
+provides `CurrentRequest`, forwards `Request.signal`, and converts Results to
+Responses in one policy:
+
+```ts
+import { Hono } from 'hono'
+import { Result } from 'better-result'
+import { HonoEffect } from 'better-effect/hono'
+
+const http = HonoEffect.make(runtime, {
+  onFailure: (error, c) => c.json({ error: String(error) }, 400)
+})
+const app = new Hono()
+
+app.use('*', http.middleware())
+app.get(
+  '/work-orders',
+  http.gen(async function* () {
+    const workOrders = yield* WorkOrderService
+    const items = yield* Result.await(workOrders.list())
+    return Result.ok(items)
+  })
+)
+```
+
+Hono validators can precede the generator or handler callback. Their validated
+`c.req.valid(...)` inputs are combined and inferred without a manual `Input`
+helper:
+
+```ts
+import { sValidator } from '@hono/standard-validator'
+
+app.post(
+  '/work-orders',
+  http.gen(
+    sValidator('json', createWorkOrderSchema),
+    async function* (c) {
+      const input = c.req.valid('json')
+      const workOrders = yield* WorkOrderService
+      const workOrder = yield* Result.await(workOrders.create(input))
+
+      return Result.ok(workOrder)
+    },
+    { status: 201 }
+  )
+)
+```
+
+For multiple validators, pass them in order before the callback:
+
+```ts
+app.post(
+  '/work-orders/:id',
+  http.gen(validateParam, validateHeader, validateCreateWorkOrder, async function* (c) {
+    const id = c.req.valid('param').id
+    const key = c.req.valid('header')['X-Idempotency-Key']
+    const input = c.req.valid('json')
+    return Result.ok({ id, key, input })
+  })
+)
+```
+
+The validator middleware runs before the Program and short-circuits with its
+own `Response` when validation fails. `http.handler` accepts the same ordered
+validator arguments followed by the program factory and options.
+
+Install `hono` only when this subpath is used. The main entrypoint does not
+load the framework.
+
 Service and Scope access share one `RuntimeContext`. Node/Bun uses
 `AsyncLocalStorage` by default; hosts without transparent async context can
 pass `contextStorage: new ExplicitRuntimeContextStorage()` from
@@ -358,8 +430,29 @@ await runtime.dispose()
 ```
 
 The entrypoint also provides `Random`/`RandomSeeded`, `Logger`/`LoggerTest`,
-`CurrentRequest`, and the compatible `CurrentAbortSignal` bridge. None is
-installed implicitly; compose a normal Layer or use the provided test helpers.
+`Config`, `CurrentRequest`, and the compatible `CurrentAbortSignal` bridge. None
+is installed implicitly; compose a normal Layer or use the provided test
+helpers.
+
+For typed environment configuration, bind a Standard Schema directly to a
+reusable descriptor:
+
+```ts
+import { Result } from 'better-result'
+import { Effect } from 'better-effect'
+import { Config } from 'better-effect/standard-services'
+
+const AppConfig = Config.fromEnv({ schema: EnvSchema, dotEnvPath: '.env' })
+
+const program = Effect.fn(async function* () {
+  const config = yield* AppConfig
+  return Result.ok(config)
+})
+```
+
+Use `Config.schema(schema)` with `Config.layer(source)` or
+`Config.layerFromEnv(options)` when several descriptors should share an
+explicitly replaceable provider.
 
 ---
 

package/dist/adapters/iti.d.mts

@@ -1,5 +1,5 @@
 import { N as AnyServiceToken } from "../index-1NLNdkJy.mjs";
-import "../index-CYAgpM_5.mjs";
+import "../index-EJlskfAW.mjs";
 import { a as LayerRegistration, n as LayerBackend } from "../map-layer-backend-DMJauecV.mjs";
 //#region src/adapters/iti.d.ts
 /**

package/dist/effect-CZdZCZLW.mjs

@@ -0,0 +1,522 @@
+import { a as runRuntimeContext, i as makeRuntimeContext, n as currentRuntimeContext, r as getRuntimeContext, t as activeRuntimeContextStorage } from "./context-B4yO5LaH.mjs";
+import { t as isPromiseLike } from "./runtime-CDcCF5cb.mjs";
+import { Result } from "better-result";
+//#region src/scope/errors.ts
+/** Thrown when Scope context is accessed outside an active Scope execution. */
+var ScopeRuntimeNotConfiguredError = class extends Error {
+	constructor() {
+		super("No Scope is available in the current execution context");
+		this.name = "ScopeRuntimeNotConfiguredError";
+	}
+};
+/** Thrown when a resource or finalizer is added after Scope closure begins. */
+var ScopeClosedError = class extends Error {
+	constructor() {
+		super("Cannot add resources or finalizers to a closed Scope");
+		this.name = "ScopeClosedError";
+	}
+};
+/** Aggregates finalizer failures encountered while closing a Scope. */
+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";
+	}
+};
+/** Thrown when a value has neither Symbol.dispose nor Symbol.asyncDispose. */
+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$1 = { status: "success" };
+/** Return a Scope finalizer for a value's async or sync disposal protocol. */
+const getDisposeFinalizer = (resource) => {
+	const candidate = Object(resource);
+	const asyncDispose = candidate[Symbol.asyncDispose];
+	if (asyncDispose instanceof Function) return () => asyncDispose.call(resource);
+	const dispose = candidate[Symbol.dispose];
+	if (dispose instanceof Function) return () => dispose.call(resource);
+};
+/** Dispose a value immediately when it implements a disposal protocol. */
+const disposeResource = (resource) => {
+	return getDisposeFinalizer(resource)?.(SCOPE_SUCCESS$1);
+};
+//#endregion
+//#region src/scope/runtime.ts
+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, 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() {
+		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
+//#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 {
+		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;
+	}
+	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 = 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);
+			} 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);
+			} catch (releaseFailure) {
+				throw new AggregateError([scopeFailure, releaseFailure], "Scope closed while adding a disposable resource and cleanup also failed");
+			}
+			throw scopeFailure;
+		}
+	}
+	close(outcome = SCOPE_SUCCESS) {
+		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 = {
+	/** Create an owned, initially open Scope. */
+	make() {
+		return new ScopeImpl();
+	},
+	/** Return the non-owning Scope available in the current execution context. */
+	current() {
+		return ScopeRuntime.current();
+	},
+	/** Run a callback with an existing Scope supplied as the current context. */
+	provide(scope, program) {
+		return ScopeRuntime.run(scope, program);
+	},
+	/** Resolve the current Scope through `yield* Scope` inside an Effect. */
+	*[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`.
+	*
+	* @example
+	* ```ts
+	* await Scope.run(async (scope) => {
+	*   const connection = await scope.acquire(connect, (connection) => connection.close())
+	*   return connection.query()
+	* })
+	* ```
+	*/
+	run(program) {
+		const scope = new ScopeImpl();
+		return runScoped(scope, () => program(scope), { classify: () => SCOPE_SUCCESS });
+	}
+};
+//#endregion
+//#region src/effect/combinators.ts
+const asResult = (value) => {
+	return value;
+};
+const mapResult = (result, fn) => {
+	return Result.map(result, fn);
+};
+const mapErrorResult = (result, fn) => {
+	return Result.mapError(result, fn);
+};
+const andThenResult = (result, next) => {
+	const resultNext = next;
+	return Result.andThen(result, resultNext);
+};
+const andThenAsyncResult = (result, next) => {
+	const resultNext = (value) => {
+		return Promise.resolve(next(value));
+	};
+	return Result.andThenAsync(result, resultNext);
+};
+function map(first, second) {
+	if (first instanceof Function && second === void 0) {
+		const callback = first;
+		return (effect) => {
+			return map(effect, callback);
+		};
+	}
+	const fn = second;
+	if (isPromiseLike(first)) return Promise.resolve(first).then((result) => {
+		return mapResult(result, fn);
+	});
+	return mapResult(first, fn);
+}
+function mapError(first, second) {
+	if (first instanceof Function && second === void 0) {
+		const callback = first;
+		return (effect) => {
+			return mapError(effect, callback);
+		};
+	}
+	const fn = second;
+	if (isPromiseLike(first)) return Promise.resolve(first).then((result) => {
+		return mapErrorResult(result, fn);
+	});
+	return mapErrorResult(first, fn);
+}
+function andThen(first, second) {
+	if (first instanceof Function && second === void 0) {
+		const callback = first;
+		return (effect) => {
+			return andThen(effect, callback);
+		};
+	}
+	return andThenResult(first, second);
+}
+function andThenAsync(first, second) {
+	if (first instanceof Function && second === void 0) {
+		const callback = first;
+		return (effect) => {
+			return andThenAsync(effect, callback);
+		};
+	}
+	const next = second;
+	if (isPromiseLike(first)) return Promise.resolve(first).then((result) => {
+		return andThenAsyncResult(result, next);
+	});
+	return andThenAsyncResult(first, next);
+}
+const tapResult = (result, fn) => Result.tap(result, fn);
+const tapErrorResult = (result, fn) => Result.tapError(result, fn);
+const tapBothResult = (result, handlers) => Result.tapBoth(result, handlers);
+const recoverResult = (result, fn) => Result.tryRecover(result, fn);
+const recoverAsyncResult = (result, fn) => Result.tryRecoverAsync(result, (error) => Promise.resolve(fn(error)));
+const flattenResult = (result) => Result.flatten(result);
+const matchResult = (result, handlers) => Result.match(result, handlers);
+const allResult = (results) => Result.all(results);
+function tap(first, second) {
+	if (first instanceof Function && second === void 0) {
+		const callback = first;
+		return (effect) => tap(effect, callback);
+	}
+	if (second === void 0) throw new TypeError("Effect.tap requires a callback");
+	const fn = second;
+	if (isPromiseLike(first)) return Promise.resolve(first).then((result) => tapResult(asResult(result), fn));
+	return tapResult(asResult(first), fn);
+}
+function tapError(first, second) {
+	if (first instanceof Function && second === void 0) {
+		const callback = first;
+		return (effect) => tapError(effect, callback);
+	}
+	if (second === void 0) throw new TypeError("Effect.tapError requires a callback");
+	const fn = second;
+	if (isPromiseLike(first)) return Promise.resolve(first).then((result) => tapErrorResult(asResult(result), fn));
+	return tapErrorResult(asResult(first), fn);
+}
+function tapBoth(first, second) {
+	if (second === void 0) return (effect) => tapBoth(effect, first);
+	if (isPromiseLike(first)) return Promise.resolve(first).then((result) => tapBothResult(result, second));
+	return tapBothResult(asResult(first), second);
+}
+function recover(first, second) {
+	if (first instanceof Function && second === void 0) {
+		const callback = first;
+		return (effect) => recover(effect, callback);
+	}
+	if (second === void 0) throw new TypeError("Effect.recover requires a callback");
+	const fn = second;
+	if (isPromiseLike(first)) return Promise.resolve(first).then((result) => recoverResult(asResult(result), fn));
+	return recoverResult(asResult(first), fn);
+}
+function recoverAsync(first, second) {
+	if (first instanceof Function && second === void 0) {
+		const callback = first;
+		return (effect) => recoverAsync(effect, callback);
+	}
+	if (second === void 0) throw new TypeError("Effect.recoverAsync requires a callback");
+	const fn = second;
+	if (isPromiseLike(first)) return Promise.resolve(first).then((result) => recoverAsyncResult(asResult(result), fn));
+	return recoverAsyncResult(asResult(first), fn);
+}
+/** Remove one nested Result/Effect layer. */
+function flatten(effect) {
+	return flattenResult(asResult(effect));
+}
+function as(first, second) {
+	if (arguments.length < 2) return (effect) => as(effect, first);
+	return mapResult(asResult(first), () => second);
+}
+/** Replace a successful value with void. */
+function asVoid(effect) {
+	return mapResult(asResult(effect), () => void 0);
+}
+function match(first, second) {
+	if (isPromiseLike(first)) return Promise.resolve(first).then((result) => match(asResult(result), second));
+	return matchResult(asResult(first), second);
+}
+/** Collect already-created Effects in input order. */
+function all(results) {
+	return allResult(results);
+}
+/** Combine two already-created Effects in input order. */
+function zip(left, right) {
+	return Result.all([left, right]);
+}
+//#endregion
+//#region src/effect/effect.ts
+const runResultGenerator = Result.gen;
+function gen(body) {
+	return runResultGenerator(body);
+}
+function fn(body) {
+	const program = () => runResultGenerator(body);
+	return program;
+}
+const validateProgramConcurrency = (concurrency) => {
+	if (concurrency !== void 0 && (!Number.isFinite(concurrency) || !Number.isInteger(concurrency) || concurrency <= 0)) throw new RangeError("Program.all concurrency must be a positive integer");
+};
+/** Build a lazy Program collection with optional bounded concurrency. */
+function programAll(programs, options = {}) {
+	validateProgramConcurrency(options.concurrency);
+	const concurrency = options.concurrency;
+	const program = async () => {
+		const results = Array.from({ length: programs.length });
+		const failures = Array.from({ length: programs.length }, () => false);
+		const causes = Array.from({ length: programs.length });
+		let nextIndex = 0;
+		const worker = async () => {
+			while (true) {
+				const index = nextIndex++;
+				if (index >= programs.length) return;
+				try {
+					results[index] = await programs[index]();
+				} catch (cause) {
+					failures[index] = true;
+					causes[index] = cause;
+				}
+			}
+		};
+		const workers = Math.min(concurrency ?? programs.length, programs.length);
+		await Promise.all(Array.from({ length: workers }, () => worker()));
+		const failureIndex = failures.findIndex(Boolean);
+		if (failureIndex >= 0) throw causes[failureIndex];
+		return Result.all(results);
+	};
+	return program;
+}
+/** Value-level namespace for lazy Program combinators. */
+const Program = { all: programAll };
+/**
+* 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. The release callback
+* receives the final outcome chosen by the enclosing execution boundary.
+*
+* @example
+* ```ts
+* const connection = yield* Effect.acquireRelease(
+*   () => pool.connect(),
+*   (connection, outcome) => connection.close(outcome)
+* )
+* ```
+*/
+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.
+*
+* The resource is not acquired by this helper. Registration failures are
+* represented in the Effect Result error channel; disposal failures remain
+* owned by Scope cleanup.
+*
+* @example
+* ```ts
+* const file = yield* Effect.add(await openFile('notes.txt'))
+* ```
+*/
+function add(resource) {
+	const scope = Scope.current();
+	return Result.await(Result.tryPromise(() => scope.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. */
+	add,
+	/** Map a successful Effect result. */
+	map,
+	/** Map an Effect error. */
+	mapError,
+	/** Chain a synchronous Effect result. */
+	andThen,
+	/** Chain an asynchronous Effect result. */
+	andThenAsync,
+	/** Observe successful values without changing the Result. */
+	tap,
+	/** Observe error values without changing the Result. */
+	tapError,
+	/** Observe the active Result branch without changing the Result. */
+	tapBoth,
+	/** Recover an error with another Effect. */
+	recover,
+	/** Recover an error asynchronously with another Effect. */
+	recoverAsync,
+	/** Remove one nested Effect layer. */
+	flatten,
+	/** Replace a successful value. */
+	as,
+	/** Replace a successful value with void. */
+	asVoid,
+	/** Match either Result branch. */
+	match,
+	/** Collect Effects in input order. */
+	all,
+	/** Zip two Effects in input order. */
+	zip
+};
+//#endregion
+export { ScopeRuntime as a, ScopeCloseError as c, runScoped as i, ScopeClosedError as l, Program as n, disposeResource as o, Scope as r, ResourceNotDisposableError as s, Effect as t, ScopeRuntimeNotConfiguredError as u };
+
+//# sourceMappingURL=effect-CZdZCZLW.mjs.map