better-effect 0.6.0 → 0.7.0

package/README.md

@@ -4,7 +4,7 @@
 
 Type your errors with `better-result`. Typecheck the rest of your application wiring with `better-effect`.
 
-Use Services directly inside `Effect.gen`, compose implementations into application environments, and let TypeScript catch missing dependencies before your application starts — while keeping Promises, `better-result`, and your DI backend.
+Use Services directly inside `Effect.fn` Programs (or eager `Effect.gen` workflows), compose implementations into application environments, and let TypeScript catch missing dependencies before your application starts — while keeping Promises, `better-result`, and your DI backend.
 
 ```bash
 bun add better-effect better-result
@@ -34,7 +34,7 @@ class UserRepository extends Service<UserRepository>()('UserRepository') {
 
 const UserRepositoryLive = Layer.make(UserRepository)
 
-await Runtime.make(UserRepositoryLive, backend)
+await Runtime.make(UserRepositoryLive)
 //                 ^^^^^^^^^^^^^^^^^^
 // Type error: Database is required but not provided
 ```
@@ -92,7 +92,7 @@ const DatabaseLive = Layer.make(Database)
 
 const AppLive = Layer.merge(DatabaseLive, UserRepositoryLive)
 
-const runtime = await Runtime.make(AppLive, backend)
+const runtime = await Runtime.make(AppLive)
 ```
 
 And the contract does not disappear after startup.
@@ -100,15 +100,42 @@ And the contract does not disappear after startup.
 A Runtime also knows which Services exist in its environment:
 
 ```ts
-await runtime.run(() =>
-  Effect.gen(async function* () {
-    const database = yield* Database
+const inspectDatabase = Effect.fn(async function* () {
+  const database = yield* Database
 
-    return Result.ok(database)
-  })
-)
+  return Result.ok(database)
+})
+
+await runtime.run(inspectDatabase)
 ```
 
+`Effect.gen` remains eager for code that already runs inside a resolver and
+Scope. `Effect.fn` captures the generator as a lazy `Program` for Runtime
+boundaries; the callback form remains supported for compatibility.
+
+`Runtime.make(AppLive)` and `Runtime.run(AppLive, program)` use the built-in
+`MapLayerBackend`. Pass `{ backend: new ItiLayerBackend() }` when an external
+container is needed; `MemoryLayerBackend` remains its compatibility alias from
+`better-effect/testing`.
+
+Runtimes are async disposables, so request-scoped code can use:
+
+```ts
+await using runtime = await Runtime.make(AppLive)
+const result = await runtime.run(program)
+```
+
+Or let `Runtime.use` own the lifetime:
+
+```ts
+const result = await Runtime.use(AppLive, (runtime) => runtime.run(program))
+```
+
+Service and Scope access share one `RuntimeContext`. Node/Bun uses
+`AsyncLocalStorage` by default; hosts without transparent async context can
+pass `contextStorage: new ExplicitRuntimeContextStorage()` from
+`better-effect/runtime/explicit`.
+
 If a program asks that Runtime for a Service its environment does not provide, TypeScript rejects the call.
 
 ```text
@@ -154,6 +181,7 @@ type Success = Effect.Success<Program>
 type Failure = Effect.Error<Program>
 type Dependencies = Effect.Requirements<Program>
 type Services = Layer.Provided<typeof AppLive>
+type Missing = Layer.Missing<typeof AppLive>
 type AppRuntime = Runtime.For<typeof AppLive>
 type DatabaseTag = Service.Tag<Database> // 'Database'
 type DatabaseToken = Service.TokenOf<Database> // Service.Token<'Database', Database>
@@ -162,9 +190,12 @@ type Outcome = Scope.Outcome
 
 These are declaration-only aliases and add nothing to the JavaScript bundle.
 The associated `Layer` helpers are intentionally namespaced; use
-`Layer.Provided`, `Layer.Required`, `Layer.Complete` and `Layer.Any` rather than
+`Layer.Provided`, `Layer.Required`, `Layer.Missing`, `Layer.Complete` and `Layer.Any` rather than
 low-level provider metadata names.
 
+`Layer.complete(layer)` is a runtime identity that checks a composition root
+immediately, so missing Services are reported where the Layer is assembled.
+
 ---
 
 ## Why better-effect?
