dirsql 0.4.146 → 0.4.147

package/dist/dirsql.d.ts

@@ -163,9 +163,10 @@ export declare class DirSQL {
     /**
      * 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.
+     * Awaits the initial scan if it has not yet finished, then reads the
+     * files that changed since the last query, so the rows match the disk.
+     * The query itself runs on the libuv threadpool, so the JS event loop
+     * stays responsive even for large result sets or long-running queries.
      *
      * `params` binds to the statement's placeholders through SQLite, so the
      * values never enter the SQL text:

package/dist/dirsql.js

@@ -101,9 +101,10 @@ export class DirSQL {
     /**
      * 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.
+     * Awaits the initial scan if it has not yet finished, then reads the
+     * files that changed since the last query, so the rows match the disk.
+     * The query itself runs on the libuv threadpool, so the JS event loop
+     * stays responsive even for large result sets or long-running queries.
      *
      * `params` binds to the statement's placeholders through SQLite, so the
      * values never enter the SQL text:

package/docs/howto/parse-files-into-columns.md

@@ -83,7 +83,7 @@ the fastest way to see whether a parser produces the rows you expect.
 
 The inline flag re-scans and re-parses every file on every query, defines one
 parser for the whole query, and forgets everything when the process exits. When
-you want a **watcher** that keeps the rows fresh, **persistence** across
+you want **row events** as files change, **persistence** across
 restarts, or **different parsers for different file sets**, move the parser into
 a `.dirsql.toml` [`[[table]]`](../reference/config.md#table) — and paste the
 command in verbatim:
@@ -110,7 +110,8 @@ dirsql query "SELECT title, author FROM posts ORDER BY title" -c ./.dirsql.toml
 ```
 
 Same command, same rows. The difference is what a declared table brings: it is
-indexed on build, kept fresh by the watcher, survives restarts with
+indexed on build, re-reads only the files that changed on each query, streams
+row events as files change, survives restarts with
 [`--persist`](./persist.md), and a config can declare
 [many tables](./define-tables.md) — each with its own `on-file` — where the flag
 gives every path-table one parser. In both spellings the table's columns are

package/docs/howto/react-to-changes.md

@@ -72,6 +72,9 @@ works — `EventSource` in a browser, an SSE client library, or plain
 
 ## Notes
 
+- Querying never waits on this stream: a query reads what is on disk when it
+  starts ([`query`](../reference/sdk.md#query)). A change a query reads first
+  still arrives here, once.
 - Events reflect *row* changes, not raw filesystem events: a file edit
   that leaves a table's rows identical emits nothing, and one file change
   can emit several events. The diffing model is part of

package/docs/reference/sdk.md

@@ -97,7 +97,8 @@ DirSQL::builder()
 :::
 
 Creates a SQLite index over a directory. The index root is the explicit
-`root` when given, else the **process cwd** — the `config` file's location
+`root` when given (a relative `root` resolves against the cwd once, at build
+time), else the **process cwd** — the `config` file's location
 never sets the root. A config's `[[table]]` globs anchor at the config file's
 own directory instead (see [glob anchor](./config.md#glob-anchor)); `root`
 governs programmatic tables and path-tables.
@@ -291,6 +292,24 @@ db.query_with(
 - Without `params`, a statement with placeholders fails the same way: a
   placeholder is never left unbound.
 
+- **Accurate to the filesystem.** A query reads what is on disk when it
+  starts: a file written, edited, renamed or deleted before the call is
+  reflected in its rows, with no watcher, wait or retry. Before reading, the
+  query walks each named table's glob and stats every match; a file whose stat
+  moved, or that changed within the last two seconds, is parsed again, and a
+  file that is gone loses its rows. The row events those re-reads produce reach
+  [`watch`](#watch) streams and the next poll, once each. If a file on disk
+  breaks a foreign key, the query fails with the error a build over that tree
+  returns. In TypeScript the re-reads run on the JavaScript thread, where
+  `onFile` runs, and the SQL then runs on the threadpool.
+
+  The check trusts the file's stat, so it shares the limits of every
+  stat-based tool (`make`, `rsync`, `git status`): a write through a shared
+  memory map can land without the file's times moving until the writer
+  unmaps or syncs it; a network filesystem that caches attributes can report
+  a stale stat; and a clock stepped backwards can stamp a new write with a
+  time older than the last read.
+
 - **Read-only.** Each statement is classified by SQLite itself
   (`sqlite3_stmt_readonly`); anything classified as a write — `INSERT`,
   `UPDATE`, `DELETE`, `DROP`, `CREATE`, `ALTER`, `VACUUM`, … — is rejected
@@ -371,7 +390,9 @@ to stop.
 The watcher is live once both `watch()` and [`ready`](#ready) have returned,
 in either order (a Rust `DirSQL` is ready when `build()` returns); a file
 written after that point produces an event and reaches the index. A write
-made while the initial scan is still running may be missed.
+made while the initial scan is still running may be missed by the stream, but
+never by a query (see [`query`](#query)). A change a query read first still
+arrives on the stream, once.
 
 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.146",
+  "version": "0.4.147",
   "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.146",
-    "@dirsql/lib-linux-arm64-gnu": "0.4.146",
-    "@dirsql/lib-darwin-x64": "0.4.146",
-    "@dirsql/lib-darwin-arm64": "0.4.146",
-    "@dirsql/lib-win32-x64-msvc": "0.4.146"
+    "@dirsql/lib-linux-x64-gnu": "0.4.147",
+    "@dirsql/lib-linux-arm64-gnu": "0.4.147",
+    "@dirsql/lib-darwin-x64": "0.4.147",
+    "@dirsql/lib-darwin-arm64": "0.4.147",
+    "@dirsql/lib-win32-x64-msvc": "0.4.147"
   }
 }