better-effect 0.3.0 → 0.5.0

package/dist/index.mjs

@@ -1,28 +1,98 @@
-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 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 { AsyncLocalStorage } from "node:async_hooks";
 import { Result, TaggedError } from "better-result";
 //#region src/service/runtime.ts
 const storage$1 = new AsyncLocalStorage();
+/** Provides the resolver context used by Service tokens during execution. */
 var ServiceRuntime = class ServiceRuntime {
+	/**
+	* Run a callback with a resolver available to `yield* Service` expressions.
+	*
+	* The context is scoped to the callback and is restored afterward.
+	*
+	* @example
+	* ```ts
+	* const value = ServiceRuntime.run(resolver, () => {
+	*   return ServiceRuntime.resolve(Database)
+	* })
+	* ```
+	*/
 	static run(resolver, program) {
 		return storage$1.run(resolver, program);
 	}
+	/** Return the resolver active in the current execution context. */
 	static current() {
 		const resolver = storage$1.getStore();
 		if (!resolver) throw new ServiceRuntimeNotConfiguredError();
 		return resolver;
 	}
+	/** Resolve a Service token using the active resolver. */
 	static async resolve(token) {
 		return await ServiceRuntime.current().resolve(token);
 	}
 };
 //#endregion
 //#region src/service/service.ts
