@terrascale/sdk 0.0.6 → 0.0.7

package/src/v1/filter.js

@@ -24,7 +24,17 @@ import { ExactDecimal } from "./json.js";
  *   | { readonly nin: readonly [V1Path, readonly V1Scalar[]] }
  *   | { readonly exists: V1Path }
  *   | { readonly prefix: readonly [V1Path, string] }
- *   | { readonly contains: readonly [V1Path, V1Scalar] }} V1Filter
+ *   | { readonly contains: readonly [V1Path, V1Scalar] }
+ *   | { readonly within: readonly [string, V1GeoCircle | V1GeoBox] }
+ *   | { readonly search: readonly [V1Path, string] }} V1Filter
+ */
+/**
+ * Points within `meters` (more than 0, at most 20000000) of a WGS 84 point, by haversine distance.
+ * @typedef {{ readonly lat: number; readonly lon: number; readonly meters: number }} V1GeoCircle
+ */
+/**
+ * Points in a latitude/longitude box; `west > east` crosses the antimeridian.
+ * @typedef {{ readonly south: number; readonly west: number; readonly north: number; readonly east: number }} V1GeoBox
  */
 
 /**
@@ -54,6 +64,28 @@ export function requirePath(path) {
   throw new TypeError('A TerraBase path is an RFC 6901 JSON Pointer of 1-16 segments, "$id".');
 }
 
+/** @param {V1Path} path @returns {V1Path} */
+function requireSearchPath(path) {
+  if (isJsonPointer(path)) return path;
+  throw new TypeError("search requires a JSON Pointer of 1-16 segments, excluding $id.");
+}
+
+/** @param {unknown} terms @returns {string} */
+function requireSearchTerms(terms) {
+  if (typeof terms !== "string" || terms.length === 0 || terms.includes("\0") || /[\uD800-\uDFFF]/u.test(terms) || new TextEncoder().encode(terms).byteLength > 4096)
+    throw new TypeError("search takes nonempty string terms of at most 4096 UTF-8 bytes without NUL.");
+  return terms;
+}
+
+/** @param {V1Filter | null | undefined} filter @returns {number} */
+export function searchCount(filter) {
+  if (!filter) return 0;
+  if ("search" in filter) return 1;
+  if ("and" in filter) return filter.and.reduce((count, child) => count + searchCount(child), 0);
+  if ("or" in filter) return filter.or.reduce((count, child) => count + searchCount(child), 0);
+  return "not" in filter ? searchCount(filter.not) : 0;
+}
+
 /**
  * @param {V1Scalar} value
  * @returns {V1Scalar}
@@ -92,6 +124,46 @@ function scalars(op, values) {
   return Object.freeze(values.map(requireScalar));
 }
 
+/**
+ * @param {unknown} lat
+ * @param {unknown} lon
+ * @returns {void}
+ */
+export function requireGeoPoint(lat, lon) {
+  if (typeof lat !== "number" || typeof lon !== "number" || !(lat >= -90 && lat <= 90 && lon >= -180 && lon <= 180))
+    throw new TypeError("lat is -90 to 90 and lon is -180 to 180.");
+}
+
+/**
+ * @param {unknown} area
+ * @returns {V1GeoCircle | V1GeoBox}
+ */
+function geoArea(area) {
+  if (typeof area !== "object" || area === null || Array.isArray(area)) throw new TypeError("within takes a circle or box object.");
+  const keys = Object.keys(area).sort().join();
+  const a = /** @type {Record<string, unknown>} */ (area);
+  if (keys === "east,north,south,west") {
+    requireGeoPoint(a.south, a.west);
+    requireGeoPoint(a.north, a.east);
+    if (/** @type {number} */ (a.south) > /** @type {number} */ (a.north)) throw new TypeError("A within box has south <= north.");
+    return Object.freeze({ south: /** @type {number} */ (a.south), west: /** @type {number} */ (a.west), north: /** @type {number} */ (a.north), east: /** @type {number} */ (a.east) });
+  }
+  if (keys !== "lat,lon,meters" || typeof a.meters !== "number" || !(a.meters > 0 && a.meters <= 20_000_000))
+    throw new TypeError("within takes {lat, lon, meters (0 to 20000000)} or {south, west, north, east}.");
+  requireGeoPoint(a.lat, a.lon);
+  return Object.freeze({ lat: /** @type {number} */ (a.lat), lon: /** @type {number} */ (a.lon), meters: a.meters });
+}
+
+/**
+ * @param {V1Path} path
+ * @param {unknown} area
+ * @returns {V1Filter}
+ */
+function within(path, area) {
+  if (requirePath(path) === "$id") throw new TypeError("within takes a JSON Pointer.");
+  return Object.freeze({ within: Object.freeze(/** @type {const} */ ([path, geoArea(area)])) });
+}
+
 const binaryOperators = new Set(["eq", "ne", "lt", "lte", "gt", "gte", "contains"]);
 
 /**
@@ -119,7 +191,15 @@ export function requireFilter(filter) {
       for (const child of args) visit(child, depth + 1);
     } else if (op === "not") visit(args, depth + 1);
     else if (op === "exists") requirePath(/** @type {V1Path} */ (args));
