dynamo-query-engine 1.0.3 → 1.0.5

package/README.md

@@ -28,6 +28,8 @@ npm install dynamoose graphql graphql-parse-resolve-info
 
 ### 1. Define Models with Grid Configuration
 
+> **Note**: The library supports any hash key field name (e.g., `pk`, `tenantId`, `userId`, etc.). It automatically detects the hash key from your schema.
+
 ```javascript
 import dynamoose from "dynamoose";
 
@@ -79,6 +81,39 @@ const UserSchema = new dynamoose.Schema({
 export const UserModel = dynamoose.model("Users", UserSchema);
 ```
 
+**Example with custom hash key name:**
+
+```javascript
+// The library works with any hash key field name
+const ReservationSchema = new dynamoose.Schema({
+  tenantId: {
+    type: String,
+    hashKey: true,  // Automatically detected by getHashKey()
+  },
+  reservationId: {
+    type: String,
+    rangeKey: true,  // Automatically detected by getRangeKey()
+  },
+  // ... other fields
+});
+
+export const ReservationModel = dynamoose.model("Reservations", ReservationSchema);
+```
+
+**Extracting keys programmatically:**
+
+```javascript
+import { getHashKey, getRangeKey } from "dynamo-query-engine";
+
+// Get the hash key field name from your schema
+const hashKeyField = getHashKey(ReservationModel.schema);
+console.log(hashKeyField); // "tenantId"
+
+// Get the range key field name (or null if none exists)
+const rangeKeyField = getRangeKey(ReservationModel.schema);
+console.log(rangeKeyField); // "reservationId"
+```
+
 ### 2. Register Models
 
 ```javascript
@@ -265,6 +300,20 @@ Registers a Dynamoose model.
 
 Retrieves a registered model.
 
+#### `getHashKey(schema)`
+
+Extracts the hash key (partition key) field name from a Dynamoose schema.
+
+**Returns:** `string` - The hash key field name
+
+**Throws:** Error if no hash key is found in the schema
+
+#### `getRangeKey(schema)`
+
+Extracts the range key (sort key) field name from a Dynamoose schema.
+
+**Returns:** `string | null` - The range key field name, or null if no range key exists
+
 ## Architecture
 
 ```

package/index.js

