@rindle/optimistic 0.1.0-rc.5

package/src/client-id.ts

@@ -0,0 +1,61 @@
+// The connection's stable clientID — kept in its own (wasm-free) module so it can be unit-tested
+// without pulling the engine in. A per-ORIGIN base (localStorage) shared by every tab and kept
+// across reloads, a per-TAB suffix (sessionStorage) that survives a reload within a tab but is
+// distinct per tab, and a per-LOAD instance suffix that keeps two clients in one tab distinct.
+// Without these two tabs (or two clients in one tab) would share a clientID and collide on the
+// server's per-clientID mid sequence (a confirmed-mid-ahead-of-issued throw, OPTIMISTIC-WRITES §8.2).
+
+/** The per-ORIGIN base id (localStorage): one logical identity shared by every tab and kept
+ *  across reloads. */
+const CLIENT_ID_KEY = "rindle-client-id";
+/** The per-TAB suffix (sessionStorage): survives a reload within a tab but is distinct per tab. */
+const TAB_ID_KEY = "rindle-tab-id";
+
+/** Read-or-mint a value in a web Storage area, tolerating its absence (SSR, privacy mode). Returns
+ *  `undefined` when the area is unavailable so the caller can pick a fallback. */
+function persistedId(area: "localStorage" | "sessionStorage", key: string, mint: () => string): string | undefined {
+  try {
+    const storage = (globalThis as unknown as Record<string, Storage | undefined>)[area];
+    if (!storage) return undefined;
+    const existing = storage.getItem(key);
+    if (existing) return existing;
+    const fresh = mint();
+    storage.setItem(key, fresh);
+    return fresh;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Per-PAGE-LOAD instance counter. The FIRST client created in a tab keeps the bare tab suffix (so a
+ *  reload resumes its mid sequence and adds no row); each ADDITIONAL client constructed in the same
+ *  load gets a distinct instance suffix, so two clients in one tab never share a mid stream. Held in
+ *  memory so it resets on reload — the sole client then reclaims the bare, reload-stable suffix. */
+let tabInstance = 0;
+
+/** Test-only: reset the per-load instance counter to simulate a fresh page load. Deliberately NOT
+ *  re-exported from the package barrel. */
+export function resetTabInstanceForTests(): void {
+  tabInstance = 0;
+}
+
+/** The connection's stable clientID. A per-origin base (localStorage) keeps one logical identity
+ *  across reloads; a per-tab suffix (sessionStorage) gives each tab its OWN mid/lmid stream; a
+ *  per-load instance suffix keeps two clients constructed in ONE tab from sharing that stream. Falls
+ *  back to a fresh random id when web storage is unavailable.
+ *
+ *  Note: an explicit "duplicate tab" copies sessionStorage, so the clone briefly shares its source's
+ *  suffix until reloaded — the one residual case of the shared-clientID collision. */
+export function stableClientID(): string {
+  const base = persistedId("localStorage", CLIENT_ID_KEY, () => crypto.randomUUID());
+  if (!base) return crypto.randomUUID(); // no localStorage: session-scoped, unique per load
+  // With localStorage but no sessionStorage, mint a fresh suffix each load so tabs still differ.
+  const tab =
+    persistedId("sessionStorage", TAB_ID_KEY, () => crypto.randomUUID().slice(0, 8)) ??
+    crypto.randomUUID().slice(0, 8);
+  // Instance 0 keeps the bare tab suffix (reload-stable, no extra row); extra concurrent clients in
+  // one tab get `.N` so they can't collide on the server's per-clientID mid sequence.
+  const instance = tabInstance++;
+  const suffix = instance === 0 ? tab : `${tab}.${instance}`;
+  return `${base}-${suffix}`;
+}

package/src/client.ts

@@ -0,0 +1,156 @@
+// createRindleClient — the one-call client for the daemon/serverless topology:
+//
+//   const app = await createRindleClient({ schema, mutators, api: { url }, daemon: { wsUrl } });
+//   const view = app.store.materialize(queries.allIssues());
+//   app.mutate.createIssue({ id: 1, title: "hi", score: 0 });
+//
+// It wires what the pieces otherwise wire by hand: the wasm engine init, a stable per-tab clientID,
+// the ws transport to the daemon, lease resolution through the API server's query route,
+// and the mutation queue flushing confirmed in-order batches through the mutate route
+// (rejection reasons surface via `onRejected`).
+
+import type { ColsMap, MutationEnvelope, Schema } from "@rindle/client";
+import {
+  RemoteOptimisticSource,
+  WsTransport,
+  createQueuedMutationSender,
+} from "@rindle/remote";
+import type { PushOutcome, RemoteOptimisticConnection, Transport } from "@rindle/remote";
+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 { createOptimisticStore, type MutateFn } from "./index.ts";
+import type { Store } from "@rindle/client";
+
+/** Must mirror `DEFAULT_RINDLE_API_ROUTES` in `@rindle/api-server` (the app-wire contract;
+ *  duplicated so the browser bundle doesn't import the server package). */
+const DEFAULT_ROUTES = { query: "/api/rindle/query", mutate: "/api/rindle/mutate" } as const;
+
+export type HeadersInit = Record<string, string>;
+
+export interface RindleClientOptions<S extends ColsMap, R extends ClientRegistry> {
+  schema: Schema<S>;
+  /** The PREDICTED mutators (the API server holds the authoritative twins by name). */
+  mutators: R;
+  /** The app API server: named queries resolve to leases here, mutations push here. */
+  api: {
+    url: string;
+    routes?: { query?: string; mutate?: string };
+    /** Extra headers per request (auth). A function is re-evaluated per call. */
+    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    fetch?: typeof fetch;
+  };
+  /** Where the live subscription ws connects.
+   *  - `{ wsUrl }` — a static endpoint (single daemon), opened eagerly; in a routed deploy this is
+   *    the SSR-injected bootstrap endpoint (READ-ROUTER-DESIGN.md §2.4). A routed lease naming a
+   *    different follower migrates the connection there.
+   *  - `{ wsUrl }` omitted — pure-lazy: the first lease's `wsEndpoint` opens the connection (a
+   *    routed SPA with no SSR bootstrap).
+   *  - `{ transport }` — a pre-built transport (tests / in-process); fixed, no migration. */
+  daemon: { wsUrl?: string } | { transport: Transport };
+  /** Stable client identity. Default: a per-origin base (localStorage) plus per-tab and per-instance
+   *  suffixes, so each tab — and each client instance within a tab — gets its own mid sequence yet a
+   *  reload keeps it; falls back to a fresh random id when web storage is unavailable. Pass a value
+   *  to override. */
+  clientID?: string;
+  /** 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 };
+}
+
+export interface RindleClient<S extends ColsMap, R extends ClientRegistry> {
+  store: Store<S>;
+  backend: OptimisticBackend<S>;
+  /** Call `mutate.foo(args)` for a normal optimistic write, or `mutate.foo.folded(opts, args)` for a
+   *  debounced, last-value-wins folded write (FOLDED-MUTATIONS-DESIGN §3). */
+  mutate: { [K in keyof R]: MutateFn<Parameters<R[K]>[1]> };
+  /** Drain every outstanding fold immediately (FOLDED-MUTATIONS-DESIGN §3) — also fired on
+   *  `beforeunload`/`pagehide` so a fold in flight isn't lost on navigation. */
+  flushFolds(): void;
+  clientID: string;
+  close(): void;
+}
+
+export async function createRindleClient<S extends ColsMap, R extends ClientRegistry>(
+  opts: RindleClientOptions<S, R>,
+): Promise<RindleClient<S, R>> {
+  await initWasm();
+
+  const clientID = opts.clientID ?? stableClientID();
+  const routes = { ...DEFAULT_ROUTES, ...opts.api.routes };
+  const fetchImpl = opts.api.fetch ?? ((...args: Parameters<typeof fetch>) => fetch(...args));
+  const base = opts.api.url.replace(/\/$/, "");
+
+  const post = async (path: string, payload: unknown): Promise<unknown> => {
+    const extra = typeof opts.api.headers === "function" ? await opts.api.headers() : (opts.api.headers ?? {});
+    const res = await fetchImpl(`${base}${path}`, {
+      method: "POST",
+      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();
+  };
+
+  // Reads-leg connection: a fixed transport (tests/in-process) or a replaceable connection built
+  // from `wsUrl` (eager when present, lazy when omitted). A routed lease's `wsEndpoint` migrates it.
+  const connection: RemoteOptimisticConnection =
+    "transport" in opts.daemon
+      ? { transport: opts.daemon.transport }
+      : { factory: (endpoint) => new WsTransport(endpoint), endpoint: opts.daemon.wsUrl };
+
+  const source = new RemoteOptimisticSource(connection, clientID, {
+    resolveSubscribe: async ({ remote }) => {
+      // Send the stable `clientId` so the api-server/router can use it as the anonymous routing key
+      // (READ-ROUTER-DESIGN.md §2.2); read back the follower's `wsEndpoint` for placement.
+      const out = (await post(routes.query, { name: remote.name, args: remote.args, clientId: clientID })) as {
+        leaseToken: string;
+        wsEndpoint?: string;
+      };
+      return { leaseToken: out.leaseToken, wsEndpoint: out.wsEndpoint };
+    },
+    pushMutation: createQueuedMutationSender({
+      maxBatch: opts.queue?.maxBatch,
+      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 }));
+      },
+    }),
+  });
+
+  const { store, backend, mutate } = createOptimisticStore(opts.schema, source, opts.mutators, { clientID });
+
+  // Drain folds before the tab goes away (FOLDED-MUTATIONS-DESIGN §0.1/§3): a fold deliberately
+  // holds its server write through the debounce window, so an unclean navigation would otherwise
+  // lose the applied-locally tail. `pagehide`/`beforeunload` is the last-chance flush; `close`
+  // also drains. (Best-effort: an unclean crash still loses the tail — an accepted cost, §0.1.)
+  const flushFolds = () => backend.flushFolds();
+  // Structural typing — this package has no DOM lib, but the browser global carries these.
+  const target = globalThis as unknown as {
+    addEventListener?: (type: string, listener: () => void) => void;
+    removeEventListener?: (type: string, listener: () => void) => void;
+  };
+  target.addEventListener?.("pagehide", flushFolds);
+  target.addEventListener?.("beforeunload", flushFolds);
+
+  return {
+    store,
+    backend,
+    mutate,
+    flushFolds,
+    clientID,
+    close: () => {
+      flushFolds();
+      target.removeEventListener?.("pagehide", flushFolds);
+      target.removeEventListener?.("beforeunload", flushFolds);
+      source.close();
+    },
+  };
+}
+
+export type { ClientRegistry, MutationTx };
+export type { MutateFn } from "./index.ts";

