on-zero 0.4.31 → 0.4.32

package/src/helpers/recoverZeroClient.ts

@@ -0,0 +1,173 @@
+import type { Emitter } from '@take-out/helpers'
+import type { ZeroEvent } from '../types'
+import type { UpdateNeededReason } from '@rocicorp/zero'
+import type { Context, LogLevel, LogSink } from '@rocicorp/logger'
+
+// per-reason guard window: the SAME reason re-failing right after its reload is
+// surfaced as fatal instead of reload-storming on something the reload can't fix.
+const RECOVER_GUARD_MS = 60_000
+
+// the fatal local-store-loss signature Zero logs when the IndexedDB it expects
+// is gone (evicted, or deleted by another tab).
+const LOCAL_STORE_LOST = 'Expected IndexedDB not found'
+
+export type ZeroRecoveryDeps = {
+  // delete THIS client's local persistent state (its own scoped IDB). pass the
+  // instance's `.delete`. recovery is per-instance, so a combined client drops
+  // EVERY underlying store; the latch below keeps it to one reload.
+  deleteLocalState: () => Promise<unknown>
+  // recovery lifecycle for consumers (preview postMessage, toast, …).
+  zeroEvents: Emitter<ZeroEvent | null>
+  // awaited before the reload — e.g. wait for the dev origin to come back so the
+  // reload doesn't land on a restarting server. optional.
+  beforeReload?: () => Promise<void>
+  // injectable for tests; defaults to a real page reload.
+  reload?: () => void
+}
+
+// one reload per page-load. the local-state deletes that must precede it are
+// collected here so EVERY affected instance (a combined client has several) drops
+// its own store before we reload — not just whichever instance fired first.
+let reloadScheduled = false
+const pendingDeletes: Array<Promise<unknown>> = []
+
+// cross-page-load, per-reason guard: distinct keys mean a NewClientGroup recovery
+// never suppresses a later SchemaVersionNotSupported one. it survives the reload
+// (sessionStorage), so a reason that reloaded then immediately re-fires is caught
+// as a genuine fatal instead of reload-storming across loads.
+function recoveryGuardOpen(reasonKey: string): boolean {
+  try {
+    const key = `on-zero-recover-${reasonKey}`
+    const last = Number(window.sessionStorage.getItem(key) || 0)
+    if (Date.now() - last < RECOVER_GUARD_MS) return false
+    window.sessionStorage.setItem(key, String(Date.now()))
+  } catch {
+    // no sessionStorage (private mode) — fall back to the in-memory latch.
+  }
+  return true
+}
+
+function recover(
+  deps: ZeroRecoveryDeps,
+  reasonKey: string,
+  message: string,
+  dropLocalState: boolean,
+): void {
+  if (typeof window === 'undefined') return
+  // each affected instance drops its OWN stale store, even when a reload is
+  // already queued — otherwise a sibling's store survives the reload and
+  // fatal-loops on the next boot. the single scheduled reload awaits these.
+  if (dropLocalState) {
+    pendingDeletes.push(
+      Promise.resolve()
+        .then(deps.deleteLocalState)
+        .catch(() => {}),
+    )
+  }
+  // only ONE reload per page-load; a later trigger just contributes its delete.
+  if (reloadScheduled) return
+  if (!recoveryGuardOpen(reasonKey)) {
+    console.error(`[on-zero] ${message} — already recovered once, not reloading`)
+    deps.zeroEvents.emit({ type: 'fatal', reason: message })
+    return
+  }
+  reloadScheduled = true
+  console.warn(`[on-zero] ${message} — recovering`)
+  deps.zeroEvents.emit({ type: 'recovering', reason: message })
+  const doReload = deps.reload ?? (() => window.location.reload())
+  // defer one microtask so sibling instances failing in the same tick enqueue
+  // their deletes first, then await them all before reloading.
+  Promise.resolve()
+    .then(() => Promise.allSettled(pendingDeletes))
+    .then(() => deps.beforeReload?.())
+    .catch(() => {})
+    .finally(doReload)
+}
+
+// passing our own onUpdateNeeded/onClientStateNotFound DISABLES Zero's built-in
+// reloadWithReason, so these handlers are the ONLY recovery — they must cover
+// every reason or the app fatal-blanks forever.
+export function makeZeroRecovery(deps: ZeroRecoveryDeps) {
+  return {
+    onUpdateNeeded(reason: UpdateNeededReason) {
+      // every update-needed reason needs new client code → reload. but only
+      // SchemaVersionNotSupported means the local rows are now incompatible:
+      // mirror Zero's own decision (it disables the client group only for that
+      // reason). NewClientGroup / VersionNotSupported are code-version mismatches
+      // whose data is still valid — and delete() there would wipe the IndexedDB
+      // OTHER live tabs of this user share (the store is keyed by user+storageKey,
+      // not per-tab), e.g. the newer tab that triggered NewClientGroup.
+      const dropLocalState = reason.type === 'SchemaVersionNotSupported'
+      recover(
+        deps,
+        reason.type,
+        `update needed (${reason.message || reason.type})`,
+        dropLocalState,
+      )
+    },
+    onClientStateNotFound() {
+      // local/server sync state is gone or rejected — the store is unusable, so
+      // drop it and reload into a fresh client.
+      recover(deps, 'client-state-not-found', 'client state not found', true)
+    },
+  }
+}
+
+// preserve Zero's default console output: we MUST install a logSink to watch for
+// the corruption signature, but doing so replaces Zero's built-in console sink —
+// so when the consumer passes none, mirror Zero's key=value context prefix here
+// instead of silently swallowing every log.
+function logToConsole(
+  level: LogLevel,
+  context: Context | undefined,
+  ...args: unknown[]
+): void {
+  const prefix = context
+    ? Object.entries(context)
+        .map(([key, value]) => (value === undefined ? key : `${key}=${value}`))
+        .join(' ')
+    : ''
+  const method = level === 'debug' ? 'debug' : level
+  console[method](...(prefix ? [prefix] : []), ...args)
+}
+
+// watch error-level logs for the local-store-lost signature (the one fatal Zero
+// surfaces only through the log, not the structured callbacks) and trigger the
+// same recovery. forwards to the consumer sink, or to the console when there is
+// none. wire this ONLY when the consumer didn't pass their own logSink, so a
+// consumer that owns log-based recovery isn't double-fired.
+export function composeRecoveryLogSink(
+  deps: ZeroRecoveryDeps,
+  consumerLogSink?: LogSink,
+): LogSink {
+  const consumerFlush = consumerLogSink?.flush
+  return {
+    log(level: LogLevel, context: Context | undefined, ...args: unknown[]): void {
+      if (consumerLogSink) consumerLogSink.log(level, context, ...args)
+      else logToConsole(level, context, ...args)
+      if (level !== 'error') return
+      const text = args
+        .map((arg) =>
+          typeof arg === 'string'
+            ? arg
+            : arg && typeof arg === 'object' && 'message' in arg
+              ? String((arg as { message: unknown }).message)
+              : '',
+        )
+        .join(' ')
+      if (text.includes(LOCAL_STORE_LOST)) {
+        recover(deps, 'local-store', 'local store lost', true)
+      }
+    },
+    // call through the consumer sink so a class-based sink keeps its `this`,
+    // rather than handing Zero a detached method reference.
+    flush: consumerFlush ? () => consumerFlush.call(consumerLogSink) : undefined,
+  }
+}
+
+// test-only: the reload latch + pending deletes are in-memory (a real page reload
+// clears them); tests simulate that reset between successive "page loads".
+export function resetRecoveryStateForTests() {
+  reloadScheduled = false
+  pendingDeletes.length = 0
+}

