@rebasepro/common 0.17.3 → 0.18.1

package/dist/index.es.js

@@ -1,4 +1,4 @@
-import { ALL_WHERE_FILTER_OPS, ANONYMOUS_USER_ID, ANONYMOUS_USER_IDS, CANONICAL_TO_REST, DEFAULT_DATA_SOURCE_KEY, DEFAULT_LIST_LIMIT, EntityReference, EntityRelation, NULL_OPS, REST_TO_CANONICAL, RLS_ROLES_SQL, RLS_UID_SQL, getDataSourceCapabilities, getDeclaredSubcollections, isAnonymousUid, isManyToMany, isPostgresCollectionConfig, isRelationAggregateSort, isRelationalCollectionConfig, policy, rewriteLegacyRlsFunctions, sortKeyToString, toCanonicalOp } from "@rebasepro/types";
+import { ALL_WHERE_FILTER_OPS, ANONYMOUS_USER_ID, ANONYMOUS_USER_IDS, CANONICAL_TO_REST, DEFAULT_DATA_SOURCE_KEY, DEFAULT_LIST_LIMIT, EntityReference, EntityRelation, NULL_OPS, REST_TO_CANONICAL, RLS_IS_ANONYMOUS_SQL, RLS_ROLES_SQL, RLS_UID_SQL, RebaseApiError, getDataSourceCapabilities, getDeclaredSubcollections, isAnonymousUid, isManyToMany, isPostgresCollectionConfig, isRelationAggregateSort, isRelationalCollectionConfig, isUnsupported, policy, resolveResourceRefs, rewriteLegacyRlsFunctions, sortKeyToString, toCanonicalOp, unsupportedMethod } from "@rebasepro/types";
 import { deepClone, firstFreeKey, generateForeignKeyName, getIn, getPolicyNamesForRules, getPolicyOperations, isDefaultFieldConfigId, mergeDeep, prettifyIdentifier, randomString, removeFunctions, toSnakeCase, toWireKey } from "@rebasepro/utils";
 import jsonLogic from "json-logic-js";
 import { deepEqual } from "fast-equals";