@@ -9,6 +9,8 @@ export { modelRegistry, ModelRegistry } from "./src/core/modelRegistry.js";
 export {
   buildGridQuery,
   extractGridConfig,
+  getHashKey,
+  getRangeKey,
 } from "./src/core/gridQueryBuilder.js";
 export {
   resolveExpand,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dynamo-query-engine",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Type-safe DynamoDB query builder for GraphQL with support for filtering, sorting, pagination, and relation expansion",
   "type": "module",
   "main": "index.js",

package/src/core/gridQueryBuilder.js

@@ -9,7 +9,6 @@ import {
   validateFilterField,
   validateSortField,
   validateFilterOperator,
-  validatePaginationModel,
 } from "../utils/validation.js";
 import { decodeCursor, validateCursor } from "../utils/cursor.js";
 
@@ -18,13 +17,13 @@ import { decodeCursor, validateCursor } from "../utils/cursor.js";
  * @param {Object} params - Query parameters
  * @param {FilterModel} params.filterModel - Filter model
  * @param {SortModel} params.sortModel - Sort model
- * @param {number} params.pageSize - Page size
+ * @param {number} params.limit - Query limit
  * @returns {string} SHA256 hash of the query parameters
  */
-function hashQuery({ filterModel, sortModel, pageSize }) {
+function hashQuery({ filterModel, sortModel, limit }) {
   return crypto
     .createHash("sha256")
-    .update(JSON.stringify({ filterModel, sortModel, pageSize }))
+    .update(JSON.stringify({ filterModel, sortModel, limit }))
     .digest("hex");
 }
 
@@ -46,6 +45,40 @@ export function extractGridConfig(schema) {
   return gridConfig;
 }
 
+/**
+ * Get the hash key (partition key) field name from Dynamoose schema
+ * @param {*} schema - Dynamoose schema
+ * @returns {string} Hash key field name
+ */
+export function getHashKey(schema) {
+  const attributes = schema.getAttributes();
+  
+  for (const [field, definition] of Object.entries(attributes)) {
+    if (definition.hashKey === true) {
+      return field;
+    }
+  }
+  
+  throw new Error("No hash key found in schema");
+}
+
+/**
+ * Get the range key (sort key) field name from Dynamoose schema
+ * @param {*} schema - Dynamoose schema
+ * @returns {string|null} Range key field name, or null if no range key exists
+ */
+export function getRangeKey(schema) {
+  const attributes = schema.getAttributes();
+  
+  for (const [field, definition] of Object.entries(attributes)) {
+    if (definition.rangeKey === true) {
+      return field;
+    }
+  }
+  
+  return null;
+}
+
 /**
  * Determine which GSI to use based on filter model
  * @param {FilterModel} filterModel - Filter model
@@ -165,7 +198,7 @@ export function buildGridQuery({
   partitionKeyValue,
   filterModel,
   sortModel,
-  paginationModel,
+  limit = 10,
   cursor,
 }) {
   // Validate inputs
@@ -175,12 +208,29 @@ export function buildGridQuery({
   if (!partitionKeyValue) {
     throw new Error("partitionKeyValue is required");
   }
-  validatePaginationModel(paginationModel);
+  
+  // Validate and normalize limit
+  if (limit !== undefined && limit !== null) {
+    const numLimit = typeof limit === "string" ? Number(limit) : limit;
+    if (Number.isNaN(numLimit) || numLimit < 1) {
+      throw new Error("limit must be a positive number");
+    }
+    if (numLimit > 1000) {
+      throw new Error("limit cannot exceed 1000 (DynamoDB limit)");
+    }
+    limit = numLimit;
+  } else {
+    limit = 10;
+  }
+  
   validateSingleSort(sortModel);
 
   // Extract grid config from schema
   const gridConfig = extractGridConfig(model.schema);
 
+  // Get the hash key field name from schema
+  const hashKeyField = getHashKey(model.schema);
+
   // Determine which index to use
   const index = determineIndex(filterModel, gridConfig);
 
@@ -188,11 +238,11 @@ export function buildGridQuery({
   const queryHash = hashQuery({
     filterModel,
     sortModel,
-    pageSize: paginationModel.pageSize,
+    limit,
   });
 
   // Initialize query with partition key
-  let query = model.query("pk").eq(partitionKeyValue);
+  let query = model.query(hashKeyField).eq(partitionKeyValue);
 
   // Use GSI if needed
   if (index) {
@@ -205,8 +255,8 @@ export function buildGridQuery({
   // Apply sort
   query = applySort(query, sortModel, gridConfig);
 
-  // Apply pagination limit
-  query = query.limit(paginationModel.pageSize);
+  // Apply limit
+  query = query.limit(limit);
 
   // Handle cursor for pagination
   if (cursor) {

package/src/core/index.js

@@ -3,7 +3,7 @@
  */
 
 export { modelRegistry, ModelRegistry } from "./modelRegistry.js";
-export { buildGridQuery, extractGridConfig } from "./gridQueryBuilder.js";
+export { buildGridQuery, extractGridConfig, getHashKey, getRangeKey } from "./gridQueryBuilder.js";
 export {
   resolveExpand,
   resolveExpands,

package/tests/unit/gridQueryBuilder.test.js

@@ -6,6 +6,8 @@ import { describe, it, expect, beforeEach, vi } from "vitest";
 import {
   buildGridQuery,
   extractGridConfig,
+  getHashKey,
+  getRangeKey,
 } from "../../src/core/gridQueryBuilder.js";
 import {
   createMockSchema,
@@ -58,6 +60,120 @@ describe("GridQueryBuilder", () => {
     });
   });
 
+  describe("getHashKey", () => {
+    it("should extract hash key field named 'pk'", () => {
+      const attributes = {
+        pk: { type: String, hashKey: true },
+        sk: { type: String, rangeKey: true },
+      };
+
+      const schema = createMockSchema(attributes);
+      const hashKey = getHashKey(schema);
+
+      expect(hashKey).toBe("pk");
+    });
+
+    it("should extract hash key field named 'tenantId'", () => {
+      const attributes = {
+        tenantId: { type: String, hashKey: true },
+        reservationId: { type: String, rangeKey: true },
+      };
+
+      const schema = createMockSchema(attributes);
+      const hashKey = getHashKey(schema);
+
+      expect(hashKey).toBe("tenantId");
+    });
+
+    it("should extract hash key field with any name", () => {
+      const attributes = {
+        customHashKey: { type: String, hashKey: true },
+        otherField: { type: String },
+      };
+
+      const schema = createMockSchema(attributes);
+      const hashKey = getHashKey(schema);
+
+      expect(hashKey).toBe("customHashKey");
+    });
+
+    it("should throw error when no hash key found", () => {
+      const attributes = {
+        field1: { type: String },
+        field2: { type: String },
+      };
+
+      const schema = createMockSchema(attributes);
+
+      expect(() => {
+        getHashKey(schema);
+      }).toThrow("No hash key found in schema");
+    });
+  });
+
+  describe("getRangeKey", () => {
+    it("should extract range key field named 'sk'", () => {
+      const attributes = {
+        pk: { type: String, hashKey: true },
+        sk: { type: String, rangeKey: true },
+      };
+
+      const schema = createMockSchema(attributes);
+      const rangeKey = getRangeKey(schema);
+
+      expect(rangeKey).toBe("sk");
+    });
+
+    it("should extract range key field named 'createdAt'", () => {
+      const attributes = {
+        pk: { type: String, hashKey: true },
+        createdAt: { type: String, rangeKey: true },
+      };
+
+      const schema = createMockSchema(attributes);
+      const rangeKey = getRangeKey(schema);
+
+      expect(rangeKey).toBe("createdAt");
+    });
+
+    it("should extract range key field named 'reservationId'", () => {
+      const attributes = {
+        tenantId: { type: String, hashKey: true },
+        reservationId: { type: String, rangeKey: true },
+      };
+
+      const schema = createMockSchema(attributes);
+      const rangeKey = getRangeKey(schema);
+
+      expect(rangeKey).toBe("reservationId");
+    });
+
+    it("should return null when no range key exists", () => {
+      const attributes = {
+        pk: { type: String, hashKey: true },
+        field1: { type: String },
+        field2: { type: String },
+      };
+
+      const schema = createMockSchema(attributes);
+      const rangeKey = getRangeKey(schema);
+
+      expect(rangeKey).toBeNull();
+    });
+
+    it("should work with custom range key names", () => {
+      const attributes = {
+        customHashKey: { type: String, hashKey: true },
+        customSortKey: { type: String, rangeKey: true },
+      };
+
+      const schema = createMockSchema(attributes);
+      const rangeKey = getRangeKey(schema);
+
+      expect(rangeKey).toBe("customSortKey");
+    });
+  });
+
   describe("buildGridQuery - Basic", () => {
     let mockModel;
     let mockQuery;
@@ -73,7 +189,7 @@ describe("GridQueryBuilder", () => {
       const { query } = buildGridQuery({
         model: mockModel,
         partitionKeyValue: "ORG#123",
-        paginationModel: { pageSize: 20 },
+        limit: 20,
       });
 
       expect(mockModel.query).toHaveBeenCalledWith("pk");
@@ -87,7 +203,7 @@ describe("GridQueryBuilder", () => {
         buildGridQuery({
           model: null,
           partitionKeyValue: "ORG#123",
-          paginationModel: { pageSize: 20 },
+          limit: 20,
         });
       }).toThrow("model is required");
     });
@@ -97,18 +213,48 @@ describe("GridQueryBuilder", () => {
         buildGridQuery({
           model: mockModel,
           partitionKeyValue: null,
-          paginationModel: { pageSize: 20 },
+          limit: 20,
         });
       }).toThrow("partitionKeyValue is required");
     });
 
-    it("should throw error when paginationModel is missing", () => {
-      expect(() => {
-        buildGridQuery({
-          model: mockModel,
-          partitionKeyValue: "ORG#123",
-        });
-      }).toThrow("paginationModel is required");
+    it("should use default limit when not provided", () => {
+      const { query } = buildGridQuery({
+        model: mockModel,
+        partitionKeyValue: "ORG#123",
+      });
+
+      expect(mockQuery.limit).toHaveBeenCalledWith(10);
+      expect(query).toBe(mockQuery);
+    });
+
+    it("should use custom hash key name from schema", () => {
+      // Create schema with custom hash key name (tenantId instead of pk)
+      const customAttributes = {
+        tenantId: { type: String, hashKey: true },
+        reservationId: { type: String, rangeKey: true },
+        status: {
+          type: String,
+          query: {
+            filter: { type: "attribute", operators: ["eq"] },
+          },
+        },
+      };
+
+      const customSchema = createMockSchema(customAttributes);
+      const customMockQuery = createMockQuery([]);
+      const customMockModel = createMockModel(customSchema, []);
+      customMockModel.query = vi.fn(() => customMockQuery);
+
+      buildGridQuery({
+        model: customMockModel,
+        partitionKeyValue: "tenant-123",
+        limit: 20,
+      });
+
+      // Should query with 'tenantId' not 'pk'
+      expect(customMockModel.query).toHaveBeenCalledWith("tenantId");
+      expect(customMockQuery.eq).toHaveBeenCalledWith("tenant-123");
     });
   });
 
@@ -132,7 +278,7 @@ describe("GridQueryBuilder", () => {
         model: mockModel,
         partitionKeyValue: "ORG#123",
         filterModel,
-        paginationModel: { pageSize: 20 },
+        limit: 20,
       });
 
       expect(mockQuery.where).toHaveBeenCalledWith("status");
@@ -150,7 +296,7 @@ describe("GridQueryBuilder", () => {
         model: mockModel,
         partitionKeyValue: "ORG#123",
         filterModel,
-        paginationModel: { pageSize: 20 },
+        limit: 20,
       });
 
       expect(mockQuery.where).toHaveBeenCalledWith("createdAt");
@@ -172,7 +318,7 @@ describe("GridQueryBuilder", () => {
         model: mockModel,
         partitionKeyValue: "ORG#123",
         filterModel,
-        paginationModel: { pageSize: 20 },
+        limit: 20,
       });
 
       expect(mockQuery.between).toHaveBeenCalledWith("2024-01-01", "2024-12-31");
@@ -187,7 +333,7 @@ describe("GridQueryBuilder", () => {
         model: mockModel,
         partitionKeyValue: "ORG#123",
         filterModel,
-        paginationModel: { pageSize: 20 },
+        limit: 20,
       });
 
       expect(mockQuery.using).toHaveBeenCalledWith("status-createdAt-index");
@@ -203,7 +349,7 @@ describe("GridQueryBuilder", () => {
           model: mockModel,
           partitionKeyValue: "ORG#123",
           filterModel,
-          paginationModel: { pageSize: 20 },
+          limit: 20,
         });
       }).toThrow("Filtering not allowed");
     });
