db-mcp 1.0.1

package/dist/utils/errors.d.ts

@@ -0,0 +1,155 @@
+/**
+ * db-mcp Enhanced Error System
+ *
+ * Provides typed error classes with categorization, actionable suggestions,
+ * and structured error responses for better diagnostics.
+ */
+/**
+ * Error categories for classification and handling
+ */
+export declare enum ErrorCategory {
+    /** Input validation failures (invalid names, paths, types) */
+    VALIDATION = "validation",
+    /** Database connection issues */
+    CONNECTION = "connection",
+    /** SQL execution errors */
+    QUERY = "query",
+    /** Authorization/permission failures */
+    PERMISSION = "permission",
+    /** Configuration/setup issues */
+    CONFIGURATION = "config",
+    /** Missing resources (tables, columns, views) */
+    RESOURCE = "resource",
+    /** Unexpected internal errors */
+    INTERNAL = "internal"
+}
+/**
+ * Find a suggestion for an error message
+ */
+export declare function findSuggestion(message: string): {
+    suggestion: string;
+    category?: ErrorCategory | undefined;
+} | null;
+/**
+ * Base error class for db-mcp with enhanced diagnostics
+ */
+export declare class DbMcpError extends Error {
+    /** Error category for classification */
+    readonly category: ErrorCategory;
+    /** Module-prefixed error code (e.g., DB_QUERY_FAILED) */
+    readonly code: string;
+    /** Actionable suggestion for resolving the error */
+    readonly suggestion: string | undefined;
+    /** Additional error details */
+    readonly details: Record<string, unknown> | undefined;
+    /** Whether the error is recoverable (can retry) */
+    readonly recoverable: boolean;
+    constructor(message: string, code: string, category: ErrorCategory, options?: {
+        suggestion?: string | undefined;
+        details?: Record<string, unknown> | undefined;
+        recoverable?: boolean | undefined;
+        cause?: Error | undefined;
+    });
+    /**
+     * Convert to structured response object
+     */
+    toResponse(): ErrorResponse;
+}
+/**
+ * Validation error for invalid inputs
+ */
+export declare class ValidationError extends DbMcpError {
+    constructor(message: string, code?: string, options?: {
+        suggestion?: string | undefined;
+        details?: Record<string, unknown> | undefined;
+        cause?: Error | undefined;
+    });
+}
+/**
+ * Connection error for database connectivity issues
+ */
+export declare class ConnectionError extends DbMcpError {
+    constructor(message: string, code?: string, options?: {
+        suggestion?: string | undefined;
+        details?: Record<string, unknown> | undefined;
+        cause?: Error | undefined;
+    });
+}
+/**
+ * Query error for SQL execution failures
+ */
+export declare class QueryError extends DbMcpError {
+    constructor(message: string, code?: string, options?: {
+        suggestion?: string | undefined;
+        details?: Record<string, unknown> | undefined;
+        sql?: string | undefined;
+        cause?: Error | undefined;
+    });
+}
+/**
+ * Permission error for authorization failures
+ */
+export declare class PermissionError extends DbMcpError {
+    constructor(message: string, code?: string, options?: {
+        suggestion?: string | undefined;
+        details?: Record<string, unknown> | undefined;
+        cause?: Error | undefined;
+    });
+}
+/**
+ * Resource not found error
+ */
+export declare class ResourceNotFoundError extends DbMcpError {
+    constructor(message: string, code?: string, options?: {
+        suggestion?: string | undefined;
+        resourceType?: string | undefined;
+        resourceName?: string | undefined;
+        details?: Record<string, unknown> | undefined;
+        cause?: Error | undefined;
+    });
+}
+/**
+ * Configuration error
+ */
+export declare class ConfigurationError extends DbMcpError {
+    constructor(message: string, code?: string, options?: {
+        suggestion?: string | undefined;
+        details?: Record<string, unknown> | undefined;
+        cause?: Error | undefined;
+    });
+}
+/**
+ * Internal error for unexpected failures
+ */
+export declare class InternalError extends DbMcpError {
+    constructor(message: string, code?: string, options?: {
+        suggestion?: string | undefined;
+        details?: Record<string, unknown> | undefined;
+        cause?: Error | undefined;
+    });
+}
+/**
+ * Structured error response format
+ */
+export interface ErrorResponse {
+    success: false;
+    error: string;
+    code: string;
+    category: ErrorCategory;
+    suggestion: string | undefined;
+    recoverable: boolean;
+    details: Record<string, unknown> | undefined;
+}
+/**
+ * Convert any error to a structured error response
+ */
+export declare function formatError(error: unknown): ErrorResponse;
+/**
+ * Wrap an error with enhanced diagnostics
+ */
+export declare function wrapError(error: unknown, defaultCode?: string, defaultCategory?: ErrorCategory): DbMcpError;
+/**
+ * Check if an error is a DbMcpError
+ */
+export declare function isDbMcpError(error: unknown): error is DbMcpError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/utils/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH;;GAEG;AACH,oBAAY,aAAa;IACvB,8DAA8D;IAC9D,UAAU,eAAe;IACzB,iCAAiC;IACjC,UAAU,eAAe;IACzB,2BAA2B;IAC3B,KAAK,UAAU;IACf,wCAAwC;IACxC,UAAU,eAAe;IACzB,iCAAiC;IACjC,aAAa,WAAW;IACxB,iDAAiD;IACjD,QAAQ,aAAa;IACrB,iCAAiC;IACjC,QAAQ,aAAa;CACtB;AA+HD;;GAEG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,GACd;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,aAAa,GAAG,SAAS,CAAA;CAAE,GAAG,IAAI,CAUrE;AAMD;;GAEG;AACH,qBAAa,UAAW,SAAQ,KAAK;IACnC,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,+BAA+B;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACtD,mDAAmD;IACnD,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;gBAG5B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,aAAa,EACvB,OAAO,CAAC,EAAE;QACR,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;QAC9C,WAAW,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;QAClC,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;KAC3B;IAiBH;;OAEG;IACH,UAAU,IAAI,aAAa;CAW5B;AAMD;;GAEG;AACH,qBAAa,eAAgB,SAAQ,UAAU;gBAE3C,OAAO,EAAE,MAAM,EACf,IAAI,SAAqB,EACzB,OAAO,CAAC,EAAE;QACR,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;QAC9C,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;KAC3B;CAOJ;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,UAAU;gBAE3C,OAAO,EAAE,MAAM,EACf,IAAI,SAAqB,EACzB,OAAO,CAAC,EAAE;QACR,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;QAC9C,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;KAC3B;CAOJ;AAED;;GAEG;AACH,qBAAa,UAAW,SAAQ,UAAU;gBAEtC,OAAO,EAAE,MAAM,EACf,IAAI,SAAgB,EACpB,OAAO,CAAC,EAAE;QACR,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;QAC9C,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QACzB,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;KAC3B;CAWJ;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,UAAU;gBAE3C,OAAO,EAAE,MAAM,EACf,IAAI,SAAqB,EACzB,OAAO,CAAC,EAAE;QACR,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;QAC9C,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;KAC3B;CAOJ;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,UAAU;gBAEjD,OAAO,EAAE,MAAM,EACf,IAAI,SAAuB,EAC3B,OAAO,CAAC,EAAE;QACR,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAChC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAClC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAClC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;QAC9C,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;KAC3B;CAYJ;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,UAAU;gBAE9C,OAAO,EAAE,MAAM,EACf,IAAI,SAAiB,EACrB,OAAO,CAAC,EAAE;QACR,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;QAC9C,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;KAC3B;CAOJ;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,UAAU;gBAEzC,OAAO,EAAE,MAAM,EACf,IAAI,SAAmB,EACvB,OAAO,CAAC,EAAE;QACR,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;QAC9C,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;KAC3B;CAOJ;AAMD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,aAAa,CAAC;IACxB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,WAAW,EAAE,OAAO,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;CAC9C;AAMD;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa,CA2BzD;AAED;;GAEG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,OAAO,EACd,WAAW,SAAkB,EAC7B,eAAe,gBAAyB,GACvC,UAAU,CAkBZ;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAEhE"}

