@rebasepro/common 0.13.0 → 0.13.1-canary.g249daa1

package/dist/index.es.js

@@ -1,4 +1,4 @@
-import { ANONYMOUS_USER_ID, ANONYMOUS_USER_IDS, CANONICAL_TO_REST, DEFAULT_DATA_SOURCE_KEY, EntityReference, EntityRelation, NULL_OPS, REST_TO_CANONICAL, getDataSourceCapabilities, getDeclaredSubcollections, isAnonymousUid, isManyToMany, isPostgresCollectionConfig, isRelationalCollectionConfig, policy, toCanonicalOp } from "@rebasepro/types";
+import { 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, isRelationalCollectionConfig, policy, rewriteLegacyRlsFunctions, toCanonicalOp } from "@rebasepro/types";
 import { deepClone, generateForeignKeyName, getIn, getPolicyNamesForRules, getPolicyOperations, isDefaultFieldConfigId, mergeDeep, prettifyIdentifier, randomString, removeFunctions, toSnakeCase } from "@rebasepro/utils";
 import jsonLogic from "json-logic-js";
 import { deepEqual } from "fast-equals";
@@ -89,10 +89,21 @@ function getRelationFrom(entity) {
 * have `id` and `path` fields — these are relation-shaped objects from
 * edge cases in the data pipeline (REST fallback, stale cache, custom data source).
 *
+* When `targetPath` is given, also accepts a bare id. A relation column is a
+* foreign key, and the REST layer returns it as the scalar it is; only some
+* fetch paths hydrate it into an object. Which form a caller sees therefore
+* depends on how the row was loaded, and a caller that only accepted objects
+* reported half of its own data as a type error. The declared target is the
+* missing half: with it, an id is a relation that has not been fetched yet.
+*
 * Returns null if the value cannot be coerced.
 */
-function normalizeToEntityRelation(value, propertyType) {
+function normalizeToEntityRelation(value, propertyType, targetPath) {
 	if (value instanceof EntityRelation) return value;
+	if (targetPath && (typeof value === "string" || typeof value === "number")) {
+		if (value === "") return null;
+		return new EntityRelation(value, targetPath);
+	}
 	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
 	const obj = value;
 	if (!(obj.__type === "relation" || obj.__type === "reference" || typeof obj.isEntityRelation === "function" && obj.isEntityRelation() || typeof obj.isEntityReference === "function" && obj.isEntityReference() || propertyType === "relation" && typeof obj.id !== "undefined" && typeof obj.path === "string")) return null;
@@ -608,6 +619,33 @@ function resolveCollectionRelations(collection) {
 	_resolvedRelationsCache.set(collection, relations);
 	return relations;
 }
+/**
+* The path of the collection a relation property points at, derived from the
+* property alone.
+*
+* A preview holds a property and a value and no collection, so it cannot call
+* `resolveRelationProperty`. It does not need to: both forms that carry a
+* target — the stamped `resolvedRelation` and the inline `relation` — name it
+* directly. Only the third form, a relation declared by name in the
+* collection's `relations` array, is out of reach, and that one has no target
+* to read without the collection anyway.
+*
+* This is what lets a preview render a relation column that arrived as a bare
+* foreign key: the id says *which* row, the declared target says *which
+* collection*, and `RelationPreview` fetches the rest. Without it a scalar id
+* is indistinguishable from a value of the wrong type.
+*/
+function getRelationTargetPath(property) {
+	const stamped = property.resolvedRelation?.targetSlug;
+	if (stamped) return stamped;
+	const target = property.relation?.target;
+	if (typeof target !== "function") return void 0;
+	try {
+		return target()?.slug;
+	} catch (_e) {
+		return;
+	}
+}
 function getTableName(collection) {
 	if (isRelationalCollectionConfig(collection)) return collection.table ?? toSnakeCase(collection.slug) ?? toSnakeCase(collection.name);
 	return toSnakeCase(collection.slug) ?? toSnakeCase(collection.name);
@@ -882,6 +920,59 @@ function getEntityChildViews(collection) {
 	return views;
 }
 /**
+* Each of `collection`'s tabs paired with the property that declared it, when a
+* property declared it: child view key → property key.
+*
+* A many-relation can only be declared as a property — that is the documented
+* and only mechanism — and {@link getEntityChildViews} promotes it to a tab. So
+* one declaration reaches the panel twice, and neither surface knew about the
+* other. The form rendered a relation picker beside the tab, and the collection
+* table rendered *two* columns under one heading: the relation's own column,
+* showing the child rows, and a jump-to-tab button carrying the same name.
+*
+* The pairing is what lets each surface decide which half is redundant, and it
+* has to be a pairing rather than two sets because the two keys differ whenever
+* a relation is named. The match is on the resolved `relationName` — the
+* identity `getEntityChildViews` itself dedupes on — so a relation declared in
+* `relations` and pointed at by a differently-named property is recognised too.
+*
+* A relation with no property of its own is absent here, which is the point: it
+* has exactly one surface already, and nothing to weigh it against.
+*
+* Only top-level properties: a relation nested inside a `map` gets no tab.
+*/
+function getChildViewDeclaringProperties(collection) {
+	const pairs = /* @__PURE__ */ new Map();
+	const relationProperties = Object.entries(collection.properties ?? {}).filter(([, property]) => property?.type === "relation");
+	if (relationProperties.length === 0) return pairs;
+	const relationViews = getEntityChildViews(collection).filter((view) => view.source.kind === "relation");
+	if (relationViews.length === 0) return pairs;
+	const resolvedRelations = resolveCollectionRelations(collection);
+	const identityOf = (relationKey) => resolvedRelations[relationKey]?.relationName ?? relationKey;
+	const declaringPropertyByIdentity = /* @__PURE__ */ new Map();
+	for (const [propertyKey, property] of relationProperties) {
+		const relation = property.resolvedRelation ?? resolvedRelations[propertyKey];
+		if (relation?.cardinality !== "many") continue;
+		const identity = relation.relationName ?? propertyKey;
+		if (!declaringPropertyByIdentity.has(identity)) declaringPropertyByIdentity.set(identity, propertyKey);
+	}
+	for (const view of relationViews) {
+		const propertyKey = declaringPropertyByIdentity.get(identityOf(view.source.relationKey));
+		if (propertyKey) pairs.set(view.key, propertyKey);
+	}
+	return pairs;
+}
+/**
+* The property keys of `collection` whose relation is already one of its tabs.
+*
+* What a form asks: the tab is the treatment for a list of child rows, so the
+* picker beside it is the redundant half. See
+* {@link getChildViewDeclaringProperties}.
+*/
+function getChildViewRelationPropertyKeys(collection) {
+	return new Set(getChildViewDeclaringProperties(collection).values());
+}
+/**
 * The child views of `collection` as bare collections.
 *
 * The flattened view of {@link getEntityChildViews}, for navigation code that
@@ -931,9 +1022,9 @@ function isKeywordAt(upper, i, keyword) {
 *
 * This used to be `sql.split(/ AND /i)`, which tore subqueries in half: the
 * `AND` inside
-*   `EXISTS (SELECT 1 FROM organization_members m WHERE m.org = t.org AND m.user_id = auth.uid())`
+*   `EXISTS (SELECT 1 FROM organization_members m WHERE m.org = t.org AND m.user_id = rebase.uid())`
 * split the expression, and re-emitting the halves produced
-*   `(EXISTS (...) AND m.user_id = auth.uid())`
+*   `(EXISTS (...) AND m.user_id = rebase.uid())`
 * where `m` is no longer in scope — SQL that Postgres rejects outright with
 * "missing FROM-clause entry for table". Returning null instead keeps such a
 * clause as a `raw` expression, which round-trips verbatim.
@@ -1007,15 +1098,15 @@ function stripOuterParens(sql) {
 	}
 }
 function sqlToPolicy(sql) {
-	const trimmed = stripOuterParens(sql.trim());
+	const trimmed = stripOuterParens(rewriteLegacyRlsFunctions(sql).trim());
 	if (trimmed.toLowerCase() === "true") return policy.true();
 	if (trimmed.toLowerCase() === "false") return policy.false();
-	const overlapMatch = trimmed.match(/^string_to_array\s*\(\s*auth\.roles\(\)\s*,\s*','\s*\)\s*&&\s*ARRAY\s*\[(.+)\]$/i);
+	const overlapMatch = trimmed.match(/^string_to_array\s*\(\s*rebase\.roles\(\)\s*,\s*','\s*\)\s*&&\s*ARRAY\s*\[(.+)\]$/i);
 	if (overlapMatch) {
 		const roles = overlapMatch[1].split(",").map((s) => s.trim().replace(/^'|'$/g, ""));
 		return policy.rolesOverlap(roles);
 	}
-	const containMatch = trimmed.match(/^string_to_array\s*\(\s*auth\.roles\(\)\s*,\s*','\s*\)\s*@>\s*ARRAY\s*\[(.+)\]$/i);
+	const containMatch = trimmed.match(/^string_to_array\s*\(\s*rebase\.roles\(\)\s*,\s*','\s*\)\s*@>\s*ARRAY\s*\[(.+)\]$/i);
 	if (containMatch) {
 		const roles = containMatch[1].split(",").map((s) => s.trim().replace(/^'|'$/g, ""));
 		return policy.rolesContain(roles);
@@ -1031,10 +1122,10 @@ function sqlToPolicy(sql) {
 		const right = parseOperand(rightStr.trim());
 		if (left && right) return policy.compare(left, op === "=" ? "eq" : "neq", right);
 	}
-	return policy.raw(sql);
+	return policy.raw(trimmed);
 }
 /**
-* Literals from other BaaS platforms that people compare `auth.uid()` against
+* Literals from other BaaS platforms that people compare `rebase.uid()` against
 * out of habit. Mirrors the driver's `FOREIGN_CONVENTION_ROLES` guard on
 * `pgRoles`, one surface over: the same muscle memory inside a `using:` string
 * is the more dangerous spelling, because it inverts a rule instead of
@@ -1045,18 +1136,25 @@ var FOREIGN_CONVENTION_UIDS = {
 	authenticated: "Supabase",
 	service_role: "Supabase"
 };
-/** `auth.uid() IS NOT NULL` in raw SQL, the clause that is always true. */
-var UID_NOT_NULL = /auth\.uid\(\)\s+IS\s+NOT\s+NULL/i;
+/**
+* `rebase.uid() IS NOT NULL` in raw SQL, the clause that is always true.
+*
+* Both schema spellings, because this runs over policy bodies read back from a
+* database, and one migrated by a pre-1.0 release still holds `auth.uid()`.
+* A security check that stops recognising a dangerous clause because the
+* framework renamed a function is a check that silently turns off.
+*/
+var UID_NOT_NULL = /\b(?:rebase|auth)\.uid\(\)\s+IS\s+NOT\s+NULL/i;
 /**
 * Find clauses that read as "signed-in users only" but admit anonymous callers.
 *
-* Both spellings come from the same place — Supabase, where `auth.uid()` really
-* is NULL for an anonymous request. Rebase substitutes
+* Both spellings come from the same place — Supabase, where its own `auth.uid()`
+* really is NULL for an anonymous request. Rebase substitutes
 * {@link ANONYMOUS_USER_ID} instead (a blank id would read back as NULL, which
 * is how the trusted *server* context is recognised), so:
 *
-*  - `auth.uid() IS NOT NULL` is a tautology on the user path, and
-*  - `auth.uid() != 'anon'` excludes one spelling of anonymous and admits the
+*  - `rebase.uid() IS NOT NULL` is a tautology on the user path, and
+*  - `rebase.uid() != 'anon'` excludes one spelling of anonymous and admits the
 *    other. This one is not hypothetical and was not only a foreign habit:
 *    rebase's own request path reported `'anon'` while everything that compiled
 *    or checked a policy used `'anonymous'`, so whichever literal an author
@@ -1088,7 +1186,7 @@ function findAnonymousGrants(expr) {
 				if (UID_NOT_NULL.test(e.sql)) found.push({
 					pattern: "uid-not-null",
 					detail: e.sql,
-					explanation: `\`auth.uid() IS NOT NULL\` is true for every request that came from a client, including anonymous ones — they carry '${ANONYMOUS_USER_ID}', not NULL. Use \`condition: policy.authenticated()\` to mean "signed in".`
+					explanation: `\`rebase.uid() IS NOT NULL\` is true for every request that came from a client, including anonymous ones — they carry '${ANONYMOUS_USER_ID}', not NULL. Use \`condition: policy.authenticated()\` to mean "signed in".`
 				});
 				return;
 			case "compare": {
@@ -1110,7 +1208,7 @@ function findAnonymousGrants(expr) {
 	return found;
 }
 function parseOperand(str) {
-	if (/current_setting\s*\(\s*'app\.(uid|user_id)'\s*\)/i.test(str) || /auth\.uid\(\)/i.test(str)) return policy.authUid();
+	if (/current_setting\s*\(\s*'app\.(uid|user_id)'\s*\)/i.test(str) || /rebase\.uid\(\)/i.test(str)) return policy.authUid();
 	const stringMatch = str.match(/^'(.+)'$/);
 	if (stringMatch) return policy.literal(stringMatch[1]);
 	if (/^\w+$/.test(str)) return policy.field(str);
@@ -1192,12 +1290,12 @@ function compile(expr, scope) {
 			const rightSql = castForAuthUid(expr.right, operandToSql(expr.right, scope), expr.left);
 			return `${leftSql} ${COMPARE_SQL[expr.op]} ${rightSql}`;
 		}
-		case "rolesOverlap": return `string_to_array(auth.roles(), ',') && ${rolesArraySql(expr.roles)}`;
-		case "rolesContain": return `string_to_array(auth.roles(), ',') @> ${rolesArraySql(expr.roles)}`;
-		case "authenticated": return `auth.uid() IS NOT NULL AND auth.uid() NOT IN (${ANONYMOUS_USER_IDS.map(quoteLiteral).join(", ")})`;
-		case "serverContext": return "auth.uid() IS NULL";
+		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 "serverContext": return `${RLS_UID_SQL} IS NULL`;
 		case "existsIn": return compileExistsIn(expr, scope);
-		case "raw": return expr.sql.replace(/\{(\w+)\}/g, (_, col) => `${outerQualifier(scope)}${resolveColumnName(col, scope.outerCollection)}`);
+		case "raw": return rewriteLegacyRlsFunctions(expr.sql).replace(/\{(\w+)\}/g, (_, col) => `${outerQualifier(scope)}${resolveColumnName(col, scope.outerCollection)}`);
 	}
 }
 /**
@@ -1234,8 +1332,8 @@ function operandToSql(operand, scope) {
 		case "field": return `${scope.fieldPrefix}${resolveColumnName(operand.name, scope.fieldCollection)}`;
 		case "outerField": return `${scope.outerPrefix}${resolveColumnName(operand.name, scope.outerCollection)}`;
 		case "literal": return quoteLiteral(operand.value);
-		case "authUid": return "auth.uid()";
-		case "authRoles": return "string_to_array(auth.roles(), ',')";
+		case "authUid": return RLS_UID_SQL;
+		case "authRoles": return `string_to_array(${RLS_ROLES_SQL}, ',')`;
 	}
 }
 /**
@@ -1996,9 +2094,14 @@ function registerConditionOperations() {
 	operationsRegistered = true;
 }
 /**
-* Evaluate a JSON Logic rule against the given context.
+* Evaluate a condition against the given context.
+*
+* A condition may be stated as a literal instead of a rule — `hidden: true`
+* rather than `hidden: { "==": [1, 1] }` — and a literal is already its own
+* answer, so it is returned rather than handed to the evaluator.
 */
 function evaluateCondition(rule, context) {
+	if (typeof rule === "boolean") return rule;
 	registerConditionOperations();
 	return jsonLogic.apply(rule, context);
 }
@@ -2317,6 +2420,142 @@ function resolveStringColumnLength(prop) {
 	return typeof max === "number" && Number.isInteger(max) && max > 0 ? max : 255;
 }
 //#endregion
+//#region src/util/internal-tables.ts
+/**
+* The tables Rebase creates for its own bookkeeping, and the SQL that keeps the
+* end-user role away from them.
+*
+* ## Why this exists
+*
+* Authenticated requests run as {@link REBASE_USER_ROLE}, and the boot-time role
+* provisioning grants that role `SELECT, INSERT, UPDATE, DELETE` on every table
+* in the schemas a project uses — including `rebase`, because a project's own
+* collections are allowed to live there (the scaffold puts `users` there). It
+* also sets `ALTER DEFAULT PRIVILEGES`, so a table created *later* by the
+* migrating role inherits the same grant.
+*
+* Every framework-internal table is created later: auth's tables come up during
+* `initializeAuth`, `api_keys` during route mounting, `cron_logs` when the first
+* job registers, `idempotency_keys` on the first request that carries a key. So
+* they all inherited full DML for the end-user role — and none of them enables
+* row-level security, because none of them is a collection with
+* `securityRules`. Measured on a freshly provisioned database, `SET ROLE
+* rebase_user` could read `rebase.refresh_tokens` (session token hashes),
+* `rebase.mfa_factors` (`secret_encrypted`), `rebase.recovery_codes`, and
+* `rebase.api_keys` (including its `admin` flag), and insert into
+* `rebase.app_config`.
+*
+* Nothing routes a user-context query at those tables today, so this was not
+* reachable over the API. That is the wrong thing to depend on: the documented
+* model is that RLS is the authorization boundary, and these tables sat outside
+* it. The boundary is now a privilege boundary instead — the role simply cannot
+* address them.
+*
+* ## Why REVOKE rather than ENABLE ROW LEVEL SECURITY
+*
+* RLS with no policy denies every row, which is the same outcome, but it is the
+* *weaker* statement: it leaves the grant in place, so a later policy — or a
+* `FORCE` flag cleared by some future migration — reopens the table. There is no
+* row of `refresh_tokens` any end user should ever reach, so the honest encoding
+* is "this role has no privilege here at all". It also keeps the owner
+* connection (which auth actually runs on) completely unaffected.
+*
+* ## Keeping it true
+*
+* `packages/rls-check` scans the `rebase` schema — it used to skip it as a
+* "platform" schema — and its `rls-disabled` check fires on exactly the
+* condition this module removes: RLS off *and* a DML grant to a reachable role.
+* So a table added here without a revoke is caught by `pnpm rls:check`, not by
+* someone re-reading this file.
+*/
+/**
+* The Postgres role authenticated requests run as.
+*
+* Defined here rather than in the Postgres driver because both the driver (which
+* provisions the role) and this module (which revokes on its behalf) need it,
+* and a second spelling of a role name is a silent no-op waiting to happen.
+*/
+var REBASE_USER_ROLE = "rebase_user";
+/**
+* Framework-internal table names, unqualified.
+*
+* Deliberately NOT including `users`: the auth user table is also a collection,
+* with `securityRules`, RLS enabled and policies applied. Users read their own
+* row through it — revoking there would break sign-in.
+*
+* `atlas_schema_revisions` is Atlas's migration ledger, which lands in `rebase`
+* because `db migrate apply` passes `--revisions-schema rebase`.
+*/
+var REBASE_INTERNAL_TABLES = [
+	"user_identities",
+	"refresh_tokens",
+	"password_reset_tokens",
+	"magic_link_tokens",
+	"mfa_factors",
+	"mfa_challenges",
+	"recovery_codes",
+	"app_config",
+	"schema_meta",
+	"api_keys",
+	"cron_logs",
+	"cron_claims",
+	"idempotency_keys",
+	"entity_history",
+	"branches",
+	"channel_messages",
+	"channel_cursors",
+	"channel_presence",
+	"atlas_schema_revisions"
+];
+/** Postgres identifiers this module is willing to interpolate. */
+var SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_$]*$/;
+/**
+* A single statement that takes every privilege on `schema.table` away from the
+* end-user role.
+*
+* Wrapped in a `DO` block guarded on `pg_roles` for two reasons, both of which
+* happen in practice:
+*
+*  - the role does not exist when the connection is unprivileged (Rebase then
+*    relies on native RLS rather than a role switch), and a bare `REVOKE` on a
+*    missing role is an error, not a no-op;
+*  - the table may not exist yet — `cron_logs` never appears in a project with
+*    no cron jobs — and `to_regclass` returning NULL has to be tolerated too.
+*
+* One command, so it is safe on handles that speak the extended query protocol
+* and reject multi-statement strings.
+*/
+function revokeInternalTableSql(schema, table) {
+	if (!SAFE_IDENTIFIER.test(schema)) throw new Error(`Refusing to build SQL with an unsafe schema name: ${JSON.stringify(schema)}`);
+	if (!SAFE_IDENTIFIER.test(table)) throw new Error(`Refusing to build SQL with an unsafe table name: ${JSON.stringify(table)}`);
+	const qualified = `"${schema}"."${table}"`;
+	return `
+        DO $rebase_revoke$
+        BEGIN
+            IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = '${REBASE_USER_ROLE}')
+               AND to_regclass('${qualified}') IS NOT NULL THEN
+                EXECUTE 'REVOKE ALL ON ${qualified} FROM ${REBASE_USER_ROLE}';
+            END IF;
+        END
+        $rebase_revoke$;
+    `.trim();
+}
+/**
+* Revoke on every internal table in `schema`, one statement at a time.
+*
+* Best-effort per table: a connection that does not own one of them (a
+* pre-provisioned database, a platform-managed ledger) cannot revoke on it, and
+* that must not take down a boot. The caller decides how loud to be — `onError`
+* exists so the driver can warn without this module importing a logger.
+*/
+async function revokeInternalTableAccess(execute, schema, options) {
+	for (const table of options?.tables ?? REBASE_INTERNAL_TABLES) try {
+		await execute(revokeInternalTableSql(schema, table));
+	} catch (error) {
+		options?.onError?.(table, error);
+	}
+}
+//#endregion
 //#region src/data/resolveDataSource.ts
 /**
 * Build a keyed registry from a list of {@link DataSourceDefinition}s.
@@ -2359,6 +2598,46 @@ function resolveDataSource(collection, registry) {
 		capabilities: getDataSourceCapabilities(engine)
 	};
 }
+/**
+* Does a SQL toolchain own this collection's storage?
+*
+* "Owns the storage" means: something generates a table for it, pushes that
+* table to a database, plans its RLS policies, and reports it as drifted when
+* the two disagree. That is true of a Postgres collection and false of a
+* Firestore or MongoDB one, whose documents live in a store Rebase never
+* migrates — and the two were never told apart. Every stage of the SQL
+* toolchain took "the collections" to mean *all* of them, so a Firestore
+* collection declared next to the Postgres ones got a `pgTable` in the
+* generated schema, a `CREATE TABLE` at boot, RLS policies, and a place in the
+* `db push` include list — where its name shielding a same-named real table
+* from Atlas's exclude list is the one that can lose data.
+*
+* The answer is the resolved engine's {@link DataSourceCapabilities}, not a
+* name check: an engine registered through `registerDataSourceCapabilities`
+* gets the same treatment as the built-in ones.
+*
+* Deliberately answers **true** for an engine nobody has heard of. Build-time
+* tooling (the CLI, the schema generator) has no data-source registry to
+* resolve a `dataSource` key against, so an unknown key resolves to an unknown
+* engine — and the cost of the two mistakes is not symmetric. Wrongly
+* including a collection generates a table nothing writes to; wrongly excluding
+* one silently stops generating a table the app is serving from. Declare
+* `engine` on a collection that is not SQL-backed and this is exact.
+*/
+function isRelationalCollection(collection, registry) {
+	return getDataSourceCapabilities(collection?.engine ?? (collection?.dataSource ? resolveDataSource(collection, registry).engine : void 0)).supportsRelations;
+}
+/**
+* The subset of `collections` a SQL toolchain owns — see
+* {@link isRelationalCollection}.
+*
+* Every stage that generates SQL from collections starts by calling this, so
+* the rule lives in one place rather than being re-decided per generator. It
+* keeps the input order.
+*/
+function relationalCollections(collections, registry) {
+	return collections.filter((collection) => isRelationalCollection(collection, registry));
+}
 //#endregion
 //#region src/collections/CollectionRegistry.ts
 var CollectionRegistry = class {
@@ -2788,8 +3067,24 @@ var QueryBuilder = class {
 	/**
 	* Set a free-text search string if supported by the backend.
 	*/
-	search(searchString) {
+	search(searchString, options) {
 		this.params.searchString = searchString;
+		if (options?.explain !== void 0) this.params.searchExplain = options.explain;
+		return this;
+	}
+	/**
+	* Order rows by nearest-neighbour distance to `vector`, closest first.
+	*
+	* Postgres only, over a property declared as `type: "vector"`. Rows come
+	* back with a `_distance`; `where` filters before the ordering.
+	*/
+	vectorSearch(property, vector, options) {
+		this.params.vectorSearch = {
+			property,
+			vector,
+			...options?.distance !== void 0 && { distance: options.distance },
+			...options?.threshold !== void 0 && { threshold: options.threshold }
+		};
 		return this;
 	}
 	/**
@@ -2861,6 +3156,30 @@ var RebasePaginationError = class RebasePaginationError extends Error {
 		Object.setPrototypeOf(this, RebasePaginationError.prototype);
 	}
 };
+/**
+* Resolve `limit`/`offset`/`page` into the window a read will actually use.
+*
+* Lives here, next to the walk, for the reason at the top of this file: every
+* transport has to mean the same thing by "page two". Four of them did not —
+* the REST layer strode by {@link DEFAULT_LIST_LIMIT}, the local-first
+* evaluator by {@link DEFAULT_PAGE_SIZE}, the in-process accessor by 20, and
+* the published type documented a fourth number. Pages that overlap or skip
+* rows are the mildest of those outcomes.
+*
+* `page` wins over `offset`, as {@link FindParams} documents. `driverOffset`
+* is the value to hand a driver: it stays `undefined` when the caller named no
+* offset, because keyset pagination seeks with a `where` clause and must not
+* look like it is paging by offset.
+*/
+function resolveFindWindow(params) {
+	const limit = params?.limit ?? DEFAULT_LIST_LIMIT;
+	const offset = params?.page != null ? Math.max(0, (params.page - 1) * limit) : params?.offset ?? 0;
+	return {
+		limit,
+		offset,
+		driverOffset: params?.page != null ? offset : params?.offset
+	};
+}
 function normalizePageSize(raw) {
 	if (raw === void 0 || !Number.isFinite(raw)) return 200;
 	return Math.max(1, Math.floor(raw));
@@ -3194,7 +3513,22 @@ function serializeLogicalCondition(cond) {
 * deserializeLogicalCondition("or(status.eq.active,age.gte.18)")
 * // → { type: "or", conditions: [...] }
 */
-function deserializeLogicalCondition(str) {
+/**
+* How deeply `or(...)`/`and(...)` groups may nest.
+*
+* This parser recurses once per level, on a value that arrives in a query
+* string. Unbounded, twenty thousand levels reached `RangeError: Maximum call
+* stack size exceeded`, which a caller sees as a 500 about the call stack
+* rather than a 400 about their filter. Node's 16 KB header cap keeps a GET
+* below that in practice, but "the HTTP layer happens to stop it" is not a
+* bound this parser should rely on.
+*
+* Thirty-two is far past anything a real filter expresses; the deepest in this
+* repository's own tests is three.
+*/
+var MAX_LOGICAL_NESTING_DEPTH = 32;
+function deserializeLogicalCondition(str, nesting = 0) {
+	if (nesting > 32) throw new Error(`Filter groups nest more than 32 levels deep. Flatten the condition — \`or(a,or(b,c))\` is \`or(a,b,c)\`.`);
 	const logicalMatch = str.match(/^(and|or)\((.+)\)$/);
 	if (logicalMatch) {
 		const type = logicalMatch[1];
@@ -3205,10 +3539,10 @@ function deserializeLogicalCondition(str) {
 		for (let i = 0; i < innerStr.length; i++) if (innerStr[i] === "(") depth++;
 		else if (innerStr[i] === ")") depth--;
 		else if (innerStr[i] === "," && depth === 0) {
-			conditions.push(deserializeLogicalCondition(innerStr.slice(start, i)));
+			conditions.push(deserializeLogicalCondition(innerStr.slice(start, i), nesting + 1));
 			start = i + 1;
 		}
-		conditions.push(deserializeLogicalCondition(innerStr.slice(start)));
+		conditions.push(deserializeLogicalCondition(innerStr.slice(start), nesting + 1));
 		return {
 			type,
 			conditions
@@ -3276,10 +3610,12 @@ function createPrimaryKeyResolver(options) {
 * than postgres still serve rows with one, and this keeps them working.
 */
 function rowToEntity(row, slug, primaryKeys = []) {
+	const { _matches, ...values } = row;
 	return {
 		id: primaryKeys.length > 0 ? buildCompositeId(row, primaryKeys) : row.id,
 		path: slug,
-		values: row
+		values,
+		..._matches ? { searchMatches: _matches } : {}
 	};
 }
 /**
@@ -3322,21 +3658,22 @@ function createDriverAccessor(driver, slug, getPks = () => []) {
 	const accessor = {
 		async find(params) {
 			const filter = params?.where ? deserializeFilter(params.where) : void 0;
-			const limit = params?.limit ?? 20;
-			const offset = params?.offset ?? 0;
+			const { limit, offset, driverOffset } = resolveFindWindow(params);
 			const fetchService = driver.restFetchService;
 			const rows = fetchService ? await fetchService.fetchCollectionForRest(slug, {
 				filter,
-				limit: params?.limit,
-				offset: params?.offset,
+				logical: params?.logical,
+				limit,
+				offset: driverOffset,
 				orderBy: params?.orderBy?.[0],
 				order: params?.orderBy?.[1],
 				searchString: params?.searchString
 			}, params?.include) : await driver.fetchCollection({
 				path: slug,
-				limit: params?.limit,
-				offset: params?.offset,
+				limit,
+				offset: driverOffset,
 				filter,
+				logical: params?.logical,
 				orderBy: params?.orderBy?.[0],
 				order: params?.orderBy?.[1],
 				searchString: params?.searchString
@@ -3346,7 +3683,9 @@ function createDriverAccessor(driver, slug, getPks = () => []) {
 			if (driver.count) {
 				total = await driver.count({
 					path: slug,
-					filter
+					filter,
+					logical: params?.logical,
+					searchString: params?.searchString
 				});
 				hasMore = offset + rows.length < total;
 			}
@@ -3398,30 +3737,48 @@ function createDriverAccessor(driver, slug, getPks = () => []) {
 				values: {}
 			} });
 		},
+		updateMany: driver.updateMany ? async (updates) => {
+			return (await driver.updateMany({
+				path: slug,
+				updates: updates.map((u) => ({
+					id: u.id,
+					values: u.data
+				}))
+			})).map((row) => rowToEntity(row, slug, getPks()));
+		} : void 0,
+		deleteMany: driver.deleteMany ? async (ids) => {
+			await driver.deleteMany({
+				path: slug,
+				ids
+			});
+		} : void 0,
 		count: driver.count ? async (params) => {
 			const filter = params?.where ? deserializeFilter(params.where) : void 0;
 			return driver.count({
 				path: slug,
-				filter
+				filter,
+				logical: params?.logical,
+				searchString: params?.searchString
 			});
 		} : void 0,
 		listen: driver.listenCollection ? (params, onUpdate, onError) => {
-			const limit = params?.limit ?? 20;
-			const offset = params?.offset ?? 0;
+			const { limit, offset, driverOffset } = resolveFindWindow(params);
 			const normalize = driver.restFetchService ? inlineRelationRefs : (row) => row;
 			return driver.listenCollection({
 				path: slug,
-				limit: params?.limit,
-				offset: params?.offset,
+				limit,
+				offset: driverOffset,
 				filter: params?.where,
+				logical: params?.logical,
 				orderBy: params?.orderBy?.[0],
 				order: params?.orderBy?.[1],
 				searchString: params?.searchString,
+				searchExplain: params?.searchExplain,
 				onUpdate: (entities) => {
 					onUpdate({
 						data: entities.map((row) => rowToEntity(normalize(row), slug, getPks())),
 						meta: {
-							total: entities.length,
+							total: offset + entities.length,
 							limit,
 							offset,
 							hasMore: entities.length >= limit
@@ -3454,8 +3811,11 @@ function createDriverAccessor(driver, slug, getPks = () => []) {
 		offset(count) {
 			return new QueryBuilder(accessor).offset(count);
 		},
-		search(searchString) {
-			return new QueryBuilder(accessor).search(searchString);
+		search(searchString, options) {
+			return new QueryBuilder(accessor).search(searchString, options);
+		},
+		vectorSearch(property, vector, options) {
+			return new QueryBuilder(accessor).vectorSearch(property, vector, options);
 		},
 		include(...relations) {
 			return new QueryBuilder(accessor).include(...relations);
@@ -3543,8 +3903,18 @@ var SdkQueryBuilder = class {
 		this.params.offset = count;
 		return this;
 	}
-	search(searchString) {
+	search(searchString, options) {
 		this.params.searchString = searchString;
+		if (options?.explain !== void 0) this.params.searchExplain = options.explain;
+		return this;
+	}
+	vectorSearch(property, vector, options) {
+		this.params.vectorSearch = {
+			property,
+			vector,
+			...options?.distance !== void 0 && { distance: options.distance },
+			...options?.threshold !== void 0 && { threshold: options.threshold }
+		};
 		return this;
 	}
 	include(...relations) {
@@ -3598,9 +3968,24 @@ function toSdkCollectionClient(snap, slug = "collection") {
 		async update(id, data) {
 			return entityToRow(await snap.update(id, data));
 		},
+		async updateMany(updates) {
+			if (!Array.isArray(updates)) throw new TypeError("updateMany expects an array of { id, data } entries.");
+			if (updates.length === 0) return [];
+			if (!snap.updateMany) throw new Error("Bulk updates are not supported by this collection's data source. Fall back to update() per record.");
+			return (await snap.updateMany(updates.map((u) => ({
+				id: u.id,
+				data: u.data
+			})))).map(entityToRow);
+		},
 		delete(id) {
 			return snap.delete(id);
 		},
+		async deleteMany(ids) {
+			if (!Array.isArray(ids)) throw new TypeError("deleteMany expects an array of ids.");
+			if (ids.length === 0) return;
+			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,
 		listen: snap.listen ? (params, onUpdate, onError) => snap.listen(params, (res) => onUpdate({
 			data: res.data.map(entityToRow),
@@ -3616,6 +4001,7 @@ function toSdkCollectionClient(snap, slug = "collection") {
 		limit: (count) => new SdkQueryBuilder(client).limit(count),
 		offset: (count) => new SdkQueryBuilder(client).offset(count),
 		search: (searchString) => new SdkQueryBuilder(client).search(searchString),
+		vectorSearch: (property, vector, options) => new SdkQueryBuilder(client).vectorSearch(property, vector, options),
 		include: (...relations) => new SdkQueryBuilder(client).include(...relations)
 	};
 	return client;
@@ -3623,7 +4009,7 @@ function toSdkCollectionClient(snap, slug = "collection") {
 /**
 * Wrap a flat {@link SDKCollectionClient} into a Entity-shaped
 * {@link CollectionAccessor}. Every returned row is re-wrapped into the
-* `{ id, path, values }` view-model the admin admin renders.
+* `{ id, path, values }` view-model the admin panel renders.
 */
 function toEntityAccessor(sdk, slug, getPks = () => []) {
 	const accessor = {
@@ -3664,6 +4050,7 @@ function toEntityAccessor(sdk, slug, getPks = () => []) {
 		limit: (count) => new QueryBuilder(accessor).limit(count),
 		offset: (count) => new QueryBuilder(accessor).offset(count),
 		search: (searchString) => new QueryBuilder(accessor).search(searchString),
+		vectorSearch: (property, vector, options) => new QueryBuilder(accessor).vectorSearch(property, vector, options),
 		include: (...relations) => new QueryBuilder(accessor).include(...relations)
 	};
 	return accessor;
@@ -3677,6 +4064,15 @@ function toEntityAccessor(sdk, slug, getPks = () => []) {
 * admin `RebaseDataContext` — without it the admin renders rows with only their
 * `id`.
 */
+/**
+* Only the by-slug accessor is asked for, so only that is required.
+*
+* Taking a whole `RebaseSdkData` meant taking `RebaseSdkData<unknown>`, whose
+* dynamic branch is an index signature — and no `RebaseSdkData<DB>` satisfies
+* it, because its own `collection` method is not a `SDKCollectionClient`. So a
+* caller holding a *typed* client could not pass it to a function that reads
+* one method off it, and that method is identical on every instantiation.
+*/
 function wrapAsEntityData(sdkData, options) {
 	const cache = /* @__PURE__ */ new Map();
 	const primaryKeysFor = createPrimaryKeyResolver(options);
@@ -3906,6 +4302,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, QueryBuilder, REBASE_INTERNAL_PREFIXES, REBASE_INTERNAL_SCHEMAS, RebasePaginationError, 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, detectJunctionTables, embedParentExpression, enumToObjectEntries, evaluateCondition, evaluatePolicy, findAnonymousGrants, findRelation, fullPathToCollectionSegments, getArrayResolvedProperties, getColumnName, getDeclaredPrimaryKeys, getDefaultValueFor, getDefaultValueFortype, getDefaultValuesFor, getEffectiveSecurityRules, getEntityChildViews, getEnumVarName, getGeneratedPolicyNames, getInjectedSecurityRules, getJunctionCollectionConfig, getJunctionSecurityRules, getLabelOrConfigFrom, getPrimaryKeys, getReferenceFrom, getRelationFrom, getSubcollections, getTableName, getTableVarName, isAddressableId, isJunctionBackedRelation, isPropertyBuilder, isRebaseInternalTable, normalizeEmail, normalizeToEntityRelation, or, paginateFind, parseIdValues, policyToPostgres, registerConditionOperations, resolveArrayProperties, resolveCollectionRelations, resolveDataSource, resolveEnumValues, resolveJunctionSpecs, resolvePrimaryKeys, resolveProperties, resolveProperty, resolvePropertyEnum, resolveRelation, resolveRelationProperty, resolveStorageFilenameString, resolveStoragePathString, resolveStorageSource, resolveStringColumnLength, sanitizeData, securityRuleToConditions, segmentsToStrippedPath, serializeFilter, serializeLogicalCondition, serializeOrderBy, sortProperties, sqlToPolicy, stripCollectionPath, traverseValueProperty, traverseValuesProperties, updateDateAutoValues, wrapAsEntityData, wrapAsSdkData };
+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, QueryBuilder, REBASE_INTERNAL_PREFIXES, REBASE_INTERNAL_SCHEMAS, REBASE_INTERNAL_TABLES, REBASE_USER_ROLE, RebasePaginationError, 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, detectJunctionTables, embedParentExpression, enumToObjectEntries, evaluateCondition, evaluatePolicy, 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, normalizeEmail, normalizeToEntityRelation, or, paginateFind, parseIdValues, policyToPostgres, 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, sortProperties, sqlToPolicy, stripCollectionPath, traverseValueProperty, traverseValuesProperties, updateDateAutoValues, wrapAsEntityData, wrapAsSdkData };
 
 //# sourceMappingURL=index.es.js.map