@fadhilp/stateql 0.17.0 → 0.19.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 (43) hide show
  1. package/dist/src/adapters.d.ts +17 -25
  2. package/dist/src/adapters.js +15 -95
  3. package/dist/src/catalog.d.ts +6 -0
  4. package/dist/src/catalog.js +52 -0
  5. package/dist/src/cli.js +8 -3
  6. package/dist/src/connect.d.ts +16 -0
  7. package/dist/src/connect.js +205 -0
  8. package/dist/src/core.d.ts +78 -0
  9. package/dist/src/core.js +477 -0
  10. package/dist/src/execution.d.ts +27 -0
  11. package/dist/src/execution.js +87 -0
  12. package/dist/src/filter.js +3 -1
  13. package/dist/src/index.d.ts +2 -1
  14. package/dist/src/index.js +1 -0
  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/os-credentials.d.ts +6 -1
  19. package/dist/src/os-credentials.js +171 -10
  20. package/dist/src/panel.d.ts +64 -0
  21. package/dist/src/panel.js +316 -0
  22. package/dist/src/plans.d.ts +31 -0
  23. package/dist/src/plans.js +275 -0
  24. package/dist/src/reads.d.ts +35 -0
  25. package/dist/src/reads.js +184 -0
  26. package/dist/src/redis.d.ts +4 -2
  27. package/dist/src/redis.js +7 -33
  28. package/dist/src/response-data.d.ts +1 -0
  29. package/dist/src/response-data.js +13 -10
  30. package/dist/src/results.d.ts +10 -0
  31. package/dist/src/results.js +153 -0
  32. package/dist/src/sqlite-process.js +16 -9
  33. package/dist/src/stateql.d.ts +7 -58
  34. package/dist/src/stateql.js +150 -2663
  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 +3 -17
  39. package/dist/src/writes.d.ts +48 -0
  40. package/dist/src/writes.js +320 -0
  41. package/docs/databases.md +2 -1
  42. package/docs/results.md +5 -0
  43. package/package.json +5 -3
@@ -1,5 +1,9 @@
1
+ import { type AdapterContext } from "./execution.js";
2
+ import { MongoAdapter } from "./mongodb.js";
3
+ import { RedisAdapter } from "./redis.js";
1
4
  import type { CatalogObject, DescribeObjectData, ListObjectsData, ListObjectsFilter, Column, Row, SqlParameters, StateConfidence } from "./types.js";
2
5
  import type { ConnectionRecord, OperationRecord } from "./store.js";