@@ -490,8 +490,7 @@ function resolveRelation(relation, sourceCollection, propertyKey) {
 		targetSlug: targetCollection.slug,
 		onUpdate: relation.onUpdate,
 		onDelete: relation.onDelete,
-		overrides: relation.overrides,
-		validation: relation.validation
+		overrides: relation.overrides
 	};
 	const sourceName = toSnakeCase(sourceCollection.slug ?? sourceCollection.name);
 	switch (relation.kind) {
@@ -669,6 +668,45 @@ function resolveCollectionRelations(collection) {
 	return relations;
 }
 /**
+* The `type: "relation"` property that declares a link, or `undefined` for one
+* that only exists in the collection's `relations` array.
+*
+* Both declaration sites end up in {@link resolveCollectionRelations}, and only
+* one of them has a property to carry field-level facts — `name`, `admin`, and
+* the one this exists for, `validation.required`.
+*/
+function relationDeclaringProperty(collection, relation) {
+	const resolved = resolveCollectionRelations(collection);
+	for (const [key, raw] of Object.entries(collection.properties ?? {})) {
+		const prop = raw;
+		if (prop?.type !== "relation") continue;
+		if (resolved[key] === relation) return prop;
+		const addressed = prop.relation?.relationName;
+		if (addressed && findRelation(resolved, addressed) === relation) return prop;
+	}
+}
+/**
+* Must every row of this collection point at a target through this link?
+*
+* Read from the declaring property's `validation.required` — the same key every
+* other field uses, and the only place it lives.
+*
+* `RelationBase` carried its own `validation.required` until 0.18, which made
+* this two questions rather than one. They were answered by different readers:
+* the Postgres DDL generator asked the property (so the foreign-key column was
+* `NOT NULL`) and the SDK type generator asked the relation (so the generated
+* `Insert` type made the field optional). A `create()` that left the relation
+* out therefore typechecked and then failed at the database with a not-null
+* violation, and the two `required`s had to be written twice, identically, for
+* the pair to agree.
+*
+* A relation with no declaring property — an entry in `relations` nothing
+* points at — is not required. There is no field to fill in.
+*/
+function isRelationRequired(collection, relation) {
+	return Boolean(relationDeclaringProperty(collection, relation)?.validation?.required);
+}
+/**
 * The path of the collection a relation property points at, derived from the
 * property alone.
 *
@@ -695,9 +733,21 @@ function getRelationTargetPath(property) {
 		return;
 	}
 }
+/**
+* The table a collection reads and writes.
+*
+* `table` when it is set, otherwise `toSnakeCase(slug)` — which is what made it
+* safe to drop `table` from the required fields on the config type: the runtime
+* had always derived it, and the type was demanding a value it did not need.
+*
+* The `||` chain is load-bearing. `toSnakeCase(undefined)` returns `""`, not
+* `undefined`, so the previous `??` chain short-circuited on the empty string
+* and the name fallback could never run — a safety net that read like one and
+* caught nothing. It was unreachable while `slug` was required; it stops being
+* unreachable the moment anything constructs a config without one.
+*/
 function getTableName(collection) {
-	if (isRelationalCollectionConfig(collection)) return collection.table ?? toSnakeCase(collection.slug) ?? toSnakeCase(collection.name);
-	return toSnakeCase(collection.slug) ?? toSnakeCase(collection.name);
+	return (isRelationalCollectionConfig(collection) ? collection.table : void 0) || toSnakeCase(collection.slug) || toSnakeCase(collection.name);
 }
 /**
 * A JavaScript identifier: what a generated `export const <name> =` needs.
@@ -1483,6 +1533,7 @@ function compile(expr, scope) {
 		case "rolesOverlap": return `string_to_array(${RLS_ROLES_SQL}, ',') && ${rolesArraySql(expr.roles)}`;
 		case "rolesContain": return `string_to_array(${RLS_ROLES_SQL}, ',') @> ${rolesArraySql(expr.roles)}`;
 		case "authenticated": return `${RLS_UID_SQL} IS NOT NULL AND ${RLS_UID_SQL} NOT IN (${ANONYMOUS_USER_IDS.map(quoteLiteral).join(", ")})`;
+		case "registered": return `${RLS_UID_SQL} IS NOT NULL AND ${RLS_UID_SQL} NOT IN (${ANONYMOUS_USER_IDS.map(quoteLiteral).join(", ")}) AND NOT ${RLS_IS_ANONYMOUS_SQL}`;
 		case "serverContext": return `${RLS_UID_SQL} IS NULL`;
 		case "existsIn": return compileExistsIn(expr, scope);
 		case "raw": return rewriteLegacyRlsFunctions(expr.sql).replace(/\{(\w+)\}/g, (_, col) => `${outerQualifier(scope)}${resolveColumnName(col, scope.outerCollection)}`);
@@ -1719,6 +1770,7 @@ function evaluatePolicy(expr, ctx) {
 			return expr.roles.every((r) => r === "public" || userRoles.includes(r));
 		}
 		case "authenticated": return ctx.uid != null && !isAnonymousUid(ctx.uid);
+		case "registered": return ctx.uid != null && !isAnonymousUid(ctx.uid) && ctx.isAnonymous !== true;
 		case "serverContext": return false;
 		case "existsIn": return "unknown";
 		case "raw": return "unknown";
@@ -1895,11 +1947,13 @@ function canDeleteEntity(collection, authContext, path, entity) {
 //#endregion
 //#region src/util/builders.ts
 /**
-* Implementation — delegates to the correct overload at the type level.
-* At runtime this is a plain identity function.
+* At runtime this is a plain identity function: a resource handle written where
+* a key belongs — `dataSource: analytics` — becomes its key, so past this point
+* a collection is plain data. The signature above is the rest of the point.
+* @group Builder
 */
 function defineCollection(collection) {
-	return collection;
+	return resolveResourceRefs(collection);
 }
 //#endregion
 //#region src/util/storage.ts
@@ -2055,6 +2109,107 @@ var buildPropertyCallbacks = (properties) => {
 	return Object.keys(propertyCallbacks).length > 0 ? propertyCallbacks : void 0;
 };
 //#endregion
+//#region src/util/callback-errors.ts
+/**
+* The code a write carries when a collection callback rejected it and did not
+* say how. Distinct from `INVALID_INPUT`, which the framework's own validation
+* raises: this one means *your* rule refused, so the message is the author's.
+*
+* `details.stage` names which callback refused — `beforeSave`, `beforeDelete`,
+* `afterSave` or `afterDelete`. An `after*` hook runs inside the write's
+* transaction, so a throw there rolls the row back too; the caller is told the
+* write did not happen and which hook decided that.
+*/
+var CALLBACK_REJECTED = "CALLBACK_REJECTED";
+/**
+* Turn whatever a user callback threw into something the API layer can answer
+* with.
+*
+* ### Why a plain `throw` has to mean 400
+*
+* Both `docs/collections/callbacks.md` ("Throw an error to **block the save**")
+* and `docs/backend/hooks.md` ("the operation is rejected with an HTTP 400
+* error response") promised this, and neither delivered it: an `Error` thrown
+* from `beforeSave` reached the client as
+*
+*     500 {"error":{"message":"Internal Server Error","code":"INTERNAL_ERROR"}}
+*
+* with the author's message visible only in the server log, because the error
+* normalizer masks 5xx bodies — correctly, since a 500 is by definition
+* something the caller must not be told about.
+*
+* But a callback is not the server failing. It is the application speaking, in
+* code its author wrote, about a request its author judged invalid. The
+* conservative reading — "an unrecognised throw might be a real bug, so 500" —
+* costs every validation rule its message and makes the documented example
+* wrong. A rule that wants a 500 can still raise one explicitly.
+*
+* ### Why `after*` comes through here too
+*
+* `afterSave` and `afterDelete` run inside the write's transaction and are
+* awaited, so a throw in one aborts the transaction: the row is not there when
+* the request ends. Left unconverted, the caller saw a 500 for a write that a
+* rule deliberately undid, and had no way to tell that from a database outage.
+* Converted, it is the same 400 `CALLBACK_REJECTED` a `before*` hook produces,
+* with `stage` naming the hook that refused.
+*
+* ### What passes through untouched
+*
+* Anything that already carries a status: `RebaseApiError` from
+* `@rebasepro/types` (the browser-safe class a `config/collections/*.ts` file
+* can import — the collection file is bundled into the admin SPA, so it may not
+* import the server package), and the server's own `ApiError`, recognised
+* structurally rather than by `instanceof` because a monorepo can resolve two
+* copies of a package and `instanceof` is false across them.
+*
+* @param error What the callback threw.
+* @param stage The callback name, for the log line.
+* @param path  The collection path, for the log line.
+*/
+function toCallbackError(error, stage, path) {
+	if (error !== null && typeof error === "object") {
+		const carried = error;
+		if (typeof carried.statusCode === "number" || typeof carried.status === "number") return error;
+	}
+	return new RebaseApiError(error instanceof Error ? error.message : typeof error === "string" ? error : `${stage} rejected the write`, {
+		status: 400,
+		code: CALLBACK_REJECTED,
+		details: {
+			stage,
+			path
+		},
+		cause: error
+	});
+}
+/**
+* The refusal a callback expresses by returning `false` rather than throwing.
+*
+* `beforeDelete` is typed `boolean | void` and documented as "return false or
+* throw to block deletion". Returning `false` did stop the delete — and then the
+* route answered `204 No Content`, which says the row is gone. The admin panel
+* removed it from the list, a client that trusted the status dropped it from its
+* cache, and the next reload brought it back. A veto that reports success is
+* worse than no veto.
+*
+* 403, not the 400 a throw produces: a throw carries the author's message and
+* reads as "this input is wrong", while `false` is a flat refusal with no
+* explanation — the server understood the request and will not perform it. The
+* code is the same either way, so a client can handle both in one branch.
+*
+* @param stage The callback name, for `details.stage`.
+* @param path  The collection path, for `details.path`.
+*/
+function callbackRefusal(stage, path) {
+	return new RebaseApiError(`${stage} refused the operation`, {
+		status: 403,
+		code: CALLBACK_REJECTED,
+		details: {
+			stage,
+			path
+		}
+	});
+}
+//#endregion
 //#region src/util/auth-default-policies.ts
 /**
 * Default RLS policies injected by the schema generator.
@@ -3048,7 +3203,7 @@ var CollectionRegistry = class {
 	dataSources = {};
 	/**
 	* Global lifecycle callbacks applied to every collection.
-	* Runs on all data paths (REST, WebSocket, `rebase.data`).
+	* Runs on all data paths (REST, WebSocket, `rebase.dataAsAdmin`).
 	* Execution order: global → collection → property callbacks.
 	*/
 	_globalCallbacks;
@@ -3186,7 +3341,7 @@ var CollectionRegistry = class {
 			else {
 				const declared = resolveCollectionRelations(collection)[key];
 				if (declared) relationProperty.resolvedRelation = declared;
-				else console.warn(`Relation property '${key}' on '${collection.slug}' declares no \`relation\`, and the collection has no relation of that name.`);
+				else console.warn(`Relation property '${key}' on '${collection.slug}' names no relation: it has no \`relation\` block, and the collection's \`relations\` array has no entry called '${key}'. The field will render no picker, generate no foreign key, and return nothing from \`include()\`.`);
 			}
 		}
 		return newProperty;
@@ -3430,7 +3585,7 @@ function normalizeOrderBy(orderBy) {
 	if (!orderBy || orderBy.length === 0) return void 0;
 	const list = Array.isArray(orderBy[0]) ? orderBy : [orderBy];
 	if (list.length === 0) return void 0;
-	return list.map(([key, direction]) => [sortKeyToString(key), direction]);
+	return list.map((entry, index) => toStrictTuple(entry, index));
 }
 /**
 * The most significant sort key, for a caller that can only express one —
@@ -3533,23 +3688,37 @@ function serializeOrderBy(orderBy) {
 /**
 * Deserialize a wire-format `"field:direction"` string into an {@link OrderByTuple}.
 *
-* Lenient parsing (matches existing server behaviour):
+* Lenient parsing:
 * - Bare field name (no colon): `"name"` → `["name", "asc"]`
 * - Unknown direction: `"name:foo"` → `["name", "asc"]`
-* - Empty / falsy input: → `undefined`
+* - Empty / falsy input, or a blank field name: → `undefined`
+*
+* The leniency is this end's alone; the *server* refuses the same value. This
+* used to say "matches existing server behaviour", and it stopped being true
+* when `parseOrderByParam` grew a strict direction check: `?orderBy=name:foo`
+* now answers `400 INVALID_ORDER_BY` ("entry 0 has direction 'foo'"). The split
+* is deliberate — see {@link parseOrderBySpecStrict} — because a value this
+* function is handed was produced by {@link serializeOrderBy} a moment earlier,
+* and one that reaches the server came from a stranger.
+*
+* A blank field is `undefined` rather than `[" ", "asc"]`: whitespace is not a
+* field name, and the tuple it used to produce could not be re-encoded — the
+* only value in this codec that survived a decode and failed the next encode.
 *
 * Reads the single-key shorthand only. For a value that may carry several keys,
 * use {@link deserializeOrderByList} — handed a JSON array this returns the
 * whole array as one nonsensical field name.
 *
 * @param raw - The wire-format string from an HTTP query parameter.
-* @returns The canonical tuple, or `undefined` if the input is empty/falsy.
+* @returns The canonical tuple, or `undefined` if the input names no field.
 */
 function deserializeOrderBy(raw) {
 	if (!raw) return void 0;
 	const idx = raw.indexOf(":");
-	if (idx === -1) return [raw, "asc"];
-	return [raw.slice(0, idx), raw.slice(idx + 1) === "desc" ? "desc" : "asc"];
+	if (idx === -1) return raw.trim() === "" ? void 0 : [raw, "asc"];
+	const field = raw.slice(0, idx);
+	if (field.trim() === "") return void 0;
+	return [field, raw.slice(idx + 1) === "desc" ? "desc" : "asc"];
 }
 /**
 * Deserialize either wire spelling — the single-key shorthand or the JSON
@@ -3607,7 +3776,11 @@ var QueryBuilder = class {
 	}
 	where(columnOrCondition, operator, value) {
 		if (typeof columnOrCondition === "object" && columnOrCondition !== null && "type" in columnOrCondition) {
-			this.params.logical = columnOrCondition;
+			const next = columnOrCondition;
+			this.params.logical = this.params.logical ? {
+				type: "and",
+				conditions: [this.params.logical, next]
+			} : next;
 			return this;
 		}
 		if (!this.params.where) this.params.where = {};
@@ -4219,6 +4392,36 @@ function readTuple(field, raw) {
 	if (isOperatorShaped(op)) throw new UnknownFilterOperatorError(field, op);
 }
 /**
+* Encode the `<op>.<value>` half of a wire condition.
+*
+* This is the single leaf encoder. Both wire positions that carry a condition
+* — a top-level query parameter (`?status=eq.active`) and a leaf inside an
+* `and(...)`/`or(...)` group (`or(status.eq.active,…)`) — go through it, so a
+* rule expressed here holds in both. The group serializer used to carry its
+* own copy, and the copy had drifted on every rule that matters: `null` went
+* out as the four-character string, the empty list as `()`, and an operator
+* this dialect does not have was silently rewritten to `eq` — a filter that
+* ran, returned rows, and answered a different question than the one asked.
+*
+* `escapeScalar` is the one thing the two positions legitimately disagree
+* about. A scalar in a query parameter owns the whole value and needs no
+* escaping; a scalar inside a group sits between the same commas a list item
+* does, so a comma in it would end the condition early.
+*/
+function serializeOperatorAndValue(op, value, { escapeScalar, where }) {
+	if (typeof op !== "string") throw new TypeError(`${where}: operator must be a string, got ${typeof op}`);
+	const restOp = CANONICAL_OP_LOOKUP.get(op);
+	if (!restOp) throw new TypeError(`${where}: unknown operator "${op}". Valid operators: ${Object.keys(CANONICAL_TO_REST).join(", ")}`);
+	if (value === null && (op === "==" || op === "!=")) return op === "==" ? "isnull.null" : "notnull.null";
+	if (NULL_OPS.has(op)) return `${restOp}.null`;
+	if (Array.isArray(value)) {
+		if (value.length === 0) return `${restOp}.(${EMPTY_LIST_TOKEN})`;
+		return `${restOp}.(${value.map((v) => escapeWireValue(stringifyValue(v))).join(",")})`;
+	}
+	const scalar = stringifyValue(value);
+	return `${restOp}.${escapeScalar ? escapeWireValue(scalar) : scalar}`;
+}
+/**
 * Serialize a single canonical condition tuple to a PostgREST dot-string.
 *
 * Throws `TypeError` if the input is not a valid `[WhereFilterOp, unknown]` tuple.
@@ -4231,15 +4434,10 @@ function readTuple(field, raw) {
 function serializeTuple(tuple) {
 	if (!Array.isArray(tuple) || tuple.length !== 2) throw new TypeError(`serializeTuple: expected a [WhereFilterOp, value] tuple, got ${JSON.stringify(tuple)}`);
 	const [op, value] = tuple;
-	if (typeof op !== "string") throw new TypeError(`serializeTuple: operator must be a string, got ${typeof op}`);
-	const restOp = CANONICAL_OP_LOOKUP.get(op);
-	if (!restOp) throw new TypeError(`serializeTuple: unknown operator "${op}". Valid operators: ${Object.keys(CANONICAL_TO_REST).join(", ")}`);
-	if (value === null && (op === "==" || op === "!=")) return op === "==" ? "isnull.null" : "notnull.null";
-	if (Array.isArray(value)) {
-		if (value.length === 0) return `${restOp}.(${EMPTY_LIST_TOKEN})`;
-		return `${restOp}.(${value.map((v) => escapeWireValue(stringifyValue(v))).join(",")})`;
-	}
-	return `${restOp}.${stringifyValue(value)}`;
+	return serializeOperatorAndValue(op, value, {
+		escapeScalar: false,
+		where: "serializeTuple"
+	});
 }
 /**
 * Convert `FilterValues` (or `WireFilterValues`) to a PostgREST-style
@@ -4344,10 +4542,21 @@ function deserializeFilter(query) {
 /**
 * Serialize a `LogicalCondition` or `FilterCondition` to its wire-format string.
 *
+* Leaf encoding is {@link serializeOperatorAndValue}, the same function
+* `serializeTuple` uses, so `null`, the empty list and an unknown operator
+* behave identically inside a group and in a query parameter.
+*
+* @throws {TypeError} when a leaf names an operator this dialect does not have.
+* It used to fall back to `eq`, which turned `age >= 18` into `age = 18` with
+* no diagnostic anywhere.
+*
 * @example
 * serializeLogicalCondition({ column: "status", operator: "==", value: "active" })
 * // → "status.eq.active"
 *
+* serializeLogicalCondition({ column: "deleted_at", operator: "==", value: null })
+* // → "deleted_at.isnull.null"
+*
 * serializeLogicalCondition({ type: "or", conditions: [...] })
 * // → "or(status.eq.active,status.eq.pending)"
 */
@@ -4356,12 +4565,60 @@ function serializeLogicalCondition(cond) {
 		const inner = (cond.conditions ?? []).map(serializeLogicalCondition).join(",");
 		return `${cond.type}(${inner})`;
 	}
-	const restOp = CANONICAL_OP_LOOKUP.get(cond.operator) ?? "eq";
-	if (Array.isArray(cond.value)) {
-		const items = cond.value.map((v) => escapeWireValue(stringifyValue(v))).join(",");
-		return `${cond.column}.${restOp}.(${items})`;
+	return `${escapeWireValue(cond.column)}.${serializeOperatorAndValue(cond.operator, cond.value, {
+		escapeScalar: true,
+		where: "serializeLogicalCondition"
+	})}`;
+}
+/**
+* Split a leaf condition into `column`, operator token and value.
+*
+* The naive reading — column is everything before the first dot, operator is
+* everything up to the second — cannot express a relation path. A filter on
+* `author.name` serializes to `author.name.eq.bob` and came back as the column
+* `author` with the operator `name`, which resolves to nothing, so the
+* fallback made it `author == "eq.bob"`: a condition that runs and matches
+* nothing, on a column the caller never named.
+*
+* So the operator is found rather than assumed: it is the first dot-separated
+* segment after the column that resolves to a real operator. Everything before
+* it is the column, everything after is the value. `version.eq.1.2.3` reads as
+* `version == "1.2.3"` because the scan stops at the first match — the `eq` at
+* offset 1, not a later segment — and `metadata->>x.eq.5` never had dots in the
+* column to begin with.
+*
+* Returns `undefined` when no segment resolves — `status.active`, an equality
+* written without an operator, which the caller handles.
+*/
+function splitLeafCondition(str) {
+	let limit = str.length;
+	for (let i = 0; i < str.length; i++) {
+		if (str[i] === "\\") {
+			i++;
+			continue;
+		}
+		if (str[i] === "(") {
+			limit = i;
+			break;
+		}
+	}
+	const dots = [];
+	for (let i = 0; i < limit; i++) {
+		if (str[i] === "\\") {
+			i++;
+			continue;
+		}
+		if (str[i] === ".") dots.push(i);
+	}
+	for (let i = 1; i < dots.length; i++) {
+		const operator = toCanonicalOp(str.substring(dots[i - 1] + 1, dots[i]));
+		if (!operator) continue;
+		return {
+			column: unescapeWireValue(str.substring(0, dots[i - 1])),
+			operator,
+			value: str.substring(dots[i] + 1)
+		};
 	}
-	return `${cond.column}.${restOp}.${escapeWireValue(stringifyValue(cond.value))}`;
 }
 /**
 * Parse a logical condition wire-format string back into a
@@ -4399,28 +4656,34 @@ function deserializeLogicalCondition(str, nesting = 0) {
 			conditions: splitGroupItems(innerStr).map((part) => deserializeLogicalCondition(part, nesting + 1))
 		};
 	}
-	const firstDot = str.indexOf(".");
-	if (firstDot === -1) return {
-		column: str,
-		operator: "==",
-		value: true
-	};
-	const column = str.substring(0, firstDot);
-	const rest = str.substring(firstDot + 1);
-	const secondDot = rest.indexOf(".");
-	if (secondDot === -1) return {
-		column,
-		operator: "==",
-		value: unescapeWireValue(rest)
-	};
-	const opStr = rest.substring(0, secondDot);
-	const valueStr = rest.substring(secondDot + 1);
-	const operator = toCanonicalOp(opStr) ?? "==";
-	if (valueStr.startsWith("(") && valueStr.endsWith(")")) return {
+	const leaf = splitLeafCondition(str);
+	if (!leaf) {
+		const firstDot = str.indexOf(".");
+		if (firstDot === -1) return {
+			column: unescapeWireValue(str),
+			operator: "==",
+			value: true
+		};
+		return {
+			column: unescapeWireValue(str.substring(0, firstDot)),
+			operator: "==",
+			value: unescapeWireValue(str.substring(firstDot + 1))
+		};
+	}
+	const { column, operator, value: valueStr } = leaf;
+	if (NULL_OPS.has(operator)) return {
 		column,
 		operator,
-		value: splitListItems(valueStr.slice(1, -1))
+		value: null
 	};
+	if (valueStr.startsWith("(") && valueStr.endsWith(")")) {
+		const inner = valueStr.slice(1, -1);
+		return {
+			column,
+			operator,
+			value: inner === EMPTY_LIST_TOKEN ? [] : splitListItems(inner)
+		};
+	}
 	return {
 		column,
 		operator,
@@ -4429,6 +4692,15 @@ function deserializeLogicalCondition(str, nesting = 0) {
 }
 //#endregion
 //#region src/data/buildRebaseData.ts
+/**
+* What a client says when its data source cannot subscribe.
+*
+* Named rather than inlined so the sentence a caller sees does not depend on
+* which of the two adapters below happened to build the client.
+*/
+var noRealtime = (slug) => `Realtime is not available for "${slug}": its data source does not support subscriptions.`;
+/** What a client says when its data source cannot count. */
+var noCount = (slug) => `Counting is not available for "${slug}": its data source does not support it.`;
 function createPrimaryKeyResolver(options) {
 	const cache = /* @__PURE__ */ new Map();
 	const warned = /* @__PURE__ */ new Set();
@@ -4723,7 +4995,11 @@ var SdkQueryBuilder = class {
 	}
 	where(columnOrCondition, operator, value) {
 		if (typeof columnOrCondition === "object" && columnOrCondition !== null && "type" in columnOrCondition) {
-			this.params.logical = columnOrCondition;
+			const next = columnOrCondition;
+			this.params.logical = this.params.logical ? {
+				type: "and",
+				conditions: [this.params.logical, next]
+			} : next;
 			return this;
 		}
 		if (!this.params.where) this.params.where = {};
@@ -4743,7 +5019,7 @@ var SdkQueryBuilder = class {
 	/** Called again, this adds a tie-breaker rather than replacing the sort. */
 	orderBy(column, direction = "asc") {
 		const existing = normalizeOrderBy(this.params.orderBy) ?? [];
-		this.params.orderBy = [...existing, [column, direction]];
+		this.params.orderBy = [...existing, [sortKeyToString(column), direction]];
 		return this;
 	}
 	limit(count) {
@@ -4775,11 +5051,39 @@ var SdkQueryBuilder = class {
 	async find() {
 		return this.client.find(this.params);
 	}
+	/**
+	* Page through everything this query matches, one row at a time.
+	*
+	* `.limit()` on the builder becomes the page size, so the ceiling on a
+	* single `find()` is not a ceiling on what the query can read.
+	*/
+	iterate(options) {
+		return this.client.iterate({
+			...this.params,
+			...this.params.limit !== void 0 && { pageSize: this.params.limit },
+			...options
+		});
+	}
+	/** Collect everything this query matches into one array. */
+	findAll(options) {
+		return this.client.findAll({
+			...this.params,
+			...this.params.limit !== void 0 && { pageSize: this.params.limit },
+			...options
+		});
+	}
+	/**
+	* Count the records matching this query.
+	*
+	* This used to answer `0` when the client had no `count` — a number, from a
+	* source that had not counted anything, indistinguishable from an empty
+	* collection. It now does what the client does, which on a source that
+	* cannot count is throw and say so.
+	*/
 	async count() {
-		return this.client.count ? this.client.count(this.params) : 0;
+		return this.client.count(this.params);
 	}
 	listen(onUpdate, onError) {
-		if (!this.client.listen) throw new Error("Listen is only available when the driver supports realtime.");
 		return this.client.listen(this.params, onUpdate, onError);
 	}
 };
@@ -4807,6 +5111,14 @@ function toSdkCollectionClient(snap, slug = "collection") {
 			const s = await snap.findById(id);
 			return s ? entityToRow(s) : void 0;
 		},
+		async get(id) {
+			const s = await snap.findById(id);
+			if (!s) throw new RebaseApiError(`No record with id ${JSON.stringify(String(id))} in "${slug}".`, {
+				status: 404,
+				code: "NOT_FOUND"
+			});
+			return entityToRow(s);
+		},
 		async create(data, id) {
 			return entityToRow(await snap.create(data, id));
 		},
@@ -4837,12 +5149,12 @@ function toSdkCollectionClient(snap, slug = "collection") {
 			if (!snap.deleteMany) throw new Error("Bulk deletes are not supported by this collection's data source. Fall back to delete() per record.");
 			await snap.deleteMany(ids);
 		},
-		count: snap.count ? (params) => snap.count(params) : void 0,
+		count: snap.count ? (params) => snap.count(params) : unsupportedMethod(noCount(slug)),
 		listen: snap.listen ? (params, onUpdate, onError) => snap.listen(params, (res) => onUpdate({
 			data: res.data.map(entityToRow),
 			meta: res.meta
-		}), onError) : void 0,
-		listenById: snap.listenById ? (id, onUpdate, onError) => snap.listenById(id, (s) => onUpdate(s ? entityToRow(s) : void 0), onError) : void 0,
+		}), onError) : unsupportedMethod(noRealtime(slug)),
+		listenById: snap.listenById ? (id, onUpdate, onError) => snap.listenById(id, (s) => onUpdate(s ? entityToRow(s) : void 0), onError) : unsupportedMethod(noRealtime(slug)),
 		where(columnOrCondition, operator, value) {
 			const builder = new SdkQueryBuilder(client);
 			if (typeof columnOrCondition === "object") return builder.where(columnOrCondition);
@@ -4889,12 +5201,12 @@ function toEntityAccessor(sdk, slug, getPks = () => []) {
 		delete(id) {
 			return sdk.delete(id);
 		},
-		count: sdk.count ? (params) => sdk.count(params) : void 0,
-		listen: sdk.listen ? (params, onUpdate, onError) => sdk.listen(params, (res) => onUpdate({
+		count: isUnsupported(sdk.count) ? void 0 : (params) => sdk.count(params),
+		listen: isUnsupported(sdk.listen) ? void 0 : (params, onUpdate, onError) => sdk.listen(params, (res) => onUpdate({
 			data: res.data.map((row) => rowToEntity(row, slug, getPks())),
 			meta: res.meta
-		}), onError) : void 0,
-		listenById: sdk.listenById ? (id, onUpdate, onError) => sdk.listenById(id, (row) => onUpdate(row ? rowToEntity(row, slug, getPks()) : void 0), onError) : void 0,
+		}), onError),
+		listenById: isUnsupported(sdk.listenById) ? void 0 : (id, onUpdate, onError) => sdk.listenById(id, (row) => onUpdate(row ? rowToEntity(row, slug, getPks()) : void 0), onError),
 		where(columnOrCondition, operator, value) {
 			const builder = new QueryBuilder(accessor);
 			if (typeof columnOrCondition === "object") return builder.where(columnOrCondition);
@@ -4974,7 +5286,7 @@ function wrapAsSdkData(entityData) {
 * Build a flat {@link RebaseSdkData} from a `DataDriver`.
 *
 * This is the developer-facing SDK data layer used by backend framework
-* callbacks & scripts (`context.data` / `rebase.data`). It returns flat rows —
+* callbacks & scripts (`context.data` / `rebase.dataAsAdmin`). It returns flat rows —
 * identical in shape to the frontend SDK client, down to how a relation is
 * served: a foreign key stays a foreign key, and a relation named in `include`
 * arrives as the target's own columns. The `{ __type: "relation" }` envelope is
@@ -5126,6 +5438,6 @@ async function detectJunctionTables(executeSql) {
 	return junctionTables;
 }
 //#endregion
-export { COLLECTION_PATH_SEPARATOR, COMPOSITE_ID_SEPARATOR, CollectionRegistry, DEFAULT_FIND_ALL_MAX_ROWS, DEFAULT_MAX_PAGES, DEFAULT_ONE_OF_TYPE, DEFAULT_ONE_OF_VALUE, DEFAULT_PAGE_SIZE, DEFAULT_STRING_COLUMN_LENGTH, JUNCTION_TABLES_SQL, MAX_LOGICAL_NESTING_DEPTH, OrderBySpecError, QueryBuilder, REBASE_INTERNAL_PREFIXES, REBASE_INTERNAL_SCHEMAS, REBASE_INTERNAL_TABLES, REBASE_USER_ROLE, RebasePaginationError, UnknownFilterOperatorError, and, buildCollectionFromTableMetadata, buildCompositeId, buildConditionContext, buildPropertyCallbacks, buildRebaseData, buildRoutedRebaseData, buildSdkData, canCreateEntity, canDeleteEntity, canEditEntity, canReadCollection, checkOperation, classifyTable, collectAllPages, cond, createDataSourceRegistry, createPaginationHelpers, createRelationRef, createRelationRefWithData, defaultUsersCollection, defineCollection, deserializeFilter, deserializeLogicalCondition, deserializeOrderBy, deserializeOrderByList, detectJunctionTables, embedParentExpression, enumToObjectEntries, evaluateCondition, evaluatePolicy, fieldKeyForColumn, findAnonymousGrants, findRelation, fullPathToCollectionSegments, getArrayResolvedProperties, getChildViewDeclaringProperties, getChildViewRelationPropertyKeys, getColumnName, getDeclaredPrimaryKeys, getDefaultValueFor, getDefaultValueFortype, getDefaultValuesFor, getEffectiveSecurityRules, getEntityChildViews, getEnumVarName, getGeneratedPolicyNames, getInjectedSecurityRules, getJunctionCollectionConfig, getJunctionSecurityRules, getLabelOrConfigFrom, getPrimaryKeys, getReferenceFrom, getRelationFrom, getRelationTargetPath, getSubcollections, getTableName, getTableVarName, isAddressableId, isJunctionBackedRelation, isPropertyBuilder, isRebaseInternalTable, isRelationalCollection, normalizeDriverOrderBy, normalizeEmail, normalizeOrderBy, normalizeToEntityRelation, or, paginateFind, parseIdValues, parseOrderBySpecStrict, policyToPostgres, primaryOrderBy, registerConditionOperations, relationalCollections, resolveArrayProperties, resolveCollectionRelations, resolveDataSource, resolveEnumValues, resolveFindWindow, resolveJunctionSpecs, resolvePrimaryKeys, resolveProperties, resolveProperty, resolvePropertyEnum, resolveRelation, resolveRelationProperty, resolveStorageFilenameString, resolveStoragePathString, resolveStorageSource, resolveStringColumnLength, revokeInternalTableAccess, revokeInternalTableSql, sanitizeData, securityRuleToConditions, segmentsToStrippedPath, serializeFilter, serializeLogicalCondition, serializeOrderBy, sortCollectionsBySlug, sortProperties, sqlToPolicy, stripCollectionPath, toFilterTuples, traverseValueProperty, traverseValuesProperties, updateDateAutoValues, wrapAsEntityData, wrapAsSdkData };
+export { CALLBACK_REJECTED, COLLECTION_PATH_SEPARATOR, COMPOSITE_ID_SEPARATOR, CollectionRegistry, DEFAULT_FIND_ALL_MAX_ROWS, DEFAULT_MAX_PAGES, DEFAULT_ONE_OF_TYPE, DEFAULT_ONE_OF_VALUE, DEFAULT_PAGE_SIZE, DEFAULT_STRING_COLUMN_LENGTH, JUNCTION_TABLES_SQL, MAX_LOGICAL_NESTING_DEPTH, OrderBySpecError, QueryBuilder, REBASE_INTERNAL_PREFIXES, REBASE_INTERNAL_SCHEMAS, REBASE_INTERNAL_TABLES, REBASE_USER_ROLE, RebasePaginationError, UnknownFilterOperatorError, and, buildCollectionFromTableMetadata, buildCompositeId, buildConditionContext, buildPropertyCallbacks, buildRebaseData, buildRoutedRebaseData, buildSdkData, callbackRefusal, canCreateEntity, canDeleteEntity, canEditEntity, canReadCollection, checkOperation, classifyTable, collectAllPages, cond, createDataSourceRegistry, createPaginationHelpers, createRelationRef, createRelationRefWithData, defaultUsersCollection, defineCollection, deserializeFilter, deserializeLogicalCondition, deserializeOrderBy, deserializeOrderByList, detectJunctionTables, embedParentExpression, enumToObjectEntries, evaluateCondition, evaluatePolicy, fieldKeyForColumn, findAnonymousGrants, findRelation, fullPathToCollectionSegments, getArrayResolvedProperties, getChildViewDeclaringProperties, getChildViewRelationPropertyKeys, getColumnName, getDeclaredPrimaryKeys, getDefaultValueFor, getDefaultValueFortype, getDefaultValuesFor, getEffectiveSecurityRules, getEntityChildViews, getEnumVarName, getGeneratedPolicyNames, getInjectedSecurityRules, getJunctionCollectionConfig, getJunctionSecurityRules, getLabelOrConfigFrom, getPrimaryKeys, getReferenceFrom, getRelationFrom, getRelationTargetPath, getSubcollections, getTableName, getTableVarName, isAddressableId, isJunctionBackedRelation, isPropertyBuilder, isRebaseInternalTable, isRelationRequired, isRelationalCollection, normalizeDriverOrderBy, normalizeEmail, normalizeOrderBy, normalizeToEntityRelation, or, paginateFind, parseIdValues, parseOrderBySpecStrict, policyToPostgres, primaryOrderBy, registerConditionOperations, relationDeclaringProperty, relationalCollections, resolveArrayProperties, resolveCollectionRelations, resolveDataSource, resolveEnumValues, resolveFindWindow, resolveJunctionSpecs, resolvePrimaryKeys, resolveProperties, resolveProperty, resolvePropertyEnum, resolveRelation, resolveRelationProperty, resolveStorageFilenameString, resolveStoragePathString, resolveStorageSource, resolveStringColumnLength, revokeInternalTableAccess, revokeInternalTableSql, sanitizeData, securityRuleToConditions, segmentsToStrippedPath, serializeFilter, serializeLogicalCondition, serializeOrderBy, sortCollectionsBySlug, sortProperties, sqlToPolicy, stripCollectionPath, toCallbackError, toFilterTuples, traverseValueProperty, traverseValuesProperties, updateDateAutoValues, wrapAsEntityData, wrapAsSdkData };
 
 //# sourceMappingURL=index.es.js.map