@terrascale/sdk 0.0.0-stage → 0.0.2

package/types/react/core.d.ts

@@ -0,0 +1,366 @@
+/**
+ * @template TValue
+ * @typedef {{ readonly kind: "snapshot" | "data"; readonly value: TValue }
+ *   | { readonly kind: "reset"; readonly reset: ReactiveReset<TValue> }
+ *   | { readonly kind: "error"; readonly error: unknown }} ReactiveHttpEvent
+ */
+/**
+ * Typed boundary for the owning HTTP contract. Implementations perform the
+ * documented request and polling protocol; this adapter only maps events to
+ * the hook's observer and propagates AbortSignal.
+ *
+ * @template TRequest, TValue
+ * @typedef {{
+ *   readonly subscribe: (
+ *     request: TRequest,
+ *     observer: { readonly event: (event: ReactiveHttpEvent<TValue>) => void },
+ *     context: ReactiveSubscriptionContext,
+ *   ) => ReactiveDisposer | void | Promise<ReactiveDisposer | void>;
+ * }} ReactiveHttpTransport
+ */
+/**
+ * @template TRequest, TValue
+ * @param {ReactiveHttpTransport<TRequest, TValue>} transport
+ * @param {TRequest} request
+ * @param {string | readonly unknown[]} [key]
+ * @returns {ReactiveQuerySource<TValue>}
+ */
+export function createReactiveHttpQuery<TRequest, TValue>(transport: ReactiveHttpTransport<TRequest, TValue>, request: TRequest, key?: string | readonly unknown[]): ReactiveQuerySource<TValue>;
+/** @typedef {import("../database-view.js").DatabaseQueryCallbacks} DatabaseQueryCallbacks */
+/** @typedef {import("../database-view.js").DatabaseQueryOptions} DatabaseQueryOptions */
+/** @typedef {import("../database-view.js").DatabaseQuerySource} DatabaseQuerySource */
+/** @typedef {import("../database-view.js").DatabaseViewBinding} DatabaseViewBinding */
+/** @typedef {import("../database-view.js").DatabaseViewPosition} DatabaseViewPosition */
+/** @typedef {import("../database-view.js").DatabaseViewSnapshot} DatabaseViewSnapshot */
+/**
+ * A subscription cleanup returned by a typed reactive transport.
+ *
+ * @typedef {(() => void) | { readonly dispose: () => void } | { readonly unsubscribe: () => void }} ReactiveDisposer
+ */
+/**
+ * @typedef {{
+ *   readonly signal: AbortSignal;
+ * }} ReactiveSubscriptionContext
+ */
+/**
+ * @template TValue
+ * @typedef {{
+ *   readonly next: (value: TValue) => void;
+ *   readonly error: (error: unknown) => void;
+ *   readonly reset: (reset: ReactiveReset<TValue>) => void;
+ * }} ReactiveQueryCallbacks
+ */
+/**
+ * The operation owned by the public reactive contract. It may use HTTP
+ * long-polling or WebSocket delivery; the hook does not know or care which.
+ *
+ * @template TValue
+ * @typedef {{
+ *   readonly key?: string | readonly unknown[];
+ *   readonly subscribe: (
+ *     observer: ReactiveQueryCallbacks<TValue>,
+ *     context: ReactiveSubscriptionContext,
+ *   ) => ReactiveDisposer | void | Promise<ReactiveDisposer | void>;
+ * }} ReactiveQuerySource
+ */
+/**
+ * @typedef {"checkpoint-expired"
+ *   | "retention-advanced"
+ *   | "generation-changed"
+ *   | "checkpoint-not-current"
+ *   | "view-diverged"
+ *   | "oversized"
+ *   | "invalid-operations"
+ *   | "invalid-checkpoint"
+ *   | "backpressure"
+ *   | (string & {})} ReactiveResetReason
+ */
+/**
+ * A server-authorized reset. The checkpoint remains opaque to the hook.
+ *
+ * @template TValue
+ * @typedef {{
+ *   readonly reason: ReactiveResetReason;
+ *   readonly data?: TValue;
+ *   readonly checkpoint?: string | Uint8Array;
+ *   readonly code?: string;
+ *   readonly message?: string;
+ * }} ReactiveReset
+ */
+/** @typedef {"subscription" | "transport" | "remote" | "cancelled" | "mutation"} ReactiveErrorKind */
+/**
+ * @typedef {{
+ *   readonly kind: ReactiveErrorKind;
+ *   readonly code: string;
+ *   readonly message: string;
+ *   readonly cause?: unknown;
+ *   readonly terraScale?: TerraScaleError;
+ *   readonly database?: Extract<DatabaseResult<never>, { readonly ok: false }>["error"];
+ * }} ReactiveError
+ */
+/** @typedef {"pending" | "success" | "error" | "reset"} ReactiveQueryStatus */
+/**
+ * @template TValue
+ * @typedef {{
+ *   readonly status: ReactiveQueryStatus;
+ *   readonly data: TValue | undefined;
+ *   readonly error: ReactiveError | undefined;
+ *   readonly reset: ReactiveReset<TValue> | undefined;
+ *   readonly isLoading: boolean;
+ *   readonly isFetching: boolean;
+ *   readonly isStale: boolean;
+ * }} ReactiveQueryState
+ */
+/**
+ * @template TValue
+ * @typedef {{
+ *   readonly enabled?: boolean;
+ *   readonly initialData?: TValue;
+ * }} ReactiveQueryOptions
+ */
+/**
+ * Framework-neutral query observer used by useQuery and SSR-safe tests.
+ *
+ * @template TValue
+ */
+export class ReactiveQueryObserver<TValue> {
+    /**
+     * @param {ReactiveQuerySource<TValue>} source
+     * @param {ReactiveQueryOptions<TValue>} [options]
+     */
+    constructor(source: ReactiveQuerySource<TValue>, options?: ReactiveQueryOptions<TValue>);
+    /** @returns {ReactiveQueryState<TValue>} */
+    getSnapshot: () => ReactiveQueryState<TValue>;
+    /** @returns {ReactiveQueryState<TValue>} */
+    getServerSnapshot: () => ReactiveQueryState<TValue>;
+    /**
+     * Updates the small, hook-facing option set without replacing the external
+     * store. React may render a hook with a new options object while preserving
+     * the observer; an `enabled` transition must therefore start/stop delivery
+     * at the subscription boundary instead of leaving a stale subscription.
+     *
+     * @param {ReactiveQueryOptions<TValue>} [options]
+     * @returns {void}
+     */
+    updateOptions(options?: ReactiveQueryOptions<TValue>): void;
+    /**
+     * @param {() => void} listener
+     * @returns {() => void}
+     */
+    subscribe: (listener: () => void) => () => void;
+    /** @returns {void} */
+    start(): void;
+    /**
+     * Aborts HTTP polling and disposes the current transport subscription.
+     *
+     * @returns {void}
+     */
+    dispose(): void;
+    /**
+     * Restart only while an enabled query has live observers.
+     *
+     * @returns {void}
+     */
+    refetch(): void;
+    #private;
+}
+/**
+ * @typedef {{
+ *   readonly signal: AbortSignal;
+ *   readonly idempotencyKey: string;
+ * }} ReactiveMutationContext
+ */
+/** @typedef {void | (() => void) | { readonly rollback: () => void }} OptimisticRollback */
+/**
+ * @template TValue, TVariables
+ * @typedef {{
+ *   readonly mutationFn: (
+ *     variables: TVariables,
+ *     context: ReactiveMutationContext,
+ *   ) => Promise<TValue | TerraScaleResult<TValue> | DatabaseResult<TValue>>;
+ *   readonly idempotencyKey?: string | ((variables: TVariables) => string);
+ *   readonly onMutate?: (variables: TVariables, context: ReactiveMutationContext) => OptimisticRollback | Promise<OptimisticRollback>;
+ * }} ReactiveMutationOptions
+ */
+/** @typedef {"idle" | "pending" | "success" | "error" | "cancelled"} ReactiveMutationStatus */
+/**
+ * @template TValue
+ * @typedef {{
+ *   readonly status: ReactiveMutationStatus;
+ *   readonly data: TValue | undefined;
+ *   readonly error: ReactiveError | undefined;
+ *   readonly idempotencyKey: string | undefined;
+ *   readonly isPending: boolean;
+ * }} ReactiveMutationState
+ */
+/**
+ * @template TValue, TVariables
+ */
+export class ReactiveMutationObserver<TValue, TVariables> {
+    /**
+     * @param {ReactiveMutationOptions<TValue, TVariables>} options
+     */
+    constructor(options: ReactiveMutationOptions<TValue, TVariables>);
+    /**
+     * Keep callbacks current when a component re-renders without replacing the
+     * observer (the normal `useMutation` lifecycle). A mutation already running
+     * captures the callbacks it started with, so a render cannot redirect an
+     * in-flight durable request.
+     *
+     * @param {ReactiveMutationOptions<TValue, TVariables>} options
+     * @returns {void}
+     */
+    updateOptions(options: ReactiveMutationOptions<TValue, TVariables>): void;
+    /** @returns {ReactiveMutationState<TValue>} */
+    getSnapshot: () => ReactiveMutationState<TValue>;
+    /**
+     * @param {() => void} listener
+     * @returns {() => void}
+     */
+    subscribe: (listener: () => void) => () => void;
+    /**
+     * @param {TVariables} variables
+     * @returns {Promise<TValue>}
+     */
+    mutateAsync(variables: TVariables): Promise<TValue>;
+    /**
+     * @param {TVariables} variables
+     * @returns {void}
+     */
+    mutate(variables: TVariables): void;
+    /**
+     * Cancels the durable request and immediately rolls back its presentation.
+     *
+     * @returns {void}
+     */
+    cancel(): void;
+    /** @returns {void} */
+    reset(): void;
+    /** @returns {void} */
+    dispose(): void;
+    #private;
+}
+export class ReactiveMutationError extends Error {
+    /**
+     * @param {string} code
+     * @param {string} message
+     * @param {unknown} [cause]
+     */
+    constructor(code: string, message: string, cause?: unknown);
+    /** @override @readonly */
+    override readonly name: "ReactiveMutationError";
+    /** @readonly @type {string} */
+    readonly code: string;
+    /** @override @readonly @type {unknown} */
+    override readonly cause: unknown;
+}
+export type ReactiveHttpEvent<TValue> = {
+    readonly kind: "snapshot" | "data";
+    readonly value: TValue;
+} | {
+    readonly kind: "reset";
+    readonly reset: ReactiveReset<TValue>;
+} | {
+    readonly kind: "error";
+    readonly error: unknown;
+};
+/**
+ * Typed boundary for the owning HTTP contract. Implementations perform the
+ * documented request and polling protocol; this adapter only maps events to
+ * the hook's observer and propagates AbortSignal.
+ */
+export type ReactiveHttpTransport<TRequest, TValue> = {
+    readonly subscribe: (request: TRequest, observer: {
+        readonly event: (event: ReactiveHttpEvent<TValue>) => void;
+    }, context: ReactiveSubscriptionContext) => ReactiveDisposer | void | Promise<ReactiveDisposer | void>;
+};
+export type DatabaseQueryCallbacks = import("../database-view.js").DatabaseQueryCallbacks;
+export type DatabaseQueryOptions = import("../database-view.js").DatabaseQueryOptions;
+export type DatabaseQuerySource = import("../database-view.js").DatabaseQuerySource;
+export type DatabaseViewBinding = import("../database-view.js").DatabaseViewBinding;
+export type DatabaseViewPosition = import("../database-view.js").DatabaseViewPosition;
+export type DatabaseViewSnapshot = import("../database-view.js").DatabaseViewSnapshot;
+/**
+ * A subscription cleanup returned by a typed reactive transport.
+ */
+export type ReactiveDisposer = (() => void) | {
+    readonly dispose: () => void;
+} | {
+    readonly unsubscribe: () => void;
+};
+export type ReactiveSubscriptionContext = {
+    readonly signal: AbortSignal;
+};
+export type ReactiveQueryCallbacks<TValue> = {
+    readonly next: (value: TValue) => void;
+    readonly error: (error: unknown) => void;
+    readonly reset: (reset: ReactiveReset<TValue>) => void;
+};
+/**
+ * The operation owned by the public reactive contract. It may use HTTP
+ * long-polling or WebSocket delivery; the hook does not know or care which.
+ */
+export type ReactiveQuerySource<TValue> = {
+    readonly key?: string | readonly unknown[];
+    readonly subscribe: (observer: ReactiveQueryCallbacks<TValue>, context: ReactiveSubscriptionContext) => ReactiveDisposer | void | Promise<ReactiveDisposer | void>;
+};
+export type ReactiveResetReason = "checkpoint-expired" | "retention-advanced" | "generation-changed" | "checkpoint-not-current" | "view-diverged" | "oversized" | "invalid-operations" | "invalid-checkpoint" | "backpressure" | (string & {});
+/**
+ * A server-authorized reset. The checkpoint remains opaque to the hook.
+ */
+export type ReactiveReset<TValue> = {
+    readonly reason: ReactiveResetReason;
+    readonly data?: TValue;
+    readonly checkpoint?: string | Uint8Array;
+    readonly code?: string;
+    readonly message?: string;
+};
+export type ReactiveErrorKind = "subscription" | "transport" | "remote" | "cancelled" | "mutation";
+export type ReactiveError = {
+    readonly kind: ReactiveErrorKind;
+    readonly code: string;
+    readonly message: string;
+    readonly cause?: unknown;
+    readonly terraScale?: TerraScaleError;
+    readonly database?: Extract<DatabaseResult<never>, {
+        readonly ok: false;
+    }>["error"];
+};
+export type ReactiveQueryStatus = "pending" | "success" | "error" | "reset";
+export type ReactiveQueryState<TValue> = {
+    readonly status: ReactiveQueryStatus;
+    readonly data: TValue | undefined;
+    readonly error: ReactiveError | undefined;
+    readonly reset: ReactiveReset<TValue> | undefined;
+    readonly isLoading: boolean;
+    readonly isFetching: boolean;
+    readonly isStale: boolean;
+};
+export type ReactiveQueryOptions<TValue> = {
+    readonly enabled?: boolean;
+    readonly initialData?: TValue;
+};
+export type ReactiveMutationContext = {
+    readonly signal: AbortSignal;
+    readonly idempotencyKey: string;
+};
+export type OptimisticRollback = void | (() => void) | {
+    readonly rollback: () => void;
+};
+export type ReactiveMutationOptions<TValue, TVariables> = {
+    readonly mutationFn: (variables: TVariables, context: ReactiveMutationContext) => Promise<TValue | TerraScaleResult<TValue> | DatabaseResult<TValue>>;
+    readonly idempotencyKey?: string | ((variables: TVariables) => string);
+    readonly onMutate?: (variables: TVariables, context: ReactiveMutationContext) => OptimisticRollback | Promise<OptimisticRollback>;
+};
+export type ReactiveMutationStatus = "idle" | "pending" | "success" | "error" | "cancelled";
+export type ReactiveMutationState<TValue> = {
+    readonly status: ReactiveMutationStatus;
+    readonly data: TValue | undefined;
+    readonly error: ReactiveError | undefined;
+    readonly idempotencyKey: string | undefined;
+    readonly isPending: boolean;
+};
+import type { TerraScaleError } from "../result.js";
+import type { DatabaseResult } from "../database-types.js";
+import type { TerraScaleResult } from "../result.js";
+export { createDatabaseQuery, DatabaseSubscriptionError, DatabaseSubscriptionView } from "../database-view.js";

