@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.
- package/dist/src/adapters.d.ts +17 -25
- package/dist/src/adapters.js +15 -95
- package/dist/src/catalog.d.ts +6 -0
- package/dist/src/catalog.js +52 -0
- package/dist/src/cli.js +8 -3
- package/dist/src/connect.d.ts +16 -0
- package/dist/src/connect.js +205 -0
- package/dist/src/core.d.ts +78 -0
- package/dist/src/core.js +477 -0
- package/dist/src/execution.d.ts +27 -0
- package/dist/src/execution.js +87 -0
- package/dist/src/filter.js +3 -1
- package/dist/src/index.d.ts +2 -1
- package/dist/src/index.js +1 -0
- package/dist/src/migrations.d.ts +1 -1
- package/dist/src/mongodb.d.ts +4 -2
- package/dist/src/mongodb.js +5 -56
- package/dist/src/os-credentials.d.ts +6 -1
- package/dist/src/os-credentials.js +171 -10
- package/dist/src/panel.d.ts +64 -0
- package/dist/src/panel.js +316 -0
- package/dist/src/plans.d.ts +31 -0
- package/dist/src/plans.js +275 -0
- package/dist/src/reads.d.ts +35 -0
- package/dist/src/reads.js +184 -0
- package/dist/src/redis.d.ts +4 -2
- package/dist/src/redis.js +7 -33
- package/dist/src/response-data.d.ts +1 -0
- package/dist/src/response-data.js +13 -10
- package/dist/src/results.d.ts +10 -0
- package/dist/src/results.js +153 -0
- package/dist/src/sqlite-process.js +16 -9
- package/dist/src/stateql.d.ts +7 -58
- package/dist/src/stateql.js +150 -2663
- package/dist/src/table-editor.js +2 -2
- package/dist/src/transactions.d.ts +8 -0
- package/dist/src/transactions.js +186 -0
- package/dist/src/types.d.ts +3 -17
- package/dist/src/writes.d.ts +48 -0
- package/dist/src/writes.js +320 -0
- package/docs/databases.md +2 -1
- package/docs/results.md +5 -0
- 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
|
+
}
|
package/dist/src/redis.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
|
-
import {
|
|
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 "./
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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(/[
|
|
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(
|
|
80
|
-
...rows.map((row) => columns.map((column) =>
|
|
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
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
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)
|
package/dist/src/stateql.d.ts
CHANGED
|
@@ -1,30 +1,16 @@
|
|
|
1
|
-
import { type
|
|
2
|
-
import type {
|
|
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
|
|
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
|
-
}):
|
|
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<
|
|
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
|
}
|