squirreling

library0.12.23jsnpmunverified

Squirreling (v0.12.23) is a streaming async SQL engine in pure JavaScript, designed for browser environments with zero dependencies. It supports standard SQL (read-only), pluggable data sources, lazy async cell evaluation, and async user-defined functions (UDFs). Key differentiators: cell-level lazy evaluation reduces unnecessary computation for network/LLM sources; true streaming via AsyncGenerators; 13 kB bundle size. Unlike WebAssembly databases, it is fully async and works where network latency matters. Ships TypeScript types.

database search

npm install squirreling

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SQUIRRELING

squirreling

databasejavascriptv0.12.23

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.

executeSql

✓ import { executeSql } from 'squirreling'

✗ const { executeSql } = require('squirreling')

ESM-only; CommonJS require will fail. Package is ESM with no CJS fallback.

collect

✓ import { collect } from 'squirreling'

✗ import collect from 'squirreling'

collect is a named export, not default. Both executeSql and collect are named.

QueryResults

✓ import type { QueryResults } from 'squirreling'

✗ import { QueryResults } from 'squirreling'

QueryResults is a TypeScript interface, not a runtime value. Use type import to avoid bundler issues.

AsyncRow

✓ import type { AsyncRow } from 'squirreling'

✗ const AsyncRow = require('squirreling').AsyncRow

AsyncRow is a TypeScript type/interface; cannot import at runtime.

Shows basic usage: execute SQL on an in-memory array, collect all rows into an array, and filter with WHERE.

import { executeSql, collect } from 'squirreling'; const users = [ { id: 1, name: 'Alice', active: true }, { id: 2, name: 'Bob', active: false }, { id: 3, name: 'Charlie', active: true }, ]; async function main() { const result = await collect(executeSql({ tables: { users }, query: 'SELECT * FROM users WHERE active = true', })); console.log(result); // [ { id: 1, name: 'Alice', active: true }, { id: 3, name: 'Charlie', active: true } ] } main().catch(console.error);

Debug

Known issues

breakingESM-only package: using require() will throw 'ERR_REQUIRE_ESM'. Must use import syntax.

fix

Use ES module imports (import) or dynamic import() in CommonJS files. Alternatively, set "type": "module" in package.json.

affects: >=0.0.0

breakingTypeScript types are shipped but are strict: interfaces like QueryResults, AsyncRow are not runtime values. Attempting to use them as objects will fail.

fix

Use type-only imports: import type { QueryResults } from 'squirreling'.

affects: >=0.0.0

gotchaLazy evaluation: cells are async thunks; calling cells.id() without await returns a Promise, not the value. Forgetting await will lead to Promise objects in output.

fix

Always await cell functions: const val = await cells.id(). Use helper collect() to materialize all cells.

affects: >=0.0.0

gotchaRead-only queries: SQL DELETE, UPDATE, INSERT are not supported. Using them will throw an error.

fix

Only use SELECT queries. For mutations, handle them outside Squirreling.

affects: >=0.0.0

deprecatedThe tables option expects objects; passing an array instead of a named object may cause a Silent failure in older versions.

fix

Upgrade to >=0.12.0; the library now validates table formats.

affects: <0.12.0

Errors

Common errors & fixes

Error: Cannot find module 'squirreling'

Missing dependency or incorrect package.json configuration (e.g., no type: module).

fix

Run npm install squirreling and ensure your project uses ESM (type: module in package.json or .mjs extension).

TypeError: executeSql is not a function

Using CommonJS require which returns an ESM module that does not export via module.exports.

fix

Switch to ES module import: import { executeSql } from 'squirreling'.

TypeError: cells.id is not a function

Accessing cells[column] directly instead of calling it as a function.

fix

Use await cells.id() instead of cells.id. Cells are functions returning promises.

Error: SQL syntax error at line 1: DELETE not allowed

Attempting to run a non-SELECT query (INSERT, UPDATE, DELETE).

fix

Only SELECT queries are supported. Remove mutation statements.

Upgrade

Version history

0.12.23latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

39 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/hyparam/squirreling ↗

packagesquirreling ↗

homepagehttps://hyperparam.app ↗