@rindle/optimistic 0.2.0 → 0.3.1

package/src/client.ts

@@ -20,7 +20,7 @@ import { initWasm } from "@rindle/wasm";
 
 import type { OptimisticBackend } from "./backend.ts";
 import type { ClientRegistry, MutationTx } from "./backend.ts";
-import { stableClientID } from "./client-id.ts";
+import { resetStableClientID, stableClientID } from "./client-id.ts";
 import { createOptimisticStore, type MutateFn } from "./index.ts";
 import type { Store } from "@rindle/client";
 
@@ -58,6 +58,13 @@ export interface RindleClientOptions<S extends ColsMap, R extends ClientRegistry
   /** A policy rejection's reason (the prediction's snap-back rides the lmid release). */
   onRejected?: (envelope: MutationEnvelope, reason: string) => void;
   queue?: { maxBatch?: number; retryDelayMs?: (attempt: number) => number };
+  /** Development-only recovery knobs. Keep off in production: a mutation gap means state loss
+   *  or two writers sharing a clientID, and should be investigated. */
+  dev?: {
+    /** On a mutation-gap response, clear the persisted clientID and hard reload the page. This
+     *  recovers from dev DB wipes while making the reset visible to the developer. */
+    resetOnMutationGap?: boolean;
+  };
 }
 
 export interface RindleClient<S extends ColsMap, R extends ClientRegistry> {
@@ -90,8 +97,9 @@ export async function createRindleClient<S extends ColsMap, R extends ClientRegi
       headers: { "content-type": "application/json", ...extra },
       body: JSON.stringify(payload),
     });
-    if (!res.ok) throw new Error(`rindle api ${path} failed: ${res.status} ${await res.text()}`);
-    return res.json();
+    const text = await res.text();
+    if (!res.ok) throw new RindleApiHttpError(path, res.status, text);
+    return text ? JSON.parse(text) : undefined;
   };
 
   // Reads-leg connection: a fixed transport (tests/in-process) or a replaceable connection built
@@ -116,8 +124,15 @@ export async function createRindleClient<S extends ColsMap, R extends ClientRegi
       retryDelayMs: opts.queue?.retryDelayMs,
       onRejected: opts.onRejected,
       send: async (envelopes) => {
-        const outcomes = (await post(routes.mutate, { envelopes })) as Array<{ accepted: boolean; reason?: string }>;
-        return outcomes.map((o): PushOutcome => ({ accepted: o.accepted, reason: o.reason }));
+        try {
+          const outcomes = (await post(routes.mutate, { envelopes })) as Array<{ accepted: boolean; reason?: string }>;
+          return outcomes.map((o): PushOutcome => ({ accepted: o.accepted, reason: o.reason }));
+        } catch (err) {
+          if (opts.dev?.resetOnMutationGap && reloadAfterMutationGap(err)) {
+            return new Promise<never>(() => {});
+          }
+          throw err;
+        }
       },
     }),
   });
@@ -154,3 +169,41 @@ export async function createRindleClient<S extends ColsMap, R extends ClientRegi
 
 export type { ClientRegistry, MutationTx };
 export type { MutateFn } from "./index.ts";
+
+class RindleApiHttpError extends Error {
+  readonly path: string;
+  readonly status: number;
+  readonly body: string;
+
+  constructor(path: string, status: number, body: string) {
+    super(`rindle api ${path} failed: ${status}${body ? ` ${body}` : ""}`);
+    this.name = "RindleApiHttpError";
+    this.path = path;
+    this.status = status;
+    this.body = body;
+  }
+}
+
+const MUTATION_GAP_RE = /\bmutation(?: id)? gap\b/i;
+
+function reloadAfterMutationGap(err: unknown): boolean {
+  const text =
+    err instanceof RindleApiHttpError
+      ? `${err.status} ${err.body} ${err.message}`
+      : String((err as Error)?.message ?? err);
+  if (!MUTATION_GAP_RE.test(text)) return false;
+
+  resetStableClientID();
+  console.error(
+    "[rindle] mutation gap detected; cleared the dev client id and reloading so this tab starts a fresh mutation stream.",
+    err,
+  );
+  const loc = (globalThis as unknown as { location?: { reload?: () => void } }).location;
+  if (typeof loc?.reload !== "function") return false;
+  try {
+    loc.reload();
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/index.ts

@@ -34,6 +34,8 @@ export type {
   OptimisticBackendOptions,
   OptimisticInspect,
   PendingInspect,
+  QueryArg,
+  QueryResultRow,
   ResultType,
 } from "./backend.ts";
 export type { MutationEnvelope, OptimisticSource, ProgressFrame } from "@rindle/client";
@@ -41,7 +43,7 @@ export type { MutationEnvelope, OptimisticSource, ProgressFrame } from "@rindle/
 // The one-call client for the daemon/serverless topology (API server + daemon ws).
 export { createRindleClient } from "./client.ts";
 export type { RindleClient, RindleClientOptions } from "./client.ts";
-export { stableClientID } from "./client-id.ts";
+export { resetStableClientID, stableClientID } from "./client-id.ts";
 
 /** A {@link Store} over an {@link OptimisticBackend}, plus the named-mutator entry
  *  (`mutate.createIssue(args)` — the §9 dream shape) and the §6 lifecycle surface. */