terrascale 0.3.0 → 1.0.0

package/src/v1/errors.js

@@ -0,0 +1,185 @@
+import { isJsonObject, parseExactJson } from "./json.js";
+/** @import { JsonObject } from "./json.js" */
+
+/**
+ * @typedef {object} TerraBaseV1ErrorInit
+ * @property {number} status
+ * @property {string} code
+ * @property {string | undefined} [message]
+ * @property {number | undefined} [op]
+ * @property {string | undefined} [handle]
+ * @property {number | undefined} [retryAfter]
+ * @property {string | undefined} [etag]
+ * @property {JsonObject | undefined} [details]
+ */
+
+/**
+ * A non-2xx TerraBase v1 response. `code` is the contract's `error.code`, or
+ * `not_modified` for a 304 and `http_<status>` when the body carried no code.
+ */
+export class TerraBaseV1Error extends Error {
+  /** @type {number} HTTP status. */
+  status;
+  /** @type {string} */
+  code;
+  /** @type {number | undefined} Failing transaction op index. */
+  op;
+  /** @type {string | undefined} New shape handle for `must_refetch`. */
+  handle;
+  /** @type {number | undefined} Parsed `Retry-After`, in seconds. */
+  retryAfter;
+  /** @type {string | undefined} Unquoted `ETag`; a deleted document's 404 carries its tombstone version. */
+  etag;
+  /** @type {JsonObject | undefined} The raw error object, for route-specific metadata. */
+  details;
+
+  /** @param {TerraBaseV1ErrorInit} init */
+  constructor(init) {
+    const suffix = [
+      init.message === undefined ? "" : `: ${init.message}`,
+      init.op === undefined ? "" : ` (op ${init.op})`,
+    ].join("");
+    super(`TerraBase ${init.status} ${init.code}${suffix}`);
+    this.name = "TerraBaseV1Error";
+    this.status = init.status;
+    this.code = init.code;
+    this.op = init.op;
+    this.handle = init.handle;
+    this.retryAfter = init.retryAfter;
+    this.etag = init.etag;
+    this.details = init.details;
+  }
+}
+
+/** Current document, collection and shape producer codes, plus client not_modified. */
+export const V1ErrorCode = Object.freeze({
+  invalidRequest: "invalid_request", invalidQuery: "invalid_query", invalidCursor: "invalid_cursor",
+  invalidPatch: "invalid_patch", sortRequiresIndex: "sort_requires_index", assertRequiresIndex: "assert_requires_index",
+  invalidKey: "invalid_key", forbiddenScope: "forbidden_scope", notFound: "not_found",
+  unknownDatabase: "unknown_database", unknownCollection: "unknown_collection", unknownRoute: "unknown_route",
+  methodNotAllowed: "method_not_allowed", patchConflict: "patch_conflict", nameTaken: "name_taken",
+  mustRefetch: "must_refetch", preconditionFailed: "precondition_failed", payloadTooLarge: "payload_too_large",
+  unsupportedMediaType: "unsupported_media_type", uriTooLong: "uri_too_long", shapeBusy: "shape_busy",
+  internalError: "internal_error", capacity: "capacity", notModified: "not_modified",
+});
+
+/** `412 precondition_failed`: an If-Match, If-None-Match, assert or assert_count failed. */
+export class V1PreconditionFailedError extends TerraBaseV1Error {
+  /** @param {TerraBaseV1ErrorInit} init */
+  constructor(init) {
+    super(init);
+    this.name = "V1PreconditionFailedError";
+  }
+}
+
+/** `401 invalid_key`: the API key is unknown or revoked. */
+export class V1InvalidKeyError extends TerraBaseV1Error {
+  /** @param {TerraBaseV1ErrorInit} init */
+  constructor(init) {
+    super(init);
+    this.name = "V1InvalidKeyError";
+  }
+}
+
+/** `403 forbidden_scope`: the key's scopes do not cover the request. */
+export class V1ForbiddenScopeError extends TerraBaseV1Error {
+  /** @param {TerraBaseV1ErrorInit} init */
+  constructor(init) {
+    super(init);
+    this.name = "V1ForbiddenScopeError";
+  }
+}
+
+/** `404 not_found`: absent or deleted; `etag` carries a tombstone version. */
+export class V1NotFoundError extends TerraBaseV1Error {
+  /** @param {TerraBaseV1ErrorInit} init */
+  constructor(init) {
+    super(init);
+    this.name = "V1NotFoundError";
+  }
+}
+
+/**
+ * @param {TerraBaseV1ErrorInit} init
+ * @returns {TerraBaseV1Error}
+ */
+function typedError(init) {
+  switch (init.code) {
+    case "precondition_failed": return new V1PreconditionFailedError(init);
+    case "invalid_key": return new V1InvalidKeyError(init);
+    case "forbidden_scope": return new V1ForbiddenScopeError(init);
+    case "not_found": return new V1NotFoundError(init);
+    default: return new TerraBaseV1Error(init);
+  }
+}
+
+/**
+ * @param {unknown} error
+ * @param {string} [code] Also require this `error.code`.
+ * @returns {error is TerraBaseV1Error}
+ */
+export function isTerraBaseV1Error(error, code) {
+  return error instanceof TerraBaseV1Error && (code === undefined || error.code === code);
+}
+
+/**
+ * @param {string | null} value
+ * @returns {string | undefined}
+ */
+export function unquoteEtag(value) {
+  if (value === null) return undefined;
+  const trimmed = value.trim().replace(/^W\//u, "");
+  return trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')
+    ? trimmed.slice(1, -1)
+    : trimmed;
+}
+
+/**
+ * @param {Headers} headers
+ * @returns {number | undefined} Seconds.
+ */
+export function parseRetryAfter(headers) {
+  const value = headers.get("retry-after")?.trim();
+  if (value === undefined || value === "") return undefined;
+  if (/^\d{1,9}$/u.test(value)) return Number(value);
+  const date = Date.parse(value);
+  return Number.isNaN(date) ? undefined : Math.max(0, (date - Date.now()) / 1000);
+}
+
+/**
+ * @param {number} status
+ * @param {Headers} headers
+ * @param {string} text
+ * @returns {TerraBaseV1Error}
+ */
+export function parseV1Error(status, headers, text) {
+  /** @type {JsonObject | undefined} */
+  let details;
+  try {
+    const parsed = text === "" ? undefined : parseExactJson(text);
+    if (isJsonObject(parsed) && isJsonObject(parsed.error)) details = parsed.error;
+  } catch {
+    details = undefined;
+  }
+  /**
+   * @param {string} name
+   * @returns {string | undefined}
+   */
+  const text_ = (name) => {
+    const value = details?.[name];
+    return typeof value === "string" ? value : undefined;
+  };
+  const op = details?.op;
+  const code =
+    text_("code") ?? (status === 304 ? "not_modified" : `http_${status}`);
+  return typedError({
+    status,
+    code,
+    message: text_("message"),
+    op: typeof op === "number" && Number.isInteger(op) ? op : undefined,
+    handle: text_("handle"),
+    retryAfter: parseRetryAfter(headers),
+    etag: unquoteEtag(headers.get("etag")),
+    details,
+  });
+}

package/src/v1/filter.js

@@ -0,0 +1,230 @@
+// Query v1 filter grammar builders (query-v1.md). Filters are plain wire
+// objects, shared by queries, transaction asserts and shapes.
+import { ExactDecimal } from "./json.js";
+
+/**
+ * A filter or sort path: an RFC 6901 JSON Pointer or "$id".
+ * @typedef {string} V1Path
+ */
+/**
+ * A filter operand: string, exact number, boolean or null.
+ * @typedef {null | boolean | string | number | bigint | ExactDecimal} V1Scalar
+ */
+/**
+ * @typedef {{ readonly and: readonly V1Filter[] }
+ *   | { readonly or: readonly V1Filter[] }
+ *   | { readonly not: V1Filter }
+ *   | { readonly eq: readonly [V1Path, V1Scalar] }
+ *   | { readonly ne: readonly [V1Path, V1Scalar] }
+ *   | { readonly lt: readonly [V1Path, V1Scalar] }
+ *   | { readonly lte: readonly [V1Path, V1Scalar] }
+ *   | { readonly gt: readonly [V1Path, V1Scalar] }
+ *   | { readonly gte: readonly [V1Path, V1Scalar] }
+ *   | { readonly in: readonly [V1Path, readonly V1Scalar[]] }
+ *   | { readonly nin: readonly [V1Path, readonly V1Scalar[]] }
+ *   | { readonly exists: V1Path }
+ *   | { readonly prefix: readonly [V1Path, string] }
+ *   | { readonly contains: readonly [V1Path, V1Scalar] }} V1Filter
+ */
+
+/**
+ * @param {unknown} pointer
+ * @returns {pointer is string}
+ */
+function isPointer(pointer) {
+  return isJsonPointer(pointer) && pointer.split("/").length - 1 <= 16;
+}
+
+/**
+ * An RFC 6901 JSON Pointer of at most 4 KiB with at least one segment: `~`
+ * only as the escapes `~0` and `~1`.
+ * @param {unknown} pointer
+ * @returns {pointer is string}
+ */
+export function isJsonPointer(pointer) {
+  return typeof pointer === "string" && pointer.length <= 4096 && pointer.split("/").length - 1 <= 16 && !/[\uD800-\uDFFF]/u.test(pointer) && /^(?:\/(?:[^~/]|~[01])*)+$/u.test(pointer);
+}
+
+/**
+ * @param {V1Path} path
+ * @returns {V1Path}
+ */
+export function requirePath(path) {
+  if (path === "$id" || isPointer(path)) return path;
+  throw new TypeError('A TerraBase path is an RFC 6901 JSON Pointer of 1-16 segments, "$id".');
+}
+
+/**
+ * @param {V1Scalar} value
+ * @returns {V1Scalar}
+ */
+function requireScalar(value) {
+  if (
+    value === null ||
+    typeof value === "boolean" ||
+    typeof value === "string" ||
+    typeof value === "bigint" ||
+    value instanceof ExactDecimal ||
+    (typeof value === "number" && Number.isFinite(value))
+  )
+    return value;
+  throw new TypeError("Filter values are JSON scalars: string, finite number, bigint, ExactDecimal, boolean or null.");
+}
+
+/**
+ * @param {"and" | "or"} op
+ * @param {readonly V1Filter[]} filters
+ * @returns {readonly V1Filter[]}
+ */
+function children(op, filters) {
+  if (filters.length < 1 || filters.length > 64) throw new TypeError(`${op} takes 1-64 filters.`);
+  return Object.freeze([...filters]);
+}
+
+/**
+ * @param {"in" | "nin"} op
+ * @param {readonly V1Scalar[]} values
+ * @returns {readonly V1Scalar[]}
+ */
+function scalars(op, values) {
+  if (!Array.isArray(values) || values.length < 1 || values.length > 256)
+    throw new TypeError(`${op} takes 1-256 values.`);
+  return Object.freeze(values.map(requireScalar));
+}
+
+const binaryOperators = new Set(["eq", "ne", "lt", "lte", "gt", "gte", "contains"]);
+
+/**
+ * Validates a filter against the query-v1 grammar (operators, arity, paths,
+ * scalar operands, depth 8 and 256 nodes), so a malformed filter fails locally
+ * instead of as a server `invalid_query`. The v1Filter builders always pass.
+ * @param {unknown} filter
+ * @returns {V1Filter}
+ */
+export function requireFilter(filter) {
+  let nodes = 0;
+  /**
+   * @param {unknown} node
+   * @param {number} depth
+   * @returns {void}
+   */
+  const visit = (node, depth) => {
+    if (++nodes > 256) throw new TypeError("A filter has at most 256 nodes.");
+    if (depth > 8) throw new TypeError("A filter nests at most 8 levels.");
+    if (typeof node !== "object" || node === null || Array.isArray(node) || Object.keys(node).length !== 1)
+      throw new TypeError("A filter node is an object with exactly one operator.");
+    const [op, args] = /** @type {[string, unknown]} */ (Object.entries(node)[0]);
+    if (op === "and" || op === "or") {
+      if (!Array.isArray(args) || args.length < 1 || args.length > 64) throw new TypeError(`${op} takes 1-64 filters.`);
+      for (const child of args) visit(child, depth + 1);
+    } else if (op === "not") visit(args, depth + 1);
+    else if (op === "exists") requirePath(/** @type {V1Path} */ (args));
+    else if (binaryOperators.has(op) || op === "prefix" || op === "in" || op === "nin") {
+      if (!Array.isArray(args) || args.length !== 2) throw new TypeError(`${op} takes [path, value].`);
+      requirePath(args[0]);
+      if (op === "in" || op === "nin") scalars(op, args[1]);
+      else if (op === "prefix") {
+        if (typeof args[1] !== "string") throw new TypeError("prefix takes a string.");
+      } else {
+        requireScalar(args[1]);
+        if (op !== "eq" && op !== "ne" && op !== "contains" && args[1] === null) throw new TypeError(`${op} does not compare null.`);
+      }
+    } else throw new TypeError(`Unknown filter operator ${op}.`);
+  };
+  visit(filter, 1);
+  return /** @type {V1Filter} */ (filter);
+}
+
+/**
+ * Query v1 filter builders. `v1Filter.id` is the `"$id"` pseudo-path.
+ */
+export const v1Filter = Object.freeze({
+  /** The document ID pseudo-path. */
+  id: /** @type {"$id"} */ ("$id"),
+  /**
+   * @param {...V1Filter} filters
+   * @returns {V1Filter}
+   */
+  and: (...filters) => Object.freeze({ and: children("and", filters) }),
+  /**
+   * @param {...V1Filter} filters
+   * @returns {V1Filter}
+   */
+  or: (...filters) => Object.freeze({ or: children("or", filters) }),
+  /**
+   * @param {V1Filter} filter
+   * @returns {V1Filter}
+   */
+  not: (filter) => Object.freeze({ not: filter }),
+  /**
+   * @param {V1Path} path
+   * @param {V1Scalar} value
+   * @returns {V1Filter}
+   */
+  eq: (path, value) => Object.freeze({ eq: Object.freeze(/** @type {const} */ ([requirePath(path), requireScalar(value)])) }),
+  /**
+   * Not equal; also matches a missing member.
+   * @param {V1Path} path
+   * @param {V1Scalar} value
+   * @returns {V1Filter}
+   */
+  ne: (path, value) => Object.freeze({ ne: Object.freeze(/** @type {const} */ ([requirePath(path), requireScalar(value)])) }),
+  /**
+   * @param {V1Path} path
+   * @param {V1Scalar} value
+   * @returns {V1Filter}
+   */
+  lt: (path, value) => Object.freeze({ lt: Object.freeze(/** @type {const} */ ([requirePath(path), requireScalar(value)])) }),
+  /**
+   * @param {V1Path} path
+   * @param {V1Scalar} value
+   * @returns {V1Filter}
+   */
+  lte: (path, value) => Object.freeze({ lte: Object.freeze(/** @type {const} */ ([requirePath(path), requireScalar(value)])) }),
+  /**
+   * @param {V1Path} path
+   * @param {V1Scalar} value
+   * @returns {V1Filter}
+   */
+  gt: (path, value) => Object.freeze({ gt: Object.freeze(/** @type {const} */ ([requirePath(path), requireScalar(value)])) }),
+  /**
+   * @param {V1Path} path
+   * @param {V1Scalar} value
+   * @returns {V1Filter}
+   */
+  gte: (path, value) => Object.freeze({ gte: Object.freeze(/** @type {const} */ ([requirePath(path), requireScalar(value)])) }),
+  /**
+   * @param {V1Path} path
+   * @param {readonly V1Scalar[]} values 1-256 values.
+   * @returns {V1Filter}
+   */
+  in: (path, values) => Object.freeze({ in: Object.freeze(/** @type {const} */ ([requirePath(path), scalars("in", values)])) }),
+  /**
+   * @param {V1Path} path
+   * @param {readonly V1Scalar[]} values 1-256 values.
+   * @returns {V1Filter}
+   */
+  nin: (path, values) => Object.freeze({ nin: Object.freeze(/** @type {const} */ ([requirePath(path), scalars("nin", values)])) }),
+  /**
+   * The member is present (including null).
+   * @param {V1Path} path
+   * @returns {V1Filter}
+   */
+  exists: (path) => Object.freeze({ exists: requirePath(path) }),
+  /**
+   * @param {V1Path} path
+   * @param {string} prefix
+   * @returns {V1Filter}
+   */
+  prefix: (path, prefix) => {
+    if (typeof prefix !== "string") throw new TypeError("prefix takes a string.");
+    return Object.freeze({ prefix: Object.freeze(/** @type {const} */ ([requirePath(path), prefix])) });
+  },
+  /**
+   * The value is an array containing the scalar.
+   * @param {V1Path} path
+   * @param {V1Scalar} value
+   * @returns {V1Filter}
+   */
+  contains: (path, value) => Object.freeze({ contains: Object.freeze(/** @type {const} */ ([requirePath(path), requireScalar(value)])) }),
+});

package/src/v1/ids.js

@@ -0,0 +1,118 @@
+// Identifiers for the TerraBase v1 Documents API (api-v1.md).
+
+const namePattern = /^[a-z][a-z0-9_-]{0,62}$/u;
+const versionPattern = /^tbv1-[0-9a-f]{32}$/u;
+const offsetPattern = /^(?:0|[1-9]\d{0,19})$/u;
+const maximumU64 = (1n << 64n) - 1n;
+
+/** RFC 9562 NAMESPACE_URL, 6ba7b811-9dad-11d1-80b4-00c04fd430c8. */
+const namespaceUrl = Uint8Array.of(
+  0x6b, 0xa7, 0xb8, 0x11, 0x9d, 0xad, 0x11, 0xd1,
+  0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8,
+);
+
+/**
+ * @param {"database" | "collection"} kind
+ * @param {unknown} name
+ * @returns {string}
+ */
+export function requireName(kind, name) {
+  if (typeof name !== "string" || !namePattern.test(name))
+    throw new TypeError(`TerraBase ${kind} names must match ^[a-z][a-z0-9_-]{0,62}$.`);
+  return name;
+}
+
+/**
+ * The producer resolves this opaque catalog project id (normally a UUID), not its display name.
+ * @param {unknown} project
+ * @returns {string}
+ */
+export function requireProject(project) {
+  if (typeof project !== "string" || project === "" || project === "." || project === ".." || /[\p{Cc}\uD800-\uDFFF]/u.test(project))
+    throw new TypeError("project must be a non-empty catalog project ID without control characters or dot path segments.");
+  return project;
+}
+
+/**
+ * @param {unknown} id
+ * @returns {string}
+ */
+export function requireDocumentId(id) {
+  if (typeof id !== "string" || id.length < 1 || id.length > 256 || /[\p{Cc}]/u.test(id) || /[\uD800-\uDFFF]/u.test(id) || id === "." || id === "..")
+    throw new TypeError("Document IDs must be 1-256 characters without control characters or dot path segments; new IDs must be lowercase UUIDs.");
+  return id;
+}
+
+/**
+ * @param {unknown} version
+ * @returns {string}
+ */
+export function requireVersion(version) {
+  if (typeof version !== "string" || !versionPattern.test(version))
+    throw new TypeError("TerraBase versions are tbv1- followed by 32 lowercase hex characters.");
+  return version;
+}
+
+/**
+ * Parses a canonical decimal u64 (an offset), or returns undefined.
+ * @param {unknown} value
+ * @returns {bigint | undefined}
+ */
+export function parseU64(value) {
+  if (typeof value !== "string" || !offsetPattern.test(value)) return undefined;
+  const parsed = BigInt(value);
+  return parsed <= maximumU64 ? parsed : undefined;
+}
+
+/**
+ * A caller-supplied u64 (a decimal string or bigint), as a bigint.
+ * @param {unknown} value
+ * @param {string} what
+ * @returns {bigint}
+ */
+export function requireU64(value, what) {
+  const parsed = parseU64(typeof value === "bigint" ? value.toString() : value);
+  if (parsed === undefined) throw new TypeError(`${what} must be a u64: a canonical decimal string or bigint.`);
+  return parsed;
+}
+
+/**
+ * @param {Uint8Array} namespace
+ * @param {string} name
+ * @returns {Promise<Uint8Array>}
+ */
+async function uuidV5(namespace, name) {
+  const encoded = new TextEncoder().encode(name);
+  const input = new Uint8Array(namespace.length + encoded.length);
+  input.set(namespace);
+  input.set(encoded, namespace.length);
+  const digest = new Uint8Array(await globalThis.crypto.subtle.digest("SHA-1", input));
+  const uuid = digest.slice(0, 16);
+  uuid[6] = ((uuid[6] ?? 0) & 0x0f) | 0x50;
+  uuid[8] = ((uuid[8] ?? 0) & 0x3f) | 0x80;
+  return uuid;
+}
+
+/**
+ * @param {Uint8Array} bytes
+ * @returns {string}
+ */
+function formatUuid(bytes) {
+  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+/**
+ * The deterministic document ID for a natural key in a collection:
+ * `uuidv5(uuidv5(NAMESPACE_URL, "terrabase:collection:" + collection), key)`.
+ * Uses WebCrypto, so it works in Node.js, browsers and workers.
+ * @param {string} collection
+ * @param {string} key
+ * @returns {Promise<string>}
+ */
+export async function documentIdFor(collection, key) {
+  requireName("collection", collection);
+  if (typeof key !== "string") throw new TypeError("The natural key must be a string.");
+  const namespace = await uuidV5(namespaceUrl, `terrabase:collection:${collection}`);
+  return formatUuid(await uuidV5(namespace, key));
+}