taurusdb-core 0.1.0

package/dist/schema/adapters/mysql.js

@@ -0,0 +1,287 @@
+const SENSITIVE_PATTERNS = [
+    /phone|mobile|tel/i,
+    /id_?card|passport|ssn/i,
+    /email/i,
+    /password|passwd|secret/i,
+    /token|api_?key/i,
+    /bank|card_?no|account/i,
+];
+const TIME_COLUMN_PATTERNS = [
+    /created(_at|_time)?$/i,
+    /updated(_at|_time)?$/i,
+    /modified(_at|_time)?$/i,
+    /event(_at|_time)?$/i,
+    /timestamp/i,
+    /date$/i,
+    /time$/i,
+];
+const TIME_DATA_TYPES = new Set(["date", "datetime", "timestamp", "time", "year"]);
+function quoteLiteral(value) {
+    return `'${value.replace(/\\/g, "\\\\").replace(/'/g, "''")}'`;
+}
+function normalizeType(value) {
+    if (typeof value === "string") {
+        return value.toLowerCase();
+    }
+    if (value === null || value === undefined) {
+        return "unknown";
+    }
+    return String(value).toLowerCase();
+}
+function normalizeNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === "string" && value.trim().length > 0) {
+        const parsed = Number.parseFloat(value);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+}
+function normalizeBoolean(value) {
+    if (typeof value === "boolean") {
+        return value;
+    }
+    if (typeof value === "number") {
+        return value !== 0;
+    }
+    if (typeof value === "string") {
+        const normalized = value.trim().toLowerCase();
+        if (["1", "true", "yes", "y"].includes(normalized)) {
+            return true;
+        }
+        if (["0", "false", "no", "n"].includes(normalized)) {
+            return false;
+        }
+    }
+    return undefined;
+}
+function readField(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 match = lowerMap.get(candidate.toLowerCase());
+        if (match !== undefined) {
+            return match;
+        }
+    }
+    return undefined;
+}
+function rowsToObjects(result) {
+    const rawRows = result.rows;
+    if (!Array.isArray(rawRows) || rawRows.length === 0) {
+        return [];
+    }
+    const firstRow = rawRows[0];
+    if (!Array.isArray(firstRow) && firstRow !== null && typeof firstRow === "object") {
+        return rawRows;
+    }
+    if (Array.isArray(firstRow) && Array.isArray(result.fields)) {
+        return rawRows.map((row) => {
+            const mapped = {};
+            result.fields?.forEach((field, index) => {
+                mapped[field.name] = row[index];
+            });
+            return mapped;
+        });
+    }
+    return [];
+}
+function mapTableType(value) {
+    const normalized = typeof value === "string" ? value.toLowerCase() : "";
+    if (normalized === "base table" || normalized === "table") {
+        return "table";
+    }
+    if (normalized === "view") {
+        return "view";
+    }
+    return undefined;
+}
+function buildEngineHints(columns, indexes, primaryKey) {
+    const indexedColumns = new Set();
+    for (const index of indexes) {
+        for (const column of index.columns) {
+            indexedColumns.add(column);
+        }
+    }
+    for (const column of primaryKey ?? []) {
+        indexedColumns.add(column);
+    }
+    const likelyTimeColumns = columns
+        .filter((column) => {
+        const byType = TIME_DATA_TYPES.has(column.dataType.toLowerCase());
+        const byName = TIME_COLUMN_PATTERNS.some((pattern) => pattern.test(column.name));
+        return byType || byName;
+    })
+        .map((column) => column.name);
+    const likelyFilterColumns = columns
+        .filter((column) => indexedColumns.has(column.name))
+        .map((column) => column.name);
+    const sensitiveColumns = columns
+        .filter((column) => SENSITIVE_PATTERNS.some((pattern) => pattern.test(column.name)))
+        .map((column) => column.name);
+    return {
+        likelyTimeColumns,
+        likelyFilterColumns,
+        sensitiveColumns,
+    };
+}
+export class MySqlSchemaAdapter {
+    connectionPool;
+    constructor(options) {
+        this.connectionPool = options.connectionPool;
+    }
+    async listDatabases(ctx) {
+        const sql = `
+      SELECT SCHEMA_NAME AS schema_name
+      FROM information_schema.SCHEMATA
+      ORDER BY SCHEMA_NAME
+    `;
+        const rows = await this.queryObjects(ctx, sql);
+        return rows.map((row) => ({
+            name: String(readField(row, ["schema_name", "SCHEMA_NAME"])),
+        }));
+    }
+    async listTables(ctx, database) {
+        const sql = `
+      SELECT TABLE_NAME AS table_name,
+             TABLE_TYPE AS table_type,
+             TABLE_COMMENT AS table_comment,
+             TABLE_ROWS AS table_rows
+      FROM information_schema.TABLES
+      WHERE TABLE_SCHEMA = ${quoteLiteral(database)}
+      ORDER BY TABLE_NAME
+    `;
+        const rows = await this.queryObjects(ctx, sql);
+        return rows.map((row) => ({
+            database,
+            name: String(readField(row, ["table_name", "TABLE_NAME"])),
+            type: mapTableType(readField(row, ["table_type", "TABLE_TYPE"])),
+            comment: readField(row, ["table_comment", "TABLE_COMMENT"]) || undefined,
+            rowCountEstimate: normalizeNumber(readField(row, ["table_rows", "TABLE_ROWS"])),
+        }));
+    }
+    async describeTable(ctx, database, table) {
+        const columnsSql = `
+      SELECT COLUMN_NAME AS column_name,
+             DATA_TYPE AS data_type,
+             IS_NULLABLE AS is_nullable,
+             COLUMN_DEFAULT AS column_default,
+             COLUMN_KEY AS column_key,
+             EXTRA AS extra,
+             COLUMN_COMMENT AS column_comment,
+             CHARACTER_MAXIMUM_LENGTH AS character_maximum_length
+      FROM information_schema.COLUMNS
+      WHERE TABLE_SCHEMA = ${quoteLiteral(database)}
+        AND TABLE_NAME = ${quoteLiteral(table)}
+      ORDER BY ORDINAL_POSITION
+    `;
+        const indexesSql = `
+      SELECT INDEX_NAME AS index_name,
+             COLUMN_NAME AS column_name,
+             NON_UNIQUE AS non_unique,
+             SEQ_IN_INDEX AS seq_in_index,
+             INDEX_TYPE AS index_type
+      FROM information_schema.STATISTICS
+      WHERE TABLE_SCHEMA = ${quoteLiteral(database)}
+        AND TABLE_NAME = ${quoteLiteral(table)}
+      ORDER BY INDEX_NAME, SEQ_IN_INDEX
+    `;
+        const tableMetaSql = `
+      SELECT TABLE_ROWS AS table_rows,
+             TABLE_COMMENT AS table_comment
+      FROM information_schema.TABLES
+      WHERE TABLE_SCHEMA = ${quoteLiteral(database)}
+        AND TABLE_NAME = ${quoteLiteral(table)}
+      LIMIT 1
+    `;
+        const [columnRows, indexRows, tableMetaRows] = await Promise.all([
+            this.queryObjects(ctx, columnsSql),
+            this.queryObjects(ctx, indexesSql),
+            this.queryObjects(ctx, tableMetaSql),
+        ]);
+        const indexes = this.mapIndexes(indexRows);
+        const primaryKey = indexes.find((index) => index.name === "PRIMARY")?.columns;
+        const indexedColumnSet = new Set(indexes.flatMap((index) => index.columns));
+        const columns = columnRows.map((row) => {
+            const name = String(readField(row, ["column_name", "COLUMN_NAME"]));
+            const dataType = normalizeType(readField(row, ["data_type", "DATA_TYPE"]));
+            const nullable = normalizeBoolean(readField(row, ["is_nullable", "IS_NULLABLE"])) ?? true;
+            return {
+                name,
+                dataType,
+                nullable,
+                defaultValue: readField(row, ["column_default", "COLUMN_DEFAULT"]),
+                maxLength: normalizeNumber(readField(row, ["character_maximum_length", "CHARACTER_MAXIMUM_LENGTH"])),
+                isPrimaryKey: readField(row, ["column_key", "COLUMN_KEY"])?.toUpperCase() === "PRI",
+                isIndexed: indexedColumnSet.has(name),
+                comment: readField(row, ["column_comment", "COLUMN_COMMENT"]) || undefined,
+            };
+        });
+        const meta = tableMetaRows[0];
+        const rowCountEstimate = meta
+            ? normalizeNumber(readField(meta, ["table_rows", "TABLE_ROWS"]))
+            : undefined;
+        const comment = meta
+            ? (readField(meta, ["table_comment", "TABLE_COMMENT"]) || undefined)
+            : undefined;
+        const schema = {
+            database,
+            table,
+            columns,
+            indexes,
+            primaryKey,
+            engineHints: buildEngineHints(columns, indexes, primaryKey),
+            comment,
+            rowCountEstimate,
+        };
+        return schema;
+    }
+    mapIndexes(rows) {
+        const byName = new Map();
+        for (const row of rows) {
+            const name = String(readField(row, ["index_name", "INDEX_NAME"]));
+            const columnName = String(readField(row, ["column_name", "COLUMN_NAME"]));
+            const nonUnique = normalizeNumber(readField(row, ["non_unique", "NON_UNIQUE"])) ?? 1;
+            const indexType = readField(row, ["index_type", "INDEX_TYPE"]);
+            const seqInIndex = normalizeNumber(readField(row, ["seq_in_index", "SEQ_IN_INDEX"])) ?? 0;
+            const current = byName.get(name) ?? {
+                name,
+                columns: [],
+                unique: nonUnique === 0,
+                type: typeof indexType === "string" ? indexType : undefined,
+            };
+            if (seqInIndex > current.columns.length) {
+                current.columns[seqInIndex - 1] = columnName;
+            }
+            else {
+                current.columns.push(columnName);
+            }
+            byName.set(name, current);
+        }
+        return [...byName.values()].map((index) => ({
+            ...index,
+            columns: index.columns.filter((column) => typeof column === "string"),
+        }));
+    }
+    async queryObjects(ctx, sql) {
+        const session = await this.connectionPool.acquire(ctx.datasource, "ro");
+        try {
+            const result = await session.execute(sql, { timeoutMs: ctx.limits.timeoutMs });
+            return rowsToObjects(result);
+        }
+        finally {
+            await this.connectionPool.release(session);
+        }
+    }
+}
+export function createMySqlSchemaAdapter(options) {
+    return new MySqlSchemaAdapter(options);
+}

