@fadhilp/stateql 0.8.1 → 0.10.0

package/dist/src/connection.js

@@ -16,8 +16,10 @@ export function detectDriver(target) {
         return "mysql";
     if (/^mongodb(?:\+srv)?:\/\//i.test(target))
         return "mongodb";
+    if (/^rediss?:\/\//i.test(target))
+        return "redis";
     if (/^[a-z][a-z\d+.-]*:\/\//i.test(target)) {
-        throw new StateQLError("UNSUPPORTED_DRIVER", "Only MongoDB, MySQL, PostgreSQL, and SQLite are supported.");
+        throw new StateQLError("UNSUPPORTED_DRIVER", "Only MongoDB, MySQL, PostgreSQL, Redis, and SQLite are supported.");
     }
     return "sqlite";
 }
@@ -44,6 +46,20 @@ export function mongoDatabaseName(target) {
     }
     throw new StateQLError("INVALID_COMMAND", "MongoDB URL must include an explicit database name.");
 }
+export function redisDatabaseName(target) {
+    try {
+        const url = new URL(target);
+        if (!url.hostname || !["redis:", "rediss:"].includes(url.protocol.toLowerCase()))
+            throw new Error();
+        const path = url.pathname.replace(/^\//, "");
+        if (path && !/^\d+$/.test(path))
+            throw new Error();
+        return `db${path || "0"}`;
+    }
+    catch {
+        throw new StateQLError("INVALID_COMMAND", "Invalid Redis URL or database number.");
+    }
+}
 export function credentialSource(value, expectedDriver, referenceSource = "secret_env") {
     const sourceLabel = referenceSource === "credential_ref"
         ? "Credential reference"
@@ -51,7 +67,7 @@ export function credentialSource(value, expectedDriver, referenceSource = "secre
     const explicitSqlite = /^sqlite:(?!\/\/)/i.test(value);
     const driver = explicitSqlite ? "sqlite" : detectDriver(value);
     if (driver === "sqlite" && (!explicitSqlite || value.length === 7)) {
-        throw new StateQLError("INVALID_COMMAND", `${sourceLabel} must contain a complete PostgreSQL/MySQL URL or an explicit sqlite: source; MongoDB URLs are also supported.`, {
+        throw new StateQLError("INVALID_COMMAND", `${sourceLabel} must contain a complete PostgreSQL/MySQL/Redis URL or an explicit sqlite: source; MongoDB URLs are also supported.`, {
             suggestedAction: "Store the full database URL, or prefix an SQLite path with sqlite:.",
         });
     }

package/dist/src/index.d.ts

@@ -1,4 +1,5 @@
 export { StateQL } from "./stateql.js";
 export { CredentialResolutionError, StateQLError, exitCodeFor, } from "./errors.js";
 export type { CredentialResolutionFailure } from "./errors.js";
-export type { ActorData, ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, BatchCommandName, BatchOptions, CapabilitiesData, CommandExecutionContext, CommandOrigin, CloseSessionData, Column, ColumnsData, CommitTransactionData, ConnectOptions, ConnectionData, CountData, CredentialAccess, CredentialOperation, CredentialRequest, CredentialSource, CredentialResolver, DisconnectData, DoctorData, Driver, ExecData, ExecOptions, ExecutionOptions, ExportData, Failure, FilterOptions, HistoryData, HistoryEntry, HistoryOptions, MongoAggregateOptions, MongoDocument, MongoFindOptions, MongoMutationOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, MongoWriteOutcome, OperationData, PlanData, PlanOptions, ProfileData, ProfileOptions, ProfilesData, PurgeData, QueryOptions, RecentOperationData, RecentResultData, RemovedProfileData, Response, ResultData, RollbackTransactionData, Row, RowsData, RowsOptions, SqlParameters, SqlDriver, StateQLActorOptions, StateQLOptions, StateConfidence, StateQLSnapshot, StatusConnectionData, StatusData, Success, SessionData, SessionListItem, SessionsData, SessionSummaryData, TransactionData, TransactionReferenceData, Warning, } from "./types.js";
+export type { TableChange, TableIdentity, TableUpdate } from "./table-editor.js";
+export type { ActorData, ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, BatchCommandName, BatchOptions, CatalogObject, CatalogObjectKind, DescribeObjectData, ListObjectsData, ListObjectsFilter, CapabilitiesData, CommandExecutionContext, CommandOrigin, CloseSessionData, Column, ColumnsData, CommitTransactionData, ConnectOptions, ConnectionData, CountData, CredentialAccess, CredentialOperation, CredentialRequest, CredentialSource, CredentialResolver, DisconnectData, DoctorData, Driver, ExecData, ExecOptions, ExecutionOptions, ExportData, Failure, FilterOptions, HistoryData, HistoryEntry, HistoryCategory, HistoryOptions, MongoAggregateOptions, MongoDocument, MongoFindOptions, MongoMutationOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, MongoWriteOutcome, OperationData, PlanData, PlanOptions, ProfileData, ProfileOptions, ProfileUpdateOptions, ProfilesData, PurgeData, RedisCommand, RedisExecOptions, RedisPlanOptions, RedisQueryOptions, RedisWriteOutcome, QueryOptions, RecentOperationData, RecentResultData, RemovedProfileData, Response, ResultData, RollbackTransactionData, Row, RowsData, RowsOptions, SqlParameters, SqlDriver, StateQLActorOptions, StateQLOptions, StateConfidence, StateQLSnapshot, StateQLSnapshotOptions, StatusConnectionData, StatusData, Success, SessionData, SessionListItem, SessionsData, SessionSummaryData, TransactionData, TransactionReferenceData, Warning, } from "./types.js";

package/dist/src/migrations.js

@@ -80,6 +80,41 @@ const MIGRATIONS = [
         apply: migrateCredentialRefs,
         validate: validateCredentialRefs,
     },
+    {
+        name: "history_target_v1",
+        apply(db) { addColumn(db, "history", "target", "TEXT"); },
+        validate(db) { requireColumns(db, "history", ["target"]); },
+    },
+    {
+        name: "generated_aliases_v1",
+        apply(db) {
+            addColumn(db, "aliases", "generated", "INTEGER NOT NULL DEFAULT 0");
+            db.exec("CREATE UNIQUE INDEX IF NOT EXISTS aliases_generated_result ON aliases(result_id) WHERE generated = 1");
+        },
+        validate(db) {
+            requireColumns(db, "aliases", ["generated"]);
+            requireIndexes(db, ["aliases_generated_result"]);
+        },
+    },
+    {
+        name: "history_classification_v1",
+        apply(db) {
+            addColumn(db, "history", "category", "TEXT NOT NULL DEFAULT 'management'");
+            addColumn(db, "history", "internal", "INTEGER NOT NULL DEFAULT 0");
+            db.exec(`
+        UPDATE history SET category = 'statement'
+        WHERE category = 'management' AND command IN
+          ('query','exec','plan','apply','filter','mongo.query','mongo.exec','mongo.plan','redis.query','redis.exec','redis.plan');
+        UPDATE history SET category = 'introspection'
+        WHERE category = 'management' AND (command LIKE 'inspect.%' OR command IN ('objects.list','object.describe','table.read'));
+      `);
+            db.exec("CREATE INDEX IF NOT EXISTS history_session_category ON history(session_id, category, internal)");
+        },
+        validate(db) {
+            requireColumns(db, "history", ["category", "internal"]);
+            requireIndexes(db, ["history_session_category"]);
+        },
+    },
 ];
 export function runMigrations(db, now) {
     db.exec(`
@@ -181,6 +216,7 @@ function createInitialSchema(db) {
       session_id TEXT NOT NULL,
       name TEXT NOT NULL,
       result_id TEXT NOT NULL,
+      generated INTEGER NOT NULL DEFAULT 0,
       PRIMARY KEY(session_id, name),
       FOREIGN KEY(result_id) REFERENCES results(id)
     );
@@ -244,6 +280,8 @@ function createInitialSchema(db) {
       actor_id TEXT NOT NULL,
       command TEXT NOT NULL,
       origin TEXT NOT NULL DEFAULT 'legacy',
+      category TEXT NOT NULL DEFAULT 'management',
+      internal INTEGER NOT NULL DEFAULT 0,
       sql TEXT,
       handle TEXT,
       executed INTEGER NOT NULL,

package/dist/src/mongodb.d.ts

@@ -1,6 +1,6 @@
 import { type AdapterContext } from "./adapters.js";
 import type { ConnectionRecord } from "./store.js";
-import type { Column, MongoReadCommand, MongoWriteCommand, MongoWriteOutcome, Row } from "./types.js";
+import type { CatalogObject, Column, DescribeObjectData, ListObjectsData, ListObjectsFilter, MongoReadCommand, MongoWriteCommand, MongoWriteOutcome, Row } from "./types.js";
 interface MongoReadResult {
     rows: Row[];
     columns: Column[];
@@ -34,9 +34,11 @@ export declare class MongoAdapter {
     ping(): Promise<void>;
     signature(): Promise<string>;
     read(command: MongoReadCommand, maxRows: number): Promise<MongoReadResult>;
-    write(command: MongoWriteCommand): Promise<MongoWriteResult>;
-    writeBatch(commands: MongoWriteCommand[], isolation: string): Promise<MongoWriteResult[]>;
+    write(command: MongoWriteCommand, expectedRows?: 1): Promise<MongoWriteResult>;
+    writeBatch(commands: MongoWriteCommand[], isolation: string, expectedRows?: boolean): Promise<MongoWriteResult[]>;
     inspect(kind: string, name?: string): Promise<unknown>;
+    listObjects(filter: ListObjectsFilter): Promise<ListObjectsData>;
+    describeObject(object: CatalogObject): Promise<DescribeObjectData>;
     close(): Promise<void>;
     private connect;
     private executeWrite;

package/dist/src/mongodb.js

@@ -221,7 +221,7 @@ export class MongoAdapter {
             await cursor?.close().catch(() => undefined);
         }
     }
-    async write(command) {
+    async write(command, expectedRows) {
         let value;
         try {
             value = validateMongoWriteCommand(command);
@@ -240,17 +240,24 @@ export class MongoAdapter {
                 throw error;
             throw new AdapterWriteError(errorText(error), false);
         }
+        if (expectedRows === 1 && (value.operation !== "updateOne" || value.options?.upsert))
+            throw new AdapterWriteError("Conditional edits require updateOne without upsert.", false);
         try {
-            return await withContext(this.executeWrite(value), this.context, () => this.stop(), true);
+            const result = await withContext(this.executeWrite(value), this.context, () => this.stop(), true);
+            if (expectedRows === 1 && result.outcome.matched_count !== 1)
+                throw new AdapterWriteError("ROW_CONFLICT: The document changed or was removed.", false);
+            return result;
         }
         catch (error) {
+            if (error instanceof AdapterWriteError)
+                throw error;
             const stopped = writeStoppedError(error, this.context, true);
             if (stopped)
                 throw stopped;
             throw new AdapterWriteError(errorText(error), knownNoWrite(error) ? false : true);
         }
     }
-    async writeBatch(commands, isolation) {
+    async writeBatch(commands, isolation, expectedRows = false) {
         if (isolation.toLowerCase() !== "snapshot") {
             throw new BatchWriteError(`Unsupported MongoDB isolation level "${isolation}".`, false);
         }
@@ -288,7 +295,10 @@ export class MongoAdapter {
             for (const command of values) {
                 throwIfStopped(this.context, dispatched);
                 dispatched = true;
-                results.push(await withContext(this.executeWrite(command, session), this.context, () => this.stop(), true));
+                const result = await withContext(this.executeWrite(command, session), this.context, () => this.stop(), true);
+                if (expectedRows && result.outcome.matched_count !== 1)
+                    throw new Error("ROW_CONFLICT: A document changed or was removed.");
+                results.push(result);
             }
             throwIfStopped(this.context, dispatched);
             committing = true;
@@ -342,6 +352,10 @@ export class MongoAdapter {
             if (kind === "constraints") {
                 return { collection: collectionName, constraints: [] };
             }
+            if (kind === "editable") {
+                const objects = await this.client.db(this.databaseName).listCollections({ name: collectionName }, { nameOnly: true, signal: operationSignal(this.context), maxTimeMS: remainingMilliseconds(this.context) }).toArray();
+                return { writable: objects[0]?.type === "collection", columns: [] };
+            }
             const columns = await this.sampleColumns(collectionName);
             if (kind === "columns")
                 return { collection: collectionName, columns };
@@ -362,6 +376,51 @@ export class MongoAdapter {
             throw readError(error, this.context);
         }
     }
+    async listObjects(filter) {
+        if (filter.kind !== undefined && filter.kind !== "collection" && filter.kind !== "view")
+            throw new Error(`MongoDB does not support catalog kind "${filter.kind}".`);
+        if (filter.schema !== undefined)
+            throw new Error("MongoDB collections do not use schemas.");
+        const offset = filter.offset ?? 0;
+        const limit = filter.limit ?? 50;
+        if (typeof offset !== "number" || !Number.isSafeInteger(offset) || offset < 0 || offset > 1_000_000 || !Number.isSafeInteger(limit) || limit < 1 || limit > 200)
+            throw new Error("Invalid MongoDB catalog page bounds.");
+        if (filter.search !== undefined && (!filter.search || filter.search.length > 200 || filter.search.includes("\0")))
+            throw new Error("Invalid MongoDB catalog search.");
+        await this.connect();
+        const query = {};
+        if (filter.kind === "collection")
+            query.type = "collection";
+        if (filter.kind === "view")
+            query.type = "view";
+        const cursor = this.client.db(this.databaseName).listCollections(query, {
+            nameOnly: true,
+            signal: operationSignal(this.context),
+            maxTimeMS: remainingMilliseconds(this.context),
+            timeoutMS: remainingMilliseconds(this.context),
+            batchSize: Math.min(limit + 1, 201),
+        });
+        const fetched = await collectCursor(cursor, offset + limit + 1, this.context);
+        const rows = fetched.slice(offset);
+        const more = rows.length > limit;
+        return {
+            objects: rows.slice(0, limit).map((row) => ({ kind: row.type === "view" ? "view" : "collection", name: String(row.name), identity: String(row.name) })),
+            next_offset: more ? offset + limit : null,
+            supported_kinds: ["collection", "view"],
+        };
+    }
+    async describeObject(object) {
+        if ((object.kind !== "collection" && object.kind !== "view") || object.schema !== undefined)
+            throw new Error(`MongoDB does not support catalog kind "${object.kind}".`);
+        const rows = await collectCursor(this.client.db(this.databaseName).listCollections({ name: object.name }, { nameOnly: false, signal: operationSignal(this.context), maxTimeMS: remainingMilliseconds(this.context), timeoutMS: remainingMilliseconds(this.context), batchSize: 1 }), 1, this.context);
+        const found = rows[0];
+        if (!found)
+            throw new Error("Catalog object was not found.");
+        return ejsonSafe({
+            object: { kind: found.type === "view" ? "view" : "collection", name: found.name, identity: found.name },
+            definition: { type: found.type, options: found.options ?? {} },
+        });
+    }
     async close() {
         if (this.closed)
             return;
@@ -775,6 +834,9 @@ function ejsonSafe(value) {
         return null;
     return JSON.parse(BSON.EJSON.stringify(value, { relaxed: false }));
 }
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 function remainingMilliseconds(context) {
     return Math.max(1, Math.min(2_147_483_647, Math.ceil(context.deadline - Date.now())));
 }

package/dist/src/redis.d.ts

@@ -0,0 +1,44 @@
+import { type AdapterContext } from "./adapters.js";
+import type { CatalogObject, DescribeObjectData, ListObjectsData, ListObjectsFilter, RedisCommand, RedisWriteOutcome, Row, Column } from "./types.js";
+export interface RedisReadResult {
+    rows: Row[];
+    columns: Column[];
+    nextCursor?: string | null;
+}
+export interface RedisPrecondition {
+    key: string;
+    fingerprint: string;
+    /** Absolute expiry in epoch milliseconds, or Redis -1/-2 sentinel. */
+    expiresAt: number;
+}
+export interface RedisWriteResult {
+    affectedRows: number;
+    outcome: RedisWriteOutcome;
+}
+export declare function validateRedisReadCommand(value: unknown): RedisCommand;
+export declare function validateRedisWriteCommand(value: unknown): RedisCommand;
+export declare function serializeRedisCommand(command: RedisCommand): string;
+export declare function deserializeRedisCommand(value: string): RedisCommand;
+export declare class RedisAdapter {
+    private readonly readOnly;
+    private readonly context;
+    readonly confidence: "ttl_based";
+    private readonly client;
+    private connected;
+    private closed;
+    constructor(source: string, readOnly: boolean, context: AdapterContext);
+    ping(): Promise<void>;
+    signature(): Promise<string>;
+    read(input: RedisCommand): Promise<RedisReadResult>;
+    precondition(input: RedisCommand): Promise<RedisPrecondition>;
+    write(input: RedisCommand, precondition?: RedisPrecondition): Promise<RedisWriteResult>;
+    listObjects(filter: ListObjectsFilter): Promise<ListObjectsData>;
+    describeObject(object: CatalogObject): Promise<DescribeObjectData>;
+    close(): Promise<void>;
+    private scanValue;
+    private expirationIdentity;
+    private keyFingerprint;
+    private connect;
+    private execute;
+    private stop;
+}