@rebasepro/common 0.23.0 → 0.24.1-canary.g56af4a4

package/dist/data/paginate.es.js

@@ -0,0 +1,181 @@
+import { normalizeOrderBy } from "./sort-dialect.es.js";
+import { DEFAULT_LIST_LIMIT, RebaseClientError } from "@rebasepro/types";
+//#region src/data/paginate.ts
+/**
+* The pagination engine behind `iterate()` / `findAll()`.
+*
+* It lives here, above both transports, on purpose: the HTTP client and the
+* in-process accessor implement the same `SDKCollectionClient` contract, and a
+* helper written twice is a helper that drifts. Both call into this file, so
+* "the SDK paginates like *this*" has exactly one definition.
+*
+* Everything below is expressed in terms of a single `find(params)` function,
+* which is all either transport has to supply.
+*/
+/** Rows requested per page when the caller does not say. */
+var DEFAULT_PAGE_SIZE = 200;
+/** Rows `findAll()` will materialise before it refuses to continue. */
+var DEFAULT_FIND_ALL_MAX_ROWS = 1e4;
+/**
+* Requests one walk may make before it gives up on the server ever saying
+* `hasMore: false`. At the default page size that is two million rows — far
+* past any legitimate walk, and short of running forever.
+*/
+var DEFAULT_MAX_PAGES = 1e4;
+/**
+* Thrown when a walk stops for a reason the caller needs to know about.
+*
+* Every one of these is a case where the alternative would be silent: a
+* truncated array that looks complete, or a loop that never returns. Check
+* {@link code} to tell them apart.
+*/
+var RebasePaginationError = class RebasePaginationError extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.name = "RebasePaginationError";
+		this.code = code;
+		Object.setPrototypeOf(this, RebasePaginationError.prototype);
+	}
+};
+/**
+* What a read naming both `page` and `offset` is refused with — by the server
+* (400 `PAGE_WITH_OFFSET`) and, before any request, by every client.
+*/
+var PAGE_WITH_OFFSET_MESSAGE = "`page` and `offset` describe the same window; send one.";
+/**
+* Resolve `limit`/`offset`/`page` into the window a read will actually use.
+*
+* Lives here, next to the walk, for the reason at the top of this file: every
+* transport has to mean the same thing by "page two". Four of them did not —
+* the REST layer strode by {@link DEFAULT_LIST_LIMIT}, the local-first
+* evaluator by {@link DEFAULT_PAGE_SIZE}, the in-process accessor by 20, and
+* the published type documented a fourth number. Pages that overlap or skip
+* rows are the mildest of those outcomes.
+*
+* `page` and `offset` together are refused with `PAGE_WITH_OFFSET`, as the
+* server refuses them: they name one window twice, and `page` used to win
+* silently over an `offset` the caller then never saw applied. `driverOffset`
+* is the value to hand a driver: it stays `undefined` when the caller named no
+* offset, because keyset pagination seeks with a `where` clause and must not
+* look like it is paging by offset.
+*/
+function resolveFindWindow(params) {
+	if (params?.page != null && params.offset != null) throw new RebaseClientError(PAGE_WITH_OFFSET_MESSAGE, { code: "PAGE_WITH_OFFSET" });
+	const limit = params?.limit ?? DEFAULT_LIST_LIMIT;
+	const offset = params?.page != null ? Math.max(0, (params.page - 1) * limit) : params?.offset ?? 0;
+	return {
+		limit,
+		offset,
+		driverOffset: params?.page != null ? offset : params?.offset
+	};
+}
+function normalizePageSize(raw) {
+	if (raw === void 0 || !Number.isFinite(raw)) return DEFAULT_PAGE_SIZE;
+	return Math.max(1, Math.floor(raw));
+}
+function normalizeMaxPages(raw) {
+	if (raw === void 0) return DEFAULT_MAX_PAGES;
+	if (raw === Number.POSITIVE_INFINITY) return raw;
+	if (!Number.isFinite(raw)) return DEFAULT_MAX_PAGES;
+	return Math.max(1, Math.floor(raw));
+}
+function normalizeMaxRows(raw) {
+	if (raw === void 0) return DEFAULT_FIND_ALL_MAX_ROWS;
+	if (raw === Number.POSITIVE_INFINITY) return raw;
+	if (!Number.isFinite(raw)) return DEFAULT_FIND_ALL_MAX_ROWS;
+	return Math.max(0, Math.floor(raw));
+}
+/**
+* Walk every row a query matches, yielding one row at a time and fetching the
+* next page only when the consumer asks for it.
+*
+* See {@link SDKCollectionClient.iterate} for the caller-facing contract,
+* including the offset-drift caveat and the `cursor` alternative.
+*
+* @param find   the transport's single-page read
+* @param params `find()` parameters minus the window, plus the walk options
+* @param label  the collection name, so an error says which walk failed
+*/
+async function* paginateFind(find, params, label = "collection") {
+	const { pageSize, cursor, maxPages, after: startAfter, offset: startOffset, page: startPage, ...rest } = params ?? {};
+	const findParams = {
+		...rest,
+		count: "none"
+	};
+	const size = normalizePageSize(pageSize);
+	const pageCap = normalizeMaxPages(maxPages);
+	const seekRequested = cursor !== void 0 && cursor !== null || !!startAfter;
+	if (cursor !== void 0 && cursor !== null) {
+		const field = typeof cursor === "string" ? cursor : cursor.field;
+		const requested = typeof cursor === "object" && cursor !== null ? cursor.direction : void 0;
+		if (!normalizeOrderBy(findParams.orderBy)) findParams.orderBy = [field, requested ?? "asc"];
+	}
+	let offset = resolveFindWindow({
+		limit: size,
+		offset: startOffset,
+		page: startPage
+	}).offset;
+	let pages = 0;
+	let after = startAfter || void 0;
+	let seekingByServerCursor = false;
+	for (;;) {
+		if (pages >= pageCap) throw new RebasePaginationError("max-pages", `Iterating "${label}" made ${pages} requests without the server reporting the end of the collection. Stopping rather than looping forever — raise \`maxPages\` if the walk is genuinely this long, or check that the backend sets \`meta.hasMore\`.`);
+		const pageParams = {
+			...findParams,
+			limit: size
+		};
+		if (seekRequested) {
+			if (after) pageParams.after = after;
+		} else if (seekingByServerCursor && after) pageParams.after = after;
+		else pageParams.offset = offset;
+		const page = await find(pageParams);
+		pages += 1;
+		const rows = page?.data ?? [];
+		if (rows.length === 0) return;
+		for (const row of rows) yield row;
+		if (page?.meta?.hasMore !== true) return;
+		if (seekRequested) {
+			const next = page.meta.nextCursor;
+			if (!next) throw new RebasePaginationError("cursor-missing", `Cannot seek past the last row of "${label}": the server reported another page but issued no cursor for it. An ordering with no stored value to compare against — relevance (\`_score\`) — cannot key a cursor. Drop \`cursor\` to page by offset.`);
+			if (next === after) throw new RebasePaginationError("cursor-stalled", `Iterating "${label}" is stuck: two pages in a row ended on the same cursor, so the walk cannot advance. Continuing would loop forever. Page by offset instead, or report this — a cursor that does not move is a server-side bug.`);
+			after = next;
+		} else {
+			offset += rows.length;
+			const next = page.meta.nextCursor;
+			seekingByServerCursor = !!next && next !== after;
+			after = seekingByServerCursor ? next : void 0;
+		}
+	}
+}
+/**
+* {@link paginateFind}, collected into an array under a ceiling.
+*
+* See {@link SDKCollectionClient.findAll}.
+*/
+async function collectAllPages(find, params, label = "collection") {
+	const { maxRows, ...rest } = params ?? {};
+	const cap = normalizeMaxRows(maxRows);
+	const out = [];
+	for await (const row of paginateFind(find, rest, label)) {
+		out.push(row);
+		if (out.length > cap) throw new RebasePaginationError("max-rows", `findAll("${label}") matched more than ${cap} rows. Returning the first ${cap} would look like the whole answer and quietly not be one, so this throws instead. Raise \`maxRows\` if you meant to load them all, or stream with \`iterate()\`.`);
+	}
+	return out;
+}
+/**
+* Build the `iterate` / `findAll` pair for one collection from its `find`.
+*
+* Both transports call this, which is what keeps the two implementations from
+* being two implementations.
+*/
+function createPaginationHelpers(find, label) {
+	return {
+		iterate: (params) => paginateFind(find, params, label),
+		findAll: (params) => collectAllPages(find, params, label)
+	};
+}
+//#endregion
+export { DEFAULT_FIND_ALL_MAX_ROWS, DEFAULT_MAX_PAGES, DEFAULT_PAGE_SIZE, PAGE_WITH_OFFSET_MESSAGE, RebasePaginationError, collectAllPages, createPaginationHelpers, paginateFind, resolveFindWindow };
+
+//# sourceMappingURL=paginate.es.js.map

