@rebasepro/server-postgres 0.16.0 → 0.16.1-canary.g0d7af95

package/dist/connection-BuZ97wsr.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"connection-BuZ97wsr.js","names":[],"sources":["../src/connection.ts"],"sourcesContent":["import { Pool, PoolConfig } from \"pg\";\nimport { drizzle } from \"drizzle-orm/node-postgres\";\nimport { logger } from \"@rebasepro/server\";\n\n/**\n * Configuration for the Postgres connection pool.\n *\n * Sensible defaults are provided for production Cloud Run / single-instance\n * deployments. Override via environment variables or explicit config.\n */\nexport interface PostgresPoolConfig {\n    /** Maximum number of connections in the pool (default: 20) */\n    max?: number;\n    /** Close idle connections after this many ms (default: 30 000) */\n    idleTimeoutMillis?: number;\n    /** Abort connection attempts after this many ms (default: 10 000) */\n    connectionTimeoutMillis?: number;\n    /** Per-query timeout in ms (default: 30 000) */\n    queryTimeout?: number;\n    /** Per-statement timeout in ms (default: 30 000) */\n    statementTimeout?: number;\n    /** Enable TCP keep-alive (default: true) */\n    keepAlive?: boolean;\n    /**\n     * `search_path` pinned on every connection (default: `\"public\"`).\n     *\n     * Pass `false` to send no `search_path` at all and inherit whatever the\n     * server/role defaults to. See {@link pinSearchPath} for why the default\n     * is not \"inherit\".\n     */\n    searchPath?: string | false;\n}\n\nconst DEFAULT_POOL: Required<PostgresPoolConfig> = {\n    max: 20,\n    searchPath: \"public\",\n    idleTimeoutMillis: 30_000,\n    connectionTimeoutMillis: 10_000,\n    // The client-side read timeout MUST be comfortably above the server-side\n    // statement_timeout. When the client timer fires first, node-postgres\n    // abandons the in-flight statement but keeps the connection — inside a\n    // transaction that leaves the tx open (and any pending ROLLBACK is\n    // spliced out of the client queue before it ever reaches the wire), so\n    // the pooled connection is returned still in-transaction with its RLS\n    // GUCs set. The server abort (SQLSTATE 57014) is the clean path; the\n    // client timeout is only a backstop for a dead network.\n    queryTimeout: 60_000,\n    statementTimeout: 30_000,\n    keepAlive: true\n};\n\n/** ReadyForQuery status byte: `I` idle, `T` in transaction, `E` failed transaction. */\nconst TX_IDLE = \"I\";\n\n/**\n * Pin `search_path` into a connection string, so unqualified SQL resolves to a\n * schema this framework chose rather than to one Postgres inferred.\n *\n * Postgres defaults `search_path` to `\"$user\", public`: the *first* candidate\n * is a schema named after the connecting role. Rebase creates a schema called\n * `rebase` (auth, history, api keys), and every template, compose file and\n * deployment doc names the database role `rebase` too — so `$user` resolves to\n * a schema that exists, and every unqualified statement lands there instead of\n * in `public`. The generated Drizzle schema emits bare `pgTable(\"posts\", …)`\n * for any collection without an explicit `schema`, which makes the *runtime's*\n * own reads and writes unqualified; a developer's raw `rebase.sql(...)`, the\n * Studio SQL editor and any hand-written migration are unqualified too. The\n * result is collection tables created in, and served from, `rebase`.\n *\n * Drizzle cannot express the fix on its side: `pgSchema(\"public\")` throws by\n * design (\"just use pgTable() instead\"), so there is no way to emit a\n * public-qualified table from the generator. The pin has to live on the\n * connection.\n *\n * Precedence is deliberate and verified against node-postgres: `options` in\n * the connection string wins over the `options` field passed to `Pool`, so\n * rewriting the URL — rather than setting the field — is what makes this\n * authoritative. Two escape hatches survive it:\n *\n *  - an `options` that already mentions `search_path` is left untouched, so a\n *    deployment that deliberately pins something else keeps it;\n *  - `searchPath: false` (or an unparseable, non-URL connection string) sends\n *    nothing and inherits the server default.\n *\n * Anything else in `options` (a `statement_timeout`, say) is preserved and the\n * `search_path` flag is appended to it.\n */\nexport function pinSearchPath(connectionString: string, searchPath: string | false = \"public\"): string {\n    if (searchPath === false) return connectionString;\n\n    let url: URL;\n    try {\n        url = new URL(connectionString);\n    } catch {\n        // Key/value DSNs and anything else we cannot parse are returned as\n        // given: a connection that works unpinned beats one we corrupted.\n        return connectionString;\n    }\n    if (url.protocol !== \"postgres:\" && url.protocol !== \"postgresql:\") return connectionString;\n\n    const existing = url.searchParams.get(\"options\");\n    if (existing && /(^|\\s)-c\\s*search_path\\s*=/.test(existing)) return connectionString;\n\n    const flag = `-c search_path=${searchPath}`;\n    url.searchParams.set(\"options\", existing ? `${existing} ${flag}` : flag);\n    // Re-serialize by hand. `URLSearchParams` writes a space as `+`, which\n    // node-postgres happens to decode but libpq does not — and this same string\n    // is handed to `pg_dump`/`psql` for backups. Percent-encoding is the form\n    // both agree on, and is what the scaffolded `.env` already ships.\n    url.search = Array.from(url.searchParams.entries())\n        .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`)\n        .join(\"&\");\n    return url.toString();\n}\n\n/**\n * Destroy pool clients that are released while still inside a transaction.\n *\n * pg-pool returns a client to the idle list whenever `release()` is called\n * without an error — even if the connection is still mid-transaction (status\n * `T`/`E`). That happens in practice: drizzle's pool transaction releases in\n * a `finally` after attempting ROLLBACK, and if the ROLLBACK itself fails\n * (e.g. it was queued behind a statement that hit the client-side\n * query_timeout), the client goes back dirty. The next checkout then runs\n * its statements inside the zombie transaction — with the previous request's\n * `app.*` RLS GUCs still applied, which turns unrelated queries into\n * RLS-scoped ones (observed in production as registration failing with\n * SQLSTATE 42501 under a leaked anonymous context).\n *\n * pg-pool emits `release` before it consults its private `_expired` set, so\n * marking the client expired here makes `_release()` destroy it instead of\n * pooling it. Both `client._txStatus` (pg ≥ 8.16) and `pool._expired` are\n * private APIs — feature-detect and fall back to loud logging so an upstream\n * change degrades to observability, never to silent corruption.\n */\nexport function guardPoolAgainstDirtyRelease(pool: Pool, label: string): void {\n    pool.on(\"release\", (err: Error | undefined, client: unknown) => {\n        if (err) return; // errored clients are already destroyed by pg-pool\n        const txStatus = (client as { _txStatus?: string | null })?._txStatus;\n        if (typeof txStatus !== \"string\" || txStatus === TX_IDLE) return;\n\n        // pg-pool keeps expired clients in a WeakSet (a plain object works too\n        // if upstream ever changes it — duck-type on add/has).\n        const expired = (pool as unknown as { _expired?: { add(c: object): unknown; has(c: object): boolean } })._expired;\n        if (expired && typeof expired.add === \"function\" && typeof expired.has === \"function\" && client && typeof client === \"object\") {\n            expired.add(client);\n            logger.error(\n                `[${label}] Client released back to the pool while still in a transaction ` +\n                `(status '${txStatus}') — destroying it so the open transaction and its ` +\n                `session state (RLS GUCs) cannot leak into the next request.`\n            );\n        } else {\n            logger.error(\n                `[${label}] Client released mid-transaction (status '${txStatus}') but the ` +\n                `pool's internal expiry set is unavailable (pg-pool internals changed?). ` +\n                `The connection may leak its open transaction into subsequent requests.`\n            );\n        }\n    });\n}\n\n/**\n * Create a Drizzle-backed Postgres connection with a production-grade\n * connection pool.\n *\n * @param connectionString  Postgres connection URL\n * @param schema            Optional Drizzle schema for the relational API\n * @param poolConfig        Optional pool tuning (merged over defaults)\n *\n * @returns `{ db, pool, connectionString }` — the `pool` is exposed so\n *          callers can register shutdown hooks (`pool.end()`) or monitor\n *          pool metrics.\n */\nexport function createPostgresDatabaseConnection(\n    connectionString: string,\n    schema?: Record<string, unknown>,\n    poolConfig?: PostgresPoolConfig\n) {\n    const opts = { ...DEFAULT_POOL,\n...poolConfig };\n    connectionString = pinSearchPath(connectionString, opts.searchPath);\n\n    const pgPoolConfig: PoolConfig = {\n        connectionString,\n        max: opts.max,\n        idleTimeoutMillis: opts.idleTimeoutMillis,\n        connectionTimeoutMillis: opts.connectionTimeoutMillis,\n        query_timeout: opts.queryTimeout,\n        statement_timeout: opts.statementTimeout,\n        keepAlive: opts.keepAlive,\n        keepAliveInitialDelayMillis: 0\n    };\n\n    const pool = new Pool(pgPoolConfig);\n\n    // ── Pool event logging ────────────────────────────────────────────────\n    // Uses console.* because the structured logger lives in server\n    // (a separate package). The caller can replace these with the structured\n    // logger if desired via pool.on() after creation.\n    pool.on(\"error\", (err) => {\n        logger.error(\"[pg-pool] Unexpected pool error\", { detail: err.message });\n        if (err.message.includes(\"ETIMEDOUT\")) {\n            logger.warn(\"[pg-pool] Connection timeout detected — pool will auto-retry\");\n        }\n    });\n    guardPoolAgainstDirtyRelease(pool, \"pg-pool\");\n\n    // Create drizzle instance — pass schema when available to enable db.query relational API\n    const db = schema ? drizzle(pool, { schema }) : drizzle(pool);\n\n    return { db,\npool,\nconnectionString };\n}\n\n/**\n * Create a direct (non-pooled) connection for operations that require\n * session-level features incompatible with PgBouncer transaction mode,\n * such as LISTEN/NOTIFY, prepared statements, or advisory locks.\n *\n * Uses a smaller pool since this is only for specific use cases.\n */\nexport function createDirectDatabaseConnection(\n    connectionString: string,\n    schema?: Record<string, unknown>,\n    poolConfig?: PostgresPoolConfig\n) {\n    const opts = {\n        ...DEFAULT_POOL,\n        max: 5,\n        ...poolConfig\n    };\n    connectionString = pinSearchPath(connectionString, opts.searchPath);\n\n    const pgPoolConfig: PoolConfig = {\n        connectionString,\n        max: opts.max,\n        idleTimeoutMillis: opts.idleTimeoutMillis,\n        connectionTimeoutMillis: opts.connectionTimeoutMillis,\n        query_timeout: opts.queryTimeout,\n        statement_timeout: opts.statementTimeout,\n        keepAlive: opts.keepAlive,\n        keepAliveInitialDelayMillis: 0\n    };\n\n    const pool = new Pool(pgPoolConfig);\n\n    pool.on(\"error\", (err) => {\n        logger.error(\"[pg-direct-pool] Unexpected pool error\", { detail: err.message });\n    });\n    guardPoolAgainstDirtyRelease(pool, \"pg-direct-pool\");\n\n    const db = schema ? drizzle(pool, { schema }) : drizzle(pool);\n\n    return { db,\npool,\nconnectionString };\n}\n\n/**\n * Create a read-only connection for routing read queries to replicas.\n * Uses a moderate pool size since reads are distributed across replicas.\n */\nexport function createReadReplicaConnection(\n    connectionString: string,\n    schema?: Record<string, unknown>,\n    poolConfig?: PostgresPoolConfig\n) {\n    const opts = {\n        ...DEFAULT_POOL,\n        max: 10,\n        ...poolConfig\n    };\n    connectionString = pinSearchPath(connectionString, opts.searchPath);\n\n    const pgPoolConfig: PoolConfig = {\n        connectionString,\n        max: opts.max,\n        idleTimeoutMillis: opts.idleTimeoutMillis,\n        connectionTimeoutMillis: opts.connectionTimeoutMillis,\n        query_timeout: opts.queryTimeout,\n        statement_timeout: opts.statementTimeout,\n        keepAlive: opts.keepAlive,\n        keepAliveInitialDelayMillis: 0\n    };\n\n    const pool = new Pool(pgPoolConfig);\n\n    pool.on(\"error\", (err) => {\n        logger.error(\"[pg-replica-pool] Unexpected pool error\", { detail: err.message });\n    });\n    guardPoolAgainstDirtyRelease(pool, \"pg-replica-pool\");\n\n    const db = schema ? drizzle(pool, { schema }) : drizzle(pool);\n\n    return { db,\npool,\nconnectionString };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCA,IAAM,eAA6C;CAC/C,KAAK;CACL,YAAY;CACZ,mBAAmB;CACnB,yBAAyB;CASzB,cAAc;CACd,kBAAkB;CAClB,WAAW;AACf;;AAGA,IAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmChB,SAAgB,cAAc,kBAA0B,aAA6B,UAAkB;CACnG,IAAI,eAAe,OAAO,OAAO;CAEjC,IAAI;CACJ,IAAI;EACA,MAAM,IAAI,IAAI,gBAAgB;CAClC,QAAQ;EAGJ,OAAO;CACX;CACA,IAAI,IAAI,aAAa,eAAe,IAAI,aAAa,eAAe,OAAO;CAE3E,MAAM,WAAW,IAAI,aAAa,IAAI,SAAS;CAC/C,IAAI,YAAY,6BAA6B,KAAK,QAAQ,GAAG,OAAO;CAEpE,MAAM,OAAO,kBAAkB;CAC/B,IAAI,aAAa,IAAI,WAAW,WAAW,GAAG,SAAS,GAAG,SAAS,IAAI;CAKvE,IAAI,SAAS,MAAM,KAAK,IAAI,aAAa,QAAQ,CAAC,CAAC,CAC9C,KAAK,CAAC,KAAK,WAAW,GAAG,mBAAmB,GAAG,EAAE,GAAG,mBAAmB,KAAK,GAAG,CAAC,CAChF,KAAK,GAAG;CACb,OAAO,IAAI,SAAS;AACxB;;;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,6BAA6B,MAAY,OAAqB;CAC1E,KAAK,GAAG,YAAY,KAAwB,WAAoB;EAC5D,IAAI,KAAK;EACT,MAAM,WAAY,QAA0C;EAC5D,IAAI,OAAO,aAAa,YAAY,aAAa,SAAS;EAI1D,MAAM,UAAW,KAAwF;EACzG,IAAI,WAAW,OAAO,QAAQ,QAAQ,cAAc,OAAO,QAAQ,QAAQ,cAAc,UAAU,OAAO,WAAW,UAAU;GAC3H,QAAQ,IAAI,MAAM;GAClB,OAAO,MACH,IAAI,MAAM,2EACE,SAAS,+GAEzB;EACJ,OACI,OAAO,MACH,IAAI,MAAM,6CAA6C,SAAS,0JAGpE;CAER,CAAC;AACL;;;;;;;;;;;;;AAcA,SAAgB,iCACZ,kBACA,QACA,YACF;CACE,MAAM,OAAO;EAAE,GAAG;EACtB,GAAG;CAAW;CACV,mBAAmB,cAAc,kBAAkB,KAAK,UAAU;CAalE,MAAM,OAAO,IAAI,KAAK;EAVlB;EACA,KAAK,KAAK;EACV,mBAAmB,KAAK;EACxB,yBAAyB,KAAK;EAC9B,eAAe,KAAK;EACpB,mBAAmB,KAAK;EACxB,WAAW,KAAK;EAChB,6BAA6B;CAGX,CAAY;CAMlC,KAAK,GAAG,UAAU,QAAQ;EACtB,OAAO,MAAM,mCAAmC,EAAE,QAAQ,IAAI,QAAQ,CAAC;EACvE,IAAI,IAAI,QAAQ,SAAS,WAAW,GAChC,OAAO,KAAK,8DAA8D;CAElF,CAAC;CACD,6BAA6B,MAAM,SAAS;CAK5C,OAAO;EAAE,IAFE,SAAS,QAAQ,MAAM,EAAE,OAAO,CAAC,IAAI,QAAQ,IAAI;EAGhE;EACA;CAAiB;AACjB;;;;;;;;AASA,SAAgB,+BACZ,kBACA,QACA,YACF;CACE,MAAM,OAAO;EACT,GAAG;EACH,KAAK;EACL,GAAG;CACP;CACA,mBAAmB,cAAc,kBAAkB,KAAK,UAAU;CAalE,MAAM,OAAO,IAAI,KAAK;EAVlB;EACA,KAAK,KAAK;EACV,mBAAmB,KAAK;EACxB,yBAAyB,KAAK;EAC9B,eAAe,KAAK;EACpB,mBAAmB,KAAK;EACxB,WAAW,KAAK;EAChB,6BAA6B;CAGX,CAAY;CAElC,KAAK,GAAG,UAAU,QAAQ;EACtB,OAAO,MAAM,0CAA0C,EAAE,QAAQ,IAAI,QAAQ,CAAC;CAClF,CAAC;CACD,6BAA6B,MAAM,gBAAgB;CAInD,OAAO;EAAE,IAFE,SAAS,QAAQ,MAAM,EAAE,OAAO,CAAC,IAAI,QAAQ,IAAI;EAGhE;EACA;CAAiB;AACjB;;;;;AAMA,SAAgB,4BACZ,kBACA,QACA,YACF;CACE,MAAM,OAAO;EACT,GAAG;EACH,KAAK;EACL,GAAG;CACP;CACA,mBAAmB,cAAc,kBAAkB,KAAK,UAAU;CAalE,MAAM,OAAO,IAAI,KAAK;EAVlB;EACA,KAAK,KAAK;EACV,mBAAmB,KAAK;EACxB,yBAAyB,KAAK;EAC9B,eAAe,KAAK;EACpB,mBAAmB,KAAK;EACxB,WAAW,KAAK;EAChB,6BAA6B;CAGX,CAAY;CAElC,KAAK,GAAG,UAAU,QAAQ;EACtB,OAAO,MAAM,2CAA2C,EAAE,QAAQ,IAAI,QAAQ,CAAC;CACnF,CAAC;CACD,6BAA6B,MAAM,iBAAiB;CAIpD,OAAO;EAAE,IAFE,SAAS,QAAQ,MAAM,EAAE,OAAO,CAAC,IAAI,QAAQ,IAAI;EAGhE;EACA;CAAiB;AACjB"}

