@rindle/sql-client 0.6.4

package/src/drizzle.ts

@@ -0,0 +1,257 @@
+import { createSqlClient } from "./client.ts";
+import { RindleSqlError, valueUnsupported } from "./errors.ts";
+import type {
+  ClientOptions,
+  SqlClient,
+  SqlTransaction,
+  SqlValue,
+  Statement,
+  StatementResult,
+} from "./types.ts";
+
+/** The small, structural statement shape consumed by drizzle-orm/libsql. */
+export interface DrizzleStatement {
+  sql: string;
+  args?: DrizzleArgs;
+}
+
+export type DrizzleArgs = readonly unknown[] | Readonly<Record<string, unknown>>;
+export type DrizzleInputStatement = string | DrizzleStatement | readonly [sql: string, args?: DrizzleArgs];
+export type DrizzleTransactionMode = "write" | "read" | "deferred";
+
+// Booleans are a bind convenience only; SQLite result storage classes never decode to boolean.
+export type DrizzleValue = Exclude<SqlValue, boolean | bigint>;
+export type DrizzleRow = DrizzleValue[] & Record<string, DrizzleValue>;
+
+export interface DrizzleResultSet {
+  columns: string[];
+  columnTypes: string[];
+  rows: DrizzleRow[];
+  rowsAffected: number;
+  lastInsertRowid: bigint | undefined;
+  toJSON(): unknown;
+}
+
+export interface DrizzleTransaction {
+  readonly closed: boolean;
+  execute(statement: DrizzleInputStatement): Promise<DrizzleResultSet>;
+  batch(statements: DrizzleInputStatement[]): Promise<DrizzleResultSet[]>;
+  executeMultiple(sql: string): Promise<void>;
+  commit(): Promise<void>;
+  rollback(): Promise<void>;
+  close(): void;
+}
+
+export interface DrizzleClient {
+  readonly protocol: string;
+  readonly closed: boolean;
+  execute(statement: DrizzleInputStatement, args?: DrizzleArgs): Promise<DrizzleResultSet>;
+  batch(statements: DrizzleInputStatement[], mode?: DrizzleTransactionMode): Promise<DrizzleResultSet[]>;
+  /** Present for structural Client typing; Drizzle's libSQL migrator is deliberately unsupported. */
+  migrate(statements: DrizzleInputStatement[]): Promise<DrizzleResultSet[]>;
+  transaction(mode?: DrizzleTransactionMode): Promise<DrizzleTransaction>;
+  executeMultiple(sql: string): Promise<void>;
+  /** Embedded-replica sync is deliberately unsupported. */
+  sync(): Promise<never>;
+  reconnect(): void;
+  close(): void;
+  /** Escape hatch for Rindle-specific operations and session-cursor persistence. */
+  readonly rindle: SqlClient;
+}
+
+function toNativeStatement(input: DrizzleInputStatement, args?: DrizzleArgs): Statement | string {
+  if (typeof input === "string") return args === undefined ? input : { sql: input, args: args as Statement["args"] };
+  if (Array.isArray(input)) return { sql: input[0], args: input[1] as Statement["args"] };
+  return {
+    sql: (input as DrizzleStatement).sql,
+    // The native codec performs the deliberate runtime refusal for binary/unsupported values.
+    args: (input as DrizzleStatement).args as Statement["args"],
+  };
+}
+
+function defineNamedCell(row: DrizzleRow, name: string, value: DrizzleValue): void {
+  // Array length and numeric aliases overlap the positional row representation; positions win.
+  const numericIndex = Number(name);
+  if (
+    name === "length" ||
+    (Number.isInteger(numericIndex) && numericIndex >= 0 && numericIndex < 0xffff_ffff && String(numericIndex) === name)
+  ) {
+    return;
+  }
+  try {
+    Object.defineProperty(row, name, { value, writable: true, enumerable: true, configurable: true });
+  } catch {
+    // An exotic/non-configurable property name cannot be represented in the hybrid row.
+  }
+}
+
+function toDrizzleValue(value: SqlValue): DrizzleValue {
+  if (typeof value === "bigint") {
+    const number = Number(value);
+    if (!Number.isSafeInteger(number)) {
+      throw valueUnsupported(`integer ${value.toString()} is outside Number's safe integer range required by Drizzle`);
+    }
+    return number;
+  }
+  // The native decoder never produces booleans, but normalize a structurally supplied result too.
+  if (typeof value === "boolean") return value ? 1 : 0;
+  return value;
+}
+
+/** Convert Rindle's lossless positional result into libSQL's positional + named hybrid rows. */
+export function toDrizzleResultSet(result: StatementResult): DrizzleResultSet {
+  const columns = result.columns.map((column) => column.name);
+  const columnTypes = result.columns.map((column) => column.decltype ?? "");
+  const rows = result.rows.map((cells) => {
+    const row = cells.map(toDrizzleValue) as DrizzleRow;
+    for (let index = 0; index < columns.length; index += 1) {
+      defineNamedCell(row, columns[index]!, row[index]!);
+    }
+    return row;
+  });
+  const converted: DrizzleResultSet = {
+    columns,
+    columnTypes,
+    rows,
+    rowsAffected: result.rowsAffected,
+    lastInsertRowid: result.lastInsertRowid === null ? undefined : BigInt(result.lastInsertRowid),
+    toJSON() {
+      return {
+        columns: this.columns,
+        columnTypes: this.columnTypes,
+        rows: this.rows,
+        rowsAffected: this.rowsAffected,
+        lastInsertRowid: this.lastInsertRowid?.toString(),
+      };
+    },
+  };
+  return converted;
+}
+
+class TransactionFacade implements DrizzleTransaction {
+  private isClosed = false;
+  private readonly tx: SqlTransaction;
+
+  constructor(tx: SqlTransaction) {
+    this.tx = tx;
+  }
+
+  get closed(): boolean {
+    return this.isClosed;
+  }
+
+  async execute(statement: DrizzleInputStatement): Promise<DrizzleResultSet> {
+    return toDrizzleResultSet(await this.tx.execute(toNativeStatement(statement)));
+  }
+
+  async batch(statements: DrizzleInputStatement[]): Promise<DrizzleResultSet[]> {
+    const native = statements.map((statement) => {
+      const converted = toNativeStatement(statement);
+      return typeof converted === "string" ? { sql: converted } : converted;
+    });
+    return (await this.tx.batch(native)).map(toDrizzleResultSet);
+  }
+
+  async executeMultiple(_sql: string): Promise<void> {
+    throw new RindleSqlError({
+      code: "STATEMENT_UNSUPPORTED",
+      message: "executeMultiple is not supported inside a Rindle interactive transaction; use batch()",
+    });
+  }
+
+  async commit(): Promise<void> {
+    if (this.isClosed) return;
+    await this.tx.commit();
+    this.isClosed = true;
+  }
+
+  async rollback(): Promise<void> {
+    if (this.isClosed) return;
+    await this.tx.rollback();
+    this.isClosed = true;
+  }
+
+  close(): void {
+    if (this.isClosed) return;
+    this.isClosed = true;
+    void this.tx.rollback().catch(() => {});
+  }
+}
+
+class ClientFacade implements DrizzleClient {
+  readonly rindle: SqlClient;
+  readonly protocol = "http";
+  private isClosed = false;
+
+  constructor(rindle: SqlClient) {
+    this.rindle = rindle;
+  }
+
+  get closed(): boolean {
+    return this.isClosed;
+  }
+
+  async execute(statement: DrizzleInputStatement, args?: DrizzleArgs): Promise<DrizzleResultSet> {
+    return toDrizzleResultSet((await this.rindle.execute(toNativeStatement(statement, args))).result);
+  }
+
+  async batch(statements: DrizzleInputStatement[], _mode?: DrizzleTransactionMode): Promise<DrizzleResultSet[]> {
+    const native = statements.map((statement) => {
+      const converted = toNativeStatement(statement);
+      return typeof converted === "string" ? { sql: converted } : converted;
+    });
+    return (await this.rindle.batch(native)).results.map(toDrizzleResultSet);
+  }
+
+  async transaction(mode: DrizzleTransactionMode = "write"): Promise<DrizzleTransaction> {
+    if (mode !== "write" && mode !== "read" && mode !== "deferred") {
+      throw new TypeError(`unsupported transaction mode: ${String(mode)}`);
+    }
+    return new TransactionFacade(await this.rindle.begin({ readOnly: mode === "read" }));
+  }
+
+  executeMultiple(sql: string): Promise<void> {
+    return this.rindle.executeMultiple(sql);
+  }
+
+  async migrate(_statements: DrizzleInputStatement[]): Promise<DrizzleResultSet[]> {
+    throw new RindleSqlError({
+      code: "MIGRATOR_UNSUPPORTED",
+      message: "drizzle-orm/libsql/migrator is not supported; apply declared migrations with SqlClient.migrate()",
+    });
+  }
+
+  async sync(): Promise<never> {
+    throw new RindleSqlError({
+      code: "SYNC_UNSUPPORTED",
+      message: "embedded-replica sync is not supported by Rindle SQL",
+    });
+  }
+
+  reconnect(): void {
+    throw new RindleSqlError({
+      code: "RECONNECT_UNSUPPORTED",
+      message: "a closed Rindle SQL client cannot be reopened; create a new client",
+    });
+  }
+
+  close(): void {
+    if (this.isClosed) return;
+    this.isClosed = true;
+    this.rindle.close();
+  }
+}
+
+/** Create the structural libSQL-client facade used by drizzle-orm/libsql. */
+export function createDrizzleClient(options: ClientOptions | SqlClient): DrizzleClient {
+  // drizzle-orm's SQLite integer mappers consume numbers (including timestamp multiplication).
+  // Keep its structural libSQL seam on that policy even though the direct Rindle client defaults
+  // to lossless bigint results. toDrizzleResultSet also normalizes an injected SqlClient.
+  const client = isSqlClient(options) ? options : createSqlClient({ ...options, intMode: "number" });
+  return new ClientFacade(client);
+}
+
+function isSqlClient(value: ClientOptions | SqlClient): value is SqlClient {
+  const candidate = value as Partial<SqlClient>;
+  return typeof candidate.execute === "function" && typeof candidate.close === "function";
+}

