@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 +5 -0
- package/dist/src/stateql.js +14 -4
- package/dist/src/types.d.ts +2 -0
- package/docs/library.md +5 -1
- package/docs/usage.md +12 -6
- package/package.json +1 -1
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.
|
package/dist/src/stateql.js
CHANGED
|
@@ -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,
|
|
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;
|
package/dist/src/types.d.ts
CHANGED
|
@@ -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
|
-
```
|
|
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
|
-
```
|
|
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`.
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
use the 30-second
|
|
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.
|