+/**
+* Declare a class-backed Service with a stable string-literal identity.
+*
+* The returned class is simultaneously the implementation type, the runtime
+* dependency token, and the value yielded by `yield*` in an Effect generator.
+* The explicit self type preserves exact instance inference, while the second
+* call captures the tag as a literal for Layer composition and diagnostics.
+*
+* @example
+* ```ts
+* class Database extends Service<Database>()('Database') {
+*   query(): string {
+*     return 'ok'
+*   }
+* }
+*
+* const database = yield* Database
+* database.query()
+* ```
+*
+* @typeParam Self The instance type implemented by the declared Service.
+*/
 function Service() {
-	return class {
-		static async *[Symbol.asyncIterator]() {
-			return await ServiceRuntime.resolve(this);
+	return function(tag) {
+		if (tag.length === 0) throw new TypeError("Service tags must not be empty");
+		class BaseService {
+			/** The stable logical identity used by Layers and resolver backends. */
+			static serviceTag = tag;
+			/**
+			* Type-check a structural implementation of this Service.
+			*
+			* This is an identity helper. It returns the supplied value unchanged
+			* and does not invoke a constructor or modify its prototype.
+			*
+			* @example
+			* ```ts
+			* class Database extends Service<Database>()('Database') {
+			*   query(sql: string): string {
+			*     return sql
+			*   }
+			* }
+			*
+			* const database = Database.of({
+			*   query: (sql) => `Result: ${sql}`
+			* })
+			*
+			* database.query('SELECT 1')
+			* // 'Result: SELECT 1'
+			* // database is the original object, not an instance of Database
+			* ```
+			*/
+			static of(implementation) {
+				return implementation;
+			}
+			/** Resolve this Service from the resolver active in the current runtime. */
+			static async *[Symbol.asyncIterator]() {
+				return await ServiceRuntime.resolve(this);
+			}
 		}
+		return BaseService;
 	};
 }
 //#endregion
@@ -39,20 +109,68 @@ const runLayerGenerator = async (service, factory) => {
 };
 //#endregion
 //#region src/layer/layer.ts
+/**
+* Declarative collection of Service providers.
+*
+* A Layer describes how to acquire implementations; it does not execute
+* providers until a `Runtime` is created. Use `merge` to compose distinct
+* providers and `override` when replacing an existing provider intentionally.
+*
+* @example
+* ```ts
+* const AppLive = Layer.merge(
+*   Layer.succeed(Database, database),
+*   Layer.make(UserRepository)
+* )
+*
+* const runtime = await Runtime.make(AppLive, backend)
+* ```
+*/
 var Layer = class Layer {
+	/** The provider registrations retained by this Layer. */
 	providers;
 	constructor(providers) {
 		this.providers = Object.freeze([...providers]);
 	}
 	static make(service, acquire) {
+		const defaultAcquire = () => {
+			return new service();
+		};
 		return new Layer([{
 			service,
-			acquire
+			acquire: acquire ?? defaultAcquire
 		}]);
 	}
+	/**
+	* Create a Layer from an already-constructed Service instance.
+	*
+	* The instance is returned as-is whenever the Service is resolved.
+	*
+	* @example
+	* ```ts
+	* const DatabaseLive = Layer.succeed(Database, database)
+	* ```
+	*/
 	static succeed(service, instance) {
 		return Layer.make(service, () => instance);
 	}
+	/**
+	* Define a provider with Runtime-root cleanup.
+	*
+	* The release callback intentionally keeps its compatibility-friendly
+	* one-argument shape and runs when the owning Runtime is disposed. Use
+	* `scopedGen` when acquisition needs contextual Services or cleanup needs
+	* `ScopeOutcome`.
+	*
+	* @example
+	* ```ts
+	* const DatabaseLive = Layer.scoped(
+	*   Database,
+	*   () => openDatabase(),
+	*   (database) => database.close()
+	* )
+	* ```
+	*/
 	static scoped(service, acquire, release) {
 		return new Layer([{
 			service,
@@ -60,6 +178,24 @@ var Layer = class Layer {
 			release: (instance) => release(instance)
 		}]);
 	}
+	/**
+	* Define a provider whose acquisition can yield contextual Services.
+	*
+	* The release callback receives the acquired instance and the final
+	* `ScopeOutcome` selected by the owning Runtime.
+	*
+	* @example
+	* ```ts
+	* const RepositoryLive = Layer.scopedGen(
+	*   UserRepository,
+	*   async function* () {
+	*     const database = yield* Database
+	*     return new UserRepository(database)
+	*   },
+	*   (repository, outcome) => repository.close(outcome)
+	* )
+	* ```
+	*/
 	static scopedGen(service, factory, release) {
 		return new Layer([{
 			service,
@@ -67,39 +203,84 @@ var Layer = class Layer {
 			release: (instance, outcome) => release(instance, outcome)
 		}]);
 	}
+	/**
+	* Define a provider whose acquisition can yield contextual Services.
+	*
+	* Unlike `scopedGen`, this variant has no release callback. Use it for
+	* providers whose lifetime is managed elsewhere or that need no cleanup.
+	*
+	* @example
+	* ```ts
+	* const RepositoryLive = Layer.gen(UserRepository, async function* () {
+	*   const database = yield* Database
+	*   return new UserRepository(database)
+	* })
+	* ```
+	*/
 	static gen(service, factory) {
 		return Layer.make(service, () => runLayerGenerator(service, factory));
 	}
+	/**
+	* Compose Layers without replacing providers.
+	*
+	* Each Service tag may appear only once. Duplicate tags are rejected at
+	* runtime; use `override` when replacement is intentional.
+	*
+	* @example
+	* ```ts
+	* const AppLive = Layer.merge(DatabaseLive, RepositoryLive)
+	* ```
+	*/
 	static merge(...layers) {
 		const providers = /* @__PURE__ */ new Map();
 		for (const layer of layers) for (const provider of layer.providers) {
 			const service = provider.service;
-			if (providers.has(service)) throw new DuplicateServiceError(service);
-			providers.set(service, provider);
+			const existing = providers.get(service.serviceTag);
+			if (existing) {
+				if (existing.service !== service) throw new ServiceTagCollisionError(existing.service, service);
+				throw new DuplicateServiceError(service);
+			}
+			providers.set(service.serviceTag, provider);
 		}
 		return new Layer([...providers.values()]);
 	}
+	/**
+	* Replace providers in a base Layer, using tag identity and compatible
+	* instance contracts.
+	*
+	* Overrides are applied from left to right; the last compatible provider for
+	* a tag wins. Incompatible same-tag replacements remain visible as a type
+	* diagnostic and cannot be passed as a complete Layer.
+	*
+	* @example
+	* ```ts
+	* const TestLive = Layer.override(AppLive, Layer.succeed(Database, fakeDb))
+	* ```
+	*/
 	static override(base, ...overrides) {
 		const providers = /* @__PURE__ */ new Map();
-		for (const provider of base.providers) providers.set(provider.service, provider);
-		for (const layer of overrides) for (const provider of layer.providers) providers.set(provider.service, provider);
+		for (const provider of base.providers) providers.set(provider.service.serviceTag, provider);
+		for (const layer of overrides) for (const provider of layer.providers) providers.set(provider.service.serviceTag, provider);
 		return new Layer([...providers.values()]);
 	}
 };
 //#endregion
 //#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) {
@@ -108,6 +289,7 @@ var ScopeCloseError = class extends Error {
 		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");
@@ -117,6 +299,7 @@ var ResourceNotDisposableError = class extends Error {
 //#endregion
 //#region src/scope/disposable.ts
 const SCOPE_SUCCESS$2 = { 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];
@@ -124,16 +307,20 @@ const getDisposeFinalizer = (resource) => {
 	const dispose = candidate[Symbol.dispose];
 	if (typeof dispose === "function") return () => dispose.call(resource);
 };
+/** Dispose a value immediately when it implements a disposal protocol. */
 const disposeResource = (resource) => {
 	return getDisposeFinalizer(resource)?.(SCOPE_SUCCESS$2);
 };
 //#endregion
 //#region src/scope/runtime.ts
 const storage = new AsyncLocalStorage();
+/** 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);
 	}
+	/** Return the Scope active in the current execution context. */
 	static current() {
 		const scope = storage.getStore();
 		if (!scope) throw new ScopeRuntimeNotConfiguredError();
@@ -279,24 +466,219 @@ var ScopeImpl = class ScopeImpl {
 	}
 };
 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$1 });
 	}
 };
 //#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) => Result.andThen(result, next);
+const andThenAsyncResult = (result, next) => Result.andThenAsync(result, (value) => Promise.resolve(next(value)));
+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);
+	return andThenResult(first, second);
+}
+function andThenAsync(first, second) {
+	if (typeof first === "function" && second === void 0) return (effect) => andThenAsync(effect, first);
+	const next = second;
+	if (isPromiseLike(first)) return Promise.resolve(first).then((result) => andThenAsyncResult(result, next));
+	return andThenAsyncResult(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. 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)));
+}
+/**
+* Effect namespace containing generator, resource, and Result combinators.
+*
+* Prefer these helpers when a program needs typed Service requirements or
+* Scope-aware acquisition and cleanup.
+*/
+const Effect = {
+	/** Compose a generator-based Effect program. */
+	gen,
+	/** 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
+};
+//#endregion
+//#region src/function/pipe.ts
+function pipe(value, ...operations) {
+	return operations.reduce((current, operation) => operation(current), value);
+}
+//#endregion
+//#region src/resource/errors.ts
+/** Describes a failure encountered while releasing a Resource. */
+var ResourceReleaseFailure = class extends TaggedError("ResourceReleaseFailure") {};
+//#endregion
+//#region src/resource/internal.ts
+const toReleaseFailure = (resource, cause) => new ResourceReleaseFailure({
+	resource,
+	cause,
+	message: `Failed to release resource: ${resource}`
+});
+const runResult = async (operation) => {
+	return (await Result.tryPromise(() => Promise.resolve(operation()))).andThen((result) => result);
+};
+const normalizeReleaseOutcome = (name, outcome) => {
+	if (outcome === void 0) return Result.ok();
+	return outcome.mapError((cause) => toReleaseFailure(name, cause));
+};
+const runRelease = async (name, resource, release) => {
+	return (await Result.tryPromise({
+		try: () => Promise.resolve(release(resource)),
+		catch: (cause) => toReleaseFailure(name, cause)
+	})).andThen((outcome) => normalizeReleaseOutcome(name, outcome));
+};
+const notifyReleaseFailure = async (observer, failure) => {
+	if (!observer) return;
+	try {
+		await observer(failure);
+	} catch {}
+};
+const combineUseAndRelease = async (used, released, onReleaseFailure) => {
+	if (Result.isError(used)) {
+		if (Result.isError(released)) await notifyReleaseFailure(onReleaseFailure, released.error);
+		return Result.err(used.error);
+	}
+	if (Result.isError(released)) {
+		await notifyReleaseFailure(onReleaseFailure, released.error);
+		return Result.err(released.error);
+	}
+	return Result.ok(used.value);
+};
+//#endregion
+//#region src/resource/resource.ts
+/**
+* Acquire a resource, use it, and always attempt release afterward.
+*
+* Acquisition, use, and release may be synchronous or asynchronous Result
+* operations. If both use and release fail, the use error remains primary and
+* `onReleaseFailure` receives the cleanup failure as a diagnostic.
+*
+* When `release` is omitted, `Symbol.asyncDispose` is preferred over
+* `Symbol.dispose`.
+*
+* @example
+* ```ts
+* const result = await Resource.acquireUseRelease({
+*   name: 'database connection',
+*   acquire: () => connect(),
+*   use: (connection) => query(connection),
+*   release: (connection) => connection.close()
+* })
+* ```
+*/
+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));
+	await scope.close();
+	return await combineUseAndRelease(used, released, onReleaseFailure);
+});
+const Resource = { 
+/** Acquire, use, and release a resource with deterministic error precedence. */
+acquireUseRelease };
+//#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) => {
@@ -309,6 +691,12 @@ const classifyRuntimeOutcome = (value) => {
 //#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];
@@ -326,7 +714,7 @@ const bindProviderToScope = (provider, rootScope) => ({
 		return await rootScope.acquire(() => provider.acquire(), (resource, outcome) => provider.release(resource, outcome));
 	})
 });
