@fadhilp/stateql 0.16.0 → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/dist/src/adapters.d.ts +17 -25
  2. package/dist/src/adapters.js +15 -95
  3. package/dist/src/agent-response.js +6 -1
  4. package/dist/src/catalog.d.ts +6 -0
  5. package/dist/src/catalog.js +52 -0
  6. package/dist/src/cli.js +76 -25
  7. package/dist/src/connect.d.ts +16 -0
  8. package/dist/src/connect.js +205 -0
  9. package/dist/src/core.d.ts +78 -0
  10. package/dist/src/core.js +477 -0
  11. package/dist/src/execution.d.ts +27 -0
  12. package/dist/src/execution.js +87 -0
  13. package/dist/src/filter.js +3 -1
  14. package/dist/src/index.d.ts +1 -1
  15. package/dist/src/migrations.d.ts +1 -1
  16. package/dist/src/mongodb.d.ts +4 -2
  17. package/dist/src/mongodb.js +5 -56
  18. package/dist/src/panel.d.ts +64 -0
  19. package/dist/src/panel.js +316 -0
  20. package/dist/src/plans.d.ts +31 -0
  21. package/dist/src/plans.js +275 -0
  22. package/dist/src/reads.d.ts +35 -0
  23. package/dist/src/reads.js +184 -0
  24. package/dist/src/redis.d.ts +4 -2
  25. package/dist/src/redis.js +7 -33
  26. package/dist/src/response-data.d.ts +1 -0
  27. package/dist/src/response-data.js +13 -10
  28. package/dist/src/results.d.ts +10 -0
  29. package/dist/src/results.js +153 -0
  30. package/dist/src/sql.d.ts +7 -1
  31. package/dist/src/sql.js +88 -8
  32. package/dist/src/sqlite-process.js +16 -9
  33. package/dist/src/stateql.d.ts +9 -59
  34. package/dist/src/stateql.js +170 -2597
  35. package/dist/src/table-editor.js +2 -2
  36. package/dist/src/transactions.d.ts +8 -0
  37. package/dist/src/transactions.js +186 -0
  38. package/dist/src/types.d.ts +20 -18
  39. package/dist/src/util.d.ts +1 -0
  40. package/dist/src/util.js +1 -1
  41. package/dist/src/writes.d.ts +48 -0
  42. package/dist/src/writes.js +320 -0
  43. package/docs/batch.md +2 -1
  44. package/docs/cli.md +15 -9
  45. package/docs/databases.md +4 -3
  46. package/docs/library.md +3 -1
  47. package/docs/results.md +17 -0
  48. package/docs/writes.md +6 -0
  49. package/package.json +5 -3
  50. package/skills/stateql/SKILL.md +14 -6
  51. package/skills/stateql/reference/writes.md +4 -1
