@terrascale/sdk 0.0.0-stage → 0.0.2

package/types/v1/decode.d.ts

@@ -0,0 +1,119 @@
+/** @import { JsonObject, JsonValue } from "./json.js" */
+/** Unknown future labels pass through. @typedef {"local_durable" | (string & {})} V1Durability */
+/**
+ * `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} version
+ * @property {"value" | "conflict" | (string & {})} state
+ * @property {JsonObject} document
+ * @property {readonly JsonValue[]} [siblings] Every live version, on a causal read with several.
+ */
+/**
+ * The result of a document write.
+ * @typedef {object} V1WriteResult
+ * @property {string} id
+ * @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.
+ */
+/**
+ * @param {string} what
+ * @returns {never}
+ */
+export function malformed(what: string): never;
+/**
+ * @param {JsonValue | undefined} value
+ * @param {string} what
+ * @returns {JsonObject}
+ */
+export function object(value: JsonValue | undefined, what: string): JsonObject;
+/**
+ * @param {JsonValue | undefined} value
+ * @param {string} what
+ * @returns {string}
+ */
+export function string(value: JsonValue | undefined, what: string): string;
+/**
+ * @param {JsonValue | undefined} value
+ * @param {string} what
+ * @returns {string}
+ */
+export function u64(value: JsonValue | undefined, what: string): string;
+/**
+ * @param {JsonValue | undefined} value
+ * @param {string} what
+ * @returns {boolean}
+ */
+export function boolean(value: JsonValue | undefined, what: string): boolean;
+/**
+ * @param {JsonValue | undefined} value
+ * @param {string} what
+ * @returns {JsonValue[]}
+ */
+export function array(value: JsonValue | undefined, what: string): JsonValue[];
+/**
+ * @param {JsonValue | undefined} value
+ * @returns {V1Durability}
+ */
+export function durability(value: JsonValue | undefined): V1Durability;
+/**
+ * @param {JsonValue | undefined} value
+ * @returns {V1Document}
+ */
+export function decodeDocument(value: JsonValue | undefined): V1Document;
+/**
+ * @param {{ status: number; headers: Headers; value: JsonValue | undefined }} response
+ * @returns {V1WriteResult}
+ */
+export function decodeWrite(response: {
+    status: number;
+    headers: Headers;
+    value: JsonValue | undefined;
+}): V1WriteResult;
+/**
+ * Unknown future labels pass through.
+ */
+export type V1Durability = "local_durable" | (string & {});
+/**
+ * `document` is the value, or the LWW winner when a causal read answers `"conflict"` with `siblings`.
+ * Unknown future states pass through.
+ */
+export type V1Document = {
+    id: string;
+    version: string;
+    state: "value" | "conflict" | (string & {});
+    document: JsonObject;
+    /**
+     * Every live version, on a causal read with several.
+     */
+    siblings?: readonly JsonValue[];
+};
+/**
+ * The result of a document write.
+ */
+export type V1WriteResult = {
+    id: string;
+    /**
+     * For a delete, the tombstone's version.
+     */
+    version: string;
+    /**
+     * The database commit offset (decimal u64), usable with shape `waitFor`.
+     */
+    offset: string;
+    durability: V1Durability;
+    /**
+     * True when a PUT or POST answered 201.
+     */
+    created: boolean;
+    /**
+     * The Location header of a POST create.
+     */
+    location: string | undefined;
+};
+import type { JsonValue } from "./json.js";
+import type { JsonObject } from "./json.js";

package/types/v1/errors.d.ts

