@ductape/sdk 0.0.4-v6 → 0.0.4-v61

package/dist/database/adapters/cassandra.adapter.js

@@ -0,0 +1,1075 @@
+"use strict";
+/**
+ * Cassandra Adapter
+ *
+ * Database adapter for Apache Cassandra using the 'cassandra-driver' library.
+ * Implements all methods from BaseAdapter with Cassandra-specific operations.
+ *
+ * Key Cassandra concepts:
+ * - Keyspace (like a database/schema)
+ * - Column family/Table
+ * - Partition key and clustering columns
+ * - No JOINs - denormalized data model
+ * - No transactions in the traditional sense (uses lightweight transactions)
+ * - Eventual consistency by default
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CassandraAdapter = void 0;
+const base_adapter_1 = require("./base.adapter");
+const enums_1 = require("../types/enums");
+const database_error_1 = require("../utils/database-error");
+/**
+ * Cassandra database adapter
+ * Provides Cassandra-specific implementations for all database operations
+ */
+class CassandraAdapter extends base_adapter_1.BaseAdapter {
+    constructor() {
+        super(...arguments);
+        this.databaseType = enums_1.DatabaseType.CASSANDRA;
+        this.cassandraClient = null;
+        this.keyspace = '';
+    }
+    // ==================== CONNECTION METHODS ====================
+    async connect(options) {
+        console.log(`[CassandraAdapter] connect() called`);
+        console.log(`[CassandraAdapter] Options:`, JSON.stringify(Object.assign(Object.assign({}, options), { connectionUrl: '***REDACTED***' }), null, 2));
+        try {
+            console.log(`[CassandraAdapter] Importing 'cassandra-driver' library...`);
+            // Dynamic import of cassandra-driver
+            const cassandra = await Promise.resolve().then(() => __importStar(require('cassandra-driver')));
+            console.log(`[CassandraAdapter] 'cassandra-driver' library imported successfully`);
+            this.connectionUrl = options.connectionUrl;
+            console.log(`[CassandraAdapter] Connection URL stored`);
+            // Parse connection URL: cassandra://host1,host2:port/keyspace
+            console.log(`[CassandraAdapter] Parsing connection URL...`);
+            const url = new URL(options.connectionUrl);
+            const hosts = url.hostname.split(',');
+            const port = parseInt(url.port) || 9042;
+            this.keyspace = url.pathname.slice(1) || 'system';
+            console.log(`[CassandraAdapter] Connection config:`, {
+                hosts,
+                port,
+                keyspace: this.keyspace,
+                hasUsername: !!url.username,
+                hasPassword: !!url.password,
+            });
+            const clientOptions = {
+                contactPoints: hosts,
+                localDataCenter: 'datacenter1', // Default, can be overridden
+                keyspace: this.keyspace,
+                protocolOptions: { port },
+            };
+            // Authentication
+            if (url.username && url.password) {
+                clientOptions.credentials = {
+                    username: url.username,
+                    password: url.password,
+                };
+                console.log(`[CassandraAdapter] Using authentication`);
+            }
+            // Parse query parameters for additional options
+            const params = new URLSearchParams(url.search);
+            if (params.get('datacenter')) {
+                clientOptions.localDataCenter = params.get('datacenter');
+                console.log(`[CassandraAdapter] Using datacenter: ${clientOptions.localDataCenter}`);
+            }
+            console.log(`[CassandraAdapter] Creating Cassandra client...`);
+            this.cassandraClient = new cassandra.Client(clientOptions);
+            console.log(`[CassandraAdapter] Client created, connecting...`);
+            await this.cassandraClient.connect();
+            console.log(`[CassandraAdapter] Connected successfully`);
+            // Get cluster information
+            console.log(`[CassandraAdapter] Getting cluster information...`);
+            const metadata = this.cassandraClient.metadata;
+            const version = await this.getClusterVersion();
+            console.log(`[CassandraAdapter] Cluster version: ${version}`);
+            this.client = this.cassandraClient;
+            this.connected = true;
+            console.log(`[CassandraAdapter] Connection marked as connected`);
+            return {
+                connected: true,
+                version: `Cassandra ${version}`,
+            };
+        }
+        catch (error) {
+            console.error(`[CassandraAdapter] Connection failed with error:`, error);
+            console.error(`[CassandraAdapter] Error type:`, error.constructor.name);
+            console.error(`[CassandraAdapter] Error message:`, error.message);
+            console.error(`[CassandraAdapter] Error code:`, error.code);
+            console.error(`[CassandraAdapter] Full error:`, JSON.stringify(error, null, 2));
+            throw database_error_1.DatabaseError.connectionError(`Failed to connect to Cassandra: ${error.message}`, error);
+        }
+    }
+    async testConnection(options) {
+        var _a;
+        try {
+            const cassandra = await Promise.resolve().then(() => __importStar(require('cassandra-driver')));
+            const url = new URL(options.connectionUrl);
+            const hosts = url.hostname.split(',');
+            const port = parseInt(url.port) || 9042;
+            const keyspace = url.pathname.slice(1) || 'system';
+            const client = new cassandra.Client({
+                contactPoints: hosts,
+                localDataCenter: 'datacenter1',
+                keyspace,
+                protocolOptions: { port },
+            });
+            await client.connect();
+            const result = await client.execute('SELECT release_version FROM system.local');
+            const version = ((_a = result.rows[0]) === null || _a === void 0 ? void 0 : _a.release_version) || 'unknown';
+            await client.shutdown();
+            return {
+                connected: true,
+                version: `Cassandra ${version}`,
+            };
+        }
+        catch (error) {
+            return {
+                connected: false,
+                error: error.message,
+            };
+        }
+    }
+    async disconnect() {
+        if (this.cassandraClient) {
+            await this.cassandraClient.shutdown();
+            this.cassandraClient = null;
+            this.client = null;
+            this.connected = false;
+        }
+    }
+    // ==================== QUERY METHODS ====================
+    async query(query) {
+        this.ensureConnected();
+        try {
+            const result = await this.cassandraClient.execute(query.sql, query.params, {
+                prepare: true,
+            });
+            return {
+                data: result.rows,
+                count: result.rows.length,
+            };
+        }
+        catch (error) {
+            throw database_error_1.DatabaseError.fromDatabaseError(error, 'cassandra');
+        }
+    }
+    async raw(options) {
+        this.ensureConnected();
+        try {
+            const result = await this.cassandraClient.execute(options.query, options.params, { prepare: true });
+            return {
+                data: result.rows,
+                count: result.rows.length,
+            };
+        }
+        catch (error) {
+            throw database_error_1.DatabaseError.fromDatabaseError(error, 'cassandra');
+        }
+    }
+    // ==================== WRITE METHODS ====================
+    async insert(options) {
+        var _a;
+        this.ensureConnected();
+        try {
+            const data = Array.isArray(options.data) ? options.data : [options.data];
+            if (data.length === 0) {
+                return { data: [], count: 0, insertedIds: [] };
+            }
+            const insertedIds = [];
+            // Use batch for multiple inserts
+            if (data.length > 1) {
+                const queries = data.map(record => {
+                    const columns = Object.keys(record);
+                    const values = Object.values(record);
+                    const placeholders = columns.map(() => '?').join(', ');
+                    return {
+                        query: `INSERT INTO ${this.escapeIdentifier(options.table)} (${columns.join(', ')}) VALUES (${placeholders})`,
+                        params: values,
+                    };
+                });
+                await this.cassandraClient.batch(queries, { prepare: true });
+            }
+            else {
+                const record = data[0];
+                const columns = Object.keys(record);
+                const values = Object.values(record);
+                const placeholders = columns.map(() => '?').join(', ');
+                let sql = `INSERT INTO ${this.escapeIdentifier(options.table)} (${columns.join(', ')}) VALUES (${placeholders})`;
+                // Handle IF NOT EXISTS for conflict handling
+                if (((_a = options.onConflict) === null || _a === void 0 ? void 0 : _a.action) === 'ignore') {
+                    sql += ' IF NOT EXISTS';
+                }
+                await this.cassandraClient.execute(sql, values, { prepare: true });
+            }
+            // Cassandra doesn't return inserted IDs
+            data.forEach(record => {
+                insertedIds.push(record.id || record._id || null);
+            });
+            return {
+                data: options.returning ? data : [],
+                count: data.length,
+                insertedIds,
+            };
+        }
+        catch (error) {
+            throw database_error_1.DatabaseError.fromDatabaseError(error, 'cassandra');
+        }
+    }
+    async update(options) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+        this.ensureConnected();
+        try {
+            const setClauses = [];
+            const values = [];
+            // Build SET clause
+            for (const [key, value] of Object.entries(options.data)) {
+                if (value && typeof value === 'object' && this.isUpdateOperator(value)) {
+                    // Handle update operators - support both lowercase (new) and uppercase (legacy)
+                    if ('$inc' in value || '$INC' in value) {
+                        // Cassandra supports counter increment
+                        setClauses.push(`${key} = ${key} + ?`);
+                        values.push((_a = value.$inc) !== null && _a !== void 0 ? _a : value.$INC);
+                    }
+                    else if ('$dec' in value || '$DEC' in value) {
+                        // Cassandra supports counter decrement
+                        setClauses.push(`${key} = ${key} - ?`);
+                        values.push((_b = value.$dec) !== null && _b !== void 0 ? _b : value.$DEC);
+                    }
+                    else if ('$set' in value || '$SET' in value) {
+                        setClauses.push(`${key} = ?`);
+                        values.push((_c = value.$set) !== null && _c !== void 0 ? _c : value.$SET);
+                    }
+                    else if (('$unset' in value && value.$unset) || ('$UNSET' in value && value.$UNSET)) {
+                        // Cassandra uses DELETE for removing columns, or set to null
+                        setClauses.push(`${key} = null`);
+                    }
+                    else if ('$push' in value || '$PUSH' in value) {
+                        // Cassandra list append
+                        setClauses.push(`${key} = ${key} + ?`);
+                        values.push([(_d = value.$push) !== null && _d !== void 0 ? _d : value.$PUSH]);
+                    }
+                    else if ('$pull' in value || '$PULL' in value) {
+                        // Cassandra list remove
+                        setClauses.push(`${key} = ${key} - ?`);
+                        values.push([(_e = value.$pull) !== null && _e !== void 0 ? _e : value.$PULL]);
+                    }
+                    else if ('$addToSet' in value || '$ADDTOSET' in value) {
+                        // Cassandra set add
+                        setClauses.push(`${key} = ${key} + ?`);
+                        values.push(new Set([(_f = value.$addToSet) !== null && _f !== void 0 ? _f : value.$ADDTOSET]));
+                    }
+                    else if ('$mul' in value || '$MUL' in value) {
+                        // Cassandra doesn't support multiply natively - log warning
+                        console.warn(`Cassandra does not support $mul operator natively for column ${key}`);
+                        setClauses.push(`${key} = ?`);
+                        values.push((_g = value.$mul) !== null && _g !== void 0 ? _g : value.$MUL); // Just set the multiplier value as fallback
+                    }
+                    else if ('$min' in value || '$MIN' in value || '$max' in value || '$MAX' in value) {
+                        // Cassandra doesn't support min/max natively - log warning
+                        console.warn(`Cassandra does not support $min/$max operator natively for column ${key}`);
+                        setClauses.push(`${key} = ?`);
+                        values.push((_k = (_j = (_h = value.$min) !== null && _h !== void 0 ? _h : value.$MIN) !== null && _j !== void 0 ? _j : value.$max) !== null && _k !== void 0 ? _k : value.$MAX); // Just set the value as fallback
+                    }
+                    else if ('$currentDate' in value || '$CURRENTDATE' in value) {
+                        setClauses.push(`${key} = toTimestamp(now())`);
+                    }
+                }
+                else {
+                    setClauses.push(`${key} = ?`);
+                    values.push(value);
+                }
+            }
+            let sql = `UPDATE ${this.escapeIdentifier(options.table)} SET ${setClauses.join(', ')}`;
+            // Build WHERE clause (required in Cassandra)
+            if (options.where) {
+                const { whereClause, whereParams } = this.buildWhereClause(options.where);
+                sql += ` WHERE ${whereClause}`;
+                values.push(...whereParams);
+            }
+            else {
+                throw new database_error_1.DatabaseError('Cassandra UPDATE requires a WHERE clause with primary key', enums_1.DatabaseErrorType.QUERY_ERROR);
+            }
+            await this.cassandraClient.execute(sql, values, { prepare: true });
+            return {
+                data: [],
+                count: 1, // Cassandra doesn't return affected rows
+            };
+        }
+        catch (error) {
+            throw database_error_1.DatabaseError.fromDatabaseError(error, 'cassandra');
+        }
+    }
+    async delete(options) {
+        this.ensureConnected();
+        try {
+            let sql = `DELETE FROM ${this.escapeIdentifier(options.table)}`;
+            const values = [];
+            // Build WHERE clause (required in Cassandra)
+            if (options.where) {
+                const { whereClause, whereParams } = this.buildWhereClause(options.where);
+                sql += ` WHERE ${whereClause}`;
+                values.push(...whereParams);
+            }
+            else {
+                throw new database_error_1.DatabaseError('Cassandra DELETE requires a WHERE clause with primary key', enums_1.DatabaseErrorType.QUERY_ERROR);
+            }
+            await this.cassandraClient.execute(sql, values, { prepare: true });
+            return {
+                count: 1, // Cassandra doesn't return affected rows
+            };
+        }
+        catch (error) {
+            throw database_error_1.DatabaseError.fromDatabaseError(error, 'cassandra');
+        }
+    }
+    async upsert(options) {
+        this.ensureConnected();
+        try {
+            // Cassandra INSERT is an upsert by default
+            const result = await this.insert(Object.assign(Object.assign({}, options), { returning: true }));
+            return {
+                data: result.data,
+                count: result.count,
+                operation: 'inserted', // Cassandra doesn't distinguish
+            };
+        }
+        catch (error) {
+            throw database_error_1.DatabaseError.fromDatabaseError(error, 'cassandra');
+        }
+    }
+    // ==================== AGGREGATION METHODS ====================
+    async count(options) {
+        this.ensureConnected();
+        try {
+            let sql = `SELECT COUNT(*) as count FROM ${this.escapeIdentifier(options.table)}`;
+            const values = [];
+            if (options.where) {
+                const { whereClause, whereParams } = this.buildWhereClause(options.where);
+                sql += ` WHERE ${whereClause}`;
+                values.push(...whereParams);
+            }
+            // Note: Cassandra's COUNT can be slow on large tables
+            const result = await this.cassandraClient.execute(sql, values, { prepare: true });
+            return Number(result.rows[0].count) || 0;
+        }
+        catch (error) {
+            throw database_error_1.DatabaseError.fromDatabaseError(error, 'cassandra');
+        }
+    }
+    async sum(options) {
+        this.ensureConnected();
+        try {
+            // Cassandra doesn't have SUM, need to fetch and compute
+            let sql = `SELECT ${this.escapeIdentifier(options.column)} FROM ${this.escapeIdentifier(options.table)}`;
+            const values = [];
+            if (options.where) {
+                const { whereClause, whereParams } = this.buildWhereClause(options.where);
+                sql += ` WHERE ${whereClause}`;
+                values.push(...whereParams);
+            }
+            const result = await this.cassandraClient.execute(sql, values, { prepare: true });
+            return result.rows.reduce((sum, row) => sum + (Number(row[options.column]) || 0), 0);
+        }
+        catch (error) {
+            throw database_error_1.DatabaseError.fromDatabaseError(error, 'cassandra');
+        }
+    }
+    async avg(options) {
+        this.ensureConnected();
+        try {
+            // Cassandra doesn't have AVG, need to fetch and compute
+            let sql = `SELECT ${this.escapeIdentifier(options.column)} FROM ${this.escapeIdentifier(options.table)}`;
+            const values = [];
+            if (options.where) {
+                const { whereClause, whereParams } = this.buildWhereClause(options.where);
+                sql += ` WHERE ${whereClause}`;
+                values.push(...whereParams);
+            }
+            const result = await this.cassandraClient.execute(sql, values, { prepare: true });
+            const rows = result.rows;
+            if (rows.length === 0)
+                return 0;
+            const sum = rows.reduce((acc, row) => acc + (Number(row[options.column]) || 0), 0);
+            return sum / rows.length;
+        }
+        catch (error) {
+            throw database_error_1.DatabaseError.fromDatabaseError(error, 'cassandra');
+        }
+    }
+    async min(options) {
+        var _a;
+        this.ensureConnected();
+        try {
+            // Use MIN function (CQL supports this)
+            let sql = `SELECT MIN(${this.escapeIdentifier(options.column)}) as min FROM ${this.escapeIdentifier(options.table)}`;
+            const values = [];
+            if (options.where) {
+                const { whereClause, whereParams } = this.buildWhereClause(options.where);
+                sql += ` WHERE ${whereClause}`;
+                values.push(...whereParams);
+            }
+            const result = await this.cassandraClient.execute(sql, values, { prepare: true });
+            return (_a = result.rows[0]) === null || _a === void 0 ? void 0 : _a.min;
+        }
+        catch (error) {
+            throw database_error_1.DatabaseError.fromDatabaseError(error, 'cassandra');
+        }
+    }
+    async max(options) {
+        var _a;
+        this.ensureConnected();
+        try {
+            // Use MAX function (CQL supports this)
+            let sql = `SELECT MAX(${this.escapeIdentifier(options.column)}) as max FROM ${this.escapeIdentifier(options.table)}`;
+            const values = [];
+            if (options.where) {
+                const { whereClause, whereParams } = this.buildWhereClause(options.where);
+                sql += ` WHERE ${whereClause}`;
+                values.push(...whereParams);
+            }
+            const result = await this.cassandraClient.execute(sql, values, { prepare: true });
+            return (_a = result.rows[0]) === null || _a === void 0 ? void 0 : _a.max;
+        }
+        catch (error) {
+            throw database_error_1.DatabaseError.fromDatabaseError(error, 'cassandra');
+        }
+    }
+    async aggregate(builtAggregation) {
+        this.ensureConnected();
+        try {
+            // Cassandra has limited aggregation support
+            // We'll execute and compute in memory
+            const options = builtAggregation.options;
+            let sql = `SELECT * FROM ${this.escapeIdentifier(options.table)}`;
+            const values = [];
+            if (options.where) {
+                const { whereClause, whereParams } = this.buildWhereClause(options.where);
+                sql += ` WHERE ${whereClause}`;
+                values.push(...whereParams);
+            }
+            const result = await this.cassandraClient.execute(sql, values, { prepare: true });
+            const rows = result.rows;
+            const aggregateResult = {};
+            const operations = options.operations || {};
+            for (const [alias, op] of Object.entries(operations)) {
+                const operation = op;
+                if (operation.$COUNT) {
+                    aggregateResult[alias] = rows.length;
+                }
+                else if (operation.$SUM) {
+                    aggregateResult[alias] = rows.reduce((sum, row) => sum + (Number(row[operation.$SUM]) || 0), 0);
+                }
+                else if (operation.$AVG) {
+                    const values = rows.map((row) => Number(row[operation.$AVG]) || 0);
+                    aggregateResult[alias] = values.length > 0 ? values.reduce((a, b) => a + b, 0) / values.length : 0;
+                }
+                else if (operation.$MIN) {
+                    const values = rows.map((row) => row[operation.$MIN]).filter((v) => v != null);
+                    aggregateResult[alias] = values.length > 0 ? Math.min(...values) : null;
+                }
+                else if (operation.$MAX) {
+                    const values = rows.map((row) => row[operation.$MAX]).filter((v) => v != null);
+                    aggregateResult[alias] = values.length > 0 ? Math.max(...values) : null;
+                }
+            }
+            return aggregateResult;
+        }
+        catch (error) {
+            throw database_error_1.DatabaseError.fromDatabaseError(error, 'cassandra');
+        }
+    }
+    async groupBy(builtGroupBy) {
+        this.ensureConnected();
+        try {
+            // Cassandra doesn't support GROUP BY in the same way as SQL
+            // We need to fetch and group in memory
+            const options = builtGroupBy.options;
+            let sql = `SELECT * FROM ${this.escapeIdentifier(options.table)}`;
+            const values = [];
+            if (options.where) {
+                const { whereClause, whereParams } = this.buildWhereClause(options.where);
+                sql += ` WHERE ${whereClause}`;
+                values.push(...whereParams);
+            }
+            const result = await this.cassandraClient.execute(sql, values, { prepare: true });
+            const rows = result.rows;
+            // Group in memory
+            const groups = new Map();
+            const groupByColumns = options.groupBy || [];
+            for (const row of rows) {
+                const groupKey = groupByColumns.map((col) => String(row[col])).join('|');
+                if (!groups.has(groupKey)) {
+                    groups.set(groupKey, []);
+                }
+                groups.get(groupKey).push(row);
+            }
+            // Compute aggregations
+            const results = [];
+            const operations = options.operations || {};
+            for (const [groupKey, groupRows] of groups) {
+                const group = {};
+                const keyParts = groupKey.split('|');
+                groupByColumns.forEach((col, i) => {
+                    group[col] = keyParts[i];
+                });
+                const aggregates = {};
+                for (const [alias, op] of Object.entries(operations)) {
+                    const operation = op;
+                    if (operation.$COUNT) {
+                        aggregates[alias] = groupRows.length;
+                    }
+                    else if (operation.$SUM) {
+                        aggregates[alias] = groupRows.reduce((sum, row) => sum + (Number(row[operation.$SUM]) || 0), 0);
+                    }
+                    else if (operation.$AVG) {
+                        const values = groupRows.map((row) => Number(row[operation.$AVG]) || 0);
+                        aggregates[alias] = values.length > 0 ? values.reduce((a, b) => a + b, 0) / values.length : 0;
+                    }
+                    else if (operation.$MIN) {
+                        const values = groupRows.map((row) => row[operation.$MIN]).filter((v) => v != null);
+                        aggregates[alias] = values.length > 0 ? Math.min(...values) : null;
+                    }
+                    else if (operation.$MAX) {
+                        const values = groupRows.map((row) => row[operation.$MAX]).filter((v) => v != null);
+                        aggregates[alias] = values.length > 0 ? Math.max(...values) : null;
+                    }
+                }
+                results.push({ group, aggregates: aggregates });
+            }
+            return results;
+        }
+        catch (error) {
+            throw database_error_1.DatabaseError.fromDatabaseError(error, 'cassandra');
+        }
+    }
+    // ==================== TRANSACTION METHODS ====================
+    //
+    // ⚠️ IMPORTANT: Cassandra Transaction Limitations
+    //
+    // Cassandra does NOT support traditional ACID transactions across multiple statements.
+    // What Cassandra offers instead:
+    //
+    // 1. Lightweight Transactions (LWT): Single-statement atomicity with IF conditions
+    //    Example: INSERT INTO users (id, email) VALUES (?, ?) IF NOT EXISTS
+    //
+    // 2. Batched Writes: Atomic writes to a single partition (LOGGED BATCH)
+    //    Note: Batches across partitions are NOT atomic
+    //
+    // 3. Per-Statement Atomicity: Each CQL statement is atomic on its own
+    //
+    // The methods below provide a transaction-like interface for API compatibility,
+    // but they DO NOT provide multi-statement ACID guarantees. Operations are
+    // collected but not executed atomically as a group.
+    //
+    // For true transactional semantics, consider:
+    // - Using a different database for transactional workloads
+    // - Designing your data model for single-partition operations
+    // - Implementing application-level compensation patterns (Saga pattern)
+    //
+    async beginTransaction(isolationLevel, readOnly, timeout) {
+        // WARNING: This creates a transaction context for API compatibility only.
+        // Cassandra does not support multi-statement transactions.
+        // Operations collected here will NOT be executed atomically.
+        console.warn('[Cassandra] beginTransaction called, but Cassandra does not support ' +
+            'multi-statement ACID transactions. Operations will be executed individually. ' +
+            'Consider using Lightweight Transactions (LWT) with IF conditions for single-statement atomicity.');
+        const id = `cass_lwt_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+        return {
+            id,
+            databaseType: 'cassandra',
+            isolationLevel: enums_1.IsolationLevel.SERIALIZABLE, // LWT provides serializable-like semantics for single statements
+            readOnly: readOnly || false,
+            timeout,
+            startedAt: new Date(),
+            client: {
+                operations: [],
+            },
+            savepoints: new Map(),
+            status: 'active',
+        };
+    }
+    async commitTransaction(context) {
+        // WARNING: This does not provide atomic commit across multiple operations.
+        // Each operation was (or should be) executed individually.
+        // This method only updates the context status for API compatibility.
+        console.warn('[Cassandra] commitTransaction called, but Cassandra does not support ' +
+            'atomic commits across multiple statements. Status updated for API compatibility only.');
+        context.status = 'committed';
+    }
+    async rollbackTransaction(context) {
+        // WARNING: Cassandra cannot rollback already-executed operations.
+        // This only clears pending operations that haven't been executed yet.
+        console.warn('[Cassandra] rollbackTransaction called, but Cassandra cannot rollback ' +
+            'already-executed operations. Only pending operations are cleared.');
+        context.client.operations = [];
+        context.status = 'rolled_back';
+    }
+    async createSavepoint(context, name) {
+        throw new database_error_1.DatabaseError('Cassandra does not support savepoints.', enums_1.DatabaseErrorType.NOT_SUPPORTED);
+    }
+    async releaseSavepoint(context, savepoint) {
+        throw new database_error_1.DatabaseError('Cassandra does not support savepoints.', enums_1.DatabaseErrorType.NOT_SUPPORTED);
+    }
+    async rollbackToSavepoint(context, savepoint) {
+        throw new database_error_1.DatabaseError('Cassandra does not support savepoints.', enums_1.DatabaseErrorType.NOT_SUPPORTED);
+    }
+    supportsSavepoints() {
+        return false;
+    }
+    // ==================== SCHEMA METHODS ====================
+    async createTable(definition, options) {
+        this.ensureConnected();
+        try {
+            const columnDefs = definition.columns.map(col => this.buildColumnDefinition(col)).join(', ');
+            // Find primary key
+            const pkColumns = definition.columns.filter(c => c.primaryKey);
+            if (pkColumns.length === 0) {
+                throw new Error('Cassandra tables require at least one primary key column');
+            }
+            const primaryKeyDef = `PRIMARY KEY (${pkColumns.map(c => c.name).join(', ')})`;
+            let sql = `CREATE TABLE`;
+            if (options === null || options === void 0 ? void 0 : options.ifNotExists)
+                sql += ' IF NOT EXISTS';
+            sql += ` ${this.escapeIdentifier(definition.name)} (${columnDefs}, ${primaryKeyDef})`;
+            await this.cassandraClient.execute(sql);
+            // Create indexes
+            if (definition.indexes) {
+                for (const index of definition.indexes) {
+                    await this.createIndex(index);
+                }
+            }
+        }
+        catch (error) {
+            throw database_error_1.DatabaseError.schemaError(`Failed to create table: ${error.message}`, error);
+        }
+    }
+    async alterTable(tableName, operations) {
+        this.ensureConnected();
+        try {
+            for (const op of operations) {
+                let sql = `ALTER TABLE ${this.escapeIdentifier(tableName)}`;
+                switch (op.type) {
+                    case 'ADD':
+                        if (op.column) {
+                            sql += ` ADD ${op.column.name} ${this.getColumnTypeString(op.column.type, op.column)}`;
+                        }
+                        break;
+                    case 'DROP':
+                        if (op.columnName) {
+                            sql += ` DROP ${op.columnName}`;
+                        }
+                        break;
+                    case 'RENAME':
+                        if (op.oldName && op.newName) {
+                            sql += ` RENAME ${op.oldName} TO ${op.newName}`;
+                        }
+                        break;
+                    case 'MODIFY':
+                        throw new database_error_1.DatabaseError('Cassandra does not support modifying column types. Drop and recreate the column instead.', enums_1.DatabaseErrorType.NOT_SUPPORTED);
+                }
+                await this.cassandraClient.execute(sql);
+            }
+        }
+        catch (error) {
+            throw database_error_1.DatabaseError.schemaError(`Failed to alter table: ${error.message}`, error);
+        }
+    }
+    async dropTable(tableName, ifExists, cascade) {
+        this.ensureConnected();
+        try {
+            let sql = 'DROP TABLE';
+            if (ifExists)
+                sql += ' IF EXISTS';
+            sql += ` ${this.escapeIdentifier(tableName)}`;
+            await this.cassandraClient.execute(sql);
+        }
+        catch (error) {
+            throw database_error_1.DatabaseError.schemaError(`Failed to drop table: ${error.message}`, error);
+        }
+    }
+    async listTables() {
+        this.ensureConnected();
+        try {
+            const result = await this.cassandraClient.execute(`SELECT table_name FROM system_schema.tables WHERE keyspace_name = ?`, [this.keyspace]);
+            return result.rows.map((r) => r.table_name);
+        }
+        catch (error) {
+            throw database_error_1.DatabaseError.schemaError(`Failed to list tables: ${error.message}`, error);
+        }
+    }
+    async tableExists(tableName) {
+        this.ensureConnected();
+        try {
+            const result = await this.cassandraClient.execute(`SELECT table_name FROM system_schema.tables WHERE keyspace_name = ? AND table_name = ?`, [this.keyspace, tableName]);
+            return result.rows.length > 0;
+        }
+        catch (error) {
+            throw database_error_1.DatabaseError.schemaError(`Failed to check table existence: ${error.message}`, error);
+        }
+    }
+    async getTableSchema(tableName) {
+        this.ensureConnected();
+        try {
+            // Get columns
+            const columnsResult = await this.cassandraClient.execute(`SELECT column_name, type, kind FROM system_schema.columns WHERE keyspace_name = ? AND table_name = ?`, [this.keyspace, tableName]);
+            const columns = columnsResult.rows.map((row) => ({
+                name: row.column_name,
+                type: row.type,
+                nullable: true,
+                isPrimaryKey: row.kind === 'partition_key' || row.kind === 'clustering',
+                isUnique: false,
+                isAutoIncrement: false,
+            }));
+            // Get indexes
+            const indexes = await this.listIndexes(tableName);
+            // Get primary key
+            const primaryKey = columns
+                .filter(c => c.isPrimaryKey)
+                .map(c => c.name);
+            return {
+                name: tableName,
+                schema: this.keyspace,
+                columns,
+                indexes,
+                constraints: [],
+                primaryKey,
+            };
+        }
+        catch (error) {
+            throw database_error_1.DatabaseError.schemaError(`Failed to get table schema: ${error.message}`, error);
+        }
+    }
+    async createIndex(index, ifNotExists, concurrent) {
+        this.ensureConnected();
+        try {
+            // Cassandra supports secondary indexes on single columns
+            if (index.columns.length !== 1) {
+                throw new database_error_1.DatabaseError('Cassandra only supports single-column secondary indexes', enums_1.DatabaseErrorType.NOT_SUPPORTED);
+            }
+            let sql = 'CREATE INDEX';
+            if (ifNotExists)
+                sql += ' IF NOT EXISTS';
+            sql += ` ${index.name} ON ${this.escapeIdentifier(index.table)} (${index.columns[0].name})`;
+            await this.cassandraClient.execute(sql);
+        }
+        catch (error) {
+            throw database_error_1.DatabaseError.schemaError(`Failed to create index: ${error.message}`, error);
+        }
+    }
+    async dropIndex(tableName, indexName, ifExists, concurrent, cascade) {
+        this.ensureConnected();
+        try {
+            let sql = 'DROP INDEX';
+            if (ifExists)
+                sql += ' IF EXISTS';
+            sql += ` ${indexName}`;
+            await this.cassandraClient.execute(sql);
+        }
+        catch (error) {
+            throw database_error_1.DatabaseError.schemaError(`Failed to drop index: ${error.message}`, error);
+        }
+    }
+    async listIndexes(tableName, includeSystem) {
+        this.ensureConnected();
+        try {
+            const result = await this.cassandraClient.execute(`SELECT index_name, options FROM system_schema.indexes WHERE keyspace_name = ? AND table_name = ?`, [this.keyspace, tableName]);
+            return result.rows.map((row) => {
+                var _a;
+                return ({
+                    name: row.index_name,
+                    table: tableName,
+                    columns: [((_a = row.options) === null || _a === void 0 ? void 0 : _a.target) || ''],
+                    unique: false,
+                    primaryKey: false,
+                    type: 'SECONDARY',
+                });
+            });
+        }
+        catch (error) {
+            throw database_error_1.DatabaseError.schemaError(`Failed to list indexes: ${error.message}`, error);
+        }
+    }
+    async getIndexStatistics(tableName, indexName) {
+        // Cassandra doesn't provide detailed index statistics via CQL
+        return [];
+    }
+    // ==================== UTILITY METHODS ====================
+    escapeIdentifier(identifier) {
+        // Cassandra uses double quotes for identifiers with special chars
+        if (/[^a-zA-Z0-9_]/.test(identifier)) {
+            return `"${identifier.replace(/"/g, '""')}"`;
+        }
+        return identifier;
+    }
+    escapeValue(value) {
+        if (value === null || value === undefined) {
+            return 'NULL';
+        }
+        if (typeof value === 'number') {
+            return String(value);
+        }
+        if (typeof value === 'boolean') {
+            return value ? 'true' : 'false';
+        }
+        if (value instanceof Date) {
+            return `'${value.toISOString()}'`;
+        }
+        if (typeof value === 'object') {
+            return `'${JSON.stringify(value).replace(/'/g, "''")}'`;
+        }
+        return `'${String(value).replace(/'/g, "''")}'`;
+    }
+    /**
+     * Check if value is an update operator object
+     * Supports both lowercase (new) and uppercase (legacy) operators
+     */
+    isUpdateOperator(value) {
+        if (!value || typeof value !== 'object')
+            return false;
+        // Support both lowercase (Mongoose style) and uppercase (legacy) operators
+        const operators = [
+            '$inc', '$INC', '$dec', '$DEC', '$mul', '$MUL', '$min', '$MIN', '$max', '$MAX',
+            '$set', '$SET', '$unset', '$UNSET', '$push', '$PUSH', '$pull', '$PULL',
+            '$addToSet', '$ADDTOSET', '$currentDate', '$CURRENTDATE'
+        ];
+        return operators.some(op => op in value);
+    }
+    getParameterPlaceholder(index) {
+        return '?';
+    }
+    getColumnTypeString(columnType, options) {
+        const typeMap = {
+            [enums_1.ColumnType.INTEGER]: 'int',
+            [enums_1.ColumnType.BIGINT]: 'bigint',
+            [enums_1.ColumnType.SMALLINT]: 'smallint',
+            [enums_1.ColumnType.TINYINT]: 'tinyint',
+            [enums_1.ColumnType.FLOAT]: 'float',
+            [enums_1.ColumnType.DOUBLE]: 'double',
+            [enums_1.ColumnType.DECIMAL]: 'decimal',
+            [enums_1.ColumnType.STRING]: 'text',
+            [enums_1.ColumnType.TEXT]: 'text',
+            [enums_1.ColumnType.VARCHAR]: 'varchar',
+            [enums_1.ColumnType.BOOLEAN]: 'boolean',
+            [enums_1.ColumnType.DATE]: 'date',
+            [enums_1.ColumnType.TIME]: 'time',
+            [enums_1.ColumnType.DATETIME]: 'timestamp',
+            [enums_1.ColumnType.TIMESTAMP]: 'timestamp',
+            [enums_1.ColumnType.UUID]: 'uuid',
+            [enums_1.ColumnType.TIMEUUID]: 'timeuuid',
+            [enums_1.ColumnType.BINARY]: 'blob',
+            [enums_1.ColumnType.BLOB]: 'blob',
+            [enums_1.ColumnType.COUNTER]: 'counter',
+            [enums_1.ColumnType.VARINT]: 'varint',
+            [enums_1.ColumnType.INET]: 'inet',
+        };
+        return typeMap[columnType] || columnType.toLowerCase();
+    }
+    getSupportedFeatures() {
+        return [
+            base_adapter_1.DatabaseFeature.TTL,
+            base_adapter_1.DatabaseFeature.SECONDARY_INDEXES,
+            base_adapter_1.DatabaseFeature.BATCH_OPERATIONS,
+            base_adapter_1.DatabaseFeature.ATOMIC_COUNTERS,
+            base_adapter_1.DatabaseFeature.UUID,
+        ];
+    }
+    parseError(error) {
+        var _a, _b, _c, _d;
+        const code = error.code;
+        let type = enums_1.DatabaseErrorType.UNKNOWN_ERROR;
+        // Map Cassandra error codes
+        if (error.name === 'NoHostAvailableError') {
+            type = enums_1.DatabaseErrorType.CONNECTION_ERROR;
+        }
+        else if (error.name === 'AuthenticationError') {
+            type = enums_1.DatabaseErrorType.AUTHENTICATION_ERROR;
+        }
+        else if (((_a = error.message) === null || _a === void 0 ? void 0 : _a.includes('Keyspace')) && ((_b = error.message) === null || _b === void 0 ? void 0 : _b.includes('does not exist'))) {
+            type = enums_1.DatabaseErrorType.NOT_FOUND;
+        }
+        else if ((_c = error.message) === null || _c === void 0 ? void 0 : _c.includes('already exists')) {
+            type = enums_1.DatabaseErrorType.UNIQUE_VIOLATION;
+        }
+        else if ((_d = error.message) === null || _d === void 0 ? void 0 : _d.includes('syntax error')) {
+            type = enums_1.DatabaseErrorType.QUERY_ERROR;
+        }
+        return {
+            type,
+            message: error.message || 'Unknown database error',
+            code,
+        };
+    }
+    // ==================== PRIVATE HELPER METHODS ====================
+    ensureConnected() {
+        if (!this.connected || !this.cassandraClient) {
+            throw new database_error_1.DatabaseError('Not connected to Cassandra', enums_1.DatabaseErrorType.CONNECTION_ERROR);
+        }
+    }
+    async getClusterVersion() {
+        var _a;
+        try {
+            const result = await this.cassandraClient.execute('SELECT release_version FROM system.local');
+            return ((_a = result.rows[0]) === null || _a === void 0 ? void 0 : _a.release_version) || 'unknown';
+        }
+        catch (_b) {
+            return 'unknown';
+        }
+    }
+    buildWhereClause(where) {
+        const clauses = [];
+        const params = [];
+        for (const [key, value] of Object.entries(where)) {
+            // Normalize key to lowercase for logical operators (support both cases for backwards compatibility)
+            const normalizedKey = key.toLowerCase();
+            if (normalizedKey === '$and') {
+                const conditions = Array.isArray(value) ? value : [value];
+                const andClauses = [];
+                for (const cond of conditions) {
+                    const andResult = this.buildWhereClause(cond);
+                    andClauses.push(andResult.whereClause);
+                    params.push(...andResult.whereParams);
+                }
+                clauses.push(`(${andClauses.join(' AND ')})`);
+            }
+            else if (normalizedKey === '$or') {
+                // Note: Cassandra has limited OR support - only within the same partition key
+                // This will generate the OR clause but may fail at runtime if not on partition key
+                const conditions = Array.isArray(value) ? value : Object.entries(value).map(([k, v]) => ({ [k]: v }));
+                const orClauses = [];
+                for (const cond of conditions) {
+                    const orResult = this.buildWhereClause(cond);
+                    orClauses.push(orResult.whereClause);
+                    params.push(...orResult.whereParams);
+                }
+                clauses.push(`(${orClauses.join(' OR ')})`);
+            }
+            else if (value !== null && typeof value === 'object' && !Array.isArray(value) && !(value instanceof Date)) {
+                for (const [op, opValue] of Object.entries(value)) {
+                    const escapedKey = this.escapeIdentifier(key);
+                    // Normalize operator to lowercase (support both cases for backwards compatibility)
+                    const normalizedOp = op.toLowerCase();
+                    switch (normalizedOp) {
+                        case '$eq':
+                            clauses.push(`${escapedKey} = ?`);
+                            params.push(opValue);
+                            break;
+                        case '$ne':
+                            clauses.push(`${escapedKey} != ?`);
+                            params.push(opValue);
+                            break;
+                        case '$gt':
+                            clauses.push(`${escapedKey} > ?`);
+                            params.push(opValue);
+                            break;
+                        case '$gte':
+                            clauses.push(`${escapedKey} >= ?`);
+                            params.push(opValue);
+                            break;
+                        case '$lt':
+                            clauses.push(`${escapedKey} < ?`);
+                            params.push(opValue);
+                            break;
+                        case '$lte':
+                            clauses.push(`${escapedKey} <= ?`);
+                            params.push(opValue);
+                            break;
+                        case '$in':
+                            clauses.push(`${escapedKey} IN ?`);
+                            params.push(opValue);
+                            break;
+                        case '$nin':
+                        case '$not_in':
+                            // Cassandra doesn't support NOT IN or multiple != conditions in WHERE clause
+                            // Throw an explicit error to prevent silent failures
+                            throw new database_error_1.DatabaseError(`$nin operator is not supported in Cassandra. ` +
+                                `Cassandra does not allow multiple inequality conditions on the same column. ` +
+                                `Consider filtering results client-side or restructuring your query.`, enums_1.DatabaseErrorType.QUERY_ERROR);
+                        case '$like':
+                            // Cassandra uses LIKE with SASI indexes or CONTAINS for collections
+                            clauses.push(`${escapedKey} LIKE ?`);
+                            params.push(opValue);
+                            break;
+                        case '$isnull':
+                        case '$is_null':
+                            // Cassandra doesn't have IS NULL syntax, use = null
+                            if (opValue) {
+                                clauses.push(`${escapedKey} = null`);
+                            }
+                            break;
+                        case '$isnotnull':
+                        case '$is_not_null':
+                            // Cassandra doesn't have IS NOT NULL, use != null
+                            if (opValue) {
+                                clauses.push(`${escapedKey} != null`);
+                            }
+                            break;
+                        case '$contains':
+                            clauses.push(`${escapedKey} CONTAINS ?`);
+                            params.push(opValue);
+                            break;
+                        case '$contains_key':
+                            // For map types in Cassandra
+                            clauses.push(`${escapedKey} CONTAINS KEY ?`);
+                            params.push(opValue);
+                            break;
+                        case '$exists':
+                            if (opValue) {
+                                clauses.push(`${escapedKey} != null`);
+                            }
+                            else {
+                                clauses.push(`${escapedKey} = null`);
+                            }
+                            break;
+                    }
+                }
+            }
+            else {
+                clauses.push(`${this.escapeIdentifier(key)} = ?`);
+                params.push(value);
+            }
+        }
+        return {
+            whereClause: clauses.join(' AND '),
+            whereParams: params,
+        };
+    }
+    buildColumnDefinition(column) {
+        return `${column.name} ${this.getColumnTypeString(column.type, column)}`;
+    }
+}
+exports.CassandraAdapter = CassandraAdapter;
+//# sourceMappingURL=cassandra.adapter.js.map