@playfast/reform 1.1.1 → 1.2.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 (85) hide show
  1. package/README.md +85 -55
  2. package/package.json +17 -17
  3. package/src/boundary/boundary.test.ts +62 -16
  4. package/src/boundary/boundary.ts +141 -32
  5. package/src/calc/asyncCalc.invalidate.test.ts +516 -18
  6. package/src/calc/asyncCalc.test.ts +207 -175
  7. package/src/calc/asyncCalc.ts +168 -39
  8. package/src/calc/calc.test.ts +3 -5
  9. package/src/calc/calc.ts +44 -18
  10. package/src/calc/calcFamily.test.ts +80 -22
  11. package/src/calc/calcFamily.ts +56 -25
  12. package/src/calc/compose.ts +1 -14
  13. package/src/channel/channel.ts +128 -11
  14. package/src/compose/composition.test.ts +19 -0
  15. package/src/compose/composition.ts +346 -62
  16. package/src/compose/props.ts +13 -6
  17. package/src/compose/provide.ts +187 -46
  18. package/src/compose/slot.ts +156 -19
  19. package/src/compose/structure.test.ts +6 -3
  20. package/src/compose/structure.ts +106 -13
  21. package/src/compose/ui.test.ts +19 -3
  22. package/src/compose/ui.ts +147 -54
  23. package/src/compose/ui.typecheck.ts +40 -4
  24. package/src/definition/definition.ts +22 -9
  25. package/src/event/event.fromSource.test.ts +172 -0
  26. package/src/event/event.test.ts +10 -0
  27. package/src/event/event.ts +102 -18
  28. package/src/feature/feature.mount.test.ts +123 -56
  29. package/src/feature/feature.test.ts +67 -63
  30. package/src/feature/feature.ts +1317 -197
  31. package/src/feature/feature.typecheck.ts +253 -61
  32. package/src/graph/closure.ts +403 -0
  33. package/src/index.ts +171 -245
  34. package/src/internal/bucketCache.ts +39 -0
  35. package/src/internal/capture.ts +9 -4
  36. package/src/internal/env.ts +1 -3
  37. package/src/internal/errors.ts +21 -10
  38. package/src/internal/queryDriver.ts +120 -15
  39. package/src/internal/queryDriverStore.ts +8 -5
  40. package/src/internal/queryDriverTypes.ts +3 -1
  41. package/src/internal/reuse.test.ts +10 -3
  42. package/src/internal/reuse.ts +5 -2
  43. package/src/internal/scheduler.ts +4 -1
  44. package/src/internal/sources.ts +25 -11
  45. package/src/internal/track.ts +3 -2
  46. package/src/internal.ts +222 -0
  47. package/src/namespace/namespace.ts +46 -25
  48. package/src/procedure/procedure.ts +38 -11
  49. package/src/reducer/reducer.ts +78 -34
  50. package/src/remote/remoteState.test.ts +515 -339
  51. package/src/remote/remoteState.ts +572 -107
  52. package/src/remote/remoteState.typecheck.ts +47 -23
  53. package/src/runtime/appRuntime.activation.test.ts +100 -0
  54. package/src/runtime/appRuntime.test.ts +157 -105
  55. package/src/runtime/appRuntime.ts +394 -33
  56. package/src/runtime/eventBudget.test.ts +1 -4
  57. package/src/runtime/eventBudget.ts +9 -8
  58. package/src/runtime/hardening.test.ts +4 -9
  59. package/src/runtime/instrumentation.test.ts +174 -192
  60. package/src/runtime/instrumentation.ts +6 -11
  61. package/src/runtime/loop.test.ts +36 -0
  62. package/src/runtime/loop.ts +69 -40
  63. package/src/scene/featureScene.test.ts +4 -2
  64. package/src/scene/scene.ts +234 -64
  65. package/src/scene/seedScene.test.ts +69 -86
  66. package/src/state/state.nominal.typecheck.ts +68 -0
  67. package/src/state/state.test.ts +17 -0
  68. package/src/state/state.ts +79 -26
  69. package/src/state/stateFamily.test.ts +14 -0
  70. package/src/state/stateFamily.ts +55 -22
  71. package/src/state/stateGroup.ts +53 -17
  72. package/src/state/token.ts +40 -10
  73. package/src/synced/syncedStore.ts +46 -23
  74. package/src/testkit/flight.testkit.ts +75 -0
  75. package/src/wire/tree.test.ts +8 -4
  76. package/src/wire/triggers.test.ts +6 -2
  77. package/src/wire/triggers.ts +14 -10
  78. package/src/calc/asyncCalcDefinitions.ts +0 -48
  79. package/src/channel/procedureRegistry.ts +0 -90
  80. package/src/feature/featureBinding.ts +0 -48
  81. package/src/internal/ctx.ts +0 -9
  82. package/src/remote/remoteStateDefinition.ts +0 -135
  83. package/src/remote/remoteStateLayers.ts +0 -118
  84. package/src/remote/remoteStateLiveTypes.ts +0 -59
  85. package/src/remote/remoteStateSend.ts +0 -64