@@ -0,0 +1,107 @@
+/**
+ * @param {unknown} error
+ * @param {string} [code] Also require this `error.code`.
+ * @returns {error is TerraBaseV1Error}
+ */
+export function isTerraBaseV1Error(error: unknown, code?: string): error is TerraBaseV1Error;
+/**
+ * @param {string | null} value
+ * @returns {string | undefined}
+ */
+export function unquoteEtag(value: string | null): string | undefined;
+/**
+ * @param {Headers} headers
+ * @returns {number | undefined} Seconds.
+ */
+export function parseRetryAfter(headers: Headers): number | undefined;
+/**
+ * @param {number} status
+ * @param {Headers} headers
+ * @param {string} text
+ * @returns {TerraBaseV1Error}
+ */
+export function parseV1Error(status: number, headers: Headers, text: string): TerraBaseV1Error;
+/** @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 {
+    /** @param {TerraBaseV1ErrorInit} init */
+    constructor(init: TerraBaseV1ErrorInit);
+    /** @type {number} HTTP status. */
+    status: number;
+    /** @type {string} */
+    code: string;
+    /** @type {number | undefined} Failing transaction op index. */
+    op: number | undefined;
+    /** @type {string | undefined} New shape handle for `must_refetch`. */
+    handle: string | undefined;
+    /** @type {number | undefined} Parsed `Retry-After`, in seconds. */
+    retryAfter: number | undefined;
+    /** @type {string | undefined} Unquoted `ETag`; a deleted document's 404 carries its tombstone version. */
+    etag: string | undefined;
+    /** @type {JsonObject | undefined} The raw error object, for route-specific metadata. */
+    details: JsonObject | undefined;
+}
+/** Current document, collection and shape producer codes, plus client not_modified. */
+export const V1ErrorCode: Readonly<{
+    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 {
+}
+/** `401 invalid_key`: the API key is unknown or revoked. */
+export class V1InvalidKeyError extends TerraBaseV1Error {
+}
+/** `403 forbidden_scope`: the key's scopes do not cover the request. */
+export class V1ForbiddenScopeError extends TerraBaseV1Error {
+}
+/** `404 not_found`: absent or deleted; `etag` carries a tombstone version. */
+export class V1NotFoundError extends TerraBaseV1Error {
+}
+export type TerraBaseV1ErrorInit = {
+    status: number;
+    code: string;
+    message?: string | undefined;
+    op?: number | undefined;
+    handle?: string | undefined;
+    retryAfter?: number | undefined;
+    etag?: string | undefined;
+    details?: JsonObject | undefined;
+};
+import type { JsonObject } from "./json.js";

package/types/v1/filter.d.ts

@@ -0,0 +1,148 @@
+/**
+ * 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: unknown): pointer is string;
+/**
+ * @param {V1Path} path
+ * @returns {V1Path}
+ */
+export function requirePath(path: V1Path): V1Path;
+/**
+ * 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: unknown): V1Filter;
+/**
+ * Query v1 filter builders. `v1Filter.id` is the `"$id"` pseudo-path.
+ */
+export const v1Filter: Readonly<{
+    /** The document ID pseudo-path. */
+    id: "$id";
+    /**
+     * @param {...V1Filter} filters
+     * @returns {V1Filter}
+     */
+    and: (...filters: V1Filter[]) => V1Filter;
+    /**
+     * @param {...V1Filter} filters
+     * @returns {V1Filter}
+     */
+    or: (...filters: V1Filter[]) => V1Filter;
+    /**
+     * @param {V1Filter} filter
+     * @returns {V1Filter}
+     */
+    not: (filter: V1Filter) => V1Filter;
+    /**
+     * @param {V1Path} path
+     * @param {V1Scalar} value
+     * @returns {V1Filter}
+     */
+    eq: (path: V1Path, value: V1Scalar) => V1Filter;
+    /**
+     * Not equal; also matches a missing member.
+     * @param {V1Path} path
+     * @param {V1Scalar} value
+     * @returns {V1Filter}
+     */
+    ne: (path: V1Path, value: V1Scalar) => V1Filter;
+    /**
+     * @param {V1Path} path
+     * @param {V1Scalar} value
+     * @returns {V1Filter}
+     */
+    lt: (path: V1Path, value: V1Scalar) => V1Filter;
+    /**
+     * @param {V1Path} path
+     * @param {V1Scalar} value
+     * @returns {V1Filter}
+     */
+    lte: (path: V1Path, value: V1Scalar) => V1Filter;
+    /**
+     * @param {V1Path} path
+     * @param {V1Scalar} value
+     * @returns {V1Filter}
+     */
+    gt: (path: V1Path, value: V1Scalar) => V1Filter;
+    /**
+     * @param {V1Path} path
+     * @param {V1Scalar} value
+     * @returns {V1Filter}
+     */
+    gte: (path: V1Path, value: V1Scalar) => V1Filter;
+    /**
+     * @param {V1Path} path
+     * @param {readonly V1Scalar[]} values 1-256 values.
+     * @returns {V1Filter}
+     */
+    in: (path: V1Path, values: readonly V1Scalar[]) => V1Filter;
+    /**
+     * @param {V1Path} path
+     * @param {readonly V1Scalar[]} values 1-256 values.
+     * @returns {V1Filter}
+     */
+    nin: (path: V1Path, values: readonly V1Scalar[]) => V1Filter;
+    /**
+     * The member is present (including null).
+     * @param {V1Path} path
+     * @returns {V1Filter}
+     */
+    exists: (path: V1Path) => V1Filter;
+    /**
+     * @param {V1Path} path
+     * @param {string} prefix
+     * @returns {V1Filter}
+     */
+    prefix: (path: V1Path, prefix: string) => V1Filter;
+    /**
+     * The value is an array containing the scalar.
+     * @param {V1Path} path
+     * @param {V1Scalar} value
+     * @returns {V1Filter}
+     */
+    contains: (path: V1Path, value: V1Scalar) => V1Filter;
+}>;
+/**
+ * A filter or sort path: an RFC 6901 JSON Pointer or "$id".
+ */
+export type V1Path = string;
+/**
+ * A filter operand: string, exact number, boolean or null.
+ */
+export type V1Scalar = null | boolean | string | number | bigint | ExactDecimal;
+export type V1Filter = {
+    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];
+};
+import { ExactDecimal } from "./json.js";

