@fadhilp/stateql 0.13.3 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,98 +1,60 @@
1
1
  # StateQL
2
2
 
3
3
  StateQL is a stateful database CLI and TypeScript library for AI agents and
4
- automation. Query, change, and inspect databases while keeping results reusable
5
- and operations traceable across commands.
4
+ automation. It keeps query results as durable handles, so later commands can
5
+ page, filter, count, or export them without querying the database again.
6
6
 
7
7
  - **SQL:** SQLite, PostgreSQL, and MySQL.
8
8
  - **Native commands:** MongoDB (EJSON) and Redis (JSON).
9
- - **Durable handles:** reuse, filter, page, count, alias, or export stored results
10
- without rerunning the original query.
11
- - **Tracked writes:** inspect operations, review plans, and stage transactions
12
- where supported by the database.
9
+ - **Compact output:** one-line JSON with a 5-row preview and column names sent once.
10
+ - **Safe writes:** read-only by default, explicit approval for unbounded or
11
+ destructive statements, idempotency keys, plans, and staged transactions.
13
12
 
14
- Requires **Node.js 22.16 or newer** for the required `node:sqlite` APIs.
13
+ Requires **Node.js 22.16 or newer**.
15
14
 
16
- ## Quick start
17
-
18
- Install the CLI:
15
+ ## Install
19
16
 
20
17
  ```bash
21
- npm install -g @fadhilp/stateql
18
+ npm install -g @fadhilp/stateql # CLI (stql)
19
+ npm install @fadhilp/stateql # TypeScript library
22
20
  ```
23
21
 
24
- Connect to an existing SQLite database containing a `users` table. These shell
25
- examples use Bash; see the [usage guide](docs/usage.md) for connection options and
26
- SQL parameter handling.
22
+ ## Quick start
27
23
 
28
24
  ```bash
29
25
  export STQL_SESSION=audit
30
- stql profile add local ./app.sqlite --read-only
31
- stql connect local
26
+ stql connect ./app.sqlite
32
27
 
33
- stql query \
34
- "SELECT id, name, email FROM users WHERE status = ? AND created_at >= ? ORDER BY id LIMIT 50" \
35
- --param active \
36
- --param 2026-01-01
28
+ stql query "SELECT id, name FROM users WHERE status = ? ORDER BY id" --param active
37
29
  ```
38
30
 
39
- Parameters keep values separate from SQL. `ORDER BY` makes paging stable, and
40
- `LIMIT` bounds work at the database. The default `agent` output is compact,
41
- one-line JSON. An example response:
42
-
43
31
  ```json
44
- {"ok":true,"handle":"q_k7m2v5x9c3d6f8h4j2n7p5r9tw","rows":[{"id":7,"name":"Ada","email":"ada@example.com"}],"truncated":false,"cached":false,"total":1,"next_offset":null}
32
+ {"ok":true,"handle":"katcitg6un","total":333,"next_offset":5,"columns":["id","name"],"rows":[[2,"Ada"],[3,"Grace"],[5,"Linus"],[6,"Alan"],[8,"Edsger"]]}
45
33
  ```
46
34
 
47
- Use the handle returned by your query in place of the example handle below.
48
- Give the snapshot a readable alias, then work with the stored data:
35
+ Reuse the result by its handle. These commands do not access the database:
49
36
 
50
37
  ```bash
51
- stql alias set active-users q_k7m2v5x9c3d6f8h4j2n7p5r9tw
52
- stql rows active-users --offset 0 --limit 10
53
- stql count active-users
54
- stql export active-users --output active-users.csv --format csv
55
- stql filter active-users "email LIKE ?" --param "%@example.com"
38
+ stql rows katcitg6un --offset 5 --limit 20
39
+ stql filter katcitg6un "name LIKE ?" --param "A%"
40
+ stql export katcitg6un --output users.csv
56
41
  ```
57
42
 
