@gonvex/client 0.1.32 → 0.3.0

package/README.md

@@ -1,11 +1,36 @@
 # @gonvex/client
 
-Browser client for Gonvex realtime queries, mutations, actions, telemetry, and
-local cache helpers.
+Browser client for Gonvex Queries, Reducers, Actions, Live Queries, the
+persistent Local Replica, and telemetry.
 
 Most React apps should use `@gonvex/react`, which wraps this package with hooks.
 Use `@gonvex/client` directly when you want lower-level control.
 
+## Control Plane
+
+Host-owned account, tenant-directory, invitation, agent-auth, voice, and support
+functions use the same persistent connection as tenant functions:
+
+```ts
+import { control } from "@gonvex/client";
+
+const account = await client.query(control.accounts.me, {});
+const tenants = await client.query(control.tenants.mine, {});
+await client.reducer(control.tenants.updateTimezone, { timezone: "America/Los_Angeles" });
+
+const stop = client.watchControlQuery(control.support.sessions, {}, (result) => {
+  renderSessions(result);
+});
+```
+
+The references include argument/result schemas and their authorization class.
+They never accept database URLs. Tenant-admin references always operate on the
+active, authoritatively admitted tenant.
+
+Control Plane live Queries resubscribe on reconnect and refresh after an
+authorized Control Plane Reducer. Use `watchControlQuery` instead of refetching
+after a write.
+
 ## Install
 
 ```bash
@@ -16,6 +41,7 @@ npm install @gonvex/client
 
 ```ts
 import { GonvexClient } from "@gonvex/client";