package/dist/schema/introspector.d.ts

@@ -0,0 +1,70 @@
+import type { DatabaseEngine } from "../auth/sql-profile-loader.js";
+import type { SessionContext } from "../context/session-context.js";
+export interface DatabaseInfo {
+    name: string;
+    owner?: string;
+    comment?: string;
+}
+export interface TableInfo {
+    database: string;
+    name: string;
+    type?: "table" | "view" | "materialized_view";
+    comment?: string;
+    rowCountEstimate?: number;
+}
+export interface ColumnInfo {
+    name: string;
+    dataType: string;
+    nullable: boolean;
+    defaultValue?: unknown;
+    maxLength?: number;
+    isPrimaryKey?: boolean;
+    isIndexed?: boolean;
+    comment?: string;
+}
+export interface IndexInfo {
+    name: string;
+    columns: string[];
+    unique: boolean;
+    type?: string;
+}
+export interface TableSchema {
+    database: string;
+    table: string;
+    columns: ColumnInfo[];
+    indexes: IndexInfo[];
+    primaryKey?: string[];
+    engineHints?: {
+        likelyTimeColumns: string[];
+        likelyFilterColumns: string[];
+        sensitiveColumns: string[];
+    };
+    comment?: string;
+    rowCountEstimate?: number;
+}
+export interface SchemaAdapter {
+    listDatabases(ctx: SessionContext): Promise<DatabaseInfo[]>;
+    listTables(ctx: SessionContext, database: string): Promise<TableInfo[]>;
+    describeTable(ctx: SessionContext, database: string, table: string): Promise<TableSchema>;
+}
+export interface SchemaIntrospector {
+    listDatabases(ctx: SessionContext): Promise<DatabaseInfo[]>;
+    listTables(ctx: SessionContext, database: string): Promise<TableInfo[]>;
+    describeTable(ctx: SessionContext, database: string, table: string): Promise<TableSchema>;
+}
+export declare class SchemaIntrospectionError extends Error {
+    readonly code: "SCHEMA_ADAPTER_NOT_FOUND" | "INVALID_INTROSPECTION_INPUT";
+    constructor(code: "SCHEMA_ADAPTER_NOT_FOUND" | "INVALID_INTROSPECTION_INPUT", message: string);
+}
+export type SchemaIntrospectorOptions = {
+    adapters: Partial<Record<DatabaseEngine, SchemaAdapter>>;
+};
+export declare class AdapterSchemaIntrospector implements SchemaIntrospector {
+    private readonly adapters;
+    constructor(options: SchemaIntrospectorOptions);
+    listDatabases(ctx: SessionContext): Promise<DatabaseInfo[]>;
+    listTables(ctx: SessionContext, database: string): Promise<TableInfo[]>;
+    describeTable(ctx: SessionContext, database: string, table: string): Promise<TableSchema>;
+    private getAdapter;
+}
+export declare function createSchemaIntrospector(options: SchemaIntrospectorOptions): SchemaIntrospector;