package/dist/data_driver-ULAyJEi9.js

@@ -1,193 +0,0 @@
-import { createRequire as __createRequire } from "module";
-import "process";
-__createRequire(import.meta.url);
-//#region ../types/src/errors.ts
-/**
-* The single error type thrown across the entire Rebase client surface —
-* HTTP data/control-plane calls, realtime/WebSocket operations, and
-* client-side logic errors (e.g. an unknown collection accessor). A `catch`
-* block only ever needs to check for this one class:
-*
-* ```ts
-* import { RebaseApiError } from "@rebasepro/client"; // re-exported
-*
-* try {
-*   await client.data.products.update(id, { price: 9 });
-* } catch (e) {
-*   if (e instanceof RebaseApiError) {
-*     if (e.status === 404) { ... }   // HTTP failures carry a status
-*     console.error(e.code, e.details);
-*   }
-* }
-* ```
-*
-* `status` is present for HTTP failures and `undefined` otherwise, so its
-* presence distinguishes transport-level errors from realtime/logic errors.
-*
-* @group Errors
-*/
-var RebaseApiError = class extends Error {
-	/** HTTP status code, or `undefined` for non-HTTP errors. */
-	status;
-	/** Stable machine-readable error code, when the server supplied one. See {@link RebaseErrorCode}. */
-	code;
-	/** Structured error payload from the server, when present. */
-	details;
-	constructor(message, init = {}) {
-		super(message);
-		this.name = "RebaseApiError";
-		this.status = init.status;
-		this.code = init.code;
-		this.details = init.details;
-		if (init.cause !== void 0) this.cause = init.cause;
-	}
-};
-//#endregion
-//#region ../types/src/types/policy.ts
-/**
-* The id a request without a logged-in user reports as `rebase.uid()`.
-*
-* A user-context request always sets `app.uid`: blank would read back as
-* `NULL`, and `NULL` is how the trusted server context is recognised, so an
-* anonymous visitor would be promoted to server privileges. The driver
-* therefore substitutes this sentinel at the single chokepoint where the GUC
-* is set.
-*
-* The consequence for policy authors is that **`rebase.uid() IS NOT NULL` is a
-* tautology on the user path** — it is true for anonymous visitors too. Use
-* {@link policy.authenticated} to mean "signed in", and
-* {@link policy.serverContext} to mean "the trusted server context". Do not
-* hand-write the comparison: see {@link ANONYMOUS_USER_IDS} for why one
-* literal is not enough.
-*
-* @group Models
-*/
-var ANONYMOUS_USER_ID = "anonymous";
-/**
-* Every uid that has ever meant "nobody is signed in" — newest first.
-*
-* There are two because there were two. The types, the policy compiler, the
-* JavaScript evaluator and the linter were all built on
-* {@link ANONYMOUS_USER_ID}, while the request path scoped unauthenticated
-* callers as `'anon'` — so `policy.authenticated()`, which compiled to
-* `rebase.uid() <> 'anonymous'`, was *true* for an anonymous visitor. The
-* sanctioned way to write "signed in" granted to everyone, and the linter
-* flagged the spelling that actually worked as a foreign convention.
-*
-* The request path now reports {@link ANONYMOUS_USER_ID}. `'anon'` stays here
-* because policies outlive the server that generated them: a database still
-* holding policies from before the fix, or a project whose server has not been
-* upgraded yet, must not become a grant in either direction. Compile against
-* this list, not against a single literal.
-*
-* No real user id is ever one of these, so a match is always "not signed in".
-*
-* @group Models
-*/
-var ANONYMOUS_USER_IDS = [ANONYMOUS_USER_ID, "anon"];
-/** @group Models */
-var policy = {
-	true: () => ({ kind: "true" }),
-	false: () => ({ kind: "false" }),
-	and: (...operands) => ({
-		kind: "and",
-		operands
-	}),
-	or: (...operands) => ({
-		kind: "or",
-		operands
-	}),
-	not: (operand) => ({
-		kind: "not",
-		operand
-	}),
-	compare: (left, op, right) => ({
-		kind: "compare",
-		op,
-		left,
-		right
-	}),
-	rolesOverlap: (roles) => ({
-		kind: "rolesOverlap",
-		roles
-	}),
-	rolesContain: (roles) => ({
-		kind: "rolesContain",
-		roles
-	}),
-	authenticated: () => ({ kind: "authenticated" }),
-	serverContext: () => ({ kind: "serverContext" }),
-	existsIn: (args) => ({
-		kind: "existsIn",
-		collection: args.collection,
-		where: args.where
-	}),
-	raw: (sql) => ({
-		kind: "raw",
-		sql
-	}),
-	field: (name) => ({
-		kind: "field",
-		name
-	}),
-	outerField: (name) => ({
-		kind: "outerField",
-		name
-	}),
-	literal: (value) => ({
-		kind: "literal",
-		value
-	}),
-	authUid: () => ({ kind: "authUid" }),
-	authRoles: () => ({ kind: "authRoles" })
-};
-/**
-* Thrown by {@link resolveClientListLimit} for a `limit` the platform will not
-* serve. Carries an HTTP status so an ingress that speaks HTTP can forward it
-* verbatim, and `maxLimit` so one can be built without re-deriving the ceiling.
-*
-* @group Errors
-*/
-var ListLimitError = class ListLimitError extends RebaseApiError {
-	/** The ceiling that was exceeded — what the caller should page by instead. */
-	maxLimit;
-	constructor(message, maxLimit) {
-		super(message, {
-			status: 400,
-			code: "INVALID_LIMIT"
-		});
-		this.name = "ListLimitError";
-		this.maxLimit = maxLimit;
-		Object.setPrototypeOf(this, ListLimitError.prototype);
-	}
-};
-/**
-* Resolve a client-supplied list `limit` into a safe, always-defined value.
-*
-* - An absent / blank limit falls back to the mode default:
-*   `vectorDefaultLimit` for a vector search, otherwise `defaultLimit`.
-* - A limit that is present must be an integer in `[1, maxLimit]`. Anything
-*   else — `0`, a negative, `1.5`, `abc`, `100000000` — throws
-*   {@link ListLimitError} rather than being coerced into range, because every
-*   coercion answers a question the caller did not ask with a page it cannot
-*   tell apart from the whole collection.
-*
-* The return is never `undefined` — no ingress that routes its client limit
-* through this can produce an unbounded read.
-*
-* @throws {ListLimitError} when a present `limit` is not an integer in range.
-*/
-function resolveClientListLimit(rawLimit, opts = {}) {
-	const maxLimit = opts.maxLimit ?? 1e3;
-	if (rawLimit != null && String(rawLimit).trim() !== "") {
-		const parsed = typeof rawLimit === "number" ? rawLimit : Number(String(rawLimit).trim());
-		if (!Number.isInteger(parsed) || parsed < 1) throw new ListLimitError(`Invalid \`limit\`: ${String(rawLimit)}. Expected a whole number between 1 and ${maxLimit}.`, maxLimit);
-		if (parsed > maxLimit) throw new ListLimitError(`\`limit\` ${parsed} is above the maximum of ${maxLimit}. Ask for at most ${maxLimit} rows per read and page through the rest with \`offset\` — answering with a smaller page would be indistinguishable from there being no more rows.`, maxLimit);
-		return parsed;
-	}
-	return opts.vectorSearch ? opts.vectorDefaultLimit ?? 10 : opts.defaultLimit ?? 50;
-}
-//#endregion
-export { policy as a, ANONYMOUS_USER_IDS as i, resolveClientListLimit as n, ANONYMOUS_USER_ID as r, ListLimitError as t };
-
-//# sourceMappingURL=data_driver-ULAyJEi9.js.map

