@playfast/reform 0.0.5 → 0.0.8

package/src/calc/asyncCalc.test.ts

@@ -0,0 +1,556 @@
+import { expect, it } from '@effect/vitest'
+import { Data, Duration, Effect, Layer, Schema as S } from 'effect'
+import { AsyncCalc, Engine, Event, State, StateGroup } from '../index'
+
+// AsyncCalc is a derived store whose value is the lifecycle of an Effect. It runs
+// the query reactively from its inputs (latest-wins), keeps the last value while
+// re-fetching (stale-while-revalidate), and goes Idle when a gated query disables.
+
+const tick = (ms = 10) => Effect.sleep(Duration.millis(ms))
+
+// Poll until the predicate holds (bounded) — for assertions that race real
+// timers under parallel-suite host load, where a fixed `tick` budget flakes.
+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('runs the query and resolves Loading -> Success', () => {
+  class Count extends State.make('count', S.Number) {}
+  class Inputs extends StateGroup.make(Count) {}
+  class Doubled extends AsyncCalc.make('Doubled', {
+    inputs: [StateGroup.select(Inputs, 'count')],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  const DoubledLive = AsyncCalc.live(Doubled, {
+    query: ({ count }) => Effect.succeed(count * 2).pipe(Effect.delay(Duration.millis(20))),
+  })
+  const TestLayer = DoubledLive.pipe(Layer.provideMerge(StateGroup.live(Inputs, { count: 5 })))
+
+  return Effect.gen(function* () {
+    const store = yield* Doubled.store
+    // Before the forked query resolves, the value is Loading.
+    expect(store.get()._tag).toBe('Loading')
+    yield* tick(40)
+    const value = store.get()
+    expect(value._tag).toBe('Success')
+    if (value._tag === 'Success') {
+      expect(value.value).toBe(10)
+      expect(value.refetching).toBe(false)
+    }
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('a failing query resolves to Error carrying the failure', () => {
+  class Count extends State.make('count', S.Number) {}
+  class Inputs extends StateGroup.make(Count) {}
+  class Q extends AsyncCalc.make('Q', {
+    inputs: [StateGroup.select(Inputs, 'count')],
+    output: S.Number,
+    error: S.instanceOf(Boom),
+    alwaysOn: true,
+  }) {}
+  const QLive = AsyncCalc.live(Q, {
+    query: () => Effect.fail(new Boom({ message: 'nope' })),
+  })
+  const TestLayer = QLive.pipe(Layer.provideMerge(StateGroup.live(Inputs, { count: 1 })))
+
+  return Effect.gen(function* () {
+    const store = yield* Q.store
+    yield* tick()
+    const value = store.get()
+    expect(value._tag).toBe('Error')
+    if (value._tag === 'Error') {
+      expect(value.error.message).toBe('nope')
+      expect(value.refetching).toBe(false)
+    }
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('a dependency change re-fetches, keeping the last value with refetching: true', () => {
+  class Count extends State.make('count', S.Number) {}
+  class Inputs extends StateGroup.make(Count) {}
+  class Doubled extends AsyncCalc.make('Doubled', {
+    inputs: [StateGroup.select(Inputs, 'count')],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  const DoubledLive = AsyncCalc.live(Doubled, {
+    query: ({ count }) => Effect.succeed(count * 2).pipe(Effect.delay(Duration.millis(20))),
+  })
+  const TestLayer = DoubledLive.pipe(Layer.provideMerge(StateGroup.live(Inputs, { count: 5 })))
+
+  return Effect.gen(function* () {
+    const source = yield* StateGroup.select(Inputs, 'count').store
+    const store = yield* Doubled.store
+    yield* tick(40)
+    expect(store.get()).toMatchObject({ _tag: 'Success', value: 10, refetching: false })
+
+    // Move the input: the prior value is kept while the new fetch is in flight.
+    source.set(7)
+    yield* tick(5)
+    expect(store.get()).toMatchObject({ _tag: 'Success', value: 10, refetching: true })
+
+    yield* tick(40)
+    expect(store.get()).toMatchObject({ _tag: 'Success', value: 14, refetching: false })
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('latest-wins: a rapid second change cancels the in-flight run', () => {
+  class Count extends State.make('count', S.Number) {}
+  class Inputs extends StateGroup.make(Count) {}
+  const runs = { n: 0 }
+  class Doubled extends AsyncCalc.make('Doubled', {
+    inputs: [StateGroup.select(Inputs, 'count')],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  const DoubledLive = AsyncCalc.live(Doubled, {
+    query: ({ count }) =>
+      Effect.sync(() => {
+        runs.n += 1
+        return count * 2
+      }).pipe(Effect.delay(Duration.millis(25))),
+  })
+  const TestLayer = DoubledLive.pipe(Layer.provideMerge(StateGroup.live(Inputs, { count: 1 })))
+
+  return Effect.gen(function* () {
+    const source = yield* StateGroup.select(Inputs, 'count').store
+    const store = yield* Doubled.store
+    yield* tick(40)
+    expect(store.get()).toMatchObject({ _tag: 'Success', value: 2 })
+
+    // Two changes in quick succession: the first run is switched out before it
+    // can write, so only the latest value lands (poll — fixed sleeps flake when
+    // a loaded host starves the 25ms query timer).
+    source.set(3)
+    yield* tick(5)
+    source.set(4)
+    const settled = yield* until(
+      () => store.get(),
+      (v) => v._tag === 'Success' && v.refetching === false && v.value !== 2,
+    )
+    expect(settled).toMatchObject({ _tag: 'Success', value: 8 })
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('a gated query starts Idle while disabled and runs once enabled', () => {
+  class Count extends State.make('count', S.Number) {}
+  class Inputs extends StateGroup.make(Count) {}
+  class Doubled extends AsyncCalc.make('Doubled', {
+    inputs: [StateGroup.select(Inputs, 'count')],
+    output: S.Number,
+  }) {}
+  const DoubledLive = AsyncCalc.live(Doubled, {
+    query: ({ count }) => Effect.succeed(count * 2),
+    disabled: ({ count }) => count < 0,
+  })
+  const TestLayer = DoubledLive.pipe(Layer.provideMerge(StateGroup.live(Inputs, { count: -1 })))
+
+  return Effect.gen(function* () {
+    const source = yield* StateGroup.select(Inputs, 'count').store
+    const store = yield* Doubled.store
+    yield* tick()
+    expect(store.get()._tag).toBe('Idle')
+
+    source.set(5)
+    yield* tick()
+    expect(store.get()).toMatchObject({ _tag: 'Success', value: 10 })
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('invalidateBy: an input change outside the key does not re-fetch', () => {
+  class Status extends State.make('status', S.String) {}
+  class Page extends State.make('page', S.Number) {}
+  class Inputs extends StateGroup.make(Status, Page) {}
+  const runs = { n: 0 }
+  class Q extends AsyncCalc.make('Q', {
+    inputs: [StateGroup.select(Inputs, 'status'), StateGroup.select(Inputs, 'page')],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  const QLive = AsyncCalc.live(Q, {
+    query: ({ page }) =>
+      Effect.sync(() => {
+        runs.n += 1
+        return page
+      }),
+    // Only `page` is part of the key; `status` churn must not re-fetch.
+    invalidateBy: ({ page }) => [page],
+  })
+  const TestLayer = QLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { status: 'a', page: 1 })),
+  )
+
+  return Effect.gen(function* () {
+    const status = yield* StateGroup.select(Inputs, 'status').store
+    const page = yield* StateGroup.select(Inputs, 'page').store
+    const store = yield* Q.store
+    yield* tick()
+    expect(runs.n).toBe(1)
+
+    // status moves, key unchanged -> no re-fetch.
+    status.set('b')
+    yield* tick()
+    expect(runs.n).toBe(1)
+
+    // page moves, key changes -> one re-fetch.
+    page.set(2)
+    yield* tick()
+    expect(runs.n).toBe(2)
+    expect(store.get()).toMatchObject({ _tag: 'Success', value: 2 })
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('reuse: a refetch returning mostly-equal data keeps unchanged element identities', () => {
+  class Page extends State.make('page', S.Number) {}
+  class Inputs extends StateGroup.make(Page) {}
+  const Row = S.Struct({ id: S.Number, name: S.String })
+  class Rows extends AsyncCalc.make('Rows', {
+    inputs: [StateGroup.select(Inputs, 'page')],
+    output: S.Array(Row),
+    alwaysOn: true,
+  }) {}
+  const RowsLive = AsyncCalc.live(Rows, {
+    // Fresh objects every run — only the row matching `page` differs.
+    query: ({ page }) =>
+      Effect.succeed([
+        { id: 1, name: 'one' },
+        { id: 2, name: page > 1 ? `two@${page}` : 'two' },
+      ]),
+    reuse: true,
+  })
+  const TestLayer = RowsLive.pipe(Layer.provideMerge(StateGroup.live(Inputs, { page: 1 })))
+
+  return Effect.gen(function* () {
+    const source = yield* StateGroup.select(Inputs, 'page').store
+    const store = yield* Rows.store
+    const first = yield* until(() => store.get(), (v) => v._tag === 'Success')
+    if (first._tag !== 'Success') return
+
+    source.set(2)
+    const second = yield* until(
+      () => store.get(),
+      (v) => v._tag === 'Success' && v.refetching === false && v.value !== first.value,
+    )
+    if (second._tag !== 'Success') return
+    // Row 1 didn't move: same identity. Row 2 did: fresh.
+    expect(second.value[0]).toBe(first.value[0])
+    expect(second.value[1]).not.toBe(first.value[1])
+    expect(second.value[1]).toEqual({ id: 2, name: 'two@2' })
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('coalesce trailing: a burst during one flight completes it and runs ONE trailing refetch', () => {
+  class Count extends State.make('count', S.Number) {}
+  class Inputs extends StateGroup.make(Count) {}
+  // Completion log: the sync body runs AFTER the delay, so the order proves
+  // which runs actually finished (and that the in-flight one was not cancelled).
+  const completed: number[] = []
+  class Doubled extends AsyncCalc.make('Doubled', {
+    inputs: [StateGroup.select(Inputs, 'count')],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  const DoubledLive = AsyncCalc.live(Doubled, {
+    query: ({ count }) =>
+      Effect.sync(() => {
+        completed.push(count)
+        return count * 2
+      }).pipe(Effect.delay(Duration.millis(25))),
+    coalesce: 'trailing',
+  })
+  const TestLayer = DoubledLive.pipe(Layer.provideMerge(StateGroup.live(Inputs, { count: 1 })))
+
+  return Effect.gen(function* () {
+    const source = yield* StateGroup.select(Inputs, 'count').store
+    const store = yield* Doubled.store
+    yield* until(() => store.get(), (v) => v._tag === 'Success')
+    expect(completed).toEqual([1])
+
+    // Three key changes during the first change's flight: the in-flight run (2)
+    // completes and lands, the middle change (3) is conflated away, and exactly
+    // one trailing run fetches the latest key (4).
+    source.set(2)
+    yield* tick(5)
+    source.set(3)
+    yield* tick(5)
+    source.set(4)
+    const settled = yield* until(
+      () => store.get(),
+      (v) => v._tag === 'Success' && v.refetching === false && v.value === 8,
+    )
+    expect(settled).toMatchObject({ _tag: 'Success', value: 8, refetching: false })
+    expect(completed).toEqual([1, 2, 4])
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('coalesce trailing: the stale settle re-flags refetching until the trailing run lands', () => {
+  class Count extends State.make('count', S.Number) {}
+  class Inputs extends StateGroup.make(Count) {}
+  class Doubled extends AsyncCalc.make('Doubled', {
+    inputs: [StateGroup.select(Inputs, 'count')],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  const DoubledLive = AsyncCalc.live(Doubled, {
+    query: ({ count }) => Effect.succeed(count * 2).pipe(Effect.delay(Duration.millis(30))),
+    coalesce: 'trailing',
+  })
+  const TestLayer = DoubledLive.pipe(Layer.provideMerge(StateGroup.live(Inputs, { count: 1 })))
+
+  return Effect.gen(function* () {
+    const source = yield* StateGroup.select(Inputs, 'count').store
+    const store = yield* Doubled.store
+    yield* until(() => store.get(), (v) => v._tag === 'Success')
+
+    // Two changes: when the in-flight result (4) lands, a trailing run is still
+    // pending — the value must read as syncing, not settled.
+    source.set(2)
+    yield* tick(5)
+    source.set(3)
+    const midflight = yield* until(
+      () => store.get(),
+      (v) => v._tag === 'Success' && v.value === 4,
+    )
+    expect(midflight).toMatchObject({ _tag: 'Success', value: 4, refetching: true })
+
+    const settled = yield* until(
+      () => store.get(),
+      (v) => v._tag === 'Success' && v.refetching === false,
+    )
+    expect(settled).toMatchObject({ _tag: 'Success', value: 6 })
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('coalesce trailing: a disable while a request waits in the slot skips the run', () => {
+  class Count extends State.make('count', S.Number) {}
+  class Inputs extends StateGroup.make(Count) {}
+  const completed: number[] = []
+  class Q extends AsyncCalc.make('Q', {
+    inputs: [StateGroup.select(Inputs, 'count')],
+    output: S.Number,
+  }) {}
+  const QLive = AsyncCalc.live(Q, {
+    query: ({ count }) =>
+      Effect.sync(() => {
+        completed.push(count)
+        return count * 2
+      }).pipe(Effect.delay(Duration.millis(25))),
+    disabled: ({ count }) => count < 0,
+    coalesce: 'trailing',
+  })
+  const TestLayer = QLive.pipe(Layer.provideMerge(StateGroup.live(Inputs, { count: 1 })))
+
+  return Effect.gen(function* () {
+    const source = yield* StateGroup.select(Inputs, 'count').store
+    const store = yield* Q.store
+    yield* until(() => store.get(), (v) => v._tag === 'Success')
+
+    // 2 starts a flight, 3 waits in the slot, then the gate closes: the flight's
+    // stale result must not land (Idle), and the queued request must not run.
+    source.set(2)
+    yield* tick(5)
+    source.set(3)
+    yield* tick(2)
+    source.set(-1)
+    yield* tick(60)
+    expect(store.get()._tag).toBe('Idle')
+    expect(completed).toEqual([1, 2])
+
+    // Re-enabling re-runs (the driver forgot its key when switched off).
+    source.set(5)
+    const settled = yield* until(() => store.get(), (v) => v._tag === 'Success')
+    expect(settled).toMatchObject({ _tag: 'Success', value: 10 })
+    expect(completed).toEqual([1, 2, 5])
+  }).pipe(Effect.provide(TestLayer))
+})
+
+// `invalidateOn` is sugar for a hidden revision state + reducer appended to the
+// key — these proofs need the Engine (the Reducers registry + bus + drain loop).
+
+it.live('invalidateOn: dispatching a listed event re-fetches with refetching: true', () => {
+  class Count extends State.make('count', S.Number) {}
+  class Inputs extends StateGroup.make(Count) {}
+  class Poke extends Event.make('Poke', S.Struct({})) {}
+  const runs = { n: 0 }
+  class Q extends AsyncCalc.make('Q', {
+    inputs: [StateGroup.select(Inputs, 'count')],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  const QLive = AsyncCalc.live(Q, {
+    query: ({ count }) =>
+      Effect.sync(() => {
+        runs.n += 1
+        return count * 2
+      }).pipe(Effect.delay(Duration.millis(15))),
+    invalidateOn: [Poke],
+  })
+  const TestLayer = QLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { count: 2 })),
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    const store = yield* Q.store
+    yield* tick(30)
+    expect(store.get()).toMatchObject({ _tag: 'Success', value: 4, refetching: false })
+    expect(runs.n).toBe(1)
+
+    // The fact lands: the hidden revision bumps, the key moves, the value is
+    // kept while the re-fetch is in flight (SWR), then settles.
+    yield* Event.dispatch(Poke, {})
+    yield* tick(5)
+    expect(store.get()).toMatchObject({ _tag: 'Success', value: 4, refetching: true })
+    yield* tick(30)
+    expect(store.get()).toMatchObject({ _tag: 'Success', value: 4, refetching: false })
+    expect(runs.n).toBe(2)
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('invalidateOn: composes with invalidateBy — non-key churn stays inert, the event re-fetches', () => {
+  class Status extends State.make('status', S.String) {}
+  class Page extends State.make('page', S.Number) {}
+  class Inputs extends StateGroup.make(Status, Page) {}
+  class Poke extends Event.make('Poke', S.Struct({})) {}
+  const runs = { n: 0 }
+  class Q extends AsyncCalc.make('Q', {
+    inputs: [StateGroup.select(Inputs, 'status'), StateGroup.select(Inputs, 'page')],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  const QLive = AsyncCalc.live(Q, {
+    query: ({ page }) =>
+      Effect.sync(() => {
+        runs.n += 1
+        return page
+      }),
+    invalidateBy: ({ page }) => [page],
+    invalidateOn: [Poke],
+  })
+  const TestLayer = QLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { status: 'a', page: 1 })),
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    const status = yield* StateGroup.select(Inputs, 'status').store
+    yield* tick()
+    expect(runs.n).toBe(1)
+
+    // Outside the user key: still no re-fetch (the hidden revision rides along
+    // WITHOUT widening the key to every input).
+    status.set('b')
+    yield* tick()
+    expect(runs.n).toBe(1)
+
+    // The listed event always re-fetches.
+    yield* Event.dispatch(Poke, {})
+    yield* tick()
+    expect(runs.n).toBe(2)
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('invalidateOn: a listed event while disabled stays Idle, and enabling re-fetches once', () => {
+  class Count extends State.make('count', S.Number) {}
+  class Inputs extends StateGroup.make(Count) {}
+  class Poke extends Event.make('Poke', S.Struct({})) {}
+  const runs = { n: 0 }
+  class Q extends AsyncCalc.make('Q', {
+    inputs: [StateGroup.select(Inputs, 'count')],
+    output: S.Number,
+  }) {}
+  const QLive = AsyncCalc.live(Q, {
+    query: ({ count }) =>
+      Effect.sync(() => {
+        runs.n += 1
+        return count * 2
+      }),
+    disabled: ({ count }) => count < 0,
+    invalidateOn: [Poke],
+  })
+  const TestLayer = QLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { count: -1 })),
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    const source = yield* StateGroup.select(Inputs, 'count').store
+    const store = yield* Q.store
+    yield* tick()
+    expect(store.get()._tag).toBe('Idle')
+
+    // A bump while gated off runs nothing — the driver shows Idle and forgets
+    // its key, so the eventual enable always re-runs.
+    yield* Event.dispatch(Poke, {})
+    yield* tick()
+    expect(store.get()._tag).toBe('Idle')
+    expect(runs.n).toBe(0)
+
+    source.set(5)
+    yield* tick()
+    expect(store.get()).toMatchObject({ _tag: 'Success', value: 10 })
+    expect(runs.n).toBe(1)
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('invalidateOn: two async calcs keep independent hidden revisions', () => {
+  class Count extends State.make('count', S.Number) {}
+  class Inputs extends StateGroup.make(Count) {}
+  class PokeA extends Event.make('PokeA', S.Struct({})) {}
+  class PokeB extends Event.make('PokeB', S.Struct({})) {}
+  const runs = { a: 0, b: 0 }
+  class QA extends AsyncCalc.make('QA', {
+    inputs: [StateGroup.select(Inputs, 'count')],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  class QB extends AsyncCalc.make('QB', {
+    inputs: [StateGroup.select(Inputs, 'count')],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  const TestLayer = Layer.mergeAll(
+    AsyncCalc.live(QA, {
+      query: ({ count }) =>
+        Effect.sync(() => {
+          runs.a += 1
+          return count
+        }),
+      invalidateOn: [PokeA],
+    }),
+    AsyncCalc.live(QB, {
+      query: ({ count }) =>
+        Effect.sync(() => {
+          runs.b += 1
+          return count
+        }),
+      invalidateOn: [PokeB],
+    }),
+  ).pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { count: 1 })),
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    yield* tick()
+    expect(runs).toEqual({ a: 1, b: 1 })
+
+    // Each calc's hidden revision is namespaced by its own name: A's fact moves
+    // only A.
+    yield* Event.dispatch(PokeA, {})
+    yield* tick()
+    expect(runs).toEqual({ a: 2, b: 1 })
+
+    yield* Event.dispatch(PokeB, {})
+    yield* tick()
+    expect(runs).toEqual({ a: 2, b: 2 })
+  }).pipe(Effect.provide(TestLayer))
+})

package/src/calc/asyncData.ts

@@ -60,12 +60,20 @@ const error = <E>(err: E, refetching = false): AsyncError<E> => ({
   refetching,
 })
 
+/** The arm-constructor namespace exposed as `AsyncData`. */
+export interface AsyncDataConstructors {
+  readonly idle: AsyncIdle
+  readonly loading: AsyncLoading
+  readonly success: <A>(value: A, refetching?: boolean) => AsyncSuccess<A>
+  readonly error: <E>(err: E, refetching?: boolean) => AsyncError<E>
+}
+
 /**
  * Constructors for the arms, namespaced under the same name as the type so call
  * sites read `AsyncData.success(v)` / `AsyncData.error(e)` — no `error` import
  * shadowing the keyword and one obvious home for every arm.
  */
-export const AsyncData = { idle, loading, success, error } as const
+export const AsyncData: AsyncDataConstructors = { idle, loading, success, error }
 
 /**
  * Narrow the live store (which holds the full `AnyAsyncData` union) to the arms