stratum-sqlite 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YOUR_NAME
+
+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,260 @@
+# stratum-sqlite
+
+Load and query a **read-only SQLite database on any static website** — plain HTML,
+Quarto, Jekyll, Hugo, and more. No server. No backend.
+
+The database file is fetched once from any public URL (GitHub Releases, Zenodo,
+your own GitHub Pages, Cloudflare R2, …) and stored in the browser's **Cache API**,
+so every page on your site after the first one loads it instantly from local cache.
+
+---
+
+## How it works
+
+```
+Your browser                          Your static site server
+    │                                         │
+    │  first visit                            │
+    ├─────── GET /libs/sqljs/sql-wasm.js ────►│
+    ├─────── GET /libs/sqljs/sql-wasm.wasm ──►│
+    ├─────── GET /data/mydb.sqlite ──────────►│
+    │                                         │
+    │  second visit (and all other pages)     │
+    │  ◄── served from browser Cache API ─────┤  (no network request!)
+    │                                         │
+```
+
+sql.js compiles SQLite to WebAssembly and runs it entirely in the browser.
+`stratum-sqlite` wraps sql.js with a simple `open()` / `query()` API and adds
+transparent caching.
+
+---
+
+## Quick start
+
+### For the demo site (local preview)
+
+The fastest way to get the demo running locally:
+
+```bash
+git clone https://github.com/stratum-toolkit/stratum-sqlite
+cd stratum-sqlite
+node build.mjs   # build the library
+bash setup.sh    # download sql.js binaries into docs/libs/sqljs/
+python3 -m http.server 8000 --directory docs
+# open http://localhost:8000
+```
+
+### Option A — Self-hosted (for your own project)
+
+1. **Download sql.js and the library** using `setup.sh` (if you have the repo),
+   or manually:
+
+   ```bash
+   mkdir -p libs/sqljs
+   curl -sSfL https://cdnjs.cloudflare.com/ajax/libs/sql.js/1.10.3/sql-wasm.js \
+        -o libs/sqljs/sql-wasm.js
+   curl -sSfL https://cdnjs.cloudflare.com/ajax/libs/sql.js/1.10.3/sql-wasm.wasm \
+        -o libs/sqljs/sql-wasm.wasm
+   ```
+
+   Then download `stratum-sqlite.umd.js` from the
+   [Releases page](https://github.com/stratum-toolkit/stratum-sqlite/releases) and
+   place it alongside sql.js:
+
+   ```
+   libs/
+   └── sqljs/
+       ├── sql-wasm.js
+       ├── sql-wasm.wasm
+       └── stratum-sqlite.umd.js
+   ```
+
+2. **Use it in your HTML**:
+
+   ```html
+   <script src="libs/sqljs/sql-wasm.js"></script>
+   <script src="libs/sqljs/stratum-sqlite.umd.js"></script>
+
+   <script type="module">
+     const db = await StratumSQLite.open("data/mydb.sqlite", {
+       sqlJsPath: "libs/sqljs/",
+       cacheKey:  "mydb@v1",       // bump version when you publish a new DB
+     });
+
+     const rows = db.query("SELECT * FROM countries WHERE region = ?", ["Europe"]);
+     console.log(rows);
+   </script>
+   ```
+
+### Option B — npm + bundler
+
+```bash
+npm install stratum-sqlite
+```
+
+```js
+import StratumSQLite from 'stratum-sqlite';
+
+const db = await StratumSQLite.open("/data/mydb.sqlite", {
+  sqlJsPath: "/libs/sqljs/",
+  cacheKey:  "mydb@v1",
+});
+
+const rows = db.query("SELECT * FROM countries");
+```
+
+---
+
+## API
+
+### `StratumSQLite.open(url, options)` → `Promise<Database>`
+
+Fetches the SQLite file at `url` and returns a `Database` instance.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `sqlJsPath` | `string` | cdnjs URL | Path (relative or absolute) to the folder containing `sql-wasm.js` and `sql-wasm.wasm`. |
+| `cacheKey` | `string` | `"stratum-sqlite:<url>@1"` | Browser Cache API bucket name. Bump the suffix (e.g. `@v2`) to force a re-download on your next publish. |
+| `onProgress` | `function(loaded, total)` | — | Called during the first download to update a loading bar. |
+
+### `db.query(sql, params?)` → `Array<Object>`
+
+Runs a SQL statement and returns rows as plain objects.
+
+```js
+db.query("SELECT name, capital FROM countries WHERE region = ?", ["Europe"])
+// → [{ name: "Norway", capital: "Oslo" }, …]
+```
+
+### `db.tables()` → `string[]`
+
+Returns the names of all user tables.
+
+### `db.columns(tableName)` → `Array<Object>`
+
+Returns column definitions from `PRAGMA table_info`.
+
+### `db.count(tableName)` → `number`
+
+Returns the total row count of a table.
+
+---
+
+## Quarto / ObservableJS integration
+
+Add `_sqljs-init.html` to your project root:
+
+```html
+<!-- _sqljs-init.html -->
+<script>
+(function () {
+  // Detect page depth by reading the relative path of any Quarto site_libs script.
+  var siteLibScript = document.querySelector('script[src*="site_libs/"]');
+  var root = siteLibScript
+    ? siteLibScript.getAttribute('src').replace(/site_libs\/.*$/, '')
+    : '';
+
+  window._dbPath    = root + 'data/mydb.sqlite';
+  window._sqljsBase = root + 'libs/sqljs/';
+
+  window._sqlJsReady = new Promise(function (resolve, reject) {
+    var s = document.createElement('script');
+    s.src = window._sqljsBase + 'sql-wasm.js';
+    s.onload = function () {
+      initSqlJs({ locateFile: function () { return window._sqljsBase + 'sql-wasm.wasm'; } })
+        .then(resolve).catch(reject);
+    };
+    s.onerror = function () { reject(new Error('sql.js load failed: ' + s.src)); };
+    document.head.appendChild(s);
+  });
+}());
+</script>
+```
+
+In `_quarto.yml`:
+
+```yaml
+format:
+  html:
+    include-in-header: _sqljs-init.html
+```
+
+In any `.qmd` file:
+
+```{ojs}
+db = {
+  const SqlJs = await window._sqlJsReady;
+  const r     = await fetch(window._dbPath);
+  const raw   = new SqlJs.Database(new Uint8Array(await r.arrayBuffer()));
+  return {
+    query: sql => {
+      const res = raw.exec(sql);
+      if (!res.length) return [];
+      const { columns, values } = res[0];
+      return values.map(row =>
+        Object.fromEntries(columns.map((c, i) => [c, row[i]])));
+    }
+  };
+}
+
+rows = (await db).query("SELECT * FROM countries")
+Inputs.table(rows)
+```
+
+---
+
+## Hosting your database
+
+Your SQLite file can be hosted anywhere with public HTTPS and
+`Access-Control-Allow-Origin: *`:
+
+| Host | Free | Max size | CORS |
+|------|------|----------|------|
+| **GitHub Pages** (same origin) | ✓ | 1 GB repo limit | same-origin |
+| **GitHub Releases** | ✓ | 2 GB per file | ✓ automatic |
+| **Zenodo** | ✓ | 50 GB | ✓ |
+| **Figshare** | ✓ | 20 GB | ✓ |
+| **Cloudflare R2** | free tier | unlimited | configure bucket policy |
+| **AWS S3** | free tier | unlimited | configure bucket policy |
+
+---
+
+## Updating the database
+
+1. Publish the new `.sqlite` file to your chosen host.
+2. Bump the `cacheKey` option: `"mydb@v1"` → `"mydb@v2"`.
+   `stratum-sqlite` automatically evicts the old cached file on next page load.
+
+---
+
+## Developing this library
+
+```bash
+git clone https://github.com/stratum-toolkit/stratum-sqlite
+cd stratum-sqlite
+
+# 1. Build dist bundles
+node build.mjs
+
+# 2. Download sql.js binaries and copy the built library (one command)
+bash setup.sh
+
+# 3. Create sample database if needed
+python3 scripts/create_demo_db.py   # Python
+Rscript scripts/create_demo_db.R    # R
+
+# 4. Serve demo site
+python3 -m http.server 8000 --directory docs
+# open http://localhost:8000
+```
+
+`setup.sh` downloads `sql-wasm.js` and `sql-wasm.wasm` from cdnjs into
+`docs/libs/sqljs/` and copies the built library there. These binary files
+are in `.gitignore` — the CI pipeline downloads them fresh on every deploy.
+
+---
+
+## License
+
+MIT

package/dist/stratum-sqlite.esm.js

@@ -0,0 +1,240 @@
+/* stratum-sqlite v0.1.2 | MIT license | https://github.com/stratum-toolkit/stratum-sqlite */
+/**
+ * stratum-sqlite
+ * Load and query a read-only SQLite database on any static website.
+ *
+ * Works with plain HTML, Quarto / ObservableJS, Jekyll, Hugo, and any other
+ * static site generator. The database is fetched once and cached in the
+ * browser's Cache API so repeat visits (and other pages on the same site)
+ * skip the network entirely.
+ *
+ * @license MIT
+ */
+
+// ─── Default sql.js location ────────────────────────────────────────────────
+// Users can override this with the sqlJsPath option when calling open().
+// The default points to cdnjs, but for offline / restricted environments you
+// should download sql-wasm.js and sql-wasm.wasm and serve them yourself.
+const DEFAULT_SQLJS_CDN =
+  'https://cdnjs.cloudflare.com/ajax/libs/sql.js/1.10.3/';
+
+// ─── Internal helpers ────────────────────────────────────────────────────────
+
+/**
+ * Inject a <script> tag and return a promise that resolves when it loads.
+ * Skips injection if a tag with the same src already exists.
+ */
+function loadScript(src) {
+  return new Promise((resolve, reject) => {
+    if (document.querySelector(`script[src="${src}"]`)) {
+      resolve();
+      return;
+    }
+    const s = document.createElement('script');
+    s.src = src;
+    s.crossOrigin = 'anonymous';
+    s.onload = resolve;
+    s.onerror = () => reject(new Error(`stratum-sqlite: failed to load script: ${src}`));
+    document.head.appendChild(s);
+  });
+}
+
+/**
+ * Fetch a URL as a Uint8Array, using the browser Cache API when available.
+ *
+ * @param {string} url         - URL of the resource to fetch
+ * @param {string} cacheKey    - Cache storage name (bump to force re-download)
+ * @param {function} onProgress - Optional callback(loaded, total) for progress
+ */
+async function fetchWithCache(url, cacheKey, onProgress) {
+  // Cache API requires a secure context (HTTPS or localhost).
+  // Fall back to a plain fetch when unavailable (e.g. file://).
+  if (!('caches' in window)) {
+    return plainFetch(url, onProgress);
+  }
+
+  const cache = await caches.open(cacheKey);
+
+  // Evict caches from older versions of the same key prefix.
+  // Convention: keys are "stratum-sqlite:<name>@<version>"
+  const prefix = cacheKey.replace(/@[^@]*$/, '@');
+  const allKeys = await caches.keys();
+  for (const key of allKeys) {
+    if (key.startsWith(prefix) && key !== cacheKey) {
+      await caches.delete(key);
+    }
+  }
+
+  let cached = await cache.match(url);
+  if (!cached) {
+    const response = await fetch(url);
+    if (!response.ok) {
+      throw new Error(`stratum-sqlite: fetch failed (${response.status}) ${url}`);
+    }
+    await cache.put(url, response.clone());
+    cached = await cache.match(url);
+  }
+
+  return streamToUint8Array(cached, onProgress);
+}
+
+async function plainFetch(url, onProgress) {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`stratum-sqlite: fetch failed (${response.status}) ${url}`);
+  }
+  return streamToUint8Array(response, onProgress);
+}
+
+/**
+ * Read a Response body as Uint8Array, reporting progress if the callback and
+ * Content-Length header are both available.
+ */
+async function streamToUint8Array(response, onProgress) {
+  const total = Number(response.headers.get('content-length')) || 0;
+
+  if (!onProgress || !total || !response.body) {
+    return new Uint8Array(await response.arrayBuffer());
+  }
+
+  const reader = response.body.getReader();
+  const chunks = [];
+  let loaded = 0;
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    chunks.push(value);
+    loaded += value.length;
+    onProgress(loaded, total);
+  }
+
+  const result = new Uint8Array(loaded);
+  let offset = 0;
+  for (const chunk of chunks) {
+    result.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return result;
+}
+
+// ─── Database wrapper ────────────────────────────────────────────────────────
+
+class Database {
+  /** @param {object} sqlJsDb - raw sql.js Database instance */
+  constructor(sqlJsDb) {
+    this._db = sqlJsDb;
+  }
+
+  /**
+   * Run a SQL query and return results as an array of plain objects.
+   *
+   * @param {string} sql    - SQL statement (SELECT …)
+   * @param {Array}  params - Optional positional parameters (? placeholders)
+   * @returns {Array<Object>}
+   *
+   * @example
+   * db.query("SELECT name, capital FROM countries WHERE region = ?", ["Europe"])
+   */
+  query(sql, params) {
+    const results = this._db.exec(sql, params);
+    if (!results.length) return [];
+    const { columns, values } = results[0];
+    return values.map(row =>
+      Object.fromEntries(columns.map((col, i) => [col, row[i]]))
+    );
+  }
+
+  /**
+   * Return the names of all user tables in the database.
+   * @returns {string[]}
+   */
+  tables() {
+    return this.query(
+      "SELECT name FROM sqlite_schema WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name"
+    ).map(r => r.name);
+  }
+
+  /**
+   * Return column definitions for a table.
+   * @param {string} tableName
+   * @returns {Array<{cid, name, type, notnull, dflt_value, pk}>}
+   */
+  columns(tableName) {
+    return this.query(`PRAGMA table_info("${tableName}")`);
+  }
+
+  /**
+   * Count rows in a table.
+   * @param {string} tableName
+   * @returns {number}
+   */
+  count(tableName) {
+    return this.query(`SELECT COUNT(*) as n FROM "${tableName}"`)[0]?.n ?? 0;
+  }
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {Object} OpenOptions
+ * @property {string}   [sqlJsPath]   - Base path/URL for sql-wasm.js and sql-wasm.wasm.
+ *                                      Defaults to cdnjs. Set to a local path like
+ *                                      "/libs/sqljs/" when serving sql.js yourself.
+ * @property {string}   [cacheKey]    - Browser Cache API key.
+ *                                      Defaults to "stratum-sqlite:<url>@1".
+ *                                      Bump the version suffix to force a re-download
+ *                                      when you publish a new database release.
+ * @property {function} [onProgress]  - Called with (bytesLoaded, bytesTotal) during
+ *                                      the first download. Not called on cache hits.
+ */
+
+/**
+ * Fetch a SQLite database from `url` and return a Database instance ready to
+ * query. On first call the file is downloaded and stored in the browser's
+ * Cache API. Subsequent calls (including from other pages on the same origin)
+ * are served instantly from cache.
+ *
+ * @param {string}      url     - URL of the .sqlite file (absolute or relative)
+ * @param {OpenOptions} options
+ * @returns {Promise<Database>}
+ *
+ * @example <caption>Plain HTML</caption>
+ * const db = await StratumSQLite.open("data/mydb.sqlite", {
+ *   sqlJsPath: "libs/sqljs/",
+ *   cacheKey:  "mydb@v1.2",
+ * });
+ * const rows = db.query("SELECT * FROM countries");
+ *
+ * @example <caption>Quarto / ObservableJS cell</caption>
+ * db = StratumSQLite.open(window._dbPath, { sqlJsPath: window._sqljsBase })
+ * rows = (await db).query("SELECT * FROM countries")
+ */
+async function open(url, options = {}) {
+  const sqlJsBase = options.sqlJsPath || DEFAULT_SQLJS_CDN;
+  const cacheKey  = options.cacheKey  || `stratum-sqlite:${url}@1`;
+  const onProgress = options.onProgress || null;
+
+  // Ensure trailing slash on sqlJsBase
+  const base = sqlJsBase.endsWith('/') ? sqlJsBase : sqlJsBase + '/';
+
+  // Load the sql.js bootstrap script (sets global `initSqlJs`)
+  await loadScript(base + 'sql-wasm.js');
+
+  // Initialise the WASM module
+  const SQL = await initSqlJs({   // eslint-disable-line no-undef
+    locateFile: () => base + 'sql-wasm.wasm',
+  });
+
+  // Fetch the database (cache hit after first load)
+  const bytes = await fetchWithCache(url, cacheKey, onProgress);
+
+  return new Database(new SQL.Database(bytes));
+}
+
+const StratumSQLite = { open, Database };
+
+
+
+export { open, Database };
+export default StratumSQLite;

package/dist/stratum-sqlite.umd.js

@@ -0,0 +1,247 @@
+/* stratum-sqlite v0.1.2 | MIT license | https://github.com/stratum-toolkit/stratum-sqlite */
+(function (global, factory) {
+  typeof exports === 'object' && typeof module !== 'undefined'
+    ? module.exports = factory()
+    : (global = typeof globalThis !== 'undefined' ? globalThis : global || self,
+       global.StratumSQLite = factory());
+})(this, function () {
+  'use strict';
+/**
+ * stratum-sqlite
+ * Load and query a read-only SQLite database on any static website.
+ *
+ * Works with plain HTML, Quarto / ObservableJS, Jekyll, Hugo, and any other
+ * static site generator. The database is fetched once and cached in the
+ * browser's Cache API so repeat visits (and other pages on the same site)
+ * skip the network entirely.
+ *
+ * @license MIT
+ */
+
+// ─── Default sql.js location ────────────────────────────────────────────────
+// Users can override this with the sqlJsPath option when calling open().
+// The default points to cdnjs, but for offline / restricted environments you
+// should download sql-wasm.js and sql-wasm.wasm and serve them yourself.
+const DEFAULT_SQLJS_CDN =
+  'https://cdnjs.cloudflare.com/ajax/libs/sql.js/1.10.3/';
+
+// ─── Internal helpers ────────────────────────────────────────────────────────
+
+/**
+ * Inject a <script> tag and return a promise that resolves when it loads.
+ * Skips injection if a tag with the same src already exists.
+ */
+function loadScript(src) {
+  return new Promise((resolve, reject) => {
+    if (document.querySelector(`script[src="${src}"]`)) {
+      resolve();
+      return;
+    }
+    const s = document.createElement('script');
+    s.src = src;
+    s.crossOrigin = 'anonymous';
+    s.onload = resolve;
+    s.onerror = () => reject(new Error(`stratum-sqlite: failed to load script: ${src}`));
+    document.head.appendChild(s);
+  });
+}
+
+/**
+ * Fetch a URL as a Uint8Array, using the browser Cache API when available.
+ *
+ * @param {string} url         - URL of the resource to fetch
+ * @param {string} cacheKey    - Cache storage name (bump to force re-download)
+ * @param {function} onProgress - Optional callback(loaded, total) for progress
+ */
+async function fetchWithCache(url, cacheKey, onProgress) {
+  // Cache API requires a secure context (HTTPS or localhost).
+  // Fall back to a plain fetch when unavailable (e.g. file://).
+  if (!('caches' in window)) {
+    return plainFetch(url, onProgress);
+  }
+
+  const cache = await caches.open(cacheKey);
+
+  // Evict caches from older versions of the same key prefix.
+  // Convention: keys are "stratum-sqlite:<name>@<version>"
+  const prefix = cacheKey.replace(/@[^@]*$/, '@');
+  const allKeys = await caches.keys();
+  for (const key of allKeys) {
+    if (key.startsWith(prefix) && key !== cacheKey) {
+      await caches.delete(key);
+    }
+  }
+
+  let cached = await cache.match(url);
+  if (!cached) {
+    const response = await fetch(url);
+    if (!response.ok) {
+      throw new Error(`stratum-sqlite: fetch failed (${response.status}) ${url}`);
+    }
+    await cache.put(url, response.clone());
+    cached = await cache.match(url);
+  }
+
+  return streamToUint8Array(cached, onProgress);
+}
+
+async function plainFetch(url, onProgress) {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`stratum-sqlite: fetch failed (${response.status}) ${url}`);
+  }
+  return streamToUint8Array(response, onProgress);
+}
+
+/**
+ * Read a Response body as Uint8Array, reporting progress if the callback and
+ * Content-Length header are both available.
+ */
+async function streamToUint8Array(response, onProgress) {
+  const total = Number(response.headers.get('content-length')) || 0;
+
+  if (!onProgress || !total || !response.body) {
+    return new Uint8Array(await response.arrayBuffer());
+  }
+
+  const reader = response.body.getReader();
+  const chunks = [];
+  let loaded = 0;
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    chunks.push(value);
+    loaded += value.length;
+    onProgress(loaded, total);
+  }
+
+  const result = new Uint8Array(loaded);
+  let offset = 0;
+  for (const chunk of chunks) {
+    result.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return result;
+}
+
+// ─── Database wrapper ────────────────────────────────────────────────────────
+
+class Database {
+  /** @param {object} sqlJsDb - raw sql.js Database instance */
+  constructor(sqlJsDb) {
+    this._db = sqlJsDb;
+  }
+
+  /**
+   * Run a SQL query and return results as an array of plain objects.
+   *
+   * @param {string} sql    - SQL statement (SELECT …)
+   * @param {Array}  params - Optional positional parameters (? placeholders)
+   * @returns {Array<Object>}
+   *
+   * @example
+   * db.query("SELECT name, capital FROM countries WHERE region = ?", ["Europe"])
+   */
+  query(sql, params) {
+    const results = this._db.exec(sql, params);
+    if (!results.length) return [];
+    const { columns, values } = results[0];
+    return values.map(row =>
+      Object.fromEntries(columns.map((col, i) => [col, row[i]]))
+    );
+  }
+
+  /**
+   * Return the names of all user tables in the database.
+   * @returns {string[]}
+   */
+  tables() {
+    return this.query(
+      "SELECT name FROM sqlite_schema WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name"
+    ).map(r => r.name);
+  }
+
+  /**
+   * Return column definitions for a table.
+   * @param {string} tableName
+   * @returns {Array<{cid, name, type, notnull, dflt_value, pk}>}
+   */
+  columns(tableName) {
+    return this.query(`PRAGMA table_info("${tableName}")`);
+  }
+
+  /**
+   * Count rows in a table.
+   * @param {string} tableName
+   * @returns {number}
+   */
+  count(tableName) {
+    return this.query(`SELECT COUNT(*) as n FROM "${tableName}"`)[0]?.n ?? 0;
+  }
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {Object} OpenOptions
+ * @property {string}   [sqlJsPath]   - Base path/URL for sql-wasm.js and sql-wasm.wasm.
+ *                                      Defaults to cdnjs. Set to a local path like
+ *                                      "/libs/sqljs/" when serving sql.js yourself.
+ * @property {string}   [cacheKey]    - Browser Cache API key.
+ *                                      Defaults to "stratum-sqlite:<url>@1".
+ *                                      Bump the version suffix to force a re-download
+ *                                      when you publish a new database release.
+ * @property {function} [onProgress]  - Called with (bytesLoaded, bytesTotal) during
+ *                                      the first download. Not called on cache hits.
+ */
+
+/**
+ * Fetch a SQLite database from `url` and return a Database instance ready to
+ * query. On first call the file is downloaded and stored in the browser's
+ * Cache API. Subsequent calls (including from other pages on the same origin)
+ * are served instantly from cache.
+ *
+ * @param {string}      url     - URL of the .sqlite file (absolute or relative)
+ * @param {OpenOptions} options
+ * @returns {Promise<Database>}
+ *
+ * @example <caption>Plain HTML</caption>
+ * const db = await StratumSQLite.open("data/mydb.sqlite", {
+ *   sqlJsPath: "libs/sqljs/",
+ *   cacheKey:  "mydb@v1.2",
+ * });
+ * const rows = db.query("SELECT * FROM countries");
+ *
+ * @example <caption>Quarto / ObservableJS cell</caption>
+ * db = StratumSQLite.open(window._dbPath, { sqlJsPath: window._sqljsBase })
+ * rows = (await db).query("SELECT * FROM countries")
+ */
+async function open(url, options = {}) {
+  const sqlJsBase = options.sqlJsPath || DEFAULT_SQLJS_CDN;
+  const cacheKey  = options.cacheKey  || `stratum-sqlite:${url}@1`;
+  const onProgress = options.onProgress || null;
+
+  // Ensure trailing slash on sqlJsBase
+  const base = sqlJsBase.endsWith('/') ? sqlJsBase : sqlJsBase + '/';
+
+  // Load the sql.js bootstrap script (sets global `initSqlJs`)
+  await loadScript(base + 'sql-wasm.js');
+
+  // Initialise the WASM module
+  const SQL = await initSqlJs({   // eslint-disable-line no-undef
+    locateFile: () => base + 'sql-wasm.wasm',
+  });
+
+  // Fetch the database (cache hit after first load)
+  const bytes = await fetchWithCache(url, cacheKey, onProgress);
+
+  return new Database(new SQL.Database(bytes));
+}
+
+const StratumSQLite = { open, Database };
+
+
+
+  return StratumSQLite;
+});

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "stratum-sqlite",
+  "version": "0.1.2",
+  "description": "Load and query a read-only SQLite database on any static website (plain HTML, Quarto, Jekyll, Hugo, …). Zero server required.",
+  "keywords": [
+    "sqlite",
+    "static-site",
+    "quarto",
+    "observablejs",
+    "indexeddb",
+    "sql"
+  ],
+  "license": "MIT",
+  "author": "Your Name <you@example.com>",
+  "homepage": "https://github.com/stratum-toolkit/stratum-sqlite#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stratum-toolkit/stratum-sqlite.git"
+  },
+  "type": "module",
+  "main": "dist/stratum-sqlite.umd.js",
+  "module": "dist/stratum-sqlite.esm.js",
+  "exports": {
+    ".": {
+      "import": "./dist/stratum-sqlite.esm.js",
+      "require": "./dist/stratum-sqlite.umd.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node build.mjs",
+    "dev": "node build.mjs --watch",
+    "prepare": "npm run build"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.0"
+  },
+  "peerDependencies": {
+    "sql.js": ">=1.10.0"
+  },
+  "peerDependenciesMeta": {
+    "sql.js": {
+      "optional": true
+    }
+  }
+}

