@saasqlite/client 0.0.1

package/README.md

@@ -0,0 +1,91 @@
+# @saasqlite/client
+
+Async SQLite-like SDK for SaaSQLite.
+
+## Install
+
+```bash
+npm install @saasqlite/client
+```
+
+## Quickstart
+
+```ts
+import { SaaSQLite } from "@saasqlite/client";
+
+const db = new SaaSQLite(
+  process.env.SAASQLITE_DB_ID!,
+  process.env.SAASQLITE_API_KEY!,
+);
+
+await db.exec(`
+  CREATE TABLE IF NOT EXISTS users (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    email TEXT NOT NULL UNIQUE,
+    name TEXT
+  )
+`);
+
+await db.run("INSERT INTO users (email, name) VALUES (?, ?)", ["ada@example.com", "Ada"]);
+
+const user = await db
+  .prepare("SELECT * FROM users WHERE email = ?")
+  .get("ada@example.com");
+
+const users = await db
+  .prepare("SELECT * FROM users ORDER BY id DESC LIMIT ?")
+  .all(10);
+
+await db.close();
+```
+
+## Connection options
+
+The gateway URL is resolved in this order:
+
+1. If the first argument is a full `http://` or `https://` URL, it is used as the gateway URL (handy for self-hosted gateways and local development)
+2. `options.gatewayUrl`
+3. The `SAASQLITE_GATEWAY_URL` environment variable
+4. The default: `https://api.saasqlite.com`
+
+```ts
+// Default (cloud): database ID + API key from the dashboard
+const db = new SaaSQLite(process.env.SAASQLITE_DB_ID!, process.env.SAASQLITE_API_KEY!);
+
+// Self-hosted gateway
+const db = new SaaSQLite(
+  process.env.SAASQLITE_DB_ID!,
+  process.env.SAASQLITE_API_KEY!,
+  { gatewayUrl: "https://db.example.com" }
+);
+
+// Or pass the full gateway URL directly
+const db = new SaaSQLite("https://db.example.com", process.env.SAASQLITE_API_KEY!);
+```
+
+The gateway identifies your database from the API key, so the URL is just the gateway base.
+
+## Migration from node:sqlite
+
+```diff
+- import { DatabaseSync } from "node:sqlite";
++ import { SaaSQLite } from "@saasqlite/client";
+
+- const db = new DatabaseSync("./app.db");
++ const db = new SaaSQLite(process.env.SAASQLITE_DB_ID!, process.env.SAASQLITE_API_KEY!);
+
+- const user = db.prepare("SELECT * FROM users WHERE id = ?").get(id);
++ const user = await db.prepare("SELECT * FROM users WHERE id = ?").get(id);
+```
+
+## API
+
+- `exec(sql)` - Execute SQL with no returned rows
+- `prepare(sql)` - Create a prepared statement
+- `get(sql, params?)` - Get one row
+- `all(sql, params?)` - Get all rows
+- `run(sql, params?)` - Run and get affected rows / last insert ID
+- `batch(statements)` - Execute multiple statements in one request
+- `pragma(sql, options?)` - Run a PRAGMA statement
+- `transaction(fn)` - Execute a function within a transaction
+- `close()` - Close the connection

package/dist/index-BdWAt290.d.ts