-    else if (binaryOperators.has(op) || op === "prefix" || op === "in" || op === "nin") {
+    else if (op === "within") {
+      if (!Array.isArray(args) || args.length !== 2) throw new TypeError("within takes [path, area].");
+      within(args[0], args[1]);
+    }
+    else if (op === "search") {
+      if (!Array.isArray(args) || args.length !== 2) throw new TypeError("search takes [path, terms].");
+      requireSearchPath(args[0]);
+      requireSearchTerms(args[1]);
+    } else if (binaryOperators.has(op) || op === "prefix" || op === "in" || op === "nin") {
       if (!Array.isArray(args) || args.length !== 2) throw new TypeError(`${op} takes [path, value].`);
       requirePath(args[0]);
       if (op === "in" || op === "nin") scalars(op, args[1]);
@@ -220,6 +300,13 @@ export const v1Filter = Object.freeze({
     if (typeof prefix !== "string") throw new TypeError("prefix takes a string.");
     return Object.freeze({ prefix: Object.freeze(/** @type {const} */ ([requirePath(path), prefix])) });
   },
+  /**
+   * Full-text search on a document member.
+   * @param {V1Path} path
+   * @param {string} terms
+   * @returns {V1Filter}
+   */
+  search: (path, terms) => Object.freeze({ search: Object.freeze(/** @type {const} */ ([requireSearchPath(path), requireSearchTerms(terms)])) }),
   /**
    * The value is an array containing the scalar.
    * @param {V1Path} path
@@ -227,4 +314,18 @@ export const v1Filter = Object.freeze({
    * @returns {V1Filter}
    */
   contains: (path, value) => Object.freeze({ contains: Object.freeze(/** @type {const} */ ([requirePath(path), requireScalar(value)])) }),
+  /**
+   * The `{lat, lon}` object at `path` lies within `meters` of the center (haversine, WGS 84 mean radius).
+   * @param {string} path JSON Pointer of a `{lat, lon}` point.
+   * @param {V1GeoCircle} circle `meters` is more than 0, at most 20000000.
+   * @returns {V1Filter}
+   */
+  withinRadius: (path, circle) => within(path, { lat: circle?.lat, lon: circle?.lon, meters: circle?.meters }),
+  /**
+   * The `{lat, lon}` object at `path` lies in the box; `west > east` crosses the antimeridian.
+   * @param {string} path JSON Pointer of a `{lat, lon}` point.
+   * @param {V1GeoBox} box
+   * @returns {V1Filter}
+   */
+  withinBox: (path, box) => within(path, { south: box?.south, west: box?.west, north: box?.north, east: box?.east }),
 });

package/src/v1/ids.js

@@ -27,11 +27,16 @@ export function requireProject(project) {
   return requireId(project);
 }
 
-/** A caller-supplied key is not a generated entity ID. @param {unknown} id @returns {string} */
+/** Every document id is a canonical ULID. @param {unknown} id @returns {string} */
 export function requireDocumentId(id) {
+  return requireId(id, "TerraBase document ID");
+}
+
+/** SQL-backed collections can return non-ULID primary keys. @param {unknown} id @returns {string} */
+export function requireStoredId(id) {
   if (typeof id !== "string" || id.length < 1 || id.length > 256 ||
       /[\u0000-\u001f\u007f-\u009f\ud800-\udfff]/u.test(id))
-    throw new TypeError("TerraBase document keys must be 1-256 characters of valid UTF-8 without control characters.");
+    throw new TypeError("TerraBase stored IDs must be 1-256 characters of valid UTF-8 without control characters.");
   return id;
 }
 

package/src/v1/indexes.js

@@ -1,10 +1,10 @@
 import { requireName } from "./ids.js";
-import { flag, list, numeric, record, text } from "./management-decode.js";
+import { flag, list, numeric, optional, record, text } from "./management-decode.js";
 import { members, mutationOptions } from "./management-validation.js";
 import { stringifyExactJson } from "./json.js";
 /** @import { V1Transport } from "./transport.js" */
 /** @import { V1RequestOptions } from "./terrabase-v1.js" */
-const index = record({ name: text, collection: text, fields: list(text), state: text });
+const index = record({ name: text, collection: text, fields: list(text), state: text, kind: optional(text) });
 const indexes = record({ items: list(index) });
 const policy = record({ collection: text, enabled: flag });
 const recommendations = record({ items: list(record({ id: text, collection: text, fields: list(text), reason: text, queries: numeric })) });
@@ -14,7 +14,8 @@ const applied = record({ status: text, index });
 /** @typedef {ReturnType<typeof policy>} V1AutoIndexPolicy */
 /** @typedef {ReturnType<typeof recommendations>} V1IndexRecommendations */
 /** @typedef {ReturnType<typeof applied>} V1AppliedIndexRecommendation */
-/** @typedef {{ readonly collection: string; readonly fields: readonly string[]; readonly name?: string | null }} V1CreateIndexRequest */
+/** @typedef {"btree" | "text"} V1IndexKind */
+/** @typedef {{ readonly collection: string; readonly fields: readonly string[]; readonly name?: string | null; readonly kind?: V1IndexKind }} V1CreateIndexRequest */
 /** @param {unknown} value @returns {string} */
 function indexName(value) {
   if (typeof value !== "string" || !/^[a-z][a-z0-9_]{0,62}$/u.test(value)) throw new TypeError("Invalid index name.");
@@ -31,7 +32,8 @@ export class V1Indexes {
   constructor(transport, database) { this.#transport = transport; this.#params = { database: requireName("database", database) }; Object.freeze(this); }
   /** @param {V1CreateIndexRequest} request @param {V1RequestOptions} [options] @returns {Promise<V1Index>} */
   async create(request, options = {}) {
-    members(request, ["collection", "fields", "name"]);
+    members(request, ["collection", "fields", "name", "kind"]);
+    if (request.kind !== undefined && request.kind !== "btree" && request.kind !== "text") throw new TypeError("kind must be btree or text.");
     requireName("collection", request.collection);
     if (!Array.isArray(request.fields) || request.fields.length < 1 || request.fields.length > 4 ||
         new Set(request.fields).size !== request.fields.length || request.fields.some(f => typeof f !== "string" || f === "_id" || f === "_rev" || !/^[A-Za-z_][A-Za-z0-9_]{0,63}(?:\.[A-Za-z_][A-Za-z0-9_]{0,63}){0,7}$/u.test(f)))

package/src/v1/shape-reader.js

@@ -5,6 +5,7 @@ import { decodeShapePage, encodeShapeRequest, requireShapeHandle, requireShapeOf
 import { decryptShapeObject } from "./shape-crypto.js";
 import { parseExactJson } from "./json.js";
 import { TerraBaseV1Error } from "./errors.js";
+import { OpaqueRedirectError } from "./transport.js";
 /** @import { V1Transport } from "./transport.js" */
 /** @import { V1ShapeRequest, V1ShapePage } from "./shapes.js" */
 /** @typedef {{handle: string; offset: string; epoch: string; keyId: string}} V1SealedShapePosition */
@@ -125,11 +126,9 @@ export async function readShapePage(transport, params, request, signal, ifNoneMa
       query.delete("cursor");
     }
   }
-  let response = await shapeCall(transport, params, "readFreeShape", { query, headers, signal });
-  if (response.status === 307) {
-    if (query.get("offset") !== "-1") malformed("unexpected shape redirect");
-    const location = response.headers.get("location");
-    if (location === null) malformed("shape redirect Location");
+  const bootstrap = query.get("offset") === "-1";
+  /** @param {string} location */
+  const redirectTarget = location => {
     const target = new URL(location, source);
     if (target.origin !== source.origin || target.pathname !== source.pathname || target.username !== "" || target.password !== "" || target.hash !== "") malformed("shape redirect target");
     for (const key of target.searchParams.keys()) {
@@ -144,6 +143,21 @@ export async function readShapePage(transport, params, request, signal, ifNoneMa
     delete headers["TB-Shape-Resume"];
     query.set("handle", handle);
     query.set("offset", offset);
+  };
+  let response;
+  try { response = await shapeCall(transport, params, "readFreeShape", { query, headers, signal }); }
+  catch (error) {
+    if (!(error instanceof OpaqueRedirectError) || !bootstrap) throw error;
+    // Browsers hide a manual 307; follow it natively, then hold the final URL to the Location rules.
+    response = await shapeCall(transport, params, "readFreeShape", { query: new URLSearchParams(query), headers: { ...headers }, signal, redirect: "follow" });
+    if (response.redirectedTo === undefined || response.status !== 200) malformed("shape bootstrap requires redirect");
+    redirectTarget(response.redirectedTo);
+  }
+  if (response.status === 307) {
+    if (!bootstrap) malformed("unexpected shape redirect");
+    const location = response.headers.get("location");
+    if (location === null) malformed("shape redirect Location");
+    redirectTarget(location);
     response = await shapeCall(transport, params, "readFreeShape", { query, headers, signal });
     if (response.status !== 200) malformed("repeated shape redirect");
   } else if (query.get("offset") === "-1") malformed("shape bootstrap requires redirect");

package/src/v1/shape-replica.js

@@ -0,0 +1,46 @@
+// Browser storage for a shape subscription's read replica. Durable writes never queue here.
+/** @import { V1ShapeReplicaStore } from "./shape-subscription.js" */
+
+/**
+ * A V1ShapeReplicaStore kept in browser IndexedDB, one record per key.
+ * @param {string} key Names one subject's shape, e.g. `${userId}/notes/open`; clear it on sign-out.
+ * @returns {V1ShapeReplicaStore}
+ */
+export function indexedDbShapeReplica(key) {
+  if (typeof key !== "string" || key === "") throw new TypeError("An IndexedDB replica key is a non-empty string.");
+  /** @type {Promise<IDBDatabase> | undefined} */
+  let opened;
+  /** @returns {Promise<IDBDatabase>} */
+  const open = () => opened ??= new Promise((resolve, reject) => {
+    const request = indexedDB.open("terrascale-shape-replicas", 1);
+    request.onupgradeneeded = () => { request.result.createObjectStore("replicas"); };
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => { opened = undefined; reject(request.error); };
+  });
+  /**
+   * @template T
+   * @param {IDBTransactionMode} mode
+   * @param {(store: IDBObjectStore) => IDBRequest<T>} operation
+   * @returns {Promise<T>}
+   */
+  const run = async (mode, operation) => {
+    const database = await open();
+    return new Promise((resolve, reject) => {
+      const transaction = database.transaction("replicas", mode);
+      const request = operation(transaction.objectStore("replicas"));
+      transaction.oncomplete = () => resolve(request.result);
+      transaction.onerror = transaction.onabort = () => reject(transaction.error ?? request.error);
+    });
+  };
+  return Object.freeze({
+    load: async () => {
+      const value = await run("readonly", store => store.get(key));
+      return typeof value === "string" ? value : undefined;
+    },
+    /** @param {string | undefined} text */
+    save: async text => {
+      if (text === undefined) await run("readwrite", store => store.delete(key));
+      else await run("readwrite", store => store.put(text, key));
+    },
+  });
+}

package/src/v1/shape-subscription.js

@@ -3,6 +3,7 @@ import { TerraBaseV1Error } from "./errors.js";
 import { requireFilter } from "./filter.js";
 import { parseExactJson, stringifyExactJson } from "./json.js";
 import { readShapePage } from "./shape-reader.js";
+import { BodyTransportError, RequestTransportError } from "./transport.js";
 /**
  * @import { JsonObject } from "./json.js"
  * @import { V1Filter } from "./filter.js"
@@ -12,6 +13,14 @@ import { readShapePage } from "./shape-reader.js";
  * @typedef {object} V1ShapeSubscribeOptions
  * @property {AbortSignal | undefined} [signal] Closes the subscription when aborted; cancellation settles `done`.
  * @property {((subscription: V1ShapeSubscription) => void) | undefined} [onUpdate] Runs after validated responses and freshness changes; throwing rejects `done` unless already closed or aborted.
+ * @property {V1ShapeReplicaStore | undefined} [replica] Keeps the last resumable state for reads across restarts and while offline; writes still go to the server.
+ */
+/**
+ * Holds one subscription's state as exact JSON text, e.g. in IndexedDB or React Native storage. Scope one store
+ * to one signed-in subject: the replica holds that subject's authorized documents. A failing store rejects `done`.
+ * @typedef {object} V1ShapeReplicaStore
+ * @property {() => string | undefined | Promise<string | undefined>} load
+ * @property {(text: string | undefined) => void | Promise<void>} save Receives undefined after must_refetch discards state.
  */
 /** @typedef {{ readonly version: string; readonly document: JsonObject }} V1ShapeDocument */
 const retryBaseMilliseconds = 250;
@@ -81,6 +90,9 @@ export class V1ShapeSubscription {
   /** @type {V1Filter | undefined} */
   #where;
   #onUpdate;
+  #replica;
+  /** @type {string} */
+  #scope;
   #external;
   #onExternalAbort = () => this.close();
   #done;
@@ -92,9 +104,11 @@ export class V1ShapeSubscription {
    */
   constructor(transport, params, shape = {}, options = {}) {
     requireMembers(shape, ["where"], "shape");
-    requireMembers(options, ["signal", "onUpdate"], "shape subscribe option");
+    requireMembers(options, ["signal", "onUpdate", "replica"], "shape subscribe option");
     const { where } = shape;
-    const { signal, onUpdate } = options;
+    const { signal, onUpdate, replica } = options;
+    if (replica !== undefined && (typeof replica?.load !== "function" || typeof replica.save !== "function"))
+      throw new TypeError("replica has load and save functions.");
     if (signal !== undefined && !(signal instanceof AbortSignal)) throw new TypeError("signal is an AbortSignal.");
     if (onUpdate !== undefined && typeof onUpdate !== "function") throw new TypeError("onUpdate is a function.");
     this.#transport = transport;
@@ -102,6 +116,9 @@ export class V1ShapeSubscription {
     // Exact copy: a structuredClone would lose the source text of large or fractional JSON numbers.
     this.#where = where === undefined ? undefined : requireFilter(parseExactJson(stringifyExactJson(requireFilter(where), "shape filter")));
     this.#onUpdate = onUpdate;
+    this.#replica = replica;
+    // A replica restores only the identical shape it was saved from.
+    this.#scope = stringifyExactJson([this.#params.database, this.#params.collection, this.#where ?? null], "shape scope");
     this.#external = signal;
     if (signal?.aborted === true) this.close();
     else signal?.addEventListener("abort", this.#onExternalAbort);
@@ -120,6 +137,7 @@ export class V1ShapeSubscription {
     const signal = this.#controller.signal;
     let retries = 0;
     try {
+      if (this.#replica !== undefined) await this.#restore(signal);
       for (;;) {
         signal.throwIfAborted();
         const request = this.#request();
@@ -127,18 +145,22 @@ export class V1ShapeSubscription {
         try {
           page = await readShapePage(this.#transport, this.#params, request, signal);
         } catch (error) {
-          if (!(error instanceof TerraBaseV1Error)) throw error;
-          if (isRetryable(error)) {
+          // Shape reads are replay-safe GETs: a lost connection keeps state and resumes at the same position.
+          const lost = error instanceof RequestTransportError || error instanceof BodyTransportError;
+          if (lost || (error instanceof TerraBaseV1Error && isRetryable(error))) {
             retries = Math.min(retries + 1, maximumBackoffAttempt);
-            await sleep(retryDelay(retries, error.retryAfter), signal);
+            await sleep(retryDelay(retries, lost ? undefined : error.retryAfter), signal);
             continue;
           }
+          if (!(error instanceof TerraBaseV1Error)) throw error;
           if (error.status !== 409 || error.code !== "must_refetch") throw error;
           this.#recover(request, error);
+          if (this.#handle === undefined) await this.#replica?.save(undefined);
           continue;
         }
         retries = 0;
         this.#commit(page);
+        await this.#persist(signal);
         this.#onUpdate?.(this);
       }
     } catch (error) {
@@ -188,6 +210,36 @@ export class V1ShapeSubscription {
     this.#resumeAttempt = false;
     this.#onUpdate?.(this);
   }
+  /** @param {AbortSignal} signal */
+  async #restore(signal) {
+    const text = await this.#replica?.load();
+    signal.throwIfAborted();
+    if (text === undefined) return;
+    /** @type {any} */
+    let saved;
+    try { saved = parseExactJson(text); } catch { saved = undefined; }
+    // Unknown or other-shape replicas are discarded, never merged.
+    if (saved?.format !== 1 || saved.scope !== this.#scope || typeof saved.handle !== "string" || typeof saved.offset !== "string" ||
+        !/^(?:0|[1-9][0-9]*)$/u.test(saved.offset) || !Array.isArray(saved.documents) ||
+        !saved.documents.every((/** @type {any} */ item) => Array.isArray(item) && typeof item[0] === "string" &&
+          typeof item[1]?.version === "string" && typeof item[1].document === "object" && item[1].document !== null)) return;
+    this.#documents = new Map(saved.documents.map((/** @type {[string, V1ShapeDocument]} */ [id, entry]) => [id, deepFreeze({ version: entry.version, document: entry.document })]));
+    this.#handle = saved.handle;
+    this.#offset = saved.offset;
+    this.#cursor = typeof saved.cursor === "string" ? saved.cursor : undefined;
+    this.#resume = typeof saved.resume === "string" ? saved.resume : undefined;
+    // Restored state is stale until the server confirms a fresh head.
+    this.#upToDate = false;
+    this.#onUpdate?.(this);
+  }
+  /** @param {AbortSignal} signal */
+  async #persist(signal) {
+    // Snapshot pages are not resumable positions; keep the previous replica until the snapshot completes.
+    if (this.#replica === undefined || this.#handle === undefined || this.#offset.startsWith("snap.")) return;
+    await this.#replica.save(stringifyExactJson({ format: 1, scope: this.#scope, handle: this.#handle, offset: this.#offset,
+      cursor: this.#cursor ?? null, resume: this.#resume ?? null, documents: [...this.#documents] }, "shape replica"));
+    signal.throwIfAborted();
+  }
   /** @param {import("./shapes.js").V1ShapePage} page */
   #commit(page) {
     // Repeats are applied, never skipped: a repeated event can carry a newer materialized value.

package/src/v1/shapes.js

@@ -1,7 +1,7 @@
 // Current C# GET collection/shape contract (docs/shape-reads.md).
 import { array, boolean, documentObject, malformed, object, string, u64 } from "./decode.js";
 import { requireFilter } from "./filter.js";
-import { parseU64, requireDocumentId, requireVersion } from "./ids.js";
+import { parseU64, requireStoredId, requireVersion } from "./ids.js";
 import { stringifyExactJson } from "./json.js";
 /**
  * @import { JsonObject, JsonValue } from "./json.js"
@@ -56,7 +56,7 @@ export function requireShapeOffset(value) {
       const bytes = Uint8Array.from(atob(encoded.replace(/-/gu, "+").replace(/_/gu, "/")), c => c.charCodeAt(0));
       const id = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
       const canonical = btoa(String.fromCharCode(...new TextEncoder().encode(id))).replace(/\+/gu, "-").replace(/\//gu, "_").replace(/=+$/u, "");
-      if (canonical === encoded) { requireDocumentId(id); return value; }
+      if (canonical === encoded) { requireStoredId(id); return value; }
     } catch { /* Invalid base64url or UTF-8. */ }
   }
   throw new TypeError("A shape offset is -1, a signed-64-bit decimal log position, or snap.<head>.<canonical-base64url-id>.");
@@ -108,7 +108,7 @@ export function decodeShapePage(value, headers) {
       const change = object(value, "shape change");
       return Object.freeze({ offset: u64(change.offset, "shape change offset"), ops: Object.freeze(array(change.ops, "shape operations").map(value => {
         const op = object(value, "shape operation");
-        const id = requireDocumentId(op.id);
+        const id = requireStoredId(op.id);
         if (op.op === "delete") return Object.freeze({ op: /** @type {const} */ ("delete"), id });
         if (op.op !== "upsert") malformed("shape operation kind");
         return Object.freeze({ op: /** @type {const} */ ("upsert"), id, version: requireVersion(op.version), document: documentObject(op.document) });

package/src/v1/sql.js

@@ -1,5 +1,5 @@
 import { array, boolean, malformed, object, string } from "./decode.js";
-import { requireDocumentId, requireName } from "./ids.js";
+import { requireStoredId, requireName } from "./ids.js";
 /**
  * @import { JsonObject, JsonValue } from "./json.js"
  * @import { V1RequestOptions } from "./terrabase-v1.js"
@@ -41,7 +41,7 @@ function decodeResult(value) {
   const raw = object(value, "SQL result");
   const rows = array(raw.rows, "SQL rows").map(entry => {
     const row = object(entry, "SQL row");
-    return Object.freeze({ id: requireDocumentId(row.id), value: object(row.value, "SQL row value") });
+    return Object.freeze({ id: requireStoredId(row.id), value: object(row.value, "SQL row value") });
   });
   const matched = raw.matched;
   if (typeof matched !== "number" || !Number.isInteger(matched) || matched < 0 || matched > 1000 || matched !== rows.length)

package/src/v1/terrabase-v1.js

@@ -4,7 +4,7 @@ import {
   array, boolean, decodeDocument, decodeWrite, documentObject, durability, malformed, object, u64,
 } from "./decode.js";
 import { requireId } from "../ids.js";
-import { isJsonPointer, requireFilter, requirePath } from "./filter.js";
+import { searchCount, isJsonPointer, requireFilter, requireGeoPoint, requirePath } from "./filter.js";
 import { requireDocumentId, requireName, requireVersion } from "./ids.js";
 import { assertJsonObject, assertJsonValue, ExactDecimal, stringifyExactJson } from "./json.js";
 import { readShapeManifest } from "./shape-manifest.js";
@@ -66,7 +66,32 @@ import { V1ChangeWebhooks } from "./change-webhooks.js";
  * Vector similarity sort, nearest first. It must be the only sort key; limit is at most 100 and there is no cursor.
  * @typedef {{ readonly near: { readonly path: V1Path; readonly vector: readonly number[]; readonly metric?: "cosine" | "l2" | undefined } }} V1NearSortKey
  */
-/** @typedef {V1FieldSortKey | V1NearSortKey} V1SortKey */
+/**
+ * Geo distance sort: meters from a WGS 84 point to each document's `{lat, lon}` object at `path`, nearest first,
+ * returned as `distance`. Like the vector `near`, it is the only sort key, limit is at most 100 and there is no cursor.
+ * @typedef {{ readonly near: { readonly path: string; readonly lat: number; readonly lon: number } }} V1GeoNearSortKey
+ */
+/** Relevance order, only sort key with exactly one search predicate. @typedef {{ readonly path: "$score"; readonly order: "desc" }} V1ScoreSortKey */
+/** @typedef {V1FieldSortKey | V1NearSortKey | V1GeoNearSortKey | V1ScoreSortKey} V1SortKey */
+/**
+ * Groups matches instead of returning documents. Summaries consider numbers only; at most 16 summary paths in total.
+ * @typedef {object} V1Aggregate
+ * @property {readonly V1Path[] | undefined} [groupBy] 0-4 paths; without it every match is one group.
+ * @property {readonly string[] | undefined} [sum] Distinct JSON Pointers.
+ * @property {readonly string[] | undefined} [avg] Distinct JSON Pointers.
+ * @property {readonly string[] | undefined} [min] Distinct JSON Pointers.
+ * @property {readonly string[] | undefined} [max] Distinct JSON Pointers.
+ */
+/**
+ * One aggregate group. Summaries are keyed by the requested JSON Pointer; `sum` is 0 and the others null without numbers.
+ * @typedef {object} V1Group
+ * @property {readonly JsonValue[]} key One value per `groupBy` path (missing members group as null).
+ * @property {string} count Matching documents in the group (decimal u64).
+ * @property {Readonly<Record<string, number | null>> | undefined} [sum]
+ * @property {Readonly<Record<string, number | null>> | undefined} [avg]
+ * @property {Readonly<Record<string, number | null>> | undefined} [min]
+ * @property {Readonly<Record<string, number | null>> | undefined} [max]
+ */
 /**
  * A query-v1 request. Every member is optional.
  * @typedef {object} V1Query
@@ -76,6 +101,7 @@ import { V1ChangeWebhooks } from "./change-webhooks.js";
  * @property {number | undefined} [limit] 1-1000 (server default 50).
  * @property {string | null | undefined} [cursor] A previous page's `nextCursor`.
  * @property {boolean | undefined} [count] Count every match (first page only).
+ * @property {V1Aggregate | undefined} [aggregate] Answer `groups` instead of items; `limit` bounds the groups. No sort, project, cursor or count.
  */
 /** @typedef {{ readonly value: string; readonly exact: boolean }} V1Count */
 /**
@@ -83,6 +109,7 @@ import { V1ChangeWebhooks } from "./change-webhooks.js";
  * @property {readonly V1Document[]} items Documents in query order.
  * @property {string | null} nextCursor
  * @property {V1Count | undefined} count
+ * @property {readonly V1Group[] | undefined} groups An aggregate query's groups in key order (`items` is then empty).
  */
 
 /** @typedef {{ readonly ifMatch: string } | { readonly ifNoneMatchAny: true }} V1Precondition */
@@ -99,7 +126,8 @@ import { V1ChangeWebhooks } from "./change-webhooks.js";
  * @property {readonly V1TransactionOpResult[]} results One per op, in order.
  */
 
-const queryMembers = new Set(["filter", "sort", "project", "limit", "cursor", "count"]);
+const queryMembers = new Set(["filter", "sort", "project", "limit", "cursor", "count", "aggregate"]);
+const summaries = /** @type {const} */ (["sum", "avg", "min", "max"]);
 
 /**
  * @param {string} path
@@ -183,16 +211,53 @@ function normalizePatch(patch) {
 }
 
 /**
- * @param {V1NearSortKey} key
+ * @param {V1Aggregate} aggregate
+ * @param {V1Query} query
+ * @returns {Record<string, unknown>}
+ */
+function encodeAggregate(aggregate, query) {
+  if (typeof aggregate !== "object" || aggregate === null || Array.isArray(aggregate)) throw new TypeError("aggregate is an object.");
+  if (query.sort !== undefined || query.project !== undefined || query.cursor != null || query.count !== undefined)
+    throw new TypeError("aggregate takes no sort, project, cursor or count.");
+  for (const member of Object.keys(aggregate))
+    if (member !== "groupBy" && !summaries.includes(/** @type {any} */ (member))) throw new TypeError(`Unknown aggregate member ${member}.`);
+  /** @type {Record<string, unknown>} */
+  const body = {};
+  if (aggregate.groupBy !== undefined) {
+    if (!Array.isArray(aggregate.groupBy) || aggregate.groupBy.length > 4) throw new TypeError("groupBy has at most 4 paths.");
+    body.group_by = aggregate.groupBy.map(requirePath);
+  }
+  let total = 0;
+  for (const op of summaries) {
+    const paths = aggregate[op];
+    if (paths === undefined) continue;
+    if (!Array.isArray(paths) || new Set(paths).size !== paths.length) throw new TypeError(`${op} takes distinct JSON Pointers.`);
+    total += paths.length;
+    body[op] = paths.map(pointer);
+  }
+  if (total > 16) throw new TypeError("An aggregate has at most 16 sum, avg, min and max paths.");
+  return body;
+}
+
+/**
+ * @param {V1NearSortKey | V1GeoNearSortKey} key
  * @param {V1Query} query
  * @returns {Record<string, unknown>}
  */
 function nearSort(key, query) {
   if (Object.keys(key).length !== 1 || query.sort?.length !== 1) throw new TypeError("near is the only sort key and has no path or order beside it.");
+  if (searchCount(query.filter) !== 0) throw new TypeError("near cannot combine with search.");
   if (query.cursor != null) throw new TypeError("A near query has one page and takes no cursor.");
   if (query.limit !== undefined && query.limit > 100) throw new TypeError("A near query limit is at most 100.");
   const near = key.near;
   if (near === null || typeof near !== "object") throw new TypeError("near is an object.");
+  if ("lat" in near || "lon" in near) {
+    const geo = /** @type {V1GeoNearSortKey["near"]} */ (near);
+    for (const member of Object.keys(geo)) if (!["path", "lat", "lon"].includes(member)) throw new TypeError(`A geo near takes path, lat and lon, not ${member}.`);
+    requireGeoPoint(geo.lat, geo.lon);
+    if (requirePath(geo.path) === "$id") throw new TypeError("A geo near path is a JSON Pointer.");
+    return { near: { path: geo.path, lat: geo.lat, lon: geo.lon } };
+  }
   for (const member of Object.keys(near)) if (!["path", "vector", "metric"].includes(member)) throw new TypeError(`Unknown near member ${member}.`);
   if (near.metric !== undefined && near.metric !== "cosine" && near.metric !== "l2") throw new TypeError('near metric is "cosine" or "l2".');
   const vector = near.vector;
@@ -220,6 +285,10 @@ function encodeQuery(query) {
       if ("near" in key) return nearSort(key, query);
       for (const member of Object.keys(key)) if (member !== "path" && member !== "order") throw new TypeError(`Unknown sort member ${member}.`);
       if (key.order !== undefined && key.order !== "asc" && key.order !== "desc") throw new TypeError('Sort order is "asc" or "desc".');
+      if (key.path === "$score") {
+        if (key.order !== "desc" || query.sort?.length !== 1 || searchCount(query.filter) !== 1) throw new TypeError("$score requires descending order as the only sort key and exactly one search predicate.");
+        return { path: "$score", order: "desc" };
+      }
       return { path: requirePath(key.path), ...(key.order === undefined ? {} : { order: key.order }) };
     });
   }
@@ -239,9 +308,29 @@ function encodeQuery(query) {
     if (typeof query.count !== "boolean") throw new TypeError("count is a boolean.");
     body.count = query.count;
   }
+  if (query.aggregate !== undefined) body.aggregate = encodeAggregate(query.aggregate, query);
   return stringifyExactJson(body, "query");
 }
 
+/**
+ * @param {JsonValue} value
+ * @returns {V1Group}
+ */
+function decodeGroup(value) {
+  const raw = object(value, "aggregate group");
+  /** @type {Record<string, unknown>} */
+  const group = { key: Object.freeze([...array(raw.key, "group key")]), count: u64(raw.count, "group count") };
+  for (const op of summaries) {
+    if (raw[op] === undefined) continue;
+    group[op] = Object.freeze(Object.fromEntries(Object.entries(object(raw[op], `group ${op}`)).map(([path, summary]) => {
+      const number = summary instanceof ExactDecimal ? summary.toNumber() : summary;
+      if (number !== null && (typeof number !== "number" || !Number.isFinite(number))) malformed(`group ${op}`);
+      return [path, number];
+    })));
+  }
+  return /** @type {V1Group} */ (Object.freeze(group));
+}
+
 /**
  * @param {JsonValue | undefined} value
  * @returns {V1QueryPage}
@@ -258,14 +347,19 @@ export function decodeQueryPage(value) {
   }
   return Object.freeze({
     items: Object.freeze(array(raw.items, "query items").map(item => {
-      const distance = object(item, "document").distance;
-      if (distance === undefined) return decodeDocument(item);
-      const value = distance instanceof ExactDecimal ? distance.toNumber() : distance;
-      if (typeof value !== "number" || !Number.isFinite(value)) malformed("near distance");
-      return Object.freeze({ ...decodeDocument(item), distance: value });
+      const raw = object(item, "document");
+      const document = { ...decodeDocument(item) };
+      for (const field of /** @type {const} */ (["distance", "score"])) {
+        if (raw[field] === undefined) continue;
+        const value = raw[field] instanceof ExactDecimal ? raw[field].toNumber() : raw[field];
+        if (typeof value !== "number" || !Number.isFinite(value)) malformed(field);
+        document[field] = value;
+      }
+      return Object.freeze(document);
     })),
     nextCursor: typeof next === "string" && next !== "" ? next : null,
     count,
+    groups: raw.groups === undefined ? undefined : Object.freeze(array(raw.groups, "aggregate groups").map(decodeGroup)),
   });
 }