@fadhilp/stateql 0.16.0 → 0.18.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.
Files changed (51) hide show
  1. package/dist/src/adapters.d.ts +17 -25
  2. package/dist/src/adapters.js +15 -95
  3. package/dist/src/agent-response.js +6 -1
  4. package/dist/src/catalog.d.ts +6 -0
  5. package/dist/src/catalog.js +52 -0
  6. package/dist/src/cli.js +76 -25
  7. package/dist/src/connect.d.ts +16 -0
  8. package/dist/src/connect.js +205 -0
  9. package/dist/src/core.d.ts +78 -0
  10. package/dist/src/core.js +477 -0
  11. package/dist/src/execution.d.ts +27 -0
  12. package/dist/src/execution.js +87 -0
  13. package/dist/src/filter.js +3 -1
  14. package/dist/src/index.d.ts +1 -1
  15. package/dist/src/migrations.d.ts +1 -1
  16. package/dist/src/mongodb.d.ts +4 -2
  17. package/dist/src/mongodb.js +5 -56
  18. package/dist/src/panel.d.ts +64 -0
  19. package/dist/src/panel.js +316 -0
  20. package/dist/src/plans.d.ts +31 -0
  21. package/dist/src/plans.js +275 -0
  22. package/dist/src/reads.d.ts +35 -0
  23. package/dist/src/reads.js +184 -0
  24. package/dist/src/redis.d.ts +4 -2
  25. package/dist/src/redis.js +7 -33
  26. package/dist/src/response-data.d.ts +1 -0
  27. package/dist/src/response-data.js +13 -10
  28. package/dist/src/results.d.ts +10 -0
  29. package/dist/src/results.js +153 -0
  30. package/dist/src/sql.d.ts +7 -1
  31. package/dist/src/sql.js +88 -8
  32. package/dist/src/sqlite-process.js +16 -9
  33. package/dist/src/stateql.d.ts +9 -59
  34. package/dist/src/stateql.js +170 -2597
  35. package/dist/src/table-editor.js +2 -2
  36. package/dist/src/transactions.d.ts +8 -0
  37. package/dist/src/transactions.js +186 -0
  38. package/dist/src/types.d.ts +20 -18
  39. package/dist/src/util.d.ts +1 -0
  40. package/dist/src/util.js +1 -1
  41. package/dist/src/writes.d.ts +48 -0
  42. package/dist/src/writes.js +320 -0
  43. package/docs/batch.md +2 -1
  44. package/docs/cli.md +15 -9
  45. package/docs/databases.md +4 -3
  46. package/docs/library.md +3 -1
  47. package/docs/results.md +17 -0
  48. package/docs/writes.md +6 -0
  49. package/package.json +5 -3
  50. package/skills/stateql/SKILL.md +14 -6
  51. package/skills/stateql/reference/writes.md +4 -1