@@ -218,7 +364,7 @@ describe("GridQueryBuilder", () => {
           model: mockModel,
           partitionKeyValue: "ORG#123",
           filterModel,
-          paginationModel: { pageSize: 20 },
+          limit: 20,
         });
       }).toThrow("not allowed");
     });
@@ -242,7 +388,7 @@ describe("GridQueryBuilder", () => {
         model: mockModel,
         partitionKeyValue: "ORG#123",
         sortModel,
-        paginationModel: { pageSize: 20 },
+        limit: 20,
       });
 
       expect(mockQuery.sort).toHaveBeenCalledWith("descending");
@@ -255,7 +401,7 @@ describe("GridQueryBuilder", () => {
         model: mockModel,
         partitionKeyValue: "ORG#123",
         sortModel,
-        paginationModel: { pageSize: 20 },
+        limit: 20,
       });
 
       // Ascending is default, so sort() should not be called
@@ -273,7 +419,7 @@ describe("GridQueryBuilder", () => {
           model: mockModel,
           partitionKeyValue: "ORG#123",
           sortModel,
-          paginationModel: { pageSize: 20 },
+          limit: 20,
         });
       }).toThrow(/sorting by one field/);
     });
@@ -286,13 +432,13 @@ describe("GridQueryBuilder", () => {
           model: mockModel,
           partitionKeyValue: "ORG#123",
           sortModel,
-          paginationModel: { pageSize: 20 },
+          limit: 20,
         });
       }).toThrow("Sorting not allowed");
     });
   });
 