package/src/errors.ts

@@ -0,0 +1,51 @@
+import type { RetryScope, StatementResult, TransactionState } from "./types.ts";
+
+export interface RindleSqlErrorOptions {
+  code: string;
+  message: string;
+  sqliteCode?: number;
+  retryScope?: RetryScope;
+  transactionState?: TransactionState;
+  status?: number;
+  requestId?: string;
+  statementIndex?: number;
+  partialResults?: StatementResult[];
+  cause?: unknown;
+}
+
+/** Stable error surfaced for both server envelopes and client-side contract refusals. */
+export 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) {
+    super(options.message, options.cause === undefined ? undefined : { cause: options.cause });
+    this.name = "RindleSqlError";
+    this.code = options.code;
+    this.sqliteCode = options.sqliteCode;
+    this.retryScope = options.retryScope ?? "never";
+    this.transactionState = options.transactionState;
+    this.status = options.status;
+    this.requestId = options.requestId;
+    this.statementIndex = options.statementIndex;
+    this.partialResults = options.partialResults;
+  }
+}
+
+export function isRindleSqlError(error: unknown): error is RindleSqlError {
+  return error instanceof RindleSqlError;
+}
+
+export function valueUnsupported(message: string): RindleSqlError {
+  return new RindleSqlError({ code: "VALUE_UNSUPPORTED", message, retryScope: "never" });
+}
+
+export function protocolError(message: string, cause?: unknown): RindleSqlError {
+  return new RindleSqlError({ code: "PROTOCOL_ERROR", message, retryScope: "never", cause });
+}

