dirsql 0.3.41 → 0.3.43

package/dist/cli/dirsql.js

@@ -1,17 +1,14 @@
 #!/usr/bin/env node
 // npm `bin` entry for `dirsql`. The package.json `bin` field points at
 // the compiled version of this file; npm symlinks `node_modules/.bin/dirsql`
-// to it. Always runs the launcher -- nothing else should import this
-// file (test the helpers in `main.ts` / `resolve-binary.ts` instead).
+// to it. All it does is invoke `runCli()` (see `run-cli.ts`); the launcher
+// logic and its error handling live there so they can be unit-tested.
 //
 // A prior `process.argv[1] === import.meta.filename` self-detection
 // guard tripped up the npm-bin symlink: argv[1] is the (unresolved)
 // symlink path, while import.meta.filename is the realpath, and the
 // guard silently skipped main() so `dirsql --version` produced no
 // output (caught by the pack-install build-CI smoke test).
-import { main } from "./main.js";
-main().catch((e) => {
-    process.stderr.write(`dirsql: ${e instanceof Error ? e.message : String(e)}\n`);
-    process.exit(1);
-});
+import { runCli } from "./run-cli.js";
+runCli();
 //# sourceMappingURL=dirsql.js.map

package/dist/cli/dirsql.js.map

@@ -1 +1 @@
-{"version":3,"file":"dirsql.js","sourceRoot":"","sources":["../../src/cli/dirsql.ts"],"names":[],"mappings":";AACA,uEAAuE;AACvE,6EAA6E;AAC7E,qEAAqE;AACrE,sEAAsE;AACtE,EAAE;AACF,oEAAoE;AACpE,oEAAoE;AACpE,oEAAoE;AACpE,kEAAkE;AAClE,2DAA2D;AAE3D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,CAAU,EAAE,EAAE;IAC1B,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,WAAW,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAC1D,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"dirsql.js","sourceRoot":"","sources":["../../src/cli/dirsql.ts"],"names":[],"mappings":";AACA,uEAAuE;AACvE,6EAA6E;AAC7E,2EAA2E;AAC3E,sEAAsE;AACtE,EAAE;AACF,oEAAoE;AACpE,oEAAoE;AACpE,oEAAoE;AACpE,kEAAkE;AAClE,2DAA2D;AAE3D,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC,MAAM,EAAE,CAAC"}

package/dist/cli/run-cli.d.ts

@@ -0,0 +1,2 @@
+export declare function runCli(): void;
+//# sourceMappingURL=run-cli.d.ts.map

package/dist/cli/run-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-cli.d.ts","sourceRoot":"","sources":["../../src/cli/run-cli.ts"],"names":[],"mappings":"AAOA,wBAAgB,MAAM,IAAI,IAAI,CAO7B"}

package/dist/cli/run-cli.js

@@ -0,0 +1,12 @@
+// The npm `bin` launcher's actual logic: run `main()` and translate a
+// rejection into a stderr message + non-zero exit. Split out of the
+// `dirsql.ts` entry shim so it carries a colocated unit test instead of
+// an exemption (#239).
+import { main } from "./main.js";
+export function runCli() {
+    main().catch((e) => {
+        process.stderr.write(`dirsql: ${e instanceof Error ? e.message : String(e)}\n`);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=run-cli.js.map

package/dist/cli/run-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-cli.js","sourceRoot":"","sources":["../../src/cli/run-cli.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,oEAAoE;AACpE,wEAAwE;AACxE,uBAAuB;AAEvB,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,MAAM,UAAU,MAAM;IACpB,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,CAAU,EAAE,EAAE;QAC1B,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,WAAW,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAC1D,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/core.d.ts

@@ -0,0 +1,16 @@
+import type { RowEvent } from "./dirsql.js";
+import type { TableDef } from "./table.js";
+export interface NativeDirSQL {
+    query(sql: string): Promise<Record<string, unknown>[]>;
+    startWatcher(): Promise<void>;
+    pollEvents(timeoutMs: number): Promise<RowEvent[]>;
+}
+export interface NativeDirSQLConstructor {
+    openAsync(root: string | null, tables: TableDef[] | null, ignore: string[] | null, config: string | null, persist: boolean | null, persistPath: string | null): Promise<NativeDirSQL>;
+}
+export interface CoreModule {
+    DirSQL: NativeDirSQLConstructor;
+    parseTableName(ddl: string): string | null;
+}
+export declare function getCore(): CoreModule;
+//# sourceMappingURL=core.d.ts.map

package/dist/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAG3C,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;IACvD,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;CACpD;AAED,MAAM,WAAW,uBAAuB;IACtC,SAAS,CACP,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,EACzB,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,EACvB,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,OAAO,EAAE,OAAO,GAAG,IAAI,EACvB,WAAW,EAAE,MAAM,GAAG,IAAI,GACzB,OAAO,CAAC,YAAY,CAAC,CAAC;CAC1B;AAID,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,uBAAuB,CAAC;IAChC,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CAC5C;AAQD,wBAAgB,OAAO,IAAI,UAAU,CAKpC"}

package/dist/core.js

@@ -0,0 +1,18 @@
+// Lazy access to the napi-rs core module, plus the test-only seam used to
+// swap in a fake binding without loading the real native binary.
+//
+// Split out of the public barrel (`index.ts`) so it carries a colocated
+// unit test instead of an exemption (#239).
+import { loadNativeCore as defaultLoadNativeCore } from "./load-native-core.js";
+// Lazy-loaded reference to the core module. Populated on first access by
+// `defaultLoadNativeCore()`. Unit tests don't reach this state: they
+// `vi.mock("./core.js")` to fake `getCore` directly, so production carries
+// no test-only injection seam.
+let core = null;
+export function getCore() {
+    if (core === null) {
+        core = defaultLoadNativeCore();
+    }
+    return core;
+}
+//# sourceMappingURL=core.js.map

package/dist/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,iEAAiE;AACjE,EAAE;AACF,wEAAwE;AACxE,4CAA4C;AAG5C,OAAO,EAAE,cAAc,IAAI,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AA4BhF,yEAAyE;AACzE,qEAAqE;AACrE,2EAA2E;AAC3E,+BAA+B;AAC/B,IAAI,IAAI,GAAsB,IAAI,CAAC;AAEnC,MAAM,UAAU,OAAO;IACrB,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,IAAI,GAAG,qBAAqB,EAAgB,CAAC;IAC/C,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/dirsql.d.ts

@@ -0,0 +1,167 @@
+import type { TableDef } from "./table.js";
+/**
+ * Options accepted by the {@link DirSQL} constructor.
+ *
+ * At least one of `root` or `config` must be supplied. When both are set,
+ * the explicit `root` wins over any `[dirsql].root` declared in the config
+ * file (a warning is emitted by the native layer).
+ */
+export interface DirSQLOptions {
+    /** Root directory to scan. */
+    root?: string;
+    /** Programmatic table definitions. Each table's `extract` runs in-process. */
+    tables?: TableDef[];
+    /** Glob patterns (relative to `root`) to ignore. */
+    ignore?: string[];
+    /**
+     * Path to a `.dirsql.toml` config file. Its `[[table]]` entries are
+     * appended to any programmatic `tables`; its `[dirsql].ignore` patterns
+     * are appended to any explicit `ignore`. If the config declares a
+     * `[dirsql].root` and no explicit `root` is given, it is resolved
+     * relative to the config file's parent directory.
+     */
+    config?: string;
+    /**
+     * Enable persistent on-disk SQLite cache. When `true`, the database is
+     * written to `<root>/.dirsql/cache.db` (override via `persistPath`) so
+     * subsequent startups only re-parse files that have actually changed.
+     */
+    persist?: boolean;
+    /**
+     * Override the location of the persistent cache file. Ignored when
+     * `persist` is not `true`.
+     */
+    persistPath?: string;
+}
+/** A row-level event emitted by the file watcher. */
+export interface RowEvent {
+    /**
+     * The table the event applies to. Always set for insert / update / delete.
+     * May be `null` on error events that occur before a file is attributed
+     * to any table (e.g. a watch-channel failure).
+     */
+    table: string | null;
+    action: "insert" | "update" | "delete" | "error";
+    row?: Record<string, unknown> | null;
+    oldRow?: Record<string, unknown> | null;
+    error?: string | null;
+    filePath?: string | null;
+}
+/**
+ * Serializable per-table portion of {@link DirSQLConfig}. Excludes the
+ * `extract` callback (closures aren't serializable) and the table's SQL
+ * `name` (derivable from `ddl`).
+ */
+export interface TableConfig {
+    ddl: string;
+    glob: string;
+    strict: boolean;
+}
+/**
+ * Serializable snapshot of a {@link DirSQL} instance's resolved runtime
+ * state, as produced by {@link DirSQL.toJSON} / `JSON.stringify(db)`.
+ *
+ * The shape is identical across the Python, Rust, and TypeScript SDKs
+ * (modulo `persist_path` ↔ `persistPath` case): the same payload can flow
+ * through the `interpret` handshake regardless of which SDK produced it.
+ *
+ * Construction artifacts that are no longer meaningful after the instance
+ * exists are intentionally excluded — `config` (already merged into `root`
+ * / `tables` / `ignore`), per-table `extract`, and per-table `name`.
+ */
+export interface DirSQLConfig {
+    root: string;
+    tables: TableConfig[];
+    ignore: string[];
+    persist: boolean;
+    persistPath: string | null;
+}
+/**
+ * Ephemeral SQL index over a local directory.
+ *
+ * The constructor is overloaded: pass a config-file path directly, or an
+ * options object with any combination of `root`, `tables`, `ignore`, and
+ * `config`.
+ *
+ * Constructing a `DirSQL` returns immediately; the directory scan, file
+ * reads, and initial row extraction run asynchronously. `db.ready`
+ * resolves once construction has completed, and every method (including
+ * {@link query}, {@link startWatcher}, {@link pollEvents}, and
+ * {@link watch}) transparently awaits `ready` before doing any work, so
+ * callers can start using the instance immediately:
+ *
+ * ```ts
+ * // From a config file:
+ * const db = new DirSQL("./my-config.toml");
+ *
+ * // Programmatic:
+ * const db2 = new DirSQL({ root: "./data", tables: [...] });
+ *
+ * await db.ready; // optional: wait for the initial scan explicitly
+ * const rows = await db.query("SELECT ...");
+ * for await (const event of db.watch()) { ... }
+ * ```
+ *
+ * The scan runs on the libuv threadpool, so constructing a `DirSQL` does
+ * not block the JS event loop even for large directories.
+ */
+export declare class DirSQL {
+    /**
+     * Resolves once the initial directory scan + row extraction have
+     * completed, or rejects if construction failed. Every other method on
+     * this class implicitly awaits `ready`, so awaiting it explicitly is
+     * only necessary when a caller needs to observe construction errors
+     * synchronously (without issuing a query first).
+     */
+    readonly ready: Promise<void>;
+    private _inner;
+    readonly _options: DirSQLOptions;
+    /** Construct from a `.dirsql.toml` config-file path. */
+    constructor(configPath: string);
+    /** Construct from structured options. */
+    constructor(options: DirSQLOptions);
+    /**
+     * Execute a SQL query and return results as an array of row objects.
+     *
+     * Awaits the initial scan if it has not yet finished, then runs the
+     * query on the libuv threadpool, so the JS event loop stays responsive
+     * even for large result sets or long-running queries.
+     */
+    query(sql: string): Promise<Record<string, unknown>[]>;
+    /**
+     * Start the file watcher. Must be called before {@link pollEvents}.
+     * Idempotent — safe to call multiple times.
+     *
+     * Awaits the initial scan if it has not yet finished, then runs on the
+     * libuv threadpool so the JS event loop stays responsive while the
+     * watcher is being initialized.
+     */
+    startWatcher(): Promise<void>;
+    /**
+     * Poll for file change events, blocking up to `timeoutMs` for the first
+     * event. Returns all events observed in the window (possibly empty).
+     *
+     * Awaits the initial scan if it has not yet finished, then runs on the
+     * libuv threadpool so the JS event loop stays responsive for the
+     * duration of the poll timeout.
+     */
+    pollEvents(timeoutMs: number): Promise<RowEvent[]>;
+    /**
+     * Resolved construction state. Recomputed on each call; reads the
+     * `.dirsql.toml` if `config` was supplied. Works before `ready`.
+     */
+    toJSON(): DirSQLConfig;
+    /**
+     * Watch for file change events as an async iterable.
+     *
+     * ```ts
+     * for await (const event of db.watch()) { ... }
+     * ```
+     *
+     * Awaits the initial scan on first iteration, starts the underlying
+     * watcher, then awaits a bounded native poll each cycle. The iterator
+     * runs indefinitely; break out of the `for await` loop to stop.
+     */
+    watch(): AsyncGenerator<RowEvent, void, unknown>;
+}
+//# sourceMappingURL=dirsql.d.ts.map

package/dist/dirsql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dirsql.d.ts","sourceRoot":"","sources":["../src/dirsql.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,8BAA8B;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC;IACpB,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qDAAqD;AACrD,MAAM,WAAW,QAAQ;IACvB;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,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;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,MAAM;IACjB;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAG9B,OAAO,CAAC,MAAM,CAAgB;IAK9B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IAEjC,wDAAwD;gBAC5C,UAAU,EAAE,MAAM;IAC9B,yCAAyC;gBAC7B,OAAO,EAAE,aAAa;IAmBlC;;;;;;OAMG;IACG,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAK5D;;;;;;;OAOG;IACG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAKnC;;;;;;;OAOG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAKxD;;;OAGG;IACH,MAAM,IAAI,YAAY;IAItB;;;;;;;;;;OAUG;IACI,KAAK,IAAI,cAAc,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC;CAaxD"}

package/dist/dirsql.js

@@ -0,0 +1,129 @@
+// The `DirSQL` facade — the SDK's primary entry point.
+//
+// Split out of the public barrel (`index.ts`) so it carries a colocated
+// unit test instead of an exemption (#239). The native binding is reached
+// through `getCore()` (see `core.ts`), which tests fake.
+import { getCore } from "./core.js";
+import { resolveConfig } from "./resolve-config.js";
+/**
+ * Ephemeral SQL index over a local directory.
+ *
+ * The constructor is overloaded: pass a config-file path directly, or an
+ * options object with any combination of `root`, `tables`, `ignore`, and
+ * `config`.
+ *
+ * Constructing a `DirSQL` returns immediately; the directory scan, file
+ * reads, and initial row extraction run asynchronously. `db.ready`
+ * resolves once construction has completed, and every method (including
+ * {@link query}, {@link startWatcher}, {@link pollEvents}, and
+ * {@link watch}) transparently awaits `ready` before doing any work, so
+ * callers can start using the instance immediately:
+ *
+ * ```ts
+ * // From a config file:
+ * const db = new DirSQL("./my-config.toml");
+ *
+ * // Programmatic:
+ * const db2 = new DirSQL({ root: "./data", tables: [...] });
+ *
+ * await db.ready; // optional: wait for the initial scan explicitly
+ * const rows = await db.query("SELECT ...");
+ * for await (const event of db.watch()) { ... }
+ * ```
+ *
+ * The scan runs on the libuv threadpool, so constructing a `DirSQL` does
+ * not block the JS event loop even for large directories.
+ */
+export class DirSQL {
+    /**
+     * Resolves once the initial directory scan + row extraction have
+     * completed, or rejects if construction failed. Every other method on
+     * this class implicitly awaits `ready`, so awaiting it explicitly is
+     * only necessary when a caller needs to observe construction errors
+     * synchronously (without issuing a query first).
+     */
+    ready;
+    // Initialized by `ready`. Do NOT touch before awaiting `ready`.
+    _inner;
+    // Constructor options preserved verbatim so `toJSON()` can resolve the
+    // serialized state synchronously without waiting for `ready`, and so
+    // `dirsql interpret` (#196) can reach the user-supplied `extract`
+    // callbacks (which `toJSON()` deliberately drops). Public-by-design.
+    _options;
+    constructor(arg) {
+        const options = typeof arg === "string" ? { config: arg } : arg;
+        this._options = options;
+        const Ctor = getCore().DirSQL;
+        const openPromise = Ctor.openAsync(options.root ?? null, options.tables ?? null, options.ignore ?? null, options.config ?? null, options.persist ?? null, options.persistPath ?? null);
+        this.ready = openPromise.then((inner) => {
+            this._inner = inner;
+        });
+    }
+    /**
+     * Execute a SQL query and return results as an array of row objects.
+     *
+     * Awaits the initial scan if it has not yet finished, then runs the
+     * query on the libuv threadpool, so the JS event loop stays responsive
+     * even for large result sets or long-running queries.
+     */
+    async query(sql) {
+        await this.ready;
+        return this._inner.query(sql);
+    }
+    /**
+     * Start the file watcher. Must be called before {@link pollEvents}.
+     * Idempotent — safe to call multiple times.
+     *
+     * Awaits the initial scan if it has not yet finished, then runs on the
+     * libuv threadpool so the JS event loop stays responsive while the
+     * watcher is being initialized.
+     */
+    async startWatcher() {
+        await this.ready;
+        return 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).
+     *
+     * Awaits the initial scan if it has not yet finished, then runs on the
+     * libuv threadpool so the JS event loop stays responsive for the
+     * duration of the poll timeout.
+     */
+    async pollEvents(timeoutMs) {
+        await this.ready;
+        return this._inner.pollEvents(timeoutMs);
+    }
+    /**
+     * Resolved construction state. Recomputed on each call; reads the
+     * `.dirsql.toml` if `config` was supplied. Works before `ready`.
+     */
+    toJSON() {
+        return resolveConfig(this._options);
+    }
+    /**
+     * Watch for file change events as an async iterable.
+     *
+     * ```ts
+     * for await (const event of db.watch()) { ... }
+     * ```
+     *
+     * Awaits the initial scan on first iteration, starts the underlying
+     * watcher, then awaits a bounded native poll each cycle. The iterator
+     * runs indefinitely; break out of the `for await` loop to stop.
+     */
+    async *watch() {
+        await this.ready;
+        await this._inner.startWatcher();
+        while (true) {
+            // Native `pollEvents` now runs on the libuv threadpool and returns a
+            // Promise, so awaiting it does not park the JS thread. A ~200ms
+            // timeout keeps the poll cadence low without starving the event loop.
+            const events = await this._inner.pollEvents(200);
+            for (const event of events) {
+                yield event;
+            }
+        }
+    }
+}
+//# sourceMappingURL=dirsql.js.map

package/dist/dirsql.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dirsql.js","sourceRoot":"","sources":["../src/dirsql.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,EAAE;AACF,wEAAwE;AACxE,0EAA0E;AAC1E,yDAAyD;AAGzD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAoFpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,OAAO,MAAM;IACjB;;;;;;OAMG;IACM,KAAK,CAAgB;IAE9B,gEAAgE;IACxD,MAAM,CAAgB;IAC9B,uEAAuE;IACvE,qEAAqE;IACrE,kEAAkE;IAClE,qEAAqE;IAC5D,QAAQ,CAAgB;IAMjC,YAAY,GAA2B;QACrC,MAAM,OAAO,GACX,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;QAClD,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QACxB,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC,MAAM,CAAC;QAC9B,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,CAChC,OAAO,CAAC,IAAI,IAAI,IAAI,EACpB,OAAO,CAAC,MAAM,IAAI,IAAI,EACtB,OAAO,CAAC,MAAM,IAAI,IAAI,EACtB,OAAO,CAAC,MAAM,IAAI,IAAI,EACtB,OAAO,CAAC,OAAO,IAAI,IAAI,EACvB,OAAO,CAAC,WAAW,IAAI,IAAI,CAC5B,CAAC;QACF,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE;YACtC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACtB,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,KAAK,CAAC,GAAW;QACrB,MAAM,IAAI,CAAC,KAAK,CAAC;QACjB,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,YAAY;QAChB,MAAM,IAAI,CAAC,KAAK,CAAC;QACjB,OAAO,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;IACpC,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,UAAU,CAAC,SAAiB;QAChC,MAAM,IAAI,CAAC,KAAK,CAAC;QACjB,OAAO,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;IAC3C,CAAC;IAED;;;OAGG;IACH,MAAM;QACJ,OAAO,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACtC,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,CAAC,KAAK;QACV,MAAM,IAAI,CAAC,KAAK,CAAC;QACjB,MAAM,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;QACjC,OAAO,IAAI,EAAE,CAAC;YACZ,qEAAqE;YACrE,gEAAgE;YAChE,sEAAsE;YACtE,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;YACjD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;gBAC3B,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

package/dist/index.d.ts

@@ -1,231 +1,6 @@
-/** 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;
-    /**
-     * Produce the rows a matched file contributes. Receives the absolute
-     * filesystem path of the file. dirsql does not read file contents; if the
-     * callback needs the file body it reads the path itself (e.g.
-     * `fs.readFileSync(filePath, "utf8")`). Returns an array of row objects.
-     */
-    extract: (filePath: string) => Record<string, unknown>[];
-    /** If true, reject rows with columns not declared in `ddl`. */
-    strict?: boolean;
-}
-/**
- * Thin class wrapper around {@link TableDef} for parity with the Python
- * `Table(ddl=..., glob=..., extract=...)` and Rust `Table::new(...)`
- * constructors. `new Table({...})` is structurally identical to a plain
- * object literal satisfying `TableDef` — anything accepting `TableDef[]`
- * (e.g. {@link DirSQL}'s `tables` option) takes either form.
- *
- * `strict` is only copied when present so the instance's enumerable keys
- * match the input literal exactly; field declarations use `declare` to
- * suppress the default class-field initializer that would otherwise pin
- * `strict` to `undefined` under `useDefineForClassFields`.
- */
-export declare class Table implements TableDef {
-    readonly ddl: string;
-    readonly glob: string;
-    readonly extract: (filePath: string) => Record<string, unknown>[];
-    readonly strict?: boolean;
-    constructor(def: TableDef);
-}
-/**
- * Options accepted by the {@link DirSQL} constructor.
- *
- * At least one of `root` or `config` must be supplied. When both are set,
- * the explicit `root` wins over any `[dirsql].root` declared in the config
- * file (a warning is emitted by the native layer).
- */
-export interface DirSQLOptions {
-    /** Root directory to scan. */
-    root?: string;
-    /** Programmatic table definitions. Each table's `extract` runs in-process. */
-    tables?: TableDef[];
-    /** Glob patterns (relative to `root`) to ignore. */
-    ignore?: string[];
-    /**
-     * Path to a `.dirsql.toml` config file. Its `[[table]]` entries are
-     * appended to any programmatic `tables`; its `[dirsql].ignore` patterns
-     * are appended to any explicit `ignore`. If the config declares a
-     * `[dirsql].root` and no explicit `root` is given, it is resolved
-     * relative to the config file's parent directory.
-     */
-    config?: string;
-    /**
-     * Enable persistent on-disk SQLite cache. When `true`, the database is
-     * written to `<root>/.dirsql/cache.db` (override via `persistPath`) so
-     * subsequent startups only re-parse files that have actually changed.
-     */
-    persist?: boolean;
-    /**
-     * Override the location of the persistent cache file. Ignored when
-     * `persist` is not `true`.
-     */
-    persistPath?: string;
-}
-/** A row-level event emitted by the file watcher. */
-export interface RowEvent {
-    /**
-     * The table the event applies to. Always set for insert / update / delete.
-     * May be `null` on error events that occur before a file is attributed
-     * to any table (e.g. a watch-channel failure).
-     */
-    table: string | null;
-    action: "insert" | "update" | "delete" | "error";
-    row?: Record<string, unknown> | null;
-    oldRow?: Record<string, unknown> | null;
-    error?: string | null;
-    filePath?: string | null;
-}
-/**
- * Serializable per-table portion of {@link DirSQLConfig}. Excludes the
- * `extract` callback (closures aren't serializable) and the table's SQL
- * `name` (derivable from `ddl`).
- */
-export interface TableConfig {
-    ddl: string;
-    glob: string;
-    strict: boolean;
-}
-/**
- * Serializable snapshot of a {@link DirSQL} instance's resolved runtime
- * state, as produced by {@link DirSQL.toJSON} / `JSON.stringify(db)`.
- *
- * The shape is identical across the Python, Rust, and TypeScript SDKs
- * (modulo `persist_path` ↔ `persistPath` case): the same payload can flow
- * through the `interpret` handshake regardless of which SDK produced it.
- *
- * Construction artifacts that are no longer meaningful after the instance
- * exists are intentionally excluded — `config` (already merged into `root`
- * / `tables` / `ignore`), per-table `extract`, and per-table `name`.
- */
-export interface DirSQLConfig {
-    root: string;
-    tables: TableConfig[];
-    ignore: string[];
-    persist: boolean;
-    persistPath: string | null;
-}
-interface NativeDirSQL {
-    query(sql: string): Promise<Record<string, unknown>[]>;
-    startWatcher(): Promise<void>;
-    pollEvents(timeoutMs: number): Promise<RowEvent[]>;
-}
-interface NativeDirSQLConstructor {
-    openAsync(root: string | null, tables: TableDef[] | null, ignore: string[] | null, config: string | null, persist: boolean | null, persistPath: string | null): Promise<NativeDirSQL>;
-}
-interface CoreModule {
-    DirSQL: NativeDirSQLConstructor;
-    parseTableName(ddl: string): string | null;
-}
-/**
- * Parse the table name out of a `CREATE TABLE <name> (...)` DDL.
- *
- * Returns `null` for a DDL the parser doesn't recognize. Backed by the
- * core Rust implementation (`dirsql::db::parse_table_name`) so the JS
- * SDK and the orchestrator agree on table-name resolution.
- */
-export declare function parseTableName(ddl: string): string | null;
-/**
- * **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.
- *
- * The constructor is overloaded: pass a config-file path directly, or an
- * options object with any combination of `root`, `tables`, `ignore`, and
- * `config`.
- *
- * Constructing a `DirSQL` returns immediately; the directory scan, file
- * reads, and initial row extraction run asynchronously. `db.ready`
- * resolves once construction has completed, and every method (including
- * {@link query}, {@link startWatcher}, {@link pollEvents}, and
- * {@link watch}) transparently awaits `ready` before doing any work, so
- * callers can start using the instance immediately:
- *
- * ```ts
- * // From a config file:
- * const db = new DirSQL("./my-config.toml");
- *
- * // Programmatic:
- * const db2 = new DirSQL({ root: "./data", tables: [...] });
- *
- * await db.ready; // optional: wait for the initial scan explicitly
- * const rows = await db.query("SELECT ...");
- * for await (const event of db.watch()) { ... }
- * ```
- *
- * The scan runs on the libuv threadpool, so constructing a `DirSQL` does
- * not block the JS event loop even for large directories.
- */
-export declare class DirSQL {
-    /**
-     * Resolves once the initial directory scan + row extraction have
-     * completed, or rejects if construction failed. Every other method on
-     * this class implicitly awaits `ready`, so awaiting it explicitly is
-     * only necessary when a caller needs to observe construction errors
-     * synchronously (without issuing a query first).
-     */
-    readonly ready: Promise<void>;
-    private _inner;
-    readonly _options: DirSQLOptions;
-    /** Construct from a `.dirsql.toml` config-file path. */
-    constructor(configPath: string);
-    /** Construct from structured options. */
-    constructor(options: DirSQLOptions);
-    /**
-     * Execute a SQL query and return results as an array of row objects.
-     *
-     * Awaits the initial scan if it has not yet finished, then runs the
-     * query on the libuv threadpool, so the JS event loop stays responsive
-     * even for large result sets or long-running queries.
-     */
-    query(sql: string): Promise<Record<string, unknown>[]>;
-    /**
-     * Start the file watcher. Must be called before {@link pollEvents}.
-     * Idempotent — safe to call multiple times.
-     *
-     * Awaits the initial scan if it has not yet finished, then runs on the
-     * libuv threadpool so the JS event loop stays responsive while the
-     * watcher is being initialized.
-     */
-    startWatcher(): Promise<void>;
-    /**
-     * Poll for file change events, blocking up to `timeoutMs` for the first
-     * event. Returns all events observed in the window (possibly empty).
-     *
-     * Awaits the initial scan if it has not yet finished, then runs on the
-     * libuv threadpool so the JS event loop stays responsive for the
-     * duration of the poll timeout.
-     */
-    pollEvents(timeoutMs: number): Promise<RowEvent[]>;
-    /**
-     * Resolved construction state. Recomputed on each call; reads the
-     * `.dirsql.toml` if `config` was supplied. Works before `ready`.
-     */
-    toJSON(): DirSQLConfig;
-    /**
-     * Watch for file change events as an async iterable.
-     *
-     * ```ts
-     * for await (const event of db.watch()) { ... }
-     * ```
-     *
-     * Awaits the initial scan on first iteration, starts the underlying
-     * watcher, then awaits a bounded native poll each cycle. The iterator
-     * runs indefinitely; break out of the `for await` loop to stop.
-     */
-    watch(): AsyncGenerator<RowEvent, void, unknown>;
-}
-export {};
+export { DirSQL } from "./dirsql.js";
+export type { DirSQLConfig, DirSQLOptions, RowEvent, TableConfig, } from "./dirsql.js";
+export { parseTableName } from "./parse-table-name.js";
+export { Table } from "./table.js";
+export type { TableDef } from "./table.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EACV,YAAY,EACZ,aAAa,EACb,QAAQ,EACR,WAAW,GACZ,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,4 +1,4 @@
-// dirsql TypeScript SDK.
+// dirsql TypeScript SDK — public API barrel.
 //
 // The public surface is implemented in Rust via napi-rs. In development
 // `pnpm build` runs `napi build` which drops `dirsql.node` at the
@@ -9,179 +9,12 @@
 // `@dirsql/lib-<slug>` sub-package (wired via `optionalDependencies`),
 // and the loader resolves the one matching the host's OS/arch. No Rust
 // toolchain is required at install time on any supported platform.
-import { loadNativeCore as defaultLoadNativeCore } from "./load-native-core.js";
-import { resolveConfig } from "./resolve-config.js";
-/**
- * Thin class wrapper around {@link TableDef} for parity with the Python
- * `Table(ddl=..., glob=..., extract=...)` and Rust `Table::new(...)`
- * constructors. `new Table({...})` is structurally identical to a plain
- * object literal satisfying `TableDef` — anything accepting `TableDef[]`
- * (e.g. {@link DirSQL}'s `tables` option) takes either form.
- *
- * `strict` is only copied when present so the instance's enumerable keys
- * match the input literal exactly; field declarations use `declare` to
- * suppress the default class-field initializer that would otherwise pin
- * `strict` to `undefined` under `useDefineForClassFields`.
- */
-export class Table {
-    constructor(def) {
-        this.ddl = def.ddl;
-        this.glob = def.glob;
-        this.extract = def.extract;
-        if (def.strict !== undefined) {
-            this.strict = def.strict;
-        }
-    }
-}
-/**
- * Parse the table name out of a `CREATE TABLE <name> (...)` DDL.
- *
- * Returns `null` for a DDL the parser doesn't recognize. Backed by the
- * core Rust implementation (`dirsql::db::parse_table_name`) so the JS
- * SDK and the orchestrator agree on table-name resolution.
- */
-export function parseTableName(ddl) {
-    return getCore().parseTableName(ddl);
-}
-// Lazy-loaded reference to the core module. Populated on first access by
-// `defaultLoadNativeCore()`, or by `__setCoreForTesting()` for tests.
-let core = null;
-function getCore() {
-    if (core === null) {
-        core = defaultLoadNativeCore();
-    }
-    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.
- */
-export function __setCoreForTesting(fake) {
-    core = fake;
-}
-/**
- * Ephemeral SQL index over a local directory.
- *
- * The constructor is overloaded: pass a config-file path directly, or an
- * options object with any combination of `root`, `tables`, `ignore`, and
- * `config`.
- *
- * Constructing a `DirSQL` returns immediately; the directory scan, file
- * reads, and initial row extraction run asynchronously. `db.ready`
- * resolves once construction has completed, and every method (including
- * {@link query}, {@link startWatcher}, {@link pollEvents}, and
- * {@link watch}) transparently awaits `ready` before doing any work, so
- * callers can start using the instance immediately:
- *
- * ```ts
- * // From a config file:
- * const db = new DirSQL("./my-config.toml");
- *
- * // Programmatic:
- * const db2 = new DirSQL({ root: "./data", tables: [...] });
- *
- * await db.ready; // optional: wait for the initial scan explicitly
- * const rows = await db.query("SELECT ...");
- * for await (const event of db.watch()) { ... }
- * ```
- *
- * The scan runs on the libuv threadpool, so constructing a `DirSQL` does
- * not block the JS event loop even for large directories.
- */
-export class DirSQL {
-    /**
-     * Resolves once the initial directory scan + row extraction have
-     * completed, or rejects if construction failed. Every other method on
-     * this class implicitly awaits `ready`, so awaiting it explicitly is
-     * only necessary when a caller needs to observe construction errors
-     * synchronously (without issuing a query first).
-     */
-    ready;
-    // Initialized by `ready`. Do NOT touch before awaiting `ready`.
-    _inner;
-    // Constructor options preserved verbatim so `toJSON()` can resolve the
-    // serialized state synchronously without waiting for `ready`, and so
-    // `dirsql interpret` (#196) can reach the user-supplied `extract`
-    // callbacks (which `toJSON()` deliberately drops). Public-by-design.
-    _options;
-    constructor(arg) {
-        const options = typeof arg === "string" ? { config: arg } : arg;
-        this._options = options;
-        const Ctor = getCore().DirSQL;
-        const openPromise = Ctor.openAsync(options.root ?? null, options.tables ?? null, options.ignore ?? null, options.config ?? null, options.persist ?? null, options.persistPath ?? null);
-        this.ready = openPromise.then((inner) => {
-            this._inner = inner;
-        });
-    }
-    /**
-     * Execute a SQL query and return results as an array of row objects.
-     *
-     * Awaits the initial scan if it has not yet finished, then runs the
-     * query on the libuv threadpool, so the JS event loop stays responsive
-     * even for large result sets or long-running queries.
-     */
-    async query(sql) {
-        await this.ready;
-        return this._inner.query(sql);
-    }
-    /**
-     * Start the file watcher. Must be called before {@link pollEvents}.
-     * Idempotent — safe to call multiple times.
-     *
-     * Awaits the initial scan if it has not yet finished, then runs on the
-     * libuv threadpool so the JS event loop stays responsive while the
-     * watcher is being initialized.
-     */
-    async startWatcher() {
-        await this.ready;
-        return 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).
-     *
-     * Awaits the initial scan if it has not yet finished, then runs on the
-     * libuv threadpool so the JS event loop stays responsive for the
-     * duration of the poll timeout.
-     */
-    async pollEvents(timeoutMs) {
-        await this.ready;
-        return this._inner.pollEvents(timeoutMs);
-    }
-    /**
-     * Resolved construction state. Recomputed on each call; reads the
-     * `.dirsql.toml` if `config` was supplied. Works before `ready`.
-     */
-    toJSON() {
-        return resolveConfig(this._options);
-    }
-    /**
-     * Watch for file change events as an async iterable.
-     *
-     * ```ts
-     * for await (const event of db.watch()) { ... }
-     * ```
-     *
-     * Awaits the initial scan on first iteration, starts the underlying
-     * watcher, then awaits a bounded native poll each cycle. The iterator
-     * runs indefinitely; break out of the `for await` loop to stop.
-     */
-    async *watch() {
-        await this.ready;
-        await this._inner.startWatcher();
-        while (true) {
-            // Native `pollEvents` now runs on the libuv threadpool and returns a
-            // Promise, so awaiting it does not park the JS thread. A ~200ms
-            // timeout keeps the poll cadence low without starving the event loop.
-            const events = await this._inner.pollEvents(200);
-            for (const event of events) {
-                yield event;
-            }
-        }
-    }
-}
+//
+// This file is a thin re-export barrel: the implementation lives in
+// colocated-tested modules (`table.ts`, `core.ts`, `parse-table-name.ts`,
+// `dirsql.ts`), each carrying its own unit test. The barrel itself is
+// covered by `index.test.ts` (#239).
+export { DirSQL } from "./dirsql.js";
+export { parseTableName } from "./parse-table-name.js";
+export { Table } from "./table.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,EAAE;AACF,wEAAwE;AACxE,kEAAkE;AAClE,uEAAuE;AACvE,qCAAqC;AACrC,EAAE;AACF,qEAAqE;AACrE,uEAAuE;AACvE,uEAAuE;AACvE,mEAAmE;AACnE,EAAE;AACF,oEAAoE;AACpE,0EAA0E;AAC1E,sEAAsE;AACtE,qCAAqC;AAErC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAOrC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC"}

package/dist/parse-table-name.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Parse the table name out of a `CREATE TABLE <name> (...)` DDL.
+ *
+ * Returns `null` for a DDL the parser doesn't recognize. Backed by the
+ * core Rust implementation (`dirsql::db::parse_table_name`) so the JS
+ * SDK and the orchestrator agree on table-name resolution.
+ */
+export declare function parseTableName(ddl: string): string | null;
+//# sourceMappingURL=parse-table-name.d.ts.map

package/dist/parse-table-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-table-name.d.ts","sourceRoot":"","sources":["../src/parse-table-name.ts"],"names":[],"mappings":"AAOA;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEzD"}

package/dist/parse-table-name.js

@@ -0,0 +1,16 @@
+// `parseTableName` — table-name resolution delegated to the Rust core.
+//
+// Split out of the public barrel (`index.ts`) so it carries a colocated
+// unit test instead of an exemption (#239).
+import { getCore } from "./core.js";
+/**
+ * Parse the table name out of a `CREATE TABLE <name> (...)` DDL.
+ *
+ * Returns `null` for a DDL the parser doesn't recognize. Backed by the
+ * core Rust implementation (`dirsql::db::parse_table_name`) so the JS
+ * SDK and the orchestrator agree on table-name resolution.
+ */
+export function parseTableName(ddl) {
+    return getCore().parseTableName(ddl);
+}
+//# sourceMappingURL=parse-table-name.js.map

package/dist/parse-table-name.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-table-name.js","sourceRoot":"","sources":["../src/parse-table-name.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,EAAE;AACF,wEAAwE;AACxE,4CAA4C;AAE5C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,OAAO,OAAO,EAAE,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;AACvC,CAAC"}

package/dist/table.d.ts

@@ -0,0 +1,36 @@
+/** 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;
+    /**
+     * Produce the rows a matched file contributes. Receives the absolute
+     * filesystem path of the file. dirsql does not read file contents; if the
+     * callback needs the file body it reads the path itself (e.g.
+     * `fs.readFileSync(filePath, "utf8")`). Returns an array of row objects.
+     */
+    extract: (filePath: string) => Record<string, unknown>[];
+    /** If true, reject rows with columns not declared in `ddl`. */
+    strict?: boolean;
+}
+/**
+ * Thin class wrapper around {@link TableDef} for parity with the Python
+ * `Table(ddl=..., glob=..., extract=...)` and Rust `Table::new(...)`
+ * constructors. `new Table({...})` is structurally identical to a plain
+ * object literal satisfying `TableDef` — anything accepting `TableDef[]`
+ * (e.g. {@link DirSQL}'s `tables` option) takes either form.
+ *
+ * `strict` is only copied when present so the instance's enumerable keys
+ * match the input literal exactly; field declarations use `declare` to
+ * suppress the default class-field initializer that would otherwise pin
+ * `strict` to `undefined` under `useDefineForClassFields`.
+ */
+export declare class Table implements TableDef {
+    readonly ddl: string;
+    readonly glob: string;
+    readonly extract: (filePath: string) => Record<string, unknown>[];
+    readonly strict?: boolean;
+    constructor(def: TableDef);
+}
+//# sourceMappingURL=table.d.ts.map

package/dist/table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../src/table.ts"],"names":[],"mappings":"AAKA,iEAAiE;AACjE,MAAM,WAAW,QAAQ;IACvB,6EAA6E;IAC7E,GAAG,EAAE,MAAM,CAAC;IACZ,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,OAAO,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IACzD,+DAA+D;IAC/D,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,KAAM,YAAW,QAAQ;IACpC,SAAiB,GAAG,EAAE,MAAM,CAAC;IAC7B,SAAiB,IAAI,EAAE,MAAM,CAAC;IAC9B,SAAiB,OAAO,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAC1E,SAAiB,MAAM,CAAC,EAAE,OAAO,CAAC;gBAEtB,GAAG,EAAE,QAAQ;CAQ1B"}

package/dist/table.js

@@ -0,0 +1,27 @@
+// `Table` definition + its thin class wrapper.
+//
+// Split out of the public barrel (`index.ts`) so it carries a colocated
+// unit test instead of an exemption (#239).
+/**
+ * Thin class wrapper around {@link TableDef} for parity with the Python
+ * `Table(ddl=..., glob=..., extract=...)` and Rust `Table::new(...)`
+ * constructors. `new Table({...})` is structurally identical to a plain
+ * object literal satisfying `TableDef` — anything accepting `TableDef[]`
+ * (e.g. {@link DirSQL}'s `tables` option) takes either form.
+ *
+ * `strict` is only copied when present so the instance's enumerable keys
+ * match the input literal exactly; field declarations use `declare` to
+ * suppress the default class-field initializer that would otherwise pin
+ * `strict` to `undefined` under `useDefineForClassFields`.
+ */
+export class Table {
+    constructor(def) {
+        this.ddl = def.ddl;
+        this.glob = def.glob;
+        this.extract = def.extract;
+        if (def.strict !== undefined) {
+            this.strict = def.strict;
+        }
+    }
+}
+//# sourceMappingURL=table.js.map

package/dist/table.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"table.js","sourceRoot":"","sources":["../src/table.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAC/C,EAAE;AACF,wEAAwE;AACxE,4CAA4C;AAmB5C;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,KAAK;IAMhB,YAAY,GAAa;QACvB,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;QAC3B,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC7B,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;QAC3B,CAAC;IACH,CAAC;CACF"}

package/docs/guide/tables.md

@@ -72,7 +72,7 @@ ddl="CREATE TABLE metrics (name TEXT, value REAL, count INTEGER)"
 ddl="CREATE TABLE items (id TEXT PRIMARY KEY, name TEXT NOT NULL)"
 ```
 
-The table name is parsed from the DDL. It must be a valid SQLite identifier.
+The table name is parsed from the DDL and must resolve to a valid SQLite identifier.
 
 ### `glob`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dirsql",
-  "version": "0.3.41",
+  "version": "0.3.43",
   "description": "Ephemeral SQL index over a local directory",
   "license": "MIT",
   "repository": "https://github.com/thekevinscott/dirsql",
@@ -219,15 +219,15 @@
     "smol-toml": "^1.6.1"
   },
   "optionalDependencies": {
-    "@dirsql/lib-linux-x64-gnu": "0.3.41",
-    "@dirsql/lib-linux-arm64-gnu": "0.3.41",
-    "@dirsql/lib-darwin-x64": "0.3.41",
-    "@dirsql/lib-darwin-arm64": "0.3.41",
-    "@dirsql/lib-win32-x64-msvc": "0.3.41",
-    "@dirsql/cli-linux-x64-gnu": "0.3.41",
-    "@dirsql/cli-linux-arm64-gnu": "0.3.41",
-    "@dirsql/cli-darwin-x64": "0.3.41",
-    "@dirsql/cli-darwin-arm64": "0.3.41",
-    "@dirsql/cli-win32-x64-msvc": "0.3.41"
+    "@dirsql/lib-linux-x64-gnu": "0.3.43",
+    "@dirsql/lib-linux-arm64-gnu": "0.3.43",
+    "@dirsql/lib-darwin-x64": "0.3.43",
+    "@dirsql/lib-darwin-arm64": "0.3.43",
+    "@dirsql/lib-win32-x64-msvc": "0.3.43",
+    "@dirsql/cli-linux-x64-gnu": "0.3.43",
+    "@dirsql/cli-linux-arm64-gnu": "0.3.43",
+    "@dirsql/cli-darwin-x64": "0.3.43",
+    "@dirsql/cli-darwin-arm64": "0.3.43",
+    "@dirsql/cli-win32-x64-msvc": "0.3.43"
   }
 }