@terrascale/sdk 0.0.3 → 0.0.4

package/src/v1/shape-subscription.js

@@ -0,0 +1,208 @@
+// Client state for one collection shape: bootstrap, snapshot pages, log chunks, then the live tail.
+import { TerraBaseV1Error } from "./errors.js";
+import { requireFilter } from "./filter.js";
+import { parseExactJson, stringifyExactJson } from "./json.js";
+import { readShapePage } from "./shape-reader.js";
+/**
+ * @import { JsonObject } from "./json.js"
+ * @import { V1Filter } from "./filter.js"
+ * @import { V1Transport } from "./transport.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.
+ */
+/** @typedef {{ readonly version: string; readonly document: JsonObject }} V1ShapeDocument */
+const retryBaseMilliseconds = 250;
+const retryCapMilliseconds = 30_000;
+// The eighth attempt reaches the delay ceiling; retries continue until success or cancellation.
+const maximumBackoffAttempt = 8;
+/** @param {import("./errors.js").TerraBaseV1Error} error @returns {boolean} */
+function isRetryable(error) {
+  return (error.status === 429 && error.code === "shape_busy") ||
+    (error.status === 503 && (error.code === "unavailable" || error.code === "shape_too_large"));
+}
+/** @param {number} attempt @param {number | undefined} retryAfter @returns {number} */
+function retryDelay(attempt, retryAfter) {
+  return Math.max(Math.min(retryCapMilliseconds, retryBaseMilliseconds * 2 ** (attempt - 1)), (retryAfter ?? 0) * 1000);
+}
+/** @param {unknown} value @param {readonly string[]} allowed @param {string} what */
+function requireMembers(value, allowed, what) {
+  if (typeof value !== "object" || value === null) throw new TypeError(`${what} is an object.`);
+  for (const key of Object.keys(value)) if (!allowed.includes(key)) throw new TypeError(`Unknown ${what} member ${key}.`);
+}
+/** @template T @param {T} value @returns {T} */
+function deepFreeze(value) {
+  if (typeof value === "object" && value !== null && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const item of Object.values(value)) deepFreeze(item);
+  }
+  return value;
+}
+// setTimeout overflows above 2^31-1 ms and fires at once, so a long Retry-After is waited in chunks.
+const maximumTimerMilliseconds = 2 ** 31 - 1;
+/** @param {number} milliseconds @param {AbortSignal} signal @returns {Promise<void>} */
+function sleep(milliseconds, signal) {
+  return new Promise((resolve, reject) => {
+    signal.throwIfAborted();
+    let remaining = milliseconds;
+    /** @type {ReturnType<typeof setTimeout> | undefined} */
+    let timer;
+    const onAbort = () => { clearTimeout(timer); reject(signal.reason); };
+    const wait = () => {
+      const chunk = Math.min(remaining, maximumTimerMilliseconds);
+      timer = setTimeout(() => {
+        remaining -= chunk;
+        if (remaining > 0) wait();
+        else { signal.removeEventListener("abort", onAbort); resolve(); }
+      }, chunk);
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    wait();
+  });
+}
+export class V1ShapeSubscription {
+  /** @type {Map<string, V1ShapeDocument>} */
+  #documents = new Map();
+  /** @type {string | undefined} */
+  #handle;
+  #offset = "-1";
+  /** @type {string | undefined} */
+  #cursor;
+  /** @type {string | undefined} Usable only from a snapshot-complete or log position. */
+  #resume;
+  #upToDate = false;
+  // Set after a changed-handle 409 while the saved resume is still usable; cleared by any commit or reset.
+  #resumeAttempt = false;
+  #controller = new AbortController();
+  #transport;
+  #params;
+  /** @type {V1Filter | undefined} */
+  #where;
+  #onUpdate;
+  #external;
+  #onExternalAbort = () => this.close();
+  #done;
+  /**
+   * @param {V1Transport} transport
+   * @param {Readonly<Record<string, string>>} params
+   * @param {{ where?: V1Filter | undefined }} [shape]
+   * @param {V1ShapeSubscribeOptions} [options]
+   */
+  constructor(transport, params, shape = {}, options = {}) {
+    requireMembers(shape, ["where"], "shape");
+    requireMembers(options, ["signal", "onUpdate"], "shape subscribe option");
+    const { where } = shape;
+    const { signal, onUpdate } = options;
+    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;
+    this.#params = Object.freeze({ ...params });
+    // 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.#external = signal;
+    if (signal?.aborted === true) this.close();
+    else signal?.addEventListener("abort", this.#onExternalAbort);
+    this.#done = this.#run();
+    // Callback-only consumers must not trigger a process-level unhandled rejection.
+    void this.#done.catch(() => {});
+  }
+  /** A copy per read: callers cannot change the documents this subscription holds. */
+  get state() { return new Map(this.#documents); }
+  get upToDate() { return this.#upToDate; }
+  /** Settles when the run ends: resolves on close, rejects on a terminal failure. */
+  get done() { return this.#done; }
+  close() { this.#controller.abort(); }
+  /** @returns {Promise<void>} */
+  async #run() {
+    const signal = this.#controller.signal;
+    let retries = 0;
+    try {
+      for (;;) {
+        signal.throwIfAborted();
+        const request = this.#request();
+        let page;
+        try {
+          page = await readShapePage(this.#transport, this.#params, request, signal);
+        } catch (error) {
+          if (!(error instanceof TerraBaseV1Error)) throw error;
+          if (isRetryable(error)) {
+            retries = Math.min(retries + 1, maximumBackoffAttempt);
+            await sleep(retryDelay(retries, error.retryAfter), signal);
+            continue;
+          }
+          if (error.status !== 409 || error.code !== "must_refetch") throw error;
+          this.#recover(request, error);
+          continue;
+        }
+        retries = 0;
+        this.#commit(page);
+        this.#onUpdate?.(this);
+      }
+    } catch (error) {
+      if (signal.aborted) return;
+      throw error;
+    } finally {
+      // A finished run must not keep the caller's signal (and this subscription) alive.
+      this.#external?.removeEventListener("abort", this.#onExternalAbort);
+    }
+  }
+  /** @returns {import("./shapes.js").V1ShapeRequest} */
+  #request() {
+    if (this.#resumeAttempt) return { where: this.#where, offset: "-1", cursor: this.#resume };
+    if (this.#handle === undefined) return { where: this.#where, offset: "-1" };
+    // Only a fresh head is a live tail; snapshot positions are never live.
+    if (this.#upToDate && !this.#offset.startsWith("snap.")) return { where: this.#where, offset: this.#offset, handle: this.#handle, live: true, cursor: this.#cursor };
+    return { where: this.#where, offset: this.#offset, handle: this.#handle };
+  }
+  /**
+   * @param {import("./shapes.js").V1ShapeRequest} request
+   * @param {TerraBaseV1Error} error
+   */
+  #recover(request, error) {
+    if (this.#resumeAttempt) return this.#reset();
+    if (request.handle === undefined) throw error;
+    // §7.6 reads the lineage from the response header. A body that names another handle is ambiguous: fail closed.
+    const handle = error.headers.get("tb-shape-handle");
+    const changed = handle !== null && handle !== this.#handle && (error.handle === undefined || error.handle === handle);
+    if (changed && this.#resume !== undefined) {
+      // One attempt on the new lineage; its own 409 falls through to #reset above.
+      this.#resumeAttempt = true;
+      if (this.#upToDate) {
+        this.#upToDate = false;
+        this.#onUpdate?.(this);
+      }
+      return;
+    }
+    this.#reset();
+  }
+  #reset() {
+    this.#documents = new Map();
+    this.#handle = undefined;
+    this.#offset = "-1";
+    this.#cursor = undefined;
+    this.#resume = undefined;
+    this.#upToDate = false;
+    this.#resumeAttempt = false;
+    this.#onUpdate?.(this);
+  }
+  /** @param {import("./shapes.js").V1ShapePage} page */
+  #commit(page) {
+    // Repeats are applied, never skipped: a repeated event can carry a newer materialized value.
+    const documents = new Map(this.#documents);
+    for (const change of page.changes)
+      for (const op of change.ops) {
+        if (op.op === "delete") documents.delete(op.id);
+        else documents.set(op.id, deepFreeze({ version: op.version, document: op.document }));
+      }
+    this.#documents = documents;
+    this.#handle = page.handle;
+    this.#offset = page.nextOffset;
+    this.#cursor = page.cursor;
+    this.#resume = page.nextOffset.startsWith("snap.") ? undefined : page.cursorResume;
+    this.#upToDate = page.upToDate;
+    this.#resumeAttempt = false;
+  }
+}

package/src/v1/shapes.js

@@ -16,7 +16,7 @@ import { stringifyExactJson } from "./json.js";
  * @property {boolean | undefined} [live] True only for log positions; waits up to 20 seconds.
  * @property {string | undefined} [cursor] Previous live response's TB-Shape-Cursor.
  */
-/** @typedef {{ readonly op: "upsert"; readonly id: import("../ids.js").EntityId; readonly version: string; readonly document: JsonObject } | { readonly op: "delete"; readonly id: import("../ids.js").EntityId }} V1ShapeOp */
+/** @typedef {{ readonly op: "upsert"; readonly id: string; readonly version: string; readonly document: JsonObject } | { readonly op: "delete"; readonly id: string }} V1ShapeOp */
 /** @typedef {{ readonly offset: string; readonly ops: readonly V1ShapeOp[] }} V1ShapeChange */
 /**
  * One snapshot page or log chunk. Only a fresh open tail/live response can report upToDate.
@@ -29,6 +29,9 @@ import { stringifyExactJson } from "./json.js";
  * @property {readonly V1ShapeChange[]} changes Apply commits and operations in their received order.
  * @property {string | undefined} cursor Echo this as cursor on the next live request.
  * @property {string | undefined} etag
+ * @property {string | undefined} [coveredOffset] Free-read protocol coverage (feed sequence, not write offset).
+ * @property {string | undefined} [valuesAt] Free-read materialization position.
+ * @property {string | undefined} [cursorResume] Opaque free-read resume token.
  */
 const maximumOffset = (1n << 63n) - 1n;
 const handlePattern = /^h1-[0-9a-f]{16}$/u;
@@ -59,7 +62,7 @@ export function requireShapeOffset(value) {
   throw new TypeError("A shape offset is -1, a signed-64-bit decimal log position, or snap.<head>.<canonical-base64url-id>.");
 }
 /** @param {unknown} value @returns {string} */
-function requireHandle(value) {
+export function requireShapeHandle(value) {
   if (typeof value !== "string" || !handlePattern.test(value)) throw new TypeError("A shape handle is h1- followed by 16 lowercase hex characters.");
   return value;
 }
@@ -72,7 +75,7 @@ export function encodeShapeRequest(request) {
   if (request.where !== undefined) query.set("where", stringifyExactJson(requireFilter(request.where), "shape filter"));
   const offset = requireShapeOffset(request.offset ?? "-1");
   query.set("offset", offset);
-  if (request.handle !== undefined) query.set("handle", requireHandle(request.handle));
+  if (request.handle !== undefined) query.set("handle", requireShapeHandle(request.handle));
   else if (offset !== "-1") throw new TypeError("A shape handle is required after bootstrap.");
   if (request.live !== undefined && typeof request.live !== "boolean") throw new TypeError("live is a boolean.");
   if (request.live === true) {
@@ -94,10 +97,13 @@ export function decodeShapePage(value, headers) {
   const cursor = headers.get("tb-shape-cursor") ?? undefined;
   if (cursor !== undefined && !isLogOffset(cursor)) malformed("shape cursor");
   return Object.freeze({
-    shapeId, handle: requireHandle(raw.handle),
+    shapeId, handle: requireShapeHandle(raw.handle),
     offset: requireShapeOffset(raw.offset), nextOffset: requireShapeOffset(raw.next_offset),
     upToDate: boolean(raw.up_to_date, "shape up_to_date"), cursor,
     etag: headers.get("etag") ?? undefined,
+    ...(raw.covered_offset === undefined ? {} : { coveredOffset: requireShapeOffset(raw.covered_offset) }),
+    ...(raw.values_at === undefined ? {} : { valuesAt: requireShapeOffset(raw.values_at) }),
+    ...(raw.cursor_resume === undefined ? {} : { cursorResume: string(raw.cursor_resume, "shape resume cursor") }),
     changes: Object.freeze(array(raw.changes, "shape changes").map(value => {
       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 => {
@@ -130,7 +136,7 @@ export async function readShape(transport, params, request, signal) {
     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");
-    const handle = requireHandle(target.searchParams.get("handle"));
+    const handle = requireShapeHandle(target.searchParams.get("handle"));
     const offset = requireShapeOffset(target.searchParams.get("offset"));
     if (!offset.startsWith("snap.")) malformed("shape bootstrap offset");
     query.set("handle", handle);

package/src/v1/sql.js

@@ -0,0 +1,98 @@
+import { array, boolean, malformed, object, string } from "./decode.js";
+import { requireDocumentId, requireName } from "./ids.js";
+/**
+ * @import { JsonObject, JsonValue } from "./json.js"
+ * @import { V1RequestOptions } from "./terrabase-v1.js"
+ * @import { V1Transport } from "./transport.js"
+ */
+
+/** @typedef {{ readonly id: string; readonly value: JsonObject }} V1SqlRow */
+/**
+ * SQL returns one bounded result, without a pagination cursor.
+ * @typedef {{ readonly matched: number; readonly truncated: boolean; readonly rows: readonly V1SqlRow[] }} V1SqlResult
+ */
+/** @typedef {{ readonly field: string; readonly reason: string }} V1SqlIndexSuggestion */
+/**
+ * @typedef {{
+ *   readonly ok: boolean;
+ *   readonly error: string | null;
+ *   readonly collection: string | null;
+ *   readonly hasLimit: boolean;
+ *   readonly plan: readonly string[];
+ *   readonly indexes: readonly string[];
+ *   readonly suggestions: readonly V1SqlIndexSuggestion[];
+ * }} V1SqlCheck
+ */
+
+/** @param {string} sql @param {V1RequestOptions} options @returns {string} */
+function requestBody(sql, options) {
+  if (typeof sql !== "string" || sql.length > 16_384)
+    throw new TypeError("SQL must be a string of at most 16384 UTF-16 code units.");
+  if (options === null || typeof options !== "object" || Array.isArray(options))
+    throw new TypeError("SQL request options must be an object.");
+  for (const member of Object.keys(options))
+    if (member !== "signal") throw new TypeError(`Unknown SQL request option ${member}.`);
+  // SQL syntax, including empty statements, stays producer-owned: check returns ok:false.
+  return JSON.stringify({ sql });
+}
+
+/** @param {JsonValue | undefined} value @returns {V1SqlResult} */
+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") });
+  });
+  const matched = raw.matched;
+  if (typeof matched !== "number" || !Number.isInteger(matched) || matched < 0 || matched > 1000 || matched !== rows.length)
+    malformed("SQL matched count");
+  if (new Set(rows.map(row => row.id)).size !== rows.length) malformed("SQL row identities");
+  return Object.freeze({ matched, truncated: boolean(raw.truncated, "SQL truncation flag"), rows: Object.freeze(rows) });
+}
+
+/** @param {JsonValue | undefined} value @param {"checkSql" | "explainSql"} operation @returns {V1SqlCheck} */
+function decodeCheck(value, operation) {
+  const raw = object(value, "SQL check");
+  const ok = boolean(raw.ok, "SQL check flag");
+  const error = raw.error === null ? null : string(raw.error, "SQL check error");
+  const collection = raw.collection === null ? null : requireName("collection", raw.collection);
+  const hasLimit = boolean(raw.hasLimit, "SQL limit flag");
+  const plan = array(raw.plan, "SQL plan").map(step => string(step, "SQL plan step"));
+  const indexes = array(raw.indexes, "SQL indexes").map(index => string(index, "SQL index"));
+  const suggestions = array(raw.suggestions, "SQL index suggestions").map(entry => {
+    const suggestion = object(entry, "SQL index suggestion");
+    return Object.freeze({ field: string(suggestion.field, "SQL index field"), reason: string(suggestion.reason, "SQL index reason") });
+  });
+  if (ok ? error !== null || collection === null : error === null || error === "" || collection !== null || hasLimit || plan.length > 0 || indexes.length > 0 || suggestions.length > 0)
+    malformed("SQL check outcome");
+  if (operation === "explainSql" && !ok) malformed("SQL explain outcome");
+  return Object.freeze({ ok, error, collection, hasLimit, plan: Object.freeze(plan), indexes: Object.freeze(indexes), suggestions: Object.freeze(suggestions) });
+}
+
+/**
+ * Runs the producer's read-only SQL subset; it never converts a legacy SQL builder.
+ * @param {V1Transport} transport
+ * @param {string} database
+ * @param {string} sql
+ * @param {V1RequestOptions} [options]
+ * @returns {Promise<V1SqlResult>}
+ */
+export async function runSql(transport, database, sql, options = {}) {
+  const body = requestBody(sql, options);
+  return decodeResult((await transport.call("runSql", { database: requireName("database", database) }, { body, signal: options.signal })).value);
+}
+
+/**
+ * Check reports invalid SQL in a successful body; explain reports a producer HTTP error.
+ * @param {V1Transport} transport
+ * @param {string} database
+ * @param {string} sql
+ * @param {V1RequestOptions} [options]
+ * @param {"checkSql" | "explainSql"} [operation]
+ * @returns {Promise<V1SqlCheck>}
+ */
+export async function checkSql(transport, database, sql, options = {}, operation = "checkSql") {
+  if (operation !== "checkSql" && operation !== "explainSql") throw new TypeError("SQL checks use checkSql or explainSql.");
+  const body = requestBody(sql, options);
+  return decodeCheck((await transport.call(operation, { database: requireName("database", database) }, { body, signal: options.signal })).value, operation);
+}

package/src/v1/system.js

@@ -0,0 +1,80 @@
+import { decodeDocument } from "./decode.js";
+import { requireId } from "../ids.js";
+import { requireDocumentId, requireName } from "./ids.js";
+import { flag, list, nullable, numeric, record, text } from "./management-decode.js";
+import { members } from "./management-validation.js";
+import { decodeCollection, decodeQueryPage } from "./terrabase-v1.js";
+import { V1Transport } from "./transport.js";
+/** @import { V1RequestOptions } from "./terrabase-v1.js" */
+const status = record({ status: text, version: text, region: text, storageFormat: text, revision: nullable(text), machine: text });
+const replication = record({ region: text, status: text, maxLagSeconds: nullable(numeric),
+  peers: list(record({ region: text, status: text, lagSeconds: nullable(numeric) })) });
+const databases = record({ items: list(record({ name: text, id: requireId, homeRegion: text, replicaRegions: list(text), allRegions: flag })) });
+/** @typedef {ReturnType<typeof status> & {readonly httpStatus: number}} V1ProbeStatus */
+/** @typedef {ReturnType<typeof replication>} V1ReplicationHealth */
+/** @typedef {ReturnType<typeof databases>} V1PlatformDatabases */
+/** @typedef {{ readonly baseUrl: string; readonly token?: string; readonly fetch?: import("../config.js").FetchLike; readonly maxResponseBytes?: number }} TerraBaseSystemClientConfig */
+
+/** Public anonymous probes; 503 readiness/backup bodies remain typed probe outcomes. */
+export class V1Health {
+  /** @type {V1Transport} */
+  #transport;
+  /** @param {V1Transport} transport */
+  constructor(transport) { this.#transport = transport; Object.freeze(this); }
+  /** @param {V1RequestOptions} [options] @returns {Promise<V1ProbeStatus>} */
+  async liveness(options = {}) {
+    const response = await this.#transport.call("healthz", {}, { signal: options.signal });
+    return Object.freeze({ ...status(response.value), httpStatus: response.status });
+  }
+  /** @param {V1RequestOptions} [options] @returns {Promise<V1ProbeStatus>} */
+  async readiness(options = {}) {
+    const response = await this.#transport.call("readyz", {}, { signal: options.signal });
+    return Object.freeze({ ...status(response.value), httpStatus: response.status });
+  }
+  /** @param {V1RequestOptions} [options] @returns {Promise<V1ProbeStatus>} */
+  async backup(options = {}) {
+    const response = await this.#transport.call("backupz", {}, { signal: options.signal });
+    return Object.freeze({ ...status(response.value), httpStatus: response.status });
+  }
+  /** @param {V1RequestOptions} [options] @returns {Promise<V1ReplicationHealth>} */
+  async replication(options = {}) { return replication((await this.#transport.call("replicationHealth", {}, { signal: options.signal })).value); }
+}
+/** The public read-only explore API requires a user JWT carrying platform_role=admin. */
+export class V1Platform {
+  /** @type {V1Transport} */
+  #transport;
+  /** @param {V1Transport} transport */
+  constructor(transport) { this.#transport = transport; Object.freeze(this); }
+  /** @param {V1RequestOptions} [options] @returns {Promise<V1PlatformDatabases>} */
+  async databases(options = {}) { return databases((await this.#transport.call("listPlatformDatabases", {}, { signal: options.signal })).value); }
+  /** @param {"ts-auth" | "ts-dashboard"} database @param {V1RequestOptions} [options] */
+  async collections(database, options = {}) {
+    const response = await this.#transport.call("listPlatformCollections", { database: requireName("database", database) }, { signal: options.signal });
+    return record({ items: list(decodeCollection), next_cursor: nullable(text) })(response.value);
+  }
+  /** @param {"ts-auth" | "ts-dashboard"} database @param {string} collection @param {{ readonly limit?: number; readonly cursor?: string }} [request] @param {V1RequestOptions} [options] */
+  async documents(database, collection, request = {}, options = {}) {
+    members(request, ["limit", "cursor"]);
+    const query = new URLSearchParams();
+    if (request.limit !== undefined) {
+      if (!Number.isInteger(request.limit) || request.limit < 1 || request.limit > 1000) throw new TypeError("limit must be 1-1000.");
+      query.set("limit", String(request.limit));
+    }
+    if (request.cursor !== undefined) {
+      if (typeof request.cursor !== "string" || request.cursor === "") throw new TypeError("cursor must be non-empty.");
+      query.set("cursor", request.cursor);
+    }
+    return decodeQueryPage((await this.#transport.call("listPlatformDocuments", { database: requireName("database", database), collection: requireName("collection", collection) }, { query, signal: options.signal })).value);
+  }
+  /** @param {"ts-auth" | "ts-dashboard"} database @param {string} collection @param {string} id @param {V1RequestOptions} [options] */
+  async document(database, collection, id, options = {}) {
+    return decodeDocument((await this.#transport.call("getPlatformDocument", { database: requireName("database", database), collection: requireName("collection", collection) }, {
+      query: new URLSearchParams({ id: requireDocumentId(id) }), signal: options.signal,
+    })).value);
+  }
+}
+/** @param {TerraBaseSystemClientConfig} config */
+export function createTerraBaseSystemClient(config) {
+  const transport = new V1Transport(config);
+  return Object.freeze({ health: new V1Health(transport), platform: new V1Platform(transport) });
+}