sql-dashboard 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,579 @@
+import { EventEmitter } from 'eventemitter3';
+import { Router } from 'express';
+import { FastifyInstance, FastifyPluginOptions } from 'fastify';
+
+declare enum DriverType {
+    SQLITE = "sqlite",
+    MYSQL = "mysql",
+    POSTGRES = "postgres",
+    MSSQL = "mssql"
+}
+interface PoolConfig {
+    min?: number;
+    max?: number;
+    acquireTimeout?: number;
+    idleTimeout?: number;
+}
+interface MySQLConfig {
+    host?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+    database?: string;
+    charset?: string;
+    timezone?: string;
+    multipleStatements?: boolean;
+    ssl?: boolean | object;
+}
+interface PostgreSQLConfig {
+    host?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+    database?: string;
+    schema?: string;
+    ssl?: boolean | object;
+    applicationName?: string;
+}
+interface MSSQLConfig {
+    server?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+    database?: string;
+    schema?: string;
+    encrypt?: boolean;
+    trustServerCertificate?: boolean;
+    options?: Record<string, unknown>;
+}
+interface SQLiteConfig {
+    path?: string;
+    mode?: 'memory' | 'file';
+    readOnly?: boolean;
+}
+type DriverConfig = {
+    type: DriverType.SQLITE;
+    connection: SQLiteConfig;
+    pool?: PoolConfig;
+} | {
+    type: DriverType.MYSQL;
+    connection: MySQLConfig;
+    pool?: PoolConfig;
+} | {
+    type: DriverType.POSTGRES;
+    connection: PostgreSQLConfig;
+    pool?: PoolConfig;
+} | {
+    type: DriverType.MSSQL;
+    connection: MSSQLConfig;
+    pool?: PoolConfig;
+};
+
+type QueryStatus = 'success' | 'error' | 'cancelled';
+interface QueryOptions {
+    timeout?: number;
+    params?: unknown[];
+    readOnly?: boolean;
+    transaction?: boolean;
+    stream?: boolean;
+    maxRows?: number;
+}
+interface QueryResult {
+    id: string;
+    status: QueryStatus;
+    rows: Record<string, unknown>[];
+    columns: string[];
+    rowCount: number;
+    affectedRows?: number;
+    duration: number;
+    query: string;
+    error?: string;
+    warning?: string;
+    insertedId?: string | number;
+}
+interface QueryHistoryEntry {
+    id: string;
+    query: string;
+    executedAt: Date;
+    duration: number;
+    status: QueryStatus;
+    rowCount: number;
+    database: string;
+    user?: string;
+}
+interface PaginatedResult<T> {
+    data: T[];
+    total: number;
+    page: number;
+    pageSize: number;
+    totalPages: number;
+}
+
+interface SchemaFilter {
+    schema?: string;
+    table?: string;
+    type?: 'table' | 'view' | 'index' | 'procedure';
+}
+interface SchemaInfo {
+    name: string;
+    tables: TableInfo[];
+    views: ViewInfo[];
+    procedures: ProcedureInfo[];
+}
+interface TableInfo {
+    name: string;
+    schema: string;
+    type: 'table' | 'view';
+    columns: ColumnInfo[];
+    indexes: IndexInfo[];
+    foreignKeys: ForeignKeyInfo[];
+    rowCount?: number;
+    size?: string;
+    comment?: string;
+    createdAt?: Date;
+    updatedAt?: Date;
+    engine?: string;
+    collation?: string;
+}
+interface ColumnInfo {
+    name: string;
+    type: string;
+    nullable: boolean;
+    primaryKey: boolean;
+    defaultValue?: string | null;
+    autoIncrement?: boolean;
+    maxLength?: number;
+    precision?: number;
+    scale?: number;
+    comment?: string;
+    enumValues?: string[];
+    foreignKey?: {
+        table: string;
+        column: string;
+    };
+}
+interface IndexInfo {
+    name: string;
+    columns: string[];
+    unique: boolean;
+    primary: boolean;
+    type: string;
+    method?: string;
+}
+interface ForeignKeyInfo {
+    name: string;
+    column: string;
+    referencedSchema: string;
+    referencedTable: string;
+    referencedColumn: string;
+    onDelete: string;
+    onUpdate: string;
+}
+interface ViewInfo {
+    name: string;
+    schema: string;
+    definition: string;
+    columns: ColumnInfo[];
+}
+interface ProcedureInfo {
+    name: string;
+    schema: string;
+    type: 'procedure' | 'function';
+    params: {
+        name: string;
+        type: string;
+        mode: 'IN' | 'OUT' | 'INOUT';
+    }[];
+    returnType?: string;
+    definition: string;
+}
+
+interface RateLimitConfig {
+    enabled?: boolean;
+    windowMs?: number;
+    maxQueries?: number;
+    maxQueriesPerUser?: Record<string, number>;
+    errorMessage?: string;
+}
+interface ReadOnlyRule {
+    enabled?: boolean;
+    allowSelect?: boolean;
+    allowShow?: boolean;
+    allowDescribe?: boolean;
+    allowExplain?: boolean;
+    bypassUsers?: string[];
+}
+interface SecurityConfig {
+    readOnly?: boolean | ReadOnlyRule;
+    rateLimit?: RateLimitConfig;
+    maxQueryLength?: number;
+    maxRows?: number;
+    bannedStatements?: string[];
+    bannedDatabases?: string[];
+    allowedDatabases?: string[];
+    requireWhere?: boolean;
+    queryTimeout?: number;
+    allowedHosts?: string[];
+}
+interface ValidationError {
+    code: string;
+    message: string;
+    line?: number;
+    column?: number;
+    severity: 'error' | 'warning';
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+    normalizedQuery: string;
+    statementType: string;
+    isReadOnly: boolean;
+    tables: string[];
+}
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+interface LoggerConfig {
+    level?: LogLevel;
+    queries?: boolean;
+    slowQueryThreshold?: number;
+    format?: 'json' | 'text';
+}
+interface DashboardOptions {
+    driver: DriverConfig;
+    security?: SecurityConfig;
+    logger?: LoggerConfig;
+    autoConnect?: boolean;
+}
+interface DashboardConfig extends Required<DashboardOptions> {
+    version: string;
+}
+
+declare abstract class BaseDriver {
+    abstract readonly type: DriverType;
+    protected connected: boolean;
+    protected config: Record<string, unknown>;
+    abstract connect(): Promise<void>;
+    abstract disconnect(): Promise<void>;
+    abstract executeQuery(sql: string, params?: unknown[]): Promise<QueryResult>;
+    abstract executeBatch(queries: string[]): Promise<QueryResult[]>;
+    abstract isConnected(): boolean;
+    protected createResult(query: string, rows: Record<string, unknown>[], duration: number, affectedRows?: number): QueryResult;
+    protected createErrorResult(query: string, error: Error, duration: number): QueryResult;
+    protected ensureConnected(): void;
+    abstract getSchema(): Promise<SchemaInfo>;
+    abstract getTables(): Promise<TableInfo[]>;
+    abstract getTableInfo(tableName: string): Promise<TableInfo>;
+    abstract getColumns(tableName: string): Promise<ColumnInfo[]>;
+    abstract getIndexes(tableName: string): Promise<IndexInfo[]>;
+    abstract getForeignKeys(tableName: string): Promise<ForeignKeyInfo[]>;
+    abstract getViews(): Promise<ViewInfo[]>;
+    abstract getTableRowCount(tableName: string): Promise<number>;
+    abstract getVersion(): Promise<string>;
+    abstract getDatabases(): Promise<string[]>;
+}
+
+declare class SQLiteDriver extends BaseDriver {
+    readonly type = DriverType.SQLITE;
+    private db;
+    private sqlJs;
+    private dbPath;
+    private memoryMode;
+    constructor(config: SQLiteConfig);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    private saveToFile;
+    executeQuery(sql: string, params?: unknown[]): Promise<QueryResult>;
+    executeBatch(queries: string[]): Promise<QueryResult[]>;
+    getSchema(): Promise<SchemaInfo>;
+    getTables(): Promise<TableInfo[]>;
+    getTableInfo(tableName: string): Promise<TableInfo>;
+    getColumns(tableName: string): Promise<ColumnInfo[]>;
+    getIndexes(tableName: string): Promise<IndexInfo[]>;
+    getForeignKeys(tableName: string): Promise<ForeignKeyInfo[]>;
+    getViews(): Promise<ViewInfo[]>;
+    getTableRowCount(tableName: string): Promise<number>;
+    getVersion(): Promise<string>;
+    getDatabases(): Promise<string[]>;
+}
+
+declare class MySQLDriver extends BaseDriver {
+    readonly type = DriverType.MYSQL;
+    private pool;
+    constructor(config: MySQLConfig);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    executeQuery(sql: string, params?: unknown[]): Promise<QueryResult>;
+    executeBatch(queries: string[]): Promise<QueryResult[]>;
+    getSchema(): Promise<SchemaInfo>;
+    private getCurrentDatabase;
+    getTables(): Promise<TableInfo[]>;
+    getTableInfo(tableName: string): Promise<TableInfo>;
+    getColumns(tableName: string): Promise<ColumnInfo[]>;
+    getIndexes(tableName: string): Promise<IndexInfo[]>;
+    getForeignKeys(tableName: string): Promise<ForeignKeyInfo[]>;
+    getViews(): Promise<ViewInfo[]>;
+    private getProcedures;
+    private getTableSize;
+    getTableRowCount(tableName: string): Promise<number>;
+    getVersion(): Promise<string>;
+    getDatabases(): Promise<string[]>;
+}
+
+declare class PostgresDriver extends BaseDriver {
+    readonly type = DriverType.POSTGRES;
+    private pool;
+    private currentSchema;
+    constructor(config: PostgreSQLConfig);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    executeQuery(sql: string, params?: unknown[]): Promise<QueryResult>;
+    executeBatch(queries: string[]): Promise<QueryResult[]>;
+    getSchema(): Promise<SchemaInfo>;
+    getTables(): Promise<TableInfo[]>;
+    getTableInfo(tableName: string): Promise<TableInfo>;
+    getColumns(tableName: string): Promise<ColumnInfo[]>;
+    private mapPostgresType;
+    getIndexes(tableName: string): Promise<IndexInfo[]>;
+    getForeignKeys(tableName: string): Promise<ForeignKeyInfo[]>;
+    getViews(): Promise<ViewInfo[]>;
+    private getProcedures;
+    getTableRowCount(tableName: string): Promise<number>;
+    getVersion(): Promise<string>;
+    getDatabases(): Promise<string[]>;
+}
+
+declare class MSSQLDriver extends BaseDriver {
+    readonly type = DriverType.MSSQL;
+    private connection;
+    constructor(config: MSSQLConfig);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    executeQuery(sql: string, _params?: unknown[]): Promise<QueryResult>;
+    executeBatch(queries: string[]): Promise<QueryResult[]>;
+    getSchema(): Promise<SchemaInfo>;
+    getTables(): Promise<TableInfo[]>;
+    getTableInfo(tableName: string): Promise<TableInfo>;
+    getColumns(tableName: string): Promise<ColumnInfo[]>;
+    getIndexes(tableName: string): Promise<IndexInfo[]>;
+    getForeignKeys(tableName: string): Promise<ForeignKeyInfo[]>;
+    getViews(): Promise<ViewInfo[]>;
+    getTableRowCount(tableName: string): Promise<number>;
+    getVersion(): Promise<string>;
+    getDatabases(): Promise<string[]>;
+}
+
+declare function createDriver(config: DriverConfig): BaseDriver;
+
+declare class SchemaBrowser {
+    private driver;
+    constructor(driver: BaseDriver);
+    getSchema(): Promise<SchemaInfo>;
+    getTables(filter?: SchemaFilter): Promise<TableInfo[]>;
+    getTable(name: string): Promise<TableInfo>;
+    getColumns(tableName: string): Promise<ColumnInfo[]>;
+    getIndexes(tableName: string): Promise<IndexInfo[]>;
+    getForeignKeys(tableName: string): Promise<ForeignKeyInfo[]>;
+    getViews(): Promise<ViewInfo[]>;
+    getTableRowCount(tableName: string): Promise<number>;
+    searchTables(query: string): Promise<TableInfo[]>;
+    getTableSummary(tableName: string): Promise<{
+        name: string;
+        columnCount: number;
+        indexCount: number;
+        foreignKeyCount: number;
+        rowCount: number;
+        size?: string;
+    }>;
+}
+
+declare class QueryHistory {
+    private storage;
+    constructor(maxEntries?: number);
+    record(result: QueryResult, database: string, user?: string): QueryHistoryEntry;
+    list(params?: {
+        page?: number;
+        pageSize?: number;
+        database?: string;
+        status?: string;
+        search?: string;
+    }): PaginatedResult<QueryHistoryEntry>;
+    getRecent(limit?: number): QueryHistoryEntry[];
+    getStats(): {
+        totalQueries: number;
+        successfulQueries: number;
+        failedQueries: number;
+        avgDuration: number;
+    };
+    clear(): void;
+    remove(id: string): void;
+}
+
+type DashboardEvents = {
+    query: (result: QueryResult) => void;
+    error: (error: Error, query?: string) => void;
+    connect: () => void;
+    disconnect: () => void;
+    warning: (warning: string) => void;
+};
+declare class SQLDashboard extends EventEmitter<DashboardEvents> {
+    readonly schema: SchemaBrowser;
+    readonly history: QueryHistory;
+    readonly config: DashboardConfig;
+    readonly version: string;
+    private driver;
+    private logger;
+    private readOnlyGuard?;
+    private rateLimiter?;
+    private connected;
+    private connectionPromise;
+    constructor(options: DashboardOptions);
+    private setupSecurity;
+    private setupEventHandlers;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    query(sql: string, options?: QueryOptions): Promise<QueryResult>;
+    execute(sql: string, options?: QueryOptions): Promise<QueryResult>;
+    batch(queries: string[]): Promise<QueryResult[]>;
+    executeBatch(sql: string): Promise<QueryResult[]>;
+    transaction<T>(callback: (query: (sql: string, params?: unknown[]) => Promise<QueryResult>) => Promise<T>): Promise<T>;
+    explain(sql: string): Promise<QueryResult>;
+    analyze(sql: string): Promise<QueryResult>;
+    status(): Promise<{
+        connected: boolean;
+        driver: string;
+        version: string;
+        uptime: number;
+        history: {
+            total: number;
+            successful: number;
+            failed: number;
+        };
+        databaseVersion?: string;
+    }>;
+    getDriverVersion(): Promise<string>;
+    getDatabases(): Promise<string[]>;
+    validate(sql: string): ValidationResult;
+    private validateQuery;
+    private ensureConnected;
+    private withTimeout;
+    private getDriverType;
+    updateSecurity(config: Partial<SecurityConfig>): void;
+    destroy(): void;
+}
+declare function createDashboard(options: DashboardOptions): SQLDashboard;
+
+declare class ReadOnlyGuard {
+    private rule;
+    constructor(rule?: ReadOnlyRule);
+    isAllowed(sql: string, user?: string): boolean;
+    checkReadOnly(sql: string, user?: string): {
+        allowed: boolean;
+        reason?: string;
+    };
+    updateRule(rule: Partial<ReadOnlyRule>): void;
+}
+
+declare class RateLimiter {
+    private config;
+    private store;
+    private cleanupInterval;
+    constructor(config?: RateLimitConfig);
+    private cleanup;
+    check(key: string): {
+        allowed: boolean;
+        remaining: number;
+        resetAt: number;
+        error?: string;
+    };
+    getRemaining(key: string): number;
+    reset(key?: string): void;
+    updateConfig(config: Partial<RateLimitConfig>): void;
+    destroy(): void;
+}
+
+interface ExpressMiddlewareOptions extends DashboardOptions {
+    basePath?: string;
+}
+declare function createExpressRouter(options: ExpressMiddlewareOptions): Router;
+declare function sqlDashboard(options: ExpressMiddlewareOptions): Router;
+
+interface FastifyPluginConfig extends FastifyPluginOptions, DashboardOptions {
+    basePath?: string;
+}
+declare function registerFastifyPlugin(fastify: FastifyInstance, options: FastifyPluginConfig): Promise<void>;
+
+interface CSVExportOptions {
+    delimiter?: string;
+    includeHeader?: boolean;
+    quoteAll?: boolean;
+    encoding?: string;
+    nullValue?: string;
+}
+declare function toCSV(result: QueryResult, options?: CSVExportOptions): string;
+declare function toCSVStream(result: QueryResult, options?: CSVExportOptions): NodeJS.ReadableStream;
+
+interface JSONExportOptions {
+    pretty?: boolean;
+    indent?: number;
+    dateFormat?: 'iso' | 'timestamp';
+    includeMeta?: boolean;
+}
+declare function toJSON(result: QueryResult, options?: JSONExportOptions): string;
+declare function toJSONLines(result: QueryResult): string;
+declare function toJSONArray(result: QueryResult): string;
+
+declare function detectStatementType(sql: string): string;
+declare function isReadOnlyStatement(sql: string): boolean;
+declare function validateQuery(sql: string, security?: SecurityConfig): ValidationResult;
+
+interface FormatOptions {
+    uppercase?: boolean;
+    indent?: string;
+}
+declare function formatSQL(sql: string, options?: FormatOptions): string;
+declare function formatResultRow(row: Record<string, unknown>, columns?: string[]): Record<string, unknown>;
+
+declare class Logger {
+    private config;
+    private timers;
+    constructor(config?: LoggerConfig);
+    private shouldLog;
+    private formatMessage;
+    debug(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    error(message: string, data?: unknown): void;
+    query(sql: string, duration: number, rowCount: number): void;
+    startTimer(label: string): void;
+    endTimer(label: string): number;
+    updateConfig(config: Partial<LoggerConfig>): void;
+}
+
+declare class QueryTimer {
+    private startTime;
+    constructor();
+    get elapsed(): number;
+    reset(): void;
+    stop(): {
+        duration: number;
+        startTime: Date;
+        endTime: Date;
+    };
+    static measure<T>(fn: () => Promise<T>): Promise<{
+        result: T;
+        duration: number;
+    }>;
+}
+
+interface PaginationParams {
+    page?: number;
+    pageSize?: number;
+    offset?: number;
+}
+declare function createPaginatedResult<T>(data: T[], total: number, params: PaginationParams): PaginatedResult<T>;
+
+export { type ColumnInfo, type DashboardOptions, type DriverConfig, DriverType, Logger, MSSQLDriver, MySQLDriver, type PaginatedResult, PostgresDriver, QueryHistory, type QueryHistoryEntry, type QueryOptions, type QueryResult, QueryTimer, RateLimiter, ReadOnlyGuard, SQLDashboard, SQLiteDriver, SchemaBrowser, type SchemaInfo, type SecurityConfig, type TableInfo, type ValidationResult, createDashboard, createDriver, createExpressRouter, createPaginatedResult, SQLDashboard as default, detectStatementType, formatResultRow, formatSQL, isReadOnlyStatement, registerFastifyPlugin, sqlDashboard, toCSV, toCSVStream, toJSON, toJSONArray, toJSONLines, validateQuery };