@terrascale/sdk 0.0.2 → 0.0.4

package/src/v1/catalog.js

@@ -0,0 +1,210 @@
+import { requireId } from "../ids.js";
+import { array, malformed, object, string } from "./decode.js";
+import { requireName } from "./ids.js";
+import { isJsonObject, stringifyExactJson } from "./json.js";
+/**
+ * @import { JsonInputObject, JsonObject, JsonValue } from "./json.js"
+ * @import { V1Transport } from "./transport.js"
+ * @import { V1RequestOptions } from "./terrabase-v1.js"
+ */
+
+/**
+ * @typedef {object} V1ManagedDatabase
+ * @property {string} id Canonical database ULID.
+ * @property {string} projectId Canonical owning-project ULID.
+ * @property {string} name Database name used in data routes.
+ * @property {string | null} branchedFrom Source database ULID, or null.
+ * @property {string} createdAt ISO date-time returned by the producer.
+ * @property {string} region Serving region.
+ * @property {string} homeRegion Management region.
+ * @property {readonly string[]} replicaRegions Other serving regions; empty when allRegions is true.
+ * @property {boolean} allRegions True when a full copy is served in every serving region, including later ones.
+ */
+/** @typedef {{ readonly name: string; readonly homeRegion?: string | null | undefined; readonly replicaRegions?: readonly string[] | null | undefined; readonly allRegions?: boolean | undefined }} V1DatabaseCreateRequest */
+/** @typedef {{ readonly replicaRegions?: readonly string[] | undefined; readonly allRegions?: true | undefined; readonly homeRegion?: string | null | undefined }} V1DatabaseUpdateRequest */
+/** @typedef {{ readonly name: string }} V1DatabaseBranchRequest */
+/** @typedef {{ readonly after?: string | undefined; readonly limit?: number | undefined }} V1DatabaseListRequest */
+/** @typedef {{ readonly items: readonly V1ManagedDatabase[]; readonly next: string | null }} V1DatabasePage */
+/** @typedef {{ readonly schema: JsonObject | boolean | null; readonly dialect?: string | null | undefined }} V1CollectionSchema */
+
+/** @param {unknown} value @param {readonly string[]} allowed @returns {void} */
+function members(value, allowed) {
+  if (typeof value !== "object" || value === null || Array.isArray(value) ||
+      ![Object.prototype, null].includes(Object.getPrototypeOf(value)))
+    throw new TypeError("A catalog request must be a plain object.");
+  for (const key of Object.keys(value))
+    if (!allowed.includes(key)) throw new TypeError(`Unknown catalog request member ${key}.`);
+}
+
+/** @param {object} options @returns {void} */
+function mutationOptions(options) {
+  if ("idempotencyKey" in options)
+    throw new TypeError("The current producer does not support Idempotency-Key; mutations are never automatically retried.");
+}
+
+/** @param {unknown} value @returns {string} */
+function region(value) {
+  if (typeof value !== "string" || !/^[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?$/u.test(value))
+    throw new TypeError("A region is 1-63 lowercase letters, digits or hyphens, starts with a letter and cannot end with a hyphen.");
+  return value;
+}
+
+/** @param {unknown} value @param {string | null | undefined} home @returns {readonly string[]} */
+function replicas(value, home) {
+  if (!Array.isArray(value) || value.length > 8) throw new TypeError("replicaRegions is an array of at most 8 regions.");
+  const result = value.map(region);
+  if (new Set(result).size !== result.length) throw new TypeError("replicaRegions must not repeat a region.");
+  if (home !== undefined && home !== null && result.includes(home))
+    throw new TypeError("replicaRegions must not include homeRegion.");
+  return result;
+}
+
+/** @param {JsonValue | undefined} value @returns {V1ManagedDatabase} */
+function database(value) {
+  const raw = object(value, "managed database");
+  const createdAt = string(raw.createdAt, "database createdAt");
+  if (!/^\d{4}-\d{2}-\d{2}T/u.test(createdAt) || !Number.isFinite(Date.parse(createdAt))) malformed("database createdAt");
+  if (typeof raw.allRegions !== "boolean") malformed("database allRegions");
+  return Object.freeze({
+    id: requireId(raw.id, "Database ID"), projectId: requireId(raw.projectId, "Project ID"),
+    name: requireName("database", raw.name),
+    branchedFrom: raw.branchedFrom === null ? null : requireId(raw.branchedFrom, "Source database ID"),
+    createdAt, region: region(raw.region), homeRegion: region(raw.homeRegion),
+    replicaRegions: Object.freeze(array(raw.replicaRegions, "database replicaRegions").map(region)),
+    allRegions: raw.allRegions,
+  });
+}
+
+/** Public database catalog operations, bound to the transport's authorized project. */
+export class V1Databases {
+  /** @type {V1Transport} */
+  #transport;
+  /** @param {V1Transport} transport */
+  constructor(transport) { this.#transport = transport; Object.freeze(this); }
+
+  /** @param {V1DatabaseCreateRequest} request @param {V1RequestOptions} [options] @returns {Promise<V1ManagedDatabase>} */
+  async create(request, options = {}) {
+    members(request, ["name", "homeRegion", "replicaRegions", "allRegions"]);
+    mutationOptions(options);
+    const name = requireName("database", request.name);
+    if (request.homeRegion !== undefined && request.homeRegion !== null) region(request.homeRegion);
+    if (request.replicaRegions !== undefined && request.replicaRegions !== null) replicas(request.replicaRegions, request.homeRegion);
+    if (request.allRegions !== undefined && typeof request.allRegions !== "boolean") throw new TypeError("allRegions must be a boolean.");
+    if (request.allRegions === true && request.replicaRegions !== undefined && request.replicaRegions !== null)
+      throw new TypeError("allRegions cannot be combined with replicaRegions.");
+    const response = await this.#transport.call("createDatabase", { database: name }, {
+      body: stringifyExactJson({ name,
+        ...(request.homeRegion === undefined ? {} : { homeRegion: request.homeRegion }),
+        ...(request.replicaRegions === undefined ? {} : { replicaRegions: request.replicaRegions }),
+        ...(request.allRegions === undefined ? {} : { allRegions: request.allRegions }),
+      }, "database create"), signal: options.signal,
+    });
+    return database(response.value);
+  }
+
+  /** @param {V1DatabaseListRequest} [request] @param {V1RequestOptions} [options] @returns {Promise<V1DatabasePage>} */
+  async list(request = {}, options = {}) {
+    members(request, ["after", "limit"]);
+    const query = new URLSearchParams();
+    if (request.after !== undefined) {
+      if (typeof request.after !== "string") throw new TypeError("Database after must be a string.");
+      query.set("after", request.after);
+    }
+    if (request.limit !== undefined) {
+      if (!Number.isInteger(request.limit) || request.limit < 1 || request.limit > 100) throw new TypeError("Database list limit is 1-100.");
+      query.set("limit", String(request.limit));
+    }
+    const response = await this.#transport.call("listDatabases", {}, { query, signal: options.signal });
+    const raw = object(response.value, "database page");
+    if (raw.next !== null && (typeof raw.next !== "string" || raw.next === "")) malformed("database next");
+    return Object.freeze({ items: Object.freeze(array(raw.items, "databases").map(database)), next: raw.next });
+  }
+
+  /** @param {string} name @param {V1RequestOptions} [options] @returns {Promise<V1ManagedDatabase>} */
+  async get(name, options = {}) {
+    const response = await this.#transport.call("getDatabase", { database: requireName("database", name) }, { signal: options.signal });
+    return database(response.value);
+  }
+
+  /** @param {string} name @param {V1DatabaseUpdateRequest} request @param {V1RequestOptions} [options] @returns {Promise<V1ManagedDatabase>} */
+  async update(name, request, options = {}) {
+    members(request, ["homeRegion", "replicaRegions", "allRegions"]);
+    mutationOptions(options);
+    if (request.homeRegion !== undefined && request.homeRegion !== null) region(request.homeRegion);
+    if (request.allRegions === true) {
+      if (request.replicaRegions !== undefined) throw new TypeError("allRegions cannot be combined with replicaRegions.");
+    } else {
+      if (request.allRegions !== undefined) throw new TypeError("allRegions must be true; send replicaRegions to turn it off.");
+      replicas(request.replicaRegions, request.homeRegion);
+    }
+    const response = await this.#transport.call("updateDatabase", { database: requireName("database", name) }, {
+      body: stringifyExactJson({
+        ...(request.allRegions === true ? { allRegions: true } : { replicaRegions: request.replicaRegions }),
+        ...(request.homeRegion === undefined ? {} : { homeRegion: request.homeRegion }),
+      }, "database update"), signal: options.signal,
+    });
+    return database(response.value);
+  }
+
+  /** @param {string} name @param {V1RequestOptions} [options] @returns {Promise<void>} */
+  async delete(name, options = {}) {
+    mutationOptions(options);
+    await this.#transport.call("deleteDatabase", { database: requireName("database", name) }, { signal: options.signal });
+  }
+
+  /** @param {string} name @param {V1DatabaseBranchRequest} request @param {V1RequestOptions} [options] @returns {Promise<V1ManagedDatabase>} */
+  async branch(name, request, options = {}) {
+    members(request, ["name"]);
+    mutationOptions(options);
+    const response = await this.#transport.call("branchDatabase", { database: requireName("database", name) }, {
+      body: stringifyExactJson({ name: requireName("database", request.name) }, "database branch"), signal: options.signal,
+    });
+    return database(response.value);
+  }
+}
+
+/** @param {JsonValue | undefined} value @returns {V1CollectionSchema} */
+function collectionSchema(value) {
+  const raw = object(value, "collection schema");
+  const schema = raw.schema;
+  if (schema !== null && typeof schema !== "boolean" && !isJsonObject(schema)) malformed("declared schema");
+  const dialect = raw.dialect;
+  if (dialect !== undefined && dialect !== null && typeof dialect !== "string") malformed("schema dialect");
+  return Object.freeze({ schema, ...(dialect === undefined ? {} : { dialect }) });
+}
+
+/** @param {boolean | JsonInputObject} schema @returns {string} */
+function schemaText(schema) {
+  if (typeof schema !== "boolean" && !isJsonObject(schema)) throw new TypeError("A declared schema must be a JSON object or boolean.");
+  const body = stringifyExactJson(schema, "declared schema");
+  if (new TextEncoder().encode(body).byteLength > 64 * 1024) throw new TypeError("A declared schema is at most 64 KiB.");
+  let nodes = 0;
+  /** @param {unknown} value @param {number} depth */
+  const visit = (value, depth) => {
+    if (++nodes > 4093) throw new TypeError("A declared schema holds at most 4093 values.");
+    if (!Array.isArray(value) && !isJsonObject(value)) return;
+    if (depth >= 15) throw new TypeError("A declared schema nests at most 15 levels.");
+    for (const child of Object.values(value)) visit(child, depth + 1);
+  };
+  visit(schema, 0);
+  return body;
+}
+
+/** @param {V1Transport} transport @param {Readonly<Record<string, string>>} params @param {V1RequestOptions} [options] @returns {Promise<V1CollectionSchema>} */
+export async function getCollectionSchema(transport, params, options = {}) {
+  return collectionSchema((await transport.call("getCollectionSchema", params, { signal: options.signal })).value);
+}
+
+/** @param {V1Transport} transport @param {Readonly<Record<string, string>>} params @param {boolean | JsonInputObject} schema @param {V1RequestOptions} [options] @returns {Promise<V1CollectionSchema>} */
+export async function putCollectionSchema(transport, params, schema, options = {}) {
+  mutationOptions(options);
+  return collectionSchema((await transport.call("putCollectionSchema", params, {
+    body: schemaText(schema), signal: options.signal,
+  })).value);
+}
+
+/** @param {V1Transport} transport @param {Readonly<Record<string, string>>} params @param {V1RequestOptions} [options] @returns {Promise<V1CollectionSchema>} */
+export async function deleteCollectionSchema(transport, params, options = {}) {
+  mutationOptions(options);
+  return collectionSchema((await transport.call("deleteCollectionSchema", params, { signal: options.signal })).value);
+}

