@fadhilp/stateql 0.1.1 → 0.2.0

package/README.md

@@ -8,12 +8,15 @@ Requires Node.js 22.5 or newer.
 
 ## Quick start
 
+```bash
+npm install -g @fadhilp/stateql
+```
+
 Connect to an existing SQLite database, then run a filtered, parameterized
 query. Parameters keep values separate from SQL; `ORDER BY` makes paging
 stable, while `LIMIT` bounds work at the database.
 
 ```bash
-npm install --global stateql
 export STQL_SESSION=audit
 stql profile add local ./app.sqlite
 stql connect local
@@ -61,17 +64,23 @@ Example first page:
 Running the same normalized query with the same parameters reuses `q_1` while
 its cache is valid. Use `--cache bypass` when a fresh read is required.
 
-PostgreSQL credentials should come from an environment variable:
+PostgreSQL and MySQL credentials should come from environment variables:
 
 ```bash
 export APP_DATABASE_URL='postgres://user:password@host/app'
 stql connect --env APP_DATABASE_URL --name app --read-only
+
+export MYSQL_DATABASE_URL='mysql://user:password@host/app'
+stql connect --env MYSQL_DATABASE_URL --name mysql-app --read-only
 ```
 
+MySQL uses positional `?` parameters. MariaDB compatibility is not currently
+claimed.
+
 ## Commands
 
 ```text
-stql connect <sqlite-path|postgres-url> [--name NAME] [--env ENV] [--read-write]
+stql connect <sqlite-path|postgres-url|mysql-url> [--name NAME] [--env ENV] [--read-write]
 stql connect --profile NAME
 stql status
 stql profile add|list|show|remove
@@ -94,6 +103,13 @@ stql batch [commands.json|commands.jsonl|-] [--continue-on-error]
 stql pipe [--continue-on-error]
 ```
 
+Database commands accept `--timeout-ms N`; default is 30,000 ms. `Ctrl+C`
+cancels active work. SQLite runs in a killable child process so long synchronous
+statements cannot block StateQL's event loop. PostgreSQL uses server-side
+`statement_timeout` plus client deadlines. MySQL deadlines destroy the active
+connection. A timed-out write may return `OUTCOME_UNKNOWN` when commit status
+cannot be proven.
+
 ## Output modes
 
 CLI output defaults to compact, one-line `agent` JSON. Successes flatten useful
@@ -173,25 +189,31 @@ Run the array with `stql batch commands.json`. Batch fields use snake case;
 supported command names match CLI paths, such as `filter`,
 `transaction.begin`, `session.summary`, `alias.set`, `plan`, and `apply`.
 Batch filters use `where` for the predicate and may assign the derived result
-with `as`.
+with `as`. Database commands may set `timeout_ms`; otherwise they use the
+30-second default.
 
 State metadata lives under `STQL_HOME`, or the platform data directory when
 unset. Set `STQL_SESSION` to select a named session.
 
 Read cache entries expire after five minutes; materialized handles expire after
-24 hours. Queries exceeding 10,000 rows fail before materialization; add a
-narrower `WHERE` clause or `LIMIT`. Command history keeps the latest 10,000
-entries per session. SQLite cache reuse also checks
-the database file signature; PostgreSQL reuse is labeled `ttl_based`, never
-authoritative. Transactions are staged in local state so they survive CLI
-invocations, then executed atomically on commit. Connections cannot be changed
-or disconnected while a transaction is active. SQLite supports `serializable`;
-PostgreSQL also supports `repeatable read`, `read committed`, and
-`read uncommitted`. PostgreSQL reads run inside database-enforced read-only
-transactions.
-
-StateQL stores no PostgreSQL password. Credential-bearing URLs must be supplied
-through `--env`. SQLite result rows are materialized locally for durable access.
+24 hours. Expired results and plans are deleted when StateQL next opens. Queries
+exceeding 10,000 rows or 16 MiB of serialized row data fail before persistence;
+add a narrower `WHERE` clause, `LIMIT`, or smaller column selection. These caps
+bound persisted materialization, while the independent deadline bounds execution
+time. Command history keeps the latest 10,000 entries per session. SQLite cache reuse also checks
+the database file signature; PostgreSQL and MySQL reuse is labeled `ttl_based`,
+never authoritative. Transactions are staged in local state so they survive CLI
+invocations, then executed atomically on commit. Database reads, plans,
+connection changes, and disconnects are rejected while a transaction is active;
+commit or roll back first. SQLite supports `serializable`;
+PostgreSQL and MySQL also support `repeatable read`, `read committed`, and
+`read uncommitted`. Server reads run inside database-enforced read-only
+transactions. MySQL staged transactions reject DDL because MySQL implicitly
+commits those statements.
+
+StateQL stores no PostgreSQL or MySQL password. Credential-bearing URLs must be
+supplied through `--env`. SQLite result rows are materialized locally for
+durable access.
 `filter` evaluates one scalar SQLite predicate against those stored rows, keeps
 source order, state metadata, and expiry, and never accesses the original
 database. Use parameters for values. Subqueries, query-shaping clauses, and
@@ -209,10 +231,18 @@ Interrupted commits remain fail-closed; stale `committing` records become
 ## Library
 
 ```ts
-import { StateQL } from "stateql";
-
-const stateql = new StateQL({ home: "./.stql" });
-const response = await stateql.query("SELECT * FROM users");
+import { StateQL } from "@fadhilp/stateql";
+
+const stateql = new StateQL({
+  home: "./.stql",
+  timeoutMs: 30_000,
+  maxResultBytes: 16 * 1024 * 1024,
+});
+const controller = new AbortController();
+const response = await stateql.query("SELECT * FROM users", {
+  signal: controller.signal,
+  timeoutMs: 5_000,
+});
 if (response.ok) {
   const handle = (response.data as { result_id: string }).result_id;
   await stateql.filter(handle, "email LIKE ?", {

package/dist/src/adapters.d.ts

@@ -7,10 +7,23 @@ export interface ReadResult {
 export interface WriteResult {
     affectedRows: number;
 }
+export interface AdapterContext {
+    deadline: number;
+    signal?: AbortSignal;
+}
+export declare class AdapterExecutionError extends Error {
+    readonly reason: "timeout" | "aborted";
+    readonly outcomeUnknown: boolean;
+    constructor(message: string, reason: "timeout" | "aborted", outcomeUnknown: boolean);
+}
 export declare class BatchWriteError extends Error {
     readonly outcomeUnknown: boolean;
     constructor(message: string, outcomeUnknown: boolean);
 }
+export declare class AdapterWriteError extends Error {
+    readonly outcomeUnknown: boolean;
+    constructor(message: string, outcomeUnknown: boolean);
+}
 export interface Adapter {
     readonly confidence: StateConfidence;
     read(sql: string, params: SqlParameters): Promise<ReadResult>;
@@ -20,4 +33,5 @@ export interface Adapter {
     inspect(kind: string, table?: string): Promise<unknown>;
     close(): Promise<void>;
 }
-export declare function createAdapter(connection: ConnectionRecord): Promise<Adapter>;
+export declare function createAdapterContext(timeoutMs: number, signal?: AbortSignal): AdapterContext;
+export declare function createAdapter(connection: ConnectionRecord, context: AdapterContext): Promise<Adapter>;