taurusdb-core 0.1.0

package/dist/executor/explain.js

@@ -0,0 +1,119 @@
+function asFiniteNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === "string" && value.trim().length > 0) {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+}
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function readObjectField(row, candidates) {
+    for (const candidate of candidates) {
+        if (Object.hasOwn(row, candidate)) {
+            return row[candidate];
+        }
+    }
+    const lowerMap = new Map();
+    for (const [key, value] of Object.entries(row)) {
+        lowerMap.set(key.toLowerCase(), value);
+    }
+    for (const candidate of candidates) {
+        const value = lowerMap.get(candidate.toLowerCase());
+        if (value !== undefined) {
+            return value;
+        }
+    }
+    return undefined;
+}
+export function normalizeExplainRows(result) {
+    const rows = Array.isArray(result.rows) ? result.rows : [];
+    if (rows.length === 0) {
+        return [];
+    }
+    const first = rows[0];
+    if (isObject(first)) {
+        return rows.filter((row) => isObject(row));
+    }
+    if (Array.isArray(first) && Array.isArray(result.fields) && result.fields.length > 0) {
+        return rows
+            .filter((row) => Array.isArray(row))
+            .map((row) => {
+            const mapped = {};
+            result.fields?.forEach((field, index) => {
+                mapped[field.name] = row[index];
+            });
+            return mapped;
+        });
+    }
+    return [];
+}
+export function summarizeExplainRows(rows) {
+    const fullTableScanLikely = rows.some((row) => {
+        const scanType = readObjectField(row, ["type", "access_type"]);
+        return typeof scanType === "string" && scanType.toUpperCase() === "ALL";
+    });
+    const indexHitLikely = rows.length > 0 &&
+        rows.every((row) => {
+            const key = readObjectField(row, ["key", "possible_key", "index_name"]);
+            if (key === null || key === undefined) {
+                return false;
+            }
+            return String(key).trim().length > 0;
+        });
+    const estimatedRows = rows.reduce((sum, row) => {
+        const numeric = asFiniteNumber(readObjectField(row, ["rows", "estimated_rows"]));
+        return numeric !== undefined ? sum + numeric : sum;
+    }, 0);
+    const usesTempStructure = rows.some((row) => {
+        const extra = readObjectField(row, ["Extra", "extra", "note"]);
+        return typeof extra === "string" && /using temporary/i.test(extra);
+    });
+    const usesFilesort = rows.some((row) => {
+        const extra = readObjectField(row, ["Extra", "extra", "note"]);
+        return typeof extra === "string" && /using filesort/i.test(extra);
+    });
+    const riskHints = [];
+    if (fullTableScanLikely) {
+        riskHints.push("Explain suggests potential full table scan.");
+    }
+    if (!indexHitLikely && rows.length > 0) {
+        riskHints.push("Explain suggests low index hit probability.");
+    }
+    if (usesTempStructure) {
+        riskHints.push("Explain contains Using temporary.");
+    }
+    if (usesFilesort) {
+        riskHints.push("Explain contains Using filesort.");
+    }
+    return {
+        fullTableScanLikely,
+        indexHitLikely,
+        estimatedRows: rows.length > 0 ? estimatedRows : null,
+        usesTempStructure,
+        usesFilesort,
+        riskHints,
+    };
+}
+export function buildExplainRecommendations(summary) {
+    const recommendations = [];
+    if (summary.fullTableScanLikely) {
+        recommendations.push("Consider adding WHERE filters and an index to avoid full table scans.");
+    }
+    if (!summary.indexHitLikely) {
+        recommendations.push("Review indexes for filter and join columns.");
+    }
+    if (summary.estimatedRows !== null && summary.estimatedRows > 100_000) {
+        recommendations.push("Estimated row count is high; consider narrowing predicates or adding selective indexes.");
+    }
+    if (summary.usesTempStructure) {
+        recommendations.push("Avoid large temporary structures by reducing sort/group cardinality.");
+    }
+    if (summary.usesFilesort) {
+        recommendations.push("Consider index support for ORDER BY to reduce filesort.");
+    }
+    return recommendations;
+}