package/dist/schema/introspector.js

@@ -0,0 +1,40 @@
+export class SchemaIntrospectionError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "SchemaIntrospectionError";
+        this.code = code;
+    }
+}
+function normalizeName(value, fieldName) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        throw new SchemaIntrospectionError("INVALID_INTROSPECTION_INPUT", `Invalid ${fieldName}: value cannot be empty.`);
+    }
+    return trimmed;
+}
+export class AdapterSchemaIntrospector {
+    adapters;
+    constructor(options) {
+        this.adapters = options.adapters;
+    }
+    async listDatabases(ctx) {
+        return this.getAdapter(ctx.engine).listDatabases(ctx);
+    }
+    async listTables(ctx, database) {
+        return this.getAdapter(ctx.engine).listTables(ctx, normalizeName(database, "database"));
+    }
+    async describeTable(ctx, database, table) {
+        return this.getAdapter(ctx.engine).describeTable(ctx, normalizeName(database, "database"), normalizeName(table, "table"));
+    }
+    getAdapter(engine) {
+        const adapter = this.adapters[engine];
+        if (!adapter) {
+            throw new SchemaIntrospectionError("SCHEMA_ADAPTER_NOT_FOUND", `Schema adapter not found for engine "${engine}".`);
+        }
+        return adapter;
+    }
+}
+export function createSchemaIntrospector(options) {
+    return new AdapterSchemaIntrospector(options);
+}

