wasm

@joaoh82/sqlrite-wasm

WebAssembly build of the SQLRite embedded database engine. Runs entirely in a browser tab — no server, no backend — via wasm-pack / wasm-bindgen.

Why the scoped name? Same reason as @joaoh82/sqlrite (the Node SDK): the unscoped form risks tripping npm's similarity check against sqlite-wasm / sqlite. Scoping under @joaoh82 is the standard Node ecosystem pattern (@napi-rs/*, @swc/*, etc.).

Install

npm install @joaoh82/sqlrite-wasm

The npm package ships the bundler target (webpack / vite / rollup / parcel-friendly). For other build targets, build locally from a repo clone:

# From a repo checkout:
cd sdk/wasm
wasm-pack build --target web --release      # → pkg/, ES modules for direct browser use
# …or for a bundler (Webpack / Vite):
wasm-pack build --target bundler --release
# …or for Node.js:
wasm-pack build --target nodejs --release

Quick tour

import init, { Database } from '@joaoh82/sqlrite-wasm';

// Async init — fetches the .wasm file and wires up memory.
// Nothing else in the module works until this resolves.
await init();

const db = new Database();   // always in-memory in the WASM build

db.exec("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, age INTEGER)");
db.exec("INSERT INTO users (name, age) VALUES ('alice', 30)");

const rows = db.query("SELECT id, name, age FROM users");
// → [{ id: 1, name: 'alice', age: 30 }]

See ../../examples/wasm/ for a runnable HTML demo — a tiny SQL console that make build && make serve spins up on http://localhost:8080.

Transactions

db.exec("BEGIN");
db.exec("INSERT INTO users (name) VALUES ('carol')");
if (looksGood) {
    db.exec("COMMIT");
} else {
    db.exec("ROLLBACK");    // restores pre-BEGIN state
}

console.log(db.inTransaction);  // false once COMMIT / ROLLBACK runs

Vector columns + KNN (Phase 7a–7d)

VECTOR(N) storage class plus vec_distance_l2 / vec_distance_cosine / vec_distance_dot distance functions. Vector literals are bracket arrays.

db.exec("CREATE TABLE docs (id INTEGER PRIMARY KEY, embedding VECTOR(384))");
db.exec("INSERT INTO docs (id, embedding) VALUES (1, [0.1, 0.2, ..., 0.0])");

const top10 = db.query(`
  SELECT id FROM docs
   ORDER BY vec_distance_l2(embedding, [0.1, 0.2, ..., 0.0])
   LIMIT 10
`);

HNSW indexes work in the WASM build too — CPU-only, no SIMD on wasm32, but algorithmically identical:

db.exec("CREATE INDEX idx_docs_emb ON docs USING hnsw (embedding)");

JSON columns (Phase 7e)

JSON / JSONB columns are validated at INSERT time. Use json_extract / json_type / json_array_length / json_object_keys. Path subset: $, .key, [N], chained.

db.exec("CREATE TABLE events (id INTEGER PRIMARY KEY, payload JSON)");
db.exec(`INSERT INTO events (payload) VALUES ('{"user": {"name": "alice"}, "score": 42}')`);

const rows = db.query(`SELECT json_extract(payload, '$.user.name') AS name FROM events`);
// → [{ name: 'alice' }]

Natural-language → SQL (Phase 7g.7)

Per Phase 7 plan Q9, the WASM SDK has a different ask() shape than the other SDKs. The WASM module does the schema-aware prompt construction in-page, but does NOT make the HTTP request itself. The caller's JS code does the call, typically routed through their own backend.

Why this design

Two reasons direct browser-to-LLM calls don't work:

1. CORS. Browsers block direct cross-origin POSTs from a WASM module to api.anthropic.com / api.openai.com unless the LLM provider serves CORS headers. They don't, by design — they don't want users embedding API keys in client-side JS.
2. API key exposure. Even if CORS were OK, putting the API key into a WASM-loaded page exposes it to anyone who opens devtools.

Both problems disappear server-side. Node, Python, Go, Desktop (Tauri runs the call in the Rust backend, not the webview) all do the HTTP from a trusted process. WASM solves it with a split: the browser tab does the prompt building (it has the schema and the rules), then hands the request to the user's backend which holds the API key.

Two-step API

import init, { Database } from '@joaoh82/sqlrite-wasm';
await init();

const db = new Database();
db.exec(`CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, age INTEGER)`);

// Step 1 — build the LLM-API request body in the browser.
const payload = db.askPrompt('How many users are over 30?');
// payload looks like:
// {
//   model: 'claude-sonnet-4-6',
//   max_tokens: 1024,
//   system: [
//     { type: 'text', text: '<rules block>' },
//     { type: 'text', text: '<schema>...</schema>',
//       cache_control: { type: 'ephemeral' } }
//   ],
//   messages: [{ role: 'user', content: 'How many users are over 30?' }]
// }

// Step 2 — your backend forwards this to Anthropic with your API key.
const apiResponse = await fetch('/api/llm/complete', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(payload),
}).then(r => r.text());     // raw response body string

// Step 3 — hand the raw API response back to WASM.
const result = db.askParse(apiResponse);
// → { sql: 'SELECT id, name FROM users WHERE age > 30',
//     explanation: 'Counts users older than thirty.',
//     usage: { inputTokens, outputTokens, cacheCreationInputTokens, cacheReadInputTokens } }

// Now run the SQL however you want.
const rows = db.query(result.sql);

Backend proxy (the bit you write)

The WASM SDK is provider-agnostic at the JS boundary, but askPrompt's default output shape is Anthropic's /v1/messages body, so you can forward it as-is to Anthropic. Your backend just needs to:

