fluxor-cloud-db 1.0.0

package/src/dynamo/dynamo.ts

@@ -0,0 +1,859 @@
+import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
+import { Service } from "fluxor-cloud";
+import { DynamoConfig } from "./dynamo.types";
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import {
+    GetCommand,
+    QueryCommand,
+    ScanCommand,
+    PutCommand,
+    BatchWriteCommand,
+    UpdateCommand,
+    DeleteCommand
+} from "@aws-sdk/lib-dynamodb";
+import { DatabaseAdapter } from "../contracts/database-adapter";
+import { DatabaseAdapterError } from "../types/error";
+import { WhereClause, QueryOptions, PaginatedResult, BatchResult, UpdateClause, QueryOperator } from "../types/query";
+
+// Source: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ReservedWords.html
+const RESERVED_KEYWORDS = new Set([
+    'ABORT', 'ABSOLUTE', 'ACTION', 'ADD', 'AFTER', 'AGENT', 'ALL', 'ALLOCATE', 'ALTER', 'ANALYZE',
+    'AND', 'ANY', 'ARCHIVE', 'ARE', 'ARRAY', 'AS', 'ASC', 'ASCII', 'ASENSITIVE', 'ASSERTION',
+    'ASYMMETRIC', 'AT', 'ATOMIC', 'ATTACH', 'ATTRIBUTE', 'AUTH', 'AUTHORIZATION', 'AUTHORIZE',
+    'AUTO', 'AVG', 'BACK', 'BACKUP', 'BASE', 'BATCH', 'BEFORE', 'BEGIN', 'BETWEEN', 'BIGINT',
+    'BINARY', 'BIT', 'BLOB', 'BLOCK', 'BOOLEAN', 'BOTH', 'BREADTH', 'BUCKET', 'BULK', 'BY',
+    'CALL', 'CALLED', 'CALLING', 'CAPACITY', 'CASCADE', 'CASCADED', 'CASE', 'CAST', 'CATALOG',
+    'CHAR', 'CHARACTER', 'CHECK', 'CLASS', 'CLOB', 'CLOSE', 'CLUSTER', 'CLUSTERED', 'CLUSTERING',
+    'CLUSTERS', 'COALESCE', 'COLLATE', 'COLLATION', 'COLLECTION', 'COLUMN', 'COLUMNS', 'COMBINE',
+    'COMMENT', 'COMMIT', 'COMPACT', 'COMPILE', 'COMPRESS', 'CONDITION', 'CONFLICT', 'CONNECT',
+    'CONNECTION', 'CONSISTENCY', 'CONSISTENT', 'CONSTRAINT', 'CONSTRAINTS', 'CONSTRUCTOR',
+    'CONSUMED', 'CONTINUE', 'CONVERT', 'COPY', 'CORRESPONDING', 'COUNT', 'COUNTER', 'CREATE',
+    'CROSS', 'CUBE', 'CURRENT', 'CURSOR', 'CYCLE', 'DATA', 'DATABASE', 'DATE', 'DATETIME',
+    'DAY', 'DEALLOCATE', 'DEC', 'DECIMAL', 'DECLARE', 'DEFAULT', 'DEFERRABLE', 'DEFERRED',
+    'DEFINE', 'DEFINED', 'DEFINITION', 'DELETE', 'DELIMITED', 'DEPTH', 'DEREF', 'DESC',
+    'DESCRIBE', 'DESCRIPTOR', 'DETACH', 'DETERMINISTIC', 'DIAGNOSTICS', 'DIRECTORIES', 'DISABLE',
+    'DISCONNECT', 'DISTINCT', 'DISTRIBUTE', 'DO', 'DOMAIN', 'DOUBLE', 'DROP', 'DUMP', 'DURATION',
+    'DYNAMIC', 'EACH', 'ELEMENT', 'ELSE', 'ELSEIF', 'EMPTY', 'ENABLE', 'END', 'EQUAL', 'EQUALS',
+    'ERROR', 'ESCAPE', 'EVALUATED', 'EXCEPT', 'EXCEPTION', 'EXCEPTIONS', 'EXCLUSIVE', 'EXEC',
+    'EXECUTE', 'EXISTS', 'EXIT', 'EXPLAIN', 'EXPLODE', 'EXPORT', 'EXPRESSION', 'EXTENDED',
+    'EXTERNAL', 'EXTRACT', 'FAIL', 'FALSE', 'FAMILY', 'FETCH', 'FIELDS', 'FILE', 'FILTER',
+    'FILTERING', 'FINAL', 'FINISH', 'FIRST', 'FIXED', 'FLATTERN', 'FLOAT', 'FOR', 'FORCE',
+    'FOREIGN', 'FORMAT', 'FORWARD', 'FOUND', 'FREE', 'FROM', 'FULL', 'FUNCTION', 'FUNCTIONS',
+    'GENERAL', 'GENERATE', 'GET', 'GLOB', 'GO', 'GOTO', 'GRANT', 'GREATER', 'GROUP', 'GROUPING',
+    'HANDLER', 'HASH', 'HAVE', 'HAVING', 'HEAP', 'HIDDEN', 'HOLD', 'HOUR', 'IDENTIFIED', 'IF',
+    'IGNORE', 'IMMEDIATE', 'IMPORT', 'IN', 'INCLUDING', 'INCLUSIVE', 'INCREMENT', 'INDETERMINATE',
+    'INDEX', 'INDEXED', 'INDEXES', 'INDICATOR', 'INFINITE', 'INITIALLY', 'INLINE', 'INNER',
+    'INNTER', 'INOUT', 'INPUT', 'INSENSITIVE', 'INSERT', 'INSTEAD', 'INT', 'INTEGER', 'INTERSECT',
+    'INTERVAL', 'INTO', 'INVALIDATE', 'IS', 'ISOLATION', 'ITEM', 'ITEMS', 'ITERATE', 'JOIN',
+    'KEY', 'KEYS', 'LAG', 'LANGUAGE', 'LARGE', 'LAST', 'LATERAL', 'LEAD', 'LEADING', 'LEAVE',
+    'LEFT', 'LENGTH', 'LESS', 'LEVEL', 'LIKE', 'LIMIT', 'LIST', 'LOAD', 'LOCAL', 'LOCALTIME',
+    'LOCALTIMESTAMP', 'LOCATION', 'LOCATOR', 'LOCK', 'LOCKS', 'LOG', 'LOGED', 'LONG', 'LOOP',
+    'LOWER', 'MAP', 'MATCH', 'MATERIALIZED', 'MAX', 'MAXLEN', 'MEMBER', 'MERGE', 'METHOD', 'MIN',
+    'MINUS', 'MINUTE', 'MISSING', 'MOD', 'MODE', 'MODIFIES', 'MODIFY', 'MODULE', 'MONTH',
+    'MULTI', 'MULTISET', 'NAME', 'NAMES', 'NATIONAL', 'NATURAL', 'NCHAR', 'NCLOB', 'NEW',
+    'NEXT', 'NO', 'NONE', 'NOT', 'NULL', 'NULLIF', 'NUMBER', 'NUMERIC', 'OBJECT', 'OF', 'OFFLINE',
+    'OFFSET', 'OLD', 'ON', 'ONLINE', 'ONLY', 'OPEN', 'OPTION', 'OR', 'ORDER', 'ORDINALITY',
+    'OUT', 'OUTER', 'OUTPUT', 'OVER', 'OVERLAPS', 'OVERRIDE', 'OWNER', 'PAD', 'PARALLEL',
+    'PARAMETER', 'PARAMETERS', 'PARTIAL', 'PARTITION', 'PARTITIONED', 'PARTITIONS', 'PATH',
+    'PERCENT', 'PERCENTILE', 'PERMISSION', 'PERMISSIONS', 'PIPE', 'PIPELINED', 'PLAN', 'POOL',
+    'POSITION', 'PRECISION', 'PREPARE', 'PRESERVE', 'PRIMARY', 'PRIOR', 'PRIVATE', 'PRIVILEGES',
+    'PROCEDURE', 'PROCESSED', 'PROJECT', 'PROJECTION', 'PROPERTY', 'PROVISIONING', 'PUBLIC',
+    'PUT', 'QUERY', 'QUIT', 'QUORUM', 'RAISE', 'RANDOM', 'RANGE', 'RANK', 'RAW', 'READ',
+    'READS', 'REAL', 'REBUILD', 'RECORD', 'RECURSIVE', 'REDUCE', 'REF', 'REFERENCE', 'REFERENCES',
+    'REFERENCING', 'REGEXP', 'REINDEX', 'RELATIVE', 'RELEASE', 'REMAINDER', 'RENAME', 'REPEAT',
+    'REPLACE', 'REQUEST', 'RESET', 'RESIGNAL', 'RESTRICT', 'RESULT', 'RETURN', 'RETURNING',
+    'RETURNS', 'REVERSE', 'REVOKE', 'RIGHT', 'ROLE', 'ROLES', 'ROLLBACK', 'ROLLUP', 'ROUTINE',
+    'ROW', 'ROWS', 'RULE', 'RULES', 'SAMPLE', 'SATISFIES', 'SAVE', 'SAVEPOINT', 'SCAN', 'SCHEMA',
+    'SCOPE', 'SCROLL', 'SEARCH', 'SECOND', 'SECTION', 'SEGMENT', 'SELECT', 'SELF', 'SEMI',
+    'SENSITIVE', 'SEPARATE', 'SEQUENCE', 'SERIALIZABLE', 'SESSION', 'SET', 'SETS', 'SHARD',
+    'SHARE', 'SHARED', 'SHORT', 'SHOW', 'SIGNAL', 'SIMILAR', 'SIZE', 'SKEWED', 'SOME', 'SOURCE',
+    'SPACE', 'SPACES', 'SPARSE', 'SPECIFIC', 'SPECIFICTYPE', 'SQL', 'SQLCODE', 'SQLERROR',
+    'SQLEXCEPTION', 'SQLSTATE', 'SQLWARNING', 'START', 'STATE', 'STATIC', 'STATUS', 'STORAGE',
+    'STORE', 'STORED', 'STREAM', 'STRING', 'STRUCT', 'STYLE', 'SUB', 'SUBMULTISET', 'SUBPARTITION',
+    'SUBSTRING', 'SUBTYPE', 'SUM', 'SUPER', 'SYMMETRIC', 'SYNONYM', 'SYSTEM', 'TABLE', 'TABLESAMPLE',
+    'TEMP', 'TEMPORARY', 'TERMINATED', 'TEXT', 'THAN', 'THEN', 'THROUGHPUT', 'TIME', 'TIMESTAMP',
+    'TIMEZONE', 'TINYINT', 'TO', 'TOKEN', 'TOTAL', 'TOUCH', 'TRAILING', 'TRANSACTION', 'TRANSFORM',
+    'TRANSLATE', 'TRANSLATION', 'TREAT', 'TRIGGER', 'TRIM', 'TRUE', 'TRUNCATE', 'TTL', 'TUPLE',
+    'TYPE', 'UNDER', 'UNDO', 'UNION', 'UNIQUE', 'UNIT', 'UNKNOWN', 'UNLOGGED', 'UNNEST', 'UNPROCESSED',
+    'UNSIGNED', 'UNTIL', 'UPDATE', 'UPPER', 'URL', 'USAGE', 'USE', 'USER', 'USERS', 'USING',
+    'UUID', 'VACUUM', 'VALUE', 'VALUED', 'VALUES', 'VARCHAR', 'VARIABLE', 'VARIANCE', 'VARINT',
+    'VARYING', 'VIEW', 'VIEWS', 'VIRTUAL', 'VOID', 'WAIT', 'WHEN', 'WHENEVER', 'WHERE', 'WHILE',
+    'WINDOW', 'WITH', 'WITHIN', 'WITHOUT', 'WORK', 'WRAPPED', 'WRITE', 'YEAR', 'ZONE',
+    // Common attribute names that often conflict
+    'NAME', 'STATUS', 'SCORE', 'PRICE', 'CATEGORY'
+]);
+
+@Service()
+export class DynamoService implements DatabaseAdapter {
+    private client: DynamoDBDocumentClient | undefined;
+    private dynamoDBClient: DynamoDBClient | undefined;
+    private isConnectedFlag = false;
+    private config: DynamoConfig | undefined;
+
+    public setConfig(config: DynamoConfig): void {
+        this.config = config;
+    }
+
+    connect(): Promise<void> {
+        if (!this.config) {
+            return Promise.reject(new DatabaseAdapterError(
+                "No configuration provided. Call setConfig() first.",
+                "INVALID_CONFIG"
+            ));
+        }
+
+        return Promise.resolve().then(() => {
+            try {
+                this.validateConfig(this.config!);
+
+                this.dynamoDBClient = new DynamoDBClient({
+                    region: this.config!.region,
+                    endpoint: this.config!.endpoint,
+                    credentials: this.config!.accessKeyId
+                        ? {
+                            accessKeyId: this.config!.accessKeyId,
+                            secretAccessKey: this.config!.secretAccessKey!
+                        }
+                        : undefined
+                });
+
+                this.client = DynamoDBDocumentClient.from(this.dynamoDBClient);
+                this.isConnectedFlag = true;
+            } catch (error) {
+                this.isConnectedFlag = false;
+
+                if (error instanceof DatabaseAdapterError) {
+                    throw error;
+                }
+
+                if (error instanceof Error) {
+                    throw new DatabaseAdapterError(
+                        `Failed to connect to DynamoDB: ${error.message}`,
+                        "CONNECTION_FAILED"
+                    );
+                }
+
+                throw new DatabaseAdapterError(
+                    "Failed to connect to DynamoDB: Unknown error",
+                    "CONNECTION_FAILED"
+                );
+            }
+        });
+    }
+
+    async disconnect(): Promise<void> {
+        try {
+            if (this.dynamoDBClient) {
+                this.dynamoDBClient.destroy();
+            }
+            this.isConnectedFlag = false;
+            this.client = undefined;
+            this.dynamoDBClient = undefined;
+        } catch (error) {
+            console.warn("Error disconnecting from DynamoDB:", error);
+            this.isConnectedFlag = false;
+            this.client = undefined;
+            this.dynamoDBClient = undefined;
+        }
+    }
+
+    isConnected(): boolean {
+        return this.isConnectedFlag && this.client !== undefined;
+    }
+
+    async healthCheck(): Promise<boolean> {
+        try {
+            const client = this.getClient();
+            await client.send(new ScanCommand({ TableName: "fake_table", Limit: 1 }));
+            return true;
+        } catch (error) {
+            if (error instanceof Error && error.message.includes("ResourceNotFoundException")) {
+                return true;
+            }
+            return false;
+        }
+    }
+
+    async selectOne<T = Record<string, any>>(
+        tableName: string,
+        where: WhereClause,
+        options?: QueryOptions
+    ): Promise<T | null> {
+        try {
+            const client = this.getClient();
+            const key = this.buildKey(where);
+
+            const params: any = {
+                TableName: tableName,
+                Key: key
+            };
+
+            if (options?.projection) {
+                const { projection, names } = this.buildProjection(options.projection);
+                params.ProjectionExpression = projection;
+                if (Object.keys(names).length > 0) {
+                    params.ExpressionAttributeNames = names;
+                }
+            }
+
+            const command = new GetCommand(params);
+            const result = await client.send(command);
+            return (result.Item as T) || null;
+        } catch (error) {
+            throw this.handleError(error, "selectOne");
+        }
+    }
+
+    async selectMany<T = Record<string, any>>(
+        tableName: string,
+        where?: WhereClause,
+        options?: QueryOptions
+    ): Promise<PaginatedResult<T>> {
+        try {
+            const client = this.getClient();
+            let command;
+            let items: T[] = [];
+            let scannedCount = 0;
+
+            // Check if where clause contains only key attributes
+            const isKeyQuery = where && this.isKeyQuery(where);
+
+            if (isKeyQuery) {
+                const { keyConditionExpression, expressionAttributeValues, names } = this.buildKeyConditionExpression(where!);
+
+                const params: any = {
+                    TableName: tableName,
+                    KeyConditionExpression: keyConditionExpression,
+                    ExpressionAttributeValues: expressionAttributeValues,
+                    Limit: options?.limit,
+                    ScanIndexForward: options?.orderBy?.[0]?.direction === "DESC" ? false : true,
+                    ConsistentRead: options?.consistent
+                };
+
+                if (Object.keys(names).length > 0) {
+                    params.ExpressionAttributeNames = names;
+                }
+
+                if (options?.projection) {
+                    const { projection, names: projNames } = this.buildProjection(options.projection);
+                    params.ProjectionExpression = projection;
+                    if (Object.keys(projNames).length > 0) {
+                        params.ExpressionAttributeNames = { ...params.ExpressionAttributeNames, ...projNames };
+                    }
+                }
+
+                command = new QueryCommand(params);
+            } else {
+                // Use Scan for non-key queries or no where clause
+                const params: any = {
+                    TableName: tableName,
+                    Limit: options?.limit
+                };
+
+                if (where && Object.keys(where).length > 0) {
+                    const { filterExpression, expressionAttributeValues, names } = this.buildFilterExpression(where);
+                    params.FilterExpression = filterExpression;
+                    params.ExpressionAttributeValues = expressionAttributeValues;
+                    if (Object.keys(names).length > 0) {
+                        params.ExpressionAttributeNames = names;
+                    }
+                }
+
+                if (options?.projection) {
+                    const { projection, names: projNames } = this.buildProjection(options.projection);
+                    params.ProjectionExpression = projection;
+                    if (Object.keys(projNames).length > 0) {
+                        params.ExpressionAttributeNames = { ...params.ExpressionAttributeNames, ...projNames };
+                    }
+                }
+
+                command = new ScanCommand(params);
+            }
+
+            const result = await client.send(command);
+            items = (result.Items as T[]) || [];
+            scannedCount = result.ScannedCount || 0;
+
+            // Apply client-side ordering (only meaningful for Scan; Query uses ScanIndexForward)
+            if (!isKeyQuery && options?.orderBy?.length) {
+                const { field, direction } = options.orderBy[0];
+                items = [...items].sort((a: any, b: any) => {
+                    if (a[field] < b[field]) return direction === "DESC" ? 1 : -1;
+                    if (a[field] > b[field]) return direction === "DESC" ? -1 : 1;
+                    return 0;
+                });
+            }
+
+            return {
+                items,
+                total: items.length,
+                hasMore: (result.LastEvaluatedKey !== undefined),
+                nextOffset: options?.offset ? options.offset + items.length : undefined
+            };
+        } catch (error) {
+            throw this.handleError(error, "selectMany");
+        }
+    }
+
+    async createOne<T = Record<string, any>>(
+        tableName: string,
+        data: Record<string, any>
+    ): Promise<T> {
+        try {
+            const client = this.getClient();
+
+            const command = new PutCommand({
+                TableName: tableName,
+                Item: data
+            });
+
+            await client.send(command);
+            return data as T;
+        } catch (error) {
+            throw this.handleError(error, "createOne");
+        }
+    }
+
+    async createMany<T = Record<string, any>>(
+        tableName: string,
+        data: Record<string, any>[],
+        options?: { stopOnError?: boolean }
+    ): Promise<{ items: T[]; result: BatchResult }> {
+        try {
+            if (!Array.isArray(data)) {
+                throw new DatabaseAdapterError(
+                    "createMany requires an array of records",
+                    "INVALID_INPUT"
+                );
+            }
+
+            const client = this.getClient();
+            const batchSize = 25;
+            let successful = 0;
+            let failed = 0;
+            const errors: { index: number; error: string }[] = [];
+            const items: T[] = [];
+
+            for (let i = 0; i < data.length; i += batchSize) {
+                const batch = data.slice(i, i + batchSize);
+                const requestItems = batch.map(item => ({
+                    PutRequest: { Item: item }
+                }));
+
+                try {
+                    const command = new BatchWriteCommand({
+                        RequestItems: {
+                            [tableName]: requestItems
+                        }
+                    });
+
+                    await client.send(command);
+                    successful += batch.length;
+                    items.push(...(batch as T[]));
+                } catch (error) {
+                    if (options?.stopOnError) {
+                        throw error;
+                    }
+                    failed += batch.length;
+                    batch.forEach((_, index) => {
+                        errors.push({
+                            index: i + index,
+                            error: error instanceof Error ? error.message : "Unknown error"
+                        });
+                    });
+                }
+            }
+
+            return {
+                items,
+                result: { successful, failed, errors: errors.length > 0 ? errors : undefined }
+            };
+        } catch (error) {
+            throw this.handleError(error, "createMany");
+        }
+    }
+
+    async updateOne<T = Record<string, any>>(
+        tableName: string,
+        update: UpdateClause,
+        where: WhereClause
+    ): Promise<T> {
+        try {
+            const client = this.getClient();
+            const key = this.buildKey(where);
+
+            // Verify the item exists before updating
+            const existing = await client.send(new GetCommand({ TableName: tableName, Key: key }));
+            if (!existing.Item) {
+                throw new DatabaseAdapterError(
+                    `Record not found`,
+                    "NOT_FOUND"
+                );
+            }
+
+            const { updateExpression, expressionAttributeValues, names } = this.buildUpdateExpression(update);
+
+            const params: any = {
+                TableName: tableName,
+                Key: key,
+                UpdateExpression: updateExpression,
+                ReturnValues: "ALL_NEW"
+            };
+
+            if (Object.keys(expressionAttributeValues).length > 0) {
+                params.ExpressionAttributeValues = expressionAttributeValues;
+            }
+
+            if (Object.keys(names).length > 0) {
+                params.ExpressionAttributeNames = names;
+            }
+
+            const command = new UpdateCommand(params);
+            const result = await client.send(command);
+            return result.Attributes as T;
+        } catch (error) {
+            throw this.handleError(error, "updateOne");
+        }
+    }
+
+    async updateMany<T = Record<string, any>>(
+        tableName: string,
+        update: UpdateClause,
+        where?: WhereClause,
+        options?: { limit?: number }
+    ): Promise<{ items: T[]; result: BatchResult }> {
+        try {
+            const selectResult = await this.selectMany(
+                tableName,
+                where,
+                { limit: options?.limit }
+            );
+
+            let successful = 0;
+            let failed = 0;
+            const errors: { index: number; error: string }[] = [];
+            const items: T[] = [];
+
+            for (let i = 0; i < selectResult.items.length; i++) {
+                try {
+                    const item = selectResult.items[i];
+                    const key = this.extractKey(item as Record<string, any>);
+                    const updated = await this.updateOne(tableName, update, key);
+                    successful++;
+                    items.push(updated as T);
+                } catch (error) {
+                    failed++;
+                    errors.push({
+                        index: i,
+                        error: error instanceof Error ? error.message : "Unknown error"
+                    });
+                }
+            }
+
+            return {
+                items,
+                result: { successful, failed, errors: errors.length > 0 ? errors : undefined }
+            };
+        } catch (error) {
+            throw this.handleError(error, "updateMany");
+        }
+    }
+
+    async deleteOne(
+        tableName: string,
+        where: WhereClause
+    ): Promise<{ success: boolean; deletedCount: number }> {
+        try {
+            const client = this.getClient();
+            const key = this.buildKey(where);
+
+            // Check if key exists first
+            const getResult = await client.send(new GetCommand({
+                TableName: tableName,
+                Key: key
+            }));
+
+            if (!getResult.Item) {
+                return { success: false, deletedCount: 0 };
+            }
+
+            const command = new DeleteCommand({
+                TableName: tableName,
+                Key: key
+            });
+
+            await client.send(command);
+            return { success: true, deletedCount: 1 };
+        } catch (error) {
+            throw this.handleError(error, "deleteOne");
+        }
+    }
+
+    async deleteMany(
+        tableName: string,
+        where?: WhereClause,
+        options?: { limit?: number }
+    ): Promise<{ success: boolean; deletedCount: number; result: BatchResult }> {
+        try {
+            const selectResult = await this.selectMany(
+                tableName,
+                where,
+                { limit: options?.limit }
+            );
+
+            let successful = 0;
+            let failed = 0;
+            const errors: { index: number; error: string }[] = [];
+
+            for (let i = 0; i < selectResult.items.length; i++) {
+                try {
+                    const item = selectResult.items[i];
+                    const key = this.extractKey(item as Record<string, any>);
+                    await this.deleteOne(tableName, key);
+                    successful++;
+                } catch (error) {
+                    failed++;
+                    errors.push({
+                        index: i,
+                        error: error instanceof Error ? error.message : "Unknown error"
+                    });
+                }
+            }
+
+            return {
+                success: failed === 0,
+                deletedCount: successful,
+                result: { successful, failed, errors: errors.length > 0 ? errors : undefined }
+            };
+        } catch (error) {
+            throw this.handleError(error, "deleteMany");
+        }
+    }
+
+    async executeRaw<T = any>(query: string, params?: Record<string, any>): Promise<T> {
+        throw new DatabaseAdapterError(
+            "executeRaw is not implemented for DynamoDB. Use native DynamoDB syntax instead.",
+            "NOT_IMPLEMENTED"
+        );
+    }
+
+    // ============ Private Helper Methods ============
+
+    private validateConfig(config: DynamoConfig): void {
+        if (!config) {
+            throw new DatabaseAdapterError(
+                "DynamoDB configuration is required",
+                "INVALID_CONFIG"
+            );
+        }
+
+        if (!config.region || config.region.trim() === "") {
+            throw new DatabaseAdapterError(
+                "DynamoDB region is required",
+                "MISSING_REGION"
+            );
+        }
+
+        if (config.accessKeyId && !config.secretAccessKey) {
+            throw new DatabaseAdapterError(
+                "secretAccessKey is required when accessKeyId is provided",
+                "INVALID_CREDENTIALS"
+            );
+        }
+
+        if (config.secretAccessKey && !config.accessKeyId) {
+            throw new DatabaseAdapterError(
+                "accessKeyId is required when secretAccessKey is provided",
+                "INVALID_CREDENTIALS"
+            );
+        }
+    }
+
+    private getClient(): DynamoDBDocumentClient {
+        if (!this.isConnectedFlag || !this.client) {
+            throw new DatabaseAdapterError(
+                "DynamoDB client is not connected. Call connect() first.",
+                "NOT_CONNECTED"
+            );
+        }
+
+        return this.client;
+    }
+
+    private buildKey(where: WhereClause): Record<string, any> {
+        const key: Record<string, any> = {};
+
+        for (const [field, condition] of Object.entries(where)) {
+            if (condition == null) {
+                continue;
+            }
+            if (typeof condition === "object" && "value" in condition) {
+                key[field] = condition.value;
+            } else {
+                key[field] = condition;
+            }
+        }
+
+        return key;
+    }
+
+    private extractKey(item: Record<string, any>): WhereClause {
+        return {
+            id: {
+                operator: "=",
+                value: item.id
+            }
+        };
+    }
+
+    private isKeyQuery(where: WhereClause): boolean {
+        // Only route to Query when filtering by 'id' with an operator supported by KeyConditionExpression.
+        // IN and NOT_IN are not valid in KeyConditionExpression — fall back to Scan for those.
+        return Object.keys(where).some(key => {
+            if (key !== 'id') return false;
+            const cond = (where as any)[key];
+            if (typeof cond === 'object' && 'operator' in cond) {
+                const unsupportedInKey = ['IN', 'NOT_IN'];
+                return !unsupportedInKey.includes(cond.operator);
+            }
+            return true;
+        });
+    }
+
+    private buildProjection(fields: string[]): { projection: string; names: Record<string, string> } {
+        const names: Record<string, string> = {};
+        const projectionParts: string[] = [];
+
+        for (const field of fields) {
+            if (RESERVED_KEYWORDS.has(field.toUpperCase())) {
+                const placeholder = `#${field}`;
+                names[placeholder] = field;
+                projectionParts.push(placeholder);
+            } else {
+                projectionParts.push(field);
+            }
+        }
+
+        return {
+            projection: projectionParts.join(", "),
+            names
+        };
+    }
+
+    private buildKeyConditionExpression(where: WhereClause): {
+        keyConditionExpression: string;
+        expressionAttributeValues: Record<string, any>;
+        names: Record<string, string>;
+    } {
+        const parts: string[] = [];
+        const values: Record<string, any> = {};
+        const names: Record<string, string> = {};
+        let valueIndex = 0;
+
+        for (const [field, condition] of Object.entries(where)) {
+            const valueKey = `:val${valueIndex}`;
+            const cond = condition as any;
+            const fieldPlaceholder = RESERVED_KEYWORDS.has(field.toUpperCase()) ? `#${field}` : field;
+
+            if (RESERVED_KEYWORDS.has(field.toUpperCase())) {
+                names[fieldPlaceholder] = field;
+            }
+
+            if (typeof cond === "object" && "operator" in cond) {
+                const operator = cond.operator as QueryOperator;
+
+                switch (operator) {
+                    case "=":
+                        parts.push(`${fieldPlaceholder} = ${valueKey}`);
+                        values[valueKey] = cond.value;
+                        break;
+                    case "!=":
+                        parts.push(`${fieldPlaceholder} <> ${valueKey}`);
+                        values[valueKey] = cond.value;
+                        break;
+                    case ">":
+                        parts.push(`${fieldPlaceholder} > ${valueKey}`);
+                        values[valueKey] = cond.value;
+                        break;
+                    case ">=":
+                        parts.push(`${fieldPlaceholder} >= ${valueKey}`);
+                        values[valueKey] = cond.value;
+                        break;
+                    case "<":
+                        parts.push(`${fieldPlaceholder} < ${valueKey}`);
+                        values[valueKey] = cond.value;
+                        break;
+                    case "<=":
+                        parts.push(`${fieldPlaceholder} <= ${valueKey}`);
+                        values[valueKey] = cond.value;
+                        break;
+                    case "BEGINS_WITH":
+                        parts.push(`begins_with(${fieldPlaceholder}, ${valueKey})`);
+                        values[valueKey] = cond.value;
+                        break;
+                    case "IN":
+                        const inValues = (cond.value as any[]).map((v, i) => `:inval${valueIndex}_${i}`);
+                        (cond.value as any[]).forEach((v, i) => {
+                            values[`:inval${valueIndex}_${i}`] = v;
+                        });
+                        parts.push(`${fieldPlaceholder} IN (${inValues.join(", ")})`);
+                        valueIndex += cond.value.length - 1;
+                        break;
+                    default:
+                        throw new DatabaseAdapterError(
+                            `Unsupported operator: ${operator}`,
+                            "UNSUPPORTED_OPERATOR"
+                        );
+                }
+            } else {
+                parts.push(`${fieldPlaceholder} = ${valueKey}`);
+                values[valueKey] = cond;
+            }
+
+            valueIndex++;
+        }
+
+        return {
+            keyConditionExpression: parts.join(" AND "),
+            expressionAttributeValues: Object.keys(values).length > 0 ? values : {},
+            names
+        };
+    }
+
+    private buildFilterExpression(where: WhereClause): {
+        filterExpression: string;
+        expressionAttributeValues: Record<string, any>;
+        names: Record<string, string>;
+    } {
+        const parts: string[] = [];
+        const values: Record<string, any> = {};
+        const names: Record<string, string> = {};
+        let valueIndex = 0;
+
+        for (const [field, condition] of Object.entries(where)) {
+            const valueKey = `:val${valueIndex}`;
+            const cond = condition as any;
+            const fieldPlaceholder = RESERVED_KEYWORDS.has(field.toUpperCase()) ? `#${field}` : field;
+
+            if (RESERVED_KEYWORDS.has(field.toUpperCase())) {
+                names[fieldPlaceholder] = field;
+            }
+
+            if (typeof cond === "object" && "operator" in cond) {
+                const operator = cond.operator as QueryOperator;
+
+                switch (operator) {
+                    case "=":
+                        parts.push(`${fieldPlaceholder} = ${valueKey}`);
+                        values[valueKey] = cond.value;
+                        break;
+                    case "!=":
+                        parts.push(`${fieldPlaceholder} <> ${valueKey}`);
+                        values[valueKey] = cond.value;
+                        break;
+                    case ">":
+                        parts.push(`${fieldPlaceholder} > ${valueKey}`);
+                        values[valueKey] = cond.value;
+                        break;
+                    case ">=":
+                        parts.push(`${fieldPlaceholder} >= ${valueKey}`);
+                        values[valueKey] = cond.value;
+                        break;
+                    case "<":
+                        parts.push(`${fieldPlaceholder} < ${valueKey}`);
+                        values[valueKey] = cond.value;
+                        break;
+                    case "<=":
+                        parts.push(`${fieldPlaceholder} <= ${valueKey}`);
+                        values[valueKey] = cond.value;
+                        break;
+                    case "BEGINS_WITH":
+                        parts.push(`begins_with(${fieldPlaceholder}, ${valueKey})`);
+                        values[valueKey] = cond.value;
+                        break;
+                    case "IN":
+                        const inValues = (cond.value as any[]).map((v, i) => `:inval${valueIndex}_${i}`);
+                        (cond.value as any[]).forEach((v, i) => {
+                            values[`:inval${valueIndex}_${i}`] = v;
+                        });
+                        parts.push(`${fieldPlaceholder} IN (${inValues.join(", ")})`);
+                        valueIndex += cond.value.length - 1;
+                        break;
+                    case "NOT_IN":
+                        const notInValues = (cond.value as any[]).map((v, i) => `:notinval${valueIndex}_${i}`);
+                        (cond.value as any[]).forEach((v, i) => {
+                            values[`:notinval${valueIndex}_${i}`] = v;
+                        });
+                        parts.push(`NOT ${fieldPlaceholder} IN (${notInValues.join(", ")})`);
+                        valueIndex += cond.value.length - 1;
+                        break;
+                    default:
+                        throw new DatabaseAdapterError(
+                            `Unsupported operator: ${operator}`,
+                            "UNSUPPORTED_OPERATOR"
+                        );
+                }
+            } else {
+                parts.push(`${fieldPlaceholder} = ${valueKey}`);
+                values[valueKey] = cond;
+            }
+
+            valueIndex++;
+        }
+
+        return {
+            filterExpression: parts.join(" AND "),
+            expressionAttributeValues: Object.keys(values).length > 0 ? values : {},
+            names
+        };
+    }
+
+    private buildUpdateExpression(update: UpdateClause): {
+        updateExpression: string;
+        expressionAttributeValues: Record<string, any>;
+        names: Record<string, string>;
+    } {
+        const setParts: string[] = [];
+        const values: Record<string, any> = {};
+        const names: Record<string, string> = {};
+        let valueIndex = 0;
+
+        for (const [field, value] of Object.entries(update)) {
+            const valueKey = `:val${valueIndex}`;
+            const fieldPlaceholder = RESERVED_KEYWORDS.has(field.toUpperCase()) ? `#${field}` : field;
+
+            if (RESERVED_KEYWORDS.has(field.toUpperCase())) {
+                names[fieldPlaceholder] = field;
+            }
+
+            setParts.push(`${fieldPlaceholder} = ${valueKey}`);
+            values[valueKey] = value;
+            valueIndex++;
+        }
+
+        return {
+            updateExpression: `SET ${setParts.join(", ")}`,
+            expressionAttributeValues: Object.keys(values).length > 0 ? values : {},
+            names
+        };
+    }
+
+    private handleError(error: unknown, operation: string): DatabaseAdapterError {
+        if (error instanceof DatabaseAdapterError) {
+            return error;
+        }
+
+        if (error instanceof Error) {
+            return new DatabaseAdapterError(
+                `${operation} failed: ${error.message}`,
+                "OPERATION_FAILED",
+                { originalError: error.message }
+            );
+        }
+
+        return new DatabaseAdapterError(
+            `${operation} failed: Unknown error`,
+            "OPERATION_FAILED"
+        );
+    }
+}