@terrascale/sdk 0.0.3 → 0.0.5

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

@@ -8,22 +8,24 @@ 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 {import("../ids.js").EntityId} 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] Live versions and tombstones on a causal conflict.
+ * @property {number} [distance] Distance to the query vector; present only on `near` query results.
  */
 
 /**
  * The result of a document write.
  * @typedef {object} V1WriteResult
- * @property {import("../ids.js").EntityId} 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.
  */
 
 /**
@@ -45,9 +47,7 @@ export function object(value, what) {
 
 /** @param {JsonValue | undefined} value @returns {JsonObject} */
 export function documentObject(value) {
-  const document = object(value, "document body");
-  if (Object.hasOwn(document, "id")) malformed("document body: the entity ID belongs in the document key");
-  return document;
+  return object(value, "document body");
 }
 
 /**
@@ -126,5 +126,6 @@ export function decodeWrite(response) {
     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,
   });
 }

package/src/v1/export.js

@@ -0,0 +1,68 @@
+import { documentObject, malformed, object } from "./decode.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" */
+
+/** @typedef {{ readonly collection: string; readonly id: string; readonly document: JsonObject }} V1ExportedDocument */
+/**
+ * @typedef {object} V1ExportOptions
+ * @property {{ readonly collection: string; readonly id: string } | undefined} [after] Resume after this document; the resumed part reads a new snapshot.
+ * @property {AbortSignal | undefined} [signal]
+ */
+
+// A 1 MiB document may require six characters per character when JSON escapes it.
+const maximumLineLength = 8 * 1024 * 1024;
+
+/** @param {string} line @returns {V1ExportedDocument} */
+function decodeLine(line) {
+  /** @type {import("./json.js").JsonValue} */
+  let value;
+  try { value = parseExactJson(line); }
+  catch { malformed("export line JSON"); }
+  const raw = object(value, "export line");
+  return Object.freeze({ collection: requireName("collection", raw.collection), id: requireDocumentId(raw.id), document: documentObject(raw.document) });
+}
+
+/**
+ * Streams every live document of a database as NDJSON, in collection then id order, from one read snapshot.
+ * A stream that ends inside a line is incomplete and throws; resume with `after` set to the last document received.
+ * @param {V1Transport} transport
+ * @param {string} database
+ * @param {V1ExportOptions} [options]
+ * @returns {AsyncGenerator<V1ExportedDocument, void, undefined>}
+ */
+export async function* exportDocuments(transport, database, options = {}) {
+  const { after, signal } = options;
+  const query = new URLSearchParams();
+  if (after !== undefined) {
+    if (typeof after !== "object" || after === null) throw new TypeError("export after is { collection, id }.");
+    query.set("after_collection", requireName("collection", after.collection));
+    query.set("after_id", requireDocumentId(after.id));
+  }
+  const response = await transport.openStream("exportDatabase", { database }, { query, signal });
+  const body = /** @type {ReadableStream<Uint8Array>} */ (response.body);
+  const decoder = /** @type {ReadableWritablePair<string, Uint8Array>} */ (new TextDecoderStream("utf-8", { fatal: true, ignoreBOM: true }));
+  const reader = body.pipeThrough(decoder).getReader();
+  let pending = "";
+  try {
+    while (true) {
+      /** @type {ReadableStreamReadResult<string>} */
+      let part;
+      try { part = await reader.read(); }
+      catch (error) { signal?.throwIfAborted(); throw new BodyTransportError(error); }
+      if (part.done) break;
+      // Split only the new text so a long line arriving in many chunks is scanned once.
+      const lines = part.value.split("\n");
+      lines[0] = pending + lines[0];
+      pending = /** @type {string} */ (lines.pop());
+      if (pending.length > maximumLineLength) malformed("export line exceeding 8 MiB");
+      for (const line of lines) yield decodeLine(line);
+    }
+    if (pending !== "") malformed("incomplete export line");
+  } finally {
+    await reader.cancel().catch(() => undefined);
+    reader.releaseLock();
+  }
+}

package/src/v1/ids.js

@@ -27,9 +27,12 @@ export function requireProject(project) {
   return requireId(project);
 }
 