package/types/v1/ids.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @param {"database" | "collection"} kind
+ * @param {unknown} name
+ * @returns {string}
+ */
+export function requireName(kind: "database" | "collection", name: unknown): string;
+/**
+ * The producer resolves this opaque catalog project id (normally a UUID), not its display name.
+ * @param {unknown} project
+ * @returns {string}
+ */
+export function requireProject(project: unknown): string;
+/**
+ * @param {unknown} id
+ * @returns {string}
+ */
+export function requireDocumentId(id: unknown): string;
+/**
+ * @param {unknown} version
+ * @returns {string}
+ */
+export function requireVersion(version: unknown): string;
+/**
+ * Parses a canonical decimal u64 (an offset), or returns undefined.
+ * @param {unknown} value
+ * @returns {bigint | undefined}
+ */
+export function parseU64(value: unknown): bigint | 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: unknown, what: string): bigint;
+/**
+ * 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 function documentIdFor(collection: string, key: string): Promise<string>;

package/types/v1/json.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Parses JSON text without losing number precision.
+ * @param {string} text
+ * @returns {JsonValue}
+ */
+export function parseExactJson(text: string): JsonValue;
+/**
+ * Validates a document, merge patch or patch operand against C# RequestJson limits.
+ * @param {unknown} value
+ * @param {string} where
+ * @returns {void}
+ */
+export function assertJsonValue(value: unknown, where: string): void;
+/**
+ * Encodes a request value exactly. bigint and ExactDecimal keep every digit.
+ * @param {unknown} value
+ * @param {string} where
+ * @returns {string}
+ */
+export function stringifyExactJson(value: unknown, where: string): string;
+/**
+ * @param {unknown} value
+ * @param {string} where
+ * @returns {void}
+ */
+export function assertJsonObject(value: unknown, where: string): void;
+/**
+ * @param {unknown} value
+ * @returns {value is JsonObject}
+ */
+export function isJsonObject(value: unknown): value is JsonObject;
+/**
+ * An exact decimal number as it travels on the wire. Values that a JavaScript
+ * number cannot represent exactly (large integers, long fractions) are
+ * returned as ExactDecimal; it serializes back to the identical JSON text.
+ */
+export class ExactDecimal {
+    /**
+     * @param {ExactDecimal | bigint | number | string} value
+     * @returns {ExactDecimal}
+     */
+    static from(value: ExactDecimal | bigint | number | string): ExactDecimal;
+    /** @param {string} text A JSON number literal. */
+    constructor(text: string);
+    /** @returns {string} The exact JSON number text. */
+    toString(): string;
+    /** @returns {unknown} A raw JSON value that serializes as the exact text. */
+    toJSON(): unknown;
+    /** @returns {number} The nearest JavaScript number; may lose precision. */
+    toNumber(): number;
+    /** @returns {boolean} */
+    isInteger(): boolean;
+    /**
+     * @returns {bigint} The exact integer value.
+     * @throws {RangeError} When the value is not an integer.
+     */
+    toBigInt(): bigint;
+    /**
+     * Exact decimal equality: 1, 1.0 and 1e0 are equal.
+     * @param {ExactDecimal | bigint | number | string} other
+     * @returns {boolean}
+     */
+    equals(other: ExactDecimal | bigint | number | string): boolean;
+    #private;
+}
+export type CanonicalDecimal = {
+    negative: boolean;
+    /**
+     * Significant digits without leading or trailing zeros; empty for zero.
+     */
+    digits: string;
+    /**
+     * The value is digits × 10^exponent.
+     */
+    exponent: bigint;
+};
+/**
+ * A decoded JSON value. Numbers are `number` when exact, else ExactDecimal.
+ */
+export type JsonValue = null | boolean | number | string | ExactDecimal | JsonArray | JsonObject;
+export type JsonArray = JsonValue[];
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+/**
+ * A JSON value accepted in requests: bigint and ExactDecimal encode exactly.
+ */
+export type JsonInput = null | boolean | number | bigint | string | ExactDecimal | JsonInputArray | JsonInputObject;
+export type JsonInputArray = readonly JsonInput[];
+export type JsonInputObject = {
+    readonly [key: string]: JsonInput;
+};