package/dist/taurus/flashback.d.ts

@@ -0,0 +1,36 @@
+import type { ReadonlyOptions } from "../executor/sql-executor.js";
+export interface FlashbackInput {
+    database?: string;
+    table: string;
+    asOf: {
+        timestamp: string;
+        relative?: never;
+    } | {
+        timestamp?: never;
+        relative: string;
+    };
+    where?: string;
+    columns?: string[];
+    limit?: number;
+}
+export type FlashbackNoViewDetails = {
+    database?: string;
+    table?: string;
+    where?: string;
+    requested_timestamp: string;
+    current_time?: string;
+    backquery_window_seconds?: number;
+    earliest_supported_timestamp_estimate?: string;
+    current_row_updated_at?: string;
+    recommended_timestamps?: string[];
+    guidance?: string[];
+};
+export declare class FlashbackNoViewError extends Error {
+    readonly details: FlashbackNoViewDetails;
+    constructor(message: string, details: FlashbackNoViewDetails);
+}
+export declare function formatTimestamp(date: Date): string;
+export declare function resolveRelativeTimestampFromBase(relative: string, baseTimestamp: string): string;
+export declare function resolveFlashbackTimestamp(asOf: FlashbackInput["asOf"], now?: () => number): string;
+export declare function buildFlashbackSql(input: FlashbackInput, defaultDatabase: string, now?: () => number): string;
+export declare function flashbackReadonlyOptions(limit: number | undefined): ReadonlyOptions | undefined;

