@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.
- 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/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/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,275 @@
|
|
|
1
|
+
import { version } from "./connection.js";
|
|
2
|
+
import { adapterOfKind, rejectSqlOnNativeConnection, } from "./core.js";
|
|
3
|
+
import { StateQLError } from "./errors.js";
|
|
4
|
+
import { AdapterExecutionError } from "./execution.js";
|
|
5
|
+
import { analyzeMongoWriteSafety, serializeMongoCommand, validateMongoWriteCommand } from "./mongodb.js";
|
|
6
|
+
import { invalidCommand, mongoDescriptor, redisDescriptor } from "./reads.js";
|
|
7
|
+
import { deserializeRedisCommand, serializeRedisCommand, validateRedisWriteCommand, } from "./redis.js";
|
|
8
|
+
import { analyzeSql, matchedRowsCount } from "./sql.js";
|
|
9
|
+
import { compileTableUpdate, parseTableUpdate, parseTableUpdates, } from "./table-editor.js";
|
|
10
|
+
import { isSqlParameters, parseJson } from "./util.js";
|
|
11
|
+
import { prepareMongoWrite, prepareRedisWrite, prepareSqlWrite, prepareTableBatch, runWrite, storedMongoWrite, } from "./writes.js";
|
|
12
|
+
const PLAN_TTL_MS = 10 * 60_000;
|
|
13
|
+
export function prepareSqlPlan(connection, sql, options) {
|
|
14
|
+
const analysis = analyzeSql(sql, connection.driver);
|
|
15
|
+
if (analysis.read) {
|
|
16
|
+
throw new StateQLError("INVALID_SQL", "plan accepts write statements only.");
|
|
17
|
+
}
|
|
18
|
+
const parameters = options.params ?? [];
|
|
19
|
+
return {
|
|
20
|
+
...guardedPlan(analysis.unboundedMutation, analysis.destructive, options),
|
|
21
|
+
descriptor: sql,
|
|
22
|
+
parameters,
|
|
23
|
+
statementType: analysis.statementType,
|
|
24
|
+
async measure(adapter) {
|
|
25
|
+
const count = matchedRowsCount(analysis, parameters, connection.driver);
|
|
26
|
+
return { estimatedRows: await countMatchedRows(adapterOfKind(adapter, "sql"), count) };
|
|
27
|
+
},
|
|
28
|
+
};
|
|
29
|
+
}
|
|
30
|
+
export function prepareMongoPlan(command, options) {
|
|
31
|
+
const value = invalidCommand(() => validateMongoWriteCommand(command));
|
|
32
|
+
const unsafe = analyzeMongoWriteSafety(value);
|
|
33
|
+
return {
|
|
34
|
+
...guardedPlan(unsafe.unbounded, unsafe.destructive, options),
|
|
35
|
+
descriptor: mongoDescriptor(value.operation),
|
|
36
|
+
parameters: [serializeMongoCommand(value)],
|
|
37
|
+
statementType: `mongo.${value.operation}`,
|
|
38
|
+
};
|
|
39
|
+
}
|
|
40
|
+
export function prepareRedisPlan(command) {
|
|
41
|
+
const value = invalidCommand(() => validateRedisWriteCommand(command));
|
|
42
|
+
return {
|
|
43
|
+
descriptor: redisDescriptor(value.command),
|
|
44
|
+
parameters: [],
|
|
45
|
+
statementType: `redis.${value.command.toLowerCase()}`,
|
|
46
|
+
destructive: value.command === "DEL",
|
|
47
|
+
allowUnbounded: false,
|
|
48
|
+
allowDestructive: true,
|
|
49
|
+
requiredOverrides: [],
|
|
50
|
+
requiresConfirmation: true,
|
|
51
|
+
async measure(adapter) {
|
|
52
|
+
const precondition = await adapterOfKind(adapter, "redis").precondition(value);
|
|
53
|
+
return { parameters: [JSON.stringify({ command: serializeRedisCommand(value), precondition })] };
|
|
54
|
+
},
|
|
55
|
+
};
|
|
56
|
+
}
|
|
57
|
+
/** Saves a plan bound to the current state version and database signature. */
|
|
58
|
+
export async function runPlan(core, session, connection, statement, options) {
|
|
59
|
+
const context = core.executionContext(options);
|
|
60
|
+
return core.withAdapter(session, connection, "plan", context, async (adapter) => {
|
|
61
|
+
const stateSignature = await adapter.signature();
|
|
62
|
+
const measured = await statement.measure?.(adapter) ?? {};
|
|
63
|
+
const plan = core.store.savePlan({
|
|
64
|
+
sessionId: session.id,
|
|
65
|
+
ownerActorId: core.actorId,
|
|
66
|
+
connectionId: connection.id,
|
|
67
|
+
sql: statement.descriptor,
|
|
68
|
+
parameters: measured.parameters ?? statement.parameters,
|
|
69
|
+
statementType: statement.statementType,
|
|
70
|
+
stateVersion: version(connection),
|
|
71
|
+
stateSignature,
|
|
72
|
+
destructive: statement.destructive,
|
|
73
|
+
allowUnbounded: statement.allowUnbounded,
|
|
74
|
+
allowDestructive: statement.allowDestructive,
|
|
75
|
+
expiresAt: statement.expiresAt ?? core.expiresAt(PLAN_TTL_MS),
|
|
76
|
+
});
|
|
77
|
+
return {
|
|
78
|
+
data: {
|
|
79
|
+
plan_id: plan.id,
|
|
80
|
+
statement_type: plan.statement_type,
|
|
81
|
+
destructive: Boolean(plan.destructive),
|
|
82
|
+
requires_confirmation: statement.requiresConfirmation,
|
|
83
|
+
required_overrides: statement.requiredOverrides,
|
|
84
|
+
state_version: plan.state_version,
|
|
85
|
+
owner_actor_id: plan.owner_actor_id,
|
|
86
|
+
expires_at: plan.expires_at,
|
|
87
|
+
...(measured.estimatedRows === undefined ? {} : { estimated_rows: measured.estimatedRows }),
|
|
88
|
+
},
|
|
89
|
+
handle: plan.id,
|
|
90
|
+
executed: true,
|
|
91
|
+
stateVersion: plan.state_version,
|
|
92
|
+
confidence: adapter.confidence,
|
|
93
|
+
};
|
|
94
|
+
});
|
|
95
|
+
}
|
|
96
|
+
/** Applies a plan once, only if the connection and database state still match it. */
|
|
97
|
+
export async function applyPlan(core, session, planId, options, editableMetadata, recordSql) {
|
|
98
|
+
core.rejectDuringStagedTransaction(session, "Plans");
|
|
99
|
+
const plan = core.store.getPlan(planId);
|
|
100
|
+
if (!plan || plan.session_id !== session.id) {
|
|
101
|
+
throw new StateQLError("STALE_PLAN", `Plan "${planId}" was not found.`);
|
|
102
|
+
}
|
|
103
|
+
if (plan.owner_actor_id !== core.actorId) {
|
|
104
|
+
throw new StateQLError("PERMISSION_DENIED", "Only the actor that created this plan may apply it.");
|
|
105
|
+
}
|
|
106
|
+
if (plan.applied_operation_id) {
|
|
107
|
+
throw new StateQLError("STALE_PLAN", "Plan was already applied.", {
|
|
108
|
+
extra: { previous_operation_id: plan.applied_operation_id },
|
|
109
|
+
});
|
|
110
|
+
}
|
|
111
|
+
if (Date.parse(plan.expires_at) <= core.now().getTime()) {
|
|
112
|
+
throw new StateQLError("STALE_PLAN", "Plan has expired.");
|
|
113
|
+
}
|
|
114
|
+
const tableMetadata = storedTableMetadata(plan);
|
|
115
|
+
const stored = storedPlan(plan);
|
|
116
|
+
const targetDriver = tableMetadata[0]?.driver === "mongodb" || stored.kind === "mongo"
|
|
117
|
+
? "mongodb"
|
|
118
|
+
: stored.kind === "redis" ? "redis" : "sql";
|
|
119
|
+
recordSql(stored.kind === "sql" ? plan.sql : undefined);
|
|
120
|
+
const claimToken = core.store.randomId("claim");
|
|
121
|
+
const claimed = core.store.claimPlan(plan.id, session.id, core.actorId, claimToken);
|
|
122
|
+
if (!claimed)
|
|
123
|
+
throw new StateQLError("STALE_PLAN", "Plan is already being applied.");
|
|
124
|
+
let retainClaim = false;
|
|
125
|
+
try {
|
|
126
|
+
const connection = core.requireConnection(session);
|
|
127
|
+
const stateChanged = connection.id !== claimed.connection_id || version(connection) !== claimed.state_version;
|
|
128
|
+
if (stateChanged) {
|
|
129
|
+
throw new StateQLError("STALE_PLAN", "Database state changed after this plan was created.");
|
|
130
|
+
}
|
|
131
|
+
if (targetDriver === "mongodb" && connection.driver !== "mongodb") {
|
|
132
|
+
throw new StateQLError("STALE_PLAN", "MongoDB plan is not attached to a MongoDB connection.");
|
|
133
|
+
}
|
|
134
|
+
if (targetDriver === "redis" && connection.driver !== "redis") {
|
|
135
|
+
throw new StateQLError("STALE_PLAN", "Redis plan is not attached to a Redis connection.");
|
|
136
|
+
}
|
|
137
|
+
if (targetDriver === "sql")
|
|
138
|
+
rejectSqlOnNativeConnection(connection, "plan");
|
|
139
|
+
for (const metadata of tableMetadata) {
|
|
140
|
+
const current = await editableMetadata(metadata.table, options);
|
|
141
|
+
if (JSON.stringify(current) !== JSON.stringify(metadata)) {
|
|
142
|
+
throw new StateQLError("STALE_PLAN", "Table metadata changed. Reload and plan again.");
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
const context = core.executionContext(options);
|
|
146
|
+
const source = await core.resolveConnectionSource(connection, session, "apply", "write", context);
|
|
147
|
+
await core.runOnAdapter(connection, context, source, async (adapter) => {
|
|
148
|
+
if ((await adapter.signature()) !== claimed.state_signature) {
|
|
149
|
+
throw new StateQLError("STALE_PLAN", "Database state changed after this plan was created.");
|
|
150
|
+
}
|
|
151
|
+
});
|
|
152
|
+
const statement = plannedWrite(connection, claimed, stored);
|
|
153
|
+
const result = await runWrite(core, session, connection, statement, { replay: stored.kind === "table-batch" }, context, { planId: claimed.id, claimToken, source });
|
|
154
|
+
return { ...result, data: { plan_id: claimed.id, ...result.data } };
|
|
155
|
+
}
|
|
156
|
+
catch (error) {
|
|
157
|
+
if (error instanceof StateQLError && error.details.code === "OUTCOME_UNKNOWN")
|
|
158
|
+
retainClaim = true;
|
|
159
|
+
throw error;
|
|
160
|
+
}
|
|
161
|
+
finally {
|
|
162
|
+
if (!retainClaim)
|
|
163
|
+
core.store.releasePlanClaim(plan.id, claimToken);
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
function guardedPlan(unbounded, destructive, options) {
|
|
167
|
+
const allowUnbounded = options.allowUnbounded ?? false;
|
|
168
|
+
const allowDestructive = options.allowDestructive ?? false;
|
|
169
|
+
const requiredOverrides = [
|
|
170
|
+
...(unbounded && !allowUnbounded ? ["--allow-unbounded"] : []),
|
|
171
|
+
...(destructive && !allowDestructive ? ["--allow-destructive"] : []),
|
|
172
|
+
];
|
|
173
|
+
return {
|
|
174
|
+
destructive: destructive || unbounded,
|
|
175
|
+
allowUnbounded,
|
|
176
|
+
allowDestructive,
|
|
177
|
+
requiredOverrides,
|
|
178
|
+
requiresConfirmation: requiredOverrides.length > 0,
|
|
179
|
+
};
|
|
180
|
+
}
|
|
181
|
+
function storedTableMetadata(plan) {
|
|
182
|
+
if (plan.statement_type === "table.update")
|
|
183
|
+
return [parseTableUpdate(plan.parameters).metadata];
|
|
184
|
+
if (plan.statement_type === "table.updates")
|
|
185
|
+
return parseTableUpdates(plan.parameters).map((update) => update.metadata);
|
|
186
|
+
return [];
|
|
187
|
+
}
|
|
188
|
+
function storedPlan(plan) {
|
|
189
|
+
if (plan.statement_type === "table.updates") {
|
|
190
|
+
const updates = parseTableUpdates(plan.parameters);
|
|
191
|
+
return { kind: "table-batch", updates, compiled: updates.map(compileTableUpdate) };
|
|
192
|
+
}
|
|
193
|
+
if (plan.statement_type === "table.update") {
|
|
194
|
+
const compiled = compileTableUpdate(parseTableUpdate(plan.parameters));
|
|
195
|
+
if (compiled.sql !== plan.sql)
|
|
196
|
+
throw new StateQLError("STALE_PLAN", "Stored update does not match its plan.");
|
|
197
|
+
if (compiled.mongo)
|
|
198
|
+
return { kind: "mongo", command: compiled.mongo, expectedRows: 1 };
|
|
199
|
+
return { kind: "sql", sql: plan.sql, parameters: compiled.params, expectedRows: 1 };
|
|
200
|
+
}
|
|
201
|
+
if (plan.statement_type.startsWith("mongo.")) {
|
|
202
|
+
return {
|
|
203
|
+
kind: "mongo",
|
|
204
|
+
command: storedMongoWrite(plan.parameters, plan.statement_type, `plan "${plan.id}"`, "STALE_PLAN"),
|
|
205
|
+
};
|
|
206
|
+
}
|
|
207
|
+
if (plan.statement_type.startsWith("redis.")) {
|
|
208
|
+
return { kind: "redis", ...storedRedisPlan(plan.parameters, plan.statement_type, plan.id) };
|
|
209
|
+
}
|
|
210
|
+
return {
|
|
211
|
+
kind: "sql",
|
|
212
|
+
sql: plan.sql,
|
|
213
|
+
parameters: parseJson(plan.parameters, `plan "${plan.id}" parameters`, isSqlParameters),
|
|
214
|
+
};
|
|
215
|
+
}
|
|
216
|
+
function plannedWrite(connection, claimed, stored) {
|
|
217
|
+
const safety = {
|
|
218
|
+
allowUnbounded: Boolean(claimed.allow_unbounded),
|
|
219
|
+
allowDestructive: Boolean(claimed.allow_destructive),
|
|
220
|
+
};
|
|
221
|
+
switch (stored.kind) {
|
|
222
|
+
case "sql":
|
|
223
|
+
return prepareSqlWrite(connection, claimed.sql, stored.parameters, {
|
|
224
|
+
...safety,
|
|
225
|
+
...(stored.expectedRows ? { expectedRows: stored.expectedRows } : {}),
|
|
226
|
+
});
|
|
227
|
+
case "mongo":
|
|
228
|
+
return prepareMongoWrite(connection, stored.command, {
|
|
229
|
+
...safety,
|
|
230
|
+
...(stored.expectedRows ? { expectedRows: stored.expectedRows } : {}),
|
|
231
|
+
});
|
|
232
|
+
case "redis":
|
|
233
|
+
return prepareRedisWrite(connection, stored.command, stored.precondition);
|
|
234
|
+
case "table-batch":
|
|
235
|
+
return prepareTableBatch(connection, claimed.id, stored.updates, stored.compiled);
|
|
236
|
+
}
|
|
237
|
+
}
|
|
238
|
+
function storedRedisPlan(parameters, statementType, planId) {
|
|
239
|
+
try {
|
|
240
|
+
const outer = JSON.parse(parameters);
|
|
241
|
+
if (!Array.isArray(outer) || outer.length !== 1 || typeof outer[0] !== "string")
|
|
242
|
+
throw new Error();
|
|
243
|
+
const payload = JSON.parse(outer[0]);
|
|
244
|
+
if (typeof payload.command !== "string" || !payload.precondition || typeof payload.precondition !== "object")
|
|
245
|
+
throw new Error();
|
|
246
|
+
const command = deserializeRedisCommand(payload.command);
|
|
247
|
+
const precondition = payload.precondition;
|
|
248
|
+
const valid = typeof precondition.key === "string" &&
|
|
249
|
+
typeof precondition.fingerprint === "string" &&
|
|
250
|
+
typeof precondition.expiresAt === "number" &&
|
|
251
|
+
Number.isFinite(precondition.expiresAt) &&
|
|
252
|
+
statementType === `redis.${command.command.toLowerCase()}`;
|
|
253
|
+
if (!valid)
|
|
254
|
+
throw new Error();
|
|
255
|
+
return { command, precondition };
|
|
256
|
+
}
|
|
257
|
+
catch {
|
|
258
|
+
throw new StateQLError("STALE_PLAN", `Stored Redis plan "${planId}" payload is invalid.`);
|
|
259
|
+
}
|
|
260
|
+
}
|
|
261
|
+
async function countMatchedRows(adapter, count) {
|
|
262
|
+
if (!count)
|
|
263
|
+
return undefined;
|
|
264
|
+
try {
|
|
265
|
+
const { rows } = await adapter.read(count.sql, count.params);
|
|
266
|
+
const value = Number(Object.values(rows[0] ?? {})[0]);
|
|
267
|
+
return Number.isSafeInteger(value) ? value : undefined;
|
|
268
|
+
}
|
|
269
|
+
catch (error) {
|
|
270
|
+
if (error instanceof AdapterExecutionError)
|
|
271
|
+
throw error;
|
|
272
|
+
// The estimate is advisory; a count the parser cannot express must not block the plan.
|
|
273
|
+
return undefined;
|
|
274
|
+
}
|
|
275
|
+
}
|
|
@@ -0,0 +1,35 @@
|
|
|
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 { Column, ExecutionOptions, ResultData, Row, SqlParameters, Warning } from "./types.js";
|
|
5
|
+
interface ReadOutput {
|
|
6
|
+
rows: Row[];
|
|
7
|
+
columns: Column[];
|
|
8
|
+
parameters?: SqlParameters;
|
|
9
|
+
}
|
|
10
|
+
/** A validated read for one driver; runRead does the caching, limits, and storage. */
|
|
11
|
+
export interface ReadStatement {
|
|
12
|
+
descriptor: string;
|
|
13
|
+
identity: Record<string, unknown>;
|
|
14
|
+
parameters: SqlParameters;
|
|
15
|
+
cacheable: boolean;
|
|
16
|
+
warnings: Warning[];
|
|
17
|
+
limitHint: string;
|
|
18
|
+
execute(adapter: DatabaseAdapter, fetchLimit: number): Promise<ReadOutput>;
|
|
19
|
+
}
|
|
20
|
+
export interface ReadOptions extends ExecutionOptions {
|
|
21
|
+
cache?: "auto" | "bypass" | "require";
|
|
22
|
+
previewRows?: number;
|
|
23
|
+
}
|
|
24
|
+
export declare function prepareSqlRead(connection: ConnectionRecord, sql: string, parameters: SqlParameters): ReadStatement;
|
|
25
|
+
export declare function prepareMongoRead(command: unknown): ReadStatement;
|
|
26
|
+
export declare function prepareRedisRead(command: unknown): ReadStatement;
|
|
27
|
+
/** Serves a valid cached result, or runs the read and stores the bounded result. */
|
|
28
|
+
export declare function runRead(core: Core, session: SessionRecord, connection: ConnectionRecord, statement: ReadStatement, options: ReadOptions): Promise<ActionResult<ResultData>>;
|
|
29
|
+
export declare function queryPreviewRows(value: number): number;
|
|
30
|
+
export declare function sqlParametersLength(parameters: SqlParameters): number;
|
|
31
|
+
export declare function mongoDescriptor(operation: string): string;
|
|
32
|
+
export declare function redisDescriptor(command: string): string;
|
|
33
|
+
/** Driver validators throw plain errors; callers see them as INVALID_COMMAND. */
|
|
34
|
+
export declare function invalidCommand<T>(validate: () => T): T;
|
|
35
|
+
export {};
|
|
@@ -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>;
|