package/dist/utils/errors.js

@@ -0,0 +1,329 @@
+/**
+ * db-mcp Enhanced Error System
+ *
+ * Provides typed error classes with categorization, actionable suggestions,
+ * and structured error responses for better diagnostics.
+ */
+// =============================================================================
+// Error Categories
+// =============================================================================
+/**
+ * Error categories for classification and handling
+ */
+export var ErrorCategory;
+(function (ErrorCategory) {
+    /** Input validation failures (invalid names, paths, types) */
+    ErrorCategory["VALIDATION"] = "validation";
+    /** Database connection issues */
+    ErrorCategory["CONNECTION"] = "connection";
+    /** SQL execution errors */
+    ErrorCategory["QUERY"] = "query";
+    /** Authorization/permission failures */
+    ErrorCategory["PERMISSION"] = "permission";
+    /** Configuration/setup issues */
+    ErrorCategory["CONFIGURATION"] = "config";
+    /** Missing resources (tables, columns, views) */
+    ErrorCategory["RESOURCE"] = "resource";
+    /** Unexpected internal errors */
+    ErrorCategory["INTERNAL"] = "internal";
+})(ErrorCategory || (ErrorCategory = {}));
+// =============================================================================
+// Error Suggestions
+// =============================================================================
+/**
+ * Pattern-based suggestions for common errors
+ */
+const ERROR_SUGGESTIONS = [
+    // Validation errors
+    {
+        pattern: /invalid table name/i,
+        suggestion: "Table names must start with a letter or underscore, followed by letters, numbers, or underscores only.",
+        category: ErrorCategory.VALIDATION,
+    },
+    {
+        pattern: /invalid column name/i,
+        suggestion: "Column names must start with a letter or underscore, followed by letters, numbers, or underscores only.",
+        category: ErrorCategory.VALIDATION,
+    },
+    {
+        pattern: /invalid (view|index) name/i,
+        suggestion: "Names must start with a letter or underscore, followed by alphanumeric characters only.",
+        category: ErrorCategory.VALIDATION,
+    },
+    {
+        pattern: /json path must start with \$/i,
+        suggestion: "JSON paths use $ as the root. Example: $.name, $.items[0], $.nested.property",
+        category: ErrorCategory.VALIDATION,
+    },
+    {
+        pattern: /vector dimensions must match/i,
+        suggestion: "All vectors in comparison must have the same number of dimensions.",
+        category: ErrorCategory.VALIDATION,
+    },
+    // Resource errors
+    {
+        pattern: /no such table[:\s]*(['"]?)(\w+)\1/i,
+        suggestion: "Table not found. Run sqlite_list_tables to see available tables.",
+        category: ErrorCategory.RESOURCE,
+    },
+    {
+        pattern: /no such column[:\s]*(['"]?)(\w+)\1/i,
+        suggestion: "Column not found. Use sqlite_describe_table to see available columns.",
+        category: ErrorCategory.RESOURCE,
+    },
+    {
+        pattern: /table .* already exists/i,
+        suggestion: "Table already exists. Use CREATE TABLE IF NOT EXISTS or drop the existing table first.",
+        category: ErrorCategory.RESOURCE,
+    },
+    // Query errors
+    {
+        pattern: /syntax error/i,
+        suggestion: "Check SQL syntax. Common issues: missing quotes, commas, parentheses, or reserved word conflicts.",
+        category: ErrorCategory.QUERY,
+    },
+    {
+        pattern: /UNIQUE constraint failed/i,
+        suggestion: "A row with this value already exists. Use UPDATE to modify existing data or check for duplicates.",
+        category: ErrorCategory.QUERY,
+    },
+    {
+        pattern: /FOREIGN KEY constraint failed/i,
+        suggestion: "The referenced row does not exist. Ensure the parent record exists before inserting.",
+        category: ErrorCategory.QUERY,
+    },
+    {
+        pattern: /NOT NULL constraint failed/i,
+        suggestion: "A required column is missing a value. Provide a value or set a default.",
+        category: ErrorCategory.QUERY,
+    },
+    {
+        pattern: /CHECK constraint failed/i,
+        suggestion: "The value does not meet the column's check constraint requirements.",
+        category: ErrorCategory.QUERY,
+    },
+    // Connection errors
+    {
+        pattern: /not connected/i,
+        suggestion: "Database connection not established. Ensure the database is configured and connected.",
+        category: ErrorCategory.CONNECTION,
+    },
+    {
+        pattern: /database is locked/i,
+        suggestion: "Database is being used by another process. Wait and retry, or check for long-running transactions.",
+        category: ErrorCategory.CONNECTION,
+    },
+    // Permission errors
+    {
+        pattern: /readonly database/i,
+        suggestion: "Database is in read-only mode. Check file permissions or connection settings.",
+        category: ErrorCategory.PERMISSION,
+    },
+    {
+        pattern: /attempt to write a readonly/i,
+        suggestion: "Write operations are not allowed. Check database configuration.",
+        category: ErrorCategory.PERMISSION,
+    },
+];
+/**
+ * Find a suggestion for an error message
+ */
+export function findSuggestion(message) {
+    for (const entry of ERROR_SUGGESTIONS) {
+        if (entry.pattern.test(message)) {
+            return {
+                suggestion: entry.suggestion,
+                category: entry.category,
+            };
+        }
+    }
+    return null;
+}
+// =============================================================================
+// Base Error Class
+// =============================================================================
+/**
+ * Base error class for db-mcp with enhanced diagnostics
+ */
+export class DbMcpError extends Error {
+    /** Error category for classification */
+    category;
+    /** Module-prefixed error code (e.g., DB_QUERY_FAILED) */
+    code;
+    /** Actionable suggestion for resolving the error */
+    suggestion;
+    /** Additional error details */
+    details;
+    /** Whether the error is recoverable (can retry) */
+    recoverable;
+    constructor(message, code, category, options) {
+        super(message, { cause: options?.cause });
+        this.name = this.constructor.name;
+        this.code = code;
+        this.category = category;
+        this.recoverable = options?.recoverable ?? false;
+        this.details = options?.details;
+        // Auto-detect suggestion if not provided
+        this.suggestion =
+            options?.suggestion ?? findSuggestion(message)?.suggestion;
+        // Capture stack trace
+        Error.captureStackTrace?.(this, this.constructor);
+    }
+    /**
+     * Convert to structured response object
+     */
+    toResponse() {
+        return {
+            success: false,
+            error: this.message,
+            code: this.code,
+            category: this.category,
+            suggestion: this.suggestion,
+            recoverable: this.recoverable,
+            details: this.details,
+        };
+    }
+}
+// =============================================================================
+// Specific Error Classes
+// =============================================================================
+/**
+ * Validation error for invalid inputs
+ */
+export class ValidationError extends DbMcpError {
+    constructor(message, code = "VALIDATION_ERROR", options) {
+        super(message, code, ErrorCategory.VALIDATION, {
+            ...options,
+            recoverable: false,
+        });
+    }
+}
+/**
+ * Connection error for database connectivity issues
+ */
+export class ConnectionError extends DbMcpError {
+    constructor(message, code = "CONNECTION_ERROR", options) {
+        super(message, code, ErrorCategory.CONNECTION, {
+            ...options,
+            recoverable: true, // Connection errors are often transient
+        });
+    }
+}
+/**
+ * Query error for SQL execution failures
+ */
+export class QueryError extends DbMcpError {
+    constructor(message, code = "QUERY_ERROR", options) {
+        super(message, code, ErrorCategory.QUERY, {
+            ...options,
+            details: {
+                ...options?.details,
+                sql: options?.sql,
+            },
+            recoverable: false,
+        });
+    }
+}
+/**
+ * Permission error for authorization failures
+ */
+export class PermissionError extends DbMcpError {
+    constructor(message, code = "PERMISSION_ERROR", options) {
+        super(message, code, ErrorCategory.PERMISSION, {
+            ...options,
+            recoverable: false,
+        });
+    }
+}
+/**
+ * Resource not found error
+ */
+export class ResourceNotFoundError extends DbMcpError {
+    constructor(message, code = "RESOURCE_NOT_FOUND", options) {
+        super(message, code, ErrorCategory.RESOURCE, {
+            ...options,
+            details: {
+                ...options?.details,
+                resourceType: options?.resourceType,
+                resourceName: options?.resourceName,
+            },
+            recoverable: false,
+        });
+    }
+}
+/**
+ * Configuration error
+ */
+export class ConfigurationError extends DbMcpError {
+    constructor(message, code = "CONFIG_ERROR", options) {
+        super(message, code, ErrorCategory.CONFIGURATION, {
+            ...options,
+            recoverable: false,
+        });
+    }
+}
+/**
+ * Internal error for unexpected failures
+ */
+export class InternalError extends DbMcpError {
+    constructor(message, code = "INTERNAL_ERROR", options) {
+        super(message, code, ErrorCategory.INTERNAL, {
+            ...options,
+            recoverable: false,
+        });
+    }
+}
+// =============================================================================
+// Utility Functions
+// =============================================================================
+/**
+ * Convert any error to a structured error response
+ */
+export function formatError(error) {
+    if (error instanceof DbMcpError) {
+        return error.toResponse();
+    }
+    if (error instanceof Error) {
+        const match = findSuggestion(error.message);
+        return {
+            success: false,
+            error: error.message,
+            code: "UNKNOWN_ERROR",
+            category: match?.category ?? ErrorCategory.INTERNAL,
+            suggestion: match?.suggestion,
+            recoverable: false,
+            details: undefined,
+        };
+    }
+    return {
+        success: false,
+        error: String(error),
+        code: "UNKNOWN_ERROR",
+        category: ErrorCategory.INTERNAL,
+        suggestion: undefined,
+        recoverable: false,
+        details: undefined,
+    };
+}
+/**
+ * Wrap an error with enhanced diagnostics
+ */
+export function wrapError(error, defaultCode = "UNKNOWN_ERROR", defaultCategory = ErrorCategory.INTERNAL) {
+    if (error instanceof DbMcpError) {
+        return error;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    const match = findSuggestion(message);
+    return new DbMcpError(message, defaultCode, match?.category ?? defaultCategory, {
+        suggestion: match?.suggestion,
+        cause: error instanceof Error ? error : undefined,
+        recoverable: false,
+    });
+}
+/**
+ * Check if an error is a DbMcpError
+ */
+export function isDbMcpError(error) {
+    return error instanceof DbMcpError;
+}
+//# sourceMappingURL=errors.js.map

package/dist/utils/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"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"}

package/dist/utils/identifiers.d.ts

@@ -0,0 +1,121 @@
+/**
+ * db-mcp - Identifier Sanitization Utilities
+ *
+ * Provides safe handling of SQLite identifiers (table names, column names)
+ * to prevent SQL injection attacks via identifier interpolation.
+ *
+ * SQLite identifier rules:
+ * - Can contain letters, digits, underscores (more permissive than PostgreSQL)
+ * - Maximum practical length: 255 bytes
+ * - Case-insensitive for ASCII letters unless quoted
+ *
+ * Adapted from postgres-mcp reference implementation for SQLite.
+ */
+/**
+ * Error thrown when an identifier is invalid
+ */
+export declare class InvalidIdentifierError extends Error {
+    readonly identifier: string;
+    readonly reason: string;
+    constructor(identifier: string, reason: string);
+}
+/**
+ * Validate a SQLite identifier
+ *
+ * @param name - The identifier to validate
+ * @throws InvalidIdentifierError if the identifier is invalid
+ */
+export declare function validateIdentifier(name: string): void;
+/**
+ * Sanitize and quote a SQLite identifier for safe use in SQL queries
+ *
+ * This function:
+ * 1. Validates the identifier against SQLite naming rules
+ * 2. Escapes any embedded double quotes
+ * 3. Wraps the identifier in double quotes for safe interpolation
+ *
+ * @param name - The identifier to sanitize
+ * @returns The sanitized, double-quoted identifier
+ * @throws InvalidIdentifierError if the identifier is invalid
+ *
+ * @example
+ * sanitizeIdentifier('users') // Returns: "users"
+ * sanitizeIdentifier('my_table') // Returns: "my_table"
+ * sanitizeIdentifier('User"Data') // Throws: InvalidIdentifierError
+ */
+export declare function sanitizeIdentifier(name: string): string;
+/**
+ * Check if an identifier needs quoting (is a reserved keyword or has special characters)
+ *
+ * @param name - The identifier to check
+ * @returns True if the identifier needs quoting
+ */
+export declare function needsQuoting(name: string): boolean;
+/**
+ * Sanitize a table name
+ *
+ * @param table - The table name
+ * @returns The sanitized table reference
+ *
+ * @example
+ * sanitizeTableName('users') // Returns: "users"
+ */
+export declare function sanitizeTableName(table: string): string;
+/**
+ * Sanitize a column reference with optional table qualifier
+ *
+ * @param column - The column name
+ * @param table - Optional table name or alias
+ * @returns The sanitized column reference
+ *
+ * @example
+ * sanitizeColumnRef('id') // Returns: "id"
+ * sanitizeColumnRef('id', 'users') // Returns: "users"."id"
+ */
+export declare function sanitizeColumnRef(column: string, table?: string): string;
+/**
+ * Sanitize an array of identifiers
+ *
+ * @param names - Array of identifier names
+ * @returns Array of sanitized identifiers
+ */
+export declare function sanitizeIdentifiers(names: string[]): string[];
+/**
+ * Create a safe column list for SELECT statements
+ *
+ * @param columns - Array of column names
+ * @returns Comma-separated list of sanitized column names
+ *
+ * @example
+ * createColumnList(['id', 'name', 'email']) // Returns: "id", "name", "email"
+ */
+export declare function createColumnList(columns: string[]): string;
+/**
+ * Sanitize an index name
+ * SQLite index names follow the same rules as identifiers
+ *
+ * @param name - The index name
+ * @returns The sanitized index name
+ */
+export declare function sanitizeIndexName(name: string): string;
+/**
+ * Quote an identifier for safe use in SQL without strict validation.
+ *
+ * Unlike sanitizeIdentifier(), this function:
+ * - Allows reserved keywords (they become valid when quoted)
+ * - Allows any valid SQLite identifier characters
+ * - Only validates basic safety (length, no dangerous characters)
+ *
+ * Use this for user-provided names where reserved keywords
+ * are perfectly valid SQLite identifiers when properly quoted.
+ *
+ * @param name - The identifier to quote
+ * @returns The double-quoted identifier safe for SQL interpolation
+ * @throws InvalidIdentifierError if the identifier is genuinely invalid
+ *
+ * @example
+ * quoteIdentifier('table') // Returns: "table" (reserved keyword, but valid)
+ * quoteIdentifier('my_column') // Returns: "my_column"
+ */
+export declare function quoteIdentifier(name: string): string;
+//# sourceMappingURL=identifiers.d.ts.map

package/dist/utils/identifiers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identifiers.d.ts","sourceRoot":"","sources":["../../src/utils/identifiers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAgJH;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;aAE7B,UAAU,EAAE,MAAM;aAClB,MAAM,EAAE,MAAM;gBADd,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM;CAKjC;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAqBrD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOvD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAYlD;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CASxE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAE7D;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAE1D;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CA2BpD"}