@@ -0,0 +1,251 @@
+import { Socket } from "node:net";
+
+//#region src/errors.d.ts
+type SaaSQLiteErrorPayload = {
+  code: string;
+  message: string;
+  details?: unknown;
+  queryId?: string;
+  sqliteCode?: string;
+};
+declare class SaaSQLiteError extends Error {
+  code: string;
+  details?: unknown;
+  queryId?: string;
+  sqliteCode?: string;
+  cause?: unknown;
+  constructor(code: string, message: string, options?: {
+    details?: unknown;
+    queryId?: string;
+    sqliteCode?: string;
+    cause?: unknown;
+  });
+  toJSON(): SaaSQLiteErrorPayload;
+}
+//#endregion
+//#region src/transport.d.ts
+type QueryResult = {
+  resultType: "select";
+  columns: string[];
+  rows: Row[];
+} | {
+  resultType: "run";
+  rowsAffected: number;
+  lastInsertRowid: number;
+};
+interface Transport {
+  query(sql: string, params: unknown[]): Promise<QueryResult>;
+  batch(statements: BatchStatement[]): Promise<BatchResult[]>;
+  close(): Promise<void>;
+}
+type HttpTransportOptions = {
+  url: string;
+  token: string;
+  timeoutMs?: number;
+};
+declare class HttpTransport implements Transport {
+  private readonly baseUrl;
+  private readonly token;
+  private readonly timeoutMs;
+  private closed;
+  constructor(opts: HttpTransportOptions);
+  private request;
+  query(sql: string, params: unknown[]): Promise<QueryResult>;
+  batch(statements: BatchStatement[]): Promise<BatchResult[]>;
+  close(): Promise<void>;
+}
+//#endregion
+//#region src/statement.d.ts
+type Row = Record<string, unknown>;
+type Params = unknown[] | Record<string, unknown>;
+type RunResult = {
+  changes: number;
+  lastInsertRowid: number | bigint | null;
+};
+type BatchStatement = {
+  sql: string;
+  params?: unknown[];
+};
+type BatchResult = {
+  type: string;
+  result: unknown;
+} | {
+  code: string;
+  message: string;
+};
+declare class Statement {
+  readonly sql: string;
+  private readonly transport;
+  private readonly timeoutMs;
+  readonly source: string;
+  readonly reader: boolean;
+  readonly readonly: boolean;
+  private _busy;
+  private _changes;
+  private _pluck;
+  private _raw;
+  private _expand;
+  private _boundParams;
+  constructor(sql: string, transport: Transport, timeoutMs: number);
+  get busy(): boolean;
+  get changes(): number;
+  pluck(enable?: boolean): this;
+  raw(enable?: boolean): this;
+  expand(enable?: boolean): this;
+  private get rowMode();
+  bind(...params: unknown[]): this;
+  columns(): Array<{
+    name: string;
+    column: string | null;
+    table: string | null;
+    database: string | null;
+    type: string | null;
+  }>;
+  get<T = Row>(...params: unknown[]): Promise<T | undefined>;
+  all<T = Row>(...params: unknown[]): Promise<T[]>;
+  run(...params: unknown[]): Promise<RunResult>;
+  iterate(...params: unknown[]): AsyncIterator<Row>;
+  private resolveParams;
+  private executeRequest;
+}
+//#endregion
+//#region src/transaction.d.ts
+declare class Transaction {
+  private readonly db;
+  constructor(db: SaaSQLite);
+  prepare(sql: string): Statement;
+  exec(sql: string): Promise<this>;
+  run(sql: string, ...params: unknown[]): Promise<any>;
+  get<T = Record<string, unknown>>(sql: string, ...params: unknown[]): Promise<T | undefined>;
+  all<T = Record<string, unknown>>(sql: string, ...params: unknown[]): Promise<T[]>;
+}
+//#endregion
+//#region src/socket-transport.d.ts
+type SocketTransportOptions = {
+  sock: string;
+  password: string;
+  timeoutMs?: number;
+};
+declare class SocketTransport implements Transport {
+  private readonly sockPath;
+  private readonly password;
+  private readonly timeoutMs;
+  private closed;
+  constructor(opts: SocketTransportOptions);
+  private withSocket;
+  query(sql: string, params: unknown[]): Promise<QueryResult>;
+  batch(statements: BatchStatement[]): Promise<BatchResult[]>;
+  close(): Promise<void>;
+}
+//#endregion
+//#region src/client.d.ts
+/**
+ * Default SaaSQLite gateway (remote cloud endpoint).
+ */
+declare const DEFAULT_GATEWAY_URL = "https://api.saasqlite.com";
+/**
+ * Public constructor options.
+ */
+type SaaSQLiteOptions = {
+  timeoutMs?: number;
+  /**
+   * Gateway base URL (e.g. `https://api.saasqlite.com` or a self-hosted
+   * gateway). Defaults to `$SAASQLITE_GATEWAY_URL` if set, otherwise
+   * `https://api.saasqlite.com`. Ignored when the first constructor
+   * argument is already a full http(s) URL.
+   */
+  gatewayUrl?: string;
+};
+/**
+ * Resolve the gateway base URL for a public-API constructor call.
+ * Precedence: full http(s) URL passed as databaseId > options.gatewayUrl
+ * > $SAASQLITE_GATEWAY_URL > DEFAULT_GATEWAY_URL.
+ */
+declare function resolveGatewayUrl(databaseId: string, opts?: SaaSQLiteOptions): string;
+/**
+ * Internal transport options (not part of public API docs).
+ */
+type SaaSQLiteInternalOptions = HttpTransportOptions | SocketTransportOptions;
+type PragmaOptions = {
+  simple?: boolean;
+};
+declare class SaaSQLite {
+  private readonly _transport;
+  private readonly _timeoutMs;
+  private _closed;
+  private _txDepth;
+  get open(): boolean;
+  readonly name: string;
+  constructor(databaseId: string, apiKey: string, options?: SaaSQLiteOptions);
+  constructor(options: SaaSQLiteInternalOptions);
+  exec(sql: string): Promise<this>;
+  prepare(sql: string): Statement;
+  pragma(sql: string): Promise<Row[]>;
+  pragma(sql: string, options: PragmaOptions): Promise<unknown>;
+  transaction<T>(fn: (tx: Transaction) => Promise<T>): Promise<T>;
+  query<T = Row>(sql: string, params?: Params): Promise<T[]>;
+  get<T = Row>(sql: string, params?: Params): Promise<T | undefined>;
+  all<T = Row>(sql: string, params?: Params): Promise<T[]>;
+  run(sql: string, params?: Params): Promise<RunResult>;
+  batch(statements: BatchStatement[]): Promise<BatchResult[]>;
+  close(): Promise<void>;
+  function(_name: string, ..._args: unknown[]): this;
+  aggregate(_name: string, ..._args: unknown[]): this;
+  table(_name: string, ..._args: unknown[]): this;
+  loadExtension(_path: string): this;
+  backup(_destination: string): Promise<unknown>;
+  serialize(): Buffer;
+  checkpoint(): this;
+  defaultSafeIntegers(_enabled?: boolean): this;
+  unsafeMode(_enabled?: boolean): this;
+  verbose(_fn?: (...args: unknown[]) => void): this;
+  private assertOpen;
+}
+//#endregion
+//#region src/params.d.ts
+type ParamObject = Record<string, unknown>;
+declare function resolveParams(sql: string, params: unknown[] | ParamObject | undefined): {
+  sql: string;
+  positionalParams: unknown[];
+};
+declare function countParameters(sql: string): number;
+//#endregion
+//#region src/protocol.d.ts
+declare const CMD_QUERY = 0,
+  CMD_BATCH = 1,
+  CMD_HEALTH = 2;
+declare const STATUS_OK = 0,
+  STATUS_ERR = 1;
+declare const RESULT_SELECT = 0,
+  RESULT_RUN = 1;
+declare const VAL_NULL = 0,
+  VAL_INT64 = 1,
+  VAL_FLOAT64 = 2,
+  VAL_TEXT = 3,
+  VAL_BLOB = 4;
+declare class Reader {
+  private buf;
+  read(s: Socket, n: number): Promise<Buffer>;
+}
+declare function w32(b: Buffer, o: number, v: number): void;
+declare function r32(b: Buffer, o: number): number;
+declare function w64(b: Buffer, o: number, v: number): void;
+declare function r64(b: Buffer, o: number): number;
+declare function wF64(b: Buffer, o: number, v: number): void;
+declare function rF64(b: Buffer, o: number): number;
+declare function encParam(p: unknown): Buffer;
+declare function encQuery(sql: string, params: unknown[]): Buffer;
+declare function encBatch(stmts: BatchStatement[]): Buffer;
+declare function encHealth(): Buffer;
+declare function readVal(r: Reader, s: Socket): Promise<unknown>;
+declare function readSelect(r: Reader, s: Socket): Promise<{
+  columns: string[];
+  rows: Row[];
+}>;
+declare function readRun(r: Reader, s: Socket): Promise<{
+  rowsAffected: number;
+  lastInsertRowid: number;
+}>;
+declare function checkStatus(r: Reader, s: Socket): Promise<void>;
+//#endregion
+export { type BatchResult, type BatchStatement, CMD_BATCH, CMD_HEALTH, CMD_QUERY, DEFAULT_GATEWAY_URL, HttpTransport, type HttpTransportOptions, type Params, type PragmaOptions, type QueryResult, RESULT_RUN, RESULT_SELECT, Reader, type Row, type RunResult, STATUS_ERR, STATUS_OK, SaaSQLite, SaaSQLiteError, type SaaSQLiteErrorPayload, type SaaSQLiteOptions, SocketTransport, type SocketTransportOptions, Statement, Transaction, type Transport, VAL_BLOB, VAL_FLOAT64, VAL_INT64, VAL_NULL, VAL_TEXT, checkStatus, countParameters, encBatch, encHealth, encParam, encQuery, r32, r64, rF64, readRun, readSelect, readVal, resolveGatewayUrl, resolveParams, w32, w64, wF64 };

