@riffdb/client 0.0.0-stage → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,332 @@
+import { DriverApplicationTransport, type DriverApplicationError, type DriverCompactQueryResult, type DriverPackedQueryResult, type DriverOperation } from "./driver.js";
+export type ApplicationValueSchema = {
+    readonly kind: "bool" | "i64" | "u64" | "string" | "uuid" | "bytes" | "date" | "timestamp" | "cursor" | "limit";
+    readonly maximumBytes?: number;
+} | {
+    readonly kind: "vector";
+    readonly dimension: number;
+} | {
+    readonly kind: "decimal";
+    readonly precision?: number;
+    readonly scale?: number;
+} | {
+    readonly kind: "money";
+    readonly precision?: number;
+    readonly scale?: number;
+    readonly currency?: string;
+} | {
+    readonly kind: "enum";
+    readonly typeId?: number;
+    readonly variants?: Readonly<Record<string, number>>;
+} | {
+    readonly kind: "optional";
+    readonly value: ApplicationValueSchema;
+} | {
+    readonly kind: "list";
+    readonly value: ApplicationValueSchema;
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly aggregateCanonicalElementBytes?: number;
+} | {
+    readonly kind: "record";
+    readonly fields: ReadonlyArray<{
+        readonly name: string;
+        readonly schema: ApplicationValueSchema;
+        readonly wireId?: number;
+    }>;
+};
+export type InputBudgetCause = "collection_count" | "individual_value_bytes" | "aggregate_canonical_element_bytes";
+export interface InputBudgetPath {
+    readonly collection: string;
+    readonly index?: number;
+    readonly leaf?: string;
+}
+export declare class InputBudgetError extends Error {
+    readonly cause: InputBudgetCause;
+    readonly path: InputBudgetPath;
+    constructor(cause: InputBudgetCause, path: InputBudgetPath);
+}
+/** One exact fixed-point value accepted by generated decimal fields. */
+export interface ExactDecimalValue {
+    readonly coefficientTwosComplement: Uint8Array;
+    readonly scale: number;
+    readonly precision: number;
+}
+/** One exact currency value accepted by generated `money<CURRENCY>` fields. */
+export interface ExactMoneyValue<Currency extends string = string> {
+    readonly currency: Currency;
+    readonly amount: ExactDecimalValue;
+}
+/**
+ * Constructs an exact fixed-point value from decimal text without using a
+ * JavaScript floating-point number.
+ */
+export declare function exactDecimal(value: string, precision: number, scale: number): ExactDecimalValue;
+/** Constructs the exact precision-38, scale-2 value used by `money<CURRENCY>`. */
+export declare function exactMoney<const Currency extends string>(currency: Currency, value: string): ExactMoneyValue<Currency>;
+export type QueryConsistency = "admissionHead";
+export interface QueryOptions {
+    readonly cursor?: string;
+    readonly readAfterCommit?: bigint;
+    readonly consistency?: QueryConsistency;
+}
+interface NamedQueryRequest<P, R> {
+    readonly driverOperation?: DriverOperation;
+    readonly contractLineage: string;
+    readonly contractVersion: number;
+    readonly contractBundleHash: string;
+    readonly moduleHash: string;
+    readonly queryName: string;
+    readonly planHash: string;
+    readonly parameters: P;
+    readonly parameterSchema: ApplicationValueSchema;
+    readonly resultSchemas: Readonly<Record<string, ApplicationValueSchema>>;
+    readonly compactDecoder?: (value: DriverCompactQueryResult) => R;
+    readonly packedDecoder?: (value: DriverPackedQueryResult) => R;
+    readonly decodeError: (value: unknown) => Error;
+    readonly resultType?: R;
+}
+interface CommandRequest<I, R> {
+    readonly driverOperation?: DriverOperation;
+    readonly contractLineage: string;
+    readonly contractVersion: number;
+    readonly commandName: string;
+    readonly planHash: string;
+    readonly input: I;
+    readonly idempotencyKey: string;
+    readonly inputSchema: ApplicationValueSchema;
+    readonly outcomeSchemas: Readonly<Record<string, ApplicationValueSchema>>;
+    readonly decodeError: (value: unknown) => Error;
+    readonly outcomeType?: R;
+}
+interface VectorInspectionRequest<P, R> {
+    readonly driverOperation?: DriverOperation;
+    readonly contractLineage: string;
+    readonly contractVersion: number;
+    readonly contractBundleHash: string;
+    readonly entity: string;
+    readonly field: string;
+    readonly inspectionKind: "staleness" | "model_versions";
+    readonly partition: P;
+    readonly partitionSchema: ApplicationValueSchema;
+    readonly limit: number;
+    readonly resultType?: R;
+}
+interface VectorInspectionOptions {
+    readonly cursor?: string;
+}
+interface TypedVectorInspectionResult<T> {
+    readonly value: T;
+    readonly applicationHead?: bigint;
+    readonly nextCursor?: string;
+}
+export interface QueryResponseIdentity {
+    readonly contractLineage: string;
+    readonly contractVersion: number;
+    readonly contractBundleHash: string;
+    readonly moduleHash: string;
+    readonly queryName: string;
+    readonly planHash: string;
+}
+export interface TypedQueryResult<T> {
+    readonly identity: QueryResponseIdentity;
+    readonly value: T;
+    readonly applicationHead: bigint;
+    readonly nextCursor?: string;
+}
+export interface TypedCommandResult<T> {
+    readonly outcome: T;
+    readonly commitSequence?: bigint;
+    readonly contractVersion: number;
+    readonly planHash: string;
+    readonly replayed: boolean;
+    readonly outcomeUri?: string;
+}
+export interface CliApplicationTransportOptions {
+    readonly riffdbPath: string;
+    readonly endpoint: string;
+    readonly credentialFile: string;
+}
+export interface ReactiveConsumerRequest<P> {
+    readonly driverOperations?: Readonly<Record<string, DriverOperation>>;
+    readonly reactiveModuleHash: string;
+    readonly operationName: string;
+    readonly parameters: P;
+    readonly parameterSchema: ApplicationValueSchema;
+    readonly consumerName: string;
+}
+export interface ReactiveConsumerOptions {
+    readonly batchLimit?: number;
+    readonly inFlightLimit?: number;
+    readonly leaseSeconds?: number;
+    readonly maximumWaitMs?: number;
+    readonly signal?: AbortSignal;
+}
+export interface ReactiveEventDelivery<E> {
+    readonly eventId: string;
+    readonly event: E;
+    readonly attempt: number;
+    readonly leaseToken: string;
+    readonly expiresAt: string;
+    readonly historyIncarnation: bigint;
+}
+export interface ReactiveConsumerBatch<E> {
+    readonly events: ReadonlyArray<ReactiveEventDelivery<E>>;
+    readonly waitTimedOut: boolean;
+    readonly status: ReactiveConsumerStatus;
+}
+export interface ContextualHydration {
+    readonly name: string;
+    readonly outcome: string;
+    readonly fields: Readonly<Record<string, unknown>>;
+}
+export interface ContextualReaction {
+    readonly name: string;
+    readonly commandName: string;
+    readonly commandId: number;
+    readonly causationToken: string;
+}
+export interface ContextualWorkItem<E> {
+    readonly delivery: ReactiveEventDelivery<E>;
+    readonly contextHead: bigint;
+    readonly hydrations: ReadonlyArray<ContextualHydration>;
+    readonly availableReactions: ReadonlyArray<ContextualReaction>;
+}
+export interface ContextualBatch<E> {
+    readonly items: ReadonlyArray<ContextualWorkItem<E>>;
+    readonly waitTimedOut: boolean;
+    readonly status: ReactiveConsumerStatus;
+}
+export interface ReactiveConsumerStatus {
+    readonly revision: bigint;
+    readonly checkpoint: string;
+    readonly historyIncarnation: bigint;
+    readonly liveLeases: number;
+    readonly retries: number;
+    readonly deadLetters: number;
+}
+export type ReactiveEventMutationResult = "applied" | "state_changed" | "not_found" | "outstanding_lease" | "stale_lease" | "lease_expired";
+export type LiveQueryPatchOperation = {
+    readonly type: "insert";
+    readonly index: number;
+    readonly record: Readonly<Record<string, unknown>>;
+} | {
+    readonly type: "remove";
+    readonly index: number;
+    readonly key: Readonly<Record<string, unknown>>;
+} | {
+    readonly type: "replace";
+    readonly index: number;
+    readonly record: Readonly<Record<string, unknown>>;
+} | {
+    readonly type: "move";
+    readonly from: number;
+    readonly to: number;
+    readonly key: Readonly<Record<string, unknown>>;
+};
+export type LiveQueryUpdate<T> = {
+    readonly type: "snapshot";
+    readonly value: T;
+    readonly cursor: string;
+    readonly applicationHead: bigint;
+    readonly historyIncarnation: bigint;
+} | {
+    readonly type: "patch";
+    readonly resultField: string;
+    readonly operations: ReadonlyArray<LiveQueryPatchOperation>;
+    readonly cursor: string;
+    readonly applicationHead: bigint;
+    readonly historyIncarnation: bigint;
+} | {
+    readonly type: "reset";
+    readonly reason: string;
+    readonly value: T;
+    readonly cursor: string;
+    readonly applicationHead: bigint;
+    readonly historyIncarnation: bigint;
+} | {
+    readonly type: "checkpoint";
+    readonly cursor: string;
+    readonly applicationHead: bigint;
+    readonly historyIncarnation: bigint;
+} | {
+    readonly type: "terminal";
+    readonly reason: string;
+    readonly lastApplicationHead?: bigint;
+    readonly historyIncarnation?: bigint;
+};
+export declare class CliApplicationTransport {
+    private readonly options;
+    constructor(options: CliApplicationTransportOptions);
+    executeNamedQuery<P, R>(request: NamedQueryRequest<P, R>, options?: QueryOptions): Promise<TypedQueryResult<R>>;
+    executeCommand<I, R>(request: CommandRequest<I, R>, attemptBudget: number): Promise<TypedCommandResult<R>>;
+    executeVectorInspection<P, R>(request: VectorInspectionRequest<P, R>, options?: VectorInspectionOptions): Promise<TypedVectorInspectionResult<R>>;
+    consumeEventStream<P, E>(request: ReactiveConsumerRequest<P>, options?: ReactiveConsumerOptions): AsyncIterable<ReactiveConsumerBatch<E>>;
+    acknowledgeEvent<P>(request: ReactiveConsumerRequest<P>, delivery: ReactiveEventDelivery<unknown>): Promise<ReactiveEventMutationResult>;
+    negativeAcknowledgeEvent<P>(request: ReactiveConsumerRequest<P>, delivery: ReactiveEventDelivery<unknown>, retryDelayMs?: number): Promise<ReactiveEventMutationResult>;
+    seekEventConsumer<P>(request: ReactiveConsumerRequest<P>, checkpoint: string): Promise<ReactiveEventMutationResult>;
+    eventConsumerStatus<P>(request: ReactiveConsumerRequest<P>): Promise<ReactiveConsumerStatus | undefined>;
+    consumeContextualSubscription<P, E>(request: ReactiveConsumerRequest<P>, maximumWaitMs?: number): Promise<ContextualBatch<E>>;
+    acknowledgeContextualItem<P>(request: ReactiveConsumerRequest<P>, item: ContextualWorkItem<unknown>): Promise<ReactiveEventMutationResult>;
+    negativeAcknowledgeContextualItem<P>(request: ReactiveConsumerRequest<P>, item: ContextualWorkItem<unknown>, retryDelayMs?: number): Promise<ReactiveEventMutationResult>;
+    contextualSubscriptionStatus<P>(request: ReactiveConsumerRequest<P>): Promise<ReactiveConsumerStatus | undefined>;
+    executeContextualReaction<P, I, R>(request: ReactiveConsumerRequest<P>, reaction: ContextualReaction, command: CommandRequest<I, R>): Promise<TypedCommandResult<R>>;
+    watchNamedQuery<P, T>(request: {
+        readonly reactiveModuleHash: string;
+        readonly operationName: string;
+        readonly parameters: P;
+        readonly parameterSchema: ApplicationValueSchema;
+        readonly cursor?: string;
+    }): AsyncIterable<LiveQueryUpdate<T>>;
+    private mutateEventLease;
+    private mutateContextualItem;
+    private reactiveArguments;
+    private baseArguments;
+    private invoke;
+    private invokeArguments;
+}
+/**
+ * Generated-facade adapter for one retained Rust driver-host session.
+ *
+ * The adapter owns only checked value assembly and result decoding. Remote
+ * trust, credentials, retries, pooling, and uncertainty remain in Rust.
+ */
+export declare class DriverGeneratedApplicationTransport {
+    private readonly driver;
+    constructor(driver: DriverApplicationTransport);
+    /** Returns the bound tenant identifier when this session is tenant-scoped. */
+    get tenant(): string | undefined;
+    executeNamedQuery<P, R>(request: NamedQueryRequest<P, R>, options?: QueryOptions): Promise<TypedQueryResult<R>>;
+    executeCommand<I, R>(request: CommandRequest<I, R>, attemptBudget: number): Promise<TypedCommandResult<R>>;
+    executeVectorInspection<P, R>(request: VectorInspectionRequest<P, R>, options?: VectorInspectionOptions): Promise<TypedVectorInspectionResult<R>>;
+    executeCommandBatch<I, R>(request: CommandRequest<I, R>, inputs: ReadonlyArray<I>, concurrency: number, checkpoint: number, attemptBudget: number): Promise<{
+        readonly items: ReadonlyArray<{
+            readonly index: number;
+            readonly result?: TypedCommandResult<R>;
+            readonly error?: DriverApplicationError;
+        }>;
+        readonly checkpoint: number;
+    }>;
+    consumeEventStream<P, E>(request: ReactiveConsumerRequest<P>, options?: ReactiveConsumerOptions): AsyncIterable<ReactiveConsumerBatch<E>>;
+    acknowledgeEvent<P>(request: ReactiveConsumerRequest<P>, delivery: ReactiveEventDelivery<unknown>): Promise<ReactiveEventMutationResult>;
+    negativeAcknowledgeEvent<P>(request: ReactiveConsumerRequest<P>, delivery: ReactiveEventDelivery<unknown>, retryDelayMs?: number): Promise<ReactiveEventMutationResult>;
+    seekEventConsumer<P>(request: ReactiveConsumerRequest<P>, checkpoint: string): Promise<ReactiveEventMutationResult>;
+    eventConsumerStatus<P>(request: ReactiveConsumerRequest<P>): Promise<ReactiveConsumerStatus | undefined>;
+    consumeContextualSubscription<P, E>(request: ReactiveConsumerRequest<P>, maximumWaitMs?: number, signal?: AbortSignal): Promise<ContextualBatch<E>>;
+    acknowledgeContextualItem<P>(request: ReactiveConsumerRequest<P>, item: ContextualWorkItem<unknown>): Promise<ReactiveEventMutationResult>;
+    negativeAcknowledgeContextualItem<P>(request: ReactiveConsumerRequest<P>, item: ContextualWorkItem<unknown>, retryDelayMs?: number): Promise<ReactiveEventMutationResult>;
+    contextualSubscriptionStatus<P>(request: ReactiveConsumerRequest<P>): Promise<ReactiveConsumerStatus | undefined>;
+    executeContextualReaction<P, I, R>(request: ReactiveConsumerRequest<P>, reaction: ContextualReaction, command: CommandRequest<I, R>): Promise<TypedCommandResult<R>>;
+    watchNamedQuery<P, T>(request: {
+        readonly driverOperations?: Readonly<Record<string, DriverOperation>>;
+        readonly reactiveModuleHash: string;
+        readonly operationName: string;
+        readonly parameters: P;
+        readonly parameterSchema: ApplicationValueSchema;
+        readonly cursor?: string;
+        readonly signal?: AbortSignal;
+    }): AsyncIterable<LiveQueryUpdate<T>>;
+    private mutateDriverLease;
+}
+export { DRIVER_ERROR_REGISTRY_HASH, DRIVER_PROTOCOL_VERSION, DRIVER_VALUE_REGISTRY_HASH, DriverApplicationError, DriverApplicationTransport, } from "./driver.js";
+export type { DriverApplicationIdentity, DriverApplicationTransportOptions, DriverBatchItem, DriverBatchResult, DriverBatchSuccess, DriverDecimal, DriverErrorDetails, DriverInvokeOptions, DriverMoney, DriverOperation, DriverPackedColumn, DriverPackedQueryResult, DriverResult, DriverTimestamp, DriverValue, } from "./driver.js";