@@ -0,0 +1,320 @@
1
+ import { databaseIdentity, version } from "./connection.js";
2
+ import { adapterOfKind, closeAdapterQuietly, errorMessage, safeCredentialErrorMessage, } from "./core.js";
3
+ import { StateQLError } from "./errors.js";
4
+ import { AdapterExecutionError, AdapterWriteError, BatchWriteError, stoppedStateQLError, } from "./execution.js";
5
+ import { analyzeMongoWriteSafety, deserializeMongoWriteCommand, serializeMongoCommand, validateMongoWriteCommand, } from "./mongodb.js";
6
+ import { invalidCommand, mongoDescriptor, redisDescriptor, sqlParametersLength, } from "./reads.js";
7
+ import { serializeRedisCommand, validateRedisWriteCommand, } from "./redis.js";
8
+ import { operationData } from "./response-data.js";
9
+ import { analyzeSql } from "./sql.js";
10
+ import { hash } from "./util.js";
11
+ const REPLAY_ACTION = "Inspect database state, then use --replay only if another execution is safe.";
12
+ const FINALIZE_ACTION = "Inspect database state before issuing any replacement write.";
13
+ export function prepareSqlWrite(connection, sql, parameters, safety) {
14
+ const analysis = analyzeSql(sql, connection.driver);
15
+ if (analysis.read) {
16
+ throw new StateQLError("INVALID_SQL", "exec accepts write statements only; use query for reads.");
17
+ }
18
+ rejectUnsafeWrite(analysis.unboundedMutation, analysis.destructive, safety, "Mutation has no WHERE clause.", "Destructive operation requires an explicit override.");
19
+ const autocommitHasInputs = safety.expectedRows !== undefined || sqlParametersLength(parameters) > 0;
20
+ if (analysis.requiresAutocommit && autocommitHasInputs) {
21
+ throw new StateQLError("INVALID_SQL", "Autocommit maintenance statements do not accept StateQL parameters or row-count preconditions.");
22
+ }
23
+ const statementName = analysis.statementType.toUpperCase();
24
+ return {
25
+ descriptor: sql,
26
+ parameters,
27
+ statementType: analysis.statementType,
28
+ fingerprint: hash({
29
+ sql: analysis.normalized,
30
+ parameters,
31
+ database: databaseIdentity(connection),
32
+ }),
33
+ ...(analysis.requiresAutocommit
34
+ ? { stagingError: `${statementName} cannot be staged in a transaction.` }
35
+ : {}),
36
+ conflictMessage: "The row changed or no longer matches. Reload before editing.",
37
+ unknownAction: REPLAY_ACTION,
38
+ async execute(adapter) {
39
+ const sqlAdapter = adapterOfKind(adapter, "sql");
40
+ if (!analysis.requiresAutocommit)
41
+ return sqlAdapter.write(sql, parameters, safety.expectedRows);
42
+ if (!sqlAdapter.writeAutocommit) {
43
+ throw new AdapterWriteError(`${statementName} requires adapter autocommit execution.`, false);
44
+ }
45
+ return sqlAdapter.writeAutocommit(sql, parameters);
46
+ },
47
+ };
48
+ }
49
+ export function prepareMongoWrite(connection, command, safety) {
50
+ const value = invalidCommand(() => validateMongoWriteCommand(command));
51
+ const unsafe = analyzeMongoWriteSafety(value);
52
+ rejectUnsafeWrite(unsafe.unbounded, unsafe.destructive, safety, "MongoDB mutation has an empty filter.", "Destructive MongoDB operation requires an explicit override.");
53
+ const serialized = serializeMongoCommand(value);
54
+ return {
55
+ descriptor: mongoDescriptor(value.operation),
56
+ parameters: [serialized],
57
+ statementType: `mongo.${value.operation}`,
58
+ fingerprint: hash({ command: serialized, database: databaseIdentity(connection) }),
59
+ conflictMessage: "The document changed or was removed. Reload before editing.",
60
+ unknownAction: REPLAY_ACTION,
61
+ execute: (adapter) => adapterOfKind(adapter, "mongodb").write(value, safety.expectedRows),
62
+ };
63
+ }
64
+ export function prepareRedisWrite(connection, command, precondition) {
65
+ const value = invalidCommand(() => validateRedisWriteCommand(command));
66
+ const serialized = serializeRedisCommand(value);
67
+ return {
68
+ descriptor: redisDescriptor(value.command),
69
+ parameters: [serialized],
70
+ statementType: `redis.${value.command.toLowerCase()}`,
71
+ fingerprint: hash({ command: serialized, database: databaseIdentity(connection) }),
72
+ stagingError: "Redis writes cannot be staged in a transaction.",
73
+ conflictMessage: "The Redis key changed. Reload and plan again.",
74
+ unknownAction: "Inspect Redis state before issuing a replacement write.",
75
+ execute: (adapter) => adapterOfKind(adapter, "redis").write(value, precondition),
76
+ };
77
+ }
78
+ export function prepareTableBatch(connection, planId, updates, compiled) {
79
+ if (connection.driver === "redis") {
80
+ throw new StateQLError("UNSUPPORTED_DRIVER", "Redis does not support table edit batches.");
81
+ }
82
+ const mongoCommands = connection.driver === "mongodb"
83
+ ? compiled.map((item) => {
84
+ if (!item.mongo)
85
+ throw new StateQLError("STALE_PLAN", "Table edit batch contains mixed drivers.");
86
+ return item.mongo;
87
+ })
88
+ : undefined;
89
+ return {
90
+ descriptor: `Conditional table update batch (${updates.length} rows)`,
91
+ parameters: [JSON.stringify({ version: 1, updates })],
92
+ statementType: "table.updates",
93
+ fingerprint: hash({ plan: planId, updates }),
94
+ stagingError: "Table edit batches cannot be staged in a transaction.",
95
+ conflictMessage: "At least one row changed; the entire edit batch was rolled back.",
96
+ unknownAction: "Inspect every edited row before retrying.",
97
+ async execute(adapter, operation) {
98
+ const results = mongoCommands
99
+ ? await adapterOfKind(adapter, "mongodb").writeBatch(mongoCommands, "snapshot", true)
100
+ : await adapterOfKind(adapter, "sql").writeBatch(compiled.map((item, index) => ({
101
+ ...operation,
102
+ id: `${operation.id}:${index}`,
103
+ sql: item.sql,
104
+ parameters: JSON.stringify(item.params),
105
+ statement_type: "update",
106
+ expectedRows: 1,
107
+ })), "serializable");
108
+ return { affectedRows: results.reduce((sum, item) => sum + item.affectedRows, 0) };
109
+ },
110
+ };
111
+ }
112
+ /** Reserves the write, stages it or runs it once, and records a definite or unknown outcome. */
113
+ export async function runWrite(core, session, connection, statement, options, context, claim) {
114
+ if (options.idempotencyKey !== undefined && !options.idempotencyKey.trim()) {
115
+ throw new StateQLError("INVALID_COMMAND", "Idempotency key cannot be empty.");
116
+ }
117
+ const transactionId = session.active_transaction_id ?? undefined;
118
+ if (transactionId)
119
+ requireStagingTransaction(core, session, connection, statement, transactionId);
120
+ const reservation = core.store.reserveOperation({
121
+ sessionId: session.id,
122
+ actorId: core.actorId,
123
+ connectionId: connection.id,
124
+ fingerprint: statement.fingerprint,
125
+ sql: statement.descriptor,
126
+ parameters: statement.parameters,
127
+ statementType: statement.statementType,
128
+ status: transactionId ? "pending" : "executing",
129
+ transactionId,
130
+ replay: options.replay ?? false,
131
+ idempotencyKey: options.idempotencyKey,
132
+ stateVersionBefore: version(connection),
133
+ });
134
+ if (reservation.denied)
135
+ throw reservationDenied(core, session, reservation.denied);
136
+ const previous = reservation.previous;
137
+ const keyReused = previous !== undefined &&
138
+ options.idempotencyKey !== undefined &&
139
+ !options.replay &&
140
+ previous.fingerprint !== statement.fingerprint;
141
+ if (keyReused) {
142
+ throw new StateQLError("IDEMPOTENCY_CONFLICT", "Idempotency key was already used for a different write.", { extra: { previous_operation_id: previous.id } });
143
+ }
144
+ if (!reservation.operation)
145
+ return duplicateWrite(previous, options.idempotencyKey);
146
+ const operation = reservation.operation;
147
+ if (transactionId) {
148
+ return {
149
+ data: operationData(operation),
150
+ handle: operation.id,
151
+ executed: false,
152
+ stateVersion: version(connection),
153
+ };
154
+ }
155
+ let adapter;
156
+ let source;
157
+ try {
158
+ source = claim?.source ??
159
+ await core.resolveConnectionSource(connection, session, "exec", "write", context);
160
+ adapter = await core.openAdapter(connection, context, source);
161
+ }
162
+ catch (error) {
163
+ core.store.failOperation(operation.id);
164
+ if (error instanceof StateQLError)
165
+ throw error;
166
+ throw new StateQLError("CONNECTION_FAILED", "Database connection failed.", { retryable: true });
167
+ }
168
+ try {
169
+ const write = await statement.execute(adapter, operation);
170
+ const finalized = finishWrite(core, connection, operation, write, claim);
171
+ return {
172
+ data: {
173
+ ...operationData(finalized.operation),
174
+ duplicate: Boolean(previous),
175
+ duplicate_override: Boolean(previous),
176
+ },
177
+ handle: finalized.operation.id,
178
+ executed: true,
179
+ stateVersion: finalized.stateVersion,
180
+ confidence: adapter.confidence,
181
+ };
182
+ }
183
+ catch (error) {
184
+ throw writeFailure(core, operation, statement, error, source);
185
+ }
186
+ finally {
187
+ await closeAdapterQuietly(adapter);
188
+ }
189
+ }
190
+ function rejectUnsafeWrite(unbounded, destructive, safety, unboundedMessage, destructiveMessage) {
191
+ if (unbounded && !safety.allowUnbounded) {
192
+ throw new StateQLError("UNBOUNDED_MUTATION", unboundedMessage, {
193
+ extra: { override_flag: "--allow-unbounded" },
194
+ });
195
+ }
196
+ if (destructive && !safety.allowDestructive) {
197
+ throw new StateQLError("DESTRUCTIVE_OPERATION_BLOCKED", destructiveMessage, {
198
+ extra: { override_flag: "--allow-destructive" },
199
+ });
200
+ }
201
+ }
202
+ function requireStagingTransaction(core, session, connection, statement, transactionId) {
203
+ if (statement.stagingError) {
204
+ throw new StateQLError("TRANSACTION_FAILED", statement.stagingError, {
205
+ suggestedAction: "Roll back or commit the staged transaction, then run this statement separately.",
206
+ });
207
+ }
208
+ const transaction = core.store.getTransaction(transactionId);
209
+ const matches = transaction !== undefined &&
210
+ transaction.session_id === session.id &&
211
+ transaction.state === "active" &&
212
+ transaction.connection_id === connection.id;
213
+ if (!matches) {
214
+ throw new StateQLError("TRANSACTION_FAILED", "Active transaction does not match the active connection.");
215
+ }
216
+ if (transaction.owner_actor_id !== core.actorId) {
217
+ throw new StateQLError("PERMISSION_DENIED", "Only the transaction owner may stage writes.");
218
+ }
219
+ }
220
+ function reservationDenied(core, session, denied) {
221
+ if (denied === "membership") {
222
+ return new StateQLError("PERMISSION_DENIED", "Actor membership changed before the write was reserved.");
223
+ }
224
+ const active = core.store.getSession(session.id)?.active_transaction_id;
225
+ const transaction = active ? core.store.getTransaction(active) : undefined;
226
+ if (transaction && transaction.owner_actor_id !== core.actorId) {
227
+ return new StateQLError("PERMISSION_DENIED", "Only the transaction owner may stage writes.");
228
+ }
229
+ return new StateQLError("TRANSACTION_FAILED", "The active transaction changed before the write was reserved.");
230
+ }
231
+ function duplicateWrite(previous, idempotencyKey) {
232
+ if (previous.status === "executing" || previous.status === "outcome_unknown") {
233
+ throw new StateQLError("OUTCOME_UNKNOWN", "A matching write has an unknown outcome.", {
234
+ executed: true,
235
+ suggestedAction: REPLAY_ACTION,
236
+ extra: { previous_operation_id: previous.id },
237
+ });
238
+ }
239
+ if (!idempotencyKey) {
240
+ throw new StateQLError("POTENTIAL_DUPLICATE_WRITE", "An equivalent operation was previously applied.", { extra: { previous_operation_id: previous.id, replay_required: true } });
241
+ }
242
+ return {
243
+ data: {
244
+ ...operationData(previous),
245
+ duplicate: true,
246
+ duplicate_of: previous.id,
247
+ idempotency_key: idempotencyKey,
248
+ },
249
+ handle: previous.id,
250
+ cached: true,
251
+ stateVersion: previous.state_version_after ?? previous.state_version_before,
252
+ };
253
+ }
254
+ function finishWrite(core, connection, operation, write, claim) {
255
+ try {
256
+ if (claim) {
257
+ return core.store.finishPlannedOperation({
258
+ planId: claim.planId,
259
+ claimToken: claim.claimToken,
260
+ operationId: operation.id,
261
+ connectionId: connection.id,
262
+ affectedRows: write.affectedRows,
263
+ outcome: write.outcome,
264
+ });
265
+ }
266
+ const stateVersion = core.store.bumpVersion(connection.id);
267
+ return {
268
+ operation: core.store.finishOperation(operation.id, write.affectedRows, stateVersion, write.outcome),
269
+ stateVersion,
270
+ };
271
+ }
272
+ catch (error) {
273
+ core.store.markOperationOutcomeUnknown(operation.id);
274
+ throw new StateQLError("OUTCOME_UNKNOWN", errorMessage(error), {
275
+ executed: true,
276
+ suggestedAction: FINALIZE_ACTION,
277
+ });
278
+ }
279
+ }
280
+ function writeFailure(core, operation, statement, error, source) {
281
+ if (error instanceof StateQLError)
282
+ return error;
283
+ const definite = (error instanceof AdapterExecutionError ||
284
+ error instanceof AdapterWriteError ||
285
+ error instanceof BatchWriteError) &&
286
+ !error.outcomeUnknown;
287
+ if (!definite) {
288
+ core.store.markOperationOutcomeUnknown(operation.id);
289
+ return new StateQLError("OUTCOME_UNKNOWN", safeCredentialErrorMessage(error, source), { executed: true, suggestedAction: statement.unknownAction });
290
+ }
291
+ core.store.failOperation(operation.id);
292
+ if (error.message.startsWith("ROW_CONFLICT:")) {
293
+ return new StateQLError("ROW_CONFLICT", statement.conflictMessage);
294
+ }
295
+ if (error instanceof AdapterExecutionError)
296
+ return stoppedStateQLError(error, false);
297
+ return new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, source), { executed: true });
298
+ }
299
+ export function storedMongoOperation(operation) {
300
+ if (!operation.statement_type.startsWith("mongo.")) {
301
+ throw new StateQLError("TRANSACTION_FAILED", "MongoDB transaction contains a mixed or corrupt native payload.");
302
+ }
303
+ return storedMongoWrite(operation.parameters, operation.statement_type, `operation "${operation.id}"`, "TRANSACTION_FAILED");
304
+ }
305
+ export function storedMongoWrite(parameters, statementType, label, errorCode) {
306
+ try {
307
+ const payload = JSON.parse(parameters);
308
+ if (!Array.isArray(payload) || payload.length !== 1 || typeof payload[0] !== "string") {
309
+ throw new Error("payload must contain one EJSON command string");
310
+ }
311
+ const command = deserializeMongoWriteCommand(payload[0]);
312
+ if (statementType !== `mongo.${command.operation}`) {
313
+ throw new Error("operation does not match its statement type");
314
+ }
315
+ return command;
316
+ }
317
+ catch {
318
+ throw new StateQLError(errorCode, `Stored MongoDB ${label} payload is invalid.`);
319
+ }
320
+ }
package/docs/batch.md CHANGED
@@ -42,7 +42,8 @@ stql batch commands.json
42
42
  Batch fields use snake case. Supported command names match CLI paths, such as
