@cf-sync/client 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +3 -1
- package/dist/{client-tvsT_ixa.d.ts → client-C488ro1Y.d.ts} +19 -0
- package/dist/index.d.ts +1 -1
- package/dist/index.js +42 -0
- package/dist/react.d.ts +1 -1
- package/docs/config.json +75 -0
- package/docs/guide/auth.md +135 -0
- package/docs/guide/collaborative-text.md +83 -0
- package/docs/guide/defining-your-app.md +117 -0
- package/docs/guide/getting-started.md +150 -0
- package/docs/guide/limits-and-costs.md +58 -0
- package/docs/guide/mutations.md +112 -0
- package/docs/guide/offline-persistence.md +67 -0
- package/docs/guide/operations.md +97 -0
- package/docs/guide/presence.md +64 -0
- package/docs/guide/reading-data.md +102 -0
- package/docs/guide/schema-evolution.md +91 -0
- package/docs/guide/testing.md +66 -0
- package/docs/guide/troubleshooting.md +68 -0
- package/docs/guide/why.md +54 -0
- package/docs/index.md +38 -0
- package/docs/reference/collections.md +105 -0
- package/docs/reference/define-kit.md +143 -0
- package/docs/reference/index.md +25 -0
- package/docs/reference/server.md +174 -0
- package/docs/reference/sync-client.md +294 -0
- package/docs/reference/testing.md +135 -0
- package/docs/reference/yjs.md +110 -0
- package/package.json +5 -4
|
@@ -0,0 +1,294 @@
|
|
|
1
|
+
# SyncClient
|
|
2
|
+
|
|
3
|
+
The per-workspace sync client from `@cf-sync/client`. It owns the WebSocket to the workspace's Durable Object, the outbox of unconfirmed mutations, optimistic application and rollback, presence, and reconnection with cursor catch-up. Construct one instance per workspace per tab; it connects on construction unless [`autoStart: false`](#autostart).
|
|
4
|
+
|
|
5
|
+
```ts
|
|
6
|
+
import { SyncClient } from '@cf-sync/client'
|
|
7
|
+
import { app } from './schema'
|
|
8
|
+
|
|
9
|
+
const client = new SyncClient({
|
|
10
|
+
url: 'wss://sync.example.com',
|
|
11
|
+
workspaceId: 'team-a',
|
|
12
|
+
app,
|
|
13
|
+
persist: true,
|
|
14
|
+
})
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Options
|
|
18
|
+
|
|
19
|
+
Options are fixed for the instance's lifetime — to change one, [`destroy()`](#destroy) and construct a new client. Only `url`, `workspaceId`, and `app` are required.
|
|
20
|
+
|
|
21
|
+
### url
|
|
22
|
+
|
|
23
|
+
`string` · **required**
|
|
24
|
+
|
|
25
|
+
Base URL of the sync worker — origin plus any mount path, no sync route: `wss://sync.example.com`. `http(s)://` is accepted and converted. The client appends `<pathPrefix>/<workspaceId>?clientId=<clientId>` itself, so the clientId in the URL (which the server binds at upgrade) can never diverge from the one used for confirmation matching.
|
|
26
|
+
|
|
27
|
+
### workspaceId
|
|
28
|
+
|
|
29
|
+
`string` · **required**
|
|
30
|
+
|
|
31
|
+
The workspace to sync. Names the server-side Durable Object (via the URL path), the local IndexedDB database, and the collection ids.
|
|
32
|
+
|
|
33
|
+
### app
|
|
34
|
+
|
|
35
|
+
`AppDefinition` · **required**
|
|
36
|
+
|
|
37
|
+
The shared [app definition](/reference/define-kit#defineapp) — the same `defineApp` object the server is configured with: schema version, table schemas, and mutator registry. Collections derive their row types and runtime validation from its schema; `mutate` is typed by mutator name and validates args locally before queueing, so bad calls fail immediately instead of surfacing as a server round-trip error (the server's validation remains authoritative).
|
|
38
|
+
|
|
39
|
+
### persist
|
|
40
|
+
|
|
41
|
+
`boolean` · default `false`
|
|
42
|
+
|
|
43
|
+
Shorthand for `store: new IndexedDBSyncStore(...)` built from `workspaceId` and the managed clientId. Turns on the whole [offline story](/guide/offline-persistence): instant reload hydration, cursor resume, and a durable outbox. Where IndexedDB is unavailable (SSR, some workers), the client warns and runs without persistence instead of throwing. Mutually exclusive with `store`.
|
|
44
|
+
|
|
45
|
+
### store
|
|
46
|
+
|
|
47
|
+
`SyncStore`
|
|
48
|
+
|
|
49
|
+
Durable storage for synced rows, the cursor, and the outbox — pass your own [`SyncStore`](#syncstore) implementation instead of the IndexedDB default. When set, `start()` hydrates registered tables from the store (collections show cached data before the socket connects), hello resumes from the persisted cursor, and unconfirmed mutations survive reloads. A schema version mismatch discards the cache and bootstraps fresh.
|
|
50
|
+
|
|
51
|
+
### clientId
|
|
52
|
+
|
|
53
|
+
`string` · default: managed by the library
|
|
54
|
+
|
|
55
|
+
Identifies one contiguous mutation sequence — unique per SyncClient instance (per tab/session), never shared across concurrent tabs. The managed default is persisted per workspace in sessionStorage (reload continuity without cross-tab sharing), random where sessionStorage is unavailable. Pass explicitly to take over the lifecycle.
|
|
56
|
+
|
|
57
|
+
### authToken
|
|
58
|
+
|
|
59
|
+
`string | (() => string | Promise<string>)`
|
|
60
|
+
|
|
61
|
+
The connection credential. Browsers cannot set headers on a WebSocket upgrade, so the token travels as a `token` query parameter on the sync URL, where the worker's [`authorize`](/guide/auth#the-authorize-hook) hook reads it: `new URL(request.url).searchParams.get('token')`. A function is invoked fresh on **every** connection attempt — including the immediate reconnect after a 4300 refresh close — so short-lived tokens renew naturally: `authToken: () => getSession().accessToken`. It may be async; a rejection is treated like a failed connection attempt (logged, retried with backoff). See [Auth & sessions](/guide/auth#sending-a-credential).
|
|
62
|
+
|
|
63
|
+
### authContext
|
|
64
|
+
|
|
65
|
+
`AuthContextOf<M>`
|
|
66
|
+
|
|
67
|
+
This client's own view of its auth context — the same shape the server's `authorize` hook stamps (typed by the app's `authContext` schema). Optimistic mutator runs see it as `ctx.auth` with `ctx.authoritative: false`, so permission checks written without the `authoritative` guard fail fast locally instead of surfacing as a server round-trip rejection. Validated against the app's `authContext` schema at construction when one is declared. The server's stamps remain authoritative either way.
|
|
68
|
+
|
|
69
|
+
Not a credential: it is never transmitted, and the server never trusts it. (Arriving from Replicache or Zero? Their `auth` option is the transmitted token — here that's [`authToken`](#authtoken).)
|
|
70
|
+
|
|
71
|
+
### autoStart
|
|
72
|
+
|
|
73
|
+
`boolean` · default `true`
|
|
74
|
+
|
|
75
|
+
Connect on construction. Pass `false` when construction and connection must be decoupled — SSR (module-scope construction would open sockets from the server; Node 22+ has a global WebSocket), tests, or apps that gate syncing on auth — and call [`start()`](#start) yourself.
|
|
76
|
+
|
|
77
|
+
### pathPrefix
|
|
78
|
+
|
|
79
|
+
`string` · default `"/sync"`
|
|
80
|
+
|
|
81
|
+
URL prefix for sync routes, matching the server router's `pathPrefix`.
|
|
82
|
+
|
|
83
|
+
### confirmTimeoutMs
|
|
84
|
+
|
|
85
|
+
`number` · default `30_000`
|
|
86
|
+
|
|
87
|
+
Memory-only clients (no `store`/`persist`): reject unconfirmed mutations after this long — the mutation is discarded and the optimistic overlay rolls back, which is honest because nothing would survive a reload anyway. Ignored when a durable store is present: a queued mutation survives reloads and still applies when connectivity returns, so the promise stays pending until a connection confirms it.
|
|
88
|
+
|
|
89
|
+
### pingIntervalMs
|
|
90
|
+
|
|
91
|
+
`number` · default `25_000`
|
|
92
|
+
|
|
93
|
+
Keepalive ping cadence. Pings keep idle edge connections alive (the server's auto-response answers without waking the DO) and give the heartbeat a liveness signal. `0` disables the heartbeat entirely.
|
|
94
|
+
|
|
95
|
+
### idleTimeoutMs
|
|
96
|
+
|
|
97
|
+
`number` · default: `2 × pingIntervalMs + 5s`
|
|
98
|
+
|
|
99
|
+
Force a reconnect when no frame of any kind has arrived for this long — the only way to detect a half-open socket, which never emits a close event.
|
|
100
|
+
|
|
101
|
+
### maxBackoffMs
|
|
102
|
+
|
|
103
|
+
`number` · default `30_000`
|
|
104
|
+
|
|
105
|
+
Cap on the exponential reconnect backoff. The browser's `online` and `visibilitychange` events short-circuit a pending backoff — a reopened laptop reconnects immediately, not after waiting out the timer.
|
|
106
|
+
|
|
107
|
+
### logger
|
|
108
|
+
|
|
109
|
+
`SyncLogger` — `(level: 'warn' | 'error', message, ...detail) => void` · default: the console
|
|
110
|
+
|
|
111
|
+
Where the client's diagnostics go — reconnect decisions, dropped frames, persistence failures. Inject to route them into your own logging; the messages arrive fully formatted (including the `[cf-sync]` prefix).
|
|
112
|
+
|
|
113
|
+
### createSocket
|
|
114
|
+
|
|
115
|
+
`(url: string) => WebSocketLike`
|
|
116
|
+
|
|
117
|
+
Socket factory for tests and non-browser runtimes. A custom factory that wraps a real browser WebSocket must set `binaryType = 'arraybuffer'` — binary-lane frames ([Yjs fields](/reference/yjs)) must arrive as ArrayBuffer, not Blob — which the default factory does.
|
|
118
|
+
|
|
119
|
+
### initialPresence
|
|
120
|
+
|
|
121
|
+
`PresenceInput`
|
|
122
|
+
|
|
123
|
+
The presence state announced as soon as the connection is ready, before any `presence.set` call. Provide identity here once (validated at construction, like `authContext`) and every later call site can be a bare `presence.update(partial)` — immune to component mount order. Requires a `presence` schema in the app. See [Presence](/guide/presence).
|
|
124
|
+
|
|
125
|
+
### presenceThrottleMs
|
|
126
|
+
|
|
127
|
+
`number` · default `100`
|
|
128
|
+
|
|
129
|
+
Trailing-edge throttle window for `presence.set` — the client sends at most one presence frame per window, carrying the latest state, so apps call `set` at input frequency without throttle glue.
|
|
130
|
+
|
|
131
|
+
### onMutationRejected
|
|
132
|
+
|
|
133
|
+
`(error: MutationError, mutation: { name: string; args: unknown }) => void`
|
|
134
|
+
|
|
135
|
+
One place to learn that a mutation was rejected — its optimistic overlay rolled back and this session will not apply it. Fires for every rejection: server app errors, local fail-fast (`InvalidArgs`, `UnknownMutator`, `LocalApplyFailed`), and the lifecycle codes (`Timeout`, `Stopped`, `Fatal` — filter on `error.code` if you only want server verdicts). Crucially it also fires for rejections with **no awaiting caller**: collection `insert`/`update`/`delete` writes, and mutations restored from the persisted outbox after a reload — without this hook, those roll back silently. With the hook set, fire-and-forget calls (`void client.mutate.todos.clear()`) are considered handled; awaiting callers still see the rejection too. See [Mutations](/guide/mutations#one-handler-instead-of-a-catch-per-call-site).
|
|
136
|
+
|
|
137
|
+
### onFatal
|
|
138
|
+
|
|
139
|
+
`(error: SyncFatalError) => void`
|
|
140
|
+
|
|
141
|
+
Called when the server permanently rejects this client — an in-band `VersionNotSupported`/`Unauthorized` error, or a close code in the permanent band `[4400, 4499]` (an `authorize` rejection or an admin kick). The error carries the close `{ code, reason }`, so apps can branch on the rejection slug. Default in the browser: reload the page — the designed recovery for a version mismatch is loading the new bundle — throttled to once per minute per workspace so a bad deploy window degrades to a slow retry instead of a reload loop. See [Auth & sessions](/guide/auth#close-codes).
|
|
142
|
+
|
|
143
|
+
### onStatusChange
|
|
144
|
+
|
|
145
|
+
`(status: SyncStatus) => void`
|
|
146
|
+
|
|
147
|
+
Constructor-time convenience; for dynamic subscribers use [`subscribeStatus`](#subscribestatus).
|
|
148
|
+
|
|
149
|
+
### onSyncProgress
|
|
150
|
+
|
|
151
|
+
`(progress: { receivedOps: number; remainingOps: number }) => void`
|
|
152
|
+
|
|
153
|
+
Progress during large pokes (bootstrap): ops received so far vs. still to come.
|
|
154
|
+
|
|
155
|
+
## Properties
|
|
156
|
+
|
|
157
|
+
### mutate
|
|
158
|
+
|
|
159
|
+
`Mutate<M>`
|
|
160
|
+
|
|
161
|
+
The typed mutation surface: `client.mutate.issue.move({ id, column })` or the string form `client.mutate('issue.move', args)`. Names autocomplete from the app definition; bad args are a compile error and are validated locally before queueing. The returned promise settles per the [mutation lifecycle](/guide/mutations#the-one-semantic-to-internalize): resolves on server confirm, rejects with a [`MutationError`](#mutationerror) when the mutation will never apply.
|
|
162
|
+
|
|
163
|
+
### presence
|
|
164
|
+
|
|
165
|
+
`PresenceApi`
|
|
166
|
+
|
|
167
|
+
Ephemeral peer state on the existing socket — see [Presence](/guide/presence) for the model.
|
|
168
|
+
|
|
169
|
+
- `presence.set(state)` — full replace, throttled trailing-edge at `presenceThrottleMs`.
|
|
170
|
+
- `presence.update(partial)` — shallow merge into the last state; `{ field: undefined }` clears one field.
|
|
171
|
+
- `presence.clear()` — peers see you go quiet.
|
|
172
|
+
- `presence.self` — your own parsed state (never included in peers).
|
|
173
|
+
- `presence.peers` — the current peers, each `{ clientId, principal?, state, receivedAt }` with identity stamped by the server.
|
|
174
|
+
- `presence.subscribe(listener)` — change notifications (peer changes *and* local `set`/`update`/`clear`, so `self` renders reactively); returns an unsubscribe function.
|
|
175
|
+
|
|
176
|
+
### hydrated
|
|
177
|
+
|
|
178
|
+
`boolean`
|
|
179
|
+
|
|
180
|
+
Whether locally cached data has been restored and collections are ready to render — the signal an offline-first UI gates its first paint on. [`SyncStatus`](#syncstatus) cannot answer this: `connecting` covers hydration, so it reads the same before and after, and an empty collection mid-hydration is indistinguishable from a genuinely empty workspace.
|
|
181
|
+
|
|
182
|
+
`true` only when there was a cached snapshot to paint. It stays `false` when no store is configured, when the store is empty (a first launch), when the cache was discarded because it targets a different app version, and when the store failed to load — in each case there is nothing cached to show, and the UI should wait for the first sync. It settles once and survives reconnects: it describes local state, not the socket. React apps use [`useHydrated`](#react-hooks).
|
|
183
|
+
|
|
184
|
+
### whenHydrated
|
|
185
|
+
|
|
186
|
+
`Promise<boolean>`
|
|
187
|
+
|
|
188
|
+
The imperative form of [`hydrated`](#hydrated) — resolves when hydration settles, with the value `hydrated` takes:
|
|
189
|
+
|
|
190
|
+
```ts
|
|
191
|
+
if (await client.whenHydrated) renderFromCache()
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
It never hangs for the client's life: a client with no store settles it immediately, and one destroyed mid-hydration settles it `false`.
|
|
195
|
+
|
|
196
|
+
### status · cursor · workspaceId · clientId · app · schema
|
|
197
|
+
|
|
198
|
+
Read-only getters: the current [`SyncStatus`](#syncstatus), the last confirmed server cursor (`null` before the first sync), and the constructor's identity values.
|
|
199
|
+
|
|
200
|
+
## Methods
|
|
201
|
+
|
|
202
|
+
### subscribeStatus
|
|
203
|
+
|
|
204
|
+
`(listener: (status: SyncStatus) => void) => () => void`
|
|
205
|
+
|
|
206
|
+
Subscribe to [`SyncStatus`](#syncstatus) transitions; returns an unsubscribe function. React apps use [`useSyncStatus`](#react-hooks) instead.
|
|
207
|
+
|
|
208
|
+
### subscribeHydrated
|
|
209
|
+
|
|
210
|
+
`(listener: (hydrated: boolean) => void) => () => void`
|
|
211
|
+
|
|
212
|
+
Subscribe to the [`hydrated`](#hydrated) transition; returns an unsubscribe function. Fires at most once per client, and only when a cache was actually restored. React apps use [`useHydrated`](#react-hooks) instead.
|
|
213
|
+
|
|
214
|
+
### start
|
|
215
|
+
|
|
216
|
+
`() => void`
|
|
217
|
+
|
|
218
|
+
Connect (only meaningful with `autoStart: false`). Hydrates from the store first when one is configured, then opens the socket. Throws if the client was destroyed.
|
|
219
|
+
|
|
220
|
+
### destroy
|
|
221
|
+
|
|
222
|
+
`() => Promise<void>`
|
|
223
|
+
|
|
224
|
+
The one teardown: stops syncing (socket close, timer cancels, and `Stopped` settlements all happen synchronously, before the first await — `void client.destroy()` in an unload path is safe), cleans up every collection from `createCollections`, detaches add-ons (Yjs fields), and closes the store connection. Nothing durable is lost — persisted rows and the offline outbox stay on disk, and the managed clientId is reused, so offline mutations still replay exactly once on the next construction. See [Closing a workspace](/guide/offline-persistence#closing-a-workspace).
|
|
225
|
+
|
|
226
|
+
### onMutationRejected (method)
|
|
227
|
+
|
|
228
|
+
`(listener: (error: MutationError, mutation: { name, args }) => void) => () => void`
|
|
229
|
+
|
|
230
|
+
The attach-later counterpart to the [`onMutationRejected` option](#onmutationrejected) — same payload, same "considered handled" semantics, both fire when both are set. For layers that mount after the client exists (a toast system, an error boundary). Returns an unsubscribe function.
|
|
231
|
+
|
|
232
|
+
### onDestroy
|
|
233
|
+
|
|
234
|
+
`(callback: () => void | Promise<void>) => () => void`
|
|
235
|
+
|
|
236
|
+
Register teardown work to run during `destroy()`; returns a deregister function. This is how add-ons tie their lifecycle to the client's.
|
|
237
|
+
|
|
238
|
+
### registerTable · registerApplier · sendBinary · onBinary
|
|
239
|
+
|
|
240
|
+
The extension seam — how `createCollections` and `@cf-sync/yjs/client` attach. Apps using the shipped adapters never call these; they are public so custom stores, custom collection layers, and binary-lane add-ons are plain library code with no privileged access.
|
|
241
|
+
|
|
242
|
+
## Errors
|
|
243
|
+
|
|
244
|
+
### MutationError
|
|
245
|
+
|
|
246
|
+
What an awaited `mutate` call rejects with and what `onMutationRejected` receives. `code` is the branchable identity, drawn from three groups:
|
|
247
|
+
|
|
248
|
+
| Group | Codes |
|
|
249
|
+
|---|---|
|
|
250
|
+
| Engine rejections (server refused before your mutator ran) | `InvalidArgs` · `UnknownMutator` · `RowTooLarge` |
|
|
251
|
+
| Client-local outcomes | `Timeout` · `Stopped` · `Fatal` · `LocalApplyFailed` |
|
|
252
|
+
| Your app's codes | whatever your mutators throw in `AppError('YourCode', …)`, passed through verbatim |
|
|
253
|
+
|
|
254
|
+
The built-in vocabulary is exported as `MutationErrorCode`. `message` is diagnostic prose — branch on `code`, not on it. `mutation` carries the rejected mutation's `{ name, args }` when the client knows them, so an awaiting `catch` has the same context the hook receives.
|
|
255
|
+
|
|
256
|
+
```ts
|
|
257
|
+
import { MutationError } from '@cf-sync/client'
|
|
258
|
+
|
|
259
|
+
try {
|
|
260
|
+
await client.mutate.issue.move({ id, column })
|
|
261
|
+
} catch (e) {
|
|
262
|
+
if (e instanceof MutationError && e.code === 'NotFound') {
|
|
263
|
+
toast('That issue was deleted by someone else.')
|
|
264
|
+
}
|
|
265
|
+
}
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
### SyncFatalError
|
|
269
|
+
|
|
270
|
+
What `onFatal` receives when the server permanently rejects this client. `code` is the close code (or `'VersionNotSupported'`/`'Unauthorized'` for in-band errors); `reason` is the close frame's slug (`membership-revoked`, `project-deleted`) — stable strings apps can branch on. The close-code bands (`4300` refresh vs `4400–4499` permanent) are covered in [Auth & sessions](/guide/auth#close-codes).
|
|
271
|
+
|
|
272
|
+
## Types
|
|
273
|
+
|
|
274
|
+
### SyncStatus
|
|
275
|
+
|
|
276
|
+
```ts
|
|
277
|
+
type SyncStatus = 'idle' | 'connecting' | 'syncing' | 'synced' | 'reconnecting' | 'fatal'
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
One value describing the pipe, not any individual mutation (those settle through `mutate`'s promise and `onMutationRejected`). `idle` is before `start()` and after `destroy()`; `connecting` covers hydration and the first socket attempt; `syncing` means the socket is open and catch-up is in flight; `synced` holds between pokes; `reconnecting` means backoff retries are running — queued mutations wait, nothing is lost, and the browser's `online`/`visibilitychange` events short-circuit the backoff so a reopened laptop reconnects immediately; `fatal` means the server permanently rejected this client.
|
|
281
|
+
|
|
282
|
+
### SyncStore
|
|
283
|
+
|
|
284
|
+
The persistence contract behind `persist`/`store` — implement it to substitute your own storage. `IndexedDBSyncStore` is the shipped default; `MemorySyncStore` is the in-memory reference implementation (useful in tests). Both are exported from `@cf-sync/client`.
|
|
285
|
+
|
|
286
|
+
## React hooks
|
|
287
|
+
|
|
288
|
+
From `@cf-sync/client/react` (React is an optional peer):
|
|
289
|
+
|
|
290
|
+
- `useSyncStatus(client)` — the current [`SyncStatus`](#syncstatus), reactively.
|
|
291
|
+
- `useHydrated(client)` — [`hydrated`](#hydrated), reactively; gate an offline-first first paint on this.
|
|
292
|
+
- `usePresence(client)` — the typed peers array, self excluded; re-renders on presence changes.
|
|
293
|
+
|
|
294
|
+
Collections are read with `useLiveQuery` from `@tanstack/react-db` — see [Collections](/reference/collections).
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
# Test engine
|
|
2
|
+
|
|
3
|
+
The in-memory workspace engine from `@cf-sync/server/testing`, for unit-testing [app definitions](/reference/define-kit#defineapp) — mutators and schema migrations — in plain vitest or jest. It runs in node with no workerd, miniflare, or bindings, yet executes the same write-buffer, validation, and error semantics as the [Workspace Durable Object](/reference/server) — shared engine core, not a reimplementation. See [Testing your app](/guide/testing) for the workflow.
|
|
4
|
+
|
|
5
|
+
```ts
|
|
6
|
+
import { createTestEngine } from '@cf-sync/server/testing'
|
|
7
|
+
import { app } from '../src/schema'
|
|
8
|
+
|
|
9
|
+
const engine = createTestEngine(app)
|
|
10
|
+
engine.seed('todos', 't1', { id: 't1', title: 'x', done: true })
|
|
11
|
+
const result = engine.mutate('todo.clearCompleted', {})
|
|
12
|
+
expect(result.error).toBeUndefined()
|
|
13
|
+
expect(engine.list('todos')).toEqual([])
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Import paths matter in node: this subpath and `@cf-sync/protocol` are safe, but the server's **main** entry imports `cloudflare:workers`, which node cannot load — never import `@cf-sync/server` itself in test files that run outside workerd.
|
|
17
|
+
|
|
18
|
+
## createTestEngine
|
|
19
|
+
|
|
20
|
+
`(app: AppDefinition, options?: TestEngineOptions) => TestEngine`
|
|
21
|
+
|
|
22
|
+
Creates a `TestEngine` from the shared app definition. Construction is where migration replay happens (see [`storedVersion`](#storedversion)), so a broken migration chain throws here — in the test run, not on a production workspace's first wake.
|
|
23
|
+
|
|
24
|
+
## Options
|
|
25
|
+
|
|
26
|
+
### clientId
|
|
27
|
+
|
|
28
|
+
`string` · default `"test"`
|
|
29
|
+
|
|
30
|
+
The clientId [`mutate`](#mutate) runs as; mutators see it as `ctx.clientId`. Use [`mutateAs`](#mutateas) to act as other clients without reconstructing the engine.
|
|
31
|
+
|
|
32
|
+
### principal
|
|
33
|
+
|
|
34
|
+
`string`
|
|
35
|
+
|
|
36
|
+
The principal mutators see as `ctx.principal` — what an `authorize` verdict would stamp on a real connection. Together with [`auth`](#auth), this makes `ctx.authoritative` permission checks testable without a socket in sight. See [Auth & sessions](/guide/auth).
|
|
37
|
+
|
|
38
|
+
### auth
|
|
39
|
+
|
|
40
|
+
`unknown`
|
|
41
|
+
|
|
42
|
+
The auth context mutators see as `ctx.auth`. Validated against the app's `authContext` schema at construction when one is declared — the parsed output is what mutators read — mirroring the DO's connect-time check, so an auth object your server would reject fails the test at construction too. Async validation is not supported and throws.
|
|
43
|
+
|
|
44
|
+
### storedVersion
|
|
45
|
+
|
|
46
|
+
`number` · default `app.version`
|
|
47
|
+
|
|
48
|
+
Simulates a workspace whose data was stored under an older schema version. When it equals `app.version` (the default), [`rows`](#rows) describe a fresh, current workspace and are validated like an admin import. When older, `rows` are stored **as-is** — old shapes, no validation — and the app's migration chain replays during construction, exactly like the DO's first wake after a deploy: one write buffer, net result validated at flush. A throwing migration step, a missing path, or a chain that produces schema-invalid rows throws from `createTestEngine` itself. See [Testing migrations](/guide/schema-evolution#testing-migrations).
|
|
49
|
+
|
|
50
|
+
### rows
|
|
51
|
+
|
|
52
|
+
`Record<string, Record<string, Record<string, unknown>>>`
|
|
53
|
+
|
|
54
|
+
Initial rows, keyed table → id → row data. Whether they are validated or taken raw depends on [`storedVersion`](#storedversion) above.
|
|
55
|
+
|
|
56
|
+
## Methods
|
|
57
|
+
|
|
58
|
+
### mutate
|
|
59
|
+
|
|
60
|
+
`(name, args?) => TestMutationResult`
|
|
61
|
+
|
|
62
|
+
Applies a named mutation authoritatively as the engine's default client, with the server's semantics: args are parsed first (invalid args are a permanent error), then the mutator runs against a write buffer that only commits on success. Names and args are typed from the app definition, and `tx.put` validates rows against the table schema — mutators read back parsed output with defaults applied. The outcome splits exactly as the [engine invariants](/guide/mutations) demand:
|
|
63
|
+
|
|
64
|
+
- An `AppError` thrown by the mutator — or invalid args — is a **permanent** rejection: writes are discarded, the result carries [`error`](#testmutationresult), and [`lastMutationId`](#lastmutationid) still advances. Assert on both when testing rejection paths.
|
|
65
|
+
- Any other throw is **transient**: it rethrows out of `mutate`, nothing commits, and the LMID does not advance — the real client would retry the push.
|
|
66
|
+
|
|
67
|
+
### mutateAs
|
|
68
|
+
|
|
69
|
+
`(clientId, name, args?) => TestMutationResult`
|
|
70
|
+
|
|
71
|
+
[`mutate`](#mutate) as a specific clientId — for testing mutators that read `ctx.clientId`, or for multi-client LMID assertions. Each clientId keeps its own mutation sequence.
|
|
72
|
+
|
|
73
|
+
### get
|
|
74
|
+
|
|
75
|
+
`(table, id) => RowOf | null`
|
|
76
|
+
|
|
77
|
+
The live row, parsed through the table schema when it was written. Returns `null` for a row that does not exist **or was deleted** — assert `toBeNull()` for deletions, not `toBeUndefined()`.
|
|
78
|
+
|
|
79
|
+
### list
|
|
80
|
+
|
|
81
|
+
`(table) => Array<{ id, data }>`
|
|
82
|
+
|
|
83
|
+
All live rows in a table.
|
|
84
|
+
|
|
85
|
+
### seed
|
|
86
|
+
|
|
87
|
+
`(table, id, data) => void`
|
|
88
|
+
|
|
89
|
+
Stores a row directly, outside any mutation — test setup for state the server would already hold. Validated against the table schema with defaults applied, like every server-side write, so seeds cannot put the engine in a state the real server could never reach.
|
|
90
|
+
|
|
91
|
+
### lastMutationId
|
|
92
|
+
|
|
93
|
+
`(clientId?) => number`
|
|
94
|
+
|
|
95
|
+
The last mutation id confirmed for a client (the engine's default client when omitted); `0` before any mutation. Permanent errors advance it too — that is invariant 2, and the thing worth asserting alongside `result.error`.
|
|
96
|
+
|
|
97
|
+
### clientId · version
|
|
98
|
+
|
|
99
|
+
Read-only getters: the default clientId, and the current data version — bumps only when a mutation or seed actually writes rows.
|
|
100
|
+
|
|
101
|
+
## Types
|
|
102
|
+
|
|
103
|
+
### TestMutationResult
|
|
104
|
+
|
|
105
|
+
`{ error?: { code: string; message: string } }`
|
|
106
|
+
|
|
107
|
+
The outcome of one authoritative mutation. `error` is present only for permanent rejections: `code` is an engine built-in (`InvalidArgs`, `UnknownMutator`, …) or an app-defined `AppError` code passed through verbatim — the same vocabulary the client's [`MutationError`](/reference/sync-client#mutationerror) carries. Transient failures never produce a result; they throw.
|
|
108
|
+
|
|
109
|
+
## Schema-drift helpers
|
|
110
|
+
|
|
111
|
+
The CI side of [drift detection](/guide/schema-evolution#drift-detection) — catching the one schema mistake the type system cannot: changing a table schema without bumping `version`.
|
|
112
|
+
|
|
113
|
+
### checkSchemaEvolution
|
|
114
|
+
|
|
115
|
+
`(app, snapshotPath: string | URL) => Promise<SchemaSnapshot>`
|
|
116
|
+
|
|
117
|
+
One test next to your app definition that fails the build on an unbumped schema change — the deployed engine only detects it after the fact, as a warning in Durable Object logs. The snapshot file works like a jest snapshot: commit it. The first run scaffolds it; a legitimate version bump rewrites it automatically (the bump is the fix, so the test passes); a schema change **without** a bump throws with the exact `migrations` entry to add. Presence is deliberately outside the fingerprint — never stored, so reshaping it needs no bump. Node-only, like everything in this subpath.
|
|
118
|
+
|
|
119
|
+
```ts
|
|
120
|
+
it('every schema change ships with a version bump', async () => {
|
|
121
|
+
await checkSchemaEvolution(app, new URL('./schema-snapshot.json', import.meta.url))
|
|
122
|
+
})
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
### schemaFingerprint
|
|
126
|
+
|
|
127
|
+
`(schema) => string`
|
|
128
|
+
|
|
129
|
+
The structural fingerprint of the table schemas — the same one the Durable Object stores for runtime drift detection. Exposed for custom tooling; `checkSchemaEvolution` calls it for you. It derives from zod's JSON Schema emission, so a zod upgrade can shift it with no semantic change (the rare false positive — delete the snapshot file to re-baseline); non-zod standard-schema tables are opaque and never trigger drift.
|
|
130
|
+
|
|
131
|
+
### SchemaSnapshot
|
|
132
|
+
|
|
133
|
+
`{ version: number; fingerprint: string }`
|
|
134
|
+
|
|
135
|
+
What `checkSchemaEvolution` stores in — and returns from — its snapshot file.
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
# Yjs fields
|
|
2
|
+
|
|
3
|
+
The collaborative-text add-on from `@cf-sync/yjs` — per-field Y.Docs hosted inside the same Workspace Durable Object as your rows, synced over a binary lane on the existing socket. Three entry points, one per side: `./server` registers the extension on the DO, `./client` attaches field handles to a [`SyncClient`](/reference/sync-client), `./react` wraps a handle in a hook. `yjs` is a peer dependency of the add-on (react an optional one); the cf-sync core stays yjs-free. For the model and when to reach for it, see [Collaborative text](/guide/collaborative-text).
|
|
4
|
+
|
|
5
|
+
```ts
|
|
6
|
+
// worker
|
|
7
|
+
extension: yjsFields({ app, authorizeWrite: ({ auth }) => auth?.role !== 'viewer' })
|
|
8
|
+
|
|
9
|
+
// browser
|
|
10
|
+
const fields = createYjsFields(client)
|
|
11
|
+
const handle = fields.getDoc(`todo-notes:${todoId}`)
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
## Server — `@cf-sync/yjs/server`
|
|
15
|
+
|
|
16
|
+
### yjsFields
|
|
17
|
+
|
|
18
|
+
`(options?: YjsFieldsOptions) => () => EngineExtension`
|
|
19
|
+
|
|
20
|
+
The extension factory, passed to [`createWorkspaceDO`](/reference/server)'s `extension` option. It returns a factory rather than an extension: the DO calls it once per workspace instance, so the doc cache and per-socket refusal state are per-workspace by construction — Cloudflare colocates instances of one DO class in a shared isolate, and extension state must never cross workspaces. Storage is two SQLite tables in the workspace DO (snapshot per field plus an update log); the typing path appends and relays without ever materializing a document.
|
|
21
|
+
|
|
22
|
+
### authorizeWrite
|
|
23
|
+
|
|
24
|
+
`(ctx: YjsFieldWriteContext) => boolean` · default: any member writes
|
|
25
|
+
|
|
26
|
+
The per-field write gate. `ctx` is `{ fieldId, auth, principal, clientId }` — the target field plus the connection's identity as stamped by the sync router's [`authorize` hook](/guide/auth) (`auth` is the verdict's context, `undefined` when no hook stamped one). `fieldId` makes per-field policies expressible: encode the owning entity into your ids (`note:<noteId>`) and derive the check from there. A `false` verdict is not an error path — it sets `writable: false` in the sync reply so [`canWrite`](#yjsfieldhandle) is read-only from first paint, and an update that arrives anyway earns a `NotWritable` reject.
|
|
27
|
+
|
|
28
|
+
### app
|
|
29
|
+
|
|
30
|
+
`AppDefinition` · typing only
|
|
31
|
+
|
|
32
|
+
The same [app definition](/reference/define-kit#defineapp) the DO takes. Passing it closes the type loop: `authorizeWrite`'s `auth` derives from the `authContext` schema already declared in `defineMutators` — one declaration, flowing everywhere. Without an app value in scope, the explicit generic (`yjsFields<MyAuthContext>({ authorizeWrite })`) is the escape hatch.
|
|
33
|
+
|
|
34
|
+
### maxCachedDocs
|
|
35
|
+
|
|
36
|
+
`number` · default `8`
|
|
37
|
+
|
|
38
|
+
Y.Docs held in memory (LRU) — sync requests are served from here instead of rebuilding snapshot-plus-tail from SQLite. Fields cap at 700 000 bytes each, so the default bounds worst-case doc memory around ~6MB per workspace.
|
|
39
|
+
|
|
40
|
+
### compactionThreshold
|
|
41
|
+
|
|
42
|
+
`number` · default `200`
|
|
43
|
+
|
|
44
|
+
Pending update-log rows per field that trigger compaction — materialize, re-encode as one snapshot, delete the tail — on the DO's maintenance alarm. Lower means smaller logs and faster cold loads at the cost of more alarm work.
|
|
45
|
+
|
|
46
|
+
## Client — `@cf-sync/yjs/client`
|
|
47
|
+
|
|
48
|
+
### createYjsFields
|
|
49
|
+
|
|
50
|
+
`(client: YjsFieldsClient) => YjsFields`
|
|
51
|
+
|
|
52
|
+
Attaches the fields surface to a client. `YjsFieldsClient` is a structural interface satisfied by `SyncClient` (its `sendBinary`/`onBinary`/`subscribeStatus`/`onDestroy` [extension seam](/reference/sync-client#registertable--registerapplier--sendbinary--onbinary)) — the add-on is plain library code with no privileged access. The library owns transport and lifecycle: every connection that reaches `synced` re-syncs every held doc in one round-trip each way (edits typed offline merge on resume — apps write no reconnect glue), and `client.destroy()` tears the fields down too via `onDestroy`.
|
|
53
|
+
|
|
54
|
+
The returned `YjsFields` has two methods: `getDoc(fieldId)` returns a [`YjsFieldHandle`](#yjsfieldhandle) (fields are created implicitly on first use; ids must be 1–256 UTF-8 bytes or `getDoc` throws), and `destroy()` detaches from the client and destroys every held doc.
|
|
55
|
+
|
|
56
|
+
### YjsFieldHandle
|
|
57
|
+
|
|
58
|
+
A ref-counted live view of one field. Two call sites holding the same `fieldId` share one underlying doc; `release()` decrements, and at refcount zero local state is dropped and the doc destroyed. There is no local persistence — a reload re-fetches small documents in one round-trip, and an app that wants offline field durability attaches y-indexeddb to `doc` itself.
|
|
59
|
+
|
|
60
|
+
- `doc` — the underlying `Y.Doc`, for rich-text bindings (a `Y.XmlFragment` for y-prosemirror and the like); the app owns the key — one field is one shape, chosen once.
|
|
61
|
+
- `text` — the paved path: a `Y.Text` at a fixed, library-owned key, so every reader and writer of a field agrees on type and key with nothing to coordinate.
|
|
62
|
+
- `whenSynced` — resolves on the first server state and stays resolved. It answers "can I render this field", not "am I currently live" — liveness is the client's [`SyncStatus`](/reference/sync-client#syncstatus).
|
|
63
|
+
- `canWrite` — whether this client may write, reactively: the server's writable flag, flipped `false` by any reject. A reject-flipped `false` is **sticky for the handle's lifetime** — only this client knows its local doc holds an op the server refused, so a later state saying writable must not resume uploading (it would re-send the refused op forever). Starts `false` and is meaningful after `whenSynced` — never guessed, so readers get no flash of editable UI.
|
|
64
|
+
- `writeBlocked` — *why* `canWrite` is false, or `null` while writable (or pre-sync): `'NotWritable'` (no write access), `'Frozen'` (administratively frozen), `'TooLarge'` (the server refused an oversized update), `'LocalTooLarge'` (the client's own frame guard tripped before sending). Render the difference — "this document is full" and "you can't edit this" deserve different UI.
|
|
65
|
+
- `subscribe(listener)` — notifies on `canWrite`/`writeBlocked` or first-sync changes; returns an unsubscribe function.
|
|
66
|
+
- `release()` — drop this reference; idempotent.
|
|
67
|
+
|
|
68
|
+
A non-writable field never sends: local edits stay buffered in the doc, and the apply-then-reject path is designed out rather than handled.
|
|
69
|
+
|
|
70
|
+
### MAX_FIELD_UPDATE_BYTES
|
|
71
|
+
|
|
72
|
+
`number` · `200_000`
|
|
73
|
+
|
|
74
|
+
The transport's ceiling on a single field update frame — the server rejects anything larger with `TooLarge`, and the client's own frame guard refuses to send it first (the field collapses to read-only locally, with a console warning, before an in-flight tail can poison the server's log). It is re-exported here so editor bindings can guard input size — a textarea `maxLength`, a paste guard — against the same limit the transport enforces, without reaching into `@cf-sync/protocol/internal`. The guard in the editor is the paved fix; the frame guard is the backstop.
|
|
75
|
+
|
|
76
|
+
## React — `@cf-sync/yjs/react`
|
|
77
|
+
|
|
78
|
+
### useYjsField
|
|
79
|
+
|
|
80
|
+
`(fields: YjsFields, fieldId: string) => YjsFieldState`
|
|
81
|
+
|
|
82
|
+
The paved-path binding for one field: owns the whole handle lifecycle — acquire on mount, `release()` on unmount, re-acquire on `fieldId` change — plus the sync gate and reactive `canWrite`.
|
|
83
|
+
|
|
84
|
+
```tsx
|
|
85
|
+
const field = useYjsField(fields, `todo-notes:${todoId}`)
|
|
86
|
+
if (!field.synced) return <Spinner />
|
|
87
|
+
return <Editor text={field.text} readOnly={!field.canWrite} />
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Re-renders happen on sync and permission changes only — **not** per keystroke. Deliberate: editor bindings (y-codemirror, y-prosemirror, a hand-rolled textarea observer) attach to `text`/`doc` and own content updates themselves, exactly as everywhere else in the Yjs ecosystem. StrictMode's double mount is safe (the second acquire re-fetches in one round-trip), and server rendering returns the unsynced state — matching the client's first paint, so hydration agrees. Switching `fieldId` snaps back to unsynced rather than leaking the previous field's content through one render.
|
|
91
|
+
|
|
92
|
+
### YjsFieldState
|
|
93
|
+
|
|
94
|
+
Discriminated on `synced`, so the loading state is impossible to forget:
|
|
95
|
+
|
|
96
|
+
```ts
|
|
97
|
+
type YjsFieldState =
|
|
98
|
+
| { synced: false; handle: null; doc: null; text: null; canWrite: false; writeBlocked: null }
|
|
99
|
+
| { synced: true; handle: YjsFieldHandle; doc: Y.Doc; text: Y.Text; canWrite: boolean; writeBlocked: WriteBlockedReason | null }
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
`writeBlocked` carries the [reason](#yjsfieldhandle) `canWrite` is false, so the read-only banner can say why.
|
|
103
|
+
|
|
104
|
+
## Field ids are an app convention
|
|
105
|
+
|
|
106
|
+
The engine never interprets field ids — `todo-notes:<todoId>` is your pointer, not its foreign key. Consequently **deleting a row does not delete its field**; an app that wants orphaned fields collected deletes them through the same [admin surface](/guide/operations) that exports and imports them.
|
|
107
|
+
|
|
108
|
+
## Operations
|
|
109
|
+
|
|
110
|
+
The [admin surface](/guide/operations) is fields-aware. `stats` includes the extension's gauges — `fields`, `frozenFields`, `fieldBytes`, `pendingUpdates`, `cachedDocs` — and `export`/`import` round-trip fields alongside rows: export compacts each field to one base64 snapshot, import validates every snapshot by applying it (a snapshot that cannot build a doc fails the whole import, not a future read) and replaces the field tables wholesale.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@cf-sync/client",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"description": "Browser client for cf-sync: SyncClient (optimistic mutations, offline outbox, IndexedDB mirror, presence) and a TanStack DB collection adapter, with React hooks",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -33,13 +33,14 @@
|
|
|
33
33
|
"./package.json": "./package.json"
|
|
34
34
|
},
|
|
35
35
|
"files": [
|
|
36
|
-
"dist"
|
|
36
|
+
"dist",
|
|
37
|
+
"docs"
|
|
37
38
|
],
|
|
38
39
|
"publishConfig": {
|
|
39
40
|
"access": "public"
|
|
40
41
|
},
|
|
41
42
|
"dependencies": {
|
|
42
|
-
"@cf-sync/protocol": "^0.1.
|
|
43
|
+
"@cf-sync/protocol": "^0.1.1"
|
|
43
44
|
},
|
|
44
45
|
"peerDependencies": {
|
|
45
46
|
"@tanstack/db": "^0.6.16",
|
|
@@ -66,7 +67,7 @@
|
|
|
66
67
|
"vitest": "^4.1.10",
|
|
67
68
|
"yjs": "^13.6.31",
|
|
68
69
|
"zod": "^4.0.0",
|
|
69
|
-
"@cf-sync/yjs": "0.
|
|
70
|
+
"@cf-sync/yjs": "0.2.0"
|
|
70
71
|
},
|
|
71
72
|
"scripts": {
|
|
72
73
|
"build": "tsdown",
|