dirsql

library0.3.22jsnpmunverified

dirsql is a TypeScript SDK that provides an ephemeral SQL index over a local directory using napi-rs bindings to a Rust core. It allows querying file contents with SQL by defining tables with glob patterns and extraction functions. Version 0.3.22 is stable, requires Node >=22, and ships with prebuilt binaries for Linux, macOS, and Windows. Key differentiators include zero Rust toolchain requirement for end users, hybrid JS/TS typing, and full SQL select support over file system data.

database

npm install dirsql

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · DIRSQL

dirsql

databasejavascriptv0.3.22

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.

DirSQL

✓ import { DirSQL } from 'dirsql'

✗ const DirSQL = require('dirsql')

dirsql is ESM-only; CommonJS require() will fail.

DirSQL

✓ import type { DirSQL } from 'dirsql'

✗ import { DirSQL } from 'dirsql'

DirSQL is also available as a type for TypeScript interfaces; use 'import type' if only needing types at compile time.

default export

✓ import DirSQL from 'dirsql'

✗ import { DirSQL } from 'dirsql'

dirsql also has a default export which provides the same DirSQL class. Both work, but default import may be preferred for consistency.

Creates a DirSQL instance over a directory, defines a table from JSON files, and runs a SQL query.

import { readFileSync } from 'node:fs'; import { DirSQL } from 'dirsql'; const db = new DirSQL({ root: '/path/to/directory', tables: [ { ddl: 'CREATE TABLE users (name TEXT, age INTEGER)', glob: 'data/*.json', extract: (filePath) => JSON.parse(readFileSync(filePath, 'utf8')), }, ], }); const rows = await db.query('SELECT * FROM users WHERE age > 25'); console.log(rows);

Debug

Known issues

breakingNode.js version >=22 required; older versions will throw a runtime error.

fix

Upgrade Node.js to version 22 or later.

affects: <22.0.0

deprecatedThe API changed during version 0.x; breaking changes may occur without major version bump.

fix

Pin to a specific version and test upgrades carefully.

affects: >=0.1.0 <1.0.0

gotchaEmpty tables or files not matching glob will cause empty query results, not errors.

fix

Verify that files exist and glob patterns are correct.

affects: *

gotchaPrebuilt binaries are not available for all architectures (e.g., musl Linux). In such cases, installation will attempt to build from source, which requires the Rust toolchain.

fix

Install Rust via rustup if prebuilt binary is not available for your platform.

affects: *

Errors

Common errors & fixes

Error: Cannot find module 'dirsql'

Missing installation or incorrect import path (e.g., requiring CommonJS in ESM context).

fix

Run 'pnpm add dirsql' and use 'import { DirSQL } from 'dirsql''

TypeError: dirsql_1.default is not a constructor

Using default import when library expects named import (or vice versa).

fix

Use 'import { DirSQL } from 'dirsql'' instead of 'import DirSQL from 'dirsql'' or vice versa.

Error: This constructor is not supported on your current platform

Prebuilt binary not available for the current OS/architecture, and no Rust toolchain to compile from source.

fix

Install Rust toolchain or use a supported platform (linux-x64, linux-arm64, darwin-x64, darwin-arm64, win32-x64).

Error: The specified module could not be found (on Windows)

Missing required native dependencies (e.g., Visual C++ Redistributable).

fix

Install Visual C++ Redistributable for Visual Studio 2015-2022.

Upgrade

Version history

0.3.22latest on npm

Audit

Dependencies

@napi-rs/clioptionalInternal build tool for napi-rs bindings; required only when building from source.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/thekevinscott/dirsql ↗

packagedirsql ↗

homepagehttps://github.com/thekevinscott/dirsql#readme ↗