@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.
- package/dist/src/adapters.d.ts +17 -25
- package/dist/src/adapters.js +15 -95
- package/dist/src/agent-response.js +6 -1
- package/dist/src/catalog.d.ts +6 -0
- package/dist/src/catalog.js +52 -0
- package/dist/src/cli.js +76 -25
- 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 +1 -1
- 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/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/sql.d.ts +7 -1
- package/dist/src/sql.js +88 -8
- package/dist/src/sqlite-process.js +16 -9
- package/dist/src/stateql.d.ts +9 -59
- package/dist/src/stateql.js +170 -2597
- 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 +20 -18
- package/dist/src/util.d.ts +1 -0
- package/dist/src/util.js +1 -1
- package/dist/src/writes.d.ts +48 -0
- package/dist/src/writes.js +320 -0
- package/docs/batch.md +2 -1
- package/docs/cli.md +15 -9
- package/docs/databases.md +4 -3
- package/docs/library.md +3 -1
- package/docs/results.md +17 -0
- package/docs/writes.md +6 -0
- package/package.json +5 -3
- package/skills/stateql/SKILL.md +14 -6
- package/skills/stateql/reference/writes.md +4 -1
package/dist/src/mongodb.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { createRequire } from "node:module";
|
|
2
2
|
import { BSON } from "bson";
|
|
3
|
-
import { AdapterExecutionError, AdapterWriteError, BatchWriteError, } from "./
|
|
3
|
+
import { AdapterExecutionError, AdapterWriteError, BatchWriteError, isStopped, remainingMilliseconds, stoppedError, throwIfStopped, withContext, } from "./execution.js";
|
|
4
4
|
const require = createRequire(import.meta.url);
|
|
5
5
|
let mongodbModule;
|
|
6
6
|
const mongodb = () => (mongodbModule ??= require("mongodb"));
|
|
@@ -156,6 +156,7 @@ export function deserializeMongoWriteCommand(value) {
|
|
|
156
156
|
}
|
|
157
157
|
export class MongoAdapter {
|
|
158
158
|
context;
|
|
159
|
+
kind = "mongodb";
|
|
159
160
|
confidence = "ttl_based";
|
|
160
161
|
client;
|
|
161
162
|
databaseName;
|
|
@@ -258,7 +259,7 @@ export class MongoAdapter {
|
|
|
258
259
|
const stopped = writeStoppedError(error, this.context, true);
|
|
259
260
|
if (stopped)
|
|
260
261
|
throw stopped;
|
|
261
|
-
throw new AdapterWriteError(errorText(error), knownNoWrite(error)
|
|
262
|
+
throw new AdapterWriteError(errorText(error), !knownNoWrite(error));
|
|
262
263
|
}
|
|
263
264
|
}
|
|
264
265
|
async writeBatch(commands, isolation, expectedRows = false) {
|
|
@@ -838,75 +839,23 @@ function ejsonSafe(value) {
|
|
|
838
839
|
return null;
|
|
839
840
|
return JSON.parse(BSON.EJSON.stringify(value, { relaxed: false }));
|
|
840
841
|
}
|
|
841
|
-
function escapeRegex(value) {
|
|
842
|
-
return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
|
|
843
|
-
}
|
|
844
|
-
function remainingMilliseconds(context) {
|
|
845
|
-
return Math.max(1, Math.min(2_147_483_647, Math.ceil(context.deadline - Date.now())));
|
|
846
|
-
}
|
|
847
842
|
function operationSignal(context) {
|
|
848
843
|
const deadlineSignal = AbortSignal.timeout(remainingMilliseconds(context));
|
|
849
844
|
return context.signal ? AbortSignal.any([context.signal, deadlineSignal]) : deadlineSignal;
|
|
850
845
|
}
|
|
851
|
-
function throwIfStopped(context, outcomeUnknown) {
|
|
852
|
-
if (context.signal?.aborted || context.deadline <= Date.now()) {
|
|
853
|
-
throw stoppedError(context, outcomeUnknown);
|
|
854
|
-
}
|
|
855
|
-
}
|
|
856
|
-
function stoppedError(context, outcomeUnknown) {
|
|
857
|
-
const aborted = context.signal?.aborted ?? false;
|
|
858
|
-
return new AdapterExecutionError(aborted ? "Database operation cancelled." : "Database operation timed out.", aborted ? "aborted" : "timeout", outcomeUnknown);
|
|
859
|
-
}
|
|
860
|
-
function withContext(promise, context, onStop, outcomeUnknown) {
|
|
861
|
-
try {
|
|
862
|
-
throwIfStopped(context, outcomeUnknown);
|
|
863
|
-
}
|
|
864
|
-
catch (error) {
|
|
865
|
-
return Promise.reject(error);
|
|
866
|
-
}
|
|
867
|
-
return new Promise((resolve, reject) => {
|
|
868
|
-
let settled = false;
|
|
869
|
-
const finish = (action) => {
|
|
870
|
-
if (settled)
|
|
871
|
-
return;
|
|
872
|
-
settled = true;
|
|
873
|
-
clearTimeout(timer);
|
|
874
|
-
context.signal?.removeEventListener("abort", stop);
|
|
875
|
-
action();
|
|
876
|
-
};
|
|
877
|
-
const stop = () => finish(() => {
|
|
878
|
-
try {
|
|
879
|
-
onStop();
|
|
880
|
-
}
|
|
881
|
-
catch {
|
|
882
|
-
// Preserve cancellation/deadline error.
|
|
883
|
-
}
|
|
884
|
-
reject(stoppedError(context, outcomeUnknown));
|
|
885
|
-
});
|
|
886
|
-
const timer = setTimeout(stop, remainingMilliseconds(context));
|
|
887
|
-
context.signal?.addEventListener("abort", stop, { once: true });
|
|
888
|
-
promise.then((result) => context.signal?.aborted || context.deadline <= Date.now()
|
|
889
|
-
? stop()
|
|
890
|
-
: finish(() => resolve(result)), (error) => context.signal?.aborted || context.deadline <= Date.now()
|
|
891
|
-
? stop()
|
|
892
|
-
: finish(() => reject(error)));
|
|
893
|
-
});
|
|
894
|
-
}
|
|
895
846
|
function readError(error, context) {
|
|
896
847
|
if (error instanceof AdapterExecutionError)
|
|
897
848
|
return error;
|
|
898
|
-
if (isTimeoutError(error) || context
|
|
849
|
+
if (isTimeoutError(error) || isStopped(context))
|
|
899
850
|
return stoppedError(context, false);
|
|
900
|
-
}
|
|
901
851
|
return error;
|
|
902
852
|
}
|
|
903
853
|
function writeStoppedError(error, context, outcomeUnknown) {
|
|
904
854
|
if (error instanceof AdapterExecutionError) {
|
|
905
855
|
return new AdapterExecutionError(error.message, error.reason, outcomeUnknown);
|
|
906
856
|
}
|
|
907
|
-
if (isTimeoutError(error) || context
|
|
857
|
+
if (isTimeoutError(error) || isStopped(context))
|
|
908
858
|
return stoppedError(context, outcomeUnknown);
|
|
909
|
-
}
|
|
910
859
|
return undefined;
|
|
911
860
|
}
|
|
912
861
|
function isTimeoutError(error) {
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
import { type Core } from "./core.js";
|
|
2
|
+
import { type EditableTable, type TableChange, type TableIdentity } from "./table-editor.js";
|
|
3
|
+
import type { Column, CommandOrigin, ExecutionOptions, MongoReadCommand, PlanData, QueryOptions, Response, ResultData, RowsData, RowsOptions, StateQLSnapshot, StateQLSnapshotOptions } from "./types.js";
|
|
4
|
+
/** Public StateQL commands the panel calls, so they are recorded in history as usual. */
|
|
5
|
+
export interface PanelHost {
|
|
6
|
+
snapshot(options: StateQLSnapshotOptions): StateQLSnapshot;
|
|
7
|
+
inspect(kind: string, table: string, options: ExecutionOptions): Promise<Response<unknown>>;
|
|
8
|
+
query(sql: string, options: QueryOptions): Promise<Response<ResultData>>;
|
|
9
|
+
mongoQuery(command: MongoReadCommand, options: QueryOptions): Promise<Response<ResultData>>;
|
|
10
|
+
}
|
|
11
|
+
export type MaterializedPage = RowsData & {
|
|
12
|
+
columns: Column[];
|
|
13
|
+
row_tokens: Array<string | null>;
|
|
14
|
+
writable_columns: string[];
|
|
15
|
+
editing_reason?: string;
|
|
16
|
+
};
|
|
17
|
+
export type TableRead = ResultData & {
|
|
18
|
+
table: {
|
|
19
|
+
schema?: string;
|
|
20
|
+
name: string;
|
|
21
|
+
};
|
|
22
|
+
sample_limit: number;
|
|
23
|
+
query: string;
|
|
24
|
+
};
|
|
25
|
+
/** Bounded table browsing and row editing for host UIs, with in-memory row identities. */
|
|
26
|
+
export declare class Panel {
|
|
27
|
+
private readonly core;
|
|
28
|
+
private readonly host;
|
|
29
|
+
private readonly tableResults;
|
|
30
|
+
private readonly editTokens;
|
|
31
|
+
private panelRows?;
|
|
32
|
+
constructor(core: Core, host: PanelHost);
|
|
33
|
+
clear(): void;
|
|
34
|
+
/** Owned, full-value pages for host UIs. Reading a page does not add a command to history. */
|
|
35
|
+
readMaterialized(id: string, options?: RowsOptions & {
|
|
36
|
+
signal?: AbortSignal;
|
|
37
|
+
}): MaterializedPage;
|
|
38
|
+
/** No caller-selected filesystem paths. The host delivers these bounded attachment bytes. */
|
|
39
|
+
serializeResult(id: string, format: "json" | "jsonl" | "csv", signal?: AbortSignal, origin?: CommandOrigin): Promise<Response<{
|
|
40
|
+
content: string;
|
|
41
|
+
format: string;
|
|
42
|
+
rows: number;
|
|
43
|
+
}>>;
|
|
44
|
+
readTable(table: {
|
|
45
|
+
schema?: string;
|
|
46
|
+
name: string;
|
|
47
|
+
}, limit?: number, options?: QueryOptions & {
|
|
48
|
+
origin?: CommandOrigin;
|
|
49
|
+
}): Promise<Response<TableRead>>;
|
|
50
|
+
planTableUpdate(token: string, changes: TableChange, options?: ExecutionOptions & {
|
|
51
|
+
origin?: CommandOrigin;
|
|
52
|
+
}): Promise<Response<PlanData>>;
|
|
53
|
+
planTableUpdates(changes: Array<{
|
|
54
|
+
row_token: string;
|
|
55
|
+
changes: TableChange;
|
|
56
|
+
}>, options?: ExecutionOptions & {
|
|
57
|
+
origin?: CommandOrigin;
|
|
58
|
+
}): Promise<Response<PlanData>>;
|
|
59
|
+
editableMetadata(table: TableIdentity, options: ExecutionOptions): Promise<EditableTable>;
|
|
60
|
+
private issueEditToken;
|
|
61
|
+
private liveEditToken;
|
|
62
|
+
private panelResult;
|
|
63
|
+
private fullResultRows;
|
|
64
|
+
}
|
|
@@ -0,0 +1,316 @@
|
|
|
1
|
+
import { randomUUID } from "node:crypto";
|
|
2
|
+
import { version } from "./connection.js";
|
|
3
|
+
import { nonNegativeInteger, positiveInteger, } from "./core.js";
|
|
4
|
+
import { StateQLError } from "./errors.js";
|
|
5
|
+
import { runPlan } from "./plans.js";
|
|
6
|
+
import { csvCell } from "./response-data.js";
|
|
7
|
+
import { compileTableUpdate, editableRow, } from "./table-editor.js";
|
|
8
|
+
import { hash } from "./util.js";
|
|
9
|
+
const EDIT_TOKEN_TTL_MS = 10 * 60_000;
|
|
10
|
+
/** Bounded table browsing and row editing for host UIs, with in-memory row identities. */
|
|
11
|
+
export class Panel {
|
|
12
|
+
core;
|
|
13
|
+
host;
|
|
14
|
+
tableResults = new Map();
|
|
15
|
+
editTokens = new Map();
|
|
16
|
+
// ponytail: cache one bounded immutable result; use indexed result storage if larger results are needed.
|
|
17
|
+
panelRows;
|
|
18
|
+
constructor(core, host) {
|
|
19
|
+
this.core = core;
|
|
20
|
+
this.host = host;
|
|
21
|
+
}
|
|
22
|
+
clear() {
|
|
23
|
+
this.panelRows = undefined;
|
|
24
|
+
this.tableResults.clear();
|
|
25
|
+
this.editTokens.clear();
|
|
26
|
+
}
|
|
27
|
+
/** Owned, full-value pages for host UIs. Reading a page does not add a command to history. */
|
|
28
|
+
readMaterialized(id, options = {}) {
|
|
29
|
+
options.signal?.throwIfAborted();
|
|
30
|
+
const result = this.panelResult(id);
|
|
31
|
+
const offset = nonNegativeInteger(options.offset ?? 0, "offset");
|
|
32
|
+
const limit = positiveInteger(options.limit ?? 100, "limit");
|
|
33
|
+
if (limit > 100 || offset > 10_000)
|
|
34
|
+
throw new StateQLError("OUTPUT_LIMIT_EXCEEDED", "Page bounds exceeded.");
|
|
35
|
+
const all = this.fullResultRows(result);
|
|
36
|
+
const rows = [];
|
|
37
|
+
let bytes = 0;
|
|
38
|
+
for (const row of all.slice(offset, offset + limit)) {
|
|
39
|
+
const size = Buffer.byteLength(JSON.stringify(row), "utf8");
|
|
40
|
+
if (bytes + size > 200 * 1024) {
|
|
41
|
+
if (!rows.length)
|
|
42
|
+
throw new StateQLError("OUTPUT_LIMIT_EXCEEDED", "A row exceeds the browser page limit. Export this result instead.");
|
|
43
|
+
break;
|
|
44
|
+
}
|
|
45
|
+
rows.push(row);
|
|
46
|
+
bytes += size;
|
|
47
|
+
}
|
|
48
|
+
const next = offset + rows.length;
|
|
49
|
+
const metadata = this.tableResults.get(id);
|
|
50
|
+
const connection = this.core.store.activeConnection(this.core.store.ensureSession(this.core.sessionName));
|
|
51
|
+
const editable = metadata !== undefined &&
|
|
52
|
+
connection?.id === result.connection_id &&
|
|
53
|
+
!connection.read_only &&
|
|
54
|
+
version(connection) === result.state_version;
|
|
55
|
+
const rowTokens = rows.map((row) => editable && editableRow(metadata, row) ? this.issueEditToken(metadata, row, result) : null);
|
|
56
|
+
const writable = metadata?.driver === "mongodb"
|
|
57
|
+
? [...new Set(rows.flatMap((row) => Object.keys(row)))].filter((name) => name !== "_id")
|
|
58
|
+
: metadata?.columns.filter((column) => !column.key && !column.generated).map((column) => column.name) ?? [];
|
|
59
|
+
return {
|
|
60
|
+
row_tokens: rowTokens,
|
|
61
|
+
writable_columns: writable,
|
|
62
|
+
...(!metadata?.writable ? { editing_reason: metadata?.reason ?? "Query results are read-only." } : {}),
|
|
63
|
+
result_id: result.id,
|
|
64
|
+
offset,
|
|
65
|
+
limit,
|
|
66
|
+
rows: structuredClone(rows),
|
|
67
|
+
columns: this.core.store.resultColumns(result),
|
|
68
|
+
returned: rows.length,
|
|
69
|
+
total: all.length,
|
|
70
|
+
truncated: next < all.length,
|
|
71
|
+
next_offset: next < all.length ? next : null,
|
|
72
|
+
};
|
|
73
|
+
}
|
|
74
|
+
/** No caller-selected filesystem paths. The host delivers these bounded attachment bytes. */
|
|
75
|
+
async serializeResult(id, format, signal, origin = "api") {
|
|
76
|
+
return this.core.withCommandContext({ signal, origin }, () => this.core.run("export", async () => {
|
|
77
|
+
if (!["json", "jsonl", "csv"].includes(format))
|
|
78
|
+
throw new StateQLError("INVALID_COMMAND", "Unsupported export format.");
|
|
79
|
+
const result = this.panelResult(id);
|
|
80
|
+
const rows = this.fullResultRows(result);
|
|
81
|
+
const columns = this.core.store.resultColumns(result).map((column) => column.name);
|
|
82
|
+
const chunks = [];
|
|
83
|
+
let bytes = 0;
|
|
84
|
+
const append = (chunk) => {
|
|
85
|
+
bytes += Buffer.byteLength(chunk, "utf8");
|
|
86
|
+
if (bytes > 32 * 1024 * 1024)
|
|
87
|
+
throw new StateQLError("OUTPUT_LIMIT_EXCEEDED", "Export exceeds 32 MiB.");
|
|
88
|
+
chunks.push(chunk);
|
|
89
|
+
};
|
|
90
|
+
if (format === "json")
|
|
91
|
+
append("[");
|
|
92
|
+
if (format === "csv")
|
|
93
|
+
append(columns.map(csvCell).join(",") + "\n");
|
|
94
|
+
const deadline = Date.now() + 30_000;
|
|
95
|
+
for (let index = 0; index < rows.length; index++) {
|
|
96
|
+
if (index % 100 === 0) {
|
|
97
|
+
await new Promise((resolve) => setImmediate(resolve));
|
|
98
|
+
signal?.throwIfAborted();
|
|
99
|
+
this.core.signal?.throwIfAborted();
|
|
100
|
+
if (Date.now() > deadline)
|
|
101
|
+
throw new StateQLError("DEADLINE_EXCEEDED", "Export preparation timed out.");
|
|
102
|
+
}
|
|
103
|
+
const row = rows[index];
|
|
104
|
+
append(format === "csv"
|
|
105
|
+
? columns.map((column) => csvCell(row[column])).join(",") + "\n"
|
|
106
|
+
: (format === "json" && index ? "," : "") + JSON.stringify(row) + (format === "jsonl" ? "\n" : ""));
|
|
107
|
+
}
|
|
108
|
+
signal?.throwIfAborted();
|
|
109
|
+
if (format === "json")
|
|
110
|
+
append("]\n");
|
|
111
|
+
this.panelResult(id);
|
|
112
|
+
return { data: { content: chunks.join(""), format, rows: rows.length }, handle: id };
|
|
113
|
+
}));
|
|
114
|
+
}
|
|
115
|
+
async readTable(table, limit = 1000, options = {}) {
|
|
116
|
+
const context = { signal: options.signal, origin: options.origin ?? "api", internal: true };
|
|
117
|
+
return this.core.withCommandContext(context, async () => {
|
|
118
|
+
if (!validTableName(table) || !Number.isSafeInteger(limit) || limit < 1 || limit > 10_000) {
|
|
119
|
+
throw new StateQLError("INVALID_COMMAND", "Invalid table or sample limit.");
|
|
120
|
+
}
|
|
121
|
+
const driver = this.host.snapshot({ historyLimit: 1 }).connection?.driver;
|
|
122
|
+
if (!driver)
|
|
123
|
+
throw new StateQLError("CONNECTION_NOT_FOUND", "Connect to a database first.");
|
|
124
|
+
if (driver === "sqlite" && table.schema && table.schema !== "main")
|
|
125
|
+
throw new StateQLError("INVALID_COMMAND", "Only the main SQLite schema is supported.");
|
|
126
|
+
if (driver === "mongodb" && table.schema)
|
|
127
|
+
throw new StateQLError("INVALID_COMMAND", "MongoDB collections do not accept a schema.");
|
|
128
|
+
if (driver === "redis")
|
|
129
|
+
throw new StateQLError("INVALID_COMMAND", "Redis keys are not SQL tables; use redisQuery and describeObject.");
|
|
130
|
+
const quote = (name) => driver === "mysql"
|
|
131
|
+
? "`" + name.replaceAll("`", "``") + "`"
|
|
132
|
+
: '"' + name.replaceAll('"', '""') + '"';
|
|
133
|
+
const qualified = [table.schema, table.name]
|
|
134
|
+
.filter((part) => Boolean(part))
|
|
135
|
+
.map(quote)
|
|
136
|
+
.join(".");
|
|
137
|
+
const find = { operation: "find", collection: table.name, options: { limit } };
|
|
138
|
+
const query = driver === "mongodb"
|
|
139
|
+
? JSON.stringify(find, null, 2)
|
|
140
|
+
: "SELECT * FROM " + qualified + " LIMIT " + limit;
|
|
141
|
+
const metadata = await this.editableMetadata(table, options);
|
|
142
|
+
const response = driver === "mongodb"
|
|
143
|
+
? await this.host.mongoQuery(find, options)
|
|
144
|
+
: await this.host.query(query, options);
|
|
145
|
+
if (!response.ok)
|
|
146
|
+
return response;
|
|
147
|
+
if (this.tableResults.size >= 20)
|
|
148
|
+
this.tableResults.delete(this.tableResults.keys().next().value);
|
|
149
|
+
this.tableResults.set(response.data.result_id, metadata);
|
|
150
|
+
return { ...response, data: { ...response.data, table, sample_limit: limit, query } };
|
|
151
|
+
});
|
|
152
|
+
}
|
|
153
|
+
async planTableUpdate(token, changes, options = {}) {
|
|
154
|
+
return this.core.withCommandContext({ signal: options.signal, origin: options.origin ?? "api" }, () => this.core.run("table.plan", async (session) => {
|
|
155
|
+
this.core.rejectDuringStagedTransaction(session, "Table edits");
|
|
156
|
+
const connection = this.core.requireConnection(session);
|
|
157
|
+
const original = this.liveEditToken(token, session, connection);
|
|
158
|
+
if (!original)
|
|
159
|
+
throw new StateQLError("STALE_PLAN", "Row identity expired or the connection changed. Reload the row.");
|
|
160
|
+
if (connection.read_only)
|
|
161
|
+
throw new StateQLError("READ_ONLY_CONNECTION", "This connection is read-only.");
|
|
162
|
+
const metadata = await this.editableMetadata(original.metadata.table, options);
|
|
163
|
+
if (JSON.stringify(metadata) !== JSON.stringify(original.metadata))
|
|
164
|
+
throw new StateQLError("STALE_PLAN", "Table metadata changed. Reload the table.");
|
|
165
|
+
const update = { metadata, original: original.original, changes };
|
|
166
|
+
const compiled = compileTableUpdate(update);
|
|
167
|
+
return runPlan(this.core, session, connection, tableEditPlan(compiled.sql, JSON.stringify(update), "table.update", original.expires), options);
|
|
168
|
+
}));
|
|
169
|
+
}
|
|
170
|
+
async planTableUpdates(changes, options = {}) {
|
|
171
|
+
return this.core.withCommandContext({ signal: options.signal, origin: options.origin ?? "api" }, () => this.core.run("table.plan", async (session) => {
|
|
172
|
+
this.core.rejectDuringStagedTransaction(session, "Table edits");
|
|
173
|
+
const bounded = Array.isArray(changes) &&
|
|
174
|
+
changes.length >= 1 &&
|
|
175
|
+
changes.length <= 100 &&
|
|
176
|
+
Buffer.byteLength(JSON.stringify(changes), "utf8") <= 256 * 1024;
|
|
177
|
+
if (!bounded)
|
|
178
|
+
throw new StateQLError("INVALID_COMMAND", "Table edit batch must contain 1-100 bounded rows.");
|
|
179
|
+
const connection = this.core.requireConnection(session);
|
|
180
|
+
if (connection.read_only)
|
|
181
|
+
throw new StateQLError("READ_ONLY_CONNECTION", "This connection is read-only.");
|
|
182
|
+
if (connection.driver === "redis")
|
|
183
|
+
throw new StateQLError("UNSUPPORTED_DRIVER", "Redis does not support table edits.");
|
|
184
|
+
const tokens = new Set();
|
|
185
|
+
const identities = new Set();
|
|
186
|
+
const updates = [];
|
|
187
|
+
let expires = Number.MAX_SAFE_INTEGER;
|
|
188
|
+
const metadataByTable = new Map();
|
|
189
|
+
for (const item of changes) {
|
|
190
|
+
if (!item || typeof item.row_token !== "string" || tokens.has(item.row_token))
|
|
191
|
+
throw new StateQLError("INVALID_COMMAND", "Table edit row tokens must be unique.");
|
|
192
|
+
tokens.add(item.row_token);
|
|
193
|
+
const original = this.liveEditToken(item.row_token, session, connection);
|
|
194
|
+
if (!original)
|
|
195
|
+
throw new StateQLError("STALE_PLAN", "A row identity expired or the connection changed. Reload the rows.");
|
|
196
|
+
const tableKey = JSON.stringify(original.metadata.table);
|
|
197
|
+
let metadata = metadataByTable.get(tableKey);
|
|
198
|
+
if (!metadata) {
|
|
199
|
+
metadata = await this.editableMetadata(original.metadata.table, options);
|
|
200
|
+
metadataByTable.set(tableKey, metadata);
|
|
201
|
+
}
|
|
202
|
+
if (JSON.stringify(metadata) !== JSON.stringify(original.metadata))
|
|
203
|
+
throw new StateQLError("STALE_PLAN", "Table metadata changed. Reload the table.");
|
|
204
|
+
const identity = tableUpdateIdentity(metadata, original.original);
|
|
205
|
+
if (identities.has(identity))
|
|
206
|
+
throw new StateQLError("INVALID_COMMAND", "The same row cannot appear twice in one edit batch.");
|
|
207
|
+
identities.add(identity);
|
|
208
|
+
const update = { metadata, original: original.original, changes: item.changes };
|
|
209
|
+
compileTableUpdate(update);
|
|
210
|
+
updates.push(update);
|
|
211
|
+
expires = Math.min(expires, original.expires);
|
|
212
|
+
}
|
|
213
|
+
return runPlan(this.core, session, connection, tableEditPlan(`Conditional table update batch (${updates.length} rows)`, JSON.stringify({ version: 1, updates }), "table.updates", expires), options);
|
|
214
|
+
}));
|
|
215
|
+
}
|
|
216
|
+
async editableMetadata(table, options) {
|
|
217
|
+
const connection = this.host.snapshot({ historyLimit: 1 }).connection;
|
|
218
|
+
const driver = connection.driver;
|
|
219
|
+
const unavailable = { table, driver, columns: [], writable: false, reason: "This table or its values cannot be edited safely." };
|
|
220
|
+
// The legacy inspection API splits qualified names. Fail closed for ambiguous names.
|
|
221
|
+
if (table.name.includes(".") || table.schema?.includes("."))
|
|
222
|
+
return { ...unavailable, reason: "Editing identifiers containing dots is not supported." };
|
|
223
|
+
const name = driver === "sqlite" || driver === "mongodb" ? table.name : [table.schema, table.name].filter(Boolean).join(".");
|
|
224
|
+
const response = await this.host.inspect("editable", name, options);
|
|
225
|
+
if (!response.ok)
|
|
226
|
+
return { ...unavailable, reason: response.error.code };
|
|
227
|
+
const value = response.data;
|
|
228
|
+
if (!value || !Array.isArray(value.columns) || value.columns.length > 100)
|
|
229
|
+
return unavailable;
|
|
230
|
+
return {
|
|
231
|
+
table,
|
|
232
|
+
driver,
|
|
233
|
+
columns: value.columns,
|
|
234
|
+
writable: value.writable === true && !connection.read_only,
|
|
235
|
+
...(value.writable ? {} : { reason: "Only ordinary tables with transactional writes and a primary key can be edited." }),
|
|
236
|
+
};
|
|
237
|
+
}
|
|
238
|
+
issueEditToken(metadata, row, result) {
|
|
239
|
+
const now = this.core.now().getTime();
|
|
240
|
+
for (const [key, entry] of this.editTokens)
|
|
241
|
+
if (entry.expires <= now)
|
|
242
|
+
this.editTokens.delete(key);
|
|
243
|
+
if (this.editTokens.size >= 1000)
|
|
244
|
+
this.editTokens.delete(this.editTokens.keys().next().value);
|
|
245
|
+
const token = randomUUID();
|
|
246
|
+
this.editTokens.set(token, {
|
|
247
|
+
metadata,
|
|
248
|
+
original: structuredClone(row),
|
|
249
|
+
sessionId: result.session_id,
|
|
250
|
+
connectionId: result.connection_id,
|
|
251
|
+
stateVersion: result.state_version,
|
|
252
|
+
expires: now + EDIT_TOKEN_TTL_MS,
|
|
253
|
+
});
|
|
254
|
+
return token;
|
|
255
|
+
}
|
|
256
|
+
liveEditToken(token, session, connection) {
|
|
257
|
+
const entry = this.editTokens.get(token);
|
|
258
|
+
const live = entry !== undefined &&
|
|
259
|
+
entry.sessionId === session.id &&
|
|
260
|
+
entry.connectionId === connection.id &&
|
|
261
|
+
entry.stateVersion === version(connection) &&
|
|
262
|
+
entry.expires > this.core.now().getTime();
|
|
263
|
+
return live ? entry : undefined;
|
|
264
|
+
}
|
|
265
|
+
panelResult(id) {
|
|
266
|
+
if (typeof id !== "string" || !id || id.length > 200)
|
|
267
|
+
throw new StateQLError("INVALID_COMMAND", "A result ID is required.");
|
|
268
|
+
const session = this.core.store.ensureSession(this.core.sessionName);
|
|
269
|
+
if (!this.core.store.isSessionMember(session.id, this.core.actorId))
|
|
270
|
+
this.core.throwMembershipDenied(session);
|
|
271
|
+
const result = this.core.requireResult(id, session);
|
|
272
|
+
if (result.id !== id)
|
|
273
|
+
throw new StateQLError("INVALID_COMMAND", "Use an immutable result ID, not an alias.");
|
|
274
|
+
if (Date.parse(result.expires_at) <= this.core.now().getTime())
|
|
275
|
+
throw new StateQLError("RESULT_EXPIRED", "Result expired. Run the query again.");
|
|
276
|
+
if (result.row_count > 10_000 || Buffer.byteLength(result.rows_json, "utf8") > 16 * 1024 * 1024) {
|
|
277
|
+
throw new StateQLError("OUTPUT_LIMIT_EXCEEDED", "Stored result exceeds browser limits.");
|
|
278
|
+
}
|
|
279
|
+
return result;
|
|
280
|
+
}
|
|
281
|
+
fullResultRows(result) {
|
|
282
|
+
if (this.panelRows?.id !== result.id || this.panelRows.json !== result.rows_json) {
|
|
283
|
+
this.panelRows = { id: result.id, json: result.rows_json, rows: this.core.store.resultRows(result) };
|
|
284
|
+
}
|
|
285
|
+
return this.panelRows.rows;
|
|
286
|
+
}
|
|
287
|
+
}
|
|
288
|
+
function tableEditPlan(descriptor, payload, statementType, expires) {
|
|
289
|
+
return {
|
|
290
|
+
descriptor,
|
|
291
|
+
parameters: [payload],
|
|
292
|
+
statementType,
|
|
293
|
+
destructive: false,
|
|
294
|
+
allowUnbounded: false,
|
|
295
|
+
allowDestructive: false,
|
|
296
|
+
requiredOverrides: [],
|
|
297
|
+
requiresConfirmation: true,
|
|
298
|
+
expiresAt: new Date(expires).toISOString(),
|
|
299
|
+
};
|
|
300
|
+
}
|
|
301
|
+
function validTableName(table) {
|
|
302
|
+
const validPart = (value) => typeof value === "string" && value.length > 0 && value.length <= 500 && !value.includes("\0");
|
|
303
|
+
return Boolean(table) && validPart(table.name) && (table.schema === undefined || validPart(table.schema));
|
|
304
|
+
}
|
|
305
|
+
function tableUpdateIdentity(metadata, row) {
|
|
306
|
+
const identity = metadata.driver === "mongodb"
|
|
307
|
+
? { table: metadata.table, id: row._id }
|
|
308
|
+
: {
|
|
309
|
+
table: metadata.table,
|
|
310
|
+
keys: metadata.columns
|
|
311
|
+
.filter((column) => column.key > 0)
|
|
312
|
+
.sort((a, b) => a.key - b.key)
|
|
313
|
+
.map((column) => [column.name, row[column.name]]),
|
|
314
|
+
};
|
|
315
|
+
return hash(identity);
|
|
316
|
+
}
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import type { DatabaseAdapter } from "./adapters.js";
|
|
2
|
+
import { type ActionResult, type Core } from "./core.js";
|
|
3
|
+
import type { ConnectionRecord, SessionRecord } from "./store.js";
|
|
4
|
+
import { type EditableTable, type TableIdentity } from "./table-editor.js";
|
|
5
|
+
import type { ApplyData, ExecutionOptions, PlanData, PlanOptions, MongoPlanOptions, SqlParameters } from "./types.js";
|
|
6
|
+
interface PlanMeasurement {
|
|
7
|
+
parameters?: SqlParameters;
|
|
8
|
+
estimatedRows?: number;
|
|
9
|
+
}
|
|
10
|
+
/** A validated plan for one driver; runPlan records it against the current database state. */
|
|
11
|
+
export interface PlanStatement {
|
|
12
|
+
descriptor: string;
|
|
13
|
+
parameters: SqlParameters;
|
|
14
|
+
statementType: string;
|
|
15
|
+
destructive: boolean;
|
|
16
|
+
allowUnbounded: boolean;
|
|
17
|
+
allowDestructive: boolean;
|
|
18
|
+
requiredOverrides: string[];
|
|
19
|
+
requiresConfirmation: boolean;
|
|
20
|
+
expiresAt?: string;
|
|
21
|
+
measure?(adapter: DatabaseAdapter): Promise<PlanMeasurement>;
|
|
22
|
+
}
|
|
23
|
+
export type EditableMetadata = (table: TableIdentity, options: ExecutionOptions) => Promise<EditableTable>;
|
|
24
|
+
export declare function prepareSqlPlan(connection: ConnectionRecord, sql: string, options: PlanOptions): PlanStatement;
|
|
25
|
+
export declare function prepareMongoPlan(command: unknown, options: MongoPlanOptions): PlanStatement;
|
|
26
|
+
export declare function prepareRedisPlan(command: unknown): PlanStatement;
|
|
27
|
+
/** Saves a plan bound to the current state version and database signature. */
|
|
28
|
+
export declare function runPlan(core: Core, session: SessionRecord, connection: ConnectionRecord, statement: PlanStatement, options: ExecutionOptions): Promise<ActionResult<PlanData>>;
|
|
29
|
+
/** Applies a plan once, only if the connection and database state still match it. */
|
|
30
|
+
export declare function applyPlan(core: Core, session: SessionRecord, planId: string, options: ExecutionOptions, editableMetadata: EditableMetadata, recordSql: (sql: string | undefined) => void): Promise<ActionResult<ApplyData>>;
|
|
31
|
+
export {};
|