package/src/index.ts

@@ -37,3 +37,8 @@ export {
   type ShowZeroClientErrorOptions,
   type ZeroClientErrorInfo,
 } from './helpers/showZeroClientError'
+export {
+  makeZeroRecovery,
+  composeRecoveryLogSink,
+  type ZeroRecoveryDeps,
+} from './helpers/recoverZeroClient'

package/src/multiInstance.test.tsx

@@ -276,9 +276,11 @@ describe('combineZeroClients facade', () => {
     a.zeroEvents.emit({ type: 'error', message: 'from-a' })
     b.zeroEvents.emit({ type: 'error', message: 'from-b' })
 
-    expect(seen.map((event) => event?.message)).toEqual(['from-a', 'from-b'])
+    const messageOf = (event: ZeroEvent | null) =>
+      event?.type === 'error' ? event.message : undefined
+    expect(seen.map(messageOf)).toEqual(['from-a', 'from-b'])
     // the source emitters stay independent of each other
-    expect(a.zeroEvents.value?.message).toBe('from-a')
-    expect(b.zeroEvents.value?.message).toBe('from-b')
+    expect(messageOf(a.zeroEvents.value)).toBe('from-a')
+    expect(messageOf(b.zeroEvents.value)).toBe('from-b')
   })
 })

