@gregale/data 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/LICENSE +202 -0
- package/README.md +1022 -2
- package/dist/bulk.d.ts +61 -0
- package/dist/bulk.js +63 -0
- package/dist/client-fetch.d.ts +34 -0
- package/dist/client-fetch.js +62 -0
- package/dist/cursor-token.d.ts +52 -0
- package/dist/cursor-token.js +165 -0
- package/dist/cursor.d.ts +44 -0
- package/dist/cursor.js +75 -0
- package/dist/deadline.d.ts +19 -0
- package/dist/deadline.js +29 -0
- package/dist/errors.d.ts +17 -0
- package/dist/errors.js +68 -0
- package/dist/index.d.ts +47 -0
- package/dist/index.js +35 -0
- package/dist/indexeddb-mutation-store.d.ts +12 -0
- package/dist/indexeddb-mutation-store.js +139 -0
- package/dist/json.d.ts +34 -0
- package/dist/json.js +39 -0
- package/dist/live/client.d.ts +192 -0
- package/dist/live/client.js +508 -0
- package/dist/live/index.d.ts +31 -0
- package/dist/live/index.js +28 -0
- package/dist/live/protocol.d.ts +125 -0
- package/dist/live/protocol.js +271 -0
- package/dist/live/react.d.ts +22 -0
- package/dist/live/react.js +59 -0
- package/dist/live/seal.d.ts +38 -0
- package/dist/live/seal.js +98 -0
- package/dist/live/sql.d.ts +11 -0
- package/dist/live/sql.js +58 -0
- package/dist/mutation-journal.d.ts +78 -0
- package/dist/mutation-journal.js +223 -0
- package/dist/numeric.d.ts +8 -0
- package/dist/numeric.js +33 -0
- package/dist/optimistic.d.ts +24 -0
- package/dist/optimistic.js +18 -0
- package/dist/reconcile.d.ts +28 -0
- package/dist/reconcile.js +28 -0
- package/dist/replay-key.d.ts +8 -0
- package/dist/replay-key.js +27 -0
- package/dist/response.d.ts +33 -0
- package/dist/response.js +29 -0
- package/dist/rpc.d.ts +20 -0
- package/dist/rpc.js +31 -0
- package/dist/storage-uploads.d.ts +55 -0
- package/dist/storage-uploads.js +78 -0
- package/dist/storage.d.ts +74 -0
- package/dist/storage.js +89 -0
- package/dist/validation.d.ts +26 -0
- package/dist/validation.js +40 -0
- package/dist/versioned-mutation.d.ts +28 -0
- package/dist/versioned-mutation.js +13 -0
- package/package.json +19 -4
|
@@ -0,0 +1,508 @@
|
|
|
1
|
+
import { LIVE_TYPES, LiveProtocolError, LiveResult, parseLiveServerFrame } from './protocol.js';
|
|
2
|
+
import { parseLosslessJSON, usesLosslessNumbers } from '../numeric.js';
|
|
3
|
+
/** The realtime subprotocol that carries live frames. */
|
|
4
|
+
export const LIVE_SUBPROTOCOL = 'gregale.realtime.v2';
|
|
5
|
+
/**
|
|
6
|
+
* Opens sockets to a realtime endpoint for LiveConnection's connect option.
|
|
7
|
+
* Live frames carry their own credential, so the socket carries none. Pass a
|
|
8
|
+
* WebSocket class where there is no global one.
|
|
9
|
+
*/
|
|
10
|
+
export function liveSocket(url, WebSocketClass) {
|
|
11
|
+
const Socket = WebSocketClass ?? globalThis.WebSocket;
|
|
12
|
+
if (!Socket)
|
|
13
|
+
throw new Error('liveSocket needs a WebSocket class in this runtime');
|
|
14
|
+
return () => new Socket(url, [LIVE_SUBPROTOCOL]);
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* The Data API read a postgrest-js query (from createDataClient) would send,
|
|
18
|
+
* for a live query in RLS mode, with a parser that decodes rows as the Data
|
|
19
|
+
* API returns them, so the query's generated row type holds:
|
|
20
|
+
* connection.query({ database, token, ...liveRead(data.from('messages').select('id, body').eq('channel_id', 1)) })
|
|
21
|
+
*/
|
|
22
|
+
export function liveRead(query) {
|
|
23
|
+
const q = query;
|
|
24
|
+
if (!(q?.url instanceof URL))
|
|
25
|
+
throw new TypeError('liveRead takes a query built with createDataClient');
|
|
26
|
+
if (q.method !== undefined && q.method !== 'GET')
|
|
27
|
+
throw new TypeError('a live query reads: build it with select()');
|
|
28
|
+
const path = q.url.pathname;
|
|
29
|
+
const at = path.indexOf('/rest/v1/');
|
|
30
|
+
const relation = at >= 0 ? path.slice(at + '/rest/v1/'.length) : path.replace(/^\//, '');
|
|
31
|
+
const headers = q.headers instanceof Headers ? q.headers : new Headers((q.headers ?? {}));
|
|
32
|
+
// postgrest-js keeps .schema() on the builder and sets the header when it runs.
|
|
33
|
+
const schema = typeof q.schema === 'string' ? q.schema : headers.get('Accept-Profile');
|
|
34
|
+
const lossless = usesLosslessNumbers(q);
|
|
35
|
+
const parse = (lossless ? (values, columns) => parseDataAPIRow(values, columns, true) : parseDataAPIRow);
|
|
36
|
+
return { read: relation + q.url.search, ...(schema ? { schema } : {}), parse };
|
|
37
|
+
}
|
|
38
|
+
function isRead(options) {
|
|
39
|
+
return 'read' in options;
|
|
40
|
+
}
|
|
41
|
+
export class LiveQueryClosedError extends Error {
|
|
42
|
+
frame;
|
|
43
|
+
constructor(frame) {
|
|
44
|
+
super(frame ? `live query closed: ${frame.code}: ${frame.message}` : 'live query closed');
|
|
45
|
+
this.frame = frame;
|
|
46
|
+
this.name = 'LiveQueryClosedError';
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
const defaultClock = {
|
|
50
|
+
now: () => Date.now(),
|
|
51
|
+
setTimeout: (fn, ms) => globalThis.setTimeout(fn, ms),
|
|
52
|
+
clearTimeout: (h) => globalThis.clearTimeout(h),
|
|
53
|
+
};
|
|
54
|
+
/** Parses common PostgreSQL types; everything else stays text. */
|
|
55
|
+
export function parseLiveRow(values, columns) {
|
|
56
|
+
const row = {};
|
|
57
|
+
columns.forEach((c, i) => { row[c.name] = parseLiveValue(values[i] ?? null, c.type); });
|
|
58
|
+
return row;
|
|
59
|
+
}
|
|
60
|
+
export function parseLiveValue(value, type) {
|
|
61
|
+
if (value === null)
|
|
62
|
+
return null;
|
|
63
|
+
switch (type) {
|
|
64
|
+
case 'bool': return value === 't' || value === 'true';
|
|
65
|
+
case 'int2':
|
|
66
|
+
case 'int4':
|
|
67
|
+
case 'oid': return Number(value);
|
|
68
|
+
case 'float4':
|
|
69
|
+
case 'float8': return value === 'NaN' ? NaN : value === 'Infinity' ? Infinity : value === '-Infinity' ? -Infinity : Number(value);
|
|
70
|
+
case 'json':
|
|
71
|
+
case 'jsonb': return JSON.parse(value);
|
|
72
|
+
default: return value; // int8 and numeric keep their precision as text
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
/** Decodes a live row as the Data API (PostgREST) returns it in JSON. */
|
|
76
|
+
export function parseDataAPIRow(values, columns, lossless = false) {
|
|
77
|
+
const row = {};
|
|
78
|
+
columns.forEach((c, i) => { row[c.name] = parseDataAPIValue(values[i] ?? null, c.type, lossless); });
|
|
79
|
+
return row;
|
|
80
|
+
}
|
|
81
|
+
const offsetHours = /([+-]\d{2})$/;
|
|
82
|
+
/**
|
|
83
|
+
* Decodes one PostgreSQL text value as PostgREST encodes it in JSON: numbers
|
|
84
|
+
* for integer, numeric and float types (non-finite values stay strings, as
|
|
85
|
+
* JSON has none), ISO 8601 timestamps, arrays element by element, and JSON.
|
|
86
|
+
* Embedded resources already arrive as JSON. Composite columns stay text.
|
|
87
|
+
*/
|
|
88
|
+
export function parseDataAPIValue(value, type, lossless = false) {
|
|
89
|
+
if (value === null)
|
|
90
|
+
return null;
|
|
91
|
+
if (type.startsWith('_'))
|
|
92
|
+
return parsePostgresArray(value, type.slice(1), lossless);
|
|
93
|
+
switch (type) {
|
|
94
|
+
case 'bool': return value === 't' || value === 'true';
|
|
95
|
+
case 'int2':
|
|
96
|
+
case 'int4':
|
|
97
|
+
case 'int8':
|
|
98
|
+
case 'oid':
|
|
99
|
+
case 'numeric':
|
|
100
|
+
case 'float4':
|
|
101
|
+
case 'float8': {
|
|
102
|
+
if (lossless)
|
|
103
|
+
return value;
|
|
104
|
+
const n = Number(value);
|
|
105
|
+
return Number.isFinite(n) ? n : value;
|
|
106
|
+
}
|
|
107
|
+
case 'json':
|
|
108
|
+
case 'jsonb': return lossless ? parseLosslessJSON(value) : JSON.parse(value);
|
|
109
|
+
case 'timestamptz': return /^\d/.test(value) ? value.replace(' ', 'T').replace(offsetHours, '$1:00') : value;
|
|
110
|
+
case 'timestamp': return /^\d/.test(value) ? value.replace(' ', 'T') : value;
|
|
111
|
+
default: return value;
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
/** Parses a PostgreSQL array literal ({a,"b c",NULL} or nested), decoding each element. */
|
|
115
|
+
function parsePostgresArray(text, elementType, lossless = false) {
|
|
116
|
+
let i = text.startsWith('[') ? text.indexOf('=') + 1 : 0; // optional dimension decoration
|
|
117
|
+
const parseLevel = () => {
|
|
118
|
+
if (text[i] !== '{')
|
|
119
|
+
throw new SyntaxError('malformed PostgreSQL array');
|
|
120
|
+
i++;
|
|
121
|
+
const items = [];
|
|
122
|
+
if (text[i] === '}') {
|
|
123
|
+
i++;
|
|
124
|
+
return items;
|
|
125
|
+
}
|
|
126
|
+
for (;;) {
|
|
127
|
+
if (text[i] === '{')
|
|
128
|
+
items.push(parseLevel());
|
|
129
|
+
else if (text[i] === '"') {
|
|
130
|
+
let element = '';
|
|
131
|
+
for (i++; text[i] !== '"'; i++) {
|
|
132
|
+
if (i >= text.length)
|
|
133
|
+
throw new SyntaxError('malformed PostgreSQL array');
|
|
134
|
+
if (text[i] === '\\')
|
|
135
|
+
i++;
|
|
136
|
+
element += text[i];
|
|
137
|
+
}
|
|
138
|
+
i++;
|
|
139
|
+
items.push(parseDataAPIValue(element, elementType, lossless));
|
|
140
|
+
}
|
|
141
|
+
else {
|
|
142
|
+
const start = i;
|
|
143
|
+
while (i < text.length && text[i] !== ',' && text[i] !== '}')
|
|
144
|
+
i++;
|
|
145
|
+
const element = text.slice(start, i).trim();
|
|
146
|
+
items.push(element.toUpperCase() === 'NULL' ? null : parseDataAPIValue(element, elementType, lossless));
|
|
147
|
+
}
|
|
148
|
+
if (text[i] === ',') {
|
|
149
|
+
i++;
|
|
150
|
+
continue;
|
|
151
|
+
}
|
|
152
|
+
if (text[i] === '}') {
|
|
153
|
+
i++;
|
|
154
|
+
return items;
|
|
155
|
+
}
|
|
156
|
+
throw new SyntaxError('malformed PostgreSQL array');
|
|
157
|
+
}
|
|
158
|
+
};
|
|
159
|
+
const result = parseLevel();
|
|
160
|
+
if (i !== text.length)
|
|
161
|
+
throw new SyntaxError('malformed PostgreSQL array');
|
|
162
|
+
return result;
|
|
163
|
+
}
|
|
164
|
+
let nextID = 0;
|
|
165
|
+
/**
|
|
166
|
+
* One connection to an app's realtime endpoint, carrying any number of live
|
|
167
|
+
* queries. It reconnects with backoff and resumes each query from the
|
|
168
|
+
* version it holds.
|
|
169
|
+
*/
|
|
170
|
+
export class LiveConnection {
|
|
171
|
+
options;
|
|
172
|
+
clock;
|
|
173
|
+
queries = new Map();
|
|
174
|
+
socket;
|
|
175
|
+
open = false;
|
|
176
|
+
closed = false;
|
|
177
|
+
attempt = 0;
|
|
178
|
+
reconnectTimer;
|
|
179
|
+
listeners = {
|
|
180
|
+
open: () => this.onOpen(),
|
|
181
|
+
message: (event) => this.onMessage(event),
|
|
182
|
+
close: () => this.onClose(),
|
|
183
|
+
error: () => { },
|
|
184
|
+
};
|
|
185
|
+
constructor(options) {
|
|
186
|
+
this.options = options;
|
|
187
|
+
this.clock = options.clock ?? defaultClock;
|
|
188
|
+
void this.connect();
|
|
189
|
+
}
|
|
190
|
+
/** Subscribes to a sealed query, or (RLS mode) a Data API read as the user. */
|
|
191
|
+
query(options) {
|
|
192
|
+
if (this.closed)
|
|
193
|
+
throw new Error('live connection is closed');
|
|
194
|
+
const handle = new LiveQueryHandle(this, `q${++nextID}`, options);
|
|
195
|
+
this.queries.set(handle.id, handle);
|
|
196
|
+
if (this.open)
|
|
197
|
+
handle.attach();
|
|
198
|
+
return handle;
|
|
199
|
+
}
|
|
200
|
+
/** Closes every query and the socket. */
|
|
201
|
+
close() {
|
|
202
|
+
this.closed = true;
|
|
203
|
+
this.clock.clearTimeout(this.reconnectTimer);
|
|
204
|
+
for (const q of this.queries.values())
|
|
205
|
+
q.finish(undefined);
|
|
206
|
+
this.queries.clear();
|
|
207
|
+
this.detach()?.close();
|
|
208
|
+
}
|
|
209
|
+
/** @internal */
|
|
210
|
+
send(frame) {
|
|
211
|
+
if (this.open && this.socket)
|
|
212
|
+
this.socket.send(JSON.stringify(frame));
|
|
213
|
+
}
|
|
214
|
+
/** @internal */
|
|
215
|
+
forget(id) {
|
|
216
|
+
this.queries.delete(id);
|
|
217
|
+
}
|
|
218
|
+
/** @internal */
|
|
219
|
+
get timers() { return this.clock; }
|
|
220
|
+
/** @internal */
|
|
221
|
+
get renewEarlyMs() { return this.options.renewEarlyMs; }
|
|
222
|
+
/** @internal */
|
|
223
|
+
get isOpen() { return this.open; }
|
|
224
|
+
async connect() {
|
|
225
|
+
if (this.closed)
|
|
226
|
+
return;
|
|
227
|
+
try {
|
|
228
|
+
const socket = await this.options.connect();
|
|
229
|
+
if (this.closed) {
|
|
230
|
+
socket.close();
|
|
231
|
+
return;
|
|
232
|
+
}
|
|
233
|
+
this.socket = socket;
|
|
234
|
+
socket.addEventListener('open', this.listeners.open);
|
|
235
|
+
socket.addEventListener('message', this.listeners.message);
|
|
236
|
+
socket.addEventListener('close', this.listeners.close);
|
|
237
|
+
socket.addEventListener('error', this.listeners.error);
|
|
238
|
+
if (socket.readyState === 1)
|
|
239
|
+
this.onOpen();
|
|
240
|
+
}
|
|
241
|
+
catch {
|
|
242
|
+
this.scheduleReconnect();
|
|
243
|
+
}
|
|
244
|
+
}
|
|
245
|
+
detach() {
|
|
246
|
+
const socket = this.socket;
|
|
247
|
+
if (!socket)
|
|
248
|
+
return undefined;
|
|
249
|
+
socket.removeEventListener('open', this.listeners.open);
|
|
250
|
+
socket.removeEventListener('message', this.listeners.message);
|
|
251
|
+
socket.removeEventListener('close', this.listeners.close);
|
|
252
|
+
socket.removeEventListener('error', this.listeners.error);
|
|
253
|
+
this.socket = undefined;
|
|
254
|
+
this.open = false;
|
|
255
|
+
return socket;
|
|
256
|
+
}
|
|
257
|
+
onOpen() {
|
|
258
|
+
if (this.open)
|
|
259
|
+
return;
|
|
260
|
+
this.open = true;
|
|
261
|
+
this.attempt = 0;
|
|
262
|
+
for (const q of this.queries.values())
|
|
263
|
+
q.attach();
|
|
264
|
+
}
|
|
265
|
+
onClose() {
|
|
266
|
+
this.detach();
|
|
267
|
+
for (const q of this.queries.values())
|
|
268
|
+
q.disconnected();
|
|
269
|
+
this.scheduleReconnect();
|
|
270
|
+
}
|
|
271
|
+
scheduleReconnect() {
|
|
272
|
+
if (this.closed)
|
|
273
|
+
return;
|
|
274
|
+
this.attempt++;
|
|
275
|
+
const delay = this.options.reconnectDelayMs?.(this.attempt)
|
|
276
|
+
?? Math.min(30_000, 250 * 2 ** Math.min(this.attempt - 1, 7)) * (0.5 + Math.random() / 2);
|
|
277
|
+
this.reconnectTimer = this.clock.setTimeout(() => { void this.connect(); }, delay);
|
|
278
|
+
}
|
|
279
|
+
onMessage(event) {
|
|
280
|
+
const data = event?.data;
|
|
281
|
+
if (typeof data !== 'string')
|
|
282
|
+
return;
|
|
283
|
+
let frame;
|
|
284
|
+
try {
|
|
285
|
+
frame = parseLiveServerFrame(data);
|
|
286
|
+
}
|
|
287
|
+
catch {
|
|
288
|
+
return; // not a live frame: other realtime traffic shares the socket
|
|
289
|
+
}
|
|
290
|
+
if (frame.type === LIVE_TYPES.progress) {
|
|
291
|
+
for (const q of this.queries.values())
|
|
292
|
+
q.receive(frame);
|
|
293
|
+
return;
|
|
294
|
+
}
|
|
295
|
+
const id = frame.subscription;
|
|
296
|
+
if (id !== undefined)
|
|
297
|
+
this.queries.get(id)?.receive(frame);
|
|
298
|
+
}
|
|
299
|
+
}
|
|
300
|
+
class LiveQueryHandle {
|
|
301
|
+
id;
|
|
302
|
+
conn;
|
|
303
|
+
options;
|
|
304
|
+
result = new LiveResult();
|
|
305
|
+
sealed;
|
|
306
|
+
state;
|
|
307
|
+
listeners = new Set();
|
|
308
|
+
waiters = [];
|
|
309
|
+
renewTimer;
|
|
310
|
+
attached = false;
|
|
311
|
+
finished = false;
|
|
312
|
+
constructor(conn, id, options) {
|
|
313
|
+
this.conn = conn;
|
|
314
|
+
this.id = id;
|
|
315
|
+
this.options = options;
|
|
316
|
+
this.sealed = isRead(options) ? undefined : options.sealed;
|
|
317
|
+
this.state = Object.freeze({
|
|
318
|
+
status: 'connecting', rows: options.initialRows ?? [], keys: [], columns: [], snapshot: null, error: undefined,
|
|
319
|
+
});
|
|
320
|
+
}
|
|
321
|
+
getSnapshot = () => this.state;
|
|
322
|
+
subscribe = (listener) => {
|
|
323
|
+
this.listeners.add(listener);
|
|
324
|
+
return () => { this.listeners.delete(listener); };
|
|
325
|
+
};
|
|
326
|
+
/** @internal Subscribes on the socket, resuming from the version held. */
|
|
327
|
+
attach() {
|
|
328
|
+
if (this.finished)
|
|
329
|
+
return;
|
|
330
|
+
const resume = this.result.ready ? this.result.version : 0;
|
|
331
|
+
const again = this.attached;
|
|
332
|
+
if (again)
|
|
333
|
+
this.result.resubscribe();
|
|
334
|
+
this.attached = true;
|
|
335
|
+
// A held seal may have expired while the socket was down.
|
|
336
|
+
void this.credential(again).then((credential) => {
|
|
337
|
+
if (this.finished || !this.conn.isOpen || !credential)
|
|
338
|
+
return;
|
|
339
|
+
const query = isRead(this.options)
|
|
340
|
+
? { database: this.options.database, rest: this.options.read, ...(this.options.schema ? { schema: this.options.schema } : {}) }
|
|
341
|
+
: {};
|
|
342
|
+
this.conn.send({ type: LIVE_TYPES.subscribe, subscription: this.id, ...query, ...credential, ...(resume > 0 ? { version: resume } : {}) });
|
|
343
|
+
});
|
|
344
|
+
}
|
|
345
|
+
awaitTxId(xid, options = {}) {
|
|
346
|
+
const target = BigInt(xid);
|
|
347
|
+
if (this.result.sees(target))
|
|
348
|
+
return Promise.resolve();
|
|
349
|
+
if (this.finished)
|
|
350
|
+
return Promise.reject(new LiveQueryClosedError(this.result.error));
|
|
351
|
+
return new Promise((resolve, reject) => {
|
|
352
|
+
const waiter = { xid: target, resolve, reject };
|
|
353
|
+
this.waiters.push(waiter);
|
|
354
|
+
options.signal?.addEventListener('abort', () => {
|
|
355
|
+
this.waiters = this.waiters.filter((w) => w !== waiter);
|
|
356
|
+
reject(options.signal?.reason);
|
|
357
|
+
}, { once: true });
|
|
358
|
+
});
|
|
359
|
+
}
|
|
360
|
+
close() {
|
|
361
|
+
if (this.finished)
|
|
362
|
+
return;
|
|
363
|
+
this.conn.send({ type: LIVE_TYPES.unsubscribe, subscription: this.id });
|
|
364
|
+
this.finish(undefined);
|
|
365
|
+
this.conn.forget(this.id);
|
|
366
|
+
}
|
|
367
|
+
/** @internal */
|
|
368
|
+
receive(frame) {
|
|
369
|
+
if (this.finished)
|
|
370
|
+
return;
|
|
371
|
+
try {
|
|
372
|
+
this.result.apply(frame);
|
|
373
|
+
}
|
|
374
|
+
catch (err) {
|
|
375
|
+
if (!(err instanceof LiveProtocolError))
|
|
376
|
+
throw err;
|
|
377
|
+
// Start over: the server sends a full result to a fresh subscription.
|
|
378
|
+
// The rows shown stay until it arrives.
|
|
379
|
+
this.conn.send({ type: LIVE_TYPES.unsubscribe, subscription: this.id });
|
|
380
|
+
this.result = new LiveResult();
|
|
381
|
+
this.attach();
|
|
382
|
+
return;
|
|
383
|
+
}
|
|
384
|
+
if (frame.type === LIVE_TYPES.error) {
|
|
385
|
+
if (frame.closed) {
|
|
386
|
+
this.finish(frame);
|
|
387
|
+
this.conn.forget(this.id);
|
|
388
|
+
return;
|
|
389
|
+
}
|
|
390
|
+
if (frame.code === 'seal_expired')
|
|
391
|
+
void this.renew();
|
|
392
|
+
}
|
|
393
|
+
if (frame.type === LIVE_TYPES.rows || frame.type === LIVE_TYPES.renewed)
|
|
394
|
+
this.scheduleRenewal();
|
|
395
|
+
this.publish();
|
|
396
|
+
}
|
|
397
|
+
/** @internal */
|
|
398
|
+
disconnected() {
|
|
399
|
+
this.conn.timers.clearTimeout(this.renewTimer);
|
|
400
|
+
if (this.state.status !== 'closed')
|
|
401
|
+
this.setState({ ...this.state, status: 'connecting' });
|
|
402
|
+
}
|
|
403
|
+
/** @internal */
|
|
404
|
+
finish(frame) {
|
|
405
|
+
if (this.finished)
|
|
406
|
+
return;
|
|
407
|
+
this.finished = true;
|
|
408
|
+
this.conn.timers.clearTimeout(this.renewTimer);
|
|
409
|
+
for (const w of this.waiters)
|
|
410
|
+
w.reject(new LiveQueryClosedError(frame));
|
|
411
|
+
this.waiters = [];
|
|
412
|
+
this.setState({ ...this.state, status: 'closed', error: frame });
|
|
413
|
+
}
|
|
414
|
+
/**
|
|
415
|
+
* The frame fields that authorize: a seal (fresh when asked), the user's
|
|
416
|
+
* current token, anonymous access or a server key.
|
|
417
|
+
*/
|
|
418
|
+
async credential(fresh) {
|
|
419
|
+
const o = this.options;
|
|
420
|
+
if (isRead(o)) {
|
|
421
|
+
if (o.anonymous === true)
|
|
422
|
+
return { anonymous: true };
|
|
423
|
+
if (typeof o.serverKey === 'string')
|
|
424
|
+
return { server_key: o.serverKey, ...(o.subject ? { subject: o.subject } : {}) };
|
|
425
|
+
try {
|
|
426
|
+
return { token: await o.token() };
|
|
427
|
+
}
|
|
428
|
+
catch {
|
|
429
|
+
return undefined; /* retried at the next reconnect */
|
|
430
|
+
}
|
|
431
|
+
}
|
|
432
|
+
if (fresh && o.refresh) {
|
|
433
|
+
try {
|
|
434
|
+
this.sealed = await o.refresh();
|
|
435
|
+
}
|
|
436
|
+
catch { /* the held seal may still be valid */ }
|
|
437
|
+
}
|
|
438
|
+
return this.sealed === undefined ? undefined : { sealed: this.sealed };
|
|
439
|
+
}
|
|
440
|
+
renewable() {
|
|
441
|
+
return isRead(this.options) || this.options.refresh !== undefined;
|
|
442
|
+
}
|
|
443
|
+
scheduleRenewal() {
|
|
444
|
+
this.conn.timers.clearTimeout(this.renewTimer);
|
|
445
|
+
if (!this.renewable() || this.result.expires <= 0)
|
|
446
|
+
return;
|
|
447
|
+
const left = this.result.expires * 1000 - this.conn.timers.now();
|
|
448
|
+
const early = this.conn.renewEarlyMs ?? Math.min(15_000, Math.max(1_000, left / 5));
|
|
449
|
+
this.renewTimer = this.conn.timers.setTimeout(() => { void this.renew(); }, Math.max(0, left - early));
|
|
450
|
+
}
|
|
451
|
+
async renew() {
|
|
452
|
+
if (!this.renewable() || this.finished)
|
|
453
|
+
return;
|
|
454
|
+
const credential = await this.credential(true);
|
|
455
|
+
// Without one it stays live until expiry, then stale; the next renewal retries.
|
|
456
|
+
if (!credential || this.finished)
|
|
457
|
+
return;
|
|
458
|
+
this.conn.send({ type: LIVE_TYPES.renew, subscription: this.id, ...credential });
|
|
459
|
+
}
|
|
460
|
+
publish() {
|
|
461
|
+
const r = this.result;
|
|
462
|
+
if (!r.ready) {
|
|
463
|
+
if (r.stale && this.state.status !== 'stale')
|
|
464
|
+
this.setState({ ...this.state, status: 'stale', error: r.error });
|
|
465
|
+
return;
|
|
466
|
+
}
|
|
467
|
+
const parse = this.options.parse ?? parseLiveRow;
|
|
468
|
+
const entries = r.entries();
|
|
469
|
+
const prev = this.state;
|
|
470
|
+
const sameRows = prev.keys.length === entries.length && prev.snapshot !== null
|
|
471
|
+
&& entries.every((e, i) => e.id === prev.keys[i] && this.rowCache.get(e.id)?.values === e.values);
|
|
472
|
+
const rows = sameRows ? prev.rows : entries.map((e) => {
|
|
473
|
+
const cached = this.rowCache.get(e.id);
|
|
474
|
+
if (cached?.values === e.values)
|
|
475
|
+
return cached.row;
|
|
476
|
+
const row = parse(e.values, r.columns);
|
|
477
|
+
this.rowCache.set(e.id, { values: e.values, row });
|
|
478
|
+
return row;
|
|
479
|
+
});
|
|
480
|
+
if (!sameRows)
|
|
481
|
+
for (const id of this.rowCache.keys())
|
|
482
|
+
if (!entries.some((e) => e.id === id))
|
|
483
|
+
this.rowCache.delete(id);
|
|
484
|
+
this.setState({
|
|
485
|
+
status: r.stale ? 'stale' : 'live',
|
|
486
|
+
rows,
|
|
487
|
+
keys: sameRows ? prev.keys : entries.map((e) => e.id),
|
|
488
|
+
columns: r.columns,
|
|
489
|
+
snapshot: r.snapshot.text,
|
|
490
|
+
error: r.stale ? r.error : undefined,
|
|
491
|
+
});
|
|
492
|
+
this.waiters = this.waiters.filter((w) => {
|
|
493
|
+
if (!r.sees(w.xid))
|
|
494
|
+
return true;
|
|
495
|
+
w.resolve();
|
|
496
|
+
return false;
|
|
497
|
+
});
|
|
498
|
+
}
|
|
499
|
+
rowCache = new Map();
|
|
500
|
+
setState(next) {
|
|
501
|
+
const s = this.state;
|
|
502
|
+
if (s.status === next.status && s.rows === next.rows && s.snapshot === next.snapshot && s.error === next.error && s.columns === next.columns)
|
|
503
|
+
return;
|
|
504
|
+
this.state = Object.freeze(next);
|
|
505
|
+
for (const l of [...this.listeners])
|
|
506
|
+
l();
|
|
507
|
+
}
|
|
508
|
+
}
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Live queries (ADR-20261016151947): SQL results that stay current. A backend seals a
|
|
3
|
+
* query, or (RLS mode) the browser sends a Data API read with its user's
|
|
4
|
+
* token; it subscribes over the app's realtime endpoint and holds the result
|
|
5
|
+
* as of a committed snapshot, updated by changes.
|
|
6
|
+
*
|
|
7
|
+
* Backend:
|
|
8
|
+
* const live = await createLiveSealer({ secret: process.env.GREGALE_LIVE_SECRET!, database: process.env.GREGALE_LIVE_DATABASE! })
|
|
9
|
+
* const sealed = await live.seal(sql`SELECT id, body FROM messages WHERE channel_id = ${id} ORDER BY id DESC LIMIT 50`)
|
|
10
|
+
*
|
|
11
|
+
* Browser:
|
|
12
|
+
* const connection = new LiveConnection({ connect: () => openRealtimeSocket() })
|
|
13
|
+
* const feed = connection.query({ sealed, refresh: () => fetchSeal(id) })
|
|
14
|
+
* feed.subscribe(() => render(feed.getSnapshot().rows))
|
|
15
|
+
* await feed.awaitTxId(xidFromWrite)
|
|
16
|
+
*
|
|
17
|
+
* RLS mode, as the signed-in user:
|
|
18
|
+
* const mine = connection.query({ database, token: () => auth.accessToken(),
|
|
19
|
+
* ...liveRead(data.from('messages').select('id, body').eq('channel_id', id).order('id', { ascending: false }).limit(50)) })
|
|
20
|
+
*
|
|
21
|
+
* A visitor without a session (public relations only), or a trusted backend:
|
|
22
|
+
* connection.query({ database, anonymous: true, ...liveRead(visitor.from('products').select('id, name')) })
|
|
23
|
+
* connection.query({ database, serverKey: process.env.SHOP_SERVER_KEY!, ...liveRead(backend.from('orders').select('id')) })
|
|
24
|
+
*/
|
|
25
|
+
export { sql, toPostgresText } from './sql.js';
|
|
26
|
+
export { createLiveSealer, LiveSealError, LIVE_SEAL_DEFAULT_TTL_SECONDS, LIVE_SEAL_MAX_TTL_SECONDS } from './seal.js';
|
|
27
|
+
export type { LiveQueryText, LiveSealer, LiveSealOptions } from './seal.js';
|
|
28
|
+
export { LIVE_SUBPROTOCOL, LiveConnection, LiveQueryClosedError, liveRead, liveSocket, parseDataAPIRow, parseDataAPIValue, parseLiveRow, parseLiveValue } from './client.js';
|
|
29
|
+
export type { LiveConnectionOptions, LiveQuery, LiveQueryOptions, LiveQueryState, LiveReadCredential, LiveReadOptions, LiveReadRow, LiveSealedOptions, LiveSocket, LiveStatus, } from './client.js';
|
|
30
|
+
export { LiveProtocolError, LiveResult, LiveSnapshot, parseLiveServerFrame, LIVE_TYPES } from './protocol.js';
|
|
31
|
+
export type { LiveChange, LiveChangesFrame, LiveColumn, LiveErrorFrame, LiveProgressFrame, LiveRenewedFrame, LiveRow, LiveRowsFrame, LiveServerFrame, LiveValues, } from './protocol.js';
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Live queries (ADR-20261016151947): SQL results that stay current. A backend seals a
|
|
3
|
+
* query, or (RLS mode) the browser sends a Data API read with its user's
|
|
4
|
+
* token; it subscribes over the app's realtime endpoint and holds the result
|
|
5
|
+
* as of a committed snapshot, updated by changes.
|
|
6
|
+
*
|
|
7
|
+
* Backend:
|
|
8
|
+
* const live = await createLiveSealer({ secret: process.env.GREGALE_LIVE_SECRET!, database: process.env.GREGALE_LIVE_DATABASE! })
|
|
9
|
+
* const sealed = await live.seal(sql`SELECT id, body FROM messages WHERE channel_id = ${id} ORDER BY id DESC LIMIT 50`)
|
|
10
|
+
*
|
|
11
|
+
* Browser:
|
|
12
|
+
* const connection = new LiveConnection({ connect: () => openRealtimeSocket() })
|
|
13
|
+
* const feed = connection.query({ sealed, refresh: () => fetchSeal(id) })
|
|
14
|
+
* feed.subscribe(() => render(feed.getSnapshot().rows))
|
|
15
|
+
* await feed.awaitTxId(xidFromWrite)
|
|
16
|
+
*
|
|
17
|
+
* RLS mode, as the signed-in user:
|
|
18
|
+
* const mine = connection.query({ database, token: () => auth.accessToken(),
|
|
19
|
+
* ...liveRead(data.from('messages').select('id, body').eq('channel_id', id).order('id', { ascending: false }).limit(50)) })
|
|
20
|
+
*
|
|
21
|
+
* A visitor without a session (public relations only), or a trusted backend:
|
|
22
|
+
* connection.query({ database, anonymous: true, ...liveRead(visitor.from('products').select('id, name')) })
|
|
23
|
+
* connection.query({ database, serverKey: process.env.SHOP_SERVER_KEY!, ...liveRead(backend.from('orders').select('id')) })
|
|
24
|
+
*/
|
|
25
|
+
export { sql, toPostgresText } from './sql.js';
|
|
26
|
+
export { createLiveSealer, LiveSealError, LIVE_SEAL_DEFAULT_TTL_SECONDS, LIVE_SEAL_MAX_TTL_SECONDS } from './seal.js';
|
|
27
|
+
export { LIVE_SUBPROTOCOL, LiveConnection, LiveQueryClosedError, liveRead, liveSocket, parseDataAPIRow, parseDataAPIValue, parseLiveRow, parseLiveValue } from './client.js';
|
|
28
|
+
export { LiveProtocolError, LiveResult, LiveSnapshot, parseLiveServerFrame, LIVE_TYPES } from './protocol.js';
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The live-query frame contract (ADR-20261016151947), mirroring the Go reference client
|
|
3
|
+
* in pkg/livequery/liveproto. Both run the shared session fixtures.
|
|
4
|
+
*/
|
|
5
|
+
export declare const LIVE_TYPES: {
|
|
6
|
+
readonly subscribe: "live.subscribe";
|
|
7
|
+
readonly renew: "live.renew";
|
|
8
|
+
readonly unsubscribe: "live.unsubscribe";
|
|
9
|
+
readonly rows: "live.rows";
|
|
10
|
+
readonly changes: "live.changes";
|
|
11
|
+
readonly progress: "live.progress";
|
|
12
|
+
readonly renewed: "live.renewed";
|
|
13
|
+
readonly error: "live.error";
|
|
14
|
+
};
|
|
15
|
+
export type LiveColumn = Readonly<{
|
|
16
|
+
name: string;
|
|
17
|
+
type: string;
|
|
18
|
+
}>;
|
|
19
|
+
/** PostgreSQL text values; null is SQL NULL. */
|
|
20
|
+
export type LiveValues = ReadonlyArray<string | null>;
|
|
21
|
+
export type LiveRow = Readonly<{
|
|
22
|
+
id: string;
|
|
23
|
+
values: LiveValues;
|
|
24
|
+
}>;
|
|
25
|
+
export type LiveRowsFrame = {
|
|
26
|
+
type: 'live.rows';
|
|
27
|
+
subscription: string;
|
|
28
|
+
database: string;
|
|
29
|
+
version: number;
|
|
30
|
+
snapshot: string;
|
|
31
|
+
expires: number;
|
|
32
|
+
columns: LiveColumn[];
|
|
33
|
+
ordered?: boolean;
|
|
34
|
+
rows: LiveRow[];
|
|
35
|
+
complete: boolean;
|
|
36
|
+
};
|
|
37
|
+
export type LiveChange = {
|
|
38
|
+
op: 'upsert';
|
|
39
|
+
id: string;
|
|
40
|
+
values: LiveValues;
|
|
41
|
+
} | {
|
|
42
|
+
op: 'remove';
|
|
43
|
+
id: string;
|
|
44
|
+
};
|
|
45
|
+
export type LiveChangesFrame = {
|
|
46
|
+
type: 'live.changes';
|
|
47
|
+
subscription: string;
|
|
48
|
+
base: number;
|
|
49
|
+
version: number;
|
|
50
|
+
snapshot: string;
|
|
51
|
+
xids: string[];
|
|
52
|
+
changes: LiveChange[];
|
|
53
|
+
order?: string[];
|
|
54
|
+
};
|
|
55
|
+
export type LiveProgressFrame = {
|
|
56
|
+
type: 'live.progress';
|
|
57
|
+
database: string;
|
|
58
|
+
snapshot: string;
|
|
59
|
+
};
|
|
60
|
+
export type LiveRenewedFrame = {
|
|
61
|
+
type: 'live.renewed';
|
|
62
|
+
subscription: string;
|
|
63
|
+
expires: number;
|
|
64
|
+
};
|
|
65
|
+
export type LiveErrorFrame = {
|
|
66
|
+
type: 'live.error';
|
|
67
|
+
subscription?: string;
|
|
68
|
+
code: string;
|
|
69
|
+
message: string;
|
|
70
|
+
closed: boolean;
|
|
71
|
+
limit?: number;
|
|
72
|
+
observed?: number;
|
|
73
|
+
docs?: string;
|
|
74
|
+
};
|
|
75
|
+
export type LiveServerFrame = LiveRowsFrame | LiveChangesFrame | LiveProgressFrame | LiveRenewedFrame | LiveErrorFrame;
|
|
76
|
+
export declare class LiveProtocolError extends Error {
|
|
77
|
+
constructor(message: string);
|
|
78
|
+
}
|
|
79
|
+
/** Decodes and shape-checks a server frame. */
|
|
80
|
+
export declare function parseLiveServerFrame(data: string): LiveServerFrame;
|
|
81
|
+
/** A parsed pg_snapshot ("xmin:xmax:xip,..."): the transactions a result reflects. */
|
|
82
|
+
export declare class LiveSnapshot {
|
|
83
|
+
readonly xmin: bigint;
|
|
84
|
+
readonly xmax: bigint;
|
|
85
|
+
readonly xip: ReadonlySet<bigint>;
|
|
86
|
+
readonly text: string;
|
|
87
|
+
private constructor();
|
|
88
|
+
static parse(text: string): LiveSnapshot;
|
|
89
|
+
static readonly zero: LiveSnapshot;
|
|
90
|
+
/** Whether a committed transaction is visible, as pg_visible_in_snapshot decides. */
|
|
91
|
+
visible(xid: bigint): boolean;
|
|
92
|
+
/** Whether every transaction visible in o is visible here: this is not older than o. */
|
|
93
|
+
covers(o: LiveSnapshot): boolean;
|
|
94
|
+
}
|
|
95
|
+
/**
|
|
96
|
+
* One subscription's result as the client holds it. apply() refuses frames
|
|
97
|
+
* that break the contract; the caller then resubscribes.
|
|
98
|
+
*/
|
|
99
|
+
export declare class LiveResult {
|
|
100
|
+
database: string;
|
|
101
|
+
columns: LiveColumn[];
|
|
102
|
+
ordered: boolean;
|
|
103
|
+
version: number;
|
|
104
|
+
snapshot: LiveSnapshot;
|
|
105
|
+
expires: number;
|
|
106
|
+
stale: boolean;
|
|
107
|
+
closed: boolean;
|
|
108
|
+
error: LiveErrorFrame | undefined;
|
|
109
|
+
private isReady;
|
|
110
|
+
private rows;
|
|
111
|
+
private order;
|
|
112
|
+
private pending;
|
|
113
|
+
private resyncing;
|
|
114
|
+
get ready(): boolean;
|
|
115
|
+
/** After a (re)subscribe, the next live.rows may start a new version sequence. */
|
|
116
|
+
resubscribe(): void;
|
|
117
|
+
apply(frame: LiveServerFrame): void;
|
|
118
|
+
private applyRows;
|
|
119
|
+
private applyChanges;
|
|
120
|
+
private advance;
|
|
121
|
+
/** The rows: in the query's order when it has one, by row ID otherwise. */
|
|
122
|
+
entries(): LiveRow[];
|
|
123
|
+
/** Whether the result reflects a committed transaction: the check behind awaitTxId. */
|
|
124
|
+
sees(xid: bigint): boolean;
|
|
125
|
+
}
|