@fadhilp/stateql 0.17.0 → 0.19.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 (43) hide show
  1. package/dist/src/adapters.d.ts +17 -25
  2. package/dist/src/adapters.js +15 -95
  3. package/dist/src/catalog.d.ts +6 -0
  4. package/dist/src/catalog.js +52 -0
  5. package/dist/src/cli.js +8 -3
  6. package/dist/src/connect.d.ts +16 -0
  7. package/dist/src/connect.js +205 -0
  8. package/dist/src/core.d.ts +78 -0
  9. package/dist/src/core.js +477 -0
  10. package/dist/src/execution.d.ts +27 -0
  11. package/dist/src/execution.js +87 -0
  12. package/dist/src/filter.js +3 -1
  13. package/dist/src/index.d.ts +2 -1
  14. package/dist/src/index.js +1 -0
  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/os-credentials.d.ts +6 -1
  19. package/dist/src/os-credentials.js +171 -10
  20. package/dist/src/panel.d.ts +64 -0
  21. package/dist/src/panel.js +316 -0
  22. package/dist/src/plans.d.ts +31 -0
  23. package/dist/src/plans.js +275 -0
  24. package/dist/src/reads.d.ts +35 -0
  25. package/dist/src/reads.js +184 -0
  26. package/dist/src/redis.d.ts +4 -2
  27. package/dist/src/redis.js +7 -33
  28. package/dist/src/response-data.d.ts +1 -0
  29. package/dist/src/response-data.js +13 -10
  30. package/dist/src/results.d.ts +10 -0
  31. package/dist/src/results.js +153 -0
  32. package/dist/src/sqlite-process.js +16 -9
  33. package/dist/src/stateql.d.ts +7 -58
  34. package/dist/src/stateql.js +150 -2663
  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 +3 -17
  39. package/dist/src/writes.d.ts +48 -0
  40. package/dist/src/writes.js +320 -0
  41. package/docs/databases.md +2 -1
  42. package/docs/results.md +5 -0
  43. package/package.json +5 -3