package/types/react/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * React's external-store primitive gives useQuery one SSR-safe snapshot and
+ * makes every server update flow through the typed reactive subscription.
+ * Keep the source object stable between renders.
+ *
+ * @template TValue
+ * @param {ReactiveQuerySource<TValue>} source
+ * @param {ReactiveQueryOptions<TValue>} [options]
+ * @returns {ReactiveQueryState<TValue> & { readonly refetch: () => void }}
+ */
+export function useQuery<TValue>(source: ReactiveQuerySource<TValue>, options?: ReactiveQueryOptions<TValue>): ReactiveQueryState<TValue> & {
+    readonly refetch: () => void;
+};
+/**
+ * @template TValue, TVariables
+ * @typedef {ReactiveMutationState<TValue> & {
+ *   readonly mutate: (variables: TVariables) => void;
+ *   readonly mutateAsync: (variables: TVariables) => Promise<TValue>;
+ *   readonly cancel: () => void;
+ *   readonly reset: () => void;
+ * }} UseMutationResult
+ */
+/**
+ * A durable mutation always receives one idempotency identity and AbortSignal.
+ * The optional onMutate result is a reversible presentation rollback; it is
+ * never an offline queue and is removed on either acceptance or rejection.
+ *
+ * @template TValue
+ * @template [TVariables=void]
+ * @param {ReactiveMutationOptions<TValue, TVariables>} options
+ * @returns {UseMutationResult<TValue, TVariables>}
+ */
+export function useMutation<TValue, TVariables = void>(options: ReactiveMutationOptions<TValue, TVariables>): UseMutationResult<TValue, TVariables>;
+/**
+ * Explicitly disposes a mutation observer created outside a React tree.
+ *
+ * @template TValue, TVariables
+ * @param {ReactiveMutationObserver<TValue, TVariables>} observer
+ * @returns {void}
+ */
+export function disposeMutation<TValue, TVariables>(observer: ReactiveMutationObserver<TValue, TVariables>): void;
+export * from "./core.js";
+export type UseMutationResult<TValue, TVariables> = ReactiveMutationState<TValue> & {
+    readonly mutate: (variables: TVariables) => void;
+    readonly mutateAsync: (variables: TVariables) => Promise<TValue>;
+    readonly cancel: () => void;
+    readonly reset: () => void;
+};
+import type { ReactiveQuerySource } from "./core.js";
+import type { ReactiveQueryOptions } from "./core.js";
+import type { ReactiveQueryState } from "./core.js";
+import type { ReactiveMutationOptions } from "./core.js";
+import { ReactiveMutationObserver } from "./core.js";
+import type { ReactiveMutationState } from "./core.js";