-  describe("buildGridQuery - Pagination", () => {
+  describe("buildGridQuery - Limit and Cursor", () => {
     let mockModel;
     let mockQuery;
 
@@ -303,11 +449,11 @@ describe("GridQueryBuilder", () => {
       mockModel.query = vi.fn(() => mockQuery);
     });
 
-    it("should apply page size limit", () => {
+    it("should apply limit", () => {
       buildGridQuery({
         model: mockModel,
         partitionKeyValue: "ORG#123",
-        paginationModel: { pageSize: 50 },
+        limit: 50,
       });
 
       expect(mockQuery.limit).toHaveBeenCalledWith(50);
@@ -320,7 +466,7 @@ describe("GridQueryBuilder", () => {
       const firstResult = buildGridQuery({
         model: mockModel,
         partitionKeyValue: "ORG#123",
-        paginationModel: { pageSize: 20 },
+        limit: 20,
       });
 
       // Create cursor with the actual queryHash
@@ -332,7 +478,7 @@ describe("GridQueryBuilder", () => {
       buildGridQuery({
         model: mockModel,
         partitionKeyValue: "ORG#123",
-        paginationModel: { pageSize: 20 },
+        limit: 20,
         cursor,
       });
 
@@ -351,7 +497,7 @@ describe("GridQueryBuilder", () => {
         buildGridQuery({
           model: mockModel,
           partitionKeyValue: "ORG#123",
-          paginationModel: { pageSize: 50 }, // Different page size
+          limit: 50, // Different limit
           cursor,
         });
       }).toThrow("Cursor does not match");
@@ -374,7 +520,7 @@ describe("GridQueryBuilder", () => {
           items: [{ field: "status", operator: "eq", value: "active" }],
         },
         sortModel: [{ field: "createdAt", sort: "desc" }],
-        paginationModel: { pageSize: 20 },
+        limit: 20,
       };
 
       const result1 = buildGridQuery(params);
@@ -387,7 +533,7 @@ describe("GridQueryBuilder", () => {
       const baseParams = {
         model: mockModel,
         partitionKeyValue: "ORG#123",
-        paginationModel: { pageSize: 20 },
+        limit: 20,
       };
 
       const result1 = buildGridQuery({
@@ -407,7 +553,7 @@ describe("GridQueryBuilder", () => {
       expect(result1.queryHash).not.toBe(result2.queryHash);
     });
 
-    it("should return different hash when page size changes", () => {
+    it("should return different hash when limit changes", () => {
       const baseParams = {
         model: mockModel,
         partitionKeyValue: "ORG#123",
@@ -415,12 +561,12 @@ describe("GridQueryBuilder", () => {
 
       const result1 = buildGridQuery({
         ...baseParams,
-        paginationModel: { pageSize: 20 },
+        limit: 20,
       });
 
       const result2 = buildGridQuery({
         ...baseParams,
-        paginationModel: { pageSize: 50 },
+        limit: 50,
       });
 
       expect(result1.queryHash).not.toBe(result2.queryHash);
@@ -438,7 +584,7 @@ describe("GridQueryBuilder", () => {
       mockModel.query = vi.fn(() => mockQuery);
     });
 
-    it("should handle query with filter, sort, and pagination", () => {
+    it("should handle query with filter, sort, and limit", () => {
       buildGridQuery({
         model: mockModel,
         partitionKeyValue: "ORG#123",
@@ -446,7 +592,7 @@ describe("GridQueryBuilder", () => {
           items: [{ field: "status", operator: "eq", value: "active" }],
         },
         sortModel: [{ field: "createdAt", sort: "desc" }],
-        paginationModel: { pageSize: 25 },
+        limit: 25,
       });
 
       // Verify all operations were applied
@@ -464,7 +610,7 @@ describe("GridQueryBuilder", () => {
         partitionKeyValue: "ORG#123",
         filterModel: { items: [] },
         sortModel: [],
-        paginationModel: { pageSize: 20 },
+        limit: 20,
       });
 
       expect(query).toBeDefined();