@rebasepro/client 0.10.1-canary.gdaf6ba4 → 0.11.0

package/dist/offline-connectivity.d.ts

@@ -14,6 +14,18 @@
 export declare function isNetworkError(error: unknown): boolean;
 /** Is this failure worth another attempt later? */
 export declare function isRetryableError(error: unknown): boolean;
+/**
+ * Did this write fail because the row is already there?
+ *
+ * Matched on the SQLSTATE the server passes through (`23505`, unique_violation)
+ * and on 409, never on the message — a duplicate-key message names the
+ * constraint and the values, so it is neither stable nor safe to parse.
+ *
+ * The queue uses this to recognise its own earlier attempt. A create whose
+ * response was lost is replayed, and for a row carrying an id the SDK generated
+ * the server can only be rejecting it because the first attempt actually landed.
+ */
+export declare function isDuplicateKeyError(error: unknown): boolean;
 export interface ConnectivityOptions {
     /** First retry delay after a failure. Defaults to 1 000 ms. */
     initialBackoffMs?: number;

package/dist/offline.d.ts

@@ -137,6 +137,25 @@ export declare class OfflineManager {
     private collections;
     /** In-memory mirror of the current scope's queue, in replay order. */
     private queue;
+    /**
+     * The mutation currently on the wire, if any.
+     *
+     * `flush` awaits `replay(op)` with `op` still at the head of `queue`, so for
+     * the whole duration of that request the in-flight op is also the queue's
+     * *tail* whenever it is the only entry. Both shortcuts in `enqueue` reach
+     * for the tail, and neither may touch an op the server is already reading:
+     *
+     * - Coalescing an update into it mutates a payload that has already been
+     *   serialized and sent, and `drop` then removes the whole entry on ACK —
+     *   so the second edit is neither sent nor kept. A silently lost write.
+     * - Cancelling it out against a delete assumes the server never saw the
+     *   create. It is seeing it right now, so the row would be created and the
+     *   delete never queued — an orphan row nothing will ever remove.
+     *
+     * Guarding on the id rather than on a boolean keeps this correct if the
+     * flush loop ever sends more than one op at a time.
+     */
+    private inFlightId;
     private queueLoad?;
     /** Serializes enqueues so concurrent writes keep the order the app made them. */
     private enqueueChain;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/client",
   "type": "module",
-  "version": "0.10.1-canary.gdaf6ba4",
+  "version": "0.11.0",
   "description": "HTTP SDK client for the Rebase custom backend",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -29,9 +29,9 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@rebasepro/common": "0.10.1-canary.gdaf6ba4",
-    "@rebasepro/types": "0.10.1-canary.gdaf6ba4",
-    "@rebasepro/utils": "0.10.1-canary.gdaf6ba4"
+    "@rebasepro/common": "0.11.0",
+    "@rebasepro/types": "0.11.0",
+    "@rebasepro/utils": "0.11.0"
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",

package/src/collection.ts

@@ -6,7 +6,8 @@ import {
     SDKCollectionClient,
     SDKQueryBuilderInterface,
     WhereFilterOp,
-    WhereValue
+    WhereValue,
+    WriteOptions
 } from "@rebasepro/types";
 
 import { SDKQueryBuilder } from "./sdk_query_builder";
@@ -125,14 +126,17 @@ export function createCollectionClient<M extends Record<string, unknown> = Recor
             }
         },
 