-var BuiltLayerImpl = class {
+var RuntimeHandleImpl = class {
 	backend;
 	rootScope;
 	onCleanupFailure;
@@ -402,10 +790,11 @@ var BuiltLayerImpl = class {
 		}
 	}
 	assertActive() {
-		if (this.state !== "active") throw new BuiltLayerDisposedError();
+		if (this.state !== "active") throw new RuntimeHandleDisposedError();
 	}
 };
-const buildLayer = async (layer, backend, options = {}) => {
+/** Build a Runtime handle for a complete Layer and register its providers. */
+const createRuntimeHandle = async (layer, backend, options = {}) => {
 	const rootScope = Scope.make();
 	let current;
 	try {
@@ -441,103 +830,50 @@ const buildLayer = async (layer, backend, options = {}) => {
 		else if (cleanupCauses.length > 1) cleanupCause = new LayerDisposeError(cleanupCauses.flatMap(normalizeDisposeCauses));
 		throw new LayerRegistrationError(current?.service, registrationCause, cleanupCause);
 	}
-	return new BuiltLayerImpl(backend, rootScope, options.onCleanupFailure);
+	return new RuntimeHandleImpl(backend, rootScope, options.onCleanupFailure);
 };
 //#endregion
-//#region src/effect/effect.ts
-function gen(body) {
-	return Result.gen(body);
-}
+//#region src/runtime/runtime.ts
 /**
-* Acquire a resource in the current Scope and register its release callback.
+* Long-lived execution environment backed by a complete Layer.
 *
-* 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.
+* A Runtime owns Layer resources until `dispose()` is called. Each `run()` is
+* isolated in a child Scope, while Layer-scoped resources remain shared.
 *
-* Registration failures are represented in the Effect Result error channel;
-* disposal failures remain owned by Scope cleanup.
+* @example
+* ```ts
+* const runtime = await Runtime.make(AppLive, new MemoryLayerBackend())
+* const result = await runtime.run(loadUser('u1'))
+* await runtime.dispose()
+* ```
+*
+* @typeParam Provided The Service constructors supplied by the Layer.
 */
-function add(resource) {
-	const scope = Scope.current();
-	return Result.await(Result.tryPromise(() => scope.add(resource)));
-}
-const Effect = {
-	gen,
-	acquireRelease,
-	add
-};
-//#endregion
-//#region src/resource/errors.ts
-var ResourceReleaseFailure = class extends TaggedError("ResourceReleaseFailure") {};
-//#endregion
-//#region src/resource/internal.ts
-const toReleaseFailure = (resource, cause) => new ResourceReleaseFailure({
-	resource,
-	cause,
-	message: `Failed to release resource: ${resource}`
-});
-const runResult = async (operation) => {
-	return (await Result.tryPromise(() => Promise.resolve(operation()))).andThen((result) => result);
-};
-const normalizeReleaseOutcome = (name, outcome) => {
-	if (outcome === void 0) return Result.ok();
-	return outcome.mapError((cause) => toReleaseFailure(name, cause));
-};
-const runRelease = async (name, resource, release) => {
-	return (await Result.tryPromise({
-		try: () => Promise.resolve(release(resource)),
-		catch: (cause) => toReleaseFailure(name, cause)
-	})).andThen((outcome) => normalizeReleaseOutcome(name, outcome));
-};
-const notifyReleaseFailure = async (observer, failure) => {
-	if (!observer) return;
-	try {
-		await observer(failure);
-	} catch {}
-};
-const combineUseAndRelease = async (used, released, onReleaseFailure) => {
-	if (Result.isError(used)) {
-		if (Result.isError(released)) await notifyReleaseFailure(onReleaseFailure, released.error);
-		return Result.err(used.error);
-	}
-	if (Result.isError(released)) {
-		await notifyReleaseFailure(onReleaseFailure, released.error);
-		return Result.err(released.error);
-	}
-	return Result.ok(used.value);
-};
-//#endregion
-//#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));
-	await scope.close();
-	return await combineUseAndRelease(used, released, onReleaseFailure);
-});
-const Resource = { acquireUseRelease };
-//#endregion
-//#region src/runtime/runtime.ts
 var Runtime = class Runtime {
-	built;
-	constructor(built) {
-		this.built = built;
-	}
+	handle;
+	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 = {}) {
-		const built = await buildLayer(layer, backend, options);
-		return new Runtime(built);
-	}
+		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);
 		let value;
