dynamo-query-engine 1.0.2 → 1.0.4

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.2",
+  "version": "1.0.4",
   "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

@@ -46,6 +46,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
@@ -181,6 +215,9 @@ export function buildGridQuery({
   // 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);
 
@@ -192,7 +229,7 @@ export function buildGridQuery({
   });
 
   // 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) {

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/src/utils/validation.js

@@ -83,22 +83,65 @@ export function validateExpandField(field, gridConfig) {
 }
 
 /**
- * Validates pagination model
+ * Validates pagination model and ensures numeric types
  * @param {PaginationModel} paginationModel - Pagination model to validate
  * @throws {Error} If pagination model is invalid
+ * @returns {PaginationModel} Normalized pagination model with numeric values
  */
 export function validatePaginationModel(paginationModel) {
   if (!paginationModel) {
     throw new Error("paginationModel is required");
   }
 
-  if (!paginationModel.pageSize || paginationModel.pageSize < 1) {
+  // Check if pageSize exists first
+  if (!paginationModel.pageSize) {
     throw new Error("paginationModel.pageSize must be a positive number");
   }
 
-  if (paginationModel.pageSize > 1000) {
+  // Convert pageSize to number if it's a string
+  let pageSize = paginationModel.pageSize;
+  if (typeof pageSize === "string") {
+    pageSize = Number(pageSize);
+    if (isNaN(pageSize)) {
+      throw new Error(
+        `paginationModel.pageSize must be a valid number, received '${paginationModel.pageSize}'`
+      );
+    }
+    // Mutate the original object to ensure downstream code uses the number
+    paginationModel.pageSize = pageSize;
+  } else if (typeof pageSize !== "number") {
+    throw new Error(
+      `paginationModel.pageSize must be a number, received ${typeof pageSize}`
+    );
+  }
+
+  if (pageSize < 1) {
+    throw new Error("paginationModel.pageSize must be a positive number");
+  }
+
+  if (pageSize > 1000) {
     throw new Error(
       "paginationModel.pageSize cannot exceed 1000 (DynamoDB limit)"
     );
   }
+
+  // Convert page to number if it exists and is a string
+  if (paginationModel.page !== undefined) {
+    let page = paginationModel.page;
+    if (typeof page === "string") {
+      page = Number(page);
+      if (isNaN(page)) {
+        throw new Error(
+          `paginationModel.page must be a valid number, received '${paginationModel.page}'`
+        );
+      }
+      paginationModel.page = page;
+    } else if (typeof page !== "number") {
+      throw new Error(
+        `paginationModel.page must be a number, received ${typeof page}`
+      );
+    }
+  }
+
+  return paginationModel;
 }

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;
@@ -110,6 +226,35 @@ describe("GridQueryBuilder", () => {
         });
       }).toThrow("paginationModel is required");
     });
+
+    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",
+        paginationModel: { pageSize: 20 },
+      });
+
+      // Should query with 'tenantId' not 'pk'
+      expect(customMockModel.query).toHaveBeenCalledWith("tenantId");
+      expect(customMockQuery.eq).toHaveBeenCalledWith("tenant-123");
+    });
   });
 
   describe("buildGridQuery - Filtering", () => {

package/tests/unit/validation.test.js

@@ -311,6 +311,67 @@ describe("Validation Utils", () => {
         validatePaginationModel({ pageSize: 2000 });
       }).toThrow(/DynamoDB limit/);
     });
+
+    describe("String to Number Conversion", () => {
+      it("should convert pageSize string to number", () => {
+        const paginationModel = { pageSize: "25" };
+        validatePaginationModel(paginationModel);
+        expect(paginationModel.pageSize).toBe(25);
+        expect(typeof paginationModel.pageSize).toBe("number");
+      });
+
+      it("should convert page string to number", () => {
+        const paginationModel = { pageSize: 25, page: "1" };
+        validatePaginationModel(paginationModel);
+        expect(paginationModel.page).toBe(1);
+        expect(typeof paginationModel.page).toBe("number");
+      });
+
+      it("should convert both pageSize and page strings to numbers", () => {
+        const paginationModel = { pageSize: "50", page: "2" };
+        validatePaginationModel(paginationModel);
+        expect(paginationModel.pageSize).toBe(50);
+        expect(paginationModel.page).toBe(2);
+        expect(typeof paginationModel.pageSize).toBe("number");
+        expect(typeof paginationModel.page).toBe("number");
+      });
+
+      it("should throw error for invalid pageSize string", () => {
+        expect(() => {
+          validatePaginationModel({ pageSize: "abc" });
+        }).toThrow("must be a valid number");
+      });
+
+      it("should throw error for invalid page string", () => {
+        expect(() => {
+          validatePaginationModel({ pageSize: 25, page: "invalid" });
+        }).toThrow("must be a valid number");
+      });
+
+      it("should throw error for non-string, non-number pageSize", () => {
+        expect(() => {
+          validatePaginationModel({ pageSize: true });
+        }).toThrow("must be a number");
+      });
+
+      it("should throw error for object pageSize", () => {
+        expect(() => {
+          validatePaginationModel({ pageSize: { value: 25 } });
+        }).toThrow("must be a number");
+      });
+
+      it("should validate converted string pageSize against limits", () => {
+        expect(() => {
+          validatePaginationModel({ pageSize: "1001" });
+        }).toThrow("cannot exceed 1000");
+      });
+
+      it("should validate converted string pageSize is positive", () => {
+        expect(() => {
+          validatePaginationModel({ pageSize: "0" });
+        }).toThrow("must be a positive number");
+      });
+    });
   });
 
   describe("Edge Cases", () => {