@rebasepro/client 0.23.0 → 0.24.1-canary.g56af4a4

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/dist/offline.d.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import { RebaseApiError } from "./transport.js";
1
2
  import { SDKCollectionClient } from "@rebasepro/types";
2
3
  import { CollectionClient } from "./collection.js";
3
4
  import { OfflineStore, PendingMutation } from "./offline-store.js";
@@ -81,7 +82,76 @@ export interface OfflineConfig {
81
82
  * Network failures are not errors: those mutations stay queued.
82
83
  */
83
84
  onSyncError?: (error: Error, mutation: PendingMutation) => void;
85
+ /**
86
+ * Detect conflicts when a queued edit replays: an `update` made offline
87
+ * is sent with `If-Match`, the version of the row it was made against,
88
+ * and if someone changed the row on the server since, this decides what
89
+ * happens to the edit:
90
+ *
91
+ * - `"overwrite"`: send it again without the precondition. Last writer
92
+ * wins, as without this option.
93
+ * - `"discard"`: drop it. The row goes back to what it was before the
94
+ * edit, as for a rejection, but it is not reported to `onSyncError`
95
+ * (writes queued on top of it are, as `DEPENDENCY_REJECTED`), and the
96
+ * row is read again from the server.
97
+ *
98
+ * The edit's version is the one the row's last read reported: a
99
+ * `findById`, a `listenById` frame, or the answer to an earlier `update`.
100
+ * A row last seen in a `find()` or `listen()` list has no version, and an
101
+ * edit made on top of another queued write to the same row has none
102
+ * either; those replay without a precondition. A caller's own `ifMatch` is
103
+ * kept on a queued edit too.
104
+ *
105
+ * The queue waits while this runs, so a prompt can ask the user. Without
106
+ * it — the default — replay sends no precondition and the last writer
107
+ * wins, per field.
108
+ */
109
+ onConflict?: (error: RebaseApiError, mutation: PendingMutation) => ConflictResolution | Promise<ConflictResolution>;
110
+ /**
111
+ * Remember, on this device, the last user who signed in, and open their
112
+ * local database when a reload cannot reach the server to restore the
113
+ * session. Off by default.
114
+ *
115
+ * This matters in cookie mode, where nothing about the session is stored
116
+ * on the device: without it, an offline reload has no user, so it shows
117
+ * the signed-out local database and queues the user's writes as the
118
+ * signed-out user's. With it, the reload shows the last user's rows, and
119
+ * writes made meanwhile go into their queue. That queue is not replayed
120
+ * until the session is confirmed — by a refresh once the connection is
121
+ * back, or a sign-in. If the server then refuses the session, or someone
122
+ * else signs in, the device switches users and the queue waits, kept, for
123
+ * its author.
124
+ *
125
+ * The trade-off is the reason it is opt-in: on a shared device, the
126
+ * previous user's cached rows can be read offline without a session.
127
+ * Turn it on for installs that belong to one person. The id is forgotten
128
+ * at sign-out, and when the server refuses the session; it is never used
129
+ * when the server answered that there is no session.
130
+ *
131
+ * {@link OfflineStatus.unverifiedUser} is `true` while the device shows a
132
+ * user whose session it has not confirmed.
133
+ */
134
+ keepLastUser?: boolean;
135
+ /**
136
+ * How many queued creates replay as one request. Defaults to `1`: every
137
+ * queued write is its own request, in order. Raise it (up to 1 000) and a
138
+ * run of consecutive offline creates in one collection drains as one
139
+ * `createMany` — 500 rows typed offline go back in a handful of requests
140
+ * instead of 500 round trips.
141
+ *
142
+ * Only creates whose ids the SDK minted as strings are folded, and never
143
+ * one that references another row of the same run: those are the writes a
144
+ * lost answer cannot duplicate (the server refuses the id the second time,
145
+ * and the create is recognised as its own) and whose values need nothing
146
+ * from the server first. Anything else — and any run the server refuses or
147
+ * defers for any reason but a lost connection — replays one write at a
148
+ * time exactly as with the default, so each write still stands or falls
149
+ * on its own.
150
+ */
151
+ replayBatchSize?: number;
84
152
  }
153
+ /** What {@link OfflineConfig.onConflict} does with an edit the row has moved past. */
154
+ export type ConflictResolution = "overwrite" | "discard";
85
155
  /** A snapshot of the engine's state, for a status indicator. */