package/README.md CHANGED
@@ -13,7 +13,7 @@ State, events, reducers, derived values, async & remote data, and compositions
13
13
 
14
14
  ---
15
15
 
16
- reform is an application framework built on [Effect](https://effect.website). You describe your app as **definitions** — state, events, reducers, calculations, compositions — and provide their behavior **separately** as Effect layers. The core renders nothing: a host package ([`@playfast/reform-react`](https://www.npmjs.com/package/@playfast/reform-react), [`@playfast/reform-react-native`](https://www.npmjs.com/package/@playfast/reform-react-native)) turns a closed *scene* into a live tree, and [`@playfast/reform-proof`](https://www.npmjs.com/package/@playfast/reform-proof) drives that same scene headlessly in tests. One model, three consumers, no seam between them.
16
+ reform is an application framework built on [Effect](https://effect.website). You describe your app as **definitions** — state, events, reducers, calculations, compositions — and provide their behavior **separately** as Effect layers. The core renders nothing: a host package ([`@playfast/reform-react`](https://www.npmjs.com/package/@playfast/reform-react), [`@playfast/reform-react-native`](https://www.npmjs.com/package/@playfast/reform-react-native)) turns a closed _scene_ into a live tree, and [`@playfast/reform-proof`](https://www.npmjs.com/package/@playfast/reform-proof) drives that same scene headlessly in tests. One model, three consumers, no seam between them.
17
17
 
18
18
  ## Install
19
19
 
@@ -62,24 +62,24 @@ class Bump extends Reducer.make('Bump', { states: [Count], events: [Bumped] }) {
62
62
  const BumpLive = Reducer.live(Bump, (n, e) => n + e.by)
63
63
  ```
64
64
 
65
- A `State` lives in a plain reactive store; reducers only *return* values, so by construction they are the **only** writers. Reads return the current snapshot through Effect.
65
+ A `State` lives in a plain reactive store; reducers only _return_ values, so by construction they are the **only** writers. Reads return the current snapshot through Effect.
66
66
 
67
67
  ### The primitives at a glance
68
68
 
69
- | primitive | definition | implementation |
70
- | --- | --- | --- |
71
- | [`State` / `StateGroup` / `StateFamily`](#state) | `State.make(name, schema, opts?)` | `.live(initial)` |
72
- | [`Event` / `EventGroup`](#event) | `Event.make(name, schema)` | — (pure data) |
73
- | [`Reducer`](#reducer) | `Reducer.make(name, { states / family, events })` | `.live(fold)` |
74
- | [`Calc` / `CalcFamily`](#calc) | `Calc.make(name, { inputs, output })` | `.live(fn)` |
75
- | [`AsyncCalc`](#asynccalc) | `AsyncCalc.make(name, { inputs, output, error?, alwaysOn? })` | `.live({ query, … })` |
76
- | [`RemoteState`](#remotestate) | `RemoteState.make(name, { inputs, output, error?, alwaysOn?, intents })` | `.live({ query, send, apply, … })` |
77
- | [`Boundary`](#boundary) | `Boundary.make(name, { over })` | `.live({ once? })` |
78
- | [`Procedure`](#procedure) | `Procedure.make(name, { events, channel })` | `.live(fn*)` |
79
- | [`Channel`](#procedure) | `Channel.make(name, { policy })` | `.live()` |
80
- | [`Composition`](#composition) | `Composition.make(name, manifest)` | `.live(fn*)` |
81
- | [`ui` / `slot`](#composition) | `ui(name)<C>()` / `slot(name)<Comp>()` | `Ui.make` / `provide` |
82
- | [`Feature`](#feature) | `Feature.make(name, config)` | (eager `module` / lazy `load`) |
69
+ | primitive | definition | implementation |
70
+ | ------------------------------------------------ | ------------------------------------------------------------------------ | ---------------------------------- |
71
+ | [`State` / `StateGroup` / `StateFamily`](#state) | `State.make(name, schema, opts?)` | `.live(initial)` |
72
+ | [`Event` / `EventGroup`](#event) | `Event.make(name, schema)` | — (pure data) |
73
+ | [`Reducer`](#reducer) | `Reducer.make(name, { states / family, events })` | `.live(fold)` |
74
+ | [`Calc` / `CalcFamily`](#calc) | `Calc.make(name, { inputs, output })` | `.live(fn)` |
75
+ | [`AsyncCalc`](#asynccalc) | `AsyncCalc.make(name, { inputs, output, error?, alwaysOn? })` | `.live({ query, … })` |
76
+ | [`RemoteState`](#remotestate) | `RemoteState.make(name, { inputs, output, error?, alwaysOn?, intents })` | `.live({ query, send, apply, … })` |
77
+ | [`Boundary`](#boundary) | `Boundary.make(name, { over })` | `.live({ once? })` |
78
+ | [`Procedure`](#procedure) | `Procedure.make(name, { events, channel })` | `.live(fn*)` |
79
+ | [`Channel`](#procedure) | `Channel.make(name, { policy })` | `.live()` |
80
+ | [`Composition`](#composition) | `Composition.make(name, manifest)` | `.live(fn*)` |
81
+ | [`ui` / `slot`](#composition) | `ui(name)<C>()` / `slot(name, identity)<Comp>()` | `Ui.make` / `provide` |
82
+ | [`Feature`](#feature) | `Feature.make(name, config)` | (eager `module` / lazy `load`) |
83
83
 
84
84
  ## The model
85
85
 
@@ -98,6 +98,7 @@ procedure ──► Bus (Normal)┘ │
98
98
  ---
99
99
 
100
100
  <a name="state"></a>
101
+
101
102
  ## State · StateGroup · StateFamily
102
103
 
103
104
  Reactive stores held outside Effect. Reducers are the sole writers; everything else reads.
@@ -119,13 +120,13 @@ A bundle of related states provided together. `StateGroup.select(Group, 'name')`
119
120
  import { State, StateGroup } from '@playfast/reform'
120
121
 
121
122
  class Count extends State.make('count', S.Number) {}
122
- class Step extends State.make('step', S.Number) {}
123
+ class Step extends State.make('step', S.Number) {}
123
124
  class Counter extends StateGroup.make(Count, Step) {}
124
125
 
125
126
  const CounterLive = StateGroup.live(Counter, { count: 0, step: 1 }) // all members required
126
127
 
127
128
  // read inside any Effect / composition:
128
- const count = yield* StateGroup.select(Counter, 'count')
129
+ const count = yield * StateGroup.select(Counter, 'count')
129
130
  ```
130
131
 
131
132
  ### `StateFamily`
@@ -149,13 +150,14 @@ const item = yield* StateFamily.read(Items, id)
149
150
  ---
150
151
 
151
152
  <a name="event"></a>
153
+
152
154
  ## Event · EventGroup
153
155
 
154
156
  Events are pure tagged data — definitions only, no `.live`.
155
157
 
156
158
  ```ts
157
- Event.make(name, schema) // → EventClass; EventOf<N, P> = { _tag: N } & P
158
- EventGroup.make(...events) // → bundle, used in Reducer/Composition manifests
159
+ Event.make(name, schema) // → EventClass; EventOf<N, P> = { _tag: N } & P
160
+ EventGroup.make(...events) // → bundle, used in Reducer/Composition manifests
159
161
 
160
162
  class LoadedTodos extends Event.make('LoadedTodos', S.Struct({ todos: S.Array(Todo) })) {}
161
163
  ```
@@ -164,11 +166,11 @@ class LoadedTodos extends Event.make('LoadedTodos', S.Struct({ todos: S.Array(To
164
166
 
165
167
  ```ts
166
168
  // From a UI view — High priority, synchronous:
167
- const toggle = yield* Event.trigger(ToggledTodo) // toggle: (payload) => void
169
+ const toggle = yield * Event.trigger(ToggledTodo) // toggle: (payload) => void
168
170
  // ...later: <input onChange={() => toggle({ id })} />
169
171
 
170
172
  // From a procedure — Normal priority:
171
- yield* Event.dispatch(TodoUpserted, { todo })
173
+ yield * Event.dispatch(TodoUpserted, { todo })
172
174
  ```
173
175
 
174
176
  `Event.trigger` returns a plain callback (`Trigger<P>`) you hand to the view; `Event.dispatch` returns an `Effect` you yield inside logic.
@@ -176,6 +178,7 @@ yield* Event.dispatch(TodoUpserted, { todo })
176
178
  ---
177
179
 
178
180
  <a name="reducer"></a>
181
+
179
182
  ## Reducer
180
183
 
181
184
  The only writers of state. A fold is a **pure, synchronous** `(value, event) => value` (async values throw at startup).
@@ -195,9 +198,13 @@ const FeedReducerLive = Reducer.live(FeedReducer, (feed, event) =>
195
198
  Match.value(event).pipe(
196
199
  Match.tags({
197
200
  StartedLoading: (): Feed => ({ _tag: 'Loading' }),
198
- LoadedTodos: ({ todos }): Feed => ({ _tag: 'Ok', todos }),
199
- FailedTodos: ({ message }): Feed => ({ _tag: 'Error', message }),
200
- TodoRemoved: ({ id }) => onOk(feed, Array.filter((t) => t.id !== id)),
201
+ LoadedTodos: ({ todos }): Feed => ({ _tag: 'Ok', todos }),
202
+ FailedTodos: ({ message }): Feed => ({ _tag: 'Error', message }),
203
+ TodoRemoved: ({ id }) =>
204
+ onOk(
205
+ feed,
206
+ Array.filter((t) => t.id !== id),
207
+ ),
201
208
  }),
202
209
  Match.exhaustive,
203
210
  ),
@@ -209,6 +216,7 @@ An event outside the reducer's declared `events` never reaches the fold; the dra
209
216
  ---
210
217
 
211
218
  <a name="calc"></a>
219
+
212
220
  ## Calc · CalcFamily
213
221
 
214
222
  Synchronous derived values — memoized projections over one or more sources.
@@ -231,15 +239,26 @@ const positive = yield* IsPositive // read the memoized value
231
239
  **`CalcFamily`** parameterizes a calc by key, one memoized store per key over shared inputs — each member notifies only its own subscribers:
232
240
 
233
241
  ```ts
234
- class GroupView extends CalcFamily.make('GroupView', { key: GroupId, inputs: [Board], output: GroupSchema }) {}
235
- const GroupViewLive = CalcFamily.live(GroupView, (id) => ({ Board }) => project(Board, id), { evictWhenUnused: true })
242
+ class GroupView extends CalcFamily.make('GroupView', {
243
+ key: GroupId,
244
+ inputs: [Board],
245
+ output: GroupSchema,
246
+ }) {}
247
+ const GroupViewLive = CalcFamily.live(
248
+ GroupView,
249
+ (id) =>
250
+ ({ Board }) =>
251
+ project(Board, id),
252
+ { evictWhenUnused: true },
253
+ )
236
254
 
237
- const view = yield* CalcFamily.read(GroupView, groupId)
255
+ const view = yield * CalcFamily.read(GroupView, groupId)
238
256
  ```
239
257
 
240
258
  ---
241
259
 
242
260
  <a name="asynccalc"></a>
261
+
243
262
  ## AsyncCalc & AsyncData
244
263
 
245
264
  Server reads with a stale-while-revalidate lifecycle. The query re-runs reactively from its inputs.
@@ -259,12 +278,12 @@ AsyncCalc.live(AsyncCalc, {
259
278
  - `error` omitted ⇒ the query is infallible (no `Error` arm). `alwaysOn: true` ⇒ no `Idle` arm and `disabled` is rejected.
260
279
  - Reading `yield* MyAsyncCalc` yields an **`AsyncData<A, E, Gated>`**:
261
280
 
262
- | arm | `_tag` | fields | when |
263
- | --- | --- | --- | --- |
264
- | `AsyncIdle` | `'Idle'` | — | gated query is `disabled` |
265
- | `AsyncLoading` | `'Loading'` | — | first fetch, no value yet |
281
+ | arm | `_tag` | fields | when |
282
+ | -------------- | ----------- | --------------------- | ------------------------------------------------ |
283
+ | `AsyncIdle` | `'Idle'` | — | gated query is `disabled` |
284
+ | `AsyncLoading` | `'Loading'` | — | first fetch, no value yet |
266
285
  | `AsyncSuccess` | `'Success'` | `value`, `refetching` | succeeded (`refetching: true` while re-fetching) |
267
- | `AsyncError` | `'Error'` | `error`, `refetching` | failed |
286
+ | `AsyncError` | `'Error'` | `error`, `refetching` | failed |
268
287
 
269
288
  ```ts
270
289
  class Doubled extends AsyncCalc.make('Doubled', {
@@ -276,7 +295,7 @@ const DoubledLive = AsyncCalc.live(Doubled, {
276
295
  query: ({ count }) => Effect.succeed(count * 2),
277
296
  })
278
297
 
279
- const data = yield* Doubled
298
+ const data = yield * Doubled
280
299
  Match.value(data).pipe(
281
300
  Match.tag('Loading', () => spinner),
282
301
  Match.tag('Success', ({ value }) => render(value)),
@@ -287,9 +306,10 @@ Match.value(data).pipe(
287
306
  ---
288
307
 
289
308
  <a name="remotestate"></a>
309
+
290
310
  ## RemoteState
291
311
 
292
- Server-owned state with optimistic mutations, fused into one primitive. **Remote state is derived-only:** the only writer is the server, the only write surface is dispatching a declared *intent*, and the visible value is `pending.reduce(apply, serverTruth)`.
312
+ Server-owned state with optimistic mutations, fused into one primitive. **Remote state is derived-only:** the only writer is the server, the only write surface is dispatching a declared _intent_, and the visible value is `pending.reduce(apply, serverTruth)`.
293
313
 
294
314
  ```ts
295
315
  RemoteState.make(name, { inputs, output, error?, alwaysOn?, intents }) // intents: Event definitions
@@ -318,23 +338,25 @@ class Board extends RemoteState.make('Board', {
318
338
  }) {}
319
339
 
320
340
  const BoardLive = RemoteState.live(Board, {
321
- query: ({ route }) => loadBoard(route.boardId),
322
- send: (intent) => Match.value(intent).pipe(
323
- Match.tag('ItemAddIntent', ({ groupId, name }) => client.AddItem({ groupId, name })),
324
- Match.tag('ItemRenameIntent', ({ itemId, name }) => client.RenameItem({ id: itemId, name })),
325
- Match.exhaustive,
326
- ),
327
- apply: (snapshot, intent) => applyIntent(snapshot, intent), // idempotent
341
+ query: ({ route }) => loadBoard(route.boardId),
342
+ send: (intent) =>
343
+ Match.value(intent).pipe(
344
+ Match.tag('ItemAddIntent', ({ groupId, name }) => client.AddItem({ groupId, name })),
345
+ Match.tag('ItemRenameIntent', ({ itemId, name }) => client.RenameItem({ id: itemId, name })),
346
+ Match.exhaustive,
347
+ ),
348
+ apply: (snapshot, intent) => applyIntent(snapshot, intent), // idempotent
328
349
  invalidateOn: [BoardChanged],
329
350
  coalesce: 'trailing',
330
351
  })
331
352
  ```
332
353
 
333
- **Semantics.** A dispatched intent appends to the queue and appears in the overlay in the same flush. On send failure the intent settles immediately and `Board.Failed` fires — there is **no rollback machinery**, the derivation just converges. The **generation rule** guarantees an optimistic change never flickers out between the RPC confirming and the refetch landing: an intent acked at query generation *g* is settled only by a later-generation `Success` run.
354
+ **Semantics.** A dispatched intent appends to the queue and appears in the overlay in the same flush. On send failure the intent settles immediately and `Board.Failed` fires — there is **no rollback machinery**, the derivation just converges. The **generation rule** guarantees an optimistic change never flickers out between the RPC confirming and the refetch landing: an intent acked at query generation _g_ is settled only by a later-generation `Success` run.
334
355
 
335
356
  ---
336
357
 
337
358
  <a name="boundary"></a>
359
+
338
360
  ## Boundary
339
361
 
340
362
  Merges the lifecycle arms of several async sources into one first-load signal, so a subtree shows a single fallback instead of per-query spinners.
@@ -360,6 +382,7 @@ const boot = yield* BootBoundary // BoundaryState
360
382
  ---
361
383
 
362
384
  <a name="procedure"></a>
385
+
363
386
  ## Procedure & Channel
364
387
 
365
388
  Procedures are side-effecting reactions to events, running on forked fibers. A **channel** is the named concurrency lane they run on.
@@ -377,14 +400,17 @@ The generator body receives the matched event, can read services from context, a
377
400
  ```ts
378
401
  class ActionsChannel extends Channel.make('Actions', { policy: { _tag: 'merge' } }) {}
379
402
 
380
- class CreateTodo extends Procedure.make('CreateTodo', { events: [SubmittedNewTodo], channel: ActionsChannel }) {}
403
+ class CreateTodo extends Procedure.make('CreateTodo', {
404
+ events: [SubmittedNewTodo],
405
+ channel: ActionsChannel,
406
+ }) {}
381
407
  const CreateTodoLive = Procedure.live(CreateTodo, function* (event) {
382
408
  const client = yield* TodosClient
383
409
  const result = yield* Effect.either(client.AddTodo({ text: event.text }))
384
410
  yield* Match.value(result).pipe(
385
411
  Match.tags({
386
412
  Right: ({ right }) => Event.dispatch(TodoUpserted, { todo: right }),
387
- Left: ({ left }) => Event.dispatch(FailedTodos, { message: String(left) }),
413
+ Left: ({ left }) => Event.dispatch(FailedTodos, { message: String(left) }),
388
414
  }),
389
415
  Match.exhaustive,
390
416
  )
@@ -396,6 +422,7 @@ Policies: `merge` (unbounded concurrency), `latest` (new event cancels the in-fl
396
422
  ---
397
423
 
398
424
  <a name="composition"></a>
425
+
399
426
  ## Composition · ui · slot · provide
400
427
 
401
428
  A **composition** is a unit of logic that reads state and renders a typed UI contract. The contract (`ui`) and its presentation are authored separately, so logic stays renderer-neutral.
@@ -426,12 +453,13 @@ const CounterView = provide(CounterUi, Ui.make(CounterUi, ({ count }, _slots, {
426
453
 
427
454
  - **`Composition.make(name, manifest)`** — manifest declares `ui` plus the `states` / `calcs` / `events` / `slots` it touches (all reflectable).
428
455
  - **`Composition.live(comp, fn*)`** — the generator reads sources and returns a `Node` (the view applied to props/events).
429
- - **`slot(name)<Comp>()`** — a hole a parent composition declares (`slots: { body: BodySlot }`) and fills with `provide(BodySlot, ChildComposition)` (or a `Feature`). Children render through the host.
456
+ - **`slot(name, identity)<Comp>()`** — a hole a parent composition declares (`slots: { body: BodySlot }`) and fills with `provide(BodySlot, ChildComposition)` (or a `Feature`). Declare `identity` as a named module-level unique symbol (`const BodySlotIdentity: unique symbol = Symbol('BodySlot')`); `Symbol.for(...)` and inline `Symbol(...)` arguments are forbidden. Reform generates a separate runtime key for every slot definition, while `name` remains a display label, so independently authored same-name slots remain distinct. Children render through the host.
430
457
  - **`provide(...)`** — binds a UI presentation to a contract, or fills a slot with a composition / feature. Returns a `Layer`.
431
458
 
432
459
  ---
433
460
 
434
461
  <a name="feature"></a>
462
+
435
463
  ## Feature
436
464
 
437
465
  The lazy/eager code-split unit. Definitions stay eager and reflectable; the heavy implementation can load on demand as an **Effect** (never a bare Promise), so code-splitting composes with the rest of the layer graph.
@@ -471,6 +499,7 @@ their boot events run once for each keyed activation.
471
499
  ---
472
500
 
473
501
  <a name="scene"></a>
502
+
474
503
  ## Scene
475
504
 
476
505
  A scene bundles a root composition with the closed wiring that runs it — the single handle the React host, React Native host, and proofs all consume.
@@ -496,6 +525,7 @@ are rejected because an application root must be immediately available.
496
525
  ---
497
526
 
498
527
  <a name="engine"></a>
528
+
499
529
  ## Engine & runtime surface
500
530
 
501
531
  `Engine` is the layer that ties a runtime together: it provides the `Bus` (one `PubSub`), the `Reducers` / `Channels` / `Procedures` registries, and forks the single drain loop. Merge it at the root of your app's layers:
@@ -564,15 +594,15 @@ Mount it with [`@playfast/reform-react`](https://www.npmjs.com/package/@playfast
564
594
 
565
595
  ## The reform family
566
596
 
567
- | Package | Role |
568
- | --- | --- |
569
- | **`@playfast/reform`** | Renderer-neutral core (this package) |
570
- | [`@playfast/reform-react`](https://www.npmjs.com/package/@playfast/reform-react) | React / DOM host |
571
- | [`@playfast/reform-react-native`](https://www.npmjs.com/package/@playfast/reform-react-native) | React Native host |
572
- | [`@playfast/reform-forms`](https://www.npmjs.com/package/@playfast/reform-forms) | Headless form state |
573
- | [`@playfast/reform-forms-react`](https://www.npmjs.com/package/@playfast/reform-forms-react) | Typed JSX mapping for forms |
574
- | [`@playfast/reform-proof`](https://www.npmjs.com/package/@playfast/reform-proof) | Headless testing toolkit |
575
- | [`@playfast/reform-eslint-plugin`](https://www.npmjs.com/package/@playfast/reform-eslint-plugin) | Lint rules for reform conventions |
597
+ | Package | Role |
598
+ | ------------------------------------------------------------------------------------------------ | ------------------------------------ |
599
+ | **`@playfast/reform`** | Renderer-neutral core (this package) |
600
+ | [`@playfast/reform-react`](https://www.npmjs.com/package/@playfast/reform-react) | React / DOM host |
601
+ | [`@playfast/reform-react-native`](https://www.npmjs.com/package/@playfast/reform-react-native) | React Native host |
602
+ | [`@playfast/reform-forms`](https://www.npmjs.com/package/@playfast/reform-forms) | Headless form state |
603
+ | [`@playfast/reform-forms-react`](https://www.npmjs.com/package/@playfast/reform-forms-react) | Typed JSX mapping for forms |
604
+ | [`@playfast/reform-proof`](https://www.npmjs.com/package/@playfast/reform-proof) | Headless testing toolkit |
605
+ | [`@playfast/reform-eslint-plugin`](https://www.npmjs.com/package/@playfast/reform-eslint-plugin) | Lint rules for reform conventions |
576
606
 
577
607
  ## License
578
608
 
package/package.json CHANGED
@@ -1,36 +1,38 @@
1
1
  {
2
2
  "name": "@playfast/reform",
3
- "playbook": "./playbook",
4
- "version": "1.1.1",
5
- "type": "module",
3
+ "version": "1.2.0",
6
4
  "description": "The renderer-neutral core of the reform framework — typed, headless state, events, reducers, derived values, async/remote data, and compositions built on Effect.",
7
5
  "keywords": [
8
- "reform",
9
6
  "effect",
10
- "state-management",
11
- "headless",
12
7
  "framework",
13
- "reactive"
8
+ "headless",
9
+ "reactive",
10
+ "reform",
11
+ "state-management"
14
12
  ],
13
+ "bugs": {
14
+ "url": "https://github.com/playfast/reform/issues"
15
+ },
15
16
  "license": "MIT",
16
17
  "repository": {
17
18
  "type": "git",
18
19
  "url": "https://github.com/playfast/reform.git",
19
20
  "directory": "packages/reform"
20
21
  },
21
- "bugs": {
22
- "url": "https://github.com/playfast/reform/issues"
23
- },
22
+ "files": [
23
+ "src",
24
+ "README.md"
25
+ ],
26
+ "type": "module",
24
27
  "sideEffects": false,
25
28
  "exports": {
26
29
  "./package.json": "./package.json",
27
30
  ".": "./src/index.ts",
28
31
  "./*": "./src/*.ts"
29
32
  },
30
- "files": [
31
- "src",
32
- "README.md"
33
- ],
33
+ "publishConfig": {
34
+ "access": "public"
35
+ },
34
36
  "scripts": {
35
37
  "clean": "rm -rf dist .tsbuildinfo",
36
38
  "check": "tsc --noEmit",
@@ -50,7 +52,5 @@
50
52
  "optional": true
51
53
  }
52
54
  },
53
- "publishConfig": {
54
- "access": "public"
55
- }
55
+ "playbook": "./playbook"
56
56
  }
@@ -31,8 +31,12 @@ it.live('pending while ANY covered query is on its first load; one Ready when al
31
31
  const TestLayer = Boundary.live(Gate).pipe(
32
32
  Layer.provideMerge(
33
33
  Layer.merge(
34
- AsyncCalc.live(Fast, { query: ({ seed }) => Effect.succeed(seed).pipe(Effect.delay('10 millis')) }),
35
- AsyncCalc.live(Slow, { query: ({ seed }) => Effect.succeed(seed).pipe(Effect.delay('40 millis')) }),
34
+ AsyncCalc.live(Fast, {
35
+ query: ({ seed }) => Effect.succeed(seed).pipe(Effect.delay('10 millis')),
36
+ }),
37
+ AsyncCalc.live(Slow, {
38
+ query: ({ seed }) => Effect.succeed(seed).pipe(Effect.delay('40 millis')),
39
+ }),
36
40
  ),
37
41
  ),
38
42
  Layer.provideMerge(StateGroup.live(Inputs, { seed: 1 })),
@@ -48,7 +52,10 @@ it.live('pending while ANY covered query is on its first load; one Ready when al
48
52
  yield* tick(20)
49
53
  expect(store.get()._tag).toBe('Pending')
50
54
 
51
- yield* until(() => store.get()._tag, (t) => t === 'Ready')
55
+ yield* until(
56
+ () => store.get()._tag,
57
+ (t) => t === 'Ready',
58
+ )
52
59
  expect(observed).toEqual(['Ready'])
53
60
  }).pipe(Effect.provide(TestLayer))
54
61
  })
@@ -77,7 +84,10 @@ it.live('a gated query that is OFF counts Ready — the off arm must not hold th
77
84
  )
78
85
  return Effect.gen(function* () {
79
86
  const store = yield* Gate.store
80
- yield* until(() => store.get()._tag, (t) => t === 'Ready')
87
+ yield* until(
88
+ () => store.get()._tag,
89
+ (t) => t === 'Ready',
90
+ )
81
91
  expect(store.get()._tag).toBe('Ready')
82
92
  }).pipe(Effect.provide(TestLayer))
83
93
  })
@@ -103,12 +113,21 @@ it.live('an SWR refetch never re-pends — Success with refetching: true is Read
103
113
  const seed = yield* StateGroup.select(Inputs, 'seed').store
104
114
  const qStore = yield* Q.store
105
115
  const store = yield* Gate.store
106
- yield* until(() => store.get()._tag, (t) => t === 'Ready')
116
+ yield* until(
117
+ () => store.get()._tag,
118
+ (t) => t === 'Ready',
119
+ )
107
120
 
108
121
  seed.set(2)
109
- yield* until(() => qStore.get(), (q) => q._tag === 'Success' && q.refetching)
122
+ yield* until(
123
+ () => qStore.get(),
124
+ (q) => q._tag === 'Success' && q.refetching,
125
+ )
110
126
  expect(store.get()._tag).toBe('Ready')
111
- yield* until(() => qStore.get(), (q) => q._tag === 'Success' && !q.refetching)
127
+ yield* until(
128
+ () => qStore.get(),
129
+ (q) => q._tag === 'Success' && !q.refetching,
130
+ )
112
131
  expect(store.get()._tag).toBe('Ready')
113
132
  }).pipe(Effect.provide(TestLayer))
114
133
  })
@@ -138,7 +157,10 @@ it.live('a first-load failure surfaces as Errored with the failure, and a retry
138
157
  )
139
158
  return Effect.gen(function* () {
140
159
  const store = yield* Gate.store
141
- const errored = yield* until(() => store.get(), (s) => s._tag === 'Errored')
160
+ const errored = yield* until(
161
+ () => store.get(),
162
+ (s) => s._tag === 'Errored',
163
+ )
142
164
  if (errored._tag === 'Errored') {
143
165
  expect(errored.errors).toHaveLength(1)
144
166
  const failure = errored.errors[0]
@@ -147,7 +169,10 @@ it.live('a first-load failure surfaces as Errored with the failure, and a retry
147
169
 
148
170
  healthy.now = true
149
171
  yield* Event.dispatch(Poke, {})
150
- yield* until(() => store.get()._tag, (t) => t === 'Ready')
172
+ yield* until(
173
+ () => store.get()._tag,
174
+ (t) => t === 'Ready',
175
+ )
151
176
  expect(store.get()._tag).toBe('Ready')
152
177
  }).pipe(Effect.provide(TestLayer))
153
178
  })
@@ -185,7 +210,10 @@ it.live('settle-gap pin: a chained gate never leaks Ready between hops', () => {
185
210
  })
186
211
  expect(store.get()._tag).toBe('Pending')
187
212
 
188
- yield* until(() => store.get()._tag, (t) => t === 'Ready')
213
+ yield* until(
214
+ () => store.get()._tag,
215
+ (t) => t === 'Ready',
216
+ )
189
217
  yield* tick(30)
190
218
  expect(observed).toEqual(['Ready'])
191
219
  }).pipe(Effect.provide(TestLayer))
@@ -221,10 +249,19 @@ it.live('once + a Calc hop in the chain: the latch never freezes a mid-flush Rea
221
249
  return Effect.gen(function* () {
222
250
  const bStore = yield* B.store
223
251
  const store = yield* Gate.store
224
- yield* until(() => bStore.get()._tag, (t) => t === 'Loading')
252
+ yield* until(
253
+ () => bStore.get()._tag,
254
+ (t) => t === 'Loading',
255
+ )
225
256
  expect(store.get()._tag).toBe('Pending')
226
- yield* until(() => bStore.get()._tag, (t) => t === 'Success')
227
- yield* until(() => store.get()._tag, (t) => t === 'Ready')
257
+ yield* until(
258
+ () => bStore.get()._tag,
259
+ (t) => t === 'Success',
260
+ )
261
+ yield* until(
262
+ () => store.get()._tag,
263
+ (t) => t === 'Ready',
264
+ )
228
265
  expect(store.get()._tag).toBe('Ready')
229
266
  }).pipe(Effect.provide(TestLayer))
230
267
  })
@@ -258,12 +295,21 @@ it.live('once: a covered gate enabling AFTER the latch never re-pends the bounda
258
295
  const route = yield* StateGroup.select(Inputs, 'routeFlag').store
259
296
  const routedStore = yield* Routed.store
260
297
  const store = yield* Gate.store
261
- yield* until(() => store.get()._tag, (t) => t === 'Ready')
298
+ yield* until(
299
+ () => store.get()._tag,
300
+ (t) => t === 'Ready',
301
+ )
262
302
 
263
303
  route.set(true)
264
- yield* until(() => routedStore.get()._tag, (t) => t === 'Loading')
304
+ yield* until(
305
+ () => routedStore.get()._tag,
306
+ (t) => t === 'Loading',
307
+ )
265
308
  expect(store.get()._tag).toBe('Ready')
266
- yield* until(() => routedStore.get()._tag, (t) => t === 'Success')
309
+ yield* until(
310
+ () => routedStore.get()._tag,
311
+ (t) => t === 'Success',
312
+ )
267
313
  expect(store.get()._tag).toBe('Ready')
268
314
  }).pipe(Effect.provide(TestLayer))
269
315
  })