package/types/v1/routes.d.ts

@@ -0,0 +1,26 @@
+/** @param {V1Operation} operation @returns {V1Route} */
+export function v1Route(operation: V1Operation): V1Route;
+/** @param {V1Route} route @param {Readonly<Record<string, string>>} params @returns {string} */
+export function v1RoutePath(route: V1Route, params: Readonly<Record<string, string>>): string;
+/** @type {readonly V1Route[]} */
+export const v1Routes: readonly V1Route[];
+export type V1Operation = "getDocument" | "putDocument" | "createDocument" | "patchDocument" | "deleteDocument" | "commitTransaction" | "queryDocuments" | "createCollection" | "getCollection" | "listCollections" | "dropCollection" | "readShape";
+export type V1Route = {
+    operation: V1Operation;
+    method: "GET" | "PUT" | "POST" | "PATCH" | "DELETE";
+    pathTemplate: string;
+    permission: "documents:read" | "documents:write" | "shapes:read";
+    requestMediaTypes: readonly string[];
+    responseMediaType: string;
+    successStatuses: readonly number[];
+    /**
+     * The producer rejects Idempotency-Key.
+     */
+    idempotencyKey: "none";
+    /**
+     * Informational only; requests are never automatically replayed.
+     */
+    replaySafe: boolean;
+    contract: string;
+    contractText: readonly string[];
+};

package/types/v1/shapes.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Validates canonical C# offsets. Snapshot positions use a UTF-8/base64url keyset, not a page number.
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function requireShapeOffset(value: unknown): string;
+/** @param {V1ShapeRequest} request @returns {URLSearchParams} */
+export function encodeShapeRequest(request: V1ShapeRequest): URLSearchParams;
+/** @param {JsonValue | undefined} value @param {Headers} headers @returns {V1ShapePage} */
+export function decodeShapePage(value: JsonValue | undefined, headers: Headers): V1ShapePage;
+/**
+ * Bootstrap extracts continuation metadata from 307 but never forwards credentials to Location.
+ * The next request is rebuilt against the same named route and configured endpoint.
+ * @param {V1Transport} transport
+ * @param {Readonly<Record<string, string>>} params
+ * @param {V1ShapeRequest} request
+ * @param {AbortSignal | undefined} signal
+ * @returns {Promise<V1ShapePage>}
+ */
+export function readShape(transport: V1Transport, params: Readonly<Record<string, string>>, request: V1ShapeRequest, signal: AbortSignal | undefined): Promise<V1ShapePage>;
+export type V1ShapeRequest = {
+    /**
+     * Filter using the current query grammar; projection is unsupported.
+     */
+    where?: V1Filter | undefined;
+    /**
+     * -1 (default, server bootstrap only), snap.<head>.<base64url-id>, or a decimal log position.
+     */
+    offset?: string | undefined;
+    /**
+     * Required after bootstrap.
+     */
+    handle?: string | undefined;
+    /**
+     * True only for log positions; waits up to 20 seconds.
+     */
+    live?: boolean | undefined;
+    /**
+     * Previous live response's TB-Shape-Cursor.
+     */
+    cursor?: string | undefined;
+};
+export type V1ShapeOp = {
+    readonly op: "upsert";
+    readonly id: string;
+    readonly version: string;
+    readonly document: JsonObject;
+} | {
+    readonly op: "delete";
+    readonly id: string;
+};
+export type V1ShapeChange = {
+    readonly offset: string;
+    readonly ops: readonly V1ShapeOp[];
+};
+/**
+ * One snapshot page or log chunk. Only a fresh open tail/live response can report upToDate.
+ */
+export type V1ShapePage = {
+    shapeId: string;
+    handle: string;
+    offset: string;
+    nextOffset: string;
+    upToDate: boolean;
+    /**
+     * Apply commits and operations in their received order.
+     */
+    changes: readonly V1ShapeChange[];
+    /**
+     * Echo this as cursor on the next live request.
+     */
+    cursor: string | undefined;
+    etag: string | undefined;
+};
+import type { JsonValue } from "./json.js";
+import type { V1Transport } from "./transport.js";
+import type { V1Filter } from "./filter.js";
+import type { JsonObject } from "./json.js";