@@ -232,7 +263,7 @@ Others own connections, sessions, files or other resources.
 const DatabaseLive = Layer.scoped(
   Database,
   () => Database.connect(),
-  (database) => database.close()
+  (database, outcome) => database.close(outcome)
 )
 ```
 
@@ -318,11 +349,11 @@ Application resources live with the Runtime. Execution resources live with the e
 
 ### better-result underneath
 
-**Result → Result.gen → Effect.gen → pipe**
+**Result → Result.gen → Effect.gen / Effect.fn → pipe**
 
 Keep `better-result` as the source of truth for typed successes, failures, short-circuiting
 and generator control flow. `Effect.gen` delegates to `Result.gen`; it adds only the
-phantom Service requirements that TypeScript needs to check the application environment.
+declaration-only Service requirements that TypeScript needs to check the application environment.
 At runtime, an `Effect<A, E, R>` is still a `better-result` Result; the requirements exist
 only in the type. `Effect.Requirements`, `Layer.Provided`, `Layer.Required` and
 `Runtime.For` expose tagged Service instance unions.
@@ -349,5 +380,6 @@ or already an `Err`. The pipeline carries the requirements of every step, so Run
 still rejects it when its Layer does not provide every required Service.
 
 Use `Effect.gen` for larger workflows with several intermediate values, branches or
-procedural logic. Use `pipe` for concise, linear composition; both are ways to compose
-`better-result` programs while keeping dependency checking in the `better-effect` layer.
+procedural logic that already has a resolver. Use `Effect.fn` when the workflow should
+start at a Runtime boundary. Use `pipe` for concise, linear composition; all three
+keep dependency checking in the `better-effect` layer.

package/dist/adapters/iti.d.mts

@@ -1,4 +1,6 @@
-import { d as LayerRegistration, t as LayerBackend, z as AnyServiceToken } from "../index-DMfjhNR_.mjs";
+import { N as AnyServiceToken } from "../index-BFgG9zZC.mjs";
+import "../index-BddlcJK6.mjs";
+import { a as LayerRegistration, n as LayerBackend } from "../map-layer-backend-CGibcwkc.mjs";
 //#region src/adapters/iti.d.ts
 /**
  * ITI-backed Layer backend.

package/dist/adapters/iti.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"iti.d.mts","names":[],"sources":["../../src/adapters/iti.ts"],"mappings":";;;;;;;;cAsBa,2BAA2B;UAC9B;mBAES;mBAEA;UAET;;EAgBR,SAAS,cAAc;;EAuBvB,QAAQ,UAAU,iBAAiB,OAAO,IAAI,aAAa,KAAK,YAAY,aAAa;;EAyBnF,cAAc"}
+{"version":3,"file":"iti.d.mts","names":[],"sources":["../../src/adapters/iti.ts"],"mappings":";;;;;;;;;;cAsBa,2BAA2B;UAC9B;mBAES;mBAEA;UAET;;EAgBR,SAAS,cAAc;;EAuBvB,QAAQ,UAAU,iBAAiB,OAAO,IAAI,aAAa,KAAK,YAAY,aAAa;;EAyBnF,cAAc"}

package/dist/adapters/iti.mjs

@@ -1,6 +1,5 @@
-import { a as ServiceTagCollisionError, o as ServiceNotFoundError, t as DuplicateServiceError } from "../errors-GR3K_nRu.mjs";
+import { l as ServiceNotFoundError, n as DuplicateServiceError, o as ServiceTagCollisionError, t as assertServiceCompatibility } from "../internal-identity-Cm4-KIUj.mjs";
 import { t as isPromiseLike } from "../runtime-CDcCF5cb.mjs";
-import { t as assertServiceCompatibility } from "../internal-identity-C6Awrc33.mjs";
 import { createContainer } from "iti";
 //#region src/adapters/iti.ts
 /**

package/dist/adapters/iti.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"iti.mjs","names":[],"sources":["../../src/adapters/iti.ts"],"sourcesContent":["import { createContainer } from 'iti'\n\nimport {\n  DuplicateServiceError,\n  ServiceTagCollisionError,\n  type LayerBackend,\n  type LayerRegistration\n} from '../layer'\n\nimport { ServiceNotFoundError, type AnyServiceToken } from '../service'\n\nimport { assertServiceCompatibility } from '../layer/internal-identity'\nimport { isPromiseLike } from '../utils/runtime'\n\ntype LayerAcquiredValue = Awaited<ReturnType<LayerRegistration['acquire']>>\n\n/**\n * ITI-backed Layer backend.\n *\n * Install `iti` as the optional peer dependency and pass an instance to\n * `Runtime.make` when using ITI's container implementation.\n */\nexport class ItiLayerBackend implements LayerBackend {\n  private container: any = createContainer()\n\n  private readonly keys = new Map<string, string>()\n\n  private readonly registered = new Map<string, AnyServiceToken>()\n\n  private keyFor(token: AnyServiceToken): string {\n    const tag = token.serviceTag\n    const existing = this.keys.get(tag)\n\n    if (existing) {\n      return existing\n    }\n\n    const key = `better-effect:${tag}`\n\n    this.keys.set(tag, key)\n\n    return key\n  }\n\n  /** Register a Layer provider under its deterministic Service-tag key. */\n  register(registration: LayerRegistration): void {\n    const token = registration.service\n    const tag = token.serviceTag\n    const existing = this.registered.get(tag)\n\n    if (existing === token) {\n      throw new DuplicateServiceError(token)\n    }\n\n    if (existing) {\n      throw new ServiceTagCollisionError(existing, token)\n    }\n\n    const key = this.keyFor(token)\n\n    this.container = this.container.add({\n      [key]: registration.acquire\n    })\n\n    this.registered.set(tag, token)\n  }\n\n  /** Resolve a registered Service through the ITI container. */\n  resolve<T extends AnyServiceToken>(token: T): InstanceType<T> | PromiseLike<InstanceType<T>> {\n    const registered = this.registered.get(token.serviceTag)\n\n    if (registered === undefined) {\n      throw new ServiceNotFoundError(token)\n    }\n\n    const key = this.keyFor(token)\n    const resolved = this.container.get(key)\n\n    const validate = (instance: LayerAcquiredValue): InstanceType<T> => {\n      assertServiceCompatibility(token, registered, instance)\n\n      // SAFETY: The registered tag and compatibility check establish the constructor-to-instance relationship after ITI erases it.\n      return instance as InstanceType<T>\n    }\n\n    if (isPromiseLike(resolved)) {\n      return Promise.resolve(resolved).then(validate)\n    }\n\n    return validate(resolved)\n  }\n\n  /** Dispose all ITI-managed provider instances. */\n  async disposeAll(): Promise<void> {\n    await this.container.disposeAll()\n  }\n}\n"],"mappings":";;;;;;;;;;;AAsBA,IAAa,kBAAb,MAAqD;CACnD,YAAyB,gBAAgB;CAEzC,uBAAwB,IAAI,IAAoB;CAEhD,6BAA8B,IAAI,IAA6B;CAE/D,OAAe,OAAgC;EAC7C,MAAM,MAAM,MAAM;EAClB,MAAM,WAAW,KAAK,KAAK,IAAI,GAAG;EAElC,IAAI,UACF,OAAO;EAGT,MAAM,MAAM,iBAAiB;EAE7B,KAAK,KAAK,IAAI,KAAK,GAAG;EAEtB,OAAO;CACT;;CAGA,SAAS,cAAuC;EAC9C,MAAM,QAAQ,aAAa;EAC3B,MAAM,MAAM,MAAM;EAClB,MAAM,WAAW,KAAK,WAAW,IAAI,GAAG;EAExC,IAAI,aAAa,OACf,MAAM,IAAI,sBAAsB,KAAK;EAGvC,IAAI,UACF,MAAM,IAAI,yBAAyB,UAAU,KAAK;EAGpD,MAAM,MAAM,KAAK,OAAO,KAAK;EAE7B,KAAK,YAAY,KAAK,UAAU,IAAI,GACjC,MAAM,aAAa,QACtB,CAAC;EAED,KAAK,WAAW,IAAI,KAAK,KAAK;CAChC;;CAGA,QAAmC,OAA0D;EAC3F,MAAM,aAAa,KAAK,WAAW,IAAI,MAAM,UAAU;EAEvD,IAAI,eAAe,KAAA,GACjB,MAAM,IAAI,qBAAqB,KAAK;EAGtC,MAAM,MAAM,KAAK,OAAO,KAAK;EAC7B,MAAM,WAAW,KAAK,UAAU,IAAI,GAAG;EAEvC,MAAM,YAAY,aAAkD;GAClE,2BAA2B,OAAO,YAAY,QAAQ;GAGtD,OAAO;EACT;EAEA,IAAI,cAAc,QAAQ,GACxB,OAAO,QAAQ,QAAQ,QAAQ,CAAC,CAAC,KAAK,QAAQ;EAGhD,OAAO,SAAS,QAAQ;CAC1B;;CAGA,MAAM,aAA4B;EAChC,MAAM,KAAK,UAAU,WAAW;CAClC;AACF"}
+{"version":3,"file":"iti.mjs","names":[],"sources":["../../src/adapters/iti.ts"],"sourcesContent":["import { createContainer } from 'iti'\n\nimport {\n  DuplicateServiceError,\n  ServiceTagCollisionError,\n  type LayerBackend,\n  type LayerRegistration\n} from '../layer'\n\nimport { ServiceNotFoundError, type AnyServiceToken } from '../service'\n\nimport { assertServiceCompatibility } from '../layer/internal-identity'\nimport { isPromiseLike } from '../utils/runtime'\n\ntype LayerAcquiredValue = Awaited<ReturnType<LayerRegistration['acquire']>>\n\n/**\n * ITI-backed Layer backend.\n *\n * Install `iti` as the optional peer dependency and pass an instance to\n * `Runtime.make` when using ITI's container implementation.\n */\nexport class ItiLayerBackend implements LayerBackend {\n  private container: any = createContainer()\n\n  private readonly keys = new Map<string, string>()\n\n  private readonly registered = new Map<string, AnyServiceToken>()\n\n  private keyFor(token: AnyServiceToken): string {\n    const tag = token.serviceTag\n    const existing = this.keys.get(tag)\n\n    if (existing) {\n      return existing\n    }\n\n    const key = `better-effect:${tag}`\n\n    this.keys.set(tag, key)\n\n    return key\n  }\n\n  /** Register a Layer provider under its deterministic Service-tag key. */\n  register(registration: LayerRegistration): void {\n    const token = registration.service\n    const tag = token.serviceTag\n    const existing = this.registered.get(tag)\n\n    if (existing === token) {\n      throw new DuplicateServiceError(token)\n    }\n\n    if (existing) {\n      throw new ServiceTagCollisionError(existing, token)\n    }\n\n    const key = this.keyFor(token)\n\n    this.container = this.container.add({\n      [key]: registration.acquire\n    })\n\n    this.registered.set(tag, token)\n  }\n\n  /** Resolve a registered Service through the ITI container. */\n  resolve<T extends AnyServiceToken>(token: T): InstanceType<T> | PromiseLike<InstanceType<T>> {\n    const registered = this.registered.get(token.serviceTag)\n\n    if (registered === undefined) {\n      throw new ServiceNotFoundError(token)\n    }\n\n    const key = this.keyFor(token)\n    const resolved = this.container.get(key)\n\n    const validate = (instance: LayerAcquiredValue): InstanceType<T> => {\n      assertServiceCompatibility(token, registered, instance)\n\n      // SAFETY: The registered tag and compatibility check establish the constructor-to-instance relationship after ITI erases it.\n      return instance as InstanceType<T>\n    }\n\n    if (isPromiseLike(resolved)) {\n      return Promise.resolve(resolved).then(validate)\n    }\n\n    return validate(resolved)\n  }\n\n  /** Dispose all ITI-managed provider instances. */\n  async disposeAll(): Promise<void> {\n    await this.container.disposeAll()\n  }\n}\n"],"mappings":";;;;;;;;;;AAsBA,IAAa,kBAAb,MAAqD;CACnD,YAAyB,gBAAgB;CAEzC,uBAAwB,IAAI,IAAoB;CAEhD,6BAA8B,IAAI,IAA6B;CAE/D,OAAe,OAAgC;EAC7C,MAAM,MAAM,MAAM;EAClB,MAAM,WAAW,KAAK,KAAK,IAAI,GAAG;EAElC,IAAI,UACF,OAAO;EAGT,MAAM,MAAM,iBAAiB;EAE7B,KAAK,KAAK,IAAI,KAAK,GAAG;EAEtB,OAAO;CACT;;CAGA,SAAS,cAAuC;EAC9C,MAAM,QAAQ,aAAa;EAC3B,MAAM,MAAM,MAAM;EAClB,MAAM,WAAW,KAAK,WAAW,IAAI,GAAG;EAExC,IAAI,aAAa,OACf,MAAM,IAAI,sBAAsB,KAAK;EAGvC,IAAI,UACF,MAAM,IAAI,yBAAyB,UAAU,KAAK;EAGpD,MAAM,MAAM,KAAK,OAAO,KAAK;EAE7B,KAAK,YAAY,KAAK,UAAU,IAAI,GACjC,MAAM,aAAa,QACtB,CAAC;EAED,KAAK,WAAW,IAAI,KAAK,KAAK;CAChC;;CAGA,QAAmC,OAA0D;EAC3F,MAAM,aAAa,KAAK,WAAW,IAAI,MAAM,UAAU;EAEvD,IAAI,eAAe,KAAA,GACjB,MAAM,IAAI,qBAAqB,KAAK;EAGtC,MAAM,MAAM,KAAK,OAAO,KAAK;EAC7B,MAAM,WAAW,KAAK,UAAU,IAAI,GAAG;EAEvC,MAAM,YAAY,aAAkD;GAClE,2BAA2B,OAAO,YAAY,QAAQ;GAGtD,OAAO;EACT;EAEA,IAAI,cAAc,QAAQ,GACxB,OAAO,QAAQ,QAAQ,QAAQ,CAAC,CAAC,KAAK,QAAQ;EAGhD,OAAO,SAAS,QAAQ;CAC1B;;CAGA,MAAM,aAA4B;EAChC,MAAM,KAAK,UAAU,WAAW;CAClC;AACF"}

package/dist/context-B4yO5LaH.mjs

@@ -0,0 +1,80 @@
+//#region src/runtime/errors.ts
+/** Thrown when no RuntimeContext is active in the selected storage. */
+var RuntimeContextNotConfiguredError = class extends Error {
+	constructor() {
+		super("No RuntimeContext is available in the current execution context");
+		this.name = "RuntimeContextNotConfiguredError";
+	}
+};
+//#endregion
+//#region src/runtime/context.ts
+const unconfiguredRuntimeContextStorage = {
+	run: (_context, program) => program(),
+	current: () => {
+		throw new RuntimeContextNotConfiguredError();
+	}
+};
+/** Build a context while keeping compatibility-only missing channels internal. */
+const makeRuntimeContext = (resolver, scope, resolutionPath, signal) => {
+	const context = {
+		resolver,
+		scope,
+		resolutionPath
+	};
+	if (signal === void 0) return context;
+	return {
+		...context,
+		signal
+	};
+};
+let activeStorage = unconfiguredRuntimeContextStorage;
+/** Install the host default used by the main Runtime entrypoint. */
+const setDefaultRuntimeContextStorage = (storage) => {
+	activeStorage = storage;
+};
+const isPromiseLike = (value) => Object(value) === value && "then" in Object(value);
+/** Return the storage currently associated with the executing callback. */
+const activeRuntimeContextStorage = () => activeStorage;
+/** Return the active context, or undefined when the storage has not been entered. */
+const getRuntimeContext = (storage = activeStorage) => {
+	try {
+		return storage.current();
+	} catch (cause) {
+		if (cause instanceof RuntimeContextNotConfiguredError) return;
+		throw cause;
+	}
+};
+/** Return the active context or throw the storage's standard missing-context error. */
+const currentRuntimeContext = () => activeStorage.current();
+/** Keep a storage discoverable to Service and Scope compatibility bridges. */
+const withActiveRuntimeContextStorage = (storage, program) => {
+	const previous = activeStorage;
+	activeStorage = storage;
+	const restore = () => {
+		if (activeStorage === storage) activeStorage = previous;
+	};
+	let value;
+	try {
+		value = program();
+	} catch (cause) {
+		restore();
+		throw cause;
+	}
+	if (!isPromiseLike(value)) {
+		restore();
+		return value;
+	}
+	return Promise.resolve(value).then((resolved) => {
+		restore();
+		return resolved;
+	}, (cause) => {
+		restore();
+		throw cause;
+	});
+};
+/** Run a callback in a context while keeping the selected storage discoverable to bridges. */
+const runRuntimeContext = (storage, context, program) => withActiveRuntimeContextStorage(storage, () => storage.run(context, program));
+//#endregion
+export { runRuntimeContext as a, RuntimeContextNotConfiguredError as c, makeRuntimeContext as i, currentRuntimeContext as n, setDefaultRuntimeContextStorage as o, getRuntimeContext as r, withActiveRuntimeContextStorage as s, activeRuntimeContextStorage as t };
+
+//# sourceMappingURL=context-B4yO5LaH.mjs.map

package/dist/context-B4yO5LaH.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-B4yO5LaH.mjs","names":[],"sources":["../src/runtime/errors.ts","../src/runtime/context.ts"],"sourcesContent":["/** Thrown when no RuntimeContext is active in the selected storage. */\nexport class RuntimeContextNotConfiguredError extends Error {\n  constructor() {\n    super('No RuntimeContext is available in the current execution context')\n\n    this.name = 'RuntimeContextNotConfiguredError'\n  }\n}\n","import { RuntimeContextNotConfiguredError } from './errors'\n\nimport type { Scope } from '../scope/scope'\nimport type { AnyServiceToken, ServiceResolver } from '../service'\n\n/** The complete contextual state shared by Service, Scope and Layer resolution. */\nexport interface RuntimeContext {\n  readonly resolver: ServiceResolver\n  readonly scope: Scope\n  readonly signal?: AbortSignal\n  readonly resolutionPath: readonly AnyServiceToken[]\n}\n\n/** Host-specific storage for the current RuntimeContext. */\nexport interface RuntimeContextStorage {\n  run<A>(context: RuntimeContext, program: () => A): A\n  current(): RuntimeContext\n}\n\nconst unconfiguredRuntimeContextStorage: RuntimeContextStorage = {\n  run: (_context, program) => program(),\n  current: () => {\n    throw new RuntimeContextNotConfiguredError()\n  }\n}\n\n/** Build a context while keeping compatibility-only missing channels internal. */\nexport const makeRuntimeContext = (\n  resolver: ServiceResolver | undefined,\n  scope: Scope | undefined,\n  resolutionPath: readonly AnyServiceToken[],\n  signal: AbortSignal | undefined\n): RuntimeContext => {\n  // SAFETY: ServiceRuntime and ScopeRuntime can be entered independently; the missing channel is rejected by the corresponding bridge before use.\n  const context: RuntimeContext = {\n    resolver: resolver as ServiceResolver,\n    scope: scope as Scope,\n    resolutionPath\n  }\n\n  if (signal === undefined) {\n    return context\n  }\n\n  return { ...context, signal }\n}\n\nlet activeStorage = unconfiguredRuntimeContextStorage\n\n/** Install the host default used by the main Runtime entrypoint. */\nexport const setDefaultRuntimeContextStorage = (storage: RuntimeContextStorage): void => {\n  activeStorage = storage\n}\n\nconst isPromiseLike = <A>(value: A): value is A & PromiseLike<unknown> =>\n  Object(value) === value && 'then' in Object(value)\n\n/** Return the storage currently associated with the executing callback. */\nexport const activeRuntimeContextStorage = (): RuntimeContextStorage => activeStorage\n\n/** Return the active context, or undefined when the storage has not been entered. */\nexport const getRuntimeContext = (\n  storage: RuntimeContextStorage = activeStorage\n): RuntimeContext | undefined => {\n  try {\n    return storage.current()\n  } catch (cause) {\n    if (cause instanceof RuntimeContextNotConfiguredError) {\n      return undefined\n    }\n\n    throw cause\n  }\n}\n\n/** Return the active context or throw the storage's standard missing-context error. */\nexport const currentRuntimeContext = (): RuntimeContext => activeStorage.current()\n\n/** Keep a storage discoverable to Service and Scope compatibility bridges. */\nexport const withActiveRuntimeContextStorage = <A>(\n  storage: RuntimeContextStorage,\n  program: () => A\n): A => {\n  const previous = activeStorage\n  activeStorage = storage\n\n  const restore = (): void => {\n    if (activeStorage === storage) {\n      activeStorage = previous\n    }\n  }\n\n  let value: A\n\n  try {\n    value = program()\n  } catch (cause) {\n    restore()\n    throw cause\n  }\n\n  if (!isPromiseLike(value)) {\n    restore()\n    return value\n  }\n\n  // SAFETY: PromiseLike values are normalized only to restore the storage after settlement; the public generic retains the callback's awaited shape.\n  return Promise.resolve(value).then(\n    (resolved) => {\n      restore()\n      return resolved\n    },\n    (cause) => {\n      restore()\n      throw cause\n    }\n  ) as A\n}\n\n/** Run a callback in a context while keeping the selected storage discoverable to bridges. */\nexport const runRuntimeContext = <A>(\n  storage: RuntimeContextStorage,\n  context: RuntimeContext,\n  program: () => A\n): A => withActiveRuntimeContextStorage(storage, () => storage.run(context, program))\n"],"mappings":";;AACA,IAAa,mCAAb,cAAsD,MAAM;CAC1D,cAAc;EACZ,MAAM,iEAAiE;EAEvE,KAAK,OAAO;CACd;AACF;;;ACYA,MAAM,oCAA2D;CAC/D,MAAM,UAAU,YAAY,QAAQ;CACpC,eAAe;EACb,MAAM,IAAI,iCAAiC;CAC7C;AACF;;AAGA,MAAa,sBACX,UACA,OACA,gBACA,WACmB;CAEnB,MAAM,UAA0B;EACpB;EACH;EACP;CACF;CAEA,IAAI,WAAW,KAAA,GACb,OAAO;CAGT,OAAO;EAAE,GAAG;EAAS;CAAO;AAC9B;AAEA,IAAI,gBAAgB;;AAGpB,MAAa,mCAAmC,YAAyC;CACvF,gBAAgB;AAClB;AAEA,MAAM,iBAAoB,UACxB,OAAO,KAAK,MAAM,SAAS,UAAU,OAAO,KAAK;;AAGnD,MAAa,oCAA2D;;AAGxE,MAAa,qBACX,UAAiC,kBACF;CAC/B,IAAI;EACF,OAAO,QAAQ,QAAQ;CACzB,SAAS,OAAO;EACd,IAAI,iBAAiB,kCACnB;EAGF,MAAM;CACR;AACF;;AAGA,MAAa,8BAA8C,cAAc,QAAQ;;AAGjF,MAAa,mCACX,SACA,YACM;CACN,MAAM,WAAW;CACjB,gBAAgB;CAEhB,MAAM,gBAAsB;EAC1B,IAAI,kBAAkB,SACpB,gBAAgB;CAEpB;CAEA,IAAI;CAEJ,IAAI;EACF,QAAQ,QAAQ;CAClB,SAAS,OAAO;EACd,QAAQ;EACR,MAAM;CACR;CAEA,IAAI,CAAC,cAAc,KAAK,GAAG;EACzB,QAAQ;EACR,OAAO;CACT;CAGA,OAAO,QAAQ,QAAQ,KAAK,CAAC,CAAC,MAC3B,aAAa;EACZ,QAAQ;EACR,OAAO;CACT,IACC,UAAU;EACT,QAAQ;EACR,MAAM;CACR,CACF;AACF;;AAGA,MAAa,qBACX,SACA,SACA,YACM,gCAAgC,eAAe,QAAQ,IAAI,SAAS,OAAO,CAAC"}

package/dist/errors-BXKc7juX.d.mts

@@ -0,0 +1,8 @@
+//#region src/runtime/errors.d.ts
+/** Thrown when no RuntimeContext is active in the selected storage. */
+declare class RuntimeContextNotConfiguredError extends Error {
+  constructor();
+}
+//#endregion
+export { RuntimeContextNotConfiguredError as t };
+//# sourceMappingURL=errors-BXKc7juX.d.mts.map

package/dist/errors-BXKc7juX.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors-BXKc7juX.d.mts","names":[],"sources":["../src/runtime/errors.ts"],"mappings":";;cACa,yCAAyC;EAAA"}

package/dist/index-BFgG9zZC.d.mts

@@ -0,0 +1,374 @@
+import { Err, InferErr, InferOk, Result } from "better-result";
+//#region src/service/types.d.ts
+/** Internal type-only identity for the branded Service instance. */
+declare const ServiceIdentityTypeId: unique symbol;
+/** A branded Service instance identity carried by the literal Service tag. */
+interface ServiceIdentity<out Tag extends string = string> {
+  readonly [ServiceIdentityTypeId]: Tag;
+}
+/** The widened Service instance constraint used by contextual APIs. */
+type AnyService = ServiceIdentity<string>;
+/** Remove the internal Service identity marker from an implementation contract. */
+type ServiceContract<S> = S extends unknown ? Omit<S, typeof ServiceIdentityTypeId> : never;
+type ServiceStatics<out Tag extends string, in out Instance extends AnyService> = {
+  readonly name: string;
+  readonly serviceTag: Tag;
+  /** Type-check a structural implementation and return it unchanged. */
+  readonly of: (this: void, implementation: ServiceContract<Instance>) => Instance;
+};
+type AbstractServiceConstructor<out Instance> = abstract new (...args: any[]) => Instance;
+/** A class constructor carrying a Service tag and its instance contract. */
+interface ServiceToken<out Tag extends string = string, in out Instance extends AnyService = any> extends AbstractServiceConstructor<Instance>, ServiceStatics<Tag, Instance> {}
+/** The widened token constraint used by generic Service infrastructure. */
+type AnyServiceToken = ServiceToken<string, any>;
+/** A concrete, constructible Service class accepted by a Layer provider. */
+type ServiceClass<Tag extends string = string, Instance extends AnyService = AnyService> = (new (...args: any[]) => Instance) & ServiceStatics<Tag, Instance>;
+/** Extract the instance type represented by a Service token. */
+type ServiceInstance<T extends AnyServiceToken> = InstanceType<T>;
+/** Extract the literal identity tag represented by a branded Service instance. */
+type ServiceTagOf<S extends AnyService> = S[typeof ServiceIdentityTypeId];
+/** Extract the Service token represented by a branded Service instance. */
+type ServiceTokenOf<S extends AnyService> = S extends AnyService ? ServiceToken<ServiceTagOf<S>, S> : never;
+/** Extract the literal identity tag represented by a Service instance or token. */
+type ServiceTag<T extends AnyService | AnyServiceToken> = T extends AnyService ? ServiceTagOf<T> : T extends AnyServiceToken ? T['serviceTag'] : never;
+type MethodRequirements<T> = { [K in keyof T]: T[K] extends ((...args: any[]) => infer Return) ? EffectRequirements<Return> : never; }[keyof T];
+/**
+ * Services required by the Effect-returning methods of a Service class.
+ *
+ * This type is used automatically by `Layer.make`, `Layer.gen`, and the other
+ * provider constructors.
+ */
+type ServiceRequirements<S extends AnyService> = MethodRequirements<S>;
+//#endregion
+//#region src/effect/types.d.ts
+type ResultValue = Result<any, any>;
+/** Keep nested Effect errors and Service requirements in one inferred yield. */
+type EffectIterator<A, E, R extends AnyService> = {
+  [Symbol.iterator](): Generator<Err<never, E> & ServiceRequirement<R>, A, unknown>;
+};
+type EffectMethods<A, E, R extends AnyService> = {
+  map<B>(fn: (value: A) => B): Effect<B, E, R>;
+  mapError<E2>(fn: (error: E) => E2): Effect<A, E2, R>;
+  tryRecover<Next extends ResultValue>(fn: (error: E) => Next): Effect<A | EffectSuccess<Next>, EffectError<Next>, R | EffectRequirements<Next>>;
+  tryRecoverAsync<Next extends ResultValue>(fn: (error: E) => Promise<Next>): Promise<Effect<A | EffectSuccess<Next>, EffectError<Next>, R | EffectRequirements<Next>>>;
+  andThen<Next extends ResultValue>(fn: (value: A) => Next): Effect<EffectSuccess<Next>, E | EffectError<Next>, R | EffectRequirements<Next>>;
+  andThenAsync<Next extends ResultValue>(fn: (value: A) => Promise<Next>): Promise<Effect<EffectSuccess<Next>, E | EffectError<Next>, R | EffectRequirements<Next>>>;
+  tap(fn: (value: A) => void): Effect<A, E, R>;
+  tapAsync(fn: (value: A) => Promise<void>): Promise<Effect<A, E, R>>;
+  tapError(fn: (error: E) => void): Effect<A, E, R>;
+  tapErrorAsync(fn: (error: E) => Promise<void>): Promise<Effect<A, E, R>>;
+  tapBoth(handlers: {
+    ok: (value: A) => void;
+    err: (error: E) => void;
+  }): Effect<A, E, R>;
+  tapBothAsync(handlers: {
+    ok: (value: A) => Promise<void>;
+    err: (error: E) => Promise<void>;
+  }): Promise<Effect<A, E, R>>;
+};
+/**
+ * Type-only identity for a Service requirement yielded by a generator.
+ *
+ * The declaration has no runtime value. Service iterators return their
+ * resolved instances without yielding a marker at runtime.
+ */
+declare const ServiceRequirementTypeId: unique symbol;
+/** Type-only identity for requirement metadata attached to Effect results. */
+declare const EffectRequirementsTypeId: unique symbol;
+/** Type-only identity for lazy Effect programs. */
+declare const ProgramTypeId: unique symbol;
+/** Required declaration-only variance carrier for Effect Service requirements. */
+interface EffectVariance<out R extends AnyService> {
+  readonly requirements: R;
+}
+/** Required declaration-only variance carrier for a lazy Program. */
+interface ProgramVariance<out A, out E, out R extends AnyService> {
+  readonly success: A;
+  readonly error: E;
+  readonly requirements: R;
+}
+/**
+ * Metadata carried by the yield type of a Service token.
+ *
+ * This interface is intentionally phantom: it is used only while TypeScript
+ * infers a generator's yielded values.
+ */
+interface ServiceRequirement<out T> {
+  readonly [ServiceRequirementTypeId]: T;
+}
+/** A `better-result` Result with required declaration-only metadata for Services. */
+type Effect<A, E, R extends AnyService = never> = EffectMethods<A, E, R> & Result<A, E> & EffectIterator<A, E, R> & {
+  readonly [EffectRequirementsTypeId]: EffectVariance<R>;
+};
+/** A nominal lazy computation that produces an Effect when invoked. */
+type Program<A, E, R extends AnyService = never> = {
+  (): Effect<A, E, R> | Promise<Effect<A, E, R>>;
+  readonly [ProgramTypeId]: ProgramVariance<A, E, R>;
+};
+/** An Effect with erased success, error, and Service requirements. */
+type AnyEffect = Effect<unknown, unknown, AnyService>;
+/** Values that an Effect generator may yield. */
+type EffectYield = Err<never, unknown> | ServiceRequirement<unknown>;
+/** Extract the error channel from Result values yielded by a generator. */
+type InferYieldError<Y> = Y extends Err<never, infer E> ? E : never;
+/** Extract branded Service instances carried by yielded Service requirements. */
+type InferYieldRequirements<Y> = Y extends ServiceRequirement<infer Requirement> ? Requirement extends AnyService ? Requirement : never : never;
+type InferEffectRequirements<T> = T extends unknown ? typeof EffectRequirementsTypeId extends keyof T ? T extends {
+  readonly [EffectRequirementsTypeId]: EffectVariance<infer Requirements extends AnyService>;
+} ? Requirements : never : never : never;
+type InferProgramSuccess<T> = T extends {
+  readonly [ProgramTypeId]: ProgramVariance<infer Success, any, any>;
+} ? Success : never;
+type InferProgramError<T> = T extends {
+  readonly [ProgramTypeId]: ProgramVariance<any, infer Error, any>;
+} ? Error : never;
+type InferProgramRequirements<T> = T extends {
+  readonly [ProgramTypeId]: ProgramVariance<any, any, infer Requirements>;
+} ? Requirements : never;
+/** Extract declaration-only Service requirements from an Effect or Promise. */
+type EffectRequirements<T> = T extends unknown ? InferProgramRequirements<T> extends never ? InferEffectRequirements<Awaited<T>> : InferProgramRequirements<T> : never;
+/** Extract the success value from an Effect or Promise. */
+type EffectSuccess<T> = T extends unknown ? InferProgramSuccess<T> extends never ? Awaited<T> extends Result<infer A, unknown> ? A : never : InferProgramSuccess<T> : never;
+/** Extract the error value from an Effect or Promise. */
+type EffectError<T> = T extends unknown ? InferProgramError<T> extends never ? Awaited<T> extends Result<unknown, infer E> ? E : never : InferProgramError<T> : never;
+/** Build the public Effect type produced from a generator. */
+type EffectFromGenerator<Yield, Returned extends Result<any, any>> = Effect<InferOk<Returned>, InferYieldError<Yield> | InferErr<Returned>, InferYieldRequirements<Yield> | EffectRequirements<Returned>>;
+/** Build the nominal lazy Program produced from a generator. */
+type ProgramFromGenerator<Yield, Returned extends Result<any, any>> = Program<InferOk<Returned>, InferYieldError<Yield> | InferErr<Returned>, InferYieldRequirements<Yield> | EffectRequirements<Returned>>;
+//#endregion
+//#region src/service/service.d.ts
+type ServiceTagLiteral<Tag extends string> = string extends Tag ? never : Tag extends '' ? never : Tag;
+interface ServiceFactory<Self> {
+  <const Tag extends string>(tag: ServiceTagLiteral<Tag>): (abstract new () => ServiceIdentity<Tag>) & {
+    readonly name: string;
+    readonly serviceTag: Tag;
+  } & {
+    readonly of: Service.FactoryOf<Self, Tag>;
+    readonly [Symbol.asyncIterator]: (this: ServiceToken<Tag, Self & ServiceIdentity<Tag>>) => AsyncGenerator<ServiceRequirement<Self>, Self, unknown>;
+  };
+}
+/**
+ * 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.
+ */
+declare function Service<Self>(): ServiceFactory<Self>;
+/** Type-level aliases for Service tokens and their instance contracts. */
+declare namespace Service {
+  /** The widened Service instance constraint. */
+  type Any = AnyService;
+  /** A class-backed Service token with a stable tag and instance contract. */
+  type Token<Tag extends string = string, Instance extends AnyService = any> = ServiceToken<Tag, Instance>;
+  /** A constructible Service class with a stable tag and instance contract. */
+  type Class<Tag extends string = string, Instance extends AnyService = AnyService> = ServiceClass<Tag, Instance>;
+  /** Extract the instance represented by a Service token. */
+  type Instance<T extends AnyServiceToken> = ServiceInstance<T>;
+  /** Extract the stable tag represented by a Service instance. */
+  type Tag<S extends AnyService> = ServiceTag<S>;
+  /** A branded Service instance identity with a stable tag. */
+  type Identity<Tag extends string = string> = ServiceIdentity<Tag>;
+  /** Remove the internal identity marker from a Service implementation contract. */
+  type Contract<S extends AnyService> = ServiceContract<S>;
+  /** Extract the Service token represented by a branded Service instance. */
+  type TokenOf<S extends AnyService> = ServiceTokenOf<S>;
+  /** Declaration bridge for the recursive structural `Service.of` signature. */
+  type FactoryOf<Self, Tag extends string> = (this: void, implementation: ServiceContract<Self & ServiceIdentity<Tag>>) => Self;
+  /** Extract Effect Service requirements from a Service instance. */
+  type Requirements<S extends AnyService> = ServiceRequirements<S>;
+}
+//#endregion
+//#region src/scope/errors.d.ts
+/** Thrown when Scope context is accessed outside an active Scope execution. */
+declare class ScopeRuntimeNotConfiguredError extends Error {
+  constructor();
+}
+/** Thrown when a resource or finalizer is added after Scope closure begins. */
+declare class ScopeClosedError extends Error {
+  constructor();
+}
+/** Aggregates finalizer failures encountered while closing a Scope. */
+declare class ScopeCloseError extends Error {
+  readonly causes: readonly unknown[];
+  constructor(causes: readonly unknown[]);
+}
+/** Thrown when a value has neither Symbol.dispose nor Symbol.asyncDispose. */
+declare class ResourceNotDisposableError extends Error {
+  constructor();
+}
+//#endregion
+//#region src/scope/types.d.ts
+/** A value that may be returned synchronously or asynchronously. */
+type MaybePromise<T> = T | PromiseLike<T>;
+/** Final outcome supplied to Scope finalizers and resource releases. */
+type ScopeOutcome = {
+  /** Indicates that the owning program completed successfully. */
+  readonly status: 'success';
+} | {
+  /** Indicates that the owning program failed or was interrupted. */
+  readonly status: 'failure';
+  /** The original program or execution failure. */
+  readonly cause: unknown;
+};
+/** Cleanup callback registered with a Scope. */
+type ScopeFinalizer = (outcome: ScopeOutcome) => MaybePromise<void>;
+/** Aggregated cleanup information reported at an execution boundary. */
+type CleanupFailureDiagnostic = {
+  /** Outcome used for the Scope close that triggered cleanup. */
+  readonly outcome: ScopeOutcome;
+  /** Aggregated finalizer failure. */
+  readonly error: ScopeCloseError;
+};
+type SyncDisposableResource = {
+  [Symbol.dispose]: () => void;
+  [Symbol.asyncDispose]?: () => MaybePromise<void>;
+};
+type AsyncDisposableResource = {
+  [Symbol.dispose]?: () => void;
+  [Symbol.asyncDispose]: () => MaybePromise<void>;
+};
+/** A value implementing at least one JavaScript disposal protocol. */
+type DisposableResource = SyncDisposableResource | AsyncDisposableResource;
+//#endregion
+//#region src/scope/scope.d.ts
+/**
+ * Non-owning lifecycle context for finalizers and child Scopes.
+ *
+ * A Scope can register cleanup and create children, but it cannot close
+ * itself. Use `Scope.make()` or `Scope.run()` when your code owns the Scope.
+ */
+interface Scope {
+  /** Register a finalizer that runs when the owning Scope closes. */
+  addFinalizer(finalizer: ScopeFinalizer): void;
+  /** Acquire a resource and register its outcome-aware release callback. */
+  acquire<R>(acquire: () => MaybePromise<R>, release: (resource: R, outcome: ScopeOutcome) => MaybePromise<void>): Promise<R>;
+  /** Register an already-acquired disposable resource. */
+  add<R extends DisposableResource>(resource: R): Promise<R>;
+  /** Create a child Scope owned by this Scope. */
+  fork(): CloseableScope;
+}
+/** A Scope whose owner is responsible for calling `close()`. */
+interface CloseableScope extends Scope {
+  /** Close the Scope and run children and finalizers in child-first LIFO order. */
+  close(outcome?: ScopeOutcome): Promise<void>;
+}
+declare const Scope: {
+  /** Create an owned, initially open Scope. */
+  readonly make: () => CloseableScope;
+  /** Return the non-owning Scope available in the current execution context. */
+  readonly current: () => Scope;
+  /** Run a callback with an existing Scope supplied as the current context. */
+  readonly provide: <A>(scope: Scope, program: () => A) => A;
+  /** Resolve the current Scope through `yield* Scope` inside an Effect. */
+  readonly [Symbol.iterator]: () => Generator<never, Scope, unknown>;
+  /**
+   * 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()
+   * })
+   * ```
+   */
+  readonly run: <A>(program: (scope: Scope) => A | PromiseLike<A>) => Promise<Awaited<A>>;
+};
+/** Type-level aliases for Scope ownership, outcomes, and cleanup contracts. */
+declare namespace Scope {
+  /** A Scope whose owner is responsible for calling `close()`. */
+  type Closeable = CloseableScope;
+  /** The outcome supplied to Scope finalizers and resource releases. */
+  type Outcome = ScopeOutcome;
+  /** A cleanup callback registered with a Scope. */
+  type Finalizer = ScopeFinalizer;
+  /** A value implementing a JavaScript disposal protocol. */
+  type Disposable = DisposableResource;
+}
+//#endregion
+//#region src/runtime/context.d.ts
+/** The complete contextual state shared by Service, Scope and Layer resolution. */
+interface RuntimeContext {
+  readonly resolver: ServiceResolver;
+  readonly scope: Scope;
+  readonly signal?: AbortSignal;
+  readonly resolutionPath: readonly AnyServiceToken[];
+}
+/** Host-specific storage for the current RuntimeContext. */
+interface RuntimeContextStorage {
+  run<A>(context: RuntimeContext, program: () => A): A;
+  current(): RuntimeContext;
+}
+//#endregion
+//#region src/service/runtime.d.ts
+/** Resolves class-backed Service tokens for a runtime execution. */
+interface ServiceResolver {
+  /** Resolve a token to its corresponding Service instance. */
+  resolve<T extends AnyServiceToken>(token: T): InstanceType<T> | PromiseLike<InstanceType<T>>;
+}
+/** Provides the resolver context used by Service tokens during execution. */
+declare 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<A>(resolver: ServiceResolver, program: () => A, storage?: RuntimeContextStorage): A;
+  /** Return the resolver active in the current execution context. */
+  static current(): ServiceResolver;
+  /** Resolve a Service token using the active resolver. */
+  static resolve<T extends AnyServiceToken>(token: T): Promise<InstanceType<T>>;
+}
+//#endregion
+//#region src/service/errors.d.ts
+/** Thrown when a Service is accessed without an active runtime resolver. */
+declare class ServiceRuntimeNotConfiguredError extends Error {
+  constructor();
+}
+/** Thrown when a runtime has no provider for the requested Service tag. */
+declare class ServiceNotFoundError extends Error {
+  readonly service: AnyServiceToken;
+  constructor(service: AnyServiceToken);
+}
+/** Thrown when resolving a Service re-enters a Service already in its path. */
+declare class CircularDependencyError extends Error {
+  readonly path: readonly AnyServiceToken[];
+  constructor(path: readonly AnyServiceToken[]);
+}
+/** Thrown when a registered Service provider fails during lazy acquisition. */
+declare class ServiceAcquisitionError extends Error {
+  readonly service: AnyServiceToken;
+  readonly cause: unknown;
+  constructor(service: AnyServiceToken, resolutionPath: readonly AnyServiceToken[], cause: unknown);
+  readonly resolutionPath: readonly AnyServiceToken[];
+}
+//#endregion
+export { ProgramFromGenerator as A, ServiceTagOf as B, EffectError as C, EffectYield as D, EffectSuccess as E, ServiceContract as F, ServiceTokenOf as H, ServiceIdentity as I, ServiceInstance as L, AnyService as M, AnyServiceToken as N, InferYieldRequirements as O, ServiceClass as P, ServiceRequirements as R, Effect as S, EffectRequirements as T, ServiceToken as V, ScopeCloseError as _, ServiceResolver as a, Service as b, RuntimeContextStorage as c, CleanupFailureDiagnostic as d, DisposableResource as f, ResourceNotDisposableError as g, ScopeOutcome as h, ServiceRuntimeNotConfiguredError as i, ServiceRequirement as j, Program as k, CloseableScope as l, ScopeFinalizer as m, ServiceAcquisitionError as n, ServiceRuntime as o, MaybePromise as p, ServiceNotFoundError as r, RuntimeContext as s, CircularDependencyError as t, Scope as u, ScopeClosedError as v, EffectFromGenerator as w, AnyEffect as x, ScopeRuntimeNotConfiguredError as y, ServiceTag as z };
+//# sourceMappingURL=index-BFgG9zZC.d.mts.map