@fadhilp/stateql 0.17.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.
@@ -1,6 +1,6 @@
1
1
  import { createRequire } from "node:module";
2
2
  import { BSON } from "bson";
3
- import { AdapterExecutionError, AdapterWriteError, BatchWriteError, } from "./adapters.js";
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) ? false : true);
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.signal?.aborted || context.deadline <= Date.now()) {
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.signal?.aborted || context.deadline <= Date.now()) {
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 {};