package/dist/data/paginate.es.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paginate.es.js","names":[],"sources":["../../src/data/paginate.ts"],"sourcesContent":["import {\n    DEFAULT_LIST_LIMIT,\n    FindAllParams,\n    FindParams,\n    FindResult,\n    IterateParams,\n    RebaseClientError\n} from \"@rebasepro/types\";\nimport { normalizeOrderBy } from \"./sort-dialect\";\n\n/**\n * The pagination engine behind `iterate()` / `findAll()`.\n *\n * It lives here, above both transports, on purpose: the HTTP client and the\n * in-process accessor implement the same `SDKCollectionClient` contract, and a\n * helper written twice is a helper that drifts. Both call into this file, so\n * \"the SDK paginates like *this*\" has exactly one definition.\n *\n * Everything below is expressed in terms of a single `find(params)` function,\n * which is all either transport has to supply.\n */\n\n/** Rows requested per page when the caller does not say. */\nexport const DEFAULT_PAGE_SIZE = 200;\n\n/** Rows `findAll()` will materialise before it refuses to continue. */\nexport const DEFAULT_FIND_ALL_MAX_ROWS = 10_000;\n\n/**\n * Requests one walk may make before it gives up on the server ever saying\n * `hasMore: false`. At the default page size that is two million rows — far\n * past any legitimate walk, and short of running forever.\n */\nexport const DEFAULT_MAX_PAGES = 10_000;\n\n/** Why a pagination walk refused to continue. */\nexport type PaginationErrorCode =\n    /** `findAll()` matched more rows than its ceiling allows. */\n    | \"max-rows\"\n    /** The walk made its maximum number of requests without the server finishing. */\n    | \"max-pages\"\n    /**\n     * The server said there was another page but issued no cursor to reach it.\n     *\n     * A query whose ordering has no stored value to seek on — relevance — is the\n     * case that produces this. Page it by offset instead.\n     */\n    | \"cursor-missing\"\n    /** Two consecutive pages returned the same cursor, so the walk cannot advance. */\n    | \"cursor-stalled\";\n\n/**\n * Thrown when a walk stops for a reason the caller needs to know about.\n *\n * Every one of these is a case where the alternative would be silent: a\n * truncated array that looks complete, or a loop that never returns. Check\n * {@link code} to tell them apart.\n */\nexport class RebasePaginationError extends Error {\n    readonly code: PaginationErrorCode;\n\n    constructor(code: PaginationErrorCode, message: string) {\n        super(message);\n        this.name = \"RebasePaginationError\";\n        this.code = code;\n        // Keeps `instanceof` working when this is compiled down for an older\n        // target, where extending a builtin otherwise loses the prototype.\n        Object.setPrototypeOf(this, RebasePaginationError.prototype);\n    }\n}\n\n/**\n * What a read naming both `page` and `offset` is refused with — by the server\n * (400 `PAGE_WITH_OFFSET`) and, before any request, by every client.\n */\nexport const PAGE_WITH_OFFSET_MESSAGE = \"`page` and `offset` describe the same window; send one.\";\n\n/** The one thing a transport has to provide to be paginated. */\nexport type PageFinder<M extends Record<string, unknown> = Record<string, unknown>> =\n    (params: FindParams<M>) => Promise<FindResult<M>>;\n\n/**\n * Resolve `limit`/`offset`/`page` into the window a read will actually use.\n *\n * Lives here, next to the walk, for the reason at the top of this file: every\n * transport has to mean the same thing by \"page two\". Four of them did not —\n * the REST layer strode by {@link DEFAULT_LIST_LIMIT}, the local-first\n * evaluator by {@link DEFAULT_PAGE_SIZE}, the in-process accessor by 20, and\n * the published type documented a fourth number. Pages that overlap or skip\n * rows are the mildest of those outcomes.\n *\n * `page` and `offset` together are refused with `PAGE_WITH_OFFSET`, as the\n * server refuses them: they name one window twice, and `page` used to win\n * silently over an `offset` the caller then never saw applied. `driverOffset`\n * is the value to hand a driver: it stays `undefined` when the caller named no\n * offset, because keyset pagination seeks with a `where` clause and must not\n * look like it is paging by offset.\n */\nexport function resolveFindWindow(\n    params?: Pick<FindParams, \"limit\" | \"offset\" | \"page\">\n): { limit: number; offset: number; driverOffset: number | undefined } {\n    if (params?.page != null && params.offset != null) {\n        throw new RebaseClientError(PAGE_WITH_OFFSET_MESSAGE, { code: \"PAGE_WITH_OFFSET\" });\n    }\n    const limit = params?.limit ?? DEFAULT_LIST_LIMIT;\n    const offset = params?.page != null\n        ? Math.max(0, (params.page - 1) * limit)\n        : (params?.offset ?? 0);\n    return {\n        limit,\n        offset,\n        driverOffset: params?.page != null ? offset : params?.offset\n    };\n}\n\nfunction normalizePageSize(raw: number | undefined): number {\n    if (raw === undefined || !Number.isFinite(raw)) return DEFAULT_PAGE_SIZE;\n    return Math.max(1, Math.floor(raw));\n}\n\nfunction normalizeMaxPages(raw: number | undefined): number {\n    if (raw === undefined) return DEFAULT_MAX_PAGES;\n    if (raw === Number.POSITIVE_INFINITY) return raw;\n    if (!Number.isFinite(raw)) return DEFAULT_MAX_PAGES;\n    return Math.max(1, Math.floor(raw));\n}\n\nfunction normalizeMaxRows(raw: number | undefined): number {\n    if (raw === undefined) return DEFAULT_FIND_ALL_MAX_ROWS;\n    if (raw === Number.POSITIVE_INFINITY) return raw;\n    if (!Number.isFinite(raw)) return DEFAULT_FIND_ALL_MAX_ROWS;\n    return Math.max(0, Math.floor(raw));\n}\n\n/**\n * Walk every row a query matches, yielding one row at a time and fetching the\n * next page only when the consumer asks for it.\n *\n * See {@link SDKCollectionClient.iterate} for the caller-facing contract,\n * including the offset-drift caveat and the `cursor` alternative.\n *\n * @param find   the transport's single-page read\n * @param params `find()` parameters minus the window, plus the walk options\n * @param label  the collection name, so an error says which walk failed\n */\nexport async function* paginateFind<M extends Record<string, unknown> = Record<string, unknown>>(\n    find: PageFinder<M>,\n    params?: IterateParams<M>,\n    label = \"collection\"\n): AsyncGenerator<M, void, undefined> {\n    const {\n        pageSize,\n        cursor,\n        maxPages,\n        // The window is the walk's, but where it starts is the caller's. Left\n        // in `rest`, these rode along on every page beside the walk's own: a\n        // caller's `after` went out next to `offset=0`, which the server\n        // refuses outright (CURSOR_WITH_OFFSET), and a caller's `offset` was\n        // overwritten by that `0`, so the walk silently started over from the\n        // top. `IterateParams` omits `offset` and `page`, but the query builder\n        // hands its whole state to `iterate()`, `.offset(40)` included.\n        after: startAfter,\n        offset: startOffset,\n        page: startPage,\n        ...rest\n    } = (params ?? {}) as IterateParams<M> & Pick<FindParams<M>, \"offset\" | \"page\">;\n\n    // No page of a walk is counted. Nothing it returns carries a total —\n    // `iterate()` yields rows, `findAll()` an array — and `hasMore`, the one\n    // thing it reads off `meta`, does not need one: without a count the read\n    // asks for one row past the page. The count is most of what a list read\n    // costs on a large table (1.8 s of a 100k-row walk's SQL, 26 ms without).\n    // A caller's own `count` is overridden for the same reason.\n    const findParams = { ...rest, count: \"none\" } as FindParams<M>;\n    const size = normalizePageSize(pageSize);\n    const pageCap = normalizeMaxPages(maxPages);\n\n    // ── Cursor (keyset) setup ────────────────────────────────────────────────\n    //\n    // The walk no longer builds a keyset of its own. It used to: a `>`/`<` on\n    // one column, expressed as an extra `where`, which threw on any multi-key\n    // sort (\"keyset pagination advances along a single column\") and dropped\n    // every row whose sort value was NULL, because `> value` answers *unknown*\n    // against NULL. The driver has had a NULL-correct multi-key comparison all\n    // along and nothing over HTTP could reach it.\n    //\n    // So this is now a *request* for seeking, not an implementation of it: the\n    // server issues `meta.nextCursor` and the walk hands it back as `after`.\n    // Multi-key sorts and nullable keys work because the comparison is the\n    // driver's, and there is one of it.\n    //\n    // A caller's own `after` is a request for seeking too: it is a cursor\n    // issued for this query's sort, so the walk continues from it by the same\n    // handoff.\n    const seekRequested = (cursor !== undefined && cursor !== null) || !!startAfter;\n    if (cursor !== undefined && cursor !== null) {\n        // A named column still means \"sort by this and seek along it\", which is\n        // what every existing caller wrote. It is an `orderBy` now rather than\n        // a second pagination mode — the seeking itself needs no column named,\n        // since the cursor carries whatever keys the sort used.\n        const field = typeof cursor === \"string\" ? cursor : cursor.field;\n        const requested = (typeof cursor === \"object\" && cursor !== null) ? cursor.direction : undefined;\n        const explicit = normalizeOrderBy(findParams.orderBy);\n        // An explicit `orderBy` wins and the named column is redundant, not\n        // wrong: seeking follows whatever the query is sorted by, so there is\n        // no longer a mismatch to refuse.\n        if (!explicit) {\n            findParams.orderBy = [field, requested ?? \"asc\"] as FindParams<M>[\"orderBy\"];\n        }\n    }\n\n    // `page` counts in pages of this walk's size, by the one rule every read\n    // resolves it with.\n    let offset = resolveFindWindow({ limit: size, offset: startOffset, page: startPage }).offset;\n    let pages = 0;\n    let after: string | undefined = startAfter || undefined;\n\n    // ── The default walk seeks too, whenever the server lets it ─────────────\n    //\n    // A walk nobody asked to seek still continues from `meta.nextCursor` when a\n    // page carries one. Advancing `offset` instead made every request skip\n    // `offset` rows in the database before reading the next page, so the walk\n    // cost grew with the square of the collection: 4.5 s of SQL for 100k rows\n    // where seeking is 1.8 s — and the order is the same, because the cursor\n    // is the server's, built over the very sort the offset pages used.\n    //\n    // Where no cursor comes — relevance, a vector search, a distinct read, a\n    // server that predates cursors — it pages by offset exactly as before, from\n    // the position it has reached (`offset` keeps counting rows either way).\n    // `after` and `offset` never go out together: the server refuses that\n    // (`CURSOR_WITH_OFFSET`). Only an explicit `cursor`/`after` walk treats a\n    // missing or stalled cursor as an error; this one never promised to seek.\n    let seekingByServerCursor = false;\n\n    for (;;) {\n        if (pages >= pageCap) {\n            throw new RebasePaginationError(\n                \"max-pages\",\n                `Iterating \"${label}\" made ${pages} requests without the server reporting the end of ` +\n                `the collection. Stopping rather than looping forever — raise \\`maxPages\\` if the walk ` +\n                `is genuinely this long, or check that the backend sets \\`meta.hasMore\\`.`\n            );\n        }\n\n        const pageParams: FindParams<M> = { ...findParams, limit: size };\n        if (seekRequested) {\n            if (after) pageParams.after = after;\n        } else if (seekingByServerCursor && after) {\n            pageParams.after = after;\n        } else {\n            pageParams.offset = offset;\n        }\n\n        const page = await find(pageParams);\n        pages += 1;\n\n        const rows = page?.data ?? [];\n        // A page with nothing on it always ends the walk, whatever the server\n        // claims about `hasMore` — there is no cursor to advance and no offset\n        // that would ever move past it.\n        if (rows.length === 0) return;\n\n        for (const row of rows) {\n            yield row;\n        }\n\n        // The server is the only authority on whether more rows exist. Never\n        // infer it from `rows.length >= size`: a last page that happens to be\n        // exactly full is indistinguishable from a middle one, and guessing\n        // there drops every row after it.\n        if (page?.meta?.hasMore !== true) return;\n\n        if (seekRequested) {\n            const next = page.meta.nextCursor;\n            if (!next) {\n                throw new RebasePaginationError(\n                    \"cursor-missing\",\n                    `Cannot seek past the last row of \"${label}\": the server reported another page but ` +\n                    `issued no cursor for it. An ordering with no stored value to compare against — ` +\n                    `relevance (\\`_score\\`) — cannot key a cursor. Drop \\`cursor\\` to page by offset.`\n                );\n            }\n            if (next === after) {\n                throw new RebasePaginationError(\n                    \"cursor-stalled\",\n                    `Iterating \"${label}\" is stuck: two pages in a row ended on the same cursor, so the ` +\n                    `walk cannot advance. Continuing would loop forever. Page by offset instead, or ` +\n                    `report this — a cursor that does not move is a server-side bug.`\n                );\n            }\n            after = next;\n        } else {\n            // Advance by what actually arrived, not by the page size: a server\n            // free to return fewer rows than asked for would otherwise leave a\n            // hole in the walk. Counted on seeked pages too, so a fallback to\n            // offset resumes exactly where the walk has got to.\n            offset += rows.length;\n            const next = page.meta.nextCursor;\n            // A cursor equal to the one just sent cannot advance the walk;\n            // offset still can.\n            seekingByServerCursor = !!next && next !== after;\n            after = seekingByServerCursor ? next : undefined;\n        }\n    }\n}\n\n/**\n * {@link paginateFind}, collected into an array under a ceiling.\n *\n * See {@link SDKCollectionClient.findAll}.\n */\nexport async function collectAllPages<M extends Record<string, unknown> = Record<string, unknown>>(\n    find: PageFinder<M>,\n    params?: FindAllParams<M>,\n    label = \"collection\"\n): Promise<M[]> {\n    const { maxRows, ...rest } = (params ?? {}) as FindAllParams<M> & Record<string, unknown>;\n    const cap = normalizeMaxRows(maxRows as number | undefined);\n\n    const out: M[] = [];\n    for await (const row of paginateFind<M>(find, rest as IterateParams<M>, label)) {\n        out.push(row);\n        if (out.length > cap) {\n            throw new RebasePaginationError(\n                \"max-rows\",\n                `findAll(\"${label}\") matched more than ${cap} rows. Returning the first ${cap} would ` +\n                `look like the whole answer and quietly not be one, so this throws instead. Raise ` +\n                `\\`maxRows\\` if you meant to load them all, or stream with \\`iterate()\\`.`\n            );\n        }\n    }\n    return out;\n}\n\n/**\n * Build the `iterate` / `findAll` pair for one collection from its `find`.\n *\n * Both transports call this, which is what keeps the two implementations from\n * being two implementations.\n */\nexport function createPaginationHelpers<M extends Record<string, unknown> = Record<string, unknown>>(\n    find: PageFinder<M>,\n    label: string\n): {\n    iterate: (params?: IterateParams<M>) => AsyncIterableIterator<M>;\n    findAll: (params?: FindAllParams<M>) => Promise<M[]>;\n} {\n    return {\n        iterate: (params?: IterateParams<M>) => paginateFind<M>(find, params, label),\n        findAll: (params?: FindAllParams<M>) => collectAllPages<M>(find, params, label)\n    };\n}\n"],"mappings":"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"}

