@terrascale/sdk 0.0.0-stage → 0.0.2

package/types/v1/terrabase-v1.d.ts

@@ -0,0 +1,374 @@
+/**
+ * Creates a TerraBase v1 client for documents, transactions, queries and shapes.
+ * @param {TerraBaseV1ClientConfig} config
+ * @returns {TerraBaseV1Client}
+ */
+export function createTerraBaseV1Client(config: TerraBaseV1ClientConfig): TerraBaseV1Client;
+/** A collection handle by name. It performs no I/O until an operation runs. */
+export class V1Collection {
+    /**
+     * @param {V1Transport} transport
+     * @param {string} database
+     * @param {string} name
+     */
+    constructor(transport: V1Transport, database: string, name: string);
+    /** @type {string} */
+    name: string;
+    /** @type {string} */
+    database: string;
+    /**
+     * Reads a document. Absent and deleted documents fail with
+     * `not_found`; a deleted document's error carries its tombstone `etag`.
+     * @param {string} id
+     * @param {V1ReadOptions} [options]
+     * @returns {Promise<V1Document>}
+     */
+    get(id: string, options?: V1ReadOptions): Promise<V1Document>;
+    /**
+     * Writes the complete document. `created` reports a 201.
+     * @param {string} id
+     * @param {JsonInputObject} document
+     * @param {V1WriteOptions} [options]
+     * @returns {Promise<V1WriteResult>}
+     */
+    put(id: string, document: JsonInputObject, options?: V1WriteOptions): Promise<V1WriteResult>;
+    /**
+     * Creates a document under a server-generated UUIDv7.
+     * @param {JsonInputObject} document
+     * @param {V1CreateOptions} [options]
+     * @returns {Promise<V1WriteResult>}
+     */
+    create(document: JsonInputObject, options?: V1CreateOptions): Promise<V1WriteResult>;
+    /**
+     * Applies a merge patch or ops patch to an existing document.
+     * @param {string} id
+     * @param {V1Patch} patch
+     * @param {V1ConditionalWriteOptions} [options]
+     * @returns {Promise<V1WriteResult>}
+     */
+    patch(id: string, patch: V1Patch, options?: V1ConditionalWriteOptions): Promise<V1WriteResult>;
+    /**
+     * Tombstones a document; `version` is the tombstone's.
+     * @param {string} id
+     * @param {V1ConditionalWriteOptions} [options]
+     * @returns {Promise<V1WriteResult>}
+     */
+    delete(id: string, options?: V1ConditionalWriteOptions): Promise<V1WriteResult>;
+    /**
+     * Runs one page of a query.
+     * @param {V1Query} [query]
+     * @param {V1RequestOptions} [options]
+     * @returns {Promise<V1QueryPage>}
+     */
+    query(query?: V1Query, options?: V1RequestOptions): Promise<V1QueryPage>;
+    /**
+     * Iterates over every page, following `nextCursor`. `count`
+     * is sent with the first page only.
+     * @param {V1Query} [query]
+     * @param {V1RequestOptions} [options]
+     * @returns {AsyncGenerator<V1QueryPage, void, undefined>}
+     */
+    pages(query?: V1Query, options?: V1RequestOptions): AsyncGenerator<V1QueryPage, void, undefined>;
+    /**
+     * Iterates over every matching document across pages.
+     * @param {V1Query} [query]
+     * @param {V1RequestOptions} [options]
+     * @returns {AsyncGenerator<V1Document, void, undefined>}
+     */
+    items(query?: V1Query, options?: V1RequestOptions): AsyncGenerator<V1Document, void, undefined>;
+    /**
+     * Reads one C# shape snapshot page or change-log chunk. Bootstrap defaults to offset -1.
+     * Echo handle, nextOffset and cursor on the following read; discard state on must_refetch.
+     * @param {V1ShapeRequest} [request]
+     * @param {V1RequestOptions} [options]
+     * @returns {Promise<V1ShapePage>}
+     */
+    shape(request?: V1ShapeRequest, options?: V1RequestOptions): Promise<V1ShapePage>;
+    #private;
+}
+/**
+ * An atomic transaction of up to 1024 ops across the collections of one
+ * database. No two ops may target the same document. Documents are encoded
+ * when an op is added, so later mutation of the input does not change it.
+ */
+export class V1Transaction {
+    /**
+     * @param {V1Precondition | undefined} precondition
+     * @param {boolean} allowNoneMatch
+     * @returns {Record<string, string>}
+     */
+    static "__#private@#precondition"(precondition: V1Precondition | undefined, allowNoneMatch: boolean): Record<string, string>;
+    /**
+     * @param {V1Transport} transport
+     * @param {string} database
+     */
+    constructor(transport: V1Transport, database: string);
+    /** @returns {number} The number of ops added. */
+    get size(): number;
+    /**
+     * Adds a create (a put requiring absence). Omit `id` to have the server
+     * generate a UUIDv7, returned in the op's result.
+     * @param {string} collection
+     * @param {JsonInputObject} document
+     * @param {string} [id]
+     * @returns {this}
+     */
+    create(collection: string, document: JsonInputObject, id?: string): this;
+    /**
+     * @param {string} collection
+     * @param {string} id
+     * @param {JsonInputObject} document
+     * @param {V1Precondition} [precondition]
+     * @returns {this}
+     */
+    put(collection: string, id: string, document: JsonInputObject, precondition?: V1Precondition): this;
+    /**
+     * @param {string} collection
+     * @param {string} id
+     * @param {V1Patch} patch
+     * @param {{ readonly ifMatch: string }} [precondition]
+     * @returns {this}
+     */
+    patch(collection: string, id: string, patch: V1Patch, precondition?: {
+        readonly ifMatch: string;
+    }): this;
+    /**
+     * @param {string} collection
+     * @param {string} id
+     * @param {{ readonly ifMatch: string }} [precondition]
+     * @returns {this}
+     */
+    delete(collection: string, id: string, precondition?: {
+        readonly ifMatch: string;
+    }): this;
+    /**
+     * Requires the document to exist and match the filter.
+     * @param {string} collection
+     * @param {string} id
+     * @param {V1Filter} filter
+     * @returns {this}
+     */
+    assert(collection: string, id: string, filter: V1Filter): this;
+    /**
+     * Requires the document to be absent or deleted.
+     * @param {string} collection
+     * @param {string} id
+     * @returns {this}
+     */
+    assertAbsent(collection: string, id: string): this;
+    /**
+     * Requires the number of the collection's documents matching `filter` to
+     * satisfy `gte` and/or `lte`. Omit the filter with null to count all documents. It is evaluated inside the commit, before
+     * this transaction's writes, so it is serializable with every other write.
+     * At most 16 per transaction; the result carries the `count`.
+     * @param {string} collection
+     * @param {V1Filter | null} filter
+     * @param {V1CountBounds} bounds
+     * @returns {this}
+     */
+    assertCount(collection: string, filter: V1Filter | null, bounds: V1CountBounds): this;
+    /**
+     * Applies every op atomically. Failures are TerraBaseV1Error values whose
+     * `op` names the failing op index.
+     * @param {V1RequestOptions} [options]
+     * @returns {Promise<V1TransactionResult>}
+     */
+    commit(options?: V1RequestOptions): Promise<V1TransactionResult>;
+    #private;
+}
+/** Collection management on the public client listener. */
+export class V1Collections {
+    /** @param {V1Transport} transport @param {string} database */
+    constructor(transport: V1Transport, database: string);
+    /** @param {string} name @param {V1RequestOptions} [options] @returns {Promise<V1CollectionInfo>} */
+    create(name: string, options?: V1RequestOptions): Promise<V1CollectionInfo>;
+    /** @param {string} name @param {V1RequestOptions} [options] @returns {Promise<V1CollectionInfo>} */
+    get(name: string, options?: V1RequestOptions): Promise<V1CollectionInfo>;
+    /** @param {V1CollectionListOptions} [request] @param {V1RequestOptions} [options] @returns {Promise<V1CollectionPage>} */
+    list(request?: V1CollectionListOptions, options?: V1RequestOptions): Promise<V1CollectionPage>;
+    /** @param {string} name @param {V1RequestOptions} [options] @returns {Promise<V1CollectionInfo>} */
+    drop(name: string, options?: V1RequestOptions): Promise<V1CollectionInfo>;
+    #private;
+}
+/** A database handle by name. It performs no I/O until an operation runs. */
+export class V1Database {
+    /**
+     * @param {V1Transport} transport
+     * @param {string} name
+     */
+    constructor(transport: V1Transport, name: string);
+    /** @type {V1Collections} */
+    collections: V1Collections;
+    /** @type {string} */
+    name: string;
+    /**
+     * @param {string} name
+     * @returns {V1Collection}
+     */
+    collection(name: string): V1Collection;
+    /** @returns {V1Transaction} */
+    transaction(): V1Transaction;
+    #private;
+}
+/**
+ * A TerraBase v1 data-plane client for one project and `tb_` API key. The key is held
+ * privately; it is never serialized, logged or forwarded to redirects.
+ */
+export class TerraBaseV1Client {
+    /** @param {TerraBaseV1ClientConfig} config */
+    constructor(config: TerraBaseV1ClientConfig);
+    /**
+     * @param {string} name
+     * @returns {V1Database}
+     */
+    database(name: string): V1Database;
+    #private;
+}
+export type V1CollectionInfo = {
+    readonly name: string;
+    readonly createdAt: string;
+};
+export type V1CollectionPage = {
+    readonly items: readonly V1CollectionInfo[];
+    readonly nextCursor: string | null;
+};
+export type V1CollectionListOptions = {
+    readonly limit?: number | undefined;
+    readonly cursor?: string | undefined;
+};
+export type V1RequestOptions = {
+    readonly signal?: AbortSignal | undefined;
+};
+export type V1ReadOptions = {
+    /**
+     * A version; an unchanged document fails with `not_modified` (304).
+     */
+    ifNoneMatch?: string | undefined;
+    signal?: AbortSignal | undefined;
+};
+export type V1WriteOptions = {
+    /**
+     * Require the current version, or "*" for a live document.
+     */
+    ifMatch?: string | undefined;
+    /**
+     * Require the document to be absent or deleted (`If-None-Match: *`).
+     */
+    ifNoneMatchAny?: boolean | undefined;
+    signal?: AbortSignal | undefined;
+};
+export type V1CreateOptions = V1WriteOptions;
+export type V1ConditionalWriteOptions = {
+    readonly ifMatch?: string | undefined;
+    readonly signal?: AbortSignal | undefined;
+};
+/**
+ * One operation of an `application/vnd.terrabase.ops+json` patch. Paths are
+ * RFC 6901 JSON Pointers without array indices.
+ */
+export type V1PatchOp = {
+    readonly op: "set";
+    readonly path: string;
+    readonly value: JsonInput;
+} | {
+    readonly op: "unset";
+    readonly path: string;
+} | {
+    readonly op: "inc";
+    readonly path: string;
+    readonly by: number | bigint | ExactDecimal;
+} | {
+    readonly op: "append";
+    readonly path: string;
+    readonly value: JsonInput;
+};
+/**
+ * A patch: an RFC 7396 merge patch (`null` removes members) or 1-256 ops.
+ */
+export type V1Patch = {
+    readonly merge: JsonInputObject;
+} | {
+    readonly ops: readonly V1PatchOp[];
+};
+export type V1SortKey = {
+    readonly path: V1Path;
+    readonly order?: "asc" | "desc" | undefined;
+};
+/**
+ * A query-v1 request. Every member is optional.
+ */
+export type V1Query = {
+    filter?: V1Filter | null | undefined;
+    /**
+     * At most 4 keys; results are finally ordered by `$id`.
+     */
+    sort?: readonly V1SortKey[] | undefined;
+    /**
+     * At most 64 paths.
+     */
+    project?: readonly string[] | undefined;
+    /**
+     * 1-1000 (server default 50).
+     */
+    limit?: number | undefined;
+    /**
+     * A previous page's `nextCursor`.
+     */
+    cursor?: string | null | undefined;
+    /**
+     * Count every match (first page only).
+     */
+    count?: boolean | undefined;
+};
+export type V1Count = {
+    readonly value: string;
+    readonly exact: boolean;
+};
+export type V1QueryPage = {
+    /**
+     * Documents in query order.
+     */
+    items: readonly V1Document[];
+    nextCursor: string | null;
+    count: V1Count | undefined;
+};
+export type V1Precondition = {
+    readonly ifMatch: string;
+} | {
+    readonly ifNoneMatchAny: true;
+};
+/**
+ * One op's result: `id` and `version` for writes, `asserted` for asserts, and
+ * also `count` (decimal u64) for `assertCount`.
+ */
+export type V1TransactionOpResult = {
+    readonly id: string;
+    readonly version: string;
+} | {
+    readonly asserted: true;
+    readonly count?: string;
+};
+export type V1CountBounds = {
+    readonly gte?: number | undefined;
+    readonly lte?: number | undefined;
+};
+export type V1TransactionResult = {
+    offset: string;
+    durability: V1Durability;
+    /**
+     * One per op, in order.
+     */
+    results: readonly V1TransactionOpResult[];
+};
+import type { TerraBaseV1ClientConfig } from "./transport.js";
+import type { V1Document } from "./decode.js";
+import type { JsonInputObject } from "./json.js";
+import type { V1WriteResult } from "./decode.js";
+import type { V1ShapeRequest } from "./shapes.js";
+import type { V1ShapePage } from "./shapes.js";
+import { V1Transport } from "./transport.js";
+import type { V1Filter } from "./filter.js";
+import type { JsonInput } from "./json.js";
+import { ExactDecimal } from "./json.js";
+import type { V1Path } from "./filter.js";
+import type { V1Durability } from "./decode.js";

