dirsql 0.0.99-test.1775729890 → 0.1.3

package/README.md

@@ -0,0 +1,47 @@
+# `dirsql` (TypeScript SDK)
+
+TypeScript SDK for `dirsql` -- napi-rs bindings wrapping the Rust core (`dirsql`).
+
+[Documentation](https://thekevinscott.github.io/dirsql/?lang=typescript)
+
+## Installation
+
+```bash
+pnpm add dirsql
+```
+
+Requires a native build step (Rust toolchain). The native module is compiled during `pnpm build`.
+
+## Usage
+
+```typescript
+import { DirSQL } from "dirsql";
+
+const db = new DirSQL("/path/to/directory", [
+  {
+    ddl: "CREATE TABLE users (name TEXT, age INTEGER)",
+    glob: "data/*.json",
+    extract: (filePath, content) => JSON.parse(content),
+  },
+]);
+
+const rows = db.query("SELECT * FROM users WHERE age > 25");
+console.log(rows);
+```
+
+## Building
+
+```bash
+pnpm install
+pnpm build
+```
+
+## Testing
+
+```bash
+pnpm test
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,105 @@
+/** Definition of a SQL-indexed table backed by files on disk. */
+export interface TableDef {
+    /** SQL DDL statement, e.g. `CREATE TABLE users (name TEXT, age INTEGER)`. */
+    ddl: string;
+    /** Glob pattern (relative to the DirSQL root) for files backing this table. */
+    glob: string;
+    /** Extract rows from a file's contents. Returns an array of row objects. */
+    extract: (filePath: string, content: string) => Record<string, unknown>[];
+    /** If true, reject rows with columns not declared in `ddl`. */
+    strict?: boolean;
+}
+/** A row-level event emitted by the file watcher. */
+export interface RowEvent {
+    table: string;
+    action: "insert" | "update" | "delete" | "error";
+    row?: Record<string, unknown> | null;
+    oldRow?: Record<string, unknown> | null;
+    error?: string | null;
+    filePath?: string | null;
+}
+interface NativeDirSQL {
+    query(sql: string): Record<string, unknown>[];
+    startWatcher(): void;
+    pollEvents(timeoutMs: number): RowEvent[];
+}
+interface NativeDirSQLConstructor {
+    new (root: string, tables: TableDef[], ignore?: string[]): NativeDirSQL;
+    fromConfig(configPath: string): NativeDirSQL;
+}
+interface CoreModule {
+    DirSQL: NativeDirSQLConstructor;
+}
+/**
+ * **Test-only.** Replace the core module used by the SDK with a fake.
+ *
+ * This is an internal escape hatch for unit tests that want to mock the
+ * napi-rs binding layer without loading the real native binary. Passing
+ * `null` resets to the default (lazy native load on next access). Not
+ * part of the public API; do not use in application code.
+ */
+export declare function __setCoreForTesting(fake: CoreModule | null): void;
+/**
+ * Ephemeral SQL index over a local directory.
+ *
+ * Constructing a `DirSQL` scans `root`, matches files against each
+ * {@link TableDef}'s `glob`, extracts rows via `extract`, and builds an
+ * in-memory SQLite database. `query` / `startWatcher` / `pollEvents`
+ * are synchronous; {@link ready} and {@link watch} expose the same
+ * surface in an async-idiomatic shape so TypeScript consumers don't
+ * need a separate `AsyncDirSQL` class.
+ *
+ * ```ts
+ * const db = new DirSQL(root, tables);
+ * await db.ready;
+ * const rows = db.query("SELECT ...");
+ * for await (const event of db.watch()) { ... }
+ * ```
+ */
+export declare class DirSQL {
+    /**
+     * Resolves once the initial directory scan has completed. Scanning
+     * runs synchronously inside the constructor, so this Promise is
+     * already resolved by the time the constructor returns; construction
+     * failures throw synchronously rather than surfacing here. Exposed
+     * as a Promise purely so consumers can write async-style code
+     * uniformly across SDKs.
+     */
+    readonly ready: Promise<void>;
+    private _inner;
+    constructor(root: string, tables: TableDef[], ignore?: string[]);
+    /**
+     * Load a {@link DirSQL} instance from a `.dirsql.toml` config file.
+     *
+     * The root directory is derived from the config file's parent. Tables
+     * are parsed using the built-in parser for each format declared in the
+     * config. No JS `extract` callback is required.
+     */
+    static fromConfig(configPath: string): DirSQL;
+    /** Execute a SQL query and return results as an array of row objects. */
+    query(sql: string): Record<string, unknown>[];
+    /**
+     * Start the file watcher. Must be called before {@link pollEvents}.
+     * Idempotent — safe to call multiple times.
+     */
+    startWatcher(): void;
+    /**
+     * Poll for file change events, blocking up to `timeoutMs` for the first
+     * event. Returns all events observed in the window (possibly empty).
+     */
+    pollEvents(timeoutMs: number): RowEvent[];
+    /**
+     * Watch for file change events as an async iterable.
+     *
+     * ```ts
+     * for await (const event of db.watch()) { ... }
+     * ```
+     *
+     * Starts the underlying watcher on first iteration, then polls in 200ms
+     * increments and yields each {@link RowEvent}. The iterator runs
+     * indefinitely; break out of the `for await` loop to stop.
+     */
+    watch(): AsyncGenerator<RowEvent, void, unknown>;
+}
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../ts/index.ts"],"names":[],"mappings":"AAgBA,iEAAiE;AACjE,MAAM,WAAW,QAAQ;IACvB,6EAA6E;IAC7E,GAAG,EAAE,MAAM,CAAC;IACZ,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,OAAO,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAC1E,+DAA+D;IAC/D,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,qDAAqD;AACrD,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;IACjD,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACxC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAGD,UAAU,YAAY;IACpB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAC9C,YAAY,IAAI,IAAI,CAAC;IACrB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,EAAE,CAAC;CAC3C;AAED,UAAU,uBAAuB;IAC/B,KAAK,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,YAAY,CAAC;IACxE,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,CAAC;CAC9C;AAID,UAAU,UAAU;IAClB,MAAM,EAAE,uBAAuB,CAAC;CACjC;AAwBD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,GAAG,IAAI,CAEjE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,MAAM;IACjB;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9B,OAAO,CAAC,MAAM,CAAe;gBAEjB,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE;IAS/D;;;;;;OAMG;IACH,MAAM,CAAC,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;IAW7C,yEAAyE;IACzE,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE;IAI7C;;;OAGG;IACH,YAAY,IAAI,IAAI;IAIpB;;;OAGG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,EAAE;IAIzC;;;;;;;;;;OAUG;IACI,KAAK,IAAI,cAAc,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC;CASxD"}

package/dist/index.js

@@ -0,0 +1,129 @@
+"use strict";
+// dirsql TypeScript SDK.
+//
+// The public surface is implemented in Rust via napi-rs. `pnpm build` runs
+// `napi build` which produces `dirsql.node` at the package root, then
+// `tsc` compiles this file to `dist/index.js` + `dist/index.d.ts`, which
+// is what consumers import via the package's `main` / `types` / `exports`
+// fields.
+//
+// The native binary lives at the package root (not in `dist/`) because
+// that is where napi-rs writes it and where `napi prepublish` expects it.
+// We resolve it relative to this file's location at runtime so the
+// loader works whether the package is consumed via `node_modules/dirsql`
+// or via a pnpm workspace self-reference from `test/`.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DirSQL = void 0;
+exports.__setCoreForTesting = __setCoreForTesting;
+const node_path_1 = require("node:path");
+// Lazy-loaded reference to the core module. Populated on first access
+// by `loadNativeCore()`, or by `__setCoreForTesting()` for tests.
+let core = null;
+/**
+ * Load the native napi-rs binary. Resolved relative to this compiled
+ * module: after `tsc` emits to `dist/`, `__dirname` is `<pkg>/dist`, so
+ * `..` reaches the package root where napi-rs writes `dirsql.node`.
+ */
+function loadNativeCore() {
+    const bindingPath = (0, node_path_1.join)(__dirname, "..", "dirsql.node");
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    return require(bindingPath);
+}
+function getCore() {
+    if (core === null) {
+        core = loadNativeCore();
+    }
+    return core;
+}
+/**
+ * **Test-only.** Replace the core module used by the SDK with a fake.
+ *
+ * This is an internal escape hatch for unit tests that want to mock the
+ * napi-rs binding layer without loading the real native binary. Passing
+ * `null` resets to the default (lazy native load on next access). Not
+ * part of the public API; do not use in application code.
+ */
+function __setCoreForTesting(fake) {
+    core = fake;
+}
+/**
+ * Ephemeral SQL index over a local directory.
+ *
+ * Constructing a `DirSQL` scans `root`, matches files against each
+ * {@link TableDef}'s `glob`, extracts rows via `extract`, and builds an
+ * in-memory SQLite database. `query` / `startWatcher` / `pollEvents`
+ * are synchronous; {@link ready} and {@link watch} expose the same
+ * surface in an async-idiomatic shape so TypeScript consumers don't
+ * need a separate `AsyncDirSQL` class.
+ *
+ * ```ts
+ * const db = new DirSQL(root, tables);
+ * await db.ready;
+ * const rows = db.query("SELECT ...");
+ * for await (const event of db.watch()) { ... }
+ * ```
+ */
+class DirSQL {
+    constructor(root, tables, ignore) {
+        const Ctor = getCore().DirSQL;
+        this._inner =
+            ignore === undefined
+                ? new Ctor(root, tables)
+                : new Ctor(root, tables, ignore);
+        this.ready = Promise.resolve();
+    }
+    /**
+     * Load a {@link DirSQL} instance from a `.dirsql.toml` config file.
+     *
+     * The root directory is derived from the config file's parent. Tables
+     * are parsed using the built-in parser for each format declared in the
+     * config. No JS `extract` callback is required.
+     */
+    static fromConfig(configPath) {
+        const instance = Object.create(DirSQL.prototype);
+        const writable = instance;
+        writable._inner = getCore().DirSQL.fromConfig(configPath);
+        writable.ready = Promise.resolve();
+        return instance;
+    }
+    /** Execute a SQL query and return results as an array of row objects. */
+    query(sql) {
+        return this._inner.query(sql);
+    }
+    /**
+     * Start the file watcher. Must be called before {@link pollEvents}.
+     * Idempotent — safe to call multiple times.
+     */
+    startWatcher() {
+        this._inner.startWatcher();
+    }
+    /**
+     * Poll for file change events, blocking up to `timeoutMs` for the first
+     * event. Returns all events observed in the window (possibly empty).
+     */
+    pollEvents(timeoutMs) {
+        return this._inner.pollEvents(timeoutMs);
+    }
+    /**
+     * Watch for file change events as an async iterable.
+     *
+     * ```ts
+     * for await (const event of db.watch()) { ... }
+     * ```
+     *
+     * Starts the underlying watcher on first iteration, then polls in 200ms
+     * increments and yields each {@link RowEvent}. The iterator runs
+     * indefinitely; break out of the `for await` loop to stop.
+     */
+    async *watch() {
+        this._inner.startWatcher();
+        while (true) {
+            const events = this._inner.pollEvents(200);
+            for (const event of events) {
+                yield event;
+            }
+        }
+    }
+}
+exports.DirSQL = DirSQL;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../ts/index.ts"],"names":[],"mappings":";AAAA,yBAAyB;AACzB,EAAE;AACF,2EAA2E;AAC3E,sEAAsE;AACtE,yEAAyE;AACzE,0EAA0E;AAC1E,UAAU;AACV,EAAE;AACF,uEAAuE;AACvE,0EAA0E;AAC1E,mEAAmE;AACnE,yEAAyE;AACzE,uDAAuD;;;AA0EvD,kDAEC;AA1ED,yCAAiC;AA0CjC,sEAAsE;AACtE,kEAAkE;AAClE,IAAI,IAAI,GAAsB,IAAI,CAAC;AAEnC;;;;GAIG;AACH,SAAS,cAAc;IACrB,MAAM,WAAW,GAAG,IAAA,gBAAI,EAAC,SAAS,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC;IACzD,iEAAiE;IACjE,OAAO,OAAO,CAAC,WAAW,CAAe,CAAC;AAC5C,CAAC;AAED,SAAS,OAAO;IACd,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,IAAI,GAAG,cAAc,EAAE,CAAC;IAC1B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,mBAAmB,CAAC,IAAuB;IACzD,IAAI,GAAG,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAa,MAAM;IAajB,YAAY,IAAY,EAAE,MAAkB,EAAE,MAAiB;QAC7D,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC,MAAM,CAAC;QAC9B,IAAI,CAAC,MAAM;YACT,MAAM,KAAK,SAAS;gBAClB,CAAC,CAAC,IAAI,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC;gBACxB,CAAC,CAAC,IAAI,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QACrC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IACjC,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,UAAU,CAAC,UAAkB;QAClC,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAW,CAAC;QAC3D,MAAM,QAAQ,GAAG,QAGhB,CAAC;QACF,QAAQ,CAAC,MAAM,GAAG,OAAO,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;QAC1D,QAAQ,CAAC,KAAK,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;QACnC,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,yEAAyE;IACzE,KAAK,CAAC,GAAW;QACf,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;IAED;;;OAGG;IACH,YAAY;QACV,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;IAC7B,CAAC;IAED;;;OAGG;IACH,UAAU,CAAC,SAAiB;QAC1B,OAAO,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;IAC3C,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,CAAC,KAAK;QACV,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;QAC3B,OAAO,IAAI,EAAE,CAAC;YACZ,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;YAC3C,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;gBAC3B,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC;IACH,CAAC;CACF;AAjFD,wBAiFC"}

package/package.json

@@ -1,11 +1,52 @@
 {
   "name": "dirsql",
-  "version": "0.0.99-test.1775729890",
+  "version": "0.1.3",
   "description": "Ephemeral SQL index over a local directory",
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/thekevinscott/dirsql.git"
+  "repository": "https://github.com/thekevinscott/dirsql",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
   },
-  "main": "index.js"
-}
+  "files": [
+    "dist/",
+    "dirsql.node"
+  ],
+  "napi": {
+    "binaryName": "dirsql",
+    "triples": {}
+  },
+  "scripts": {
+    "artifacts": "napi artifacts",
+    "build": "napi build --release && tsc",
+    "build:debug": "napi build && tsc",
+    "prepublishOnly": "napi prepublish -t npm",
+    "test": "vitest run",
+    "test:unit": "vitest run --dir src --passWithNoTests",
+    "test:integration": "vitest run --dir test --passWithNoTests",
+    "coverage": "vitest run --coverage",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "format:check": "biome format ."
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.0",
+    "@napi-rs/cli": "^3.0.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.1.1",
+    "@vitest/coverage-v8": "^3.1.1"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "@biomejs/biome",
+      "esbuild"
+    ]
+  },
+  "optionalDependencies": {}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Kevin Scott
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/index.js

@@ -1,5 +0,0 @@
-"use strict";
-
-module.exports = {
-  message: "dirsql TypeScript SDK is not yet implemented. See https://github.com/thekevinscott/dirsql for status.",
-};