43
43
  `actor.show`, `actor.set-name`, `filter`, `transaction.begin`, `session.summary`,
44
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
45
+ `name` field. Query commands may set `preview_rows` from 0 to 200. `rows` may
46
+ set `columns` to an array of column names; `summarize` takes `handle`. Native MongoDB
46
47
  batches use `mongo.query`, `mongo.exec`, or `mongo.plan` with the command object
47
48
  in `mongo`; the same cache, replay, idempotency, safety, and timeout fields
48
49
  apply. Database commands may set `timeout_ms`; otherwise they use the 30-second
package/docs/cli.md CHANGED
@@ -15,25 +15,25 @@ stql profile add|update NAME [TARGET [--ask-password] | --env ENV | --credential
15
15
  [--read-only|--read-write]
16
16
  stql profile list|show|remove
17
17
  stql session start|list|show|summary|close
18
- stql query <sql> [--params JSON | --param VALUE...] [--cache auto|bypass|require]
18
+ stql query <sql> | --file FILE [--params JSON | --param VALUE...] [--cache auto|bypass|require]
19
19
  [--preview-rows 0..200]
20
20
  stql filter <result-handle> <predicate> [--params JSON | --param VALUE...]
21
- stql exec <sql> [--params JSON | --param VALUE...] [--idempotency-key KEY] [--replay]
21
+ stql exec <sql> | --file FILE [--params JSON | --param VALUE...] [--idempotency-key KEY] [--replay]
22
22
  [--allow-unbounded] [--allow-destructive]
23
- stql mongo query|exec|plan '<EJSON command>' [--cache MODE] [--idempotency-key KEY]
23
+ stql mongo query|exec|plan '<EJSON command>' | --file FILE [--cache MODE] [--idempotency-key KEY]
24
24
  [--replay] [--allow-unbounded] [--allow-destructive]
25
25
  stql redis query '<JSON command>' [--cache auto|bypass|require]
26
26
  stql redis exec '<JSON command>' [--idempotency-key KEY] [--replay]
27
27
  stql redis plan '<JSON command>'
28
- stql show|count|columns <result-handle>
29
- stql rows <result-handle> [--offset N] [--limit N]
28
+ stql show|count|columns|summarize <result-handle>
29
+ stql rows <result-handle> [--offset N] [--limit N] [--columns a,b]
30
30
  stql alias set <name> <result-handle>
31
- stql export <result-handle> --output FILE [--format json|jsonl|csv]
31
+ stql export <result-handle> --output FILE [--format json|jsonl|csv] [--columns a,b]
32
32
  stql inspect schema|table|collection|collections|columns|indexes|constraints [name]
33
33
  stql objects [KIND] [--schema NAME] [--search TEXT] [--offset N|--cursor CURSOR] [--limit N]
34
34
  stql object KIND NAME [IDENTITY] [--schema NAME]
35
35
  stql transaction begin|status|commit|rollback [--isolation LEVEL]
36
- stql plan <sql> [--params JSON | --param VALUE...] [--allow-unbounded] [--allow-destructive]
36
+ stql plan <sql> | --file FILE [--params JSON | --param VALUE...] [--allow-unbounded] [--allow-destructive]
37
37
  stql apply <plan-handle>
38
38
  stql history [--limit N] [--offset N] [--category statement|introspection|management]
39
39
  [--internal|--external]
@@ -43,7 +43,7 @@ stql purge [expired|results|history|all]
43
43
  stql capabilities
44
44
  stql batch [commands.json|commands.jsonl|-] [--continue-on-error]
45
45
  stql pipe [--continue-on-error]
46
- stql help
46
+ stql help [command]
47
47
  ```
48
48
 
49
49
  Global options: `--output MODE`, `--timeout-ms N`, `--max-cell-characters N`,
@@ -63,6 +63,10 @@ Use `--params JSON` for a JSON array or named parameters. Use
63
63
  `--params-file FILE` when JSON is awkward to quote; `--params-file -` reads
64
64
  JSON from standard input.
65
65
 
66
+ Use `--file FILE` instead of inline text to read the SQL, or the MongoDB or
67
+ Redis command, from a file. `--file -` reads standard input, so it cannot be
68
+ combined with `--params-file -`. A leading UTF-8 BOM is ignored.
69
+
66
70
  ## Catalog inspection
67
71
 
68
72
  Use `objects` to list a bounded page and `object` to describe an entry:
@@ -98,6 +102,8 @@ their complete error object. Empty warnings and tracing metadata are omitted.
98
102
 
99
103
  Agent mode also removes data that costs tokens but adds no information:
100
104
 
105
+ - `summarize` returns `columns` (`name`, `nulls`, `distinct`, `min`, `max`) and
106
+ one row per result column.
101
107
  - `query`, `filter`, `show`, `mongo.query`, and `rows` return `columns` once and
102
108
  each row as an array in that order. When rows have different keys (for
103
109
  example, MongoDB documents), rows stay objects and `columns` is omitted.
@@ -110,7 +116,7 @@ Agent mode also removes data that costs tokens but adds no information:
110
116
  - `capabilities` lists enabled `features` as names.
111
117
  - `objects` returns `columns` once and each entry as an array. `identity` is
112
118
  omitted when it equals `schema.name` (or `name`) for every entry.
113
- - `rows`, `count`, and `columns` do not repeat the handle you passed.
119
+ - `rows`, `count`, `columns`, and `summarize` do not repeat the handle you passed.
114
120
  - Result `handle` is the generated alias, which cannot be reassigned. Full
115
121
  `q_...` IDs work too and appear in `--output json`, `silent`, and history.
116
122
  `alias` is present only when you chose a different name (batch `as`).
package/docs/databases.md CHANGED
@@ -17,7 +17,8 @@ covered under [write safety](writes.md).
17
17
  ## Driver notes
18
18
 
19
19
  - **SQLite:** use a filesystem path for direct connections or `sqlite:` for an
20
- environment-backed path.
20
+ environment-backed path. Reads run with `PRAGMA query_only`, also on
21
+ read-write connections, so a read cannot change the database.
21
22
  - **PostgreSQL:** StateQL preserves strict TLS verification by normalizing
22
23
  `sslmode=prefer`, `require`, and `verify-ca` to `verify-full` before opening
23
24
  the adapter. Use `sslmode=verify-full` explicitly for clarity. Setting
@@ -95,8 +96,8 @@ stql plan "REINDEX TABLE public.jobs" --allow-destructive
95
96
 
96
97
  The PostgreSQL 14–18 grammar includes parenthesized `REINDEX CONCURRENTLY`,
97
98
  PostgreSQL 16 `BUFFER_USAGE_LIMIT` for `VACUUM`/`ANALYZE`, optional
98
- `DATABASE`/`SYSTEM` reindex names, and PostgreSQL 18 `ONLY table *` maintenance
99
- targets. Memory sizes accept an integer number of kilobytes or a quoted
99
+ `DATABASE`/`SYSTEM` reindex names, and PostgreSQL 18 `ONLY table` and `table *`
100
+ maintenance targets (not both on one table). Memory sizes accept an integer number of kilobytes or a quoted
100
101
  `B|kB|MB|GB|TB` value. Older servers may reject newer forms after dispatch, so
101
102
  StateQL retains conservative unknown-outcome handling.
102
103
 
package/docs/library.md CHANGED
@@ -63,7 +63,9 @@ Library responses retain the full response envelope regardless of the CLI
63
63
  output mode. Check `response.ok` before reading `response.data`; failures expose
64
64
  `response.error`. Queries return typed `ResultData` with `result_id`, `preview`,
65
65
  and result metadata. Reuse `result_id` with methods such as `filter`, `rows`,
66
- `count`, and `exportResult`; the CLI instead presents its primary ID as `handle`.
66
+ `count`, `summarize`, and `exportResult`; the CLI instead presents its primary ID as `handle`.
67
+ `rows(id, { columns })` and `exportResult(id, output, format, columns)` return
68
+ only the named columns.
67
69
  Queries preview five rows by default. Set `previewRows` from 0 to 200 on an
68
70
  individual query to control its response without changing or rerunning the
69
71
  materialized result. The constructor-level `previewRows` option changes the
package/docs/results.md CHANGED
@@ -67,6 +67,23 @@ use `results`, `history`, or `all` for explicit session cleanup. On POSIX
67
67
  systems, StateQL removes group and world access from its state directory,
68
68
  database, and SQLite sidecar files.
69
69
 
70
+ ## Column projection and summaries
71
+
72
+ `rows` and `export` accept `--columns a,b` (library: `columns: ["a", "b"]`) to
73
+ return only those columns, in that order. Unknown column names fail with
74
+ `INVALID_COMMAND` and a list of the available columns.
75
+
76
+ CSV exports put a `'` before text cells that start with `=`, `+`, `-`, or `@`
77
+ (after optional spaces or control characters), or with a tab or line break.
78
+ Spreadsheets then show these cells as text and do not run them as formulas.
79
+ Number values are not changed.
80
+
81
+ `summarize` returns, for each column of a stored result, the null count, the
82
+ distinct count, and the min and max. Min and max are computed only when all
83
+ non-null values are numbers or all are strings. Numeric strings, such as
84
+ PostgreSQL `numeric` values, compare as numbers. Neither command accesses the
85
+ original database.
86
+
70
87
  ## Local filtering
71
88
 
72
89
  `filter` evaluates one scalar SQLite predicate against a stored result. It
package/docs/writes.md CHANGED
@@ -10,6 +10,12 @@ The flags are independent.
10
10
  the flags explicitly supplied when it is created; `apply` never adds
11
11
  authorization.
12
12
 
13
+ For a single-table SQL `UPDATE` or `DELETE` without `ORDER BY` or `LIMIT`,
14
+ `plan` also returns `estimated_rows`: a `COUNT(*)` of the rows that the `WHERE`
15
+ clause matches at plan time. The field is absent for other statements, or when
16
+ the count cannot be derived. Data can change before `apply`, so treat it as an
17
+ estimate; `affected_rows` on `apply` is the real value.
18
+
13
19
  Use an idempotency key to protect retryable writes from duplicate execution:
14
20
 
15
21
  ```bash
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fadhilp/stateql",
3
- "version": "0.16.0",
3
+ "version": "0.18.0",
4
4
  "description": "Stateful, agent-oriented database CLI for safe result reuse",
5
5
  "repository": {
6
6
  "type": "git",
@@ -26,8 +26,9 @@
26
26
  "LICENSE"
27
27
  ],
28
28
  "scripts": {
29
- "build": "tsc -p tsconfig.json",
30
- "test": "npm run build && node --test dist/test/cli.test.js dist/test/credential.test.js dist/test/import.test.js dist/test/mongodb.test.js dist/test/mysql.test.js dist/test/postgres.test.js dist/test/query.test.js dist/test/redis.test.js dist/test/sqlite.test.js dist/test/store.test.js dist/test/terminal.test.js dist/test/transaction.test.js dist/test/write.test.js dist/test/panel.test.js",
29
+ "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.json",
30
+ "test": "npm run build && node --test \"dist/test/*.test.js\"",
31
+ "lint": "biome lint",
31
32
  "release": "npm version",
32
33
  "version": "npm install",
33
34
  "prepack": "npm test"
@@ -56,6 +57,7 @@
56
57
  "pg": "^8.16.3"
57
58
  },
58
59
  "devDependencies": {
60
+ "@biomejs/biome": "2.5.15",
59
61
  "@types/node": "^24.0.0",
60
62
  "@types/pg": "^8.15.5",
61
63
  "node-pty": "^1.1.0",
@@ -51,14 +51,18 @@ shows saved profiles.
51
51
  4. Read the response (see below). `total` is the full row count, so you do not
52
52
  need a separate `COUNT(*)`.
53
53
  5. More rows: `stql rows <handle> --offset <next_offset> --limit 50`
54
- (default 20, maximum 1000).
54
+ (default 20, maximum 1000). Add `--columns id,email` to return only some
55
+ columns of a wide result.
56
+ To understand the data, run `stql summarize <handle>`: for each column it
57
+ returns the null count, distinct count, min, and max.
55
58
  6. Narrow down: `stql filter <handle> 'CAST(total AS REAL) > ?' --param 100`.
56
59
  This runs locally on the stored rows in SQLite syntax, always with `?`, and
57
60
  returns a new handle. PostgreSQL `numeric`/`bigint` and MySQL `DECIMAL` values
58
61
  are stored as strings (`"7.50"`), and SQLite treats every string as greater
59
62
  than every number, so `total > ?` silently matches all rows. Wrap such
60
63
  columns in `CAST(... AS REAL)`, or filter in SQL with a new query.
61
- 7. Save all rows: `stql export <handle> --output rows.csv` (`--format json|jsonl|csv`).
64
+ 7. Save all rows: `stql export <handle> --output rows.csv` (`--format json|jsonl|csv`,
65
+ optional `--columns`).
62
66
 
63
67
  Use `--preview-rows N` (0 to 200) on `query` to change the preview size. Use
64
68
  `--cache bypass` when data may have changed outside this session; writes made
@@ -72,7 +76,7 @@ through `stql` invalidate the cache automatically.
72
76
 
73
77
  | Field | Meaning |
74
78
  | --- | --- |
75
- | `handle` | Stable result handle. Pass it to `rows`, `filter`, `count`, `columns`, `show`, `export`. |
79
+ | `handle` | Stable result handle. Pass it to `rows`, `filter`, `count`, `columns`, `summarize`, `show`, `export`. |
76
80
  | `columns` + `rows` | Each row is an array in `columns` order. If rows have different keys (MongoDB documents), rows are objects and `columns` is absent. |
77
81
  | `total` | Rows in the stored result. |
78
82
  | `next_offset` | Present only when more rows exist. Absent means you have every row. |
@@ -96,12 +100,16 @@ through `stql` invalidate the cache automatically.
96
100
 
97
101
  - Put SQL in single quotes. In bash and PowerShell, `"$1"` expands to an empty
98
102
  string and breaks the query.
103
+ - For long SQL, or SQL with quotes, write it to a file and pass
104
+ `--file query.sql` instead of the inline SQL. `--file -` reads standard input.
105
+ This works for `query`, `exec`, `plan`, `stql mongo`, and `stql redis`.
99
106
  - Use parameters instead of string literals, so you do not need quotes inside
100
107
  quotes: `--param 'Ada Lovelace'`.
101
108
  - **Windows PowerShell 5.1** removes the double quotes inside JSON arguments, so
102
109
  `--params '[1]'` is fine but `stql redis query '{"command":"GET"}'` breaks.
103
- Send JSON on standard input instead: `'<one JSON command>' | stql pipe` (see
104
- below), or escape every inner quote as `\"`.
110
+ Send the JSON on standard input instead:
111
+ `'{"command":"GET","args":["a"]}' | stql redis query --file -`, or
112
+ `'<one JSON command>' | stql pipe` (see below).
105
113
 
106
114
  ## Several steps in one call
107
115
 
@@ -168,4 +176,4 @@ before you use `stql mongo` or `stql redis`.
168
176
  | `stql history --limit 10` | Recent commands in this session |
169
177
  | `stql receipt <operation-handle>` | Full record of a write |
170
178
  | `stql session summary` | Open results and recent writes |
171
- | `stql help` | Command syntax |
179
+ | `stql help <command>` | Syntax of one command (`stql help` lists all) |
@@ -43,10 +43,13 @@ Use a plan when the user should review a write before it runs.
43
43
 
44
44
  ```bash
45
45
  stql plan 'DELETE FROM sessions WHERE expires_at < $1' --param 2026-01-01 --allow-destructive
46
- # show the user statement_type, required_overrides, and expires_at
46
+ # show the user statement_type, estimated_rows, required_overrides, and expires_at
47
47
  stql apply <plan-handle>
48
48
  ```
49
49
 
50
+ - `estimated_rows` is the number of rows the `WHERE` clause matched when the
51
+ plan was made. It is present only for single-table `UPDATE` and `DELETE`
52
+ without `ORDER BY`/`LIMIT`. If it is absent, count the rows with a query.
50
53
  - A plan keeps only the approval flags given to `plan`; `apply` never adds any.
51
54
  - If data changed after `plan`, `apply` returns `STALE_PLAN`. Create a new plan.
52
55
  - Plans expire after 10 minutes.