@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.
- package/README.md +85 -55
- package/package.json +17 -17
- package/src/boundary/boundary.test.ts +62 -16
- package/src/boundary/boundary.ts +141 -32
- package/src/calc/asyncCalc.invalidate.test.ts +516 -18
- package/src/calc/asyncCalc.test.ts +207 -175
- package/src/calc/asyncCalc.ts +168 -39
- package/src/calc/calc.test.ts +3 -5
- package/src/calc/calc.ts +44 -18
- package/src/calc/calcFamily.test.ts +80 -22
- package/src/calc/calcFamily.ts +56 -25
- package/src/calc/compose.ts +1 -14
- package/src/channel/channel.ts +128 -11
- package/src/compose/composition.test.ts +19 -0
- package/src/compose/composition.ts +346 -62
- package/src/compose/props.ts +13 -6
- package/src/compose/provide.ts +187 -46
- package/src/compose/slot.ts +156 -19
- package/src/compose/structure.test.ts +6 -3
- package/src/compose/structure.ts +106 -13
- package/src/compose/ui.test.ts +19 -3
- package/src/compose/ui.ts +147 -54
- package/src/compose/ui.typecheck.ts +40 -4
- package/src/definition/definition.ts +22 -9
- package/src/event/event.fromSource.test.ts +172 -0
- package/src/event/event.test.ts +10 -0
- package/src/event/event.ts +102 -18
- package/src/feature/feature.mount.test.ts +123 -56
- package/src/feature/feature.test.ts +67 -63
- package/src/feature/feature.ts +1317 -197
- package/src/feature/feature.typecheck.ts +253 -61
- package/src/graph/closure.ts +403 -0
- package/src/index.ts +171 -245
- package/src/internal/bucketCache.ts +39 -0
- package/src/internal/capture.ts +9 -4
- package/src/internal/env.ts +1 -3
- package/src/internal/errors.ts +21 -10
- package/src/internal/queryDriver.ts +120 -15
- package/src/internal/queryDriverStore.ts +8 -5
- package/src/internal/queryDriverTypes.ts +3 -1
- package/src/internal/reuse.test.ts +10 -3
- package/src/internal/reuse.ts +5 -2
- package/src/internal/scheduler.ts +4 -1
- package/src/internal/sources.ts +25 -11
- package/src/internal/track.ts +3 -2
- package/src/internal.ts +222 -0
- package/src/namespace/namespace.ts +46 -25
- package/src/procedure/procedure.ts +38 -11
- package/src/reducer/reducer.ts +78 -34
- package/src/remote/remoteState.test.ts +515 -339
- package/src/remote/remoteState.ts +572 -107
- package/src/remote/remoteState.typecheck.ts +47 -23
- package/src/runtime/appRuntime.activation.test.ts +100 -0
- package/src/runtime/appRuntime.test.ts +157 -105
- package/src/runtime/appRuntime.ts +394 -33
- package/src/runtime/eventBudget.test.ts +1 -4
- package/src/runtime/eventBudget.ts +9 -8
- package/src/runtime/hardening.test.ts +4 -9
- package/src/runtime/instrumentation.test.ts +174 -192
- package/src/runtime/instrumentation.ts +6 -11
- package/src/runtime/loop.test.ts +36 -0
- package/src/runtime/loop.ts +69 -40
- package/src/scene/featureScene.test.ts +4 -2
- package/src/scene/scene.ts +234 -64
- package/src/scene/seedScene.test.ts +69 -86
- package/src/state/state.nominal.typecheck.ts +68 -0
- package/src/state/state.test.ts +17 -0
- package/src/state/state.ts +79 -26
- package/src/state/stateFamily.test.ts +14 -0
- package/src/state/stateFamily.ts +55 -22
- package/src/state/stateGroup.ts +53 -17
- package/src/state/token.ts +40 -10
- package/src/synced/syncedStore.ts +46 -23
- package/src/testkit/flight.testkit.ts +75 -0
- package/src/wire/tree.test.ts +8 -4
- package/src/wire/triggers.test.ts +6 -2
- package/src/wire/triggers.ts +14 -10
- package/src/calc/asyncCalcDefinitions.ts +0 -48
- package/src/channel/procedureRegistry.ts +0 -90
- package/src/feature/featureBinding.ts +0 -48
- package/src/internal/ctx.ts +0 -9
- package/src/remote/remoteStateDefinition.ts +0 -135
- package/src/remote/remoteStateLayers.ts +0 -118
- package/src/remote/remoteStateLiveTypes.ts +0 -59
- 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
|
|
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
|
|
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
|
|
70
|
-
|
|
|
71
|
-
| [`State` / `StateGroup` / `StateFamily`](#state) | `State.make(name, schema, opts?)`
|
|
72
|
-
| [`Event` / `EventGroup`](#event)
|
|
73
|
-
| [`Reducer`](#reducer)
|
|
74
|
-
| [`Calc` / `CalcFamily`](#calc)
|
|
75
|
-
| [`AsyncCalc`](#asynccalc)
|
|
76
|
-
| [`RemoteState`](#remotestate)
|
|
77
|
-
| [`Boundary`](#boundary)
|
|
78
|
-
| [`Procedure`](#procedure)
|
|
79
|
-
| [`Channel`](#procedure)
|
|
80
|
-
| [`Composition`](#composition)
|
|
81
|
-
| [`ui` / `slot`](#composition)
|
|
82
|
-
| [`Feature`](#feature)
|
|
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
|
|
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)
|
|
158
|
-
EventGroup.make(...events)
|
|
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)
|
|
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:
|
|
199
|
-
FailedTodos:
|
|
200
|
-
TodoRemoved:
|
|
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', {
|
|
235
|
-
|
|
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
|
|
263
|
-
|
|
|
264
|
-
| `AsyncIdle`
|
|
265
|
-
| `AsyncLoading` | `'Loading'` | —
|
|
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`
|
|
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
|
|
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:
|
|
322
|
-
send:
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
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
|
|
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', {
|
|
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:
|
|
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
|
|
568
|
-
|
|
|
569
|
-
| **`@playfast/reform`**
|
|
570
|
-
| [`@playfast/reform-react`](https://www.npmjs.com/package/@playfast/reform-react)
|
|
571
|
-
| [`@playfast/reform-react-native`](https://www.npmjs.com/package/@playfast/reform-react-native)
|
|
572
|
-
| [`@playfast/reform-forms`](https://www.npmjs.com/package/@playfast/reform-forms)
|
|
573
|
-
| [`@playfast/reform-forms-react`](https://www.npmjs.com/package/@playfast/reform-forms-react)
|
|
574
|
-
| [`@playfast/reform-proof`](https://www.npmjs.com/package/@playfast/reform-proof)
|
|
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
|
-
"
|
|
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
|
-
"
|
|
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
|
-
"
|
|
22
|
-
"
|
|
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
|
-
"
|
|
31
|
-
"
|
|
32
|
-
|
|
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
|
-
"
|
|
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, {
|
|
35
|
-
|
|
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(
|
|
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(
|
|
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(
|
|
116
|
+
yield* until(
|
|
117
|
+
() => store.get()._tag,
|
|
118
|
+
(t) => t === 'Ready',
|
|
119
|
+
)
|
|
107
120
|
|
|
108
121
|
seed.set(2)
|
|
109
|
-
yield* until(
|
|
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(
|
|
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(
|
|
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(
|
|
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(
|
|
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(
|
|
252
|
+
yield* until(
|
|
253
|
+
() => bStore.get()._tag,
|
|
254
|
+
(t) => t === 'Loading',
|
|
255
|
+
)
|
|
225
256
|
expect(store.get()._tag).toBe('Pending')
|
|
226
|
-
yield* until(
|
|
227
|
-
|
|
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(
|
|
298
|
+
yield* until(
|
|
299
|
+
() => store.get()._tag,
|
|
300
|
+
(t) => t === 'Ready',
|
|
301
|
+
)
|
|
262
302
|
|
|
263
303
|
route.set(true)
|
|
264
|
-
yield* until(
|
|
304
|
+
yield* until(
|
|
305
|
+
() => routedStore.get()._tag,
|
|
306
|
+
(t) => t === 'Loading',
|
|
307
|
+
)
|
|
265
308
|
expect(store.get()._tag).toBe('Ready')
|
|
266
|
-
yield* until(
|
|
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
|
})
|