package/dist/index-CWaghtMg.d.cts

@@ -0,0 +1,251 @@
+import { Socket } from "node:net";
+
+//#region src/errors.d.ts
+type SaaSQLiteErrorPayload = {
+  code: string;
+  message: string;
+  details?: unknown;
+  queryId?: string;
+  sqliteCode?: string;
+};
+declare class SaaSQLiteError extends Error {
+  code: string;
+  details?: unknown;
+  queryId?: string;
+  sqliteCode?: string;
+  cause?: unknown;
+  constructor(code: string, message: string, options?: {
+    details?: unknown;
+    queryId?: string;
+    sqliteCode?: string;
+    cause?: unknown;
+  });
+  toJSON(): SaaSQLiteErrorPayload;
+}
+//#endregion
+//#region src/transport.d.ts
+type QueryResult = {
+  resultType: "select";
+  columns: string[];
+  rows: Row[];
+} | {
+  resultType: "run";
+  rowsAffected: number;
+  lastInsertRowid: number;
+};
+interface Transport {
+  query(sql: string, params: unknown[]): Promise<QueryResult>;
+  batch(statements: BatchStatement[]): Promise<BatchResult[]>;
+  close(): Promise<void>;
+}
+type HttpTransportOptions = {
+  url: string;
+  token: string;
+  timeoutMs?: number;
+};
+declare class HttpTransport implements Transport {
+  private readonly baseUrl;
+  private readonly token;
+  private readonly timeoutMs;
+  private closed;
+  constructor(opts: HttpTransportOptions);
+  private request;
+  query(sql: string, params: unknown[]): Promise<QueryResult>;
+  batch(statements: BatchStatement[]): Promise<BatchResult[]>;
+  close(): Promise<void>;
+}
+//#endregion
+//#region src/statement.d.ts
+type Row = Record<string, unknown>;
+type Params = unknown[] | Record<string, unknown>;
+type RunResult = {
+  changes: number;
+  lastInsertRowid: number | bigint | null;
+};
+type BatchStatement = {
+  sql: string;
+  params?: unknown[];
+};
+type BatchResult = {
+  type: string;
+  result: unknown;
+} | {
+  code: string;
+  message: string;
+};
+declare class Statement {
+  readonly sql: string;
+  private readonly transport;
+  private readonly timeoutMs;
+  readonly source: string;
+  readonly reader: boolean;
+  readonly readonly: boolean;
+  private _busy;
+  private _changes;
+  private _pluck;
+  private _raw;
+  private _expand;
+  private _boundParams;
+  constructor(sql: string, transport: Transport, timeoutMs: number);
+  get busy(): boolean;
+  get changes(): number;
+  pluck(enable?: boolean): this;
+  raw(enable?: boolean): this;
+  expand(enable?: boolean): this;
+  private get rowMode();
+  bind(...params: unknown[]): this;
+  columns(): Array<{
+    name: string;
+    column: string | null;
+    table: string | null;
+    database: string | null;
+    type: string | null;
+  }>;
+  get<T = Row>(...params: unknown[]): Promise<T | undefined>;
+  all<T = Row>(...params: unknown[]): Promise<T[]>;
+  run(...params: unknown[]): Promise<RunResult>;
+  iterate(...params: unknown[]): AsyncIterator<Row>;
+  private resolveParams;
+  private executeRequest;
+}
+//#endregion
+//#region src/transaction.d.ts
+declare class Transaction {
+  private readonly db;
+  constructor(db: SaaSQLite);
+  prepare(sql: string): Statement;
+  exec(sql: string): Promise<this>;
+  run(sql: string, ...params: unknown[]): Promise<any>;
+  get<T = Record<string, unknown>>(sql: string, ...params: unknown[]): Promise<T | undefined>;
+  all<T = Record<string, unknown>>(sql: string, ...params: unknown[]): Promise<T[]>;
+}
+//#endregion
+//#region src/socket-transport.d.ts
+type SocketTransportOptions = {
+  sock: string;
+  password: string;
+  timeoutMs?: number;
+};
+declare class SocketTransport implements Transport {
+  private readonly sockPath;
+  private readonly password;
+  private readonly timeoutMs;
+  private closed;
+  constructor(opts: SocketTransportOptions);
+  private withSocket;
+  query(sql: string, params: unknown[]): Promise<QueryResult>;
+  batch(statements: BatchStatement[]): Promise<BatchResult[]>;
+  close(): Promise<void>;
+}
+//#endregion
+//#region src/client.d.ts
+/**
+ * Default SaaSQLite gateway (remote cloud endpoint).
+ */
+declare const DEFAULT_GATEWAY_URL = "https://api.saasqlite.com";
+/**
+ * Public constructor options.
+ */
+type SaaSQLiteOptions = {
+  timeoutMs?: number;
+  /**
+   * Gateway base URL (e.g. `https://api.saasqlite.com` or a self-hosted
+   * gateway). Defaults to `$SAASQLITE_GATEWAY_URL` if set, otherwise
+   * `https://api.saasqlite.com`. Ignored when the first constructor
+   * argument is already a full http(s) URL.
+   */
+  gatewayUrl?: string;
+};
+/**
+ * Resolve the gateway base URL for a public-API constructor call.
+ * Precedence: full http(s) URL passed as databaseId > options.gatewayUrl
+ * > $SAASQLITE_GATEWAY_URL > DEFAULT_GATEWAY_URL.
+ */
+declare function resolveGatewayUrl(databaseId: string, opts?: SaaSQLiteOptions): string;
+/**
+ * Internal transport options (not part of public API docs).
+ */
+type SaaSQLiteInternalOptions = HttpTransportOptions | SocketTransportOptions;
+type PragmaOptions = {
+  simple?: boolean;
+};
+declare class SaaSQLite {
+  private readonly _transport;
+  private readonly _timeoutMs;
+  private _closed;
+  private _txDepth;
+  get open(): boolean;
+  readonly name: string;
+  constructor(databaseId: string, apiKey: string, options?: SaaSQLiteOptions);
+  constructor(options: SaaSQLiteInternalOptions);
+  exec(sql: string): Promise<this>;
+  prepare(sql: string): Statement;
+  pragma(sql: string): Promise<Row[]>;
+  pragma(sql: string, options: PragmaOptions): Promise<unknown>;
+  transaction<T>(fn: (tx: Transaction) => Promise<T>): Promise<T>;
+  query<T = Row>(sql: string, params?: Params): Promise<T[]>;
+  get<T = Row>(sql: string, params?: Params): Promise<T | undefined>;
+  all<T = Row>(sql: string, params?: Params): Promise<T[]>;
+  run(sql: string, params?: Params): Promise<RunResult>;
+  batch(statements: BatchStatement[]): Promise<BatchResult[]>;
+  close(): Promise<void>;
+  function(_name: string, ..._args: unknown[]): this;
+  aggregate(_name: string, ..._args: unknown[]): this;
+  table(_name: string, ..._args: unknown[]): this;
+  loadExtension(_path: string): this;
+  backup(_destination: string): Promise<unknown>;
+  serialize(): Buffer;
+  checkpoint(): this;
+  defaultSafeIntegers(_enabled?: boolean): this;
+  unsafeMode(_enabled?: boolean): this;
+  verbose(_fn?: (...args: unknown[]) => void): this;
+  private assertOpen;
+}
+//#endregion
+//#region src/params.d.ts
+type ParamObject = Record<string, unknown>;
+declare function resolveParams(sql: string, params: unknown[] | ParamObject | undefined): {
+  sql: string;
+  positionalParams: unknown[];
+};
+declare function countParameters(sql: string): number;
+//#endregion
+//#region src/protocol.d.ts
+declare const CMD_QUERY = 0,
+  CMD_BATCH = 1,
+  CMD_HEALTH = 2;
+declare const STATUS_OK = 0,
+  STATUS_ERR = 1;
+declare const RESULT_SELECT = 0,
+  RESULT_RUN = 1;
+declare const VAL_NULL = 0,
+  VAL_INT64 = 1,
+  VAL_FLOAT64 = 2,
+  VAL_TEXT = 3,
+  VAL_BLOB = 4;
+declare class Reader {
+  private buf;
+  read(s: Socket, n: number): Promise<Buffer>;
+}
+declare function w32(b: Buffer, o: number, v: number): void;
+declare function r32(b: Buffer, o: number): number;
+declare function w64(b: Buffer, o: number, v: number): void;
+declare function r64(b: Buffer, o: number): number;
+declare function wF64(b: Buffer, o: number, v: number): void;
+declare function rF64(b: Buffer, o: number): number;
+declare function encParam(p: unknown): Buffer;
+declare function encQuery(sql: string, params: unknown[]): Buffer;
+declare function encBatch(stmts: BatchStatement[]): Buffer;
+declare function encHealth(): Buffer;
+declare function readVal(r: Reader, s: Socket): Promise<unknown>;
+declare function readSelect(r: Reader, s: Socket): Promise<{
+  columns: string[];
+  rows: Row[];
+}>;
+declare function readRun(r: Reader, s: Socket): Promise<{
+  rowsAffected: number;
+  lastInsertRowid: number;
+}>;
+declare function checkStatus(r: Reader, s: Socket): Promise<void>;
+//#endregion
+export { type BatchResult, type BatchStatement, CMD_BATCH, CMD_HEALTH, CMD_QUERY, DEFAULT_GATEWAY_URL, HttpTransport, type HttpTransportOptions, type Params, type PragmaOptions, type QueryResult, RESULT_RUN, RESULT_SELECT, Reader, type Row, type RunResult, STATUS_ERR, STATUS_OK, SaaSQLite, SaaSQLiteError, type SaaSQLiteErrorPayload, type SaaSQLiteOptions, SocketTransport, type SocketTransportOptions, Statement, Transaction, type Transport, VAL_BLOB, VAL_FLOAT64, VAL_INT64, VAL_NULL, VAL_TEXT, checkStatus, countParameters, encBatch, encHealth, encParam, encQuery, r32, r64, rF64, readRun, readSelect, readVal, resolveGatewayUrl, resolveParams, w32, w64, wF64 };