dirsql 0.3.31 → 0.3.33

package/README.md

@@ -1,6 +1,6 @@
 # `dirsql` (TypeScript SDK)
 
-TypeScript SDK for `dirsql` -- napi-rs bindings wrapping the Rust core (`dirsql`).
+Ephemeral SQL index over a local directory. `dirsql` watches a filesystem, ingests structured files into an in-memory SQLite database, and exposes a SQL query interface -- the filesystem is always the source of truth. Built on the Rust core via napi-rs bindings.
 
 [Documentation](https://thekevinscott.github.io/dirsql/?lang=typescript)
 
@@ -9,32 +9,88 @@ Also available as [`dirsql` on crates.io](https://crates.io/crates/dirsql) and [
 ## Installation
 
 ```bash
-pnpm add dirsql
+npm add dirsql
 ```
 
-Prebuilt binaries ship for linux-x64, linux-arm64, darwin-x64, darwin-arm64, and win32-x64. npm / pnpm pick up the right one via `optionalDependencies` — no Rust toolchain required.
+Prebuilt binaries ship for linux-x64, linux-arm64, darwin-x64, darwin-arm64, and win32-x64; npm picks up the right one via `optionalDependencies`, so no Rust toolchain is required. The npm CLI requires **Node >= 20.11**.
 
-## Usage
+## Quick start
+
+Constructing a `DirSQL` returns immediately; scanning runs in the background and every method awaits it, so you can query right away (or `await db.ready` to surface scan errors up front). Each table is a `(ddl, glob, extract)` object: the DDL defines the SQLite schema, the glob selects files (relative to `root`), and `extract` returns the rows a matched file contributes -- always an array, return `[]` to skip a file. `dirsql` does not read file contents; if `extract` needs the file body it reads `path` itself.
+
+```typescript
+import { readFileSync } from "node:fs";
+import { DirSQL, type TableDef } from "dirsql";
+
+const tables: TableDef[] = [
+  {
+    ddl: "CREATE TABLE posts (title TEXT, author TEXT)",
+    glob: "posts/*.json",
+    extract: (path) => [JSON.parse(readFileSync(path, "utf8"))],
+  },
+];
+
+const db = new DirSQL({ root: "./my-blog", tables });
+
+const posts = await db.query("SELECT * FROM posts WHERE author = 'alice'");
+console.log(posts);
+```
+
+## Multiple tables and joins
 
 ```typescript
 import { readFileSync } from "node:fs";
-import { DirSQL } from "dirsql";
+import { DirSQL, type TableDef } from "dirsql";
 
+const tables: TableDef[] = [
+  {
+    ddl: "CREATE TABLE posts (title TEXT, author_id TEXT)",
+    glob: "posts/*.json",
+    extract: (path) => [JSON.parse(readFileSync(path, "utf8"))],
+  },
+  {
+    ddl: "CREATE TABLE authors (id TEXT, name TEXT)",
+    glob: "authors/*.json",
+    extract: (path) => [JSON.parse(readFileSync(path, "utf8"))],
+  },
+];
+
+const db = new DirSQL({ root: "./my-blog", tables });
+
+const results = await db.query(`
+  SELECT posts.title, authors.name
+  FROM posts JOIN authors ON posts.author_id = authors.id
+`);
+```
+
+## Ignoring files
+
+Pass `ignore` patterns to skip files during scanning and watching:
+
+```typescript
 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")),
-    },
-  ],
+  root: "./my-blog",
+  tables: [/* ... */],
+  ignore: ["**/drafts/**", "**/.git/**"],
 });
+```
+
+## Watching for changes
 
-const rows = await db.query("SELECT * FROM users WHERE age > 25");
-console.log(rows);
+`db.watch()` returns an async iterable of row-level change events as files change on disk:
+
+```typescript
+for await (const event of db.watch()) {
+  console.log(`${event.action} on ${event.table}:`, event.row);
+}
 ```
 
+Each event has `.action` (`'insert'` | `'update'` | `'delete'` | `'error'`), `.table`, `.row` (the new row, or the deleted row on `delete`), `.oldRow` (the previous row, on `update`), `.filePath`, and `.error` (on `error`).
+
+## CLI
+
+`npx dirsql` runs an HTTP server exposing the SDK over HTTP: `POST /query` for SQL and `GET /events` for a Server-Sent Events change stream. Requires **Node >= 20.11**. See the [CLI guide](https://thekevinscott.github.io/dirsql/cli/).
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dirsql",
-  "version": "0.3.31",
+  "version": "0.3.33",
   "description": "Ephemeral SQL index over a local directory",
   "license": "MIT",
   "repository": "https://github.com/thekevinscott/dirsql",
@@ -178,7 +178,8 @@
   "devDependencies": {
     "@biomejs/biome": "^1.9.0",
     "@napi-rs/cli": "^3.0.0",
-    "@types/node": "^22.0.0",
+    "@tsconfig/node20": "^20.1.9",
+    "@types/node": "^20.19.43",
     "@types/sql.js": "^1.4.11",
     "@vitest/coverage-v8": "^3.1.1",
     "sql.js": "^1.14.1",
@@ -197,15 +198,15 @@
     "smol-toml": "^1.6.1"
   },
   "optionalDependencies": {
-    "@dirsql/lib-linux-x64-gnu": "0.3.31",
-    "@dirsql/lib-linux-arm64-gnu": "0.3.31",
-    "@dirsql/lib-darwin-x64": "0.3.31",
-    "@dirsql/lib-darwin-arm64": "0.3.31",
-    "@dirsql/lib-win32-x64-msvc": "0.3.31",
-    "@dirsql/cli-linux-x64-gnu": "0.3.31",
-    "@dirsql/cli-linux-arm64-gnu": "0.3.31",
-    "@dirsql/cli-darwin-x64": "0.3.31",
-    "@dirsql/cli-darwin-arm64": "0.3.31",
-    "@dirsql/cli-win32-x64-msvc": "0.3.31"
+    "@dirsql/lib-linux-x64-gnu": "0.3.33",
+    "@dirsql/lib-linux-arm64-gnu": "0.3.33",
+    "@dirsql/lib-darwin-x64": "0.3.33",
+    "@dirsql/lib-darwin-arm64": "0.3.33",
+    "@dirsql/lib-win32-x64-msvc": "0.3.33",
+    "@dirsql/cli-linux-x64-gnu": "0.3.33",
+    "@dirsql/cli-linux-arm64-gnu": "0.3.33",
+    "@dirsql/cli-darwin-x64": "0.3.33",
+    "@dirsql/cli-darwin-arm64": "0.3.33",
+    "@dirsql/cli-win32-x64-msvc": "0.3.33"
   }
 }