better-effect 0.13.0 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (109) hide show
  1. package/README.md +337 -88
  2. package/dist/adapters/iti.d.mts +2 -3
  3. package/dist/adapters/iti.d.mts.map +1 -1
  4. package/dist/adapters/iti.mjs +2 -2
  5. package/dist/bun.d.mts +75 -23
  6. package/dist/bun.d.mts.map +1 -1
  7. package/dist/bun.mjs +170 -33
  8. package/dist/bun.mjs.map +1 -1
  9. package/dist/{context-BphfFUMO.mjs → context-DSGSqcJj.mjs} +12 -3
  10. package/dist/context-DSGSqcJj.mjs.map +1 -0
  11. package/dist/{current-request-DDKNyymv.mjs → current-request-Bc1YHL0w.mjs} +3 -2
  12. package/dist/{current-request-DDKNyymv.mjs.map → current-request-Bc1YHL0w.mjs.map} +1 -1
  13. package/dist/{current-request-CIU7AHhF.d.mts → current-request-Dm-QQ3Xr.d.mts} +4 -4
  14. package/dist/current-request-Dm-QQ3Xr.d.mts.map +1 -0
  15. package/dist/{effect-CPdV7Yv8.mjs → effect-W0IQXY8P.mjs} +21 -2
  16. package/dist/effect-W0IQXY8P.mjs.map +1 -0
  17. package/dist/{errors-BKcsQ0ip.d.mts → errors-CpHMzPiP.d.mts} +6 -2
  18. package/dist/errors-CpHMzPiP.d.mts.map +1 -0
  19. package/dist/hono.d.mts +63 -27
  20. package/dist/hono.d.mts.map +1 -1
  21. package/dist/hono.mjs +111 -45
  22. package/dist/hono.mjs.map +1 -1
  23. package/dist/{index-CCi07kUw.d.mts → index-3Bkl-sxS.d.mts} +7 -2
  24. package/dist/{index-CCi07kUw.d.mts.map → index-3Bkl-sxS.d.mts.map} +1 -1
  25. package/dist/{index-cXgyMa0v.d.mts → index-C2ed9Ilq.d.mts} +32 -7
  26. package/dist/index-C2ed9Ilq.d.mts.map +1 -0
  27. package/dist/{index-BodMy6rO.d.mts → index-ClNndn2-.d.mts} +93 -63
  28. package/dist/index-ClNndn2-.d.mts.map +1 -0
  29. package/dist/{index-DAKn0qHk.d.mts → index-Cy1VsU-u.d.mts} +2 -4
  30. package/dist/index-Cy1VsU-u.d.mts.map +1 -0
  31. package/dist/index.d.mts +6 -8
  32. package/dist/index.mjs +8 -9
  33. package/dist/index.mjs.map +1 -1
  34. package/dist/{internal-identity-CbXoZIfw.mjs → internal-identity-BuHBtP0k.mjs} +2 -2
  35. package/dist/{internal-identity-CbXoZIfw.mjs.map → internal-identity-BuHBtP0k.mjs.map} +1 -1
  36. package/dist/layer-2kjHVv4N.mjs +343 -0
  37. package/dist/layer-2kjHVv4N.mjs.map +1 -0
  38. package/dist/layer-C2OaqTmB.d.mts +987 -0
  39. package/dist/layer-C2OaqTmB.d.mts.map +1 -0
  40. package/dist/next.d.mts +102 -26
  41. package/dist/next.d.mts.map +1 -1
  42. package/dist/next.mjs +157 -40
  43. package/dist/next.mjs.map +1 -1
  44. package/dist/{node-context-DczjAcrX.d.mts → node-context-1YEjrU9g.d.mts} +2 -2
  45. package/dist/{node-context-DczjAcrX.d.mts.map → node-context-1YEjrU9g.d.mts.map} +1 -1
  46. package/dist/{node-context-Ca18oNSg.mjs → node-context-g3bCcY9t.mjs} +2 -2
  47. package/dist/{node-context-Ca18oNSg.mjs.map → node-context-g3bCcY9t.mjs.map} +1 -1
  48. package/dist/node.d.mts +11 -6
  49. package/dist/node.d.mts.map +1 -1
  50. package/dist/node.mjs +156 -10
  51. package/dist/node.mjs.map +1 -1
  52. package/dist/opentelemetry.d.mts +20 -2
  53. package/dist/opentelemetry.d.mts.map +1 -1
  54. package/dist/opentelemetry.mjs +423 -5
  55. package/dist/opentelemetry.mjs.map +1 -1
  56. package/dist/{registration-drnZk0SY.mjs → registration-Bwe2GbVu.mjs} +8 -2
  57. package/dist/registration-Bwe2GbVu.mjs.map +1 -0
  58. package/dist/runtime/explicit.d.mts +2 -2
  59. package/dist/runtime/explicit.mjs +1 -1
  60. package/dist/runtime/node.d.mts +3 -3
  61. package/dist/runtime/node.mjs +2 -2
  62. package/dist/runtime-qpcVwaz_.mjs +1680 -0
  63. package/dist/runtime-qpcVwaz_.mjs.map +1 -0
  64. package/dist/service-CO9VJQYa.mjs +74 -0
  65. package/dist/service-CO9VJQYa.mjs.map +1 -0
  66. package/dist/{signal-nfgFyNCk.mjs → signal-5Rg9bUUe.mjs} +2 -2
  67. package/dist/{signal-nfgFyNCk.mjs.map → signal-5Rg9bUUe.mjs.map} +1 -1
  68. package/dist/{standard-services-vnGIafkS.mjs → standard-services-B-iMM_W7.mjs} +38 -4
  69. package/dist/standard-services-B-iMM_W7.mjs.map +1 -0
  70. package/dist/standard-services.d.mts +4 -4
  71. package/dist/standard-services.mjs +3 -3
  72. package/dist/testing.d.mts +25 -7
  73. package/dist/testing.d.mts.map +1 -1
  74. package/dist/testing.mjs +51 -7
  75. package/dist/testing.mjs.map +1 -1
  76. package/dist/{types-oihI-ESv.d.mts → types-BFTqCCcw.d.mts} +32 -5
  77. package/dist/types-BFTqCCcw.d.mts.map +1 -0
  78. package/dist/web-effect-B9hp9jIe.mjs +380 -0
  79. package/dist/web-effect-B9hp9jIe.mjs.map +1 -0
  80. package/dist/web.d.mts +22 -13
  81. package/dist/web.d.mts.map +1 -1
  82. package/dist/web.mjs +1 -1
  83. package/package.json +10 -16
  84. package/dist/context-BphfFUMO.mjs.map +0 -1
  85. package/dist/current-request-CIU7AHhF.d.mts.map +0 -1
  86. package/dist/disposable-CP-Q2H3l.mjs +0 -57
  87. package/dist/disposable-CP-Q2H3l.mjs.map +0 -1
  88. package/dist/effect-CPdV7Yv8.mjs.map +0 -1
  89. package/dist/errors-BKcsQ0ip.d.mts.map +0 -1
  90. package/dist/index-AiKM71-u.d.mts +0 -376
  91. package/dist/index-AiKM71-u.d.mts.map +0 -1
  92. package/dist/index-BodMy6rO.d.mts.map +0 -1
  93. package/dist/index-DAKn0qHk.d.mts.map +0 -1
  94. package/dist/index-cXgyMa0v.d.mts.map +0 -1
  95. package/dist/layer-D16GKxuX.mjs +0 -269
  96. package/dist/layer-D16GKxuX.mjs.map +0 -1
  97. package/dist/observer-9nhbL7Pr.d.mts +0 -68
  98. package/dist/observer-9nhbL7Pr.d.mts.map +0 -1
  99. package/dist/outcome-DI8LPIQ4.d.mts +0 -387
  100. package/dist/outcome-DI8LPIQ4.d.mts.map +0 -1
  101. package/dist/program-metadata-BxjGkT17.mjs +0 -260
  102. package/dist/program-metadata-BxjGkT17.mjs.map +0 -1
  103. package/dist/registration-drnZk0SY.mjs.map +0 -1
  104. package/dist/runtime-C_55ofnL.mjs +0 -791
  105. package/dist/runtime-C_55ofnL.mjs.map +0 -1
  106. package/dist/standard-services-vnGIafkS.mjs.map +0 -1
  107. package/dist/types-oihI-ESv.d.mts.map +0 -1
  108. package/dist/web-Bq3MfMrj.mjs +0 -147
  109. package/dist/web-Bq3MfMrj.mjs.map +0 -1