package/src/v1/changes.js

@@ -0,0 +1,225 @@
+import { documentObject, malformed, object, u64 } from "./decode.js";
+import { parseV1Error } from "./errors.js";
+import { requireDocumentId, requireName } from "./ids.js";
+import { parseExactJson } from "./json.js";
+import { BodyTransportError } from "./transport.js";
+/** @import { JsonObject } from "./json.js" */
+/** @import { V1Transport } from "./transport.js" */
+
+/**
+ * Cursors are opaque and must be resumed with the identical collection filter.
+ * @typedef {object} V1ChangeStreamRequest
+ * @property {string | undefined} [cursor] An issued cursor, or `now`; omitted starts at retention.
+ * @property {readonly string[] | undefined} [collections] One to 64 collection names.
+ * @property {string | undefined} [lastEventId] Overrides cursor, as the producer's Last-Event-ID header.
+ */
+/**
+ * At-least-once delivery: callers deduplicate by origin, version, collection and id.
+ * The document is its current serving value, including null, rather than a historical value.
+ * Only the last change of an origin/version carries a resumable cursor.
+ * @typedef {{ readonly type: "change"; readonly cursor: string | undefined; readonly collection: string; readonly id: string;
+ *   readonly op: "upsert" | "delete"; readonly version: string; readonly origin: string;
+ *   readonly document: JsonObject | null }} V1DatabaseChange
+ */
+/** @typedef {{ readonly type: "cursor"; readonly cursor: string }} V1DatabaseChangeCursor */
+/** @typedef {{ type: string | undefined; id: string | undefined; data: string }} WireEvent */
+
+// A 1 MiB document may require six bytes per character when JSON escapes it.
+const maximumEventBytes = 8 * 1024 * 1024;
+
+/** @param {unknown} value @returns {string} */
+function requireCursor(value) {
+  if (typeof value !== "string" || value === "" || /[\u0000-\u0020\u007f-\u009f\ud800-\udfff]/u.test(value))
+    throw new TypeError("A changes cursor is a non-empty opaque string without whitespace or control characters.");
+  return value;
+}
+
+/** @param {V1ChangeStreamRequest} request */
+function encodeRequest(request) {
+  if (typeof request !== "object" || request === null || Array.isArray(request)) throw new TypeError("A changes request is an object.");
+  for (const key of Object.keys(request))
+    if (!["cursor", "collections", "lastEventId"].includes(key)) throw new TypeError(`Unknown changes member ${key}.`);
+  const query = new URLSearchParams();
+  if (request.cursor !== undefined) query.set("cursor", requireCursor(request.cursor));
+  if (request.collections !== undefined) {
+    if (!Array.isArray(request.collections) || request.collections.length < 1 || request.collections.length > 64)
+      throw new TypeError("A changes filter has one to 64 collections.");
+    query.set("collections", request.collections.map(name => requireName("collection", name)).join(","));
+  }
+  return { query, lastEventId: request.lastEventId === undefined ? undefined : requireCursor(request.lastEventId) };
+}
+
+/**
+ * Parses lines from bytes so split UTF-8 and CRLF never change a checkpoint.
+ * @param {Response} response
+ * @param {AbortSignal | undefined} signal
+ * @returns {AsyncGenerator<WireEvent, void, undefined>}
+ */
+async function* events(response, signal) {
+  const reader = response.body?.getReader();
+  if (reader === undefined) malformed("empty changes stream");
+  const abort = () => { void reader.cancel(signal?.reason).catch(() => undefined); };
+  signal?.addEventListener("abort", abort, { once: true });
+  const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+  /** @type {Uint8Array[]} */
+  let lineParts = [];
+  let lineBytes = 0;
+  let eventBytes = 0;
+  let skipLf = false;
+  let firstLine = true;
+  /** @type {string | undefined} */
+  let type;
+  /** @type {string | undefined} */
+  let id;
+  /** @type {string[]} */
+  let data = [];
+  let hasFields = false;
+  /** @param {Uint8Array} bytes */
+  const append = bytes => {
+    eventBytes += bytes.byteLength;
+    if (eventBytes > maximumEventBytes) malformed("changes event exceeding 8 MiB");
+    if (bytes.byteLength > 0) { lineParts.push(bytes); lineBytes += bytes.byteLength; }
+  };
+  try {
+    while (true) {
+      signal?.throwIfAborted();
+      /** @type {ReadableStreamReadResult<Uint8Array>} */
+      let part;
+      try { part = await reader.read(); }
+      catch (error) { signal?.throwIfAborted(); throw new BodyTransportError(error); }
+      signal?.throwIfAborted();
+      if (part.done) break;
+      let start = 0;
+      for (let index = 0; index < part.value.byteLength; index++) {
+        const byte = part.value[index];
+        if (skipLf) {
+          skipLf = false;
+          if (byte === 10) { start = index + 1; continue; }
+        }
+        if (byte !== 10 && byte !== 13) continue;
+        append(part.value.subarray(start, index));
+        if (++eventBytes > maximumEventBytes) malformed("changes event exceeding 8 MiB");
+        const bytes = new Uint8Array(lineBytes);
+        let at = 0;
+        for (const fragment of lineParts) { bytes.set(fragment, at); at += fragment.byteLength; }
+        let line = decoder.decode(bytes);
+        if (firstLine) { firstLine = false; if (line.startsWith("\ufeff")) line = line.slice(1); }
+        lineParts = [];
+        lineBytes = 0;
+        start = index + 1;
+        skipLf = byte === 13;
+        if (line === "") {
+          const event = hasFields ? { type, id, data: data.join("\n") } : undefined;
+          type = undefined; id = undefined; data = []; hasFields = false; eventBytes = 0;
+          if (event !== undefined) { signal?.throwIfAborted(); yield event; signal?.throwIfAborted(); }
+          continue;
+        }
+        if (line.startsWith(":")) continue;
+        const colon = line.indexOf(":");
+        const field = colon === -1 ? line : line.slice(0, colon);
+        let value = colon === -1 ? "" : line.slice(colon + 1);
+        if (value.startsWith(" ")) value = value.slice(1);
+        if (field === "event") { type = value; hasFields = true; }
+        else if (field === "id") { id = value; hasFields = true; }
+        else if (field === "data") { data.push(value); hasFields = true; }
+      }
+      append(part.value.subarray(start));
+    }
+    if (lineBytes !== 0 || hasFields) malformed("incomplete changes event");
+  } finally {
+    signal?.removeEventListener("abort", abort);
+    await reader.cancel().catch(() => undefined);
+    reader.releaseLock();
+  }
+}
+
+/** @param {WireEvent} event @param {Headers} headers @returns {V1DatabaseChange | V1DatabaseChangeCursor} */
+function decodeEvent(event, headers) {
+  /** @type {import("./json.js").JsonValue} */
+  let value;
+  try { value = parseExactJson(event.data); }
+  catch { malformed("changes event JSON"); }
+  const raw = object(value, "changes event");
+  if (event.type === "error") {
+    const detail = object(raw.error, "changes error");
+    if (typeof detail.code !== "string" || detail.code === "") malformed("changes error code");
+    // Headers have already committed: retain the actual HTTP 200 and the producer's terminal code.
+    throw parseV1Error(200, headers, event.data);
+  }
+  if (event.type === "cursor") {
+    const cursor = requireCursor(event.id);
+    if (raw.cursor !== cursor) malformed("changes cursor position");
+    return Object.freeze({ type: "cursor", cursor });
+  }
+  if (event.type !== "change") malformed("changes event kind");
+  const cursor = event.id === undefined ? undefined : requireCursor(event.id);
+  if (raw.op !== "upsert" && raw.op !== "delete") malformed("changes operation");
+  if (typeof raw.origin !== "string" || !/^[0-9a-f]{16}$/u.test(raw.origin)) malformed("changes origin");
+  return Object.freeze({ type: "change", cursor, collection: requireName("collection", raw.collection),
+    id: requireDocumentId(raw.id), op: raw.op, version: u64(raw.version, "changes version"), origin: raw.origin,
+    document: raw.document === null ? null : documentObject(raw.document),
+  });
+}
+
+/** @param {AbortSignal | undefined} signal @returns {Promise<void>} */
+function reconnectDelay(signal) {
+  signal?.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    const abort = () => { clearTimeout(timer); signal?.removeEventListener("abort", abort); reject(signal?.reason); };
+    const timer = setTimeout(() => { signal?.removeEventListener("abort", abort); resolve(); }, 250);
+    signal?.addEventListener("abort", abort, { once: true });
+  });
+}
+
+/**
+ * Reconnects only a normally completed, valid stream, with the latest issued cursor.
+ * Denials, terminal errors, malformed data and lost connections are returned to the caller.
+ * @param {V1Transport} transport
+ * @param {string} database
+ * @param {V1ChangeStreamRequest} [request]
+ * @param {AbortSignal | undefined} [signal]
+ * @returns {AsyncGenerator<V1DatabaseChange | V1DatabaseChangeCursor, void, undefined>}
+ */
+export function streamChanges(transport, database, request = {}, signal) {
+  const controller = new AbortController();
+  const combined = signal === undefined ? controller.signal : AbortSignal.any([signal, controller.signal]);
+  const iterator = readChanges(transport, database, request, combined);
+  const next = iterator.next.bind(iterator);
+  const finish = iterator.return.bind(iterator);
+  const closed = new DOMException("The changes stream was closed.", "AbortError");
+  iterator.next = async () => {
+    try { return await next(); }
+    catch (error) { if (error === closed) return { done: true, value: undefined }; throw error; }
+  };
+  // Native generator return queues behind a pending read; interrupt its private signal first.
+  iterator.return = value => { controller.abort(closed); return finish(value); };
+  return iterator;
+}
+
+/**
+ * @param {V1Transport} transport
+ * @param {string} database
+ * @param {V1ChangeStreamRequest} request
+ * @param {AbortSignal} signal
+ * @returns {AsyncGenerator<V1DatabaseChange | V1DatabaseChangeCursor, void, undefined>}
+ */
+async function* readChanges(transport, database, request, signal) {
+  const encoded = encodeRequest(request);
+  let lastEventId = encoded.lastEventId;
+  while (true) {
+    signal?.throwIfAborted();
+    const response = await transport.openStream("streamDatabaseChanges", { database }, {
+      query: encoded.query, ...(lastEventId === undefined ? {} : { headers: { "last-event-id": lastEventId } }), signal,
+    });
+    let count = 0;
+    for await (const wire of events(response, signal)) {
+      const event = decodeEvent(wire, response.headers);
+      if (event.cursor !== undefined) lastEventId = event.cursor;
+      count++;
+      yield event;
+      signal?.throwIfAborted();
+    }
+    if (count === 0 || lastEventId === undefined) malformed("empty changes stream");
+    await reconnectDelay(signal);
+  }
+}

