peffect 0.1.2__py3-none-any.whl

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.
peffect/layer.py ADDED
@@ -0,0 +1,789 @@
1
+ """Layer: a recipe that builds a Context, shared across one build by identity.
2
+
3
+ Users = Layer.effect(UsersTag, acquire_release(open_repo, close_repo))
4
+ App = Users.pipe(Layer.provide(Db)).pipe(Layer.merge(Log))
5
+ yield from provide_layer(App)(program) # build, run program, release
6
+
7
+ A ``Layer[ROut, E, RIn]`` builds services for the tags in ROut, may fail with E and needs RIn.
8
+ Building one always goes through a MemoMap: requesting a layer the map already holds reuses its
9
+ Context, and every requester's scope keeps the shared resources alive until the last one
10
+ closes. Scope in an effect's R is the layer's own lifetime, so the constructors remove it.
11
+
12
+ Effect v4: Layer.ts:240-420 (MemoMap, fromBuild, fromBuildMemo), :600-781 (CurrentMemoMap, build),
13
+ mergeAll, provide, and internal/layer.ts:8-22 (Effect.provide with a layer). Not ported:
14
+ Layer.fresh, suspend, recovery and tracing; ``merge_all`` is typed for 1 to 4 layers.
15
+ """
16
+
17
+ from __future__ import annotations
18
+
19
+ from collections.abc import Callable, Mapping
20
+ from functools import reduce
21
+ from types import MappingProxyType
22
+ from typing import Any, Final, Never, Protocol, final, overload
23
+
24
+ from .context import Context, Tag, provide
25
+ from .core import ContextMap, Effect, Exit, Failure, WithFiber, succeed, suspend
26
+ from .deferred import Deferred
27
+ from .fiber import for_each
28
+ from .scope import Closeable, Scope, ScopeService
29
+
30
+ type _F[X, Y] = Callable[[X], Y]
31
+ type _Build[ROut, E, RIn] = Callable[[MemoMap, ScopeService], Effect[Context[ROut], E, RIn]]
32
+
33
+ VOID: Effect[None, Never, Never] = succeed(None)
34
+
35
+
36
+ @final
37
+ class _Token:
38
+ __slots__ = ()
39
+
40
+
41
+ _TOKEN = _Token()
42
+
43
+
44
+ class _TagClass[S, T](Protocol):
45
+ """A tag class such as ``Users``: ``Users.context(service)`` is a ``Context[Users]``."""
46
+
47
+ def context(self, service: S, /) -> Context[T]: ...
48
+
49
+
50
+ @final
51
+ class Layer[ROut, E = Never, RIn = Never]:
52
+ """Built only by the constructors below; the builder cannot be replaced after."""
53
+
54
+ __slots__ = ("_builder",)
55
+
56
+ def __init__(self, builder: _Build[ROut, E, RIn], token: _Token) -> None:
57
+ if token is not _TOKEN:
58
+ raise TypeError("build a Layer with Layer.effect, Layer.succeed, ..., not Layer(...)")
59
+ self._builder: Final = builder
60
+
61
+ # pipe(f1, ..., fn): 0-20 steps, left to right, like Effect.pipe (Layer is Pipeable,
62
+ # Pipeable.ts:46-526); nest a second pipe for more.
63
+ @overload
64
+ def pipe(self, /) -> Layer[ROut, E, RIn]: ...
65
+ @overload
66
+ def pipe[T1](self, f1: _F[Layer[ROut, E, RIn], T1], /) -> T1: ...
67
+ @overload
68
+ def pipe[T1, T2](self, f1: _F[Layer[ROut, E, RIn], T1], f2: _F[T1, T2], /) -> T2: ...
69
+ @overload
70
+ def pipe[T1, T2, T3](
71
+ self,
72
+ f1: _F[Layer[ROut, E, RIn], T1],
73
+ f2: _F[T1, T2],
74
+ f3: _F[T2, T3],
75
+ /,
76
+ ) -> T3: ...
77
+ @overload
78
+ def pipe[T1, T2, T3, T4](
79
+ self,
80
+ f1: _F[Layer[ROut, E, RIn], T1],
81
+ f2: _F[T1, T2],
82
+ f3: _F[T2, T3],
83
+ f4: _F[T3, T4],
84
+ /,
85
+ ) -> T4: ...
86
+ @overload
87
+ def pipe[T1, T2, T3, T4, T5](
88
+ self,
89
+ f1: _F[Layer[ROut, E, RIn], T1],
90
+ f2: _F[T1, T2],
91
+ f3: _F[T2, T3],
92
+ f4: _F[T3, T4],
93
+ f5: _F[T4, T5],
94
+ /,
95
+ ) -> T5: ...
96
+ @overload
97
+ def pipe[T1, T2, T3, T4, T5, T6](
98
+ self,
99
+ f1: _F[Layer[ROut, E, RIn], T1],
100
+ f2: _F[T1, T2],
101
+ f3: _F[T2, T3],
102
+ f4: _F[T3, T4],
103
+ f5: _F[T4, T5],
104
+ f6: _F[T5, T6],
105
+ /,
106
+ ) -> T6: ...
107
+ @overload
108
+ def pipe[T1, T2, T3, T4, T5, T6, T7](
109
+ self,
110
+ f1: _F[Layer[ROut, E, RIn], T1],
111
+ f2: _F[T1, T2],
112
+ f3: _F[T2, T3],
113
+ f4: _F[T3, T4],
114
+ f5: _F[T4, T5],
115
+ f6: _F[T5, T6],
116
+ f7: _F[T6, T7],
117
+ /,
118
+ ) -> T7: ...
119
+ @overload
120
+ def pipe[T1, T2, T3, T4, T5, T6, T7, T8](
121
+ self,
122
+ f1: _F[Layer[ROut, E, RIn], T1],
123
+ f2: _F[T1, T2],
124
+ f3: _F[T2, T3],
125
+ f4: _F[T3, T4],
126
+ f5: _F[T4, T5],
127
+ f6: _F[T5, T6],
128
+ f7: _F[T6, T7],
129
+ f8: _F[T7, T8],
130
+ /,
131
+ ) -> T8: ...
132
+ @overload
133
+ def pipe[T1, T2, T3, T4, T5, T6, T7, T8, T9](
134
+ self,
135
+ f1: _F[Layer[ROut, E, RIn], T1],
136
+ f2: _F[T1, T2],
137
+ f3: _F[T2, T3],
138
+ f4: _F[T3, T4],
139
+ f5: _F[T4, T5],
140
+ f6: _F[T5, T6],
141
+ f7: _F[T6, T7],
142
+ f8: _F[T7, T8],
143
+ f9: _F[T8, T9],
144
+ /,
145
+ ) -> T9: ...
146
+ @overload
147
+ def pipe[T1, T2, T3, T4, T5, T6, T7, T8, T9, T10](
148
+ self,
149
+ f1: _F[Layer[ROut, E, RIn], T1],
150
+ f2: _F[T1, T2],
151
+ f3: _F[T2, T3],
152
+ f4: _F[T3, T4],
153
+ f5: _F[T4, T5],
154
+ f6: _F[T5, T6],
155
+ f7: _F[T6, T7],
156
+ f8: _F[T7, T8],
157
+ f9: _F[T8, T9],
158
+ f10: _F[T9, T10],
159
+ /,
160
+ ) -> T10: ...
161
+ @overload
162
+ def pipe[T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11](
163
+ self,
164
+ f1: _F[Layer[ROut, E, RIn], T1],
165
+ f2: _F[T1, T2],
166
+ f3: _F[T2, T3],
167
+ f4: _F[T3, T4],
168
+ f5: _F[T4, T5],
169
+ f6: _F[T5, T6],
170
+ f7: _F[T6, T7],
171
+ f8: _F[T7, T8],
172
+ f9: _F[T8, T9],
173
+ f10: _F[T9, T10],
174
+ f11: _F[T10, T11],
175
+ /,
176
+ ) -> T11: ...
177
+ @overload
178
+ def pipe[T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12](
179
+ self,
180
+ f1: _F[Layer[ROut, E, RIn], T1],
181
+ f2: _F[T1, T2],
182
+ f3: _F[T2, T3],
183
+ f4: _F[T3, T4],
184
+ f5: _F[T4, T5],
185
+ f6: _F[T5, T6],
186
+ f7: _F[T6, T7],
187
+ f8: _F[T7, T8],
188
+ f9: _F[T8, T9],
189
+ f10: _F[T9, T10],
190
+ f11: _F[T10, T11],
191
+ f12: _F[T11, T12],
192
+ /,
193
+ ) -> T12: ...
194
+ @overload
195
+ def pipe[T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13](
196
+ self,
197
+ f1: _F[Layer[ROut, E, RIn], T1],
198
+ f2: _F[T1, T2],
199
+ f3: _F[T2, T3],
200
+ f4: _F[T3, T4],
201
+ f5: _F[T4, T5],
202
+ f6: _F[T5, T6],
203
+ f7: _F[T6, T7],
204
+ f8: _F[T7, T8],
205
+ f9: _F[T8, T9],
206
+ f10: _F[T9, T10],
207
+ f11: _F[T10, T11],
208
+ f12: _F[T11, T12],
209
+ f13: _F[T12, T13],
210
+ /,
211
+ ) -> T13: ...
212
+ @overload
213
+ def pipe[T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14](
214
+ self,
215
+ f1: _F[Layer[ROut, E, RIn], T1],
216
+ f2: _F[T1, T2],
217
+ f3: _F[T2, T3],
218
+ f4: _F[T3, T4],
219
+ f5: _F[T4, T5],
220
+ f6: _F[T5, T6],
221
+ f7: _F[T6, T7],
222
+ f8: _F[T7, T8],
223
+ f9: _F[T8, T9],
224
+ f10: _F[T9, T10],
225
+ f11: _F[T10, T11],
226
+ f12: _F[T11, T12],
227
+ f13: _F[T12, T13],
228
+ f14: _F[T13, T14],
229
+ /,
230
+ ) -> T14: ...
231
+ @overload
232
+ def pipe[T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, T15](
233
+ self,
234
+ f1: _F[Layer[ROut, E, RIn], T1],
235
+ f2: _F[T1, T2],
236
+ f3: _F[T2, T3],
237
+ f4: _F[T3, T4],
238
+ f5: _F[T4, T5],
239
+ f6: _F[T5, T6],
240
+ f7: _F[T6, T7],
241
+ f8: _F[T7, T8],
242
+ f9: _F[T8, T9],
243
+ f10: _F[T9, T10],
244
+ f11: _F[T10, T11],
245
+ f12: _F[T11, T12],
246
+ f13: _F[T12, T13],
247
+ f14: _F[T13, T14],
248
+ f15: _F[T14, T15],
249
+ /,
250
+ ) -> T15: ...
251
+ @overload
252
+ def pipe[T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, T15, T16](
253
+ self,
254
+ f1: _F[Layer[ROut, E, RIn], T1],
255
+ f2: _F[T1, T2],
256
+ f3: _F[T2, T3],
257
+ f4: _F[T3, T4],
258
+ f5: _F[T4, T5],
259
+ f6: _F[T5, T6],
260
+ f7: _F[T6, T7],
261
+ f8: _F[T7, T8],
262
+ f9: _F[T8, T9],
263
+ f10: _F[T9, T10],
264
+ f11: _F[T10, T11],
265
+ f12: _F[T11, T12],
266
+ f13: _F[T12, T13],
267
+ f14: _F[T13, T14],
268
+ f15: _F[T14, T15],
269
+ f16: _F[T15, T16],
270
+ /,
271
+ ) -> T16: ...
272
+ @overload
273
+ def pipe[T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, T15, T16, T17](
274
+ self,
275
+ f1: _F[Layer[ROut, E, RIn], T1],
276
+ f2: _F[T1, T2],
277
+ f3: _F[T2, T3],
278
+ f4: _F[T3, T4],
279
+ f5: _F[T4, T5],
280
+ f6: _F[T5, T6],
281
+ f7: _F[T6, T7],
282
+ f8: _F[T7, T8],
283
+ f9: _F[T8, T9],
284
+ f10: _F[T9, T10],
285
+ f11: _F[T10, T11],
286
+ f12: _F[T11, T12],
287
+ f13: _F[T12, T13],
288
+ f14: _F[T13, T14],
289
+ f15: _F[T14, T15],
290
+ f16: _F[T15, T16],
291
+ f17: _F[T16, T17],
292
+ /,
293
+ ) -> T17: ...
294
+ @overload
295
+ def pipe[T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, T15, T16, T17, T18](
296
+ self,
297
+ f1: _F[Layer[ROut, E, RIn], T1],
298
+ f2: _F[T1, T2],
299
+ f3: _F[T2, T3],
300
+ f4: _F[T3, T4],
301
+ f5: _F[T4, T5],
302
+ f6: _F[T5, T6],
303
+ f7: _F[T6, T7],
304
+ f8: _F[T7, T8],
305
+ f9: _F[T8, T9],
306
+ f10: _F[T9, T10],
307
+ f11: _F[T10, T11],
308
+ f12: _F[T11, T12],
309
+ f13: _F[T12, T13],
310
+ f14: _F[T13, T14],
311
+ f15: _F[T14, T15],
312
+ f16: _F[T15, T16],
313
+ f17: _F[T16, T17],
314
+ f18: _F[T17, T18],
315
+ /,
316
+ ) -> T18: ...
317
+ @overload
318
+ def pipe[T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, T15, T16, T17, T18, T19](
319
+ self,
320
+ f1: _F[Layer[ROut, E, RIn], T1],
321
+ f2: _F[T1, T2],
322
+ f3: _F[T2, T3],
323
+ f4: _F[T3, T4],
324
+ f5: _F[T4, T5],
325
+ f6: _F[T5, T6],
326
+ f7: _F[T6, T7],
327
+ f8: _F[T7, T8],
328
+ f9: _F[T8, T9],
329
+ f10: _F[T9, T10],
330
+ f11: _F[T10, T11],
331
+ f12: _F[T11, T12],
332
+ f13: _F[T12, T13],
333
+ f14: _F[T13, T14],
334
+ f15: _F[T14, T15],
335
+ f16: _F[T15, T16],
336
+ f17: _F[T16, T17],
337
+ f18: _F[T17, T18],
338
+ f19: _F[T18, T19],
339
+ /,
340
+ ) -> T19: ...
341
+ @overload
342
+ def pipe[
343
+ T1,
344
+ T2,
345
+ T3,
346
+ T4,
347
+ T5,
348
+ T6,
349
+ T7,
350
+ T8,
351
+ T9,
352
+ T10,
353
+ T11,
354
+ T12,
355
+ T13,
356
+ T14,
357
+ T15,
358
+ T16,
359
+ T17,
360
+ T18,
361
+ T19,
362
+ T20,
363
+ ](
364
+ self,
365
+ f1: _F[Layer[ROut, E, RIn], T1],
366
+ f2: _F[T1, T2],
367
+ f3: _F[T2, T3],
368
+ f4: _F[T3, T4],
369
+ f5: _F[T4, T5],
370
+ f6: _F[T5, T6],
371
+ f7: _F[T6, T7],
372
+ f8: _F[T7, T8],
373
+ f9: _F[T8, T9],
374
+ f10: _F[T9, T10],
375
+ f11: _F[T10, T11],
376
+ f12: _F[T11, T12],
377
+ f13: _F[T12, T13],
378
+ f14: _F[T13, T14],
379
+ f15: _F[T14, T15],
380
+ f16: _F[T15, T16],
381
+ f17: _F[T16, T17],
382
+ f18: _F[T17, T18],
383
+ f19: _F[T18, T19],
384
+ f20: _F[T19, T20],
385
+ /,
386
+ ) -> T20: ...
387
+ def pipe(self, /, *fs: _F[Any, Any]) -> Any:
388
+ """Apply each function to the previous result, eagerly (pipeArguments, Pipeable.ts:567)."""
389
+ out: Any = self
390
+ for f in fs:
391
+ out = f(out)
392
+ return out
393
+
394
+ # -- constructors (Layer.ts:360-372, :1031-1180) -------------------------------------------
395
+
396
+ @staticmethod
397
+ def from_build[O, E2, R](build: _Build[O, E2, R]) -> Layer[O, E2, R]:
398
+ """Not memoized. The build gets a scope forked from the caller's, closed if it fails."""
399
+
400
+ def run(memo_map: MemoMap, scope: ScopeService) -> Effect[Context[O], E2, R]:
401
+ layer_scope = Scope.fork_unsafe(scope)
402
+
403
+ def close_on_failure(exit_: Exit[Context[O], E2]) -> Effect[None, Never, Never]:
404
+ return Scope.close(layer_scope, exit_) if isinstance(exit_, Failure) else VOID
405
+
406
+ return build(memo_map, layer_scope).on_exit(close_on_failure)
407
+
408
+ return Layer(run, _TOKEN)
409
+
410
+ @staticmethod
411
+ def _from_build_memo[O, E2, R](build: _Build[O, E2, R]) -> Layer[O, E2, R]:
412
+ """fromBuildMemo: the layer itself is the memo key."""
413
+
414
+ def memoized(memo_map: MemoMap, scope: ScopeService) -> Effect[Context[O], E2, R]:
415
+ return memo_map.get_or_else_memoize(layer, scope, build)
416
+
417
+ layer = Layer.from_build(memoized)
418
+ return layer
419
+
420
+ @staticmethod
421
+ def succeed[S, T](tag: _TagClass[S, T], service: S) -> Layer[T]:
422
+ """Not memoized; the Context is made once, here."""
423
+ ctx = tag.context(service)
424
+ return Layer(lambda _m, _s: succeed(ctx), _TOKEN)
425
+
426
+ @overload
427
+ @staticmethod
428
+ def effect_context[T, E2](eff: Effect[Context[T], E2, Scope]) -> Layer[T, E2]: ...
429
+ @overload
430
+ @staticmethod
431
+ def effect_context[T, E2, R](
432
+ eff: Effect[Context[T], E2, Scope | R],
433
+ ) -> Layer[T, E2, R]: ...
434
+ @staticmethod
435
+ def effect_context(eff: Effect[Context[Any], Any, Any]) -> Layer[Any, Any, Any]:
436
+ return Layer._from_build_memo(lambda _m, scope: Scope.provide(scope)(eff))
437
+
438
+ @overload
439
+ @staticmethod
440
+ def effect[S, T, E2](tag: _TagClass[S, T], eff: Effect[S, E2, Scope]) -> Layer[T, E2]: ...
441
+ @overload
442
+ @staticmethod
443
+ def effect[S, T, E2, R](
444
+ tag: _TagClass[S, T], eff: Effect[S, E2, Scope | R]
445
+ ) -> Layer[T, E2, R]: ...
446
+ @staticmethod
447
+ def effect(tag: _TagClass[Any, Any], eff: Effect[Any, Any, Any]) -> Layer[Any, Any, Any]:
448
+ return Layer.effect_context(eff.map(tag.context))
449
+
450
+ @overload
451
+ @staticmethod
452
+ def effect_discard[E2](eff: Effect[object, E2, Scope]) -> Layer[Never, E2]: ...
453
+ @overload
454
+ @staticmethod
455
+ def effect_discard[E2, R](eff: Effect[object, E2, Scope | R]) -> Layer[Never, E2, R]: ...
456
+ @staticmethod
457
+ def effect_discard(eff: Effect[object, Any, Any]) -> Layer[Any, Any, Any]:
458
+ return Layer.effect_context(eff.as_(Context.empty()))
459
+
460
+ # -- composition (Layer.ts mergeAll, merge, provide, provideWith) ----------------------------
461
+
462
+ # Pyright loses an all-Never union across free type parameters (resources.py:70): for
463
+ # each arity, overloads for all-Never E and R channels come before the general one.
464
+ @overload
465
+ @staticmethod
466
+ def merge_all[O1, E1, R1](a: Layer[O1, E1, R1], /) -> Layer[O1, E1, R1]: ...
467
+ @overload
468
+ @staticmethod
469
+ def merge_all[O1, O2](
470
+ a: Layer[O1, Never, Never], b: Layer[O2, Never, Never], /
471
+ ) -> Layer[O1 | O2, Never, Never]: ...
472
+ @overload
473
+ @staticmethod
474
+ def merge_all[O1, O2, R1, R2](
475
+ a: Layer[O1, Never, R1], b: Layer[O2, Never, R2], /
476
+ ) -> Layer[O1 | O2, Never, R1 | R2]: ...
477
+ @overload
478
+ @staticmethod
479
+ def merge_all[O1, O2, E1, E2](
480
+ a: Layer[O1, E1, Never], b: Layer[O2, E2, Never], /
481
+ ) -> Layer[O1 | O2, E1 | E2, Never]: ...
482
+ @overload
483
+ @staticmethod
484
+ def merge_all[O1, O2, E1, E2, R1, R2](
485
+ a: Layer[O1, E1, R1], b: Layer[O2, E2, R2], /
486
+ ) -> Layer[O1 | O2, E1 | E2, R1 | R2]: ...
487
+ @overload
488
+ @staticmethod
489
+ def merge_all[O1, O2, O3](
490
+ a: Layer[O1, Never, Never], b: Layer[O2, Never, Never], c: Layer[O3, Never, Never], /
491
+ ) -> Layer[O1 | O2 | O3, Never, Never]: ...
492
+ @overload
493
+ @staticmethod
494
+ def merge_all[O1, O2, O3, R1, R2, R3](
495
+ a: Layer[O1, Never, R1], b: Layer[O2, Never, R2], c: Layer[O3, Never, R3], /
496
+ ) -> Layer[O1 | O2 | O3, Never, R1 | R2 | R3]: ...
497
+ @overload
498
+ @staticmethod
499
+ def merge_all[O1, O2, O3, E1, E2, E3](
500
+ a: Layer[O1, E1, Never], b: Layer[O2, E2, Never], c: Layer[O3, E3, Never], /
501
+ ) -> Layer[O1 | O2 | O3, E1 | E2 | E3, Never]: ...
502
+ @overload
503
+ @staticmethod
504
+ def merge_all[O1, O2, O3, E1, E2, E3, R1, R2, R3](
505
+ a: Layer[O1, E1, R1], b: Layer[O2, E2, R2], c: Layer[O3, E3, R3], /
506
+ ) -> Layer[O1 | O2 | O3, E1 | E2 | E3, R1 | R2 | R3]: ...
507
+ @overload
508
+ @staticmethod
509
+ def merge_all[O1, O2, O3, O4](
510
+ a: Layer[O1, Never, Never],
511
+ b: Layer[O2, Never, Never],
512
+ c: Layer[O3, Never, Never],
513
+ d: Layer[O4, Never, Never],
514
+ /,
515
+ ) -> Layer[O1 | O2 | O3 | O4, Never, Never]: ...
516
+ @overload
517
+ @staticmethod
518
+ def merge_all[O1, O2, O3, O4, R1, R2, R3, R4](
519
+ a: Layer[O1, Never, R1],
520
+ b: Layer[O2, Never, R2],
521
+ c: Layer[O3, Never, R3],
522
+ d: Layer[O4, Never, R4],
523
+ /,
524
+ ) -> Layer[O1 | O2 | O3 | O4, Never, R1 | R2 | R3 | R4]: ...
525
+ @overload
526
+ @staticmethod
527
+ def merge_all[O1, O2, O3, O4, E1, E2, E3, E4](
528
+ a: Layer[O1, E1, Never],
529
+ b: Layer[O2, E2, Never],
530
+ c: Layer[O3, E3, Never],
531
+ d: Layer[O4, E4, Never],
532
+ /,
533
+ ) -> Layer[O1 | O2 | O3 | O4, E1 | E2 | E3 | E4, Never]: ...
534
+ @overload
535
+ @staticmethod
536
+ def merge_all[O1, O2, O3, O4, E1, E2, E3, E4, R1, R2, R3, R4](
537
+ a: Layer[O1, E1, R1], b: Layer[O2, E2, R2], c: Layer[O3, E3, R3], d: Layer[O4, E4, R4], /
538
+ ) -> Layer[O1 | O2 | O3 | O4, E1 | E2 | E3 | E4, R1 | R2 | R3 | R4]: ...
539
+ @staticmethod
540
+ def merge_all(*layers: Layer[Any, Any, Any]) -> Layer[Any, Any, Any]:
541
+ """Builds every layer at once, each in a sequential child of one parallel scope."""
542
+
543
+ def build(memo_map: MemoMap, scope: ScopeService) -> Effect[Context[Any], Any, Any]:
544
+ parent = Scope.fork_unsafe(scope, "parallel")
545
+ return for_each(
546
+ layers,
547
+ lambda layer, _i: layer._builder(memo_map, Scope.fork_unsafe(parent, "sequential")),
548
+ concurrency=len(layers),
549
+ ).map(lambda ctxs: reduce(lambda a, b: a | b, ctxs, Context.empty()))
550
+
551
+ return Layer._from_build_memo(build)
552
+
553
+ @staticmethod
554
+ def merge[O2, E2, R2](that: Layer[O2, E2, R2]) -> _Merge[O2, E2, R2]:
555
+ """``self.pipe(Layer.merge(that))`` is ``Layer.merge_all(self, that)``."""
556
+ return _Merge(that)
557
+
558
+ @staticmethod
559
+ def provide[O, E2, R2](that: Layer[O, E2, R2]) -> _Provide[O, E2, R2]:
560
+ """``self.pipe(Layer.provide(that))``: build ``that`` first and give its services to
561
+ ``self``; the result provides only what ``self`` does."""
562
+
563
+ def apply(self: Layer[Any, Any, Any]) -> Layer[Any, Any, Any]:
564
+ def build(memo_map: MemoMap, scope: ScopeService) -> Effect[Context[Any], Any, Any]:
565
+ return that._builder(memo_map, scope).flat_map(
566
+ lambda ctx: provide(ctx)(self._builder(memo_map, scope))
567
+ )
568
+
569
+ return Layer._from_build_memo(build)
570
+
571
+ return _Provide(that, apply)
572
+
573
+ # -- building (Layer.ts:670-781) -------------------------------------------------------------
574
+
575
+ @staticmethod
576
+ def build_with_memo_map[O, E2, R](
577
+ layer: Layer[O, E2, R], memo_map: MemoMap, scope: ScopeService
578
+ ) -> Effect[Context[O], E2, R]:
579
+ """While building, and in the built Context, CurrentMemoMap is ``memo_map``."""
580
+ current = CurrentMemoMap.context(memo_map)
581
+ built = suspend(lambda: layer._builder(memo_map, scope)).map(lambda ctx: ctx | current)
582
+ return provide(current)(built)
583
+
584
+ @staticmethod
585
+ def build_with_scope[O, E2, R](
586
+ layer: Layer[O, E2, R], scope: ScopeService
587
+ ) -> Effect[Context[O], E2, R]:
588
+ return WithFiber(
589
+ lambda fiber: Layer.build_with_memo_map(
590
+ layer, CurrentMemoMap.fork_or_create(fiber.context), scope
591
+ )
592
+ )
593
+
594
+ @staticmethod
595
+ def build[O, E2, R](layer: Layer[O, E2, R]) -> Effect[Context[O], E2, R | Scope]:
596
+ """Resources live as long as the caller's Scope."""
597
+
598
+ def start(context: ContextMap) -> Effect[Context[O], E2, R]:
599
+ scope: ScopeService = context[Scope.key]
600
+ return Layer.build_with_memo_map(layer, CurrentMemoMap.fork_or_create(context), scope)
601
+
602
+ return WithFiber(lambda fiber: start(fiber.context))
603
+
604
+ @staticmethod
605
+ def make_memo_map_unsafe() -> MemoMap:
606
+ return MemoMap(None)
607
+
608
+ @staticmethod
609
+ def make_memo_map() -> Effect[MemoMap, Never, Never]:
610
+ return suspend(lambda: succeed(MemoMap(None)))
611
+
612
+ @staticmethod
613
+ def fork_memo_map_unsafe(parent: MemoMap) -> MemoMap:
614
+ """Reads fall back to ``parent``; entries built here stay here."""
615
+ return MemoMap(parent)
616
+
617
+ @staticmethod
618
+ def fork_memo_map(parent: MemoMap) -> Effect[MemoMap, Never, Never]:
619
+ return suspend(lambda: succeed(MemoMap(parent)))
620
+
621
+
622
+ @final
623
+ class _Merge[O2, E2, R2]:
624
+ __slots__ = ("_that",)
625
+
626
+ def __init__(self, that: Layer[O2, E2, R2]) -> None:
627
+ self._that: Final = that
628
+
629
+ def __call__[O1, E1, R1](self, layer: Layer[O1, E1, R1]) -> Layer[O1 | O2, E1 | E2, R1 | R2]:
630
+ return Layer.merge_all(layer, self._that)
631
+
632
+
633
+ @final
634
+ class _Provide[O, E2, R2]:
635
+ """Two overloads stand in for ``Exclude<RIn, O>``, as ``provide`` does for effects."""
636
+
637
+ __slots__ = ("_apply", "_that")
638
+
639
+ def __init__(
640
+ self,
641
+ that: Layer[O, E2, R2],
642
+ apply: Callable[[Layer[Any, Any, Any]], Layer[Any, Any, Any]],
643
+ ) -> None:
644
+ self._that: Final = that
645
+ self._apply: Final = apply
646
+
647
+ @overload
648
+ def __call__[O1, E1](self, layer: Layer[O1, E1, O]) -> Layer[O1, E1 | E2, R2]: ...
649
+ @overload
650
+ def __call__[O1, E1, R1](self, layer: Layer[O1, E1, O | R1]) -> Layer[O1, E1 | E2, R1 | R2]: ...
651
+ def __call__(self, layer: Layer[Any, Any, Any]) -> Layer[Any, Any, Any]:
652
+ return self._apply(layer)
653
+
654
+
655
+ # -- MemoMap (Layer.ts:240-420) ------------------------------------------------------------------
656
+
657
+
658
+ @final
659
+ class _Entry:
660
+ """One shared build: how many open scopes observe it, its result, and its own scope."""
661
+
662
+ __slots__ = ("deferred", "finalizer", "observers", "scope")
663
+
664
+ def __init__(self, forget: Callable[[], object]) -> None:
665
+ self.observers = 0
666
+ self.deferred: Final = Deferred[Context[Any], Any].make_unsafe()
667
+ self.scope: Final[Closeable] = Scope.make_unsafe()
668
+
669
+ # Holds the entry and `forget` only, never the requester that made it (Layer.ts:250).
670
+ def finalizer(exit_: Exit[Any, Any]) -> Effect[None, Never, Never]:
671
+ def release() -> Effect[None, Never, Never]:
672
+ self.observers -= 1
673
+ if self.observers > 0:
674
+ return VOID
675
+ forget()
676
+ return Scope.close(self.scope, exit_)
677
+
678
+ return suspend(release)
679
+
680
+ self.finalizer: Final = finalizer
681
+
682
+
683
+ def _observe(entry: _Entry, scope: ScopeService) -> bool:
684
+ """Count and register at once, so no interrupt can land between the two (Layer.ts:268-275).
685
+ A closed scope cannot own anything: the caller builds unshared instead."""
686
+ if scope.state.tag == "Closed":
687
+ return False
688
+ entry.observers += 1
689
+ Scope.add_finalizer_unsafe(scope, object(), entry.finalizer)
690
+ return True
691
+
692
+
693
+ @final
694
+ class MemoMap:
695
+ """Built layers by identity. A forked map reads its parent's entries but never writes them."""
696
+
697
+ __slots__ = ("_map", "_parent")
698
+
699
+ def __init__(self, parent: MemoMap | None) -> None:
700
+ self._parent: Final = parent
701
+ self._map: Final[dict[Layer[Any, Any, Any], _Entry]] = {}
702
+
703
+ @property
704
+ def map(self) -> Mapping[Layer[Any, Any, Any], object]:
705
+ """This map's own entries, read-only."""
706
+ return MappingProxyType(self._map)
707
+
708
+ def get[O, E, R](
709
+ self, layer: Layer[O, E, R], scope: ScopeService
710
+ ) -> Effect[Context[O], E, R] | None:
711
+ """The shared build of ``layer``, or None. ``scope`` owns a share from this call on,
712
+ whether or not the returned effect ever runs."""
713
+ entry = self._map.get(layer)
714
+ if entry is None:
715
+ return None if self._parent is None else self._parent.get(layer, scope)
716
+ _observe(entry, scope)
717
+ done = entry.deferred.effect
718
+ return done if done is not None else entry.deferred.await_()
719
+
720
+ def get_or_else_memoize[O, E, R](
721
+ self, layer: Layer[O, E, R], scope: ScopeService, build: _Build[O, E, R]
722
+ ) -> Effect[Context[O], E, R]:
723
+ """The first requester builds in the entry's own scope and publishes its Exit, whatever
724
+ it is, the moment the build ends; later requesters wait for that Exit."""
725
+
726
+ def start() -> Effect[Context[O], E, R]:
727
+ published: list[Deferred[Context[Any], Any]] = []
728
+
729
+ def request() -> Effect[Context[O], E, R]:
730
+ existing = self.get(layer, scope)
731
+ if existing is not None:
732
+ return existing
733
+ entry = _Entry(lambda: self._map.pop(layer, None))
734
+ if not _observe(entry, scope):
735
+ return build(self, scope)
736
+ published.append(entry.deferred)
737
+ self._map[layer] = entry
738
+ return build(self, entry.scope)
739
+
740
+ def publish(exit_: Exit[Context[O], E]) -> Effect[None, Never, Never]:
741
+ for deferred in published:
742
+ deferred.done_unsafe(exit_)
743
+ return VOID
744
+
745
+ return suspend(request).on_exit(publish)
746
+
747
+ return suspend(start)
748
+
749
+
750
+ class CurrentMemoMap(Tag[MemoMap], key="effect/Layer/CurrentMemoMap"):
751
+ """The MemoMap of the build in progress; nested builds fork it (Layer.ts:600-604)."""
752
+
753
+ @staticmethod
754
+ def fork_or_create(context: ContextMap) -> MemoMap:
755
+ current = context.get(CurrentMemoMap.key)
756
+ return MemoMap(current if isinstance(current, MemoMap) else None)
757
+
758
+
759
+ # -- Effect.provide(layer) (internal/layer.ts:8-22) ----------------------------------------------
760
+
761
+
762
+ def _close_with(scope: Closeable, exit_: Exit[Any, Any]) -> Effect[None, Never, Never]:
763
+ closing = Scope.close_unsafe(scope, exit_)
764
+ return VOID if closing is None else closing
765
+
766
+
767
+ @final
768
+ class provide_layer[O, E2 = Never, R2 = Never]:
769
+ """``provide_layer(layer)(program)``: build ``layer`` in a fresh scope, run ``program`` with
770
+ its services, and close the scope with ``program``'s Exit. The scope is not provided."""
771
+
772
+ __slots__ = ("_layer",)
773
+
774
+ def __init__(self, layer: Layer[O, E2, R2]) -> None:
775
+ self._layer: Final = layer
776
+
777
+ @overload
778
+ def __call__[A, E](self, eff: Effect[A, E, O]) -> Effect[A, E | E2, R2]: ...
779
+ @overload
780
+ def __call__[A, E, R](self, eff: Effect[A, E, O | R]) -> Effect[A, E | E2, R | R2]: ...
781
+ def __call__(self, eff: Effect[Any, Any, Any]) -> Effect[Any, Any, Any]:
782
+ layer = self._layer
783
+
784
+ def start() -> Effect[Any, Any, Any]:
785
+ scope = Scope.make_unsafe()
786
+ run = Layer.build_with_scope(layer, scope).flat_map(lambda ctx: provide(ctx)(eff))
787
+ return run.on_exit(lambda exit_: _close_with(scope, exit_))
788
+
789
+ return suspend(start)