basaltdb 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maniarasan Sivaseran and Basalt contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,116 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/basalt-db/basalt/main/docs/basalt-icon.png" alt="Basalt" width="96" height="96">
+</p>
+
+# basaltdb — JavaScript/TypeScript client for Basalt
+
+Use [Basalt](https://github.com/basalt-db/basalt) from Node or the
+browser. Two modes, one API:
+
+- **Embedded** (in-process, WebAssembly — like `sql.js`): the whole engine runs
+  in your process, no server. The database lives in memory. Great for tests,
+  demos, notebooks, and browser apps.
+- **Client/server**: talk to a running `basalt` server over HTTP for a
+  persistent, disk-backed database.
+
+The WASM binary is bundled **inside** the package (single file, base64-embedded),
+so there are no extra assets to host or `fetch` — it just works in Node and
+bundlers.
+
+```bash
+npm install basaltdb
+```
+
+## Embedded (in-process)
+
+```js
+import { Basalt } from 'basaltdb';
+
+const db = await Basalt.create();            // in-memory, seeded with a demo dataset
+db.exec('CREATE TABLE t (id BIGINT PRIMARY KEY, name VARCHAR, qty INT)');
+db.exec("INSERT INTO t (id, name, qty) VALUES (1, 'widget', 5)");
+
+db.query('SELECT * FROM t');                 // -> [{ id: 1, name: 'widget', qty: 5 }]
+const r = db.exec('SELECT COUNT(*) AS c FROM t');
+console.log(r.stats.ms, r.stats.access);     // timing + access method
+```
+
+`exec()` returns the full result object: `{ columns, types, rows, total_rows,
+truncated, stats, plan, message? }`, plus `.toObjects()`. `query()` is shorthand
+for `exec(sql).toObjects()`.
+
+## Client/server (HTTP)
+
+```js
+import { BasaltClient } from 'basaltdb';
+
+const db = new BasaltClient('http://127.0.0.1:8090', { db: 'mydb' });
+await db.query('SELECT * FROM users ORDER BY id');
+await db.databases();                        // list served databases
+await db.schema();                           // tables + columns
+```
+
+In Node < 18 (no global `fetch`) pass one: `new BasaltClient(url, { fetch })`.
+
+## Query builder (ORM-lite)
+
+A small fluent builder that generates SQL. It works the same on both `Basalt`
+(sync) and `BasaltClient` (async) — `await` works in both cases:
+
+```js
+await db.table('users').select('id', 'name').where('tier', '>', 1).orderBy('id', 'DESC').all();
+await db.table('users').where('id', 1).first();
+db.table('users').insert({ id: 4, name: 'dana', tier: 2 });
+db.table('users').insert([{ id: 5, name: 'e' }, { id: 6, name: 'f' }]);
+db.table('users').where('id', 6).update({ tier: 3 });
+db.table('users').where('id', 6).delete();
+```
+
+Values are escaped (`lit()`); **identifiers are never taken from user input**.
+Call `.toSQL()` on any builder to see the generated statement.
+
+## What Basalt supports (and doesn't, yet)
+
+This is a young, learning-oriented engine — the builder deliberately stays close
+to what the SQL engine actually does:
+
+- ✅ `SELECT` with `WHERE` / `GROUP BY` / aggregates / `ORDER BY` / `LIMIT`,
+  `INNER`/`LEFT JOIN`, `INSERT` (positional or column-list), `UPDATE`, `DELETE`,
+  `CREATE/DROP TABLE`, `CREATE/DROP INDEX`.
+- ⛔ No transactions, no subqueries/CTEs/window functions, no prepared
+  statements yet (see the [roadmap](https://github.com/basalt-db/basalt/blob/main/ROADMAP.md)).
+  That's why this is a query builder rather than a full ORM adapter — a Prisma /
+  Sequelize / Drizzle dialect will land once transactions and richer SQL do.
+
+## API
+
+- `Basalt.create()` → `Promise<Basalt>` — embedded in-memory engine.
+- `db.exec(sql)` → `Result` · `db.query(sql)` → `object[]` · `db.schema()` → tables.
+- `new BasaltClient(url, { db, fetch })` — async `exec` / `query` / `databases` /
+  `schema` / `createDatabase` / `dropDatabase` / `use(db)`.
+- `db.table(name)` → builder: `select`, `where`, `orderBy`, `limit`, `all`,
+  `first`, `insert`, `update`, `delete`, `toSQL`.
+- `lit(value)` — SQL literal formatting; `BasaltError` — thrown on engine errors.
+
+## Building `src/engine.js`
+
+`src/engine.js` is the Basalt C++ engine compiled to a single-file ESM WebAssembly
+bundle (base64-embedded), vendored here so `npm install` needs no toolchain. It's
+generated from the engine sources in the **[main Basalt repo](https://github.com/basalt-db/basalt)**
+(`src/`) with emscripten:
+
+```bash
+# in a checkout of basalt-db/basalt
+emcc -std=c++17 -O3 -fexceptions -I src \
+  src/logical.cpp src/storage.cpp src/sql.cpp src/exec.cpp \
+  src/exec_join.cpp src/database.cpp src/wasm.cpp \
+  -sMODULARIZE=1 -sEXPORT_ES6=1 -sSINGLE_FILE=1 -sENVIRONMENT=web,node \
+  -sEXPORT_NAME=createBasalt -sEXPORTED_RUNTIME_METHODS=ccall,cwrap \
+  -sEXPORTED_FUNCTIONS=_hydb_exec,_hydb_schema,_hydb_init,_malloc,_free \
+  -sALLOW_MEMORY_GROWTH=1 -sINITIAL_MEMORY=64MB -o engine.js
+# then copy engine.js -> this repo's src/engine.js
+```
+
+Run the smoke test (embedded engine, no server): `npm test`.
+
+MIT. Part of the [Basalt](https://github.com/basalt-db/basalt) project.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "basaltdb",
+  "version": "0.1.0",
+  "description": "Official JavaScript/TypeScript client for Basalt — a from-scratch HTAP database engine. Run it embedded in-process via WebAssembly (Node & browser), or talk to a Basalt server over HTTP.",
+  "type": "module",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "files": [
+    "src/index.js",
+    "src/index.d.ts",
+    "src/engine.js",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node test/smoke.mjs",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "database", "sql", "htap", "olap", "oltp", "columnar", "wasm",
+    "webassembly", "embedded-database", "basalt", "in-memory", "analytics"
+  ],
+  "homepage": "https://github.com/basalt-db/basalt-js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/basalt-db/basalt-js.git"
+  },
+  "bugs": { "url": "https://github.com/basalt-db/basalt-js/issues" },
+  "license": "MIT",
+  "engines": { "node": ">=18" },
+  "sideEffects": false
+}