@terrascale/sdk 0.0.0-stage → 0.0.2

package/types/schema.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Field IDs must come from the application's reviewed collection binding.
+ *
+ * @param {number} id
+ * @param {string} name
+ * @param {FieldType} type
+ * @param {FieldOptions} [options]
+ * @returns {FieldDef}
+ */
+export function defineField(id: number, name: string, type: FieldType, options?: FieldOptions): FieldDef;
+/**
+ * @param {string} name
+ * @param {CollectionOptions} [options]
+ * @returns {CollectionBuilder}
+ */
+export function collection(name: string, options?: CollectionOptions): CollectionBuilder;
+/**
+ * @param {readonly (CollectionSchema | CollectionBuilder)[]} entries
+ * @returns {SchemaBuilder}
+ */
+export function defineSchema(entries: readonly (CollectionSchema | CollectionBuilder)[]): SchemaBuilder;
+/**
+ * @param {SchemaJson | SchemaBuilder} schema
+ * @returns {string}
+ */
+export function serializeSchema(schema: SchemaJson | SchemaBuilder): string;
+/**
+ * @param {SchemaJson} schema
+ * @returns {SchemaJson}
+ */
+export function normalizeSchema(schema: SchemaJson): SchemaJson;
+/**
+ * @param {SchemaJson} schema
+ * @returns {void}
+ */
+export function validateSchema(schema: SchemaJson): void;
+/**
+ * @param {CollectionSchema} schema
+ * @returns {void}
+ */
+export function validateCollection(schema: CollectionSchema): void;
+/**
+ * Validate native values using the accepted codec; never coerce integers or bytes.
+ *
+ * @param {CollectionSchema} schema
+ * @param {Readonly<Record<string, DatabaseValue>>} record
+ * @returns {readonly DatabaseField[]}
+ */
+export function encodeSchemaFields(schema: CollectionSchema, record: Readonly<Record<string, DatabaseValue>>): readonly DatabaseField[];
+/** @import { DatabaseField, DatabaseValue } from "./database-types.js" */
+/** Pure local declarations. These are not server catalog or migration requests. */
+export const FieldTypes: Readonly<{
+    readonly bool: "bool";
+    readonly i64: "i64";
+    readonly utf8: "utf8";
+    readonly bytes: "bytes";
+    readonly map: "map";
+    readonly array: "array";
+}>;
+export class SchemaValidationError extends Error {
+    /**
+     * @param {string} message
+     */
+    constructor(message: string);
+}
+/** Persistent fluent builder; each branch keeps its own declarations. */
+export class CollectionBuilder {
+    /**
+     * @param {string} name
+     * @param {CollectionOptions} [options]
+     */
+    constructor(name: string, options?: CollectionOptions);
+    /**
+     * @param {number} id
+     * @param {string} name
+     * @param {FieldType} type
+     * @param {FieldOptions} [options]
+     * @returns {CollectionBuilder}
+     */
+    field(id: number, name: string, type: FieldType, options?: FieldOptions): CollectionBuilder;
+    /**
+     * @returns {CollectionSchema}
+     */
+    build(): CollectionSchema;
+    /**
+     * @returns {string}
+     */
+    toJSON(): string;
+    #private;
+}
+export class SchemaBuilder {
+    /**
+     * @param {readonly (CollectionSchema | CollectionBuilder)[]} [entries]
+     */
+    constructor(entries?: readonly (CollectionSchema | CollectionBuilder)[]);
+    /**
+     * @param {CollectionSchema | CollectionBuilder} entry
+     * @returns {SchemaBuilder}
+     */
+    addCollection(entry: CollectionSchema | CollectionBuilder): SchemaBuilder;
+    /**
+     * @param {string} name
+     * @param {CollectionOptions} [options]
+     * @returns {SchemaBuilder}
+     */
+    collection(name: string, options?: CollectionOptions): SchemaBuilder;
+    /**
+     * @returns {SchemaJson}
+     */
+    build(): SchemaJson;
+    /**
+     * @returns {void}
+     */
+    validate(): void;
+    /**
+     * @returns {string}
+     */
+    toJSON(): string;
+    #private;
+}
+export type FieldType = (typeof FieldTypes)[keyof typeof FieldTypes];
+export type FieldOptions = {
+    readonly required?: boolean;
+};
+/**
+ * `required` refers to field presence; explicit native null remains distinct.
+ */
+export type FieldDef = {
+    readonly id: number;
+    readonly name: string;
+    readonly type: FieldType;
+    readonly required: boolean;
+};
+export type CollectionSchema = {
+    readonly name: string;
+    readonly fields: readonly FieldDef[];
+};
+export type SchemaJson = {
+    readonly collections: readonly CollectionSchema[];
+};
+export type CollectionOptions = {
+    readonly fields?: readonly FieldDef[];
+};
+import type { DatabaseValue } from "./database-types.js";
+import type { DatabaseField } from "./database-types.js";