package/dist/taurus/flashback.js

@@ -0,0 +1,149 @@
+const IDENTIFIER_PATTERN = /^[A-Za-z_][A-Za-z0-9_$]*$/;
+const SQL_TIMESTAMP_PATTERN = /^(\d{4}-\d{2}-\d{2})[ T](\d{2}:\d{2}:\d{2})(?:\.\d{1,6})?$/;
+const RELATIVE_DURATION_PATTERN = /(\d+)\s*(ms|milliseconds?|s|sec|secs|seconds?|m|min|mins|minutes?|h|hr|hrs|hours?|d|days?)/gi;
+const UNIT_TO_MS = {
+    ms: 1,
+    s: 1000,
+    m: 60_000,
+    h: 3_600_000,
+    d: 86_400_000,
+};
+function normalizeDurationUnit(unit) {
+    const normalized = unit.toLowerCase();
+    if (normalized.startsWith("ms")) {
+        return "ms";
+    }
+    if (normalized.startsWith("s")) {
+        return "s";
+    }
+    if (normalized.startsWith("m")) {
+        return "m";
+    }
+    if (normalized.startsWith("h")) {
+        return "h";
+    }
+    return "d";
+}
+function quoteIdentifier(identifier, fieldName) {
+    if (!IDENTIFIER_PATTERN.test(identifier)) {
+        throw new Error(`Invalid ${fieldName}: "${identifier}".`);
+    }
+    return `\`${identifier}\``;
+}
+export class FlashbackNoViewError extends Error {
+    details;
+    constructor(message, details) {
+        super(message);
+        this.name = "FlashbackNoViewError";
+        this.details = details;
+    }
+}
+export function formatTimestamp(date) {
+    if (Number.isNaN(date.getTime())) {
+        throw new Error("Invalid flashback timestamp.");
+    }
+    const year = String(date.getFullYear()).padStart(4, "0");
+    const month = String(date.getMonth() + 1).padStart(2, "0");
+    const day = String(date.getDate()).padStart(2, "0");
+    const hours = String(date.getHours()).padStart(2, "0");
+    const minutes = String(date.getMinutes()).padStart(2, "0");
+    const seconds = String(date.getSeconds()).padStart(2, "0");
+    return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}`;
+}
+function parseTimestampLiteral(timestamp) {
+    const match = timestamp.trim().match(SQL_TIMESTAMP_PATTERN);
+    if (!match) {
+        return undefined;
+    }
+    return `${match[1]} ${match[2]}`;
+}
+function parseRelativeDurationMs(relative) {
+    const input = relative.trim();
+    if (!input) {
+        throw new Error("Flashback relative time cannot be empty.");
+    }
+    let consumed = "";
+    let offsetMs = 0;
+    for (const match of input.matchAll(RELATIVE_DURATION_PATTERN)) {
+        consumed += match[0];
+        const amount = Number.parseInt(match[1], 10);
+        const unit = normalizeDurationUnit(match[2]);
+        offsetMs += amount * UNIT_TO_MS[unit];
+    }
+    if (offsetMs <= 0 || consumed.replace(/\s+/g, "") !== input.replace(/\s+/g, "")) {
+        throw new Error(`Invalid flashback relative time: "${relative}". Expected values like 5m, 10min, 1h, or 2h30m.`);
+    }
+    return offsetMs;
+}
+function parseTimestampLiteralToDate(timestamp) {
+    const literal = parseTimestampLiteral(timestamp);
+    if (literal) {
+        const match = literal.match(SQL_TIMESTAMP_PATTERN);
+        if (!match) {
+            throw new Error("Invalid flashback timestamp.");
+        }
+        const [, datePart, timePart] = match;
+        const [year, month, day] = datePart.split("-").map(Number);
+        const [hours, minutes, seconds] = timePart.split(":").map(Number);
+        const date = new Date(year, month - 1, day, hours, minutes, seconds, 0);
+        if (Number.isNaN(date.getTime())) {
+            throw new Error("Invalid flashback timestamp.");
+        }
+        return date;
+    }
+    const parsed = new Date(timestamp);
+    if (Number.isNaN(parsed.getTime())) {
+        throw new Error("Invalid flashback timestamp.");
+    }
+    return parsed;
+}
+export function resolveRelativeTimestampFromBase(relative, baseTimestamp) {
+    const offsetMs = parseRelativeDurationMs(relative);
+    const baseDate = parseTimestampLiteralToDate(baseTimestamp);
+    return formatTimestamp(new Date(baseDate.getTime() - offsetMs));
+}
+export function resolveFlashbackTimestamp(asOf, now = Date.now) {
+    if ("timestamp" in asOf && typeof asOf.timestamp === "string") {
+        const literal = parseTimestampLiteral(asOf.timestamp);
+        if (literal) {
+            return literal;
+        }
+        return formatTimestamp(new Date(asOf.timestamp));
+    }
+    if ("relative" in asOf && typeof asOf.relative === "string") {
+        const offsetMs = parseRelativeDurationMs(asOf.relative);
+        return formatTimestamp(new Date(now() - offsetMs));
+    }
+    throw new Error("Flashback query requires either as_of.timestamp or as_of.relative.");
+}
+export function buildFlashbackSql(input, defaultDatabase, now = Date.now) {
+    const database = quoteIdentifier(input.database ?? defaultDatabase, "database");
+    const table = quoteIdentifier(input.table, "table");
+    const columns = input.columns && input.columns.length > 0
+        ? input.columns.map((column) => quoteIdentifier(column, "column")).join(", ")
+        : "*";
+    const timestamp = resolveFlashbackTimestamp(input.asOf, now);
+    const clauses = [
+        `SELECT ${columns}`,
+        `FROM ${database}.${table} AS OF TIMESTAMP '${timestamp}'`,
+    ];
+    const whereClause = input.where?.trim();
+    if (whereClause) {
+        clauses.push(`WHERE (${whereClause})`);
+    }
+    if (input.limit !== undefined) {
+        if (!Number.isInteger(input.limit) || input.limit <= 0) {
+            throw new Error("Flashback query limit must be a positive integer.");
+        }
+        clauses.push(`LIMIT ${input.limit}`);
+    }
+    return clauses.join(" ");
+}
+export function flashbackReadonlyOptions(limit) {
+    if (limit === undefined) {
+        return undefined;
+    }
+    return {
+        maxRows: limit,
+    };
+}

package/dist/taurus/recycle-bin.d.ts

@@ -0,0 +1,14 @@
+import type { MutationOptions, MutationResult, QueryResult, ReadonlyOptions } from "../executor/sql-executor.js";
+export interface RestoreRecycleBinTableInput {
+    recycleTable: string;
+    method?: "native_restore" | "insert_select";
+    destinationDatabase?: string;
+    destinationTable?: string;
+}
+export declare const RECYCLE_BIN_DATABASE = "__recyclebin__";
+export declare function buildListRecycleBinSql(): string;
+export declare function buildRestoreRecycleBinTableSql(input: RestoreRecycleBinTableInput): string;
+export declare function recycleBinReadonlyOptions(opts?: ReadonlyOptions): ReadonlyOptions;
+export declare function recycleBinMutationOptions(opts?: MutationOptions): MutationOptions | undefined;
+export type RecycleBinListResult = QueryResult;
+export type RecycleBinRestoreResult = MutationResult;

package/dist/taurus/recycle-bin.js

@@ -0,0 +1,61 @@
+export const RECYCLE_BIN_DATABASE = "__recyclebin__";
+const SIMPLE_IDENTIFIER_PATTERN = /^[A-Za-z_][A-Za-z0-9_$]*$/;
+const RECYCLE_TABLE_PATTERN = /^[A-Za-z0-9_$@.-]+$/;
+function quoteIdentifier(identifier, fieldName) {
+    if (!SIMPLE_IDENTIFIER_PATTERN.test(identifier)) {
+        throw new Error(`Invalid ${fieldName}: "${identifier}".`);
+    }
+    return `\`${identifier}\``;
+}
+function quoteRecycleTableName(table) {
+    if (!RECYCLE_TABLE_PATTERN.test(table)) {
+        throw new Error(`Invalid recycle_table: "${table}".`);
+    }
+    return `\`${table.replace(/`/g, "``")}\``;
+}
+function quoteStringLiteral(value, fieldName) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        throw new Error(`Invalid ${fieldName}: value cannot be empty.`);
+    }
+    if (trimmed !== value) {
+        throw new Error(`Invalid ${fieldName}: extra leading or trailing spaces are not allowed.`);
+    }
+    if (!RECYCLE_TABLE_PATTERN.test(trimmed) && fieldName === "recycle_table") {
+        throw new Error(`Invalid recycle_table: "${value}".`);
+    }
+    return `'${trimmed.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+}
+export function buildListRecycleBinSql() {
+    return "call dbms_recyclebin.show_tables()";
+}
+export function buildRestoreRecycleBinTableSql(input) {
+    const method = input.method ?? "native_restore";
+    const recycleTable = quoteStringLiteral(input.recycleTable, "recycle_table");
+    if (method === "native_restore") {
+        if (input.destinationDatabase || input.destinationTable) {
+            if (!input.destinationDatabase || !input.destinationTable) {
+                throw new Error("native_restore requires destination_database and destination_table to be provided together.");
+            }
+            return `call dbms_recyclebin.restore_table(${recycleTable}, ${quoteStringLiteral(input.destinationDatabase, "destination_database")}, ${quoteStringLiteral(input.destinationTable, "destination_table")})`;
+        }
+        return `call dbms_recyclebin.restore_table(${recycleTable})`;
+    }
+    if (method === "insert_select") {
+        if (!input.destinationDatabase || !input.destinationTable) {
+            throw new Error("insert_select restore requires destination_database and destination_table. Create the destination table with a compatible structure before calling this tool.");
+        }
+        return `INSERT INTO ${quoteIdentifier(input.destinationDatabase, "destination_database")}.${quoteIdentifier(input.destinationTable, "destination_table")} SELECT * FROM \`${RECYCLE_BIN_DATABASE}\`.${quoteRecycleTableName(input.recycleTable)}`;
+    }
+    throw new Error(`Unsupported restore method: ${method}.`);
+}
+export function recycleBinReadonlyOptions(opts) {
+    return {
+        maxRows: 100,
+        maxColumns: 20,
+        ...opts,
+    };
+}
+export function recycleBinMutationOptions(opts) {
+    return opts;
+}