package/dist/data/query_builder.d.ts

@@ -1,6 +1,34 @@
 import { CollectionAccessor, FilterCondition, FindResponse, LogicalCondition, QueryBuilderInterface, WhereFilterOp, WhereValueFor, type ComputedSortField } from "@rebasepro/types";
-export declare function or(...conditions: (FilterCondition | LogicalCondition)[]): LogicalCondition;
-export declare function and(...conditions: (FilterCondition | LogicalCondition)[]): LogicalCondition;
+/**
+ * Any condition a group may hold. The helpers below are generic over it so the
+ * group they return keeps each condition's column, operator and value exactly
+ * as written — which is what lets a typed `logical` / `.where(group)` check
+ * them against the row ({@link LogicalConditionFor}). Their results are still
+ * plain `LogicalCondition`s anywhere one is expected.
+ */
+type AnyCondition = FilterCondition | LogicalCondition;
+/** A value as `cond` keeps it: literals stay literals, so `"draft"` can match a `"draft" | "published"` column. */
+type ConditionValue = string | number | bigint | boolean | symbol | object | null | undefined;
+/** An empty group, to push conditions into later. */
+export declare function or(): {
+    type: "or";
+    conditions: AnyCondition[];
+};
+/** The group keeps the union of what was passed, so a mixed `or(cond(…), and(…))` keeps each one. */
+export declare function or<Cs extends AnyCondition[]>(...conditions: Cs): {
+    type: "or";
+    conditions: Cs[number][];
+};
+/** An empty group, to push conditions into later. */
+export declare function and(): {
+    type: "and";
+    conditions: AnyCondition[];
+};
+/** The group keeps the union of what was passed, so a mixed `or(cond(…), and(…))` keeps each one. */
+export declare function and<Cs extends AnyCondition[]>(...conditions: Cs): {
+    type: "and";
+    conditions: Cs[number][];
+};
 /**
  * Negate a group: `not(a)` is `NOT a`, and `not(a, b)` is `NOT (a AND b)`.
  *
@@ -15,8 +43,27 @@ export declare function and(...conditions: (FilterCondition | LogicalCondition)[
  * one of them is the query the caller wrote. It also means a negation includes
  * rows whose column is NULL — which is what `NOT` means.
  */
