dirsql 0.4.141 → 0.4.143

package/dist/core.d.ts

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

package/dist/dirsql.d.ts

@@ -82,6 +82,13 @@ export interface RowEvent {
     error?: string | null;
     filePath?: string | null;
 }
+/**
+ * Bind parameters for {@link DirSQL.query}: an array fills `?` placeholders
+ * in order; a plain object fills `:name`, `@name` and `$name` placeholders,
+ * keyed by the name without its prefix. Values bind as SQLite's native types:
+ * `null`, `number`, `bigint`, `boolean`, `string`, `Buffer` / `Uint8Array`.
+ */
+export type QueryParams = readonly unknown[] | Record<string, unknown> | null;
 /** The result of {@link DirSQL.queryOrdered}. */
 export interface QueryResult {
     /**
@@ -159,8 +166,16 @@ export declare class DirSQL {
      * 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.
+     *
+     * `params` binds to the statement's placeholders through SQLite, so the
+     * values never enter the SQL text:
+     *
+     * ```ts
+     * await db.query("SELECT path FROM './*.json' WHERE content ->> 'a' = :a", { a: text });
+     * await db.query("SELECT * FROM notes WHERE author = ?", ["ann"]);
+     * ```
      */
-    query(sql: string): Promise<Record<string, unknown>[]>;
+    query(sql: string, params?: QueryParams): Promise<Record<string, unknown>[]>;
     /**
      * {@link query}, plus the column order the SELECT list names. Use it to
      * render columns in the order the caller asked for.
@@ -170,7 +185,7 @@ export declare class DirSQL {
      * // columns: ["path", "size"]
      * ```
      */
-    queryOrdered(sql: string): Promise<QueryResult>;
+    queryOrdered(sql: string, params?: QueryParams): Promise<QueryResult>;
     /**
      * The files the initial scan could not index, each with its root-relative
      * `path` and the hook's own `message`.

package/dist/dirsql.js

@@ -104,10 +104,18 @@ export class DirSQL {
      * 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.
+     *
+     * `params` binds to the statement's placeholders through SQLite, so the
+     * values never enter the SQL text:
+     *
+     * ```ts
+     * await db.query("SELECT path FROM './*.json' WHERE content ->> 'a' = :a", { a: text });
+     * await db.query("SELECT * FROM notes WHERE author = ?", ["ann"]);
+     * ```
      */
-    async query(sql) {
+    async query(sql, params) {
         await this.ready;
-        return this._inner.query(sql);
+        return this._inner.query(sql, params);
     }
     /**
      * {@link query}, plus the column order the SELECT list names. Use it to
@@ -118,9 +126,9 @@ export class DirSQL {
      * // columns: ["path", "size"]
      * ```
      */
-    async queryOrdered(sql) {
+    async queryOrdered(sql, params) {
         await this.ready;
-        return this._inner.queryOrdered(sql);
+        return this._inner.queryOrdered(sql, params);
     }
     /**
      * The files the initial scan could not index, each with its root-relative

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { DirSQL } from "./dirsql.js";
-export type { DirSQLOptions, ExtensionSpec, QueryResult, RowEvent, ScanFailure, } from "./dirsql.js";
+export type { DirSQLOptions, ExtensionSpec, QueryParams, QueryResult, RowEvent, ScanFailure, } from "./dirsql.js";
 export { Table } from "./table.js";
 export type { TableDef } from "./table.js";

package/docs/reference/sdk.md

@@ -208,22 +208,87 @@ observe construction errors before issuing a query.
 ::: code-group
 
 ```python [Python]
-await db.query(sql: str) -> list[dict]
+await db.query(sql: str, params: Sequence | Mapping | None = None) -> list[dict]
 ```
 
 ```typescript [TypeScript]
-await db.query(sql: string) -> Record<string, unknown>[]
+await db.query(sql: string, params?: unknown[] | Record<string, unknown> | null) -> Record<string, unknown>[]
 // Runs on the libuv threadpool; the JS event loop stays responsive.
 ```
 
 ```rust [Rust]
 db.query(sql: &str) -> Result<Vec<Row>>   // Row = HashMap<String, Value>
+db.query_with(sql: &str, params: &Params) -> Result<Vec<Row>>
 ```
 
 :::
 
 Executes a SQL query and returns rows keyed by column name.
 
+**Bind parameters.** `params` reaches SQLite's own parameter binding; the
+values never enter the SQL text, so text holding quotes needs no escaping.
+A sequence (a TypeScript array) fills `?` placeholders in order; a mapping
+(a TypeScript plain object) fills `:name`, `@name` and `$name` placeholders,
+keyed by the name without its prefix. It works for path-tables
+and declared tables alike:
+
+::: code-group
+
+```python [Python]
+await db.query(
+    "SELECT path FROM './*.json' WHERE content ->> 'advice' = :advice",
+    {"advice": text},
+)
+await db.query("SELECT * FROM notes WHERE author = ? AND year = ?", ("ann", 2024))
+```
+
+```typescript [TypeScript]
+await db.query(
+  "SELECT path FROM './*.json' WHERE content ->> 'advice' = :advice",
+  { advice: text },
+);
+await db.query("SELECT * FROM notes WHERE author = ? AND year = ?", ["ann", 2024]);
+// queryOrdered takes params the same way.
+```
+
+```rust [Rust]
+use dirsql::{Params, Value};
+use std::collections::HashMap;
+
+db.query_with(
+    "SELECT path FROM './*.json' WHERE content ->> 'advice' = :advice",
+    &Params::Named(HashMap::from([("advice".into(), Value::Text(text))])),
+)?;
+db.query_with(
+    "SELECT * FROM notes WHERE author = ?",
+    &Params::Positional(vec![Value::Text("ann".into())]),
+)?;
+// query_ordered_with and query_each_with bind the same way;
+// AsyncDirSQL::query_with is the async twin.
+```
+
+:::
+
+- Values bind as SQLite's native types. Python accepts `None`, `int`
+  (`bool` binds as `0`/`1`), `float`, `str`, `bytes` and `bytearray`;
+  anything else raises `TypeError` rather than being stringified, and an
+  `int` outside the signed 64-bit range raises `OverflowError`. TypeScript
+  accepts `null`, `number` (an integral value binds as an INTEGER, any other
+  as a REAL, so `1.0` binds as `1`), `bigint`, `boolean` (`0`/`1`), `string`,
+  and `Buffer` / `Uint8Array`; anything else, `undefined` included, rejects
+  with a `TypeError`, and a `bigint` outside the signed 64-bit range with a
+  `RangeError`. Rust binds a `Value`.
+- The params must fit the placeholders exactly, or the query fails with an
+  error naming the problem: a wrong count for a sequence, a placeholder name
+  the mapping lacks, a mapping key no placeholder uses, or a sequence for
+  named placeholders (and a mapping for `?`). Python raises a
+  `RuntimeError` for these, and a `TypeError` when `params` is neither a
+  sequence nor a mapping (a `str` counts as neither). TypeScript rejects
+  with an `Error` for these, and a `TypeError` when `params` is neither an
+  array nor a plain object. Rust returns `DbError::Params`.
+- Without `params`, a statement with placeholders fails the same way: a
+  placeholder is never left unbound.
+
 - **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
@@ -259,11 +324,12 @@ round-trips.
 ::: code-group
 
 ```typescript [TypeScript]
-await db.queryOrdered(sql: string) -> { columns: string[]; rows: Record<string, unknown>[] }
+await db.queryOrdered(sql: string, params?: unknown[] | Record<string, unknown> | null) -> { columns: string[]; rows: Record<string, unknown>[] }
 ```
 
 ```rust [Rust]
 db.query_ordered(sql: &str) -> Result<QueryResult>   // QueryResult { columns, rows }
+db.query_ordered_with(sql: &str, params: &Params) -> Result<QueryResult>
 ```
 
 :::

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dirsql",
-  "version": "0.4.141",
+  "version": "0.4.143",
   "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.141",
-    "@dirsql/lib-linux-arm64-gnu": "0.4.141",
-    "@dirsql/lib-darwin-x64": "0.4.141",
-    "@dirsql/lib-darwin-arm64": "0.4.141",
-    "@dirsql/lib-win32-x64-msvc": "0.4.141"
+    "@dirsql/lib-linux-x64-gnu": "0.4.143",
+    "@dirsql/lib-linux-arm64-gnu": "0.4.143",
+    "@dirsql/lib-darwin-x64": "0.4.143",
+    "@dirsql/lib-darwin-arm64": "0.4.143",
+    "@dirsql/lib-win32-x64-msvc": "0.4.143"
   }
 }