package/dist/executor/query-tracker.d.ts

@@ -0,0 +1,45 @@
+export type QueryState = "running" | "completed" | "failed" | "cancelled";
+export interface QueryInfo {
+    queryId: string;
+    taskId: string;
+    datasource: string;
+    mode: "ro" | "rw";
+    statementType?: string;
+    sqlHash?: string;
+    startedAt: number;
+    dbConnectionId?: number;
+    status: QueryState;
+    endedAt?: number;
+    durationMs?: number;
+    error?: string;
+}
+export interface QueryStatusResult {
+    status: Exclude<QueryState, "running">;
+    endedAt?: number;
+    durationMs?: number;
+    error?: string;
+}
+export interface QueryTracker {
+    register(queryId: string, info: QueryInfo): void;
+    get(queryId: string): QueryInfo | undefined;
+    markCompleted(queryId: string, result: QueryStatusResult): void;
+    listActive(): QueryInfo[];
+    cleanup(olderThanMs: number): void;
+}
+export type QueryTrackerOptions = {
+    now?: () => number;
+    historyLimit?: number;
+};
+export declare class InMemoryQueryTracker implements QueryTracker {
+    private readonly now;
+    private readonly historyLimit;
+    private readonly items;
+    constructor(options?: QueryTrackerOptions);
+    register(queryId: string, info: QueryInfo): void;
+    get(queryId: string): QueryInfo | undefined;
+    markCompleted(queryId: string, result: QueryStatusResult): void;
+    listActive(): QueryInfo[];
+    cleanup(olderThanMs: number): void;
+    private evictIfNeeded;
+}
+export declare function createQueryTracker(options?: QueryTrackerOptions): QueryTracker;

package/dist/executor/query-tracker.js

@@ -0,0 +1,83 @@
+function cloneInfo(info) {
+    return { ...info };
+}
+export class InMemoryQueryTracker {
+    now;
+    historyLimit;
+    items = new Map();
+    constructor(options = {}) {
+        this.now = options.now ?? Date.now;
+        this.historyLimit = options.historyLimit ?? 500;
+    }
+    register(queryId, info) {
+        this.items.set(queryId, cloneInfo(info));
+        this.evictIfNeeded();
+    }
+    get(queryId) {
+        const info = this.items.get(queryId);
+        return info ? cloneInfo(info) : undefined;
+    }
+    markCompleted(queryId, result) {
+        const existing = this.items.get(queryId);
+        if (!existing) {
+            return;
+        }
+        const endedAt = result.endedAt ?? this.now();
+        const durationMs = result.durationMs ?? Math.max(0, endedAt - existing.startedAt);
+        existing.status = result.status;
+        existing.endedAt = endedAt;
+        existing.durationMs = durationMs;
+        existing.error = result.error;
+        this.items.set(queryId, existing);
+        this.evictIfNeeded();
+    }
+    listActive() {
+        const active = [];
+        for (const info of this.items.values()) {
+            if (info.status === "running") {
+                active.push(cloneInfo(info));
+            }
+        }
+        return active.sort((a, b) => a.startedAt - b.startedAt);
+    }
+    cleanup(olderThanMs) {
+        if (!Number.isFinite(olderThanMs) || olderThanMs < 0) {
+            return;
+        }
+        const threshold = this.now() - olderThanMs;
+        for (const [queryId, info] of this.items.entries()) {
+            if (info.status === "running") {
+                continue;
+            }
+            const referenceTime = info.endedAt ?? info.startedAt;
+            if (referenceTime <= threshold) {
+                this.items.delete(queryId);
+            }
+        }
+    }
+    evictIfNeeded() {
+        if (this.items.size <= this.historyLimit) {
+            return;
+        }
+        const removable = [];
+        for (const [queryId, info] of this.items.entries()) {
+            if (info.status === "running") {
+                continue;
+            }
+            removable.push({
+                queryId,
+                refTime: info.endedAt ?? info.startedAt,
+            });
+        }
+        removable.sort((a, b) => a.refTime - b.refTime);
+        for (const entry of removable) {
+            if (this.items.size <= this.historyLimit) {
+                break;
+            }
+            this.items.delete(entry.queryId);
+        }
+    }
+}
+export function createQueryTracker(options = {}) {
+    return new InMemoryQueryTracker(options);
+}