package/types/sql.d.ts

@@ -0,0 +1,288 @@
+/**
+ * @template {SqlCollectionSchema} S
+ * @overload
+ * @param {S} schema
+ * @returns {SelectBuilder<S>}
+ */
+export function select<S extends SqlCollectionSchema>(schema: S): SelectBuilder<S>;
+/**
+ * @overload
+ * @param {readonly string[]} [columns]
+ * @returns {SelectBuilder}
+ */
+export function select(columns?: readonly string[] | undefined): SelectBuilder;
+/**
+ * @template {SqlCollectionSchema} S
+ * @param {S} schema
+ * @returns {SelectBuilder<S>}
+ */
+export function selectSchema<S extends SqlCollectionSchema>(schema: S): SelectBuilder<S>;
+/**
+ * @param {string} sql
+ * @param {readonly SqlParameter[]} [parameters]
+ * @returns {Query}
+ */
+export function raw(sql: string, parameters?: readonly SqlParameter[]): Query;
+/**
+ * Validate the client-side read-only SQL allow-list and positional bindings.
+ *
+ * @param {string} sql
+ * @param {readonly SqlParameter[]} [parameters]
+ * @returns {void}
+ */
+export function validateSql(sql: string, parameters?: readonly SqlParameter[]): void;
+export type Direction = (typeof Direction)[keyof typeof Direction];
+/** @import { CollectionSchema, FieldDef, FieldType } from "./schema.js" */
+/**
+ * @typedef {Pick<FieldDef, "name" | "type"> &
+ *   Partial<Omit<FieldDef, "name" | "type">>} SqlFieldDef
+ */
+/**
+ * @typedef {{
+ *   readonly name: string;
+ *   readonly fields: readonly SqlFieldDef[];
+ * } & Partial<Omit<CollectionSchema, "name" | "fields">>} SqlCollectionSchema
+ */
+/**
+ * @template {SqlCollectionSchema} S
+ * @typedef {S["fields"][number]} SchemaField
+ */
+/**
+ * @template {SqlCollectionSchema} S
+ * @typedef {SchemaField<S>} QueryField
+ */
+export const Direction: Readonly<{
+    readonly Asc: "ASC";
+    readonly Desc: "DESC";
+}>;
+/** @typedef {(typeof Direction)[keyof typeof Direction]} Direction */
+/** @typedef {boolean | bigint | number | string | Uint8Array | null} SqlScalar */
+/** @typedef {SqlScalar} SqlParameter */
+export class SqlValidationError extends Error {
+    /**
+     * @param {string} message
+     */
+    constructor(message: string);
+    /**
+     * @override
+     * @readonly
+     */
+    override readonly name: "SqlValidationError";
+    /** @readonly */
+    readonly code: "invalid_sql";
+}
+/** A validated, parameterized read-only SQL statement. */
+export class Query {
+    /**
+     * @param {string} sql
+     * @param {readonly SqlParameter[]} [parameters]
+     * @returns {Query}
+     */
+    static raw(sql: string, parameters?: readonly SqlParameter[]): Query;
+    /**
+     * @param {readonly string[]} [columns]
+     * @returns {SelectBuilder}
+     */
+    static select(columns?: readonly string[]): SelectBuilder;
+    /**
+     * @template {SqlCollectionSchema} S
+     * @param {S} schema
+     * @returns {SelectBuilder<S>}
+     */
+    static selectSchema<S extends SqlCollectionSchema>(schema: S): SelectBuilder<S>;
+    /**
+     * @private
+     * @param {string} sql
+     * @param {readonly SqlParameter[]} parameters
+     */
+    private constructor();
+    /**
+     * @readonly
+     * @type {string}
+     */
+    readonly statement: string;
+    /**
+     * @returns {readonly SqlParameter[]}
+     */
+    get parameters(): readonly SqlParameter[];
+    /**
+     * @returns {QueryDescriptor}
+     */
+    toDescriptor(): QueryDescriptor;
+    #private;
+}
+/**
+ * Schema-bound SELECT builder.
+ *
+ * @template {SqlCollectionSchema} [S=SqlCollectionSchema]
+ */
+export class SelectBuilder<S extends SqlCollectionSchema = SqlCollectionSchema> {
+    /**
+     * @param {readonly string[]} columns
+     * @returns {SelectBuilder}
+     */
+    static fromColumns(columns: readonly string[]): SelectBuilder;
+    /**
+     * @template {SqlCollectionSchema} T
+     * @param {T} schema
+     * @returns {SelectBuilder<T>}
+     */
+    static fromSchema<T extends SqlCollectionSchema>(schema: T): SelectBuilder<T>;
+    /**
+     * @private
+     * @param {{
+     *   columns: readonly string[];
+     *   from?: string | undefined;
+     *   schema?: S | undefined;
+     *   predicates?: readonly string[];
+     *   order?: readonly (readonly [string, Direction])[];
+     *   limit?: number | undefined;
+     *   offset?: number | undefined;
+     *   parameters?: readonly SqlParameter[];
+     *   schemaBound?: boolean;
+     * }} input
+     */
+    private constructor();
+    /**
+     * @param {QueryField<S>} field
+     * @returns {SelectBuilder<S>}
+     */
+    column(field: QueryField<S>): SelectBuilder<S>;
+    /**
+     * @param {readonly QueryField<S>[]} fields
+     * @returns {SelectBuilder<S>}
+     */
+    columns(fields: readonly QueryField<S>[]): SelectBuilder<S>;
+    /**
+     * @param {string} collection
+     * @returns {SelectBuilder<S>}
+     */
+    from(collection: string): SelectBuilder<S>;
+    /**
+     * @template {SqlParameter} T
+     * @param {QueryField<S>} field
+     * @param {T} value
+     * @returns {SelectBuilder<S>}
+     */
+    whereEq<T extends SqlParameter>(field: QueryField<S>, value: T): SelectBuilder<S>;
+    /**
+     * @template {SqlParameter} T
+     * @param {QueryField<S>} field
+     * @param {T} value
+     * @returns {SelectBuilder<S>}
+     */
+    whereNe<T extends SqlParameter>(field: QueryField<S>, value: T): SelectBuilder<S>;
+    /**
+     * @template {SqlParameter} T
+     * @param {QueryField<S>} field
+     * @param {T} value
+     * @returns {SelectBuilder<S>}
+     */
+    whereGt<T extends SqlParameter>(field: QueryField<S>, value: T): SelectBuilder<S>;
+    /**
+     * @template {SqlParameter} T
+     * @param {QueryField<S>} field
+     * @param {T} value
+     * @returns {SelectBuilder<S>}
+     */
+    whereGte<T extends SqlParameter>(field: QueryField<S>, value: T): SelectBuilder<S>;
+    /**
+     * @template {SqlParameter} T
+     * @param {QueryField<S>} field
+     * @param {T} value
+     * @returns {SelectBuilder<S>}
+     */
+    whereLt<T extends SqlParameter>(field: QueryField<S>, value: T): SelectBuilder<S>;
+    /**
+     * @template {SqlParameter} T
+     * @param {QueryField<S>} field
+     * @param {T} value
+     * @returns {SelectBuilder<S>}
+     */
+    whereLte<T extends SqlParameter>(field: QueryField<S>, value: T): SelectBuilder<S>;
+    /**
+     * @template {SqlParameter} T
+     * @param {QueryField<S>} field
+     * @param {T} value
+     * @returns {SelectBuilder<S>}
+     */
+    whereLike<T extends SqlParameter>(field: QueryField<S>, value: T): SelectBuilder<S>;
+    /**
+     * @template {SqlParameter} T
+     * @param {QueryField<S>} field
+     * @param {readonly T[]} values
+     * @returns {SelectBuilder<S>}
+     */
+    whereIn<T extends SqlParameter>(field: QueryField<S>, values: readonly T[]): SelectBuilder<S>;
+    /**
+     * @param {SchemaField<S>} field
+     * @param {Direction} [direction]
+     * @returns {SelectBuilder<S>}
+     */
+    orderByField(field: SchemaField<S>, direction?: Direction): SelectBuilder<S>;
+    /**
+     * @param {string} column
+     * @param {Direction} [direction]
+     * @returns {SelectBuilder<S>}
+     */
+    orderBy(column: string, direction?: Direction): SelectBuilder<S>;
+    /**
+     * @param {number} value
+     * @returns {SelectBuilder<S>}
+     */
+    limit(value: number): SelectBuilder<S>;
+    /**
+     * @param {number} value
+     * @returns {SelectBuilder<S>}
+     */
+    offset(value: number): SelectBuilder<S>;
+    /**
+     * @param {{
+     *   readonly limit: number;
+     *   readonly offset?: number | undefined;
+     * }} options
+     * @returns {SelectBuilder<S>}
+     */
+    paginate(options: {
+        readonly limit: number;
+        readonly offset?: number | undefined;
+    }): SelectBuilder<S>;
+    /**
+     * @param {number} page
+     * @param {number} pageSize
+     * @returns {SelectBuilder<S>}
+     */
+    page(page: number, pageSize: number): SelectBuilder<S>;
+    /**
+     * @returns {Query}
+     */
+    build(): Query;
+    /**
+     * @returns {QueryDescriptor}
+     */
+    toDescriptor(): QueryDescriptor;
+    #private;
+}
+/**
+ * Validate the client-side read-only SQL allow-list and positional bindings.
+ *
+ * @param {string} sql
+ * @param {readonly SqlParameter[]} [parameters]
+ * @returns {void}
+ */
+export function validate_sql(sql: string, parameters?: readonly SqlParameter[]): void;
+export type QueryDescriptor = {
+    readonly statement: string;
+    readonly parameters: readonly SqlParameter[];
+};
+export type SqlFieldDef = Pick<FieldDef, "name" | "type"> & Partial<Omit<FieldDef, "name" | "type">>;
+export type SqlCollectionSchema = {
+    readonly name: string;
+    readonly fields: readonly SqlFieldDef[];
+} & Partial<Omit<CollectionSchema, "name" | "fields">>;
+export type SchemaField<S extends SqlCollectionSchema> = S["fields"][number];
+export type QueryField<S extends SqlCollectionSchema> = SchemaField<S>;
+export type SqlScalar = boolean | bigint | number | string | Uint8Array | null;
+export type SqlParameter = SqlScalar;
+import type { FieldDef } from "./schema.js";
+import type { CollectionSchema } from "./schema.js";

