@protobase/query 0.12.21 → 0.13.0

package/dist/cursor.js

@@ -1,37 +1,43 @@
 import { QueryError } from "./fields/query-error.js";
+import { filterFingerprint } from "./filter-fingerprint.js";
 import { sortSignature } from "./sort.js";
 //#region src/cursor.ts
-const invalidCursor = () => new QueryError("invalid_cursor", "Cursor is malformed or does not match the requested sort");
+const invalidCursor = () => new QueryError("invalid_cursor", "Cursor is malformed or does not match the requested sort and filter");
 const isStringList = (value) => Array.isArray(value) && value.every((item) => typeof item === "string");
 const isCellList = (value) => Array.isArray(value) && value.every((item) => item === null || typeof item === "string");
 /**
 * Opaque cursor: the sort signature plus the row's sort values as text (so timestamps and bigints round-trip exactly,
-* null for NULL values). The JSON is UTF-8 encoded before base64url, so any text value survives.
+* null for NULL values), and a fingerprint of the filter when there is one, so a cursor only continues the list it
+* came from (AIP-158). The JSON is UTF-8 encoded before base64url, so any text value survives.
 * `values` may be a prefix of the sort keys; such a boundary cursor is produced by scroll anchors.
 */
-const encodeCursor = (keys, values) => {
+const encodeCursor = (keys, values, filter) => {
+	const fingerprint = filterFingerprint(filter);
 	const payload = {
 		s: sortSignature(keys).slice(0, values.length),
-		v: values
+		v: values,
+		...fingerprint && { f: fingerprint }
 	};
 	return toBase64Url(JSON.stringify(payload));
 };
-const decodeCursor = (cursor, keys) => {
+const decodeCursor = (cursor, keys, filter) => {
 	const payload = parse(cursor);
 	const signature = sortSignature(keys);
 	const prefixOk = payload.s.length === payload.v.length && payload.s.every((part, i) => part === signature[i]);
 	const lengthOk = payload.v.length === keys.length || payload.v.length === 1;
-	if (!prefixOk || !lengthOk) throw invalidCursor();
+	const filterOk = (payload.f ?? "") === filterFingerprint(filter);
+	if (!prefixOk || !lengthOk || !filterOk) throw invalidCursor();
 	return payload.v;
 };
 const parse = (cursor) => {
 	const payload = parseJson(cursor);
 	if (typeof payload !== "object" || payload === null) throw invalidCursor();
-	const { s, v } = payload;
-	if (!isStringList(s) || !isCellList(v)) throw invalidCursor();
+	const { s, v, f } = payload;
+	if (!isStringList(s) || !isCellList(v) || f !== void 0 && typeof f !== "string") throw invalidCursor();
 	return {
 		s,
-		v
+		v,
+		...f !== void 0 && { f }
 	};
 };
 const toBase64Url = (text) => btoa(String.fromCharCode(...new TextEncoder().encode(text))).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");

package/dist/filter-fingerprint.js

@@ -0,0 +1,24 @@
+//#region src/filter-fingerprint.ts
+/** The filter's structure without source spans, each field named by its column, so equal filters match however they were written. */
+const canonical = (filter) => JSON.stringify(filter, (key, value) => {
+	if (key === "span") return void 0;
+	if (key === "field") return value.column;
+	return value;
+});
+/** cyrb53, a fast 53-bit string hash; the fingerprint guards against mistakes, not forgery. */
+const hash = (text) => {
+	let h1 = 3735928559;
+	let h2 = 1103547991;
+	for (let i = 0; i < text.length; i++) {
+		const code = text.charCodeAt(i);
+		h1 = Math.imul(h1 ^ code, 2654435761);
+		h2 = Math.imul(h2 ^ code, 1597334677);
+	}
+	h1 = Math.imul(h1 ^ h1 >>> 16, 2246822507) ^ Math.imul(h2 ^ h2 >>> 13, 3266489909);
+	h2 = Math.imul(h2 ^ h2 >>> 16, 2246822507) ^ Math.imul(h1 ^ h1 >>> 13, 3266489909);
+	return (4294967296 * (2097151 & h2) + (h1 >>> 0)).toString(36);
+};
+/** A short fingerprint of the filter a cursor was issued for; empty without a filter. */
+const filterFingerprint = (filter) => filter ? hash(canonical(filter)) : "";
+//#endregion
+export { filterFingerprint };

package/dist/list-query.js

@@ -33,7 +33,7 @@ const buildListQuery = async (db, model, query, scope, options = {}) => {
 	const limit = clampLimit(query.limit);
 	await assertFilterRequirements(db, query.filter, scope);
 	const keys = effectiveSort(model, query.sort);
-	const cursorValues = query.cursor === void 0 ? void 0 : decodeCursor(query.cursor, keys);
+	const cursorValues = query.cursor === void 0 ? void 0 : decodeCursor(query.cursor, keys, query.filter);
 	return {
 		query: selectPage(db, model, query, scope, keys, cursorValues, options),
 		limit,
@@ -48,7 +48,7 @@ const listQuery = async (db, model, query, scope, options = {}) => {
 	const more = fetched.length > limit;
 	const page = more ? fetched.slice(0, limit) : fetched;
 	if (reverse) page.reverse();
-	const cursorOf = (row) => encodeCursor(keys, keys.map((_, i) => row[keyAlias(i)] === null ? null : String(row[keyAlias(i)])));
+	const cursorOf = (row) => encodeCursor(keys, keys.map((_, i) => row[keyAlias(i)] === null ? null : String(row[keyAlias(i)])), query.filter);
 	const first = page[0];
 	const last = page.at(-1);
 	return {

package/dist/scroll-anchors.js

@@ -60,7 +60,7 @@ const scrollAnchors = async (db, model, sortField, options = {}) => {
 		seekToPosition: async (position) => {
 			if (position <= 0) return void 0;
 			const anchor = anchors.findLast((candidate) => candidate.position <= position);
-			return anchor && anchor.position > 0 ? encodeCursor(keys, [anchor.value]) : void 0;
+			return anchor && anchor.position > 0 ? encodeCursor(keys, [anchor.value], filter) : void 0;
 		}
 	};
 };

package/dist/scroll-exact.js

@@ -21,7 +21,7 @@ const exactSeek = async (db, model, keys, scope, filter, position) => {
 	if (position <= 0) return void 0;
 	const row = await db.selectFrom(rankedRows(db, model, keys, scope, filter).as("r")).selectAll().where(sql`r.rn = ${position}`).executeTakeFirst();
 	if (!row) return void 0;
-	return encodeCursor(keys, keys.map((_, i) => row[`k${i}`] === null ? null : String(row[`k${i}`])));
+	return encodeCursor(keys, keys.map((_, i) => row[`k${i}`] === null ? null : String(row[`k${i}`])), filter);
 };
 //#endregion
 export { exactAnchors, exactSeek };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/query",
-  "version": "0.12.21",
+  "version": "0.13.0",
   "description": "Kysely list, filter, count and aggregate queries over Protobase resources.",
   "license": "Apache-2.0",
   "repository": {
@@ -29,7 +29,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@protobase/schema": "0.12.21",
+    "@protobase/schema": "0.13.0",
     "kysely": "^0.29.6"
   }
 }