@playfast/reform 0.0.5 → 0.0.8

package/package.json

@@ -1,24 +1,45 @@
 {
   "name": "@playfast/reform",
-  "version": "0.0.5",
+  "playbook": "./playbook",
+  "version": "0.0.8",
   "type": "module",
-  "sideEffects": [],
+  "description": "The renderer-neutral core of the reform framework — typed, headless state, events, reducers, derived values, async/remote data, and compositions built on Effect.",
+  "keywords": [
+    "reform",
+    "effect",
+    "state-management",
+    "headless",
+    "framework",
+    "reactive"
+  ],
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/playfast/reform.git",
+    "directory": "packages/reform"
+  },
+  "bugs": {
+    "url": "https://github.com/playfast/reform/issues"
+  },
+  "sideEffects": false,
   "exports": {
     "./package.json": "./package.json",
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
   },
   "files": [
     "src",
-    "README.md",
-    "!src/**/*.test.ts",
-    "!src/**/*.test.tsx",
-    "!src/**/*.typecheck.ts",
-    "!src/**/*.typecheck.tsx"
+    "README.md"
   ],
   "scripts": {
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run"
+    "clean": "rm -rf dist .tsbuildinfo",
+    "check": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage",
+    "lint": "oxlint src",
+    "lint:fix": "oxlint --fix src"
   },
   "peerDependencies": {
     "effect": "*",

package/src/boundary/boundary.test.ts

@@ -0,0 +1,301 @@
+import { expect, it } from '@effect/vitest'
+import { Data, Duration, Effect, Layer, Schema as S } from 'effect'
+import { AsyncCalc, Boundary, Calc, Engine, Event, State, StateGroup } from '../index'
+
+// Boundary merges several async lifecycles into one Pending/Errored/Ready value
+// — the Suspense-boundary analog, value-level. The behaviours under test: the
+// arm mapping (Loading pends, Idle and SWR-refetching count Ready, Error
+// surfaces), the chained-gate settle-gap pin, the `once` latch, and the
+// notification economy (arm-stable churn wakes nobody).
+
+const tick = (ms = 10) => Effect.sleep(Duration.millis(ms))
+
+const until = <A>(read: () => A, pred: (a: A) => boolean, rounds = 200): Effect.Effect<A> =>
+  Effect.suspend(() => {
+    const a = read()
+    return pred(a) || rounds <= 0
+      ? Effect.succeed(a)
+      : Effect.flatMap(tick(10), () => until(read, pred, rounds - 1))
+  })
+
+class Boom extends Data.TaggedError('Boom')<{ readonly message: string }> {}
+
+it.live('pending while ANY covered query is on its first load; one Ready when all settle', () => {
+  class Seed extends State.make('seed', S.Number) {}
+  class Inputs extends StateGroup.make(Seed) {}
+  class Fast extends AsyncCalc.make('Fast', {
+    inputs: [StateGroup.select(Inputs, 'seed')],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  class Slow extends AsyncCalc.make('Slow', {
+    inputs: [StateGroup.select(Inputs, 'seed')],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  class Gate extends Boundary.make('Gate', { over: [Fast, Slow] }) {}
+  const TestLayer = Boundary.live(Gate).pipe(
+    Layer.provideMerge(
+      Layer.merge(
+        AsyncCalc.live(Fast, { query: ({ seed }) => Effect.succeed(seed).pipe(Effect.delay('10 millis')) }),
+        AsyncCalc.live(Slow, { query: ({ seed }) => Effect.succeed(seed).pipe(Effect.delay('40 millis')) }),
+      ),
+    ),
+    Layer.provideMerge(StateGroup.live(Inputs, { seed: 1 })),
+  )
+  return Effect.gen(function* () {
+    const store = yield* Gate.store
+    const observed: Array<string> = []
+    store.subscribe(() => {
+      observed.push(store.get()._tag)
+    })
+    expect(store.get()._tag).toBe('Pending')
+
+    // The fast query settles first — still Pending (the slow one holds it).
+    yield* tick(20)
+    expect(store.get()._tag).toBe('Pending')
+
+    yield* until(() => store.get()._tag, (t) => t === 'Ready')
+    // Exactly ONE notification fired across the whole boot: Pending→Pending
+    // churn (Fast settling) was absorbed by the stable arm reference.
+    expect(observed).toEqual(['Ready'])
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('a gated query that is OFF counts Ready — the off arm must not hold the gate', () => {
+  class Flag extends State.make('flag', S.Boolean) {}
+  class Inputs extends StateGroup.make(Flag) {}
+  class Always extends AsyncCalc.make('Always', {
+    inputs: [StateGroup.select(Inputs, 'flag')],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  class Gated extends AsyncCalc.make('Gated', {
+    inputs: [StateGroup.select(Inputs, 'flag')],
+    output: S.Number,
+  }) {}
+  class Gate extends Boundary.make('Gate', { over: [Always, Gated] }) {}
+  const TestLayer = Boundary.live(Gate).pipe(
+    Layer.provideMerge(
+      Layer.merge(
+        AsyncCalc.live(Always, { query: () => Effect.succeed(1) }),
+        AsyncCalc.live(Gated, { query: () => Effect.succeed(2), disabled: ({ flag }) => !flag }),
+      ),
+    ),
+    Layer.provideMerge(StateGroup.live(Inputs, { flag: false })),
+  )
+  return Effect.gen(function* () {
+    const store = yield* Gate.store
+    // The gated query is Idle (deliberately off): only the always-on first
+    // load pends, and Ready arrives without ever waiting on the Idle arm.
+    yield* until(() => store.get()._tag, (t) => t === 'Ready')
+    expect(store.get()._tag).toBe('Ready')
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('an SWR refetch never re-pends — Success with refetching: true is Ready', () => {
+  class Seed extends State.make('seed', S.Number) {}
+  class Inputs extends StateGroup.make(Seed) {}
+  class Q extends AsyncCalc.make('Q', {
+    inputs: [StateGroup.select(Inputs, 'seed')],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  class Gate extends Boundary.make('Gate', { over: [Q] }) {}
+  const TestLayer = Boundary.live(Gate).pipe(
+    Layer.provideMerge(
+      AsyncCalc.live(Q, {
+        query: ({ seed }) => Effect.succeed(seed * 2).pipe(Effect.delay('15 millis')),
+      }),
+    ),
+    Layer.provideMerge(StateGroup.live(Inputs, { seed: 1 })),
+  )
+  return Effect.gen(function* () {
+    const seed = yield* StateGroup.select(Inputs, 'seed').store
+    const qStore = yield* Q.store
+    const store = yield* Gate.store
+    yield* until(() => store.get()._tag, (t) => t === 'Ready')
+
+    // Move the input: the query goes Success+refetching (SWR) — Ready holds.
+    seed.set(2)
+    yield* until(() => qStore.get(), (q) => q._tag === 'Success' && q.refetching)
+    expect(store.get()._tag).toBe('Ready')
+    yield* until(() => qStore.get(), (q) => q._tag === 'Success' && !q.refetching)
+    expect(store.get()._tag).toBe('Ready')
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('a first-load failure surfaces as Errored with the failure, and a retry recovers', () => {
+  class Seed extends State.make('seed', S.Number) {}
+  class Inputs extends StateGroup.make(Seed) {}
+  class Poke extends Event.make('Poke', S.Struct({})) {}
+  const healthy = { now: false }
+  class Q extends AsyncCalc.make('Q', {
+    inputs: [StateGroup.select(Inputs, 'seed')],
+    output: S.Number,
+    error: S.instanceOf(Boom),
+    alwaysOn: true,
+  }) {}
+  class Gate extends Boundary.make('Gate', { over: [Q] }) {}
+  const TestLayer = Boundary.live(Gate).pipe(
+    Layer.provideMerge(
+      AsyncCalc.live(Q, {
+        query: () =>
+          healthy.now ? Effect.succeed(1) : Effect.fail(new Boom({ message: 'server down' })),
+        invalidateOn: [Poke],
+      }),
+    ),
+    Layer.provideMerge(StateGroup.live(Inputs, { seed: 1 })),
+    Layer.provideMerge(Engine),
+  )
+  return Effect.gen(function* () {
+    const store = yield* Gate.store
+    const errored = yield* until(() => store.get(), (s) => s._tag === 'Errored')
+    if (errored._tag === 'Errored') {
+      expect(errored.errors).toHaveLength(1)
+      const failure = errored.errors[0]
+      expect(failure instanceof Boom && failure.message).toBe('server down')
+    }
+
+    // The retry path: the server heals, a listed fact refetches, Ready lands.
+    healthy.now = true
+    yield* Event.dispatch(Poke, {})
+    yield* until(() => store.get()._tag, (t) => t === 'Ready')
+    expect(store.get()._tag).toBe('Ready')
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('settle-gap pin: a chained gate never leaks Ready between hops', () => {
+  // B enables only when A has succeeded — the app's Session → Bootstrap shape.
+  // The dangerous instant: A flips Success while B is still Idle (Idle counts
+  // Ready), so a naive merge could notify Ready before B's driver flips it to
+  // Loading. Layer dependency order (B's driver subscribes to A's store before
+  // the boundary does) plus the one-microtask fixpoint flush close the gap;
+  // this records every notification to prove no intermediate Ready escapes.
+  class Seed extends State.make('seed', S.Number) {}
+  class Inputs extends StateGroup.make(Seed) {}
+  class A extends AsyncCalc.make('A', {
+    inputs: [StateGroup.select(Inputs, 'seed')],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  class B extends AsyncCalc.make('B', {
+    inputs: [A],
+    output: S.Number,
+  }) {}
+  class Gate extends Boundary.make('Gate', { over: [A, B] }) {}
+  const TestLayer = Boundary.live(Gate).pipe(
+    Layer.provideMerge(
+      AsyncCalc.live(B, {
+        query: () => Effect.succeed(2).pipe(Effect.delay('15 millis')),
+        disabled: ({ A: a }) => a._tag !== 'Success',
+      }),
+    ),
+    Layer.provideMerge(
+      AsyncCalc.live(A, { query: () => Effect.succeed(1).pipe(Effect.delay('15 millis')) }),
+    ),
+    Layer.provideMerge(StateGroup.live(Inputs, { seed: 1 })),
+  )
+  return Effect.gen(function* () {
+    const store = yield* Gate.store
+    const observed: Array<string> = []
+    store.subscribe(() => {
+      observed.push(store.get()._tag)
+    })
+    expect(store.get()._tag).toBe('Pending')
+
+    yield* until(() => store.get()._tag, (t) => t === 'Ready')
+    yield* tick(30) // let any straggler notification land before judging
+    // ONE Ready, at the end — never a Ready while B's hop was still pending.
+    expect(observed).toEqual(['Ready'])
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('once + a Calc hop in the chain: the latch never freezes a mid-flush Ready', () => {
+  // The app's boot shape: AsyncCalc A → plain Calc projecting it → AsyncCalc B
+  // gated on the projection. Propagation crosses TWO scheduler-flush rounds,
+  // so when A settles there is a mid-flush frame where B has not yet flipped
+  // to Loading — a recompute-time latch would freeze that intermediate Ready
+  // and the boundary would abandon B's whole first load (caught live by the
+  // boot-frames walk: nav in, boards card still spinning).
+  class Seed extends State.make('seed', S.Number) {}
+  class Inputs extends StateGroup.make(Seed) {}
+  class A extends AsyncCalc.make('A', {
+    inputs: [StateGroup.select(Inputs, 'seed')],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  class Hop extends Calc.make('Hop', { inputs: [A], output: S.Number }) {}
+  class B extends AsyncCalc.make('B', {
+    inputs: [Hop],
+    output: S.Number,
+  }) {}
+  class Gate extends Boundary.make('Gate', { over: [A, B] }) {}
+  const TestLayer = Boundary.live(Gate, { once: true }).pipe(
+    Layer.provideMerge(
+      AsyncCalc.live(B, {
+        query: () => Effect.succeed(2).pipe(Effect.delay('25 millis')),
+        disabled: ({ Hop: hop }) => hop < 0,
+      }),
+    ),
+    Layer.provideMerge(Calc.live(Hop, ({ A: a }) => (a._tag === 'Success' ? a.value : -1))),
+    Layer.provideMerge(
+      AsyncCalc.live(A, { query: () => Effect.succeed(1).pipe(Effect.delay('15 millis')) }),
+    ),
+    Layer.provideMerge(StateGroup.live(Inputs, { seed: 1 })),
+  )
+  return Effect.gen(function* () {
+    const bStore = yield* B.store
+    const store = yield* Gate.store
+    // While B's first load is in flight the boundary MUST still be Pending —
+    // a poisoned latch would already report Ready here.
+    yield* until(() => bStore.get()._tag, (t) => t === 'Loading')
+    expect(store.get()._tag).toBe('Pending')
+    yield* until(() => bStore.get()._tag, (t) => t === 'Success')
+    yield* until(() => store.get()._tag, (t) => t === 'Ready')
+    expect(store.get()._tag).toBe('Ready')
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('once: a covered gate enabling AFTER the latch never re-pends the boundary', () => {
+  // The boot-boundary semantics: a route-gated query (the board) first loads
+  // on a later navigation — its own screen owns that loading state, the shell
+  // splash must not come back.
+  class Route extends State.make('routeFlag', S.Boolean) {}
+  class Inputs extends StateGroup.make(Route) {}
+  class Always extends AsyncCalc.make('Always', {
+    inputs: [StateGroup.select(Inputs, 'routeFlag')],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  class Routed extends AsyncCalc.make('Routed', {
+    inputs: [StateGroup.select(Inputs, 'routeFlag')],
+    output: S.Number,
+  }) {}
+  class Gate extends Boundary.make('Gate', { over: [Always, Routed] }) {}
+  const TestLayer = Boundary.live(Gate, { once: true }).pipe(
+    Layer.provideMerge(
+      Layer.merge(
+        AsyncCalc.live(Always, { query: () => Effect.succeed(1) }),
+        AsyncCalc.live(Routed, {
+          query: () => Effect.succeed(2).pipe(Effect.delay('20 millis')),
+          disabled: ({ routeFlag }) => !routeFlag,
+        }),
+      ),
+    ),
+    Layer.provideMerge(StateGroup.live(Inputs, { routeFlag: false })),
+  )
+  return Effect.gen(function* () {
+    const route = yield* StateGroup.select(Inputs, 'routeFlag').store
+    const routedStore = yield* Routed.store
+    const store = yield* Gate.store
+    yield* until(() => store.get()._tag, (t) => t === 'Ready')
+
+    // "Navigate": the routed query enables and goes Loading — latched Ready holds.
+    route.set(true)
+    yield* until(() => routedStore.get()._tag, (t) => t === 'Loading')
+    expect(store.get()._tag).toBe('Ready')
+    yield* until(() => routedStore.get()._tag, (t) => t === 'Success')
+    expect(store.get()._tag).toBe('Ready')
+  }).pipe(Effect.provide(TestLayer))
+})