+import { api } from "./gonvex/_generated/api";
 
 const client = new GonvexClient("ws://localhost:8080/ws", {
   project: "my-project",
@@ -24,8 +50,8 @@ const client = new GonvexClient("ws://localhost:8080/ws", {
 
 client.connect();
 
-const unsubscribe = client.subscribeQuery(
-  { kind: "query", path: "tasks.list" },
+const unsubscribe = client.subscribeLiveQuery(
+  api.tasks.list,
   { status: "open" },
   (message) => {
     if (message.type === "query.result") {
@@ -34,8 +60,8 @@ const unsubscribe = client.subscribeQuery(
   },
 );
 
-await client.mutation(
-  { kind: "mutation", path: "tasks.create" },
+await client.reducer(
+  { kind: "reducer", path: "tasks.create" },
   { title: "Ship Gonvex" },
 );
 
@@ -43,110 +69,94 @@ unsubscribe();
 client.close();
 ```
 
-## Transparent Browser Cache
+## Local Replica
 
-Live query results are persisted automatically in supported browsers when the
-runtime advertises a safe cache scope. A warm `subscribeQuery`, `watchQuery`, or
-React `useQuery` can replay its last result while the normal server subscription
-runs in parallel. The server result always wins and refreshes the snapshot,
-including results produced by realtime invalidation.
+The Local Replica is the only client-side server-state store. It owns normalized
+entities, live-query/replica windows, revision metadata, and optimistic command
+patches. One-shot Query results are transient and are never persisted.
 
-Caching is isolated by runtime deployment, project, tenant, user, and current
-permissions. New clients connected to older runtimes stay server-only.
-
-No setup is required. To opt out or clear the disposable cache:
+Inject a durable adapter when desired; omit it for memory-only operation:
 
 ```ts
-const client = new GonvexClient(url, { queryCache: false });
-
-await client.clearQueryCache();
-await client.clearQueryCache({ allScopes: true });
+const client = new GonvexClient(url, {
+  localReplica: { storage: indexedDbReplicaStorage },
+});
 ```
 
-Dexie is loaded asynchronously only after a cache-capable session is confirmed,
-so IndexedDB setup does not delay the WebSocket query path.
+All window updates are applied atomically before listeners are notified. Live
+Query windows and Replica Collections reference the same normalized entities,
+so every view of an entity converges together.
 
-## Durable Sync Collections
+## Replica Collections
 
-Sync functions materialize bounded, authorized single-table collections in a
-normalized IndexedDB store and resume them from a durable Postgres cursor:
+Replica Collections materialize bounded, authorized entity sets in normalized
+IndexedDB storage and resume them from a durable Postgres revision:
 
 ```ts
-const watch = client.watchSync<Task>(
-  { kind: "sync", path: "tasks.recent" },
+const watch = client.watchReplica<Task>(
+  api.tasks.recent,
   { workspaceId: "workspace-a" },
 );
 
 const stop = watch.onUpdate(() => {
-  render(watch.localSyncResult() ?? []);
+  const state = watch.localReplicaState();
+  render(state?.rows ?? []);
+  console.log(state?.completeness, state?.truncated, state?.computedRevision);
   console.log(watch.status()); // { isLoading, isUpToDate }
 });
 ```
 
-Configure or disable the sync store when constructing the client:
+Configure Local Replica persistence when constructing the client:
 
 ```ts
 const client = new GonvexClient(url, {
-  sync: {
-    databaseName: "my-product-sync",
-    maxBytes: 150 * 1024 * 1024,
-  },
+  localReplica: { storage: indexedDbReplicaStorage },
 });
-
-const memoryOnly = new GonvexClient(url, { sync: false });
 ```
 
-The default global IndexedDB budget is 100 MiB. Server-declared per-collection
-row/byte budgets still apply, and least-recently-used collections are evicted
-first. Storage is isolated by runtime, project, tenant, authenticated identity,
-and permissions.
+## Optimistic Reducers
 
-## Entity-level optimistic mutations
+Every public interactive Reducer declares its optimistic transaction. The
+authoritative transaction and optimistic patches are reconciled in LocalReplica.
 
-Declare how a mutation maps its arguments to an entity row and how each live
-read projects that entity:
-
-```go
-app.Mutation(
-  "tasks.update",
-  updateTask,
-  gonvex.OptimisticMutation("tasks").RowIDArg("taskId").FieldsArg("updates"),
-)
-
-app.Query(
-  "tasks.byWorkspace",
-  tasksByWorkspace,
-  gonvex.OptimisticProjection("tasks").Key("_id").ResultPath("page"),
-)
-```
-
-Generated references carry this metadata, so a normal mutation call is enough:
+Generated references carry this metadata, so a normal Reducer call is enough:
 
 ```ts
-await client.mutation(api.tasks.update, {
+await client.reducer(api.tasks.update, {
   taskId,
   updates: { priority_id: priorityId },
 });
 ```
 
-The client persists the pending mutation before exposing it, layers it over
-every matching sync and query subscription, and notifies watchers immediately.
-An RPC result marks the write accepted but does not remove it; the overlay is
-retired only when every source that displayed it reports the mutation id (or a
-restored committed snapshot already matches). Deterministic server errors
-remove the overlay and repaint the authoritative rows. This keeps stale query
-or sync frames from briefly reverting the UI.
+The client persists the pending command, applies it through LocalReplica, and
+notifies watchers immediately. Reducer success includes an
+`originCommandId` and committed revision. The overlay is removed only after the
+corresponding authoritative transaction has been applied locally, preventing an
+empty or stale frame between optimistic and committed state.
 
-The authoritative sync/query cache stays immutable. Durable pending state lives
-in the mutation outbox and is re-applied to cached rows after reload. Outbox
+Authoritative entity state and optimistic entities are materialized by one
+LocalReplica graph. Durable pending state lives in the command outbox and is
+re-applied after reload. Outbox
 rows are isolated by project, tenant, and authenticated identity; an account
 switch removes the previous identity's overlay and can never replay its writes
 under the new session. Unscoped rows from the pre-isolation schema are removed
 during migration because their owner cannot be proven. If an opaque credential
 does not expose a stable identity (and no `identity` hint is supplied), its
-outbox is deliberately session-only rather than risking cross-user replay. For
-a complex projection that cannot be derived from one nested fields argument,
-callers can still provide explicit `optimistic` entity patches.
+outbox is deliberately session-only rather than risking cross-user replay.
+
+## Offline Live Queries
+
+Generated Live Query references include the same structured plan Gonvex
+compiles to PostgreSQL. While offline, the client executes that plan over the
+normalized cached corpus:
+
+```ts
+const result = client.offlineLiveQuery(api.tasks.grid, args);
+// { rows, completeness: "complete" | "partial", supported }
+```
+
+`supported: false` means the plan is explicitly server-only. A partial result
+must be labeled as cached data rather than presented as the full database.
 
 ## Lightweight Error Tracking
 
@@ -165,9 +175,23 @@ const client = new GonvexClient(url, {
 });
 ```
 
-Use `GonvexErrorReporter` directly when integrating an existing application
-logger. See the Error Tracking guide in the full documentation for privacy,
-grouping, persistence, and dashboard details.
+Error registration and envelopes use native persistent-protocol frames. No
+browser HTTP ingestion endpoint is needed.
+
+Applications can report an explicit event through the public API:
+
+```ts
+await client.reportError("envelope", {
+  events: [{
+    message: "Task preview failed",
+    level: "error",
+    context: { component: "TaskPreview" },
+  }],
+});
+```
+
+`new GonvexErrorReporter({ client })` adds global browser error capture and
+re-registers its telemetry session after reconnect.
 
 ## Connection reliability
 
@@ -180,7 +204,7 @@ reconnect.
 client.connectionState();
 // {
 //   isWebSocketConnected, hasEverConnected, connectionCount, connectionRetries,
-//   hasInflightRequests, inflightMutations, inflightActions, inflightOneShotQueries
+//   hasInflightRequests, inflightReducers, inflightActions, inflightOneShotQueries
 // }
 
 const stop = client.subscribeToConnectionState((state) => {
@@ -193,7 +217,7 @@ const stop = client.subscribeToConnectionState((state) => {
 | Operation | Default |
 | --- | --- |
 | One-shot `query()` | 20s |
-| `mutation()` | 20s |
+| `reducer()` | 20s |
 | `action()` | 60s |
 
 Override per client (`timeouts` option) or per call (`{ timeoutMs }`). Use `0` to disable.
@@ -202,43 +226,43 @@ Override per client (`timeouts` option) or per call (`{ timeoutMs }`). Use `0` t
 
 Rejected operations throw `GonvexClientError` with `code`:
 
-- `server` — runtime executed the function and returned an error
-- `timeout` — no response within the timeout
-- `disconnected` — socket dropped while the operation was pending
-- `closed` — client was explicitly closed
-- `auth` — authentication rejected
+- `server`: runtime executed the function and returned an error
+- `timeout`: no response within the timeout
+- `disconnected`: socket dropped while the operation was pending
+- `closed`: client was explicitly closed
+- `auth`: authentication rejected
 
-### Mutation / action disconnect policy
+### Reducer / Action disconnect policy
 
-Actions and mutations without `{ offline: "queue" }` fail closed after a
+Actions and Reducers without `{ offline: "queue" }` fail closed after a
 disconnect. They reject with `code: "disconnected"` (or `timeout` / `closed`).
-Optimistic mutations are persisted before transport even in fail-closed mode,
+Optimistic Reducers are persisted before transport even in fail-closed mode,
 so a process reload cannot expose an older cached row while an accepted write
 is still waiting for its authoritative subscription update.
 
-Pass `{ offline: "queue" }` to a mutation to durably accept a transport failure
+Pass `{ offline: "queue" }` to a Reducer to durably accept a transport failure
 and replay the same idempotency key after reconnect, whether or not that
-mutation also declares optimistic UI metadata. Actions are never queued.
+Reducer also declares optimistic UI metadata. Actions are never queued.
 Deterministic server errors are never queued and always roll an optimistic
 entity overlay back when one exists.
 
-Live queries keep last-good data at the React layer (`useQueryResult`) and
-resubscribe after reconnect. Call `client.retryQuery(ref, args)` to force a
-re-request after a server error or soft timeout.
+Live Queries persist their last verified window in the Local Replica and
+resubscribe after reconnect. Call `client.retryLiveQuery(ref, args)` to force a
+re-request after a server error. `useQueryResult` is for one-shot Queries.
 
 ## Exports
 
 The package exports:
 
 - `GonvexClient`
-- `ConvexReactClient` compatibility alias
 - `GonvexClientError`, `ConnectionState`, timeout defaults
-- transparent persistent query caching and lower-level experimental cache helpers
-- durable entity-level optimistic overlays for query and sync projections
-- opt-in mutation outbox replay with stable idempotency keys
-- `subscribeSync`, `watchSync`, and normalized persistent sync storage
+- normalized Local Replica entities and Live Query windows
+- durable optimistic Reducer overlays reconciled by command ID and revision
+- opt-in command outbox replay with stable idempotency keys
+- `subscribeReplica`, `watchReplica`, and persistent Replica storage
+- `watchControlQuery` for authorized Control Plane live Queries
 - browser capability and telemetry helpers
-- `GonvexErrorReporter` and automatic operation error reporting
+- `reportError`, `GonvexErrorReporter`, and automatic operation error reporting
 
 ## Related Packages