@tapedb/tapedb 0.0.0-stage → 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/API.md +301 -0
- package/LICENSE +21 -0
- package/LIMITATIONS.md +34 -0
- package/PRIVACY.md +119 -0
- package/README.md +720 -2
- package/RELEASING.md +117 -0
- package/SECURITY.md +121 -0
- package/dist/chunk-3AL32Q4K.js +241 -0
- package/dist/chunk-3AL32Q4K.js.map +1 -0
- package/dist/chunk-CYDXFAEB.js +33 -0
- package/dist/chunk-CYDXFAEB.js.map +1 -0
- package/dist/chunk-UYZJAMBR.js +27 -0
- package/dist/chunk-UYZJAMBR.js.map +1 -0
- package/dist/chunk-VWW5OS5B.js +841 -0
- package/dist/chunk-VWW5OS5B.js.map +1 -0
- package/dist/cli.d.ts +44 -0
- package/dist/cli.js +1501 -0
- package/dist/cli.js.map +1 -0
- package/dist/client-DgSnn9BE.d.ts +646 -0
- package/dist/index.d.ts +24 -0
- package/dist/index.js +3007 -0
- package/dist/index.js.map +1 -0
- package/dist/react.d.ts +41 -0
- package/dist/react.js +59 -0
- package/dist/react.js.map +1 -0
- package/dist/schema-CVcGZJfR.d.ts +691 -0
- package/dist/schema-entry-CpO_IGFv.d.ts +522 -0
- package/dist/schema.d.ts +2 -0
- package/dist/schema.js +22 -0
- package/dist/schema.js.map +1 -0
- package/dist/worker.d.ts +437 -0
- package/dist/worker.js +9270 -0
- package/dist/worker.js.map +1 -0
- package/package.json +93 -4
|
@@ -0,0 +1,646 @@
|
|
|
1
|
+
import { O as OutboxEntry, I as InitConfig, d as StorageFetch, e as TransactInput, f as TxOp, g as QueryDocument, i as QueryResult, j as QueryPageInfo, k as QueryState, P as PresencePeer, l as TopicListener, D as DataClient, Q as QueryError, T as TopicSender, S as StorageObject, b as WriteRejection } from './schema-CVcGZJfR.js';
|
|
2
|
+
import { M as Models, e as Fields, W as Where, O as OrderBy, I as Include, g as Select, h as Selected, R as Row, i as WithInclude, j as FieldsOf, k as ModelInfo, l as AggregateMeasures, n as AggregateOutput, G as GroupKeys, o as GroupRow, b as CreateData, U as UpdateData, c as Schema } from './schema-entry-CpO_IGFv.js';
|
|
3
|
+
|
|
4
|
+
interface RecoveringRetryOptions {
|
|
5
|
+
waitMs?: number;
|
|
6
|
+
sleep?: (ms: number) => Promise<void>;
|
|
7
|
+
now?: () => number;
|
|
8
|
+
}
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* IndexedDB-backed outbox for unacknowledged writes.
|
|
12
|
+
*
|
|
13
|
+
* The outbox is keyed by `clientTxId`, so retrying the same optimistic write
|
|
14
|
+
* replaces the pending entry instead of appending a duplicate. When
|
|
15
|
+
* IndexedDB is unavailable (server render, tests, private-mode failures) the
|
|
16
|
+
* same operations run against an in-memory map.
|
|
17
|
+
*/
|
|
18
|
+
|
|
19
|
+
interface Outbox {
|
|
20
|
+
add(entry: OutboxEntry): Promise<void>;
|
|
21
|
+
list(workspaceId: string): Promise<OutboxEntry[]>;
|
|
22
|
+
remove(clientTxId: string): Promise<void>;
|
|
23
|
+
clear(workspaceId?: string): Promise<void>;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* One shared WebSocket per data client, with reconnect + resubscribe.
|
|
28
|
+
*
|
|
29
|
+
* Browsers cannot set an `Authorization` header on a WebSocket upgrade, so
|
|
30
|
+
* the role claim rides in `Sec-WebSocket-Protocol` (see socket-protocol.ts),
|
|
31
|
+
* never in the URL. A fresh token is fetched for every reconnect attempt.
|
|
32
|
+
*/
|
|
33
|
+
|
|
34
|
+
interface WebSocketLike {
|
|
35
|
+
send(data: string): void;
|
|
36
|
+
close(code?: number, reason?: string): void;
|
|
37
|
+
onopen: ((event: unknown) => void) | null;
|
|
38
|
+
onmessage: ((event: {
|
|
39
|
+
data: unknown;
|
|
40
|
+
}) => void) | null;
|
|
41
|
+
onerror: ((event: unknown) => void) | null;
|
|
42
|
+
onclose: ((event: unknown) => void) | null;
|
|
43
|
+
}
|
|
44
|
+
/** Creates a socket for `url`, offering `protocols` (they carry the claim; pass them on). */
|
|
45
|
+
type WebSocketFactory = (url: string, protocols: string[]) => WebSocketLike;
|
|
46
|
+
|
|
47
|
+
/** One recorded change to a row (`db.$history`). */
|
|
48
|
+
interface HistoryEntry {
|
|
49
|
+
/** Log sequence of the transaction. */
|
|
50
|
+
seq: number;
|
|
51
|
+
/** Commit time, ms since the epoch. */
|
|
52
|
+
at: number;
|
|
53
|
+
/** The writer's claim subject. */
|
|
54
|
+
sub: string | null;
|
|
55
|
+
/** The writer's workspace role level. */
|
|
56
|
+
role: number | null;
|
|
57
|
+
action: "insert" | "update" | "delete";
|
|
58
|
+
}
|
|
59
|
+
interface FetchResponseLike {
|
|
60
|
+
body?: ReadableStream<Uint8Array> | null;
|
|
61
|
+
ok: boolean;
|
|
62
|
+
status: number;
|
|
63
|
+
json(): Promise<unknown>;
|
|
64
|
+
}
|
|
65
|
+
type FetchLike = (url: string, init: {
|
|
66
|
+
method: string;
|
|
67
|
+
headers: Record<string, string>;
|
|
68
|
+
body?: string;
|
|
69
|
+
}) => Promise<FetchResponseLike>;
|
|
70
|
+
interface ClientDeps {
|
|
71
|
+
fetch?: FetchLike;
|
|
72
|
+
storageFetch?: StorageFetch;
|
|
73
|
+
createWebSocket?: WebSocketFactory;
|
|
74
|
+
outbox?: Outbox;
|
|
75
|
+
now?: () => number;
|
|
76
|
+
/** Test hook: how requests wait out a restore (`recovering.ts`). */
|
|
77
|
+
recoveringRetry?: RecoveringRetryOptions;
|
|
78
|
+
}
|
|
79
|
+
/** One row of the workspace's file index. */
|
|
80
|
+
interface StoredFile {
|
|
81
|
+
id: string;
|
|
82
|
+
path: string;
|
|
83
|
+
r2Key: string;
|
|
84
|
+
size: number;
|
|
85
|
+
contentType: string | null;
|
|
86
|
+
/** The uploader's claim subject. */
|
|
87
|
+
uploadedBy: string;
|
|
88
|
+
createdAt: number;
|
|
89
|
+
updatedAt: number;
|
|
90
|
+
}
|
|
91
|
+
declare class DataClientImpl {
|
|
92
|
+
private readonly config;
|
|
93
|
+
private readonly fetchImpl;
|
|
94
|
+
private readonly createWebSocket;
|
|
95
|
+
private readonly outbox;
|
|
96
|
+
private readonly missingUserScope;
|
|
97
|
+
private readonly now;
|
|
98
|
+
private readonly cache;
|
|
99
|
+
private readonly subIdToKey;
|
|
100
|
+
private nextSubId;
|
|
101
|
+
/** One-shot page subscriptions, keyed by their ephemeral subscription id. */
|
|
102
|
+
private readonly pages;
|
|
103
|
+
/** Coalesces concurrent `loadMore()` calls for the same query. */
|
|
104
|
+
private readonly pagesInFlight;
|
|
105
|
+
private nextPageId;
|
|
106
|
+
private socket;
|
|
107
|
+
private retryTimer;
|
|
108
|
+
private retryAttempt;
|
|
109
|
+
private authFailures;
|
|
110
|
+
private flushing;
|
|
111
|
+
private readonly inFlight;
|
|
112
|
+
/** Unacked optimistic ops, replayed over server data until they are acked. */
|
|
113
|
+
private readonly pendingOps;
|
|
114
|
+
private readonly presencePeers;
|
|
115
|
+
private readonly topicListeners;
|
|
116
|
+
/** Last sequence seen per joined topic; a rejoin asks for what came after. */
|
|
117
|
+
private readonly topicSeq;
|
|
118
|
+
/** Sends made while the socket was down, sent after reconnecting. */
|
|
119
|
+
private readonly topicQueue;
|
|
120
|
+
/** This client's id across connections: replay skips its own messages. */
|
|
121
|
+
private readonly topicOrigin;
|
|
122
|
+
private readonly presenceListeners;
|
|
123
|
+
private readonly localPresence;
|
|
124
|
+
private onlineHandler;
|
|
125
|
+
private closed;
|
|
126
|
+
constructor(config: InitConfig, deps?: ClientDeps);
|
|
127
|
+
/**
|
|
128
|
+
* Applies ops optimistically, queues them, and sends them. Resolves to
|
|
129
|
+
* "applied" once the engine acknowledged them, or "queued" when the send
|
|
130
|
+
* failed transiently and the outbox will retry. Permanent refusals reject.
|
|
131
|
+
*/
|
|
132
|
+
transact(input: TransactInput): Promise<"applied" | "queued">;
|
|
133
|
+
/**
|
|
134
|
+
* The write path every write takes: optimistic apply, outbox, send. Returns
|
|
135
|
+
* the engine's result when it answered, so a bulk write can report the rows
|
|
136
|
+
* it matched.
|
|
137
|
+
*/
|
|
138
|
+
private submit;
|
|
139
|
+
/**
|
|
140
|
+
* A bulk write, on the same path as every write: applied to the cached rows
|
|
141
|
+
* it certainly matches, kept in the outbox, sent. The engine resolves the
|
|
142
|
+
* rows when the write reaches it and writes them all in one transaction.
|
|
143
|
+
* Online, `count` is the engine's; queued offline, it is the cached rows
|
|
144
|
+
* changed so far, and `queued` is true.
|
|
145
|
+
*/
|
|
146
|
+
bulk(op: TxOp): Promise<{
|
|
147
|
+
count: number;
|
|
148
|
+
queued?: true;
|
|
149
|
+
}>;
|
|
150
|
+
/**
|
|
151
|
+
* The workspace export, one parsed NDJSON record at a time, read from the
|
|
152
|
+
* response stream as it arrives rather than buffered.
|
|
153
|
+
*/
|
|
154
|
+
erasePerson(subject: string): Promise<void>;
|
|
155
|
+
history(model: string, id: string): Promise<HistoryEntry[]>;
|
|
156
|
+
exportRecords(): AsyncGenerator<Record<string, unknown>>;
|
|
157
|
+
/** One-shot read over HTTP: no socket, no cache, no live updates. */
|
|
158
|
+
queryOnce(query: QueryDocument): Promise<{
|
|
159
|
+
data: QueryResult;
|
|
160
|
+
pageInfo: QueryPageInfo;
|
|
161
|
+
}>;
|
|
162
|
+
/** The workspace's file index. */
|
|
163
|
+
listFiles(): Promise<StoredFile[]>;
|
|
164
|
+
subscribeQuery(query: QueryDocument, listener: () => void): () => void;
|
|
165
|
+
getQueryState(query: QueryDocument): QueryState;
|
|
166
|
+
/**
|
|
167
|
+
* Requests the next page for the cached query and appends it.
|
|
168
|
+
*
|
|
169
|
+
* The cursor comes from the engine (`pageInfo[namespace].nextCursor`), never
|
|
170
|
+
* from a client-side offset: keyset pagination stays correct when rows are
|
|
171
|
+
* inserted or deleted between pages. One request covers every top-level
|
|
172
|
+
* namespace that reported a cursor; nested link results ride along with the
|
|
173
|
+
* page instead of being paginated.
|
|
174
|
+
*/
|
|
175
|
+
loadMore(query: QueryDocument): Promise<boolean>;
|
|
176
|
+
publishPresence(target: string, presence: unknown): void;
|
|
177
|
+
publishCursor(target: string, cursor: unknown): void;
|
|
178
|
+
publishDrag(target: string, drag: unknown): void;
|
|
179
|
+
clearDrag(target: string): void;
|
|
180
|
+
clearPresence(target: string): void;
|
|
181
|
+
subscribePresence(target: string, listener: (peers: PresencePeer[]) => void): () => void;
|
|
182
|
+
/**
|
|
183
|
+
* Listens on a broadcast topic. The socket joins the topic with the first
|
|
184
|
+
* listener and leaves it with the last, and rejoins after a reconnect.
|
|
185
|
+
*/
|
|
186
|
+
subscribeTopic(topic: string, listener: TopicListener): () => void;
|
|
187
|
+
/**
|
|
188
|
+
* Sends to everyone else joined to `topic`. While the socket is down the
|
|
189
|
+
* message waits (up to `TOPIC_QUEUE_MESSAGES` per topic, for
|
|
190
|
+
* `TOPIC_QUEUE_MS`) and goes out after reconnecting: `"queued"`. False
|
|
191
|
+
* only when that queue is full.
|
|
192
|
+
*/
|
|
193
|
+
sendTopic(topic: string, message: unknown): boolean | "queued";
|
|
194
|
+
private flushTopicQueue;
|
|
195
|
+
connect(): Promise<void>;
|
|
196
|
+
flushOutbox(): Promise<void>;
|
|
197
|
+
clearOutbox(): Promise<void>;
|
|
198
|
+
close(): void;
|
|
199
|
+
private configProblem;
|
|
200
|
+
private entry;
|
|
201
|
+
private entryBySubId;
|
|
202
|
+
private sendSubscribe;
|
|
203
|
+
/**
|
|
204
|
+
* The query the live subscription actually runs: the caller's query, with
|
|
205
|
+
* each paged namespace's limit widened to the rows already loaded. The cache
|
|
206
|
+
* key stays the caller's query, so `useQuery` callers are unaffected.
|
|
207
|
+
*/
|
|
208
|
+
private liveDocument;
|
|
209
|
+
private resubscribeAll;
|
|
210
|
+
/**
|
|
211
|
+
* The request for the next page: every top-level namespace with a cursor,
|
|
212
|
+
* each carrying its own `after` on top of the options the caller already
|
|
213
|
+
* passed. Returns null when nothing is left to fetch.
|
|
214
|
+
*/
|
|
215
|
+
private nextPageDocument;
|
|
216
|
+
/**
|
|
217
|
+
* Sends one page request and waits for its `query:data`.
|
|
218
|
+
*
|
|
219
|
+
* It is a subscription rather than an HTTP call because the paginated rows
|
|
220
|
+
* must come from the same authenticated socket and the same view rules as the
|
|
221
|
+
* first page. The id is ephemeral and unsubscribed as soon as the page lands,
|
|
222
|
+
* so it never joins the live-query cache.
|
|
223
|
+
*/
|
|
224
|
+
private requestPage;
|
|
225
|
+
/** Settles a pending page request with its reply. */
|
|
226
|
+
private resolvePage;
|
|
227
|
+
/** Settles a pending page request with an error, at most once. */
|
|
228
|
+
private failPage;
|
|
229
|
+
/**
|
|
230
|
+
* Appends a page to the cached result.
|
|
231
|
+
*
|
|
232
|
+
* Rows are deduped by id, so the same page delivered twice (a retried cursor,
|
|
233
|
+
* a server that repeats a boundary row) cannot duplicate entities. `pageInfo`
|
|
234
|
+
* is replaced with the page's own metadata; a namespace the engine no longer
|
|
235
|
+
* caps loses its entry, which is what makes the next `loadMore()` return
|
|
236
|
+
* false.
|
|
237
|
+
*/
|
|
238
|
+
private appendPage;
|
|
239
|
+
private ensureSocket;
|
|
240
|
+
private republishPresence;
|
|
241
|
+
private patchPeer;
|
|
242
|
+
private notifyPresence;
|
|
243
|
+
private handleServerMessage;
|
|
244
|
+
/** Re-applies every unacked optimistic write over freshly received data. */
|
|
245
|
+
private overlayPending;
|
|
246
|
+
private notify;
|
|
247
|
+
private failActiveQueries;
|
|
248
|
+
private snapshot;
|
|
249
|
+
private restore;
|
|
250
|
+
private applyOptimistic;
|
|
251
|
+
private reportRejection;
|
|
252
|
+
private sendTransaction;
|
|
253
|
+
private requireToken;
|
|
254
|
+
private doFlush;
|
|
255
|
+
private scheduleRetry;
|
|
256
|
+
private clearRetryTimer;
|
|
257
|
+
}
|
|
258
|
+
/**
|
|
259
|
+
* Framework-free client. Everything except the hook: usable from a Worker, a
|
|
260
|
+
* Node script, a Svelte store or a test.
|
|
261
|
+
*/
|
|
262
|
+
/** The runtime facade the model client and the tests drive. */
|
|
263
|
+
type HeadlessDataClient = DataClient;
|
|
264
|
+
|
|
265
|
+
/**
|
|
266
|
+
* `db.$across(workspaceIds)`: reads over several workspaces.
|
|
267
|
+
*
|
|
268
|
+
* Each workspace is its own database with its own claim, so the client asks
|
|
269
|
+
* each one with that workspace's token and merges the answers. There is no
|
|
270
|
+
* server-side fan-out: the Worker would need a claim for every workspace.
|
|
271
|
+
* Writes stay per workspace (one writer each, one serializable log each).
|
|
272
|
+
*/
|
|
273
|
+
|
|
274
|
+
/** Live state over several workspaces. `data` holds what the answering workspaces returned. */
|
|
275
|
+
interface AcrossLiveState<T> extends LiveState<T> {
|
|
276
|
+
/** The workspaces whose query failed, with their error. */
|
|
277
|
+
errors: Record<string, QueryError>;
|
|
278
|
+
}
|
|
279
|
+
/** A failed workspace in a one-off read: the others' result is in `partial`. */
|
|
280
|
+
declare class AcrossError<T = unknown> extends Error {
|
|
281
|
+
readonly errors: Record<string, unknown>;
|
|
282
|
+
readonly partial: T;
|
|
283
|
+
constructor(errors: Record<string, unknown>, partial: T);
|
|
284
|
+
}
|
|
285
|
+
interface AcrossQuery<T> extends PromiseLike<T> {
|
|
286
|
+
/** Identifies the query: the workspaces and each workspace's query. */
|
|
287
|
+
readonly key: string;
|
|
288
|
+
/** Live results. The listener runs now, then on every change in any workspace. */
|
|
289
|
+
subscribe(listener: (state: AcrossLiveState<T>) => void): () => void;
|
|
290
|
+
/** The current live state; referentially stable while nothing changed (`useLive`). */
|
|
291
|
+
snapshot(): AcrossLiveState<T>;
|
|
292
|
+
}
|
|
293
|
+
|
|
294
|
+
/**
|
|
295
|
+
* `createClient()`: one accessor per model, plus `$transaction`, `$files` and
|
|
296
|
+
* `$presence`.
|
|
297
|
+
*
|
|
298
|
+
* Reads return a `Query`: await it for one result over HTTP, or subscribe to
|
|
299
|
+
* it for live results over the workspace socket. Writes return a `Write`:
|
|
300
|
+
* await it to send it alone, or pass several to `$transaction` to send them as
|
|
301
|
+
* one log entry. Both are lazy, so building one costs nothing.
|
|
302
|
+
*/
|
|
303
|
+
|
|
304
|
+
interface LiveState<T> {
|
|
305
|
+
/** Undefined until the first result arrives. */
|
|
306
|
+
data: T | undefined;
|
|
307
|
+
isLoading: boolean;
|
|
308
|
+
error: QueryError | null;
|
|
309
|
+
}
|
|
310
|
+
interface Page<R> {
|
|
311
|
+
rows: R[];
|
|
312
|
+
hasMore: boolean;
|
|
313
|
+
/** Pass back as `after` for the next page; null on the last page. */
|
|
314
|
+
cursor: string | null;
|
|
315
|
+
}
|
|
316
|
+
interface WriteResult {
|
|
317
|
+
id: string;
|
|
318
|
+
/** "queued" when the send failed transiently and the outbox will retry. */
|
|
319
|
+
status: "applied" | "queued";
|
|
320
|
+
}
|
|
321
|
+
interface BulkResult {
|
|
322
|
+
/**
|
|
323
|
+
* Rows the filter matched, and therefore wrote. While the write is queued
|
|
324
|
+
* offline: the cached rows it changed so far; the engine decides the rest
|
|
325
|
+
* when the write reaches it.
|
|
326
|
+
*/
|
|
327
|
+
count: number;
|
|
328
|
+
/** Set while the write waits in the offline queue. */
|
|
329
|
+
queued?: true;
|
|
330
|
+
}
|
|
331
|
+
interface FindArgs<M extends Models, F extends Fields> {
|
|
332
|
+
where?: Where<F, M>;
|
|
333
|
+
orderBy?: OrderBy<F>;
|
|
334
|
+
take?: number;
|
|
335
|
+
include?: Include<M, F>;
|
|
336
|
+
/**
|
|
337
|
+
* Return only these fields. The engine reads and sends only them, plus the
|
|
338
|
+
* id and sequence it needs for live updates; the result type narrows to
|
|
339
|
+
* match. Relations named here are included. Not combined with `include`.
|
|
340
|
+
*/
|
|
341
|
+
select?: Select<M, F>;
|
|
342
|
+
}
|
|
343
|
+
interface AggregateArgs<M extends Models, F extends Fields> extends AggregateMeasures<F> {
|
|
344
|
+
where?: Where<F, M>;
|
|
345
|
+
}
|
|
346
|
+
interface GroupByArgs<M extends Models, F extends Fields> extends AggregateMeasures<F> {
|
|
347
|
+
/** Fields to group by: one result row per distinct combination. */
|
|
348
|
+
by: GroupKeys<F>[];
|
|
349
|
+
where?: Where<F, M>;
|
|
350
|
+
/** Orders groups by their key fields. Default: every key ascending. */
|
|
351
|
+
orderBy?: Partial<Record<GroupKeys<F>, "asc" | "desc">>;
|
|
352
|
+
/** At most this many groups (1 to 1000). */
|
|
353
|
+
take?: number;
|
|
354
|
+
}
|
|
355
|
+
interface PageArgs<M extends Models, F extends Fields> extends FindArgs<M, F> {
|
|
356
|
+
/** A previous page's `cursor`. */
|
|
357
|
+
after?: string | null;
|
|
358
|
+
}
|
|
359
|
+
type Result<M extends Models, F extends Fields, A> = (A extends {
|
|
360
|
+
select: infer S;
|
|
361
|
+
} ? Selected<M, F, S> : Row<F>) & (A extends {
|
|
362
|
+
include: infer I;
|
|
363
|
+
} ? WithInclude<M, F, I> : unknown);
|
|
364
|
+
interface ModelClient<M extends Models, F extends Fields> {
|
|
365
|
+
findMany<A extends FindArgs<M, F> = FindArgs<M, F>>(args?: A): Query<Result<M, F, A>[]>;
|
|
366
|
+
findFirst<A extends FindArgs<M, F> = FindArgs<M, F>>(args?: A): Query<Result<M, F, A> | null>;
|
|
367
|
+
findUnique<A extends {
|
|
368
|
+
where: {
|
|
369
|
+
id: string;
|
|
370
|
+
};
|
|
371
|
+
include?: Include<M, F>;
|
|
372
|
+
select?: Select<M, F>;
|
|
373
|
+
}>(args: A): Query<Result<M, F, A> | null>;
|
|
374
|
+
/** One page in a stable order. Defaults to `orderBy: { id: "asc" }` (ids are time-ordered). */
|
|
375
|
+
findPage<A extends PageArgs<M, F> = PageArgs<M, F>>(args?: A): PageQuery<Result<M, F, A>>;
|
|
376
|
+
count(args?: {
|
|
377
|
+
where?: Where<F, M>;
|
|
378
|
+
}): Query<number>;
|
|
379
|
+
/**
|
|
380
|
+
* Count, sum, average, minimum and maximum over the rows matching `where`,
|
|
381
|
+
* as the caller's read rules see them. Await it or subscribe to it.
|
|
382
|
+
*
|
|
383
|
+
* @experimental The result shape may change in a minor release.
|
|
384
|
+
*/
|
|
385
|
+
aggregate<A extends AggregateArgs<M, F>>(args: A): Query<AggregateOutput<F, A>>;
|
|
386
|
+
/**
|
|
387
|
+
* The same measures, one row per distinct value of the `by` fields.
|
|
388
|
+
*
|
|
389
|
+
* @experimental The result shape may change in a minor release.
|
|
390
|
+
*/
|
|
391
|
+
groupBy<A extends GroupByArgs<M, F>>(args: A): Query<GroupRow<F, A>[]>;
|
|
392
|
+
create(args: {
|
|
393
|
+
data: CreateData<F, M>;
|
|
394
|
+
}): Write;
|
|
395
|
+
/**
|
|
396
|
+
* Writes every row matching `where`, in one transaction however many
|
|
397
|
+
* match: it commits whole or not at all. Like single-row writes it is
|
|
398
|
+
* queued offline and applied to the cache at once, to the cached rows it
|
|
399
|
+
* certainly matches; the engine resolves which rows match when the write
|
|
400
|
+
* reaches it, so a write queued offline applies to the rows matching then.
|
|
401
|
+
*/
|
|
402
|
+
updateMany(args: {
|
|
403
|
+
where: Where<F, M>;
|
|
404
|
+
data: UpdateData<F, M>;
|
|
405
|
+
}): Promise<BulkResult>;
|
|
406
|
+
/** Deletes every row matching `where`, in one transaction like `updateMany`. */
|
|
407
|
+
deleteMany(args: {
|
|
408
|
+
where: Where<F, M>;
|
|
409
|
+
}): Promise<BulkResult>;
|
|
410
|
+
update(args: {
|
|
411
|
+
where: {
|
|
412
|
+
id: string;
|
|
413
|
+
};
|
|
414
|
+
data: UpdateData<F, M>;
|
|
415
|
+
}): Write;
|
|
416
|
+
upsert(args: {
|
|
417
|
+
where: {
|
|
418
|
+
id: string;
|
|
419
|
+
};
|
|
420
|
+
create: CreateData<F, M>;
|
|
421
|
+
update: UpdateData<F, M>;
|
|
422
|
+
}): Write;
|
|
423
|
+
delete(args: {
|
|
424
|
+
where: {
|
|
425
|
+
id: string;
|
|
426
|
+
};
|
|
427
|
+
}): Write;
|
|
428
|
+
}
|
|
429
|
+
interface FilesClient {
|
|
430
|
+
upload(file: Blob, options: {
|
|
431
|
+
path: string;
|
|
432
|
+
}): Promise<StorageObject>;
|
|
433
|
+
download(path: string): Promise<Blob>;
|
|
434
|
+
delete(path: string): Promise<void>;
|
|
435
|
+
list(options?: {
|
|
436
|
+
prefix?: string;
|
|
437
|
+
}): Promise<StoredFile[]>;
|
|
438
|
+
}
|
|
439
|
+
interface PresenceRoom {
|
|
440
|
+
set(presence: unknown): void;
|
|
441
|
+
cursor(cursor: unknown): void;
|
|
442
|
+
drag(drag: unknown): void;
|
|
443
|
+
clearDrag(): void;
|
|
444
|
+
subscribe(listener: (peers: PresencePeer[]) => void): () => void;
|
|
445
|
+
leave(): void;
|
|
446
|
+
}
|
|
447
|
+
/**
|
|
448
|
+
* A broadcast topic: fire-and-forget messages between clients of a workspace.
|
|
449
|
+
*
|
|
450
|
+
* @experimental May change in a minor release.
|
|
451
|
+
*/
|
|
452
|
+
interface BroadcastTopic<T = unknown> {
|
|
453
|
+
/**
|
|
454
|
+
* Sends to every other client listening on the topic: `true`. While the
|
|
455
|
+
* socket is down the message waits and goes out after reconnecting:
|
|
456
|
+
* `"queued"` (up to 100 per topic, for 60 seconds). `false` when that
|
|
457
|
+
* queue is full.
|
|
458
|
+
*/
|
|
459
|
+
send(message: T): boolean | "queued";
|
|
460
|
+
/**
|
|
461
|
+
* Listens until the returned function is called. Your own messages are not
|
|
462
|
+
* delivered back to you. `onError` hears refusals, such as an `authorize`
|
|
463
|
+
* hook saying no.
|
|
464
|
+
*/
|
|
465
|
+
subscribe(listener: (message: T, from: TopicSender) => void, options?: {
|
|
466
|
+
onError?: (error: QueryError) => void;
|
|
467
|
+
}): () => void;
|
|
468
|
+
}
|
|
469
|
+
/** One line of `$export()`. */
|
|
470
|
+
type ExportRecord<M extends Models = Models> = {
|
|
471
|
+
type: "header";
|
|
472
|
+
format: "tapedb-export";
|
|
473
|
+
version: 1;
|
|
474
|
+
workspaceId: string;
|
|
475
|
+
/** Workspace sequence when the export started. */
|
|
476
|
+
seq: number;
|
|
477
|
+
exportedAt: number;
|
|
478
|
+
schemaVersion: string | null;
|
|
479
|
+
/** Models exported, in order. */
|
|
480
|
+
models: string[];
|
|
481
|
+
/** Models the caller may not read, and why. */
|
|
482
|
+
skipped: Array<{
|
|
483
|
+
model: string;
|
|
484
|
+
reason: string;
|
|
485
|
+
}>;
|
|
486
|
+
} | {
|
|
487
|
+
[K in keyof M & string]: {
|
|
488
|
+
type: "row";
|
|
489
|
+
model: K;
|
|
490
|
+
data: Row<FieldsOf<M[K]>>;
|
|
491
|
+
};
|
|
492
|
+
}[keyof M & string] | {
|
|
493
|
+
type: "file";
|
|
494
|
+
file: StoredFile & {
|
|
495
|
+
id: string;
|
|
496
|
+
r2Key: string;
|
|
497
|
+
createdAt: number;
|
|
498
|
+
updatedAt: number;
|
|
499
|
+
};
|
|
500
|
+
} | {
|
|
501
|
+
type: "end";
|
|
502
|
+
startSeq: number;
|
|
503
|
+
/** Workspace sequence when the export finished. */
|
|
504
|
+
seq: number;
|
|
505
|
+
rows: number;
|
|
506
|
+
counts: Record<string, number>;
|
|
507
|
+
/** True when no write landed during the export: it is the workspace exactly at `seq`. */
|
|
508
|
+
consistent: boolean;
|
|
509
|
+
} | {
|
|
510
|
+
type: "error";
|
|
511
|
+
code: string;
|
|
512
|
+
message: string;
|
|
513
|
+
};
|
|
514
|
+
interface ClientExtras {
|
|
515
|
+
/** Sends several writes as one log entry: one sequence, all or nothing. */
|
|
516
|
+
$transaction(writes: Write[]): Promise<WriteResult[]>;
|
|
517
|
+
$files: FilesClient;
|
|
518
|
+
$presence(room: string): PresenceRoom;
|
|
519
|
+
/**
|
|
520
|
+
* A broadcast topic on the workspace socket. Topics are 1-128 of A-Z a-z 0-9 : _ . -
|
|
521
|
+
*
|
|
522
|
+
* @experimental May change in a minor release.
|
|
523
|
+
*/
|
|
524
|
+
$broadcast<T = unknown>(topic: string): BroadcastTopic<T>;
|
|
525
|
+
/**
|
|
526
|
+
* Every row the caller may read, model by model, then the file index, as
|
|
527
|
+
* the engine streams it. Read rules apply. The last record is `end` (or
|
|
528
|
+
* `error` if the export stopped).
|
|
529
|
+
*/
|
|
530
|
+
$export(): AsyncIterable<ExportRecord<Models>>;
|
|
531
|
+
/** Deletes a subject key so its personal fields become unreadable. Owners only. */
|
|
532
|
+
$erasePerson(subject: string): Promise<void>;
|
|
533
|
+
/**
|
|
534
|
+
* Who changed one row and when, oldest first, within the retention.
|
|
535
|
+
* Admins and owners only; needs `defineTapeDB({ audit: true })`.
|
|
536
|
+
*/
|
|
537
|
+
$history(target: {
|
|
538
|
+
model: keyof Models & string;
|
|
539
|
+
id: string;
|
|
540
|
+
}): Promise<HistoryEntry[]>;
|
|
541
|
+
/** Retries queued writes now (also runs on reconnect and when back online). */
|
|
542
|
+
$flush(): Promise<void>;
|
|
543
|
+
/** Closes the socket. */
|
|
544
|
+
$close(): void;
|
|
545
|
+
}
|
|
546
|
+
/** One model's reads over several workspaces; every row carries its `workspaceId`. */
|
|
547
|
+
interface AcrossModel<M extends Models, F extends Fields> {
|
|
548
|
+
findMany<A extends FindArgs<M, F> = FindArgs<M, F>>(args?: A): AcrossQuery<Array<Result<M, F, A> & {
|
|
549
|
+
workspaceId: string;
|
|
550
|
+
}>>;
|
|
551
|
+
findFirst<A extends FindArgs<M, F> = FindArgs<M, F>>(args?: A): AcrossQuery<(Result<M, F, A> & {
|
|
552
|
+
workspaceId: string;
|
|
553
|
+
}) | null>;
|
|
554
|
+
findPage<A extends PageArgs<M, F> = PageArgs<M, F>>(args?: A): PromiseLike<Page<Result<M, F, A> & {
|
|
555
|
+
workspaceId: string;
|
|
556
|
+
}>>;
|
|
557
|
+
count(args?: {
|
|
558
|
+
where?: Where<F, M>;
|
|
559
|
+
}): AcrossQuery<number>;
|
|
560
|
+
}
|
|
561
|
+
type Across<M extends Models> = {
|
|
562
|
+
[K in keyof M & string]: AcrossModel<M, FieldsOf<M[K]>>;
|
|
563
|
+
};
|
|
564
|
+
interface AcrossOptions {
|
|
565
|
+
/**
|
|
566
|
+
* A claim for one workspace. Required unless the client uses the
|
|
567
|
+
* development claim route (no `getToken`).
|
|
568
|
+
*/
|
|
569
|
+
getToken?: (workspaceId: string) => Promise<string>;
|
|
570
|
+
}
|
|
571
|
+
type Client<M extends Models> = {
|
|
572
|
+
[K in keyof M & string]: ModelClient<M, FieldsOf<M[K]>>;
|
|
573
|
+
} & Omit<ClientExtras, "$export" | "$history"> & {
|
|
574
|
+
$export(): AsyncIterable<ExportRecord<M>>;
|
|
575
|
+
$history(target: {
|
|
576
|
+
model: keyof M & string;
|
|
577
|
+
id: string;
|
|
578
|
+
}): Promise<HistoryEntry[]>;
|
|
579
|
+
/**
|
|
580
|
+
* Reads over several workspaces: one request (or live socket) per
|
|
581
|
+
* workspace with that workspace's claim, merged in `orderBy` order.
|
|
582
|
+
* A workspace that fails rejects a one-off read with `AcrossError`
|
|
583
|
+
* (the others' rows in `partial`) and shows in a live state's `errors`.
|
|
584
|
+
*/
|
|
585
|
+
$across(workspaceIds: string[], options?: AcrossOptions): Across<M>;
|
|
586
|
+
};
|
|
587
|
+
interface ClientConfig<M extends Models> {
|
|
588
|
+
/** Claim subject; required for authenticated browser persistence. Recreate the client on account changes. */
|
|
589
|
+
userId?: string;
|
|
590
|
+
schema: Schema<M>;
|
|
591
|
+
/** The Worker's origin, e.g. https://api.example.com or http://localhost:8787. */
|
|
592
|
+
url: string;
|
|
593
|
+
/** Workspace id (a UUID): which database this client talks to. */
|
|
594
|
+
workspace: string;
|
|
595
|
+
/** Returns a short-lived claim for every request. Omit in `tapedb dev`. */
|
|
596
|
+
getToken?: () => Promise<string>;
|
|
597
|
+
/** A queued write the engine refused for good during a background flush. */
|
|
598
|
+
onWriteRejected?: (rejection: WriteRejection) => void;
|
|
599
|
+
}
|
|
600
|
+
interface Runtime {
|
|
601
|
+
impl: DataClientImpl;
|
|
602
|
+
parts: HeadlessDataClient;
|
|
603
|
+
graph: Record<string, ModelInfo>;
|
|
604
|
+
snapshots: Map<string, {
|
|
605
|
+
state: QueryState;
|
|
606
|
+
view: LiveState<unknown>;
|
|
607
|
+
}>;
|
|
608
|
+
}
|
|
609
|
+
type Project<T> = (data: QueryResult, pageInfo: QueryPageInfo) => T;
|
|
610
|
+
declare class Query<T> implements PromiseLike<T> {
|
|
611
|
+
protected readonly runtime: Runtime;
|
|
612
|
+
readonly document: QueryDocument;
|
|
613
|
+
private readonly project;
|
|
614
|
+
/** Identifies the query: equal keys share one live subscription. */
|
|
615
|
+
readonly key: string;
|
|
616
|
+
constructor(runtime: Runtime, document: QueryDocument, project: Project<T>, kind: string);
|
|
617
|
+
then<R1 = T, R2 = never>(onFulfilled?: ((value: T) => R1 | PromiseLike<R1>) | null, onRejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null): Promise<R1 | R2>;
|
|
618
|
+
catch<R = never>(onRejected?: ((reason: unknown) => R | PromiseLike<R>) | null): Promise<T | R>;
|
|
619
|
+
finally(onFinally?: (() => void) | null): Promise<T>;
|
|
620
|
+
/** Live results. The listener runs now with the current state, then on every change. */
|
|
621
|
+
subscribe(listener: (state: LiveState<T>) => void): () => void;
|
|
622
|
+
/**
|
|
623
|
+
* The current live state. Referentially stable while nothing changed, so it
|
|
624
|
+
* can back `useSyncExternalStore`.
|
|
625
|
+
*/
|
|
626
|
+
snapshot(): LiveState<T>;
|
|
627
|
+
}
|
|
628
|
+
declare class PageQuery<R> extends Query<Page<R>> {
|
|
629
|
+
/** Live only: appends the next page to this subscription. False when there is none. */
|
|
630
|
+
loadMore(): Promise<boolean>;
|
|
631
|
+
}
|
|
632
|
+
declare class Write implements PromiseLike<WriteResult> {
|
|
633
|
+
private readonly runtime;
|
|
634
|
+
readonly ops: TxOp[];
|
|
635
|
+
readonly id: string;
|
|
636
|
+
private sent;
|
|
637
|
+
constructor(runtime: Runtime, ops: TxOp[], id: string);
|
|
638
|
+
then<R1 = WriteResult, R2 = never>(onFulfilled?: ((value: WriteResult) => R1 | PromiseLike<R1>) | null, onRejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null): Promise<R1 | R2>;
|
|
639
|
+
catch<R = never>(onRejected?: ((reason: unknown) => R | PromiseLike<R>) | null): Promise<WriteResult | R>;
|
|
640
|
+
finally(onFinally?: (() => void) | null): Promise<WriteResult>;
|
|
641
|
+
}
|
|
642
|
+
/** Creates a client for one workspace. */
|
|
643
|
+
declare function createClient<M extends Models>(config: ClientConfig<M>, deps?: ClientDeps): Client<M>;
|
|
644
|
+
|
|
645
|
+
export { Query as Q, Write as W, AcrossError as a, PageQuery as i, createClient as l };
|
|
646
|
+
export type { Across as A, BroadcastTopic as B, Client as C, ExportRecord as E, FilesClient as F, HistoryEntry as H, LiveState as L, ModelClient as M, Page as P, Result as R, StoredFile as S, AcrossLiveState as b, AcrossModel as c, AcrossOptions as d, AcrossQuery as e, ClientConfig as f, FindArgs as g, PageArgs as h, PresenceRoom as j, WriteResult as k };
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
export { A as Across, a as AcrossError, b as AcrossLiveState, c as AcrossModel, d as AcrossOptions, e as AcrossQuery, B as BroadcastTopic, C as Client, f as ClientConfig, E as ExportRecord, F as FilesClient, g as FindArgs, H as HistoryEntry, L as LiveState, M as ModelClient, P as Page, h as PageArgs, i as PageQuery, j as PresenceRoom, Q as Query, R as Result, S as StoredFile, W as Write, k as WriteResult, l as createClient } from './client-DgSnn9BE.js';
|
|
2
|
+
export { P as PresencePeer, Q as QueryError, R as RoleClaim, S as StorageObject, T as TopicSender, W as WORKSPACE_ROLE_LEVELS, a as WorkspaceRole, b as WriteRejection, h as hasRole, c as hasRoleLevel } from './schema-CVcGZJfR.js';
|
|
3
|
+
export { A as Access, a as AccessAuth, C as CheckContext, b as CreateData, D as DeleteBehaviour, F as FieldFilter, I as Include, O as OrderBy, R as Row, S as ScalarKind, c as Schema, U as UpdateData, W as Where, d as check, f as filter, m as model, r as role, s as schema, t } from './schema-entry-CpO_IGFv.js';
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Client-generated entity ids.
|
|
7
|
+
*
|
|
8
|
+
* UUIDv7 keeps the timestamp prefix so ids sort roughly with creation time,
|
|
9
|
+
* which matches the engine's client-generated id contract. When
|
|
10
|
+
* `crypto.getRandomValues` is unavailable we fall back to `crypto.randomUUID`
|
|
11
|
+
* (UUIDv4), and finally to a Math.random-based UUID.
|
|
12
|
+
*/
|
|
13
|
+
/**
|
|
14
|
+
* Returns a UUIDv7 (or a random UUID when the platform cannot do better).
|
|
15
|
+
*
|
|
16
|
+
* Ids from one client sort in the order they were made, even within one
|
|
17
|
+
* millisecond: the 12 bits after the version carry a counter (RFC 9562,
|
|
18
|
+
* method 1), seeded randomly in the lower half each millisecond so there is
|
|
19
|
+
* room to count up. When the counter runs out the timestamp moves forward by
|
|
20
|
+
* one, which keeps order at the cost of a millisecond of drift.
|
|
21
|
+
*/
|
|
22
|
+
declare function id(): string;
|
|
23
|
+
|
|
24
|
+
export { id };
|