@weebforge/db

A high-performance, deterministic data layer for Node.js. This is a controlled abstraction layer that enforces consistency and speed over SQLite via the native node:sqlite engine. Built with a synchronous core to guarantee predictable performance and zero event-loop blocking overhead.

Prerequisites: Node.js >= 22.5.0 is strictly required as it leverages the natively built-in SQLite driver.

Installation

npm install @weebforge/db

Quick Start (Code)

import{WeebDB}from'@weebforge/db';constdb=newWeebDB({path: './data.db'});// KV Storagedb.set('user:id',{username: 'admin'});constuser=db.get('user:id');// Structured Tablesdb.defineTable('users',{columns: {id: {type: 'INTEGER',primaryKey: true},username: {type: 'TEXT',unique: true}}});db.table('users').insert({username: 'admin'});

Quick Start (CLI)

The package includes a deterministic CLI tool for management and interaction.

# Initialize a new config and database
npx wdb init
# Write and read data directly from terminal
npx wdb kv set config '{"theme":"dark"}'
npx wdb kv get config --json
# Run local benchmark suite
npx wdb bench

Documentation

Full documentation is split into dedicated guides:

1. Key-Value Store Usage
2. Structured Table Management
3. CLI Reference

Architecture Notes

• Fully synchronous core, preventing event loop context switching penalties.
• Prepared statement pool handles caching and execution reuse natively.
• WAL mode and optimized memory pragmas configured by default.