@fadhilp/stateql 0.1.2 → 0.2.2

package/dist/src/cli.js

@@ -24,6 +24,7 @@ const parsed = parseArgs({
         "allow-destructive": { type: "boolean" },
         offset: { type: "string" },
         limit: { type: "string" },
+        "timeout-ms": { type: "string" },
         format: { type: "string" },
         output: { type: "string" },
         isolation: { type: "string" },
@@ -35,14 +36,21 @@ const parsed = parseArgs({
 const [command, subcommand, ...rest] = parsed.positionals;
 const values = parsed.values;
 if (values.version) {
-    console.log("0.1.0");
+    console.log(packageVersion());
     process.exit(0);
 }
 if (values.help || !command) {
     console.log(helpText());
     process.exit(0);
 }
-const stateql = new StateQL();
+const abortController = new AbortController();
+process.once("SIGINT", () => abortController.abort());
+const stateql = new StateQL({
+    ...(values["timeout-ms"] === undefined
+        ? {}
+        : { timeoutMs: Number(values["timeout-ms"]) }),
+    signal: abortController.signal,
+});
 try {
     if (command === "batch" || command === "pipe") {
         await runBatch();
@@ -494,7 +502,7 @@ function extractHandle(data) {
     return undefined;
 }
 function helpText() {
-    return `StateQL 0.1.0
+    return `StateQL ${packageVersion()}
 
 Usage: stql <command> [arguments] [options]
 
@@ -511,6 +519,11 @@ Commands:
   pipe
 
 SQL parameters: --params JSON, repeated --param VALUE, or --params-file FILE.
+Deadline: --timeout-ms N (default: 30000). Ctrl+C cancels database work.
 Output: --output agent|json|jsonl|text|silent (default: agent).
 Batch/pipe accept JSON array files or JSONL streams. Stop on first error.`;
 }
+function packageVersion() {
+    const packageJson = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
+    return packageJson.version;
+}

package/dist/src/connection.d.ts

@@ -0,0 +1,10 @@
+import type { ConnectionRecord } from "./store.js";
+import type { Driver, StateConfidence } from "./types.js";
+export declare function databaseIdentity(connection: ConnectionRecord): unknown;
+export declare function detectDriver(target: string): Driver;
+export declare function normalizeSqliteSource(target: string): string;
+export declare function databaseUrlHasSecret(target: string): boolean;
+export declare function version(connection: ConnectionRecord): string;
+export declare function confidence(connection: ConnectionRecord): StateConfidence;
+export declare function validateProfileName(name: string): void;
+export declare function isEnvironmentName(name: string): boolean;

package/dist/src/connection.js

@@ -0,0 +1,51 @@
+import { resolve } from "node:path";
+import { StateQLError } from "./errors.js";
+export function databaseIdentity(connection) {
+    return {
+        driver: connection.driver,
+        database: connection.database_name,
+        source: connection.source,
+        secretEnvironment: connection.secret_env,
+    };
+}
+export function detectDriver(target) {
+    if (/^postgres(?:ql)?:\/\//i.test(target))
+        return "postgres";
+    if (/^mysql:\/\//i.test(target))
+        return "mysql";
+    if (/^[a-z][a-z\d+.-]*:\/\//i.test(target)) {
+        throw new StateQLError("UNSUPPORTED_DRIVER", "Only MySQL, PostgreSQL, and SQLite are supported.");
+    }
+    return "sqlite";
+}
+export function normalizeSqliteSource(target) {
+    const source = target.startsWith("sqlite:") ? target.slice(7) : target;
+    if (source === ":memory:") {
+        throw new StateQLError("INVALID_COMMAND", "SQLite :memory: databases cannot persist across StateQL commands.");
+    }
+    return resolve(source);
+}
+export function databaseUrlHasSecret(target) {
+    try {
+        const url = new URL(target);
+        return (Boolean(url.password) ||
+            [...url.searchParams.keys()].some((key) => /pass|token|secret|private[_-]?key|api[_-]?key/i.test(key)));
+    }
+    catch {
+        throw new StateQLError("INVALID_COMMAND", "Invalid database URL.");
+    }
+}
+export function version(connection) {
+    return `sv_${connection.version}`;
+}
+export function confidence(connection) {
+    return connection.driver === "sqlite" ? "database_reported" : "ttl_based";
+}
+export function validateProfileName(name) {
+    if (/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/.test(name))
+        return;
+    throw new StateQLError("INVALID_COMMAND", "Profile name must be 1-64 letters, numbers, dots, underscores, or hyphens.");
+}
+export function isEnvironmentName(name) {
+    return /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name);
+}

package/dist/src/errors.js

@@ -20,14 +20,18 @@ export function exitCodeFor(code) {
         return 2;
     if (code.startsWith("CONNECTION_"))
         return 3;
-    if (code === "QUERY_FAILED")
+    if (code === "QUERY_FAILED" ||
+        code === "DEADLINE_EXCEEDED" ||
+        code === "OPERATION_CANCELLED")
         return 4;
     if (code === "READ_ONLY_CONNECTION" ||
         code === "UNBOUNDED_MUTATION" ||
         code === "DESTRUCTIVE_OPERATION_BLOCKED") {
         return 5;
     }
-    if (code === "POTENTIAL_DUPLICATE_WRITE" || code === "OUTCOME_UNKNOWN")
+    if (code === "POTENTIAL_DUPLICATE_WRITE" ||
+        code === "OUTCOME_UNKNOWN" ||
+        code === "IDEMPOTENCY_CONFLICT")
         return 6;
     if (code.startsWith("STALE_") || code === "RESULT_EXPIRED")
         return 7;

package/dist/src/filter.d.ts

@@ -0,0 +1,14 @@
+import type { Column, Row, SqlParameters } from "./types.js";
+interface PreparedFilter {
+    sql: string;
+    normalized: string;
+    tableName: string;
+    indexColumn: string;
+    columnNames: string[];
+    positionalParameters: number;
+    namedParameters: string[];
+}
+export declare function prepareFilterStatement(columns: Column[], predicate: string): PreparedFilter;
+export declare function filterMaterializedRows(rows: Row[], filter: PreparedFilter, parameters: SqlParameters): Row[];
+export declare function validateFilterParameters(filter: PreparedFilter, parameters: SqlParameters): void;
+export {};

package/dist/src/filter.js

@@ -0,0 +1,256 @@
+import { DatabaseSync } from "node:sqlite";
+import { StateQLError } from "./errors.js";
+import { analyzeSql } from "./sql.js";
+export function prepareFilterStatement(columns, predicate) {
+    const text = predicate.trim();
+    if (!text) {
+        throw new StateQLError("INVALID_SQL", "Filter predicate is required.");
+    }
+    const columnNames = columns.map((column) => column.name);
+    if (columnNames.length === 0) {
+        throw new StateQLError("INVALID_SQL", "Filter requires at least one result column.");
+    }
+    const names = new Set();
+    for (const name of columnNames) {
+        const normalized = name.toLowerCase();
+        if (!name || name.includes("\0") || names.has(normalized)) {
+            throw new StateQLError("INVALID_SQL", "Filter requires unique, non-empty result column names.");
+        }
+        names.add(normalized);
+    }
+    const tableName = "__stateql_filter_source";
+    let indexColumn = "__stateql_row_index";
+    while (names.has(indexColumn.toLowerCase()))
+        indexColumn += "_";
+    const sql = `SELECT ${quoteIdentifier(indexColumn)} ` +
+        `FROM ${quoteIdentifier(tableName)} WHERE (${text})`;
+    const analysis = analyzeSql(sql, "sqlite");
+    const details = analysis.ast;
+    const from = details.from;
+    const source = Array.isArray(from)
+        ? from[0]
+        : undefined;
+    if (!analysis.read ||
+        !Array.isArray(from) ||
+        from.length !== 1 ||
+        source?.table !== tableName ||
+        details.with ||
+        details.groupby ||
+        details.having ||
+        details.orderby ||
+        details.limit ||
+        details.for_update ||
+        details._next ||
+        details.set_op ||
+        containsSelect(details.where)) {
+        throw new StateQLError("INVALID_SQL", "Filter accepts one scalar predicate only.");
+    }
+    validateFilterExpression(details.where, names, tableName);
+    const bindings = filterBindings(details.where);
+    return {
+        sql,
+        normalized: analysis.normalized,
+        tableName,
+        indexColumn,
+        columnNames,
+        positionalParameters: bindings.positional,
+        namedParameters: [...bindings.named],
+    };
+}
+export function filterMaterializedRows(rows, filter, parameters) {
+    const db = new DatabaseSync(":memory:");
+    try {
+        const definitions = [
+            `${quoteIdentifier(filter.indexColumn)} INTEGER PRIMARY KEY`,
+            ...filter.columnNames.map(quoteIdentifier),
+        ];
+        db.exec(`CREATE TABLE ${quoteIdentifier(filter.tableName)} ` +
+            `(${definitions.join(", ")})`);
+        const placeholders = filter.columnNames.map(() => "?").join(", ");
+        const insert = db.prepare(`INSERT INTO ${quoteIdentifier(filter.tableName)} (` +
+            `${quoteIdentifier(filter.indexColumn)}, ` +
+            `${filter.columnNames.map(quoteIdentifier).join(", ")}) ` +
+            `VALUES (?, ${placeholders})`);
+        db.exec("BEGIN");
+        try {
+            rows.forEach((row, index) => {
+                const values = filter.columnNames.map((name) => sqliteFilterValue(row[name]));
+                insert.run(index, ...values);
+            });
+            db.exec("COMMIT");
+        }
+        catch (error) {
+            db.exec("ROLLBACK");
+            throw error;
+        }
+        const statement = db.prepare(`${filter.sql}\nORDER BY ${quoteIdentifier(filter.indexColumn)}`);
+        const selected = filterAll(statement, parameters);
+        return selected.map((row) => {
+            const index = Number(row[filter.indexColumn]);
+            if (!Number.isInteger(index) || !rows[index]) {
+                throw new StateQLError("INVALID_SQL", "Filter produced an invalid source row index.");
+            }
+            return rows[index];
+        });
+    }
+    catch (error) {
+        if (error instanceof StateQLError)
+            throw error;
+        throw new StateQLError("INVALID_SQL", errorMessage(error));
+    }
+    finally {
+        db.close();
+    }
+}
+function filterAll(statement, parameters) {
+    if (Array.isArray(parameters)) {
+        return statement.all(...parameters);
+    }
+    return statement.all(parameters);
+}
+function sqliteFilterValue(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "bigint") {
+        return value;
+    }
+    if (typeof value === "boolean")
+        return value ? 1 : 0;
+    if (value instanceof Uint8Array)
+        return value;
+    try {
+        return JSON.stringify(value) ?? null;
+    }
+    catch {
+        return String(value);
+    }
+}
+function quoteIdentifier(value) {
+    return `"${value.replaceAll('"', '""')}"`;
+}
+function containsSelect(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    if (record.type === "select")
+        return true;
+    return Object.values(record).some(containsSelect);
+}
+const FILTER_FUNCTIONS = new Set([
+    "abs",
+    "coalesce",
+    "ifnull",
+    "instr",
+    "json_extract",
+    "json_type",
+    "json_valid",
+    "length",
+    "lower",
+    "ltrim",
+    "nullif",
+    "round",
+    "rtrim",
+    "substr",
+    "substring",
+    "trim",
+    "typeof",
+    "upper",
+]);
+function validateFilterExpression(value, columns, tableName) {
+    if (!value || typeof value !== "object")
+        return;
+    const record = value;
+    if (record.type === "column_ref") {
+        const column = record.column;
+        const table = record.table;
+        if (typeof column !== "string" ||
+            !columns.has(column.toLowerCase()) ||
+            (table !== null && table !== undefined && table !== tableName)) {
+            throw new StateQLError("INVALID_SQL", `Unknown filter column "${String(column)}".`);
+        }
+    }
+    else if (record.type === "double_quote_string") {
+        const column = String(record.value);
+        if (!columns.has(column.toLowerCase())) {
+            throw new StateQLError("INVALID_SQL", `Unknown filter column "${column}".`);
+        }
+    }
+    else if (record.type === "function") {
+        const name = filterFunctionName(record);
+        if (!name || !FILTER_FUNCTIONS.has(name)) {
+            throw new StateQLError("INVALID_SQL", `Filter function "${name ?? "unknown"}" is not allowed.`);
+        }
+    }
+    Object.values(record).forEach((item) => validateFilterExpression(item, columns, tableName));
+}
+function filterFunctionName(record) {
+    const name = record.name;
+    const parts = name?.name;
+    if (!Array.isArray(parts))
+        return undefined;
+    const last = parts.at(-1);
+    return typeof last?.value === "string" ? last.value.toLowerCase() : undefined;
+}
+function filterBindings(value) {
+    const named = new Set();
+    const prefixes = new Map();
+    let positional = 0;
+    const visit = (item) => {
+        if (!item || typeof item !== "object")
+            return;
+        const record = item;
+        if (record.type === "origin" && record.value === "?")
+            positional += 1;
+        if (record.type === "param" && typeof record.value === "string") {
+            addNamed(String(record.value), `:${String(record.value)}`);
+        }
+        if (record.type === "var" &&
+            typeof record.name === "string" &&
+            (record.prefix === "$" || record.prefix === "@")) {
+            addNamed(record.name, `${String(record.prefix)}${record.name}`);
+        }
+        Object.values(record).forEach(visit);
+    };
+    const addNamed = (name, token) => {
+        const previous = prefixes.get(name);
+        if (previous && previous !== token) {
+            throw new StateQLError("INVALID_SQL", `Filter parameter "${name}" uses conflicting prefixes.`);
+        }
+        prefixes.set(name, token);
+        named.add(name);
+    };
+    visit(value);
+    if (positional && named.size) {
+        throw new StateQLError("INVALID_SQL", "Filter cannot mix positional and named parameters.");
+    }
+    return { positional, named };
+}
+export function validateFilterParameters(filter, parameters) {
+    if (filter.positionalParameters) {
+        if (!Array.isArray(parameters) ||
+            parameters.length !== filter.positionalParameters) {
+            throw new StateQLError("INVALID_SQL", `Filter requires exactly ${filter.positionalParameters} positional parameters.`);
+        }
+        return;
+    }
+    if (filter.namedParameters.length) {
+        if (Array.isArray(parameters)) {
+            throw new StateQLError("INVALID_SQL", "Filter requires named parameters.");
+        }
+        const supplied = Object.keys(parameters).sort();
+        const expected = [...filter.namedParameters].sort();
+        if (JSON.stringify(supplied) !== JSON.stringify(expected)) {
+            throw new StateQLError("INVALID_SQL", `Filter requires named parameters: ${expected.join(", ")}.`);
+        }
+        return;
+    }
+    if ((Array.isArray(parameters) && parameters.length) ||
+        (!Array.isArray(parameters) && Object.keys(parameters).length)) {
+        throw new StateQLError("INVALID_SQL", "Filter predicate has no parameters.");
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/src/index.d.ts

@@ -1,3 +1,3 @@
 export { StateQL } from "./stateql.js";
 export { StateQLError, exitCodeFor } from "./errors.js";
-export type { BatchCommand, BatchCommandName, BatchOptions, ConnectOptions, ExecOptions, Failure, FilterOptions, PlanOptions, ProfileOptions, QueryOptions, Response, RowsOptions, SqlParameters, StateQLOptions, Success, } from "./types.js";
+export type { BatchCommand, BatchCommandName, BatchOptions, ConnectOptions, ExecOptions, ExecutionOptions, Failure, FilterOptions, HistoryEntry, PlanOptions, ProfileOptions, QueryOptions, Response, RowsOptions, SqlParameters, StateQLOptions, StateQLSnapshot, Success, } from "./types.js";

package/dist/src/response-data.d.ts

@@ -0,0 +1,8 @@
+import type { OperationRecord, ProfileRecord, SessionRecord, TransactionRecord } from "./store.js";
+import type { Row, Warning } from "./types.js";
+export declare function sessionData(session: SessionRecord): unknown;
+export declare function profileData(profile: ProfileRecord): Record<string, unknown>;
+export declare function operationData(operation: OperationRecord): Record<string, unknown>;
+export declare function transactionData(transaction: TransactionRecord, statements: number): unknown;
+export declare function paginationWarnings(ordered: boolean): Warning[];
+export declare function rowsToCsv(rows: Row[], columns: string[]): string;

package/dist/src/response-data.js

@@ -0,0 +1,66 @@
+export function sessionData(session) {
+    return {
+        session_id: session.id,
+        name: session.name,
+        state: session.status,
+        active_connection: session.active_connection_id,
+        active_transaction: session.active_transaction_id,
+    };
+}
+export function profileData(profile) {
+    return {
+        profile: profile.name,
+        target: profile.target,
+        secret_env: profile.secret_env,
+        read_only: Boolean(profile.read_only),
+    };
+}
+export function operationData(operation) {
+    return {
+        operation_id: operation.id,
+        statement_type: operation.statement_type,
+        affected_rows: operation.affected_rows,
+        status: operation.status,
+        committed: operation.status === "committed",
+        transaction_id: operation.transaction_id,
+        state_version_before: operation.state_version_before,
+        state_version_after: operation.state_version_after,
+        ...(operation.replay_of ? { replay_of: operation.replay_of } : {}),
+    };
+}
+export function transactionData(transaction, statements) {
+    return {
+        transaction_id: transaction.id,
+        state: transaction.state,
+        connection_id: transaction.connection_id,
+        statements,
+        pending_writes: transaction.state === "active" ? statements : 0,
+        start_state_version: transaction.start_version,
+        isolation_level: transaction.isolation_level,
+        age_ms: Date.now() - Date.parse(transaction.created_at),
+    };
+}
+export function paginationWarnings(ordered) {
+    if (ordered)
+        return [];
+    return [
+        {
+            code: "NON_DETERMINISTIC_PAGINATION",
+            message: "Result has no explicit ORDER BY clause.",
+        },
+    ];
+}
+export function rowsToCsv(rows, columns) {
+    const encode = (value) => {
+        const text = value === null || value === undefined
+            ? ""
+            : typeof value === "object"
+                ? JSON.stringify(value)
+                : String(value);
+        return /[",\r\n]/.test(text) ? `"${text.replaceAll('"', '""')}"` : text;
+    };
+    return [
+        columns.map(encode).join(","),
+        ...rows.map((row) => columns.map((column) => encode(row[column])).join(",")),
+    ].join("\n") + "\n";
+}

package/dist/src/sql.js

@@ -18,7 +18,11 @@ export function analyzeSql(sql, driver) {
     if (!trimmed)
         throw new StateQLError("INVALID_SQL", "SQL is empty.");
     try {
-        const database = driver === "postgres" ? "Postgresql" : "Sqlite";
+        const database = driver === "postgres"
+            ? "Postgresql"
+            : driver === "mysql"
+                ? "MySQL"
+                : "Sqlite";
         const parsed = parser.astify(trimmed, { database });
         if (Array.isArray(parsed)) {
             if (parsed.length !== 1) {
@@ -50,7 +54,9 @@ export function analyzeSql(sql, driver) {
             statementType === "alter" ||
             statementType === "delete" ||
             statementType === "replace" ||
-            statementType === "truncate";
+            statementType === "truncate" ||
+            (driver === "sqlite" &&
+                /^(?:INSERT|UPDATE) OR REPLACE\b/i.test(normalized));
         return {
             ast,
             normalized,

package/dist/src/sqlite-process.d.ts

@@ -0,0 +1 @@
+export {};