@gregale/data 0.0.0-stage → 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.
Files changed (57) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +1031 -2
  3. package/dist/bulk.d.ts +61 -0
  4. package/dist/bulk.js +63 -0
  5. package/dist/client-fetch.d.ts +34 -0
  6. package/dist/client-fetch.js +62 -0
  7. package/dist/cursor-token.d.ts +53 -0
  8. package/dist/cursor-token.js +179 -0
  9. package/dist/cursor.d.ts +45 -0
  10. package/dist/cursor.js +78 -0
  11. package/dist/deadline.d.ts +19 -0
  12. package/dist/deadline.js +29 -0
  13. package/dist/errors.d.ts +17 -0
  14. package/dist/errors.js +68 -0
  15. package/dist/exact-numeric.d.ts +15 -0
  16. package/dist/exact-numeric.js +125 -0
  17. package/dist/index.d.ts +49 -0
  18. package/dist/index.js +39 -0
  19. package/dist/indexeddb-mutation-store.d.ts +12 -0
  20. package/dist/indexeddb-mutation-store.js +139 -0
  21. package/dist/json.d.ts +39 -0
  22. package/dist/json.js +39 -0
  23. package/dist/live/client.d.ts +192 -0
  24. package/dist/live/client.js +555 -0
  25. package/dist/live/index.d.ts +31 -0
  26. package/dist/live/index.js +28 -0
  27. package/dist/live/protocol.d.ts +125 -0
  28. package/dist/live/protocol.js +271 -0
  29. package/dist/live/react.d.ts +22 -0
  30. package/dist/live/react.js +59 -0
  31. package/dist/live/seal.d.ts +38 -0
  32. package/dist/live/seal.js +98 -0
  33. package/dist/live/sql.d.ts +11 -0
  34. package/dist/live/sql.js +58 -0
  35. package/dist/mutation-journal.d.ts +78 -0
  36. package/dist/mutation-journal.js +223 -0
  37. package/dist/numeric.d.ts +11 -0
  38. package/dist/numeric.js +40 -0
  39. package/dist/optimistic.d.ts +24 -0
  40. package/dist/optimistic.js +18 -0
  41. package/dist/reconcile.d.ts +28 -0
  42. package/dist/reconcile.js +28 -0
  43. package/dist/replay-key.d.ts +8 -0
  44. package/dist/replay-key.js +27 -0
  45. package/dist/response.d.ts +33 -0
  46. package/dist/response.js +29 -0
  47. package/dist/rpc.d.ts +20 -0
  48. package/dist/rpc.js +31 -0
  49. package/dist/storage-uploads.d.ts +63 -0
  50. package/dist/storage-uploads.js +104 -0
  51. package/dist/storage.d.ts +74 -0
  52. package/dist/storage.js +89 -0
  53. package/dist/validation.d.ts +26 -0
  54. package/dist/validation.js +40 -0
  55. package/dist/versioned-mutation.d.ts +28 -0
  56. package/dist/versioned-mutation.js +13 -0
  57. package/package.json +19 -4