package/types/v1/transport.d.ts

@@ -0,0 +1,117 @@
+/**
+ * @param {string} raw
+ * @param {string} what
+ * @returns {URL}
+ */
+export function requireServiceUrl(raw: string, what: string): URL;
+/**
+ * An explicitly configured endpoint, with no discovery or hardcoded hosts.
+ * @param {string} baseUrl
+ * @returns {V1EndpointResolver}
+ */
+export function staticBaseUrlResolver(baseUrl: string): V1EndpointResolver;
+/**
+ * @import { FetchLike } from "../config.js"
+ * @import { TerraBaseV1Error } from "./errors.js"
+ * @import { JsonValue } from "./json.js"
+ * @import { V1Operation } from "./routes.js"
+ */
+/** Server request body limit (api-v1.md). */
+export const maximumRequestBytes: number;
+/** A response body that failed in transit after its headers arrived. */
+export class BodyTransportError extends Error {
+    /** @param {unknown} cause */
+    constructor(cause: unknown);
+}
+/** Internal transport bound to one data key. */
+export class V1Transport {
+    /**
+     * @param {Response} response
+     * @param {string} text
+     * @returns {JsonValue | undefined}
+     */
+    static "__#private@#decodeJson"(response: Response, text: string): JsonValue | undefined;
+    /** @param {TerraBaseV1ClientConfig} config */
+    constructor(config: TerraBaseV1ClientConfig);
+    /**
+     * @param {V1Operation} operation
+     * @param {Readonly<Record<string, string>>} params
+     * @param {AbortSignal | undefined} [signal]
+     * @returns {Promise<string>}
+     */
+    url(operation: V1Operation, params: Readonly<Record<string, string>>, signal?: AbortSignal | undefined): Promise<string>;
+    /**
+     * Reads a response body as UTF-8 text within the response byte bound. A
+     * connection failure while reading is a BodyTransportError.
+     * @param {Response} response
+     * @returns {Promise<string>}
+     */
+    readText(response: Response): Promise<string>;
+    /**
+     * Parses a JSON response body exactly.
+     * @param {Response} response
+     * @returns {Promise<JsonValue | undefined>}
+     */
+    readJson(response: Response): Promise<JsonValue | undefined>;
+    /**
+     * Converts a non-success response to a TerraBaseV1Error.
+     * @param {Response} response
+     * @returns {Promise<TerraBaseV1Error>}
+     */
+    error(response: Response): Promise<TerraBaseV1Error>;
+    /**
+     * Calls only a named producer route. Redirects and failed mutations are never replayed.
+     * @param {V1Operation} operation
+     * @param {Readonly<Record<string, string>>} params
+     * @param {V1CallOptions} [options]
+     * @returns {Promise<V1CallResult>}
+     */
+    call(operation: V1Operation, params: Readonly<Record<string, string>>, options?: V1CallOptions): Promise<V1CallResult>;
+    #private;
+}
+/**
+ * Resolver input contains no credential. A successful URL is cached for this client/database.
+ */
+export type V1EndpointContext = {
+    readonly project: string;
+    readonly database: string;
+    readonly signal?: AbortSignal | undefined;
+};
+export type V1EndpointResolver = (context: V1EndpointContext) => string | Promise<string>;
+/**
+ * Project-scoped C# Documents API client. Supply exactly one of baseUrl or endpointResolver.
+ * URLs must use HTTPS or loopback HTTP. Mutations are never automatically replayed.
+ */
+export type TerraBaseV1ClientConfig = {
+    project: string;
+    /**
+     * A tb_ API key; held privately.
+     */
+    token: string;
+    baseUrl?: string | undefined;
+    endpointResolver?: V1EndpointResolver | undefined;
+    fetch?: FetchLike | undefined;
+    /**
+     * Default 64 MiB, including query framing and escaping.
+     */
+    maxResponseBytes?: number | undefined;
+};
+export type V1CallOptions = {
+    body?: string;
+    contentType?: string;
+    /**
+     * Contract headers only (If-Match, If-None-Match).
+     */
+    headers?: Readonly<Record<string, string>>;
+    query?: URLSearchParams | undefined;
+    signal?: AbortSignal | undefined;
+};
+export type V1CallResult = {
+    status: number;
+    headers: Headers;
+    value: JsonValue | undefined;
+};
+import type { V1Operation } from "./routes.js";
+import type { JsonValue } from "./json.js";
+import type { TerraBaseV1Error } from "./errors.js";
+import type { FetchLike } from "../config.js";