API index and search · Build metadata

Source snapshot

packages/sql-client/src/types.ts

1/** A value accepted by Rindle SQL's v1 client. Binary values are deliberately unsupported. */2export type SqlValue = null | string | number | bigint | boolean;34export type SqlArgs = readonly SqlValue[] | Readonly<Record<string, SqlValue>>;56export interface Statement {7  sql: string;8  args?: SqlArgs;9  wantRows?: boolean;10}1112export interface Column {13  name: string;14  decltype: string | null;15}1617export interface StatementResult {18  columns: Column[];19  rows: SqlValue[][];20  rowsAffected: number;21  lastInsertRowid: string | null;22  rowsRead: number | null;23  rowsWritten: number | null;24}2526export interface RoutingMetadata {27  servedBy: "master" | "follower" | "standalone";28  appliedLagMs: number | null;29  fenceFallback: boolean;30}3132export interface ExecuteResult {33  result: StatementResult;34  commitCursor: string | null;35  routing: RoutingMetadata;36}3738export interface BatchResult {39  results: StatementResult[];40  commitCursor: string | null;41  routing: RoutingMetadata;42}4344export interface MigrationInput {45  id: string;46  checksum: string;47  statements: string[];48}4950export interface MigrationResult {51  applied: boolean;52  commitCursor: string;53}5455export type ReadConsistency = "session" | "strong" | "eventual";56export type IntMode = "bigint" | "number" | "string";57export type RetryScope = "request" | "transaction" | "closure" | "never";58export type TransactionState = "open" | "closed" | "unknown";5960export interface OperationOptions {61  signal?: AbortSignal;62}6364export interface ExecuteOptions extends OperationOptions {65  consistency?: ReadConsistency;66  sessionCursor?: string | null;67}6869export type BatchOptions = ExecuteOptions;7071export interface TransactionOptions extends OperationOptions {72  readOnly?: boolean;73  isolation?: "serializable" | "snapshot";74  consistency?: ReadConsistency;75  sessionCursor?: string | null;76}7778/** The optimistic mutation whose effects a mutation-aware SQL transaction commits. `mid` is the79 *  requested mutation id; `lmid` is server-owned state and therefore only appears in receipts. */80export interface MutationIdentity {81  clientId: string;82  mid: number;83}8485/** The authoritative outcome of a mutation commit or lmid-only rejection. */86export interface MutationReceipt {87  applied: boolean;88  lmid: number;89  commitCursor: string | null;90}9192/** Positional rows returned by a read inside an open mutation transaction. */93export interface MutationRows {94  columns: string[];95  rows: SqlValue[][];96}9798export interface ExecuteMutationInput extends MutationIdentity {99  /** May be empty: an accepted no-op must still advance lmid and retire the prediction. */100  statements: Statement[];101}102103export interface BeginMutationInput extends MutationIdentity {104  /** A pure-write prefix accumulated before the mutator's first read. */105  statements?: Statement[];106  /** Optional first read, coalesced with begin to preserve the mutation fast path. */107  query?: Statement | string;108}109110export interface RejectMutationInput extends MutationIdentity {111  reason?: string;112}113114export interface SqlMutationTransaction {115  execute(statement: Statement | string, options?: OperationOptions): Promise<void>;116  batch(statements: Statement[], options?: OperationOptions): Promise<void>;117  query(statement: Statement | string, options?: OperationOptions): Promise<MutationRows>;118  commit(options?: OperationOptions): Promise<MutationReceipt>;119  rollback(options?: OperationOptions): Promise<void>;120}121122/** Begin-time mid dedup can absorb a replay without opening a transaction; callers must skip the123 *  mutator body in that branch. */124export type BeginMutationResult =125  | { absorbed: true; receipt: MutationReceipt }126  | { absorbed: false; transaction: SqlMutationTransaction; read?: MutationRows };127128export interface RetryOptions extends TransactionOptions {129  /** Total closure attempts, including the first. Defaults to 5. */130  maxAttempts?: number;131  /** Initial closure-retry delay. Defaults to 10ms. */132  baseDelayMs?: number;133  /** Maximum closure-retry delay. Defaults to 250ms. */134  maxDelayMs?: number;135}136137/** Portable subset of the WHATWG fetch signature used by the client. Keeping the input to the138 *  URL forms we actually emit avoids leaking the DOM-only `RequestInfo` alias into Node/Worker139 *  consumers that compile this package from source. */140export type Fetch = (input: string | URL, init?: RequestInit) => Promise<Response>;141142export interface ClientOptions {143  url: string;144  authToken: string;145  consistency?: ReadConsistency;146  sessionCursor?: string | null;147  intMode?: IntMode;148  /** Test/service-binding seam. The default is the runtime's global fetch. */149  fetch?: Fetch;150}151152export interface SqlTransaction {153  execute(statement: Statement | string, options?: OperationOptions): Promise<StatementResult>;154  batch(statements: Statement[], options?: OperationOptions): Promise<StatementResult[]>;155  commit(options?: OperationOptions): Promise<{ commitCursor: string | null }>;156  rollback(options?: OperationOptions): Promise<void>;157}158159export interface SqlSession {160  execute(statement: Statement | string, options?: ExecuteOptions): Promise<ExecuteResult>;161  batch(statements: Statement[], options?: BatchOptions): Promise<BatchResult>;162  begin(options?: TransactionOptions): Promise<SqlTransaction>;163  withTransaction<T>(fn: (tx: SqlTransaction) => Promise<T>, options?: TransactionOptions): Promise<T>;164  withTransactionRetry<T>(fn: (tx: SqlTransaction) => Promise<T>, options?: RetryOptions): Promise<T>;165  /** One-round-trip optimistic mutation commit (effects + lmid in the same atomic unit). */166  executeMutation(input: ExecuteMutationInput, options?: OperationOptions): Promise<MutationReceipt>;167  /** Open an interactive optimistic mutation transaction, or absorb a replay before it runs. */168  beginMutation(input: BeginMutationInput, options?: OperationOptions): Promise<BeginMutationResult>;169  /** Process a business/pre-flight rejection as an lmid-only commit. */170  rejectMutation(input: RejectMutationInput, options?: OperationOptions): Promise<MutationReceipt>;171  executeDdl(sql: string, options?: OperationOptions): Promise<ExecuteResult>;172  migrate(input: MigrationInput, options?: OperationOptions): Promise<MigrationResult>;173  executeMultiple(sql: string, options?: OperationOptions): Promise<void>;174  session(cursor?: string | null): SqlSession;175  getSessionCursor(): string | null;176  resetSessionCursor(): void;177  ping(options?: OperationOptions): Promise<void>;178}179180export interface SqlClient extends SqlSession {181  close(): void;182}183184// Frozen v1 JSON value and statement DTOs.185export interface WireI64 {186  $rindle: "i64";187  value: string;188}189190export interface WireFloat {191  $rindle: "float";192  value: "Infinity" | "-Infinity";193}194195export type WireSqlValue = null | string | number | WireI64 | WireFloat;196export type WireArgs = WireSqlValue[] | Record<string, WireSqlValue>;197198export interface WireStatement {199  sql: string;200  args?: WireArgs;201  want_rows?: boolean;202}203204export interface WireColumn {205  name: string;206  decltype: string | null;207}208209export interface WireStatementResult {210  columns: WireColumn[];211  rows: WireSqlValue[][];212  rows_affected: number;213  last_insert_rowid: string | null;214  rows_read: number | null;215  rows_written: number | null;216}217218export interface WireRoutingMetadata {219  served_by: "master" | "follower" | "standalone";220  applied_lag_ms: number | null;221  fence_fallback: boolean;222}223224export interface WireExecuteResponse {225  result: WireStatementResult;226  commit_cursor: string | null;227  routing: WireRoutingMetadata;228}229230export interface WireBatchResponse {231  results: WireStatementResult[];232  commit_cursor: string | null;233  routing: WireRoutingMetadata;234}235