@@ -0,0 +1,987 @@
1
+ import { Err, InferErr, InferOk, Result } from "better-result";
2
+ //#region src/service/types.d.ts
3
+ /** Internal type-only identity for the branded Service instance. */
4
+ declare const ServiceIdentityTypeId: unique symbol;
5
+ /** A branded Service instance identity carried by the literal Service tag. */
6
+ interface ServiceIdentity<out Tag extends string = string> {
7
+ readonly [ServiceIdentityTypeId]: Tag;
8
+ }
9
+ /** The widened Service instance constraint used by contextual APIs. */
10
+ type AnyService = ServiceIdentity<string>;
11
+ /** Remove the internal Service identity marker from an implementation contract. */
12
+ type ServiceContract<S> = S extends unknown ? Omit<S, typeof ServiceIdentityTypeId> : never;
13
+ type ServiceStatics<out Tag extends string, in out Instance extends AnyService> = {
14
+ readonly name: string;
15
+ readonly serviceTag: Tag;
16
+ /** Yield this Service from a synchronous generator factory. */
17
+ readonly [Symbol.iterator]: () => Generator<ServiceRequirement<Instance>, Instance, unknown>;
18
+ /** Type-check a structural implementation and return it unchanged. */
19
+ readonly of: (this: void, implementation: ServiceContract<Instance>) => Instance;
20
+ };
21
+ type AbstractServiceConstructor<out Instance> = abstract new (...args: any[]) => Instance;
22
+ /** A class constructor carrying a Service tag and its instance contract. */
23
+ interface ServiceToken<out Tag extends string = string, in out Instance extends AnyService = any> extends AbstractServiceConstructor<Instance>, ServiceStatics<Tag, Instance> {}
24
+ /** The widened token constraint used by generic Service infrastructure. */
25
+ type AnyServiceToken = ServiceToken<string, any>;
26
+ /** A concrete, constructible Service class accepted by a Layer provider. */
27
+ type ServiceClass<Tag extends string = string, Instance extends AnyService = AnyService> = (new (...args: any[]) => Instance) & ServiceStatics<Tag, Instance>;
28
+ /** Extract the instance type represented by a Service token. */
29
+ type ServiceInstance<T extends AnyServiceToken> = InstanceType<T>;
30
+ /** Extract the literal identity tag represented by a branded Service instance. */
31
+ type ServiceTagOf<S extends AnyService> = S[typeof ServiceIdentityTypeId];
32
+ /** Extract the Service token represented by a branded Service instance. */
33
+ type ServiceTokenOf<S extends AnyService> = S extends AnyService ? ServiceToken<ServiceTagOf<S>, S> : never;
34
+ /** Extract the literal identity tag represented by a Service instance or token. */
35
+ type ServiceTag<T extends AnyService | AnyServiceToken> = T extends AnyService ? ServiceTagOf<T> : T extends AnyServiceToken ? T['serviceTag'] : never;
36
+ type MethodRequirements<T> = { [K in keyof T]: T[K] extends ((...args: any[]) => infer Return) ? EffectRequirements<Return> : never; }[keyof T];
37
+ /**
38
+ * Services required by the Effect-returning methods of a Service class.
39
+ *
40
+ * This type is used automatically by `Layer.make`, `Layer.gen`, and the other
41
+ * provider constructors.
42
+ */
43
+ type ServiceRequirements<S extends AnyService> = MethodRequirements<S>;
44
+ //#endregion
45
+ //#region src/effect/types.d.ts
46
+ type ResultValue = Result<any, any>;
47
+ /** Keep nested Effect errors and Service requirements in one inferred yield. */
48
+ type EffectIterator<A, E, R extends AnyService> = {
49
+ [Symbol.iterator](): Generator<Err<never, E> & ServiceRequirement<R>, A, unknown>;
50
+ };
51
+ type EffectMethods<A, E, R extends AnyService> = {
52
+ map<B>(fn: (value: A) => B): Effect<B, E, R>;
53
+ mapError<E2>(fn: (error: E) => E2): Effect<A, E2, R>;
54
+ tryRecover<Next extends ResultValue>(fn: (error: E) => Next): Effect<A | EffectSuccess<Next>, EffectError<Next>, R | EffectRequirements<Next>>;
55
+ tryRecoverAsync<Next extends ResultValue>(fn: (error: E) => Promise<Next>): Promise<Effect<A | EffectSuccess<Next>, EffectError<Next>, R | EffectRequirements<Next>>>;
56
+ andThen<Next extends ResultValue>(fn: (value: A) => Next): Effect<EffectSuccess<Next>, E | EffectError<Next>, R | EffectRequirements<Next>>;
57
+ andThenAsync<Next extends ResultValue>(fn: (value: A) => Promise<Next>): Promise<Effect<EffectSuccess<Next>, E | EffectError<Next>, R | EffectRequirements<Next>>>;
58
+ tap(fn: (value: A) => void): Effect<A, E, R>;
59
+ tapAsync(fn: (value: A) => PromiseLike<void>): Promise<Effect<A, E, R>>;
60
+ tapError(fn: (error: E) => void): Effect<A, E, R>;
61
+ tapErrorAsync(fn: (error: E) => PromiseLike<void>): Promise<Effect<A, E, R>>;
62
+ tapBoth(handlers: {
63
+ ok: (value: A) => void;
64
+ err: (error: E) => void;
65
+ }): Effect<A, E, R>;
66
+ tapBothAsync(handlers: {
67
+ ok: (value: A) => PromiseLike<void>;
68
+ err: (error: E) => PromiseLike<void>;
69
+ }): Promise<Effect<A, E, R>>;
70
+ };
71
+ /**
72
+ * Type-only identity for a Service requirement yielded by a generator.
73
+ *
74
+ * The declaration has no runtime value. Service iterators return their
75
+ * resolved instances without yielding a marker at runtime.
76
+ */
77
+ declare const ServiceRequirementTypeId: unique symbol;
78
+ /** Type-only identity for requirement metadata attached to Effect results. */
79
+ declare const EffectRequirementsTypeId: unique symbol;
80
+ /** Type-only identity for lazy Effect programs. */
81
+ declare const ProgramTypeId: unique symbol;
82
+ /** Required declaration-only variance carrier for Effect Service requirements. */
83
+ interface EffectVariance<out R extends AnyService> {
84
+ readonly requirements: R;
85
+ }
86
+ /** Required declaration-only variance carrier for a lazy Program. */
87
+ interface ProgramVariance<out A, out E, out R extends AnyService> {
88
+ readonly success: A;
89
+ readonly error: E;
90
+ readonly requirements: R;
91
+ }
92
+ /**
93
+ * Metadata carried by the yield type of a Service token.
94
+ *
95
+ * This interface is intentionally phantom: it is used only while TypeScript
96
+ * infers a generator's yielded values.
97
+ */
98
+ interface ServiceRequirement<out T> {
99
+ readonly [ServiceRequirementTypeId]: T;
100
+ }
101
+ /** A `better-result` Result with required declaration-only metadata for Services. */
102
+ type Effect<A, E, R extends AnyService = never> = EffectMethods<A, E, R> & Result<A, E> & EffectIterator<A, E, R> & {
103
+ readonly [EffectRequirementsTypeId]: EffectVariance<R>;
104
+ };
105
+ /** A nominal lazy computation that produces an Effect when invoked. */
106
+ type Program<A, E, R extends AnyService = never> = {
107
+ (): Effect<A, E, R> | Promise<Effect<A, E, R>>;
108
+ readonly [ProgramTypeId]: ProgramVariance<A, E, R>;
109
+ };
110
+ /** An Effect with erased success, error, and Service requirements. */
111
+ type AnyEffect = Effect<unknown, unknown, AnyService>;
112
+ /** Values that an Effect generator may yield. */
113
+ type EffectYield = Err<never, unknown> | ServiceRequirement<unknown>;
114
+ /** Extract the error channel from Result values yielded by a generator. */
115
+ type InferYieldError<Y> = Y extends Err<never, infer E> ? E : never;
116
+ /** Extract branded Service instances carried by yielded Service requirements. */
117
+ type InferYieldRequirements<Y> = Y extends ServiceRequirement<infer Requirement> ? Requirement extends AnyService ? Requirement : never : never;
118
+ type InferEffectRequirements<T> = T extends unknown ? typeof EffectRequirementsTypeId extends keyof T ? T extends {
119
+ readonly [EffectRequirementsTypeId]: EffectVariance<infer Requirements extends AnyService>;
120
+ } ? Requirements : never : never : never;
121
+ type InferProgramSuccess<T> = T extends {
122
+ readonly [ProgramTypeId]: ProgramVariance<infer Success, any, any>;
123
+ } ? Success : never;
124
+ type InferProgramError<T> = T extends {
125
+ readonly [ProgramTypeId]: ProgramVariance<any, infer Error, any>;
126
+ } ? Error : never;
127
+ type InferProgramRequirements<T> = T extends {
128
+ readonly [ProgramTypeId]: ProgramVariance<any, any, infer Requirements>;
129
+ } ? Requirements : never;
130
+ /** Extract declaration-only Service requirements from an Effect or Promise. */
131
+ type EffectRequirements<T> = T extends unknown ? InferProgramRequirements<T> extends never ? InferEffectRequirements<Awaited<T>> : InferProgramRequirements<T> : never;
132
+ /** Extract the success value from an Effect or Promise. */
133
+ type EffectSuccess<T> = T extends unknown ? InferProgramSuccess<T> extends never ? Awaited<T> extends Result<infer A, unknown> ? A : never : InferProgramSuccess<T> : never;
134
+ /** Extract the error value from an Effect or Promise. */
135
+ type EffectError<T> = T extends unknown ? InferProgramError<T> extends never ? Awaited<T> extends Result<unknown, infer E> ? E : never : InferProgramError<T> : never;
136
+ /** Build the public Effect type produced from a generator. */
137
+ type EffectFromGenerator<Yield, Returned extends Result<any, any>> = Effect<InferOk<Returned>, InferYieldError<Yield> | InferErr<Returned>, InferYieldRequirements<Yield> | EffectRequirements<Returned>>;
138
+ /** Build the nominal lazy Program produced from a generator. */
139
+ type ProgramFromGenerator<Yield, Returned extends Result<any, any>> = Program<InferOk<Returned>, InferYieldError<Yield> | InferErr<Returned>, InferYieldRequirements<Yield> | EffectRequirements<Returned>>;
140
+ //#endregion
141
+ //#region src/service/service.d.ts
142
+ type ServiceTagLiteral<Tag extends string> = string extends Tag ? never : Tag extends '' ? never : Tag;
143
+ interface ServiceFactory<Self> {
144
+ <const Tag extends string>(tag: ServiceTagLiteral<Tag>): (abstract new () => ServiceIdentity<Tag>) & {
145
+ readonly name: string;
146
+ readonly serviceTag: Tag;
147
+ } & {
148
+ readonly of: Service.FactoryOf<Self, Tag>;
149
+ readonly [Symbol.iterator]: (this: ServiceToken<Tag, Self & ServiceIdentity<Tag>>) => Generator<ServiceRequirement<Self>, Self, unknown>;
150
+ readonly [Symbol.asyncIterator]: (this: ServiceToken<Tag, Self & ServiceIdentity<Tag>>) => AsyncGenerator<ServiceRequirement<Self>, Self, unknown>;
151
+ };
152
+ }
153
+ /**
154
+ * Declare a class-backed Service with a stable string-literal identity.
155
+ *
156
+ * The returned class is simultaneously the implementation type, the runtime
157
+ * dependency token, and the value yielded by `yield*` in an Effect generator.
158
+ * The explicit self type preserves exact instance inference, while the second
159
+ * call captures the tag as a literal for Layer composition and diagnostics.
160
+ *
161
+ * @example
162
+ * ```ts
163
+ * class Database extends Service<Database>()('Database') {
164
+ * query(): string {
165
+ * return 'ok'
166
+ * }
167
+ * }
168
+ *
169
+ * const database = yield* Database
170
+ * database.query()
171
+ * ```
172
+ *
173
+ * @typeParam Self The instance type implemented by the declared Service.
174
+ */
175
+ declare function Service<Self>(): ServiceFactory<Self>;
176
+ /** Type-level aliases for Service tokens and their instance contracts. */
177
+ declare namespace Service {
178
+ /** The widened Service instance constraint. */
179
+ type Any = AnyService;
180
+ /** A class-backed Service token with a stable tag and instance contract. */
181
+ type Token<Tag extends string = string, Instance extends AnyService = any> = ServiceToken<Tag, Instance>;
182
+ /** A constructible Service class with a stable tag and instance contract. */
183
+ type Class<Tag extends string = string, Instance extends AnyService = AnyService> = ServiceClass<Tag, Instance>;
184
+ /** Extract the instance represented by a Service token. */
185
+ type Instance<T extends AnyServiceToken> = ServiceInstance<T>;
186
+ /** Extract the stable tag represented by a Service instance. */
187
+ type Tag<S extends AnyService> = ServiceTag<S>;
188
+ /** A branded Service instance identity with a stable tag. */
189
+ type Identity<Tag extends string = string> = ServiceIdentity<Tag>;
190
+ /** Remove the internal identity marker from a Service implementation contract. */
191
+ type Contract<S extends AnyService> = ServiceContract<S>;
192
+ /** Extract the Service token represented by a branded Service instance. */
193
+ type TokenOf<S extends AnyService> = ServiceTokenOf<S>;
194
+ /** Declaration bridge for the recursive structural `Service.of` signature. */
195
+ type FactoryOf<Self, Tag extends string> = (this: void, implementation: ServiceContract<Self & ServiceIdentity<Tag>>) => Self;
196
+ /** Extract Effect Service requirements from a Service instance. */
197
+ type Requirements<S extends AnyService> = ServiceRequirements<S>;
198
+ }
199
+ //#endregion
200
+ //#region src/scope/errors.d.ts
201
+ /** Thrown when Scope context is accessed outside an active Scope execution. */
202
+ declare class ScopeRuntimeNotConfiguredError extends Error {
203
+ constructor();
204
+ }
205
+ /** Thrown when a resource or finalizer is added after Scope closure begins. */
206
+ declare class ScopeClosedError extends Error {
207
+ constructor();
208
+ }
209
+ /** Aggregates finalizer failures encountered while closing a Scope. */
210
+ declare class ScopeCloseError extends Error {
211
+ readonly causes: readonly unknown[];
212
+ constructor(causes: readonly unknown[]);
213
+ }
214
+ /** Thrown when a value has neither Symbol.dispose nor Symbol.asyncDispose. */
215
+ declare class ResourceNotDisposableError extends Error {
216
+ constructor();
217
+ }
218
+ //#endregion
219
+ //#region src/scope/types.d.ts
220
+ /** A value that may be returned synchronously or asynchronously. */
221
+ type MaybePromise$1<T> = T | PromiseLike<T>;
222
+ /** Final outcome supplied to Scope finalizers and resource releases. */
223
+ type ScopeOutcome = {
224
+ /** Indicates that the owning program completed successfully. */
225
+ readonly status: 'success';
226
+ } | {
227
+ /** Indicates that the owning program failed or was interrupted. */
228
+ readonly status: 'failure';
229
+ /** The original program or execution failure. */
230
+ readonly cause: unknown;
231
+ };
232
+ /** Cleanup callback registered with a Scope. */
233
+ type ScopeFinalizer = (outcome: ScopeOutcome) => MaybePromise$1<void>;
234
+ /** Aggregated cleanup information reported at an execution boundary. */
235
+ type CleanupFailureDiagnostic = {
236
+ /** Outcome used for the Scope close that triggered cleanup. */
237
+ readonly outcome: ScopeOutcome;
238
+ /** Aggregated finalizer failure. */
239
+ readonly error: ScopeCloseError;
240
+ };
241
+ type SyncDisposableResource = {
242
+ [Symbol.dispose]: () => void;
243
+ [Symbol.asyncDispose]?: () => MaybePromise$1<void>;
244
+ };
245
+ type AsyncDisposableResource = {
246
+ [Symbol.dispose]?: () => void;
247
+ [Symbol.asyncDispose]: () => MaybePromise$1<void>;
248
+ };
249
+ /** A value implementing at least one JavaScript disposal protocol. */
250
+ type DisposableResource = SyncDisposableResource | AsyncDisposableResource;
251
+ //#endregion
252
+ //#region src/scope/scope.d.ts
253
+ /**
254
+ * Non-owning lifecycle context for finalizers and child Scopes.
255
+ *
256
+ * A Scope can register cleanup and create children, but it cannot close
257
+ * itself. Use `Scope.make()` or `Scope.run()` when your code owns the Scope.
258
+ */
259
+ interface Scope {
260
+ /** Register a finalizer that runs when the owning Scope closes. */
261
+ addFinalizer(finalizer: ScopeFinalizer): void;
262
+ /** Acquire a resource and register its outcome-aware release callback. */
263
+ acquire<R>(acquire: () => MaybePromise$1<R>, release: (resource: R, outcome: ScopeOutcome) => MaybePromise$1<void>): Promise<R>;
264
+ /** Register an already-acquired disposable resource. */
265
+ add<R extends DisposableResource>(resource: R): Promise<R>;
266
+ /** Create a child Scope owned by this Scope. */
267
+ fork(): CloseableScope;
268
+ }
269
+ /** A Scope whose owner is responsible for calling `close()`. */
270
+ interface CloseableScope extends Scope {
271
+ /** Close the Scope and run children and finalizers in child-first LIFO order. */
272
+ close(outcome?: ScopeOutcome): Promise<void>;
273
+ }
274
+ declare const Scope: {
275
+ /** Create an owned, initially open Scope. */
276
+ readonly make: () => CloseableScope;
277
+ /** Return the non-owning Scope available in the current execution context. */
278
+ readonly current: () => Scope;
279
+ /** Run a callback with an existing Scope supplied as the current context. */
280
+ readonly provide: <A>(scope: Scope, program: () => A) => A;
281
+ /** Resolve the current Scope through `yield* Scope` inside an Effect. */
282
+ readonly [Symbol.iterator]: () => Generator<never, Scope, unknown>;
283
+ /**
284
+ * Run a program in a newly owned Scope.
285
+ *
286
+ * Scope is independent from `better-result`, so returned values—including
287
+ * `Result.err`—close this Scope with a successful outcome. Result-aware
288
+ * outcome classification belongs to `Runtime.run`.
289
+ *
290
+ * @example
291
+ * ```ts
292
+ * await Scope.run(async (scope) => {
293
+ * const connection = await scope.acquire(connect, (connection) => connection.close())
294
+ * return connection.query()
295
+ * })
296
+ * ```
297
+ */
298
+ readonly run: <A>(program: (scope: Scope) => A | PromiseLike<A>) => Promise<Awaited<A>>;
299
+ };
300
+ /** Type-level aliases for Scope ownership, outcomes, and cleanup contracts. */
301
+ declare namespace Scope {
302
+ /** A Scope whose owner is responsible for calling `close()`. */
303
+ type Closeable = CloseableScope;
304
+ /** The outcome supplied to Scope finalizers and resource releases. */
305
+ type Outcome = ScopeOutcome;
306
+ /** A cleanup callback registered with a Scope. */
307
+ type Finalizer = ScopeFinalizer;
308
+ /** A value implementing a JavaScript disposal protocol. */
309
+ type Disposable = DisposableResource;
310
+ }
311
+ //#endregion
312
+ //#region src/internal/missing-dependencies.d.ts
313
+ type MissingDependencies<Missing extends AnyService> = {
314
+ /** Names the Services that must be supplied before execution. */
315
+ readonly missingServices: Missing;
316
+ };
317
+ //#endregion
318
+ //#region src/layer/metadata.d.ts
319
+ /** Package-private declaration-only carrier for inferred Layer provenance. */
320
+ declare const LayerProvenanceTypeId: unique symbol;
321
+ interface ProviderEntry<out Provided extends AnyService, out RawRequired extends AnyService = never> {
322
+ readonly provided: Provided;
323
+ readonly required: RawRequired;
324
+ }
325
+ interface ErasedProvenance<out Provided extends AnyService, out StickyRequired extends AnyService> {
326
+ readonly provided: Provided;
327
+ readonly stickyRequired: StickyRequired;
328
+ }
329
+ interface LayerProvenance<out Entries extends ProviderEntry<AnyService, AnyService> = never, out Erased extends ErasedProvenance<AnyService, AnyService> = never> {
330
+ readonly [LayerProvenanceTypeId]: {
331
+ readonly entries: Entries;
332
+ readonly erased: Erased;
333
+ };
334
+ }
335
+ //#endregion
336
+ //#region src/layer/inference.d.ts
337
+ type IsAny<T> = 0 extends 1 & T ? true : false;
338
+ type IsNever<T> = [T] extends [never] ? true : false;
339
+ type IsUnion$1<T, Candidate = T> = T extends unknown ? [Candidate] extends [T] ? false : true : never;
340
+ /** Any Layer shape accepted by type-level inference helpers. */
341
+ type LayerInput = Layer<any, any> | Layer<never, any>;
342
+ /** Extract the public Service environment channels from a Layer. */
343
+ type ProvidedEnvironment<L extends LayerInput> = L extends Layer<infer Provided, infer _Required> ? Provided : never;
344
+ type RequiredEnvironment<L extends LayerInput> = L extends Layer<infer _Provided, infer Required> ? Required : never;
345
+ type HasWidenedTag<Services> = IsAny<Services> extends true ? false : Services extends AnyService ? string extends ServiceTagOf<Services> ? true : false : false;
346
+ type SameServiceTag<Left extends AnyService, Right extends AnyService> = [ServiceTagOf<Left>] extends [ServiceTagOf<Right>] ? [ServiceTagOf<Right>] extends [ServiceTagOf<Left>] ? true : false : false;
347
+ type SameServiceContract<Left extends AnyService, Right extends AnyService> = [ServiceContract<Left>] extends [ServiceContract<Right>] ? [ServiceContract<Right>] extends [ServiceContract<Left>] ? true : false : false;
348
+ type SameService<Left extends AnyService, Right extends AnyService> = SameServiceTag<Left, Right> extends true ? SameServiceContract<Left, Right> : false;
349
+ type RequirementProvided<Requirement extends AnyService, Provided extends AnyService> = Provided extends AnyService ? SameService<Requirement, Provided> : false;
350
+ type MissingRequirement<Requirement extends AnyService, Provided> = true extends RequirementProvided<Requirement, Extract<Provided, AnyService>> ? never : Requirement;
351
+ /**
352
+ * Existing Runtime matching semantics. Widened Service environments are an
353
+ * explicit execution erasure and therefore satisfy every concrete requirement.
354
+ */
355
+ type MissingServices<Required extends AnyService, Provided extends AnyService> = ServiceToken<string, Required> extends ServiceToken<string, Provided> ? never : IsAny<Required> extends true ? never : IsAny<Provided> extends true ? never : true extends HasWidenedTag<Required | Provided> ? never : Required extends AnyService ? MissingRequirement<Required, Provided> : never;
356
+ /** Layer matching that keeps widened Service.Any as an external requirement. */
357
+ type LayerExternalRequirements<RawRequired extends AnyService, Provided extends AnyService> = true extends HasWidenedTag<Extract<RawRequired | Provided, AnyService>> ? Extract<RawRequired, AnyService> : MissingServices<RawRequired, Provided>;
358
+ type AnyProviderEntry = ProviderEntry<AnyService, AnyService>;
359
+ type AnyErasedProvenance = ErasedProvenance<AnyService, AnyService>;
360
+ type EntryProvided<Entries> = Entries extends ProviderEntry<infer Provided, any> ? Provided : never;
361
+ type EntryRequired<Entries> = Entries extends ProviderEntry<any, infer Required> ? Required : never;
362
+ type ErasedProvided<Erased> = Erased extends ErasedProvenance<infer Provided, any> ? Provided : never;
363
+ type ErasedRequired<Erased> = Erased extends ErasedProvenance<any, infer Required> ? Required : never;
364
+ /** Extract precise provider entries carried by an inferred Layer. */
365
+ type PreciseEntries<L extends LayerInput> = L extends LayerProvenance<infer Entries, any> ? Entries : never;
366
+ /**
367
+ * Extract erased provenance, falling back to the public channels for an
368
+ * explicitly annotated Layer.
369
+ */
370
+ type ErasedEntries<L extends LayerInput> = L extends LayerProvenance<any, infer Erased> ? Erased : [ProvidedEnvironment<L> | RequiredEnvironment<L>] extends [never] ? never : ErasedProvenance<ProvidedEnvironment<L>, RequiredEnvironment<L>>;
371
+ type PossibleProvidedEnvironment<L extends LayerInput> = EntryProvided<PreciseEntries<L>> | ErasedProvided<ErasedEntries<L>>;
372
+ type LayerMetadata<Entries extends AnyProviderEntry, Erased extends AnyErasedProvenance> = [Entries | Erased] extends [never] ? unknown : LayerProvenance<Entries, Erased>;
373
+ /** Opaque internal result type used by Layer constructors and combinators. */
374
+ type LayerResult<Entries extends AnyProviderEntry, Erased extends AnyErasedProvenance = never, VisibleProvided extends AnyService = EntryProvided<Entries> | ErasedProvided<Erased>> = Layer<VisibleProvided, LayerExternalRequirements<EntryRequired<Entries> | ErasedRequired<Erased>, VisibleProvided>> & LayerMetadata<Entries, Erased>;
375
+ type LayerChannelPair<L> = L extends Layer<infer Provided, infer Required> ? [Provided, Required] : never;
376
+ type ExactUncheckedArm<L> = LayerChannelPair<L> extends [infer Provided extends AnyService, infer Required extends AnyService] ? IsAny<Provided> extends true ? IsAny<Required> extends true ? true : false : IsNever<Provided> extends true ? IsAny<Required> extends true ? true : false : false : false;
377
+ type HasUncheckedProvidedArm<L> = L extends unknown ? LayerChannelPair<L> extends [infer Provided, infer Required] ? IsAny<Provided> extends true ? IsAny<Required> extends true ? true : false : false : false : never;
378
+ type HasUncheckedEmptyArm<L> = L extends unknown ? LayerChannelPair<L> extends [infer Provided, infer Required] ? IsNever<Provided> extends true ? IsAny<Required> extends true ? true : false : false : false : never;
379
+ type HasNonUncheckedArm<L> = L extends unknown ? ExactUncheckedArm<L> extends true ? false : true : never;
380
+ /** Recognize only the documented exact unchecked Layer sentinels. */
381
+ type IsExactUncheckedLayer<L> = IsUnion$1<L> extends false ? ExactUncheckedArm<L> : true extends HasNonUncheckedArm<L> ? false : true extends HasUncheckedProvidedArm<L> ? true extends HasUncheckedEmptyArm<L> ? true : false : false;
382
+ type PartialAnyArm<L> = LayerChannelPair<L> extends [infer Provided extends AnyService, infer Required extends AnyService] ? IsAny<Provided> extends true ? IsAny<Required> extends true ? false : true : IsAny<Required> extends true ? IsNever<Provided> extends true ? false : true : false : false;
383
+ /** Detect any Layer constituent with only one erased generic channel. */
384
+ type HasPartialAnyChannel<L> = true extends (L extends unknown ? PartialAnyArm<L> : never) ? true : false;
385
+ /** Detect a concrete union of Layer values, preserving the original shape. */
386
+ type IsConcreteUnion<L> = IsAny<L> extends true ? false : IsUnion$1<L> extends true ? IsExactUncheckedLayer<L> extends true ? false : true : false;
387
+ type LayerInputState<L> = IsExactUncheckedLayer<L> extends true ? 'unchecked' : HasPartialAnyChannel<L> extends true ? 'invalid-partial-any' : IsConcreteUnion<L> extends true ? 'invalid-union' : 'typed';
388
+ type InvalidLayerErasure = {
389
+ readonly __betterEffectInvalidLayerErasure: unique symbol;
390
+ };
391
+ type AmbiguousLayerUnion = {
392
+ readonly __betterEffectAmbiguousLayerUnion: unique symbol;
393
+ };
394
+ /** Validate an original Layer argument without widening it to Layer.Any. */
395
+ type ValidateLayerInput<L extends LayerInput> = LayerInputState<L> extends 'invalid-partial-any' ? InvalidLayerErasure : LayerInputState<L> extends 'invalid-union' ? AmbiguousLayerUnion : unknown;
396
+ /** Validate every original element of a merge tuple. */
397
+ type ValidateLayerTuple<Layers extends readonly LayerInput[]> = { [Index in keyof Layers]: ValidateLayerInput<Layers[Index]>; };
398
+ type HasMatchingServiceTag<Left extends AnyService, Right extends AnyService> = [Extract<ServiceTagOf<Left>, ServiceTagOf<Right>>] extends [never] ? false : true;
399
+ /** Remove compatible Services from a union while retaining all other identities. */
400
+ type RemoveCompatibleServices<Provided extends AnyService, Replacements extends AnyService> = Provided extends AnyService ? HasMatchingServiceTag<Provided, Replacements> extends true ? true extends (Replacements extends AnyService ? SameService<Provided, Replacements> : false) ? never : Provided : Provided : never;
401
+ type HasCompatibleService<Provided extends AnyService, Replacements extends AnyService> = HasMatchingServiceTag<Provided, Replacements> extends true ? true extends (Replacements extends AnyService ? SameService<Provided, Replacements> : false) ? true : false : false;
402
+ type RemoveCompatibleEntries<Entries extends AnyProviderEntry, Replacements extends AnyService> = Entries extends ProviderEntry<infer Provided, any> ? HasCompatibleService<Provided, Replacements> extends true ? never : Entries : never;
403
+ type ReplacePreciseOne<Entries extends AnyProviderEntry, Replacement extends LayerInput> = RemoveCompatibleEntries<Entries, Extract<ProvidedEnvironment<Replacement>, AnyService>> | PreciseEntries<Replacement>;
404
+ type ReplaceErasedOne<Erased extends AnyErasedProvenance, Replacement extends LayerInput> = Erased extends ErasedProvenance<infer Provided, infer StickyRequired> ? ErasedProvenance<RemoveCompatibleServices<Provided, Extract<ProvidedEnvironment<Replacement>, AnyService>>, StickyRequired> : never;
405
+ type ApplyPreciseOverrides<Entries extends AnyProviderEntry, Overrides extends readonly LayerInput[]> = Overrides extends readonly [infer Head extends LayerInput, ...infer Tail extends readonly LayerInput[]] ? ApplyPreciseOverrides<ReplacePreciseOne<Entries, Head>, Tail> : Entries;
406
+ type ApplyErasedOverrides<Erased extends AnyErasedProvenance, Overrides extends readonly LayerInput[]> = Overrides extends readonly [infer Head extends LayerInput, ...infer Tail extends readonly LayerInput[]] ? ApplyErasedOverrides<ReplaceErasedOne<Erased, Head> | Extract<ErasedEntries<Head>, AnyErasedProvenance>, Tail> : Erased;
407
+ type HasMatchingService<Candidate extends AnyService, Available extends AnyService> = true extends (Available extends AnyService ? SameService<Candidate, Available> : never) ? true : false;
408
+ type GuaranteedServiceCandidates<Candidates extends AnyService, Branches extends LayerInput> = Candidates extends AnyService ? false extends (Branches extends LayerInput ? HasMatchingService<Candidates, Extract<ProvidedEnvironment<Branches>, AnyService>> : never) ? never : Candidates : never;
409
+ type GuaranteedProvided<Branch extends LayerInput, Branches extends LayerInput = Branch> = Branch extends LayerInput ? GuaranteedServiceCandidates<Extract<ProvidedEnvironment<Branch>, AnyService>, Branches> : never;
410
+ type HasUncheckedLayerInTuple<Layers extends readonly LayerInput[]> = true extends { [Index in keyof Layers]: IsExactUncheckedLayer<Layers[Index]>; }[number] ? true : false;
411
+ type MergeLayerResult<Layers extends readonly LayerInput[]> = HasUncheckedLayerInTuple<Layers> extends true ? Layer<any, any> : LayerResult<PreciseEntries<Layers[number]>, ErasedEntries<Layers[number]>>;
412
+ /** Internal result type for Layer.merge. */
413
+ type MergeResult<Layers extends readonly LayerInput[]> = MergeLayerResult<Layers>;
414
+ type ApplyVisibleOverrides<CurrentProvided extends AnyService, Overrides extends readonly LayerInput[]> = Overrides extends readonly [infer Head extends LayerInput, ...infer Tail extends readonly LayerInput[]] ? ApplyVisibleOverrides<RemoveCompatibleServices<CurrentProvided, Extract<ProvidedEnvironment<Head>, AnyService>> | Extract<ProvidedEnvironment<Head>, AnyService>, Tail> : CurrentProvided;
415
+ type OverrideLayerBranches<Base extends LayerInput, Overrides extends readonly LayerInput[]> = Overrides extends readonly LayerInput[] ? Layer<ApplyVisibleOverrides<Extract<ProvidedEnvironment<Base>, AnyService>, Overrides>, never> : never;
416
+ type OverrideLayerResultUnchecked<Base extends LayerInput, Overrides extends readonly LayerInput[]> = HasUncheckedLayerInTuple<[Base, ...Overrides]> extends true ? Layer<any, any> : LayerResult<ApplyPreciseOverrides<PreciseEntries<Base>, Overrides>, ApplyErasedOverrides<ErasedEntries<Base>, Overrides>, Extract<GuaranteedProvided<OverrideLayerBranches<Base, Overrides>>, AnyService>>;
417
+ /** Internal result type for an ordered override tuple. */
418
+ type OverrideLayerResult<Base extends LayerInput, Overrides extends readonly LayerInput[]> = OverrideLayerResultUnchecked<Base, Overrides>;
419
+ type IncompatibleOverridePair<Current extends AnyService, Replacement extends AnyService> = SameServiceTag<Current, Replacement> extends true ? SameServiceContract<Current, Replacement> extends true ? never : ServiceTokenOf<Replacement> : never;
420
+ /** Fully distributive same-tag incompatible override comparison. */
421
+ type IncompatibleOverridePairs<CurrentProvided extends AnyService, ReplacementProvided extends AnyService> = HasMatchingServiceTag<CurrentProvided, ReplacementProvided> extends true ? CurrentProvided extends AnyService ? ReplacementProvided extends AnyService ? IncompatibleOverridePair<CurrentProvided, ReplacementProvided> : never : never : never;
422
+ type IncompatibleLayerOverride<Tokens extends AnyServiceToken> = {
423
+ readonly __betterEffectIncompatibleLayerOverride: Tokens;
424
+ };
425
+ type InvalidWidenedProvidedEnvironment = {
426
+ readonly __betterEffectWidenedProvidedEnvironment: unique symbol;
427
+ };
428
+ type ValidateOverrideLayerInput<L extends LayerInput> = IsExactUncheckedLayer<L> extends true ? unknown : ValidateLayerInput<L> & (true extends HasWidenedTag<Extract<ProvidedEnvironment<L>, AnyService>> ? InvalidWidenedProvidedEnvironment : unknown);
429
+ type UnionToIntersection<Union> = (Union extends unknown ? (value: Union) => void : never) extends ((value: infer Intersection) => void) ? Intersection : never;
430
+ type ValidationFailuresToConstraint<Failures> = [Failures] extends [never] ? unknown : UnionToIntersection<Failures>;
431
+ type ValidateOverrideTuple<Overrides extends readonly LayerInput[]> = { [Index in keyof Overrides]: ValidateOverrideLayerInput<Overrides[Index]>; };
432
+ type ValidateOverrideTupleFailures<Overrides extends readonly LayerInput[]> = ValidationFailuresToConstraint<Overrides extends readonly LayerInput[] ? ValidationFailureWitness<{ [Index in keyof Overrides]: ValidateOverrideLayerInput<Overrides[Index]>; }> : never>;
433
+ type ServiceAtTag<Services, Tag extends string> = Tag extends keyof Services ? Extract<Services[Tag], AnyService> : never;
434
+ type ServiceTagMap<Services extends AnyService> = { [Tag in ServiceTagOf<Services>]: Extract<Services, {
435
+ readonly [ServiceIdentityTypeId]: Tag;
436
+ }>; };
437
+ type ExactMapOverrideMatch<Current, Replacement extends AnyService> = [MapServicesAtTag<Current, ServiceTagOf<Replacement>>] extends [never] ? true : [MapServicesAtTag<Current, ServiceTagOf<Replacement>>] extends [Replacement] ? [Replacement] extends [MapServicesAtTag<Current, ServiceTagOf<Replacement>>] ? true : false : false;
438
+ type CanSkipBaseOverride<Current, Replacement extends AnyService> = false extends (Replacement extends AnyService ? [MapServicesAtTag<Current, ServiceTagOf<Replacement>>] extends [never] ? false : ExactMapOverrideMatch<Current, Replacement> : never) ? false : true;
439
+ type MapServicesAtTag<Maps, Tag extends string> = Maps extends unknown ? ServiceAtTag<Maps, Tag> : never;
440
+ type IncompatibleOverridePairsForValidation<CurrentProvided extends AnyService, Replacement extends AnyService> = CurrentProvided extends AnyService ? Replacement extends AnyService ? IncompatibleOverridePair<CurrentProvided, Replacement> : never : never;
441
+ type ApplyValidationOverride<CurrentProvided extends AnyService, ReplacementProvided extends AnyService> = RemoveCompatibleServices<CurrentProvided, ReplacementProvided> | ReplacementProvided;
442
+ type ValidateOverridePair<CurrentProvided extends AnyService, ReplacementProvided extends AnyService> = IncompatibleOverridePairsForValidation<CurrentProvided, ReplacementProvided> extends (infer Incompatible) ? [Incompatible] extends [never] ? unknown : IncompatibleLayerOverride<Extract<Incompatible, AnyServiceToken>> : never;
443
+ /**
444
+ * Validate overrides while carrying only the current provided union.
445
+ * Rebuilding the full Layer provenance for every step is quadratic and can
446
+ * exhaust TypeScript's instantiation depth on otherwise simple override lists.
447
+ */
448
+ type ValidateOverridesFromStateForArm<Overrides extends readonly LayerInput[], BaseMap, CurrentProvided extends AnyService, CurrentChanged extends boolean, CurrentUnchecked extends boolean> = Overrides extends readonly [infer Head extends LayerInput, ...infer Tail extends readonly LayerInput[]] ? CurrentUnchecked extends true ? ValidateOverridesFromStateForArm<Tail, BaseMap, AnyService, true, true> : IsExactUncheckedLayer<Head> extends true ? ValidateOverridesFromStateForArm<Tail, BaseMap, AnyService, true, true> : CurrentChanged extends false ? CanSkipBaseOverride<BaseMap, Extract<ProvidedEnvironment<Head>, AnyService>> extends true ? ValidateOverridesFromStateForArm<Tail, BaseMap, CurrentProvided, false, false> : ValidateOverridePair<CurrentProvided, Extract<ProvidedEnvironment<Head>, AnyService>> & ValidateOverridesFromStateForArm<Tail, BaseMap, ApplyValidationOverride<CurrentProvided, Extract<ProvidedEnvironment<Head>, AnyService>>, true, false> : ValidateOverridePair<CurrentProvided, Extract<ProvidedEnvironment<Head>, AnyService>> & ValidateOverridesFromStateForArm<Tail, BaseMap, ApplyValidationOverride<CurrentProvided, Extract<ProvidedEnvironment<Head>, AnyService>>, true, false> : unknown;
449
+ /** Validate every possible override tuple arm instead of accepting one valid arm. */
450
+ type ValidateOverridesFromState<Overrides extends readonly LayerInput[], BaseMap, CurrentProvided extends AnyService, CurrentChanged extends boolean, CurrentUnchecked extends boolean> = ValidationFailuresToConstraint<Overrides extends readonly LayerInput[] ? ValidationFailureWitness<ValidateOverridesFromStateForArm<Overrides, BaseMap, CurrentProvided, CurrentChanged, CurrentUnchecked>> : never>;
451
+ /** Validate one override against the currently accumulated Layer state. */
452
+ type ValidateOneOverride<Current extends LayerInput, Replacement extends LayerInput> = ValidateOverrideLayerInput<Current> & ValidateOverrideLayerInput<Replacement> & (IsExactUncheckedLayer<Current> extends true ? unknown : IsExactUncheckedLayer<Replacement> extends true ? unknown : [IncompatibleOverridePairs<Extract<PossibleProvidedEnvironment<Current>, AnyService>, Extract<PossibleProvidedEnvironment<Replacement>, AnyService>>] extends [never] ? unknown : IncompatibleLayerOverride<IncompatibleOverridePairs<Extract<PossibleProvidedEnvironment<Current>, AnyService>, Extract<PossibleProvidedEnvironment<Replacement>, AnyService>>>);
453
+ type IsTuple<Values extends readonly unknown[]> = number extends Values['length'] ? false : true;
454
+ type InvalidWidenedOverrideList = {
455
+ readonly __betterEffectWidenedOverrideList: unique symbol;
456
+ };
457
+ /** Validate ordered overrides against the state produced by earlier overrides. */
458
+ type ValidateOverrides<Base extends LayerInput, Overrides extends readonly LayerInput[]> = [Overrides] extends [never] ? unknown : IsTuple<Overrides> extends false ? IsExactUncheckedLayer<Base> extends true ? unknown : InvalidWidenedOverrideList : ValidateOverrideLayerInput<Base> & ValidateOverrideTuple<Overrides> & ValidationFailuresToConstraint<Overrides extends readonly LayerInput[] ? [Overrides] extends [readonly []] ? never : ValidationFailureWitness<ValidateOverrideTuple<Overrides> & ValidateOverrideTupleFailures<Overrides> & ValidateOverridesFromState<Overrides, ServiceTagMap<Extract<PossibleProvidedEnvironment<Base>, AnyService>>, Extract<PossibleProvidedEnvironment<Base>, AnyService>, false, IsExactUncheckedLayer<Base>>> : never>;
459
+ type ValidationFailureWitness<Value> = Value extends {
460
+ readonly __betterEffectIncompatibleLayerOverride: infer Tokens;
461
+ } ? {
462
+ readonly __betterEffectIncompatibleLayerOverride: Tokens;
463
+ } : Value extends {
464
+ readonly __betterEffectInvalidLayerErasure: unique symbol;
465
+ } ? Value : Value extends {
466
+ readonly __betterEffectAmbiguousLayerUnion: unique symbol;
467
+ } ? Value : Value extends {
468
+ readonly __betterEffectWidenedProvidedEnvironment: unique symbol;
469
+ } ? Value : Value extends {
470
+ readonly __betterEffectWidenedOverrideList: unique symbol;
471
+ } ? Value : Value extends readonly (infer Element)[] ? ValidationFailureWitness<Element> : never;
472
+ /** Reduce Layer override validation to a usable call-site diagnostic witness. */
473
+ type ValidateOverridesWitness<Base extends LayerInput, Overrides extends readonly LayerInput[]> = ValidationFailureWitness<ValidateOverrides<Base, Overrides>> extends (infer Failure) ? [Failure] extends [never] ? unknown : Failure : never;
474
+ /** A Layer accepted by Runtime boundaries after completeness validation. */
475
+ type CompleteInput<L extends LayerInput> = ValidateLayerInput<L> & (LayerInputState<L> extends 'unchecked' ? L : LayerInputState<L> extends 'typed' ? [RequiredEnvironment<L>] extends [never] ? L : L & MissingDependencies<Extract<RequiredEnvironment<L>, AnyService>> : L);
476
+ type ExecutionRequirementsMissing<RootProvided extends AnyService, Request extends LayerInput> = MissingServices<Extract<RequiredEnvironment<Request>, AnyService>, Extract<RootProvided, AnyService>>;
477
+ /** Validate a per-execution Layer against the Runtime root environment. */
478
+ type CompleteExecutionLayer<RootProvided extends AnyService, Request extends LayerInput> = ValidateLayerInput<Request> & (LayerInputState<Request> extends 'unchecked' ? Request : LayerInputState<Request> extends 'typed' ? [ExecutionRequirementsMissing<RootProvided, Request>] extends [never] ? Request : Request & MissingDependencies<ExecutionRequirementsMissing<RootProvided, Request>> : Request);
479
+ /** Services required by an execution result that are not in its environment. */
480
+ type ExecutionMissing<Provided extends AnyService, ProgramResult> = MissingServices<EffectRequirements<ProgramResult>, Provided>;
481
+ type ExecutionProgram<A> = () => A | PromiseLike<A>;
482
+ type CompleteExecutionWithRequirements<Provided extends AnyService, A, Required extends AnyService> = [MissingServices<Required, Provided>] extends [never] ? ExecutionProgram<A> : ExecutionProgram<A> & MissingDependencies<MissingServices<Required, Provided>>;
483
+ /** Keep execution callbacks unchanged when their Effect requirements are met. */
484
+ type CompleteExecution<Provided extends AnyService, A> = CompleteExecutionWithRequirements<Provided, A, EffectRequirements<A>>;
485
+ //#endregion
486
+ //#region src/layer/errors.d.ts
487
+ type LayerCause = Extract<ScopeOutcome, {
488
+ readonly status: 'failure';
489
+ }>['cause'];
490
+ /** Thrown when a Layer registers the same Service tag more than once. */
491
+ declare class DuplicateServiceError extends Error {
492
+ readonly service: AnyServiceToken;
493
+ constructor(service: AnyServiceToken);
494
+ }
495
+ /** Thrown when one Service tag is associated with incompatible constructors. */
496
+ declare class ServiceTagCollisionError extends Error {
497
+ readonly existing: AnyServiceToken;
498
+ readonly incoming: AnyServiceToken;
499
+ constructor(existing: AnyServiceToken, incoming: AnyServiceToken);
500
+ }
501
+ /** Thrown when a backend fails while registering a Layer provider. */
502
+ declare class LayerRegistrationError extends Error {
503
+ readonly service: AnyServiceToken | undefined;
504
+ readonly registrationCause: LayerCause;
505
+ readonly cleanupCause?: LayerCause;
506
+ constructor(service: AnyServiceToken | undefined, registrationCause: LayerCause, cleanupCause?: LayerCause);
507
+ }
508
+ /** Thrown when one or more Layer-owned resources fail during disposal. */
509
+ declare class LayerDisposeError extends Error {
510
+ readonly causes: readonly unknown[];
511
+ constructor(causes: readonly unknown[]);
512
+ }
513
+ /** Thrown when a Layer generator yields a value other than a Service requirement. */
514
+ declare class LayerGeneratorYieldError extends Error {
515
+ readonly service: AnyServiceToken;
516
+ constructor(service: AnyServiceToken);
517
+ }
518
+ //#endregion
519
+ //#region src/utils/types.d.ts
520
+ type MaybePromise<T> = T | PromiseLike<T>;
521
+ //#endregion
522
+ //#region src/layer/types.d.ts
523
+ /** Callback that stops a resource from admitting new work. */
524
+ type LayerQuiesce<Instance = unknown> = (instance: Instance, reason: RuntimeShutdownReason) => MaybePromise<void>;
525
+ /** Lifecycle callbacks for a resource owned by a Runtime root Scope. */
526
+ type LayerLifecycle<Instance> = {
527
+ readonly quiesce?: LayerQuiesce<Instance>;
528
+ readonly release: (instance: Instance, outcome: ScopeOutcome) => MaybePromise<void>;
529
+ };
530
+ /** Runtime-facing provider registration supplied by a Layer backend. */
531
+ interface LayerRegistration {
532
+ /** The class-backed Service token provided by this registration. */
533
+ readonly service: ServiceToken<any, any>;
534
+ /**
535
+ * The canonical tag captured when the provider was created.
536
+ *
537
+ * This remains optional for direct backend registrations created against the
538
+ * pre-inspection API; backends capture the token tag synchronously when it is
539
+ * omitted.
540
+ */
541
+ readonly serviceTag?: string;
542
+ /** Lazily acquire the Service instance; concrete types are erased at this backend boundary. */
543
+ readonly acquire: () => MaybePromise<unknown>;
544
+ /** Optional Runtime-root quiesce hook retained by Layer-created registrations. */
545
+ readonly quiesce?: LayerQuiesce;
546
+ }
547
+ /** Generator shape used by `Layer.gen` and `Layer.scopedGen`. */
548
+ type LayerGenerator<S extends ServiceToken<any, any>, Yield extends ServiceRequirement<unknown> = ServiceRequirement<unknown>> = () => Generator<Yield, ServiceContract<InstanceType<S>>, unknown> | AsyncGenerator<Yield, ServiceContract<InstanceType<S>>, unknown>;
549
+ /** Service requirements inferred from a provider's methods and generator. */
550
+ type LayerGeneratorRequirements<S extends ServiceToken<any, any>, Yield extends ServiceRequirement<unknown>> = ServiceRequirements<InstanceType<S>> | InferYieldRequirements<Yield>;
551
+ /** Generator shape used by lifecycle-only Layer entries. */
552
+ type LayerDiscardGenerator<Yield extends ServiceRequirement<unknown>, Acquired> = () => Generator<Yield, Acquired, unknown> | AsyncGenerator<Yield, Acquired, unknown>;
553
+ /** Service requirements inferred from a lifecycle-only generator. */
554
+ type LayerDiscardRequirements<Yield extends ServiceRequirement<unknown>> = InferYieldRequirements<Yield>;
555
+ //#endregion
556
+ //#region src/layer/backend.d.ts
557
+ /** Observation hook invoked for acquisitions that disposal will await. */
558
+ type LayerBackendDisposeOptions = {
559
+ /**
560
+ * Receives the in-flight acquisition Promises when disposal begins. The callback
561
+ * is invoked synchronously and awaited before the backend clears its state.
562
+ */
563
+ readonly onPendingAcquisitions?: (acquisitions: readonly Promise<unknown>[]) => void | PromiseLike<void>;
564
+ };
565
+ /** Runtime adapter responsible for registering, resolving, and disposing Layer providers. */
566
+ interface LayerBackend extends ServiceResolver {
567
+ /** Register one Service provider with the backend. */
568
+ register(registration: LayerRegistration): MaybePromise<void>;
569
+ /** Dispose all backend-owned instances and provider registrations. */
570
+ disposeAll(options?: LayerBackendDisposeOptions): MaybePromise<void>;
571
+ }
572
+ //#endregion
573
+ //#region src/effect/task.d.ts
574
+ type AnyProgram$1 = Program<any, any, AnyService>;
575
+ /** The live state of a Scope-owned task. */
576
+ type ScopedTaskState = 'running' | 'succeeded' | 'failed' | 'defected' | 'interrupted';
577
+ /** The terminal observation of a Scope-owned task. */
578
+ type ScopedTaskExit<A, E> = {
579
+ readonly status: 'succeeded';
580
+ readonly value: A;
581
+ readonly cleanupFailure?: ScopeCloseError;
582
+ } | {
583
+ readonly status: 'failed';
584
+ readonly error: E;
585
+ readonly cleanupFailure?: ScopeCloseError;
586
+ } | {
587
+ readonly status: 'defected';
588
+ readonly cause: unknown;
589
+ readonly cleanupFailure?: ScopeCloseError;
590
+ } | {
591
+ readonly status: 'interrupted';
592
+ readonly reason: unknown;
593
+ readonly cleanupFailure?: ScopeCloseError;
594
+ };
595
+ /** A small, immutable handle for a task owned by the current Scope. */
596
+ type ScopedTask<out A, out E> = {
597
+ readonly state: ScopedTaskState;
598
+ await(): Promise<Result<A, E>>;
599
+ awaitExit(): Promise<ScopedTaskExit<A, E>>;
600
+ interrupt(reason?: unknown): Promise<void>;
601
+ };
602
+ /** Start a nominal Program as a child task supervised by the current Scope. */
603
+ declare function forkScoped<Input extends AnyProgram$1>(program: Input): Effect<ScopedTask<EffectSuccess<Input>, EffectError<Input>>, never, EffectRequirements<Input>>;
604
+ //#endregion
605
+ //#region src/runtime/observer.d.ts
606
+ /** Observable Runtime shutdown phase. */
607
+ type RuntimeShutdownPhase = 'shutdown-requested' | 'quiesce-start' | 'quiesce-end' | 'drain-start' | 'drain-end' | 'abort-active' | 'release-start' | 'release-end' | 'shutdown-complete' | 'shutdown-failure';
608
+ /** Detached metadata for one Runtime shutdown phase. */
609
+ type RuntimeShutdownEvent = {
610
+ readonly phase: RuntimeShutdownPhase;
611
+ readonly reason: RuntimeShutdownReason;
612
+ readonly activeExecutions?: number;
613
+ readonly durationMs?: number;
614
+ readonly error?: unknown;
615
+ };
616
+ /** Event emitted after a Service resolution attempt settles. */
617
+ type RuntimeServiceResolveEvent = {
618
+ readonly service: AnyServiceToken;
619
+ readonly resolutionPath: readonly AnyServiceToken[];
620
+ readonly outcome: ScopeOutcome;
621
+ /** Runtime execution owner, omitted for warmup and other root activity. */
622
+ readonly executionId?: string;
623
+ };
624
+ /** Event emitted after a provider acquisition attempt settles. */
625
+ type RuntimeServiceAcquireEvent = {
626
+ readonly service: AnyServiceToken;
627
+ readonly resolutionPath: readonly AnyServiceToken[];
628
+ readonly outcome: ScopeOutcome;
629
+ /** Runtime execution owner, omitted for warmup and other root activity. */
630
+ readonly executionId?: string;
631
+ };
632
+ /** Values supplied to one Runtime execution for diagnostic correlation. */
633
+ type RuntimeExecutionAttributes = Readonly<Record<string, unknown>>;
634
+ /** Metadata shared by the start and end events for one execution. */
635
+ type RuntimeExecutionMetadata = {
636
+ readonly executionId: string;
637
+ readonly name?: string;
638
+ readonly attributes?: RuntimeExecutionAttributes;
639
+ /** Monotonic host timestamp captured immediately before the Program starts. */
640
+ readonly startedAt: number;
641
+ };
642
+ /** Event emitted immediately before a program starts in an execution Scope. */
643
+ type RuntimeExecutionStartEvent = RuntimeExecutionMetadata & {
644
+ readonly scope: Scope;
645
+ };
646
+ /** Event emitted after a program and its execution Scope settle. */
647
+ type RuntimeExecutionEndEvent = RuntimeExecutionMetadata & {
648
+ readonly scope: Scope;
649
+ /** The program outcome used to run execution-scope cleanup. */
650
+ readonly outcome: ScopeOutcome;
651
+ /** Execution-scope cleanup failure, without changing the primary program outcome. */
652
+ readonly cleanupFailure?: ScopeCloseError;
653
+ /** Monotonic elapsed time for the Program and its execution cleanup. */
654
+ readonly durationMs: number;
655
+ };
656
+ /** Metadata shared by the start and end events for one Scope-owned task. */
657
+ type RuntimeTaskMetadata = {
658
+ readonly taskId: string;
659
+ /** The execution that created the task, omitted for root lifecycle tasks. */
660
+ readonly parentExecutionId?: string;
661
+ readonly name?: string;
662
+ readonly startedAt: number;
663
+ };
664
+ /** Event emitted immediately before a Scope-owned task starts. */
665
+ type RuntimeTaskStartEvent = RuntimeTaskMetadata & {
666
+ readonly state: 'running';
667
+ };
668
+ /** Event emitted after a Scope-owned task settles and its child Scope closes. */
669
+ type RuntimeTaskEndEvent = RuntimeTaskMetadata & {
670
+ readonly state: Exclude<ScopedTaskState, 'running'>;
671
+ /** Child Scope cleanup failure, without changing the task's primary state. */
672
+ readonly cleanupFailure?: ScopeCloseError;
673
+ };
674
+ /** Event emitted after a Layer provider release callback settles. */
675
+ type RuntimeResourceReleaseEvent = {
676
+ readonly service: AnyServiceToken;
677
+ readonly outcome: ScopeOutcome;
678
+ readonly error?: unknown;
679
+ /** Runtime execution owner, omitted for Runtime-root cleanup. */
680
+ readonly executionId?: string;
681
+ };
682
+ /** Metadata shared by lifecycle-only Layer events. */
683
+ type RuntimeLifecycleEventMetadata = {
684
+ readonly kind: 'lifecycle';
685
+ /** Stable identity for one lifecycle entry; no acquired resource is retained. */
686
+ readonly lifecycleId: symbol;
687
+ readonly name?: string;
688
+ };
689
+ /** Event emitted immediately before a lifecycle-only entry is acquired. */
690
+ type RuntimeLifecycleStartEvent = RuntimeLifecycleEventMetadata;
691
+ /** Event emitted after a lifecycle-only entry's acquisition settles. */
692
+ type RuntimeLifecycleEndEvent = RuntimeLifecycleEventMetadata & {
693
+ readonly outcome: ScopeOutcome;
694
+ readonly error?: unknown;
695
+ };
696
+ /** Event emitted after a lifecycle-only entry's release callback settles. */
697
+ type RuntimeLifecycleReleaseEvent = RuntimeLifecycleEventMetadata & {
698
+ readonly outcome: ScopeOutcome;
699
+ readonly error?: unknown;
700
+ };
701
+ /** Optional best-effort hooks for Runtime lifecycle and resolution events. */
702
+ type RuntimeObserver = {
703
+ readonly onServiceResolve?: (event: RuntimeServiceResolveEvent) => MaybePromise<void>;
704
+ readonly onServiceAcquire?: (event: RuntimeServiceAcquireEvent) => MaybePromise<void>;
705
+ readonly onExecutionStart?: (event: RuntimeExecutionStartEvent) => MaybePromise<void>;
706
+ readonly onExecutionEnd?: (event: RuntimeExecutionEndEvent) => MaybePromise<void>;
707
+ readonly onTaskStart?: (event: RuntimeTaskStartEvent) => MaybePromise<void>;
708
+ readonly onTaskEnd?: (event: RuntimeTaskEndEvent) => MaybePromise<void>;
709
+ readonly onResourceRelease?: (event: RuntimeResourceReleaseEvent) => MaybePromise<void>;
710
+ readonly onLifecycleStart?: (event: RuntimeLifecycleStartEvent) => MaybePromise<void>;
711
+ readonly onLifecycleEnd?: (event: RuntimeLifecycleEndEvent) => MaybePromise<void>;
712
+ readonly onLifecycleRelease?: (event: RuntimeLifecycleReleaseEvent) => MaybePromise<void>;
713
+ readonly onShutdown?: (event: RuntimeShutdownEvent) => MaybePromise<void>;
714
+ };
715
+ /** Compose best-effort Runtime observers into one observer. */
716
+ declare const RuntimeObserver: {
717
+ compose: (...observers: readonly RuntimeObserver[]) => RuntimeObserver;
718
+ };
719
+ //#endregion
720
+ //#region src/runtime/outcome.d.ts
721
+ /** Metadata explaining why a Runtime shutdown was requested. */
722
+ type RuntimeShutdownReason = {
723
+ readonly kind: 'dispose' | 'signal' | 'external-abort' | 'main-settled';
724
+ readonly signal?: 'SIGINT' | 'SIGTERM';
725
+ readonly cause?: unknown;
726
+ };
727
+ /** Aggregated cleanup information reported during Runtime shutdown. */
728
+ type RuntimeShutdownDiagnostic = {
729
+ /** Final outcome supplied to the Runtime root Scope. */
730
+ readonly outcome: ScopeOutcome;
731
+ /** Aggregated root-Scope and backend cleanup failure. */
732
+ readonly error: LayerDisposeError;
733
+ };
734
+ /** Observer notified about cleanup failures without changing primary results. */
735
+ type CleanupFailureObserver = (diagnostic: CleanupFailureDiagnostic | RuntimeShutdownDiagnostic) => MaybePromise$1<void>;
736
+ /** Optional Runtime configuration for cleanup diagnostics. */
737
+ type RuntimeOptions = {
738
+ /** Backend used to register and resolve the Layer. Defaults to MapLayerBackend. */
739
+ readonly backend?: LayerBackend;
740
+ /** Resolve every Layer provider before Runtime.make resolves. */
741
+ readonly warmup?: boolean;
742
+ /** Best-effort lifecycle and Service resolution observers. */
743
+ readonly observers?: readonly RuntimeObserver[];
744
+ /** Optional observer for best-effort cleanup diagnostics. */
745
+ readonly onCleanupFailure?: CleanupFailureObserver;
746
+ /** Context storage used by Service, Scope and Layer resolution. */
747
+ readonly contextStorage?: RuntimeContextStorage;
748
+ /** Optional signal exposed through the RuntimeContext. */
749
+ readonly signal?: AbortSignal;
750
+ };
751
+ /** Optional signal and diagnostic attributes supplied to one Runtime execution. */
752
+ type RuntimeRunOptions = {
753
+ readonly signal?: AbortSignal;
754
+ /** Copied once and exposed as a readonly event view. */
755
+ readonly attributes?: RuntimeExecutionAttributes;
756
+ };
757
+ /** Cooperative shutdown policy for a managed Runtime. */
758
+ type RuntimeDisposeOptions = {
759
+ /** Time to let active executions settle before requesting cancellation. */
760
+ readonly gracePeriod?: number;
761
+ /** Abort active execution signals after the grace period expires. */
762
+ readonly abortAfterGracePeriod?: boolean;
763
+ /** Boundary metadata supplied to Layer quiesce callbacks. */
764
+ readonly reason?: RuntimeShutdownReason;
765
+ };
766
+ //#endregion
767
+ //#region src/runtime/executor.d.ts
768
+ /** The value published by one managed execution before its work completes. */
769
+ type RuntimeManagedPlan<A> = {
770
+ readonly readiness: A | PromiseLike<A>;
771
+ readonly completion: PromiseLike<void>;
772
+ readonly cancel?: (reason?: unknown) => PromiseLike<void>;
773
+ };
774
+ /** A non-owning handle for an execution whose readiness is separate from completion. */
775
+ type RuntimeManagedExecution<A> = {
776
+ readonly readiness: Promise<Awaited<A>>;
777
+ readonly completion: Promise<void>;
778
+ readonly signal: AbortSignal;
779
+ readonly run: <B>(program: () => B | PromiseLike<B>) => Promise<Awaited<B>>;
780
+ readonly cancel: (reason?: unknown) => Promise<void>;
781
+ };
782
+ /**
783
+ * A non-owning view of a Runtime that can start isolated executions.
784
+ *
785
+ * The view deliberately contains only execution operations. Runtime disposal,
786
+ * warmup, inspection, backend access and Scope ownership stay on `Runtime`.
787
+ */
788
+ interface RuntimeExecutor<in out Provided extends AnyService = any> {
789
+ readonly run: <A>(program: CompleteExecution<Provided, A>, options?: RuntimeRunOptions) => Promise<Awaited<A>>;
790
+ readonly runWith: <Request extends LayerInput, A>(layer: Request & CompleteExecutionLayer<Provided, Request>, program: CompleteExecution<Provided | ProvidedEnvironment<Request>, A>, options?: RuntimeRunOptions) => Promise<Awaited<A>>;
791
+ readonly runWithManaged: <Request extends LayerInput, A>(layer: Request & CompleteExecutionLayer<Provided, Request>, program: CompleteExecution<Provided | ProvidedEnvironment<Request>, RuntimeManagedPlan<A>>, options?: RuntimeRunOptions) => RuntimeManagedExecution<A>;
792
+ }
793
+ /** Yieldable request for the executor active in the current Runtime context. */
794
+ interface RuntimeExecutorRequest<Provided extends AnyService> {
795
+ [Symbol.iterator](): Generator<ServiceRequirement<Provided>, RuntimeExecutor<Provided>, unknown>;
796
+ [Symbol.asyncIterator](): AsyncGenerator<ServiceRequirement<Provided>, RuntimeExecutor<Provided>, unknown>;
797
+ }
798
+ //#endregion
799
+ //#region src/runtime/context.d.ts
800
+ /** Contextual state shared by Service, Scope and Layer resolution. */
801
+ interface RuntimeContext {
802
+ readonly resolver?: ServiceResolver;
803
+ readonly scope?: Scope;
804
+ readonly signal?: AbortSignal;
805
+ /** Non-owning executor view for the Runtime root of this context. */
806
+ readonly executor?: RuntimeExecutor<AnyService>;
807
+ readonly resolutionPath: readonly AnyServiceToken[];
808
+ /** Runtime execution owner, omitted for warmup and Runtime-root activity. */
809
+ readonly executionId?: string;
810
+ }
811
+ /** Host-specific storage for the current RuntimeContext. */
812
+ interface RuntimeContextStorage {
813
+ run<A>(context: RuntimeContext, program: () => A): A;
814
+ current(): RuntimeContext;
815
+ }
816
+ //#endregion
817
+ //#region src/service/runtime.d.ts
818
+ /** Resolves class-backed Service tokens for a runtime execution. */
819
+ interface ServiceResolver {
820
+ /** Resolve a token to its corresponding Service instance. */
821
+ resolve<T extends AnyServiceToken>(token: T): InstanceType<T> | PromiseLike<InstanceType<T>>;
822
+ }
823
+ /** Provides the resolver context used by Service tokens during execution. */
824
+ declare class ServiceRuntime {
825
+ /**
826
+ * Run a callback with a resolver available to `yield* Service` expressions.
827
+ *
828
+ * The context is scoped to the callback and is restored afterward.
829
+ *
830
+ * @example
831
+ * ```ts
832
+ * const value = ServiceRuntime.run(resolver, () => {
833
+ * return ServiceRuntime.resolve(Database)
834
+ * })
835
+ * ```
836
+ */
837
+ static run<A>(resolver: ServiceResolver, program: () => A, storage?: RuntimeContextStorage): A;
838
+ /** Return the resolver active in the current execution context. */
839
+ static current(): ServiceResolver;
840
+ /** Resolve a Service token using the active resolver. */
841
+ static resolve<T extends AnyServiceToken>(token: T): Promise<InstanceType<T>>;
842
+ }
843
+ //#endregion
844
+ //#region src/service/errors.d.ts
845
+ /** Thrown when a Service is accessed without an active runtime resolver. */
846
+ declare class ServiceRuntimeNotConfiguredError extends Error {
847
+ constructor();
848
+ }
849
+ /** Thrown when a runtime has no provider for the requested Service tag. */
850
+ declare class ServiceNotFoundError extends Error {
851
+ readonly service: AnyServiceToken;
852
+ constructor(service: AnyServiceToken);
853
+ }
854
+ /** Thrown when resolving a Service re-enters a Service already in its path. */
855
+ declare class CircularDependencyError extends Error {
856
+ readonly path: readonly AnyServiceToken[];
857
+ constructor(path: readonly AnyServiceToken[]);
858
+ }
859
+ /** Thrown when a registered Service provider fails during lazy acquisition. */
860
+ declare class ServiceAcquisitionError extends Error {
861
+ readonly service: AnyServiceToken;
862
+ readonly cause: unknown;
863
+ constructor(service: AnyServiceToken, resolutionPath: readonly AnyServiceToken[], cause: unknown);
864
+ readonly resolutionPath: readonly AnyServiceToken[];
865
+ }
866
+ //#endregion
867
+ //#region src/internal/variance.d.ts
868
+ /** Type-level marker for a value produced by `A`. */
869
+ type Covariant<A> = () => A;
870
+ /** Type-level marker that both consumes and produces `A`. */
871
+ type Invariant<A> = (value: A) => A;
872
+ //#endregion
873
+ //#region src/layer/layer.d.ts
874
+ declare const LayerTypeId: unique symbol;
875
+ interface LayerVariance<in out Provided, out Required> {
876
+ readonly _Provided: Invariant<Provided>;
877
+ readonly _Required: Covariant<Required>;
878
+ }
879
+ type CapturedLayerAcquisition = {
880
+ readonly instance: unknown;
881
+ readonly release: ScopeFinalizer;
882
+ };
883
+ interface LayerProvider extends LayerRegistration {
884
+ /** The tag captured before this provider can cross an asynchronous boundary. */
885
+ readonly serviceTag: string;
886
+ /** Provider storage deliberately erases the concrete instance type. */
887
+ readonly release?: (instance: unknown, outcome: ScopeOutcome) => MaybePromise<void>;
888
+ readonly quiesce?: LayerQuiesce;
889
+ /** Capture acquisition-local cleanup without retaining the acquired instance. */
890
+ readonly acquireWithRelease?: () => MaybePromise<CapturedLayerAcquisition>;
891
+ }
892
+ type AnyProgram = Program<any, any, AnyService>;
893
+ type EffectDiscardValidation<P extends AnyProgram> = [EffectSuccess<P>] extends [void] ? [EffectError<P>] extends [never] ? unknown : {
894
+ readonly __betterEffectDiscardTypedFailure: unique symbol;
895
+ } : {
896
+ readonly __betterEffectDiscardSuccessMustBeVoid: unique symbol;
897
+ };
898
+ /** A Service class whose constructor can be called without arguments. */
899
+ type DefaultConstructibleServiceClass<Tag extends string = string, Instance extends AnyService = AnyService> = ServiceClass<Tag, Instance> & (new () => Instance);
900
+ type IsUnion<Type, Candidate = Type> = Type extends unknown ? [Candidate] extends [Type] ? false : true : never;
901
+ type InvalidUnionAliasToken = {
902
+ readonly __betterEffectUnionLayerAliasToken: unique symbol;
903
+ };
904
+ type RejectUnionAliasToken<Token> = IsUnion<Token> extends true ? InvalidUnionAliasToken : unknown;
905
+ type LayerAliasOptions<From extends ServiceToken<any, any>, To extends ServiceToken<any, any>> = {
906
+ readonly from: From;
907
+ readonly to: To;
908
+ } & RejectUnionAliasToken<From> & RejectUnionAliasToken<To> & ([ServiceContract<InstanceType<From>>] extends [ServiceContract<InstanceType<To>>] ? unknown : {
909
+ readonly __betterEffectIncompatibleLayerAlias: unique symbol;
910
+ });
911
+ /**
912
+ * Declarative collection of Service providers.
913
+ *
914
+ * A Layer describes how to acquire implementations; it does not execute
915
+ * providers until a `Runtime` is created. Use `merge` to compose distinct
916
+ * providers and `override` when replacing an existing provider intentionally.
917
+ *
918
+ * @example
919
+ * ```ts
920
+ * const AppLive = Layer.merge(
921
+ * Layer.succeed(Database, database),
922
+ * Layer.make(UserRepository)
923
+ * )
924
+ *
925
+ * const runtime = await Runtime.make(AppLive, backend)
926
+ * ```
927
+ */
928
+ declare class Layer<in out Provided extends AnyService = AnyService, out Required extends AnyService = AnyService> {
929
+ readonly [LayerTypeId]: LayerVariance<Provided, Required>;
930
+ /** The Service provider registrations retained by this Layer. */
931
+ readonly providers: readonly LayerProvider[];
932
+ private constructor();
933
+ private static makeLifecycleLayer;
934
+ /** A stable provider-free Layer for composition roots with no Services. */
935
+ static readonly empty: Layer<never, never>;
936
+ /** Create a Layer that lazily acquires a Service instance. */
937
+ static make<S extends DefaultConstructibleServiceClass<any, any>>(service: S): LayerResult<ProviderEntry<InstanceType<S>, ServiceRequirements<InstanceType<S>>>>;
938
+ static make<S extends ServiceToken<any, any>>(service: S, acquire: () => MaybePromise<ServiceContract<InstanceType<S>>>): LayerResult<ProviderEntry<InstanceType<S>, ServiceRequirements<InstanceType<S>>>>;
939
+ /** Create a Layer from an already-constructed Service instance. */
940
+ static succeed<S extends ServiceToken<any, any>>(service: S, instance: ServiceContract<InstanceType<S>>): LayerResult<ProviderEntry<InstanceType<S>, ServiceRequirements<InstanceType<S>>>>;
941
+ /** Alias a source Service under a compatible target contract. */
942
+ static alias<From extends ServiceToken<any, any>, To extends ServiceToken<any, any>>(options: LayerAliasOptions<From, To>): LayerResult<ProviderEntry<InstanceType<To>, InstanceType<From> | ServiceRequirements<InstanceType<To>>>>;
943
+ /** Define a provider with Runtime-root cleanup. */
944
+ static scoped<S extends ServiceToken<any, any>>(service: S, acquire: () => MaybePromise<ServiceContract<InstanceType<S>>>, release: (instance: InstanceType<S>, outcome: ScopeOutcome) => MaybePromise<void>): LayerResult<ProviderEntry<InstanceType<S>, ServiceRequirements<InstanceType<S>>>>;
945
+ static scoped<S extends ServiceToken<any, any>>(service: S, acquire: () => MaybePromise<ServiceContract<InstanceType<S>>>, lifecycle: LayerLifecycle<InstanceType<S>>): LayerResult<ProviderEntry<InstanceType<S>, ServiceRequirements<InstanceType<S>>>>;
946
+ /** Define a provider with Runtime-root cleanup through its disposal protocol. */
947
+ static scopedDisposable<S extends ServiceToken<any, any>>(service: S, acquire: () => MaybePromise<ServiceContract<InstanceType<S>> & DisposableResource>): LayerResult<ProviderEntry<InstanceType<S>, ServiceRequirements<InstanceType<S>>>>;
948
+ /** Define a provider whose acquisition can yield contextual Services. */
949
+ static scopedGen<S extends ServiceToken<any, any>, Yield extends ServiceRequirement<unknown>>(service: S, factory: LayerGenerator<S, Yield>, release: (instance: InstanceType<S>, outcome: ScopeOutcome) => MaybePromise<void>): LayerResult<ProviderEntry<InstanceType<S>, LayerGeneratorRequirements<S, Yield>>>;
950
+ static scopedGen<S extends ServiceToken<any, any>, Yield extends ServiceRequirement<unknown>>(service: S, factory: LayerGenerator<S, Yield>, lifecycle: LayerLifecycle<InstanceType<S>>): LayerResult<ProviderEntry<InstanceType<S>, LayerGeneratorRequirements<S, Yield>>>;
951
+ /** Define a provider whose acquisition can yield contextual Services. */
952
+ static gen<S extends ServiceToken<any, any>, Yield extends ServiceRequirement<unknown>>(service: S, factory: LayerGenerator<S, Yield>): LayerResult<ProviderEntry<InstanceType<S>, LayerGeneratorRequirements<S, Yield>>>;
953
+ /** Define a lifecycle-only entry with direct acquisition and root cleanup. */
954
+ static scopedDiscard<Yield extends ServiceRequirement<unknown>, Acquired>(acquire: LayerDiscardGenerator<Yield, Acquired>, release: (instance: Acquired, outcome: ScopeOutcome) => MaybePromise<void>): LayerResult<ProviderEntry<never, LayerDiscardRequirements<Yield>>>;
955
+ static scopedDiscard<Yield extends ServiceRequirement<unknown>, Acquired>(acquire: LayerDiscardGenerator<Yield, Acquired>, lifecycle: LayerLifecycle<Acquired>): LayerResult<ProviderEntry<never, LayerDiscardRequirements<Yield>>>;
956
+ static scopedDiscard<Acquired>(acquire: () => MaybePromise<Acquired>, release: (instance: Acquired, outcome: ScopeOutcome) => MaybePromise<void>): LayerResult<ProviderEntry<never, never>>;
957
+ static scopedDiscard<Acquired>(acquire: () => MaybePromise<Acquired>, lifecycle: LayerLifecycle<Acquired>): LayerResult<ProviderEntry<never, never>>;
958
+ /** Define a lifecycle-only entry whose acquisition can yield contextual Services. */
959
+ static scopedDiscardGen<Yield extends ServiceRequirement<unknown>, Acquired>(acquire: LayerDiscardGenerator<Yield, Acquired>, release: (instance: Acquired, outcome: ScopeOutcome) => MaybePromise<void>): LayerResult<ProviderEntry<never, LayerDiscardRequirements<Yield>>>;
960
+ static scopedDiscardGen<Yield extends ServiceRequirement<unknown>, Acquired>(acquire: LayerDiscardGenerator<Yield, Acquired>, lifecycle: LayerLifecycle<Acquired>): LayerResult<ProviderEntry<never, LayerDiscardRequirements<Yield>>>;
961
+ /** Run a no-failure Effect Program as a lifecycle-only entry. */
962
+ static effectDiscard<P extends AnyProgram>(program: P & EffectDiscardValidation<P>): LayerResult<ProviderEntry<never, Extract<EffectRequirements<P>, AnyService>>>;
963
+ /** Compose Layers without replacing providers. */
964
+ static merge<const Layers extends readonly LayerInput[]>(...layers: Layers & ValidateLayerTuple<Layers>): MergeResult<Layers>;
965
+ /** Mark a Layer composition root as complete without changing its runtime value. */
966
+ static complete<L extends LayerInput>(layer: L & CompleteInput<L>): L;
967
+ /** Replace providers in a base Layer, using tag identity and compatible contracts. */
968
+ static override<Base extends LayerInput>(base: Base & ValidateLayerInput<Base>): OverrideLayerResult<Base, readonly []>;
969
+ static override<Base extends LayerInput, const Overrides extends readonly [LayerInput, ...LayerInput[]]>(base: Base & ValidateLayerInput<Base>, ...overrides: Overrides & ValidateOverrides<Base, Overrides>): OverrideLayerResult<Base, Overrides>;
970
+ static override<Base extends LayerInput, const Overrides extends readonly LayerInput[]>(base: Base & ValidateLayerInput<Base>, ...overrides: Overrides & ValidateOverrides<Base, Overrides>): OverrideLayerResult<Base, Overrides>;
971
+ }
972
+ /** Type-level aliases for inspecting Layer environments and completeness. */
973
+ declare namespace Layer {
974
+ /** The widened Layer shape accepted by generic Layer infrastructure. */
975
+ type Any = LayerInput;
976
+ /** Extract the branded Service instances provided by a Layer. */
977
+ type Provided<L extends LayerInput> = ProvidedEnvironment<L>;
978
+ /** Extract the external Service requirements of a Layer. */
979
+ type Required<L extends LayerInput> = RequiredEnvironment<L>;
980
+ /** Extract the Services still missing from a Layer composition. */
981
+ type Missing<L extends LayerInput> = RequiredEnvironment<L>;
982
+ /** Validate a Layer's requirements and input shape. */
983
+ type Complete<L extends LayerInput> = CompleteInput<L>;
984
+ }
985
+ //#endregion
986
+ export { CompleteInput as $, RuntimeServiceAcquireEvent as A, EffectRequirements as At, forkScoped as B, ServiceContract as Bt, RuntimeExecutionStartEvent as C, ScopeClosedError as Ct, RuntimeLifecycleStartEvent as D, Effect as Dt, RuntimeLifecycleReleaseEvent as E, AnyEffect as Et, RuntimeTaskMetadata as F, ProgramFromGenerator as Ft, LayerRegistration as G, ServiceTagOf as Gt, LayerBackendDisposeOptions as H, ServiceInstance as Ht, RuntimeTaskStartEvent as I, ServiceRequirement as It, LayerGeneratorYieldError as J, DuplicateServiceError as K, ServiceToken as Kt, ScopedTask as L, AnyService as Lt, RuntimeShutdownEvent as M, EffectYield as Mt, RuntimeShutdownPhase as N, InferYieldRequirements as Nt, RuntimeObserver as O, EffectError as Ot, RuntimeTaskEndEvent as P, Program as Pt, CompleteExecutionLayer as Q, ScopedTaskExit as R, AnyServiceToken as Rt, RuntimeExecutionMetadata as S, ScopeCloseError as St, RuntimeLifecycleEventMetadata as T, Service as Tt, LayerLifecycle as U, ServiceRequirements as Ut, LayerBackend as V, ServiceIdentity as Vt, LayerQuiesce as W, ServiceTag as Wt, ServiceTagCollisionError as X, LayerRegistrationError as Y, CompleteExecution as Z, RuntimeRunOptions as _, DisposableResource as _t, ServiceRuntimeNotConfiguredError as a, OverrideLayerResult as at, RuntimeExecutionAttributes as b, ScopeOutcome as bt, RuntimeContext as c, ValidateLayerInput as ct, RuntimeExecutorRequest as d, ValidateOverridesWitness as dt, ExecutionMissing as et, RuntimeManagedExecution as f, ProviderEntry as ft, RuntimeOptions as g, CleanupFailureDiagnostic as gt, RuntimeDisposeOptions as h, Scope as ht, ServiceNotFoundError as i, MissingServices as it, RuntimeServiceResolveEvent as j, EffectSuccess as jt, RuntimeResourceReleaseEvent as k, EffectFromGenerator as kt, RuntimeContextStorage as l, ValidateOneOverride as lt, CleanupFailureObserver as m, CloseableScope as mt, CircularDependencyError as n, LayerInputState as nt, ServiceResolver as o, ProvidedEnvironment as ot, RuntimeManagedPlan as p, MissingDependencies as pt, LayerDisposeError as q, ServiceTokenOf as qt, ServiceAcquisitionError as r, LayerResult as rt, ServiceRuntime as s, RequiredEnvironment as st, Layer as t, LayerInput as tt, RuntimeExecutor as u, ValidateOverrides as ut, RuntimeShutdownDiagnostic as v, MaybePromise$1 as vt, RuntimeLifecycleEndEvent as w, ScopeRuntimeNotConfiguredError as wt, RuntimeExecutionEndEvent as x, ResourceNotDisposableError as xt, RuntimeShutdownReason as y, ScopeFinalizer as yt, ScopedTaskState as z, ServiceClass as zt };
987
+ //# sourceMappingURL=layer-C2OaqTmB.d.mts.map