package/dist/executor/result-normalizer.d.ts

@@ -0,0 +1,6 @@
+import type { RawResult } from "./connection-pool.js";
+import type { ColumnMeta } from "./types.js";
+export declare function asFiniteNumber(value: unknown): number | undefined;
+export declare function isObject(value: unknown): value is Record<string, unknown>;
+export declare function inferColumns(raw: RawResult, rows: unknown[]): ColumnMeta[];
+export declare function normalizeRows(rows: unknown[], columns: ColumnMeta[]): unknown[][];

package/dist/executor/result-normalizer.js

@@ -0,0 +1,47 @@
+export function asFiniteNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === "string" && value.trim().length > 0) {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+}
+export function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function inferColumns(raw, rows) {
+    if (Array.isArray(raw.fields) && raw.fields.length > 0) {
+        return raw.fields.map((field) => ({
+            name: field.name,
+            type: field.type,
+        }));
+    }
+    const first = rows[0];
+    if (isObject(first)) {
+        return Object.keys(first).map((name) => ({ name }));
+    }
+    if (Array.isArray(first)) {
+        return first.map((_, index) => ({ name: `col_${index + 1}` }));
+    }
+    return [];
+}
+export function normalizeRows(rows, columns) {
+    if (rows.length === 0) {
+        return [];
+    }
+    const first = rows[0];
+    if (Array.isArray(first)) {
+        return rows.map((row) => (Array.isArray(row) ? row : [row]));
+    }
+    if (isObject(first)) {
+        return rows.map((row) => {
+            if (!isObject(row)) {
+                return [row];
+            }
+            return columns.map((column) => row[column.name]);
+        });
+    }
+    return rows.map((row) => [row]);
+}

package/dist/executor/sql-executor.d.ts

@@ -0,0 +1,32 @@
+import type { ConnectionPool } from "./connection-pool.js";
+import type { SessionContext } from "../context/session-context.js";
+import { type QueryTracker } from "./query-tracker.js";
+import { type ResultRedactor } from "../safety/redaction.js";
+import type { CancelResult, ExplainResult, MutationOptions, MutationResult, QueryResult, QueryStatus, ReadonlyOptions, SqlExecutor } from "./types.js";
+export type { CancelResult, ColumnMeta, ExplainResult, MutationOptions, MutationResult, QueryResult, QueryStatus, ReadonlyOptions, SqlExecutor, } from "./types.js";
+export type SqlExecutorOptions = {
+    connectionPool: ConnectionPool;
+    now?: () => number;
+    queryIdGenerator?: () => string;
+    historyLimit?: number;
+    queryTracker?: QueryTracker;
+    resultRedactor?: ResultRedactor;
+};
+export declare class SqlExecutorImpl implements SqlExecutor {
+    private readonly connectionPool;
+    private readonly now;
+    private readonly queryIdGenerator;
+    private readonly queryTracker;
+    private readonly resultRedactor;
+    private readonly activeSessions;
+    constructor(options: SqlExecutorOptions);
+    explain(sql: string, ctx: SessionContext): Promise<ExplainResult>;
+    executeReadonly(sql: string, ctx: SessionContext, opts?: ReadonlyOptions): Promise<QueryResult>;
+    executeMutation(sql: string, ctx: SessionContext, opts?: MutationOptions): Promise<MutationResult>;
+    getQueryStatus(queryId: string): Promise<QueryStatus>;
+    cancelQuery(queryId: string): Promise<CancelResult>;
+    private beginQuery;
+    private completeQuery;
+    private endQuerySession;
+}
+export declare function createSqlExecutor(options: SqlExecutorOptions): SqlExecutor;

