@ahmadmoussawi/webdb 0.0.0-stage → 0.1.0-alpha.0

package/README.md

@@ -1,3 +1,387 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="docs/public/logo.svg" width="96" height="96" alt="WebDB Logo" />
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">WebDB</h1>
+
+<p align="center">
+  <strong>An ultra-lean (&lt;50 KB), and powerful browser-native relational database engine built from scratch in C compiled to WASM.</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/ahmad-moussawi/webdb/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT" /></a>
+  <img src="https://img.shields.io/badge/wasm%20size-%3C50%20KB-success.svg?logo=webassembly&logoColor=white" alt="Wasm Size: <50KB" />
+  <a href="https://ahmad-moussawi.github.io/webdb/playground/"><img src="https://img.shields.io/badge/Studio%20IDE-live%20playground-7c3aed?logo=visualstudiocode&logoColor=white" alt="Studio IDE" /></a>
+  <a href="https://ahmad-moussawi.github.io/webdb/benchmark/"><img src="https://img.shields.io/badge/benchmarks-live%20suite-059669?logo=speedtest&logoColor=white" alt="Live Benchmarks" /></a>
+  <a href="https://www.npmjs.com/package/@ahmadmoussawi/webdb"><img src="https://img.shields.io/npm/v/@ahmadmoussawi/webdb/alpha?label=npm%20alpha&color=orange&logo=npm" alt="npm alpha" /></a>
+  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.7-blue?logo=typescript&logoColor=white" alt="TypeScript" /></a>
+  <a href="https://vitest.dev/"><img src="https://img.shields.io/badge/tests-348%20unit%20%2B%206%20e2e%20passing-brightgreen?logo=vitest&logoColor=white" alt="Tests" /></a>
+  <a href="https://ahmad-moussawi.github.io/webdb/"><img src="https://img.shields.io/badge/docs-online-646cff?logo=vite&logoColor=white" alt="Docs" /></a>
+</p>
+
+<p align="center">
+  <a href="https://ahmad-moussawi.github.io/webdb/playground/"><strong>🚀 Launch Studio Playground</strong></a> &nbsp;•&nbsp;
+  <a href="https://ahmad-moussawi.github.io/webdb/benchmark/"><strong>⚡ Run Live Benchmarks</strong></a> &nbsp;•&nbsp;
+  <a href="https://ahmad-moussawi.github.io/webdb/"><strong>📖 Documentation</strong></a> &nbsp;•&nbsp;
+  <a href="https://ahmad-moussawi.github.io/webdb/plans/plan.html"><strong>📐 Specifications</strong></a>
+</p>
+
+**WebDB** is an ultra-lightweight, relational database built from scratch specifically for the web. Think of it as **SQLite reimagined for modern browsers**—bringing true SQL capabilities, ACID transactions, and persistent storage to offline-first apps without multi-megabyte bundles or complex server headers.
+
+- 🪶 **Tiny Footprint (&lt;50 KB Wasm):** Up to 90%+ smaller than ported desktop SQLite or Postgres (PGlite) builds.
+- ⚡ **True Relational Power:** Fast filtering, indexing, aggregations, multi-column sorting, and joins—replacing cumbersome IndexedDB cursor queries.
+- 🔄 **Async VFS by Heart:** Built from the ground up for asynchronous browser storage—clean non-blocking page faults with zero Emscripten `Asyncify` stack hacks or slow workarounds.
+- 🌐 **Embraces the Web Platform:** Uses the browser instead of fighting it—delegating to native `crypto.subtle`, `Intl`, `RegExp`, `Date`, and Web Locks rather than packing redundant C libraries into Wasm.
+- 💾 **Reliable Offline Persistence:** First-class storage with high-speed **OPFS** (desktop & workers) and **IndexedDB** (Safari, mobile WebViews, private browsing).
+- 🔌 **Zero Configuration:** Works everywhere out of the box with zero `COOP`/`COEP` header headaches.
+
+---
+
+## 🎮 Try WebDB Live in Your Browser
+
+Experience WebDB directly on your device with zero installation or setup:
+
+| Tool | Highlights | Link |
+| :--- | :--- | :--- |
+| **WebDB Studio Playground** | Full in-browser database IDE with Monaco editor, live table explorer, low-level binary 4KB slotted page inspector, buffer pool visualizer, and real-time bytecode disassembler. | [**Launch Studio IDE →**](https://ahmad-moussawi.github.io/webdb/playground/) |
+| **In-Browser Benchmark Suite** | Live comparative benchmarking engine measuring throughput (ops/sec), latency, and memory allocations against Raw JS Arrays, Native IndexedDB, and official SQLite WASM on your hardware. | [**Run Benchmarks →**](https://ahmad-moussawi.github.io/webdb/benchmark/) |
+
+---
+
+## Why WebDB? (The Vision)
+
+Web developers building offline apps have long been stuck between two extremes: **IndexedDB** is an awkward key-value cursor store lacking relational queries, joins, and aggregations; while **ported desktop engines (like SQLite or Postgres/PGlite)** drag 1 MB to 5 MB+ of desktop C legacy, POSIX thread logic, and Emscripten hacks into the browser.
+
+WebDB fills this gap by **reimagining a database engine from scratch for modern browsers**.
+
+```
+┌─────────────────────────────────┐       ┌─────────────────────────────────┐
+│  Ported Desktop DBs (Wasm)      │       │             WebDB               │
+├─────────────────────────────────┤       ├─────────────────────────────────┤
+│ • 500 KB - 5 MB+ (SQLite/PGlite)│       │ • <50 KB Wasm (ultra-lean)      │
+│ • Bundles text SQL parser/lexer │  ──►  │ • Fluent TS Builder ➔ Bytecode  │
+│ • Bundles POSIX pthread/mutexes │       │ • Single-threaded by design     │
+│ • Bundles C date/regex/ICU shims│       │ • Embraces native Web APIs      │
+│ • Asyncify call-stack rewriting │       │ • Native async page faults      │
+└─────────────────────────────────┘       └─────────────────────────────────┘
+```
+
+### The Architectural Shift
+
+**No Heavy SQL Parser:** Traditional SQL parsers, lexers, and tokenizer tables account for a huge portion of database binary size. In WebDB, the TypeScript Query Builder compiles queries directly into compact binary bytecode instructions (`Uint8Array`). The Wasm engine core only executes binary instructions—trimming tens of kilobytes of parser bloat.
+
+**Single-Threaded by Design:** Browsers run in isolated, single-threaded contexts (Main Thread or Web Worker). Stripping out POSIX thread handling and internal lock contention keeps the engine razor-sharp, delegating cross-tab coordination to the browser's native **Web Locks API** (`navigator.locks`).
+
+**Embracing Web APIs:** Instead of bundling heavy C libraries for dates, regexes, Unicode segmentation, or cryptography, WebDB delegates directly to native browser APIs (`Date`, `RegExp`, `Intl.Segmenter`, and `crypto.subtle`) via zero-overhead synchronous UDFs.
+
+**Async VFS by Heart:** Desktop databases expect synchronous POSIX disk calls, forcing Wasm ports to rely on Emscripten’s slow, bloated `Asyncify` stack rewriting. WebDB's execution engine suspends cleanly via non-blocking page faults whenever a 4KB page is missing. This makes the storage layer completely pluggable: pages can be read from high-speed **OPFS**, persisted in **IndexedDB**, or even streamed on-demand across the network from an S3/CDN bucket via **HTTP Range Requests** (`HttpVfsAdapter`).
+
+---
+
+## Current Status & Development Strategy
+
+WebDB is currently in an **early prototype ("walking skeleton") stage**:
+
+- **V1 (C-Style JS Engine):** The initial release is built in **strict C-style TypeScript/JavaScript** (direct `ArrayBuffer` pointer arithmetic, flat structs, and zero heap allocations). Writing V1 in JS accelerates the development cycle, simplifies debugging, and creates an instant feedback loop with the web community.
+- **V2 (Drop-In C / Wasm Port):** Once the binary formats, VDBE opcodes, and APIs are battle-tested, the core engine will be ported 1:1 to C and compiled to an ultra-lean Wasm binary (&lt;50 KB)—with zero changes required to the host JS orchestration layer.
+- **Current Milestone:** Slotted-page layouts, basic VDBE opcode execution, in-memory/IndexedDB adapters, and query planning are implemented and verified with automated test suites. Full V1 engine development is actively underway.
+- **Interactive Tools Live:** You can test queries in the [WebDB Studio Playground](https://ahmad-moussawi.github.io/webdb/playground/) or evaluate performance in the [In-Browser Benchmark Suite](https://ahmad-moussawi.github.io/webdb/benchmark/).
+
+Read our complete specifications:
+
+- [Strategic Master Plan](https://ahmad-moussawi.github.io/webdb/plans/plan.html)
+- [System Limitations & Invariants](https://ahmad-moussawi.github.io/webdb/plans/limitations.html)
+- [Future Extensions: Vector, JSON & Hybrid Search](https://ahmad-moussawi.github.io/webdb/plans/future_extensions_roadmap.html)
+
+---
+
+## 📦 Installation
+
+Install the alpha release of `@ahmadmoussawi/webdb` via npm, pnpm, or yarn:
+
+```bash
+# npm
+npm install @ahmadmoussawi/webdb@alpha
+
+# pnpm
+pnpm add @ahmadmoussawi/webdb@alpha
+
+# yarn
+yarn add @ahmadmoussawi/webdb@alpha
+```
+
+---
+
+## 🚀 Quick Start (Runnable Example)
+
+The snippet below is a complete, runnable example you can paste into any TypeScript or JavaScript project (Vite, Next.js, Node 20+, or Vitest):
+
+```typescript
+import { WebDB } from "@ahmadmoussawi/webdb";
+
+async function main() {
+  // 1. Open a database
+  //    storage: 'idb' (IndexedDB) | 'opfs' (Origin Private File System) | 'memory' (In-Memory)
+  //    core:    'wasm' (default ~13 KB Wasm engine) | 'js' (pure JS fallback)
+  const db = await WebDB.open({
+    name: "app_data",
+    storage: typeof indexedDB !== "undefined" ? "idb" : "memory",
+    core: "wasm",
+  });
+
+  // 2. Define a table schema stored in Page 1 (Binary Master Catalog)
+  //    Supported column types: 'INT32' | 'INT64' | 'FLOAT64' | 'TEXT' | 'BLOB' | 'UUID' | 'ULID'
+  await db.createTable("users", [
+    { name: "id", type: "UUID", flags: { primaryKey: true } }, // Packed into 16 raw bytes
+    { name: "name", type: "TEXT", flags: { notNull: true } },
+    { name: "age", type: "INT32" },
+    { name: "score", type: "FLOAT64" },
+  ]);
+
+  // Create a secondary B+Tree index for fast range scans & ordered queries
+  await db.createIndex("users", "score");
+
+  // 3. Insert single or bulk records
+  await db.insert("users", {
+    id: "018d3e2a-1b4c-7000-8000-123456789abc",
+    name: "Alice",
+    age: 28,
+    score: 95.5,
+  });
+
+  await db.insertMany("users", [
+    { id: crypto.randomUUID(), name: "Bob", age: 19, score: 82.0 },
+    { id: crypto.randomUUID(), name: "Charlie", age: 34, score: 88.0 },
+  ]);
+
+  // 4. ACID Transactions with Write-Ahead Logging (WAL) & Nested Savepoints
+  //    Automatically coordinates across browser tabs via Web Locks (navigator.locks)
+  await db.transaction(async (tx) => {
+    await tx.insert("users", {
+      id: crypto.randomUUID(),
+      name: "Diana",
+      age: 25,
+      score: 99.0,
+    });
+
+    // Nested transactions act as savepoints — rolling back an inner block
+    // restores state without aborting the outer transaction
+    await tx
+      .transaction(async (nestedTx) => {
+        await nestedTx.insert("users", {
+          id: crypto.randomUUID(),
+          name: "Temporary User",
+          age: 40,
+          score: 10.0,
+        });
+        throw new Error("Abort inner savepoint only");
+      })
+      .catch(() => {
+        // Inner insert was cleanly rolled back; Diana remains!
+      });
+  });
+
+  // 5. Fluent Queries (compiled directly to compact VDBE binary bytecode)
+  const topAdults = await db
+    .from("users")
+    .select("name", "age", "score")
+    .where("age", ">=", 21)
+    .whereNotNull("score")
+    .orderBy("score", "desc")
+    .limit(10)
+    .toArray();
+
+  console.table(topAdults);
+  // ┌─────────┬───────────┬─────┬───────┐
+  // │ (index) │ name      │ age │ score │
+  // ├─────────┼───────────┼─────┼───────┤
+  // │ 0       │ 'Diana'   │ 25  │ 99    │
+  // │ 1       │ 'Alice'   │ 28  │ 95.5  │
+  // │ 2       │ 'Charlie' │ 34  │ 88    │
+  // └─────────┴───────────┴─────┴───────┘
+
+  // 6. Inspect the Query Plan & VDBE Bytecode Disassembly
+  const explain = await db.from("users").where("score", ">", 80).explain();
+  console.log("Execution Plan:", explain.plan);
+  console.table(explain.instructions);
+
+  await db.close();
+}
+
+main();
+```
+
+---
+
+## ⚙️ Core Architecture: TypeScript ➔ C Transpiler
+
+WebDB uses an automated **TypeScript-to-C Transpiler** (`scripts/transpiler/`) to maintain a single canonical source of truth for its core storage and execution engine (`src/core/js/*.c.ts`). 
+
+TypeScript code is written in a strict, zero-allocation, C-compatible style. The transpiler translates this code into freestanding C99 (`src/core/c/`), which is then compiled via Clang (`wasm32-unknown-unknown -nostdlib -O3`) and optimized with `wasm-opt` into an **ultra-lean ~13 KB WASM binary**.
+
+```
+  ┌─────────────────────────────────────────────────────────────┐
+  │         Canonical TypeScript Core (src/core/js/*.c.ts)      │
+  │    (Runs in Node/Vitest tests & Host JS Fallback Mode)      │
+  └──────────────────────────────┬──────────────────────────────┘
+                                 │
+                 npm run transpile:c / build:wasm
+                                 │
+                                 ▼
+  ┌─────────────────────────────────────────────────────────────┐
+  │             Freestanding C99 Core (src/core/c/)              │
+  │         Zero-libc, slotted-page pointer arithmetic          │
+  └──────────────────────────────┬──────────────────────────────┘
+                                 │
+                   clang -nostdlib -O3 + wasm-opt
+                                 │
+                                 ▼
+  ┌─────────────────────────────────────────────────────────────┐
+  │             WebAssembly Binary (~13 KB WASM)                │
+  │     Embedded directly into npm package with zero bloat      │
+  └─────────────────────────────────────────────────────────────┘
+```
+
+### CLI Commands
+
+```bash
+# Transpile all TypeScript core modules to C source (.c) and headers (.h)
+npm run transpile:c
+
+# Transpile a single file for inspection
+npx vite-node scripts/transpiler/index.ts src/core/js/codecs.c.ts
+
+# Complete build pipeline: layouts ➔ transpiler ➔ clang wasm32 ➔ wasm-opt -O3
+npm run build:wasm
+
+# Run the 275+ automated test suite across both JS and WASM cores
+npm test
+```
+
+### Type System Mapping (`src/core/types.ts`)
+
+Primitive type aliases in TypeScript map directly to C native fixed-width types:
+
+| TypeScript Alias | C Native Type | Description |
+| :--- | :--- | :--- |
+| `u8`, `u16`, `u32` | `uint8_t`, `uint16_t`, `uint32_t` | Unsigned 8, 16, 32-bit integers |
+| `i8`, `i16`, `i32` | `int8_t`, `int16_t`, `int32_t` | Signed 8, 16, 32-bit integers |
+| `u64`, `i64` | `uint64_t`, `int64_t` | 64-bit integers (`bigint` in JS) |
+| `f64` | `double` | 64-bit IEEE 754 floating point |
+| `byte_ptr` | `uint32_t` | Linear memory byte offset |
+| `const_u8_ptr` | `const uint8_t *` | Immutable byte buffer pointer |
+| `u8_ptr` | `uint8_t *` | Mutable byte buffer pointer |
+| `const_char_ptr` | `const char *` | Null-terminated C string pointer |
+| `char_ptr` | `char *` | Mutable character buffer pointer |
+
+### Transpiler Annotations Reference
+
+The transpiler supports annotations to customize code generation and enable dual implementations:
+
+#### 1. `@export_c` (Exported Function)
+Exports the function in both the C source and the `.h` header with `WEBDB_EXPORT`.
+```typescript
+/**
+ * @export_c
+ */
+export function page_get_cell_count(page_offset: u32): u16 {
+  return load_u16(page_offset + PAGE_HEADER_OFFSET_CELL_COUNT);
+}
+```
+
+#### 2. `@internal_c` (Module-Private Static Helper)
+Generates a `static` C function internal to the translation unit, omitted from the `.h` header.
+```typescript
+/**
+ * @internal_c
+ */
+function init_crc_table(): void {
+  // Generated as static void init_crc_table(void)
+}
+```
+
+#### 3. `@manual_c` / `@native_c` (Dual Implementation Shortcut)
+Instructs the transpiler that a function is manually implemented in C:
+- **In TypeScript / Vitest**: Executes the TypeScript body normally.
+- **In C Header (`.h`)**: Still registers `WEBDB_EXPORT` so callers have the prototype.
+- **In C Source (`.c`)**: **Skips** generating the body in `.c`. The implementation is resolved from existing C files, companion files, or headers.
+
+```typescript
+/**
+ * @export_c
+ * @manual_c
+ */
+export function btree_split_leaf(page_offset: u32, new_key: u32): i32 {
+  // High-level TS implementation runs in JS mode & Vitest tests
+  return 0;
+}
+```
+
+#### 4. Inline C Blocks (` ```c ... ``` `)
+Embed hand-crafted C code directly inside the TypeScript JSDoc comment. The transpiler emits the C code block verbatim:
+
+```typescript
+/**
+ * @export_c
+ * @manual_c
+ * ```c
+ * WEBDB_EXPORT uint32_t fast_crc32(uint32_t crc, const uint8_t *buf, uint32_t len) {
+ *   // Hand-optimized C routine
+ *   return crc ^ len;
+ * }
+ * ```
+ */
+export function fast_crc32(crc: u32, buf: Uint8Array, len: u32): u32 {
+  return (crc ^ len) >>> 0;
+}
+```
+
+#### 5. `@use_c: target_c_name` (Symbol & Call Rewriting)
+Maps the TypeScript function to a differently named existing C function. The transpiler automatically rewrites all call sites across transpiled code to call `target_c_name(...)`:
+
+```typescript
+/**
+ * @export_c
+ * @use_c: c_fast_checksum
+ */
+export function checksum(ptr: u32): u32 {
+  return 123;
+}
+```
+
+#### 6. Companion Files (`<module>.manual.c`)
+For large or performance-critical manual C functions:
+- Create `src/core/c/<module>.manual.c` (e.g. `src/core/c/catalog.manual.c`).
+- The transpiler automatically detects it and appends `#include "<module>.manual.c"` at the end of the generated `.c` file.
+- The companion file is completely safe from transpiler overwrites.
+
+#### 7. `c_inline(cCode, jsFallback)` (Compile-Time Intrinsic)
+Embeds C-specific intrinsics without breaking TypeScript execution:
+
+```typescript
+import { c_inline, u32 } from "../types.ts";
+
+export function compute_leading_zeros(val: u32): u32 {
+  // In JS: returns Math.clz32(val)
+  // In C:  emits __builtin_clz(val)
+  return c_inline("__builtin_clz(val)", Math.clz32(val));
+}
+```
+
+#### 8. `@c_include` & `@c_raw` Directives
+- `/** @c_include "custom_header.h" */`: Adds `#include "custom_header.h"` at the top of the generated C file.
+- `/** @c_raw ```c ... ``` */`: Injects top-level C macros or typedefs directly into the generated C file.
+
+---
+
+## Support the Project ⭐
+
+WebDB is an ambitious open-source initiative to build a modern, featherweight relational database engine purpose-built for the web platform. If you believe in this vision, here is how you can support the development:
+
+- ⭐ **Star this Repository:** If you find this project interesting or valuable, please give it a **Star on GitHub**. It takes two seconds, boosts project visibility, and helps attract more contributors!
+- 🎮 **Explore the Playground & Benchmarks:** Experiment with live queries in the [WebDB Studio Playground](https://ahmad-moussawi.github.io/webdb/playground/) and test throughput with the [In-Browser Benchmarks](https://ahmad-moussawi.github.io/webdb/benchmark/).
+- 📢 **Spread the Word:** Share WebDB on X (Twitter), Bluesky, LinkedIn, Reddit, or with developer friends building offline-first or local-first apps.
+- 💬 **Join the Discussion:** Review our [Architectural Blueprints](https://ahmad-moussawi.github.io/webdb/plans/plan.html), open an issue with suggestions, or share your offline data use cases.
+- 🛠️ **Contribute:** PRs, benchmarks, and feedback on our prototype and specifications are warmly welcome.
+
+WebDB is open source under the [MIT License](https://github.com/ahmad-moussawi/webdb/blob/main/LICENSE).

package/dist/constants.d.ts

@@ -0,0 +1,18 @@
+export * from './layouts/index.ts';
+export declare const CURRENT_ENGINE_VERSION = 1;
+export declare const CURRENT_MIN_READ_VERSION = 1;
+export declare const PAGE_TYPE_FREE = 0;
+export declare const PAGE_TYPE_INDEX_INTERIOR = 2;
+export declare const PAGE_TYPE_TABLE_INTERIOR = 5;
+export declare const PAGE_TYPE_INDEX_LEAF = 10;
+export declare const PAGE_TYPE_CATALOG_PAGE = 12;
+export declare const PAGE_TYPE_LEAF_DATA = 13;
+export declare const VM_FRAME_SIZE = 1280;
+export declare const VM_FRAME_COUNT = 8;
+export declare const MAX_REGISTERS_PER_FRAME = 64;
+export declare const MAX_CURSORS_PER_FRAME = 16;
+export declare const MAX_SUBQUERY_DEPTH = 7;
+export declare const WAL_HEADER_SIZE = 32;
+export declare const MAX_TOPK_HEAP_LIMIT = 10000;
+export declare const MAX_IN_LIST_SIZE = 10000;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AACA,cAAc,oBAAoB,CAAC;AAGnC,eAAO,MAAM,sBAAsB,IAAI,CAAC;AACxC,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAG1C,eAAO,MAAM,cAAc,IAAO,CAAC;AACnC,eAAO,MAAM,wBAAwB,IAAO,CAAC;AAC7C,eAAO,MAAM,wBAAwB,IAAO,CAAC;AAC7C,eAAO,MAAM,oBAAoB,KAAO,CAAC;AACzC,eAAO,MAAM,sBAAsB,KAAO,CAAC;AAC3C,eAAO,MAAM,mBAAmB,KAAO,CAAC;AAGxC,eAAO,MAAM,aAAa,OAAO,CAAC;AAClC,eAAO,MAAM,cAAc,IAAI,CAAC;AAChC,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAC1C,eAAO,MAAM,qBAAqB,KAAK,CAAC;AACxC,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAGpC,eAAO,MAAM,eAAe,KAAK,CAAC;AAGlC,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AACzC,eAAO,MAAM,gBAAgB,QAAQ,CAAC"}

package/dist/core/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * WebDB Core Engine C / FFI Export Boundary
+ *
+ * Explicitly exposes each C Core function annotated with @export_c to the Host layer.
+ * In Phase 1 (TypeScript Core), these are direct C-style functional exports.
+ * In Phase 2 (C/Wasm Core), these correspond 1-to-1 to the compiled WebAssembly exports.
+ */
+export { page_init, page_init_free, page_get_type, page_set_type, page_get_cell_count, page_set_cell_count, page_get_cell_content_offset, page_set_cell_content_offset, page_get_next_page_id, page_set_next_page_id, page_get_free_bytes, page_set_free_bytes, page_get_checksum, page_set_checksum, page_get_cell_offset, page_set_cell_offset, page_get_contiguous_free_space, page_get_total_free_space, page_compact, page_get_row_length, page_insert_row, page_delete_row, page_update_row, page_get_table_layout, page_serialize_row, page_deserialize_row, page_init_interior, page_get_right_child_page_id, page_set_right_child_page_id, page_insert_interior_cell, page_binary_search_interior, page_split_interior, page_init_index_leaf, page_compare_index_keys, page_insert_index_leaf_cell, page_binary_search_index_leaf, serialize_single_key, serialize_composite_key, } from './js/page.c.js';
+export { page_table_hash, page_table_get, page_table_set, page_table_delete, } from './js/page_table.c.js';
+export { buf_pool_get_slot_offset, buf_pool_read_slot_to_page, buf_pool_write_slot_to_page, buf_pool_get_resident_slot, buf_pool_assign_slot, buf_pool_unassign_slot, buf_pool_mark_dirty, buf_pool_clear_dirty, buf_pool_is_dirty, buf_pool_pin_slot, buf_pool_unpin_slot, buf_pool_is_pinned, buf_pool_find_victim, buf_pool_select_eviction_victim, } from './js/buffer_pool.c.js';
+export { vm_step, sql_like_match, compare_sorter_keys, fnv1a_32, } from './js/vm.c.js';
+export { catalog_init_page1, catalog_read_page1_header, catalog_get_total_pages, catalog_set_total_pages, catalog_get_free_page_head, catalog_set_free_page_head, catalog_get_schema_version, catalog_increment_schema_version, catalog_get_change_counter, catalog_increment_change_counter, catalog_update_page1_checksum, catalog_write_fixed_string, catalog_read_fixed_string, catalog_parse_data_type, catalog_read_table_descriptor, catalog_write_table_descriptor, catalog_find_table_by_name, catalog_find_table_slot, catalog_find_free_table_slot, catalog_list_table_descriptors, catalog_read_index_descriptor, catalog_write_index_descriptor, catalog_find_free_index_slot, catalog_find_index_by_name, catalog_list_table_indexes, catalog_delete_index_descriptor, catalog_delete_table_descriptor, catalog_init_page, catalog_read_page_header, catalog_write_page_header, catalog_write_column_meta, catalog_read_column_meta, catalog_map_column_location, catalog_create_table, catalog_load_table_meta, catalog_load_all_tables, } from './js/catalog.c.js';
+export { createWasmCore, type WasmCoreExports, } from './wasm/wasm_core.js';
+export { getWebDbCoreWasmBytes, WEBDB_CORE_WASM_BASE64, } from './wasm/embedded_wasm.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,EACL,SAAS,EACT,cAAc,EACd,aAAa,EACb,aAAa,EACb,mBAAmB,EACnB,mBAAmB,EACnB,4BAA4B,EAC5B,4BAA4B,EAC5B,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,8BAA8B,EAC9B,yBAAyB,EACzB,YAAY,EACZ,mBAAmB,EACnB,eAAe,EACf,eAAe,EACf,eAAe,EACf,qBAAqB,EACrB,kBAAkB,EAClB,oBAAoB,EACpB,kBAAkB,EAClB,4BAA4B,EAC5B,4BAA4B,EAC5B,yBAAyB,EACzB,2BAA2B,EAC3B,mBAAmB,EACnB,oBAAoB,EACpB,uBAAuB,EACvB,2BAA2B,EAC3B,6BAA6B,EAC7B,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,gBAAgB,CAAC;AAKxB,OAAO,EACL,eAAe,EACf,cAAc,EACd,cAAc,EACd,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EACL,wBAAwB,EACxB,0BAA0B,EAC1B,2BAA2B,EAC3B,0BAA0B,EAC1B,oBAAoB,EACpB,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,+BAA+B,GAChC,MAAM,uBAAuB,CAAC;AAK/B,OAAO,EACL,OAAO,EACP,cAAc,EACd,mBAAmB,EACnB,QAAQ,GACT,MAAM,cAAc,CAAC;AAKtB,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,uBAAuB,EACvB,uBAAuB,EACvB,0BAA0B,EAC1B,0BAA0B,EAC1B,0BAA0B,EAC1B,gCAAgC,EAChC,0BAA0B,EAC1B,gCAAgC,EAChC,6BAA6B,EAC7B,0BAA0B,EAC1B,yBAAyB,EACzB,uBAAuB,EACvB,6BAA6B,EAC7B,8BAA8B,EAC9B,0BAA0B,EAC1B,uBAAuB,EACvB,4BAA4B,EAC5B,8BAA8B,EAC9B,6BAA6B,EAC7B,8BAA8B,EAC9B,4BAA4B,EAC5B,0BAA0B,EAC1B,0BAA0B,EAC1B,+BAA+B,EAC/B,+BAA+B,EAC/B,iBAAiB,EACjB,wBAAwB,EACxB,yBAAyB,EACzB,yBAAyB,EACzB,wBAAwB,EACxB,2BAA2B,EAC3B,oBAAoB,EACpB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAK3B,OAAO,EACL,cAAc,EACd,KAAK,eAAe,GACrB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,yBAAyB,CAAC"}

package/dist/core/js/buffer_pool.c.d.ts

@@ -0,0 +1,142 @@
+import { u32, i32 } from '../types.ts';
+/**
+ * @export_c
+ * Returns the byte offset for a given slot in linear memory.
+ */
+export declare function buf_pool_get_slot_offset(slot_idx: u32): u32;
+/**
+ * @export_c
+ * Reads the page ID currently assigned to slot_idx from the slot_to_page map.
+ */
+export declare function buf_pool_read_slot_to_page(view: DataView, slot_to_page_offset: u32, slot_idx: u32): u32;
+/**
+ * @export_c
+ * Writes the page ID assigned to slot_idx in the slot_to_page map.
+ */
+export declare function buf_pool_write_slot_to_page(view: DataView, slot_to_page_offset: u32, slot_idx: u32, page_id: u32): void;
+/**
+ * @export_c
+ * Looks up the resident slot for page_id in the open-addressing hash table.
+ * Returns slot index or -1 if not resident.
+ */
+export declare function buf_pool_get_resident_slot(view: DataView, page_to_slot_offset: u32, page_to_slot_buckets: u32, page_id: u32): i32;
+/**
+ * @export_c
+ * Assigns slot_idx to page_id, updating slot_to_page and page_to_slot hash tables.
+ */
+export declare function buf_pool_assign_slot(view: DataView, slot_to_page_offset: u32, page_to_slot_offset: u32, page_to_slot_buckets: u32, slot_idx: u32, page_id: u32): i32;
+/**
+ * @export_c
+ * Unassigns slot_idx, clearing its page table entry and setting assigned page to 0.
+ */
+export declare function buf_pool_unassign_slot(view: DataView, slot_to_page_offset: u32, page_to_slot_offset: u32, page_to_slot_buckets: u32, slot_idx: u32): i32;
+/**
+ * @export_c
+ * Marks slot_idx as dirty in the dirty bitmask.
+ */
+export declare function buf_pool_mark_dirty(dirty_mask: Uint8Array, dirty_mask_offset: u32, slot_idx: u32): void;
+/**
+ * @export_c
+ * Clears the dirty bit for slot_idx in the dirty bitmask.
+ */
+export declare function buf_pool_clear_dirty(dirty_mask: Uint8Array, dirty_mask_offset: u32, slot_idx: u32): void;
+/**
+ * @export_c
+ * Checks if slot_idx is marked dirty in the dirty bitmask.
+ */
+export declare function buf_pool_is_dirty(dirty_mask: Uint8Array, dirty_mask_offset: u32, slot_idx: u32): boolean;
+/**
+ * Increments pin count for slot_idx. Throws on uint32 overflow.
+ */
+export declare function buf_pool_pin_slot(pin_counts: Uint32Array, slot_idx: number): void;
+/**
+ * Decrements pin count for slot_idx. Slot 0 is permanently pinned.
+ */
+export declare function buf_pool_unpin_slot(pin_counts: Uint32Array, slot_idx: number): void;
+/**
+ * Returns true if slot_idx is pinned (pin_count > 0 or slot 0).
+ */
+export declare function buf_pool_is_pinned(pin_counts: Uint32Array, slot_idx: number): boolean;
+/**
+ * Finds an eviction candidate slot using Clock sweep with second-chance bit check.
+ */
+export declare function buf_pool_find_victim(buffer: ArrayBuffer, ref_bits: Uint8Array, pin_counts: Uint32Array, slot_to_page_offset: number, slot_count: number, current_clock_hand: number): {
+    candidate_slot: number;
+    next_clock_hand: number;
+};
+/**
+ * Selects an eviction candidate slot for a requested page using the Core Clock sweep.
+ * Examines candidate slot to determine if it holds a dirty page that must be flushed.
+ */
+export declare function buf_pool_select_eviction_victim(buffer: ArrayBuffer, ref_bits: Uint8Array, pin_counts: Uint32Array, slot_to_page_offset: number, dirty_mask_offset: number, slot_count: number, current_clock_hand: number, page_id: number): {
+    candidate_slot: number;
+    flush_page_id: number;
+    next_clock_hand: number;
+};
+export interface BufferPoolOptions {
+    slotCount?: number;
+    maxQueryMemory?: number;
+    vfs?: any;
+}
+export declare class BufferPool {
+    readonly slot_count: number;
+    readonly max_query_memory: number;
+    readonly wasm_memory: WebAssembly.Memory;
+    buffer: ArrayBuffer;
+    view: DataView;
+    uint8: Uint8Array;
+    readonly slots_end_offset: number;
+    readonly slot_to_page_offset: number;
+    readonly page_to_slot_offset: number;
+    readonly page_to_slot_buckets: number;
+    readonly dirty_mask_offset: number;
+    readonly vm_context_offset: number;
+    readonly result_buffer_offset: number;
+    readonly bytecode_offset: number;
+    readonly page_scratchpad_offset: number;
+    readonly transient_arena_offset: number;
+    readonly pin_counts: Uint32Array;
+    readonly slot_dirty_generations: Uint32Array;
+    readonly ref_bits: Uint8Array;
+    private clock_hand;
+    private arena_offset;
+    constructor(options?: BufferPoolOptions);
+    read_u8(address: number): number;
+    write_u8(address: number, val: number): void;
+    read_u16(address: number): number;
+    write_u16(address: number, val: number): void;
+    read_u32(address: number): number;
+    write_u32(address: number, val: number): void;
+    read_i32(address: number): number;
+    write_i32(address: number, val: number): void;
+    read_f64(address: number): number;
+    write_f64(address: number, val: number): void;
+    get_bytes(address: number, length: number): Uint8Array;
+    set_bytes(address: number, source: Uint8Array): void;
+    fill_bytes(address: number, length: number, val?: number): void;
+    private validate_slot_idx;
+    private validate_page_id;
+    get_assigned_page(slot_idx: number): number;
+    assign_slot(slot_idx: number, page_id: number): void;
+    unassign_slot(slot_idx: number): void;
+    mark_dirty(slot_idx: number): void;
+    clear_dirty(slot_idx: number): void;
+    is_dirty(slot_idx: number): boolean;
+    pin_slot(slot_idx: number): void;
+    unpin_slot(slot_idx: number): void;
+    pin_page(page_id: number): void;
+    unpin_page(page_id: number): void;
+    is_pinned(slot_idx: number): boolean;
+    get_pin_count(slot_idx: number): number;
+    get_ref_bit(slot_idx: number): number;
+    set_ref_bit(slot_idx: number, val: number): void;
+    get_slot_offset(slot_idx: number): number;
+    get_page_bytes_in_slot(slot_idx: number): Uint8Array;
+    get_slot_data_view(slot_idx: number): DataView;
+    get_resident_slot(page_id: number): number;
+    find_eviction_candidate_slot(): number;
+    get_arena_offset(): number;
+    alloc_arena(size: number): number;
+    reset_arena(): void;
+}
+//# sourceMappingURL=buffer_pool.c.d.ts.map

package/dist/core/js/buffer_pool.c.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buffer_pool.c.d.ts","sourceRoot":"","sources":["../../../src/core/js/buffer_pool.c.ts"],"names":[],"mappings":"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"}