package/src/id.ts

@@ -0,0 +1,25 @@
+function randomBytes(): Uint8Array {
+  const crypto = globalThis.crypto;
+  if (typeof crypto?.getRandomValues !== "function") {
+    throw new TypeError("Rindle SQL requires Web Crypto getRandomValues for request identities");
+  }
+  return crypto.getRandomValues(new Uint8Array(16));
+}
+
+function hexBytes(bytes: Uint8Array): string {
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+/** Runtime-portable one-shot idempotency key; its wire format is intentionally centralized here. */
+export function newIdempotencyKey(): string {
+  const now = Date.now();
+  if (!Number.isSafeInteger(now) || now < 0 || now > 9_999_999_999_999) {
+    throw new TypeError("system clock is outside the canonical SQL idempotency-key range");
+  }
+  return `sql1.${now.toString().padStart(13, "0")}.${hexBytes(randomBytes())}`;
+}
+
+/** One canonical design-225 logical request id backed by 128 cryptographically random bits. */
+export function newRequestId(): string {
+  return `rid1.${hexBytes(randomBytes())}`;
+}

package/src/index.ts

@@ -0,0 +1,48 @@
+export { createSqlClient } from "./client.ts";
+export { RindleSqlError, isRindleSqlError } from "./errors.ts";
+export { decodeSqlValue, encodeArgs, encodeSqlValue, encodeStatement } from "./value.ts";
+
+export type {
+  BatchOptions,
+  BatchResult,
+  BeginMutationInput,
+  BeginMutationResult,
+  ClientOptions,
+  Column,
+  ExecuteMutationInput,
+  ExecuteOptions,
+  ExecuteResult,
+  Fetch,
+  IntMode,
+  MigrationInput,
+  MigrationResult,
+  MutationIdentity,
+  MutationReceipt,
+  MutationRows,
+  OperationOptions,
+  ReadConsistency,
+  RejectMutationInput,
+  RetryOptions,
+  RetryScope,
+  RoutingMetadata,
+  SqlArgs,
+  SqlClient,
+  SqlMutationTransaction,
+  SqlSession,
+  SqlTransaction,
+  SqlValue,
+  Statement,
+  StatementResult,
+  TransactionOptions,
+  TransactionState,
+  WireArgs,
+  WireBatchResponse,
+  WireColumn,
+  WireExecuteResponse,
+  WireFloat,
+  WireI64,
+  WireRoutingMetadata,
+  WireSqlValue,
+  WireStatement,
+  WireStatementResult,
+} from "./types.ts";

package/src/types.ts

@@ -0,0 +1,234 @@
+/** A value accepted by Rindle SQL's v1 client. Binary values are deliberately unsupported. */
+export type SqlValue = null | string | number | bigint | boolean;
+
+export type SqlArgs = readonly SqlValue[] | Readonly<Record<string, SqlValue>>;
+
+export interface Statement {
+  sql: string;
+  args?: SqlArgs;
+  wantRows?: boolean;
+}
+
+export interface Column {
+  name: string;
+  decltype: string | null;
+}
+
+export interface StatementResult {
+  columns: Column[];
+  rows: SqlValue[][];
+  rowsAffected: number;
+  lastInsertRowid: string | null;
+  rowsRead: number | null;
+  rowsWritten: number | null;
+}
+
+export interface RoutingMetadata {
+  servedBy: "master" | "follower";
+  appliedLagMs: number | null;
+  fenceFallback: boolean;
+}
+
+export interface ExecuteResult {
+  result: StatementResult;
+  commitCursor: string | null;
+  routing: RoutingMetadata;
+}
+
+export interface BatchResult {
+  results: StatementResult[];
+  commitCursor: string | null;
+  routing: RoutingMetadata;
+}
+
+export interface MigrationInput {
+  id: string;
+  checksum: string;
+  statements: string[];
+}
+
+export interface MigrationResult {
+  applied: boolean;
+  commitCursor: string;
+}
+
+export type ReadConsistency = "session" | "strong" | "eventual";
+export type IntMode = "bigint" | "number" | "string";
+export type RetryScope = "request" | "transaction" | "closure" | "never";
+export type TransactionState = "open" | "closed" | "unknown";
+
+export interface OperationOptions {
+  signal?: AbortSignal;
+}
+
+export interface ExecuteOptions extends OperationOptions {
+  consistency?: ReadConsistency;
+  sessionCursor?: string | null;
+}
+
+export type BatchOptions = ExecuteOptions;
+
+export interface TransactionOptions extends OperationOptions {
+  readOnly?: boolean;
+  isolation?: "serializable" | "snapshot";
+  consistency?: ReadConsistency;
+  sessionCursor?: string | null;
+}
+
+/** 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;
+}
+
+/** The authoritative outcome of a mutation commit or lmid-only rejection. */
+export interface MutationReceipt {
+  applied: boolean;
+  lmid: number;
+  commitCursor: string | null;
+}
+
+/** Positional rows returned by a read inside an open mutation transaction. */
+export interface MutationRows {
+  columns: string[];
+  rows: SqlValue[][];
+}
+
+export interface ExecuteMutationInput extends MutationIdentity {
+  /** May be empty: an accepted no-op must still advance lmid and retire the prediction. */
+  statements: Statement[];
+}
+
+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;
+}
+
+export interface RejectMutationInput extends MutationIdentity {
+  reason?: string;
+}
+
+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>;
+}
+
+/** 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 };
+
+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;
+}
+
+/** 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>;
+
+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;
+}
+
+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>;
+}
+
+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>;
+}
+
+export interface SqlClient extends SqlSession {
+  close(): void;
+}
+
+// Frozen v1 JSON value and statement DTOs.
+export interface WireI64 {
+  $rindle: "i64";
+  value: string;
+}
+
+export interface WireFloat {
+  $rindle: "float";
+  value: "Infinity" | "-Infinity";
+}
+
+export type WireSqlValue = null | string | number | WireI64 | WireFloat;
+export type WireArgs = WireSqlValue[] | Record<string, WireSqlValue>;
+
+export interface WireStatement {
+  sql: string;
+  args?: WireArgs;
+  want_rows?: boolean;
+}
+
+export interface WireColumn {
+  name: string;
+  decltype: string | null;
+}
+
+export interface WireStatementResult {
+  columns: WireColumn[];
+  rows: WireSqlValue[][];
+  rows_affected: number;
+  last_insert_rowid: string | null;
+  rows_read: number | null;
+  rows_written: number | null;
+}
+
+export interface WireRoutingMetadata {
+  served_by: "master" | "follower";
+  applied_lag_ms: number | null;
+  fence_fallback: boolean;
+}
+
+export interface WireExecuteResponse {
+  result: WireStatementResult;
+  commit_cursor: string | null;
+  routing: WireRoutingMetadata;
+}
+
+export interface WireBatchResponse {
+  results: WireStatementResult[];
+  commit_cursor: string | null;
+  routing: WireRoutingMetadata;
+}