How abelcha/buckdb works
Project Type & Purpose
• BuckDB is a TypeScript/JavaScript library (NPM package) that provides a fluent API for building SQL queries.
• It ships two runtime back-ends:
– Node.js adapter via @duckdb/node-api
– WASM adapter via @duckdb/duckdb-wasm
• It also includes a standalone demo application (web UI built with Vite) and CLI scripts (demo.ts, demo_showcase.ts) that showcase the library.
Top-Level Components (from file tree)
• Core Library (src/)
– Parser & AST (jsep.ts, parser.ts)
– Query Builder & Fluent API (build.ts, copy.ts, serializers, interface-generator.ts)
– Type System & Sync (type-system, sync-types.ts)
– Utility modules (readers.ts, utils.ts)
• Entry Points
– buckdb.ts (Node.js adapter entry)
– buckdb.wasm.ts (WASM adapter entry)
• Demo Application (demo/)
– Frontend (HTML, CSS, Vite config)
– Features modules (intellisense, debugger, editor, terminal, etc.)
– Web Workers (crossOriginWorker.ts, extHostWorker.ts, fakeWorker.ts)
• CLI Scripts (demo.ts, demo_showcase.ts)
• Config & Build files (tsconfig.json, package.json, bun.lockb, dprint.json)
Key Architectural Patterns & Principles
• Adapter Pattern – isolates the DuckDB back-end (Node vs WASM) behind a common API.
• Layered Modular Design –
– Layer 1: Public API (from(), copy())
– Layer 2: Core engine (parser → builder → serializer)
– Layer 3: Runtime backend (DuckDB node-api or WASM)
– Layer 4: I/O sinks (filesystem, HTTP(S), S3, in-memory)
• Separation of Concerns – demo UI is fully decoupled from core library code.
• Plugin-style extension for DuckDB functions (D.* in where()/select()).