@@ -0,0 +1,184 @@
1
+ import { version } from "./connection.js";
2
+ import { adapterOfKind, errorMessage, nonNegativeInteger, } from "./core.js";
3
+ import { StateQLError } from "./errors.js";
4
+ import { serializeMongoCommand, validateMongoReadCommand } from "./mongodb.js";
5
+ import { serializeRedisCommand, validateRedisReadCommand } from "./redis.js";
6
+ import { paginationWarnings } from "./response-data.js";
7
+ import { analyzeSql } from "./sql.js";
8
+ import { hash } from "./util.js";
9
+ export function prepareSqlRead(connection, sql, parameters) {
10
+ const analysis = analyzeSql(sql, connection.driver);
11
+ if (!analysis.read) {
12
+ throw new StateQLError("INVALID_SQL", "query accepts read statements only; use exec for writes.");
13
+ }
14
+ if (analysis.requiresAutocommit && sqlParametersLength(parameters) > 0) {
15
+ throw new StateQLError("INVALID_SQL", "Autocommit diagnostic statements do not accept StateQL parameters.");
16
+ }
17
+ return {
18
+ descriptor: sql,
19
+ identity: { sql: analysis.normalized, parameters },
20
+ parameters,
21
+ cacheable: analysis.cacheable,
22
+ warnings: paginationWarnings(analysis.ordered),
23
+ limitHint: "Add a narrower WHERE clause or LIMIT.",
24
+ async execute(adapter, fetchLimit) {
25
+ const sqlAdapter = adapterOfKind(adapter, "sql");
26
+ const executionSql = analysis.wrapForLimit
27
+ ? boundedReadSql(analysis.limitSql ?? sql, fetchLimit)
28
+ : sql;
29
+ if (!analysis.requiresAutocommit)
30
+ return sqlAdapter.read(executionSql, parameters);
31
+ if (!sqlAdapter.readAutocommit) {
32
+ throw new StateQLError("UNSUPPORTED_DRIVER", `${analysis.statementType.toUpperCase()} requires adapter autocommit reads.`);
33
+ }
34
+ return sqlAdapter.readAutocommit(executionSql, parameters);
35
+ },
36
+ };
37
+ }
38
+ export function prepareMongoRead(command) {
39
+ const value = invalidCommand(() => validateMongoReadCommand(command));
40
+ const serialized = serializeMongoCommand(value);
41
+ return {
42
+ descriptor: mongoDescriptor(value.operation),
43
+ identity: { command: serialized },
44
+ parameters: [serialized],
45
+ cacheable: true,
46
+ warnings: mongoPaginationWarnings(value),
47
+ limitHint: "Use a narrower filter or limit.",
48
+ execute: (adapter, fetchLimit) => adapterOfKind(adapter, "mongodb").read(value, fetchLimit),
49
+ };
50
+ }
51
+ export function prepareRedisRead(command) {
52
+ const value = invalidCommand(() => validateRedisReadCommand(command));
53
+ const serialized = serializeRedisCommand(value);
54
+ return {
55
+ descriptor: redisDescriptor(value.command),
56
+ identity: { command: serialized },
57
+ parameters: [serialized],
58
+ cacheable: true,
59
+ warnings: [],
60
+ limitHint: "Read fewer keys or members.",
61
+ async execute(adapter) {
62
+ const result = await adapterOfKind(adapter, "redis").read(value);
63
+ return { ...result, parameters: [serialized, result.nextCursor ?? null] };
64
+ },
65
+ };
66
+ }
67
+ /** Serves a valid cached result, or runs the read and stores the bounded result. */
68
+ export async function runRead(core, session, connection, statement, options) {
69
+ const cacheMode = options.cache ?? "auto";
70
+ if (!statement.cacheable && cacheMode === "require") {
71
+ throw cacheMiss("This statement is not cacheable.");
72
+ }
73
+ const { maxResultRows, maxResultBytes, resultTtlSeconds } = core.settings;
74
+ const previewRows = options.previewRows ?? core.settings.previewRows;
75
+ const context = core.executionContext(options);
76
+ return core.withAdapter(session, connection, "query", context, async (adapter) => {
77
+ const stateVersion = version(connection);
78
+ const stateSignature = await adapter.signature();
79
+ const fingerprint = hash({
80
+ ...statement.identity,
81
+ driver: connection.driver,
82
+ connection: connection.id,
83
+ database: connection.database_name,
84
+ transaction: session.active_transaction_id,
85
+ stateVersion,
86
+ });
87
+ const cached = statement.cacheable && cacheMode !== "bypass"
88
+ ? core.store.findResult(fingerprint)
89
+ : undefined;
90
+ if (cached &&
91
+ cached.row_count <= maxResultRows &&
92
+ core.cacheValid(cached, stateVersion, stateSignature)) {
93
+ return {
94
+ data: core.resultData(cached, true, previewRows),
95
+ handle: cached.id,
96
+ cached: true,
97
+ warnings: statement.warnings,
98
+ stateVersion,
99
+ confidence: cached.state_confidence,
100
+ };
101
+ }
102
+ if (cacheMode === "require")
103
+ throw cacheMiss("No valid cached result exists.");
104
+ const result = await statement.execute(adapter, maxResultRows + 1);
105
+ if (result.rows.length > maxResultRows) {
106
+ throw new StateQLError("OUTPUT_LIMIT_EXCEEDED", `Query exceeds the ${maxResultRows}-row materialization limit.`, { suggestedAction: statement.limitHint });
107
+ }
108
+ const parameters = result.parameters ?? statement.parameters;
109
+ const resultBytes = Buffer.byteLength(JSON.stringify(parameters), "utf8") +
110
+ Buffer.byteLength(JSON.stringify(result.rows), "utf8") +
111
+ Buffer.byteLength(JSON.stringify(result.columns), "utf8");
112
+ if (resultBytes > maxResultBytes) {
113
+ throw new StateQLError("OUTPUT_LIMIT_EXCEEDED", `Query exceeds the ${maxResultBytes}-byte materialization limit.`, { suggestedAction: statement.limitHint });
114
+ }
115
+ const saved = core.store.saveResult({
116
+ sessionId: session.id,
117
+ connectionId: connection.id,
118
+ fingerprint,
119
+ sql: statement.descriptor,
120
+ parameters,
121
+ rows: result.rows,
122
+ columns: result.columns,
123
+ stateVersion,
124
+ stateSignature,
125
+ stateConfidence: adapter.confidence,
126
+ expiresAt: core.expiresAt(resultTtlSeconds * 1000),
127
+ });
128
+ return {
129
+ data: core.resultData(saved, false, previewRows),
130
+ handle: saved.id,
131
+ executed: true,
132
+ warnings: statement.warnings,
133
+ stateVersion,
134
+ confidence: adapter.confidence,
135
+ };
136
+ });
137
+ }
138
+ export function queryPreviewRows(value) {
139
+ const previewRows = nonNegativeInteger(value, "previewRows");
140
+ if (previewRows <= 200)
141
+ return previewRows;
142
+ throw new StateQLError("OUTPUT_LIMIT_EXCEEDED", "previewRows cannot exceed 200 rows.");
143
+ }
144
+ export function sqlParametersLength(parameters) {
145
+ return Array.isArray(parameters)
146
+ ? parameters.length
147
+ : Object.keys(parameters).length;
148
+ }
149
+ export function mongoDescriptor(operation) {
150
+ return `MongoDB native ${operation}`;
151
+ }
152
+ export function redisDescriptor(command) {
153
+ return `Redis native ${command}`;
154
+ }
155
+ /** Driver validators throw plain errors; callers see them as INVALID_COMMAND. */
156
+ export function invalidCommand(validate) {
157
+ try {
158
+ return validate();
159
+ }
160
+ catch (error) {
161
+ throw new StateQLError("INVALID_COMMAND", errorMessage(error));
162
+ }
163
+ }
164
+ function cacheMiss(message) {
165
+ return new StateQLError("CACHE_MISS", message, {
166
+ retryable: true,
167
+ suggestedAction: "Run with cache auto or cache bypass.",
168
+ });
169
+ }
170
+ function boundedReadSql(sql, limit) {
171
+ const statement = sql.trim().replace(/;\s*$/, "");
172
+ return `SELECT * FROM (${statement}) AS _stateql_bounded LIMIT ${limit}`;
173
+ }
174
+ function mongoPaginationWarnings(command) {
175
+ const ordered = command.operation === "find"
176
+ ? command.options?.sort !== undefined
177
+ : command.pipeline.some((stage) => Object.hasOwn(stage, "$sort"));
178
+ return ordered
179
+ ? []
180
+ : [{
181
+ code: "NON_DETERMINISTIC_PAGINATION",
182
+ message: "MongoDB result has no explicit sort.",
183
+ }];
184
+ }
@@ -1,4 +1,5 @@
1
- import { type AdapterContext } from "./adapters.js";
1
+ import type { BaseAdapter } from "./adapters.js";
2
+ import { type AdapterContext } from "./execution.js";
2
3
  import type { CatalogObject, DescribeObjectData, ListObjectsData, ListObjectsFilter, RedisCommand, RedisWriteOutcome, Row, Column } from "./types.js";
