dirsql 0.4.142 → 0.4.144

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

@@ -212,7 +212,7 @@ 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.
 ```
 
@@ -227,8 +227,9 @@ 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 fills `?` placeholders in order; a mapping fills `:name`
-placeholders, keyed by the name without its prefix. It works for path-tables
+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
@@ -241,6 +242,15 @@ await db.query(
 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;
@@ -259,20 +269,23 @@ db.query_with(
 
 :::
 
-TypeScript does not take bind parameters yet.
-
 - 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`. Rust binds a
-  `Value`.
+  `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). Rust returns
-  `DbError::Params`.
+  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.
 
@@ -311,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.142",
+  "version": "0.4.144",
   "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.142",
-    "@dirsql/lib-linux-arm64-gnu": "0.4.142",
-    "@dirsql/lib-darwin-x64": "0.4.142",
-    "@dirsql/lib-darwin-arm64": "0.4.142",
-    "@dirsql/lib-win32-x64-msvc": "0.4.142"
+    "@dirsql/lib-linux-x64-gnu": "0.4.144",
+    "@dirsql/lib-linux-arm64-gnu": "0.4.144",
+    "@dirsql/lib-darwin-x64": "0.4.144",
+    "@dirsql/lib-darwin-arm64": "0.4.144",
+    "@dirsql/lib-win32-x64-msvc": "0.4.144"
   }
 }