@rindle/sql-client

0.0.0 · Public export map; development manifest version (0.0.0).

Source revision 05d0bf2c2e56 · build details

Source revision: 05d0bf2c2e56.
TypeScript input SHA-256: aabe6cfcc4172b870d5e272142958e9ea8d8784c2aa23133156e5a7ee633318e
Generated 2026-09-04T23:58:25.590Z with TypeScript 6.0.3. Public TypeScript checks and declaration emit passed. Package runtime tests are separate.

Entry point source

BatchOptions

TypeAliasDeclaration · Source: packages/sql-client/src/types.ts:69 · Supporting declarations

export type BatchOptions = ExecuteOptions;

BatchResult

InterfaceDeclaration · Source: packages/sql-client/src/types.ts:38 · Supporting declarations

export interface BatchResult {
    results: StatementResult[];
    commitCursor: string | null;
    routing: RoutingMetadata;
}

BeginMutationInput

InterfaceDeclaration · Source: packages/sql-client/src/types.ts:103 · Supporting declarations

export interface BeginMutationInput extends MutationIdentity {
    /** A pure-write prefix accumulated before the mutator's first read. */
    statements?: Statement[];
    /** Optional first read, coalesced with begin to preserve the mutation fast path. */
    query?: Statement | string;
}

BeginMutationResult

TypeAliasDeclaration · Source: packages/sql-client/src/types.ts:124 · Supporting declarations

Begin-time mid dedup can absorb a replay without opening a transaction; callers must skip the mutator body in that branch.

export type BeginMutationResult = {
    absorbed: true;
    receipt: MutationReceipt;
} | {
    absorbed: false;
    transaction: SqlMutationTransaction;
    read?: MutationRows;
};

ClientOptions

InterfaceDeclaration · Source: packages/sql-client/src/types.ts:142 · Supporting declarations

export interface ClientOptions {
    url: string;
    authToken: string;
    consistency?: ReadConsistency;
    sessionCursor?: string | null;
    intMode?: IntMode;
    /** Test/service-binding seam. The default is the runtime's global fetch. */
    fetch?: Fetch;
}

Column

InterfaceDeclaration · Source: packages/sql-client/src/types.ts:12 · Supporting declarations

export interface Column {
    name: string;
    decltype: string | null;
}

createSqlClient

FunctionDeclaration · Source: packages/sql-client/src/client.ts:1157 · Supporting declarations

export declare function createSqlClient(options: ClientOptions): SqlClient;

decodeSqlValue

FunctionDeclaration · Source: packages/sql-client/src/value.ts:66 · Supporting declarations

Decode one frozen v1 tagged JSON value using the client's integer policy.

export declare function decodeSqlValue(value: unknown, intMode?: IntMode): SqlValue;

encodeArgs

FunctionDeclaration · Source: packages/sql-client/src/value.ts:94 · Supporting declarations

export declare function encodeArgs(args: SqlArgs): WireArgs;

encodeSqlValue

FunctionDeclaration · Source: packages/sql-client/src/value.ts:24 · Supporting declarations

Encode one public SDK value into the frozen v1 tagged JSON representation.

export declare function encodeSqlValue(value: SqlValue): WireSqlValue;

encodeStatement

FunctionDeclaration · Source: packages/sql-client/src/value.ts:102 · Supporting declarations

export declare function encodeStatement(statement: Statement | string): WireStatement;

ExecuteMutationInput

InterfaceDeclaration · Source: packages/sql-client/src/types.ts:98 · Supporting declarations

export interface ExecuteMutationInput extends MutationIdentity {
    /** May be empty: an accepted no-op must still advance lmid and retire the prediction. */
    statements: Statement[];
}

ExecuteOptions

InterfaceDeclaration · Source: packages/sql-client/src/types.ts:64 · Supporting declarations

export interface ExecuteOptions extends OperationOptions {
    consistency?: ReadConsistency;
    sessionCursor?: string | null;
}

ExecuteResult

InterfaceDeclaration · Source: packages/sql-client/src/types.ts:32 · Supporting declarations

export interface ExecuteResult {
    result: StatementResult;
    commitCursor: string | null;
    routing: RoutingMetadata;
}

Fetch

TypeAliasDeclaration · Source: packages/sql-client/src/types.ts:140 · Supporting declarations

Portable subset of the WHATWG fetch signature used by the client. Keeping the input to the URL forms we actually emit avoids leaking the DOM-only RequestInfo alias into Node/Worker consumers that compile this package from source.

export type Fetch = (input: string | URL, init?: RequestInit) => Promise<Response>;

IntMode

TypeAliasDeclaration · Source: packages/sql-client/src/types.ts:56 · Supporting declarations

export type IntMode = "bigint" | "number" | "string";

isRindleSqlError

FunctionDeclaration · Source: packages/sql-client/src/errors.ts:41 · Supporting declarations

export declare function isRindleSqlError(error: unknown): error is RindleSqlError;

MigrationInput

InterfaceDeclaration · Source: packages/sql-client/src/types.ts:44 · Supporting declarations

