@playfast/reform-query-browser 0.1.0 → 1.0.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@playfast/reform-query-browser",
   "playbook": "./playbook",
-  "version": "0.1.0",
+  "version": "1.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": [

package/src/index.ts

@@ -1,8 +1,3 @@
-// `@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

@@ -1,15 +1,10 @@
 import { QueryStore, type QueryStoreApi, noopQueryStore } from '@playfast/reform'
 import { Effect, Layer, Option, Schema } 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 JsonValue = Schema.parseJson(Schema.Unknown)
-// A hand-edited or version-skewed entry fails to decode → `None`: a cache miss, fetch fresh.
+// Corrupt/version-skewed entry → None (cache miss); fetch fresh.
 const decodeJson = Schema.decodeUnknownOption(JsonValue)
 const encodeJson = Schema.encodeSync(JsonValue)
 
@@ -34,5 +29,4 @@ const makeApi = (): QueryStoreApi => {
   }
 }
 
-/** 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

@@ -1,13 +1,6 @@
 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* () {
@@ -20,8 +13,7 @@ export const QueryEventsBrowser: Layer.Layer<QueryEvents> = Layer.scoped(
     const fire = (listeners: ReadonlySet<() => void>) => {
       listeners.forEach((listener) => listener())
     }
-    // Refocus and tab-becomes-visible both count as "focus"; ignore the
-    // visibility event that fires on hide.
+    // Focus + tab-visible both fire; ignore hide visibilitychange.
     const onFocus = () => {
       if (document.visibilityState === 'visible') {
         fire(focusListeners)
@@ -29,7 +21,6 @@ export const QueryEventsBrowser: Layer.Layer<QueryEvents> = Layer.scoped(
     }
     const onOnline = () => fire(onlineListeners)
 
-    // `visibilitychange` targets `document`; `focus`/`online` target `window`.
     document.addEventListener('visibilitychange', onFocus)
     window.addEventListener('focus', onFocus)
     window.addEventListener('online', onOnline)

package/src/refetchManagers.ts

@@ -2,12 +2,6 @@ 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> =>
@@ -23,21 +17,14 @@ const onSignal = (
     }),
   )
 
-/** 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,

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

@@ -1,10 +1,5 @@
 /**
  * @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'
@@ -13,7 +8,11 @@ import { localStorageQueryStore } from './localStorage.store'
 import { QueryEventsBrowser } from './queryEvents.browser'
 import { RefetchOnFocus } from './refetchManagers'
 
-const tick = (ms = 10) => Effect.sleep(Duration.millis(ms))
+const waitUntil = (predicate: () => boolean) =>
+  Effect.sleep(Duration.millis(5)).pipe(
+    Effect.repeat({ until: predicate }),
+    Effect.timeout(Duration.seconds(2)),
+  )
 
 it.live('window focus invalidates a live query, so an active reader refetches', () => {
   class Count extends State.make('count', S.Number) {}
@@ -40,12 +39,11 @@ it.live('window focus invalidates a live query, so an active reader refetches',
   return Effect.gen(function* () {
     const store = yield* Q.store
     store.subscribe(() => {}) // an active reader (a mounted view)
-    yield* tick(30)
+    yield* waitUntil(() => runs.n === 1)
     expect(runs.n).toBe(1)
 
-    // A focus event invalidates the query; stale + active ⇒ refetch.
     window.dispatchEvent(new Event('focus'))
-    yield* tick(30)
+    yield* waitUntil(() => runs.n === 2)
     expect(runs.n).toBe(2)
   }).pipe(Effect.provide(App))
 })
@@ -73,7 +71,7 @@ it.live('persist hydrates from localStorage (stale) then writes the settled valu
     const view = yield* Q.store
     expect(view.get()).toMatchObject({ _tag: 'Success', value: 99, refetching: true })
 
-    yield* tick(40)
+    yield* waitUntil(() => localStorage.getItem('reform-query:P') === '10')
     expect(view.get()).toMatchObject({ _tag: 'Success', value: 10, refetching: false })
     expect(localStorage.getItem('reform-query:P')).toBe('10')
   }).pipe(Effect.provide(App))