-export declare function not(...conditions: (FilterCondition | LogicalCondition)[]): LogicalCondition;
-export declare function cond(column: string, operator: WhereFilterOp, value: unknown): FilterCondition;
+export declare function not(): {
+    type: "not";
+    conditions: AnyCondition[];
+};
+export declare function not<Cs extends AnyCondition[]>(...conditions: Cs): {
+    type: "not";
+    conditions: Cs[number][];
+};
+/**
+ * One condition: `cond("age", ">=", 18)`.
+ *
+ * It returns the column, operator and value as written rather than a
+ * `FilterCondition`, so that where the group is used on a typed client the
+ * column and the value are checked against the row — a typo'd column or a
+ * string compared to a number column is a compile error there.
+ */
+export declare function cond<K extends string, Op extends WhereFilterOp, V extends ConditionValue>(column: K, operator: Op, value: V): {
+    column: K;
+    operator: Op;
+    value: V;
+};
 export declare class QueryBuilder<M extends Record<string, unknown> = Record<string, unknown>> implements QueryBuilderInterface<M> {
     private collection;
     private params;
@@ -86,3 +133,4 @@ export declare class QueryBuilder<M extends Record<string, unknown> = Record<str
      */
     listen(onUpdate: (data: FindResponse<M>) => void, onError?: (error: Error) => void): () => void;
 }
+export {};

package/dist/data/query_builder.es.js

