terrascale 0.3.0

package/types/tanstack/index.d.ts

@@ -0,0 +1,165 @@
+/**
+ * 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 "../database.js";
+import type { PreparedDatabaseCommit } from "../database.js";

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

@@ -0,0 +1,11 @@
+/** 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;
+}