basaltdb 0.1.0

package/src/index.d.ts

@@ -0,0 +1,68 @@
+// Type definitions for basaltdb
+
+export class BasaltError extends Error {}
+
+export interface ColumnInfo { name: string; type: string; pk: boolean; indexed: boolean; }
+export interface TableInfo { name: string; nrows: number; columns: ColumnInfo[]; }
+export interface QueryStats {
+  scanned: number; matched: number; used_pk_index: boolean; access: string; ms: number;
+}
+export interface Result {
+  columns: string[];
+  types: string[];
+  rows: Array<Array<string | number | boolean | null>>;
+  total_rows: number;
+  truncated: boolean;
+  stats: QueryStats;
+  plan: string[];
+  message?: string;
+  /** Rows as `{ column: value }` objects. */
+  toObjects(): Array<Record<string, string | number | boolean | null>>;
+}
+
+export type Value = string | number | boolean | Date | null | undefined;
+
+export class QueryBuilder {
+  select(...cols: string[]): this;
+  where(col: string, op: string, val: Value): this;
+  where(col: string, val: Value): this;
+  orderBy(col: string, dir?: 'ASC' | 'DESC' | 'asc' | 'desc'): this;
+  limit(n: number): this;
+  toSQL(): string;
+  all(): Promise<Record<string, any>[]> | Record<string, any>[];
+  first(): Promise<Record<string, any> | null> | (Record<string, any> | null);
+  insert(rows: Record<string, Value> | Record<string, Value>[]): Promise<Result> | Result;
+  update(patch: Record<string, Value>): Promise<Result> | Result;
+  delete(): Promise<Result> | Result;
+}
+
+/** Embedded, in-process (WebAssembly) database. */
+export class Basalt {
+  static create(): Promise<Basalt>;
+  exec(sql: string): Result;
+  query(sql: string): Record<string, any>[];
+  schema(): TableInfo[];
+  table(name: string): QueryBuilder;
+}
+
+export interface BasaltClientOptions {
+  db?: string;
+  fetch?: typeof fetch;
+}
+
+/** Client for a running `basalt` server (HTTP). */
+export class BasaltClient {
+  constructor(baseUrl?: string, opts?: BasaltClientOptions);
+  db: string;
+  exec(sql: string, db?: string): Promise<Result>;
+  query(sql: string, db?: string): Promise<Record<string, any>[]>;
+  databases(): Promise<string[]>;
+  schema(db?: string): Promise<TableInfo[]>;
+  createDatabase(name: string): Promise<any>;
+  dropDatabase(name: string): Promise<any>;
+  use(db: string): this;
+  table(name: string): QueryBuilder;
+}
+
+export function lit(v: Value): string;
+export default Basalt;

package/src/index.js