export interface MigrationInput {
    id: string;
    checksum: string;
    statements: string[];
}

MigrationResult

InterfaceDeclaration · Source: packages/sql-client/src/types.ts:50 · Supporting declarations

export interface MigrationResult {
    applied: boolean;
    commitCursor: string;
}

MutationIdentity

InterfaceDeclaration · Source: packages/sql-client/src/types.ts:80 · Supporting declarations

The optimistic mutation whose effects a mutation-aware SQL transaction commits. mid is the requested mutation id; lmid is server-owned state and therefore only appears in receipts.

export interface MutationIdentity {
    clientId: string;
    mid: number;
}

MutationReceipt

InterfaceDeclaration · Source: packages/sql-client/src/types.ts:86 · Supporting declarations

The authoritative outcome of a mutation commit or lmid-only rejection.

export interface MutationReceipt {
    applied: boolean;
    lmid: number;
    commitCursor: string | null;
}

MutationRows

InterfaceDeclaration · Source: packages/sql-client/src/types.ts:93 · Supporting declarations

Positional rows returned by a read inside an open mutation transaction.

export interface MutationRows {
    columns: string[];
    rows: SqlValue[][];
}

OperationOptions

InterfaceDeclaration · Source: packages/sql-client/src/types.ts:60 · Supporting declarations

export interface OperationOptions {
    signal?: AbortSignal;
}

ReadConsistency

TypeAliasDeclaration · Source: packages/sql-client/src/types.ts:55 · Supporting declarations

export type ReadConsistency = "session" | "strong" | "eventual";

RejectMutationInput

InterfaceDeclaration · Source: packages/sql-client/src/types.ts:110 · Supporting declarations

export interface RejectMutationInput extends MutationIdentity {
    reason?: string;
}

RetryOptions

InterfaceDeclaration · Source: packages/sql-client/src/types.ts:128 · Supporting declarations

export interface RetryOptions extends TransactionOptions {
    /** Total closure attempts, including the first. Defaults to 5. */
    maxAttempts?: number;
    /** Initial closure-retry delay. Defaults to 10ms. */
    baseDelayMs?: number;
    /** Maximum closure-retry delay. Defaults to 250ms. */
    maxDelayMs?: number;
}

RetryScope

TypeAliasDeclaration · Source: packages/sql-client/src/types.ts:57 · Supporting declarations

export type RetryScope = "request" | "transaction" | "closure" | "never";

RindleSqlError

ClassDeclaration · Source: packages/sql-client/src/errors.ts:17 · Supporting declarations

Stable error surfaced for both server envelopes and client-side contract refusals.

export declare class RindleSqlError extends Error {
    readonly code: string;
    readonly sqliteCode: number | undefined;
    readonly retryScope: RetryScope;
    readonly transactionState: TransactionState | undefined;
    readonly status: number | undefined;
    readonly requestId: string | undefined;
    readonly statementIndex: number | undefined;
    readonly partialResults: StatementResult[] | undefined;
    constructor(options: RindleSqlErrorOptions);
}

RoutingMetadata

InterfaceDeclaration · Source: packages/sql-client/src/types.ts:26 · Supporting declarations

export interface RoutingMetadata {
    servedBy: "master" | "follower" | "standalone";
    appliedLagMs: number | null;
    fenceFallback: boolean;
}

SqlArgs

TypeAliasDeclaration · Source: packages/sql-client/src/types.ts:4 · Supporting declarations

export type SqlArgs = readonly SqlValue[] | Readonly<Record<string, SqlValue>>;

SqlClient

InterfaceDeclaration · Source: packages/sql-client/src/types.ts:180 · Supporting declarations

export interface SqlClient extends SqlSession {
    close(): void;
}

SqlMutationTransaction

InterfaceDeclaration · Source: packages/sql-client/src/types.ts:114 · Supporting declarations

export interface SqlMutationTransaction {
    execute(statement: Statement | string, options?: OperationOptions): Promise<void>;
    batch(statements: Statement[], options?: OperationOptions): Promise<void>;
    query(statement: Statement | string, options?: OperationOptions): Promise<MutationRows>;
    commit(options?: OperationOptions): Promise<MutationReceipt>;
    rollback(options?: OperationOptions): Promise<void>;
}

SqlSession

InterfaceDeclaration · Source: packages/sql-client/src/types.ts:159 · Supporting declarations