package/src/multiInstanceNested.test.tsx

@@ -220,7 +220,7 @@ test('direct-path views re-materialize when the owning instance rotates', async
   await waitFor(() => probe.data?.name === 'before-rotation', 'pre-rotation row')
 
   // identity change rotates the mounted zero instance (new client group,
-  // fresh store) — the same mechanism a zeroInstanceGeneration bump uses
+  // fresh store) via the instanceKey change
   await render(<App userID="rot-2" />)
   await waitFor(() => probe.data === undefined, 'view reset to the new empty store')
 

package/src/types.ts

@@ -135,7 +135,12 @@ export type TablePrimaryKeys<TS extends GenericTable> = TupleToUnion<
   GetTableSchema<TS>['primaryKey']
 >
 
-export type ZeroEvent = { type: 'error'; message: string }
+export type ZeroEvent =
+  | { type: 'error'; message: string }
+  // recovery lifecycle: 'recovering' = dropping local state + reloading;
+  // 'fatal' = recovery already attempted (loop guard tripped), not reloading.
+  | { type: 'recovering'; reason: string }
+  | { type: 'fatal'; reason: string }
 
 /**
  * Admin role bypass for permissions:

package/types/createZeroClient.authData.test.d.ts

@@ -0,0 +1,5 @@
+declare global {
+    var IS_REACT_ACT_ENVIRONMENT: boolean | undefined;
+}
+export {};
+//# sourceMappingURL=createZeroClient.authData.test.d.ts.map

package/types/createZeroClient.authData.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createZeroClient.authData.test.d.ts","sourceRoot":"","sources":["../src/createZeroClient.authData.test.tsx"],"names":[],"mappings":"AAeA,OAAO,CAAC,MAAM,CAAC;IAEb,IAAI,wBAAwB,EAAE,OAAO,GAAG,SAAS,CAAA;CAClD"}

package/types/createZeroClient.d.ts

@@ -18,12 +18,13 @@ export declare function createZeroClient<Schema extends ZeroSchema, Models exten
 }): {
     instanceName: string;
     zeroEvents: import("@take-out/helpers").Emitter<ZeroEvent | null>;
-    ProvideZero: ({ children, authData: authDataIn, disable, transport, pullIntervalMs, ...props }: Omit<ZeroOptions<Schema, GetZeroMutators<Models>>, "schema" | "mutators"> & {
+    ProvideZero: ({ children, authData: authDataIn, disable, transport, pullIntervalMs, beforeReload, ...props }: Omit<ZeroOptions<Schema, GetZeroMutators<Models>>, "schema" | "mutators"> & {
         children: ReactNode;
         authData?: AuthData | null;
         disable?: boolean;
         transport?: "http-pull";
         pullIntervalMs?: number;
+        beforeReload?: () => Promise<void>;
     }) => string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react/jsx-runtime").JSX.Element | null | undefined;
     ControlQueries: ({ children, action, whenDisabled, }: {
         children: ReactNode;

package/types/createZeroClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createZeroClient.d.ts","sourceRoot":"","sources":["../src/createZeroClient.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"createZeroClient.d.ts","sourceRoot":"","sources":["../src/createZeroClient.tsx"],"names":[],"mappings":"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"}

package/types/createZeroServer.d.ts

@@ -124,7 +124,7 @@ export declare function createZeroServer<Schema extends ZeroSchema, Models exten
                 clientID: string;
             }[];
             origin: "zeroCache";
-            reason: "parse" | "internal" | "timeout";
+            reason: "parse" | "timeout" | "internal";
         } | {
             mutations: {
                 id: {
@@ -200,7 +200,7 @@ export declare function createZeroServer<Schema extends ZeroSchema, Models exten
                 clientID: string;
             }[];
             origin: "zeroCache";
-            reason: "parse" | "internal" | "timeout";
+            reason: "parse" | "timeout" | "internal";
         };
         asyncTasks: AsyncAction[];
     }>;
@@ -250,7 +250,7 @@ export declare function createZeroServer<Schema extends ZeroSchema, Models exten
             kind: "TransformFailed";
             queryIDs: string[];
             origin: "zeroCache";
-            reason: "parse" | "internal" | "timeout";
+            reason: "parse" | "timeout" | "internal";
         } | ["transformed", ({
             id: string;
             name: string;
@@ -289,7 +289,7 @@ export declare function createZeroServer<Schema extends ZeroSchema, Models exten
             kind: "TransformFailed";
             queryIDs: string[];
             origin: "zeroCache";
-            reason: "parse" | "internal" | "timeout";
+            reason: "parse" | "timeout" | "internal";
         }];
     }>;
     transaction: <CB extends (tx: Transaction) => Promise<any>, Returns extends CB extends (tx: Transaction) => Promise<infer X> ? X : never>(query: CB) => Promise<Returns>;

package/types/helpers/recoverZeroClient.d.ts

@@ -0,0 +1,17 @@
+import type { Emitter } from '@take-out/helpers';
+import type { ZeroEvent } from '../types';
+import type { UpdateNeededReason } from '@rocicorp/zero';
+import type { LogSink } from '@rocicorp/logger';
+export type ZeroRecoveryDeps = {
+    deleteLocalState: () => Promise<unknown>;
+    zeroEvents: Emitter<ZeroEvent | null>;
+    beforeReload?: () => Promise<void>;
+    reload?: () => void;
+};
+export declare function makeZeroRecovery(deps: ZeroRecoveryDeps): {
+    onUpdateNeeded(reason: UpdateNeededReason): void;
+    onClientStateNotFound(): void;
+};
+export declare function composeRecoveryLogSink(deps: ZeroRecoveryDeps, consumerLogSink?: LogSink): LogSink;
+export declare function resetRecoveryStateForTests(): void;
+//# sourceMappingURL=recoverZeroClient.d.ts.map

package/types/helpers/recoverZeroClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recoverZeroClient.d.ts","sourceRoot":"","sources":["../../src/helpers/recoverZeroClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AACzC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AACxD,OAAO,KAAK,EAAqB,OAAO,EAAE,MAAM,kBAAkB,CAAA;AAUlE,MAAM,MAAM,gBAAgB,GAAG;IAI7B,gBAAgB,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;IAExC,UAAU,EAAE,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAA;IAGrC,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAElC,MAAM,CAAC,EAAE,MAAM,IAAI,CAAA;CACpB,CAAA;AAgED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,gBAAgB;2BAE5B,kBAAkB;;EAsB5C;AAyBD,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,gBAAgB,EACtB,eAAe,CAAC,EAAE,OAAO,GACxB,OAAO,CAwBT;AAID,wBAAgB,0BAA0B,SAGzC"}

package/types/helpers/recoverZeroClient.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=recoverZeroClient.test.d.ts.map

package/types/helpers/recoverZeroClient.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recoverZeroClient.test.d.ts","sourceRoot":"","sources":["../../src/helpers/recoverZeroClient.test.ts"],"names":[],"mappings":""}

package/types/index.d.ts

@@ -22,4 +22,5 @@ export { defineQuery, defineQueries } from '@rocicorp/zero';
 export type * from './types';
 export { clearZeroClientData, type ClearZeroClientDataOptions, } from './helpers/clearZeroClientData';
 export { showZeroClientErrorOnce, resetShownZeroClientError, type ShowZeroClientErrorOptions, type ZeroClientErrorInfo, } from './helpers/showZeroClientError';
+export { makeZeroRecovery, composeRecoveryLogSink, type ZeroRecoveryDeps, } from './helpers/recoverZeroClient';
 //# sourceMappingURL=index.d.ts.map

package/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAA;AACnC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,sBAAsB,CAAA;AACpC,cAAc,0BAA0B,CAAA;AACxC,cAAc,0BAA0B,CAAA;AACxC,cAAc,0BAA0B,CAAA;AACxC,cAAc,uBAAuB,CAAA;AACrC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAErD,cAAc,sBAAsB,CAAA;AACpC,cAAc,oBAAoB,CAAA;AAClC,cAAc,qBAAqB,CAAA;AACnC,cAAc,kBAAkB,CAAA;AAChC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,OAAO,CAAA;AACrB,OAAO,EAAE,SAAS,EAAE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAA;AACzD,cAAc,aAAa,CAAA;AAC3B,cAAc,SAAS,CAAA;AACvB,cAAc,eAAe,CAAA;AAC7B,cAAc,OAAO,CAAA;AACrB,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAM3D,mBAAmB,SAAS,CAAA;AAE5B,OAAO,EACL,mBAAmB,EACnB,KAAK,0BAA0B,GAChC,MAAM,+BAA+B,CAAA;AACtC,OAAO,EACL,uBAAuB,EACvB,yBAAyB,EACzB,KAAK,0BAA0B,EAC/B,KAAK,mBAAmB,GACzB,MAAM,+BAA+B,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAA;AACnC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,sBAAsB,CAAA;AACpC,cAAc,0BAA0B,CAAA;AACxC,cAAc,0BAA0B,CAAA;AACxC,cAAc,0BAA0B,CAAA;AACxC,cAAc,uBAAuB,CAAA;AACrC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAErD,cAAc,sBAAsB,CAAA;AACpC,cAAc,oBAAoB,CAAA;AAClC,cAAc,qBAAqB,CAAA;AACnC,cAAc,kBAAkB,CAAA;AAChC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,OAAO,CAAA;AACrB,OAAO,EAAE,SAAS,EAAE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAA;AACzD,cAAc,aAAa,CAAA;AAC3B,cAAc,SAAS,CAAA;AACvB,cAAc,eAAe,CAAA;AAC7B,cAAc,OAAO,CAAA;AACrB,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAM3D,mBAAmB,SAAS,CAAA;AAE5B,OAAO,EACL,mBAAmB,EACnB,KAAK,0BAA0B,GAChC,MAAM,+BAA+B,CAAA;AACtC,OAAO,EACL,uBAAuB,EACvB,yBAAyB,EACzB,KAAK,0BAA0B,EAC/B,KAAK,mBAAmB,GACzB,MAAM,+BAA+B,CAAA;AACtC,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,KAAK,gBAAgB,GACtB,MAAM,6BAA6B,CAAA"}

package/types/types.d.ts

@@ -73,6 +73,12 @@ export type TablePrimaryKeys<TS extends GenericTable> = TupleToUnion<GetTableSch
 export type ZeroEvent = {
     type: 'error';
     message: string;
+} | {
+    type: 'recovering';
+    reason: string;
+} | {
+    type: 'fatal';
+    reason: string;
 };
 /**
  * Admin role bypass for permissions:

package/types/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}