@@ -0,0 +1,151 @@
+import { normalizeOrderBy } from "./sort-dialect.es.js";
+//#region src/data/query_builder.ts
+function or(...conditions) {
+	return {
+		type: "or",
+		conditions
+	};
+}
+function and(...conditions) {
+	return {
+		type: "and",
+		conditions
+	};
+}
+function not(...conditions) {
+	return {
+		type: "not",
+		conditions
+	};
+}
+/**
+* One condition: `cond("age", ">=", 18)`.
+*
+* It returns the column, operator and value as written rather than a
+* `FilterCondition`, so that where the group is used on a typed client the
+* column and the value are checked against the row — a typo'd column or a
+* string compared to a number column is a compile error there.
+*/
+function cond(column, operator, value) {
+	return {
+		column,
+		operator,
+		value
+	};
+}
+var QueryBuilder = class {
+	collection;
+	params = { where: {} };
+	constructor(collection) {
+		this.collection = collection;
+	}
+	where(columnOrCondition, operator, value) {
+		if (typeof columnOrCondition === "object" && columnOrCondition !== null && "type" in columnOrCondition) {
+			const next = columnOrCondition;
+			this.params.logical = this.params.logical ? {
+				type: "and",
+				conditions: [this.params.logical, next]
+			} : next;
+			return this;
+		}
+		if (!this.params.where) this.params.where = {};
+		const column = columnOrCondition;
+		const condition = [operator, value];
+		const existing = this.params.where[column];
+		if (existing === void 0) this.params.where[column] = condition;
+		else if (Array.isArray(existing) && existing.length > 0 && Array.isArray(existing[0])) this.params.where[column].push(condition);
+		else {
+			let firstCondition;
+			if (Array.isArray(existing) && existing.length === 2 && typeof existing[0] === "string") firstCondition = existing;
+			else firstCondition = ["==", existing];
+			this.params.where[column] = [firstCondition, condition];
+		}
+		return this;
+	}
+	/**
+	* Order the results by a specific column.
+	*
+	* Called again, this adds a tie-breaker rather than replacing the sort:
+	* keys apply in the order they were added.
+	*
+	* @example
+	* client.collection('users').orderBy('createdAt', 'desc').find()
+	* @example
+	* client.collection('users').orderBy('roles').orderBy('createdAt', 'desc').find()
+	*/
+	orderBy(column, direction = "asc") {
+		const existing = normalizeOrderBy(this.params.orderBy) ?? [];
+		this.params.orderBy = [...existing, [column, direction]];
+		return this;
+	}
+	/**
+	* Limit the number of results returned.
+	*/
+	limit(count) {
+		this.params.limit = count;
+		return this;
+	}
+	/**
+	* Skip the first N results.
+	*/
+	offset(count) {
+		this.params.offset = count;
+		return this;
+	}
+	/**
+	* Set a free-text search string if supported by the backend.
+	*/
+	search(searchString, options) {
+		this.params.searchString = searchString;
+		if (options?.explain !== void 0) this.params.searchExplain = options.explain;
+		return this;
+	}
+	/**
+	* Order rows by nearest-neighbour distance to `vector`, closest first.
+	*
+	* Postgres only, over a property declared as `type: "vector"`. Rows come
+	* back with a `_distance`; `where` filters before the ordering.
+	*/
+	vectorSearch(property, vector, options) {
+		this.params.vectorSearch = {
+			property,
+			vector,
+			...options?.distance !== void 0 && { distance: options.distance },
+			...options?.threshold !== void 0 && { threshold: options.threshold }
+		};
+		return this;
+	}
+	/**
+	* Include related entities in the response.
+	* Relations will be populated with full entity data instead of just IDs.
+	*
+	* @param relations - Relation names to include, or "*" for all.
+	* @example
+	* // Include specific relations
+	* client.data.posts.include("tags", "author").find()
+	*
+	* // Include all relations
+	* client.data.posts.include("*").find()
+	*/
+	include(...relations) {
+		this.params.include = relations;
+		return this;
+	}
+	/**
+	* Execute the find query and return the results.
+	*/
+	async find() {
+		return this.collection.find(this.params);
+	}
+	/**
+	* Listen to realtime updates matching this query.
+	*/
+	listen(onUpdate, onError) {
+		if (!this.collection.listen) throw new Error("Listen is only available when RebaseClient is configured with a websocketUrl.");
+		return this.collection.listen(this.params, onUpdate, onError);
+	}
+};
+//#endregion
+export { QueryBuilder, and, cond, not, or };
+
+//# sourceMappingURL=query_builder.es.js.map