package/src/index.js

@@ -0,0 +1,237 @@
+/**
+ * stratum-sqlite
+ * Load and query a read-only SQLite database on any static website.
+ *
+ * Works with plain HTML, Quarto / ObservableJS, Jekyll, Hugo, and any other
+ * static site generator. The database is fetched once and cached in the
+ * browser's Cache API so repeat visits (and other pages on the same site)
+ * skip the network entirely.
+ *
+ * @license MIT
+ */
+
+// ─── Default sql.js location ────────────────────────────────────────────────
+// Users can override this with the sqlJsPath option when calling open().
+// The default points to cdnjs, but for offline / restricted environments you
+// should download sql-wasm.js and sql-wasm.wasm and serve them yourself.
+const DEFAULT_SQLJS_CDN =
+  'https://cdnjs.cloudflare.com/ajax/libs/sql.js/1.10.3/';
+
+// ─── Internal helpers ────────────────────────────────────────────────────────
+
+/**
+ * Inject a <script> tag and return a promise that resolves when it loads.
+ * Skips injection if a tag with the same src already exists.
+ */
+function loadScript(src) {
+  return new Promise((resolve, reject) => {
+    if (document.querySelector(`script[src="${src}"]`)) {
+      resolve();
+      return;
+    }
+    const s = document.createElement('script');
+    s.src = src;
+    s.crossOrigin = 'anonymous';
+    s.onload = resolve;
+    s.onerror = () => reject(new Error(`stratum-sqlite: failed to load script: ${src}`));
+    document.head.appendChild(s);
+  });
+}
+
+/**
+ * Fetch a URL as a Uint8Array, using the browser Cache API when available.
+ *
+ * @param {string} url         - URL of the resource to fetch
+ * @param {string} cacheKey    - Cache storage name (bump to force re-download)
+ * @param {function} onProgress - Optional callback(loaded, total) for progress
+ */
+async function fetchWithCache(url, cacheKey, onProgress) {
+  // Cache API requires a secure context (HTTPS or localhost).
+  // Fall back to a plain fetch when unavailable (e.g. file://).
+  if (!('caches' in window)) {
+    return plainFetch(url, onProgress);
+  }
+
+  const cache = await caches.open(cacheKey);
+
+  // Evict caches from older versions of the same key prefix.
+  // Convention: keys are "stratum-sqlite:<name>@<version>"
+  const prefix = cacheKey.replace(/@[^@]*$/, '@');
+  const allKeys = await caches.keys();
+  for (const key of allKeys) {
+    if (key.startsWith(prefix) && key !== cacheKey) {
+      await caches.delete(key);
+    }
+  }
+
+  let cached = await cache.match(url);
+  if (!cached) {
+    const response = await fetch(url);
+    if (!response.ok) {
+      throw new Error(`stratum-sqlite: fetch failed (${response.status}) ${url}`);
+    }
+    await cache.put(url, response.clone());
+    cached = await cache.match(url);
+  }
+
+  return streamToUint8Array(cached, onProgress);
+}
+
+async function plainFetch(url, onProgress) {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`stratum-sqlite: fetch failed (${response.status}) ${url}`);
+  }
+  return streamToUint8Array(response, onProgress);
+}
+
+/**
+ * Read a Response body as Uint8Array, reporting progress if the callback and
+ * Content-Length header are both available.
+ */
+async function streamToUint8Array(response, onProgress) {
+  const total = Number(response.headers.get('content-length')) || 0;
+
+  if (!onProgress || !total || !response.body) {
+    return new Uint8Array(await response.arrayBuffer());
+  }
+
+  const reader = response.body.getReader();
+  const chunks = [];
+  let loaded = 0;
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    chunks.push(value);
+    loaded += value.length;
+    onProgress(loaded, total);
+  }
+
+  const result = new Uint8Array(loaded);
+  let offset = 0;
+  for (const chunk of chunks) {
+    result.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return result;
+}
+
+// ─── Database wrapper ────────────────────────────────────────────────────────
+
+class Database {
+  /** @param {object} sqlJsDb - raw sql.js Database instance */
+  constructor(sqlJsDb) {
+    this._db = sqlJsDb;
+  }
+
+  /**
+   * Run a SQL query and return results as an array of plain objects.
+   *
+   * @param {string} sql    - SQL statement (SELECT …)
+   * @param {Array}  params - Optional positional parameters (? placeholders)
+   * @returns {Array<Object>}
+   *
+   * @example
+   * db.query("SELECT name, capital FROM countries WHERE region = ?", ["Europe"])
+   */
+  query(sql, params) {
+    const results = this._db.exec(sql, params);
+    if (!results.length) return [];
+    const { columns, values } = results[0];
+    return values.map(row =>
+      Object.fromEntries(columns.map((col, i) => [col, row[i]]))
+    );
+  }
+
+  /**
+   * Return the names of all user tables in the database.
+   * @returns {string[]}
+   */
+  tables() {
+    return this.query(
+      "SELECT name FROM sqlite_schema WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name"
+    ).map(r => r.name);
+  }
+
+  /**
+   * Return column definitions for a table.
+   * @param {string} tableName
+   * @returns {Array<{cid, name, type, notnull, dflt_value, pk}>}
+   */
+  columns(tableName) {
+    return this.query(`PRAGMA table_info("${tableName}")`);
+  }
+
+  /**
+   * Count rows in a table.
+   * @param {string} tableName
+   * @returns {number}
+   */
+  count(tableName) {
+    return this.query(`SELECT COUNT(*) as n FROM "${tableName}"`)[0]?.n ?? 0;
+  }
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {Object} OpenOptions
+ * @property {string}   [sqlJsPath]   - Base path/URL for sql-wasm.js and sql-wasm.wasm.
+ *                                      Defaults to cdnjs. Set to a local path like
+ *                                      "/libs/sqljs/" when serving sql.js yourself.
+ * @property {string}   [cacheKey]    - Browser Cache API key.
+ *                                      Defaults to "stratum-sqlite:<url>@1".
+ *                                      Bump the version suffix to force a re-download
+ *                                      when you publish a new database release.
+ * @property {function} [onProgress]  - Called with (bytesLoaded, bytesTotal) during
+ *                                      the first download. Not called on cache hits.
+ */
+
+/**
+ * Fetch a SQLite database from `url` and return a Database instance ready to
+ * query. On first call the file is downloaded and stored in the browser's
+ * Cache API. Subsequent calls (including from other pages on the same origin)
+ * are served instantly from cache.
+ *
+ * @param {string}      url     - URL of the .sqlite file (absolute or relative)
+ * @param {OpenOptions} options
+ * @returns {Promise<Database>}
+ *
+ * @example <caption>Plain HTML</caption>
+ * const db = await StratumSQLite.open("data/mydb.sqlite", {
+ *   sqlJsPath: "libs/sqljs/",
+ *   cacheKey:  "mydb@v1.2",
+ * });
+ * const rows = db.query("SELECT * FROM countries");
+ *
+ * @example <caption>Quarto / ObservableJS cell</caption>
+ * db = StratumSQLite.open(window._dbPath, { sqlJsPath: window._sqljsBase })
+ * rows = (await db).query("SELECT * FROM countries")
+ */
+async function open(url, options = {}) {
+  const sqlJsBase = options.sqlJsPath || DEFAULT_SQLJS_CDN;
+  const cacheKey  = options.cacheKey  || `stratum-sqlite:${url}@1`;
+  const onProgress = options.onProgress || null;
+
+  // Ensure trailing slash on sqlJsBase
+  const base = sqlJsBase.endsWith('/') ? sqlJsBase : sqlJsBase + '/';
+
+  // Load the sql.js bootstrap script (sets global `initSqlJs`)
+  await loadScript(base + 'sql-wasm.js');
+
+  // Initialise the WASM module
+  const SQL = await initSqlJs({   // eslint-disable-line no-undef
+    locateFile: () => base + 'sql-wasm.wasm',
+  });
+
+  // Fetch the database (cache hit after first load)
+  const bytes = await fetchWithCache(url, cacheKey, onProgress);
+
+  return new Database(new SQL.Database(bytes));
+}
+
+const StratumSQLite = { open, Database };
+
+export { open, Database };
+export default StratumSQLite;