@@ -101,7 +101,7 @@ export function parseTableUpdate(parameters) {
101
101
  if (!Array.isArray(outer) || outer.length !== 1 || typeof outer[0] !== "string" || outer[0].length > 128 * 1024)
102
102
  throw new Error();
103
103
  const update = JSON.parse(outer[0]);
104
- if (!update || !update.metadata || !["sqlite", "postgres", "mysql", "mongodb"].includes(update.metadata.driver) ||
104
+ if (!update?.metadata || !["sqlite", "postgres", "mysql", "mongodb"].includes(update.metadata.driver) ||
105
105
  !Array.isArray(update.metadata.columns) || update.metadata.columns.length > 100 ||
106
106
  !update.metadata.columns.every(column => typeof column.name === "string" && typeof column.type === "string" && typeof column.nullable === "boolean" && typeof column.generated === "boolean" && Number.isSafeInteger(column.key)) ||
107
107
  !update.original || !update.changes || typeof update.changes !== "object")
@@ -119,7 +119,7 @@ export function parseTableUpdates(parameters) {
119
119
  if (!Array.isArray(outer) || outer.length !== 1 || typeof outer[0] !== "string" || outer[0].length > 512 * 1024)
120
120
  throw new Error();
121
121
  const batch = JSON.parse(outer[0]);
122
- if (!batch || batch.version !== 1 || !Array.isArray(batch.updates) || batch.updates.length < 1 || batch.updates.length > 100)
122
+ if (batch?.version !== 1 || !Array.isArray(batch.updates) || batch.updates.length < 1 || batch.updates.length > 100)
123
123
  throw new Error();
124
124
  for (const update of batch.updates) {
125
125
  if (!update?.metadata || !["sqlite", "postgres", "mysql", "mongodb"].includes(update.metadata.driver) ||
@@ -0,0 +1,8 @@
1
+ import { type ActionResult, type Core } from "./core.js";
2
+ import type { SessionRecord } from "./store.js";
3
+ import type { CommitTransactionData, ExecutionOptions, RollbackTransactionData, TransactionData } from "./types.js";
4
+ export declare function beginTransaction(core: Core, session: SessionRecord, isolation: string | undefined): ActionResult<TransactionData>;
5
+ export declare function transactionStatus(core: Core, session: SessionRecord, id: string | undefined): ActionResult<TransactionData>;
6
+ /** Runs every staged write in one database transaction, then records the outcome. */
7
+ export declare function commitTransaction(core: Core, session: SessionRecord, id: string | undefined, options: ExecutionOptions): Promise<ActionResult<CommitTransactionData>>;
8
+ export declare function rollbackTransaction(core: Core, session: SessionRecord, id: string | undefined): ActionResult<RollbackTransactionData>;
@@ -0,0 +1,186 @@
1
+ import { version } from "./connection.js";
2
+ import { adapterOfKind, closeAdapterQuietly, safeCredentialErrorMessage, } from "./core.js";
3
+ import { StateQLError } from "./errors.js";
4
+ import { AdapterExecutionError, BatchWriteError, stoppedStateQLError, } from "./execution.js";
5
+ import { transactionData } from "./response-data.js";
6
+ import { storedMongoOperation } from "./writes.js";
7
+ const COMMIT_UNKNOWN_ACTION = "Inspect database state before issuing any replacement write.";
8
+ export function beginTransaction(core, session, isolation) {
9
+ const connection = core.requireConnection(session);
10
+ if (connection.driver === "redis") {
11
+ throw new StateQLError("UNSUPPORTED_DRIVER", "Redis does not support staged StateQL transactions; use redisPlan/apply for one guarded mutation.");
12
+ }
13
+ if (connection.read_only) {
14
+ throw new StateQLError("READ_ONLY_CONNECTION", "Cannot begin a write transaction on a read-only connection.");
15
+ }
16
+ if (session.active_transaction_id) {
17
+ throw new StateQLError("TRANSACTION_FAILED", `Transaction "${session.active_transaction_id}" is already active.`);
18
+ }
19
+ const transaction = core.store.createTransaction({
20
+ sessionId: session.id,
21
+ actorId: core.actorId,
22
+ connectionId: connection.id,
23
+ isolation: normalizeIsolation(isolation ?? (connection.driver === "mongodb" ? "snapshot" : "serializable"), connection.driver),
24
+ });
25
+ if (!transaction) {
26
+ throw new StateQLError("TRANSACTION_FAILED", "Another actor acquired the active transaction.");
27
+ }
28
+ return {
29
+ data: transactionData(transaction, 0),
30
+ handle: transaction.id,
31
+ executed: true,
32
+ stateVersion: transaction.start_version,
33
+ };
34
+ }
35
+ export function transactionStatus(core, session, id) {
36
+ const transactionId = id ?? session.active_transaction_id;
37
+ if (!transactionId) {
38
+ throw new StateQLError("TRANSACTION_NOT_FOUND", "No active transaction.");
39
+ }
40
+ const transaction = core.store.getTransaction(transactionId);
41
+ if (!transaction || transaction.session_id !== session.id) {
42
+ throw new StateQLError("TRANSACTION_NOT_FOUND", `Transaction "${transactionId}" was not found.`);
43
+ }
44
+ return {
45
+ data: transactionData(transaction, core.store.transactionOperations(transaction.id).length),
46
+ handle: transaction.id,
47
+ stateVersion: transaction.start_version,
48
+ };
49
+ }
50
+ /** Runs every staged write in one database transaction, then records the outcome. */
51
+ export async function commitTransaction(core, session, id, options) {
52
+ const transaction = core.requireActiveTransaction(session, id);
53
+ const connection = core.store.getConnection(transaction.connection_id);
54
+ if (!connection) {
55
+ throw new StateQLError("CONNECTION_NOT_FOUND", "Transaction connection was not found.");
56
+ }
57
+ if (version(connection) !== transaction.start_version) {
58
+ throw new StateQLError("TRANSACTION_FAILED", "Connection state changed after the transaction began.", { suggestedAction: "Roll back and begin a new transaction." });
59
+ }
60
+ // Validate durable payloads before opening a database adapter or changing the transaction state.
61
+ const operations = core.store.validatedTransactionOperations(transaction.id);
62
+ if (operations.some((operation) => operation.connection_id !== connection.id)) {
63
+ throw new StateQLError("TRANSACTION_FAILED", "Transaction contains writes staged for another connection.");
64
+ }
65
+ const mongoCommands = connection.driver === "mongodb"
66
+ ? operations.map(storedMongoOperation)
67
+ : undefined;
68
+ const sqlHasMongoWrites = !mongoCommands &&
69
+ operations.some((operation) => operation.statement_type.startsWith("mongo."));
70
+ if (sqlHasMongoWrites) {
71
+ throw new StateQLError("TRANSACTION_FAILED", "Transaction contains native MongoDB writes for a SQL connection.");
72
+ }
73
+ const context = core.executionContext(options);
74
+ const source = await core.resolveConnectionSource(connection, session, "transaction.commit", "write", context);
75
+ const adapter = await core.openAdapter(connection, context, source);
76
+ const markUnknown = () => markTransactionOutcomeUnknown(core.store, transaction.id, session.id, core.actorId);
77
+ const outcomeUnknown = (message) => new StateQLError("OUTCOME_UNKNOWN", message, {
78
+ executed: true,
79
+ suggestedAction: COMMIT_UNKNOWN_ACTION,
80
+ });
81
+ try {
82
+ if (!core.store.claimTransactionForCommit(transaction.id, session.id, core.actorId, operations)) {
83
+ throw new StateQLError("TRANSACTION_FAILED", "Transaction is no longer active.");
84
+ }
85
+ let results;
86
+ try {
87
+ results = mongoCommands
88
+ ? await adapterOfKind(adapter, "mongodb").writeBatch(mongoCommands, transaction.isolation_level)
89
+ : await adapterOfKind(adapter, "sql").writeBatch(operations, transaction.isolation_level);
90
+ }
91
+ catch (error) {
92
+ const definite = (error instanceof BatchWriteError || error instanceof AdapterExecutionError) &&
93
+ !error.outcomeUnknown;
94
+ if (!definite) {
95
+ markUnknown();
96
+ throw outcomeUnknown(safeCredentialErrorMessage(error, source));
97
+ }
98
+ core.store.finishTransaction(transaction.id, session.id, core.actorId, "failed");
99
+ if (error instanceof AdapterExecutionError)
100
+ throw stoppedStateQLError(error, false);
101
+ throw new StateQLError("TRANSACTION_FAILED", safeCredentialErrorMessage(error, source), { retryable: true });
102
+ }
103
+ if (results.length !== operations.length) {
104
+ markUnknown();
105
+ throw outcomeUnknown("Database returned an incomplete transaction result.");
106
+ }
107
+ let stateVersion;
108
+ try {
109
+ stateVersion = core.store.commitTransactionMetadata({
110
+ transactionId: transaction.id,
111
+ sessionId: session.id,
112
+ actorId: core.actorId,
113
+ connectionId: connection.id,
114
+ operations: operations.map((operation, index) => ({
115
+ id: operation.id,
116
+ affectedRows: results[index].affectedRows,
117
+ ...(results[index].outcome ? { outcome: results[index].outcome } : {}),
118
+ })),
119
+ });
120
+ }
121
+ catch (error) {
122
+ markUnknown();
123
+ throw outcomeUnknown(safeCredentialErrorMessage(error, source));
124
+ }
125
+ return {
126
+ data: {
127
+ transaction_id: transaction.id,
128
+ state: "committed",
129
+ statements_executed: operations.length,
130
+ affected_rows: results.reduce((total, result) => total + result.affectedRows, 0),
131
+ state_version: stateVersion,
132
+ },
133
+ handle: transaction.id,
134
+ executed: true,
135
+ stateVersion,
136
+ confidence: adapter.confidence,
137
+ };
138
+ }
139
+ finally {
140
+ await closeAdapterQuietly(adapter);
141
+ }
142
+ }
143
+ export function rollbackTransaction(core, session, id) {
144
+ const transaction = core.requireActiveTransaction(session, id);
145
+ const count = core.store.transactionOperations(transaction.id).length;
146
+ if (!core.store.finishTransaction(transaction.id, session.id, core.actorId, "rolled_back")) {
147
+ throw new StateQLError("TRANSACTION_FAILED", "Transaction is no longer active.");
148
+ }
149
+ return {
150
+ data: {
151
+ transaction_id: transaction.id,
152
+ state: "rolled_back",
153
+ discarded_statements: count,
154
+ },
155
+ handle: transaction.id,
156
+ executed: true,
157
+ stateVersion: transaction.start_version,
158
+ };
159
+ }
160
+ function markTransactionOutcomeUnknown(store, transactionId, sessionId, actorId) {
161
+ try {
162
+ store.markTransactionOutcomeUnknown(transactionId, sessionId, actorId);
163
+ }
164
+ catch {
165
+ // A stale committing transaction is recovered as unknown after five minutes.
166
+ }
167
+ }
168
+ function normalizeIsolation(isolation, driver) {
169
+ const normalized = isolation.trim().toLowerCase().replace(/[_-]+/g, " ").replace(/\s+/g, " ");
170
+ if (driver === "redis") {
171
+ throw new StateQLError("UNSUPPORTED_DRIVER", "Redis does not support staged SQL-style transactions.");
172
+ }
173
+ if (driver === "mongodb") {
174
+ if (normalized === "snapshot")
175
+ return normalized;
176
+ throw new StateQLError("INVALID_COMMAND", `MongoDB does not support isolation level "${normalized}".`);
177
+ }
178
+ const supported = new Set(["serializable", "repeatable read", "read committed", "read uncommitted"]);
179
+ if (!supported.has(normalized)) {
180
+ throw new StateQLError("INVALID_COMMAND", `Unsupported isolation level "${isolation}".`);
181
+ }
182
+ if (driver === "sqlite" && normalized !== "serializable") {
183
+ throw new StateQLError("INVALID_COMMAND", `SQLite does not support isolation level "${normalized}".`);
184
+ }
185
+ return normalized;
186
+ }
@@ -120,25 +120,11 @@ export interface StateQLSnapshot {
120
120
  database: string;
121
121
  read_only: boolean;
122
122
  } | null;
123
- transaction: {
124
- transaction_id: string;
125
- owner_actor_id: string;
126
- state: string;
127
- } | null;
123
+ transaction: TransactionReferenceData | null;
128
124
  state_version: string | null;
129
125
  state_confidence: StateConfidence | null;
130
- recent_results: Array<{
131
- alias: string | null;
132
- handle: string;
133
- rows: number;
134
- }>;
135
- recent_operations: Array<{
136
- handle: string;
137
- actor_id: string;
138
- type: string;
139
- affected_rows: number | null;
140
- status: string;
141
- }>;
126
+ recent_results: RecentResultData[];
127
+ recent_operations: RecentOperationData[];
142
128
  history: HistoryEntry[];
143
129
  }
144
130
  export type SqlParameters = unknown[] | Record<string, unknown>;
@@ -337,6 +323,7 @@ export interface RedisPlanOptions extends ExecutionOptions {
337
323
  export interface RowsOptions {
338
324
  offset?: number;
339
325
  limit?: number;
326
+ columns?: string[];
340
327
  }
341
328
  export interface PlanOptions extends ExecutionOptions {
342
329
  params?: SqlParameters;
@@ -347,7 +334,7 @@ export interface MongoPlanOptions extends ExecutionOptions {
347
334
  allowUnbounded?: boolean;
348
335
  allowDestructive?: boolean;
349
336
  }
350
- export type BatchCommandName = "connect" | "disconnect" | "status" | "actor.show" | "actor.set-name" | "profile.add" | "profile.list" | "profile.show" | "profile.remove" | "profile.update" | "session.start" | "session.list" | "session.show" | "session.summary" | "session.close" | "query" | "filter" | "exec" | "show" | "rows" | "count" | "columns" | "alias.set" | "inspect" | "transaction.begin" | "transaction.status" | "transaction.commit" | "transaction.rollback" | "plan" | "mongo.query" | "mongo.exec" | "mongo.plan" | "redis.query" | "redis.exec" | "redis.plan" | "objects.list" | "object.describe" | "apply" | "history" | "receipt" | "doctor" | "purge" | "capabilities";
337
+ export type BatchCommandName = "connect" | "disconnect" | "status" | "actor.show" | "actor.set-name" | "profile.add" | "profile.list" | "profile.show" | "profile.remove" | "profile.update" | "session.start" | "session.list" | "session.show" | "session.summary" | "session.close" | "query" | "filter" | "exec" | "show" | "rows" | "count" | "columns" | "summarize" | "alias.set" | "inspect" | "transaction.begin" | "transaction.status" | "transaction.commit" | "transaction.rollback" | "plan" | "mongo.query" | "mongo.exec" | "mongo.plan" | "redis.query" | "redis.exec" | "redis.plan" | "objects.list" | "object.describe" | "apply" | "history" | "receipt" | "doctor" | "purge" | "capabilities";
351
338
  export interface BatchCommand {
352
339
  command: BatchCommandName;
353
340
  target?: string;
@@ -364,6 +351,7 @@ export interface BatchCommand {
364
351
  object?: CatalogObject;
365
352
  cache?: "auto" | "bypass" | "require";
366
353
  preview_rows?: number;
354
+ columns?: string[];
367
355
  read_only?: boolean;
368
356
  secret_env?: string;
369
357
  credential_ref?: string;
@@ -542,6 +530,18 @@ export interface ColumnsData {
542
530
  result_id: string;
543
531
  columns: Column[];
544
532
  }
533
+ export interface ColumnSummary {
534
+ name: string;
535
+ nulls: number;
536
+ distinct: number;
537
+ min: unknown;
538
+ max: unknown;
539
+ }
540
+ export interface SummaryData {
541
+ result_id: string;
542
+ total: number;
543
+ columns: ColumnSummary[];
544
+ }
545
545
  export interface AliasData {
546
546
  alias: string;
547
547
  result_id: string;
@@ -603,6 +603,8 @@ export interface PlanData {
603
603
  state_version: string;
604
604
  owner_actor_id: string;
605
605
  expires_at: string;
606
+ /** Rows a single-table UPDATE or DELETE matched at plan time; absent when not derivable. */
607
+ estimated_rows?: number;
606
608
  }
607
609
  export interface ApplyData extends ExecData {
608
610
  plan_id: string;
@@ -9,4 +9,5 @@ export declare function isColumns(value: unknown): value is Column[];
9
9
  export declare function isRecord(value: unknown): value is Record<string, unknown>;
10
10
  export declare function redact(value: string): string;
11
11
  export declare function compactRows(rows: Row[], maxCellCharacters: number): Row[];
12
+ export declare function compactValue(value: unknown, max: number): unknown;
12
13
  export declare function toJsonSafe<T>(value: T): T;
package/dist/src/util.js CHANGED
@@ -78,7 +78,7 @@ export function compactRows(rows, maxCellCharacters) {
78
78
  compactValue(value, maxCellCharacters),
79
79
  ])));
80
80
  }
81
- function compactValue(value, max) {
81
+ export function compactValue(value, max) {
82
82
  if (typeof value === "bigint")
83
83
  return value.toString();
84
84
  if (Buffer.isBuffer(value)) {
@@ -0,0 +1,48 @@
1
+ import type { DatabaseAdapter } from "./adapters.js";
2
+ import { type ActionResult, type Core } from "./core.js";
3
+ import { type AdapterContext } from "./execution.js";
4
+ import { type RedisPrecondition } from "./redis.js";
5
+ import type { ConnectionRecord, OperationRecord, SessionRecord } from "./store.js";
6
+ import type { compileTableUpdate, TableUpdate } from "./table-editor.js";
7
+ import type { ExecData, MongoWriteCommand, MongoWriteOutcome, SqlParameters } from "./types.js";
8
+ interface WriteOutput {
9
+ affectedRows: number;
10
+ outcome?: MongoWriteOutcome;
11
+ }
12
+ /** A validated write for one driver; runWrite does deduplication, staging, and outcome tracking. */
13
+ export interface WriteStatement {
14
+ descriptor: string;
15
+ parameters: SqlParameters;
16
+ statementType: string;
17
+ /** Duplicate-write protection compares this across versions; keep its input stable. */
18
+ fingerprint: string;
19
+ stagingError?: string;
20
+ conflictMessage: string;
21
+ unknownAction: string;
22
+ execute(adapter: DatabaseAdapter, operation: OperationRecord): Promise<WriteOutput>;
23
+ }
24
+ export interface WriteSafety {
25
+ allowUnbounded?: boolean;
26
+ allowDestructive?: boolean;
27
+ expectedRows?: 1;
28
+ }
29
+ export interface WriteOptions {
30
+ replay?: boolean;
31
+ idempotencyKey?: string;
32
+ }
33
+ /** A claimed plan that this write finishes; its source was resolved with write access. */
34
+ export interface PlanClaim {
35
+ planId: string;
36
+ claimToken: string;
37
+ source: string;
38
+ }
39
+ type CompiledTableUpdate = ReturnType<typeof compileTableUpdate>;
40
+ export declare function prepareSqlWrite(connection: ConnectionRecord, sql: string, parameters: SqlParameters, safety: WriteSafety): WriteStatement;
41
+ export declare function prepareMongoWrite(connection: ConnectionRecord, command: unknown, safety: WriteSafety): WriteStatement;
42
+ export declare function prepareRedisWrite(connection: ConnectionRecord, command: unknown, precondition?: RedisPrecondition): WriteStatement;
43
+ export declare function prepareTableBatch(connection: ConnectionRecord, planId: string, updates: TableUpdate[], compiled: CompiledTableUpdate[]): WriteStatement;
44
+ /** Reserves the write, stages it or runs it once, and records a definite or unknown outcome. */
45
+ export declare function runWrite(core: Core, session: SessionRecord, connection: ConnectionRecord, statement: WriteStatement, options: WriteOptions, context: AdapterContext, claim?: PlanClaim): Promise<ActionResult<ExecData>>;
46
+ export declare function storedMongoOperation(operation: OperationRecord): MongoWriteCommand;
47
+ export declare function storedMongoWrite(parameters: string, statementType: string, label: string, errorCode: string): MongoWriteCommand;
48
+ export {};