@rebasepro/client 0.13.0 → 0.13.1-canary.g249daa1

package/src/offline-query.ts

@@ -9,6 +9,7 @@ import {
     toCanonicalOp
 } from "@rebasepro/types";
 import { FindParams } from "./transport";
+import { resolveFindWindow } from "@rebasepro/common";
 
 /**
  * A local evaluator for `FindParams`, so cached rows can answer a query the
@@ -38,8 +39,15 @@ const collator = typeof Intl !== "undefined" && typeof Intl.Collator === "functi
     ? new Intl.Collator(undefined, { numeric: false, sensitivity: "variant" })
     : undefined;
 
-/** The server's page size when the caller does not ask for one. */
-export const DEFAULT_PAGE_SIZE = 20;
+/**
+ * The server's page size when the caller does not ask for one.
+ *
+ * Re-exported rather than redeclared. This was its own `= 20` — a third
+ * constant of this name in the workspace, next to `@rebasepro/common`'s 200 and
+ * the 50 the REST layer actually applies — and a local copy of a number that
+ * belongs to another process is a number that goes stale silently.
+ */
+export { DEFAULT_LIST_LIMIT as DEFAULT_PAGE_SIZE } from "@rebasepro/types";
 
 function isNullish(value: unknown): boolean {
     return value === null || value === undefined;
@@ -137,17 +145,31 @@ export function looseEquals(a: unknown, b: unknown): boolean {
  */
 function likeToRegExp(pattern: string, caseInsensitive: boolean): RegExp {
     let source = "^";
+    // Runs of `%` collapse to one. `%%%%X` means exactly what `%X` means, but
+    // as a regular expression it is four adjacent unbounded quantifiers, and on
+    // a subject that does not match the engine tries every way of splitting the
+    // subject between them. Fourteen of them against a forty-eight character
+    // value took eighty-seven seconds to answer `false`.
+    //
+    // The pattern is user input — `?title=like.%25%25%25…` over HTTP — so that
+    // is a request that pins a CPU. Collapsing is semantics-preserving and
+    // removes the ambiguity the backtracking feeds on.
+    let lastWasWildcard = false;
     for (let i = 0; i < pattern.length; i++) {
         const char = pattern[i];
         if (char === "\\" && i + 1 < pattern.length) {
             source += pattern[i + 1].replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
             i++;
+            lastWasWildcard = false;
         } else if (char === "%") {
-            source += "[\\s\\S]*";
+            if (!lastWasWildcard) source += "[\\s\\S]*";
+            lastWasWildcard = true;
         } else if (char === "_") {
             source += "[\\s\\S]";
+            lastWasWildcard = false;
         } else {
             source += char.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+            lastWasWildcard = false;
         }
     }
     return new RegExp(source + "$", caseInsensitive ? "i" : "");
@@ -311,12 +333,17 @@ function tiebreak(a: Record<string, unknown>, b: Record<string, unknown>): numbe
     return cmp ?? 0;
 }
 
-/** Resolve `page`/`offset`/`limit` the way the server does. */
+/**
+ * Resolve `page`/`offset`/`limit` the way the server does.
+ *
+ * It did not: this defaulted an absent limit to 20 while `/api/data` pages by
+ * 50, so the same `observe()` answered with 20 rows from the local database and
+ * 50 from the network — a list that changed length depending on which side
+ * answered, with `page` striding differently on each. Delegated now, so the
+ * sentence above is true by construction rather than by agreement.
+ */
 export function resolvePagination(params?: FindParams): { limit: number; offset: number } {
-    const limit = params?.limit ?? DEFAULT_PAGE_SIZE;
-    const offset = params?.page != null
-        ? Math.max(0, (params.page - 1) * limit)
-        : (params?.offset ?? 0);
+    const { limit, offset } = resolveFindWindow(params);
     return { limit, offset };
 }
 
@@ -332,6 +359,11 @@ export function isExactlyEvaluable(params?: FindParams): boolean {
     if (!params) return true;
     if (params.include && params.include.length > 0) return false;
     if (params.searchString) return false;
+    // Nearest-neighbour ordering is the server's to compute: the cache holds no
+    // vectors, and even with them, answering from a subset would return the
+    // nearest of what happens to be cached while looking like the nearest there
+    // are — a wrong answer that is indistinguishable from a right one.
+    if (params.vectorSearch) return false;
     return true;
 }
 

package/src/offline-store.ts

@@ -52,9 +52,13 @@ export interface PendingMutation {
     /** Unique, lexicographically sortable identity — also the queue key suffix. */
     mutationId: string;
     collection: string;
-    type: "create" | "createMany" | "update" | "delete";
+    type: "create" | "createMany" | "update" | "updateMany" | "delete" | "deleteMany";
     /** Target row id for update/delete, and the (client-generated) id of an offline create. */
     id?: string | number;
+    /** Target row ids for `deleteMany`. */
+    ids?: (string | number)[];
+    /** `{ id, data }` entries for `updateMany`. */
+    updates?: { id: string | number; data: Record<string, unknown> }[];
     /**
      * True when the SDK minted this create's id itself. Only such creates may
      * cancel out against a later offline delete: a freshly generated UUID

package/src/offline.test.ts

@@ -16,7 +16,7 @@ type Row = Record<string, unknown>;
 function createFakeServer() {
     const state = { online: true };
     const tables = new Map<string, Map<string, Row>>();
-    const log: { collection: string; op: string; id?: unknown; upsert?: boolean }[] = [];
+    const log: { collection: string; op: string; id?: unknown; ids?: unknown[]; upsert?: boolean }[] = [];
 
     function table(slug: string): Map<string, Row> {
         if (!tables.has(slug)) tables.set(slug, new Map());
@@ -67,11 +67,30 @@ function createFakeServer() {
                 table(slug).set(String(id), row);
                 return row;
             },
+            async updateMany(updates: { id: string | number; data: Partial<Row> }[]) {
+                assertOnline();
+                log.push({ collection: slug, op: "updateMany", ids: updates.map(u => u.id) });
+                return updates.map(({ id, data }) => {
+                    const existing = table(slug).get(String(id));
+                    if (!existing) throw new RebaseApiError("Not found", { status: 404 });
+                    const row = { ...existing, ...data };
+                    table(slug).set(String(id), row);
+                    return row;
+                });
+            },
             async delete(id: string | number) {
                 assertOnline();
                 log.push({ collection: slug, op: "delete", id });
                 table(slug).delete(String(id));
             },
+            async deleteMany(ids: (string | number)[]) {
+                assertOnline();
+                log.push({ collection: slug, op: "deleteMany", ids });
+                for (const id of ids) {
+                    if (!table(slug).has(String(id))) throw new RebaseApiError("Not found", { status: 404 });
+                }
+                for (const id of ids) table(slug).delete(String(id));
+            },
             async count(_params?: FindParams) {
                 assertOnline();
                 return table(slug).size;
@@ -503,6 +522,100 @@ describe("OfflineManager", () => {
         });
     });
 
+    describe("updateMany / deleteMany", () => {
+        it("queues a bulk update offline, overlays it, and replays it once", async () => {
+            const server = createFakeServer();
+            const { manager, wrap } = createManager(server);
+            const posts = wrap("posts");
+            await posts.create({ title: "a" });
+            await posts.create({ title: "b" });
+            const seeded = (await posts.find()).data;
+
+            server.state.online = false;
+            const updated = await posts.updateMany(
+                seeded.map((r) => ({ id: r.id as string, data: { title: `${r.title}!` } }))
+            );
+            expect(updated.map((r) => r.title)).toEqual(["a!", "b!"]);
+
+            // The overlay is what a UI renders while the write is queued.
+            const overlaid = await posts.find();
+            expect(overlaid.data.map((r) => r.title).sort()).toEqual(["a!", "b!"]);
+
+            server.state.online = true;
+            await manager.sync();
+            const bulk = server.log.filter((e) => e.op === "updateMany");
+            expect(bulk).toHaveLength(1);
+            expect([...server.table("posts").values()].map((r) => r.title).sort()).toEqual(["a!", "b!"]);
+        });
+
+        it("queues a bulk delete offline, hides the rows, and replays it once", async () => {
+            const server = createFakeServer();
+            const { manager, wrap } = createManager(server);
+            const posts = wrap("posts");
+            await posts.create({ title: "a" });
+            await posts.create({ title: "b" });
+            await posts.create({ title: "c" });
+            const seeded = (await posts.find()).data;
+
+            server.state.online = false;
+            await posts.deleteMany(seeded.slice(0, 2).map((r) => r.id as string));
+
+            const overlaid = await posts.find();
+            expect(overlaid.data.map((r) => r.title)).toEqual(["c"]);
+
+            server.state.online = true;
+            await manager.sync();
+            const bulk = server.log.filter((e) => e.op === "deleteMany");
+            expect(bulk).toHaveLength(1);
+            expect([...server.table("posts").values()].map((r) => r.title)).toEqual(["c"]);
+        });
+
+        it("queues a bulk update whose rows have writes still pending", async () => {
+            // Splitting the batch — some rows now, some later — would break the
+            // one guarantee a batch makes, and would reorder a write against a
+            // row whose own create has not landed yet.
+            const server = createFakeServer();
+            const { manager, wrap } = createManager(server);
+            const posts = wrap("posts");
+            await posts.find();
+
+            server.state.online = false;
+            const created = await posts.create({ title: "fresh" });
+            await posts.updateMany([{ id: created.id as string, data: { title: "edited" } }]);
+
+            server.state.online = true;
+            await manager.sync();
+
+            // The create ran first, then the batch — order preserved.
+            expect(server.log.map((e) => e.op)).toEqual(["create", "updateMany"]);
+            expect([...server.table("posts").values()][0].title).toBe("edited");
+        });
+
+        it("goes straight to the server when online", async () => {
+            const server = createFakeServer();
+            const { wrap } = createManager(server);
+            const posts = wrap("posts");
+            const a = await posts.create({ title: "a" });
+
+            await posts.updateMany([{ id: a.id as string, data: { title: "A" } }]);
+            expect(server.table("posts").get(String(a.id))!.title).toBe("A");
+
+            await posts.deleteMany([a.id as string]);
+            expect(server.table("posts").size).toBe(0);
+        });
+
+        it("treats empty input as a no-op that touches neither queue nor server", async () => {
+            const server = createFakeServer();
+            const { wrap } = createManager(server);
+            const posts = wrap("posts");
+            await posts.find();
+
+            expect(await posts.updateMany([])).toEqual([]);
+            await posts.deleteMany([]);
+            expect(server.log.filter((e) => e.op.endsWith("Many"))).toHaveLength(0);
+        });
+    });
+
     describe("concurrency", () => {
         it("gives concurrent offline writes distinct, ordered mutation ids", async () => {
             const server = createFakeServer();

package/src/offline.ts

@@ -1,5 +1,5 @@
 import { buildQueryString, FindParams, RebaseApiError } from "./transport";
-import { FindAllParams, FindResult, IterateParams, LogicalCondition, SDKCollectionClient, WhereFilterOp, WhereValue } from "@rebasepro/types";
+import { FindAllParams, FindResult, IterateParams, LogicalCondition, SDKCollectionClient, WhereFilterOp, WhereValue, WriteOptions } from "@rebasepro/types";
 import { collectAllPages, paginateFind } from "@rebasepro/common";
 import { CollectionClient, LiveResult, ObserveOptions, RowSnapshotMeta } from "./collection";
 import { SDKQueryBuilder } from "./sdk_query_builder";
@@ -15,6 +15,7 @@ import {
 import {
     isExactlyEvaluable,
     matchesParams,
+    resolvePagination,
     runLocalQuery,
     sortRows
 } from "./offline-query";
@@ -545,6 +546,83 @@ export class OfflineManager {
                 return rows;
             },
 
+            updateMany: async (updates: { id: string | number; data: Partial<M> }[], options?: WriteOptions) => {
+                await this.ensureCollection(slug);
+                if (!Array.isArray(updates)) {
+                    throw new TypeError("updateMany expects an array of { id, data } entries.");
+                }
+                if (updates.length === 0) return [];
+                // Any row in the batch with a write already queued sends the
+                // whole batch to the queue. Splitting it — some rows now, some
+                // later — would break the one guarantee a batch makes, that its
+                // rows land together, and would reorder writes against a row
+                // whose own create has not landed yet.
+                const anyPending = updates.some((u) => this.hasPending(slug, u.id));
+                if (this.connectivity.shouldAttempt() && !anyPending) {
+                    try {
+                        const rows = await inner.updateMany(updates, options);
+                        this.connectivity.markSuccess();
+                        await this.ingest(slug, rows);
+                        this.notifyCollection(slug);
+                        return rows;
+                    } catch (error) {
+                        if (!isNetworkError(error)) throw error;
+                        this.connectivity.markFailure();
+                    }
+                }
+                const rollback: Record<string, AnyRow | null> = {};
+                const optimistic: M[] = [];
+                for (const { id, data } of updates) {
+                    const base = this.rawLocalRow(slug, id);
+                    rollback[String(id)] = base ?? null;
+                    optimistic.push({ ...(base ?? {}), ...(data as AnyRow), id } as unknown as M);
+                }
+                await this.enqueue({
+                    collection: slug,
+                    type: "updateMany",
+                    updates: updates.map((u) => ({ id: u.id,
+data: u.data as AnyRow })),
+                    rollback: { rows: rollback }
+                });
+                for (const row of optimistic) this.setLocalRow(slug, row.id as string | number, row);
+                this.notifyCollection(slug);
+                return optimistic;
+            },
+
+            deleteMany: async (ids: (string | number)[], options?: WriteOptions) => {
+                await this.ensureCollection(slug);
+                if (!Array.isArray(ids)) {
+                    throw new TypeError("deleteMany expects an array of ids.");
+                }
+                if (ids.length === 0) return;
+                const anyPending = ids.some((id) => this.hasPending(slug, id));
+                if (this.connectivity.shouldAttempt() && !anyPending) {
+                    try {
+                        await inner.deleteMany(ids, options);
+                        this.connectivity.markSuccess();
+                        for (const id of ids) this.removeLocalRow(slug, id, true);
+                        this.notifyCollection(slug);
+                        this.scheduleRefresh(slug);
+                        return;
+                    } catch (error) {
+                        if (!isNetworkError(error)) throw error;
+                        this.connectivity.markFailure();
+                    }
+                }
+                const rollback: Record<string, AnyRow | null> = {};
+                for (const id of ids) {
+                    rollback[String(id)] = this.rawLocalRow(slug, id) ?? null;
+                }
+                await this.enqueue({
+                    collection: slug,
+                    type: "deleteMany",
+                    ids,
+                    rollback: { rows: rollback }
+                });
+                for (const id of ids) this.removeLocalRow(slug, id, false);
+                this.notifyCollection(slug);
+            },
+
             update: async (id: string | number, data: Partial<M>) => {
                 await this.ensureCollection(slug);
                 // Never overtake a write already queued for this row. The
@@ -657,7 +735,8 @@ export class OfflineManager {
             orderBy: (column, direction) => new SDKQueryBuilder<M>(wrapped).orderBy(column, direction),
             limit: (count) => new SDKQueryBuilder<M>(wrapped).limit(count),
             offset: (count) => new SDKQueryBuilder<M>(wrapped).offset(count),
-            search: (searchString) => new SDKQueryBuilder<M>(wrapped).search(searchString),
+            search: (searchString, options) => new SDKQueryBuilder<M>(wrapped).search(searchString, options),
+            vectorSearch: (property, vector, options) => new SDKQueryBuilder<M>(wrapped).vectorSearch(property, vector, options),
             include: (...relations) => new SDKQueryBuilder<M>(wrapped).include(...relations)
         };
 
@@ -942,7 +1021,7 @@ export class OfflineManager {
         if (!state) {
             return {
                 data: [],
-                meta: { total: 0, limit: params?.limit ?? 20, offset: params?.offset ?? 0, hasMore: false },
+                meta: { ...resolvePagination(params), total: 0, hasMore: false },
                 fromCache: true,
                 hasPendingWrites: false,
                 partial: true
@@ -996,9 +1075,18 @@ export class OfflineManager {
                 rows.push(entry.row as M);
                 added++;
             }
-            if (added > 0 && params?.orderBy) sortRows(rows, params.orderBy);
         }
 
+        // Order is part of the query, not a detail of how the rows were
+        // obtained. This used to sort only when a locally-created row had been
+        // injected — every other read handed back cache order, which is
+        // insertion order, and a caller that asked for `orderBy` got whatever
+        // the store happened to hold. In the admin that is the collection's
+        // `sort` being silently ignored on every list backed by this overlay:
+        // the query carries it, the server honours it, and the answer served
+        // from here did not.
+        if (params?.orderBy) sortRows(rows, params.orderBy);
+
         const total = Math.max(rows.length, snapshot.total - removed + added);
         return {
             data: rows,
@@ -1150,12 +1238,13 @@ export class OfflineManager {
     }
 
     private recordSnapshot(slug: string, params: FindParams | undefined, result: FindResult<AnyRow>): QuerySnapshot {
-        const meta = result.meta ?? { total: result.data?.length ?? 0, limit: 20, offset: 0, hasMore: false };
+        const window = resolvePagination(params);
+        const meta = result.meta ?? { total: result.data?.length ?? 0, ...window, hasMore: false };
         const snapshot: QuerySnapshot = {
             ids: (result.data ?? []).map((row) => row.id as string | number).filter((id) => id !== undefined),
             total: meta.total ?? result.data?.length ?? 0,
-            limit: meta.limit ?? params?.limit ?? 20,
-            offset: meta.offset ?? params?.offset ?? 0,
+            limit: meta.limit ?? window.limit,
+            offset: meta.offset ?? window.offset,
             hasMore: meta.hasMore ?? false
         };
         const state = this.collectionState(slug);
@@ -1466,13 +1555,39 @@ export class OfflineManager {
             await this.adoptServerRow(op, op.id, row);
         } else if (op.type === "createMany") {
             const queued = (op.data as AnyRow[]) ?? [];
-            const rows = await inner.createMany(queued, op.upsert ? { upsert: true } : undefined);
+            // The mutation id names this batch, exactly as it names a single
+            // `create` above — and it matters more here. Without it, a batch
+            // whose ACK went missing replays as a second genuine import and
+            // duplicates every row it holds, not one. `upsert` masked that for
+            // the callers who set it; nothing covered the ones who did not.
+            const rows = await inner.createMany(queued, {
+                ...(op.upsert ? { upsert: true } : {}),
+                idempotencyKey: op.mutationId
+            });
             for (let i = 0; i < rows.length; i++) {
                 await this.adoptServerRow(op, queued[i]?.id as string | number | undefined, rows[i]);
             }
+        } else if (op.type === "updateMany") {
+            const queued = op.updates ?? [];
+            // Keyed like every other replay: an update re-applied in full is
+            // naturally idempotent, but one interleaved with another writer's is
+            // not, and a lost ACK would otherwise re-apply a stale batch over
+            // newer data.
+            const rows = await inner.updateMany(
+                queued.map(u => ({ id: u.id,
+data: u.data as AnyRow })),
+                { idempotencyKey: op.mutationId }
+            );
+            for (let i = 0; i < rows.length; i++) {
+                await this.ingestReplaced(op, queued[i].id, rows[i]);
+            }
         } else if (op.type === "update") {
             const row = await inner.update(op.id!, op.data as AnyRow);
             await this.ingestReplaced(op, op.id!, row);
+        } else if (op.type === "deleteMany") {
+            const ids = op.ids ?? [];
+            await inner.deleteMany(ids, { idempotencyKey: op.mutationId });
+            for (const id of ids) this.removeLocalRow(op.collection, id, true);
         } else if (op.type === "delete") {
             await inner.delete(op.id!);
             this.removeLocalRow(op.collection, op.id!, true);

package/src/query-contract.types.ts

@@ -0,0 +1,114 @@
+/**
+ * Compile-time assertions about the query surface.
+ *
+ * ## Read this before adding a `.test.ts` for a type
+ *
+ * These assertions are **not** in a test file, on purpose. In this repo a jest
+ * test cannot check a type at all:
+ *
+ * - `ts-jest` is configured transpile-only. Verified: a test containing
+ *   `const n: number = "nope"` passes. `@ts-expect-error` in a `.test.ts` is
+ *   therefore inert — it asserts nothing and never fails.
+ * - `tsconfig.typecheck.json` — the gate CI runs as `pnpm run typecheck` —
+ *   covers every package's `src` directory but **excludes every `*.test.ts`**.
+ *
+ * So a type assertion written as a test is checked by nothing, twice over. This
+ * file is a plain module under `src`, which is exactly what the gate does read.
+ * It is imported by nothing and emits no runtime code.
+ *
+ * ## What went wrong that this exists to prevent
+ *
+ * `_score` was accepted by the runtime, documented in the SDK docs and skills,
+ * and rejected by `orderBy`'s type, which was `keyof M`. On a project with a
+ * generated SDK — where `M` is a concrete row type — the documented call was a
+ * compile error. Nothing in this repo noticed; a downstream application did.
+ */
+import type { FindParams, FindResult, SDKQueryBuilderInterface } from "@rebasepro/types";
+
+/**
+ * A row shaped the way a **generated** SDK shapes one: a type alias with a
+ * finite key set.
+ *
+ * This detail is the whole test. An `interface … extends Record<string,
+ * unknown>` also satisfies the constraint, but its index signature makes
+ * `keyof M` collapse to `string` — so every assertion below would pass no
+ * matter what `orderBy` accepted, typos included. That is how the first draft
+ * of this file was written, and every `@ts-expect-error` in it reported
+ * "unused directive": the fixture proved nothing.
+ *
+ * A generated row type has no index signature, which is exactly why a real
+ * project caught what this repo did not.
+ */
+type ContractRow = {
+    id: string;
+    title: string;
+    created_at: string;
+};
+
+// ── orderBy accepts relevance, and still rejects nonsense ───────────────────
+
+/** The documented relevance sort must compile. */
+export const orderByScore: FindParams<ContractRow> = {
+    searchString: "auditor",
+    orderBy: ["_score", "desc"]
+};
+
+/** An ordinary column must keep compiling. */
+export const orderByColumn: FindParams<ContractRow> = { orderBy: ["created_at", "desc"] };
+
+/**
+ * A column that does not exist must still be refused. Widening `orderBy` to
+ * `string` would have fixed the `_score` error and silently given up this,
+ * turning every typo into an unsorted 200 in production.
+ */
+// @ts-expect-error - "nope" is neither a column of ContractRow nor computed
+export const orderByTypo: FindParams<ContractRow> = { orderBy: ["nope", "desc"] };
+
+// ── the fluent builder agrees with FindParams ──────────────────────────────
+
+export const fluentScore = (qb: SDKQueryBuilderInterface<ContractRow>) =>
+    qb.search("auditor").orderBy("_score", "desc");
+
+export const fluentColumn = (qb: SDKQueryBuilderInterface<ContractRow>) =>
+    qb.orderBy("created_at", "asc");
+
+export const fluentTypo = (qb: SDKQueryBuilderInterface<ContractRow>) =>
+    // @ts-expect-error - the fluent signature must reject what FindParams rejects
+    qb.orderBy("_scoer", "desc");
+
+/** Vector search must be reachable from the builder, and chain. */
+export const fluentVector = (qb: SDKQueryBuilderInterface<ContractRow>) =>
+    qb.vectorSearch("embedding", [0.1, 0.2], { threshold: 0.3 }).limit(10);
+
+// ── what a query computes is readable off the row ──────────────────────────
+
+/**
+ * Sorting by relevance and then being unable to read it was the other half of
+ * the same bug — the e2e cast around it, which should have been the tell.
+ */
+export const readComputed = (result: FindResult<ContractRow>) => {
+    const row = result.data[0];
+    const score: number | undefined = row._score;
+    const distance: number | undefined = row._distance;
+    const title: string = row.title;
+    return { score, distance, title };
+};
+
+/** Widening the row must not have turned it into `any`. */
+export const readUnknown = (result: FindResult<ContractRow>) =>
+    // @ts-expect-error - `nope` is neither a column nor computed
+    result.data[0].nope;
+
+/**
+ * A result row must stay assignable to `Record<string, unknown>`.
+ *
+ * Widening the row to `M & QueryComputedFields` broke this in seven places in
+ * one downstream app, because `QueryComputedFields` was first written as an
+ * `interface`: TypeScript grants an implicit index signature to a type alias
+ * and withholds it from an interface, so the intersection stopped overlapping
+ * with `Record<string, unknown>` and every `as Record<string, unknown>` cast
+ * became an error. Nothing in this repo casts a row that way, which is why
+ * nothing here noticed.
+ */
+export const rowStaysIndexable = (result: FindResult<ContractRow>) =>
+    result.data.map(row => row as Record<string, unknown>);