dynamo-query-engine 1.0.1 → 1.0.2

package/README.md

@@ -39,7 +39,7 @@ const UserSchema = new dynamoose.Schema({
   createdAt: {
     type: String,
     rangeKey: true,
-    grid: {
+    query: {
       sort: { type: "key" },
       filter: {
         type: "key",
@@ -54,7 +54,7 @@ const UserSchema = new dynamoose.Schema({
       global: true,
       rangeKey: "createdAt",
     },
-    grid: {
+    query: {
       filter: {
         type: "key",
         operators: ["eq"],
@@ -65,7 +65,7 @@ const UserSchema = new dynamoose.Schema({
   teamIds: {
     type: Array,
     schema: [String],
-    grid: {
+    query: {
       expand: {
         type: "Team",
         relation: "MANY",
@@ -176,7 +176,7 @@ query UsersGrid(
 ### Filter Configuration
 
 ```javascript
-grid: {
+query: {
   filter: {
     type: "key",                    // Only "key" supported
     operators: ["eq", "gte", "lte"], // Allowed operators
@@ -190,7 +190,7 @@ grid: {
 ### Sort Configuration
 
 ```javascript
-grid: {
+query: {
   sort: { type: "key" } // Only range keys can be sorted
 }
 ```
@@ -200,7 +200,7 @@ grid: {
 ### Expand Configuration
 
 ```javascript
-grid: {
+query: {
   expand: {
     type: "Team",           // Model name (must be registered)
     relation: "MANY",       // "ONE" or "MANY"
@@ -316,7 +316,7 @@ status: {
     global: true,
     rangeKey: "createdAt",
   },
-  grid: {
+  query: {
     filter: {
       type: "key",
       operators: ["eq"],
@@ -376,10 +376,52 @@ The library provides descriptive errors:
 - `"Cursor does not match query"` - Query params changed between pages
 - `"Model 'X' not found in registry"` - Model not registered
 
+## Testing
+
+The package includes comprehensive unit tests with Vitest.
+
+### Run Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run tests with UI
+npm run test:ui
+
+# Run tests once (CI mode)
+npm run test:run
+
+# Generate coverage report
+npm run coverage
+```
+
+### Test Coverage
+
+- **Cursor Utils**: ~80% coverage
+- **Validation**: ~70% coverage  
+- **GridQueryBuilder**: ~50% coverage
+- **Overall**: ~50-60% coverage
+
+See [tests/README.md](./tests/README.md) for detailed testing documentation.
+
 ## Contributing
 
 Contributions are welcome! Please open an issue or pull request.
 
+### Development Setup
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Check coverage
+npm run coverage
+```
+
 ## License
 
 MIT © Sascha Eckstein

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dynamo-query-engine",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Type-safe DynamoDB query builder for GraphQL with support for filtering, sorting, pagination, and relation expansion",
   "type": "module",
   "main": "index.js",
@@ -10,7 +10,10 @@
     "./utils": "./src/utils/index.js"
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:run": "vitest run",
+    "coverage": "vitest --coverage"
   },
   "keywords": [
     "dynamodb",
@@ -39,6 +42,10 @@
   "dependencies": {
     "graphql-parse-resolve-info": "^4.13.0"
   },
+  "devDependencies": {
+    "@vitest/ui": "^2.1.8",
+    "vitest": "^2.1.8"
+  },
   "engines": {
     "node": ">=18.0.0"
   }

package/src/core/expandResolver.js

@@ -11,7 +11,7 @@ import { extractGridConfig } from "./gridQueryBuilder.js";
 /**
  * Extract expand policy from schema
  * @param {*} schema - Dynamoose schema
- * @returns {Object.<string, ExpandConfig>} Expand policies by field name
+ * @returns {Object.<string, import("../types/jsdoc.js").ExpandConfig>} Expand policies by field name
  */
 export function extractExpandPolicy(schema) {
   const gridConfig = extractGridConfig(schema);

package/src/core/gridQueryBuilder.js

@@ -31,15 +31,15 @@ function hashQuery({ filterModel, sortModel, pageSize }) {
 /**
  * Extract grid configuration from Dynamoose schema
  * @param {*} schema - Dynamoose schema
- * @returns {ExtractedGridConfig} Extracted grid configuration
+ * @returns {Object.<string, import("../types/jsdoc.js").GridConfig>} Extracted grid configuration
  */
 export function extractGridConfig(schema) {
   const attributes = schema.getAttributes();
   const gridConfig = {};
 
   for (const [field, definition] of Object.entries(attributes)) {
-    if (definition.grid) {
-      gridConfig[field] = definition.grid;
+    if (definition.query) {
+      gridConfig[field] = definition.query;
     }
   }
 

package/src/utils/validation.js

@@ -20,7 +20,7 @@ export function validateSingleSort(sortModel) {
 /**
  * Validates that a field can be filtered based on grid config
  * @param {string} field - Field name to filter
- * @param {ExtractedGridConfig} gridConfig - Extracted grid configuration
+ * @param {Object.<string, import("../types/jsdoc.js").GridConfig>} gridConfig - Extracted grid configuration
  * @throws {Error} If filtering is not allowed on this field
  */
 export function validateFilterField(field, gridConfig) {
@@ -35,7 +35,7 @@ export function validateFilterField(field, gridConfig) {
 /**
  * Validates that a field can be sorted based on grid config
  * @param {string} field - Field name to sort
- * @param {ExtractedGridConfig} gridConfig - Extracted grid configuration
+ * @param {Object.<string, import("../types/jsdoc.js").GridConfig>} gridConfig - Extracted grid configuration
  * @throws {Error} If sorting is not allowed on this field
  */
 export function validateSortField(field, gridConfig) {
@@ -51,7 +51,7 @@ export function validateSortField(field, gridConfig) {
  * Validates that operator is allowed for a filter field
  * @param {string} field - Field name
  * @param {string} operator - Operator to validate
- * @param {ExtractedGridConfig} gridConfig - Extracted grid configuration
+ * @param {Object.<string, import("../types/jsdoc.js").GridConfig>} gridConfig - Extracted grid configuration
  * @throws {Error} If operator is not allowed for this field
  */
 export function validateFilterOperator(field, operator, gridConfig) {
@@ -70,7 +70,7 @@ export function validateFilterOperator(field, operator, gridConfig) {
 /**
  * Validates that a field can be expanded based on grid config
  * @param {string} field - Field name to expand
- * @param {ExtractedGridConfig} gridConfig - Extracted grid configuration
+ * @param {Object.<string, import("../types/jsdoc.js").GridConfig>} gridConfig - Extracted grid configuration
  * @throws {Error} If expand is not allowed on this field
  */
 export function validateExpandField(field, gridConfig) {

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,
+      },
+    },
+  },
+};