dirsql 0.4.135 → 0.4.136

package/dist/core.d.ts

@@ -3,7 +3,7 @@ import type { TableDef } from "./table.js";
 export interface NativeDirSQL {
     query(sql: string): Promise<Record<string, unknown>[]>;
     queryOrdered(sql: string): Promise<QueryResult>;
-    startWatcher(): Promise<void>;
+    startWatcher(): void;
     pollEvents(timeoutMs: number): Promise<RowEvent[]>;
     scanFailures(): ScanFailure[];
     close(): void;

package/dist/dirsql.d.ts

@@ -147,6 +147,7 @@ export declare class DirSQL {
     private _inner;
     private readonly _watchStreams;
     private _watchPoll?;
+    private _watcherStarted;
     readonly _options: DirSQLOptions;
     /** Construct from a `.dirsql.toml` config-file path. */
     constructor(configPath: string);
@@ -186,11 +187,11 @@ export declare class DirSQL {
      * 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.
+     * Awaits the initial scan if it has not yet finished, then registers the
+     * watcher on the JS thread; the watcher is live once this resolves.
      */
     startWatcher(): Promise<void>;
+    private _ensureWatcher;
     /**
      * Poll for file change events, blocking up to `timeoutMs` for the first
      * event. Returns all events observed in the window (possibly empty).
@@ -207,9 +208,16 @@ export declare class DirSQL {
      * 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.
+     * The watcher is live once both `watch()` and {@link ready} have
+     * returned, in either order: a file written after that point produces an
+     * event and reaches the index. Called after the scan, `watch()` starts the
+     * watcher before returning; called before it, the watcher starts before
+     * `ready` resolves. Writes made while the scan is still running may be
+     * missed.
+     *
+     * The stream awaits `ready` on first iteration, then awaits a bounded
+     * native poll each cycle. The iterator runs indefinitely; break out of the
+     * `for await` loop to stop.
      * Each stream receives every event observed after its creation, even
      * while another stream is consuming events on the same instance.
      */

package/dist/dirsql.js

@@ -49,6 +49,7 @@ export class DirSQL {
     _inner;
     _watchStreams = new Set();
     _watchPoll;
+    _watcherStarted = false;
     // Constructor options preserved verbatim; public-by-design.
     _options;
     constructor(arg) {
@@ -85,6 +86,15 @@ export class DirSQL {
         })
             .then((inner) => {
             this._inner = inner;
+            if (this._watchStreams.size > 0) {
+                try {
+                    this._ensureWatcher();
+                }
+                catch {
+                    // A watcher that cannot start is the stream's error, not init's:
+                    // the stream's first next() retries the start and throws there.
+                }
+            }
         });
         this._ready.catch(() => { });
     }
@@ -131,13 +141,18 @@ export class DirSQL {
      * 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.
+     * Awaits the initial scan if it has not yet finished, then registers the
+     * watcher on the JS thread; the watcher is live once this resolves.
      */
     async startWatcher() {
         await this.ready;
-        return this._inner.startWatcher();
+        this._ensureWatcher();
+    }
+    _ensureWatcher() {
+        if (!this._watcherStarted) {
+            this._inner.startWatcher();
+            this._watcherStarted = true;
+        }
     }
     /**
      * Poll for file change events, blocking up to `timeoutMs` for the first
@@ -158,13 +173,23 @@ export class DirSQL {
      * 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.
+     * The watcher is live once both `watch()` and {@link ready} have
+     * returned, in either order: a file written after that point produces an
+     * event and reaches the index. Called after the scan, `watch()` starts the
+     * watcher before returning; called before it, the watcher starts before
+     * `ready` resolves. Writes made while the scan is still running may be
+     * missed.
+     *
+     * The stream awaits `ready` on first iteration, then awaits a bounded
+     * native poll each cycle. The iterator runs indefinitely; break out of the
+     * `for await` loop to stop.
      * Each stream receives every event observed after its creation, even
      * while another stream is consuming events on the same instance.
      */
     watch() {
+        if (this._inner !== undefined) {
+            this._ensureWatcher();
+        }
         const buffer = [];
         const reference = new WeakRef(buffer);
         this._watchStreams.add(reference);
@@ -172,7 +197,7 @@ export class DirSQL {
         return (async function* () {
             try {
                 await owner.ready;
-                await owner._inner.startWatcher();
+                owner._ensureWatcher();
                 while (true) {
                     while (buffer.length === 0) {
                         owner._watchPoll ??= owner._inner

package/docs/reference/sdk.md

@@ -297,9 +297,14 @@ while let Some(event) = stream.next().await { ... }
 :::
 
 Returns a stream of [`RowEvent`](#rowevent)s reflecting filesystem changes
-under the root. The watcher starts on first iteration (Python/TypeScript)
-or at the `watch()` call (Rust). The stream never terminates on its own;
-stop consuming it to stop.
+under the root. The stream never terminates on its own; stop consuming it
+to stop.
+
+A file written once the watcher is live produces an event and reaches the
+index. Rust: the watcher is live when `watch()` returns. Python: it is live
+once both `watch()` and `ready()` have returned, in either order; a write made
+while the initial scan is still running may be missed. TypeScript: the watcher
+starts on first iteration.
 
 An instance with no named tables cannot be watched: path-tables emit no
 watch events, so `watch()` (and the polling primitives) raise an error naming

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dirsql",
-  "version": "0.4.135",
+  "version": "0.4.136",
   "description": "Ephemeral SQL index over a local directory",
   "license": "MIT",
   "repository": "https://github.com/thekevinscott/dirsql",
@@ -221,10 +221,10 @@
     ]
   },
   "optionalDependencies": {
-    "@dirsql/lib-linux-x64-gnu": "0.4.135",
-    "@dirsql/lib-linux-arm64-gnu": "0.4.135",
-    "@dirsql/lib-darwin-x64": "0.4.135",
-    "@dirsql/lib-darwin-arm64": "0.4.135",
-    "@dirsql/lib-win32-x64-msvc": "0.4.135"
+    "@dirsql/lib-linux-x64-gnu": "0.4.136",
+    "@dirsql/lib-linux-arm64-gnu": "0.4.136",
+    "@dirsql/lib-darwin-x64": "0.4.136",
+    "@dirsql/lib-darwin-arm64": "0.4.136",
+    "@dirsql/lib-win32-x64-msvc": "0.4.136"
   }
 }