fluxor-cloud-db 1.0.0

package/src/types/query.ts

@@ -0,0 +1,53 @@
+export type QueryOperator = "=" | "!=" | ">" | ">=" | "<" | "<=" | "IN" | "NOT_IN" | "BETWEEN" | "LIKE" | "EXISTS" | "BEGINS_WITH";
+
+/**
+ * Represents a single condition in a WHERE clause
+ */
+export interface QueryCondition {
+    operator: QueryOperator;
+    value: any;
+}
+
+/**
+ * Represents a single field condition or nested conditions
+ */
+export interface WhereClause {
+    [key: string]: QueryCondition | QueryCondition[] | WhereClause;
+}
+
+/**
+ * Represents update operations on specific fields
+ */
+export interface UpdateClause {
+    [key: string]: any;
+}
+
+/**
+ * Configuration for query operations
+ */
+export interface QueryOptions {
+    limit?: number;
+    offset?: number;
+    orderBy?: { field: string; direction: "ASC" | "DESC" }[];
+    projection?: string[]; // Select specific fields
+    consistent?: boolean; // For databases that support consistency levels
+}
+
+/**
+ * Result wrapper for paginated responses
+ */
+export type PaginatedResult<T> = {
+    items: T[];
+    total: number;
+    hasMore: boolean;
+    nextOffset?: number;
+}
+
+/**
+ * Result wrapper for batch operations
+ */
+export interface BatchResult {
+    successful: number;
+    failed: number;
+    errors?: { index: number; error: string }[];
+}

package/tests/dynamodb.test.ts