86
156
  export interface OfflineStatus {
87
157
  /** False once a request has failed to reach the server, until one does. */
@@ -94,8 +164,41 @@ export interface OfflineStatus {
94
164
  lastSyncedAt?: number;
95
165
  /** The last replay rejection, if any. */
96
166
  lastError?: string;
167
+ /**
168
+ * Whether the browser agreed to keep the offline database through storage
169
+ * pressure (`navigator.storage.persist()`), asked when the first write is
170
+ * queued. `false` means it may be evicted — on Safari, after seven days
171
+ * without a visit — and unsent writes with it; a UI can warn. Unset until
172
+ * asked, and where there is nothing to ask.
173
+ */
174
+ persisted?: boolean;
175
+ /**
176
+ * `true` while the local data shown is the last signed-in user's, opened
177
+ * without a confirmed session ({@link OfflineConfig.keepLastUser}): their
178
+ * writes queue, and none replays until the session is confirmed. Unset
179
+ * otherwise.
180
+ */
181
+ unverifiedUser?: boolean;
182
+ }
183
+ export type { LiveResult, ObserveByIdOptions, ObserveOptions, RowSnapshotMeta } from "./collection.js";
184
+ /** Which queue {@link OfflineApi.pending} and {@link OfflineApi.clear} act on. */
185
+ export interface OfflineQueueOptions {
186
+ /**
187
+ * The writes queued while nobody was signed in, instead of the current
188
+ * user's.
189
+ *
190
+ * While someone is signed in these are held back: they were not made by
191
+ * that user, so they are never replayed under their credentials, and never
192
+ * moved into their queue. `pending({ orphaned: true })` lists them so the
193
+ * app can decide — re-issue them as the signed-in user, or discard them
194
+ * with `clear({ orphaned: true })`. Left alone, they replay the next time
195
+ * nobody is signed in.
196
+ *
197
+ * With nobody signed in they are the current queue, and are not orphaned:
198
+ * `pending({ orphaned: true })` lists nothing.
199
+ */
200
+ orphaned?: boolean;
97
201
  }
98
- export type { LiveResult, ObserveOptions, RowSnapshotMeta } from "./collection.js";
99
202
  /** What `client.offline` exposes to the app. */
100
203
  export interface OfflineApi {
101
204
  /** Replay the queue now. Resolves with what was flushed and what remains. */
@@ -103,8 +206,12 @@ export interface OfflineApi {
103
206
  flushed: number;
104
207
  remaining: number;
105
208
  }>;
106
- /** The queued mutations for the current user, oldest first. */
107
- pending(): Promise<PendingMutation[]>;
209
+ /**
210
+ * The queued mutations for the current user, oldest first — or, with
211
+ * `{ orphaned: true }`, the ones queued while nobody was signed in (see
212
+ * {@link OfflineQueueOptions.orphaned}).
213
+ */
214
+ pending(options?: OfflineQueueOptions): Promise<PendingMutation[]>;
108
215
  /** The current engine state — connectivity, queue depth, last sync. */
109
216
  status(): OfflineStatus;
110
217
  /** Subscribe to {@link OfflineStatus} changes (for a sync indicator). */
@@ -114,20 +221,16 @@ export interface OfflineApi {
114
221
  * Destructive: queued writes are lost, not replayed. For "discard my
115
222
  * offline changes" flows, not for sign-out (scoping already isolates
116
223
  * users).
224
+ *
225
+ * With `{ orphaned: true }`, drop the writes queued while nobody was
226
+ * signed in, and the local rows they were applied to, instead — the
227
+ * current user's are left alone.
117
228
  */
118
- clear(): Promise<void>;
229
+ clear(options?: OfflineQueueOptions): Promise<void>;
119
230
  /** Subscribe to queue-size changes (for a "pending changes" badge). */
120
231
  onQueueChange(listener: (count: number) => void): () => void;
121
232
  }
122
- /**
123
- * True when a read failed because there was neither network nor local data.
124
- *
125
- * The code is `OFFLINE`. It was `"offline"`, the one lowercase code in a
126
- * surface whose every other code is `SCREAMING_SNAKE_CASE` — including the
127
- * `NETWORK_ERROR` it sits next to — so `e.code === "OFFLINE"`, which is what
128
- * anyone writes, never matched.
129
- */
130
- export declare function isOfflineError(error: unknown): boolean;
233
+ export { isOfflineError } from "./offline-errors.js";
131
234
  type AnyRow = Record<string, unknown>;
132
235
  type InnerFactory = (slug: string) => SDKCollectionClient<AnyRow>;
133
236
  export declare class OfflineManager {
@@ -136,16 +239,58 @@ export declare class OfflineManager {
136
239
  private readonly maxCachedRows;
137
240
  private readonly maxRetries;
138
241
  private readonly onSyncError?;
242
+ private readonly onConflict?;
139
243
  private readonly createInner;
140
244
  private readonly inners;
141
245
  private readonly connectivity;
246
+ private readonly keepLastUser;
247
+ private readonly replayBatchSize;
142
248
  private scope;
249
+ /**
250
+ * The scope is the last signed-in user's, taken without a confirmed
251
+ * session ({@link resumeLastUser}). Nothing replays while it is set: the
252
+ * queue is sent under the credentials of whoever is signed in, and nobody
253
+ * is yet.
254
+ */
255
+ private unverified;
256
+ /**
257
+ * Set while the manager does not know whose data it holds: from
258
+ * {@link holdScope} until the next {@link setScope}. `scope` is not
259
+ * consulted meanwhile — no operation gets a {@link ScopeTicket}, and
260
+ * nothing reads or writes the store.
261
+ */
262
+ private scopeHold?;
263
+ /**
264
+ * Bumped by every change of user, and by `clear()`.
265
+ *
266
+ * The load paths always re-checked the scope after their awaits; the write
267
+ * paths did not. A `find` sent for user A that answered after B had signed
268
+ * in wrote A's RLS-filtered rows into B's local database, under B's keys,
269
+ * and showed them to B's observers; a replay acknowledged after the switch
270
+ * dequeued a key under B's scope that did not exist, so A's write stayed
271
+ * queued and was sent again when A came back. Every write now carries the
272
+ * {@link ScopeTicket} its operation started under, and one that is stale
273
+ * touches nothing that belongs to the new user.
274
+ */
275
+ private scopeEpoch;
143
276
  /** The local database: normalized rows and query snapshots per collection. */
144
277
  private collections;
145
278
  /** In-memory mirror of the current scope's queue, in replay order. */
146
- private queue;
279
+ private queueEntries;
280
+ private get queue();
281
+ private set queue(value);
282
+ /**
283
+ * Per collection, the row ids the queue writes to and the ones it creates
284
+ * — {@link hasPending} and {@link isLocallyCreated}, which answering a
285
+ * page asks once or twice per row. Each used to scan the whole queue: a
286
+ * 500-row page against 200 queued writes read 80,000 queue entries, on
287
+ * every emit. Built on first use after the queue changes; whatever changes
288
+ * it in place calls {@link queueChangedInPlace}.
289
+ */
290
+ private pendingIndex?;
147
291
  /**
148
- * The mutation currently on the wire, if any.
292
+ * The mutations currently on the wire: one, or the members of a folded
293
+ * run (`replayBatchSize`).
149
294
  *
150
295
  * `flush` awaits `replay(op)` with `op` still at the head of `queue`, so for
151
296
  * the whole duration of that request the in-flight op is also the queue's
@@ -159,10 +304,10 @@ export declare class OfflineManager {
159
304
  * create. It is seeing it right now, so the row would be created and the
160
305
  * delete never queued — an orphan row nothing will ever remove.
161
306
  *
162
- * Guarding on the id rather than on a boolean keeps this correct if the
163
- * flush loop ever sends more than one op at a time.
307
+ * Guarding on ids rather than on a boolean is what keeps this correct
308
+ * when a folded run sends several at once, its last member the tail.
164
309
  */
165
- private inFlightId;
310
+ private readonly inFlight;
166
311
  private queueLoad?;
167
312
  /** Serializes enqueues so concurrent writes keep the order the app made them. */
168
313
  private enqueueChain;
@@ -173,6 +318,8 @@ export declare class OfflineManager {
173
318
  private refreshPending;
174
319
  private revCounter;
175
320
  private disposed;
321
+ /** Whether {@link requestPersistence} has asked. */
322
+ private persistenceRequested;
176
323
  private currentStatus;
177
324
  private readonly channel?;
178
325
  private readonly tabId;
@@ -184,7 +331,56 @@ export declare class OfflineManager {
184
331
  * replay under the credentials that made them — so neither may ever leak
185
332
  * across a sign-out/sign-in on a shared browser.
186
333
  */
187
- setScope(uid: string | undefined): void;
334
+ setScope(uid: string | undefined, options?: {
335
+ unverified?: boolean;
336
+ }): void;
337
+ /** Whether the manager was created with {@link OfflineConfig.keepLastUser}. */
338
+ get keepsLastUser(): boolean;
339
+ /**
340
+ * Take the scope of the last user who signed in on this device, without a
341
+ * session — for a load whose session restore could not reach the server.
342
+ * See {@link OfflineConfig.keepLastUser}. With no user remembered (or the
343
+ * option off) this is the signed-out scope, as it would have been anyway.
344
+ *
345
+ * Only while the scope is still held: an auth event that settled it while
346
+ * the id was being read is newer news.
347
+ */
348
+ resumeLastUser(): Promise<void>;
349
+ /**
350
+ * Keep the signed-in user's id for {@link resumeLastUser}, or forget it at
351
+ * sign-out. Forgetting does not depend on the option, so turning it off
352
+ * does not leave the last id behind for good.
353
+ */
354
+ private rememberUser;
355
+ /**
356
+ * Forget whose data this is until the next {@link setScope}.
357
+ *
358
+ * For the time before the client knows who is signed in — a session being
359
+ * restored on load. Taking that time for "signed out" would put the user's
360
+ * own writes in the signed-out queue, which no sign-in replays, and show
361
+ * them the signed-out local database instead of theirs.
362
+ *
363
+ * Meanwhile the manager has no scope at all. Every operation — a read, a
364
+ * write, a replay, `pending()`, `clear()` — waits for one and then runs
365
+ * for whoever it turns out to be, and nothing reads or writes the store.
366
+ * A realtime frame arriving in between is handed on as the server sent it
367
+ * and kept nowhere.
368
+ */
369
+ holdScope(): void;
370
+ /** Let go of the current user's rows and queue: in memory, and on screen. */
371
+ private leaveScope;
372
+ /** Settles once the manager knows whose data it holds — see {@link holdScope}. */
373
+ private scopeKnown;
374
+ /**
375
+ * The user an operation is running for — see {@link scopeEpoch} — or
376
+ * nothing while that is not known ({@link holdScope}). An operation takes
377
+ * it as `this.ticket() ?? await this.nextTicket()`, before its first await.
378
+ */
379
+ private ticket;
380
+ /** The ticket of whoever the held scope turns out to be. */
381
+ private nextTicket;
382
+ /** Whether an operation's user is still the signed-in one. */
383
+ private isCurrent;
188
384
  /**
189
385
  * Throw away every local row, for a scope change or an explicit clear.
190
386
  *
@@ -198,6 +394,21 @@ export declare class OfflineManager {
198
394
  /** Release listeners, timers and the cross-tab channel (client.close()). */
199
395
  dispose(): void;
200
396
  wrap<M extends AnyRow>(slug: string, inner: CollectionClient<M>): CollectionClient<M>;
397
+ /**
398
+ * `client.data.<slug>.trash` on an offline client: every call goes to the
399
+ * server, and none is cached or queued.
400
+ *
401
+ * The local database holds live rows only — a trashed row read into it
402
+ * would show up in every live query that matches it — so it cannot answer
403
+ * a trash read, and a restore or a purge queued offline would act on a row
404
+ * this device has never seen. Each of them rejects with `OFFLINE` instead.
405
+ *
406
+ * What the server answers does reach the local database: a restored row
407
+ * is live again and joins it, and a purged row leaves it. A row with a
408
+ * write still queued is synced first, so a purge never overtakes the
409
+ * queued delete it follows; if the queue cannot drain, the call is refused.
410
+ */
411
+ private wrapTrash;
201
412
  private observe;
202
413
  private observeById;
203
414
  private observersFor;
@@ -250,6 +461,13 @@ export declare class OfflineManager {
250
461
  * the difference. Reading one row first is enough to fix it.
251
462
  */
252
463
  private mintOfflineId;
464
+ /**
465
+ * Keep the version a server row came with, or forget the one held when it
466
+ * came with none: a row from a list carries no version, and may be newer
467
+ * than the one held. Only with `onConflict`, the one reader of it.
468
+ */
469
+ private noteETag;
470
+ private etagFor;
253
471
  private rawLocalRow;
254
472
  private localRow;
255
473
  private setLocalRow;
@@ -297,9 +515,35 @@ export declare class OfflineManager {
297
515
  */
298
516
  private scheduleRefresh;
299
517
  private evictRows;
518
+ /**
519
+ * Tombstones are tiny but unbounded — every row the app ever asked for and
520
+ * did not find leaves one. Capped against the row budget, oldest first,
521
+ * whenever one is added: the cap used to sit behind the row cache's own
522
+ * early return, so it only applied once the rows were over theirs, and
523
+ * looking up missing ids grew the set without limit.
524
+ */
525
+ private capTombstones;
300
526
  private evictSnapshots;
301
527
  private ensureQueueLoaded;
302
528
  private enqueue;
529
+ /**
530
+ * Ask the browser to keep the offline database, once, when there is first
531
+ * something in it worth keeping. Without it IndexedDB is best-effort
532
+ * storage, evicted under pressure (and by Safari after seven days without
533
+ * a visit) with the unsent writes in it.
534
+ */
535
+ private requestPersistence;
536
+ /** The queue's row ids for one collection — see {@link pendingIndex}. */
537
+ private pendingIds;
538
+ /**
539
+ * Did the queued writes to this row bring it into the query's filter? The
540
+ * row as it was before the first of them is that write's rollback; one
541
+ * that did not match then is in no server page of the query, so only
542
+ * this side can put it on screen.
543
+ */
544
+ private movedIntoFilter;
545
+ /** The queue's entries were changed without replacing the array. */
546
+ private queueChangedInPlace;
303
547
  private hasPending;
304
548
  /** Is this row one the server has never been told about? */
305
549
  private isLocallyCreated;
@@ -310,6 +554,38 @@ export declare class OfflineManager {
310
554
  remaining: number;
311
555
  }>;
312
556
  private flush;
557
+ /**
558
+ * The creates at the head of the queue that may replay as one request —
559
+ * see {@link OfflineConfig.replayBatchSize}. Fewer than two means the head
560
+ * replays on its own.
561
+ *
562
+ * Consecutive, so the queue's order holds; one collection, since a bulk
563
+ * write is one collection's. Each is a create never sent (so its request
564
+ * is still its own to choose) with an id the SDK minted as a string — a
565
+ * lost answer then cannot duplicate it, because the server refuses that
566
+ * id the second time and the single replay recognises the row as its
567
+ * own. A create whose values name another member's minted id waits: the
568
+ * server may give that row a different id, which only a replay one at a
569
+ * time can carry over.
570
+ */
571
+ private foldableRun;
572
+ /**
573
+ * Replay a {@link foldableRun} as one `createMany`.
574
+ *
575
+ * - `"done"`: every member is acknowledged, adopted and dropped.
576
+ * - `"offline"`: the connection failed; the members stay queued, as one
577
+ * write would.
578
+ * - `"unbatch"`: anything else — a refusal, a busy server. Nothing was
579
+ * written (a bulk write is one transaction), and the caller replays the
580
+ * members one at a time, where each refusal, retry budget and recovery
581
+ * applies to its own write.
582
+ *
583
+ * The key names the run by its first and last member and its length,
584
+ * which fixes its composition: a run re-sent after a lost answer is the
585
+ * same request under the same key, and is answered from the server's
586
+ * record of it.
587
+ */
588
+ private replayRun;
313
589
  private replay;
314
590
  /**
315
591
  * Send a queued write under its key.
@@ -353,6 +629,22 @@ export declare class OfflineManager {
353
629
  * silently lose writes the server would have accepted.
354
630
  */
355
631
  private rejectMutation;
632
+ /**
633
+ * An edit replayed with `If-Match` and refused with a 412: ask
634
+ * {@link OfflineConfig.onConflict}, and do what it says. A callback that
635
+ * throws, or none, is "overwrite" — what replay did before it knew of
636
+ * conflicts.
637
+ */
638
+ private resolveConflict;
639
+ /**
640
+ * Put the separate edits a coalesced `update` was made of back in the
641
+ * queue, in its place and in their order, each with the row as it stood
642
+ * before it as its rollback — so a refusal undoes that edit alone.
643
+ *
644
+ * Their ids extend the merged op's, which sorts them after it and before
645
+ * whatever was queued next, so the queue's order survives a reload.
646
+ */
647
+ private splitCoalesced;
356
648
  /** Every row id a mutation writes to. */
357
649
  private idsOf;
358
650
  private drop;
@@ -371,6 +663,10 @@ export declare class OfflineManager {
371
663
  private rowKey;
372
664
  private absentKey;
373
665
  private queueKey;
666
+ /** Queue a write in the store, its rows encoded as the cache's are. */
667
+ private persistMutation;
668
+ /** The store's queue under `prefix`, its rows revived. */
669
+ private readQueue;
374
670
  private readCache;
375
671
  private writeCache;
376
672
  private deleteCache;
@@ -23,7 +23,7 @@
23
23
  * generated SDK — where `M` is a concrete row type — the documented call was a
24
24
  * compile error. Nothing in this repo noticed; a downstream application did.
25
25
  */
26
- import type { FindParams, FindResult, SDKQueryBuilderInterface, WhereFilterOp } from "@rebasepro/types";
26
+ import type { AggregateParams, FindParams, FindResult, LogicalCondition, SDKCollectionClient, SDKQueryBuilderInterface, UpdateValues, WhereFilterOp } from "@rebasepro/types";
27
27
  /**
28
28
  * A row shaped the way a **generated** SDK shapes one: a type alias with a
29
29
  * finite key set.
@@ -46,6 +46,10 @@ type ContractRow = {
46
46
  tags: string[];
47
47
  age: number;
48
48
  deleted_at: string | null;
49
+ /** A `vector` property. */
50
+ embedding: number[];
51
+ /** An `enum` property, which codegen emits as a union of literals. */
52
+ status: "draft" | "published";
49
53
  };
50
54
  /** A to-many relation, which codegen emits as `Array<TargetRow>`. */
51
55
  type TagRow = {
@@ -67,11 +71,11 @@ export declare const orderByColumn: FindParams<ContractRow>;
67
71
  * turning every typo into an unsorted 200 in production.
68
72
  */
69
73
  export declare const orderByTypo: FindParams<ContractRow>;
70
- export declare const fluentScore: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
71
- export declare const fluentColumn: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
72
- export declare const fluentTypo: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
74
+ export declare const fluentScore: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
75
+ export declare const fluentColumn: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
76
+ export declare const fluentTypo: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
73
77
  /** Vector search must be reachable from the builder, and chain. */
74
- export declare const fluentVector: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
78
+ export declare const fluentVector: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
75
79
  /**
76
80
  * `array-contains` takes an **element** of the column, not the column.
77
81
  *
@@ -82,42 +86,57 @@ export declare const fluentVector: (qb: SDKQueryBuilderInterface<ContractRow>) =
82
86
  * did compile, `["featured"]`, builds `@> ARRAY[$1]` with the whole array bound
83
87
  * as the single element and matches nothing, forever, with no error anywhere.
84
88
  */
85
- export declare const fluentArrayContains: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
86
- export declare const fluentArrayContainsWrapped: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
89
+ export declare const fluentArrayContains: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
90
+ export declare const fluentArrayContainsWrapped: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
87
91
  /**
88
92
  * Same defect, and the case the relation compiler was specifically built for:
89
93
  * a to-many relation is emitted as `Array<TargetRow>`, and the compiler answers
90
94
  * `array-contains` on it by comparing **ids**. So the id must be accepted even
91
95
  * though it is not the element type.
92
96
  */
93
- export declare const fluentRelationContains: (qb: SDKQueryBuilderInterface<PostRow>, tagId: string) => SDKQueryBuilderInterface<PostRow>;
94
- export declare const fluentRelationIn: (qb: SDKQueryBuilderInterface<PostRow>, tagIds: string[]) => SDKQueryBuilderInterface<PostRow>;
95
- export declare const fluentRelationTypo: (qb: SDKQueryBuilderInterface<PostRow>) => SDKQueryBuilderInterface<PostRow>;
97
+ export declare const fluentRelationContains: (qb: SDKQueryBuilderInterface<PostRow>, tagId: string) => SDKQueryBuilderInterface<PostRow, import("@rebasepro/types").IncludeSpec>;
98
+ export declare const fluentRelationIn: (qb: SDKQueryBuilderInterface<PostRow>, tagIds: string[]) => SDKQueryBuilderInterface<PostRow, import("@rebasepro/types").IncludeSpec>;
99
+ export declare const fluentRelationTypo: (qb: SDKQueryBuilderInterface<PostRow>) => SDKQueryBuilderInterface<PostRow, import("@rebasepro/types").IncludeSpec>;
96
100
  /** The list operators take a list of elements — or one, read as a one-element list. */
97
- export declare const fluentInList: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
98
- export declare const fluentInScalar: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
99
- export declare const fluentInNested: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
101
+ export declare const fluentInList: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
102
+ export declare const fluentInScalar: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
103
+ export declare const fluentInNested: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
100
104
  /** A comparison takes one value. `eq(column, ["a","b"])` is not a query anyone meant. */
101
- export declare const fluentEqArray: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
105
+ export declare const fluentEqArray: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
102
106
  /**
103
107
  * A pattern is a string on every column type. The driver casts, so refusing
104
108
  * `"%3%"` on a numeric column was the type being stricter than the runtime.
105
109
  */
106
- export declare const fluentLikeOnNumber: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
110
+ export declare const fluentLikeOnNumber: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
107
111
  /** The null operators ignore their value; `null` is the conventional spelling. */
108
- export declare const fluentIsNull: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
112
+ export declare const fluentIsNull: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
109
113
  /**
110
114
  * A caller holding an unnarrowed operator — a dynamic filter UI — must keep
111
115
  * compiling. `WhereValueFor` distributes over the operator, so this is the
112
116
  * union of every branch rather than a `never`.
113
117
  */
114
- export declare const fluentDynamicOp: (qb: SDKQueryBuilderInterface<ContractRow>, op: WhereFilterOp) => SDKQueryBuilderInterface<ContractRow>;
118
+ export declare const fluentDynamicOp: (qb: SDKQueryBuilderInterface<ContractRow>, op: WhereFilterOp) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
115
119
  /** Two conditions on one column: the shape the Mongo compiler used to drop. */
116
- export declare const fluentRange: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
120
+ export declare const fluentRange: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
117
121
  /** The object form must accept exactly what the fluent form accepts. */
118
122
  export declare const paramsArrayContains: FindParams<ContractRow>;
119
123
  /** …and the array-of-tuples form the builder produces from two `.where()` calls. */
120
124
  export declare const paramsRange: FindParams<ContractRow>;
125
+ /**
126
+ * `cond` cannot know the row on its own; the place the group is used can.
127
+ * `logical` and `.where(group)` check every condition in the tree against `M`,
128
+ * as the object-form `where` does, so a typo'd column is a compile error, not
129
+ * the server's 400.
130
+ */
131
+ export declare const logicalOk: FindParams<ContractRow>;
132
+ export declare const logicalTypo: FindParams<ContractRow>;
133
+ export declare const logicalWrongValue: FindParams<ContractRow>;
134
+ export declare const logicalEnumTypo: FindParams<ContractRow>;
135
+ export declare const logicalArrayContainsList: FindParams<ContractRow>;
136
+ export declare const fluentLogicalTypo: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
137
+ export declare const fluentLogicalOk: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
138
+ /** A group built at runtime keeps working where the row is untyped. */
139
+ export declare const untypedLogical: (qb: SDKQueryBuilderInterface, group: LogicalCondition) => SDKQueryBuilderInterface<Record<string, unknown>, import("@rebasepro/types").IncludeSpec>;
121
140
  /**
122
141
  * Sorting by relevance and then being unable to read it was the other half of
123
142
  * the same bug — the e2e cast around it, which should have been the tell.
@@ -150,11 +169,11 @@ export declare const rowStaysIndexable: (result: FindResult<ContractRow>) => Rec
150
169
  * which is to say: on every project that took the trouble to be typed.
151
170
  */
152
171
  /** 1. A relation path. `find({ where: { "author.name": … } })` always compiled. */
153
- export declare const fluentRelationPath: (qb: SDKQueryBuilderInterface<PostRow>) => SDKQueryBuilderInterface<PostRow>;
172
+ export declare const fluentRelationPath: (qb: SDKQueryBuilderInterface<PostRow>) => SDKQueryBuilderInterface<PostRow, import("@rebasepro/types").IncludeSpec>;
154
173
  /** 2. A JSON path into a `jsonb` column — `?metadata->>tier=eq.gold` on the wire. */
155
- export declare const fluentJsonPath: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
174
+ export declare const fluentJsonPath: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
156
175
  /** 3. An aggregate over a to-many relation, which `FindParams.orderBy` takes. */
157
- export declare const fluentRelationAggregateSort: (qb: SDKQueryBuilderInterface<PostRow>) => SDKQueryBuilderInterface<PostRow>;
176
+ export declare const fluentRelationAggregateSort: (qb: SDKQueryBuilderInterface<PostRow>) => SDKQueryBuilderInterface<PostRow, import("@rebasepro/types").IncludeSpec>;
158
177
  /** 4. Paging past the `limit` ceiling, which the client can do and the builder could not. */
159
178
  export declare const fluentIterate: (qb: SDKQueryBuilderInterface<ContractRow>) => AsyncIterableIterator<ContractRow>;
160
179
  export declare const fluentFindAll: (qb: SDKQueryBuilderInterface<ContractRow>) => Promise<ContractRow[]>;
@@ -164,11 +183,44 @@ export declare const fluentFindAll: (qb: SDKQueryBuilderInterface<ContractRow>)
164
183
  * `unknown` — turning every one of the assertions above into a silent pass.
165
184
  * These are the same refusals as before.
166
185
  */
167
- export declare const fluentPathTypo: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
168
- export declare const fluentPathDoesNotLoosenValues: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
169
- export declare const fluentAggregateSortTypo: (qb: SDKQueryBuilderInterface<PostRow>) => SDKQueryBuilderInterface<PostRow>;
186
+ export declare const fluentPathTypo: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
187
+ export declare const fluentPathDoesNotLoosenValues: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
188
+ export declare const fluentAggregateSortTypo: (qb: SDKQueryBuilderInterface<PostRow>) => SDKQueryBuilderInterface<PostRow, import("@rebasepro/types").IncludeSpec>;
170
189
  /** And the object form still takes all four, unchanged. */
171
190
  export declare const paramsRelationPath: FindParams<PostRow>;
172
191
  export declare const paramsJsonPath: FindParams<ContractRow>;
173
192
  export declare const paramsRelationAggregateSort: FindParams<PostRow>;
193
+ /**
194
+ * `FilterValues` typed the key and left the value `unknown`, so the shape the
195
+ * fluent form was fixed to refuse compiled in `find({ where })` — the form
196
+ * `listen`, `observe`, `count` and `iterate` all take.
197
+ */
198
+ export declare const paramsArrayContainsWholeArray: FindParams<ContractRow>;
199
+ export declare const paramsWrongValueType: FindParams<ContractRow>;
200
+ /** A path that is not a column has nothing to check against, and stays open. */
201
+ export declare const paramsRelationPathTyped: FindParams<ContractRow>;
202
+ /** An untyped row keeps the object form exactly as permissive as it was. */
203
+ export declare const paramsUntyped: FindParams;
204
+ /** `fields` is a projection of columns; a typo was `UNKNOWN_FIELD` at runtime. */
205
+ export declare const fieldsColumn: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
206
+ export declare const fieldsTypo: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
207
+ /** `vectorSearch` names a column. */
208
+ export declare const vectorTypo: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
209
+ /** `sum` and `avg` add numbers up; `min`/`max` order anything. */
210
+ export declare const aggregateSum: AggregateParams<ContractRow>;
211
+ export declare const aggregateSumText: AggregateParams<ContractRow>;
212
+ /** A field operation fits its column: `$inc` a number, `$push` an array. */
213
+ export declare const updateOps: UpdateValues<Partial<ContractRow>>;
214
+ export declare const updateIncText: UpdateValues<Partial<ContractRow>>;
215
+ /** An untyped row keeps every operation on every key. */
216
+ export declare const updateUntyped: UpdateValues<Partial<Record<string, unknown>>>;
217
+ /**
218
+ * A typed client is still a client: a helper written against the wide
219
+ * `SDKCollectionClient` (an export, a paginator, a seeder) takes
220
+ * `rebase.data.posts`. The column checks above must narrow what a typed
221
+ * client's methods accept without making the typed client a different kind
222
+ * of thing — `NumericKeyOf` as a conditional over `keyof M` made tsc measure
223
+ * `AggregateParams` invariant, and this line stopped compiling.
224
+ */
225
+ export declare const typedClientWidens: (posts: SDKCollectionClient<ContractRow>) => SDKCollectionClient;
174
226
  export {};
@@ -98,6 +98,19 @@ export interface ChannelTransport {
98
98
  sendMessage(message: Record<string, unknown>): Promise<unknown>;
99
99
  onChannelMessage(channel: string, handler: (message: ChannelMessage) => void): () => void;
100
100
  onReconnect(handler: () => void): () => void;
101
+ /**
102
+ * Notified once per outage that outlasted a blip. Optional so a test
103
+ * transport need not implement it.
104
+ */
105
+ onConnectionLost?(handler: (error: RebaseApiError) => void): () => void;
106
+ /**
107
+ * Whether the server agreed, for the current socket, to `name` (see the
108
+ * socket's `hello`). A transport without it is one whose server agreed to
109
+ * nothing.
110
+ */
111
+ hasServerOptIn?(name: string): boolean;
112
+ /** The current socket's id on the server: the `senderId` of what it broadcasts. */
113
+ readonly socketClientId?: string;
101
114
  }
102
115
  export declare class RebaseRealtimeChannel {
103
116
  readonly name: string;
@@ -298,6 +311,23 @@ export declare class RebaseRealtimeChannel {
298
311
  private stopHeartbeat;
299
312
  /** Fold an incoming frame into the roster and fan it out. */
300
313
  private handle;
314
+ /**
315
+ * Whether a jump in the sequence means a missed message: only when the
316
+ * server numbers this client's own broadcasts for it (`channel_seq`), so
317
+ * its own messages leave no hole. Against a server that does not, a hole
318
+ * is as likely to be the client's own message, and the old behaviour —
319
+ * deliver, advance — stands.
320
+ */
321
+ private watchesForGaps;
322
+ /**
323
+ * Hold `event` back and fetch what lies between it and {@link lastSeq},
324
+ * when it is past a hole. A frame can go missing between instances — a
325
+ * dropped bus connection, a bus that does not order — and the watermark
326
+ * would otherwise step over it for good.
327
+ *
328
+ * @returns Whether it was held back.
329
+ */
330
+ private fillsGap;
301
331
  /** Tell the app that retention dropped messages it never received. */
302
332
  private reportHistoryGap;
303
333
  private emitError;