package/dist/data_driver-ULAyJEi9.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"data_driver-ULAyJEi9.js","names":[],"sources":["../../types/src/errors.ts","../../types/src/types/policy.ts","../../types/src/controllers/data_driver.ts"],"sourcesContent":["/**\n * The error codes every route can produce, as `RebaseApiError.code`.\n *\n * These are the defaults on `ApiError`'s static constructors server-side, so\n * any endpoint can answer with one. They are **not** the complete set: routes\n * pass their own more specific codes too (`EMAIL_EXISTS`, `TOKEN_EXPIRED`,\n * `INVALID_BULK_BODY`, …), and auth alone defines a couple of dozen.\n *\n * Hence the union is deliberately open rather than closed. It exists to give\n * autocomplete and to catch a typo in the common cases — `code` was a bare\n * `string`, so `e.code === \"NOT_FOUND\"` and `e.code === \"NOTFOUND\"` were\n * equally valid and only one of them worked. Closing it would be a lie that\n * broke the moment a route added a code.\n *\n * @example\n * if (e instanceof RebaseApiError) {\n *   switch (e.code) {\n *     case \"NOT_FOUND\": return null;          // completed\n *     case \"FORBIDDEN\": return redirect();\n *     default: throw e;                       // routes' own codes land here\n *   }\n * }\n *\n * @group Errors\n */\nexport type RebaseErrorCode =\n    | \"BAD_REQUEST\"\n    | \"UNAUTHORIZED\"\n    | \"FORBIDDEN\"\n    | \"NOT_FOUND\"\n    | \"CONFLICT\"\n    | \"INTERNAL_ERROR\"\n    | \"SERVICE_UNAVAILABLE\"\n    | \"DB_PERMISSION_DENIED\"\n    | \"SCHEMA_DRIFT\"\n    // `string & {}` keeps the union open while preserving completion on the\n    // literals above — a bare `| string` would collapse them and offer nothing.\n    | (string & {});\n\n/**\n * Structured initializer for {@link RebaseApiError}.\n *\n * @group Errors\n */\nexport interface RebaseErrorInit {\n    /**\n     * HTTP status code, when the error originated from an HTTP response.\n     * Left `undefined` for realtime/WebSocket, network, and client-side\n     * logic errors that have no HTTP status.\n     */\n    status?: number;\n    /** Stable, machine-readable error code. See {@link RebaseErrorCode}. */\n    code?: RebaseErrorCode;\n    /** Structured error payload returned by the server, when present. */\n    details?: unknown;\n    /** The underlying error this one wraps, if any. */\n    cause?: unknown;\n}\n\n/**\n * The single error type thrown across the entire Rebase client surface —\n * HTTP data/control-plane calls, realtime/WebSocket operations, and\n * client-side logic errors (e.g. an unknown collection accessor). A `catch`\n * block only ever needs to check for this one class:\n *\n * ```ts\n * import { RebaseApiError } from \"@rebasepro/client\"; // re-exported\n *\n * try {\n *   await client.data.products.update(id, { price: 9 });\n * } catch (e) {\n *   if (e instanceof RebaseApiError) {\n *     if (e.status === 404) { ... }   // HTTP failures carry a status\n *     console.error(e.code, e.details);\n *   }\n * }\n * ```\n *\n * `status` is present for HTTP failures and `undefined` otherwise, so its\n * presence distinguishes transport-level errors from realtime/logic errors.\n *\n * @group Errors\n */\nexport class RebaseApiError extends Error {\n    /** HTTP status code, or `undefined` for non-HTTP errors. */\n    readonly status?: number;\n    /** Stable machine-readable error code, when the server supplied one. See {@link RebaseErrorCode}. */\n    readonly code?: RebaseErrorCode;\n    /** Structured error payload from the server, when present. */\n    readonly details?: unknown;\n\n    constructor(message: string, init: RebaseErrorInit = {}) {\n        super(message);\n        this.name = \"RebaseApiError\";\n        this.status = init.status;\n        this.code = init.code;\n        this.details = init.details;\n        if (init.cause !== undefined) {\n            // `cause` is standard on Error but not always in the lib target's type.\n            (this as { cause?: unknown }).cause = init.cause;\n        }\n    }\n}\n\n/**\n * Client-side logic error — raised before any request is made (e.g. accessing\n * an unknown collection accessor when a typed dictionary is configured).\n *\n * A subclass of {@link RebaseApiError} (with no `status`), so a single\n * `catch (e) { if (e instanceof RebaseApiError) ... }` handles it too.\n *\n * @group Errors\n */\nexport class RebaseClientError extends RebaseApiError {\n    constructor(message: string) {\n        super(message);\n        this.name = \"RebaseClientError\";\n    }\n}\n","/**\n * Structured, engine-agnostic policy expressions.\n *\n * A {@link PolicyExpression} is the single source of truth for a row-level\n * security condition. It is compiled to Postgres `USING`/`WITH CHECK` SQL\n * (authoritative enforcement) and independently evaluated in JavaScript (to\n * drive the admin UI, and — in future — to enforce on engines without native\n * RLS such as MongoDB). Because both the SQL and the JS decision derive from\n * the *same* expression, the UI matches database enforcement by construction —\n * no drift between two hand-written implementations.\n *\n * The only escape hatch that cannot be evaluated client-side is the\n * {@link RawPolicyExpression} node (`{ kind: \"raw\" }`): it preserves full\n * PostgreSQL power but, being arbitrary SQL, is treated as *unknown* by the\n * JavaScript evaluator (never silently allowed) and reflected exactly in the UI\n * via server-computed capability flags.\n *\n * @group Models\n */\nexport type PolicyExpression =\n    | TruePolicyExpression\n    | FalsePolicyExpression\n    | AndPolicyExpression\n    | OrPolicyExpression\n    | NotPolicyExpression\n    | ComparePolicyExpression\n    | RolesOverlapPolicyExpression\n    | RolesContainPolicyExpression\n    | AuthenticatedPolicyExpression\n    | ServerContextPolicyExpression\n    | ExistsInPolicyExpression\n    | RawPolicyExpression;\n\n/**\n * The id a request without a logged-in user reports as `rebase.uid()`.\n *\n * A user-context request always sets `app.uid`: blank would read back as\n * `NULL`, and `NULL` is how the trusted server context is recognised, so an\n * anonymous visitor would be promoted to server privileges. The driver\n * therefore substitutes this sentinel at the single chokepoint where the GUC\n * is set.\n *\n * The consequence for policy authors is that **`rebase.uid() IS NOT NULL` is a\n * tautology on the user path** — it is true for anonymous visitors too. Use\n * {@link policy.authenticated} to mean \"signed in\", and\n * {@link policy.serverContext} to mean \"the trusted server context\". Do not\n * hand-write the comparison: see {@link ANONYMOUS_USER_IDS} for why one\n * literal is not enough.\n *\n * @group Models\n */\nexport const ANONYMOUS_USER_ID = \"anonymous\";\n\n/**\n * Every uid that has ever meant \"nobody is signed in\" — newest first.\n *\n * There are two because there were two. The types, the policy compiler, the\n * JavaScript evaluator and the linter were all built on\n * {@link ANONYMOUS_USER_ID}, while the request path scoped unauthenticated\n * callers as `'anon'` — so `policy.authenticated()`, which compiled to\n * `rebase.uid() <> 'anonymous'`, was *true* for an anonymous visitor. The\n * sanctioned way to write \"signed in\" granted to everyone, and the linter\n * flagged the spelling that actually worked as a foreign convention.\n *\n * The request path now reports {@link ANONYMOUS_USER_ID}. `'anon'` stays here\n * because policies outlive the server that generated them: a database still\n * holding policies from before the fix, or a project whose server has not been\n * upgraded yet, must not become a grant in either direction. Compile against\n * this list, not against a single literal.\n *\n * No real user id is ever one of these, so a match is always \"not signed in\".\n *\n * @group Models\n */\nexport const ANONYMOUS_USER_IDS: readonly string[] = [ANONYMOUS_USER_ID, \"anon\"];\n\n/**\n * Whether a uid stands for \"no one is signed in\", in any spelling rebase has\n * used. `null`/`undefined` is the trusted server context, not an anonymous\n * caller, and is therefore **not** anonymous — see {@link ANONYMOUS_USER_ID}.\n *\n * @group Models\n */\nexport function isAnonymousUid(uid: string | null | undefined): boolean {\n    return typeof uid === \"string\" && ANONYMOUS_USER_IDS.includes(uid);\n}\n\n/** Always allows. Compiles to `true`. @group Models */\nexport interface TruePolicyExpression {\n    kind: \"true\";\n}\n\n/** Always denies. Compiles to `false`. @group Models */\nexport interface FalsePolicyExpression {\n    kind: \"false\";\n}\n\n/** Logical AND — every operand must pass. @group Models */\nexport interface AndPolicyExpression {\n    kind: \"and\";\n    operands: readonly PolicyExpression[];\n}\n\n/** Logical OR — at least one operand must pass. @group Models */\nexport interface OrPolicyExpression {\n    kind: \"or\";\n    operands: readonly PolicyExpression[];\n}\n\n/** Logical negation. @group Models */\nexport interface NotPolicyExpression {\n    kind: \"not\";\n    operand: PolicyExpression;\n}\n\n/** Comparison operators available to {@link ComparePolicyExpression}. @group Models */\nexport type PolicyCompareOperator = \"eq\" | \"neq\" | \"lt\" | \"lte\" | \"gt\" | \"gte\";\n\n/**\n * Compares two operands, e.g. `owner_id = rebase.uid()`.\n * @group Models\n */\nexport interface ComparePolicyExpression {\n    kind: \"compare\";\n    op: PolicyCompareOperator;\n    left: PolicyOperand;\n    right: PolicyOperand;\n}\n\n/**\n * True when the user holds *at least one* of the given application roles.\n * Compiles to `string_to_array(rebase.roles(), ',') && ARRAY[...]`.\n * @group Models\n */\nexport interface RolesOverlapPolicyExpression {\n    kind: \"rolesOverlap\";\n    roles: readonly string[];\n}\n\n/**\n * True when the user holds *all* of the given application roles.\n * Compiles to `string_to_array(rebase.roles(), ',') @> ARRAY[...]`.\n * @group Models\n */\nexport interface RolesContainPolicyExpression {\n    kind: \"rolesContain\";\n    roles: readonly string[];\n}\n\n/**\n * True when a signed-in user is making the request. Compiles to\n * `rebase.uid() IS NOT NULL AND rebase.uid() <> 'anonymous'`.\n *\n * Both halves are load-bearing. `IS NOT NULL` excludes the server context;\n * the {@link ANONYMOUS_USER_ID} comparison excludes anonymous visitors, who\n * *do* carry a non-null `rebase.uid()`. Checking only `IS NOT NULL` grants to\n * everyone — see {@link ANONYMOUS_USER_ID}.\n *\n * `policy.not(policy.authenticated())` therefore means \"anonymous visitor or\n * the server context\". To single out the server context, use\n * {@link ServerContextPolicyExpression}.\n * @group Models\n */\nexport interface AuthenticatedPolicyExpression {\n    kind: \"authenticated\";\n}\n\n/**\n * True only in the trusted **server context** — the built-in flows that run\n * without a user (signup, migrations, `dataAsAdmin`) set no user GUC, so\n * `rebase.uid()` is `NULL` for them and only for them. Compiles to\n * `rebase.uid() IS NULL`.\n *\n * This is what lets the owner connection satisfy a policy even under FORCE RLS.\n * It is deliberately a primitive rather than `not(authenticated())`: the two\n * meant the same thing while `authenticated` ignored {@link ANONYMOUS_USER_ID},\n * and conflating them is what turns a server-only grant into an anonymous one.\n *\n * The JavaScript evaluator always returns `false` for this node — a client is\n * never the server context.\n * @group Models\n */\nexport interface ServerContextPolicyExpression {\n    kind: \"serverContext\";\n}\n\n/**\n * Membership / relational access: true when at least one row exists in another\n * collection (a join/membership table) matching `where`. This is what lets you\n * scope reads to \"rows whose team the caller belongs to\" without an N+1\n * per-row lookup — it compiles to a single correlated `EXISTS` subquery.\n *\n * Inside `where`, {@link FieldPolicyOperand} (`policy.field`) references a column\n * of the joined collection, while {@link OuterFieldPolicyOperand}\n * (`policy.outerField`) references a column of the row being checked (the outer\n * table under RLS). Combine with {@link AuthUidPolicyOperand} to correlate to\n * the caller.\n *\n * @example\n * ```ts\n * // documents visible only to members of the document's team:\n * policy.existsIn({\n *   collection: \"team_members\",\n *   where: policy.and(\n *     policy.compare(policy.field(\"team_id\"), \"eq\", policy.outerField(\"team_id\")),\n *     policy.compare(policy.field(\"user_id\"), \"eq\", policy.authUid()),\n *   ),\n * })\n * // → EXISTS (SELECT 1 FROM team_members _ex0\n * //           WHERE _ex0.team_id = documents.team_id AND _ex0.user_id = rebase.uid())\n * ```\n *\n * Postgres-authoritative: like {@link RawPolicyExpression}, the JavaScript\n * evaluator treats it as *unknown* (it cannot run a subquery client-side), so\n * enforcement is always the database's.\n * @group Models\n */\nexport interface ExistsInPolicyExpression {\n    kind: \"existsIn\";\n    /** Slug of the collection to search (the join / membership table). */\n    collection: string;\n    /** Condition evaluated against the joined collection's rows. */\n    where: PolicyExpression;\n}\n\n/**\n * A raw PostgreSQL boolean expression — the full-power escape hatch.\n *\n * Columns can be referenced as `{column_name}`. This is Postgres-only and\n * **server-authoritative**: the JavaScript evaluator cannot evaluate arbitrary\n * SQL, so it treats this node as *unknown* rather than guessing.\n * @group Models\n */\nexport interface RawPolicyExpression {\n    kind: \"raw\";\n    sql: string;\n}\n\n/**\n * An operand referenced by a {@link ComparePolicyExpression}.\n * @group Models\n */\nexport type PolicyOperand =\n    | FieldPolicyOperand\n    | OuterFieldPolicyOperand\n    | LiteralPolicyOperand\n    | AuthUidPolicyOperand\n    | AuthRolesPolicyOperand;\n\n/** A column value on the row being evaluated. @group Models */\nexport interface FieldPolicyOperand {\n    kind: \"field\";\n    /** The property/column name (resolved to its DB column when compiled). */\n    name: string;\n}\n\n/**\n * A column value on the *outer* row when used inside {@link ExistsInPolicyExpression}\n * — i.e. the row the RLS policy is being evaluated for, referenced from within the\n * subquery. Outside an `existsIn` it is equivalent to {@link FieldPolicyOperand}.\n * @group Models\n */\nexport interface OuterFieldPolicyOperand {\n    kind: \"outerField\";\n    /** The property/column name on the outer collection. */\n    name: string;\n}\n\n/** A constant value. @group Models */\nexport interface LiteralPolicyOperand {\n    kind: \"literal\";\n    value: string | number | boolean | null;\n}\n\n/** The current user's id — compiles to `rebase.uid()`. @group Models */\nexport interface AuthUidPolicyOperand {\n    kind: \"authUid\";\n}\n\n/**\n * The current user's roles as an array — compiles to\n * `string_to_array(rebase.roles(), ',')`.\n * @group Models\n */\nexport interface AuthRolesPolicyOperand {\n    kind: \"authRoles\";\n}\n\n// ── Constructor helpers ──────────────────────────────────────────────\n// Small, dependency-free builders so callers (and the desugaring in\n// `@rebasepro/common`) can assemble expressions without object-literal noise.\n\n/** @group Models */\nexport const policy = {\n    true: (): TruePolicyExpression => ({ kind: \"true\" }),\n    false: (): FalsePolicyExpression => ({ kind: \"false\" }),\n    and: (...operands: readonly PolicyExpression[]): AndPolicyExpression => ({ kind: \"and\",\noperands: operands as PolicyExpression[] }),\n    or: (...operands: readonly PolicyExpression[]): OrPolicyExpression => ({ kind: \"or\",\noperands: operands as PolicyExpression[] }),\n    not: (operand: PolicyExpression): NotPolicyExpression => ({ kind: \"not\",\noperand }),\n    compare: (left: PolicyOperand, op: PolicyCompareOperator, right: PolicyOperand): ComparePolicyExpression =>\n        ({ kind: \"compare\",\nop,\nleft,\nright }),\n    rolesOverlap: (roles: readonly string[]): RolesOverlapPolicyExpression => ({ kind: \"rolesOverlap\",\nroles: roles as string[] }),\n    rolesContain: (roles: readonly string[]): RolesContainPolicyExpression => ({ kind: \"rolesContain\",\nroles: roles as string[] }),\n    authenticated: (): AuthenticatedPolicyExpression => ({ kind: \"authenticated\" }),\n    serverContext: (): ServerContextPolicyExpression => ({ kind: \"serverContext\" }),\n    existsIn: (args: { collection: string; where: PolicyExpression }): ExistsInPolicyExpression =>\n        ({ kind: \"existsIn\",\ncollection: args.collection,\nwhere: args.where }),\n    raw: (sql: string): RawPolicyExpression => ({ kind: \"raw\",\nsql }),\n    field: (name: string): FieldPolicyOperand => ({ kind: \"field\",\nname }),\n    outerField: (name: string): OuterFieldPolicyOperand => ({ kind: \"outerField\",\nname }),\n    literal: (value: string | number | boolean | null): LiteralPolicyOperand => ({ kind: \"literal\",\nvalue }),\n    authUid: (): AuthUidPolicyOperand => ({ kind: \"authUid\" }),\n    authRoles: (): AuthRolesPolicyOperand => ({ kind: \"authRoles\" })\n};\n","import { RebaseApiError } from \"../errors\";\nimport type { CollectionRegistryController } from \"./collection_registry\";\nimport type { EntityStatus, EntityValues } from \"../types/entities\";\nimport type { CollectionConfig, FilterValues } from \"../types/collections\";\nimport type { OrderByTuple } from \"../types/filter-operators\";\nimport type { RebaseCallContext } from \"../call_context\";\nimport type { LogicalCondition } from \"./data\";\n\n\n/**\n * @internal\n */\nexport interface FetchOneProps<M extends Record<string, unknown> = Record<string, unknown>> {\n    path: string;\n    id: string | number;\n    databaseId?: string;\n    collection?: CollectionConfig<M>\n}\n\n/**\n * @internal\n */\nexport type ListenOneProps<M extends Record<string, unknown> = Record<string, unknown>> =\n    FetchOneProps<M>\n    & {\n        onUpdate: (row: Record<string, unknown> | null) => void,\n        onError?: (error: Error) => void,\n    }\n\n/**\n * Configuration for vector similarity search queries.\n * Vector search applies an ORDER BY distance expression and optionally\n * filters results by a distance threshold.\n */\nexport interface VectorSearchParams {\n    /** Property name containing the vector column */\n    property: string;\n    /** Query vector to compare against */\n    vector: number[];\n    /** Distance function (default: \"cosine\") */\n    distance?: \"cosine\" | \"l2\" | \"inner_product\";\n    /** Only return results within this distance threshold */\n    threshold?: number;\n}\n\n// ── List pagination bounds ────────────────────────────────────────────────\n//\n// Client-driven list reads (REST `GET /<collection>` and the WebSocket\n// `subscribe_collection` message) accept a client-supplied `limit`. Without\n// bounds, an ABSENT limit streams the entire table into memory — a trivial\n// OOM/DoS — and `limit=100000000` (or `limit=0`, historically an unlimited\n// bypass) is honoured verbatim. `resolveClientListLimit` is the single shared\n// enforcement point so every untrusted ingress behaves identically. Trusted\n// server-side callers build fetch options directly and are intentionally NOT\n// bounded here (migrations, admin exports, and CDC refetches may need the full\n// set).\n//\n// A limit the platform will not serve is REFUSED, not quietly shrunk. Clamping\n// answers a request for 100 000 rows with 1 000 of them, and a short page is\n// indistinguishable from \"that is all the data there is\" — which is how a CSV\n// export shipped 50 rows of a 100 000-row collection under a filename that read\n// like the whole thing. `meta.total`/`meta.hasMore` make truncation *detectable*\n// on the REST list response, but only for a caller who thinks to compare what it\n// asked for against what it got, and the WebSocket `collection_update` frame\n// carries neither — so signalling cannot be the answer on every surface and\n// rejecting is. An ABSENT limit still defaults: naming no window is not the same\n// as asking for one that cannot be served.\n\n/** Rows returned for a plain / text-search list read when the client sends no `limit`. */\nexport const DEFAULT_LIST_LIMIT = 50;\n/** Rows returned for a vector-search list read when the client sends no `limit`. */\nexport const DEFAULT_VECTOR_LIST_LIMIT = 10;\n/** Largest `limit` a client may ask for on any surface. Above it, the read is refused. */\nexport const MAX_LIST_LIMIT = 1000;\n\n/** Overridable bounds for {@link resolveClientListLimit}. */\nexport interface ListLimitBounds {\n    /** Default page size for plain and text-search reads. */\n    defaultLimit?: number;\n    /** Default page size for vector-search reads. */\n    vectorDefaultLimit?: number;\n    /** Largest limit a client may ask for. A larger one is rejected, not clamped. */\n    maxLimit?: number;\n}\n\n/**\n * Thrown by {@link resolveClientListLimit} for a `limit` the platform will not\n * serve. Carries an HTTP status so an ingress that speaks HTTP can forward it\n * verbatim, and `maxLimit` so one can be built without re-deriving the ceiling.\n *\n * @group Errors\n */\nexport class ListLimitError extends RebaseApiError {\n    /** The ceiling that was exceeded — what the caller should page by instead. */\n    readonly maxLimit: number;\n\n    constructor(message: string, maxLimit: number) {\n        super(message, { status: 400, code: \"INVALID_LIMIT\" });\n        this.name = \"ListLimitError\";\n        this.maxLimit = maxLimit;\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, ListLimitError.prototype);\n    }\n}\n\n/**\n * Resolve a client-supplied list `limit` into a safe, always-defined value.\n *\n * - An absent / blank limit falls back to the mode default:\n *   `vectorDefaultLimit` for a vector search, otherwise `defaultLimit`.\n * - A limit that is present must be an integer in `[1, maxLimit]`. Anything\n *   else — `0`, a negative, `1.5`, `abc`, `100000000` — throws\n *   {@link ListLimitError} rather than being coerced into range, because every\n *   coercion answers a question the caller did not ask with a page it cannot\n *   tell apart from the whole collection.\n *\n * The return is never `undefined` — no ingress that routes its client limit\n * through this can produce an unbounded read.\n *\n * @throws {ListLimitError} when a present `limit` is not an integer in range.\n */\nexport function resolveClientListLimit(\n    rawLimit: number | string | null | undefined,\n    opts: ListLimitBounds & { vectorSearch?: boolean } = {}\n): number {\n    const maxLimit = opts.maxLimit ?? MAX_LIST_LIMIT;\n    if (rawLimit != null && String(rawLimit).trim() !== \"\") {\n        // `Number`, not `parseInt`: `parseInt(\"50rows\")` is 50, which silently\n        // reads a typo as a window the caller never wrote.\n        const parsed = typeof rawLimit === \"number\" ? rawLimit : Number(String(rawLimit).trim());\n        if (!Number.isInteger(parsed) || parsed < 1) {\n            throw new ListLimitError(\n                `Invalid \\`limit\\`: ${String(rawLimit)}. Expected a whole number between 1 and ${maxLimit}.`,\n                maxLimit\n            );\n        }\n        if (parsed > maxLimit) {\n            throw new ListLimitError(\n                `\\`limit\\` ${parsed} is above the maximum of ${maxLimit}. Ask for at most ${maxLimit} rows ` +\n                \"per read and page through the rest with `offset` — answering with a smaller page would be \" +\n                \"indistinguishable from there being no more rows.\",\n                maxLimit\n            );\n        }\n        return parsed;\n    }\n    return opts.vectorSearch\n        ? (opts.vectorDefaultLimit ?? DEFAULT_VECTOR_LIST_LIMIT)\n        : (opts.defaultLimit ?? DEFAULT_LIST_LIMIT);\n}\n\n/**\n * @internal\n */\nexport interface FetchCollectionProps<M extends Record<string, unknown> = Record<string, unknown>> {\n    path: string;\n    collection?: CollectionConfig<M>;\n    filter?: FilterValues<Extract<keyof M, string>>,\n    /**\n     * An `or(...)`/`and(...)` group, applied alongside `filter`.\n     *\n     * The REST layer parsed `?or=` into this and then had nowhere to put it, so\n     * the group was dropped and the read ran unfiltered — returning every row\n     * the caller's policies allowed rather than the ones they asked for.\n     */\n    logical?: LogicalCondition;\n    limit?: number;\n    offset?: number;\n    startAfter?: unknown;\n    /**\n     * The sort, in either of two spellings:\n     *\n     * - a field name, whose direction is the separate `order` below — the\n     *   original single-column contract, which every existing driver reads;\n     * - a list of `[field, direction]` tuples applied in order of significance,\n     *   which carries a multi-column sort and ignores `order` entirely.\n     *\n     * `normalizeDriverOrderBy` in `@rebasepro/common` collapses the pair to the\n     * list form. A driver that has not been taught the list form should read it\n     * through that helper rather than assume a string: handed an array, `String()`\n     * would produce a field name like `roles,asc` and the sort would 400 (or,\n     * with unknown-field warnings on, silently vanish).\n     */\n    orderBy?: string | OrderByTuple[];\n    searchString?: string;\n    /** Ask each row which declared search field matched — populates `_matches`. */\n    searchExplain?: boolean;\n    /** Direction for the string form of `orderBy`. Ignored when `orderBy` is a list. */\n    order?: \"desc\" | \"asc\";\n    /** Vector similarity search configuration */\n    vectorSearch?: VectorSearchParams;\n}\n\n/**\n * @internal\n */\nexport type ListenCollectionProps<M extends Record<string, unknown> = Record<string, unknown>> =\n    FetchCollectionProps<M> &\n    {\n        onUpdate: (rows: Record<string, unknown>[]) => void;\n        onError?: (error: Error) => void;\n    };\n\n/**\n * @internal\n */\nexport interface SaveProps<M extends Record<string, unknown> = Record<string, unknown>> {\n    path: string;\n    values: Partial<EntityValues<M>>;\n    id?: string | number; // can be empty for new entities\n    previousValues?: Partial<EntityValues<M>>;\n    collection?: CollectionConfig<M>;\n    status: EntityStatus;\n    /**\n     * Write the row with INSERT ... ON CONFLICT DO UPDATE on the primary key\n     * instead of choosing between insert and update up front.\n     *\n     * One statement, so it does not lose the race a read-then-write can, and it\n     * succeeds whether or not the row is already there — what a re-runnable\n     * import needs. Requires every primary key column to be present; without\n     * them there is no conflict target and the row is inserted normally.\n     */\n    upsert?: boolean;\n}\n\n/**\n * @internal\n */\nexport interface SaveManyProps<M extends Record<string, unknown> = Record<string, unknown>> {\n    path: string;\n    /**\n     * The rows to write. A row carrying its primary key updates (or, with\n     * `upsert`, inserts-or-updates) that row; one without inserts.\n     */\n    rows: Partial<EntityValues<M>>[];\n    collection?: CollectionConfig<M>;\n    /** Apply every row as INSERT ... ON CONFLICT DO UPDATE. See {@link SaveProps.upsert}. */\n    upsert?: boolean;\n}\n\n/**\n * @internal\n */\nexport interface UpdateManyProps<M extends Record<string, unknown> = Record<string, unknown>> {\n    path: string;\n    /**\n     * The rows to update, each named by its address.\n     *\n     * Distinct from {@link SaveManyProps.rows}, which carries keys *inside* the\n     * values and is insert-shaped — `saveMany` passes `status: \"new\"` and no\n     * `id`, so it cannot express \"update exactly this row\". This can, and it is\n     * why bulk update is a separate driver method rather than a flag on that one.\n     */\n    updates: { id: string | number; values: Partial<EntityValues<M>> }[];\n    collection?: CollectionConfig<M>;\n}\n\n/**\n * @internal\n */\nexport interface DeleteProps<M extends Record<string, unknown> = Record<string, unknown>> {\n    row: { id: string | number; path: string; values?: Partial<EntityValues<M>> };\n    collection?: CollectionConfig<M>;\n}\n\n/**\n * @internal\n */\nexport interface DeleteManyProps<M extends Record<string, unknown> = Record<string, unknown>> {\n    path: string;\n    ids: (string | number)[];\n    collection?: CollectionConfig<M>;\n}\n\nexport type FilterCombinationValidProps = {\n    path: string;\n    databaseId?: string;\n    collection: CollectionConfig;\n    filterValues: FilterValues<string>;\n    sortBy?: [string, \"asc\" | \"desc\"];\n};\n\n/**\n * The integration SPI for plugging a data backend into Rebase.\n *\n * Implement this interface to connect a custom backend (or use a built-in\n * driver such as the Firestore one) and register it on\n * `<Rebase dataSources>`. Rebase wraps drivers via `buildRebaseData` and\n * routes collections to them by their `dataSource` key.\n *\n * For *consuming* data in application code, use `RebaseData` /\n * `context.data` instead — this interface is only for providing it.\n *\n * @group Datasource\n */\nexport interface DataDriver {\n\n    /**\n     * Key that identifies this driver\n     */\n    key?: string;\n\n    /**\n     * If the driver has been initialised\n     */\n    initialised?: boolean;\n\n    /**\n     * Fetch data from a collection\n     * @param props\n     * @return Promise of flat rows\n     */\n    fetchCollection<M extends Record<string, unknown> = Record<string, unknown>>(props: FetchCollectionProps<M>): Promise<Record<string, unknown>[]>;\n\n    /**\n     * Listen to a collection in a given path. If you don't implement this method\n     * `fetchCollection` will be used instead, with no real time updates.\n     * @param props\n     * @return Function to cancel subscription\n     */\n    listenCollection?<M extends Record<string, unknown> = Record<string, unknown>>(props: ListenCollectionProps<M>): () => void;\n\n    /**\n     * Retrieve a single row given a path and a collection\n     * @param props\n     */\n    fetchOne<M extends Record<string, unknown> = Record<string, unknown>>(props: FetchOneProps<M>): Promise<Record<string, unknown> | undefined>;\n\n    /**\n     * Get realtime updates on one row.\n     * @param props\n     * @return Function to cancel subscription\n     */\n    listenOne?<M extends Record<string, unknown> = Record<string, unknown>>(props: ListenOneProps<M>): () => void;\n\n    /**\n     * Save a row to the specified path\n     * @param props\n     */\n    save<M extends Record<string, unknown> = Record<string, unknown>>(props: SaveProps<M>): Promise<Record<string, unknown>>;\n\n    /**\n     * Save many rows as one unit of work.\n     *\n     * Every row runs the same pipeline as {@link save} — callbacks, relations\n     * and row-level security all still apply — but they share a single\n     * transaction, so the batch either lands whole or not at all. That, and the\n     * single round trip, is what makes importing tens of thousands of rows\n     * viable without dropping to raw SQL.\n     *\n     * Optional: drivers that cannot do this leave it undefined and callers fall\n     * back to `save` per row.\n     */\n    saveMany?<M extends Record<string, unknown> = Record<string, unknown>>(props: SaveManyProps<M>): Promise<Record<string, unknown>[]>;\n\n    /**\n     * Update many rows in one transaction, each addressed by id.\n     *\n     * Optional for the same reason `saveMany` is: a driver that cannot make the\n     * batch atomic should not pretend to. The REST layer reports\n     * `BULK_UNSUPPORTED` rather than silently falling back to a loop of single\n     * writes, which would be neither atomic nor one round trip — the two things\n     * a caller reaches for a batch to get.\n     */\n    updateMany?<M extends Record<string, unknown> = Record<string, unknown>>(props: UpdateManyProps<M>): Promise<Record<string, unknown>[]>;\n\n    /**\n     * Delete the row `props.row` addresses.\n     *\n     * **Resolving means the row is gone because this call removed it.** A\n     * delete that matched nothing must reject with a not-found error\n     * (`ApiError.notFound`, `statusCode: 404`) rather than resolving quietly.\n     *\n     * The rule is here rather than in each driver because the two\n     * implementations answered differently and each had a test pinning its own\n     * habit: Postgres threw, Mongo logged a warning and resolved. Three things\n     * decide it in favour of rejecting.\n     *\n     * The REST layer already says 404 — `DELETE /api/data/<c>/<id>` reads the\n     * row before removing it — so a quiet resolve made the driver API disagree\n     * with the HTTP API about the same operation, and only in-process\n     * `rebase.data` callers could see the difference.\n     *\n     * A caller cannot tell \"deleted\" from \"there was nothing there\" without it,\n     * and those are different facts: one means the caller's model of the data\n     * was right, the other that it was stale. Silence hands back the wrong one\n     * and the caller carries on.\n     *\n     * And on a driver with row-level security, \"matched nothing\" is *also* how\n     * a policy refusal arrives — Postgres filters `DELETE` through `USING`\n     * rather than raising. A driver that resolves on zero rows therefore\n     * reports a refused delete as a completed one, which is the defect\n     * `explainZeroRowWrite` exists to prevent (see `write-denial.ts`).\n     *\n     * Conformance for both server drivers lives in\n     * `packages/server/test/contract/delete-contract.ts`, run by each driver's\n     * own suite against its own database. `packages/firebase`'s Firestore\n     * driver does not honour it: `deleteDoc` resolves for a missing document\n     * and reporting otherwise would cost a read on every delete. It runs in the\n     * browser against Firestore's own semantics rather than behind\n     * `rebase.data`, and that exception is stated here rather than left to be\n     * discovered.\n     */\n    delete<M extends Record<string, unknown> = Record<string, unknown>>(props: DeleteProps<M>): Promise<void>;\n\n    /**\n     * Delete all entities from a collection.\n     * @param path Collection path\n     */\n    deleteAll?(path: string): Promise<void>;\n\n    /**\n     * Delete many rows in one transaction, addressed by id.\n     *\n     * Ids rather than a filter, deliberately — see\n     * {@link SDKCollectionClient.deleteMany}. Optional, as `saveMany` is.\n     */\n    deleteMany?<M extends Record<string, unknown> = Record<string, unknown>>(props: DeleteManyProps<M>): Promise<void>;\n\n    /**\n     * Check if the given property is unique in the given collection\n     * @param path Collection path\n     * @param name of the property\n     * @param value\n     * @param id\n     * @param collection\n     * @return `true` if there are no other fields besides the given entity\n     */\n    checkUniqueField(\n        path: string,\n        name: string,\n        value: unknown,\n        id?: string | number,\n        collection?: CollectionConfig\n    ): Promise<boolean>;\n\n    /**\n     * Count the number of entities in a collection\n     */\n    count?<M extends Record<string, unknown> = Record<string, unknown>>(props: FetchCollectionProps<M>): Promise<number>;\n\n    /**\n     * Check if the given filter combination is valid\n     * @param props\n     */\n    isFilterCombinationValid?(props: Omit<FilterCombinationValidProps, \"collection\"> & {\n        databaseId?: string\n    }): boolean;\n\n    /**\n     * Get the object to generate the current time in the driver\n     */\n    currentTime?: () => unknown;\n\n    delegateToCMSModel?: (data: unknown) => unknown;\n\n    cmsToDelegateModel?: (data: unknown) => unknown;\n\n    initTextSearch?: (props: {\n        context: RebaseCallContext,\n        path: string,\n        databaseId?: string,\n        collection: CollectionConfig,\n        parentCollectionSlugs?: string[];\n        parentEntityIds?: string[];\n    }) => Promise<boolean>;\n\n    /**\n     * Flag to indicate if the driver has requested the initialization of the text search index\n     */\n    needsInitTextSearch?: boolean;\n\n    // ── REST fetch capabilities ─────────────────────────────────────────\n\n    /**\n     * Optional REST-optimised fetch service. When present, the REST API\n     * generator uses these methods instead of the generic `fetchOne` /\n     * `fetchCollection` pipeline, enabling include-aware eager-loading.\n     */\n    restFetchService?: RestFetchService;\n\n    // ── Admin capabilities ─────────────────────────────────────────────\n    //\n    // Admin operations are now modelled as capability-specific interfaces\n    // (SQLAdmin, DocumentAdmin, SchemaAdmin) in `@rebasepro/types/backend`.\n    //\n    // Drivers that support admin features should expose them here.\n    // Consumers should use the `isSQLAdmin()`, `isSchemaAdmin()` etc.\n    // type guards to safely narrow the type before calling methods.\n\n    /**\n     * Return the admin capabilities of this driver.\n     * @see SQLAdmin\n     * @see DocumentAdmin\n     * @see SchemaAdmin\n     */\n    admin?: import(\"../types/backend\").DatabaseAdmin;\n\n}\n\n/**\n * REST-optimised fetch service exposed by drivers that support\n * eager-loading of relations via `include`.\n *\n * The methods return flattened rows — exactly the table's columns, under their\n * own names and with the types the database returned — and included relations\n * inlined as plain nested rows. This is the shape served to app developers\n * through the REST API / SDK client.\n *\n * No synthesized `id`: identity is a primary key, which may be named anything\n * and span several columns, so an address is derived by whoever needs one (see\n * `buildCompositeId`) rather than written into the row on top of the data.\n *\n * @group DataDriver\n */\nexport interface RestFetchService {\n    /**\n     * Fetch a collection of flattened entities with optional relation includes.\n     */\n    fetchCollectionForRest(\n        collectionPath: string,\n        options?: {\n            filter?: FilterValues<string>;\n            /** An `or(...)`/`and(...)` group, applied alongside `filter`. */\n            logical?: LogicalCondition;\n            /** See `FetchCollectionProps.orderBy`: a field name plus `order`, or a list of tuples. */\n            orderBy?: string | OrderByTuple[];\n            order?: \"desc\" | \"asc\";\n            limit?: number;\n            offset?: number;\n            startAfter?: Record<string, unknown>;\n            searchString?: string;\n            /** Ask each row which declared search fields matched — populates `_matches`. */\n            searchExplain?: boolean;\n            databaseId?: string;\n            vectorSearch?: VectorSearchParams;\n        },\n        include?: string[]\n    ): Promise<Record<string, unknown>[]>;\n\n    /**\n     * `count`/`sum`/`avg`/`min`/`max` over the rows a filter selects,\n     * optionally grouped.\n     *\n     * Optional, and the REST route answers 501 where a driver does not\n     * implement it — an aggregate is not a thing to approximate, and an empty\n     * result set would read as \"nothing matched\".\n     *\n     * Any implementation **must apply the same row-level authorization as a\n     * read**. An aggregate is an efficient way to learn about rows you cannot\n     * select, and `count(*)` over a table whose policies would return nothing\n     * has to be zero.\n     */\n    aggregate?(\n        collectionPath: string,\n        options: {\n            aggregates: { fn: \"count\" | \"sum\" | \"avg\" | \"min\" | \"max\"; field?: string; alias: string }[];\n            groupBy?: string[];\n            filter?: FilterValues<string>;\n            logical?: LogicalCondition;\n            searchString?: string;\n            limit?: number;\n        }\n    ): Promise<Record<string, unknown>[]>;\n\n    /**\n     * Fetch a single flattened entity with optional relation includes.\n     */\n    fetchOneForRest(\n        collectionPath: string,\n        id: string | number,\n        include?: string[],\n        databaseId?: string\n    ): Promise<Record<string, unknown> | null>;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmFA,IAAa,iBAAb,cAAoC,MAAM;;CAEtC;;CAEA;;CAEA;CAEA,YAAY,SAAiB,OAAwB,CAAC,GAAG;EACrD,MAAM,OAAO;EACb,KAAK,OAAO;EACZ,KAAK,SAAS,KAAK;EACnB,KAAK,OAAO,KAAK;EACjB,KAAK,UAAU,KAAK;EACpB,IAAI,KAAK,UAAU,KAAA,GAEf,KAA8B,QAAQ,KAAK;CAEnD;AACJ;;;;;;;;;;;;;;;;;;;;;ACnDA,IAAa,oBAAoB;;;;;;;;;;;;;;;;;;;;;;AAuBjC,IAAa,qBAAwC,CAAC,mBAAmB,MAAM;;AA2N/E,IAAa,SAAS;CAClB,aAAmC,EAAE,MAAM,OAAO;CAClD,cAAqC,EAAE,MAAM,QAAQ;CACrD,MAAM,GAAG,cAAgE;EAAE,MAAM;EAC3E;CAA+B;CACrC,KAAK,GAAG,cAA+D;EAAE,MAAM;EACzE;CAA+B;CACrC,MAAM,aAAoD;EAAE,MAAM;EACtE;CAAQ;CACJ,UAAU,MAAqB,IAA2B,WACrD;EAAE,MAAM;EACjB;EACA;EACA;CAAM;CACF,eAAe,WAA4D;EAAE,MAAM;EAChF;CAAkB;CACrB,eAAe,WAA4D;EAAE,MAAM;EAChF;CAAkB;CACrB,sBAAqD,EAAE,MAAM,gBAAgB;CAC7E,sBAAqD,EAAE,MAAM,gBAAgB;CAC7E,WAAW,UACN;EAAE,MAAM;EACjB,YAAY,KAAK;EACjB,OAAO,KAAK;CAAM;CACd,MAAM,SAAsC;EAAE,MAAM;EACxD;CAAI;CACA,QAAQ,UAAsC;EAAE,MAAM;EAC1D;CAAK;CACD,aAAa,UAA2C;EAAE,MAAM;EACpE;CAAK;CACD,UAAU,WAAmE;EAAE,MAAM;EACzF;CAAM;CACF,gBAAsC,EAAE,MAAM,UAAU;CACxD,kBAA0C,EAAE,MAAM,YAAY;AAClE;;;;;;;;AC3OA,IAAa,iBAAb,MAAa,uBAAuB,eAAe;;CAE/C;CAEA,YAAY,SAAiB,UAAkB;EAC3C,MAAM,SAAS;GAAE,QAAQ;GAAK,MAAM;EAAgB,CAAC;EACrD,KAAK,OAAO;EACZ,KAAK,WAAW;EAGhB,OAAO,eAAe,MAAM,eAAe,SAAS;CACxD;AACJ;;;;;;;;;;;;;;;;;AAkBA,SAAgB,uBACZ,UACA,OAAqD,CAAC,GAChD;CACN,MAAM,WAAW,KAAK,YAAA;CACtB,IAAI,YAAY,QAAQ,OAAO,QAAQ,CAAC,CAAC,KAAK,MAAM,IAAI;EAGpD,MAAM,SAAS,OAAO,aAAa,WAAW,WAAW,OAAO,OAAO,QAAQ,CAAC,CAAC,KAAK,CAAC;EACvF,IAAI,CAAC,OAAO,UAAU,MAAM,KAAK,SAAS,GACtC,MAAM,IAAI,eACN,sBAAsB,OAAO,QAAQ,EAAE,0CAA0C,SAAS,IAC1F,QACJ;EAEJ,IAAI,SAAS,UACT,MAAM,IAAI,eACN,aAAa,OAAO,2BAA2B,SAAS,oBAAoB,SAAS,qJAGrF,QACJ;EAEJ,OAAO;CACX;CACA,OAAO,KAAK,eACL,KAAK,sBAAA,KACL,KAAK,gBAAA;AAChB"}