package/types/svelte/index.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The Svelte store contract; `$store` auto-subscription binds to it directly.
+ *
+ * @typedef {() => void} SvelteUnsubscriber
+ */
+/**
+ * @template TValue
+ * @typedef {(value: TValue) => void} SvelteSubscriber
+ */
+/**
+ * @template TValue
+ * @typedef {{
+ *   readonly subscribe: (run: SvelteSubscriber<TValue>) => SvelteUnsubscriber;
+ * }} SvelteReadable
+ */
+/**
+ * A query store; `refetch` restarts delivery from a fresh generation, like
+ * the React `refetch`.
+ *
+ * @template TValue
+ * @typedef {SvelteReadable<ReactiveQueryState<TValue>> & {
+ *   readonly refetch: () => void;
+ * }} SvelteQuery
+ */
+/**
+ * One reactive query as a Svelte store. The observer lifecycle follows the
+ * store subscription count, so `$query` in a component starts delivery on
+ * mount and disposes the transport on unmount. Keep the source object stable
+ * between renders.
+ *
+ * @template TValue
+ * @param {ReactiveQuerySource<TValue>} source
+ * @param {ReactiveQueryOptions<TValue>} [options]
+ * @returns {SvelteQuery<TValue>}
+ */
+export function createQuery<TValue>(source: ReactiveQuerySource<TValue>, options?: ReactiveQueryOptions<TValue>): SvelteQuery<TValue>;
+/**
+ * @template TValue, TVariables
+ * @typedef {SvelteReadable<ReactiveMutationState<TValue>> & {
+ *   readonly mutate: (variables: TVariables) => void;
+ *   readonly mutateAsync: (variables: TVariables) => Promise<TValue>;
+ *   readonly cancel: () => void;
+ *   readonly reset: () => void;
+ * }} SvelteMutation
+ */
+/**
+ * A durable mutation as a Svelte store; `$mutation.isPending` drives the UI.
+ *
+ * @template TValue
+ * @template [TVariables=void]
+ * @param {ReactiveMutationOptions<TValue, TVariables>} options
+ * @returns {SvelteMutation<TValue, TVariables>}
+ */
+export function createMutation<TValue, TVariables = void>(options: ReactiveMutationOptions<TValue, TVariables>): SvelteMutation<TValue, TVariables>;
+export * from "../react/core.js";
+/**
+ * The Svelte store contract; `$store` auto-subscription binds to it directly.
+ */
+export type SvelteUnsubscriber = () => void;
+export type SvelteSubscriber<TValue> = (value: TValue) => void;
+export type SvelteReadable<TValue> = {
+    readonly subscribe: (run: SvelteSubscriber<TValue>) => SvelteUnsubscriber;
+};
+/**
+ * A query store; `refetch` restarts delivery from a fresh generation, like
+ * the React `refetch`.
+ */
+export type SvelteQuery<TValue> = SvelteReadable<ReactiveQueryState<TValue>> & {
+    readonly refetch: () => void;
+};
+export type SvelteMutation<TValue, TVariables> = SvelteReadable<ReactiveMutationState<TValue>> & {
+    readonly mutate: (variables: TVariables) => void;
+    readonly mutateAsync: (variables: TVariables) => Promise<TValue>;
+    readonly cancel: () => void;
+    readonly reset: () => void;
+};
+import type { ReactiveQuerySource } from "../react/core.js";
+import type { ReactiveQueryOptions } from "../react/core.js";
+import type { ReactiveMutationOptions } from "../react/core.js";
+import type { ReactiveQueryState } from "../react/core.js";
+import type { ReactiveMutationState } from "../react/core.js";

