dynamo-query-engine 1.0.1 → 1.0.2

package/tests/unit/cursor.test.js

@@ -0,0 +1,167 @@
+/**
+ * @fileoverview Tests for cursor utilities
+ */
+
+import { describe, it, expect } from "vitest";
+import {
+  encodeCursor,
+  decodeCursor,
+  validateCursor,
+} from "../../src/utils/cursor.js";
+
+describe("Cursor Utils", () => {
+  describe("encodeCursor", () => {
+    it("should encode cursor with lastKey and queryHash", () => {
+      const lastKey = { pk: "ORG#123", sk: "USER#456" };
+      const queryHash = "abc123def456";
+
+      const cursor = encodeCursor(lastKey, queryHash);
+
+      expect(cursor).toBeDefined();
+      expect(typeof cursor).toBe("string");
+      expect(cursor.length).toBeGreaterThan(0);
+    });
+
+    it("should create different cursors for different lastKeys", () => {
+      const lastKey1 = { pk: "ORG#123", sk: "USER#456" };
+      const lastKey2 = { pk: "ORG#456", sk: "USER#789" };
+      const queryHash = "abc123";
+
+      const cursor1 = encodeCursor(lastKey1, queryHash);
+      const cursor2 = encodeCursor(lastKey2, queryHash);
+
+      expect(cursor1).not.toBe(cursor2);
+    });
+
+    it("should throw error when lastKey is missing", () => {
+      expect(() => {
+        encodeCursor(null, "queryHash");
+      }).toThrow("lastKey is required");
+    });
+
+    it("should throw error when queryHash is missing", () => {
+      expect(() => {
+        encodeCursor({ pk: "ORG#123" }, null);
+      }).toThrow("queryHash is required");
+    });
+  });
+
+  describe("decodeCursor", () => {
+    it("should decode a valid cursor", () => {
+      const lastKey = { pk: "ORG#123", sk: "USER#456" };
+      const queryHash = "abc123def456";
+      const cursor = encodeCursor(lastKey, queryHash);
+
+      const decoded = decodeCursor(cursor);
+
+      expect(decoded).toBeDefined();
+      expect(decoded.lastKey).toEqual(lastKey);
+      expect(decoded.queryHash).toBe(queryHash);
+    });
+
+    it("should roundtrip encode and decode", () => {
+      const originalData = {
+        lastKey: { pk: "ORG#999", createdAt: "2024-01-01" },
+        queryHash: "hash999",
+      };
+
+      const cursor = encodeCursor(originalData.lastKey, originalData.queryHash);
+      const decoded = decodeCursor(cursor);
+
+      expect(decoded).toEqual(originalData);
+    });
+
+    it("should throw error for invalid cursor string", () => {
+      expect(() => {
+        decodeCursor("invalid-cursor-string");
+      }).toThrow("Failed to decode cursor");
+    });
+
+    it("should throw error for empty cursor", () => {
+      expect(() => {
+        decodeCursor("");
+      }).toThrow("Invalid cursor: must be a non-empty string");
+    });
+
+    it("should throw error for null cursor", () => {
+      expect(() => {
+        decodeCursor(null);
+      }).toThrow("Invalid cursor: must be a non-empty string");
+    });
+
+    it("should throw error for malformed cursor structure", () => {
+      // Create a cursor without required fields
+      const invalidData = { someField: "value" };
+      const cursor = Buffer.from(JSON.stringify(invalidData)).toString(
+        "base64"
+      );
+
+      expect(() => {
+        decodeCursor(cursor);
+      }).toThrow("Invalid cursor structure");
+    });
+  });
+
+  describe("validateCursor", () => {
+    it("should not throw when query hashes match", () => {
+      const queryHash = "abc123def456";
+
+      expect(() => {
+        validateCursor(queryHash, queryHash);
+      }).not.toThrow();
+    });
+
+    it("should throw when query hashes do not match", () => {
+      const decodedHash = "abc123";
+      const currentHash = "def456";
+
+      expect(() => {
+        validateCursor(decodedHash, currentHash);
+      }).toThrow("Cursor does not match current query");
+    });
+
+    it("should provide helpful error message", () => {
+      expect(() => {
+        validateCursor("oldHash", "newHash");
+      }).toThrow(/Filters, sort, or page size have changed/);
+    });
+  });
+
+  describe("Integration: encode, decode, validate", () => {
+    it("should handle complete cursor workflow", () => {
+      const lastKey = { pk: "ORG#123", sk: "USER#789" };
+      const queryHash = "query-hash-123";
+
+      // Encode
+      const cursor = encodeCursor(lastKey, queryHash);
+      expect(cursor).toBeDefined();
+
+      // Decode
+      const decoded = decodeCursor(cursor);
+      expect(decoded.lastKey).toEqual(lastKey);
+      expect(decoded.queryHash).toBe(queryHash);
+
+      // Validate
+      expect(() => {
+        validateCursor(decoded.queryHash, queryHash);
+      }).not.toThrow();
+    });
+
+    it("should detect query changes between pagination requests", () => {
+      const lastKey = { pk: "ORG#123" };
+      const originalQueryHash = "original-hash";
+      const modifiedQueryHash = "modified-hash";
+
+      // Encode with original query
+      const cursor = encodeCursor(lastKey, originalQueryHash);
+
+      // Decode
+      const decoded = decodeCursor(cursor);
+
+      // Validate with modified query - should fail
+      expect(() => {
+        validateCursor(decoded.queryHash, modifiedQueryHash);
+      }).toThrow("Cursor does not match current query");
+    });
+  });
+});

