@fadhilp/stateql 0.13.1 → 0.13.2

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/dist/src/cli.js CHANGED
@@ -20,6 +20,7 @@ const parsed = parseArgs({
20
20
  param: { type: "string", multiple: true },
21
21
  "params-file": { type: "string" },
22
22
  cache: { type: "string" },
23
+ "preview-rows": { type: "string" },
23
24
  replay: { type: "boolean" },
24
25
  "idempotency-key": { type: "string" },
25
26
  "allow-unbounded": { type: "boolean" },
@@ -175,6 +176,9 @@ async function dispatch() {
175
176
  return stateql.query(sql, {
176
177
  params,
177
178
  cache: cacheMode(values.cache),
179
+ ...(values["preview-rows"] === undefined
180
+ ? {}
181
+ : { previewRows: Number(values["preview-rows"]) }),
178
182
  });
179
183
  case "filter":
180
184
  return stateql.filter(requireValue(subcommand, "result handle"), requireValue(rest.join(" ").trim(), "filter predicate"), { params });
@@ -656,6 +660,7 @@ Commands:
656
660
  pipe
657
661
 
658
662
  SQL parameters: --params JSON, repeated --param VALUE, or --params-file FILE.
663
+ Query preview: --preview-rows N (default: 5, maximum: 200).
659
664
  Deadline: --timeout-ms N (default: 30000). Ctrl+C cancels database work.
660
665
  Credential refs require a trusted host CredentialResolver; the standalone CLI cannot resolve them.
661
666
  State: --max-state-bytes N, --cache-ttl-seconds N, --result-ttl-seconds N.
@@ -665,6 +665,9 @@ export class StateQL {
665
665
  }
666
666
  async query(sql, options = {}) {
667
667
  return this.run("query", async (session) => {
668
+ const previewRows = options.previewRows === undefined
669
+ ? this.previewRows
670
+ : queryPreviewRows(options.previewRows);
668
671
  const connection = this.requireConnection(session);
669
672
  this.rejectMongoSql(connection, "mongoQuery");
670
673
  this.rejectDuringStagedTransaction(session, "Queries");
@@ -705,7 +708,7 @@ export class StateQL {
705
708
  cached.row_count <= this.maxResultRows &&
706
709
  this.cacheValid(cached, stateVersion, stateSignature)) {
707
710
  return {
708
- data: this.resultData(cached, true),
711
+ data: this.resultData(cached, true, previewRows),
709
712
  handle: cached.id,
710
713
  cached: true,
711
714
  warnings: paginationWarnings(analysis.ordered),
@@ -752,7 +755,7 @@ export class StateQL {
752
755
  expiresAt,
753
756
  });
754
757
  return {
755
- data: this.resultData(saved, false),
758
+ data: this.resultData(saved, false, previewRows),
756
759
  handle: saved.id,
757
760
  executed: true,
758
761
  warnings: paginationWarnings(analysis.ordered),
@@ -2027,6 +2030,7 @@ export class StateQL {
2027
2030
  const response = await this.query(batchString(command.sql, "sql"), {
2028
2031
  params: command.params ?? [],
2029
2032
  cache: command.cache ?? "auto",
2033
+ previewRows: command.preview_rows,
2030
2034
  timeoutMs: command.timeout_ms,
2031
2035
  });
2032
2036
  if (!response.ok || !command.as)
@@ -2931,9 +2935,9 @@ export class StateQL {
2931
2935
  executionContext(options) {
2932
2936
  return createAdapterContext(executionTimeout(options.timeoutMs ?? this.timeoutMs), combineAbortSignals(options.signal, this.commandContexts.getStore()?.signal, this.signal));
2933
2937
  }
2934
- resultData(result, cached) {
2938
+ resultData(result, cached, previewRows = this.previewRows) {
2935
2939
  const rows = this.store.resultRows(result);
2936
- const preview = compactRows(rows.slice(0, this.previewRows), this.maxCellCharacters);
2940
+ const preview = compactRows(rows.slice(0, previewRows), this.maxCellCharacters);
2937
2941
  return {
2938
2942
  result_id: result.id,
2939
2943
  alias: result.alias ?? this.store.generatedAlias(result.id),
@@ -3286,6 +3290,12 @@ function nonNegativeInteger(value, name) {
3286
3290
  return value;
3287
3291
  throw new StateQLError("INVALID_COMMAND", `${name} must be a non-negative integer.`);
3288
3292
  }
3293
+ function queryPreviewRows(value) {
3294
+ const previewRows = nonNegativeInteger(value, "previewRows");
3295
+ if (previewRows <= 200)
3296
+ return previewRows;
3297
+ throw new StateQLError("OUTPUT_LIMIT_EXCEEDED", "previewRows cannot exceed 200 rows.");
3298
+ }
3289
3299
  function positiveInteger(value, name) {
3290
3300
  if (Number.isInteger(value) && value > 0)
3291
3301
  return value;
@@ -281,6 +281,7 @@ export type StateQLWorkspaceOptions = StateQLActorOptions & {
281
281
  export interface QueryOptions extends ExecutionOptions {
282
282
  params?: SqlParameters;
283
283
  cache?: "auto" | "bypass" | "require";
284
+ previewRows?: number;
284
285
  }
285
286
  export interface MongoQueryOptions extends ExecutionOptions {
286
287
  cache?: "auto" | "bypass" | "require";
@@ -360,6 +361,7 @@ export interface BatchCommand {
360
361
  redis?: RedisCommand;
361
362
  object?: CatalogObject;
362
363
  cache?: "auto" | "bypass" | "require";
364
+ preview_rows?: number;
363
365
  read_only?: boolean;
364
366
  secret_env?: string;
365
367
  credential_ref?: string;
package/docs/library.md CHANGED
@@ -29,7 +29,7 @@ try {
29
29
 
30
30
  const result = await stateql.query(
31
31
  "SELECT id, email FROM users WHERE status = ? ORDER BY id LIMIT 50",
32
- { params: ["active"], timeoutMs: 5_000 },
32
+ { params: ["active"], timeoutMs: 5_000, previewRows: 20 },
33
33
  );
34
34
  if (!result.ok) throw new Error(result.error.message);
35
35
 
@@ -62,6 +62,10 @@ output mode. Check `response.ok` before reading `response.data`; failures expose
62
62
  `response.error`. Queries return typed `ResultData` with `result_id`, `preview`,
63
63
  and result metadata. Reuse `result_id` with methods such as `filter`, `rows`,
64
64
  `count`, and `exportResult`; the CLI instead presents its primary ID as `handle`.
65
+ Queries preview five rows by default. Set `previewRows` from 0 to 200 on an
66
+ individual query to control its response without changing or rerunning the
67
+ materialized result. The constructor-level `previewRows` option changes the
68
+ client default.
65
69
 
66
70
  The following snippets assume an open client and an appropriate connection.
67
71
 
package/docs/usage.md CHANGED
@@ -93,7 +93,7 @@ for source-replacement and downgrade restrictions.
93
93
 
94
94
  ## CLI reference
95
95
 
96
- ```text
96
+ ```bash
97
97
  stql connect <target> [--name NAME] [--read-only|--read-write]
98
98
  stql connect --env ENV [--name NAME] [--read-only|--read-write]
99
99
  stql connect --credential-ref REF [--name NAME] [--read-only|--read-write]
@@ -105,6 +105,7 @@ stql profile add|update NAME [TARGET | --env ENV | --credential-ref REF]
105
105
  stql profile list|show|remove
106
106
  stql session start|list|show|summary|close
107
107
  stql query <sql> [--params JSON | --param VALUE...] [--cache auto|bypass|require]
108
+ [--preview-rows 0..200]
108
109
  stql filter <result-handle> <predicate> [--params JSON | --param VALUE...]
109
110
  stql exec <sql> [--params JSON | --param VALUE...] [--idempotency-key KEY] [--replay]
110
111
  [--allow-unbounded] [--allow-destructive]
@@ -138,7 +139,7 @@ stql pipe [--continue-on-error]
138
139
  For shell-safe positional parameters, repeat `--param`. JSON scalars become
139
140
  their native types; other values remain strings.
140
141
 
141
- ```powershell
142
+ ```bash
142
143
  stql exec "INSERT INTO users (name, status) VALUES (?, ?)" `
143
144
  --param Ada --param trial
144
145
  ```
@@ -238,6 +239,10 @@ columns. These caps bound persisted materialization; the independent deadline
238
239
  bounds execution time. Native commands may impose stricter
239
240
  [database-specific limits](databases.md).
240
241
 
242
+ Query responses preview five rows by default. Use `--preview-rows N` to return
243
+ between 0 and 200 preview rows without rerunning or changing the stored result.
244
+ Additional rows remain available through `stql rows <result-handle>`.
245
+
241
246
  Command history keeps the latest 10,000 entries per session. SQLite cache reuse
242
247
  also checks the database file signature. PostgreSQL, MySQL, and MongoDB cache
243
248
  reuse is labeled `ttl_based` and is never authoritative.
@@ -346,7 +351,8 @@ stql batch commands.json
346
351
 
347
352
  Batch fields use snake case. Supported command names match CLI paths, such as
348
353
  `filter`, `transaction.begin`, `session.summary`, `alias.set`, `plan`, and
349
- `apply`. Native MongoDB batches use `mongo.query`, `mongo.exec`, or `mongo.plan`
350
- with the command object in `mongo`; the same cache, replay, idempotency, safety,
351
- and timeout fields apply. Database commands may set `timeout_ms`; otherwise they
352
- use the 30-second default.
354
+ `apply`. Query commands may set `preview_rows` from 0 to 200. Native MongoDB
355
+ batches use `mongo.query`, `mongo.exec`, or `mongo.plan` with the command object
356
+ in `mongo`; the same cache, replay, idempotency, safety, and timeout fields
357
+ apply. Database commands may set `timeout_ms`; otherwise they use the 30-second
358
+ default.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fadhilp/stateql",
3
- "version": "0.13.1",
3
+ "version": "0.13.2",
4
4
  "description": "Stateful, agent-oriented database CLI for safe result reuse",
5
5
  "repository": {
6
6
  "type": "git",