@@ -0,0 +1,160 @@
+// basaltdb — official JavaScript/TypeScript client for the Basalt database.
+//
+// Two ways to use it:
+//   1. Embedded (in-process, WebAssembly) — like sql.js. Runs in Node and the
+//      browser, no server. The database lives in memory for the process lifetime.
+//        import { Basalt } from 'basaltdb';
+//        const db = await Basalt.create();
+//        db.exec("CREATE TABLE t (id BIGINT PRIMARY KEY, v INT)");
+//   2. Client/server — talk to a running `basalt` server over HTTP (persistent).
+//        import { BasaltClient } from 'basaltdb';
+//        const db = new BasaltClient('http://127.0.0.1:8090', { db: 'mydb' });
+//
+// Both expose the same query surface (exec / query / a small query builder), so
+// code can move between embedded and server with minimal changes.
+import createBasalt from './engine.js';
+
+export class BasaltError extends Error {
+  constructor(message) { super(message); this.name = 'BasaltError'; }
+}
+
+// Attach convenience accessors to a raw result object from the engine/server.
+// Raw shape: { columns, types, rows, total_rows, truncated, stats, plan, message?, error? }
+function shape(r) {
+  if (r && r.error) throw new BasaltError(r.error);
+  Object.defineProperty(r, 'toObjects', {
+    enumerable: false,
+    value() {
+      const cols = r.columns || [];
+      return (r.rows || []).map(row => {
+        const o = {};
+        for (let i = 0; i < cols.length; i++) o[cols[i]] = row[i];
+        return o;
+      });
+    },
+  });
+  return r;
+}
+
+// Await-through: works whether `v` is a value (embedded) or a Promise (HTTP).
+function then(v, f) { return v && typeof v.then === 'function' ? v.then(f) : f(v); }
+
+// SQL literal formatting (values only — identifiers are never taken from input).
+export function lit(v) {
+  if (v === null || v === undefined) return 'NULL';
+  if (typeof v === 'number') return Number.isFinite(v) ? String(v) : 'NULL';
+  if (typeof v === 'boolean') return v ? 'TRUE' : 'FALSE';
+  if (v instanceof Date) return `'${v.toISOString().slice(0, 19).replace('T', ' ')}'`;
+  return `'${String(v).replace(/'/g, "''")}'`;
+}
+
+// ---- fluent query builder (ORM-lite) -------------------------------------
+// Generates SQL and runs it through whichever runner created it. Not a full ORM
+// (see the README for what Basalt's SQL surface does and doesn't support yet).
+class QueryBuilder {
+  constructor(runner, table) {
+    this._r = runner; this._t = table;
+    this._sel = '*'; this._where = []; this._order = null; this._limit = null;
+  }
+  select(...cols) { this._sel = cols.length ? cols.join(', ') : '*'; return this; }
+  where(col, op, val) {
+    if (val === undefined) { val = op; op = '='; }   // .where('id', 1) → id = 1
+    this._where.push(`${col} ${op} ${lit(val)}`); return this;
+  }
+  orderBy(col, dir = 'ASC') { this._order = `${col} ${String(dir).toUpperCase()}`; return this; }
+  limit(n) { this._limit = n | 0; return this; }
+
+  toSQL() {
+    let s = `SELECT ${this._sel} FROM ${this._t}`;
+    if (this._where.length) s += ` WHERE ${this._where.join(' AND ')}`;
+    if (this._order) s += ` ORDER BY ${this._order}`;
+    if (this._limit != null) s += ` LIMIT ${this._limit}`;
+    return s;
+  }
+  /** Run the SELECT and return an array of row objects. */
+  all() { return then(this._r._run(this.toSQL()), r => r.toObjects()); }
+  /** Run the SELECT and return the first row object (or null). */
+  first() { this.limit(1); return then(this.all(), rows => rows[0] ?? null); }
+
+  /** INSERT one object or an array of objects. */
+  insert(rows) {
+    const list = Array.isArray(rows) ? rows : [rows];
+    if (!list.length) throw new BasaltError('insert(): no rows');
+    const cols = Object.keys(list[0]);
+    const vals = list.map(o => `(${cols.map(c => lit(o[c])).join(', ')})`).join(', ');
+    return this._r._run(`INSERT INTO ${this._t} (${cols.join(', ')}) VALUES ${vals}`);
+  }
+  /** UPDATE with the accumulated WHERE. */
+  update(patch) {
+    const set = Object.keys(patch).map(c => `${c} = ${lit(patch[c])}`).join(', ');
+    let s = `UPDATE ${this._t} SET ${set}`;
+    if (this._where.length) s += ` WHERE ${this._where.join(' AND ')}`;
+    return this._r._run(s);
+  }
+  /** DELETE with the accumulated WHERE. */
+  delete() {
+    let s = `DELETE FROM ${this._t}`;
+    if (this._where.length) s += ` WHERE ${this._where.join(' AND ')}`;
+    return this._r._run(s);
+  }
+}
+
+// ---- embedded engine (WASM, in-process) ----------------------------------
+export class Basalt {
+  constructor(mod) {
+    this._m = mod;
+    this._exec = mod.cwrap('hydb_exec', 'string', ['string']);
+    this._schemaFn = mod.cwrap('hydb_schema', 'string', []);
+  }
+  /** Create an in-memory Basalt database (seeded with a small demo dataset). */
+  static async create() {
+    const mod = await createBasalt();
+    mod.ccall('hydb_init');
+    return new Basalt(mod);
+  }
+  /** Execute one SQL statement; returns the full result object (throws BasaltError on error). */
+  exec(sql) { return shape(JSON.parse(this._exec(String(sql)))); }
+  _run(sql) { return this.exec(sql); }
+  /** Execute a SELECT and return an array of row objects. */
+  query(sql) { return this.exec(sql).toObjects(); }
+  /** Current schema: [{ name, nrows, columns:[{name,type,pk,indexed}] }]. */
+  schema() { return JSON.parse(this._schemaFn()).tables; }
+  /** Start a query builder on a table. */
+  table(name) { return new QueryBuilder(this, name); }
+}
+
+// ---- HTTP client (talks to a running `basalt` server) --------------------
+export class BasaltClient {
+  constructor(baseUrl = 'http://127.0.0.1:8090', opts = {}) {
+    this.base = String(baseUrl).replace(/\/+$/, '');
+    this.db = opts.db || '';
+    this._fetch = opts.fetch || globalThis.fetch;
+    if (!this._fetch) throw new BasaltError('no fetch available; pass opts.fetch');
+  }
+  async _post(path, body) {
+    const res = await this._fetch(this.base + path, { method: 'POST', body: body ?? '' });
+    return res.json();
+  }
+  async _get(path) { const res = await this._fetch(this.base + path); return res.json(); }
+
+  /** Execute one SQL statement against `db` (defaults to the client's db). */
+  async exec(sql, db = this.db) {
+    return shape(await this._post(`/api/query?db=${encodeURIComponent(db)}`, String(sql)));
+  }
+  _run(sql) { return this.exec(sql); }
+  async query(sql, db) { return (await this.exec(sql, db)).toObjects(); }
+
+  /** List database directories the server is serving. */
+  databases() { return this._get('/api/databases'); }
+  /** Schema for a database. */
+  async schema(db = this.db) { return (await this._get(`/api/schema?db=${encodeURIComponent(db)}`)).tables; }
+  createDatabase(name) { return this._post(`/api/create_db?db=${encodeURIComponent(name)}`); }
+  dropDatabase(name) { return this._post(`/api/drop_db?db=${encodeURIComponent(name)}`); }
+
+  /** Use a specific database for subsequent calls (returns this). */
+  use(db) { this.db = db; return this; }
+  /** Start a query builder on a table. */
+  table(name) { return new QueryBuilder(this, name); }
+}
+
+export default Basalt;