3
4
  export interface RedisReadResult {
4
5
  rows: Row[];
@@ -19,9 +20,10 @@ export declare function validateRedisReadCommand(value: unknown): RedisCommand;
19
20
  export declare function validateRedisWriteCommand(value: unknown): RedisCommand;
20
21
  export declare function serializeRedisCommand(command: RedisCommand): string;
21
22
  export declare function deserializeRedisCommand(value: string): RedisCommand;
22
- export declare class RedisAdapter {
23
+ export declare class RedisAdapter implements BaseAdapter {
23
24
  private readonly readOnly;
24
25
  private readonly context;
26
+ readonly kind: "redis";
25
27
  readonly confidence: "ttl_based";
26
28
  private readonly client;
27
29
  private connected;
package/dist/src/redis.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import { createRequire } from "node:module";
2
- import { AdapterExecutionError, AdapterWriteError } from "./adapters.js";
2
+ import { AdapterExecutionError, AdapterWriteError, remainingMilliseconds, throwIfStopped, withContext, } from "./execution.js";
3
3
  import { hash, toJsonSafe } from "./util.js";
4
4
  const require = createRequire(import.meta.url);
5
5
  let redisModule;
@@ -101,6 +101,7 @@ export function deserializeRedisCommand(value) {
101
101
  export class RedisAdapter {
102
102
  readOnly;
103
103
  context;
104
+ kind = "redis";
104
105
  confidence = "ttl_based";
105
106
  client;
106
107
  connected = false;
@@ -166,7 +167,7 @@ export class RedisAdapter {
166
167
  const transaction = this.client.multi();
167
168
  transaction.addCommand([command.command, ...(command.args ?? [])]);
168
169
  dispatched = true;
169
- const result = await withDeadline(transaction.exec(), this.context, true, () => this.stop());
170
+ const result = await withContext(transaction.exec(), this.context, () => this.stop(), true);
170
171
  if (result === null)
171
172
  throw new AdapterWriteError("ROW_CONFLICT: The Redis key changed. Reload before editing.", false);
172
173
  raw = result[0];
@@ -277,7 +278,7 @@ export class RedisAdapter {
277
278
  }
278
279
  const [type, dump] = await Promise.all([
279
280
  this.execute(["TYPE", key], false),
280
- withDeadline(this.client.sendCommand(["DUMP", key], { typeMapping: { [redis().RESP_TYPES.BLOB_STRING]: Buffer } }), this.context, false, () => this.stop()),
281
+ withContext(this.client.sendCommand(["DUMP", key], { typeMapping: { [redis().RESP_TYPES.BLOB_STRING]: Buffer } }), this.context, () => this.stop(), false),
281
282
  ]);
282
283
  const encoded = Buffer.isBuffer(dump) ? dump.toString("base64") : dump;
283
284
  if (Buffer.byteLength(JSON.stringify(encoded), "utf8") > MAX_RESPONSE_BYTES * 2) {
@@ -291,12 +292,12 @@ export class RedisAdapter {
291
292
  throw new Error("Redis adapter is closed.");
292
293
  if (this.connected)
293
294
  return;
294
- await withDeadline(this.client.connect(), this.context, false, () => this.stop());
295
+ await withContext(this.client.connect(), this.context, () => this.stop(), false);
295
296
  this.connected = true;
296
297
  }
297
298
  async execute(command, outcomeUnknown) {
298
299
  throwIfStopped(this.context, outcomeUnknown);
299
- return withDeadline(this.client.sendCommand(command), this.context, outcomeUnknown, () => this.stop());
300
+ return withContext(this.client.sendCommand(command), this.context, () => this.stop(), outcomeUnknown);
300
301
  }
301
302
  stop() { if (this.client.isOpen)
302
303
  this.client.destroy(); this.closed = true; }
@@ -343,7 +344,7 @@ function boundedRange(startText, stopText) {
343
344
  function boundedLimit(value) { const limit = value ?? 50; if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_COLLECTION_VALUES)
344
345
  throw new Error(`limit must be 1-${MAX_COLLECTION_VALUES}.`); return limit; }
345
346
  function escapeGlob(value) { if (!value || value.length > 200 || value.includes("\0"))
346
- throw new Error("Redis search must be 1-200 characters."); return value.replace(/[\\*?\[\]]/g, "\\$&"); }
347
+ throw new Error("Redis search must be 1-200 characters."); return value.replace(/[\\*?[\]]/g, "\\$&"); }
347
348
  function redisRows(command, raw) {
348
349
  if (["SCAN", "HSCAN", "SSCAN", "ZSCAN"].includes(command.command)) {
349
350
  if (!Array.isArray(raw) || raw.length !== 2 || !Array.isArray(raw[1]))
@@ -368,31 +369,4 @@ function normalizeScalar(value) { if (value === null || typeof value === "string
368
369
  return value; return JSON.stringify(toJsonSafe(value)); }
369
370
  function redisAffectedRows(command, result) { if (typeof result === "number")
370
371
  return result; return command === "SET" && result === "OK" ? 1 : 0; }
371
- function remainingMilliseconds(context) { const remaining = context.deadline - Date.now(); if (remaining <= 0)
372
- throw new AdapterExecutionError("Database operation timed out.", "timeout", false); return Math.min(remaining, 2_147_483_647); }
373
- function throwIfStopped(context, outcomeUnknown) { if (context.signal?.aborted)
374
- throw new AdapterExecutionError("Database operation was cancelled.", "aborted", outcomeUnknown); if (context.deadline <= Date.now())
375
- throw new AdapterExecutionError("Database operation timed out.", "timeout", outcomeUnknown); }
376
- async function withDeadline(promise, context, outcomeUnknown, stop) {
377
- throwIfStopped(context, outcomeUnknown);
378
- let timer;
379
- let abort;
380
- const stopped = new Promise((_, reject) => {
381
- timer = setTimeout(() => { stop(); reject(new AdapterExecutionError("Database operation timed out.", "timeout", outcomeUnknown)); }, remainingMilliseconds(context));
382
- timer.unref();
383
- if (context.signal) {
384
- abort = () => { stop(); reject(new AdapterExecutionError("Database operation was cancelled.", "aborted", outcomeUnknown)); };
385
- context.signal.addEventListener("abort", abort, { once: true });
386
- }
387
- });
388
- try {
389
- return await Promise.race([promise, stopped]);
390
- }
391
- finally {
392
- if (timer)
393
- clearTimeout(timer);
394
- if (abort && context.signal)
395
- context.signal.removeEventListener("abort", abort);
396
- }
397
- }
398
372
  function errorText(error) { return error instanceof Error ? error.message : String(error); }
@@ -5,4 +5,5 @@ export declare function profileData(profile: ProfileRecord): ProfileData;
5
5
  export declare function operationData(operation: OperationRecord): OperationData;
6
6
  export declare function transactionData(transaction: TransactionRecord, statements: number): TransactionData;
7
7
  export declare function paginationWarnings(ordered: boolean): Warning[];
8
+ export declare function csvCell(value: unknown): string;
8
9
  export declare function rowsToCsv(rows: Row[], columns: string[]): string;
@@ -66,17 +66,20 @@ export function paginationWarnings(ordered) {
66
66
  },
67
67
  ];
68
68
  }
69
+ export function csvCell(value) {
70
+ let text = value === null || value === undefined
71
+ ? ""
72
+ : typeof value === "object"
73
+ ? JSON.stringify(value)
74
+ : String(value);
75
+ // Spreadsheets evaluate cells that start like a formula; a leading quote keeps them text.
76
+ if (typeof value !== "number" && /^[\s\u0000-\u001f]*[=+@-]|^[\t\r\n]/u.test(text))
77
+ text = `'${text}`;
78
+ return /[",\r\n]/u.test(text) ? `"${text.replaceAll('"', '""')}"` : text;
79
+ }
69
80
  export function rowsToCsv(rows, columns) {
70
- const encode = (value) => {
71
- const text = value === null || value === undefined
72
- ? ""
73
- : typeof value === "object"
74
- ? JSON.stringify(value)
75
- : String(value);
76
- return /[",\r\n]/.test(text) ? `"${text.replaceAll('"', '""')}"` : text;
77
- };
78
81
  return [
79
- columns.map(encode).join(","),
80
- ...rows.map((row) => columns.map((column) => encode(row[column])).join(",")),
82
+ columns.map(csvCell).join(","),
83
+ ...rows.map((row) => columns.map((column) => csvCell(row[column])).join(",")),
81
84
  ].join("\n") + "\n";
82
85
  }
@@ -0,0 +1,10 @@
1
+ import { type ActionResult, type Core } from "./core.js";
2
+ import type { ResultRecord } from "./store.js";
3
+ import type { ColumnsData, CountData, ExportData, FilterOptions, ResultData, RowsData, RowsOptions, SummaryData } from "./types.js";
4
+ export declare function showResult(core: Core, result: ResultRecord): ActionResult<ResultData>;
5
+ export declare function filterResult(core: Core, source: ResultRecord, predicate: string, options: FilterOptions): ActionResult<ResultData>;
6
+ export declare function resultRows(core: Core, result: ResultRecord, options: RowsOptions): ActionResult<RowsData>;
7
+ export declare function countResult(result: ResultRecord): ActionResult<CountData>;
8
+ export declare function resultColumns(core: Core, result: ResultRecord): ActionResult<ColumnsData>;
9
+ export declare function summarizeResult(core: Core, result: ResultRecord): ActionResult<SummaryData>;
10
+ export declare function exportResult(core: Core, result: ResultRecord, output: string, format: "json" | "jsonl" | "csv", columns: string[] | undefined): ActionResult<ExportData>;
@@ -0,0 +1,153 @@
1
+ import { writeFileSync } from "node:fs";
2
+ import { resolve } from "node:path";
3
+ import { nonNegativeInteger, positiveInteger } from "./core.js";
4
+ import { StateQLError } from "./errors.js";
5
+ import { filterMaterializedRows, prepareFilterStatement, validateFilterParameters, } from "./filter.js";
6
+ import { rowsToCsv } from "./response-data.js";
7
+ import { compactRows, compactValue, hash } from "./util.js";
8
+ export function showResult(core, result) {
9
+ return storedResult(result, core.resultData(result, true));
10
+ }
11
+ export function filterResult(core, source, predicate, options) {
12
+ const columns = core.store.resultColumns(source);
13
+ const filter = prepareFilterStatement(columns, predicate);
14
+ const parameters = options.params ?? [];
15
+ validateFilterParameters(filter, parameters);
16
+ const fingerprint = hash({
17
+ command: "filter",
18
+ source: source.id,
19
+ predicate: filter.normalized,
20
+ parameters,
21
+ });
22
+ const cached = core.store.findResult(fingerprint);
23
+ const reusable = cached !== undefined &&
24
+ cached.session_id === source.session_id &&
25
+ cached.connection_id === source.connection_id &&
26
+ Date.parse(cached.expires_at) > core.now().getTime();
27
+ if (reusable)
28
+ return storedResult(cached, core.resultData(cached, true));
29
+ const saved = core.store.saveResult({
30
+ sessionId: source.session_id,
31
+ connectionId: source.connection_id,
32
+ fingerprint,
33
+ sql: `FILTER ${source.id} WHERE ${predicate.trim()}`,
34
+ parameters,
35
+ rows: filterMaterializedRows(core.store.resultRows(source), filter, parameters),
36
+ columns,
37
+ stateVersion: source.state_version,
38
+ stateSignature: source.state_signature,
39
+ stateConfidence: source.state_confidence,
40
+ expiresAt: source.expires_at,
41
+ });
42
+ return {
43
+ data: core.resultData(saved, false),
44
+ handle: saved.id,
45
+ executed: true,
46
+ stateVersion: saved.state_version,
47
+ confidence: saved.state_confidence,
48
+ };
49
+ }
50
+ export function resultRows(core, result, options) {
51
+ const offset = nonNegativeInteger(options.offset ?? 0, "offset");
52
+ const limit = positiveInteger(options.limit ?? 20, "limit");
53
+ if (limit > 1_000) {
54
+ throw new StateQLError("OUTPUT_LIMIT_EXCEEDED", "limit cannot exceed 1000 rows.", { suggestedAction: "Fetch another page or use export." });
55
+ }
56
+ const rows = selectColumns(core.store.resultRows(result).slice(offset, offset + limit), core.store.resultColumns(result), options.columns);
57
+ const next = offset + rows.length;
58
+ return storedResult(result, {
59
+ result_id: result.id,
60
+ offset,
61
+ limit,
62
+ rows: compactRows(rows, core.settings.maxCellCharacters),
63
+ returned: rows.length,
64
+ total: result.row_count,
65
+ truncated: next < result.row_count,
66
+ next_offset: next < result.row_count ? next : null,
67
+ });
68
+ }
69
+ export function countResult(result) {
70
+ return storedResult(result, { result_id: result.id, rows: result.row_count });
71
+ }
72
+ export function resultColumns(core, result) {
73
+ return storedResult(result, { result_id: result.id, columns: core.store.resultColumns(result) });
74
+ }
75
+ export function summarizeResult(core, result) {
76
+ const rows = core.store.resultRows(result);
77
+ return storedResult(result, {
78
+ result_id: result.id,
79
+ total: result.row_count,
80
+ columns: core.store.resultColumns(result).map((column) => summarizeColumn(column.name, rows, core.settings.maxCellCharacters)),
81
+ });
82
+ }
83
+ export function exportResult(core, result, output, format, columns) {
84
+ const resultColumns = core.store.resultColumns(result);
85
+ const rows = selectColumns(core.store.resultRows(result), resultColumns, columns);
86
+ const content = format === "json"
87
+ ? `${JSON.stringify(rows, null, 2)}\n`
88
+ : format === "jsonl"
89
+ ? `${rows.map((row) => JSON.stringify(row)).join("\n")}\n`
90
+ : rowsToCsv(rows, columns ?? resultColumns.map((column) => column.name));
91
+ const path = resolve(output);
92
+ writeFileSync(path, content, "utf8");
93
+ return {
94
+ data: { result_id: result.id, output: path, format, rows: rows.length },
95
+ handle: result.id,
96
+ executed: true,
97
+ };
98
+ }
99
+ function storedResult(result, data) {
100
+ return {
101
+ data,
102
+ handle: result.id,
103
+ cached: true,
104
+ stateVersion: result.state_version,
105
+ confidence: result.state_confidence,
106
+ };
107
+ }
108
+ function selectColumns(rows, available, selected) {
109
+ if (!selected)
110
+ return rows;
111
+ const names = available.map((column) => column.name);
112
+ const unknown = selected.filter((name) => !names.includes(name));
113
+ if (selected.length === 0 || unknown.length > 0) {
114
+ throw new StateQLError("INVALID_COMMAND", unknown.length > 0 ? `Unknown column: ${unknown.join(", ")}.` : "columns cannot be empty.", { suggestedAction: `Use one or more of: ${names.join(", ")}.` });
115
+ }
116
+ // Keep missing keys missing, so MongoDB documents still distinguish missing from null.
117
+ return rows.map((row) => Object.fromEntries(selected.filter((name) => name in row).map((name) => [name, row[name]])));
118
+ }
119
+ function summarizeColumn(name, rows, maxCellCharacters) {
120
+ const values = rows
121
+ .map((row) => row[name])
122
+ .filter((value) => value !== null && value !== undefined);
123
+ const [min, max] = valueRange(values);
124
+ return {
125
+ name,
126
+ nulls: rows.length - values.length,
127
+ distinct: new Set(values.map((value) => JSON.stringify(value))).size,
128
+ min: compactValue(min, maxCellCharacters),
129
+ max: compactValue(max, maxCellCharacters),
130
+ };
131
+ }
132
+ const NUMERIC_TEXT = /^-?\d+(?:\.\d+)?$/;
133
+ // Exact numerics (PostgreSQL numeric/bigint, MySQL DECIMAL) arrive as strings, so compare them as numbers.
134
+ function valueRange(values) {
135
+ const numeric = values.every((value) => typeof value === "number" || (typeof value === "string" && NUMERIC_TEXT.test(value)));
136
+ const text = values.every((value) => typeof value === "string");
137
+ if (values.length === 0)
138
+ return [null, null];
139
+ if (!numeric && !text)
140
+ return [null, null];
141
+ const compare = numeric
142
+ ? (left, right) => Number(left) - Number(right)
143
+ : (left, right) => (String(left) < String(right) ? -1 : String(left) > String(right) ? 1 : 0);
144
+ let min = values[0];
145
+ let max = values[0];
146
+ for (const value of values) {
147
+ if (compare(value, min) < 0)
148
+ min = value;
149
+ if (compare(value, max) > 0)
150
+ max = value;
151
+ }
152
+ return [min, max];
153
+ }
@@ -44,15 +44,22 @@ function execute(request) {
44
44
  switch (request.operation) {
45
45
  case "read": {
46
46
  const [sql, params] = request.args;
47
- const statement = database.prepare(sql);
48
- const rows = bindAll(statement, params);
49
- return {
50
- rows: toJsonSafe(rows),
51
- columns: statement.columns().map((column) => ({
52
- name: column.name,
53
- type: column.type?.toLowerCase() ?? inferType(rows, column.name),
54
- })),
55
- };
47
+ // SQLite itself rejects writes here even if SQL analysis misclassifies a statement.
48
+ database.exec("PRAGMA query_only = ON");
49
+ try {
50
+ const statement = database.prepare(sql);
51
+ const rows = bindAll(statement, params);
52
+ return {
53
+ rows: toJsonSafe(rows),
54
+ columns: statement.columns().map((column) => ({
55
+ name: column.name,
56
+ type: column.type?.toLowerCase() ?? inferType(rows, column.name),
57
+ })),
58
+ };
59
+ }
60
+ finally {
61
+ database.exec("PRAGMA query_only = OFF");
62
+ }
56
63
  }
57
64
  case "write": {
58
65
  if (readOnly)
@@ -1,30 +1,16 @@
1
- import { type TableChange } from "./table-editor.js";
2
- import type { ActorData, ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, CommandExecutionContext, CommandOrigin, BatchOptions, CapabilitiesData, CatalogObject, DescribeObjectData, ListObjectsData, ListObjectsFilter, CloseSessionData, ColumnsData, CommitTransactionData, ConnectOptions, ConnectionData, CountData, DisconnectData, DoctorData, ExecData, ExecOptions, ExecutionOptions, ExportData, FilterOptions, HistoryData, HistoryOptions, OperationData, PlanData, PlanOptions, ProfileData, ProfilesData, ProfileOptions, ProfileUpdateOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, RedisCommand, RedisExecOptions, RedisPlanOptions, RedisQueryOptions, PurgeData, QueryOptions, RemovedProfileData, Response, ResultData, RollbackTransactionData, RowsData, RowsOptions, Column, SummaryData, StateQLActorOptions, StateQLOptions, StateQLWorkspaceOptions, StateQLSnapshot, StateQLSnapshotOptions, StatusData, SessionData, SessionsData, SessionSummaryData, TransactionData } from "./types.js";
1
+ import { type MaterializedPage, type TableRead } from "./panel.js";
2
+ import type { TableChange } from "./table-editor.js";
3
+ import type { ActorData, ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, BatchOptions, CapabilitiesData, CatalogObject, CloseSessionData, ColumnsData, CommandExecutionContext, CommandOrigin, CommitTransactionData, ConnectionData, ConnectOptions, CountData, DescribeObjectData, DisconnectData, DoctorData, ExecData, ExecOptions, ExecutionOptions, ExportData, FilterOptions, HistoryData, HistoryOptions, ListObjectsData, ListObjectsFilter, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, OperationData, PlanData, PlanOptions, ProfileData, ProfileOptions, ProfilesData, ProfileUpdateOptions, PurgeData, QueryOptions, RedisCommand, RedisExecOptions, RedisPlanOptions, RedisQueryOptions, RemovedProfileData, Response, ResultData, RollbackTransactionData, RowsData, RowsOptions, SessionData, SessionsData, SessionSummaryData, StateQLActorOptions, StateQLOptions, StateQLSnapshot, StateQLSnapshotOptions, StateQLWorkspaceOptions, StatusData, SummaryData, TransactionData } from "./types.js";
3
4
  export declare class StateQL {
4
5
  /** Runtime contract marker for passwordRef/password_ref support. */
5
6
  static readonly passwordReferenceVersion: 1;
6
7
  static forActor(options: StateQLActorOptions): StateQL;
7
8
  /** Opens one actor in a named shared workspace for a trusted library host. */
8
9
  static forWorkspace(options: StateQLWorkspaceOptions): StateQL;
10
+ private readonly core;
9
11
  private readonly store;
10
- private readonly sessionName;
11
- private readonly actorId;
12
- private readonly previewRows;
13
- private readonly cacheTtlSeconds;
14
- private readonly resultTtlSeconds;
15
- private readonly maxCellCharacters;
16
- private readonly maxResultRows;
17
- private readonly maxResultBytes;
18
- private readonly timeoutMs;
19
- private readonly credentialTimeoutMs;
20
- private readonly signal?;
21
- private readonly commandContexts;
22
- private readonly credentialResolver?;
23
- private readonly now;
12
+ private readonly panel;
24
13
  private closed;
25
- private readonly tableResults;
26
- private readonly editTokens;
27
- private panelRows?;
28
14
  constructor(options?: StateQLOptions);
29
15
  close(): void;
30
16
  [Symbol.dispose](): void;
@@ -61,12 +47,7 @@ export declare class StateQL {
61
47
  /** Owned, full-value pages for host UIs. Reading a page does not add a command to history. */
62
48
  readMaterialized(id: string, options?: RowsOptions & {
63
49
  signal?: AbortSignal;
64
- }): RowsData & {
65
- columns: Column[];
66
- row_tokens: Array<string | null>;
67
- writable_columns: string[];
68
- editing_reason?: string;
69
- };
50
+ }): MaterializedPage;
70
51
  /** No caller-selected filesystem paths. The host delivers these bounded attachment bytes. */
71
52
  serializeResult(id: string, format: "json" | "jsonl" | "csv", signal?: AbortSignal, origin?: CommandOrigin): Promise<Response<{
72
53
  content: string;
@@ -78,14 +59,7 @@ export declare class StateQL {
78
59
  name: string;
79
60
  }, limit?: number, options?: QueryOptions & {
80
61
  origin?: CommandOrigin;
81
- }): Promise<Response<ResultData & {
82
- table: {
83
- schema?: string;
84
- name: string;
85
- };
86
- sample_limit: number;
87
- query: string;
88
- }>>;
62
+ }): Promise<Response<TableRead>>;
89
63
  planTableUpdate(token: string, changes: TableChange, options?: ExecutionOptions & {
90
64
  origin?: CommandOrigin;
91
65
  }): Promise<Response<PlanData>>;
@@ -95,9 +69,6 @@ export declare class StateQL {
95
69
  }>, options?: ExecutionOptions & {
96
70
  origin?: CommandOrigin;
97
71
  }): Promise<Response<PlanData>>;
98
- private editableMetadata;
99
- private panelResult;
100
- private fullResultRows;
101
72
  exportResult(idOrAlias: string, output: string, format?: "json" | "jsonl" | "csv", columns?: string[]): Promise<Response<ExportData>>;
102
73
  exec(sql: string, options?: ExecOptions): Promise<Response<ExecData>>;
103
74
  mongoExec(command: MongoWriteCommand, options?: MongoExecOptions): Promise<Response<ExecData>>;
@@ -120,30 +91,8 @@ export declare class StateQL {
120
91
  capabilities(): Promise<Response<CapabilitiesData>>;
121
92
  executeCommand(command: BatchCommand, context?: CommandExecutionContext): Promise<Response<unknown>>;
122
93
  batch(commands: Iterable<BatchCommand> | AsyncIterable<BatchCommand>, options?: BatchOptions): AsyncGenerator<Response<unknown>>;
123
- private performExec;
124
- private performMongoExec;
125
- private performRedisExec;
126
- private performTableBatch;
127
94
  private batchFailure;
128
- private withResult;
129
- private rejectDuringStagedTransaction;
130
- private requireResult;
131
- private requireConnection;
132
- private requireMongoConnection;
133
- private requireRedisConnection;
134
- private rejectMongoSql;
135
- private requireActiveTransaction;
136
95
  private requireSelectedSession;
137
96
  private validateActorId;
138
97
  private validateActorName;
139
- private throwMembershipDenied;
140
- private resolveConnectionSource;
141
- private resolveCredential;
142
- private openAdapter;
143
- private openMongoAdapter;
144
- private openRedisAdapter;
145
- private executionContext;
146
- private resultData;
147
- private cacheValid;
148
- private run;
149
98
  }