6
+ export { AdapterExecutionError, AdapterWriteError, BatchWriteError, createAdapterContext, type AdapterContext, } from "./execution.js";
3
7
  export interface ReadResult {
4
8
  rows: Row[];
5
9
  columns: Column[];
@@ -10,40 +14,28 @@ export interface WriteResult {
10
14
  export type BatchWriteOperation = OperationRecord & {
11
15
  expectedRows?: 1;
12
16
  };
13
- export interface AdapterContext {
14
- deadline: number;
15
- timeoutMs?: number;
16
- signal?: AbortSignal;
17
- }
18
- export declare class AdapterExecutionError extends Error {
19
- readonly reason: "timeout" | "aborted";
20
- readonly outcomeUnknown: boolean;
21
- constructor(message: string, reason: "timeout" | "aborted", outcomeUnknown: boolean);
22
- }
23
- export declare class BatchWriteError extends Error {
24
- readonly outcomeUnknown: boolean;
25
- constructor(message: string, outcomeUnknown: boolean);
26
- }
27
- export declare class AdapterWriteError extends Error {
28
- readonly outcomeUnknown: boolean;
29
- constructor(message: string, outcomeUnknown: boolean);
30
- }
31
- export interface Adapter {
17
+ /** What every database adapter offers, whatever its command language. */
18
+ export interface BaseAdapter {
32
19
  readonly confidence: StateConfidence;
33
20
  ping(): Promise<void>;
21
+ signature(): Promise<string>;
22
+ listObjects(filter: ListObjectsFilter): Promise<ListObjectsData>;
23
+ describeObject(object: CatalogObject): Promise<DescribeObjectData>;
24
+ close(): Promise<void>;
25
+ }
26
+ export interface SqlAdapter extends BaseAdapter {
27
+ readonly kind: "sql";
34
28
  read(sql: string, params: SqlParameters): Promise<ReadResult>;
35
29
  readAutocommit?(sql: string, params: SqlParameters): Promise<ReadResult>;
36
30
  write(sql: string, params: SqlParameters, expectedRows?: 1): Promise<WriteResult>;
37
31
  writeAutocommit?(sql: string, params: SqlParameters): Promise<WriteResult>;
38
32
  writeBatch(operations: BatchWriteOperation[], isolation: string): Promise<WriteResult[]>;
39
- signature(): Promise<string>;
40
33
  inspect(kind: string, table?: string): Promise<unknown>;
41
- listObjects(filter: ListObjectsFilter): Promise<ListObjectsData>;
42
- describeObject(object: CatalogObject): Promise<DescribeObjectData>;
43
- close(): Promise<void>;
44
34
  }
45
- export declare function createAdapterContext(timeoutMs: number, signal?: AbortSignal): AdapterContext;
35
+ export type DatabaseAdapter = SqlAdapter | MongoAdapter | RedisAdapter;
36
+ /** Opens the adapter for any supported driver; this is the only place that maps drivers to adapters. */
37
+ export declare function openAdapter(connection: ConnectionRecord, context: AdapterContext, source: string): Promise<DatabaseAdapter>;
46
38
  export declare function createAdapter(connection: ConnectionRecord, context: AdapterContext, input: {
47
39
  source: string;
48
- }): Promise<Adapter>;
40
+ }): Promise<SqlAdapter>;
49
41
  export declare function normalizePostgresConnectionString(source: string): string;
@@ -1,44 +1,23 @@
1
1
  import { fork } from "node:child_process";
2
2
  import { createRequire } from "node:module";
3
3
  import { StateQLError } from "./errors.js";
4
+ import { AdapterExecutionError, AdapterWriteError, BatchWriteError, remainingMilliseconds, stoppedError, throwIfStopped, withContext, } from "./execution.js";
5
+ import { MongoAdapter } from "./mongodb.js";
6
+ import { RedisAdapter } from "./redis.js";
4
7
  import { isSqlParameters, parseJson, toJsonSafe } from "./util.js";
8
+ export { AdapterExecutionError, AdapterWriteError, BatchWriteError, createAdapterContext, } from "./execution.js";
5
9
  const require = createRequire(import.meta.url);
6
10
  let mysqlModule;
7
11
  let postgresModule;
8
12
  const mysql = () => (mysqlModule ??= require("mysql2"));
9
13
  const postgres = () => (postgresModule ??= require("pg"));
10
- export class AdapterExecutionError extends Error {
11
- reason;
12
- outcomeUnknown;
13
- constructor(message, reason, outcomeUnknown) {
14
- super(message);
15
- this.reason = reason;
16
- this.outcomeUnknown = outcomeUnknown;
17
- this.name = "AdapterExecutionError";
18
- }
19
- }
20
- export class BatchWriteError extends Error {
21
- outcomeUnknown;
22
- constructor(message, outcomeUnknown) {
23
- super(message);
24
- this.outcomeUnknown = outcomeUnknown;
25
- this.name = "BatchWriteError";
26
- }
27
- }
28
- export class AdapterWriteError extends Error {
29
- outcomeUnknown;
30
- constructor(message, outcomeUnknown) {
31
- super(message);
32
- this.outcomeUnknown = outcomeUnknown;
33
- this.name = "AdapterWriteError";
34
- }
35
- }
36
- export function createAdapterContext(timeoutMs, signal) {
37
- return {
38
- deadline: Date.now() + timeoutMs,
39
- timeoutMs,
40
- ...(signal ? { signal } : {}),
41
- };
14
+ /** Opens the adapter for any supported driver; this is the only place that maps drivers to adapters. */
15
+ export async function openAdapter(connection, context, source) {
16
+ if (connection.driver === "mongodb")
17
+ return new MongoAdapter(connection, context, { source });
18
+ if (connection.driver === "redis")
19
+ return new RedisAdapter(source, Boolean(connection.read_only), context);
20
+ return createAdapter(connection, context, { source });
42
21
  }
43
22
  export async function createAdapter(connection, context, input) {
44
23
  const { source } = input;
@@ -60,6 +39,7 @@ class SQLiteAdapter {
60
39
  source;
61
40
  readOnly;
62
41
  context;
42
+ kind = "sql";
63
43
  confidence = "database_reported";
64
44
  child;
65
45
  pending = new Map();
@@ -239,6 +219,7 @@ const POSTGRES_AUTOCOMMIT_STATEMENTS = new Set([
239
219
  class PostgresAdapter {
240
220
  readOnly;
241
221
  context;
222
+ kind = "sql";
242
223
  confidence = "ttl_based";
243
224
  client;
244
225
  pgTypes;
@@ -249,7 +230,7 @@ class PostgresAdapter {
249
230
  this.context = context;
250
231
  const { Client, types } = postgres();
251
232
  this.pgTypes = types;
252
- const timeout = Math.min(2_147_483_647, remainingMilliseconds(context));
233
+ const timeout = remainingMilliseconds(context);
253
234
  this.client = new Client({
254
235
  connectionString: normalizePostgresConnectionString(source),
255
236
  connectionTimeoutMillis: timeout,
@@ -574,6 +555,7 @@ class MySqlAdapter {
574
555
  source;
575
556
  readOnly;
576
557
  context;
558
+ kind = "sql";
577
559
  confidence = "ttl_based";
578
560
  rawClient;
579
561
  client;
@@ -1052,68 +1034,6 @@ function postgresCatalogFilter(filter) {
1052
1034
  }
1053
1035
  return { where: predicates.length ? `WHERE ${predicates.join(" AND ")}` : "", params };
1054
1036
  }
1055
- function remainingMilliseconds(context) {
1056
- return Math.max(1, Math.ceil(context.deadline - Date.now()));
1057
- }
1058
- function throwIfStopped(context, outcomeUnknown) {
1059
- if (context.signal?.aborted || context.deadline <= Date.now()) {
1060
- throw stoppedError(context, outcomeUnknown);
1061
- }
1062
- }
1063
- function stoppedError(context, outcomeUnknown) {
1064
- const aborted = context.signal?.aborted ?? false;
1065
- return new AdapterExecutionError(aborted ? "Database operation cancelled." : "Database operation timed out.", aborted ? "aborted" : "timeout", outcomeUnknown);
1066
- }
1067
- function withContext(promise, context, onStop, outcomeUnknown) {
1068
- try {
1069
- throwIfStopped(context, outcomeUnknown);
1070
- }
1071
- catch (error) {
1072
- try {
1073
- onStop();
1074
- }
1075
- catch {
1076
- // Preserve deadline/cancellation error.
1077
- }
1078
- return Promise.reject(error);
1079
- }
1080
- return new Promise((resolve, reject) => {
1081
- let settled = false;
1082
- const finish = (action) => {
1083
- if (settled)
1084
- return;
1085
- settled = true;
1086
- clearTimeout(timer);
1087
- context.signal?.removeEventListener("abort", stop);
1088
- action();
1089
- };
1090
- const stop = () => {
1091
- finish(() => {
1092
- try {
1093
- onStop();
1094
- }
1095
- catch {
1096
- // Preserve deadline/cancellation error.
1097
- }
1098
- reject(stoppedError(context, outcomeUnknown));
1099
- });
1100
- };
1101
- const stopped = () => Boolean(context.signal?.aborted) || context.deadline <= Date.now();
1102
- const timer = setTimeout(stop, remainingMilliseconds(context));
1103
- context.signal?.addEventListener("abort", stop, { once: true });
1104
- promise.then((value) => {
1105
- if (stopped())
1106
- stop();
1107
- else
1108
- finish(() => resolve(value));
1109
- }, (error) => {
1110
- if (stopped())
1111
- stop();
1112
- else
1113
- finish(() => reject(error));
1114
- });
1115
- });
1116
- }
1117
1037
  function postgresErrorCode(error) {
1118
1038
  if (!error || typeof error !== "object")
1119
1039
  return undefined;
@@ -0,0 +1,6 @@
1
+ import { type ActionResult, type Core } from "./core.js";
2
+ import type { SessionRecord } from "./store.js";
3
+ import type { CatalogObject, DescribeObjectData, ExecutionOptions, ListObjectsData, ListObjectsFilter } from "./types.js";
4
+ export declare function inspectSchema(core: Core, session: SessionRecord, kind: string, table: string | undefined, options: ExecutionOptions): Promise<ActionResult<unknown>>;
5
+ export declare function listObjects(core: Core, session: SessionRecord, filter: ListObjectsFilter, options: ExecutionOptions): Promise<ActionResult<ListObjectsData>>;
6
+ export declare function describeObject(core: Core, session: SessionRecord, object: CatalogObject, options: ExecutionOptions): Promise<ActionResult<DescribeObjectData>>;
@@ -0,0 +1,52 @@
1
+ import { version } from "./connection.js";
2
+ import { adapterOfKind } from "./core.js";
3
+ import { StateQLError } from "./errors.js";
4
+ const OBJECT_KINDS = ["table", "view", "collection", "function", "trigger", "enum", "key"];
5
+ export async function inspectSchema(core, session, kind, table, options) {
6
+ const connection = core.requireConnection(session);
7
+ core.rejectDuringStagedTransaction(session, "Schema inspection");
8
+ if (connection.driver === "redis") {
9
+ throw new StateQLError("INVALID_COMMAND", "Legacy inspect is not supported for Redis; use listObjects or describeObject.");
10
+ }
11
+ return catalogRead(core, session, connection, options, (adapter) => adapter.kind === "mongodb"
12
+ ? adapter.inspect(kind, table)
13
+ : adapterOfKind(adapter, "sql").inspect(kind, table));
14
+ }
15
+ export async function listObjects(core, session, filter, options) {
16
+ validateCatalogFilter(filter);
17
+ const connection = core.requireConnection(session);
18
+ core.rejectDuringStagedTransaction(session, "Catalog discovery");
19
+ return catalogRead(core, session, connection, options, (adapter) => adapter.listObjects(filter));
20
+ }
21
+ export async function describeObject(core, session, object, options) {
22
+ validateCatalogObject(object);
23
+ const connection = core.requireConnection(session);
24
+ core.rejectDuringStagedTransaction(session, "Catalog description");
25
+ return catalogRead(core, session, connection, options, (adapter) => adapter.describeObject(object));
26
+ }
27
+ async function catalogRead(core, session, connection, options, read) {
28
+ const context = core.executionContext(options);
29
+ return core.withAdapter(session, connection, "inspect", context, async (adapter) => ({
30
+ data: await read(adapter),
31
+ executed: true,
32
+ stateVersion: version(connection),
33
+ confidence: adapter.confidence,
34
+ }));
35
+ }
36
+ function validateCatalogFilter(filter) {
37
+ if (!filter || typeof filter !== "object" || Array.isArray(filter) || Object.keys(filter).some((key) => !["kind", "schema", "search", "offset", "limit"].includes(key)))
38
+ throw new StateQLError("INVALID_COMMAND", "Catalog filter contains unknown fields.");
39
+ if (filter.kind !== undefined && !OBJECT_KINDS.includes(filter.kind))
40
+ throw new StateQLError("INVALID_COMMAND", "Unknown catalog object kind.");
41
+ for (const [name, value] of [["schema", filter.schema], ["search", filter.search]])
42
+ if (value !== undefined && (typeof value !== "string" || !value || value.length > 200 || value.includes("\0")))
43
+ throw new StateQLError("INVALID_COMMAND", `Catalog ${name} is invalid.`);
44
+ if (filter.offset !== undefined && !((typeof filter.offset === "number" && Number.isSafeInteger(filter.offset) && filter.offset >= 0) || (typeof filter.offset === "string" && /^\d+$/.test(filter.offset))))
45
+ throw new StateQLError("INVALID_COMMAND", "Catalog offset is invalid.");
46
+ if (filter.limit !== undefined && (!Number.isSafeInteger(filter.limit) || filter.limit < 1 || filter.limit > 200))
47
+ throw new StateQLError("INVALID_COMMAND", "Catalog limit must be 1-200.");
48
+ }
49
+ function validateCatalogObject(object) {
50
+ if (!object || typeof object !== "object" || Array.isArray(object) || !OBJECT_KINDS.includes(object.kind) || typeof object.name !== "string" || !object.name || object.name.length > 500 || object.name.includes("\0") || (object.schema !== undefined && (typeof object.schema !== "string" || !object.schema || object.schema.length > 500 || object.schema.includes("\0"))) || (object.identity !== undefined && (typeof object.identity !== "string" || !object.identity || object.identity.length > 1000 || object.identity.includes("\0"))))
51
+ throw new StateQLError("INVALID_COMMAND", "Catalog object identity is invalid.");
52
+ }
package/dist/src/cli.js CHANGED
@@ -7,7 +7,7 @@ import { BSON } from "mongodb";
7
7
  import { exitCodeFor } from "./errors.js";
8
8
  import { StateQL } from "./stateql.js";
9
9
  import { agentResponse } from "./agent-response.js";
10
- import { askPassword, cliCredentialResolver, deleteOsPassword, saveOsPassword } from "./os-credentials.js";
10
+ import { askPassword, cliCredentialResolver, createOsPasswordRef, deleteOsPassword, saveOsPassword } from "./os-credentials.js";
11
11
  const USAGE = `stql connect <target> [--name NAME] [--read-only|--read-write]
12
12
  stql connect --env ENV | --credential-ref REF | --profile NAME [--name NAME] [--read-only|--read-write]
13
13
  stql disconnect|status
@@ -397,6 +397,11 @@ async function dispatchSession(action, args) {
397
397
  throw new Error(`Unknown session command "${action ?? ""}".`);
398
398
  }
399
399
  }
400
+ async function askAndSavePassword(profile, target) {
401
+ const reference = createOsPasswordRef();
402
+ await saveOsPassword(reference, target, await askPassword(profile, target));
403
+ return reference;
404
+ }
400
405
  async function dispatchProfile(action, args) {
401
406
  switch (action) {
402
407
  case "add": {
@@ -405,7 +410,7 @@ async function dispatchProfile(action, args) {
405
410
  }
406
411
  const name = requireValue(args[0], "profile name");
407
412
  const passwordRef = values["ask-password"]
408
- ? await saveOsPassword(await askPassword(name, requireValue(args[1], "TARGET for --ask-password")))
413
+ ? await askAndSavePassword(name, requireValue(args[1], "TARGET for --ask-password"))
409
414
  : undefined;
410
415
  const added = await stateql.addProfile(name, args[1], {
411
416
  ...(values.env ? { secretEnv: values.env } : {}),
@@ -426,7 +431,7 @@ async function dispatchProfile(action, args) {
426
431
  return before;
427
432
  const target = args[1] ?? before.data.target;
428
433
  const passwordRef = values["ask-password"]
429
- ? await saveOsPassword(await askPassword(name, requireValue(target ?? undefined, "TARGET for --ask-password")))
434
+ ? await askAndSavePassword(name, requireValue(target ?? undefined, "TARGET for --ask-password"))
430
435
  : undefined;
431
436
  const updated = await stateql.updateProfile(name, {
432
437
  ...(args[1] !== undefined ? { target: args[1] } : {}),
@@ -0,0 +1,16 @@
1
+ import { type ActionResult, type Core } from "./core.js";
2
+ import type { SessionRecord } from "./store.js";
3
+ import type { ConnectionData, ConnectOptions } from "./types.js";
4
+ /** Resolves the target, pings the database, and stores the connection as active. */
5
+ export declare function connect(core: Core, session: SessionRecord, target: string | undefined, options: ConnectOptions): Promise<ActionResult<ConnectionData>>;
6
+ export declare function validatedProfileSource(input: {
7
+ target?: string;
8
+ secretEnv?: string;
9
+ credentialRef?: string;
10
+ passwordRef?: string;
11
+ }): {
12
+ target: string | null;
13
+ secretEnv: string | null;
14
+ credentialRef: string | null;
15
+ passwordRef: string | null;
16
+ };
@@ -0,0 +1,205 @@
1
+ import { basename } from "node:path";
2
+ import { credentialSource, databaseUrlHasSecret, detectDriver, injectPassword, isEnvironmentName, mongoDatabaseName, normalizeSqliteSource, redisDatabaseName, validateCredentialRef, validatePasswordReferenceTarget, } from "./connection.js";
3
+ import { closeAdapterQuietly, driverDisplayName, safeCredentialErrorMessage, } from "./core.js";
4
+ import { StateQLError } from "./errors.js";
5
+ import { AdapterExecutionError, stoppedStateQLError } from "./execution.js";
6
+ import { redact } from "./util.js";
7
+ /** Resolves the target, pings the database, and stores the connection as active. */
8
+ export async function connect(core, session, target, options) {
9
+ if (session.active_transaction_id) {
10
+ throw new StateQLError("TRANSACTION_FAILED", "Commit or roll back the active transaction before connecting again.");
11
+ }
12
+ const sourceCount = [target, options.profile, options.secretEnv, options.credentialRef]
13
+ .filter((value) => value !== undefined).length;
14
+ if (sourceCount !== 1) {
15
+ throw new StateQLError("INVALID_COMMAND", "Use exactly one connection target, profile, secret environment variable, or credential reference.");
16
+ }
17
+ const passwordWithoutTarget = target === undefined || options.profile !== undefined ||
18
+ options.secretEnv !== undefined || options.credentialRef !== undefined;
19
+ if (options.passwordRef !== undefined && passwordWithoutTarget) {
20
+ throw new StateQLError("INVALID_COMMAND", "A password reference requires a literal remote connection target.");
21
+ }
22
+ const profile = connectionProfile(core, target, options);
23
+ const resolvedTarget = profile?.target ?? target;
24
+ const secretEnv = options.secretEnv ?? profile?.secret_env ?? undefined;
25
+ const credentialRef = options.credentialRef ?? profile?.credential_ref ?? undefined;
26
+ const passwordRef = options.passwordRef ?? profile?.password_ref ?? undefined;
27
+ if (secretEnv !== undefined && !isEnvironmentName(secretEnv)) {
28
+ throw new StateQLError("INVALID_COMMAND", "Secret environment variable name is invalid.");
29
+ }
30
+ if (credentialRef !== undefined)
31
+ validateCredentialRef(credentialRef);
32
+ if (passwordRef !== undefined) {
33
+ validateCredentialRef(passwordRef);
34
+ if (!resolvedTarget) {
35
+ throw new StateQLError("INVALID_COMMAND", "A password reference requires a literal remote connection target.");
36
+ }
37
+ validatePasswordReferenceTarget(resolvedTarget);
38
+ }
39
+ const readOnly = options.readOnly ?? (profile ? Boolean(profile.read_only) : true);
40
+ const context = core.executionContext(options);
41
+ const credentialDetails = {
42
+ ...(profile ? { profile: { name: profile.name } } : {}),
43
+ requestedReadOnly: readOnly,
44
+ };
45
+ const access = readOnly ? "read" : "write";
46
+ const reference = secretEnv ?? credentialRef;
47
+ const referenceSource = secretEnv !== undefined
48
+ ? "secret_env"
49
+ : credentialRef !== undefined ? "credential_ref" : undefined;
50
+ let resolved;
51
+ if (passwordRef !== undefined) {
52
+ const password = await core.resolveCredential(passwordRef, "password_ref", session, "connect", access, context, credentialDetails, resolvedTarget);
53
+ const injected = injectPassword(resolvedTarget, password);
54
+ resolved = { driver: injected.driver, adapterSource: injected.source };
55
+ }
56
+ else {
57
+ const secret = reference && referenceSource
58
+ ? await core.resolveCredential(reference, referenceSource, session, "connect", access, context, credentialDetails)
59
+ : resolvedTarget;
60
+ resolved = resolveSecretTarget(secret, referenceSource);
61
+ }
62
+ const { driver, adapterSource } = resolved;
63
+ const persistedSource = passwordRef !== undefined
64
+ ? resolvedTarget
65
+ : driver !== "sqlite" && referenceSource ? redact(adapterSource) : adapterSource;
66
+ const identitySource = passwordRef !== undefined ? resolvedTarget : adapterSource;
67
+ const databaseName = connectionDatabaseName(driver, adapterSource, identitySource);
68
+ const draft = {
69
+ id: "pending",
70
+ session_id: session.id,
71
+ name: options.name ?? profile?.name ?? databaseName,
72
+ driver,
73
+ database_name: databaseName,
74
+ source: persistedSource,
75
+ secret_env: secretEnv ?? null,
76
+ credential_ref: credentialRef ?? null,
77
+ password_ref: passwordRef ?? null,
78
+ read_only: readOnly ? 1 : 0,
79
+ version: 0,
80
+ created_at: core.now().toISOString(),
81
+ };
82
+ await pingConnection(core, draft, context, adapterSource);
83
+ const connection = core.store.addConnection({
84
+ sessionId: session.id,
85
+ actorId: core.actorId,
86
+ name: draft.name,
87
+ driver,
88
+ databaseName,
89
+ source: persistedSource,
90
+ ...(secretEnv ? { secretEnv } : {}),
91
+ ...(credentialRef ? { credentialRef } : {}),
92
+ ...(passwordRef !== undefined ? { passwordRef } : {}),
93
+ readOnly,
94
+ });
95
+ if (!connection) {
96
+ throw new StateQLError("TRANSACTION_FAILED", "A transaction became active while changing the connection.");
97
+ }
98
+ const stateConfidence = driver === "sqlite" ? "database_reported" : "ttl_based";
99
+ return {
100
+ data: {
101
+ connection_id: connection.id,
102
+ alias: connection.alias,
103
+ display_alias: connection.alias,
104
+ driver,
105
+ database: databaseName,
106
+ name: connection.name,
107
+ profile: profile?.name ?? null,
108
+ read_only: readOnly,
109
+ state_version: "sv_0",
110
+ state_confidence: stateConfidence,
111
+ },
112
+ handle: connection.id,
113
+ executed: true,
114
+ stateVersion: "sv_0",
115
+ confidence: stateConfidence,
116
+ };
117
+ }
118
+ function connectionProfile(core, target, options) {
119
+ const usesReference = Boolean(options.secretEnv || options.credentialRef) || options.passwordRef !== undefined;
120
+ const implicitProfile = !options.profile && !usesReference && target
121
+ ? core.store.getProfile(target)
122
+ : undefined;
123
+ const profile = options.profile ? core.store.getProfile(options.profile) : implicitProfile;
124
+ if (options.profile && !profile) {
125
+ throw new StateQLError("CONNECTION_NOT_FOUND", `Profile "${options.profile}" was not found.`, { suggestedAction: "Run stql profile list." });
126
+ }
127
+ if (!profile)
128
+ return undefined;
129
+ const sources = [profile.target, profile.secret_env, profile.credential_ref].filter((value) => value !== null);
130
+ const passwordWithoutTarget = profile.password_ref !== null && profile.target === null;
131
+ if (sources.length !== 1 || passwordWithoutTarget) {
132
+ throw new StateQLError("STATE_CORRUPTED", `Profile "${profile.name}" has an invalid connection source.`);
133
+ }
134
+ return profile;
135
+ }
136
+ function resolveSecretTarget(secret, referenceSource) {
137
+ if (!secret)
138
+ throw new StateQLError("INVALID_COMMAND", "Connection target is required.");
139
+ if (referenceSource) {
140
+ const resolved = credentialSource(secret, undefined, referenceSource);
141
+ return { driver: resolved.driver, adapterSource: resolved.source };
142
+ }
143
+ const driver = detectDriver(secret);
144
+ if (driver === "sqlite")
145
+ return { driver, adapterSource: normalizeSqliteSource(secret) };
146
+ if (databaseUrlHasSecret(secret)) {
147
+ throw new StateQLError("PERMISSION_DENIED", `Credential-bearing ${driverDisplayName(driver)} URLs must use --env or --credential-ref.`, { suggestedAction: "Use an environment variable or trusted host credential reference." });
148
+ }
149
+ return { driver, adapterSource: secret };
150
+ }
151
+ function connectionDatabaseName(driver, adapterSource, identitySource) {
152
+ switch (driver) {
153
+ case "sqlite": return basename(adapterSource);
154
+ case "mongodb": return mongoDatabaseName(identitySource);
155
+ case "redis": return redisDatabaseName(identitySource);
156
+ default: return new URL(identitySource).pathname.replace(/^\//, "") || driver;
157
+ }
158
+ }
159
+ async function pingConnection(core, draft, context, source) {
160
+ const adapter = await core.openAdapter(draft, context, source);
161
+ try {
162
+ await adapter.ping();
163
+ }
164
+ catch (error) {
165
+ if (error instanceof AdapterExecutionError)
166
+ throw stoppedStateQLError(error, false);
167
+ throw new StateQLError("CONNECTION_FAILED", safeCredentialErrorMessage(error, source), { retryable: true });
168
+ }
169
+ finally {
170
+ await closeAdapterQuietly(adapter);
171
+ }
172
+ }
173
+ export function validatedProfileSource(input) {
174
+ const sourceCount = [input.target, input.secretEnv, input.credentialRef].filter((value) => value !== undefined).length;
175
+ const emptySource = input.target === "" || input.secretEnv === "" || input.credentialRef === "";
176
+ if (sourceCount !== 1 || emptySource) {
177
+ throw new StateQLError("INVALID_COMMAND", "Profile requires exactly one target, secret environment variable, or credential reference.");
178
+ }
179
+ if (input.secretEnv !== undefined && !isEnvironmentName(input.secretEnv))
180
+ throw new StateQLError("INVALID_COMMAND", "Secret environment variable name is invalid.");
181
+ if (input.credentialRef !== undefined)
182
+ validateCredentialRef(input.credentialRef);
183
+ if (input.passwordRef !== undefined)
184
+ validateCredentialRef(input.passwordRef);
185
+ let target = input.target ?? null;
186
+ if (input.passwordRef !== undefined && target === null) {
187
+ throw new StateQLError("INVALID_COMMAND", "A password reference requires a literal remote profile target.");
188
+ }
189
+ if (target) {
190
+ const driver = input.passwordRef !== undefined
191
+ ? validatePasswordReferenceTarget(target)
192
+ : detectDriver(target);
193
+ if (input.passwordRef === undefined && driver !== "sqlite" && databaseUrlHasSecret(target)) {
194
+ throw new StateQLError("PERMISSION_DENIED", `Credential-bearing ${driverDisplayName(driver)} URLs must use --env or --credential-ref.`);
195
+ }
196
+ if (driver === "sqlite")
197
+ target = normalizeSqliteSource(target);
198
+ }
199
+ return {
200
+ target,
201
+ secretEnv: input.secretEnv ?? null,
202
+ credentialRef: input.credentialRef ?? null,
203
+ passwordRef: input.passwordRef ?? null,
204
+ };
205
+ }
@@ -0,0 +1,78 @@
1
+ import { AsyncLocalStorage } from "node:async_hooks";
2
+ import { type DatabaseAdapter } from "./adapters.js";
3
+ import { type AdapterContext } from "./execution.js";
4
+ import type { ConnectionRecord, ResultRecord, SessionRecord, StateStore, TransactionRecord } from "./store.js";
5
+ import type { CommandExecutionContext, CommandOrigin, CredentialAccess, CredentialOperation, CredentialRequest, CredentialResolver, CredentialSource, ExecutionOptions, HistoryCategory, Response, ResultData, StateConfidence, Warning } from "./types.js";
6
+ export interface ActionResult<T> {
7
+ data: T;
8
+ handle?: string;
9
+ executed?: boolean;
10
+ cached?: boolean;
11
+ warnings?: Warning[];
12
+ stateVersion?: string;
13
+ confidence?: StateConfidence;
14
+ session?: SessionRecord;
15
+ }
16
+ export interface CoreSettings {
17
+ previewRows: number;
18
+ cacheTtlSeconds: number;
19
+ resultTtlSeconds: number;
20
+ maxCellCharacters: number;
21
+ maxResultRows: number;
22
+ maxResultBytes: number;
23
+ timeoutMs: number;
24
+ credentialTimeoutMs: number;
25
+ }
26
+ type NativeDriver = "mongodb" | "redis";
27
+ type SqlCommand = "query" | "exec" | "plan";
28
+ /** State and checks shared by every command; one instance per StateQL. */
29
+ export declare class Core {
30
+ readonly store: StateStore;
31
+ readonly settings: CoreSettings;
32
+ readonly sessionName: string;
33
+ readonly actorId: string;
34
+ readonly now: () => Date;
35
+ readonly signal: AbortSignal | undefined;
36
+ private readonly credentialResolver;
37
+ readonly commandContexts: AsyncLocalStorage<CommandExecutionContext>;
38
+ constructor(store: StateStore, settings: CoreSettings, sessionName: string, actorId: string, now: () => Date, signal: AbortSignal | undefined, credentialResolver: CredentialResolver | undefined);
39
+ withCommandContext<T>(supplied: CommandExecutionContext, action: () => T): T;
40
+ executionContext(options: ExecutionOptions): AdapterContext;
41
+ expiresAt(milliseconds: number): string;
42
+ openAdapter(connection: ConnectionRecord, context: AdapterContext, source: string): Promise<DatabaseAdapter>;
43
+ /** Resolves read credentials, then runs the action on a fresh adapter. */
44
+ withAdapter<T>(session: SessionRecord, connection: ConnectionRecord, operation: CredentialOperation, context: AdapterContext, action: (adapter: DatabaseAdapter) => Promise<T>): Promise<T>;
45
+ /** Opens the adapter, maps driver errors to StateQL errors, and always closes it. */
46
+ runOnAdapter<T>(connection: ConnectionRecord, context: AdapterContext, source: string, action: (adapter: DatabaseAdapter) => Promise<T>): Promise<T>;
47
+ run<T>(command: string, action: (session: SessionRecord) => Promise<ActionResult<T>>, historySql?: string | (() => string | undefined), historyTarget?: string): Promise<Response<T>>;
48
+ /** Runs a command on a stored result that has not expired. */
49
+ withResult<T>(command: string, idOrAlias: string, action: (result: ResultRecord, session: SessionRecord) => Promise<ActionResult<T>>): Promise<Response<T>>;
50
+ resolveConnectionSource(connection: ConnectionRecord, session: SessionRecord, operation: CredentialOperation, access: CredentialAccess, context: AdapterContext): Promise<string>;
51
+ resolveCredential(reference: string, source: CredentialSource, session: SessionRecord, operation: CredentialOperation, access: CredentialAccess, context: AdapterContext, details?: Pick<CredentialRequest, "profile" | "requestedReadOnly" | "connection">, passwordTarget?: string): Promise<string>;
52
+ requireConnection(session: SessionRecord): ConnectionRecord;
53
+ requireSqlConnection(session: SessionRecord, command: SqlCommand): ConnectionRecord;
54
+ requireNativeConnection(session: SessionRecord, driver: NativeDriver, command: SqlCommand): ConnectionRecord;
55
+ requireWritable(connection: ConnectionRecord): void;
56
+ requireResult(idOrAlias: string, session: SessionRecord): ResultRecord;
57
+ requireActiveTransaction(session: SessionRecord, id?: string): TransactionRecord;
58
+ rejectDuringStagedTransaction(session: SessionRecord, operation: string): void;
59
+ throwMembershipDenied(session: SessionRecord): never;
60
+ resultData(result: ResultRecord, cached: boolean, previewRows?: number): ResultData;
61
+ cacheValid(result: ResultRecord, stateVersion: string, stateSignature: string): boolean;
62
+ }
63
+ export declare function adapterOfKind<K extends DatabaseAdapter["kind"]>(adapter: DatabaseAdapter, kind: K): Extract<DatabaseAdapter, {
64
+ kind: K;
65
+ }>;
66
+ export declare function rejectSqlOnNativeConnection(connection: ConnectionRecord, command: SqlCommand): void;
67
+ export declare function driverDisplayName(driver: ConnectionRecord["driver"]): string;
68
+ export declare function parseCommandOrigin(value: unknown): CommandOrigin;
69
+ export declare function mergeCommandExecutionContext(inherited: CommandExecutionContext | undefined, supplied: CommandExecutionContext): CommandExecutionContext;
70
+ export declare function closeAdapterQuietly(adapter: DatabaseAdapter): Promise<void>;
71
+ export declare function safeCredentialErrorMessage(error: unknown, source: string): string;
72
+ export declare function executionTimeout(value: number, name?: string): number;
73
+ export declare function nonNegativeInteger(value: number, name: string): number;
74
+ export declare function positiveInteger(value: number, name: string): number;
75
+ export declare function errorMessage(error: unknown): string;
76
+ export declare function historyCategory(command: string): HistoryCategory;
77
+ export declare function parseHistoryCategory(value: unknown): HistoryCategory;
78
+ export {};