@@ -0,0 +1,192 @@
1
+ import { type LiveColumn, type LiveErrorFrame } from './protocol.js';
2
+ /** The socket a live connection runs over: an app's realtime endpoint. */
3
+ export interface LiveSocket {
4
+ readonly readyState: number;
5
+ addEventListener(type: 'open' | 'message' | 'close' | 'error', listener: (event: unknown) => void): void;
6
+ removeEventListener(type: 'open' | 'message' | 'close' | 'error', listener: (event: unknown) => void): void;
7
+ send(data: string): void;
8
+ close(): void;
9
+ }
10
+ /** The realtime subprotocol that carries live frames. */
11
+ export declare const LIVE_SUBPROTOCOL = "gregale.realtime.v2";
12
+ type LiveSocketConstructor = new (url: string, protocols: string[]) => LiveSocket;
13
+ /**
14
+ * Opens sockets to a realtime endpoint for LiveConnection's connect option.
15
+ * Live frames carry their own credential, so the socket carries none. Pass a
16
+ * WebSocket class where there is no global one.
17
+ */
18
+ export declare function liveSocket(url: string, WebSocketClass?: LiveSocketConstructor): () => LiveSocket;
19
+ export type LiveStatus = 'connecting' | 'live' | 'stale' | 'closed';
20
+ export type LiveQueryState<Row> = Readonly<{
21
+ status: LiveStatus;
22
+ /** Rows in the query's order when it has ORDER BY, otherwise in a stable order. */
23
+ rows: ReadonlyArray<Row>;
24
+ /** Stable row identities, aligned with rows (for list keys). */
25
+ keys: ReadonlyArray<string>;
26
+ columns: ReadonlyArray<LiveColumn>;
27
+ /** The snapshot the rows reflect (pg_snapshot text), once live. */
28
+ snapshot: string | null;
29
+ error: LiveErrorFrame | undefined;
30
+ }>;
31
+ type LiveRowOptions<Row> = {
32
+ /** Rows rendered on the server, shown until the live result arrives. */
33
+ initialRows?: ReadonlyArray<Row>;
34
+ /** Turns a row's PostgreSQL text values into a row; defaults to parseLiveRow. */
35
+ parse?: (values: ReadonlyArray<string | null>, columns: ReadonlyArray<LiveColumn>) => Row;
36
+ };
37
+ /** Sealed mode: a query the app's backend sealed. */
38
+ export type LiveSealedOptions<Row> = LiveRowOptions<Row> & {
39
+ /** A sealed query from the app's backend. */
40
+ sealed: string;
41
+ /** Fetches a fresh seal for the same query: before expiry, and to resume after a reconnect. */
42
+ refresh?: () => Promise<string>;
43
+ };
44
+ /**
45
+ * Who a live Data API read runs as. Row-level security decides every row in
46
+ * each case, as for the Data API itself.
47
+ */
48
+ export type LiveReadCredential =
49
+ /** The signed-in user: called to subscribe, again before it expires, and after a reconnect. */
50
+ {
51
+ token: () => string | Promise<string>;
52
+ anonymous?: never;
53
+ serverKey?: never;
54
+ subject?: never;
55
+ }
56
+ /** A visitor without a session: only relations the Data API makes public, embedded ones included. */
57
+ | {
58
+ anonymous: true;
59
+ token?: never;
60
+ serverKey?: never;
61
+ subject?: never;
62
+ }
63
+ /**
64
+ * A Data API server key, for trusted backends only. realtimed refuses it on
65
+ * browser connections. subject acts for one application user.
66
+ */
67
+ | {
68
+ serverKey: string;
69
+ subject?: string;
70
+ token?: never;
71
+ anonymous?: never;
72
+ };
73
+ /**
74
+ * RLS mode: a Data API read. The realtime endpoint verifies the user's token
75
+ * (or admits an anonymous or server-key read against the Data API's rules),
76
+ * and the database's row-level security decides every row.
77
+ */
78
+ export type LiveReadOptions<Row> = LiveRowOptions<Row> & LiveReadCredential & {
79
+ /** The database the read is from, as bound to the app. */
80
+ database: string;
81
+ /** The PostgREST read ("messages?select=id,body&order=id.desc&limit=50"); see liveRead for a query builder. */
82
+ read: string;
83
+ /** The schema the read is in; defaults to the Data API's first exposed schema. */
84
+ schema?: string;
85
+ };
86
+ export type LiveQueryOptions<Row> = LiveSealedOptions<Row> | LiveReadOptions<Row>;
87
+ /**
88
+ * The row a postgrest-js query resolves to: a typed query from the generated
89
+ * contract gives a typed live row, anything else a plain record.
90
+ */
91
+ export type LiveReadRow<Query> = Query extends PromiseLike<infer Response> ? LiveDataRow<Response extends {
92
+ data: infer Data;
93
+ } ? Data : never> : Record<string, unknown>;
94
+ type LiveDataRow<Data> = [Data] extends [never] ? Record<string, unknown> : Data extends null ? never : Data extends ReadonlyArray<infer Row> ? Row : Data;
95
+ /**
96
+ * The Data API read a postgrest-js query (from createDataClient) would send,
97
+ * for a live query in RLS mode, with a parser that decodes rows as the Data
98
+ * API returns them, so the query's generated row type holds:
99
+ * connection.query({ database, token, ...liveRead(data.from('messages').select('id, body').eq('channel_id', 1)) })
100
+ */
101
+ export declare function liveRead<Query>(query: Query): {
102
+ read: string;
103
+ schema?: string;
104
+ parse: (values: ReadonlyArray<string | null>, columns: ReadonlyArray<LiveColumn>) => LiveReadRow<Query>;
105
+ };
106
+ export type LiveConnectionOptions = {
107
+ /** Opens an authenticated socket to the app's realtime endpoint (called again on every reconnect). */
108
+ connect: () => LiveSocket | Promise<LiveSocket>;
109
+ /** Delay before reconnect attempt n (from 1); default capped exponential backoff with jitter. */
110
+ reconnectDelayMs?: (attempt: number) => number;
111
+ /** Renew this long before a seal expires; default 15 seconds or a fifth of its lifetime. */
112
+ renewEarlyMs?: number;
113
+ /** Clock and timers, for tests. */
114
+ clock?: {
115
+ now(): number;
116
+ setTimeout(fn: () => void, ms: number): unknown;
117
+ clearTimeout(handle: unknown): void;
118
+ };
119
+ };
120
+ export declare class LiveQueryClosedError extends Error {
121
+ readonly frame: LiveErrorFrame | undefined;
122
+ constructor(frame: LiveErrorFrame | undefined);
123
+ }
124
+ /** Parses common PostgreSQL types; everything else stays text. */
125
+ export declare function parseLiveRow(values: ReadonlyArray<string | null>, columns: ReadonlyArray<LiveColumn>): Record<string, unknown>;
126
+ export declare function parseLiveValue(value: string | null, type: string): unknown;
127
+ /** Decodes a live row as the Data API (PostgREST) returns it in JSON. */
128
+ export declare function parseDataAPIRow(values: ReadonlyArray<string | null>, columns: ReadonlyArray<LiveColumn>, lossless?: boolean | 'exact'): Record<string, unknown>;
129
+ /**
130
+ * Decodes one PostgreSQL text value as PostgREST encodes it in JSON: numbers
131
+ * for integer, numeric and float types (non-finite values stay strings, as
132
+ * JSON has none), ISO 8601 timestamps, arrays element by element, and JSON.
133
+ * Embedded resources already arrive as JSON. Composite columns stay text.
134
+ */
135
+ export declare function parseDataAPIValue(value: string | null, type: string, lossless?: boolean | 'exact'): unknown;
136
+ /**
137
+ * One connection to an app's realtime endpoint, carrying any number of live
138
+ * queries. It reconnects with backoff and resumes each query from the
139
+ * version it holds.
140
+ */
141
+ export declare class LiveConnection {
142
+ private readonly options;
143
+ private readonly clock;
144
+ private readonly queries;
145
+ private socket;
146
+ private open;
147
+ private closed;
148
+ private attempt;
149
+ private reconnectTimer;
150
+ private readonly listeners;
151
+ constructor(options: LiveConnectionOptions);
152
+ /** Subscribes to a sealed query, or (RLS mode) a Data API read as the user. */
153
+ query<Row = Record<string, unknown>>(options: LiveQueryOptions<Row>): LiveQuery<Row>;
154
+ /** Closes every query and the socket. */
155
+ close(): void;
156
+ /** @internal */
157
+ send(frame: Record<string, unknown>): void;
158
+ /** @internal */
159
+ forget(id: string): void;
160
+ /** @internal */
161
+ get timers(): {
162
+ now(): number;
163
+ setTimeout(fn: () => void, ms: number): unknown;
164
+ clearTimeout(handle: unknown): void;
165
+ };
166
+ /** @internal */
167
+ get renewEarlyMs(): number | undefined;
168
+ /** @internal */
169
+ get isOpen(): boolean;
170
+ private connect;
171
+ private detach;
172
+ private onOpen;
173
+ private onClose;
174
+ private scheduleReconnect;
175
+ private onMessage;
176
+ }
177
+ /** A live query's state, for useSyncExternalStore and other stores. */
178
+ export interface LiveQuery<Row> {
179
+ readonly id: string;
180
+ getSnapshot(): LiveQueryState<Row>;
181
+ subscribe(listener: () => void): () => void;
182
+ /**
183
+ * Resolves once the result reflects a committed transaction, such as the
184
+ * one that wrote the data (SELECT pg_current_xact_id()), whether or not
185
+ * the write changed these rows.
186
+ */
187
+ awaitTxId(xid: bigint | number | string, options?: {
188
+ signal?: AbortSignal;
189
+ }): Promise<void>;
190
+ close(): void;
191
+ }
192
+ export {};