@fadhilp/stateql 0.13.2 → 0.14.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/README.md CHANGED
@@ -1,99 +1,60 @@
1
1
  # StateQL
2
2
 
3
3
  StateQL is a stateful database CLI and TypeScript library for AI agents and
4
- automation. Query, change, and inspect databases while keeping results reusable
5
- and operations traceable across commands.
4
+ automation. It keeps query results as durable handles, so later commands can
5
+ page, filter, count, or export them without querying the database again.
6
6
 
7
7
  - **SQL:** SQLite, PostgreSQL, and MySQL.
8
8
  - **Native commands:** MongoDB (EJSON) and Redis (JSON).
9
- - **Durable handles:** reuse, filter, page, count, alias, or export stored results
10
- without rerunning the original query.
11
- - **Tracked writes:** inspect operations, review plans, and stage transactions
12
- where supported by the database.
9
+ - **Compact output:** one-line JSON with a 5-row preview and column names sent once.
10
+ - **Safe writes:** read-only by default, explicit approval for unbounded or
11
+ destructive statements, idempotency keys, plans, and staged transactions.
13
12
 
14
- Requires **Node.js 22.16 or newer** for the required `node:sqlite` APIs.
13
+ Requires **Node.js 22.16 or newer**.
15
14
 
16
- ## Quick start
17
-
18
- Install the CLI:
15
+ ## Install
19
16
 
20
17
  ```bash
21
- npm install -g @fadhilp/stateql
18
+ npm install -g @fadhilp/stateql # CLI (stql)
19
+ npm install @fadhilp/stateql # TypeScript library
22
20
  ```
23
21
 
24
- Connect to an existing SQLite database containing a `users` table. These shell
25
- examples use Bash; see the [usage guide](docs/usage.md) for connection options and
26
- SQL parameter handling.
22
+ ## Quick start
27
23
 
28
24
  ```bash
29
25
  export STQL_SESSION=audit
30
- stql profile add local ./app.sqlite --read-only
31
- stql connect local
26
+ stql connect ./app.sqlite
32
27
 
33
- stql query \
34
- "SELECT id, name, email FROM users WHERE status = ? AND created_at >= ? ORDER BY id LIMIT 50" \
35
- --param active \
36
- --param 2026-01-01
28
+ stql query "SELECT id, name FROM users WHERE status = ? ORDER BY id" --param active
37
29
  ```
38
30
 
39
- Parameters keep values separate from SQL. `ORDER BY` makes paging stable, and
40
- `LIMIT` bounds work at the database. The default `agent` output is compact,
41
- one-line JSON. An example response:
42
-
43
31
  ```json
44
- {"ok":true,"handle":"q_k7m2v5x9c3d6f8h4j2n7p5r9tw","rows":[{"id":7,"name":"Ada","email":"ada@example.com"}],"truncated":false,"cached":false,"total":1,"next_offset":null}
32
+ {"ok":true,"handle":"katcitg6un","total":333,"next_offset":5,"columns":["id","name"],"rows":[[2,"Ada"],[3,"Grace"],[5,"Linus"],[6,"Alan"],[8,"Edsger"]]}
45
33
  ```
46
34
 
47
- Use the handle returned by your query in place of the example handle below.
48
- Give the snapshot a readable alias, then work with the stored data:
35
+ Reuse the result by its handle. These commands do not access the database:
49
36
 
50
37
  ```bash
51
- stql alias set active-users q_k7m2v5x9c3d6f8h4j2n7p5r9tw
52
- stql rows active-users --offset 0 --limit 10
53
- stql count active-users
54
- stql export active-users --output active-users.csv --format csv
55
- stql filter active-users "email LIKE ?" --param "%@example.com"
38
+ stql rows katcitg6un --offset 5 --limit 20
39
+ stql filter katcitg6un "name LIKE ?" --param "A%"
40
+ stql export katcitg6un --output users.csv
56
41
  ```
57
42
 