package/src/index.ts

@@ -0,0 +1,68 @@
+// @rindle/optimistic — optimistic writes over the local-first wasm engine
+// (OPTIMISTIC-WRITES-DESIGN.md): named client mutators (invoked optimistically,
+// RE-INVOKED on every rebase), the cv-buffered coherent release (§8.5), and the
+// engine-side fork/rebase reconcile cycle (§1.3) behind the ordinary `Backend` seam.
+
+import { Store } from "@rindle/client";
+import type { ColsMap, Schema, OptimisticSource } from "@rindle/client";
+
+import {
+  OptimisticBackend,
+  type ClientRegistry,
+  type FoldHandle,
+  type FoldOptions,
+  type OptimisticBackendOptions,
+} from "./backend.ts";
+
+/** One entry of the {@link createOptimisticStore} `mutate` facade: call it for a normal optimistic
+ *  write (returns the `mid`), or `.folded(opts, args)` for a debounced, last-value-wins folded write
+ *  (returns a {@link FoldHandle} — the `mid` is assigned at flush, FOLDED-MUTATIONS-DESIGN §3). */
+export type MutateFn<Args> = ((args: Args) => number) & {
+  folded(opts: FoldOptions, args: Args): FoldHandle;
+};
+
+export { OptimisticBackend } from "./backend.ts";
+export type {
+  ClientMutator,
+  ClientRegistry,
+  FoldClock,
+  FoldHandle,
+  FoldOptions,
+  KeyedRow,
+  MutationTx,
+  OptimisticBackendOptions,
+  ResultType,
+} from "./backend.ts";
+export type { MutationEnvelope, OptimisticSource, ProgressFrame } from "@rindle/client";
+
+// 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";
+
+/** A {@link Store} over an {@link OptimisticBackend}, plus the named-mutator entry
+ *  (`mutate.createIssue(args)` — the §9 dream shape) and the §6 lifecycle surface. */
+export function createOptimisticStore<S extends ColsMap, R extends ClientRegistry>(
+  schema: Schema<S>,
+  source: OptimisticSource,
+  registry: R,
+  opts: OptimisticBackendOptions,
+): {
+  store: Store<S>;
+  backend: OptimisticBackend<S>;
+  mutate: { [K in keyof R]: MutateFn<Parameters<R[K]>[1]> };
+} {
+  const backend = new OptimisticBackend(schema, source, registry, opts);
+  const store = new Store(schema, backend);
+  const mutate = new Proxy(
+    {},
+    {
+      get: (_t, name: string) => {
+        const fn = ((args: unknown) => backend.invoke(name, args)) as MutateFn<unknown>;
+        fn.folded = (foldOpts: FoldOptions, args: unknown) => backend.invokeFolded(name, foldOpts, args);
+        return fn;
+      },
+    },
+  ) as { [K in keyof R]: MutateFn<Parameters<R[K]>[1]> };
+  return { store, backend, mutate };
+}