package/tests/unit/gridQueryBuilder.test.js

@@ -0,0 +1,474 @@
+/**
+ * @fileoverview Tests for grid query builder
+ */
+
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import {
+  buildGridQuery,
+  extractGridConfig,
+} from "../../src/core/gridQueryBuilder.js";
+import {
+  createMockSchema,
+  createMockModel,
+  createMockQuery,
+  mockAttributes,
+} from "../mocks/dynamoose.mock.js";
+
+describe("GridQueryBuilder", () => {
+  describe("extractGridConfig", () => {
+    it("should extract query config from schema", () => {
+      const schema = createMockSchema(mockAttributes);
+      const gridConfig = extractGridConfig(schema);
+
+      expect(gridConfig).toBeDefined();
+      expect(gridConfig.createdAt).toBeDefined();
+      expect(gridConfig.createdAt.sort).toEqual({ type: "key" });
+      expect(gridConfig.createdAt.filter).toBeDefined();
+    });
+
+    it("should only extract fields with query config", () => {
+      const attributes = {
+        field1: {
+          type: String,
+          query: { filter: { type: "key", operators: ["eq"] } },
+        },
+        field2: {
+          type: String,
+          // No query config
+        },
+      };
+
+      const schema = createMockSchema(attributes);
+      const gridConfig = extractGridConfig(schema);
+
+      expect(gridConfig.field1).toBeDefined();
+      expect(gridConfig.field2).toBeUndefined();
+    });
+
+    it("should return empty object when no fields have query config", () => {
+      const attributes = {
+        field1: { type: String },
+        field2: { type: String },
+      };
+
+      const schema = createMockSchema(attributes);
+      const gridConfig = extractGridConfig(schema);
+
+      expect(gridConfig).toEqual({});
+    });
+  });
+
+  describe("buildGridQuery - Basic", () => {
+    let mockModel;
+    let mockQuery;
+
+    beforeEach(() => {
+      const schema = createMockSchema(mockAttributes);
+      mockQuery = createMockQuery([]);
+      mockModel = createMockModel(schema, []);
+      mockModel.query = vi.fn(() => mockQuery);
+    });
+
+    it("should build query with partition key", () => {
+      const { query } = buildGridQuery({
+        model: mockModel,
+        partitionKeyValue: "ORG#123",
+        paginationModel: { pageSize: 20 },
+      });
+
+      expect(mockModel.query).toHaveBeenCalledWith("pk");
+      expect(mockQuery.eq).toHaveBeenCalledWith("ORG#123");
+      expect(mockQuery.limit).toHaveBeenCalledWith(20);
+      expect(query).toBe(mockQuery);
+    });
+
+    it("should throw error when model is missing", () => {
+      expect(() => {
+        buildGridQuery({
+          model: null,
+          partitionKeyValue: "ORG#123",
+          paginationModel: { pageSize: 20 },
+        });
+      }).toThrow("model is required");
+    });
+
+    it("should throw error when partitionKeyValue is missing", () => {
+      expect(() => {
+        buildGridQuery({
+          model: mockModel,
+          partitionKeyValue: null,
+          paginationModel: { pageSize: 20 },
+        });
+      }).toThrow("partitionKeyValue is required");
+    });
+
+    it("should throw error when paginationModel is missing", () => {
+      expect(() => {
+        buildGridQuery({
+          model: mockModel,
+          partitionKeyValue: "ORG#123",
+        });
+      }).toThrow("paginationModel is required");
+    });
+  });
+
+  describe("buildGridQuery - Filtering", () => {
+    let mockModel;
+    let mockQuery;
+
+    beforeEach(() => {
+      const schema = createMockSchema(mockAttributes);
+      mockQuery = createMockQuery([]);
+      mockModel = createMockModel(schema, []);
+      mockModel.query = vi.fn(() => mockQuery);
+    });
+
+    it("should apply eq filter", () => {
+      const filterModel = {
+        items: [{ field: "status", operator: "eq", value: "active" }],
+      };
+
+      buildGridQuery({
+        model: mockModel,
+        partitionKeyValue: "ORG#123",
+        filterModel,
+        paginationModel: { pageSize: 20 },
+      });
+
+      expect(mockQuery.where).toHaveBeenCalledWith("status");
+      expect(mockQuery.eq).toHaveBeenCalledWith("active");
+    });
+
+    it("should apply gte filter", () => {
+      const filterModel = {
+        items: [
+          { field: "createdAt", operator: "gte", value: "2024-01-01" },
+        ],
+      };
+
+      buildGridQuery({
+        model: mockModel,
+        partitionKeyValue: "ORG#123",
+        filterModel,
+        paginationModel: { pageSize: 20 },
+      });
+
+      expect(mockQuery.where).toHaveBeenCalledWith("createdAt");
+      expect(mockQuery.ge).toHaveBeenCalledWith("2024-01-01");
+    });
+
+    it("should apply between filter", () => {
+      const filterModel = {
+        items: [
+          {
+            field: "createdAt",
+            operator: "between",
+            value: ["2024-01-01", "2024-12-31"],
+          },
+        ],
+      };
+
+      buildGridQuery({
+        model: mockModel,
+        partitionKeyValue: "ORG#123",
+        filterModel,
+        paginationModel: { pageSize: 20 },
+      });
+
+      expect(mockQuery.between).toHaveBeenCalledWith("2024-01-01", "2024-12-31");
+    });
+
+    it("should use GSI when filter specifies index", () => {
+      const filterModel = {
+        items: [{ field: "status", operator: "eq", value: "active" }],
+      };
+
+      buildGridQuery({
+        model: mockModel,
+        partitionKeyValue: "ORG#123",
+        filterModel,
+        paginationModel: { pageSize: 20 },
+      });
+
+      expect(mockQuery.using).toHaveBeenCalledWith("status-createdAt-index");
+    });
+
+    it("should throw error for invalid field", () => {
+      const filterModel = {
+        items: [{ field: "invalidField", operator: "eq", value: "test" }],
+      };
+
+      expect(() => {
+        buildGridQuery({
+          model: mockModel,
+          partitionKeyValue: "ORG#123",
+          filterModel,
+          paginationModel: { pageSize: 20 },
+        });
+      }).toThrow("Filtering not allowed");
+    });
+
+    it("should throw error for invalid operator", () => {
+      const filterModel = {
+        items: [{ field: "status", operator: "contains", value: "test" }],
+      };
+
+      expect(() => {
+        buildGridQuery({
+          model: mockModel,
+          partitionKeyValue: "ORG#123",
+          filterModel,
+          paginationModel: { pageSize: 20 },
+        });
+      }).toThrow("not allowed");
+    });
+  });
+
+  describe("buildGridQuery - Sorting", () => {
+    let mockModel;
+    let mockQuery;
+
+    beforeEach(() => {
+      const schema = createMockSchema(mockAttributes);
+      mockQuery = createMockQuery([]);
+      mockModel = createMockModel(schema, []);
+      mockModel.query = vi.fn(() => mockQuery);
+    });
+
+    it("should apply descending sort", () => {
+      const sortModel = [{ field: "createdAt", sort: "desc" }];
+
+      buildGridQuery({
+        model: mockModel,
+        partitionKeyValue: "ORG#123",
+        sortModel,
+        paginationModel: { pageSize: 20 },
+      });
+
+      expect(mockQuery.sort).toHaveBeenCalledWith("descending");
+    });
+
+    it("should not call sort for ascending (default)", () => {
+      const sortModel = [{ field: "createdAt", sort: "asc" }];
+
+      buildGridQuery({
+        model: mockModel,
+        partitionKeyValue: "ORG#123",
+        sortModel,
+        paginationModel: { pageSize: 20 },
+      });
+
+      // Ascending is default, so sort() should not be called
+      expect(mockQuery.sort).not.toHaveBeenCalled();
+    });
+
+    it("should throw error for multiple sort fields", () => {
+      const sortModel = [
+        { field: "createdAt", sort: "desc" },
+        { field: "status", sort: "asc" },
+      ];
+
+      expect(() => {
+        buildGridQuery({
+          model: mockModel,
+          partitionKeyValue: "ORG#123",
+          sortModel,
+          paginationModel: { pageSize: 20 },
+        });
+      }).toThrow(/sorting by one field/);
+    });
+
+    it("should throw error for invalid sort field", () => {
+      const sortModel = [{ field: "name", sort: "desc" }];
+
+      expect(() => {
+        buildGridQuery({
+          model: mockModel,
+          partitionKeyValue: "ORG#123",
+          sortModel,
+          paginationModel: { pageSize: 20 },
+        });
+      }).toThrow("Sorting not allowed");
+    });
+  });
+
+  describe("buildGridQuery - Pagination", () => {
+    let mockModel;
+    let mockQuery;
+
+    beforeEach(() => {
+      const schema = createMockSchema(mockAttributes);
+      mockQuery = createMockQuery([]);
+      mockModel = createMockModel(schema, []);
+      mockModel.query = vi.fn(() => mockQuery);
+    });
+
+    it("should apply page size limit", () => {
+      buildGridQuery({
+        model: mockModel,
+        partitionKeyValue: "ORG#123",
+        paginationModel: { pageSize: 50 },
+      });
+
+      expect(mockQuery.limit).toHaveBeenCalledWith(50);
+    });
+
+    it("should handle cursor for next page", () => {
+      const lastKey = { pk: "ORG#123", createdAt: "2024-01-01" };
+      
+      // First, build query to get the correct queryHash
+      const firstResult = buildGridQuery({
+        model: mockModel,
+        partitionKeyValue: "ORG#123",
+        paginationModel: { pageSize: 20 },
+      });
+
+      // Create cursor with the actual queryHash
+      const cursor = Buffer.from(
+        JSON.stringify({ lastKey, queryHash: firstResult.queryHash })
+      ).toString("base64");
+
+      // Build query again with cursor
+      buildGridQuery({
+        model: mockModel,
+        partitionKeyValue: "ORG#123",
+        paginationModel: { pageSize: 20 },
+        cursor,
+      });
+
+      expect(mockQuery.startAt).toHaveBeenCalledWith(lastKey);
+    });
+
+    it("should validate cursor matches query", () => {
+      const lastKey = { pk: "ORG#123" };
+      const queryHash = "originalHash";
+      const cursor = Buffer.from(
+        JSON.stringify({ lastKey, queryHash })
+      ).toString("base64");
+
+      // Different query parameters should cause hash mismatch
+      expect(() => {
+        buildGridQuery({
+          model: mockModel,
+          partitionKeyValue: "ORG#123",
+          paginationModel: { pageSize: 50 }, // Different page size
+          cursor,
+        });
+      }).toThrow("Cursor does not match");
+    });
+  });
+
+  describe("buildGridQuery - Query Hash", () => {
+    let mockModel;
+
+    beforeEach(() => {
+      const schema = createMockSchema(mockAttributes);
+      mockModel = createMockModel(schema, []);
+    });
+
+    it("should return consistent query hash for same parameters", () => {
+      const params = {
+        model: mockModel,
+        partitionKeyValue: "ORG#123",
+        filterModel: {
+          items: [{ field: "status", operator: "eq", value: "active" }],
+        },
+        sortModel: [{ field: "createdAt", sort: "desc" }],
+        paginationModel: { pageSize: 20 },
+      };
+
+      const result1 = buildGridQuery(params);
+      const result2 = buildGridQuery(params);
+
+      expect(result1.queryHash).toBe(result2.queryHash);
+    });
+
+    it("should return different hash when filters change", () => {
+      const baseParams = {
+        model: mockModel,
+        partitionKeyValue: "ORG#123",
+        paginationModel: { pageSize: 20 },
+      };
+
+      const result1 = buildGridQuery({
+        ...baseParams,
+        filterModel: {
+          items: [{ field: "status", operator: "eq", value: "active" }],
+        },
+      });
+
+      const result2 = buildGridQuery({
+        ...baseParams,
+        filterModel: {
+          items: [{ field: "status", operator: "eq", value: "inactive" }],
+        },
+      });
+
+      expect(result1.queryHash).not.toBe(result2.queryHash);
+    });
+
+    it("should return different hash when page size changes", () => {
+      const baseParams = {
+        model: mockModel,
+        partitionKeyValue: "ORG#123",
+      };
+
+      const result1 = buildGridQuery({
+        ...baseParams,
+        paginationModel: { pageSize: 20 },
+      });
+
+      const result2 = buildGridQuery({
+        ...baseParams,
+        paginationModel: { pageSize: 50 },
+      });
+
+      expect(result1.queryHash).not.toBe(result2.queryHash);
+    });
+  });
+
+  describe("buildGridQuery - Complex Scenarios", () => {
+    let mockModel;
+    let mockQuery;
+
+    beforeEach(() => {
+      const schema = createMockSchema(mockAttributes);
+      mockQuery = createMockQuery([]);
+      mockModel = createMockModel(schema, []);
+      mockModel.query = vi.fn(() => mockQuery);
+    });
+
+    it("should handle query with filter, sort, and pagination", () => {
+      buildGridQuery({
+        model: mockModel,
+        partitionKeyValue: "ORG#123",
+        filterModel: {
+          items: [{ field: "status", operator: "eq", value: "active" }],
+        },
+        sortModel: [{ field: "createdAt", sort: "desc" }],
+        paginationModel: { pageSize: 25 },
+      });
+
+      // Verify all operations were applied
+      expect(mockModel.query).toHaveBeenCalledWith("pk");
+      expect(mockQuery.eq).toHaveBeenCalled();
+      expect(mockQuery.using).toHaveBeenCalled();
+      expect(mockQuery.where).toHaveBeenCalled();
+      expect(mockQuery.sort).toHaveBeenCalledWith("descending");
+      expect(mockQuery.limit).toHaveBeenCalledWith(25);
+    });
+
+    it("should handle empty filter and sort models", () => {
+      const { query } = buildGridQuery({
+        model: mockModel,
+        partitionKeyValue: "ORG#123",
+        filterModel: { items: [] },
+        sortModel: [],
+        paginationModel: { pageSize: 20 },
+      });
+
+      expect(query).toBeDefined();
+      expect(mockQuery.limit).toHaveBeenCalledWith(20);
+    });
+  });
+});