-/** @param {unknown} id @returns {import("../ids.js").EntityId} */
+/** A caller-supplied key is not a generated entity ID. @param {unknown} id @returns {string} */
 export function requireDocumentId(id) {
-  return requireId(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.");
+  return id;
 }
 
 /**

package/src/v1/imports.js

@@ -0,0 +1,72 @@
+import { requireId } from "../ids.js";
+import { requireName } from "./ids.js";
+import { flag, list, nullable, numeric, 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 importOptions = record({ missingPrimaryKey: nullable(text), exclude: nullable(list(text)) });
+const column = record({ name: text, sourceType: text, mapping: text, nullable: flag, excluded: flag });
+const constraint = record({ kind: text, name: nullable(text), columns: list(text), references: nullable(text), enforced: flag });
+const issue = record({ severity: text, code: text, column: nullable(text), row: nullable(numeric), message: text });
+const table = record({ source: text, collection: text, excluded: flag, rows: numeric, idPolicy: text, primaryKey: list(text),
+  columns: list(column), constraints: list(constraint), issues: list(issue) });
+const preview = record({ id: requireId, tables: list(table), skipped: list(record({ kind: text, name: text })), skippedTruncated: flag, blocking: numeric, warnings: numeric });
+const progress = record({ tablesDone: numeric, tablesTotal: numeric, rowsWritten: numeric, rowsTotal: numeric, currentTable: nullable(text) });
+const validation = record({ passed: flag, tables: list(record({ source: text, collection: text, sourceRows: numeric, documents: numeric,
+  sourceChecksum: text, documentChecksum: text, match: flag })) });
+const error = record({ code: text, message: text, retryable: flag, table: nullable(text), row: nullable(numeric), column: nullable(text) });
+const job = record({ id: requireId, project: requireId, database: text, region: text, state: text, cancelRequested: flag, options: importOptions,
+  source: record({ format: text, bytes: numeric, sha256: text, receivedBytes: numeric, staged: flag, retainedUntil: nullable(text) }),
+  preview: nullable(preview), confirmedPreviewId: nullable(requireId), progress: nullable(progress), validation: nullable(validation), error: nullable(error),
+  createdAt: text, updatedAt: text, startedAt: nullable(text), finishedAt: nullable(text) });
+/** @typedef {ReturnType<typeof job>} V1ImportJob */
+/** @typedef {{ readonly missingPrimaryKey?: "reject" | "generate" | null; readonly exclude?: readonly string[] | null }} V1ImportOptions */
+/** @typedef {{ readonly format: "postgres_plain" | "sqlite"; readonly sourceBytes: number; readonly sourceSha256: string; readonly options?: V1ImportOptions | null }} V1CreateImportRequest */
+
+/** One import job belongs to its destination database; preview confirmation is explicit. */
+export class V1Imports {
+  /** @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 {V1CreateImportRequest} request @param {V1RequestOptions} [options] @returns {Promise<V1ImportJob>} */
+  async create(request, options = {}) {
+    members(request, ["format", "sourceBytes", "sourceSha256", "options"]);
+    if (!["postgres_plain", "sqlite"].includes(request.format) || !Number.isSafeInteger(request.sourceBytes) || request.sourceBytes < 1 || request.sourceBytes > 1073741824 ||
+        typeof request.sourceSha256 !== "string" || !/^[a-f0-9]{64}$/u.test(request.sourceSha256)) throw new TypeError("Invalid import format, size or SHA-256.");
+    mutationOptions(options);
+    return job((await this.#transport.call("createImport", this.#params, { body: stringifyExactJson(request, "import create"), signal: options.signal })).value);
+  }
+  /** @param {V1RequestOptions} [options] @returns {Promise<V1ImportJob>} */
+  async get(options = {}) { return job((await this.#transport.call("getImport", this.#params, { signal: options.signal })).value); }
+  /** @param {number | bigint} offset @param {Uint8Array} bytes @param {V1RequestOptions} [options] @returns {Promise<V1ImportJob>} */
+  async uploadSource(offset, bytes, options = {}) {
+    if (!(typeof offset === "bigint" || typeof offset === "number" && Number.isSafeInteger(offset)) || offset < 0 || BigInt(offset) > 9223372036854775807n)
+      throw new TypeError("offset must be a non-negative signed 64-bit integer.");
+    if (!(bytes instanceof Uint8Array) || bytes.byteLength < 1 || bytes.byteLength > 4194304) throw new TypeError("A source part must contain 1-4194304 bytes.");
+    mutationOptions(options);
+    return job((await this.#transport.call("uploadImportSource", this.#params, {
+      body: bytes.slice(), contentType: "application/octet-stream", query: new URLSearchParams({ offset: String(offset) }), signal: options.signal,
+    })).value);
+  }
+  /** @param {{readonly options?: V1ImportOptions | null}} request @param {V1RequestOptions} [options] @returns {Promise<V1ImportJob>} */
+  async update(request, options = {}) {
+    members(request, ["options"]);
+    mutationOptions(options);
+    return job((await this.#transport.call("updateImport", this.#params, { body: stringifyExactJson(request, "import update"), signal: options.signal })).value);
+  }
+  /** @param {{readonly previewId: string}} request @param {V1RequestOptions} [options] @returns {Promise<V1ImportJob>} */
+  async start(request, options = {}) {
+    members(request, ["previewId"]);
+    requireId(request.previewId, "Preview ID");
+    mutationOptions(options);
+    return job((await this.#transport.call("startImport", this.#params, { body: stringifyExactJson(request, "import start"), signal: options.signal })).value);
+  }
+  /** @param {V1RequestOptions} [options] @returns {Promise<V1ImportJob>} */
+  async cancel(options = {}) { mutationOptions(options); return job((await this.#transport.call("cancelImport", this.#params, { signal: options.signal })).value); }
+  /** @param {V1RequestOptions} [options] @returns {Promise<V1ImportJob>} */
+  async resume(options = {}) { mutationOptions(options); return job((await this.#transport.call("resumeImport", this.#params, { signal: options.signal })).value); }
+}

package/src/v1/indexes.js

@@ -0,0 +1,76 @@
+import { requireName } from "./ids.js";
+import { flag, list, numeric, 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 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 })) });
+const applied = record({ status: text, index });
+/** @typedef {ReturnType<typeof index>} V1Index */
+/** @typedef {ReturnType<typeof indexes>} V1IndexList */
+/** @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 */
+/** @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.");
+  return value;
+}
+
+/** Secondary indexes, automatic policies and workload recommendations for one database. */
+export class V1Indexes {
+  /** @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 {V1CreateIndexRequest} request @param {V1RequestOptions} [options] @returns {Promise<V1Index>} */
+  async create(request, options = {}) {
+    members(request, ["collection", "fields", "name"]);
+    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)))
+      throw new TypeError("fields must be 1-4 distinct dotted paths, excluding _id and _rev.");
+    if (request.name !== undefined && request.name !== null) indexName(request.name);
+    mutationOptions(options);
+    return index((await this.#transport.call("createIndex", this.#params, { body: stringifyExactJson(request, "index"), signal: options.signal })).value);
+  }
+  /** @param {{ readonly collection?: string }} [request] @param {V1RequestOptions} [options] @returns {Promise<V1IndexList>} */
+  async list(request = {}, options = {}) {
+    members(request, ["collection"]);
+    const query = new URLSearchParams();
+    if (request.collection !== undefined) query.set("collection", requireName("collection", request.collection));
+    return indexes((await this.#transport.call("listIndexes", this.#params, { query, signal: options.signal })).value);
+  }
+  /** @param {string} name @param {V1RequestOptions} [options] @returns {Promise<void>} */
+  async drop(name, options = {}) {
+    mutationOptions(options);
+    await this.#transport.call("dropIndex", { ...this.#params, index: indexName(name) }, { signal: options.signal });
+  }
+  /** @param {string} collection @param {V1RequestOptions} [options] @returns {Promise<V1AutoIndexPolicy>} */
+  async getAutoPolicy(collection, options = {}) {
+    return policy((await this.#transport.call("getAutoIndexPolicy", { ...this.#params, collection: requireName("collection", collection) }, { signal: options.signal })).value);
+  }
+  /** @param {string} collection @param {{ readonly enabled: boolean }} request @param {V1RequestOptions} [options] @returns {Promise<V1AutoIndexPolicy>} */
+  async setAutoPolicy(collection, request, options = {}) {
+    members(request, ["enabled"]);
+    if (typeof request.enabled !== "boolean") throw new TypeError("enabled must be boolean.");
+    mutationOptions(options);
+    return policy((await this.#transport.call("setAutoIndexPolicy", { ...this.#params, collection: requireName("collection", collection) }, {
+      body: stringifyExactJson(request, "auto-index policy"), signal: options.signal,
+    })).value);
+  }
+  /** @param {V1RequestOptions} [options] @returns {Promise<V1IndexRecommendations>} */
+  async recommendations(options = {}) { return recommendations((await this.#transport.call("listIndexRecommendations", this.#params, { signal: options.signal })).value); }
+  /** @param {string} id Opaque producer recommendation identifier. @param {V1RequestOptions} [options] @returns {Promise<V1AppliedIndexRecommendation>} */
+  async applyRecommendation(id, options = {}) {
+    if (typeof id !== "string" || id === "") throw new TypeError("A recommendation identifier is required.");
+    mutationOptions(options);
+    return applied((await this.#transport.call("applyIndexRecommendation", { ...this.#params, recommendation: id }, { signal: options.signal })).value);
+  }
+}

package/src/v1/json.js

@@ -28,9 +28,10 @@ function canonicalDecimal(text) {
   let digits = `${match[2]}${fraction}`.replace(/^0+/u, "");
   let exponent = BigInt(match[4] ?? "0") - BigInt(fraction.length);
   if (digits === "") return { negative: false, digits: "", exponent: 0n };
-  const trimmed = digits.replace(/0+$/u, "");
-  exponent += BigInt(digits.length - trimmed.length);
-  digits = trimmed;
+  let end = digits.length;
+  while (digits[end - 1] === "0") end--;
+  exponent += BigInt(digits.length - end);
+  digits = digits.slice(0, end);
   return { negative: match[1] === "-", digits, exponent };
 }