package/types/result.d.ts

@@ -0,0 +1,161 @@
+/**
+ * @typedef {(
+ *   | "authentication"
+ *   | "authorization"
+ *   | "conflict"
+ *   | "domain"
+ *   | "invalid-response"
+ *   | "not-found"
+ *   | "rate-limit"
+ *   | "server"
+ *   | "transport"
+ *   | "unavailable"
+ *   | "validation"
+ * )} TerraScaleErrorKind
+ */
+/**
+ * The stable category names published by the TerraScale error envelope.
+ * @typedef {(
+ *   | "Validation"
+ *   | "Authentication"
+ *   | "Authorization"
+ *   | "NotFound"
+ *   | "Conflict"
+ *   | "RateLimit"
+ *   | "Schema"
+ *   | "Query"
+ *   | "Placement"
+ *   | "AutoFix"
+ *   | "AutoIndex"
+ *   | "Sandbox"
+ *   | "System"
+ * )} TerraScaleErrorCategory
+ */
+/**
+ * @typedef {{
+ *   readonly path?: string;
+ *   readonly message: string;
+ *   readonly code?: string;
+ * }} TerraScaleValidationIssue
+ */
+/**
+ * `fix` is optional producer-provided remediation from the published error body.
+ * `retryAfter` is the retry delay from the Retry-After header, in milliseconds,
+ * when the server sent one.
+ * @typedef {{
+ *   readonly kind: TerraScaleErrorKind;
+ *   readonly code: string;
+ *   readonly message: string;
+ *   readonly fix?: string | undefined;
+ *   readonly retryAfter?: number | undefined;
+ *   readonly category?: TerraScaleErrorCategory | undefined;
+ *   readonly detail?: string | undefined;
+ *   readonly suggestedAction?: string | undefined;
+ *   readonly docsUrl?: string | undefined;
+ *   readonly traceId?: string | undefined;
+ *   readonly status?: number | undefined;
+ *   readonly target?: string | undefined;
+ *   readonly requestId?: string | undefined;
+ *   readonly validation?: readonly TerraScaleValidationIssue[] | undefined;
+ *   readonly details?: unknown | undefined;
+ * }} TerraScaleError
+ */
+/**
+ * @template TValue
+ * @typedef {{
+ *   readonly ok: true;
+ *   readonly routeName: string;
+ *   readonly status: number;
+ *   readonly headers: Headers;
+ *   readonly value: TValue;
+ * }} TerraScaleSuccess
+ */
+/**
+ * @typedef {{
+ *   readonly ok: false;
+ *   readonly routeName: string;
+ *   readonly status?: number | undefined;
+ *   readonly headers?: Headers | undefined;
+ *   readonly error: TerraScaleError;
+ *   readonly body?: unknown | undefined;
+ * }} TerraScaleFailure
+ */
+/**
+ * @template TValue
+ * @typedef {TerraScaleFailure | TerraScaleSuccess<TValue>} TerraScaleResult
+ */
+/**
+ * @template TValue
+ * @param {string} routeName
+ * @param {number} status
+ * @param {Headers} headers
+ * @param {TValue} value
+ * @returns {TerraScaleSuccess<TValue>}
+ */
+export function ok<TValue>(routeName: string, status: number, headers: Headers, value: TValue): TerraScaleSuccess<TValue>;
+/**
+ * @param {string} routeName
+ * @param {TerraScaleError} error
+ * @param {number} [status]
+ * @param {Headers} [headers]
+ * @param {unknown} [body]
+ * @returns {TerraScaleFailure}
+ */
+export function err(routeName: string, error: TerraScaleError, status?: number, headers?: Headers, body?: unknown): TerraScaleFailure;
+/**
+ * Makes values safe to retain in a public result. Error bodies and transport
+ * failures are producer-controlled and may contain credentials even when the
+ * published error contract does not. Keep this deliberately conservative:
+ * sensitive fields are replaced and secret-bearing URLs are never preserved.
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+export function sanitizeDiagnostic(value: unknown): unknown;
+export type TerraScaleErrorKind = ("authentication" | "authorization" | "conflict" | "domain" | "invalid-response" | "not-found" | "rate-limit" | "server" | "transport" | "unavailable" | "validation");
+/**
+ * The stable category names published by the TerraScale error envelope.
+ */
+export type TerraScaleErrorCategory = ("Validation" | "Authentication" | "Authorization" | "NotFound" | "Conflict" | "RateLimit" | "Schema" | "Query" | "Placement" | "AutoFix" | "AutoIndex" | "Sandbox" | "System");
+export type TerraScaleValidationIssue = {
+    readonly path?: string;
+    readonly message: string;
+    readonly code?: string;
+};
+/**
+ * `fix` is optional producer-provided remediation from the published error body.
+ * `retryAfter` is the retry delay from the Retry-After header, in milliseconds,
+ * when the server sent one.
+ */
+export type TerraScaleError = {
+    readonly kind: TerraScaleErrorKind;
+    readonly code: string;
+    readonly message: string;
+    readonly fix?: string | undefined;
+    readonly retryAfter?: number | undefined;
+    readonly category?: TerraScaleErrorCategory | undefined;
+    readonly detail?: string | undefined;
+    readonly suggestedAction?: string | undefined;
+    readonly docsUrl?: string | undefined;
+    readonly traceId?: string | undefined;
+    readonly status?: number | undefined;
+    readonly target?: string | undefined;
+    readonly requestId?: string | undefined;
+    readonly validation?: readonly TerraScaleValidationIssue[] | undefined;
+    readonly details?: unknown | undefined;
+};
+export type TerraScaleSuccess<TValue> = {
+    readonly ok: true;
+    readonly routeName: string;
+    readonly status: number;
+    readonly headers: Headers;
+    readonly value: TValue;
+};
+export type TerraScaleFailure = {
+    readonly ok: false;
+    readonly routeName: string;
+    readonly status?: number | undefined;
+    readonly headers?: Headers | undefined;
+    readonly error: TerraScaleError;
+    readonly body?: unknown | undefined;
+};
+export type TerraScaleResult<TValue> = TerraScaleFailure | TerraScaleSuccess<TValue>;