export interface SqlSession {
    execute(statement: Statement | string, options?: ExecuteOptions): Promise<ExecuteResult>;
    batch(statements: Statement[], options?: BatchOptions): Promise<BatchResult>;
    begin(options?: TransactionOptions): Promise<SqlTransaction>;
    withTransaction<T>(fn: (tx: SqlTransaction) => Promise<T>, options?: TransactionOptions): Promise<T>;
    withTransactionRetry<T>(fn: (tx: SqlTransaction) => Promise<T>, options?: RetryOptions): Promise<T>;
    /** One-round-trip optimistic mutation commit (effects + lmid in the same atomic unit). */
    executeMutation(input: ExecuteMutationInput, options?: OperationOptions): Promise<MutationReceipt>;
    /** Open an interactive optimistic mutation transaction, or absorb a replay before it runs. */
    beginMutation(input: BeginMutationInput, options?: OperationOptions): Promise<BeginMutationResult>;
    /** Process a business/pre-flight rejection as an lmid-only commit. */
    rejectMutation(input: RejectMutationInput, options?: OperationOptions): Promise<MutationReceipt>;
    executeDdl(sql: string, options?: OperationOptions): Promise<ExecuteResult>;
    migrate(input: MigrationInput, options?: OperationOptions): Promise<MigrationResult>;
    executeMultiple(sql: string, options?: OperationOptions): Promise<void>;
    session(cursor?: string | null): SqlSession;
    getSessionCursor(): string | null;
    resetSessionCursor(): void;
    ping(options?: OperationOptions): Promise<void>;
}

SqlTransaction

InterfaceDeclaration · Source: packages/sql-client/src/types.ts:152 · Supporting declarations

export interface SqlTransaction {
    execute(statement: Statement | string, options?: OperationOptions): Promise<StatementResult>;
    batch(statements: Statement[], options?: OperationOptions): Promise<StatementResult[]>;
    commit(options?: OperationOptions): Promise<{
        commitCursor: string | null;
    }>;
    rollback(options?: OperationOptions): Promise<void>;
}

SqlValue

TypeAliasDeclaration · Source: packages/sql-client/src/types.ts:2 · Supporting declarations

A value accepted by Rindle SQL's v1 client. Binary values are deliberately unsupported.

export type SqlValue = null | string | number | bigint | boolean;

Statement

InterfaceDeclaration · Source: packages/sql-client/src/types.ts:6 · Supporting declarations

export interface Statement {
    sql: string;
    args?: SqlArgs;
    wantRows?: boolean;
}

StatementResult

InterfaceDeclaration · Source: packages/sql-client/src/types.ts:17 · Supporting declarations

export interface StatementResult {
    columns: Column[];
    rows: SqlValue[][];
    rowsAffected: number;
    lastInsertRowid: string | null;
    rowsRead: number | null;
    rowsWritten: number | null;
}

TransactionOptions

InterfaceDeclaration · Source: packages/sql-client/src/types.ts:71 · Supporting declarations

export interface TransactionOptions extends OperationOptions {
    readOnly?: boolean;
    isolation?: "serializable" | "snapshot";
    consistency?: ReadConsistency;
    sessionCursor?: string | null;
}

TransactionState

TypeAliasDeclaration · Source: packages/sql-client/src/types.ts:58 · Supporting declarations

export type TransactionState = "open" | "closed" | "unknown";

WireArgs

TypeAliasDeclaration · Source: packages/sql-client/src/types.ts:196 · Supporting declarations

export type WireArgs = WireSqlValue[] | Record<string, WireSqlValue>;

WireBatchResponse

InterfaceDeclaration · Source: packages/sql-client/src/types.ts:230 · Supporting declarations

export interface WireBatchResponse {
    results: WireStatementResult[];
    commit_cursor: string | null;
    routing: WireRoutingMetadata;
}

WireColumn

InterfaceDeclaration · Source: packages/sql-client/src/types.ts:204 · Supporting declarations

export interface WireColumn {
    name: string;
    decltype: string | null;
}

WireExecuteResponse

InterfaceDeclaration · Source: packages/sql-client/src/types.ts:224 · Supporting declarations

export interface WireExecuteResponse {
    result: WireStatementResult;
    commit_cursor: string | null;
    routing: WireRoutingMetadata;
}

WireFloat

InterfaceDeclaration · Source: packages/sql-client/src/types.ts:190 · Supporting declarations

export interface WireFloat {
    $rindle: "float";
    value: "Infinity" | "-Infinity";
}

WireI64

InterfaceDeclaration · Source: packages/sql-client/src/types.ts:185 · Supporting declarations

export interface WireI64 {
    $rindle: "i64";
    value: string;
}

WireRoutingMetadata

InterfaceDeclaration · Source: packages/sql-client/src/types.ts:218 · Supporting declarations

export interface WireRoutingMetadata {
    served_by: "master" | "follower" | "standalone";
    applied_lag_ms: number | null;
    fence_fallback: boolean;
}

WireSqlValue

TypeAliasDeclaration · Source: packages/sql-client/src/types.ts:195 · Supporting declarations

export type WireSqlValue = null | string | number | WireI64 | WireFloat;

WireStatement

InterfaceDeclaration · Source: packages/sql-client/src/types.ts:198 · Supporting declarations

export interface WireStatement {
    sql: string;
    args?: WireArgs;
    want_rows?: boolean;
}

WireStatementResult

InterfaceDeclaration · Source: packages/sql-client/src/types.ts:209 · Supporting declarations

export interface WireStatementResult {
    columns: WireColumn[];
    rows: WireSqlValue[][];
    rows_affected: number;
    last_insert_rowid: string | null;
    rows_read: number | null;
    rows_written: number | null;
}