@playfast/reform-query-browser 0.0.2

package/README.md

@@ -0,0 +1,47 @@
+# @playfast/reform-query-browser
+
+Browser host layers for Reform's `AsyncCalc`. Reform core stays renderer-neutral —
+it declares the optional `QueryEvents` (lifecycle signals) and `QueryStore`
+(persistence) seams but contains no DOM. This package implements them over the
+real browser, plus the focus/reconnect auto-invalidation managers built on top.
+
+## What it gives you
+
+- **`QueryEventsBrowser`** — implements `QueryEvents` over `window` focus /
+  `document` visibility / `online`. Falls back to a no-op off the main thread
+  (SSR, workers, tests), so the same app layer is safe everywhere.
+- **`localStorageQueryStore`** — implements `QueryStore` over `localStorage`
+  (JSON, namespaced under `reform-query:`). Provide it to enable `persist` on a
+  calc.
+- **`RefetchOnFocus` / `RefetchOnReconnect`** — managers that invalidate every
+  live query on the matching signal (React-Query's `refetchOnWindowFocus` /
+  `refetchOnReconnect`). Invalidation only marks queries stale; a stale query
+  that's actively read refetches.
+- **`BrowserQueryDefaults`** — focus + reconnect managers pre-wired over
+  `QueryEventsBrowser`, so you only need `Queries` (part of `Engine`) in context.
+
+## Usage
+
+```ts
+import { Engine, AsyncCalc } from '@playfast/reform'
+import { BrowserQueryDefaults, localStorageQueryStore } from '@playfast/reform-query-browser'
+
+// In your app layer, alongside Engine:
+const base = Layer.mergeAll(
+  Engine,
+  BrowserQueryDefaults,    // refetch on focus + reconnect
+  localStorageQueryStore,  // enables `persist`
+  /* your state + calc layers */
+)
+
+// Opt a query into persistence:
+AsyncCalc.live(Todos, { query, persist: { key: 'todos' } })
+
+// Imperative control anywhere you can run an Effect:
+runtime.runFork(AsyncCalc.invalidate(Todos)) // mark stale (refetches if active)
+runtime.runFork(AsyncCalc.refetch(Todos))    // force a run now
+```
+
+All of `QueryEvents`/`QueryStore` are optional: a calc that uses `persist` with no
+`QueryStore` in context (or runs where there's no `window`) simply behaves as if
+the feature were off — no hard requirement is added to your layer.

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@playfast/reform-query-browser",
+  "playbook": "./playbook",
+  "version": "0.0.2",
+  "type": "module",
+  "description": "Browser host layers for Reform's AsyncCalc — window focus/online auto-invalidation and localStorage persistence. Keeps reform core DOM-free: implements the optional QueryEvents and QueryStore seams.",
+  "keywords": [
+    "reform",
+    "effect",
+    "react-query",
+    "persistence",
+    "refetch-on-focus",
+    "layer"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/playfast/reform.git",
+    "directory": "packages/reform-query-browser"
+  },
+  "bugs": {
+    "url": "https://github.com/playfast/reform/issues"
+  },
+  "sideEffects": false,
+  "exports": {
+    "./package.json": "./package.json",
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "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": "*",
+    "@playfast/reform": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+// `@playfast/reform-query-browser` — browser host layers for AsyncCalc's optional
+// seams. Reform core stays DOM-free; these layers implement `QueryEvents`
+// (window focus/online) and `QueryStore` (localStorage), plus the focus/reconnect
+// auto-invalidation managers built on them. Provide them alongside `Engine`.
+
+export { QueryEventsBrowser } from './queryEvents.browser'
+export { localStorageQueryStore } from './localStorage.store'
+export { BrowserQueryDefaults, RefetchOnFocus, RefetchOnReconnect } from './refetchManagers'

package/src/localStorage.store.ts

@@ -0,0 +1,40 @@
+import { QueryStore, type QueryStoreApi, noopQueryStore } from '@playfast/reform'
+import { Effect, Layer, Option } from 'effect'
+
+// `QueryStore` implemented over `localStorage` (JSON values under a namespace
+// prefix). The driver hands already-`output`-encoded values across this seam, so
+// JSON round-trips faithfully; a corrupt/absent entry reads as `None` and the
+// query just fetches fresh. Off the main thread it falls back to the no-op store.
+
+const PREFIX = 'reform-query:'
+
+const parse = (raw: string): Option.Option<unknown> => {
+  try {
+    return Option.some(JSON.parse(raw))
+  } catch {
+    // A hand-edited or version-skewed entry: treat as a cache miss, fetch fresh.
+    return Option.none()
+  }
+}
+
+const makeApi = (): QueryStoreApi => {
+  if (typeof window === 'undefined' || typeof localStorage === 'undefined') return noopQueryStore
+  return {
+    get: (key) =>
+      Effect.sync(() => {
+        const raw = localStorage.getItem(PREFIX + key)
+        return raw === null ? Option.none() : parse(raw)
+      }),
+    set: (key, value) =>
+      Effect.sync(() => {
+        localStorage.setItem(PREFIX + key, JSON.stringify(value))
+      }),
+    remove: (key) =>
+      Effect.sync(() => {
+        localStorage.removeItem(PREFIX + key)
+      }),
+  }
+}
+
+/** A `QueryStore` backed by `window.localStorage`. Provide it to enable `persist`. */
+export const localStorageQueryStore: Layer.Layer<QueryStore> = Layer.succeed(QueryStore, makeApi())

package/src/queryEvents.browser.ts

@@ -0,0 +1,54 @@
+import { QueryEvents, type QueryEventsApi, noopQueryEvents } from '@playfast/reform'
+import { Effect, Layer } from 'effect'
+
+// `QueryEvents` implemented over the browser: window focus/visibility drives the
+// focus signal, `online` drives the reconnect signal. This is the only place the
+// DOM is touched — reform core stays renderer-neutral. Off the main thread (SSR,
+// a worker, a test with no `window`), it falls back to the inert no-op source, so
+// the same app layer is safe everywhere.
+
+/** A browser-backed `QueryEvents`, scoped so the window listeners are removed with the layer. */
+export const QueryEventsBrowser: Layer.Layer<QueryEvents> = Layer.scoped(
+  QueryEvents,
+  Effect.gen(function* () {
+    if (typeof window === 'undefined') return noopQueryEvents
+
+    const focusListeners = new Set<() => void>()
+    const onlineListeners = new Set<() => void>()
+    const fire = (listeners: ReadonlySet<() => void>) => {
+      for (const listener of listeners) listener()
+    }
+    // Refocus and tab-becomes-visible both count as "focus"; ignore the
+    // visibility event that fires on hide.
+    const onFocus = () => {
+      if (document.visibilityState === 'visible') fire(focusListeners)
+    }
+    const onOnline = () => fire(onlineListeners)
+
+    // `visibilitychange` targets `document`; `focus`/`online` target `window`.
+    document.addEventListener('visibilitychange', onFocus)
+    window.addEventListener('focus', onFocus)
+    window.addEventListener('online', onOnline)
+    yield* Effect.addFinalizer(() =>
+      Effect.sync(() => {
+        document.removeEventListener('visibilitychange', onFocus)
+        window.removeEventListener('focus', onFocus)
+        window.removeEventListener('online', onOnline)
+      }),
+    )
+
+    const subscribeTo =
+      (listeners: Set<() => void>) =>
+      (listener: () => void): (() => void) => {
+        listeners.add(listener)
+        return () => {
+          listeners.delete(listener)
+        }
+      }
+    const api: QueryEventsApi = {
+      subscribeFocus: subscribeTo(focusListeners),
+      subscribeOnline: subscribeTo(onlineListeners),
+    }
+    return api
+  }),
+)

package/src/refetchManagers.ts

@@ -0,0 +1,44 @@
+import { QueryEvents, type QueryEventsApi, Queries } from '@playfast/reform'
+import { Effect, Layer } from 'effect'
+import { QueryEventsBrowser } from './queryEvents.browser'
+
+// Auto-invalidation managers: a window signal (focus / reconnect) invalidates
+// every live query, so stale + actively-read queries refetch (React-Query's
+// `refetchOnWindowFocus` / `refetchOnReconnect`). They are pure routers — the
+// signal comes from `QueryEvents`, the act is `handle.invalidate()` on the
+// `Queries` registry — so nothing here touches the DOM directly.
+
+const onSignal = (
+  pick: (events: QueryEventsApi) => (listener: () => void) => () => void,
+): Layer.Layer<never, never, QueryEvents | Queries> =>
+  Layer.scopedDiscard(
+    Effect.gen(function* () {
+      const events = yield* QueryEvents
+      const queries = yield* Queries
+      const invalidateAll = () => {
+        for (const handle of queries.byName.values()) handle.invalidate()
+      }
+      const unsubscribe = pick(events)(invalidateAll)
+      yield* Effect.addFinalizer(() => Effect.sync(unsubscribe))
+    }),
+  )
+
+/** Invalidate every live query when the window regains focus. Requires `QueryEvents`. */
+export const RefetchOnFocus: Layer.Layer<never, never, QueryEvents | Queries> = onSignal(
+  (events) => events.subscribeFocus,
+)
+
+/** Invalidate every live query when the network reconnects. Requires `QueryEvents`. */
+export const RefetchOnReconnect: Layer.Layer<never, never, QueryEvents | Queries> = onSignal(
+  (events) => events.subscribeOnline,
+)
+
+/**
+ * The common browser default: focus + reconnect auto-invalidation wired over the
+ * browser `QueryEvents`, so the app only needs `Queries` (part of `Engine`) in
+ * context. Merge it alongside `Engine`; add `localStorageQueryStore` to persist.
+ */
+export const BrowserQueryDefaults: Layer.Layer<never, never, Queries> = Layer.mergeAll(
+  RefetchOnFocus,
+  RefetchOnReconnect,
+).pipe(Layer.provide(QueryEventsBrowser))

package/src/reform-query-browser.test.ts

@@ -0,0 +1,80 @@
+/**
+ * @vitest-environment happy-dom
+ *
+ * The browser host layers, end to end over a real (happy-dom) window: window
+ * focus invalidates live queries (so an actively-read query refetches), and
+ * `persist` hydrates from / writes through `localStorage` — with reform core
+ * never touching the DOM.
+ */
+import { expect, it } from '@effect/vitest'
+import { AsyncCalc, Engine, State, StateGroup } from '@playfast/reform'
+import { Duration, Effect, Layer, Schema as S } from 'effect'
+import { localStorageQueryStore } from './localStorage.store'
+import { QueryEventsBrowser } from './queryEvents.browser'
+import { RefetchOnFocus } from './refetchManagers'
+
+const tick = (ms = 10) => Effect.sleep(Duration.millis(ms))
+
+it.live('window focus invalidates a live query, so an active reader refetches', () => {
+  class Count extends State.make('count', S.Number) {}
+  class Inputs extends StateGroup.make(Count) {}
+  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
+      }).pipe(Effect.delay(Duration.millis(10))),
+  })
+  const App = Layer.mergeAll(QLive, RefetchOnFocus).pipe(
+    Layer.provideMerge(QueryEventsBrowser),
+    Layer.provideMerge(StateGroup.live(Inputs, { count: 1 })),
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    const store = yield* Q.store
+    store.subscribe(() => {}) // an active reader (a mounted view)
+    yield* tick(30)
+    expect(runs.n).toBe(1)
+
+    // A focus event invalidates the query; stale + active ⇒ refetch.
+    window.dispatchEvent(new Event('focus'))
+    yield* tick(30)
+    expect(runs.n).toBe(2)
+  }).pipe(Effect.provide(App))
+})
+
+it.live('persist hydrates from localStorage (stale) then writes the settled value through', () => {
+  localStorage.setItem('reform-query:P', '99') // a previously-persisted value
+  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,
+    alwaysOn: true,
+  }) {}
+  const QLive = AsyncCalc.live(Q, {
+    query: ({ count }) => Effect.succeed(count * 2).pipe(Effect.delay(Duration.millis(20))),
+    persist: { key: 'P' },
+  })
+  const App = QLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { count: 5 })),
+    Layer.provideMerge(localStorageQueryStore),
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    const view = yield* Q.store
+    expect(view.get()).toMatchObject({ _tag: 'Success', value: 99, refetching: true })
+
+    yield* tick(40)
+    expect(view.get()).toMatchObject({ _tag: 'Success', value: 10, refetching: false })
+    expect(localStorage.getItem('reform-query:P')).toBe('10')
+  }).pipe(Effect.provide(App))
+})