package/types/tanstack/index.d.ts

@@ -0,0 +1,166 @@
+/**
+ * @deprecated Retired SQLite/Rust adapter; no C# shape adapter is provided.
+ * Options for `createCollection(terrascaleCollectionOptions(...))`.
+ *
+ * @template {object} T
+ * @template {string | number} [TKey=string]
+ * @param {TerraScaleTanStackAdapterOptions<T, TKey>} options
+ * @returns {TerraScaleTanStackCollectionOptions<T, TKey> & { readonly adapter: TerraScaleTanStackCollectionSync<T, TKey> }}
+ */
+export function terrascaleCollectionOptions<T extends object, TKey extends string | number = string>(options: TerraScaleTanStackAdapterOptions<T, TKey>): TerraScaleTanStackCollectionOptions<T, TKey> & {
+    readonly adapter: TerraScaleTanStackCollectionSync<T, TKey>;
+};
+/**
+ * Every complete native cut owns its mapped values until collection acknowledgment.
+ *
+ * @template {object} T
+ * @template {string | number} [TKey=string]
+ */
+export class TerraScaleTanStackCollectionPublisher<T extends object, TKey extends string | number = string> {
+    /**
+     * @param {TerraScaleTanStackSyncParams<T, TKey>} params
+     * @param {(row: DatabaseQueryRow) => T} mapRow
+     * @param {(item: T) => TKey} getKey
+     */
+    constructor(params: TerraScaleTanStackSyncParams<T, TKey>, mapRow: (row: DatabaseQueryRow) => T, getKey: (item: T) => TKey);
+    /** @returns {DatabaseViewPosition | undefined} */
+    getPosition(): DatabaseViewPosition | undefined;
+    /** @returns {void} */
+    reset(): void;
+    /** @returns {void} */
+    dispose(): void;
+    /**
+     * @param {DatabaseViewSnapshot} snapshot
+     * @param {AbortSignal} [externalSignal]
+     * @returns {Promise<void>}
+     */
+    publish(snapshot: DatabaseViewSnapshot, externalSignal?: AbortSignal): Promise<void>;
+    #private;
+}
+export class TerraScaleTanStackMutationError extends Error {
+    /**
+     * @param {Extract<DatabaseResult<DatabaseCommitReceipt>, { readonly ok: false }>["error"]} detail
+     */
+    constructor(detail: Extract<DatabaseResult<DatabaseCommitReceipt>, {
+        readonly ok: false;
+    }>["error"]);
+    /** @override @readonly */
+    override readonly name: "TerraScaleTanStackMutationError";
+    /** @readonly @type {Extract<DatabaseResult<DatabaseCommitReceipt>, { readonly ok: false }>["error"]} */
+    readonly detail: Extract<DatabaseResult<DatabaseCommitReceipt>, {
+        readonly ok: false;
+    }>["error"];
+    /** @returns {string} */
+    get code(): string;
+}
+/**
+ * Native HTTP snapshot/poll collection adapter. All durable writes reach the server.
+ *
+ * @template {object} T
+ * @template {string | number} [TKey=string]
+ */
+export class TerraScaleTanStackCollectionSync<T extends object, TKey extends string | number = string> {
+    /**
+     * @param {TerraScaleTanStackAdapterOptions<T, TKey>} options
+     */
+    constructor(options: TerraScaleTanStackAdapterOptions<T, TKey>);
+    /** @returns {TerraScaleTanStackCollectionOptions<T, TKey>} */
+    get options(): TerraScaleTanStackCollectionOptions<T, TKey>;
+    /** @returns {string | undefined} */
+    getCheckpoint(): string | undefined;
+    /**
+     * Reconnect correctness starts with a fresh, complete authorized snapshot.
+     *
+     * @returns {void}
+     */
+    resubscribe(): void;
+    /** @returns {void} */
+    dispose(): void;
+    #private;
+}
+/**
+ * Structural TanStack DB callbacks keep this optional integration dependency free.
+ */
+export type TerraScaleTanStackChange<T extends object, TKey extends string | number> = {
+    readonly type: "insert" | "update";
+    readonly value: T;
+} | {
+    readonly type: "delete";
+    readonly key: TKey;
+};
+export type TerraScaleTanStackSyncParams<T extends object, TKey extends string | number> = {
+    readonly collection: unknown;
+    readonly begin: (options?: {
+        readonly immediate?: boolean;
+    }) => void;
+    readonly write: (message: TerraScaleTanStackChange<T, TKey>) => void;
+    readonly commit: (signal?: AbortSignal) => true | Promise<void>;
+    readonly markReady: () => void;
+    readonly markError: (error?: unknown) => void;
+    readonly truncate: () => void;
+};
+export type TerraScaleTanStackMutation<T extends object = Record<string, unknown>> = {
+    readonly mutationId?: string;
+    readonly key: string | number;
+    readonly original?: Partial<T>;
+    readonly modified: T;
+    readonly changes?: Partial<T>;
+    readonly type: "insert" | "update" | "delete";
+    readonly metadata?: unknown;
+};
+export type TerraScaleTanStackTransaction<T extends object = Record<string, unknown>> = {
+    readonly id?: string;
+    readonly mutations: readonly TerraScaleTanStackMutation<T>[];
+    readonly metadata?: Record<string, unknown>;
+};
+export type TerraScaleTanStackMutationRequest<T extends object, TKey extends string | number> = {
+    readonly operation: "insert" | "update" | "delete";
+    readonly idempotencyKey: string;
+    readonly transactionId: string;
+    readonly transaction: TerraScaleTanStackTransaction<T>;
+    readonly scope: DatabaseScope;
+    readonly collection: string;
+    readonly signal: AbortSignal;
+    readonly keyOf: (item: T) => TKey;
+};
+export type TerraScaleTanStackCollectionOptions<T extends object, TKey extends string | number = string> = {
+    readonly id?: string;
+    readonly getKey: (item: T) => TKey;
+    readonly sync: {
+        readonly rowUpdateMode: "full";
+        readonly sync: (params: TerraScaleTanStackSyncParams<T, TKey>) => () => void;
+    };
+    readonly onInsert: (params: {
+        readonly transaction: TerraScaleTanStackTransaction<T>;
+    }) => Promise<DatabaseCommitReceipt>;
+    readonly onUpdate: (params: {
+        readonly transaction: TerraScaleTanStackTransaction<T>;
+    }) => Promise<DatabaseCommitReceipt>;
+    readonly onDelete: (params: {
+        readonly transaction: TerraScaleTanStackTransaction<T>;
+    }) => Promise<DatabaseCommitReceipt>;
+};
+/**
+ * `mapRow` maps the complete native point explicitly; conflicts are never
+ * flattened. `prepareMutation` prepares through this same client. The adapter
+ * sends the resulting commit to the server once; TanStack owns its reversible
+ * optimistic presentation.
+ */
+export type TerraScaleTanStackAdapterOptions<T extends object, TKey extends string | number = string> = DatabaseQueryOptions & {
+    readonly client: TerraBaseClient;
+    readonly mapRow: (row: DatabaseQueryRow) => T;
+    readonly getKey: (item: T) => TKey;
+    readonly id?: string;
+    readonly prepareMutation?: (request: TerraScaleTanStackMutationRequest<T, TKey>) => Promise<PreparedDatabaseCommit>;
+    readonly idempotencyKey?: (transaction: TerraScaleTanStackTransaction<T>) => string;
+    readonly signal?: AbortSignal;
+};
+import type { DatabaseViewPosition } from "../database-view.js";
+import type { DatabaseViewSnapshot } from "../database-view.js";
+import type { DatabaseQueryRow } from "../database-types.js";
+import type { DatabaseCommitReceipt } from "../database-types.js";
+import type { DatabaseResult } from "../database-types.js";
+import type { DatabaseScope } from "../database-types.js";
+import type { DatabaseQueryOptions } from "../database-view.js";
+import type { TerraBaseClient } from "../local/legacy-client.js";
+import type { PreparedDatabaseCommit } from "../local/legacy-client.js";

package/types/ts-auth-discovery.d.ts

@@ -0,0 +1,19 @@
+/**
+ * ts-auth issues from its regional host, https://<region>.auth.terrascale.tech.
+ * Behind the Atlas proxy that issuer's region is called directly: Atlas could
+ * rank another region, which is another issuer.
+ * @param {string} issuer
+ * @returns {string | undefined}
+ */
+export function regionalIssuerOrigin(issuer: string): string | undefined;
+/** The public auth routing document, validated before any credentials are sent. */
+export class TsAuthEndpointDiscovery {
+    /** @param {typeof globalThis.fetch} fetchHandler */
+    constructor(fetchHandler: typeof globalThis.fetch);
+    /**
+     * @param {AbortSignal} [signal]
+     * @returns {Promise<readonly string[]>}
+     */
+    endpoints(signal?: AbortSignal): Promise<readonly string[]>;
+    #private;
+}