@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.
@@ -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
+ }
@@ -1,4 +1,5 @@
1
- import { type AdapterContext } from "./adapters.js";
1
+ import type { BaseAdapter } from "./adapters.js";
2
+ import { type AdapterContext } from "./execution.js";
2
3
  import type { CatalogObject, DescribeObjectData, ListObjectsData, ListObjectsFilter, RedisCommand, RedisWriteOutcome, Row, Column } from "./types.js";
3
4
  export interface RedisReadResult {
4
5
  rows: Row[];
@@ -19,9 +20,10 @@ export declare function validateRedisReadCommand(value: unknown): RedisCommand;
19
20
  export declare function validateRedisWriteCommand(value: unknown): RedisCommand;
20
21
  export declare function serializeRedisCommand(command: RedisCommand): string;
21
22
  export declare function deserializeRedisCommand(value: string): RedisCommand;
22
- export declare class RedisAdapter {
23
+ export declare class RedisAdapter implements BaseAdapter {
23
24
  private readonly readOnly;
24
25
  private readonly context;
26
+ readonly kind: "redis";
25
27
  readonly confidence: "ttl_based";
26
28
  private readonly client;
27
29
  private connected;
package/dist/src/redis.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import { createRequire } from "node:module";
2
- import { AdapterExecutionError, AdapterWriteError } from "./adapters.js";
2
+ import { AdapterExecutionError, AdapterWriteError, remainingMilliseconds, throwIfStopped, withContext, } from "./execution.js";
3
3
  import { hash, toJsonSafe } from "./util.js";
4
4
  const require = createRequire(import.meta.url);
5
5
  let redisModule;
@@ -101,6 +101,7 @@ export function deserializeRedisCommand(value) {
101
101
  export class RedisAdapter {
102
102
  readOnly;
103
103
  context;
104
+ kind = "redis";
104
105
  confidence = "ttl_based";
105
106
  client;
106
107
  connected = false;
@@ -166,7 +167,7 @@ export class RedisAdapter {
166
167
  const transaction = this.client.multi();
167
168
  transaction.addCommand([command.command, ...(command.args ?? [])]);
168
169
  dispatched = true;
169
- const result = await withDeadline(transaction.exec(), this.context, true, () => this.stop());
170
+ const result = await withContext(transaction.exec(), this.context, () => this.stop(), true);
170
171
  if (result === null)
171
172
  throw new AdapterWriteError("ROW_CONFLICT: The Redis key changed. Reload before editing.", false);
172
173
  raw = result[0];
@@ -277,7 +278,7 @@ export class RedisAdapter {
277
278
  }
278
279
  const [type, dump] = await Promise.all([
279
280
  this.execute(["TYPE", key], false),
280
- withDeadline(this.client.sendCommand(["DUMP", key], { typeMapping: { [redis().RESP_TYPES.BLOB_STRING]: Buffer } }), this.context, false, () => this.stop()),
281
+ withContext(this.client.sendCommand(["DUMP", key], { typeMapping: { [redis().RESP_TYPES.BLOB_STRING]: Buffer } }), this.context, () => this.stop(), false),
281
282
  ]);
282
283
  const encoded = Buffer.isBuffer(dump) ? dump.toString("base64") : dump;
283
284
  if (Buffer.byteLength(JSON.stringify(encoded), "utf8") > MAX_RESPONSE_BYTES * 2) {
@@ -291,12 +292,12 @@ export class RedisAdapter {
291
292
  throw new Error("Redis adapter is closed.");
292
293
  if (this.connected)
293
294
  return;
294
- await withDeadline(this.client.connect(), this.context, false, () => this.stop());
295
+ await withContext(this.client.connect(), this.context, () => this.stop(), false);
295
296
  this.connected = true;
296
297
  }
297
298
  async execute(command, outcomeUnknown) {
298
299
  throwIfStopped(this.context, outcomeUnknown);
299
- return withDeadline(this.client.sendCommand(command), this.context, outcomeUnknown, () => this.stop());
300
+ return withContext(this.client.sendCommand(command), this.context, () => this.stop(), outcomeUnknown);
300
301
  }
301
302
  stop() { if (this.client.isOpen)
302
303
  this.client.destroy(); this.closed = true; }
@@ -343,7 +344,7 @@ function boundedRange(startText, stopText) {
343
344
  function boundedLimit(value) { const limit = value ?? 50; if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_COLLECTION_VALUES)
344
345
  throw new Error(`limit must be 1-${MAX_COLLECTION_VALUES}.`); return limit; }
345
346
  function escapeGlob(value) { if (!value || value.length > 200 || value.includes("\0"))
346
- throw new Error("Redis search must be 1-200 characters."); return value.replace(/[\\*?\[\]]/g, "\\$&"); }
347
+ throw new Error("Redis search must be 1-200 characters."); return value.replace(/[\\*?[\]]/g, "\\$&"); }
347
348
  function redisRows(command, raw) {
348
349
  if (["SCAN", "HSCAN", "SSCAN", "ZSCAN"].includes(command.command)) {
349
350
  if (!Array.isArray(raw) || raw.length !== 2 || !Array.isArray(raw[1]))
@@ -368,31 +369,4 @@ function normalizeScalar(value) { if (value === null || typeof value === "string
368
369
  return value; return JSON.stringify(toJsonSafe(value)); }
369
370
  function redisAffectedRows(command, result) { if (typeof result === "number")
370
371
  return result; return command === "SET" && result === "OK" ? 1 : 0; }
371
- function remainingMilliseconds(context) { const remaining = context.deadline - Date.now(); if (remaining <= 0)
372
- throw new AdapterExecutionError("Database operation timed out.", "timeout", false); return Math.min(remaining, 2_147_483_647); }
373
- function throwIfStopped(context, outcomeUnknown) { if (context.signal?.aborted)
374
- throw new AdapterExecutionError("Database operation was cancelled.", "aborted", outcomeUnknown); if (context.deadline <= Date.now())
375
- throw new AdapterExecutionError("Database operation timed out.", "timeout", outcomeUnknown); }
376
- async function withDeadline(promise, context, outcomeUnknown, stop) {
377
- throwIfStopped(context, outcomeUnknown);
378
- let timer;
379
- let abort;
380
- const stopped = new Promise((_, reject) => {
381
- timer = setTimeout(() => { stop(); reject(new AdapterExecutionError("Database operation timed out.", "timeout", outcomeUnknown)); }, remainingMilliseconds(context));
382
- timer.unref();
383
- if (context.signal) {
384
- abort = () => { stop(); reject(new AdapterExecutionError("Database operation was cancelled.", "aborted", outcomeUnknown)); };
385
- context.signal.addEventListener("abort", abort, { once: true });
386
- }
387
- });
388
- try {
389
- return await Promise.race([promise, stopped]);
390
- }
391
- finally {
392
- if (timer)
393
- clearTimeout(timer);
394
- if (abort && context.signal)
395
- context.signal.removeEventListener("abort", abort);
396
- }
397
- }
398
372
  function errorText(error) { return error instanceof Error ? error.message : String(error); }
@@ -5,4 +5,5 @@ export declare function profileData(profile: ProfileRecord): ProfileData;
5
5
  export declare function operationData(operation: OperationRecord): OperationData;
6
6
  export declare function transactionData(transaction: TransactionRecord, statements: number): TransactionData;
7
7
  export declare function paginationWarnings(ordered: boolean): Warning[];
8
+ export declare function csvCell(value: unknown): string;
8
9
  export declare function rowsToCsv(rows: Row[], columns: string[]): string;
@@ -66,17 +66,20 @@ export function paginationWarnings(ordered) {
66
66
  },
67
67
  ];
68
68
  }
69
+ export function csvCell(value) {
70
+ let text = value === null || value === undefined
71
+ ? ""
72
+ : typeof value === "object"
73
+ ? JSON.stringify(value)
74
+ : String(value);
75
+ // Spreadsheets evaluate cells that start like a formula; a leading quote keeps them text.
76
+ if (typeof value !== "number" && /^[\s\u0000-\u001f]*[=+@-]|^[\t\r\n]/u.test(text))
77
+ text = `'${text}`;
78
+ return /[",\r\n]/u.test(text) ? `"${text.replaceAll('"', '""')}"` : text;
79
+ }
69
80
  export function rowsToCsv(rows, columns) {
70
- const encode = (value) => {
71
- const text = value === null || value === undefined
72
- ? ""
73
- : typeof value === "object"
74
- ? JSON.stringify(value)
75
- : String(value);
76
- return /[",\r\n]/.test(text) ? `"${text.replaceAll('"', '""')}"` : text;
77
- };
78
81
  return [
79
- columns.map(encode).join(","),
80
- ...rows.map((row) => columns.map((column) => encode(row[column])).join(",")),
82
+ columns.map(csvCell).join(","),
83
+ ...rows.map((row) => columns.map((column) => csvCell(row[column])).join(",")),
81
84
  ].join("\n") + "\n";
82
85
  }
@@ -0,0 +1,10 @@
1
+ import { type ActionResult, type Core } from "./core.js";
2
+ import type { ResultRecord } from "./store.js";
3
+ import type { ColumnsData, CountData, ExportData, FilterOptions, ResultData, RowsData, RowsOptions, SummaryData } from "./types.js";
4
+ export declare function showResult(core: Core, result: ResultRecord): ActionResult<ResultData>;
5
+ export declare function filterResult(core: Core, source: ResultRecord, predicate: string, options: FilterOptions): ActionResult<ResultData>;
6
+ export declare function resultRows(core: Core, result: ResultRecord, options: RowsOptions): ActionResult<RowsData>;
7
+ export declare function countResult(result: ResultRecord): ActionResult<CountData>;
8
+ export declare function resultColumns(core: Core, result: ResultRecord): ActionResult<ColumnsData>;
9
+ export declare function summarizeResult(core: Core, result: ResultRecord): ActionResult<SummaryData>;
10
+ export declare function exportResult(core: Core, result: ResultRecord, output: string, format: "json" | "jsonl" | "csv", columns: string[] | undefined): ActionResult<ExportData>;