sqlite-hub-client 0.2.0

package/README.md

@@ -0,0 +1,412 @@
+# sqlite-db-client
+
+High-level TypeScript/JavaScript client for [sqlite-db-hub](https://github.com/0xdps/sqlite-db-hub).  
+Comes with a full set of APIs for schema management, reads, writes — all using an **adapter** abstraction so the same code works over HTTP today and can talk to SQLite directly later.
+
+## Install
+
+```bash
+npm install sqlite-db-client
+```
+
+## Quick start
+
+```ts
+import { connect } from "sqlite-db-client";
+
+const db = connect({
+  url: process.env.SQLITE_DB_HUB_URL, // e.g. https://my-app.up.railway.app
+  token: process.env.SQLITE_DB_HUB_TOKEN, // ADMIN_TOKEN set on the service
+  db: "my-service", // database name
+});
+
+// Create table
+await db.createTable("users", [
+  { name: "id", type: "INTEGER", primaryKey: true, autoIncrement: true },
+  { name: "email", type: "TEXT", notNull: true, unique: true },
+  { name: "name", type: "TEXT" },
+  { name: "created_at", type: "TEXT", default: "(datetime('now'))" },
+]);
+
+// Create index
+await db.createIndex("idx_users_email", "users", ["email"], { unique: true });
+
+// Insert
+const { lastInsertRowid } = await db.insert("users", {
+  email: "alice@example.com",
+  name: "Alice",
+});
+
+// Bulk insert
+await db.insertMany("users", [
+  { email: "bob@example.com", name: "Bob" },
+  { email: "carol@example.com", name: "Carol" },
+]);
+
+// Read — find all
+const users = await db.find<{ id: number; email: string; name: string }>(
+  "users"
+);
+
+// Read — filtered, paginated, ordered
+const page = await db.find(
+  "users",
+  {},
+  {
+    orderBy: "created_at",
+    order: "DESC",
+    limit: 10,
+    offset: 0,
+  }
+);
+
+// Read — single row by arbitrary filter
+const alice = await db.findOne("users", { email: "alice@example.com" });
+
+// Read — by primary key
+const user = await db.findById("users", 1);
+
+// Count
+const total = await db.count("users");
+const active = await db.count("users", { active: 1 });
+
+// Exists check
+const exists = await db.exists("users", { email: "alice@example.com" });
+
+// Update
+await db.update("users", { name: "Alice Smith" }, { id: 1 });
+
+// Delete
+await db.delete("users", { id: 1 });
+
+// Drop table
+await db.dropTable("users");
+
+// Raw SQL escape hatch
+const result = await db.exec("PRAGMA table_info(users)");
+```
+
+## API
+
+### `connect(options)` — create a database client
+
+| Option    | Type     | Required | Description                                           |
+| --------- | -------- | -------- | ----------------------------------------------------- |
+| `url`     | `string` | ✅       | Base URL of your sqlite-db-hub deployment             |
+| `token`   | `string` | ✅       | `ADMIN_TOKEN` configured on the sqlite-db-hub service |
+| `db`      | `string` | ✅       | Name of the database to operate on                    |
+| `timeout` | `number` | ❌       | Request timeout in ms (default: `10000`)              |
+
+Returns a `Database` instance.
+
+---
+
+### Schema
+
+#### `db.createTable(table, columns, options?)`
+
+```ts
+await db.createTable(
+  "posts",
+  [
+    { name: "id", type: "INTEGER", primaryKey: true, autoIncrement: true },
+    { name: "title", type: "TEXT", notNull: true },
+    { name: "body", type: "TEXT" },
+  ],
+  { ifNotExists: true }
+); // ifNotExists: true is the default
+```
+
+**`ColumnDef` fields:**
+
+| Field           | Type               | Description                                    |
+| --------------- | ------------------ | ---------------------------------------------- |
+| `name`          | `string`           | Column name                                    |
+| `type`          | `string`           | SQLite type: `INTEGER`, `TEXT`, `REAL`, `BLOB` |
+| `primaryKey`    | `boolean`          | Mark as PRIMARY KEY                            |
+| `autoIncrement` | `boolean`          | Add AUTOINCREMENT                              |
+| `notNull`       | `boolean`          | Add NOT NULL constraint                        |
+| `unique`        | `boolean`          | Add UNIQUE constraint                          |
+| `default`       | `string \| number` | DEFAULT value (raw SQL fragment)               |
+
+#### `db.dropTable(table, ifExists?)`
+
+```ts
+await db.dropTable("posts"); // IF EXISTS by default
+```
+
+#### `db.createIndex(indexName, table, columns, options?)`
+
+```ts
+await db.createIndex("idx_posts_title", "posts", ["title"]);
+await db.createIndex("idx_unique_email", "users", ["email"], { unique: true });
+```
+
+#### `db.dropIndex(indexName, ifExists?)`
+
+```ts
+await db.dropIndex("idx_posts_title");
+```
+
+---
+
+### Write
+
+#### `db.insert(table, data)` → `ExecResult`
+
+```ts
+const { lastInsertRowid } = await db.insert("posts", {
+  title: "Hello",
+  body: "World",
+});
+```
+
+#### `db.insertMany(table, rows)` → `ExecResult`
+
+```ts
+await db.insertMany("posts", [
+  { title: "Post 1", body: "..." },
+  { title: "Post 2", body: "..." },
+]);
+```
+
+#### `db.update(table, data, where)` → `ExecResult`
+
+```ts
+const { rowsAffected } = await db.update(
+  "posts",
+  { title: "Updated" },
+  { id: 1 }
+);
+```
+
+#### `db.delete(table, where)` → `ExecResult`
+
+```ts
+await db.delete("posts", { id: 1 });
+```
+
+---
+
+### Read
+
+#### `db.find<T>(table, where?, options?)` → `T[]`
+
+```ts
+const posts = await db.find<Post>(
+  "posts",
+  { published: 1 },
+  {
+    columns: ["id", "title"],
+    orderBy: "created_at",
+    order: "DESC", // "ASC" | "DESC"
+    limit: 20,
+    offset: 0,
+  }
+);
+```
+
+#### `db.findOne<T>(table, where?)` → `T | null`
+
+```ts
+const post = await db.findOne<Post>("posts", { id: 5 });
+```
+
+#### `db.findById<T>(table, id, idColumn?)` → `T | null`
+
+```ts
+const post = await db.findById<Post>("posts", 5); // uses "id" column
+const item = await db.findById<Item>("items", "abc", "slug"); // custom PK column
+```
+
+#### `db.count(table, where?)` → `number`
+
+```ts
+const total = await db.count("posts");
+const drafts = await db.count("posts", { published: 0 });
+```
+
+#### `db.exists(table, where)` → `boolean`
+
+```ts
+const taken = await db.exists("users", { email: "alice@example.com" });
+```
+
+---
+
+### Raw SQL
+
+#### `db.exec<T>(sql, bindings?)` → `QueryResult<T> | ExecResult`
+
+```ts
+// SELECT → QueryResult
+const result = await db.exec<{ n: number }>("SELECT COUNT(*) AS n FROM posts");
+
+// DDL / DML → ExecResult
+await db.exec("CREATE INDEX IF NOT EXISTS idx_title ON posts (title)");
+```
+
+---
+
+## Architecture
+
+```
+sqlite-db-client
+├── index.ts              ← connect() factory + all public exports
+├── database.ts           ← Database class — all high-level APIs
+└── adapters/
+    ├── types.ts          ← IAdapter interface (exec only)
+    ├── http.ts           ← HttpAdapter (sqlite-db-hub over HTTP)
+    └── index.ts          ← re-exports
+```
+
+Adding a direct SQLite adapter in the future is a one-liner:
+
+```ts
+// future
+import { Database } from "sqlite-db-client";
+import { DirectAdapter } from "sqlite-db-client/adapters/direct"; // coming soon
+
+const db = new Database(new DirectAdapter({ path: "./local.db" }));
+// same API — createTable, find, insert, update, delete…
+```
+
+## License
+
+MIT
+
+## Install
+
+```bash
+npm install sqlite-db-hub-client
+```
+
+Or directly from GitHub (before the npm package is published):
+
+```bash
+npm install github:0xdps/sqlite-db-hub-client
+```
+
+## Quick start
+
+```ts
+import { createClient } from "sqlite-db-hub-client";
+
+const db = createClient({
+  url: process.env.SQLITE_DB_HUB_URL, // e.g. https://my-app.up.railway.app
+  token: process.env.SQLITE_DB_HUB_TOKEN, // ADMIN_TOKEN set on the service
+  db: "my-service", // name of the database to use
+});
+
+// Create a table
+await db.run(`
+  CREATE TABLE IF NOT EXISTS users (
+    id    INTEGER PRIMARY KEY AUTOINCREMENT,
+    email TEXT NOT NULL UNIQUE,
+    name  TEXT
+  )
+`);
+
+// Insert a row
+await db.run("INSERT INTO users (email, name) VALUES (?, ?)", [
+  "alice@example.com",
+  "Alice",
+]);
+
+// Query rows (typed)
+const users = await db.query<{ id: number; email: string; name: string }>(
+  "SELECT * FROM users"
+);
+
+// Query a single row (or null)
+const user = await db.queryOne<{ id: number; email: string }>(
+  "SELECT * FROM users WHERE email = ?",
+  ["alice@example.com"]
+);
+```
+
+## API
+
+### `createClient(options)` / `new FileDbClient(options)`
+
+| Option    | Type     | Required | Description                                           |
+| --------- | -------- | -------- | ----------------------------------------------------- |
+| `url`     | `string` | ✅       | Base URL of your sqlite-db-hub deployment             |
+| `token`   | `string` | ✅       | `ADMIN_TOKEN` configured on the sqlite-db-hub service |
+| `db`      | `string` | ✅       | Name of the database to operate on                    |
+| `timeout` | `number` | ❌       | Request timeout in ms (default: `10000`)              |
+
+---
+
+### `db.exec(sql, bindings?)`
+
+Run any SQL statement. Returns a `QueryResult` for SELECT, or an `ExecResult` for writes.
+
+```ts
+const result = await db.exec("SELECT count(*) as n FROM users");
+// { headers: [...], rows: [{ n: 1 }], rowsRead: 1 }
+```
+
+---
+
+### `db.query<T>(sql, bindings?)`
+
+Run a SELECT and return typed rows.
+
+```ts
+const rows = await db.query<{ id: number; name: string }>(
+  "SELECT id, name FROM users WHERE id > ?",
+  [5]
+);
+```
+
+---
+
+### `db.queryOne<T>(sql, bindings?)`
+
+Run a SELECT and return the first row, or `null` if no results.
+
+```ts
+const row = await db.queryOne<{ name: string }>(
+  "SELECT name FROM users WHERE id = ?",
+  [1]
+);
+```
+
+---
+
+### `db.run(sql, bindings?)`
+
+Run a write statement (INSERT, UPDATE, DELETE, CREATE, ALTER, DROP). Returns `{ rowsAffected, lastInsertRowid }`.
+
+```ts
+const { rowsAffected, lastInsertRowid } = await db.run(
+  "INSERT INTO jobs (payload) VALUES (?)",
+  [JSON.stringify({ task: "send-email" })]
+);
+```
+
+## Types
+
+```ts
+interface QueryResult<T> {
+  headers: ColumnHeader[];
+  rows: T[];
+  rowsRead: number;
+}
+
+interface ExecResult {
+  rowsAffected: number;
+  lastInsertRowid: number | null;
+}
+
+interface ColumnHeader {
+  name: string;
+  displayName: string;
+  originalType: string | null;
+}
+```
+
+## License
+
+MIT

package/dist/adapters/http.d.ts

@@ -0,0 +1,22 @@
+import type { IAdapter, RawResult } from "./types.js";
+export interface HttpAdapterOptions {
+    /** Base URL of the sqlite-db-hub deployment, e.g. https://my-app.up.railway.app */
+    url: string;
+    /** ADMIN_TOKEN configured on the sqlite-db-hub service */
+    token: string;
+    /** Name of the database to operate on */
+    db: string;
+    /** Request timeout in ms (default: 10 000) */
+    timeout?: number;
+}
+/**
+ * Adapter that executes SQL via the sqlite-db-hub HTTP API
+ * (POST /api/db/:name/exec).
+ */
+export declare class HttpAdapter implements IAdapter {
+    private readonly options;
+    private readonly http;
+    private readonly dbPath;
+    constructor(options: HttpAdapterOptions);
+    exec<T = Record<string, unknown>>(sql: string, bindings?: unknown[]): Promise<RawResult<T>>;
+}

package/dist/adapters/http.js

@@ -0,0 +1,38 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpAdapter = void 0;
+const fetch_1 = __importDefault(require("@pingpong-js/fetch"));
+/**
+ * Adapter that executes SQL via the sqlite-db-hub HTTP API
+ * (POST /api/db/:name/exec).
+ */
+class HttpAdapter {
+    constructor(options) {
+        this.options = options;
+        this.dbPath = `/api/db/${encodeURIComponent(options.db)}/exec`;
+        this.http = fetch_1.default.create({
+            baseURL: options.url.replace(/\/$/, ""),
+            timeout: options.timeout ?? 10000,
+            headers: {
+                Authorization: `Bearer ${options.token}`,
+                "Content-Type": "application/json",
+            },
+        });
+    }
+    async exec(sql, bindings) {
+        const res = await this.http.post(this.dbPath, {
+            sql,
+            ...(bindings?.length ? { bindings } : {}),
+        });
+        if (res.isError()) {
+            const body = res.data;
+            throw new Error(body?.error ??
+                `sqlite-db-hub: HTTP ${res.status} for db "${this.options.db}"`);
+        }
+        return res.data;
+    }
+}
+exports.HttpAdapter = HttpAdapter;

package/dist/adapters/index.d.ts

@@ -0,0 +1,3 @@
+export { HttpAdapter } from "./http.js";
+export type { HttpAdapterOptions } from "./http.js";
+export type { IAdapter, ColumnHeader, QueryResult, ExecResult, RawResult } from "./types.js";

package/dist/adapters/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpAdapter = void 0;
+var http_js_1 = require("./http.js");
+Object.defineProperty(exports, "HttpAdapter", { enumerable: true, get: function () { return http_js_1.HttpAdapter; } });

package/dist/adapters/types.d.ts

@@ -0,0 +1,29 @@
+/** A single column header returned by a SELECT */
+export interface ColumnHeader {
+    name: string;
+    displayName: string;
+    originalType: string | null;
+}
+/** Result of a SELECT statement */
+export interface QueryResult<T = Record<string, unknown>> {
+    headers: ColumnHeader[];
+    rows: T[];
+    rowsRead: number;
+}
+/** Result of INSERT / UPDATE / DELETE / DDL */
+export interface ExecResult {
+    rowsAffected: number;
+    lastInsertRowid: number | null;
+}
+export type RawResult<T = Record<string, unknown>> = QueryResult<T> | ExecResult;
+/**
+ * Minimal contract every adapter must fulfil.
+ * Only `exec` is required — all high-level APIs are built on top of it.
+ */
+export interface IAdapter {
+    /**
+     * Execute a SQL statement with optional positional bindings.
+     * Returns QueryResult for SELECT, ExecResult for everything else.
+     */
+    exec<T = Record<string, unknown>>(sql: string, bindings?: unknown[]): Promise<RawResult<T>>;
+}

package/dist/adapters/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/database.d.ts

@@ -0,0 +1,141 @@
+import type { IAdapter, ExecResult, RawResult } from "./adapters/types.js";
+export type WhereClause = Record<string, unknown>;
+export type OrderDirection = "ASC" | "DESC";
+export interface FindOptions {
+    /** Columns to SELECT (default: all) */
+    columns?: string[];
+    orderBy?: string;
+    order?: OrderDirection;
+    limit?: number;
+    offset?: number;
+}
+export interface ColumnDef {
+    name: string;
+    type: "INTEGER" | "TEXT" | "REAL" | "BLOB" | "NUMERIC" | string;
+    primaryKey?: boolean;
+    autoIncrement?: boolean;
+    notNull?: boolean;
+    unique?: boolean;
+    default?: string | number;
+}
+export interface CreateTableOptions {
+    ifNotExists?: boolean;
+}
+export interface CreateIndexOptions {
+    unique?: boolean;
+    ifNotExists?: boolean;
+}
+/**
+ * High-level database client.
+ * Accepts any `IAdapter` — currently `HttpAdapter`, extensible to direct
+ * SQLite (via better-sqlite3 or sql.js) without changing business code.
+ */
+export declare class Database {
+    private readonly adapter;
+    constructor(adapter: IAdapter);
+    /**
+     * Create a table.
+     *
+     * @example
+     * await db.createTable("users", [
+     *   { name: "id",    type: "INTEGER", primaryKey: true, autoIncrement: true },
+     *   { name: "email", type: "TEXT",    notNull: true, unique: true },
+     *   { name: "name",  type: "TEXT" },
+     * ]);
+     */
+    createTable(table: string, columns: ColumnDef[], options?: CreateTableOptions): Promise<ExecResult>;
+    /**
+     * Drop a table.
+     */
+    dropTable(table: string, ifExists?: boolean): Promise<ExecResult>;
+    /**
+     * Create an index on one or more columns.
+     *
+     * @example
+     * await db.createIndex("idx_users_email", "users", ["email"], { unique: true });
+     */
+    createIndex(indexName: string, table: string, columns: string[], options?: CreateIndexOptions): Promise<ExecResult>;
+    /**
+     * Drop an index.
+     */
+    dropIndex(indexName: string, ifExists?: boolean): Promise<ExecResult>;
+    /**
+     * Insert a single row.  Returns `{ rowsAffected, lastInsertRowid }`.
+     *
+     * @example
+     * const { lastInsertRowid } = await db.insert("users", { email: "a@b.com", name: "Alice" });
+     */
+    insert(table: string, data: Record<string, unknown>): Promise<ExecResult>;
+    /**
+     * Insert multiple rows in a single transaction.
+     *
+     * @example
+     * await db.insertMany("users", [
+     *   { email: "a@b.com", name: "Alice" },
+     *   { email: "b@c.com", name: "Bob" },
+     * ]);
+     */
+    insertMany(table: string, rows: Record<string, unknown>[]): Promise<ExecResult>;
+    /**
+     * Update rows matching `where`.
+     *
+     * @example
+     * await db.update("users", { name: "Bob" }, { id: 1 });
+     */
+    update(table: string, data: Record<string, unknown>, where: WhereClause): Promise<ExecResult>;
+    /**
+     * Delete rows matching `where`.
+     *
+     * @example
+     * await db.delete("users", { id: 1 });
+     */
+    delete(table: string, where: WhereClause): Promise<ExecResult>;
+    /**
+     * Find rows with optional filtering, ordering, and pagination.
+     *
+     * @example
+     * const users = await db.find<User>("users", { active: 1 }, {
+     *   columns: ["id", "email"],
+     *   orderBy: "created_at",
+     *   order: "DESC",
+     *   limit: 20,
+     *   offset: 0,
+     * });
+     */
+    find<T = Record<string, unknown>>(table: string, where?: WhereClause, options?: FindOptions): Promise<T[]>;
+    /**
+     * Find the first row matching `where`, or `null`.
+     *
+     * @example
+     * const user = await db.findOne<User>("users", { email: "a@b.com" });
+     */
+    findOne<T = Record<string, unknown>>(table: string, where?: WhereClause): Promise<T | null>;
+    /**
+     * Find a row by its primary key value (column `id` by default).
+     *
+     * @example
+     * const user = await db.findById<User>("users", 42);
+     */
+    findById<T = Record<string, unknown>>(table: string, id: unknown, idColumn?: string): Promise<T | null>;
+    /**
+     * Count rows matching `where`.
+     *
+     * @example
+     * const total = await db.count("users");
+     * const active = await db.count("users", { active: 1 });
+     */
+    count(table: string, where?: WhereClause): Promise<number>;
+    /**
+     * Check whether any row matching `where` exists.
+     */
+    exists(table: string, where: WhereClause): Promise<boolean>;
+    /**
+     * Run any raw SQL statement.
+     *
+     * @example
+     * const result = await db.exec("PRAGMA table_info(users)");
+     */
+    exec<T = Record<string, unknown>>(sql: string, bindings?: unknown[]): Promise<RawResult<T>>;
+    private _read;
+    private _write;
+}

package/dist/database.js

@@ -0,0 +1,232 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Database = void 0;
+// ── SQL builder helpers ─────────────────────────────────────────────────────
+function buildWhere(where) {
+    const keys = Object.keys(where);
+    if (keys.length === 0)
+        return { clause: "", bindings: [] };
+    const parts = keys.map((k) => `"${k}" = ?`);
+    return {
+        clause: " WHERE " + parts.join(" AND "),
+        bindings: keys.map((k) => where[k]),
+    };
+}
+function isQueryResult(r) {
+    return "rows" in r;
+}
+function isExecResult(r) {
+    return "rowsAffected" in r;
+}
+// ── Database ─────────────────────────────────────────────────────────────────
+/**
+ * High-level database client.
+ * Accepts any `IAdapter` — currently `HttpAdapter`, extensible to direct
+ * SQLite (via better-sqlite3 or sql.js) without changing business code.
+ */
+class Database {
+    constructor(adapter) {
+        this.adapter = adapter;
+    }
+    // ── Schema ──────────────────────────────────────────────────────────────
+    /**
+     * Create a table.
+     *
+     * @example
+     * await db.createTable("users", [
+     *   { name: "id",    type: "INTEGER", primaryKey: true, autoIncrement: true },
+     *   { name: "email", type: "TEXT",    notNull: true, unique: true },
+     *   { name: "name",  type: "TEXT" },
+     * ]);
+     */
+    async createTable(table, columns, options = {}) {
+        const ifNotExists = options.ifNotExists !== false ? "IF NOT EXISTS" : "";
+        const cols = columns.map((c) => {
+            let def = `"${c.name}" ${c.type}`;
+            if (c.primaryKey)
+                def += " PRIMARY KEY";
+            if (c.autoIncrement)
+                def += " AUTOINCREMENT";
+            if (c.notNull)
+                def += " NOT NULL";
+            if (c.unique)
+                def += " UNIQUE";
+            if (c.default !== undefined)
+                def += ` DEFAULT ${c.default}`;
+            return def;
+        });
+        const sql = `CREATE TABLE ${ifNotExists} "${table}" (${cols.join(", ")})`;
+        return this._write(sql);
+    }
+    /**
+     * Drop a table.
+     */
+    async dropTable(table, ifExists = true) {
+        const ie = ifExists ? "IF EXISTS" : "";
+        return this._write(`DROP TABLE ${ie} "${table}"`);
+    }
+    /**
+     * Create an index on one or more columns.
+     *
+     * @example
+     * await db.createIndex("idx_users_email", "users", ["email"], { unique: true });
+     */
+    async createIndex(indexName, table, columns, options = {}) {
+        const unique = options.unique ? "UNIQUE" : "";
+        const ifNotExists = options.ifNotExists !== false ? "IF NOT EXISTS" : "";
+        const cols = columns.map((c) => `"${c}"`).join(", ");
+        const sql = `CREATE ${unique} INDEX ${ifNotExists} "${indexName}" ON "${table}" (${cols})`;
+        return this._write(sql);
+    }
+    /**
+     * Drop an index.
+     */
+    async dropIndex(indexName, ifExists = true) {
+        const ie = ifExists ? "IF EXISTS" : "";
+        return this._write(`DROP INDEX ${ie} "${indexName}"`);
+    }
+    // ── Write ────────────────────────────────────────────────────────────────
+    /**
+     * Insert a single row.  Returns `{ rowsAffected, lastInsertRowid }`.
+     *
+     * @example
+     * const { lastInsertRowid } = await db.insert("users", { email: "a@b.com", name: "Alice" });
+     */
+    async insert(table, data) {
+        const keys = Object.keys(data);
+        const cols = keys.map((k) => `"${k}"`).join(", ");
+        const placeholders = keys.map(() => "?").join(", ");
+        const bindings = keys.map((k) => data[k]);
+        return this._write(`INSERT INTO "${table}" (${cols}) VALUES (${placeholders})`, bindings);
+    }
+    /**
+     * Insert multiple rows in a single transaction.
+     *
+     * @example
+     * await db.insertMany("users", [
+     *   { email: "a@b.com", name: "Alice" },
+     *   { email: "b@c.com", name: "Bob" },
+     * ]);
+     */
+    async insertMany(table, rows) {
+        if (rows.length === 0)
+            return { rowsAffected: 0, lastInsertRowid: null };
+        const keys = Object.keys(rows[0]);
+        const cols = keys.map((k) => `"${k}"`).join(", ");
+        const rowPlaceholders = rows.map(() => `(${keys.map(() => "?").join(", ")})`).join(", ");
+        const bindings = rows.flatMap((row) => keys.map((k) => row[k]));
+        return this._write(`INSERT INTO "${table}" (${cols}) VALUES ${rowPlaceholders}`, bindings);
+    }
+    /**
+     * Update rows matching `where`.
+     *
+     * @example
+     * await db.update("users", { name: "Bob" }, { id: 1 });
+     */
+    async update(table, data, where) {
+        const setKeys = Object.keys(data);
+        const setClauses = setKeys.map((k) => `"${k}" = ?`).join(", ");
+        const setBindings = setKeys.map((k) => data[k]);
+        const { clause, bindings: whereBindings } = buildWhere(where);
+        return this._write(`UPDATE "${table}" SET ${setClauses}${clause}`, [...setBindings, ...whereBindings]);
+    }
+    /**
+     * Delete rows matching `where`.
+     *
+     * @example
+     * await db.delete("users", { id: 1 });
+     */
+    async delete(table, where) {
+        const { clause, bindings } = buildWhere(where);
+        return this._write(`DELETE FROM "${table}"${clause}`, bindings);
+    }
+    // ── Read ─────────────────────────────────────────────────────────────────
+    /**
+     * Find rows with optional filtering, ordering, and pagination.
+     *
+     * @example
+     * const users = await db.find<User>("users", { active: 1 }, {
+     *   columns: ["id", "email"],
+     *   orderBy: "created_at",
+     *   order: "DESC",
+     *   limit: 20,
+     *   offset: 0,
+     * });
+     */
+    async find(table, where = {}, options = {}) {
+        const cols = options.columns?.map((c) => `"${c}"`).join(", ") ?? "*";
+        const { clause, bindings } = buildWhere(where);
+        let sql = `SELECT ${cols} FROM "${table}"${clause}`;
+        if (options.orderBy)
+            sql += ` ORDER BY "${options.orderBy}" ${options.order ?? "ASC"}`;
+        if (options.limit !== undefined)
+            sql += ` LIMIT ${options.limit}`;
+        if (options.offset !== undefined)
+            sql += ` OFFSET ${options.offset}`;
+        return this._read(sql, bindings);
+    }
+    /**
+     * Find the first row matching `where`, or `null`.
+     *
+     * @example
+     * const user = await db.findOne<User>("users", { email: "a@b.com" });
+     */
+    async findOne(table, where = {}) {
+        const rows = await this.find(table, where, { limit: 1 });
+        return rows[0] ?? null;
+    }
+    /**
+     * Find a row by its primary key value (column `id` by default).
+     *
+     * @example
+     * const user = await db.findById<User>("users", 42);
+     */
+    async findById(table, id, idColumn = "id") {
+        return this.findOne(table, { [idColumn]: id });
+    }
+    /**
+     * Count rows matching `where`.
+     *
+     * @example
+     * const total = await db.count("users");
+     * const active = await db.count("users", { active: 1 });
+     */
+    async count(table, where = {}) {
+        const { clause, bindings } = buildWhere(where);
+        const sql = `SELECT COUNT(*) AS n FROM "${table}"${clause}`;
+        const rows = await this._read(sql, bindings);
+        return rows[0]?.n ?? 0;
+    }
+    /**
+     * Check whether any row matching `where` exists.
+     */
+    async exists(table, where) {
+        return (await this.count(table, where)) > 0;
+    }
+    // ── Raw escape hatch ─────────────────────────────────────────────────────
+    /**
+     * Run any raw SQL statement.
+     *
+     * @example
+     * const result = await db.exec("PRAGMA table_info(users)");
+     */
+    async exec(sql, bindings) {
+        return this.adapter.exec(sql, bindings);
+    }
+    // ── Internal ─────────────────────────────────────────────────────────────
+    async _read(sql, bindings) {
+        const result = await this.adapter.exec(sql, bindings);
+        if (!isQueryResult(result)) {
+            throw new Error(`sqlite-db-hub: expected SELECT, got write result for: ${sql}`);
+        }
+        return result.rows;
+    }
+    async _write(sql, bindings) {
+        const result = await this.adapter.exec(sql, bindings);
+        if (!isExecResult(result)) {
+            throw new Error(`sqlite-db-hub: expected write result, got SELECT for: ${sql}`);
+        }
+        return result;
+    }
+}
+exports.Database = Database;

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+export { Database } from "./database.js";
+export type { WhereClause, FindOptions, ColumnDef, CreateTableOptions, CreateIndexOptions, OrderDirection, } from "./database.js";
+export { HttpAdapter } from "./adapters/http.js";
+export type { HttpAdapterOptions } from "./adapters/http.js";
+export type { IAdapter, ColumnHeader, QueryResult, ExecResult, RawResult, } from "./adapters/types.js";
+import { Database } from "./database.js";
+import { type HttpAdapterOptions } from "./adapters/http.js";
+/**
+ * Create a Database connected to a sqlite-db-hub service over HTTP.
+ *
+ * @example
+ * const db = connect({
+ *   url:   process.env.SQLITE_DB_HUB_URL,
+ *   token: process.env.SQLITE_DB_HUB_TOKEN,
+ *   db:    "my-service",
+ * });
+ */
+export declare function connect(options: HttpAdapterOptions): Database;
+export default connect;

package/dist/index.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpAdapter = exports.Database = void 0;
+exports.connect = connect;
+var database_js_1 = require("./database.js");
+Object.defineProperty(exports, "Database", { enumerable: true, get: function () { return database_js_1.Database; } });
+var http_js_1 = require("./adapters/http.js");
+Object.defineProperty(exports, "HttpAdapter", { enumerable: true, get: function () { return http_js_1.HttpAdapter; } });
+// ── Convenience factory ──────────────────────────────────────────────────────
+const database_js_2 = require("./database.js");
+const http_js_2 = require("./adapters/http.js");
+/**
+ * Create a Database connected to a sqlite-db-hub service over HTTP.
+ *
+ * @example
+ * const db = connect({
+ *   url:   process.env.SQLITE_DB_HUB_URL,
+ *   token: process.env.SQLITE_DB_HUB_TOKEN,
+ *   db:    "my-service",
+ * });
+ */
+function connect(options) {
+    return new database_js_2.Database(new http_js_2.HttpAdapter(options));
+}
+exports.default = connect;

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "sqlite-hub-client",
+  "version": "0.2.0",
+  "description": "High-level SQLite client for sqlite-db-hub — HTTP adapter included, direct SQLite coming soon",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsc"
+  },
+  "keywords": ["sqlite", "sqlite-db-hub", "railway", "orm", "database"],
+  "license": "MIT",
+  "dependencies": {
+    "@pingpong-js/fetch": "^1.0.2"
+  },
+  "devDependencies": {
+    "typescript": "^5"
+  }
+}