package/dist/data/query_builder.es.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query_builder.es.js","names":[],"sources":["../../src/data/query_builder.ts"],"sourcesContent":["import {\n    CollectionAccessor,\n    FilterCondition,\n    FindParams,\n    FindResponse,\n    LogicalCondition,\n    OrderByTuple,\n    QueryBuilderInterface,\n    WhereFilterOp,\n    WhereValueFor,\n    type ComputedSortField\n} from \"@rebasepro/types\";\nimport { normalizeOrderBy } from \"./sort-dialect\";\n\n/**\n * Any condition a group may hold. The helpers below are generic over it so the\n * group they return keeps each condition's column, operator and value exactly\n * as written — which is what lets a typed `logical` / `.where(group)` check\n * them against the row ({@link LogicalConditionFor}). Their results are still\n * plain `LogicalCondition`s anywhere one is expected.\n */\ntype AnyCondition = FilterCondition | LogicalCondition;\n\n/** A value as `cond` keeps it: literals stay literals, so `\"draft\"` can match a `\"draft\" | \"published\"` column. */\ntype ConditionValue = string | number | bigint | boolean | symbol | object | null | undefined;\n\n/** An empty group, to push conditions into later. */\nexport function or(): { type: \"or\"; conditions: AnyCondition[] };\n/** The group keeps the union of what was passed, so a mixed `or(cond(…), and(…))` keeps each one. */\nexport function or<Cs extends AnyCondition[]>(...conditions: Cs): { type: \"or\"; conditions: Cs[number][] };\nexport function or(...conditions: AnyCondition[]): LogicalCondition {\n    return { type: \"or\",\nconditions };\n}\n\n/** An empty group, to push conditions into later. */\nexport function and(): { type: \"and\"; conditions: AnyCondition[] };\n/** The group keeps the union of what was passed, so a mixed `or(cond(…), and(…))` keeps each one. */\nexport function and<Cs extends AnyCondition[]>(...conditions: Cs): { type: \"and\"; conditions: Cs[number][] };\nexport function and(...conditions: AnyCondition[]): LogicalCondition {\n    return { type: \"and\",\nconditions };\n}\n\n/**\n * Negate a group: `not(a)` is `NOT a`, and `not(a, b)` is `NOT (a AND b)`.\n *\n * The conjunction, not the disjunction — one rule, stated on\n * {@link LogicalCondition} and applied identically by the wire codec, the REST\n * `?not=` parameter and every driver compiler. Groups nest, so De Morgan's\n * other half is `not(or(a, b))`.\n *\n * It compiles to a real SQL `NOT (...)` rather than to inverted operators,\n * which matters more than it looks: SQL is three-valued, so `NOT (a AND b)` and\n * `(NOT a) OR (NOT b)` stop agreeing the moment a NULL is involved, and only\n * one of them is the query the caller wrote. It also means a negation includes\n * rows whose column is NULL — which is what `NOT` means.\n */\nexport function not(): { type: \"not\"; conditions: AnyCondition[] };\nexport function not<Cs extends AnyCondition[]>(...conditions: Cs): { type: \"not\"; conditions: Cs[number][] };\nexport function not(...conditions: AnyCondition[]): LogicalCondition {\n    return { type: \"not\",\nconditions };\n}\n\n/**\n * One condition: `cond(\"age\", \">=\", 18)`.\n *\n * It returns the column, operator and value as written rather than a\n * `FilterCondition`, so that where the group is used on a typed client the\n * column and the value are checked against the row — a typo'd column or a\n * string compared to a number column is a compile error there.\n */\nexport function cond<K extends string, Op extends WhereFilterOp, V extends ConditionValue>(\n    column: K,\n    operator: Op,\n    value: V\n): { column: K; operator: Op; value: V } {\n    return { column,\noperator,\nvalue };\n}\n\nexport class QueryBuilder<M extends Record<string, unknown> = Record<string, unknown>> implements QueryBuilderInterface<M> {\n    // Keyed by plain `string` on purpose: it is written in place by the\n    // methods below, whose own parameters are typed against `M`, and a\n    // `Partial<Record<FieldPath<M>, …>>` is read-only under a generic `M`\n    // (TS2862). The typing users see is on the methods; this is the buffer\n    // behind them, cast once at each handoff.\n    private params: FindParams = { where: {} };\n\n    constructor(private collection: CollectionAccessor<M>) {}\n\n    /**\n     * Add a filter condition to your query.\n     * @example\n     * client.collection('users').where('age', '>=', 18).find()\n     */\n    where<K extends keyof M & string, Op extends WhereFilterOp>(column: K, operator: Op, value: WhereValueFor<Op, M[K]>): this;\n    where(logicalCondition: LogicalCondition): this;\n    where(columnOrCondition: string | LogicalCondition, operator?: WhereFilterOp, value?: unknown): this {\n        // Handle LogicalCondition signature\n        if (typeof columnOrCondition === \"object\" && columnOrCondition !== null && \"type\" in columnOrCondition) {\n            // A second group narrows rather than replaces — see the SDK builder\n            // in `@rebasepro/client`, which had the same defect: every other\n            // `.where()` adds a condition, so the one that silently dropped the\n            // previous group was also the one that widened the result set.\n            const next = columnOrCondition as LogicalCondition;\n            this.params.logical = this.params.logical\n                ? { type: \"and\", conditions: [this.params.logical, next] }\n                : next;\n            return this;\n        }\n\n        if (!this.params.where) {\n            this.params.where = {};\n        }\n\n        const column = columnOrCondition as string;\n        const condition: [WhereFilterOp, unknown] = [operator!, value];\n        const existing = this.params.where[column];\n\n        if (existing === undefined) {\n            this.params.where[column] = condition;\n        } else if (Array.isArray(existing) && existing.length > 0 && Array.isArray(existing[0])) {\n            (this.params.where[column] as [WhereFilterOp, unknown][]).push(condition);\n        } else {\n            // Convert existing single tuple/value into array of tuples\n            let firstCondition: [WhereFilterOp, unknown];\n            if (Array.isArray(existing) && existing.length === 2 && typeof existing[0] === \"string\") {\n                firstCondition = existing as [WhereFilterOp, unknown];\n            } else {\n                firstCondition = [\"==\", existing];\n            }\n            this.params.where[column] = [firstCondition, condition];\n        }\n\n        return this;\n    }\n\n    /**\n     * Order the results by a specific column.\n     *\n     * Called again, this adds a tie-breaker rather than replacing the sort:\n     * keys apply in the order they were added.\n     *\n     * @example\n     * client.collection('users').orderBy('createdAt', 'desc').find()\n     * @example\n     * client.collection('users').orderBy('roles').orderBy('createdAt', 'desc').find()\n     */\n    orderBy(column: (keyof M & string) | ComputedSortField, direction: \"asc\" | \"desc\" = \"asc\"): this {\n        const existing = normalizeOrderBy(this.params.orderBy) ?? [];\n        this.params.orderBy = [...existing, [column, direction] as OrderByTuple];\n        return this;\n    }\n\n    /**\n     * Limit the number of results returned.\n     */\n    limit(count: number): this {\n        this.params.limit = count;\n        return this;\n    }\n\n    /**\n     * Skip the first N results.\n     */\n    offset(count: number): this {\n        this.params.offset = count;\n        return this;\n    }\n\n    /**\n     * Set a free-text search string if supported by the backend.\n     */\n    search(searchString: string, options?: { explain?: boolean }): this {\n        this.params.searchString = searchString;\n        if (options?.explain !== undefined) this.params.searchExplain = options.explain;\n        return this;\n    }\n\n    /**\n     * Order rows by nearest-neighbour distance to `vector`, closest first.\n     *\n     * Postgres only, over a property declared as `type: \"vector\"`. Rows come\n     * back with a `_distance`; `where` filters before the ordering.\n     */\n    vectorSearch(\n        property: string,\n        vector: number[],\n        options?: { distance?: \"cosine\" | \"l2\" | \"inner_product\"; threshold?: number }\n    ): this {\n        this.params.vectorSearch = {\n            property,\n            vector,\n            ...(options?.distance !== undefined && { distance: options.distance }),\n            ...(options?.threshold !== undefined && { threshold: options.threshold })\n        };\n        return this;\n    }\n\n    /**\n     * Include related entities in the response.\n     * Relations will be populated with full entity data instead of just IDs.\n     *\n     * @param relations - Relation names to include, or \"*\" for all.\n     * @example\n     * // Include specific relations\n     * client.data.posts.include(\"tags\", \"author\").find()\n     *\n     * // Include all relations\n     * client.data.posts.include(\"*\").find()\n     */\n    include(...relations: string[]): this {\n        this.params.include = relations;\n        return this;\n    }\n\n    /**\n     * Execute the find query and return the results.\n     */\n    async find(): Promise<FindResponse<M>> {\n        return this.collection.find(this.params as FindParams<M>) as Promise<FindResponse<M>>;\n    }\n\n    /**\n     * Listen to realtime updates matching this query.\n     */\n    listen(onUpdate: (data: FindResponse<M>) => void, onError?: (error: Error) => void): () => void {\n        if (!this.collection.listen) {\n            throw new Error(\"Listen is only available when RebaseClient is configured with a websocketUrl.\");\n        }\n        return this.collection.listen(this.params as FindParams<M>, onUpdate, onError);\n    }\n}\n"],"mappings":";;AA8BA,SAAgB,GAAG,GAAG,YAA8C;CAChE,OAAO;EAAE,MAAM;EACnB;CAAW;AACX;AAMA,SAAgB,IAAI,GAAG,YAA8C;CACjE,OAAO;EAAE,MAAM;EACnB;CAAW;AACX;AAkBA,SAAgB,IAAI,GAAG,YAA8C;CACjE,OAAO;EAAE,MAAM;EACnB;CAAW;AACX;;;;;;;;;AAUA,SAAgB,KACZ,QACA,UACA,OACqC;CACrC,OAAO;EAAE;EACb;EACA;CAAM;AACN;AAEA,IAAa,eAAb,MAA2H;CAQnG;CAFpB,SAA6B,EAAE,OAAO,CAAC,EAAE;CAEzC,YAAY,YAA2C;EAAnC,KAAA,aAAA;CAAoC;CASxD,MAAM,mBAA8C,UAA0B,OAAuB;EAEjG,IAAI,OAAO,sBAAsB,YAAY,sBAAsB,QAAQ,UAAU,mBAAmB;GAKpG,MAAM,OAAO;GACb,KAAK,OAAO,UAAU,KAAK,OAAO,UAC5B;IAAE,MAAM;IAAO,YAAY,CAAC,KAAK,OAAO,SAAS,IAAI;GAAE,IACvD;GACN,OAAO;EACX;EAEA,IAAI,CAAC,KAAK,OAAO,OACb,KAAK,OAAO,QAAQ,CAAC;EAGzB,MAAM,SAAS;EACf,MAAM,YAAsC,CAAC,UAAW,KAAK;EAC7D,MAAM,WAAW,KAAK,OAAO,MAAM;EAEnC,IAAI,aAAa,KAAA,GACb,KAAK,OAAO,MAAM,UAAU;OACzB,IAAI,MAAM,QAAQ,QAAQ,KAAK,SAAS,SAAS,KAAK,MAAM,QAAQ,SAAS,EAAE,GAClF,KAAM,OAAO,MAAM,OAAO,CAAgC,KAAK,SAAS;OACrE;GAEH,IAAI;GACJ,IAAI,MAAM,QAAQ,QAAQ,KAAK,SAAS,WAAW,KAAK,OAAO,SAAS,OAAO,UAC3E,iBAAiB;QAEjB,iBAAiB,CAAC,MAAM,QAAQ;GAEpC,KAAK,OAAO,MAAM,UAAU,CAAC,gBAAgB,SAAS;EAC1D;EAEA,OAAO;CACX;;;;;;;;;;;;CAaA,QAAQ,QAAgD,YAA4B,OAAa;EAC7F,MAAM,WAAW,iBAAiB,KAAK,OAAO,OAAO,KAAK,CAAC;EAC3D,KAAK,OAAO,UAAU,CAAC,GAAG,UAAU,CAAC,QAAQ,SAAS,CAAiB;EACvE,OAAO;CACX;;;;CAKA,MAAM,OAAqB;EACvB,KAAK,OAAO,QAAQ;EACpB,OAAO;CACX;;;;CAKA,OAAO,OAAqB;EACxB,KAAK,OAAO,SAAS;EACrB,OAAO;CACX;;;;CAKA,OAAO,cAAsB,SAAuC;EAChE,KAAK,OAAO,eAAe;EAC3B,IAAI,SAAS,YAAY,KAAA,GAAW,KAAK,OAAO,gBAAgB,QAAQ;EACxE,OAAO;CACX;;;;;;;CAQA,aACI,UACA,QACA,SACI;EACJ,KAAK,OAAO,eAAe;GACvB;GACA;GACA,GAAI,SAAS,aAAa,KAAA,KAAa,EAAE,UAAU,QAAQ,SAAS;GACpE,GAAI,SAAS,cAAc,KAAA,KAAa,EAAE,WAAW,QAAQ,UAAU;EAC3E;EACA,OAAO;CACX;;;;;;;;;;;;;CAcA,QAAQ,GAAG,WAA2B;EAClC,KAAK,OAAO,UAAU;EACtB,OAAO;CACX;;;;CAKA,MAAM,OAAiC;EACnC,OAAO,KAAK,WAAW,KAAK,KAAK,MAAuB;CAC5D;;;;CAKA,OAAO,UAA2C,SAA8C;EAC5F,IAAI,CAAC,KAAK,WAAW,QACjB,MAAM,IAAI,MAAM,+EAA+E;EAEnG,OAAO,KAAK,WAAW,OAAO,KAAK,QAAyB,UAAU,OAAO;CACjF;AACJ"}

