@rindle/optimistic 0.4.3 → 0.5.0

package/README.md

@@ -1,70 +1,39 @@
 # @rindle/optimistic
 
-Optimistic writes over the local-first wasm engine (`OPTIMISTIC-WRITES-DESIGN.md`).
+The browser store for a synced Rindle app: optimistic writes over the local-first wasm
+engine. `createRindleClient` boots the wasm engine, opens the ws subscription to the
+daemon, resolves query leases through your API server, and runs the mutation queue.
 
-The local IVM engine **is** the rebase function: the wasm `Db` keeps an authoritative
-`sync` fork per base table and reconciles every server batch by **rewinding** the live
-pipeline to the authoritative state and **re-invoking** the still-pending client
-mutators against it — no inverse mutations, no second materialization. This package is
-the client glue around that engine cycle:
-
-- **Named client mutators** (`ClientRegistry`): `(tx, args) => void` against a
-  `MutationTx` (`get`/`add`/`remove`/`edit`; reads see the current base + the
-  transaction's own writes). Deterministic and replayable — a mutator is re-invoked on
-  every rebase, so a read-dependent `incrementScore(+5)` computed on a stale `10`
-  correctly becomes `105` after the server lands `100`.
-- **cv-buffering** (§8.5): per-query data frames are `cv`-tagged and buffer; a
-  connection-level progress frame `{ cvMin, lmid, rejected }` releases everything
-  `cv ≤ cvMin` as one coherent step — no torn multi-query reads, ever. Buffer
-  overflow drops + re-hydrates (the one new client obligation).
-- **Pending stack** of `(mid, name, args)` — never effects; `lmid` confirms (drop),
-  `rejected` snaps back (the engine cycle removes the phantom effects).
-- **`ResultType`** per query (§6/§7): the **server channel's** state only — `unknown`
-  while not hydrated (the server hasn't answered yet), `complete` once it has. A pending
-  mutation no longer moves it; `error` is reserved and currently unproduced.
-- **Pending axis** (§7.2): "is an unconfirmed prediction touching this query?" is its own
-  reactive signal — `pending(qid)` / `onPending` / `pendingTables()` — so a "saving…"
-  indicator is separate from loading.
-- **Local-only tables**: `table("draft", { local: true })` declares client-authoritative
-  state that never syncs, rebases, or appears in the normalized server schema. Use
-  `store.writeLocal(...)` for selections, drafts, and view prefs; replayable predicted
-  mutators are intentionally barred from reading/writing local-only tables.
-- **Folded mutations** (FOLDED-MUTATIONS-DESIGN): `mutate.foo.folded({ key, debounceMs,
-  maxWaitMs }, args)` collapses a run of high-frequency same-key writes (a slider drag) into
-  **one** debounced, last-value-wins server write while the local view still updates on every
-  call. Folded mutators must be **absorbing** (last-writer-wins); a read-dependent one is
-  refused. `flushFolds()` (also auto-fired on `pagehide`/`beforeunload`) drains in-flight folds.
+The local IVM engine **is** the rebase function: it keeps an authoritative fork per base
+table and reconciles every server batch by **rewinding** to the authoritative state and
+**re-invoking** the still-pending mutators against it — no inverse mutations, no rollback
+code. A rejected write snaps back on its own.
 
 ```ts
-import { createOptimisticStore, type ClientRegistry } from "@rindle/optimistic";
-import { defineQuery, newQueryBuilder } from "@rindle/client";
-// `schema` is your @rindle/client schema; `source` is an `OptimisticSource`
-// (e.g. `createRemoteOptimisticSource` from @rindle/remote).
-
-const registry = {
-  createIssue: (tx, args: { id: number; title: string }) =>
-    tx.add("issue", [args.id, args.title]),
-} satisfies ClientRegistry;
-
-const q = newQueryBuilder(schema);
-const queries = {
-  allIssues: defineQuery("allIssues", () => q.issue.orderBy("id", "asc")),
-};
-
-const { store, backend, mutate } = createOptimisticStore(schema, source, registry, {
-  clientID: "client-1",
+import { createRindleClient } from "@rindle/optimistic";
+import { mutators, schema } from "../shared/app-def.ts"; // isomorphic mutators + generated schema
+
+export const app = await createRindleClient({
+  schema,
+  mutators,                                  // one generator body per mutator, run on both tiers
+  user: () => currentUser(),                 // the acting principal a mutator sees as ctx.user
+  api: { url: "" },                          // your API server (named queries + mutations)
+  daemon: { wsUrl: "ws://127.0.0.1:7601" },  // the daemon's PUBLIC subscription port
 });
 
-const view = store.materialize(queries.allIssues()); // named remote footprint + local view
-mutate.createIssue({ id: 7, title: "instant" }); // applies NOW; reconciles when confirmed
-backend.resultType(/* queryId */ 1); // "unknown" (loading) → "complete"
-backend.pending(/* queryId */ 1);    // is an optimistic write pending on this query?
+app.mutate.createIssue({ id, title: "ship it", createdAt: Date.now() }); // applies NOW, rebases on confirm
 ```
 
-A `Store` over an `OptimisticBackend` is an ordinary `@rindle/client` store — the
-`Backend` seam holds. Unstamped `store.query...materialize()` calls are local-only; use
-`defineQuery` + `store.materialize(query)` for remote sync. The `OptimisticSource` (the server side: cv-tagged normalized
-frames + progress frames + the mutation upstream) is pluggable; the ws transport wiring
-is the follow-up slice. The engine-side cycle and the server protocol are proven in
-Rust (`src/optimistic.rs`, `rindle-replica`'s mutation/envelope suites); this package's
-tests pin the TS wiring against a scripted source.
+Also in the box: **folded mutations** (collapse a slider drag into one last-value-wins
+server write), **local-only tables** (`{ local: true }` — client state that never syncs
+or rebases, written with `store.writeLocal`), the per-query **`ResultType`** axis
+(loading vs. server-answered) and the separate **pending** axis (is an unconfirmed write
+touching this query?).
+
+## Docs
+
+Full docs — wiring, optimistic writes & rebase, folded writes, local-only tables, and the
+loading/pending signals: **[rindle.sh/docs/client](https://rindle.sh/docs/client)** ·
+markdown mirror: [`client.md`](https://rindle.sh/docs/client.md) · the mutator contract:
+[rindle.sh/docs/mutators](https://rindle.sh/docs/mutators) · for agents:
+[llms.txt](https://rindle.sh/llms.txt)