package/dist/executor/sql-executor.js

@@ -0,0 +1,250 @@
+import { generateQueryId } from "../utils/id.js";
+import { buildExplainRecommendations, normalizeExplainRows, summarizeExplainRows, } from "./explain.js";
+import { createQueryTracker, } from "./query-tracker.js";
+import { createResultRedactor, } from "../safety/redaction.js";
+import { asFiniteNumber, inferColumns, normalizeRows } from "./result-normalizer.js";
+export class SqlExecutorImpl {
+    connectionPool;
+    now;
+    queryIdGenerator;
+    queryTracker;
+    resultRedactor;
+    activeSessions = new Map();
+    constructor(options) {
+        this.connectionPool = options.connectionPool;
+        this.now = options.now ?? Date.now;
+        this.queryIdGenerator = options.queryIdGenerator ?? (() => generateQueryId());
+        this.queryTracker =
+            options.queryTracker ??
+                createQueryTracker({
+                    now: this.now,
+                    historyLimit: options.historyLimit,
+                });
+        this.resultRedactor = options.resultRedactor ?? createResultRedactor();
+    }
+    async explain(sql, ctx) {
+        const queryId = this.queryIdGenerator();
+        const startedAt = this.now();
+        const session = await this.connectionPool.acquire(ctx.datasource, "ro");
+        const active = this.beginQuery(queryId, session, ctx, "ro", startedAt);
+        try {
+            const result = await session.execute(`EXPLAIN ${sql}`, {
+                timeoutMs: ctx.limits.timeoutMs,
+            });
+            const plan = normalizeExplainRows(result);
+            const riskSummary = summarizeExplainRows(plan);
+            const recommendations = buildExplainRecommendations(riskSummary);
+            const durationMs = this.now() - startedAt;
+            this.completeQuery(active.queryId, "completed", durationMs);
+            return {
+                queryId,
+                plan,
+                riskSummary,
+                recommendations,
+                durationMs,
+            };
+        }
+        catch (error) {
+            const durationMs = this.now() - startedAt;
+            this.completeQuery(active.queryId, active.cancelRequested ? "cancelled" : "failed", durationMs, error);
+            throw error;
+        }
+        finally {
+            await this.endQuerySession(active.queryId);
+        }
+    }
+    async executeReadonly(sql, ctx, opts = {}) {
+        const queryId = this.queryIdGenerator();
+        const startedAt = this.now();
+        const maxRows = opts.maxRows ?? ctx.limits.maxRows;
+        const maxColumns = opts.maxColumns ?? ctx.limits.maxColumns;
+        const maxFieldChars = opts.maxFieldChars ?? ctx.limits.maxFieldChars ?? 2048;
+        const timeoutMs = opts.timeoutMs ?? ctx.limits.timeoutMs;
+        const session = await this.connectionPool.acquire(ctx.datasource, "ro");
+        const active = this.beginQuery(queryId, session, ctx, "ro", startedAt);
+        try {
+            const result = await session.execute(sql, { timeoutMs });
+            const sourceRows = Array.isArray(result.rows) ? result.rows : [];
+            const columns = inferColumns(result, sourceRows);
+            const normalizedRows = normalizeRows(sourceRows, columns);
+            const rowCount = asFiniteNumber(result.rowCount) ?? normalizedRows.length;
+            const redacted = this.resultRedactor.redact({
+                columns,
+                rows: normalizedRows,
+                rowCount,
+            }, {
+                maxRows,
+                maxColumns,
+                maxFieldChars,
+                sensitiveColumns: opts.sensitiveColumns,
+                sensitiveStrategy: opts.sensitiveStrategy,
+            });
+            const durationMs = this.now() - startedAt;
+            this.completeQuery(active.queryId, "completed", durationMs);
+            return {
+                queryId,
+                columns: redacted.columns,
+                rows: redacted.rows,
+                rowCount: redacted.rowCount,
+                originalRowCount: redacted.originalRowCount,
+                truncated: redacted.truncated,
+                rowTruncated: redacted.rowTruncated,
+                columnTruncated: redacted.columnTruncated,
+                fieldTruncated: redacted.fieldTruncated,
+                redactedColumns: redacted.redactedColumns,
+                droppedColumns: redacted.droppedColumns,
+                truncatedColumns: redacted.truncatedColumns,
+                durationMs,
+            };
+        }
+        catch (error) {
+            const durationMs = this.now() - startedAt;
+            this.completeQuery(active.queryId, active.cancelRequested ? "cancelled" : "failed", durationMs, error);
+            throw error;
+        }
+        finally {
+            await this.endQuerySession(active.queryId);
+        }
+    }
+    async executeMutation(sql, ctx, opts = {}) {
+        if (ctx.limits.readonly) {
+            throw new Error("Readonly session context cannot execute mutation SQL.");
+        }
+        const queryId = this.queryIdGenerator();
+        const startedAt = this.now();
+        const timeoutMs = opts.timeoutMs ?? ctx.limits.timeoutMs;
+        const session = await this.connectionPool.acquire(ctx.datasource, "rw", {
+            allowWithoutGlobalMutations: opts.allowWithoutGlobalMutations,
+            allowReadonlyFallbackForMutations: opts.allowReadonlyFallbackForMutations,
+        });
+        const active = this.beginQuery(queryId, session, ctx, "rw", startedAt);
+        try {
+            await session.execute("BEGIN", { timeoutMs });
+            const result = await session.execute(sql, { timeoutMs });
+            await session.execute("COMMIT", { timeoutMs });
+            const affectedRows = asFiniteNumber(result.affectedRows) ??
+                asFiniteNumber(result.rowCount) ??
+                0;
+            const durationMs = this.now() - startedAt;
+            this.completeQuery(active.queryId, "completed", durationMs);
+            return {
+                queryId,
+                affectedRows,
+                durationMs,
+            };
+        }
+        catch (error) {
+            try {
+                await session.execute("ROLLBACK", { timeoutMs });
+            }
+            catch {
+                // Ignore rollback failure and keep original error.
+            }
+            const durationMs = this.now() - startedAt;
+            this.completeQuery(active.queryId, active.cancelRequested ? "cancelled" : "failed", durationMs, error);
+            throw error;
+        }
+        finally {
+            await this.endQuerySession(active.queryId);
+        }
+    }
+    async getQueryStatus(queryId) {
+        const info = this.queryTracker.get(queryId);
+        if (!info) {
+            return {
+                queryId,
+                status: "not_found",
+            };
+        }
+        return {
+            queryId,
+            taskId: info.taskId,
+            datasource: info.datasource,
+            mode: info.mode,
+            status: info.status,
+            startedAt: info.startedAt,
+            endedAt: info.endedAt,
+            durationMs: info.durationMs,
+            error: info.error,
+        };
+    }
+    async cancelQuery(queryId) {
+        const active = this.activeSessions.get(queryId);
+        if (!active) {
+            const info = this.queryTracker.get(queryId);
+            if (!info) {
+                return { queryId, status: "not_found" };
+            }
+            if (info.status === "completed") {
+                return { queryId, status: "completed" };
+            }
+            return {
+                queryId,
+                status: info.status === "failed" ? "failed" : "cancelled",
+                message: info.error,
+            };
+        }
+        active.cancelRequested = true;
+        try {
+            await active.session.cancel();
+            const now = this.now();
+            this.completeQuery(queryId, "cancelled", now - active.startedAt);
+            return {
+                queryId,
+                status: "cancelled",
+            };
+        }
+        catch (error) {
+            const now = this.now();
+            this.completeQuery(queryId, "failed", now - active.startedAt, error);
+            return {
+                queryId,
+                status: "failed",
+                message: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    beginQuery(queryId, session, ctx, mode, startedAt) {
+        const active = {
+            queryId,
+            session,
+            startedAt,
+            cancelRequested: false,
+        };
+        this.activeSessions.set(queryId, active);
+        this.queryTracker.register(queryId, {
+            queryId,
+            taskId: ctx.task_id,
+            datasource: ctx.datasource,
+            mode,
+            status: "running",
+            startedAt,
+        });
+        return active;
+    }
+    completeQuery(queryId, status, durationMs, error) {
+        const info = this.queryTracker.get(queryId);
+        if (!info) {
+            return;
+        }
+        const endedAt = info.startedAt + durationMs;
+        const errorMessage = error instanceof Error ? error.message : error !== undefined ? String(error) : undefined;
+        this.queryTracker.markCompleted(queryId, {
+            status,
+            endedAt,
+            durationMs,
+            error: errorMessage,
+        });
+    }
+    async endQuerySession(queryId) {
+        const active = this.activeSessions.get(queryId);
+        if (!active) {
+            return;
+        }
+        this.activeSessions.delete(queryId);
+        await this.connectionPool.release(active.session);
+    }
+}
+export function createSqlExecutor(options) {
+    return new SqlExecutorImpl(options);
+}

package/dist/executor/types.d.ts

@@ -0,0 +1,70 @@
+import type { SessionContext } from "../context/session-context.js";
+import type { SensitiveStrategy } from "../safety/redaction.js";
+import type { ExplainRiskSummary } from "../safety/sql-validator.js";
+export interface ColumnMeta {
+    name: string;
+    type?: string;
+}
+export interface ReadonlyOptions {
+    maxRows?: number;
+    maxColumns?: number;
+    maxFieldChars?: number;
+    timeoutMs?: number;
+    sensitiveColumns?: Iterable<string>;
+    sensitiveStrategy?: SensitiveStrategy;
+}
+export interface MutationOptions {
+    timeoutMs?: number;
+    allowWithoutGlobalMutations?: boolean;
+    allowReadonlyFallbackForMutations?: boolean;
+}
+export interface QueryResult {
+    queryId: string;
+    columns: ColumnMeta[];
+    rows: unknown[][];
+    rowCount: number;
+    originalRowCount: number;
+    truncated: boolean;
+    rowTruncated: boolean;
+    columnTruncated: boolean;
+    fieldTruncated: boolean;
+    redactedColumns: string[];
+    droppedColumns: string[];
+    truncatedColumns: string[];
+    durationMs: number;
+}
+export interface MutationResult {
+    queryId: string;
+    affectedRows: number;
+    durationMs: number;
+}
+export interface ExplainResult {
+    queryId: string;
+    plan: Record<string, unknown>[];
+    riskSummary: ExplainRiskSummary;
+    recommendations: string[];
+    durationMs: number;
+}
+export interface QueryStatus {
+    queryId: string;
+    status: "running" | "completed" | "failed" | "cancelled" | "not_found";
+    taskId?: string;
+    datasource?: string;
+    mode?: "ro" | "rw";
+    startedAt?: number;
+    endedAt?: number;
+    durationMs?: number;
+    error?: string;
+}
+export interface CancelResult {
+    queryId: string;
+    status: "cancelled" | "not_found" | "completed" | "failed";
+    message?: string;
+}
+export interface SqlExecutor {
+    explain(sql: string, ctx: SessionContext): Promise<ExplainResult>;
+    executeReadonly(sql: string, ctx: SessionContext, opts?: ReadonlyOptions): Promise<QueryResult>;
+    executeMutation(sql: string, ctx: SessionContext, opts?: MutationOptions): Promise<MutationResult>;
+    getQueryStatus(queryId: string): Promise<QueryStatus>;
+    cancelQuery(queryId: string): Promise<CancelResult>;
+}

package/dist/executor/types.js

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