@@ -0,0 +1,547 @@
+import { DynamoService } from "../src/dynamo/dynamo";
+import { DatabaseAdapterError } from "../src/types/error";
+import { DynamoConfig } from "../src/dynamo/dynamo.types";
+import { CreateTableCommand, DeleteTableCommand, DynamoDBClient, DynamoDBClientConfig } from "@aws-sdk/client-dynamodb";
+
+/**
+ * DynamoDB Unit Tests using LocalStack
+ * Requires LocalStack running on localhost:4566
+ */
+describe("DynamoService", () => {
+    let service: DynamoService;
+    let tableManagementClient: DynamoDBClient;
+    const tableName = "test_table";
+
+    const config: DynamoConfig = {
+        region: "us-east-1",
+        endpoint: "http://localhost:4566",
+        accessKeyId: "test",
+        secretAccessKey: "test"
+    };
+
+    beforeAll(async () => {
+        // Service manages its own connection
+        service = new DynamoService();
+        service.setConfig(config);
+        await service.connect();
+
+        // Separate client only for table management
+        tableManagementClient = new DynamoDBClient({
+            region: config.region,
+            endpoint: config.endpoint,
+            credentials: {
+                accessKeyId: config.accessKeyId,
+                secretAccessKey: config.secretAccessKey
+            }
+        } as DynamoDBClientConfig);
+
+        // Create table once for all tests
+        try {
+            await tableManagementClient.send(new DeleteTableCommand({ TableName: tableName }));
+            await new Promise(resolve => setTimeout(resolve, 1000));
+        } catch (error) {
+            // Ignore if table doesn't exist
+        }
+
+        await tableManagementClient.send(
+            new CreateTableCommand({
+                TableName: tableName,
+                KeySchema: [{ AttributeName: "id", KeyType: "HASH" }],
+                AttributeDefinitions: [{ AttributeName: "id", AttributeType: "N" }],
+                BillingMode: "PAY_PER_REQUEST"
+            })
+        );
+
+        await new Promise(resolve => setTimeout(resolve, 1000));
+    }, 15000);
+
+    afterAll(async () => {
+        await service.disconnect();
+        tableManagementClient.destroy();
+    });
+
+    beforeEach(async () => {
+        // Clear all data from table before each test
+        try {
+            const result = await service.selectMany(tableName);
+            for (const item of result.items) {
+                await service.deleteOne(tableName, { id: { operator: "=", value: (item as any).id } });
+            }
+        } catch (error) {
+            // Ignore errors during cleanup
+        }
+    }, 5000);
+
+    // ============ CONNECTION TESTS ============
+
+    describe("Connection Management", () => {
+        it("should connect successfully with valid config", async () => {
+            const testService = new DynamoService();
+            testService.setConfig(config);
+            await testService.connect();
+
+            expect(testService.isConnected()).toBe(true);
+
+            await testService.disconnect();
+        });
+
+        it("should reject connection when no config is set", async () => {
+            const testService = new DynamoService();
+
+            await expect(testService.connect()).rejects.toThrow(DatabaseAdapterError);
+        });
+
+        it("should reject connection with invalid region", async () => {
+            const testService = new DynamoService();
+            testService.setConfig({
+                ...config,
+                region: ""
+            });
+
+            await expect(testService.connect()).rejects.toThrow(DatabaseAdapterError);
+        });
+
+        it("should be disconnected after calling disconnect", async () => {
+            const testService = new DynamoService();
+            testService.setConfig(config);
+            await testService.connect();
+
+            expect(testService.isConnected()).toBe(true);
+
+            await testService.disconnect();
+            expect(testService.isConnected()).toBe(false);
+        });
+
+        it("should return false for healthCheck on disconnected service", async () => {
+            const testService = new DynamoService();
+            const health = await testService.healthCheck();
+            expect(health).toBe(false);
+        });
+    });
+
+    // ============ CREATE OPERATIONS ============
+
+    describe("createOne", () => {
+        it("should insert a single record", async () => {
+            const data = { id: 1, name: "Test User", email: "test@example.com" };
+            const result = await service.createOne(tableName, data);
+
+            expect(result).toEqual(data);
+            expect(result.id).toBe(1);
+        });
+
+        it("should return inserted data with correct types", async () => {
+            const data = {
+                id: 2,
+                name: "John Doe",
+                age: 30,
+                active: true,
+                tags: ["admin", "user"]
+            };
+
+            const result = await service.createOne(tableName, data);
+
+            expect(result.id).toBe(2);
+            expect(result.name).toBe("John Doe");
+            expect(result.age).toBe(30);
+            expect(result.active).toBe(true);
+            expect(result.tags).toEqual(["admin", "user"]);
+        });
+
+        it("should handle nested objects", async () => {
+            const data = {
+                id: 3,
+                user: {
+                    firstName: "Jane",
+                    lastName: "Doe",
+                    contact: {
+                        email: "jane@example.com",
+                        phone: "123-456-7890"
+                    }
+                }
+            };
+
+            const result = await service.createOne(tableName, data);
+
+            expect(result.user.firstName).toBe("Jane");
+            expect(result.user.contact.email).toBe("jane@example.com");
+        });
+    });
+
+    describe("createMany", () => {
+        it("should insert multiple records", async () => {
+            const data = [
+                { id: 1, name: "User 1" },
+                { id: 2, name: "User 2" },
+                { id: 3, name: "User 3" }
+            ];
+
+            const result = await service.createMany(tableName, data);
+
+            expect(result.items).toHaveLength(3);
+            expect(result.result.successful).toBe(3);
+            expect(result.result.failed).toBe(0);
+        });
+
+        it("should handle empty array", async () => {
+            const result = await service.createMany(tableName, []);
+
+            expect(result.items).toHaveLength(0);
+            expect(result.result.successful).toBe(0);
+            expect(result.result.failed).toBe(0);
+        });
+
+        it("should throw error if data is not array", async () => {
+            await expect(
+                service.createMany(tableName, { id: 1 } as any)
+            ).rejects.toThrow();
+        });
+
+        it("should batch inserts in groups of 25", async () => {
+            const data: Array<{ id: number; name: string }> = [];
+            for (let i = 1; i <= 50; i++) {
+                data.push({ id: i, name: `User ${i}` });
+            }
+
+            const result = await service.createMany(tableName, data);
+
+            expect(result.items.length).toBe(50);
+            expect(result.result.successful).toBe(50);
+        });
+    });
+
+    // ============ SELECT OPERATIONS ============
+
+    describe("selectOne", () => {
+        beforeEach(async () => {
+            await service.createOne(tableName, { id: 1, name: "Test", status: "active" });
+            await service.createOne(tableName, { id: 2, name: "Another", status: "inactive" });
+        });
+
+        it("should select a single record by id", async () => {
+            const result = await service.selectOne(tableName, {
+                id: { operator: "=", value: 1 }
+            });
+
+            expect(result).not.toBeNull();
+            expect(result?.id).toBe(1);
+            expect(result?.name).toBe("Test");
+        });
+
+        it("should return null when record not found", async () => {
+            const result = await service.selectOne(tableName, {
+                id: { operator: "=", value: 999 }
+            });
+
+            expect(result).toBeNull();
+        });
+
+        it("should support projection", async () => {
+            const result = await service.selectOne(
+                tableName,
+                { id: { operator: "=", value: 1 } },
+                { projection: ["id", "name"] }
+            );
+
+            expect(result?.id).toBe(1);
+            expect(result?.name).toBe("Test");
+        });
+    });
+
+    describe("selectMany", () => {
+        beforeEach(async () => {
+            const data = [
+                { id: 1, name: "User 1", status: "active", score: 100 },
+                { id: 2, name: "User 2", status: "active", score: 85 },
+                { id: 3, name: "User 3", status: "inactive", score: 90 },
+                { id: 4, name: "User 4", status: "active", score: 75 },
+                { id: 5, name: "User 5", status: "inactive", score: 95 }
+            ];
+            await service.createMany(tableName, data);
+        });
+
+        it("should select multiple records with condition", async () => {
+            const result = await service.selectMany(tableName, {
+                status: { operator: "=", value: "active" }
+            });
+
+            expect(result.items.length).toBeGreaterThan(0);
+            expect(result.items.every((item: any) => item.status === "active")).toBe(true);
+        });
+
+        it("should handle empty result set", async () => {
+            const result = await service.selectMany(tableName, {
+                status: { operator: "=", value: "nonexistent" }
+            });
+
+            expect(result.items).toHaveLength(0);
+            expect(result.total).toBe(0);
+        });
+
+        it("should support limit and offset", async () => {
+            const result = await service.selectMany(tableName, undefined, {
+                limit: 2,
+                offset: 0
+            });
+
+            expect(result.items.length).toBeLessThanOrEqual(2);
+        });
+
+        it("should support ordering", async () => {
+            const result = await service.selectMany(tableName, undefined, {
+                orderBy: [{ field: "id", direction: "DESC" }],
+                limit: 5
+            });
+
+            if (result.items.length > 1) {
+                const ids = result.items.map((item: any) => item.id);
+                for (let i = 1; i < ids.length; i++) {
+                    expect(ids[i]).toBeLessThanOrEqual(ids[i - 1]);
+                }
+            }
+        });
+
+        it("should support projection", async () => {
+            const result = await service.selectMany(tableName, undefined, {
+                projection: ["id", "name"],
+                limit: 3
+            });
+
+            result.items.forEach((item: any) => {
+                expect(item).toHaveProperty("id");
+                expect(item).toHaveProperty("name");
+            });
+        });
+
+        it("should return pagination info", async () => {
+            const result = await service.selectMany(tableName, undefined, { limit: 2 });
+
+            expect(result).toHaveProperty("total");
+            expect(result).toHaveProperty("hasMore");
+            expect(result).toHaveProperty("items");
+        });
+
+        it("should support greater than operator", async () => {
+            const result = await service.selectMany(tableName, {
+                score: { operator: ">", value: 80 }
+            });
+
+            expect(result.items.every((item: any) => item.score > 80)).toBe(true);
+        });
+
+        it("should support less than operator", async () => {
+            const result = await service.selectMany(tableName, {
+                score: { operator: "<", value: 80 }
+            });
+
+            expect(result.items.every((item: any) => item.score < 80)).toBe(true);
+        });
+    });
+
+    // ============ UPDATE OPERATIONS ============
+
+    describe("updateOne", () => {
+        beforeEach(async () => {
+            await service.createOne(tableName, { id: 1, name: "Original", status: "active" });
+            await service.createOne(tableName, { id: 2, name: "Another", status: "inactive" });
+        });
+
+        it("should update a single record", async () => {
+            const result = await service.updateOne(
+                tableName,
+                { name: "Updated", status: "inactive" },
+                { id: { operator: "=", value: 1 } }
+            );
+
+            expect(result.name).toBe("Updated");
+            expect(result.status).toBe("inactive");
+        });
+
+        it("should throw error when record not found", async () => {
+            await expect(
+                service.updateOne(
+                    tableName,
+                    { name: "Updated" },
+                    { id: { operator: "=", value: 999 } }
+                )
+            ).rejects.toThrow(DatabaseAdapterError);
+        });
+
+        it("should preserve other fields during update", async () => {
+            const result = await service.updateOne(
+                tableName,
+                { name: "Updated" },
+                { id: { operator: "=", value: 1 } }
+            );
+
+            expect(result.id).toBe(1);
+            expect(result.name).toBe("Updated");
+            expect(result.status).toBe("active");
+        });
+    });
+
+    describe("updateMany", () => {
+        beforeEach(async () => {
+            const data = [
+                { id: 1, name: "User 1", status: "active" },
+                { id: 2, name: "User 2", status: "active" },
+                { id: 3, name: "User 3", status: "inactive" },
+                { id: 4, name: "User 4", status: "active" }
+            ];
+            await service.createMany(tableName, data);
+        });
+
+        it("should update multiple records matching condition", async () => {
+            const result = await service.updateMany(
+                tableName,
+                { status: "archived" },
+                { status: { operator: "=", value: "inactive" } }
+            );
+
+            expect(result.result.successful).toBeGreaterThan(0);
+        });
+
+        it("should respect limit option", async () => {
+            const result = await service.updateMany(
+                tableName,
+                { status: "archived" },
+                { status: { operator: "=", value: "active" } },
+                { limit: 2 }
+            );
+
+            expect(result.items.length).toBeLessThanOrEqual(2);
+        });
+
+        it("should return empty result when no matches found", async () => {
+            const result = await service.updateMany(
+                tableName,
+                { status: "archived" },
+                { status: { operator: "=", value: "nonexistent" } }
+            );
+
+            expect(result.items).toHaveLength(0);
+            expect(result.result.successful).toBe(0);
+        });
+    });
+
+    // ============ DELETE OPERATIONS ============
+
+    describe("deleteOne", () => {
+        beforeEach(async () => {
+            await service.createOne(tableName, { id: 1, name: "User 1" });
+            await service.createOne(tableName, { id: 2, name: "User 2" });
+        });
+
+        it("should delete a single record", async () => {
+            const result = await service.deleteOne(tableName, {
+                id: { operator: "=", value: 1 }
+            });
+
+            expect(result.success).toBe(true);
+            expect(result.deletedCount).toBe(1);
+
+            const check = await service.selectOne(tableName, {
+                id: { operator: "=", value: 1 }
+            });
+            expect(check).toBeNull();
+        });
+
+        it("should handle deletion of non-existent record", async () => {
+            const result = await service.deleteOne(tableName, {
+                id: { operator: "=", value: 999 }
+            });
+
+            expect(result.success).toBe(false);
+            expect(result.deletedCount).toBe(0);
+        });
+    });
+
+    describe("deleteMany", () => {
+        beforeEach(async () => {
+            const data = [
+                { id: 1, name: "User 1", status: "active" },
+                { id: 2, name: "User 2", status: "inactive" },
+                { id: 3, name: "User 3", status: "active" },
+                { id: 4, name: "User 4", status: "inactive" }
+            ];
+            await service.createMany(tableName, data);
+        });
+
+        it("should delete multiple records matching condition", async () => {
+            const result = await service.deleteMany(tableName, {
+                status: { operator: "=", value: "inactive" }
+            });
+
+            expect(result.success).toBe(true);
+            expect(result.deletedCount).toBeGreaterThan(0);
+        });
+
+        it("should respect limit option", async () => {
+            const result = await service.deleteMany(
+                tableName,
+                { status: { operator: "=", value: "active" } },
+                { limit: 1 }
+            );
+
+            expect(result.deletedCount).toBeLessThanOrEqual(1);
+        });
+
+        it("should handle no matches", async () => {
+            const result = await service.deleteMany(tableName, {
+                status: { operator: "=", value: "nonexistent" }
+            });
+
+            expect(result.success).toBe(true);
+            expect(result.deletedCount).toBe(0);
+        });
+    });
+
+    // ============ OPERATOR TESTS ============
+
+    describe("Query Operators", () => {
+        beforeEach(async () => {
+            const data = [
+                { id: 1, price: 100, category: "electronics" },
+                { id: 2, price: 200, category: "electronics" },
+                { id: 3, price: 50, category: "books" },
+                { id: 4, price: 150, category: "books" }
+            ];
+            await service.createMany(tableName, data);
+        });
+
+        it("should support IN operator", async () => {
+            const result = await service.selectMany(tableName, {
+                id: { operator: "IN", value: [1, 2] }
+            });
+
+            expect(result.items.length).toBeGreaterThan(0);
+            expect(result.items.every((item: any) => [1, 2].includes(item.id))).toBe(true);
+        });
+    });
+
+    // ============ ERROR HANDLING ============
+
+    describe("Error Handling", () => {
+        it("should throw error on operation without connection", async () => {
+            const disconnectedService = new DynamoService();
+
+            await expect(
+                disconnectedService.selectOne(tableName, { id: { operator: "=", value: 1 } })
+            ).rejects.toThrow(DatabaseAdapterError);
+        });
+
+        it("should throw error on unsupported operator", async () => {
+            await expect(
+                service.selectMany(tableName, {
+                    id: { operator: "UNSUPPORTED" as any, value: 1 }
+                })
+            ).rejects.toThrow();
+        });
+
+        it("should throw error on executeRaw", async () => {
+            await expect(
+                service.executeRaw("raw query")
+            ).rejects.toThrow(DatabaseAdapterError);
+        });
+    });
+});