package/src/v1/database-schema.js

@@ -0,0 +1,45 @@
+import { requireName } from "./ids.js";
+import { list, numeric, optional, nullable, record, text, dictionary } 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 constraint = record({ name: text, fields: list(text), normalization: text });
+const schema = record({ collection: text, documents: numeric, sampledDocuments: numeric,
+  fields: list(record({ path: text, present: numeric, types: dictionary(numeric) })), uniqueConstraints: optional(nullable(list(constraint))) });
+const collections = record({ items: list(record({ name: text, documents: numeric, bytes: numeric })) });
+const unique = record({ constraints: list(constraint) });
+const shapes = record({ items: list(record({ id: text, collection: text, shape: text, queries: numeric,
+  totalLatencyMs: numeric, maxLatencyMs: numeric, rowsScanned: numeric, lastSeenAt: text })) });
+/** @typedef {ReturnType<typeof schema>} V1InferredSchema */
+/** @typedef {ReturnType<typeof collections>} V1DatabaseSchema */
+/** @typedef {ReturnType<typeof unique>} V1UniqueSchema */
+/** @typedef {ReturnType<typeof shapes>} V1QueryShapes */
+/** @typedef {"none" | "lowercase" | "trim_lowercase"} V1Normalization */
+/** @typedef {{ readonly fields?: readonly { readonly name: string; readonly unique?: boolean; readonly normalization?: V1Normalization | null }[] | null; readonly indexes?: readonly { readonly name: string; readonly fields: readonly string[]; readonly unique?: boolean; readonly normalization?: V1Normalization | null }[] | null }} V1UniqueSchemaRequest */
+
+/** Inferred collection fields, declared uniqueness, and observed query statistics. */
+export class V1DatabaseSchemaClient {
+  /** @type {V1Transport} */
+  #transport;
+  /** @type {{database: string}} */
+  #params;
+  /** @param {V1Transport} transport @param {string} database */
+  constructor(transport, database) { this.#transport = transport; this.#params = { database: requireName("database", database) }; Object.freeze(this); }
+  /** @param {V1RequestOptions} [options] @returns {Promise<V1DatabaseSchema>} */
+  async list(options = {}) { return collections((await this.#transport.call("getDatabaseSchema", this.#params, { signal: options.signal })).value); }
+  /** @param {string} collection @param {V1RequestOptions} [options] @returns {Promise<V1InferredSchema>} */
+  async infer(collection, options = {}) {
+    return schema((await this.#transport.call("inferCollectionSchema", { ...this.#params, collection: requireName("collection", collection) }, { signal: options.signal })).value);
+  }
+  /** @param {string} collection @param {V1UniqueSchemaRequest} request @param {V1RequestOptions} [options] @returns {Promise<V1UniqueSchema>} */
+  async declare(collection, request, options = {}) {
+    members(request, ["fields", "indexes"]);
+    mutationOptions(options);
+    return unique((await this.#transport.call("declareCollectionSchema", { ...this.#params, collection: requireName("collection", collection) }, {
+      body: stringifyExactJson(request, "unique schema"), signal: options.signal,
+    })).value);
+  }
+  /** @param {V1RequestOptions} [options] @returns {Promise<V1QueryShapes>} */
+  async queryShapes(options = {}) { return shapes((await this.#transport.call("listQueryShapes", this.#params, { signal: options.signal })).value); }
+}

package/src/v1/decode.js

@@ -1,5 +1,5 @@
 // Typed decoding of TerraBase v1 response bodies.
-import { parseU64, requireVersion } from "./ids.js";
+import { parseU64, requireDocumentId, requireVersion } from "./ids.js";
 import { isJsonObject } from "./json.js";
 /** @import { JsonObject, JsonValue } from "./json.js" */
 
@@ -8,22 +8,23 @@ import { isJsonObject } from "./json.js";
  * `document` is the value, or the LWW winner when a causal read answers `"conflict"` with `siblings`.
  * Unknown future states pass through.
  * @typedef {object} V1Document
- * @property {string} id
+ * @property {string} id Caller-supplied key or server-generated ULID.
  * @property {string} version
  * @property {"value" | "conflict" | (string & {})} state
  * @property {JsonObject} document
- * @property {readonly JsonValue[]} [siblings] Every live version, on a causal read with several.
+ * @property {readonly JsonValue[]} [siblings] Live versions and tombstones on a causal conflict.
  */
 
 /**
  * The result of a document write.
  * @typedef {object} V1WriteResult
- * @property {string} id
+ * @property {string} id Caller-supplied key or server-generated ULID.
  * @property {string} version For a delete, the tombstone's version.
  * @property {string} offset The database commit offset (decimal u64), usable with shape `waitFor`.
  * @property {V1Durability} durability
  * @property {boolean} created True when a PUT or POST answered 201.
  * @property {string | undefined} location The Location header of a POST create.
+ * @property {JsonObject} [document] Stored document returned by PATCH.
  */
 
 /**
@@ -43,6 +44,11 @@ export function object(value, what) {
   return isJsonObject(value) ? value : malformed(what);
 }
 
+/** @param {JsonValue | undefined} value @returns {JsonObject} */
+export function documentObject(value) {
+  return object(value, "document body");
+}
+
 /**
  * @param {JsonValue | undefined} value
  * @param {string} what
@@ -93,12 +99,17 @@ export function durability(value) {
  */
 export function decodeDocument(value) {
   const raw = object(value, "document");
-  const id = string(raw.id, "document id");
+  const id = requireDocumentId(raw.id);
   const version = requireVersion(raw.version);
   const state = string(raw.state, "document state");
-  const document = object(raw.document, "document body");
+  const document = documentObject(raw.document);
   if (raw.siblings === undefined) return Object.freeze({ id, version, state, document });
-  return Object.freeze({ id, version, state, document, siblings: Object.freeze(array(raw.siblings, "document siblings")) });
+  const siblings = array(raw.siblings, "document siblings");
+  for (const sibling of siblings) {
+    const entry = object(sibling, "document sibling");
+    if (entry.deleted !== true || entry.document !== undefined) documentObject(entry.document);
+  }
+  return Object.freeze({ id, version, state, document, siblings: Object.freeze(siblings) });
 }
 
 /**
@@ -108,11 +119,12 @@ export function decodeDocument(value) {
 export function decodeWrite(response) {
   const raw = object(response.value, "write result");
   return Object.freeze({
-    id: string(raw.id, "write id"),
+    id: requireDocumentId(raw.id),
     version: requireVersion(raw.version),
     offset: u64(raw.offset, "write offset"),
     durability: durability(raw.durability),
     created: response.status === 201,
     location: response.headers.get("location") ?? undefined,
+    ...(raw.document === undefined ? {} : { document: documentObject(raw.document) }),
   });
 }

package/src/v1/errors.js

@@ -1,5 +1,5 @@
 import { isJsonObject, parseExactJson } from "./json.js";
-/** @import { JsonObject } from "./json.js" */
+/** @import { JsonObject, JsonValue } from "./json.js" */
 
 /**
  * @typedef {object} TerraBaseV1ErrorInit
@@ -11,6 +11,9 @@ import { isJsonObject, parseExactJson } from "./json.js";
  * @property {number | undefined} [retryAfter]
  * @property {string | undefined} [etag]
  * @property {JsonObject | undefined} [details]
+ * @property {JsonValue | undefined} [body]
+ * @property {string | undefined} [responseText]
+ * @property {Headers | undefined} [headers]
  */
 
 /**
@@ -32,6 +35,14 @@ export class TerraBaseV1Error extends Error {
   etag;
   /** @type {JsonObject | undefined} The raw error object, for route-specific metadata. */
   details;
+  /** @type {JsonValue | undefined} Complete parsed response body, including unknown fields. */
+  body;
+  /** @type {string} Original response text; empty when absent or unreadable. */
+  responseText;
+  /** @type {Headers} Response headers, including authentication challenges and retry metadata. */
+  headers;
+  /** @type {string | undefined} Diagnostic X-Request-ID, when supplied by the responder. */
+  requestId;
 
   /** @param {TerraBaseV1ErrorInit} init */
   constructor(init) {
@@ -48,6 +59,10 @@ export class TerraBaseV1Error extends Error {
     this.retryAfter = init.retryAfter;
     this.etag = init.etag;
     this.details = init.details;
+    this.body = init.body;
+    this.responseText = init.responseText ?? "";
+    this.headers = new Headers(init.headers);
+    this.requestId = this.headers.get("x-request-id") ?? undefined;
   }
 }
 
@@ -153,11 +168,13 @@ export function parseRetryAfter(headers) {
  * @returns {TerraBaseV1Error}
  */
 export function parseV1Error(status, headers, text) {
+  /** @type {JsonValue | undefined} */
+  let body;
   /** @type {JsonObject | undefined} */
   let details;
   try {
-    const parsed = text === "" ? undefined : parseExactJson(text);
-    if (isJsonObject(parsed) && isJsonObject(parsed.error)) details = parsed.error;
+    body = text === "" ? undefined : parseExactJson(text);
+    if (isJsonObject(body) && isJsonObject(body.error)) details = body.error;
   } catch {
     details = undefined;
   }
@@ -181,5 +198,8 @@ export function parseV1Error(status, headers, text) {
     retryAfter: parseRetryAfter(headers),
     etag: unquoteEtag(headers.get("etag")),
     details,
+    body,
+    responseText: text,
+    headers,
   });
 }