@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
@@ -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 {};