dynamo-query-engine 1.0.0 → 1.0.2

package/tests/README.md

@@ -0,0 +1,279 @@
+# Tests
+
+Unit-Tests für DynamoDB Query Engine mit Vitest.
+
+## Test-Struktur
+
+```
+tests/
+├── unit/
+│   ├── cursor.test.js           # Cursor Utils Tests
+│   ├── validation.test.js       # Validation Tests
+│   └── gridQueryBuilder.test.js # Query Builder Tests
+└── mocks/
+    └── dynamoose.mock.js        # Dynamoose Mock Utilities
+```
+
+## Tests ausführen
+
+### Alle Tests
+
+```bash
+npm test
+```
+
+### Tests im Watch-Modus
+
+```bash
+npm test -- --watch
+```
+
+### Tests mit UI
+
+```bash
+npm run test:ui
+```
+
+### Einzelne Tests
+
+```bash
+npm test cursor
+npm test validation
+npm test gridQueryBuilder
+```
+
+### Coverage-Report
+
+```bash
+npm run coverage
+```
+
+Der Coverage-Report wird in `coverage/` generiert. Öffnen Sie `coverage/index.html` im Browser für eine detaillierte Ansicht.
+
+## Test-Abdeckung
+
+### Cursor Utils (~80% Coverage)
+
+**Getestete Funktionen:**
+- `encodeCursor()` - Base64-Encoding von Cursor-Daten
+- `decodeCursor()` - Base64-Decoding von Cursors
+- `validateCursor()` - Cursor-Hash-Validierung
+
+**Test-Cases:**
+- ✅ Erfolgreiche Encodierung
+- ✅ Erfolgreiche Decodierung
+- ✅ Roundtrip encode/decode
+- ✅ Error-Handling für fehlende Parameter
+- ✅ Error-Handling für ungültige Cursors
+- ✅ Cursor-Validierung
+- ✅ Hash-Mismatch-Erkennung
+
+### Validation Utils (~70% Coverage)
+
+**Getestete Funktionen:**
+- `validateSingleSort()` - Validierung von Sort-Feldern
+- `validateFilterField()` - Validierung von Filter-Feldern
+- `validateSortField()` - Validierung von Sort-Feldern
+- `validateFilterOperator()` - Validierung von Operatoren
+- `validateExpandField()` - Validierung von Expand-Feldern
+- `validatePaginationModel()` - Validierung von Pagination
+
+**Test-Cases:**
+- ✅ Erlaubte Konfigurationen
+- ✅ Error bei nicht-konfigurierten Feldern
+- ✅ Error bei ungültigen Operatoren
+- ✅ Error bei mehrfachen Sort-Feldern
+- ✅ Edge-Cases (leere Configs, null, undefined)
+- ✅ Hilfreiche Fehlermeldungen
+
+### GridQueryBuilder (~50% Coverage)
+
+**Getestete Funktionen:**
+- `extractGridConfig()` - Config-Extraktion aus Schema
+- `buildGridQuery()` - Query-Generierung
+
+**Test-Cases:**
+- ✅ Basis-Query mit Partition Key
+- ✅ Filter-Anwendung (eq, gte, between)
+- ✅ Sort-Anwendung (asc/desc)
+- ✅ Pagination mit Limit
+- ✅ Cursor-Handling
+- ✅ GSI-Verwendung
+- ✅ Query-Hash-Generierung
+- ✅ Error-Handling
+- ✅ Komplexe Szenarien
+
+## Mocks
+
+### Dynamoose Mock
+
+Der `dynamoose.mock.js` bietet Utilities zum Mocken von Dynamoose-Models:
+
+```javascript
+import { createMockSchema, createMockModel } from "../mocks/dynamoose.mock.js";
+
+// Schema mocken
+const schema = createMockSchema(attributes);
+
+// Model mocken
+const model = createMockModel(schema, queryResult);
+```
+
+**Features:**
+- Chainable Query-Methoden
+- Konfigurierbare Exec-Ergebnisse
+- Schema mit `getAttributes()`
+- Vordefinierte Test-Attribute
+
+## Best Practices
+
+### Test-Struktur
+
+```javascript
+describe("FunctionName", () => {
+  describe("Happy Path", () => {
+    it("should do X when Y", () => {
+      // Arrange
+      const input = ...;
+      
+      // Act
+      const result = functionName(input);
+      
+      // Assert
+      expect(result).toBe(expected);
+    });
+  });
+
+  describe("Error Handling", () => {
+    it("should throw error when Z", () => {
+      expect(() => {
+        functionName(invalidInput);
+      }).toThrow("Expected error message");
+    });
+  });
+});
+```
+
+### beforeEach für Setup
+
+```javascript
+describe("MyTests", () => {
+  let mockModel;
+  let mockQuery;
+
+  beforeEach(() => {
+    mockQuery = createMockQuery();
+    mockModel = createMockModel(schema);
+  });
+
+  it("test case", () => {
+    // mockModel ist hier verfügbar
+  });
+});
+```
+
+### Assertions
+
+```javascript
+// Exakte Gleichheit
+expect(result).toBe(expected);
+expect(result).toEqual(expected);
+
+// Fehler
+expect(() => func()).toThrow("error message");
+expect(() => func()).toThrow(/regex pattern/);
+
+// Mock-Aufrufe
+expect(mockFn).toHaveBeenCalled();
+expect(mockFn).toHaveBeenCalledWith(arg1, arg2);
+expect(mockFn).toHaveBeenCalledTimes(1);
+
+// Objekt-Properties
+expect(obj).toBeDefined();
+expect(obj.prop).toBeUndefined();
+expect(array.length).toBeGreaterThan(0);
+```
+
+## Debugging
+
+### Einzelnen Test ausführen
+
+```javascript
+it.only("should test specific case", () => {
+  // Nur dieser Test wird ausgeführt
+});
+```
+
+### Test überspringen
+
+```javascript
+it.skip("should test later", () => {
+  // Wird übersprungen
+});
+```
+
+### Debug-Output
+
+```javascript
+it("should debug test", () => {
+  console.log("Debug info:", someValue);
+  expect(someValue).toBeDefined();
+});
+```
+
+## Coverage-Ziele
+
+- **Gesamt**: ~50-60% Coverage
+- **Kritische Utils**: >70% Coverage
+- **Core Logic**: ~50% Coverage
+
+## Continuous Integration
+
+Für CI/CD-Pipelines:
+
+```bash
+# Tests ohne Watch-Modus
+npm run test:run
+
+# Mit Coverage
+npm run coverage
+
+# Exit-Code bei Fehler
+npm run test:run -- --reporter=verbose
+```
+
+## Erweiterung
+
+### Neue Tests hinzufügen
+
+1. Datei in `tests/unit/` erstellen
+2. Vitest importieren: `import { describe, it, expect } from "vitest"`
+3. Tests schreiben
+4. Ausführen: `npm test`
+
+### Neue Mocks hinzufügen
+
+Mocks für zusätzliche Dependencies in `tests/mocks/` ablegen.
+
+## Troubleshooting
+
+### "Cannot find module"
+
+```bash
+# Dependencies installieren
+npm install
+```
+
+### Tests schlagen fehl nach Code-Änderungen
+
+```bash
+# Cache leeren
+npm test -- --clearCache
+```
+
+### Coverage zu niedrig
+
+Fokus auf kritische Pfade:
+- Happy Path
+- Error-Handling
+- Edge-Cases