58
- These commands do not access the original database. `filter` creates a new
59
- snapshot with its own handle. Repeating a query can reuse a valid cached result;
60
- use `--cache bypass` when a fresh database read is required.
61
-
62
- ## Safety and state
63
-
64
- - Connections are **read-only by default**. Writes require a read-write connection.
65
- - Destructive and unbounded SQL/MongoDB operations require independent
66
- `--allow-destructive` and `--allow-unbounded` approvals, respectively.
67
- - `plan` stores a write for review; `apply` never adds authorization. Use
68
- idempotency keys to protect retryable writes from duplicate execution.
69
- - A write reported as `OUTCOME_UNKNOWN` must be inspected at the database before
70
- replaying it. Transactions are staged locally, not live interactive SQL
71
- transactions.
72
- - Supply credential-bearing URLs through environment variables or a trusted
73
- library credential resolver, not literal command arguments or profiles.
74
- - Results and history persist under `STQL_HOME` (or the platform data directory).
75
- Treat that state as database data; retention and size limits are configurable.
76
-
77
- See [write safety](docs/usage.md#write-safety),
78
- [credentials](docs/usage.md#environment-backed-credentials), and
79
- [database restrictions](docs/databases.md) before using production data.
80
-
81
43
  ## Documentation
82
44
 
83
- | Guide | Contents |
45
+ | Page | Contents |
84
46
  | --- | --- |
85
- | [Usage](docs/usage.md) | Connections, CLI reference, results, sessions, limits, writes, transactions, batch and pipes |
86
- | [Database support](docs/databases.md) | SQL dialects, diagnostics, maintenance, native MongoDB and Redis commands |
87
- | [TypeScript library](docs/library.md) | Connection setup, response handling, cleanup, actors, workspaces, and credential resolution |
88
- | [SQL command roadmap](SQL_COMMAND_ROADMAP.md) | Development priorities and requirements for extending SQL support |
89
-
90
- Run `stql --help` for command syntax or `stql capabilities` for capability details.
47
+ | [Agent guide](docs/agents.md) | The short version for agents: connect, query, reuse, save tokens |
48
+ | [Connections](docs/connections.md) | Targets, environment credentials, profiles |
49
+ | [CLI reference](docs/cli.md) | Commands, parameters, catalog, output modes, deadlines |
50
+ | [Results and state](docs/results.md) | Sessions, actors, limits, caching, local filtering |
51
+ | [Write safety](docs/writes.md) | Approvals, plans, idempotency, transactions |
52
+ | [Batch and pipes](docs/batch.md) | Run many commands in one call |
53
+ | [Database support](docs/databases.md) | Dialects, diagnostics, MongoDB and Redis commands |
54
+ | [TypeScript library](docs/library.md) | API, responses, actors, credential resolution |
91
55
 
92
- ## TypeScript installation
56
+ Run `stql help` for command syntax and `stql capabilities` for feature details.
93
57
 
94
- ```bash
95
- npm install @fadhilp/stateql
96
- ```
58
+ ## License
97
59
 
98
- The package exports `StateQL` and public TypeScript types. Start with the
99
- [connected, cleanup-safe example](docs/library.md#getting-started).
60
+ [MIT](LICENSE)
@@ -1,8 +1,12 @@
1
1
  import { fork } from "node:child_process";
2
- import { createConnection as createMySqlConnection, } from "mysql2";
3
- import { Client, types as pgTypes } from "pg";
2
+ import { createRequire } from "node:module";
4
3
  import { StateQLError } from "./errors.js";
5
4
  import { isSqlParameters, parseJson, toJsonSafe } from "./util.js";
5
+ const require = createRequire(import.meta.url);
6
+ let mysqlModule;
7
+ let postgresModule;
8
+ const mysql = () => (mysqlModule ??= require("mysql2"));
9
+ const postgres = () => (postgresModule ??= require("pg"));
6
10
  export class AdapterExecutionError extends Error {
7
11
  reason;
8
12
  outcomeUnknown;
@@ -237,11 +241,14 @@ class PostgresAdapter {
237
241
  context;
238
242
  confidence = "ttl_based";
239
243
  client;
244
+ pgTypes;
240
245
  connected = false;
241
246
  ending;
242
247
  constructor(source, readOnly, context) {
243
248
  this.readOnly = readOnly;
244
249
  this.context = context;
250
+ const { Client, types } = postgres();
251
+ this.pgTypes = types;
245
252
  const timeout = Math.min(2_147_483_647, remainingMilliseconds(context));
246
253
  this.client = new Client({
247
254
  connectionString: normalizePostgresConnectionString(source),
@@ -263,7 +270,7 @@ class PostgresAdapter {
263
270
  rows: toJsonSafe(result.rows),
264
271
  columns: result.fields.map((field) => ({
265
272
  name: field.name,
266
- type: pgTypes.getTypeParser(field.dataTypeID).name ||
273
+ type: this.pgTypes.getTypeParser(field.dataTypeID).name ||
267
274
  `oid_${field.dataTypeID}`,
268
275
  })),
269
276
  };
@@ -884,7 +891,7 @@ class MySqlAdapter {
884
891
  throwIfStopped(this.context, false);
885
892
  if (this.closed)
886
893
  throw new Error("MySQL adapter is closed.");
887
- const rawClient = createMySqlConnection({
894
+ const rawClient = mysql().createConnection({
888
895
  uri: this.source,
889
896
  connectTimeout: remainingMilliseconds(this.context),
890
897
  multipleStatements: false,
package/dist/src/cli.js CHANGED
@@ -6,6 +6,13 @@ import { parseArgs } from "node:util";
6
6
  import { BSON } from "mongodb";
7
7
  import { exitCodeFor } from "./errors.js";
8
8
  import { StateQL } from "./stateql.js";
9
+ import { isColumns, isRecord } from "./util.js";
10
+ const RESULT_COMMANDS = new Set(["query", "mongo.query", "filter", "show"]);
11
+ const FALSE_DEFAULT_KEYS = ["cached", "duplicate", "duplicate_override"];
12
+ const SHARED_HISTORY_KEYS = ["session_id", "actor_id", "actor_name", "origin"];
13
+ // The caller already holds the handle it passed to these commands.
14
+ const HANDLE_ECHO_COMMANDS = new Set(["rows", "count", "columns"]);
15
+ const WRITE_COMMANDS = new Set(["exec", "mongo.exec", "apply"]);
9
16
  const parsed = parseArgs({
10
17
  allowPositionals: true,
11
18
  strict: true,
@@ -21,6 +28,7 @@ const parsed = parseArgs({
21
28
  "params-file": { type: "string" },
22
29
  cache: { type: "string" },
23
30
  "preview-rows": { type: "string" },
31
+ "max-cell-characters": { type: "string" },
24
32
  replay: { type: "boolean" },
25
33
  "idempotency-key": { type: "string" },
26
34
  "allow-unbounded": { type: "boolean" },
@@ -51,7 +59,7 @@ if (values.version) {
51
59
  console.log(packageVersion());
52
60
  process.exit(0);
53
61
  }
54
- if (values.help || !command) {
62
+ if (values.help || !command || command === "help") {
55
63
  console.log(helpText());
56
64
  process.exit(0);
57
65
  }
@@ -71,6 +79,9 @@ const stateql = new StateQL({
71
79
  ...(values["result-ttl-seconds"] === undefined
72
80
  ? {}
73
81
  : { resultTtlSeconds: Number(values["result-ttl-seconds"]) }),
82
+ ...(values["max-cell-characters"] === undefined
83
+ ? {}
84
+ : { maxCellCharacters: Number(values["max-cell-characters"]) }),
74
85
  signal: abortController.signal,
75
86
  });
76
87
  try {
@@ -164,6 +175,8 @@ async function dispatch() {
164
175
  return stateql.disconnect();
165
176
  case "status":
166
177
  return stateql.status();
178
+ case "actor":
179
+ return dispatchActor(subcommand, rest);
167
180
  case "profile":
168
181
  return dispatchProfile(subcommand, rest);
169
182
  case "session":
@@ -315,6 +328,16 @@ function parseMongoCommand(value) {
315
328
  throw new Error("Invalid MongoDB EJSON command.");
316
329
  }
317
330
  }
331
+ async function dispatchActor(action, args) {
332
+ switch (action) {
333
+ case "show":
334
+ return stateql.showActor();
335
+ case "set-name":
336
+ return stateql.setActorName(requireValue(args.join(" ").trim(), "actor name"));
337
+ default:
338
+ throw new Error(`Unknown actor command "${action ?? ""}".`);
339
+ }
340
+ }
318
341
  async function dispatchSession(action, args) {
319
342
  switch (action) {
320
343
  case "start":
@@ -522,33 +545,33 @@ function print(result, mode, currentCommand) {
522
545
  function toAgentResponse(result, currentCommand) {
523
546
  if (!result.ok)
524
547
  return { ok: false, error: result.error };
525
- if (!result.data ||
526
- typeof result.data !== "object" ||
527
- Array.isArray(result.data)) {
548
+ if (!isRecord(result.data))
528
549
  return { ok: true, data: result.data };
529
- }
530
550
  const data = { ...result.data };
531
551
  const handleKey = primaryHandleKey(currentCommand);
532
- const handle = handleKey && typeof data[handleKey] === "string" && data[handleKey]
552
+ let handle = handleKey && typeof data[handleKey] === "string" && data[handleKey]
533
553
  ? data[handleKey]
534
554
  : undefined;
535
555
  if (handle && handleKey)
536
556
  delete data[handleKey];
537
- if ((currentCommand === "query" ||
538
- currentCommand === "mongo.query" ||
539
- currentCommand === "filter" ||
540
- currentCommand === "show") &&
557
+ const generatedAlias = data.display_alias;
558
+ delete data.display_alias;
559
+ // Generated aliases cannot be reassigned, so they are stable short result handles.
560
+ if (RESULT_COMMANDS.has(currentCommand) && typeof generatedAlias === "string") {
561
+ handle = generatedAlias;
562
+ if (data.alias === generatedAlias)
563
+ delete data.alias;
564
+ }
565
+ const isResult = RESULT_COMMANDS.has(currentCommand) &&
541
566
  typeof data.rows === "number" &&
542
- Array.isArray(data.preview)) {
543
- const total = data.rows;
544
- const rows = data.preview;
545
- const truncated = Boolean(data.truncated);
546
- data.rows = rows;
547
- data.total = total;
548
- data.next_offset = truncated ? rows.length : null;
567
+ Array.isArray(data.preview);
568
+ if (isResult) {
569
+ data.total = data.rows;
570
+ data.next_offset = data.truncated ? data.preview.length : null;
571
+ data.rows = data.preview;
549
572
  delete data.preview;
550
573
  delete data.preview_count;
551
- delete data.columns;
574
+ delete data.truncated;
552
575
  delete data.storage;
553
576
  delete data.state_version;
554
577
  delete data.duplicate_of;
@@ -557,11 +580,55 @@ function toAgentResponse(result, currentCommand) {
557
580
  delete data.offset;
558
581
  delete data.limit;
559
582
  delete data.returned;
583
+ delete data.truncated;
560
584
  }
561
585
  else if (currentCommand === "count" && typeof data.rows === "number") {
562
586
  data.total = data.rows;
563
587
  delete data.rows;
564
588
  }
589
+ else if (WRITE_COMMANDS.has(currentCommand)) {
590
+ delete data.actor_id;
591
+ delete data.plan_id;
592
+ delete data.state_version_before;
593
+ if (typeof data.status === "string")
594
+ delete data.committed;
595
+ }
596
+ else if (currentCommand === "history" &&
597
+ Array.isArray(data.history) &&
598
+ data.history.every(isRecord)) {
599
+ Object.assign(data, compactHistory(data.history));
600
+ }
601
+ else if (currentCommand === "inspect" && Array.isArray(data.columns)) {
602
+ data.columns = data.columns.map(withoutFalsePrimaryKey);
603
+ }
604
+ else if (currentCommand === "capabilities" && isRecord(data.features)) {
605
+ const features = data.features;
606
+ data.features = Object.keys(features).filter((key) => features[key] === true);
607
+ }
608
+ else if (currentCommand === "objects" &&
609
+ Array.isArray(data.objects) &&
610
+ data.objects.every(isRecord)) {
611
+ const objects = data.objects.every(hasDerivedIdentity)
612
+ ? data.objects.map(withoutIdentity)
613
+ : data.objects;
614
+ const table = columnarRows(objects, undefined);
615
+ delete data.objects;
616
+ Object.assign(data, { columns: table.columns, objects: table.rows });
617
+ }
618
+ else if (currentCommand === "object" &&
619
+ isRecord(data.object) &&
620
+ hasDerivedIdentity(data.object)) {
621
+ data.object = withoutIdentity(data.object);
622
+ }
623
+ if (isResult || (currentCommand === "rows" && Array.isArray(data.rows))) {
624
+ const table = columnarRows(data.rows, data.columns);
625
+ delete data.columns;
626
+ delete data.rows;
627
+ Object.assign(data, table);
628
+ }
629
+ const hasMoreRows = data.next_offset !== null && data.next_offset !== undefined;
630
+ const warnings = result.warnings.filter((warning) => warning.code !== "NON_DETERMINISTIC_PAGINATION" || hasMoreRows);
631
+ dropFalseDefaults(data);
565
632
  for (const key of ["ok", "error", "handle", "warnings"]) {
566
633
  if (!(key in data))
567
634
  continue;
@@ -570,10 +637,76 @@ function toAgentResponse(result, currentCommand) {
570
637
  }
571
638
  return {
572
639
  ok: true,
573
- ...(handle ? { handle } : {}),
574
- ...data,
575
- ...(result.warnings.length ? { warnings: result.warnings } : {}),
640
+ ...(handle && !HANDLE_ECHO_COMMANDS.has(currentCommand) ? { handle } : {}),
641
+ ...withoutNulls(data),
642
+ ...(warnings.length ? { warnings } : {}),
643
+ };
644
+ }
645
+ // Rows with differing keys (e.g. MongoDB documents) stay objects so missing and null remain distinct.
646
+ function columnarRows(rows, columns) {
647
+ const names = isColumns(columns)
648
+ ? columns.map((column) => column.name)
649
+ : Object.keys(rows[0] ?? {});
650
+ if (names.length === 0)
651
+ return { rows };
652
+ const nameSet = new Set(names);
653
+ const hasColumnKeys = (row) => {
654
+ if (!isRecord(row))
655
+ return false;
656
+ const keys = Object.keys(row);
657
+ return keys.length === names.length && keys.every((key) => nameSet.has(key));
576
658
  };
659
+ if (!rows.every(hasColumnKeys))
660
+ return { rows };
661
+ return {
662
+ columns: names,
663
+ rows: rows.map((row) => names.map((name) => row[name])),
664
+ };
665
+ }
666
+ function compactHistory(entries) {
667
+ const shared = {};
668
+ for (const key of SHARED_HISTORY_KEYS) {
669
+ const value = entries[0]?.[key];
670
+ if (value === undefined)
671
+ continue;
672
+ if (entries.every((entry) => entry[key] === value))
673
+ shared[key] = value;
674
+ }
675
+ const history = entries.map((entry) => {
676
+ const compact = withoutNulls(entry);
677
+ dropFalseDefaults(compact);
678
+ for (const key of Object.keys(shared))
679
+ delete compact[key];
680
+ return compact;
681
+ });
682
+ return { ...shared, history };
683
+ }
684
+ function hasDerivedIdentity(object) {
685
+ const qualifiedName = typeof object.schema === "string"
686
+ ? `${object.schema}.${String(object.name)}`
687
+ : object.name;
688
+ return object.identity === undefined || object.identity === qualifiedName;
689
+ }
690
+ function withoutIdentity(object) {
691
+ const compact = { ...object };
692
+ delete compact.identity;
693
+ return compact;
694
+ }
695
+ function withoutFalsePrimaryKey(column) {
696
+ if (!isRecord(column) || column.primary_key !== false)
697
+ return column;
698
+ const compact = { ...column };
699
+ delete compact.primary_key;
700
+ return compact;
701
+ }
702
+ function dropFalseDefaults(record) {
703
+ for (const key of FALSE_DEFAULT_KEYS) {
704
+ if (record[key] === false)
705
+ delete record[key];
706
+ }
707
+ }
708
+ function withoutNulls(record) {
709
+ return Object.fromEntries(Object.entries(record).filter(([, value]) => value !== null));
577
710
  }
578
711
  function primaryHandleKey(currentCommand) {
579
712
  const keys = {
@@ -645,6 +778,7 @@ Usage: stql <command> [arguments] [options]
645
778
  Commands:
646
779
  connect TARGET | --env ENV | --credential-ref REF | --profile NAME
647
780
  disconnect, status
781
+ actor show | set-name NAME
648
782
  profile add|update NAME [TARGET | --env ENV | --credential-ref REF]
649
783
  profile list|show|remove
650
784
  query, filter, exec, show, rows, count, columns, export
@@ -661,10 +795,13 @@ Commands:
661
795
 
662
796
  SQL parameters: --params JSON, repeated --param VALUE, or --params-file FILE.
663
797
  Query preview: --preview-rows N (default: 5, maximum: 200).
798
+ Long cells: --max-cell-characters N (default: 200); use export for full values.
664
799
  Deadline: --timeout-ms N (default: 30000). Ctrl+C cancels database work.
665
800
  Credential refs require a trusted host CredentialResolver; the standalone CLI cannot resolve them.
666
801
  State: --max-state-bytes N, --cache-ttl-seconds N, --result-ttl-seconds N.
667
802
  Output: --output agent|json|jsonl|text|silent (default: agent).
803
+ Agent rows: arrays in "columns" order (objects when shapes differ). next_offset only when more rows exist.
804
+ Agent output omits null fields and false cached/duplicate flags. Guide: docs/agents.md.
668
805
  Batch/pipe accept JSON array files or JSONL streams. Stop on first error.`;
669
806
  }
670
807
  function packageVersion() {
@@ -14,4 +14,5 @@ export declare class StateQLError extends Error {
14
14
  });
15
15
  }
16
16
  export declare function exitCodeFor(code: string): number;
17
+ export declare function isTransientDatabaseError(error: unknown): boolean;
17
18
  export declare function asStateQLError(error: unknown): StateQLError;
@@ -49,6 +49,46 @@ export function exitCodeFor(code) {
49
49
  return 9;
50
50
  return 1;
51
51
  }
52
+ const TRANSIENT_NETWORK_CODES = new Set([
53
+ "ECONNRESET",
54
+ "ECONNREFUSED",
55
+ "ETIMEDOUT",
56
+ "EPIPE",
57
+ "EAI_AGAIN",
58
+ "PROTOCOL_CONNECTION_LOST",
59
+ ]);
60
+ // SQLSTATE classes: connection, transaction rollback, resources, operator intervention, system.
61
+ const TRANSIENT_SQLSTATE_CLASSES = new Set(["08", "40", "53", "57", "58"]);
62
+ // MySQL: too many connections, lock wait timeout, deadlock.
63
+ const TRANSIENT_MYSQL_ERRNOS = new Set([1040, 1205, 1213]);
64
+ const TRANSIENT_ERROR_NAMES = new Set([
65
+ "MongoNetworkError",
66
+ "MongoNetworkTimeoutError",
67
+ "MongoServerSelectionError",
68
+ "SocketClosedUnexpectedlyError",
69
+ "ConnectionTimeoutError",
70
+ ]);
71
+ const TRANSIENT_SQLITE_MESSAGE = /database (table )?is locked|SQLITE_BUSY/i;
72
+ // Permanent failures such as a missing table must not invite retries; unknown errors are not retryable.
73
+ export function isTransientDatabaseError(error) {
74
+ if (!(error instanceof Error))
75
+ return false;
76
+ const details = error;
77
+ if (typeof details.code === "string" && TRANSIENT_NETWORK_CODES.has(details.code))
78
+ return true;
79
+ if (TRANSIENT_ERROR_NAMES.has(error.name))
80
+ return true;
81
+ if (typeof details.errno === "number" && TRANSIENT_MYSQL_ERRNOS.has(details.errno))
82
+ return true;
83
+ if (Array.isArray(details.errorLabels) && details.errorLabels.includes("TransientTransactionError")) {
84
+ return true;
85
+ }
86
+ const sqlState = typeof details.sqlState === "string" ? details.sqlState : details.code;
87
+ if (typeof sqlState === "string" && /^[0-9A-Z]{5}$/.test(sqlState)) {
88
+ return TRANSIENT_SQLSTATE_CLASSES.has(sqlState.slice(0, 2));
89
+ }
90
+ return TRANSIENT_SQLITE_MESSAGE.test(error.message);
91
+ }
52
92
  export function asStateQLError(error) {
53
93
  if (error instanceof StateQLError)
54
94
  return error;
@@ -131,6 +131,26 @@ const MIGRATIONS = [
131
131
  apply: migratePasswordRefs,
132
132
  validate: validatePasswordRefs,
133
133
  },
134
+ {
135
+ name: "actor_display_names_v1",
136
+ apply(db) {
137
+ addColumn(db, "session_members", "actor_name", "TEXT");
138
+ addColumn(db, "history", "actor_name", "TEXT");
139
+ db.exec(`
140
+ UPDATE session_members SET actor_name = actor_id WHERE actor_name IS NULL;
141
+ UPDATE history SET actor_name = actor_id WHERE actor_name IS NULL;
142
+ `);
143
+ },
144
+ validate(db) {
145
+ requireColumns(db, "session_members", ["actor_name"]);
146
+ requireColumns(db, "history", ["actor_name"]);
147
+ for (const table of ["session_members", "history"]) {
148
+ const row = db.prepare(`SELECT COUNT(*) AS count FROM ${table} WHERE actor_name IS NULL OR actor_name = ''`).get();
149
+ if (row.count)
150
+ throw new Error(`State migration left ${table}.actor_name empty.`);
151
+ }
152
+ },
153
+ },
134
154
  ];
135
155
  export function runMigrations(db, now) {
136
156
  db.exec(`
@@ -178,6 +198,7 @@ function createInitialSchema(db) {
178
198
  CREATE TABLE IF NOT EXISTS session_members (
179
199
  session_id TEXT NOT NULL,
180
200
  actor_id TEXT NOT NULL UNIQUE,
201
+ actor_name TEXT NOT NULL,
181
202
  attached_at TEXT NOT NULL,
182
203
  PRIMARY KEY(session_id, actor_id),
183
204
  FOREIGN KEY(session_id) REFERENCES sessions(id)
@@ -294,6 +315,7 @@ function createInitialSchema(db) {
294
315
  timestamp TEXT NOT NULL,
295
316
  session_id TEXT NOT NULL,
296
317
  actor_id TEXT NOT NULL,
318
+ actor_name TEXT NOT NULL,
297
319
  command TEXT NOT NULL,
298
320
  origin TEXT NOT NULL DEFAULT 'legacy',
299
321
  category TEXT NOT NULL DEFAULT 'management',
@@ -313,19 +335,22 @@ function migrateSharedSessionActors(db) {
313
335
  CREATE TABLE IF NOT EXISTS session_members (
314
336
  session_id TEXT NOT NULL,
315
337
  actor_id TEXT NOT NULL UNIQUE,
338
+ actor_name TEXT,
316
339
  attached_at TEXT NOT NULL,
317
340
  PRIMARY KEY(session_id, actor_id),
318
341
  FOREIGN KEY(session_id) REFERENCES sessions(id)
319
342
  )
320
343
  `);
344
+ addColumn(db, "session_members", "actor_name", "TEXT");
321
345
  addColumn(db, "operations", "actor_id", "TEXT");
322
346
  addColumn(db, "transactions", "owner_actor_id", "TEXT");
323
347
  addColumn(db, "plans", "owner_actor_id", "TEXT");
324
348
  addColumn(db, "plans", "claim_token", "TEXT");
325
349
  addColumn(db, "history", "actor_id", "TEXT");
326
350
  db.exec(`
327
- INSERT OR IGNORE INTO session_members(session_id, actor_id, attached_at)
328
- SELECT id, name, created_at FROM sessions;
351
+ INSERT OR IGNORE INTO session_members(session_id, actor_id, actor_name, attached_at)
352
+ SELECT id, name, name, created_at FROM sessions;
353
+ UPDATE session_members SET actor_name = actor_id WHERE actor_name IS NULL;
329
354
  UPDATE operations SET actor_id = (
330
355
  SELECT name FROM sessions WHERE sessions.id = operations.session_id
331
356
  ) WHERE actor_id IS NULL;
@@ -1,5 +1,9 @@
1
- import { BSON, MongoClient, } from "mongodb";
1
+ import { createRequire } from "node:module";
2
+ import { BSON } from "bson";
2
3
  import { AdapterExecutionError, AdapterWriteError, BatchWriteError, } from "./adapters.js";
4
+ const require = createRequire(import.meta.url);
5
+ let mongodbModule;
6
+ const mongodb = () => (mongodbModule ??= require("mongodb"));
3
7
  const MAX_INSPECTION_ITEMS = 1_000;
4
8
  const FIND_OPTIONS = new Set([
5
9
  "projection",
@@ -170,7 +174,7 @@ export class MongoAdapter {
170
174
  this.databaseName = connection.database_name;
171
175
  this.readOnly = Boolean(connection.read_only);
172
176
  const timeout = remainingMilliseconds(context);
173
- this.client = new MongoClient(input.source, {
177
+ this.client = new (mongodb().MongoClient)(input.source, {
174
178
  connectTimeoutMS: timeout,
175
179
  serverSelectionTimeoutMS: timeout,
176
180
  waitQueueTimeoutMS: timeout,
package/dist/src/redis.js CHANGED
@@ -1,6 +1,9 @@
1
- import { createClient, RESP_TYPES, WatchError } from "@redis/client";
1
+ import { createRequire } from "node:module";
2
2
  import { AdapterExecutionError, AdapterWriteError } from "./adapters.js";
3
3
  import { hash, toJsonSafe } from "./util.js";
4
+ const require = createRequire(import.meta.url);
5
+ let redisModule;
6
+ const redis = () => (redisModule ??= require("@redis/client"));
4
7
  const MAX_ARGUMENTS = 100;
5
8
  const MAX_ARGUMENT_BYTES = 256 * 1024;
6
9
  const MAX_RESPONSE_BYTES = 1024 * 1024;
@@ -105,7 +108,7 @@ export class RedisAdapter {
105
108
  constructor(source, readOnly, context) {
106
109
  this.readOnly = readOnly;
107
110
  this.context = context;
108
- this.client = createClient({
111
+ this.client = redis().createClient({
109
112
  url: source,
110
113
  socket: {
111
114
  connectTimeout: remainingMilliseconds(context),
@@ -183,7 +186,7 @@ export class RedisAdapter {
183
186
  catch (error) {
184
187
  if (error instanceof AdapterWriteError)
185
188
  throw error;
186
- if (error instanceof WatchError)
189
+ if (error instanceof redis().WatchError)
187
190
  throw new AdapterWriteError("ROW_CONFLICT: The Redis key changed. Reload before editing.", false);
188
191
  if (error instanceof AdapterExecutionError)
189
192
  throw error;
@@ -274,7 +277,7 @@ export class RedisAdapter {
274
277
  }
275
278
  const [type, dump] = await Promise.all([
276
279
  this.execute(["TYPE", key], false),
277
- withDeadline(this.client.sendCommand(["DUMP", key], { typeMapping: { [RESP_TYPES.BLOB_STRING]: Buffer } }), this.context, false, () => this.stop()),
280
+ withDeadline(this.client.sendCommand(["DUMP", key], { typeMapping: { [redis().RESP_TYPES.BLOB_STRING]: Buffer } }), this.context, false, () => this.stop()),
278
281
  ]);
279
282
  const encoded = Buffer.isBuffer(dump) ? dump.toString("base64") : dump;
280
283
  if (Buffer.byteLength(JSON.stringify(encoded), "utf8") > MAX_RESPONSE_BYTES * 2) {