@cf-sync/client 0.1.0
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/LICENSE +21 -0
- package/README.md +32 -0
- package/dist/client-tvsT_ixa.d.ts +714 -0
- package/dist/index.d.ts +139 -0
- package/dist/index.js +2051 -0
- package/dist/react.d.ts +49 -0
- package/dist/react.js +53 -0
- package/package.json +76 -0
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
import { S as SyncFatalError, _ as Mutate, a as SyncLogger, b as MutationErrorCode, c as TableHooks, d as MemorySyncStore, f as PersistedOutboxEntry, g as SyncStore, h as PokePersist, i as SyncClientOptions, l as TableWriteOp, m as PersistedState, n as IntentTransactionRunner, o as SyncStatus, p as PersistedRowOp, r as PresenceApi, s as TableApplier, t as SyncClient, u as WebSocketLike, v as MutateNamespace, x as SyncFatalCode, y as MutationError } from "./client-tvsT_ixa.js";
|
|
2
|
+
import { AnyMutators, AnyMutators as AnyMutators$1, AnySyncSchema, AnySyncSchema as AnySyncSchema$1, AppDefinition, AppError, AuthContextOf, CLOSE_AUTH_CONTEXT_INVALID, CLOSE_PERMANENT_MAX, CLOSE_PERMANENT_MIN, CLOSE_REFRESH, CLOSE_SUPERSEDED, CLOSE_UNAUTHORIZED, CLOSE_VERSION_NOT_SUPPORTED, CrudDelArgs, CrudMutators, CrudPutArgs, EngineErrorCode, MutationArgs, MutatorContext, MutatorDef, MutatorTx, MutatorsFor, PresenceOf, PresencePeer, RowInputOf, RowInputOf as RowInputOf$1, RowOf, RowOf as RowOf$1, SchemaMigration, SchemaMigrationFn, StandardSchemaV1, StandardSchemaV1 as StandardSchemaV1$1, SyncSchema, TableName, TableName as TableName$1, TableSchema, crudMutators, defineApp, defineMutators, defineSchema, isPermanentCloseCode } from "@cf-sync/protocol";
|
|
3
|
+
import { Collection, CollectionConfig } from "@tanstack/db";
|
|
4
|
+
//#region src/collection.d.ts
|
|
5
|
+
/**
|
|
6
|
+
* Configuration for {@link workspaceCollectionOptions}: the client, the
|
|
7
|
+
* schema table to bind, and optional key and sync-start behavior. `getKey`
|
|
8
|
+
* is required only when the table's row schema has no string `id` field.
|
|
9
|
+
*/
|
|
10
|
+
type WorkspaceCollectionConfig<S extends AnySyncSchema$1, K extends TableName$1<S>> = {
|
|
11
|
+
client: SyncClient<S, any>;
|
|
12
|
+
/** Server-side table name (a key of the client's schema). One collection per table. */
|
|
13
|
+
table: K;
|
|
14
|
+
/** Start syncing immediately instead of on first subscriber. */
|
|
15
|
+
startSync?: boolean;
|
|
16
|
+
} & (RowOf$1<S, K> extends {
|
|
17
|
+
id: string;
|
|
18
|
+
} ? {
|
|
19
|
+
/** Defaults to `row.id` — the row schema has a string `id` field. */
|
|
20
|
+
getKey?: (row: RowOf$1<S, K>) => string;
|
|
21
|
+
} : {
|
|
22
|
+
/** Required: the row schema has no string `id` field to default to. */
|
|
23
|
+
getKey: (row: RowOf$1<S, K>) => string;
|
|
24
|
+
});
|
|
25
|
+
/**
|
|
26
|
+
* TanStack DB collection options creator backed by a cf-sync SyncClient.
|
|
27
|
+
* The row type, the collection's runtime validation schema, and the key
|
|
28
|
+
* function all derive from the table's entry in the shared `defineSchema`.
|
|
29
|
+
*
|
|
30
|
+
* Synced data flows through the poke pipeline (begin/write/commit per poke,
|
|
31
|
+
* truncate on reset). Local writes become `sync.put` / `sync.del` mutations;
|
|
32
|
+
* each handler resolves only when the server confirms the mutation, at which
|
|
33
|
+
* point TanStack DB drops the optimistic overlay (TanStack's store handles
|
|
34
|
+
* rebasing overlays on top of newly synced state).
|
|
35
|
+
*
|
|
36
|
+
* Table hooks register with the client at options creation, buffered until
|
|
37
|
+
* TanStack starts the sync pipeline — a lazily-subscribed collection costs no
|
|
38
|
+
* full resync. The collection also serves as `mutate`'s optimistic surface:
|
|
39
|
+
* intent mutations run their shared `apply` against it locally.
|
|
40
|
+
*/
|
|
41
|
+
declare function workspaceCollectionOptions<S extends AnySyncSchema$1, K extends TableName$1<S>>(cfg: WorkspaceCollectionConfig<S, K>): CollectionConfig<RowOf$1<S, K> & object, string, S['tables'][K] & StandardSchemaV1$1> & {
|
|
42
|
+
schema: S['tables'][K] & StandardSchemaV1$1;
|
|
43
|
+
};
|
|
44
|
+
/** One live TanStack DB collection per table in the app's schema. */
|
|
45
|
+
type WorkspaceCollections<S extends AnySyncSchema$1> = { [K in TableName$1<S>]: Collection<RowOf$1<S, K> & object, string, {}, S['tables'][K] & StandardSchemaV1$1, RowInputOf$1<S, K> & object>; };
|
|
46
|
+
/**
|
|
47
|
+
* Creates one collection per table in the client's schema, fully typed —
|
|
48
|
+
* the one-line alternative to a `createCollection(workspaceCollectionOptions(…))`
|
|
49
|
+
* block per table:
|
|
50
|
+
*
|
|
51
|
+
* ```ts
|
|
52
|
+
* const { todos, issues } = createCollections(client)
|
|
53
|
+
* ```
|
|
54
|
+
*
|
|
55
|
+
* Collections start syncing immediately (`startSync` defaults to true here,
|
|
56
|
+
* unlike `workspaceCollectionOptions`, which keeps TanStack's lazy default):
|
|
57
|
+
* the client receives pokes for every table on the one socket regardless, so
|
|
58
|
+
* eager sync costs no extra network — it only applies already-buffered data,
|
|
59
|
+
* and first render sees rows without waiting for a subscriber. Pass
|
|
60
|
+
* `{ startSync: false }` to defer to first subscriber anyway.
|
|
61
|
+
*
|
|
62
|
+
* Rows are keyed by their `id` field (this engine's row model); a table whose
|
|
63
|
+
* rows key differently needs an individual `workspaceCollectionOptions` call
|
|
64
|
+
* with its own `getKey`.
|
|
65
|
+
*/
|
|
66
|
+
declare function createCollections<S extends AnySyncSchema$1>(client: SyncClient<S, any>, options?: {
|
|
67
|
+
startSync?: boolean;
|
|
68
|
+
}): WorkspaceCollections<S>;
|
|
69
|
+
/** What {@link createWorkspace} returns: the client, its collections, and the one teardown — held and threaded as a unit. */
|
|
70
|
+
interface Workspace<S extends AnySyncSchema$1, M extends AnyMutators$1 = AnyMutators$1, P extends StandardSchemaV1$1 | undefined = StandardSchemaV1$1 | undefined> {
|
|
71
|
+
client: SyncClient<S, M, P>;
|
|
72
|
+
collections: WorkspaceCollections<S>;
|
|
73
|
+
/** Tears down the client, every collection, and the store connection — `client.destroy()` under one roof. */
|
|
74
|
+
destroy: () => Promise<void>;
|
|
75
|
+
}
|
|
76
|
+
/**
|
|
77
|
+
* The one-call bootstrap: constructs the `SyncClient` and every collection,
|
|
78
|
+
* and returns them with their shared teardown —
|
|
79
|
+
*
|
|
80
|
+
* ```ts
|
|
81
|
+
* const ws = createWorkspace({ url: SYNC_URL, workspaceId, app, persist: true })
|
|
82
|
+
* ws.collections.todos.insert({ id, title: 'ship it' })
|
|
83
|
+
* await ws.client.mutate.todos.clearCompleted()
|
|
84
|
+
* ```
|
|
85
|
+
*
|
|
86
|
+
* The unit shape is the point for workspace-per-project apps: switching
|
|
87
|
+
* projects is `await ws.destroy()` then `createWorkspace({ ...same, workspaceId: next })`
|
|
88
|
+
* — nothing to individually rebuild or re-thread. Takes every
|
|
89
|
+
* `SyncClientOptions` field, plus `startSync` forwarded to
|
|
90
|
+
* {@link createCollections}.
|
|
91
|
+
*/
|
|
92
|
+
declare function createWorkspace<S extends AnySyncSchema$1, M extends AnyMutators$1, P extends StandardSchemaV1$1 | undefined = undefined>(options: SyncClientOptions<S, M, P> & {
|
|
93
|
+
startSync?: boolean;
|
|
94
|
+
}): Workspace<S, M, P>;
|
|
95
|
+
//#endregion
|
|
96
|
+
//#region src/idb-store.d.ts
|
|
97
|
+
/**
|
|
98
|
+
* Constructor options for {@link IndexedDBSyncStore} — where its database
|
|
99
|
+
* lives and which clientId's outbox partition it owns.
|
|
100
|
+
*/
|
|
101
|
+
interface IndexedDBSyncStoreOptions {
|
|
102
|
+
/** One database per workspace; safe to share across tabs. */
|
|
103
|
+
workspaceId: string;
|
|
104
|
+
/** Partitions the outbox: each tab/session replays only its own mutations. */
|
|
105
|
+
clientId: string;
|
|
106
|
+
/** Database name prefix. Default: "cf-sync". */
|
|
107
|
+
dbNamePrefix?: string;
|
|
108
|
+
/** Outbox records from clientIds idle longer than this are GC'd on load. Default: 30 days. */
|
|
109
|
+
outboxMaxAgeMs?: number;
|
|
110
|
+
/** Injectable for tests. Default: globalThis.indexedDB. */
|
|
111
|
+
indexedDB?: IDBFactory;
|
|
112
|
+
}
|
|
113
|
+
/**
|
|
114
|
+
* SyncStore over IndexedDB. Rows, cursor, and outbox commit in a single
|
|
115
|
+
* IndexedDB transaction spanning all three object stores, which is what
|
|
116
|
+
* upholds the cursor-never-newer-than-rows contract.
|
|
117
|
+
*
|
|
118
|
+
* The rows and meta stores are shared by every tab on the workspace; a
|
|
119
|
+
* subsumption guard makes concurrent writers safe: a poke whose cursor does
|
|
120
|
+
* not advance past the stored one is skipped, because catch-up patches carry
|
|
121
|
+
* current row state (not historical deltas), so the newer writer's rows
|
|
122
|
+
* already cover it. Outbox records are per-clientId, so tabs never touch
|
|
123
|
+
* each other's pending mutations.
|
|
124
|
+
*
|
|
125
|
+
* All operations run through an internal queue, preserving call order even
|
|
126
|
+
* though callers fire-and-forget.
|
|
127
|
+
*/
|
|
128
|
+
declare class IndexedDBSyncStore implements SyncStore {
|
|
129
|
+
#private;
|
|
130
|
+
constructor(opts: IndexedDBSyncStoreOptions);
|
|
131
|
+
load(): Promise<PersistedState | null>;
|
|
132
|
+
applyPoke(update: PokePersist): Promise<void>;
|
|
133
|
+
saveOutbox(outbox: PersistedOutboxEntry[], confirmedLmid: number): Promise<void>;
|
|
134
|
+
reset(): Promise<void>;
|
|
135
|
+
/** Closes the database connection (tests and teardown). */
|
|
136
|
+
close(): Promise<void>;
|
|
137
|
+
}
|
|
138
|
+
//#endregion
|
|
139
|
+
export { type AnyMutators, type AnySyncSchema, type AppDefinition, AppError, type AuthContextOf, CLOSE_AUTH_CONTEXT_INVALID, CLOSE_PERMANENT_MAX, CLOSE_PERMANENT_MIN, CLOSE_REFRESH, CLOSE_SUPERSEDED, CLOSE_UNAUTHORIZED, CLOSE_VERSION_NOT_SUPPORTED, type CrudDelArgs, type CrudMutators, type CrudPutArgs, type EngineErrorCode, IndexedDBSyncStore, type IndexedDBSyncStoreOptions, type IntentTransactionRunner, MemorySyncStore, type Mutate, type MutateNamespace, type MutationArgs, MutationError, type MutationErrorCode, type MutatorContext, type MutatorDef, type MutatorTx, type MutatorsFor, type PersistedOutboxEntry, type PersistedRowOp, type PersistedState, type PokePersist, type PresenceApi, type PresenceOf, type PresencePeer, type RowInputOf, type RowOf, type SchemaMigration, type SchemaMigrationFn, type StandardSchemaV1, SyncClient, type SyncClientOptions, type SyncFatalCode, SyncFatalError, type SyncLogger, type SyncSchema, type SyncStatus, type SyncStore, type TableApplier, type TableHooks, type TableName, type TableSchema, type TableWriteOp, type WebSocketLike, type Workspace, type WorkspaceCollectionConfig, type WorkspaceCollections, createCollections, createWorkspace, crudMutators, defineApp, defineMutators, defineSchema, isPermanentCloseCode, workspaceCollectionOptions };
|