@rebasepro/types 0.13.1-canary.gef9608c → 0.14.0

package/dist/controllers/data_driver.d.ts

@@ -1,3 +1,4 @@
+import { RebaseApiError } from "../errors";
 import type { EntityStatus, EntityValues } from "../types/entities";
 import type { CollectionConfig, FilterValues } from "../types/collections";
 import type { RebaseCallContext } from "../call_context";
@@ -37,7 +38,7 @@ export interface VectorSearchParams {
 export declare const DEFAULT_LIST_LIMIT = 50;
 /** Rows returned for a vector-search list read when the client sends no `limit`. */
 export declare const DEFAULT_VECTOR_LIST_LIMIT = 10;
-/** Hard ceiling clamped onto any client-supplied `limit`, on every surface. */
+/** Largest `limit` a client may ask for on any surface. Above it, the read is refused. */
 export declare const MAX_LIST_LIMIT = 1000;
 /** Overridable bounds for {@link resolveClientListLimit}. */
 export interface ListLimitBounds {
@@ -45,19 +46,36 @@ export interface ListLimitBounds {
     defaultLimit?: number;
     /** Default page size for vector-search reads. */
     vectorDefaultLimit?: number;
-    /** Upper bound clamped onto any client-supplied limit. */
+    /** Largest limit a client may ask for. A larger one is rejected, not clamped. */
     maxLimit?: number;
 }
+/**
+ * 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
+ */
+export declare class ListLimitError extends RebaseApiError {
+    /** The ceiling that was exceeded — what the caller should page by instead. */
+    readonly maxLimit: number;
+    constructor(message: string, maxLimit: number);
+}
 /**
  * Resolve a client-supplied list `limit` into a safe, always-defined value.
  *
- * - A provided limit is coerced to an integer and clamped to `[1, maxLimit]`,
- *   so `0`, negatives, and absurd values can never bypass the cap.
- * - An absent / blank / non-numeric limit falls back to the mode default:
+ * - 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.
  */
 export declare function resolveClientListLimit(rawLimit: number | string | null | undefined, opts?: ListLimitBounds & {
     vectorSearch?: boolean;
@@ -82,6 +100,8 @@ export interface FetchCollectionProps<M extends Record<string, unknown> = Record
     startAfter?: unknown;
     orderBy?: string;
     searchString?: string;
+    /** Ask each row which declared search field matched — populates `_matches`. */
+    searchExplain?: boolean;
     order?: "desc" | "asc";
     /** Vector similarity search configuration */
     vectorSearch?: VectorSearchParams;
@@ -128,6 +148,25 @@ export interface SaveManyProps<M extends Record<string, unknown> = Record<string
     /** Apply every row as INSERT ... ON CONFLICT DO UPDATE. See {@link SaveProps.upsert}. */
     upsert?: boolean;
 }
+/**
+ * @internal
+ */
+export interface UpdateManyProps<M extends Record<string, unknown> = Record<string, unknown>> {
+    path: string;
+    /**
+     * The rows to update, each named by its address.
+     *
+     * Distinct from {@link SaveManyProps.rows}, which carries keys *inside* the
+     * values and is insert-shaped — `saveMany` passes `status: "new"` and no
+     * `id`, so it cannot express "update exactly this row". This can, and it is
+     * why bulk update is a separate driver method rather than a flag on that one.
+     */
+    updates: {
+        id: string | number;
+        values: Partial<EntityValues<M>>;
+    }[];
+    collection?: CollectionConfig<M>;
+}
 /**
  * @internal
  */
@@ -139,6 +178,14 @@ export interface DeleteProps<M extends Record<string, unknown> = Record<string,
     };
     collection?: CollectionConfig<M>;
 }
+/**
+ * @internal
+ */
+export interface DeleteManyProps<M extends Record<string, unknown> = Record<string, unknown>> {
+    path: string;
+    ids: (string | number)[];
+    collection?: CollectionConfig<M>;
+}
 export type FilterCombinationValidProps = {
     path: string;
     databaseId?: string;
@@ -211,9 +258,51 @@ export interface DataDriver {
      */
     saveMany?<M extends Record<string, unknown> = Record<string, unknown>>(props: SaveManyProps<M>): Promise<Record<string, unknown>[]>;
     /**
-     * Delete a entity
-     * @param props
-     * @return was the whole deletion flow successful
+     * Update many rows in one transaction, each addressed by id.
+     *
+     * Optional for the same reason `saveMany` is: a driver that cannot make the
+     * batch atomic should not pretend to. The REST layer reports
+     * `BULK_UNSUPPORTED` rather than silently falling back to a loop of single
+     * writes, which would be neither atomic nor one round trip — the two things
+     * a caller reaches for a batch to get.
+     */
+    updateMany?<M extends Record<string, unknown> = Record<string, unknown>>(props: UpdateManyProps<M>): Promise<Record<string, unknown>[]>;
+    /**
+     * Delete the row `props.row` addresses.
+     *
+     * **Resolving means the row is gone because this call removed it.** A
+     * delete that matched nothing must reject with a not-found error
+     * (`ApiError.notFound`, `statusCode: 404`) rather than resolving quietly.
+     *
+     * The rule is here rather than in each driver because the two
+     * implementations answered differently and each had a test pinning its own
+     * habit: Postgres threw, Mongo logged a warning and resolved. Three things
+     * decide it in favour of rejecting.
+     *
+     * The REST layer already says 404 — `DELETE /api/data/<c>/<id>` reads the
+     * row before removing it — so a quiet resolve made the driver API disagree
+     * with the HTTP API about the same operation, and only in-process
+     * `rebase.data` callers could see the difference.
+     *
+     * A caller cannot tell "deleted" from "there was nothing there" without it,
+     * and those are different facts: one means the caller's model of the data
+     * was right, the other that it was stale. Silence hands back the wrong one
+     * and the caller carries on.
+     *
+     * And on a driver with row-level security, "matched nothing" is *also* how
+     * a policy refusal arrives — Postgres filters `DELETE` through `USING`
+     * rather than raising. A driver that resolves on zero rows therefore
+     * reports a refused delete as a completed one, which is the defect
+     * `explainZeroRowWrite` exists to prevent (see `write-denial.ts`).
+     *
+     * Conformance for both server drivers lives in
+     * `packages/server/test/contract/delete-contract.ts`, run by each driver's
+     * own suite against its own database. `packages/firebase`'s Firestore
+     * driver does not honour it: `deleteDoc` resolves for a missing document
+     * and reporting otherwise would cost a read on every delete. It runs in the
+     * browser against Firestore's own semantics rather than behind
+     * `rebase.data`, and that exception is stated here rather than left to be
+     * discovered.
      */
     delete<M extends Record<string, unknown> = Record<string, unknown>>(props: DeleteProps<M>): Promise<void>;
     /**
@@ -221,6 +310,13 @@ export interface DataDriver {
      * @param path Collection path
      */
     deleteAll?(path: string): Promise<void>;
+    /**
+     * Delete many rows in one transaction, addressed by id.
+     *
+     * Ids rather than a filter, deliberately — see
+     * {@link SDKCollectionClient.deleteMany}. Optional, as `saveMany` is.
+     */
+    deleteMany?<M extends Record<string, unknown> = Record<string, unknown>>(props: DeleteManyProps<M>): Promise<void>;
     /**
      * Check if the given property is unique in the given collection
      * @param path Collection path
@@ -303,6 +399,8 @@ export interface RestFetchService {
         offset?: number;
         startAfter?: Record<string, unknown>;
         searchString?: string;
+        /** Ask each row which declared search fields matched — populates `_matches`. */
+        searchExplain?: boolean;
         databaseId?: string;
         vectorSearch?: VectorSearchParams;
     }, include?: string[]): Promise<Record<string, unknown>[]>;

package/dist/errors.d.ts

@@ -1,3 +1,29 @@
+/**
+ * The error codes every route can produce, as `RebaseApiError.code`.
+ *
+ * These are the defaults on `ApiError`'s static constructors server-side, so
+ * any endpoint can answer with one. They are **not** the complete set: routes
+ * pass their own more specific codes too (`EMAIL_EXISTS`, `TOKEN_EXPIRED`,
+ * `INVALID_BULK_BODY`, …), and auth alone defines a couple of dozen.
+ *
+ * Hence the union is deliberately open rather than closed. It exists to give
+ * autocomplete and to catch a typo in the common cases — `code` was a bare
+ * `string`, so `e.code === "NOT_FOUND"` and `e.code === "NOTFOUND"` were
+ * equally valid and only one of them worked. Closing it would be a lie that
+ * broke the moment a route added a code.
+ *
+ * @example
+ * if (e instanceof RebaseApiError) {
+ *   switch (e.code) {
+ *     case "NOT_FOUND": return null;          // completed
+ *     case "FORBIDDEN": return redirect();
+ *     default: throw e;                       // routes' own codes land here
+ *   }
+ * }
+ *
+ * @group Errors
+ */
+export type RebaseErrorCode = "BAD_REQUEST" | "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "CONFLICT" | "INTERNAL_ERROR" | "SERVICE_UNAVAILABLE" | "DB_PERMISSION_DENIED" | "SCHEMA_DRIFT" | (string & {});
 /**
  * Structured initializer for {@link RebaseApiError}.
  *
@@ -10,8 +36,8 @@ export interface RebaseErrorInit {
      * logic errors that have no HTTP status.
      */
     status?: number;
-    /** Stable, machine-readable error code (e.g. `"NOT_FOUND"`, `"BAD_REQUEST"`). */
-    code?: string;
+    /** Stable, machine-readable error code. See {@link RebaseErrorCode}. */
+    code?: RebaseErrorCode;
     /** Structured error payload returned by the server, when present. */
     details?: unknown;
     /** The underlying error this one wraps, if any. */
@@ -44,8 +70,8 @@ export interface RebaseErrorInit {
 export declare class RebaseApiError extends Error {
     /** HTTP status code, or `undefined` for non-HTTP errors. */
     readonly status?: number;
-    /** Stable machine-readable error code, when the server supplied one. */
-    readonly code?: string;
+    /** Stable machine-readable error code, when the server supplied one. See {@link RebaseErrorCode}. */
+    readonly code?: RebaseErrorCode;
     /** Structured error payload from the server, when present. */
     readonly details?: unknown;
     constructor(message: string, init?: RebaseErrorInit);

package/dist/index.es.js

@@ -26,7 +26,7 @@
 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. */
+	/** Stable machine-readable error code, when the server supplied one. See {@link RebaseErrorCode}. */
 	code;
 	/** Structured error payload from the server, when present. */
 	details;
@@ -250,6 +250,19 @@ var ALL_WHERE_FILTER_OPS = [
 /** All canonical operator strings for runtime validation. */
 var CANONICAL_OPS = new Set(ALL_WHERE_FILTER_OPS);
 /**
+* The REST table as a `Map`, because the key `toCanonicalOp` is handed comes
+* off the wire.
+*
+* Indexed as a plain object, every `Object.prototype` member answered:
+* `toCanonicalOp("valueOf")` returned the inherited *function* as though it
+* were a `WhereFilterOp`, and every caller here treats a defined result as
+* "known operator". Same defect the REST codec's own lookup tables were
+* converted away from in `filter-dialect.ts`; this is the copy that survived
+* one package over, and it now sits under the operator validation the REST
+* parser does, which would otherwise have admitted `["constructor", x]`.
+*/
+var REST_OP_LOOKUP = new Map(Object.entries(REST_TO_CANONICAL));
+/**
 * Resolve any operator string (canonical or REST short-code) to its
 * canonical `WhereFilterOp` form. Returns `undefined` for unknown operators.
 *
@@ -261,7 +274,7 @@ var CANONICAL_OPS = new Set(ALL_WHERE_FILTER_OPS);
 */
 function toCanonicalOp(op) {
 	if (CANONICAL_OPS.has(op)) return op;
-	return REST_TO_CANONICAL[op];
+	return REST_OP_LOOKUP.get(op);
 }
 //#endregion
 //#region src/types/admin_block.ts
@@ -318,6 +331,7 @@ var ADMIN_COLLECTION_KEYS = [
 	"formAutoSave",
 	"formView",
 	"group",
+	"hideFromEntityViews",
 	"hideFromNavigation",
 	"hideIdFromCollection",
 	"hideIdFromForm",
@@ -382,6 +396,64 @@ var ADMIN_PROPERTY_KEYS = [
 	"urlPreview",
 	"widget"
 ];
+/**
+* Move flattened admin keys back down into the `admin` block.
+*
+* The admin panel works with a *flat* view model — the block merged onto the
+* collection — so what comes back from a form has `icon` and `defaultViewMode`
+* at the top level while `admin` still holds whatever the file was loaded with.
+* This is the way back.
+*
+* **The top-level value wins.** It is the one the form just wrote; the block is
+* the copy the collection was loaded with, and preferring it resolves every edit
+* in favour of the value the user changed away from.
+*
+* This lives here, next to the key lists, because it had two implementations —
+* `toAdminCollectionConfig` in `@rebasepro/admin-types` and `nestAdminKeys` in
+* `@rebasepro/server`'s schema editor — that agreed on everything except that
+* precedence, which is the only part that decides whether a save is visible.
+*
+* @group Models
+*/
+function nestAdminKeysOf(source, adminKeys) {
+	const keys = new Set(adminKeys);
+	const top = {};
+	const block = { ...source.admin ?? {} };
+	for (const [key, value] of Object.entries(source)) {
+		if (key === "admin") continue;
+		if (keys.has(key)) block[key] = value;
+		else top[key] = value;
+	}
+	if (Object.keys(block).length > 0) top.admin = block;
+	return top;
+}
+/**
+* {@link nestAdminKeysOf} for a collection.
+*
+* @group Models
+*/
+function nestAdminCollectionKeys(collection) {
+	return nestAdminKeysOf(collection, ADMIN_COLLECTION_KEYS);
+}
+/**
+* {@link nestAdminKeysOf} for a property, applied to its children too.
+*
+* A map property carries `properties`, an array property carries `of`, and both
+* hold properties with `admin` blocks of their own. A flat `readOnly` left on a
+* child is as dead — and as fatal at the next boot — as one left on the parent,
+* so the walk goes all the way down.
+*
+* @group Models
+*/
+function nestAdminPropertyKeys(property) {
+	const nested = nestAdminKeysOf(property, ADMIN_PROPERTY_KEYS);
+	const children = nested.properties;
+	if (children && typeof children === "object" && !Array.isArray(children)) nested.properties = Object.fromEntries(Object.entries(children).map(([key, child]) => [key, child && typeof child === "object" && !Array.isArray(child) ? nestAdminPropertyKeys(child) : child]));
+	const of = nested.of;
+	if (Array.isArray(of)) nested.of = of.map((entry) => entry && typeof entry === "object" && !Array.isArray(entry) ? nestAdminPropertyKeys(entry) : entry);
+	else if (of && typeof of === "object") nested.of = nestAdminPropertyKeys(of);
+	return nested;
+}
 //#endregion
 //#region src/types/data_source.ts
 /**
@@ -578,6 +650,22 @@ function getDeclaredSubcollections(collection) {
 	return collection.subcollections;
 }
 //#endregion
+//#region src/types/search.ts
+/** The column name used when {@link SearchConfig.column} is not given. */
+var DEFAULT_SEARCH_COLUMN = "search_vector";
+/** The text search configuration used when {@link SearchConfig.language} is not given. */
+var DEFAULT_SEARCH_LANGUAGE = "simple";
+/** The weight a field carries when it does not name one. */
+var DEFAULT_SEARCH_WEIGHT = "B";
+/** The similarity floor used when {@link SearchConfig.fuzzyThreshold} is not given. */
+var DEFAULT_FUZZY_THRESHOLD = .3;
+/**
+* The relevance sort key. Valid only on a collection that declares a
+* {@link SearchConfig} *and* on a query that carries a search string; anywhere
+* else it is an unknown field and the request is refused.
+*/
+var RELEVANCE_SORT_FIELD = "_score";
+//#endregion
 //#region src/types/relations.ts
 /** @group Models */
 function hasForeignKeyOnTarget(relation) {
@@ -594,7 +682,7 @@ function isToMany(relation) {
 //#endregion
 //#region src/types/policy.ts
 /**
-* The id a request without a logged-in user reports as `auth.uid()`.
+* 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
@@ -602,7 +690,7 @@ function isToMany(relation) {
 * therefore substitutes this sentinel at the single chokepoint where the GUC
 * is set.
 *
-* The consequence for policy authors is that **`auth.uid() IS NOT NULL` is a
+* 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
@@ -619,7 +707,7 @@ var ANONYMOUS_USER_ID = "anonymous";
 * 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
-* `auth.uid() <> 'anonymous'`, was *true* for an anonymous visitor. The
+* `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.
 *
@@ -701,6 +789,96 @@ var policy = {
 	authRoles: () => ({ kind: "authRoles" })
 };
 //#endregion
+//#region src/types/rls-functions.ts
+/**
+* The SQL helper functions RLS policies call, and the schema they live in.
+*
+* ## One schema, and it is ours
+*
+* Rebase creates exactly one schema in a project's database: `rebase`. These
+* three functions live in it alongside the framework's own tables, and that is
+* the whole contract — a reader can look at a database and know precisely which
+* namespace belongs to the framework and that nothing else was touched.
+*
+* It used to be two. `uid()`, `jwt()` and `roles()` sat in a schema called
+* `auth`, which is Supabase's name, chosen so that a developer who had written
+* Supabase RLS would recognise `auth.uid()`. The familiarity was real but the
+* name was not Rebase's to take, and taking it had a concrete cost: pointing
+* Rebase at a database that already had a Supabase `auth` schema meant
+* `CREATE OR REPLACE FUNCTION auth.uid() RETURNS text` against Supabase's
+* `RETURNS uuid`, which Postgres rejects outright —
+*
+*     ERROR:  cannot change return type of existing function
+*     HINT:   Use DROP FUNCTION auth.uid() first.
+*
+* — and the failure landed inside a catch-all that logged a warning and carried
+* on, leaving a database with auth tables, no helper functions, and policies
+* calling functions that did not exist. Under `rebase db migrate` the same
+* statements aborted the migration instead.
+*
+* `rebase.uid()` collides with nobody. A Supabase database keeps its `auth`
+* schema untouched and gains a `rebase` one, which is what a gradual migration
+* needs.
+*
+* ## Why functions at all, rather than inlining `current_setting`
+*
+* Because the indirection has already been spent once. `uid()` resolves
+* `app.uid` and falls back to the pre-rename `app.user_id`, so that during a
+* rolling deploy — old and new pods serving one database — both eras resolve
+* the principal. That was a single `CREATE OR REPLACE`. Inlined into policy
+* bodies it would have been a rewrite of every policy on every table.
+*
+* ## Why the name is not configurable
+*
+* A policy body is stored SQL: Postgres parses `USING (…)` once and keeps it, so
+* these strings are written into every policy in every database Rebase has
+* provisioned. Everything that reads policies back — the SQL-to-policy parser
+* behind the admin UI, the drift checker, `rls-check` — would have to know the
+* configured value to recognise its own output. One frozen name is the feature.
+*/
+/** The schema Rebase owns. The only schema Rebase creates. */
+var REBASE_SCHEMA = "rebase";
+/**
+* The principal of the current request, as text, or NULL in the server context.
+*
+* Never NULL for a user request — an anonymous one carries
+* {@link ANONYMOUS_USER_ID} — which is what makes `IS NULL` a reliable test for
+* the trusted server plane and `IS NOT NULL` a tautology.
+*/
+var RLS_UID_SQL = `${REBASE_SCHEMA}.uid()`;
+/** The request's roles as a comma-separated string, for `string_to_array`. */
+var RLS_ROLES_SQL = `${REBASE_SCHEMA}.roles()`;
+/** The request's JWT claims as `jsonb`, or `{}`. */
+var RLS_JWT_SQL = `${REBASE_SCHEMA}.jwt()`;
+/**
+* The pre-1.0 spellings, for recognising policies and hand-written SQL that
+* predate the move.
+*
+* Kept because policies outlive the server that wrote them: a database migrated
+* by an older release still holds `auth.uid()` in its policy bodies until the
+* next push or boot recompiles them, and anything that reads policies back has
+* to recognise both eras or report the framework's own output as foreign drift.
+* Also used to give a project whose `securityRules` contain raw `auth.uid()` a
+* message naming the replacement, instead of a parse failure.
+*/
+var LEGACY_RLS_SCHEMA = "auth";
+var LEGACY_RLS_UID_SQL = `${LEGACY_RLS_SCHEMA}.uid()`;
+var LEGACY_RLS_ROLES_SQL = `${LEGACY_RLS_SCHEMA}.roles()`;
+var LEGACY_RLS_JWT_SQL = `${LEGACY_RLS_SCHEMA}.jwt()`;
+/**
+* Rewrites the pre-1.0 function calls in a fragment of policy SQL.
+*
+* Deliberately anchored on a word boundary and the schema qualifier, so a column
+* called `auth_uid` or a table named `auth` is left alone.
+*/
+function rewriteLegacyRlsFunctions(sql) {
+	return sql.replace(/\bauth\.(uid|jwt|roles)\s*\(\s*\)/gi, (_match, fn) => `${REBASE_SCHEMA}.${fn.toLowerCase()}()`);
+}
+/** Whether a fragment of SQL still calls the pre-1.0 functions. */
+function usesLegacyRlsFunctions(sql) {
+	return /\bauth\.(uid|jwt|roles)\s*\(\s*\)/i.test(sql);
+}
+//#endregion
 //#region src/types/backend.ts
 /**
 * Type guard: does this admin support SQL operations?
@@ -1132,24 +1310,51 @@ function computeSchemaVersion(collections) {
 var DEFAULT_LIST_LIMIT = 50;
 /** Rows returned for a vector-search list read when the client sends no `limit`. */
 var DEFAULT_VECTOR_LIST_LIMIT = 10;
-/** Hard ceiling clamped onto any client-supplied `limit`, on every surface. */
+/** Largest `limit` a client may ask for on any surface. Above it, the read is refused. */
 var MAX_LIST_LIMIT = 1e3;
 /**
+* 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.
 *
-* - A provided limit is coerced to an integer and clamped to `[1, maxLimit]`,
-*   so `0`, negatives, and absurd values can never bypass the cap.
-* - An absent / blank / non-numeric limit falls back to the mode default:
+* - 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 : parseInt(String(rawLimit), 10);
-		if (Number.isFinite(parsed)) return Math.min(Math.max(1, Math.floor(parsed)), maxLimit);
+		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;
 }
@@ -1181,6 +1386,6 @@ function isPublicStoragePath(path) {
 	return p.startsWith("public/") || p.startsWith(`default/public/`);
 }
 //#endregion
-export { ADMIN_COLLECTION_KEYS, ADMIN_PROPERTY_KEYS, ALL_WHERE_FILTER_OPS, ANONYMOUS_USER_ID, ANONYMOUS_USER_IDS, BUNDLE_FORMAT_VERSION, CANONICAL_TO_REST, DEFAULT_CAPABILITIES, DEFAULT_DATA_SOURCE_KEY, DEFAULT_FILTERABLE_RELATION_KINDS, DEFAULT_LIST_LIMIT, DEFAULT_STORAGE_SOURCE_KEY, DEFAULT_VECTOR_LIST_LIMIT, EntityReference, EntityRelation, FIREBASE_CAPABILITIES, GeoPoint, MAX_LIST_LIMIT, MONGODB_CAPABILITIES, NULL_OPS, POSTGRES_CAPABILITIES, PUBLIC_STORAGE_PREFIX, REST_TO_CANONICAL, RUNTIME_CONTRACT_VERSION, RebaseApiError, RebaseClientError, SCHEMA_VERSION_HEADER, Vector, canonicalSchemaPayload, computeSchemaVersion, deserializeCollections, findStorageSuffixCollision, getCollectionDataPath, getDataSourceCapabilities, getDeclaredSubcollections, hasForeignKeyOnTarget, isAnonymousUid, isBranchAdmin, isChannelBusInstance, isDocumentAdmin, isFirebaseCollectionConfig, isLazyComponentRef, isManyToMany, isMongoDBCollectionConfig, isPostgresCollectionConfig, isPublicStoragePath, isRelationalCollectionConfig, isSQLAdmin, isSchemaAdmin, isSerializedCollectionRef, isToMany, normalizeStorageSources, policy, registerDataSourceCapabilities, resolveClientListLimit, serializeCollections, storageEnvSuffix, toCanonicalOp };
+export { ADMIN_COLLECTION_KEYS, ADMIN_PROPERTY_KEYS, ALL_WHERE_FILTER_OPS, ANONYMOUS_USER_ID, ANONYMOUS_USER_IDS, BUNDLE_FORMAT_VERSION, CANONICAL_TO_REST, DEFAULT_CAPABILITIES, DEFAULT_DATA_SOURCE_KEY, DEFAULT_FILTERABLE_RELATION_KINDS, DEFAULT_FUZZY_THRESHOLD, DEFAULT_LIST_LIMIT, DEFAULT_SEARCH_COLUMN, DEFAULT_SEARCH_LANGUAGE, DEFAULT_SEARCH_WEIGHT, DEFAULT_STORAGE_SOURCE_KEY, DEFAULT_VECTOR_LIST_LIMIT, EntityReference, EntityRelation, FIREBASE_CAPABILITIES, GeoPoint, LEGACY_RLS_JWT_SQL, LEGACY_RLS_ROLES_SQL, LEGACY_RLS_SCHEMA, LEGACY_RLS_UID_SQL, ListLimitError, MAX_LIST_LIMIT, MONGODB_CAPABILITIES, NULL_OPS, POSTGRES_CAPABILITIES, PUBLIC_STORAGE_PREFIX, REBASE_SCHEMA, RELEVANCE_SORT_FIELD, REST_TO_CANONICAL, RLS_JWT_SQL, RLS_ROLES_SQL, RLS_UID_SQL, RUNTIME_CONTRACT_VERSION, RebaseApiError, RebaseClientError, SCHEMA_VERSION_HEADER, Vector, canonicalSchemaPayload, computeSchemaVersion, deserializeCollections, findStorageSuffixCollision, getCollectionDataPath, getDataSourceCapabilities, getDeclaredSubcollections, hasForeignKeyOnTarget, isAnonymousUid, isBranchAdmin, isChannelBusInstance, isDocumentAdmin, isFirebaseCollectionConfig, isLazyComponentRef, isManyToMany, isMongoDBCollectionConfig, isPostgresCollectionConfig, isPublicStoragePath, isRelationalCollectionConfig, isSQLAdmin, isSchemaAdmin, isSerializedCollectionRef, isToMany, nestAdminCollectionKeys, nestAdminKeysOf, nestAdminPropertyKeys, normalizeStorageSources, policy, registerDataSourceCapabilities, resolveClientListLimit, rewriteLegacyRlsFunctions, serializeCollections, storageEnvSuffix, toCanonicalOp, usesLegacyRlsFunctions };
 
 //# sourceMappingURL=index.es.js.map