flatsql

library1.0.1jsnpmunverified

FlatSQL is a streaming query engine (v1.0.1, Apache 2.0) that enables SQL queries directly over raw FlatBuffer data using SQLite virtual tables. Unlike traditional approaches that require deserializing FlatBuffers into SQLite rows (which is expensive), FlatSQL provides zero-conversion access with real-time indexing and pure streaming ingestion. It supports multiple FlatBuffer sources with automatic source tagging and is available as a WASM module for browsers and Node.js (requires Node ≥24). Key differentiators include: zero-copy access, portable FlatBuffer output, and multi-source federation. Active development, with TypeScript types included.

database

npm install flatsql

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · FLATSQL

flatsql

databasejavascriptv1.0.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

initFlatSQL

✓ import { initFlatSQL } from 'flatsql/wasm'

✗ const { initFlatSQL } = require('flatsql/wasm')

ESM-only since v1.0.0; CJS require() will fail because the package uses native ESM.

FlatSQLDatabase

✓ import { FlatSQLDatabase } from 'flatsql'

✗ import { FlatSQLDatabase } from 'flatsql/wasm'

The pure TypeScript in-memory database is exported from the main entry. The WASM-backed class is only available in 'flatsql/wasm'.

WASIRunner

✓ import { WASIRunner } from 'flatsql/standalone'

For standalone Node/WasmEdge hosts; not available in browser bundles. TypeScript types are exported from the same path.

Initializes FlatSQL WASM engine, creates a database with a schema, ingests a FlatBuffer file, runs a parameterized SQL query, and exports the result.

import { initFlatSQL } from 'flatsql/wasm'; import { readFileSync } from 'fs'; // Initialize the WASM engine (Node.js >=24.0.0) const flatsql = await initFlatSQL(); // Create a database with a schema const db = flatsql.createDatabase(` table User { id: int (id); name: string; email: string (key); age: int; } `, 'myapp'); // Register a file identifier for routing (must match FlatBuffer file_identifier) db.registerFileId('USER', 'User'); // Ingest a FlatBuffer from a file (streaming) const buffer = readFileSync('users.bfbs'); db.ingest(buffer); // Query with SQL const result = db.query('SELECT name, email FROM User WHERE age > ?', [25]); console.log(result.columns); // ['name', 'email'] console.log(result.rows); // [['Alice', 'alice@example.com'], ...] // Export as standard FlatBuffer db.export('users_export.bfbs');

Debug

Known issues

breakingNode.js version requirement: flatsql v1.x requires Node.js >= 24.0.0 due to WASI support.

fix

Upgrade Node.js to v24 or later. Check compatibility with your runtime environment.

affects: >=1.0.0

deprecatedinitFlatSQL was renamed from createEngine in v1.0.0; createEngine is still available but deprecated.

fix

Use initFlatSQL() instead of createEngine().

affects: >=1.0.0, <1.0.0

gotchaESM-only: flatsql uses native ES modules. CommonJS require() will throw ERR_REQUIRE_ESM.

fix

Use import instead of require, or enable dynamic import() in a CommonJS context.

affects: >=1.0.0

gotchaWASM path requires proper MIME type and Cross-Origin-Embedder-Policy in browser environments.

fix

Serve WASM with applicatio/wasm MIME type and set COEP: require-corp on the page.

affects: all

gotchaSchema definition must use the FlatSQL-specific syntax (not standard FlatBuffers .fbs).

fix

Use the createDatabase() first argument with the DSL shown in the quickstart; compile .fbs separately if needed.

affects: all

Errors

Common errors & fixes

Error: async_hooks is not supported in this runtime

Flatsql's WASM runner requires Node.js async hooks; not available in some edge runtimes like Cloudflare Workers.

fix

Use the browser WASM path with a compatible bundler, or switch to a Node.js v24+ environment.

RangeError: WebAssembly.Instance(): Out of memory

FlatSQL WASM instance requires significant memory; the default allocation may be insufficient for large datasets.

fix

Provide initial memory setting via initFlatSQL options: initFlatSQL({ initialMemory: 256 * 1024 * 1024 }).

TypeError: flatsql is not a function

Misunderstanding that initFlatSQL returns a database object directly; it's an async function that returns an engine.

fix

Call initFlatSQL() then call createDatabase() on the returned engine: const engine = await initFlatSQL(); const db = engine.createDatabase(...).

Error: ENOTSUP: operation not supported on socket

Caused by using the WASI runner in an environment without proper socket support (e.g., WSL1).

fix

Switch to the browser path or ensure a full Node.js v24 environment with WASI support (WSL2 recommended).

Upgrade

Version history

1.0.1latest on npm

Audit

Dependencies

flatbuffersrequiredFlatSQL depends on the flatbuffers package for schema compilation and runtime binary access

better-sqlite3optionalSQLite virtual table backend used as a peer dependency for non-WASM builds

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/DigitalArsenal/flatsql ↗

packageflatsql ↗

homepagehttps://digitalarsenal.github.io/flatsql/ ↗