package/tests/mocks/dynamoose.mock.js

@@ -0,0 +1,124 @@
+/**
+ * @fileoverview Mock for Dynamoose models and schemas
+ */
+
+import { vi } from "vitest";
+
+/**
+ * Creates a mock Dynamoose schema
+ * @param {Object} attributes - Schema attributes with query config
+ * @returns {Object} Mock schema
+ */
+export function createMockSchema(attributes) {
+  return {
+    getAttributes: vi.fn(() => attributes),
+  };
+}
+
+/**
+ * Creates a chainable mock query object
+ * @param {*} execResult - Result to return from exec()
+ * @returns {Object} Mock query object
+ */
+export function createMockQuery(execResult = []) {
+  const mockQuery = {
+    eq: vi.fn().mockReturnThis(),
+    ne: vi.fn().mockReturnThis(),
+    gt: vi.fn().mockReturnThis(),
+    ge: vi.fn().mockReturnThis(),
+    lt: vi.fn().mockReturnThis(),
+    le: vi.fn().mockReturnThis(),
+    between: vi.fn().mockReturnThis(),
+    beginsWith: vi.fn().mockReturnThis(),
+    contains: vi.fn().mockReturnThis(),
+    where: vi.fn().mockReturnThis(),
+    using: vi.fn().mockReturnThis(),
+    limit: vi.fn().mockReturnThis(),
+    sort: vi.fn().mockReturnThis(),
+    startAt: vi.fn().mockReturnThis(),
+    exec: vi.fn().mockResolvedValue(execResult),
+  };
+
+  return mockQuery;
+}
+
+/**
+ * Creates a mock Dynamoose model
+ * @param {Object} schema - Mock schema
+ * @param {*} queryResult - Result to return from query execution
+ * @returns {Object} Mock model
+ */
+export function createMockModel(schema, queryResult = []) {
+  const mockQuery = createMockQuery(queryResult);
+
+  return {
+    schema,
+    query: vi.fn(() => mockQuery),
+    _mockQuery: mockQuery, // Expose for testing
+  };
+}
+
+/**
+ * Common schema attributes for testing
+ */
+export const mockAttributes = {
+  pk: {
+    type: String,
+    hashKey: true,
+  },
+  createdAt: {
+    type: String,
+    rangeKey: true,
+    query: {
+      sort: { type: "key" },
+      filter: {
+        type: "key",
+        operators: ["between", "gte", "lte"],
+      },
+    },
+  },
+  status: {
+    type: String,
+    index: {
+      name: "status-createdAt-index",
+      global: true,
+      rangeKey: "createdAt",
+    },
+    query: {
+      filter: {
+        type: "key",
+        operators: ["eq"],
+        index: "status-createdAt-index",
+      },
+    },
+  },
+  email: {
+    type: String,
+    index: {
+      name: "email-index",
+      global: true,
+    },
+    query: {
+      filter: {
+        type: "key",
+        operators: ["eq"],
+        index: "email-index",
+      },
+    },
+  },
+  name: {
+    type: String,
+  },
+  teamIds: {
+    type: Array,
+    schema: [String],
+    query: {
+      expand: {
+        type: "Team",
+        relation: "MANY",
+        defaultLimit: 5,
+        maxLimit: 20,
+      },
+    },
+  },
+};

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");
+    });
+  });
+});