-        async create(data: Partial<M>, id?: string | number) {
+        async create(data: Partial<M>, id?: string | number, options?: WriteOptions) {
             const body: Record<string, unknown> = { ...data };
             if (id !== undefined) {
                 body.id = id;
             }
             const raw = await transport.request<Record<string, unknown>>(basePath, {
                 method: "POST",
-                body: JSON.stringify(body)
+                body: JSON.stringify(body),
+                ...(options?.idempotencyKey
+                    ? { headers: { "Idempotency-Key": options.idempotencyKey } }
+                    : {})
             });
             return raw as M;
         },

package/src/offline-connectivity.ts

@@ -45,6 +45,22 @@ export function isRetryableError(error: unknown): boolean {
     return false;
 }
 
+/**
+ * Did this write fail because the row is already there?
+ *
+ * Matched on the SQLSTATE the server passes through (`23505`, unique_violation)
+ * and on 409, never on the message — a duplicate-key message names the
+ * constraint and the values, so it is neither stable nor safe to parse.
+ *
+ * The queue uses this to recognise its own earlier attempt. A create whose
+ * response was lost is replayed, and for a row carrying an id the SDK generated
+ * the server can only be rejecting it because the first attempt actually landed.
+ */
+export function isDuplicateKeyError(error: unknown): boolean {
+    if (!(error instanceof RebaseApiError)) return false;
+    return error.code === "23505" || error.status === 409;
+}
+
 export interface ConnectivityOptions {
     /** First retry delay after a failure. Defaults to 1 000 ms. */
     initialBackoffMs?: number;

package/src/offline-sync-engine.test.ts

@@ -31,6 +31,14 @@ function createFakeServer() {
         return tables.get(slug)!;
     }
 
+    /**
+     * Requests parked mid-flight, keyed `${op}:${id}`. Holding a request open is
+     * the only way to reproduce anything that goes wrong *while* an op is on the
+     * wire — the queue treats an in-flight op differently from a queued one, and
+     * a fake that returns immediately can never be in that state.
+     */
+    const gates = new Map<string, Promise<void>>();
+
     function guard(slug: string, op: string, id?: unknown) {
         calls.push({ collection: slug, op, id });
         if (!state.online) throw new TypeError("fetch failed");
@@ -38,6 +46,11 @@ function createFakeServer() {
         if (rejection) throw rejection;
     }
 
+    /** Await after `guard`, so a parked request has already been counted. */
+    function hold(op: string, id?: unknown): Promise<void> | undefined {
+        return gates.get(`${op}:${String(id)}`);
+    }
+
     function client(slug: string): CollectionClient<Row> {
         const fake = {
             async find(params?: FindParams) {
@@ -51,6 +64,7 @@ function createFakeServer() {
             async create(data: Row, id?: string | number) {
                 const wanted = id ?? data.id;
                 guard(slug, "create", wanted);
+                await hold("create", wanted);
                 const rowId = idRewrites.get(String(wanted)) ?? wanted ?? `srv-${table(slug).size + 1}`;
                 const row = { ...data, id: rowId };
                 table(slug).set(String(rowId), row);
@@ -92,6 +106,7 @@ function createFakeServer() {
         client,
         rejections,
         idRewrites,
+        gates,
         countCalls: (op: string) => calls.filter((c) => c.op === op).length
     };
 }
@@ -725,3 +740,118 @@ describe("counts", () => {
         expect(await posts.count()).toBe(1);
     });
 });
+
+describe("a write made while another is on the wire", () => {
+    /**
+     * `flush` awaits `replay(op)` with `op` still sitting at the head of the
+     * queue, so for the whole duration of that request the in-flight op is also
+     * the tail — and both of `enqueue`'s shortcuts reach for the tail.
+     */
+    it("does not swallow an edit that lands mid-request", async () => {
+        const server = createFakeServer();
+        const { wrap, manager } = createManager(server);
+        const posts = wrap("posts");
+
+        server.state.online = false;
+        await posts.create({ title: "first" }, "p1");
+
+        // Park the create so the edit below arrives while it is in flight.
+        let release!: () => void;
+        server.gates.set("create:p1", new Promise<void>((resolve) => { release = resolve; }));
+
+        server.state.online = true;
+        const syncing = manager.sync();
+        await settle();
+
+        await posts.update("p1", { title: "edited" });
+        release();
+        await syncing;
+        await manager.sync();
+
+        // Coalesced into the in-flight create, this edit was dropped with it on
+        // ACK: never sent, and gone from the queue. The user's second keystroke
+        // vanished with no error anywhere.
+        expect(server.table("posts").get("p1")).toMatchObject({ title: "edited" });
+    });
+
+    it("does not strand a row when a delete cancels out an in-flight create", async () => {
+        const server = createFakeServer();
+        const { wrap, manager } = createManager(server);
+        const posts = wrap("posts");
+
+        server.state.online = false;
+        const created = await posts.create({ title: "doomed" });
+        const id = String((created as Row).id);
+
+        let release!: () => void;
+        server.gates.set(`create:${id}`, new Promise<void>((resolve) => { release = resolve; }));
+
+        server.state.online = true;
+        const syncing = manager.sync();
+        await settle();
+
+        // Cancel-out assumes the server never saw the create. It is reading it
+        // right now, so the row lands — and if the delete is discarded with it,
+        // nothing will ever remove it.
+        await posts.delete(id);
+        release();
+        await syncing;
+        await manager.sync();
+
+        expect(server.table("posts").has(id)).toBe(false);
+    });
+});
+
+describe("replaying a create whose response was lost", () => {
+    it("keeps the row when the server says it is already there", async () => {
+        const server = createFakeServer();
+        const errors: Error[] = [];
+        const { wrap, manager } = createManager(server, {
+            onSyncError: (error) => errors.push(error)
+        });
+        const posts = wrap("posts");
+
+        server.state.online = false;
+        const created = await posts.create({ title: "saved" });
+        const id = String((created as Row).id);
+
+        // The first attempt committed; only the ACK was lost. The replay
+        // therefore finds the row already present.
+        server.table("posts").set(id, { id, title: "saved" });
+        server.rejections.set(`create:${id}`, new RebaseApiError("duplicate key", { status: 409, code: "23505" }));
+
+        server.state.online = true;
+        await manager.sync();
+
+        // Read with the network down, or this falls through to the server and
+        // passes on the row seeded above no matter what the local store did —
+        // which is exactly how this test first passed against the bug.
+        server.state.online = false;
+        // The old behaviour rolled the write back and deleted the local row —
+        // the one case where the row genuinely exists on the server.
+        expect(await posts.findById(id)).toMatchObject({ title: "saved" });
+        expect(errors).toHaveLength(0);
+        expect(manager.api.status().pending).toBe(0);
+    });
+
+    it("still reports a real conflict on a caller-supplied id", async () => {
+        const server = createFakeServer();
+        const errors: Error[] = [];
+        const { wrap, manager } = createManager(server, {
+            onSyncError: (error) => errors.push(error)
+        });
+        const posts = wrap("posts");
+
+        server.state.online = false;
+        // The caller chose this id, so a duplicate may well be someone else's
+        // row. Swallowing that would hide a genuine collision.
+        await posts.create({ title: "mine" }, "chosen-1");
+        server.rejections.set("create:chosen-1", new RebaseApiError("duplicate key", { status: 409, code: "23505" }));
+
+        server.state.online = true;
+        await manager.sync();
+
+        expect(errors).toHaveLength(1);
+        expect(manager.api.status().pending).toBe(0);
+    });
+});

package/src/offline.ts

@@ -3,7 +3,7 @@ import { FindResult, LogicalCondition, SDKCollectionClient, WhereFilterOp, Where
 import { CollectionClient, LiveResult, ObserveOptions, RowSnapshotMeta } from "./collection";
 import { SDKQueryBuilder } from "./sdk_query_builder";
 import { dehydrateRow, hydrateRow } from "./offline-codec";
-import { ConnectivityMonitor, isNetworkError, isRetryableError } from "./offline-connectivity";
+import { ConnectivityMonitor, isDuplicateKeyError, isNetworkError, isRetryableError } from "./offline-connectivity";
 import {
     IndexedDBOfflineStore,
     MemoryOfflineStore,
@@ -231,6 +231,25 @@ export class OfflineManager {
     private collections = new Map<string, CollectionState>();
     /** In-memory mirror of the current scope's queue, in replay order. */
     private queue: PendingMutation[] = [];
+    /**
+     * The mutation currently on the wire, if any.
+     *
+     * `flush` awaits `replay(op)` with `op` still at the head of `queue`, so for
+     * the whole duration of that request the in-flight op is also the queue's
+     * *tail* whenever it is the only entry. Both shortcuts in `enqueue` reach
+     * for the tail, and neither may touch an op the server is already reading:
+     *
+     * - Coalescing an update into it mutates a payload that has already been
+     *   serialized and sent, and `drop` then removes the whole entry on ACK —
+     *   so the second edit is neither sent nor kept. A silently lost write.
+     * - Cancelling it out against a delete assumes the server never saw the
+     *   create. It is seeing it right now, so the row would be created and the
+     *   delete never queued — an orphan row nothing will ever remove.
+     *
+     * Guarding on the id rather than on a boolean keeps this correct if the
+     * flush loop ever sends more than one op at a time.
+     */
+    private inFlightId: string | null = null;
     private queueLoad?: Promise<void>;
     /** Serializes enqueues so concurrent writes keep the order the app made them. */
     private enqueueChain: Promise<unknown> = Promise.resolve();
@@ -520,7 +539,13 @@ export class OfflineManager {
 
             update: async (id: string | number, data: Partial<M>) => {
                 await this.ensureCollection(slug);
-                if (this.connectivity.shouldAttempt()) {
+                // Never overtake a write already queued for this row. The
+                // reads already respect the queue; the writes did not, so an
+                // edit made while the row's own create was still pending went
+                // straight to a server that had never heard of the row and came
+                // back 404 — the caller's edit failing on a row they could see.
+                // Queuing keeps the order the app issued the writes in.
+                if (this.connectivity.shouldAttempt() && !this.hasPending(slug, id)) {
                     try {
                         const row = await inner.update(id, data);
                         this.connectivity.markSuccess();
@@ -548,7 +573,10 @@ export class OfflineManager {
 
             delete: async (id: string | number) => {
                 await this.ensureCollection(slug);
-                if (this.connectivity.shouldAttempt()) {
+                // As in `update`: a delete must not overtake this row's own
+                // queued create, or it 404s and the create then lands behind
+                // it, leaving the row the caller just deleted.
+                if (this.connectivity.shouldAttempt() && !this.hasPending(slug, id)) {
                     try {
                         await inner.delete(id);
                         this.connectivity.markSuccess();
@@ -1212,6 +1240,7 @@ export class OfflineManager {
             if (mutation.type === "update") {
                 const tail = this.queue[this.queue.length - 1];
                 if (tail
+                    && tail.mutationId !== this.inFlightId
                     && tail.collection === mutation.collection
                     && (tail.type === "create" || tail.type === "update")
                     && tail.id === mutation.id) {
@@ -1233,14 +1262,19 @@ export class OfflineManager {
             // the delete must still remove), and neither do rows queued inside
             // a createMany (the bulk op replays first, then the delete).
             if (mutation.type === "delete") {
+                // An in-flight create disqualifies the shortcut entirely: the
+                // server is being told about the row as we speak, so "it never
+                // saw it" is false and the delete has to replay after it.
                 const hasPendingCreate = this.queue.some((m) =>
                     m.collection === mutation.collection && m.type === "create"
-                    && m.id === mutation.id && m.generatedId === true);
+                    && m.id === mutation.id && m.generatedId === true
+                    && m.mutationId !== this.inFlightId);
                 if (hasPendingCreate) {
                     const doomed = this.queue.filter((m) =>
                         m.collection === mutation.collection
                         && m.id === mutation.id
-                        && (m.type === "create" || m.type === "update"));
+                        && (m.type === "create" || m.type === "update")
+                        && m.mutationId !== this.inFlightId);
                     for (const op of doomed) await this.store.dequeue(this.queueKey(op));
                     this.queue = this.queue.filter((m) => !doomed.includes(m));
                     this.afterQueueChange();
@@ -1332,31 +1366,40 @@ export class OfflineManager {
             while (this.queue.length > 0 && !this.disposed) {
                 const op = this.queue[0];
                 touched.add(op.collection);
+                // Held across `drop` as well as `replay`: between the ACK and
+                // the dequeue the op is still in `queue`, still the tail, and
+                // still about to be removed — coalescing into it there loses
+                // the write exactly as coalescing during the request does.
+                this.inFlightId = op.mutationId;
                 try {
-                    await this.replay(op);
-                } catch (error) {
-                    if (isNetworkError(error)) {
-                        // Still offline — keep the op and everything behind it.
-                        this.connectivity.markFailure();
-                        break;
-                    }
-                    op.attempts = (op.attempts ?? 0) + 1;
-                    op.lastError = (error as Error)?.message ?? String(error);
-                    if (isRetryableError(error) && op.attempts < this.maxRetries) {
-                        // The server is busy, not unhappy. Keep the op — and
-                        // its place in line, since later writes may depend on
-                        // it — and come back after a backoff.
-                        await this.store.enqueue(this.queueKey(op), op).catch(() => undefined);
-                        this.connectivity.deferRetry();
-                        this.patchStatus({ lastError: op.lastError });
-                        break;
+                    try {
+                        await this.replay(op);
+                    } catch (error) {
+                        if (isNetworkError(error)) {
+                            // Still offline — keep the op and everything behind it.
+                            this.connectivity.markFailure();
+                            break;
+                        }
+                        op.attempts = (op.attempts ?? 0) + 1;
+                        op.lastError = (error as Error)?.message ?? String(error);
+                        if (isRetryableError(error) && op.attempts < this.maxRetries) {
+                            // The server is busy, not unhappy. Keep the op — and
+                            // its place in line, since later writes may depend on
+                            // it — and come back after a backoff.
+                            await this.store.enqueue(this.queueKey(op), op).catch(() => undefined);
+                            this.connectivity.deferRetry();
+                            this.patchStatus({ lastError: op.lastError });
+                            break;
+                        }
+                        await this.rejectMutation(op, error as Error);
+                        continue;
                     }
-                    await this.rejectMutation(op, error as Error);
-                    continue;
+                    this.connectivity.markSuccess();
+                    await this.drop(op);
+                    flushed++;
+                } finally {
+                    this.inFlightId = null;
                 }
-                this.connectivity.markSuccess();
-                await this.drop(op);
-                flushed++;
             }
         } finally {
             this.patchStatus({ syncing: false });
@@ -1382,7 +1425,36 @@ export class OfflineManager {
         const inner = this.innerFor(op.collection);
         if (op.type === "create") {
             // The queued row already carries its (client-generated) id.
-            const row = await inner.create(op.data as AnyRow);
+            let row: AnyRow | undefined;
+            try {
+                // The mutation id names this write, so a server that stores keys
+                // recognises a replay instead of inserting a second row. This is
+                // the only defence for a table with a server-assigned id: the id
+                // the client chose was never used, so a duplicate is invisible
+                // from here. Ignored by servers that do not support it.
+                row = await inner.create(op.data as AnyRow, undefined, { idempotencyKey: op.mutationId });
+            } catch (error) {
+                // A lost response, not a rejection. The request reached the
+                // server and committed; only the ACK went missing, so the
+                // replay finds the row already there.
+                //
+                // Restricted to ids the SDK minted: a fresh uuid cannot name a
+                // row anyone else created, so a duplicate under it is
+                // necessarily this mutation's own first attempt. A
+                // caller-supplied id carries no such guarantee — it may well
+                // collide with a row that was already there, which is a real
+                // conflict the caller has to hear about.
+                //
+                // Without this, `rejectMutation` rolled the write back and
+                // DELETED the local row — the one case where the row does exist
+                // on the server. The user watched their own saved record vanish.
+                if (!(op.generatedId === true && isDuplicateKeyError(error))) throw error;
+                row = await inner.findById(op.id!).catch(() => undefined) as AnyRow | undefined;
+                // The read can fail on its own (offline again, RLS). The row is
+                // known to exist, so keep the local copy rather than rolling
+                // back; the next refresh reconciles it.
+                if (!row) return;
+            }
             await this.adoptServerRow(op, op.id, row);
         } else if (op.type === "createMany") {
             const queued = (op.data as AnyRow[]) ?? [];