1. Receive the JSON payload from the browser.
2. Add the x-api-key header from your secure storage.
3. POST to https://api.anthropic.com/v1/messages.
4. Pipe the response body back to the browser.

A minimal Node/Express version:

import express from 'express';
const app = express();
app.use(express.json());

app.post('/api/llm/complete', async (req, res) => {
  const upstream = await fetch('https://api.anthropic.com/v1/messages', {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      'x-api-key': process.env.ANTHROPIC_API_KEY,
      'anthropic-version': '2023-06-01',
    },
    body: JSON.stringify(req.body),
  });
  res.status(upstream.status);
  res.set('content-type', 'application/json');
  res.send(await upstream.text());
});

app.listen(3000);

A minimal Cloudflare Worker / Vercel Edge function is essentially identical — read JSON in, forward with the key header, pass the response body through. The API key stays on the server; the browser never sees it.

Ready-to-deploy templates for Cloudflare Workers, Vercel Edge Functions, Deno Deploy, Firebase Functions, AWS Lambda, and Express live in docs/ask-backend-examples.md. For the broader Ask-feature reference (every SDK, env vars, defaults, prompt caching, security model), see docs/ask.md. A runnable end-to-end demo (browser + zero-dep Node proxy) lives at examples/wasm/ — make build && make ask-demo.

askPrompt options

import { AskPromptOptions } from '@joaoh82/sqlrite-wasm';

const opts = new AskPromptOptions();
opts.model = 'claude-haiku-4-5';   // default: 'claude-sonnet-4-6'
opts.max_tokens = 512;             // default: 1024
opts.cache_ttl = '1h';             // default: '5m', also '1h' or 'off'

const payload = db.askPrompt('How many users?', opts);

Using a non-Anthropic provider on your backend

askPrompt produces an Anthropic-shaped body. If your backend talks to OpenAI / Ollama / etc., translate the body server-side before forwarding (the system blocks → system message, messages array stays the same shape). The token-usage fields in askParse's output read from Anthropic's usage shape too — for non-Anthropic responses, your backend can normalize the response into that shape before returning it to the browser.

OpenAI / Ollama / Together / ... bindings are tracked in the broader Phase 7 roadmap (docs/phase-7-plan.md Q4); the WASM SDK's split design means provider variety lives entirely on your backend, with no SDK changes needed.

Verifying prompt-cache hits

The result.usage.cacheReadInputTokens field in askParse's output reports tokens served from Anthropic's prompt cache. After the first askPrompt call against a given schema, repeat calls within 5 minutes (1 hour with cacheTtl: '1h') should show non-zero cacheReadInputTokens. If it stays zero, something in the prefix is invalidating the cache — most likely a timestamp / UUID / non-deterministic field bleeding into the system blocks. The WASM SDK builds the same schema dump the other SDKs do (alphabetically sorted, byte-stable), so as long as your DB schema doesn't change between calls, caching should work.

API surface

JS	Purpose
new Database()	In-memory DB (only mode in the WASM build)
db.exec(sql)	DDL / DML / BEGIN / COMMIT / ROLLBACK — no return
db.query(sql)	SELECT — returns Array<Object>, one entry per row
db.columns(sql)	Column names a SELECT would produce
db.inTransaction (getter)	true inside BEGIN/…/COMMIT
db.readonly (getter)	Always false (no RO path in WASM)
db.free()	Releases the underlying state before GC

Rows come back as plain objects keyed by column name, matching the Node.js SDK's shape. Projection order is preserved (Object.keys(row) matches the SELECT list).

Scope of the MVP

• In-memory only. Connection::open(path) doesn't have a reasonable browser semantic — the OS file locks and -wal sidecar that file-backed mode needs don't exist in a tab's sandbox. We only expose Connection::open_in_memory(). Persistence via the browser's OPFS (Origin Private File System) is a natural follow-up but out of scope here.
• No prepared-statement object. Unlike the Python / Node / Go / Rust SDKs, the WASM build collapses prepare → step → finalize into the one-shot db.query(sql). The engine still does the work internally; JS just sees a single call. The added objects + lifetimes don't earn their keep in the in-memory MVP.
• Parameter binding follows the same "not yet, 5a.2 will add it" story as every other SDK.

Build sizes

A release build (wasm-pack build --target web --release) produces roughly:

File	Size (before gzip)
sqlrite_wasm_bg.wasm	~1.8 MB
sqlrite_wasm.js (glue)	~14 KB

The wasm gzips to ~500 KB; browsers serve it compressed.

How this is wired

• Depends on sqlrite with default-features = false, so the cli feature (rustyline + clap + env_logger — not wasm-safe) and file-locks feature (fs2 — no POSIX flock in wasm32) are both off. The engine's file-locking code is #[cfg]-gated behind file-locks and compiles to a no-op when the feature is absent.
• console_error_panic_hook (default-on feature) turns Rust panics into readable console.error stack traces in devtools.
• Release profile uses opt-level = "z" + LTO + codegen-units = 1 + symbol stripping — wasm binary size is the main cost center on the wire.
• Rows are marshalled to JS via serde_wasm_bindgen with serialize_maps_as_objects(true) (so each row is a plain JS Object, not a Map) and serde_json's preserve_order feature (so column keys come across in projection order, not alphabetical).

Sibling products

The WASM SDK is browser-only. For LLM-agent-driven server-side access to SQLRite, install the sqlrite-mcp Model Context Protocol server (cargo install sqlrite-mcp) and wire it into Claude Code / Cursor / mcp-inspector / any MCP-aware client. Same engine underneath.

Status

Phase 5g MVP: ✅ — in-memory CRUD, transactions, columns(), panic hook, serialization behavior matches the Node.js SDK. OPFS-backed persistence, prepared-statement objects, and parameter binding are natural follow-ups.