package/dist/data/resolveDataSource.es.js

@@ -0,0 +1,87 @@
+import { DEFAULT_DATA_SOURCE_KEY, getDataSourceCapabilities } from "@rebasepro/types";
+//#region src/data/resolveDataSource.ts
+/**
+* Build a keyed registry from a list of {@link DataSourceDefinition}s.
+* Later entries win on key collision.
+*/
+function createDataSourceRegistry(definitions) {
+	const registry = {};
+	for (const def of definitions ?? []) registry[def.key] = def;
+	return registry;
+}
+/**
+* Resolve the effective data source for a collection — the single source of
+* truth shared by the frontend router, the backend driver registry, and the
+* editor's capability lookups.
+*
+* Resolution order:
+* 1. The routing **key** is `collection.dataSource`, else
+*    {@link DEFAULT_DATA_SOURCE_KEY}.
+* 2. If a definition is registered for that key, it provides `engine`,
+*    `transport`, and `databaseId`.
+* 3. Otherwise values are synthesized: `engine` from `collection.engine`
+*    (or the key, or `"postgres"`), `transport` defaults to `"server"`,
+*    and `databaseId` from the collection.
+*
+* `capabilities` are always derived from the resolved `engine`, so two
+* data sources sharing an engine share capabilities.
+*
+* @param collection the collection (or any object carrying the routing fields)
+* @param registry   optional registry of declared data sources
+*/
+function resolveDataSource(collection, registry) {
+	const key = collection?.dataSource ?? DEFAULT_DATA_SOURCE_KEY;
+	const def = registry?.[key];
+	const engine = def?.engine ?? collection?.engine ?? (key !== DEFAULT_DATA_SOURCE_KEY ? key : "postgres");
+	return {
+		key,
+		engine,
+		transport: def?.transport ?? "server",
+		databaseId: collection?.databaseId ?? def?.databaseId,
+		capabilities: getDataSourceCapabilities(engine)
+	};
+}
+/**
+* Does a SQL toolchain own this collection's storage?
+*
+* "Owns the storage" means: something generates a table for it, pushes that
+* table to a database, plans its RLS policies, and reports it as drifted when
+* the two disagree. That is true of a Postgres collection and false of a
+* Firestore or MongoDB one, whose documents live in a store Rebase never
+* migrates — and the two were never told apart. Every stage of the SQL
+* toolchain took "the collections" to mean *all* of them, so a Firestore
+* collection declared next to the Postgres ones got a `pgTable` in the
+* generated schema, a `CREATE TABLE` at boot, RLS policies, and a place in the
+* `db push` include list — where its name shielding a same-named real table
+* from Atlas's exclude list is the one that can lose data.
+*
+* The answer is the resolved engine's {@link DataSourceCapabilities}, not a
+* name check: an engine registered through `registerDataSourceCapabilities`
+* gets the same treatment as the built-in ones.
+*
+* Deliberately answers **true** for an engine nobody has heard of. Build-time
+* tooling (the CLI, the schema generator) has no data-source registry to
+* resolve a `dataSource` key against, so an unknown key resolves to an unknown
+* engine — and the cost of the two mistakes is not symmetric. Wrongly
+* including a collection generates a table nothing writes to; wrongly excluding
+* one silently stops generating a table the app is serving from. Declare
+* `engine` on a collection that is not SQL-backed and this is exact.
+*/
+function isRelationalCollection(collection, registry) {
+	return getDataSourceCapabilities(collection?.engine ?? (collection?.dataSource ? resolveDataSource(collection, registry).engine : void 0)).supportsRelations;
+}
+/**
+* The subset of `collections` a SQL toolchain owns — see
+* {@link isRelationalCollection}.
+*
+* Every stage that generates SQL from collections starts by calling this, so
+* the rule lives in one place rather than being re-decided per generator. It
+* keeps the input order.
+*/
+function relationalCollections(collections, registry) {
+	return collections.filter((collection) => isRelationalCollection(collection, registry));
+}
+//#endregion
+export { createDataSourceRegistry, isRelationalCollection, relationalCollections, resolveDataSource };
+
+//# sourceMappingURL=resolveDataSource.es.js.map