58
- These commands do not access the original database. `filter` creates a new
59
- snapshot with its own handle. Repeating a query can reuse a valid cached result;
60
- use `--cache bypass` when a fresh database read is required.
61
-
62
- ## Safety and state
63
-
64
- - Connections are **read-only by default**. Writes require a read-write connection.
65
- - Destructive and unbounded SQL/MongoDB operations require independent
66
- `--allow-destructive` and `--allow-unbounded` approvals, respectively.
67
- - `plan` stores a write for review; `apply` never adds authorization. Use
68
- idempotency keys to protect retryable writes from duplicate execution.
69
- - A write reported as `OUTCOME_UNKNOWN` must be inspected at the database before
70
- replaying it. Transactions are staged locally, not live interactive SQL
71
- transactions.
72
- - Supply credential-bearing URLs through environment variables or a trusted
73
- library credential resolver, not literal command arguments or profiles.
74
- - Results and history persist under `STQL_HOME` (or the platform data directory).
75
- Treat that state as database data; retention and size limits are configurable.
76
-
77
- See [write safety](docs/usage.md#write-safety),
78
- [credentials](docs/usage.md#environment-backed-credentials), and
79
- [database restrictions](docs/databases.md) before using production data.
80
-
81
43
  ## Documentation
82
44
 
83
- | Guide | Contents |
45
+ | Page | Contents |
84
46
  | --- | --- |
85
- | [Usage](docs/usage.md) | Connections, CLI reference, results, sessions, limits, writes, transactions, batch and pipes |
86
- | [Database support](docs/databases.md) | SQL dialects, diagnostics, maintenance, native MongoDB and Redis commands |
87
- | [TypeScript library](docs/library.md) | Connection setup, response handling, cleanup, actors, workspaces, and credential resolution |
88
-
89
- Run `stql --help` for command syntax or `stql capabilities` for capability details.
47
+ | [Agent guide](docs/agents.md) | The short version for agents: connect, query, reuse, save tokens |
48
+ | [Connections](docs/connections.md) | Targets, environment credentials, profiles |
49
+ | [CLI reference](docs/cli.md) | Commands, parameters, catalog, output modes, deadlines |
50
+ | [Results and state](docs/results.md) | Sessions, actors, limits, caching, local filtering |
51
+ | [Write safety](docs/writes.md) | Approvals, plans, idempotency, transactions |
52
+ | [Batch and pipes](docs/batch.md) | Run many commands in one call |
53
+ | [Database support](docs/databases.md) | Dialects, diagnostics, MongoDB and Redis commands |
54
+ | [TypeScript library](docs/library.md) | API, responses, actors, credential resolution |
90
55
 
91
- ## TypeScript installation
56
+ Run `stql help` for command syntax and `stql capabilities` for feature details.
92
57
 
93
- ```bash
94
- npm install @fadhilp/stateql
95
- ```
58
+ ## License
96
59
 
97
- The package exports `StateQL` and public TypeScript types. Start with the
98
- [connected, cleanup-safe example](docs/library.md#getting-started).
60
+ [MIT](LICENSE)
package/dist/src/cli.js CHANGED
@@ -6,6 +6,13 @@ import { parseArgs } from "node:util";
6
6
  import { BSON } from "mongodb";
7
7
  import { exitCodeFor } from "./errors.js";
8
8
  import { StateQL } from "./stateql.js";
9
+ import { isColumns, isRecord } from "./util.js";
10
+ const RESULT_COMMANDS = new Set(["query", "mongo.query", "filter", "show"]);
11
+ const FALSE_DEFAULT_KEYS = ["cached", "duplicate", "duplicate_override"];
12
+ const SHARED_HISTORY_KEYS = ["session_id", "actor_id", "actor_name", "origin"];
13
+ // The caller already holds the handle it passed to these commands.
14
+ const HANDLE_ECHO_COMMANDS = new Set(["rows", "count", "columns"]);
15
+ const WRITE_COMMANDS = new Set(["exec", "mongo.exec", "apply"]);
9
16
  const parsed = parseArgs({
10
17
  allowPositionals: true,
11
18
  strict: true,
@@ -21,6 +28,7 @@ const parsed = parseArgs({
21
28
  "params-file": { type: "string" },
22
29
  cache: { type: "string" },
23
30
  "preview-rows": { type: "string" },
31
+ "max-cell-characters": { type: "string" },
24
32
  replay: { type: "boolean" },
25
33
  "idempotency-key": { type: "string" },
26
34
  "allow-unbounded": { type: "boolean" },
@@ -51,7 +59,7 @@ if (values.version) {
51
59
  console.log(packageVersion());
52
60
  process.exit(0);
53
61
  }
54
- if (values.help || !command) {
62
+ if (values.help || !command || command === "help") {
55
63
  console.log(helpText());
56
64
  process.exit(0);
57
65
  }
@@ -71,6 +79,9 @@ const stateql = new StateQL({
71
79
  ...(values["result-ttl-seconds"] === undefined
72
80
  ? {}
73
81
  : { resultTtlSeconds: Number(values["result-ttl-seconds"]) }),
82
+ ...(values["max-cell-characters"] === undefined
83
+ ? {}
84
+ : { maxCellCharacters: Number(values["max-cell-characters"]) }),
74
85
  signal: abortController.signal,
75
86
  });
76
87
  try {
@@ -534,33 +545,33 @@ function print(result, mode, currentCommand) {
534
545
  function toAgentResponse(result, currentCommand) {
535
546
  if (!result.ok)
536
547
  return { ok: false, error: result.error };
537
- if (!result.data ||
538
- typeof result.data !== "object" ||
539
- Array.isArray(result.data)) {
548
+ if (!isRecord(result.data))
540
549
  return { ok: true, data: result.data };
541
- }
542
550
  const data = { ...result.data };
543
551
  const handleKey = primaryHandleKey(currentCommand);
544
- const handle = handleKey && typeof data[handleKey] === "string" && data[handleKey]
552
+ let handle = handleKey && typeof data[handleKey] === "string" && data[handleKey]
545
553
  ? data[handleKey]
546
554
  : undefined;
547
555
  if (handle && handleKey)
548
556
  delete data[handleKey];
549
- if ((currentCommand === "query" ||
550
- currentCommand === "mongo.query" ||
551
- currentCommand === "filter" ||
552
- currentCommand === "show") &&
557
+ const generatedAlias = data.display_alias;
558
+ delete data.display_alias;
559
+ // Generated aliases cannot be reassigned, so they are stable short result handles.
560
+ if (RESULT_COMMANDS.has(currentCommand) && typeof generatedAlias === "string") {
561
+ handle = generatedAlias;
562
+ if (data.alias === generatedAlias)
563
+ delete data.alias;
564
+ }
565
+ const isResult = RESULT_COMMANDS.has(currentCommand) &&
553
566
  typeof data.rows === "number" &&
554
- Array.isArray(data.preview)) {
555
- const total = data.rows;
556
- const rows = data.preview;
557
- const truncated = Boolean(data.truncated);
558
- data.rows = rows;
559
- data.total = total;
560
- data.next_offset = truncated ? rows.length : null;
567
+ Array.isArray(data.preview);
568
+ if (isResult) {
569
+ data.total = data.rows;
570
+ data.next_offset = data.truncated ? data.preview.length : null;
571
+ data.rows = data.preview;
561
572
  delete data.preview;
562
573
  delete data.preview_count;
563
- delete data.columns;
574
+ delete data.truncated;
564
575
  delete data.storage;
565
576
  delete data.state_version;
566
577
  delete data.duplicate_of;
@@ -569,11 +580,55 @@ function toAgentResponse(result, currentCommand) {
569
580
  delete data.offset;
570
581
  delete data.limit;
571
582
  delete data.returned;
583
+ delete data.truncated;
572
584
  }
573
585
  else if (currentCommand === "count" && typeof data.rows === "number") {
574
586
  data.total = data.rows;
575
587
  delete data.rows;
576
588
  }
589
+ else if (WRITE_COMMANDS.has(currentCommand)) {
590
+ delete data.actor_id;
591
+ delete data.plan_id;
592
+ delete data.state_version_before;
593
+ if (typeof data.status === "string")
594
+ delete data.committed;
595
+ }
596
+ else if (currentCommand === "history" &&
597
+ Array.isArray(data.history) &&
598
+ data.history.every(isRecord)) {
599
+ Object.assign(data, compactHistory(data.history));
600
+ }
601
+ else if (currentCommand === "inspect" && Array.isArray(data.columns)) {
602
+ data.columns = data.columns.map(withoutFalsePrimaryKey);
603
+ }
604
+ else if (currentCommand === "capabilities" && isRecord(data.features)) {
605
+ const features = data.features;
606
+ data.features = Object.keys(features).filter((key) => features[key] === true);
607
+ }
608
+ else if (currentCommand === "objects" &&
609
+ Array.isArray(data.objects) &&
610
+ data.objects.every(isRecord)) {
611
+ const objects = data.objects.every(hasDerivedIdentity)
612
+ ? data.objects.map(withoutIdentity)
613
+ : data.objects;
614
+ const table = columnarRows(objects, undefined);
615
+ delete data.objects;
616
+ Object.assign(data, { columns: table.columns, objects: table.rows });
617
+ }
618
+ else if (currentCommand === "object" &&
619
+ isRecord(data.object) &&
620
+ hasDerivedIdentity(data.object)) {
621
+ data.object = withoutIdentity(data.object);
622
+ }
623
+ if (isResult || (currentCommand === "rows" && Array.isArray(data.rows))) {
624
+ const table = columnarRows(data.rows, data.columns);
625
+ delete data.columns;
626
+ delete data.rows;
627
+ Object.assign(data, table);
628
+ }
629
+ const hasMoreRows = data.next_offset !== null && data.next_offset !== undefined;
630
+ const warnings = result.warnings.filter((warning) => warning.code !== "NON_DETERMINISTIC_PAGINATION" || hasMoreRows);
631
+ dropFalseDefaults(data);
577
632
  for (const key of ["ok", "error", "handle", "warnings"]) {
578
633
  if (!(key in data))
579
634
  continue;
@@ -582,11 +637,77 @@ function toAgentResponse(result, currentCommand) {
582
637
  }
583
638
  return {
584
639
  ok: true,
585
- ...(handle ? { handle } : {}),
586
- ...data,
587
- ...(result.warnings.length ? { warnings: result.warnings } : {}),
640
+ ...(handle && !HANDLE_ECHO_COMMANDS.has(currentCommand) ? { handle } : {}),
641
+ ...withoutNulls(data),
642
+ ...(warnings.length ? { warnings } : {}),
588
643
  };
589
644
  }
645
+ // Rows with differing keys (e.g. MongoDB documents) stay objects so missing and null remain distinct.
646
+ function columnarRows(rows, columns) {
647
+ const names = isColumns(columns)
648
+ ? columns.map((column) => column.name)
649
+ : Object.keys(rows[0] ?? {});
650
+ if (names.length === 0)
651
+ return { rows };
652
+ const nameSet = new Set(names);
653
+ const hasColumnKeys = (row) => {
654
+ if (!isRecord(row))
655
+ return false;
656
+ const keys = Object.keys(row);
657
+ return keys.length === names.length && keys.every((key) => nameSet.has(key));
658
+ };
659
+ if (!rows.every(hasColumnKeys))
660
+ return { rows };
661
+ return {
662
+ columns: names,
663
+ rows: rows.map((row) => names.map((name) => row[name])),
664
+ };
665
+ }
666
+ function compactHistory(entries) {
667
+ const shared = {};
668
+ for (const key of SHARED_HISTORY_KEYS) {
669
+ const value = entries[0]?.[key];
670
+ if (value === undefined)
671
+ continue;
672
+ if (entries.every((entry) => entry[key] === value))
673
+ shared[key] = value;
674
+ }
675
+ const history = entries.map((entry) => {
676
+ const compact = withoutNulls(entry);
677
+ dropFalseDefaults(compact);
678
+ for (const key of Object.keys(shared))
679
+ delete compact[key];
680
+ return compact;
681
+ });
682
+ return { ...shared, history };
683
+ }
684
+ function hasDerivedIdentity(object) {
685
+ const qualifiedName = typeof object.schema === "string"
686
+ ? `${object.schema}.${String(object.name)}`
687
+ : object.name;
688
+ return object.identity === undefined || object.identity === qualifiedName;
689
+ }
690
+ function withoutIdentity(object) {
691
+ const compact = { ...object };
692
+ delete compact.identity;
693
+ return compact;
694
+ }
695
+ function withoutFalsePrimaryKey(column) {
696
+ if (!isRecord(column) || column.primary_key !== false)
697
+ return column;
698
+ const compact = { ...column };
699
+ delete compact.primary_key;
700
+ return compact;
701
+ }
702
+ function dropFalseDefaults(record) {
703
+ for (const key of FALSE_DEFAULT_KEYS) {
704
+ if (record[key] === false)
705
+ delete record[key];
706
+ }
707
+ }
708
+ function withoutNulls(record) {
709
+ return Object.fromEntries(Object.entries(record).filter(([, value]) => value !== null));
710
+ }
590
711
  function primaryHandleKey(currentCommand) {
591
712
  const keys = {
592
713
  query: "result_id",
@@ -674,10 +795,13 @@ Commands:
674
795
 
675
796
  SQL parameters: --params JSON, repeated --param VALUE, or --params-file FILE.
676
797
  Query preview: --preview-rows N (default: 5, maximum: 200).
798
+ Long cells: --max-cell-characters N (default: 200); use export for full values.
677
799
  Deadline: --timeout-ms N (default: 30000). Ctrl+C cancels database work.
678
800
  Credential refs require a trusted host CredentialResolver; the standalone CLI cannot resolve them.
679
801
  State: --max-state-bytes N, --cache-ttl-seconds N, --result-ttl-seconds N.
680
802
  Output: --output agent|json|jsonl|text|silent (default: agent).
803
+ Agent rows: arrays in "columns" order (objects when shapes differ). next_offset only when more rows exist.
804
+ Agent output omits null fields and false cached/duplicate flags. Guide: docs/agents.md.
681
805
  Batch/pipe accept JSON array files or JSONL streams. Stop on first error.`;
682
806
  }
683
807
  function packageVersion() {
@@ -14,4 +14,5 @@ export declare class StateQLError extends Error {
14
14
  });
15
15
  }
16
16
  export declare function exitCodeFor(code: string): number;
17
+ export declare function isTransientDatabaseError(error: unknown): boolean;
17
18
  export declare function asStateQLError(error: unknown): StateQLError;
@@ -49,6 +49,46 @@ export function exitCodeFor(code) {
49
49
  return 9;
50
50
  return 1;
51
51
  }
52
+ const TRANSIENT_NETWORK_CODES = new Set([
53
+ "ECONNRESET",
54
+ "ECONNREFUSED",
55
+ "ETIMEDOUT",
56
+ "EPIPE",
57
+ "EAI_AGAIN",
58
+ "PROTOCOL_CONNECTION_LOST",
59
+ ]);
60
+ // SQLSTATE classes: connection, transaction rollback, resources, operator intervention, system.
61
+ const TRANSIENT_SQLSTATE_CLASSES = new Set(["08", "40", "53", "57", "58"]);
62
+ // MySQL: too many connections, lock wait timeout, deadlock.
63
+ const TRANSIENT_MYSQL_ERRNOS = new Set([1040, 1205, 1213]);
64
+ const TRANSIENT_ERROR_NAMES = new Set([
65
+ "MongoNetworkError",
66
+ "MongoNetworkTimeoutError",
67
+ "MongoServerSelectionError",
68
+ "SocketClosedUnexpectedlyError",
69
+ "ConnectionTimeoutError",
70
+ ]);
71
+ const TRANSIENT_SQLITE_MESSAGE = /database (table )?is locked|SQLITE_BUSY/i;
72
+ // Permanent failures such as a missing table must not invite retries; unknown errors are not retryable.
73
+ export function isTransientDatabaseError(error) {
74
+ if (!(error instanceof Error))
75
+ return false;
76
+ const details = error;
77
+ if (typeof details.code === "string" && TRANSIENT_NETWORK_CODES.has(details.code))
78
+ return true;
79
+ if (TRANSIENT_ERROR_NAMES.has(error.name))
80
+ return true;
81
+ if (typeof details.errno === "number" && TRANSIENT_MYSQL_ERRNOS.has(details.errno))
82
+ return true;
83
+ if (Array.isArray(details.errorLabels) && details.errorLabels.includes("TransientTransactionError")) {
84
+ return true;
85
+ }
86
+ const sqlState = typeof details.sqlState === "string" ? details.sqlState : details.code;
87
+ if (typeof sqlState === "string" && /^[0-9A-Z]{5}$/.test(sqlState)) {
88
+ return TRANSIENT_SQLSTATE_CLASSES.has(sqlState.slice(0, 2));
89
+ }
90
+ return TRANSIENT_SQLITE_MESSAGE.test(error.message);
91
+ }
52
92
  export function asStateQLError(error) {
53
93
  if (error instanceof StateQLError)
54
94
  return error;
package/dist/src/sql.js CHANGED
@@ -58,7 +58,13 @@ function parseSqlStatement(sql, driver) {
58
58
  ? "MySQL"
59
59
  : "Sqlite";
60
60
  const parserSql = driver === "postgres" ? postgresParserSql(sql) : sql;
61
- const parsed = parser.astify(parserSql, { database });
61
+ let parsed;
62
+ try {
63
+ parsed = parser.astify(parserSql, { database });
64
+ }
65
+ catch (error) {
66
+ throw new StateQLError("INVALID_SQL", syntaxErrorMessage(error, parserSql));
67
+ }
62
68
  if (Array.isArray(parsed) && parsed.length !== 1) {
63
69
  throw new StateQLError("INVALID_SQL", "Exactly one SQL statement is required.");
64
70
  }
@@ -1073,6 +1079,17 @@ function postgresBlockCommentEnd(sql, start) {
1073
1079
  }
1074
1080
  return undefined;
1075
1081
  }
1082
+ // The parser lists every expected token (often 500+ characters); position and nearby text are enough to fix the SQL.
1083
+ function syntaxErrorMessage(error, sql) {
1084
+ const start = error.location?.start;
1085
+ if (!start)
1086
+ return error instanceof Error ? error.message : "Invalid SQL.";
1087
+ const near = sql.slice(start.offset, start.offset + 20).split("\n")[0];
1088
+ const position = `line ${start.line}, column ${start.column}`;
1089
+ return near
1090
+ ? `Syntax error at ${position} near "${near}".`
1091
+ : `Syntax error at ${position}: unexpected end of input.`;
1092
+ }
1076
1093
  function postgresParserSql(sql) {
1077
1094
  const output = sql.split("");
1078
1095
  const orderDepths = new Set();
@@ -6,7 +6,7 @@ import { basename, resolve } from "node:path";
6
6
  import { env } from "node:process";
7
7
  import { AdapterExecutionError, AdapterWriteError, BatchWriteError, createAdapter, createAdapterContext, } from "./adapters.js";
8
8
  import { confidence, credentialSource, databaseIdentity, databaseUrlHasSecret, detectDriver, isEnvironmentName, injectPassword, mongoDatabaseName, redisDatabaseName, normalizeSqliteSource, validateCredentialRef, validatePasswordReferenceTarget, validateProfileName, version, } from "./connection.js";
9
- import { asStateQLError, CredentialResolutionError, StateQLError, } from "./errors.js";
9
+ import { asStateQLError, CredentialResolutionError, isTransientDatabaseError, StateQLError, } from "./errors.js";
10
10
  import { analyzeMongoWriteSafety, deserializeMongoWriteCommand, serializeMongoCommand, validateMongoReadCommand, validateMongoWriteCommand, MongoAdapter, } from "./mongodb.js";
11
11
  import { deserializeRedisCommand, RedisAdapter, serializeRedisCommand, validateRedisReadCommand, validateRedisWriteCommand, } from "./redis.js";
12
12
  import { filterMaterializedRows, prepareFilterStatement, validateFilterParameters, } from "./filter.js";
@@ -811,7 +811,7 @@ export class StateQL {
811
811
  throw stoppedStateQLError(error, true);
812
812
  }
813
813
  throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), {
814
- retryable: true,
814
+ retryable: isTransientDatabaseError(error),
815
815
  executed: true,
816
816
  });
817
817
  }
@@ -902,7 +902,7 @@ export class StateQL {
902
902
  if (error instanceof AdapterExecutionError) {
903
903
  throw stoppedStateQLError(error, true);
904
904
  }
905
- throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), { retryable: true, executed: true });
905
+ throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), { retryable: isTransientDatabaseError(error), executed: true });
906
906
  }
907
907
  finally {
908
908
  await closeAdapterQuietly(adapter);
@@ -947,7 +947,7 @@ export class StateQL {
947
947
  throw error;
948
948
  if (error instanceof AdapterExecutionError)
949
949
  throw stoppedStateQLError(error, true);
950
- throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, source), { retryable: true, executed: true });
950
+ throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, source), { retryable: isTransientDatabaseError(error), executed: true });
951
951
  }
952
952
  finally {
953
953
  await closeAdapterQuietly(adapter);
@@ -1694,7 +1694,7 @@ export class StateQL {
1694
1694
  if (error instanceof AdapterExecutionError) {
1695
1695
  throw stoppedStateQLError(error, true);
1696
1696
  }
1697
- throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), { retryable: true, executed: true });
1697
+ throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), { retryable: isTransientDatabaseError(error), executed: true });
1698
1698
  }
1699
1699
  finally {
1700
1700
  await closeAdapterQuietly(adapter);
@@ -1759,7 +1759,7 @@ export class StateQL {
1759
1759
  if (error instanceof AdapterExecutionError) {
1760
1760
  throw stoppedStateQLError(error, true);
1761
1761
  }
1762
- throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), { retryable: true, executed: true });
1762
+ throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), { retryable: isTransientDatabaseError(error), executed: true });
1763
1763
  }
1764
1764
  finally {
1765
1765
  await closeAdapterQuietly(adapter);
@@ -1886,7 +1886,7 @@ export class StateQL {
1886
1886
  if (error instanceof AdapterExecutionError) {
1887
1887
  throw stoppedStateQLError(error, true);
1888
1888
  }
1889
- throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), { retryable: true, executed: true });
1889
+ throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), { retryable: isTransientDatabaseError(error), executed: true });
1890
1890
  }
1891
1891
  finally {
1892
1892
  await closeAdapterQuietly(adapter);
@@ -6,6 +6,7 @@ export declare function parseJson<T>(value: string, context: string, validate?:
6
6
  export declare function isSqlParameters(value: unknown): value is SqlParameters;
7
7
  export declare function isRows(value: unknown): value is Row[];
8
8
  export declare function isColumns(value: unknown): value is Column[];
9
+ export declare function isRecord(value: unknown): value is Record<string, unknown>;
9
10
  export declare function redact(value: string): string;
10
11
  export declare function compactRows(rows: Row[], maxCellCharacters: number): Row[];
11
12
  export declare function toJsonSafe<T>(value: T): T;
package/dist/src/util.js CHANGED
@@ -49,7 +49,7 @@ export function isColumns(value) {
49
49
  typeof column.name === "string" &&
50
50
  typeof column.type === "string");
51
51
  }
52
- function isRecord(value) {
52
+ export function isRecord(value) {
53
53
  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
54
54
  }
55
55
  function corruptedState(context) {
package/docs/agents.md ADDED
@@ -0,0 +1,72 @@
1
+ # Agent guide
2
+
3
+ [StateQL](../README.md) · [Agents](agents.md) · [Connections](connections.md) · [CLI](cli.md) · [Results](results.md) · [Writes](writes.md) · [Batch](batch.md) · [Databases](databases.md) · [Library](library.md)
4
+
5
+ The minimum an agent needs to query a database with `stql`. Read the other pages
6
+ only for the topic at hand.
7
+
8
+ ## Setup
9
+
10
+ ```bash
11
+ export STQL_SESSION=task-42 # keeps handles and aliases across calls
12
+ stql connect ./app.sqlite # read-only by default
13
+ stql connect --env DATABASE_URL # remote URL from an environment variable
14
+ ```
15
+
16
+ ## Read
17
+
18
+ ```bash
19
+ stql objects table --search user # find tables
20
+ stql object table users # table DDL
21
+ stql query "SELECT id, name FROM users WHERE status = ? ORDER BY id" --param active
22
+ ```
23
+
24
+ ```json
25
+ {"ok":true,"handle":"katcitg6un","total":333,"next_offset":5,"columns":["id","name"],"rows":[[2,"Ada"],[3,"Grace"],[5,"Linus"],[6,"Alan"],[8,"Edsger"]]}
26
+ ```
27
+
28
+ - Rows are arrays in `columns` order. If rows have different keys, they stay
29
+ objects and `columns` is omitted.
30
+ - `next_offset` is present only when more rows exist.
31
+ - Null fields and false `cached`/`duplicate` flags are omitted.
32
+ - Long cells come back as `{"type":"text","length":N,"preview":"..."}`.
33
+ - `objects` uses the same `columns` + arrays shape.
34
+ - `rows`, `count`, and `columns` do not repeat the handle you passed.
35
+ - Result handles are short, stable aliases. Full `q_...` IDs also work.
36
+ - Writes return `handle`, `statement_type`, `affected_rows`, `status`, and
37
+ `state_version_after`.
38
+
39
+ ## Reuse a result without querying again
40
+
41
+ ```bash
42
+ stql rows katcitg6un --offset 5 --limit 20
43
+ stql count katcitg6un
44
+ stql filter katcitg6un "name LIKE ?" --param "A%"
45
+ stql export katcitg6un --output users.csv
46
+ ```
47
+
48
+ ## Save tokens
49
+
50
+ - Select only the columns you need, and add `ORDER BY` and `LIMIT`.
51
+ - Use `--preview-rows 0` when you need only the handle and `total`.
52
+ - Use `stql pipe` to run several commands in one call:
53
+
54
+ ```bash
55
+ printf '%s\n' \
56
+ '{"command":"query","sql":"SELECT id, email FROM users ORDER BY id","as":"users"}' \
57
+ '{"command":"count","handle":"users"}' | stql pipe
58
+ ```
59
+
60
+ ## Errors
61
+
62
+ Errors are `{"ok":false,"error":{"code":...,"message":...}}`. Follow
63
+ `suggested_action` or `override_flag` when present. Retry only when
64
+ `retryable` is true (lost connection, deadlock, lock timeout). SQL syntax errors
65
+ give the line, column, and nearby text. Do not replay a write that
66
+ returned `OUTCOME_UNKNOWN` until you have checked the database.
67
+
68
+ ## Writes
69
+
70
+ Connect with `--read-write`. Use `stql exec` with `--idempotency-key KEY` for
71
+ retryable writes. Writes without `WHERE` need `--allow-unbounded`, and
72
+ destructive statements need `--allow-destructive`. See [write safety](writes.md).
package/docs/batch.md ADDED
@@ -0,0 +1,49 @@
1
+ # Batch and pipes
2
+
3
+ [StateQL](../README.md) · [Agents](agents.md) · [Connections](connections.md) · [CLI](cli.md) · [Results](results.md) · [Writes](writes.md) · [Batch](batch.md) · [Databases](databases.md) · [Library](library.md)
4
+
5
+ `batch` reads a JSON array from a `.json` file or JSONL from a `.jsonl` file.
6
+ `pipe` reads JSONL from standard input. Commands run sequentially and stop on
7
+ the first error unless `--continue-on-error` is set. Output defaults to one
8
+ compact `agent` JSON object per line.
9
+
10
+ Pipe commands directly:
11
+
12
+ ```bash
13
+ printf '%s\n' \
14
+ '{"command":"query","sql":"SELECT id, email FROM users ORDER BY id","as":"users"}' \
15
+ '{"command":"filter","handle":"users","where":"email LIKE ?","params":["%@example.com"],"as":"example_users"}' \
16
+ '{"command":"rows","handle":"example_users","limit":10}' |
17
+ stql pipe
18
+ ```
19
+
20
+ Or save a JSON array as `commands.json`:
21
+
22
+ ```json
23
+ [
24
+ {
25
+ "command": "exec",
26
+ "sql": "UPDATE jobs SET claimed = 1 WHERE id = ?",
27
+ "params": [42],
28
+ "idempotency_key": "claim-job-42"
29
+ },
30
+ {
31
+ "command": "query",
32
+ "sql": "SELECT * FROM jobs WHERE id = ?",
33
+ "params": [42]
34
+ }
35
+ ]
36
+ ```
37
+
38
+ ```bash
39
+ stql batch commands.json
40
+ ```
41
+
42
+ Batch fields use snake case. Supported command names match CLI paths, such as
43
+ `actor.show`, `actor.set-name`, `filter`, `transaction.begin`, `session.summary`,
44
+ `alias.set`, `plan`, and `apply`. `actor.set-name` takes the display name in the
45
+ `name` field. Query commands may set `preview_rows` from 0 to 200. Native MongoDB
46
+ batches use `mongo.query`, `mongo.exec`, or `mongo.plan` with the command object
47
+ in `mongo`; the same cache, replay, idempotency, safety, and timeout fields
48
+ apply. Database commands may set `timeout_ms`; otherwise they use the 30-second
49
+ default.