@@ -574,20 +910,22 @@ var Runtime = class Runtime {
 		if (executionFailed) throw executionFailure;
 		return value;
 	}
+	/** Run one execution in this Runtime's child Scope. */
 	run(program) {
-		return this.built.run(program);
+		return this.handle.run(program);
 	}
 	runUnchecked(program) {
-		return this.built.run(program);
+		return this.handle.run(program);
 	}
+	/** Stop new executions and release the Runtime's Layer resources. */
 	dispose() {
-		return this.built.dispose();
+		return this.handle.dispose();
 	}
 	disposeWithOutcome(outcome) {
-		return this.built.dispose(outcome);
+		return this.handle.dispose(outcome);
 	}
 };
 //#endregion
-export { BuiltLayerDisposedError, DuplicateServiceError, Effect, Layer, LayerDisposeError, LayerGeneratorYieldError, LayerRegistrationError, Resource, ResourceNotDisposableError, ResourceReleaseFailure, Runtime, Scope, ScopeCloseError, ScopeClosedError, ScopeRuntimeNotConfiguredError, Service, ServiceNotFoundError, ServiceRuntime, ServiceRuntimeNotConfiguredError, buildLayer };
+export { DuplicateServiceError, Effect, Layer, LayerDisposeError, LayerGeneratorYieldError, LayerRegistrationError, Resource, ResourceNotDisposableError, ResourceReleaseFailure, Runtime, Scope, ScopeCloseError, ScopeClosedError, ScopeRuntimeNotConfiguredError, Service, ServiceNotFoundError, ServiceRuntime, ServiceRuntimeNotConfiguredError, ServiceTagCollisionError, pipe };
 
 //# sourceMappingURL=index.mjs.map