package/dist/data/resolveDataSource.es.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveDataSource.es.js","names":[],"sources":["../../src/data/resolveDataSource.ts"],"sourcesContent":["import {\n    DataSourceDefinition,\n    ResolvedDataSource,\n    DEFAULT_DATA_SOURCE_KEY,\n    getDataSourceCapabilities\n} from \"@rebasepro/types\";\n\n/**\n * The subset of a collection needed to resolve its data source. Accepting a\n * structural type (rather than the full `CollectionConfig`) keeps this usable\n * from anywhere — frontend router, backend registry, editor — without coupling\n * to the collection union.\n */\nexport interface DataSourceResolvable {\n    /** Preferred routing key. */\n    dataSource?: string;\n    /** Engine type discriminant (set on variant collection types). */\n    engine?: string;\n    /** Within-engine instance. */\n    databaseId?: string;\n}\n\n/** A lookup of data-source definitions by key. */\nexport type DataSourceRegistry = Record<string, DataSourceDefinition>;\n\n/**\n * Build a keyed registry from a list of {@link DataSourceDefinition}s.\n * Later entries win on key collision.\n */\nexport function createDataSourceRegistry(definitions?: DataSourceDefinition[]): DataSourceRegistry {\n    const registry: DataSourceRegistry = {};\n    for (const def of definitions ?? []) {\n        registry[def.key] = def;\n    }\n    return registry;\n}\n\n/**\n * Resolve the effective data source for a collection — the single source of\n * truth shared by the frontend router, the backend driver registry, and the\n * editor's capability lookups.\n *\n * Resolution order:\n * 1. The routing **key** is `collection.dataSource`, else\n *    {@link DEFAULT_DATA_SOURCE_KEY}.\n * 2. If a definition is registered for that key, it provides `engine`,\n *    `transport`, and `databaseId`.\n * 3. Otherwise values are synthesized: `engine` from `collection.engine`\n *    (or the key, or `\"postgres\"`), `transport` defaults to `\"server\"`,\n *    and `databaseId` from the collection.\n *\n * `capabilities` are always derived from the resolved `engine`, so two\n * data sources sharing an engine share capabilities.\n *\n * @param collection the collection (or any object carrying the routing fields)\n * @param registry   optional registry of declared data sources\n */\nexport function resolveDataSource(\n    collection: DataSourceResolvable | undefined,\n    registry?: DataSourceRegistry\n): ResolvedDataSource {\n    const key = collection?.dataSource ?? DEFAULT_DATA_SOURCE_KEY;\n    const def = registry?.[key];\n\n    const engine = def?.engine\n        ?? collection?.engine\n        ?? (key !== DEFAULT_DATA_SOURCE_KEY ? key : \"postgres\");\n\n    const transport = def?.transport ?? \"server\";\n    const databaseId = collection?.databaseId ?? def?.databaseId;\n\n    return {\n        key,\n        engine,\n        transport,\n        databaseId,\n        capabilities: getDataSourceCapabilities(engine)\n    };\n}\n\n/**\n * Does a SQL toolchain own this collection's storage?\n *\n * \"Owns the storage\" means: something generates a table for it, pushes that\n * table to a database, plans its RLS policies, and reports it as drifted when\n * the two disagree. That is true of a Postgres collection and false of a\n * Firestore or MongoDB one, whose documents live in a store Rebase never\n * migrates — and the two were never told apart. Every stage of the SQL\n * toolchain took \"the collections\" to mean *all* of them, so a Firestore\n * collection declared next to the Postgres ones got a `pgTable` in the\n * generated schema, a `CREATE TABLE` at boot, RLS policies, and a place in the\n * `db push` include list — where its name shielding a same-named real table\n * from Atlas's exclude list is the one that can lose data.\n *\n * The answer is the resolved engine's {@link DataSourceCapabilities}, not a\n * name check: an engine registered through `registerDataSourceCapabilities`\n * gets the same treatment as the built-in ones.\n *\n * Deliberately answers **true** for an engine nobody has heard of. Build-time\n * tooling (the CLI, the schema generator) has no data-source registry to\n * resolve a `dataSource` key against, so an unknown key resolves to an unknown\n * engine — and the cost of the two mistakes is not symmetric. Wrongly\n * including a collection generates a table nothing writes to; wrongly excluding\n * one silently stops generating a table the app is serving from. Declare\n * `engine` on a collection that is not SQL-backed and this is exact.\n */\nexport function isRelationalCollection(\n    collection: DataSourceResolvable | undefined,\n    registry?: DataSourceRegistry\n): boolean {\n    // The collection's own `engine` wins over a registered definition's. That\n    // is the opposite of {@link resolveDataSource}'s precedence, deliberately:\n    // there a definition describes where the data *goes*, so it should override;\n    // here the question is what the author said this collection is, and a\n    // collection declaring `engine: \"firestore\"` with no `dataSource` must not\n    // come back as the default source's engine and be handed a table.\n    const engine = collection?.engine\n        ?? (collection?.dataSource ? resolveDataSource(collection, registry).engine : undefined);\n    return getDataSourceCapabilities(engine).supportsRelations;\n}\n\n/**\n * The subset of `collections` a SQL toolchain owns — see\n * {@link isRelationalCollection}.\n *\n * Every stage that generates SQL from collections starts by calling this, so\n * the rule lives in one place rather than being re-decided per generator. It\n * keeps the input order.\n */\nexport function relationalCollections<C extends DataSourceResolvable>(\n    collections: readonly C[],\n    registry?: DataSourceRegistry\n): C[] {\n    return collections.filter(collection => isRelationalCollection(collection, registry));\n}\n"],"mappings":";;;;;;AA6BA,SAAgB,yBAAyB,aAA0D;CAC/F,MAAM,WAA+B,CAAC;CACtC,KAAK,MAAM,OAAO,eAAe,CAAC,GAC9B,SAAS,IAAI,OAAO;CAExB,OAAO;AACX;;;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,kBACZ,YACA,UACkB;CAClB,MAAM,MAAM,YAAY,cAAc;CACtC,MAAM,MAAM,WAAW;CAEvB,MAAM,SAAS,KAAK,UACb,YAAY,WACX,QAAQ,0BAA0B,MAAM;CAKhD,OAAO;EACH;EACA;EACA,WANc,KAAK,aAAa;EAOhC,YANe,YAAY,cAAc,KAAK;EAO9C,cAAc,0BAA0B,MAAM;CAClD;AACJ;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,SAAgB,uBACZ,YACA,UACO;CASP,OAAO,0BAFQ,YAAY,WACnB,YAAY,aAAa,kBAAkB,YAAY,QAAQ,CAAC,CAAC,SAAS,KAAA,EAC3C,CAAC,CAAC;AAC7C;;;;;;;;;AAUA,SAAgB,sBACZ,aACA,UACG;CACH,OAAO,YAAY,QAAO,eAAc,uBAAuB,YAAY,QAAQ,CAAC;AACxF"}

package/dist/data/row-etag.d.ts

@@ -0,0 +1,46 @@
+/**
+ * A row's version — the `ETag` the read that produced it reported — kept on
+ * the row without being part of it.
+ *
+ * @module
+ */
+/**
+ * Where a fetched row's version is kept.
+ *
+ * Non-enumerable, so it does not appear in `Object.keys`, in `JSON.stringify`,
+ * in a spread into an update body, or in the generated `Row` type — a row's
+ * version is a fact about the *response*, not a column, and putting it in the
+ * row proper would mean the server having to strip it back off every write.
+ *
+ * A string key rather than a symbol so it survives the structured clone an
+ * offline store or a worker boundary does… which it does not, and that is the
+ * honest position: an etag is per-read, and a row that has been through a cache
+ * has not been read from the server. `etagOf` answers `undefined` there, and a
+ * conditional write without a tag is an unconditional one.
+ */
+export declare const ETAG_KEY = "__etag";
+/**
+ * The version of a row, when it came straight from a read that reported one.
+ *
+ * ```ts
+ * const post = await client.data.posts.get(1);
+ * await client.data.posts.update(1, { title: "New" }, { ifMatch: etagOf(post) });
+ * ```
+ *
+ * Set on a row from `findById()`/`get()`, from `update()`, and on every row
+ * `listenById()` delivers (the SDK asks the server to tag each frame).
+ * `undefined` for a row from `find()` (a list response carries one ETag at
+ * most, and it would not be this row's), from the offline cache, or from a
+ * server that does not send them. Passing `undefined` as `ifMatch` sends no
+ * precondition, so the call above degrades to an ordinary update rather than
+ * failing — which is the right default, and the reason to read this at the call
+ * site where the choice is visible.
+ */
+export declare function etagOf(row: unknown): string | undefined;
+/**
+ * Attach a version to a row without making it part of the row: a
+ * non-enumerable `__etag`, so it stays out of `Object.keys`, a spread and
+ * `JSON.stringify`, and a row copied through any of them has no tag — which
+ * is right, since the copy was not read from the server.
+ */
+export declare function withETag<T>(row: T, etag: string | undefined): T;