dirsql 0.3.25 → 0.3.26

package/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';
 ```
 
 :::

package/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
 

package/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),

package/docs/guide/crdt.md

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

package/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);
 ```
 
 :::

package/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
 

package/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}")
         }
     }
 }

package/package.json

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