dirsql 0.3.23__tar.gz → 0.3.25__tar.gz

{dirsql-0.3.23 → dirsql-0.3.25}/Cargo.lock

@@ -499,7 +499,7 @@ dependencies = [
 
 [[package]]
 name = "dirsql-py-ext"
-version = "0.3.23"
+version = "0.3.25"
 dependencies = [
  "dirsql",
  "pyo3",

{dirsql-0.3.23 → dirsql-0.3.25}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirsql
-Version: 0.3.23
+Version: 0.3.25
 Requires-Dist: pytest>=8 ; extra == 'dev'
 Requires-Dist: pytest-describe>=2 ; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23 ; extra == 'dev'

{dirsql-0.3.23 → dirsql-0.3.25}/docs/api/index.md

@@ -188,11 +188,12 @@ import { Table } from 'dirsql';
 ::: code-group
 
 ```python [Python]
-Table(*, ddl: str, glob: str, extract: Callable[[str], list[dict]])
+Table(*, ddl: str, glob: str, extract: Callable[[str], list[dict]], strict: bool = False)
 ```
 
 ```rust [Rust]
-Table::new(ddl: &str, glob: &str, extract: fn(&str) -> Vec<Value>)
+// Row = HashMap<String, Value>
+Table::new(ddl: &str, glob: &str, extract: fn(&str) -> Vec<HashMap<String, Value>>)
 ```
 
 ```typescript [TypeScript]
@@ -207,7 +208,8 @@ Defines a mapping from files to SQLite table rows.
 
 - `ddl` -- A `CREATE TABLE` statement. The table name is parsed from this DDL.
 - `glob` -- A glob pattern matched against file paths relative to the root directory.
-- `extract` -- A callable `(path) -> list[dict]`. Receives the absolute filesystem path of the matched file. `dirsql` does not read file contents; a callback that needs the file body reads `path` itself. Returns a list of dicts/maps mapping column names to values. Return an empty list to skip a file.
+- `extract` -- A callable `(path) -> list[dict]`. Receives the path of the matched file -- relative to the scan root, or absolute when `root` is absolute. `dirsql` does not read file contents; a callback that needs the file body reads `path` itself. Returns a list of dicts/maps mapping column names to values. Return an empty list to skip a file.
+- `strict` -- Optional (default `False`). Controls row/schema validation. In the default relaxed mode, extra row keys are dropped and missing columns become `NULL`. When `True`, every row key must be a valid column identifier and any extra or missing key raises an error. Surfaced in [serialization](#serialization) above as part of each table's `{ ddl, glob, strict }`.
 
 **Attributes:**
 
@@ -231,7 +233,7 @@ use dirsql::RowEvent;
 ```
 
 ```typescript [TypeScript]
-import { RowEvent } from 'dirsql';
+import type { RowEvent } from 'dirsql';
 ```
 
 :::

{dirsql-0.3.23/packages/python → dirsql-0.3.25}/docs/cli/config.md

@@ -6,12 +6,24 @@ canonical: https://thekevinscott.github.io/dirsql/cli/config
 
 > Online: <https://thekevinscott.github.io/dirsql/cli/config>
 
-`dirsql` can be configured with an optional config file (if omitted, server falls back to [defaults](./server.md#defaults)). Two formats are accepted:
+`dirsql` is configured with an optional config file; with none, the server
+falls back to [zero-config defaults](./server.md#defaults). Choose a format by
+what you need:
 
-- **`dirsql.toml`** — declarative; covers filesystem-fact tables. Works with any installation.
-- **`.py` / `.js`** — native-language; lets you write `extract` callbacks in Python or JavaScript. CLI-only, and only the launcher matching the file's language can run it. See [Native-Language Configs](#native-language-configs).
+- **[TOML](#toml)** — declarative; defines filesystem-fact tables (the path,
+  glob captures, and stat metadata). Works with any installation.
+- **[Python](#python)** and **[JavaScript](#javascript)** — native-language
+  configs that build tables from the *contents* of files (frontmatter, JSON
+  values, CSV cells) through a dynamic `extract` callback. CLI-only; only the
+  launcher matching the file's language can run it.
 
-## Basic Example
+## TOML
+
+Reach for a TOML config — the default `.dirsql.toml` — to declare tables from
+filesystem facts: a glob selects files, and columns come from path captures and
+stat metadata. No code required, and it works with every installation.
+
+### Basic Example
 
 ```toml
 [dirsql]
@@ -24,9 +36,11 @@ glob = "posts/*.md"
 
 Each `posts/*.md` file produces one row in the `posts` table.
 
-## Loading a Config File
+### Loading a Config File
 
-Pass the config file path to the `DirSQL` constructor:
+The CLI loads `./.dirsql.toml` by default; pass `--config <path>` to point at
+another file. To load the same `.toml` from the SDK, pass its path to the
+`DirSQL` constructor:
 
 ::: code-group
 
@@ -60,7 +74,7 @@ directory. Override it by passing `root` explicitly (the explicit value
 wins and a warning is emitted) or by declaring `[dirsql].root` in the
 config file itself.
 
-## Root Directory
+### Root Directory
 
 By default, the config file's parent directory is the scan root. To index
 a different location, declare `[dirsql].root` (relative paths are resolved
@@ -72,7 +86,7 @@ root = "../data"
 ignore = ["node_modules/**"]
 ```
 
-## Stat Virtuals
+### Stat Virtuals
 
 Every config-defined table can expose any of these reserved columns. Add
 the ones you want to your DDL; the rest are silently dropped.
@@ -96,7 +110,7 @@ WHERE _mtime > strftime('%s', '2024-01-01')
 ORDER BY _mtime DESC;
 ```
 
-## Path Captures
+### Path Captures
 
 Use `{name}` in glob patterns to extract path segments as columns. Add a
 matching column name to the DDL and the capture is auto-populated:
@@ -111,7 +125,7 @@ A file at `_comments/abc123/2024-05-05.jsonl` produces a row with
 `thread_id = "abc123"`, `_basename = "2024-05-05.jsonl"`, and `_mtime` set
 to the file's modification time.
 
-## Ignore Patterns
+### Ignore Patterns
 
 The `ignore` list skips files and directories entirely (not even scanned):
 
@@ -124,7 +138,7 @@ The top-level `.dirsql/` directory is always excluded, whether you list it
 or not — it is a reserved namespace for `dirsql`'s own metadata (see
 [Persistence](../guide/persistence.md)).
 
-## Persistence
+### Persistence
 
 Set `persist = true` to keep the SQLite database on disk between runs
 instead of rebuilding from scratch on every startup:
@@ -138,7 +152,7 @@ persist = true
 See [Persistence](../guide/persistence.md) for the full reconcile algorithm,
 storage layout, and limitations.
 
-## Loading extensions
+### Loading extensions
 
 You can load SQLite extensions by specifying them in a config.
 
@@ -165,7 +179,7 @@ be declared as a `[[table]]` — `dirsql` tables are per-file row tables — so
 `CREATE VIRTUAL TABLE` DDL is rejected; call the extension's functions in your
 queries instead.
 
-## Strict Mode
+### Strict Mode
 
 By default, auto-injected virtuals that aren't in the DDL are silently
 dropped, and undeclared user-extract keys are dropped. Enable strict mode
@@ -180,10 +194,11 @@ strict = true
 
 Strict mode does **not** apply to auto-injected stat virtuals — those are
 always filtered to the DDL's declared columns regardless. Strict mode
-applies only to keys produced by an extract callback (relevant for
-programmatic [tables](../guide/tables.md)).
+applies only to keys produced by an extract callback (relevant for the
+[Python](#python) / [JavaScript](#javascript) configs below and programmatic
+[tables](../guide/tables.md)).
 
-## Full Example
+### Full Example
 
 ```toml
 [dirsql]
@@ -202,20 +217,18 @@ ddl  = "CREATE TABLE logs (_path TEXT, _size INTEGER, _mtime INTEGER)"
 glob = "logs/*.csv"
 ```
 
-## Native-Language Configs
+## Python
 
-You can provide a config file in a particular language, allowing you to define a dynamic extract function. This can be useful for building a database based on the _contents_ of a file.
+Reach for a Python config when your columns come from the *contents* of a
+file — parsed JSON, frontmatter, CSV cells — rather than from filesystem
+facts alone. You write a dynamic `extract` callback in Python, and the file
+otherwise looks exactly like the in-process SDK construction (same `DirSQL` /
+`Table` API):
 
 ```bash
 dirsql --config dirsql.config.py
-dirsql --config dirsql.config.js
 ```
 
-The file looks exactly like the in-process SDK construction — same
-`DirSQL` / `Table` API:
-
-::: code-group
-
 ```python [dirsql.config.py]
 import json
 from dirsql import DirSQL, Table
@@ -224,8 +237,9 @@ def extract_meta(path):
     with open(path) as f:
         return [json.load(f)]
 
-# Python must export an `app` variable
+# Python must export a module-level `app`.
 app = DirSQL(
+    root="papers",  # required — see "Set a root" below
     tables=[
         Table(
             ddl="CREATE TABLE papers (title TEXT, _path TEXT)",
@@ -236,11 +250,26 @@ app = DirSQL(
 )
 ```
 
+`extract` receives the path of each matched file and returns a list of rows
+(one dict per row).
+
+## JavaScript
+
+A JavaScript config gives you the same contents-driven `extract` in Node,
+in either ES module or CommonJS form:
+
+```bash
+dirsql --config dirsql.config.mjs
+```
+
+::: code-group
+
 ```javascript [dirsql.config.mjs]
 import { readFileSync } from "node:fs";
 import { DirSQL } from "dirsql";
 
 export default new DirSQL({
+  root: "papers", // required — see "Set a root" below
   tables: [
     {
       ddl: "CREATE TABLE papers (title TEXT, _path TEXT)",
@@ -256,6 +285,7 @@ const { readFileSync } = require("node:fs");
 const { DirSQL } = require("dirsql");
 
 module.exports = new DirSQL({
+  root: "papers", // required — see "Set a root" below
   tables: [
     {
       ddl: "CREATE TABLE papers (title TEXT, _path TEXT)",
@@ -268,10 +298,21 @@ module.exports = new DirSQL({
 
 :::
 
-Only the extension matters — the file can be named anything. `dirsql.config.{py,mjs,cjs}` is the suggested convention but not required.
-
-### Module conventions
-
-- **Python (`.py`)** — module-level `app = DirSQL(...)`.
-- **ESM (`.mjs`, or `.js` in an ESM package)** — `export default new DirSQL(...)`.
-- **CommonJS (`.cjs`, or `.js` in a CJS package)** — `module.exports = new DirSQL(...)`.
+## Notes for native-language configs
+
+These apply to both the Python and JavaScript forms above.
+
+- **Export the config.** Python exposes a module-level `app = DirSQL(...)`; an
+  ES module (`.mjs`, or `.js` in an ESM package) uses
+  `export default new DirSQL(...)`; CommonJS (`.cjs`, or `.js` in a CJS
+  package) uses `module.exports = new DirSQL(...)`. Only the extension
+  matters — the file can be named anything; `dirsql.config.{py,mjs,cjs}` is the
+  suggested convention, not a requirement.
+- **Set a `root`.** Unlike TOML configs (which default the scan root to the
+  config file's directory), native-language configs require an explicit `root`.
+  Without one the Python launcher errors and the JavaScript launcher silently
+  indexes nothing.
+- **Install the launcher on your `PATH`.** To run your `extract`, the server
+  spawns `dirsql interpret`, so the matching `dirsql` launcher must be installed
+  and on your `PATH` — a global `pip`/`uv` install for `.py`, or `npm` for
+  `.mjs` / `.cjs`. Only the launcher matching the file's language can run it.

{dirsql-0.3.23/packages/rust → dirsql-0.3.25}/docs/cli/http-api.md

@@ -33,12 +33,12 @@ On error, the server returns a non-2xx status with a JSON body:
 {"error": "syntax error near \"SLECT\""}
 ```
 
-Malformed SQL returns `400`, not `500` — the client sent bad input. Missing / unreadable config returns `503`.
+Malformed SQL returns `400`. An unreadable or malformed config returns `503`; a *missing* config is not an error — the server serves the default `files` table.
 
 ```bash
 curl -s http://localhost:7117/query \
   -H 'content-type: application/json' \
-  -d '{"sql":"SELECT COUNT(*) AS n FROM posts"}' \
+  -d '{"sql":"SELECT COUNT(*) AS n FROM files"}' \
   | jq
 ```
 
@@ -47,9 +47,14 @@ for SQL semantics, the read-only restriction, and the return format.
 
 ## `GET /events`
 
-Opens a [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) stream of change events. Each `data:` payload is the same JSON schema the SDK emits from [`db.watch()`](../guide/watching.md#event-types):
+Opens a [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) stream of change events.
+
+On stream open the server emits a single `ready` frame so clients have a reliable signal that the subscription is attached. Every subsequent frame is named `row`, and its `data:` payload is the same JSON schema the SDK emits from [`db.watch()`](../guide/watching.md#event-types):
 
 ```
+event: ready
+data: {}
+
 event: row
 data: {"action":"insert","table":"posts","file_path":"posts/hello.json","row":{"title":"Hello World","author":"alice"},"old_row":null}
 
@@ -60,7 +65,14 @@ event: row
 data: {"action":"delete","table":"posts","file_path":"posts/second.json","row":{"title":"Second Post","author":"bob"},"old_row":null}
 ```
 
-Errors during extraction appear as `{"action":"error",...}` events on the same stream. They do **not** terminate the stream — a malformed file is a per-event problem, not a server-wide one.
+Errors during extraction appear as `error` action events on the same `row` stream. An error event carries an `error` message string and does **not** include `row` or `old_row`:
+
+```
+event: row
+data: {"action":"error","table":"posts","file_path":"posts/broken.json","error":"Extract error: ..."}
+```
+
+(`table` is `null` when the failure isn't tied to a specific table.) Errors do **not** terminate the stream — a malformed file is a per-event problem, not a server-wide one.
 
 ```bash
 curl -N http://localhost:7117/events

{dirsql-0.3.23 → dirsql-0.3.25}/docs/cli/index.md

@@ -53,7 +53,7 @@ for the library-vs-CLI feature split.
 
 ## Quick start
 
-From a directory containing your files and a [`.dirsql.toml`](./config.md):
+From any directory containing your files (no config needed):
 
 ```bash
 dirsql
@@ -66,7 +66,7 @@ Then query it over HTTP:
 ```bash
 curl -s http://localhost:7117/query \
   -H 'content-type: application/json' \
-  -d '{"sql":"SELECT COUNT(*) AS n FROM posts"}' \
+  -d '{"sql":"SELECT COUNT(*) AS n FROM files"}' \
   | jq
 ```
 

{dirsql-0.3.23 → dirsql-0.3.25}/docs/cli/server.md

@@ -28,7 +28,7 @@ $ Running at localhost:7117
 
 The server reads tables from a [config file](./config.md). By default it
 looks for `./.dirsql.toml`; pass `--config <path>` to point at a different
-`.toml` file or a [native-language config](./config.md#native-language-configs)
+`.toml` file or a [native-language config](./config.md)
 (`.py` / `.js`).
 
 ## Defaults
@@ -53,7 +53,7 @@ A config file will override the default.
 
 | Flag | Default | Description |
 |---|---|---|
-| `--config <path>` | `./.dirsql.toml` | Path to the config file (`.toml` or [native-language](./config.md#native-language-configs)). The index is rooted at the directory containing this file. |
+| `--config <path>` | `./.dirsql.toml` | Path to the config file (`.toml` or [native-language](./config.md)). The index is rooted at the directory containing this file. |
 | `--host <addr>` | `localhost` | Bind address |
 | `--port <n>` | `7117` | TCP port to bind |
 

{dirsql-0.3.23 → dirsql-0.3.25}/docs/getting-started.md

@@ -171,7 +171,7 @@ const results = await db.query(`
 
 1. `dirsql` walks the directory tree
 2. Files matching each table's glob pattern are identified
-3. The `extract` function receives each matched file's absolute path and returns rows
+3. The `extract` function receives each matched file's path (relative to the scan root, or absolute when `root` is absolute) and returns rows
 4. Rows are inserted into an in-memory SQLite database
 5. SQL queries run against that database
 

{dirsql-0.3.23 → dirsql-0.3.25}/docs/guide/async.md

@@ -28,6 +28,7 @@ async def main():
             ),
         ],
     )
+    await db.ready()
 
     # Query (runs in a thread, does not block the event loop)
     results = await db.query("SELECT * FROM items WHERE value > 10")
@@ -37,7 +38,31 @@ asyncio.run(main())
 ```
 
 ```rust [Rust]
-use dirsql::{DirSQL, Table};
+use dirsql::{DirSQL, Table, Value};
+use std::collections::HashMap;
+
+// See `row_from_json` in getting-started.md for a reusable helper that
+// turns a JSON object into a dirsql row (dirsql::Value is not Deserialize,
+// so a row can't be produced by serde_json::from_str directly).
+fn row_from_json(raw: &str) -> HashMap<String, Value> {
+    let v: serde_json::Value = serde_json::from_str(raw).unwrap();
+    let serde_json::Value::Object(obj) = v else { return HashMap::new() };
+    obj.into_iter()
+        .map(|(k, val)| {
+            let v = match val {
+                serde_json::Value::String(s) => Value::Text(s),
+                serde_json::Value::Number(n) => n
+                    .as_i64()
+                    .map(Value::Integer)
+                    .unwrap_or_else(|| Value::Real(n.as_f64().unwrap_or(0.0))),
+                serde_json::Value::Bool(b) => Value::Integer(b as i64),
+                serde_json::Value::Null => Value::Null,
+                other => Value::Text(other.to_string()),
+            };
+            (k, v)
+        })
+        .collect()
+}
 
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
@@ -47,7 +72,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
             Table::new(
                 "CREATE TABLE items (name TEXT, value INTEGER)",
                 "data/*.json",
-                |path| vec![serde_json::from_str(&std::fs::read_to_string(path).unwrap()).unwrap()],
+                |path| vec![row_from_json(&std::fs::read_to_string(path).unwrap())],
             ),
         ],
     )?;
@@ -83,7 +108,7 @@ console.log(results);
 ## Constructor
 
 ```python
-DirSQL(root=None, *, tables=None, ignore=None, config=None)
+DirSQL(root=None, *, tables=None, ignore=None, config=None, persist=False, persist_path=None)
 ```
 
 The constructor immediately starts scanning in a background thread via `asyncio.ensure_future`. The constructor itself returns immediately without blocking.
@@ -132,15 +157,29 @@ async for event in db.watch():
 ```
 
 ```rust [Rust]
+// `RowEvent` is an enum; match on the variant to destructure its fields.
+// `StreamExt` (for `.next()`) comes from the `futures` crate, which is only a
+// dirsql dependency under its `cli` feature -- add it to your own project:
+//
+//     cargo add futures
+use dirsql::RowEvent;
 use futures::StreamExt;
 
-let mut stream = db.watch();
+let mut stream = db.watch()?; // watch() returns Result<WatchStream>
 while let Some(event) = stream.next().await {
-    match event.action {
-        Action::Insert => println!("New row in {}: {:?}", event.table, event.row),
-        Action::Update => println!("Updated row in {}: {:?}", event.table, event.row),
-        Action::Delete => println!("Deleted row from {}: {:?}", event.table, event.row),
-        Action::Error => eprintln!("Error: {:?}", event.error),
+    match event {
+        RowEvent::Insert { table, row, file_path } => {
+            println!("New row in {table} ({file_path}): {row:?}")
+        }
+        RowEvent::Update { table, new_row, file_path, .. } => {
+            println!("Updated row in {table} ({file_path}): {new_row:?}")
+        }
+        RowEvent::Delete { table, row, file_path } => {
+            println!("Deleted row from {table} ({file_path}): {row:?}")
+        }
+        RowEvent::Error { file_path, error, .. } => {
+            eprintln!("Error on {file_path:?}: {error}")
+        }
     }
 }
 ```
@@ -188,16 +227,20 @@ async def main():
 ```
 
 ```rust [Rust]
-async fn watch_and_serve(db: &DirSQL) {
-    let mut stream = db.watch();
+// `.next()` needs `StreamExt` from the `futures` crate (`cargo add futures`).
+use futures::StreamExt;
+
+async fn watch_and_serve(db: &DirSQL) -> Result<(), Box<dyn std::error::Error>> {
+    let mut stream = db.watch()?; // watch() returns Result<WatchStream>
     while let Some(event) = stream.next().await {
         notify_clients(&event).await;
     }
+    Ok(())
 }
 
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
-    let db = DirSQL::new("./data", vec![...])?;
+    let db = DirSQL::new("./data", vec![/* tables */])?;
 
     tokio::join!(
         watch_and_serve(&db),

{dirsql-0.3.23/packages/python → dirsql-0.3.25}/docs/guide/crdt.md

@@ -94,7 +94,7 @@ const tables: TableDef[] = [
   },
 ];
 
-const db = new DirSQL('./workspace', tables);
+const db = new DirSQL({ root: './workspace', tables });
 ```
 
 :::

{dirsql-0.3.23 → dirsql-0.3.25}/docs/guide/querying.md

@@ -160,8 +160,9 @@ assert!(matches!(err, dirsql::DirSqlError::WriteForbidden));
 ```
 
 ```typescript [TypeScript]
-// Throws an Error whose message explains writes are not accepted.
-expect(() => db.query('DELETE FROM posts')).toThrow(/read-only/i);
+// Rejects with an Error whose message explains writes are not accepted.
+// `db.query` is async, so assert on the rejected promise.
+await expect(db.query('DELETE FROM posts')).rejects.toThrow(/read-only/i);
 ```
 
 :::

{dirsql-0.3.23/packages/rust → dirsql-0.3.25}/docs/guide/tables.md

@@ -91,7 +91,7 @@ Glob syntax follows standard Unix globbing rules. `**` matches any number of dir
 
 A callable `(path: str) -> list[dict]` that converts a file into rows.
 
-- `path` is the **absolute filesystem path** of the matched file
+- `path` is the path of the matched file, **relative to the scan root** (or absolute when the `root` passed to `DirSQL` is absolute)
 - Return a list of dicts, where each dict maps column names to values
 - Return an empty list to skip a file
 

{dirsql-0.3.23 → dirsql-0.3.25}/docs/guide/watching.md

@@ -36,6 +36,10 @@ async for event in db.watch():
 ```
 
 ```rust [Rust]
+// `StreamExt` (for `.next()`) comes from the `futures` crate. dirsql only
+// depends on `futures` under its `cli` feature, so add it to your project:
+//
+//     cargo add futures
 use dirsql::{DirSQL, RowEvent, Table, Value};
 use futures::StreamExt;
 use std::collections::HashMap;
@@ -84,8 +88,8 @@ while let Some(event) = stream.next().await {
         RowEvent::Delete { table, row, file_path } => {
             println!("delete on {table} ({file_path}): {row:?}")
         }
-        RowEvent::Error { file_path, error } => {
-            println!("error on {file_path:?}: {error}")
+        RowEvent::Error { table, file_path, error } => {
+            println!("error on {table:?} {file_path:?}: {error}")
         }
     }
 }

{dirsql-0.3.23 → dirsql-0.3.25}/packages/python/Cargo.toml

@@ -4,7 +4,7 @@ name = "dirsql-py-ext"
 # pypi/maturin handler can rewrite it via `write-version` before
 # `maturin build`. `pyproject.toml` declares `dynamic = ["version"]`
 # and maturin reads this field. Mirrors `packages/rust/Cargo.toml`.
-version = "0.3.23"
+version = "0.3.25"
 edition.workspace = true
 publish = false
 readme = "README.md"

{dirsql-0.3.23/packages/rust → dirsql-0.3.25/packages/python}/docs/api/index.md

@@ -188,11 +188,12 @@ import { Table } from 'dirsql';
 ::: code-group
 
 ```python [Python]
-Table(*, ddl: str, glob: str, extract: Callable[[str], list[dict]])
+Table(*, ddl: str, glob: str, extract: Callable[[str], list[dict]], strict: bool = False)
 ```
 
 ```rust [Rust]
-Table::new(ddl: &str, glob: &str, extract: fn(&str) -> Vec<Value>)
+// Row = HashMap<String, Value>
+Table::new(ddl: &str, glob: &str, extract: fn(&str) -> Vec<HashMap<String, Value>>)
 ```
 
 ```typescript [TypeScript]
@@ -207,7 +208,8 @@ Defines a mapping from files to SQLite table rows.
 
 - `ddl` -- A `CREATE TABLE` statement. The table name is parsed from this DDL.
 - `glob` -- A glob pattern matched against file paths relative to the root directory.
-- `extract` -- A callable `(path) -> list[dict]`. Receives the absolute filesystem path of the matched file. `dirsql` does not read file contents; a callback that needs the file body reads `path` itself. Returns a list of dicts/maps mapping column names to values. Return an empty list to skip a file.
+- `extract` -- A callable `(path) -> list[dict]`. Receives the path of the matched file -- relative to the scan root, or absolute when `root` is absolute. `dirsql` does not read file contents; a callback that needs the file body reads `path` itself. Returns a list of dicts/maps mapping column names to values. Return an empty list to skip a file.
+- `strict` -- Optional (default `False`). Controls row/schema validation. In the default relaxed mode, extra row keys are dropped and missing columns become `NULL`. When `True`, every row key must be a valid column identifier and any extra or missing key raises an error. Surfaced in [serialization](#serialization) above as part of each table's `{ ddl, glob, strict }`.
 
 **Attributes:**
 
@@ -231,7 +233,7 @@ use dirsql::RowEvent;
 ```
 
 ```typescript [TypeScript]
-import { RowEvent } from 'dirsql';
+import type { RowEvent } from 'dirsql';
 ```
 
 :::