dynamo-query-engine 1.0.7 → 1.0.9

package/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dynamo-query-engine",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "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/expandResolver.js

@@ -35,7 +35,9 @@ export async function resolveExpand({
   field,
   args = {},
 }) {
+
   if (!parentItems || parentItems.length === 0) {
+    console.log(`[expandResolver] No parent items, skipping expand for field: ${field}`);
     return;
   }
 
@@ -52,11 +54,13 @@ export async function resolveExpand({
   const policy = expandPolicy[field];
 
   if (!policy) {
+    console.error(`[expandResolver] Field '${field}' does not have expand configuration`);
     throw new Error(
       `Field '${field}' does not have expand configuration in parent model`
     );
   }
 
+  
   // Get target model from registry
   const targetModel = modelRegistry.get(policy.type);
 
@@ -77,12 +81,20 @@ export async function resolveExpand({
   const expandPromises = parentItems.map(async (parent) => {
     try {
       // Get partition key value from parent
-      // This should be either parent.pk or the first field (usually tenantId)
-      const partitionKeyValue = parent.pk || parent[Object.keys(parent)[0]];
+      // First, determine the target model's hash key name
+      const targetAttributes = targetModel.schema.getAttributes();
+      const targetHashKeyName = Object.keys(targetAttributes).find(
+        (key) => targetAttributes[key].hashKey === true
+      );
+      
+      
+      // Get the partition key value from the parent using the target's hash key name
+      const partitionKeyValue = parent[targetHashKeyName];
 
+      
       if (!partitionKeyValue) {
         console.warn(
-          `Cannot expand '${field}' for parent: missing partition key value`
+          `[expandResolver] Cannot expand '${field}' for parent: missing partition key value`
         );
         parent[expandPropertyName] = policy.relation === "ONE" ? null : [];
         return;
@@ -96,7 +108,7 @@ export async function resolveExpand({
         
         if (!foreignKeyValue) {
           console.warn(
-            `Cannot expand '${field}' for parent: missing foreign key value '${policy.foreignKey}'`
+            `[expandResolver] Cannot expand '${field}' for parent: missing foreign key value '${policy.foreignKey}'`
           );
           parent[expandPropertyName] = null;
           return;
@@ -110,7 +122,7 @@ export async function resolveExpand({
 
         if (!rangeKeyName) {
           console.warn(
-            `Cannot expand '${field}': target model '${policy.type}' has no range key defined`
+            `[expandResolver] Cannot expand '${field}': target model '${policy.type}' has no range key defined`
           );
           parent[expandPropertyName] = null;
           return;
@@ -121,11 +133,12 @@ export async function resolveExpand({
           items: [
             {
               field: rangeKeyName,
-              operator: "equals",
+              operator: "eq",
               value: foreignKeyValue,
             },
           ],
         });
+      
 
         const { query } = buildGridQuery({
           model: targetModel,
@@ -155,6 +168,7 @@ export async function resolveExpand({
         __typename: graphqlTypeName,
       }));
 
+ 
       // Assign results to parent
       if (policy.relation === "ONE") {
         parent[expandPropertyName] = resultsWithTypename.length > 0 ? resultsWithTypename[0] : null;
@@ -162,7 +176,8 @@ export async function resolveExpand({
         parent[expandPropertyName] = resultsWithTypename;
       }
     } catch (error) {
-      console.error(`Error expanding '${field}' for parent:`, error);
+      console.error(`[expandResolver] Error expanding '${field}' for parent:`, error);
+      console.error(`[expandResolver] Error stack:`, error.stack);
       // Gracefully handle errors - set empty result
       parent[expandPropertyName] = policy.relation === "ONE" ? null : [];
     }
@@ -193,19 +208,99 @@ function createGraphQLToSchemaFieldMap(schema) {
   return map;
 }
 
+/**
+ * Parse AppSync selectionSetList to extract requested expand fields
+ * @param {string[]} selectionSetList - AppSync selectionSetList array
+ * @param {string} parentPath - Parent path prefix (e.g., "rows")
+ * @returns {Set<string>} Set of field names that were requested
+ */
+function parseAppSyncSelectionSet(selectionSetList, parentPath = "rows") {
+  const requestedFields = new Set();
+  const prefix = parentPath + "/";
+  
+  for (const path of selectionSetList) {
+    if (path.startsWith(prefix)) {
+      const afterPrefix = path.substring(prefix.length);
+      const firstSlash = afterPrefix.indexOf("/");
+      
+      if (firstSlash === -1) {
+        // This is a direct child field (e.g., "rows/unitId")
+        requestedFields.add(afterPrefix);
+      } else {
+        // This is a nested field (e.g., "rows/Unit/name")
+        const fieldName = afterPrefix.substring(0, firstSlash);
+        requestedFields.add(fieldName);
+      }
+    }
+  }
+  
+  return requestedFields;
+}
+
 /**
  * Resolve multiple expands from GraphQL resolve info
  * @param {Array} parentItems - Parent items to expand
  * @param {*} parentModel - Parent Dynamoose model
- * @param {Object} fieldsByTypeName - Fields by type name from graphql-parse-resolve-info
+ * @param {Object|string[]} fieldsByTypeName - Fields by type name from graphql-parse-resolve-info OR AppSync selectionSetList
+ * @param {Object} [options] - Additional options
+ * @param {boolean} [options.isAppSync] - Whether to parse AppSync selectionSetList format
+ * @param {string} [options.parentPath] - Parent path for AppSync (default: "rows")
  * @returns {Promise<void>}
  */
 export async function resolveExpands(
   parentItems,
   parentModel,
-  fieldsByTypeName
+  fieldsByTypeName,
+  options = {}
 ) {
+  const { isAppSync = false, parentPath = "rows" } = options;
+
+  // Handle AppSync format
+  if (isAppSync) {
+    const selectionSetList = fieldsByTypeName;
+    
+    if (!selectionSetList || selectionSetList.length === 0) {
+      console.log(`[expandResolver] No selectionSetList, skipping`);
+      return;
+    }
+
+    // Parse AppSync selection set to find requested fields
+    const requestedFields = parseAppSyncSelectionSet(selectionSetList, parentPath);
+
+    // Get expand policy to filter only expandable fields
+    const expandPolicy = extractExpandPolicy(parentModel.schema);
+
+    // Create mapping from GraphQL field names to schema field names
+    const graphqlToSchemaMap = createGraphQLToSchemaFieldMap(parentModel.schema);
+
+    // Resolve all expands in parallel
+    const expandPromises = Array.from(requestedFields)
+      .map((graphqlFieldName) => {
+        // Map GraphQL field name to schema field name
+        const schemaFieldName = graphqlToSchemaMap[graphqlFieldName];
+        
+        // Check if this field is expandable
+        if (!schemaFieldName || !expandPolicy[schemaFieldName]) {
+          console.log(`[expandResolver] Field '${graphqlFieldName}' is not expandable (schemaFieldName: ${schemaFieldName}, has policy: ${!!expandPolicy[schemaFieldName]})`);
+          return null;
+        }
+
+        return resolveExpand({
+          parentItems,
+          parentModel,
+          field: schemaFieldName,
+          args: {},
+        });
+      })
+      .filter(Boolean); // Remove null entries
+
+    await Promise.all(expandPromises);
+    return;
+  }
+
+  // Handle standard graphql-parse-resolve-info format
   if (!fieldsByTypeName || Object.keys(fieldsByTypeName).length === 0) {
+    console.log(`[expandResolver] No fieldsByTypeName, skipping`);
     return;
   }
 
@@ -214,12 +309,13 @@ export async function resolveExpands(
   const fields = fieldsByTypeName[typeName];
 
   if (!fields) {
+    console.log(`[expandResolver] No fields found for type ${typeName}`);
     return;
   }
 
   // Get expand policy to filter only expandable fields
   const expandPolicy = extractExpandPolicy(parentModel.schema);
-  
+
   // Create mapping from GraphQL field names to schema field names
   const graphqlToSchemaMap = createGraphQLToSchemaFieldMap(parentModel.schema);
 
@@ -231,6 +327,7 @@ export async function resolveExpands(
       
       // Check if this field is expandable
       if (!schemaFieldName || !expandPolicy[schemaFieldName]) {
+        console.log(`[expandResolver] Field '${graphqlFieldName}' is not expandable (schemaFieldName: ${schemaFieldName}, has policy: ${!!expandPolicy[schemaFieldName]})`);
         return null;
       }
 

package/src/core/gridQueryBuilder.js

@@ -10,7 +10,7 @@ import {
   validateSortField,
   validateFilterOperator,
 } from "../utils/validation.js";
-import { decodeCursor, validateCursor } from "../utils/cursor.js";
+import { decodeCursor, validateCursor, encodeCursor } from "../utils/cursor.js";
 
 /**
  * Generate a hash for query parameters to validate cursor consistency
@@ -52,13 +52,13 @@ export function extractGridConfig(schema) {
  */
 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");
 }
 
@@ -69,18 +69,19 @@ export function getHashKey(schema) {
  */
 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
+ * Only uses index if explicitly configured in grid config
  * @param {FilterModel} filterModel - Filter model
  * @param {ExtractedGridConfig} gridConfig - Grid configuration
  * @returns {string|null} GSI name or null
@@ -90,7 +91,7 @@ function determineIndex(filterModel, gridConfig) {
     return null;
   }
 
-  // Find the first filter with an index
+  // Find the first filter with an explicit index configuration
   for (const filterItem of filterModel.items) {
     const fieldConfig = gridConfig[filterItem.field]?.filter;
     if (fieldConfig && fieldConfig.index) {
@@ -101,6 +102,35 @@ function determineIndex(filterModel, gridConfig) {
   return null;
 }
 
+/**
+ * Find the index name where the given field is used as rangeKey
+ * @param {string} sortField - The field name to sort by
+ * @param {*} schema - Dynamoose schema
+ * @returns {string|null} Index name or null if no index found
+ */
+function findIndexForSortField(sortField, schema) {
+  const attributes = schema.getAttributes();
+
+  // Iterate through all attributes to find an index that uses sortField as rangeKey
+  for (const definition of Object.values(attributes)) {
+    // Check if this attribute has an index configuration
+    if (definition.index) {
+      const indexes = Array.isArray(definition.index)
+        ? definition.index
+        : [definition.index];
+
+      for (const idx of indexes) {
+        // Check if this index has the sortField as its rangeKey
+        if (idx.rangeKey === sortField) {
+          return idx.name;
+        }
+      }
+    }
+  }
+
+  return null;
+}
+
 /**
  * Apply filters to the query
  * @param {*} query - Dynamoose query object
@@ -114,30 +144,38 @@ function applyFilters(query, filterModel, gridConfig) {
   }
 
   for (const filterItem of filterModel.items) {
-    validateFilterField(filterItem.field, gridConfig);
+    // Only validate operator restrictions if field has explicit filter config
     validateFilterOperator(filterItem.field, filterItem.operator, gridConfig);
 
     // Apply the filter using Dynamoose query syntax
     query = query.where(filterItem.field);
 
-    // Map operators to Dynamoose methods
+    // Map operators to Dynamoose methods (support both short and long forms)
     switch (filterItem.operator) {
+      case "equals":
       case "eq":
         query = query.eq(filterItem.value);
         break;
+      case "notEquals":
       case "ne":
         query = query.ne(filterItem.value);
         break;
+      case "greaterThan":
       case "gt":
         query = query.gt(filterItem.value);
         break;
+      case "greaterThanOrEqualTo":
       case "gte":
+      case "ge":
         query = query.ge(filterItem.value);
         break;
+      case "lessThan":
       case "lt":
         query = query.lt(filterItem.value);
         break;
+      case "lessThanOrEqualTo":
       case "lte":
+      case "le":
         query = query.le(filterItem.value);
         break;
       case "between":
@@ -164,26 +202,57 @@ function applyFilters(query, filterModel, gridConfig) {
   return query;
 }
 
+/**
+ * Determine which index to use based on sort model
+ * @param {SortModel} sortModel - Sort model
+ * @param {ExtractedGridConfig} gridConfig - Grid configuration
+ * @param {*} schema - Dynamoose schema
+ * @returns {string|null} Index name or null if no index needed
+ */
+function determineSortIndex(sortModel, gridConfig, schema) {
+  if (!sortModel || sortModel.length === 0) {
+    return null;
+  }
+
+  const sortItem = sortModel[0];
+  validateSortField(sortItem.field, gridConfig);
+
+  // Find the index where this field is used as rangeKey
+  const indexName = findIndexForSortField(sortItem.field, schema);
+
+  if (!indexName) {
+    // Check if it's the main table's range key (no index needed)
+    const rangeKey = getRangeKey(schema);
+    if (sortItem.field === rangeKey) {
+      return null; // No index needed, it's the main range key
+    }
+
+    throw new Error(
+      `No index found for sorting by field '${sortItem.field}'. ` +
+      `Make sure an index exists with '${sortItem.field}' as rangeKey.`
+    );
+  }
+
+  return indexName;
+}
+
 /**
  * Apply sorting to the query
  * @param {*} query - Dynamoose query object
  * @param {SortModel} sortModel - Sort model
- * @param {ExtractedGridConfig} gridConfig - Grid configuration
  * @returns {*} Updated query object
  */
-function applySort(query, sortModel, gridConfig) {
+function applySort(query, sortModel) {
   if (!sortModel || sortModel.length === 0) {
     return query;
   }
 
   const sortItem = sortModel[0];
-  validateSortField(sortItem.field, gridConfig);
 
-  // Apply descending sort if specified
+  // Only apply sort if descending (ascending is the default)
   if (sortItem.sort === "desc") {
     query = query.sort("descending");
   }
-  // Default is ascending, no need to explicitly set
 
   return query;
 }
@@ -208,7 +277,7 @@ export function buildGridQuery({
   if (!partitionKeyValue) {
     throw new Error("partitionKeyValue is required");
   }
-  
+
   // Validate and normalize limit
   if (limit !== undefined && limit !== null) {
     const numLimit = typeof limit === "string" ? Number(limit) : limit;
@@ -216,13 +285,13 @@ export function buildGridQuery({
       throw new Error("limit must be a positive number");
     }
     if (numLimit > 1000) {
-      throw new Error("limit cannot exceed 1000 (DynamoDB limit)");
+      throw new Error("limit cannot exceed 1000");
     }
     limit = numLimit;
   } else {
     limit = 10;
   }
-  
+
   validateSingleSort(sortModel);
 
   // Extract grid config from schema
@@ -231,8 +300,23 @@ export function buildGridQuery({
   // Get the hash key field name from schema
   const hashKeyField = getHashKey(model.schema);
 
-  // Determine which index to use
-  const index = determineIndex(filterModel, gridConfig);
+  // Determine which index to use - prioritize sort index
+  // Prefer sort index when sorting is requested, as DynamoDB returns results efficiently
+  // and consistently ordered by the sort key.
+  // Use filter index only when no sorting is needed for optimal query performance and consistency.
+  const sortIndex = determineSortIndex(sortModel, gridConfig, model.schema);
+  const filterIndex = determineIndex(filterModel, gridConfig);
+
+  // Decide which index to use - sort takes priority
+  let index = sortIndex || filterIndex;
+
+  // Validate that filter and sort are compatible if both exist
+  if (sortIndex && filterIndex && sortIndex !== filterIndex) {
+    throw new Error(
+      `Cannot use different indexes for filtering ('${filterIndex}') and sorting ('${sortIndex}'). ` +
+      `Ensure your filters and sort use compatible indexes.`
+    );
+  }
 
   // Generate query hash for cursor validation
   const queryHash = hashQuery({
@@ -253,7 +337,7 @@ export function buildGridQuery({
   query = applyFilters(query, filterModel, gridConfig);
 
   // Apply sort
-  query = applySort(query, sortModel, gridConfig);
+  query = applySort(query, sortModel);
 
   // Apply limit
   query = query.limit(limit);
@@ -267,3 +351,120 @@ export function buildGridQuery({
 
   return { query, queryHash };
 }
+
+/**
+ * Execute grid query with automatic page filling when filters reduce results
+ * This function handles DynamoDB's behavior of applying limit before filters,
+ * which can result in pages with fewer items than requested.
+ * 
+ * @param {BuildGridQueryOptions} options - Query build options
+ * @returns {Promise<ExecuteGridQueryResult>} Query results with items and cursor
+ */
+export async function executeGridQuery(options) {
+  const {
+    model,
+    partitionKeyValue,
+    filterModel,
+    sortModel,
+    limit = 10,
+    cursor,
+  } = options;
+
+  const results = [];
+  let currentCursor = cursor;
+  let lastKey = null;
+  let hasMorePages = true;
+  const maxIterations = 10; // Safety limit to prevent infinite loops
+  let iterations = 0;
+
+  // Generate the original query hash once (with the original limit)
+  const originalQueryHash = hashQuery({
+    filterModel,
+    sortModel,
+    limit,
+  });
+
+  // Continue fetching until we have enough results or no more data
+  while (results.length < limit && hasMorePages && iterations < maxIterations) {
+    iterations++;
+
+    // Calculate how many more items we need
+    const remainingNeeded = limit - results.length;
+    
+    // Build query - we'll manually apply the cursor to avoid hash mismatch
+    const gridConfig = extractGridConfig(model.schema);
+    const hashKeyField = getHashKey(model.schema);
+    const sortIndex = determineSortIndex(sortModel, gridConfig, model.schema);
+    const filterIndex = determineIndex(filterModel, gridConfig);
+    let index = sortIndex || filterIndex;
+
+    // Validate that filter and sort are compatible if both exist
+    if (sortIndex && filterIndex && sortIndex !== filterIndex) {
+      throw new Error(
+        `Cannot use different indexes for filtering ('${filterIndex}') and sorting ('${sortIndex}'). ` +
+        `Ensure your filters and sort use compatible indexes.`
+      );
+    }
+
+    // Initialize query with partition key
+    let query = model.query(hashKeyField).eq(partitionKeyValue);
+
+    // Use GSI if needed
+    if (index) {
+      query = query.using(index);
+    }
+
+    // Apply filters
+    query = applyFilters(query, filterModel, gridConfig);
+
+    // Apply sort
+    query = applySort(query, sortModel);
+
+    // Apply limit
+    query = query.limit(remainingNeeded);
+
+    // Handle cursor for pagination
+    if (currentCursor) {
+      const decoded = decodeCursor(currentCursor);
+      validateCursor(decoded.queryHash, originalQueryHash);
+      query = query.startAt(decoded.lastKey);
+    }
+
+    // Execute query
+    const response = await query.exec();
+
+    // Add results
+    if (response && response.length > 0) {
+      results.push(...response);
+    }
+
+    // Get lastKey from the response
+    lastKey = response.lastKey;
+
+    // Check if there are more pages
+    hasMorePages = !!lastKey;
+
+    // If we have more pages, prepare cursor for next iteration
+    if (hasMorePages && results.length < limit) {
+      currentCursor = encodeCursor(lastKey, originalQueryHash);
+    } else {
+      break;
+    }
+  }
+
+  // Trim results to exact limit if we fetched more
+  const finalResults = results.slice(0, limit);
+
+  // Generate final cursor
+  let nextCursor = null;
+  if (lastKey && results.length >= limit) {
+    nextCursor = encodeCursor(lastKey, originalQueryHash);
+  }
+
+  return {
+    items: finalResults,
+    cursor: nextCursor,
+    hasMore: !!nextCursor,
+  };
+}
+

package/src/core/index.js

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

package/src/types/jsdoc.js

@@ -87,6 +87,14 @@
  * @property {string} queryHash - Hash of the query parameters
  */
 
+/**
+ * Execute grid query result
+ * @typedef {Object} ExecuteGridQueryResult
+ * @property {Array} items - Query result items
+ * @property {string|null} cursor - Base64 encoded cursor for next page
+ * @property {boolean} hasMore - Whether there are more pages available
+ */
+
 /**
  * Expand arguments from GraphQL
  * @typedef {Object} ExpandArgs

package/src/utils/validation.js

@@ -19,17 +19,14 @@ export function validateSingleSort(sortModel) {
 
 /**
  * Validates that a field can be filtered based on grid config
+ * This function now only checks if a field has filter configuration, but doesn't throw
  * @param {string} field - Field name to filter
  * @param {Object.<string, import("../types/jsdoc.js").GridConfig>} gridConfig - Extracted grid configuration
- * @throws {Error} If filtering is not allowed on this field
+ * @returns {boolean} True if field has filter config, false otherwise
  */
 export function validateFilterField(field, gridConfig) {
   const config = gridConfig[field];
-  if (!config || !config.filter) {
-    throw new Error(
-      `Filtering not allowed on field '${field}'. Only fields with grid.filter config can be filtered.`
-    );
-  }
+  return !!(config && config.filter);
 }
 
 /**
@@ -42,28 +39,55 @@ export function validateSortField(field, gridConfig) {
   const config = gridConfig[field];
   if (!config || !config.sort) {
     throw new Error(
-      `Sorting not allowed on field '${field}'. Only fields with grid.sort config can be sorted.`
+      `Sorting not allowed on field '${field}'. Only fields with query.sort config can be sorted.`
     );
   }
 }
 
+/**
+ * Operator alias mapping (short form to long form)
+ */
+const OPERATOR_ALIASES = {
+  eq: "equals",
+  ne: "notEquals",
+  gt: "greaterThan",
+  gte: "greaterThanOrEqualTo",
+  ge: "greaterThanOrEqualTo",
+  lt: "lessThan",
+  lte: "lessThanOrEqualTo",
+  le: "lessThanOrEqualTo",
+};
+
 /**
  * Validates that operator is allowed for a filter field
+ * Only validates if the field has explicit operator restrictions in grid config
  * @param {string} field - Field name
  * @param {string} operator - Operator to validate
  * @param {Object.<string, import("../types/jsdoc.js").GridConfig>} gridConfig - Extracted grid configuration
- * @throws {Error} If operator is not allowed for this field
+ * @throws {Error} If field has operator restrictions and operator is not allowed
  */
 export function validateFilterOperator(field, operator, gridConfig) {
   const config = gridConfig[field]?.filter;
+  
+  // If no filter config exists, allow any operator
   if (!config) {
-    throw new Error(`Field '${field}' does not have filter configuration`);
+    return;
   }
 
-  if (config.operators && !config.operators.includes(operator)) {
-    throw new Error(
-      `Operator '${operator}' not allowed for field '${field}'. Allowed operators: ${config.operators.join(", ")}`
-    );
+  if (config.operators) {
+    // Normalize operator to long form if it's an alias
+    const normalizedOperator = OPERATOR_ALIASES[operator] || operator;
+    
+    // Check if either the original operator or normalized operator is allowed
+    const isAllowed =
+      config.operators.includes(operator) ||
+      config.operators.includes(normalizedOperator);
+
+    if (!isAllowed) {
+      throw new Error(
+        `Operator '${operator}' not allowed for field '${field}'. Allowed operators: ${config.operators.join(", ")}`
+      );
+    }
   }
 }
 

package/tests/unit/gridQueryBuilder.test.js

@@ -2,9 +2,11 @@
  * @fileoverview Tests for grid query builder
  */
 
+import crypto from "crypto";
 import { describe, it, expect, beforeEach, vi } from "vitest";
 import {
   buildGridQuery,
+  executeGridQuery,
   extractGridConfig,
   getHashKey,
   getRangeKey,
@@ -339,21 +341,6 @@ describe("GridQueryBuilder", () => {
       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,
-          limit: 20,
-        });
-      }).toThrow("Filtering not allowed");
-    });
-
     it("should throw error for invalid operator", () => {
       const filterModel = {
         items: [{ field: "status", operator: "contains", value: "test" }],
@@ -436,6 +423,76 @@ describe("GridQueryBuilder", () => {
         });
       }).toThrow("Sorting not allowed");
     });
+
+    it("should use index for sort field with rangeKey", () => {
+      // Create a schema with a field that has an index with rangeKey
+      const attributesWithSortIndex = {
+        ...mockAttributes,
+        externalId: {
+          type: String,
+          query: {
+            sort: { type: "key" },
+          },
+        },
+        tenantId: {
+          type: String,
+          hashKey: true,
+          index: [
+            {
+              name: "byExternalId",
+              global: true,
+              rangeKey: "externalId",
+            },
+          ],
+        },
+      };
+
+      const schema = createMockSchema(attributesWithSortIndex);
+      const mockQuery = createMockQuery([]);
+      const mockModel = createMockModel(schema, []);
+      mockModel.query = vi.fn(() => mockQuery);
+
+      const sortModel = [{ field: "externalId", sort: "desc" }];
+
+      buildGridQuery({
+        model: mockModel,
+        partitionKeyValue: "TENANT#123",
+        sortModel,
+        limit: 20,
+      });
+
+      // Should use the index
+      expect(mockQuery.using).toHaveBeenCalledWith("byExternalId");
+      // Should apply descending sort
+      expect(mockQuery.sort).toHaveBeenCalledWith("descending");
+    });
+
+    it("should throw error when no index found for sort field", () => {
+      // Create a schema with a sort field but no index
+      const attributesWithoutIndex = {
+        ...mockAttributes,
+        fieldWithoutIndex: {
+          type: String,
+          query: {
+            sort: { type: "key" },
+          },
+        },
+      };
+
+      const schema = createMockSchema(attributesWithoutIndex);
+      const mockModel = createMockModel(schema, []);
+
+      const sortModel = [{ field: "fieldWithoutIndex", sort: "desc" }];
+
+      expect(() => {
+        buildGridQuery({
+          model: mockModel,
+          partitionKeyValue: "ORG#123",
+          sortModel,
+          limit: 20,
+        });
+      }).toThrow(/No index found for sorting/);
+    });
   });
 
   describe("buildGridQuery - Limit and Cursor", () => {
@@ -617,4 +674,202 @@ describe("GridQueryBuilder", () => {
       expect(mockQuery.limit).toHaveBeenCalledWith(20);
     });
   });
+
+  describe("executeGridQuery - Page Filling", () => {
+    let mockModel;
+    let mockQuery;
+
+    beforeEach(() => {
+      const schema = createMockSchema(mockAttributes);
+      mockQuery = createMockQuery([]);
+      mockModel = createMockModel(schema, []);
+      mockModel.query = vi.fn(() => mockQuery);
+    });
+
+    it("should return full page when no filters reduce results", async () => {
+      // Mock query to return exactly the requested amount
+      const mockItems = [
+        { id: "1", name: "Item 1" },
+        { id: "2", name: "Item 2" },
+        { id: "3", name: "Item 3" },
+      ];
+      
+      mockQuery.exec = vi.fn().mockResolvedValue(
+        Object.assign(mockItems, { lastKey: null })
+      );
+
+      const result = await executeGridQuery({
+        model: mockModel,
+        partitionKeyValue: "ORG#123",
+        limit: 3,
+      });
+
+      expect(result.items).toHaveLength(3);
+      expect(result.hasMore).toBe(false);
+      expect(result.cursor).toBeNull();
+      expect(mockQuery.exec).toHaveBeenCalledTimes(1);
+    });
+
+    it("should make multiple requests to fill page when filters reduce results", async () => {
+      // First call returns 2 items (with more available)
+      const firstBatch = [
+        { id: "1", name: "Item 1" },
+        { id: "2", name: "Item 2" },
+      ];
+      
+      // Second call returns 3 more items
+      const secondBatch = [
+        { id: "3", name: "Item 3" },
+        { id: "4", name: "Item 4" },
+        { id: "5", name: "Item 5" },
+      ];
+
+      mockQuery.exec = vi.fn()
+        .mockResolvedValueOnce(
+          Object.assign(firstBatch, { lastKey: { pk: "ORG#123", sk: "2" } })
+        )
+        .mockResolvedValueOnce(
+          Object.assign(secondBatch, { lastKey: null })
+        );
+
+      const result = await executeGridQuery({
+        model: mockModel,
+        partitionKeyValue: "ORG#123",
+        limit: 5,
+      });
+
+      expect(result.items).toHaveLength(5);
+      expect(mockQuery.exec).toHaveBeenCalledTimes(2);
+    });
+
+    it("should stop at limit even if more data is available", async () => {
+      // First call returns 3 items (with more available)
+      const firstBatch = [
+        { id: "1", name: "Item 1" },
+        { id: "2", name: "Item 2" },
+        { id: "3", name: "Item 3" },
+      ];
+      
+      // Second call returns 4 more items
+      const secondBatch = [
+        { id: "4", name: "Item 4" },
+        { id: "5", name: "Item 5" },
+        { id: "6", name: "Item 6" },
+        { id: "7", name: "Item 7" },
+      ];
+
+      mockQuery.exec = vi.fn()
+        .mockResolvedValueOnce(
+          Object.assign(firstBatch, { lastKey: { pk: "ORG#123", sk: "3" } })
+        )
+        .mockResolvedValueOnce(
+          Object.assign(secondBatch, { lastKey: { pk: "ORG#123", sk: "7" } })
+        );
+
+      const result = await executeGridQuery({
+        model: mockModel,
+        partitionKeyValue: "ORG#123",
+        limit: 5,
+      });
+
+      expect(result.items).toHaveLength(5);
+      expect(result.hasMore).toBe(true);
+      expect(result.cursor).not.toBeNull();
+    });
+
+    it("should return cursor when more pages are available", async () => {
+      const mockItems = [
+        { id: "1", name: "Item 1" },
+        { id: "2", name: "Item 2" },
+        { id: "3", name: "Item 3" },
+      ];
+      
+      mockQuery.exec = vi.fn().mockResolvedValue(
+        Object.assign(mockItems, { lastKey: { pk: "ORG#123", sk: "3" } })
+      );
+
+      const result = await executeGridQuery({
+        model: mockModel,
+        partitionKeyValue: "ORG#123",
+        limit: 3,
+      });
+
+      expect(result.hasMore).toBe(true);
+      expect(result.cursor).not.toBeNull();
+      expect(typeof result.cursor).toBe("string");
+    });
+
+    it("should stop after max iterations to prevent infinite loops", async () => {
+      // Mock to always return empty results but with a lastKey
+      mockQuery.exec = vi.fn().mockResolvedValue(
+        Object.assign([], { lastKey: { pk: "ORG#123", sk: "1" } })
+      );
+
+      const result = await executeGridQuery({
+        model: mockModel,
+        partitionKeyValue: "ORG#123",
+        limit: 10,
+      });
+
+      expect(result.items).toHaveLength(0);
+      expect(mockQuery.exec).toHaveBeenCalledTimes(10); // maxIterations
+    });
+
+    it("should handle cursor-based pagination correctly", async () => {
+      const mockItems = [
+        { id: "4", name: "Item 4" },
+        { id: "5", name: "Item 5" },
+      ];
+      
+      mockQuery.exec = vi.fn().mockResolvedValue(
+        Object.assign(mockItems, { lastKey: null })
+      );
+
+      // Create a valid cursor with matching queryHash
+      const { encodeCursor } = await import("../../src/utils/cursor.js");
+      const queryHash = crypto
+        .createHash("sha256")
+        .update(JSON.stringify({ filterModel: undefined, sortModel: undefined, limit: 2 }))
+        .digest("hex");
+      const validCursor = encodeCursor({ pk: "ORG#123", sk: "3" }, queryHash);
+
+      const result = await executeGridQuery({
+        model: mockModel,
+        partitionKeyValue: "ORG#123",
+        limit: 2,
+        cursor: validCursor,
+      });
+
+      expect(result.items).toHaveLength(2);
+      expect(mockQuery.startAt).toHaveBeenCalled();
+    });
+
+    it("should respect filters and sort in all requests", async () => {
+      const firstBatch = [{ id: "1", status: "active" }];
+      const secondBatch = [{ id: "2", status: "active" }];
+
+      mockQuery.exec = vi.fn()
+        .mockResolvedValueOnce(
+          Object.assign(firstBatch, { lastKey: { pk: "ORG#123", sk: "1" } })
+        )
+        .mockResolvedValueOnce(
+          Object.assign(secondBatch, { lastKey: null })
+        );
+
+      await executeGridQuery({
+        model: mockModel,
+        partitionKeyValue: "ORG#123",
+        filterModel: {
+          items: [{ field: "status", operator: "eq", value: "active" }],
+        },
+        sortModel: [{ field: "createdAt", sort: "desc" }],
+        limit: 2,
+      });
+
+      // Should apply filter on both queries
+      expect(mockQuery.where).toHaveBeenCalledWith("status");
+      expect(mockQuery.eq).toHaveBeenCalledWith("active");
+      expect(mockQuery.sort).toHaveBeenCalledWith("descending");
+    });
+  });
 });

package/tests/unit/validation.test.js

@@ -79,34 +79,30 @@ describe("Validation Utils", () => {
       },
     };
 
-    it("should allow filtering on configured field", () => {
-      expect(() => {
-        validateFilterField("status", gridConfig);
-      }).not.toThrow();
+    it("should return true for filtering on configured field", () => {
+      const result = validateFilterField("status", gridConfig);
+      expect(result).toBe(true);
     });
 
-    it("should throw error for non-configured field", () => {
-      expect(() => {
-        validateFilterField("name", gridConfig);
-      }).toThrow("Filtering not allowed on field 'name'");
+    it("should return false for non-configured field", () => {
+      const result = validateFilterField("name", gridConfig);
+      expect(result).toBe(false);
     });
 
-    it("should throw error for field without filter config", () => {
+    it("should return false for field without filter config", () => {
       const configWithoutFilter = {
         name: {
           sort: { type: "key" },
         },
       };
 
-      expect(() => {
-        validateFilterField("name", configWithoutFilter);
-      }).toThrow("Filtering not allowed");
+      const result = validateFilterField("name", configWithoutFilter);
+      expect(result).toBe(false);
     });
 
-    it("should provide helpful error message", () => {
-      expect(() => {
-        validateFilterField("invalidField", gridConfig);
-      }).toThrow(/grid\.filter config/);
+    it("should return false for non-existent field", () => {
+      const result = validateFilterField("invalidField", gridConfig);
+      expect(result).toBe(false);
     });
   });
 
@@ -147,7 +143,7 @@ describe("Validation Utils", () => {
     it("should provide helpful error message", () => {
       expect(() => {
         validateSortField("invalidField", gridConfig);
-      }).toThrow(/grid\.sort config/);
+      }).toThrow(/query\.sort config/);
     });
   });
 
@@ -193,10 +189,14 @@ describe("Validation Utils", () => {
       }).toThrow("Operator 'gte' not allowed for field 'status'");
     });
 
-    it("should throw error for field without filter config", () => {
+    it("should allow any operator for field without filter config", () => {
       expect(() => {
         validateFilterOperator("nonexistent", "eq", gridConfig);
-      }).toThrow("does not have filter configuration");
+      }).not.toThrow();
+      
+      expect(() => {
+        validateFilterOperator("nonexistent", "contains", gridConfig);
+      }).not.toThrow();
     });
 
     it("should list allowed operators in error message", () => {
@@ -378,9 +378,8 @@ describe("Validation Utils", () => {
     it("should handle empty grid config", () => {
       const emptyConfig = {};
 
-      expect(() => {
-        validateFilterField("anyField", emptyConfig);
-      }).toThrow();
+      const filterResult = validateFilterField("anyField", emptyConfig);
+      expect(filterResult).toBe(false);
 
       expect(() => {
         validateSortField("anyField", emptyConfig);
@@ -400,11 +399,11 @@ describe("Validation Utils", () => {
         },
       };
 
-      expect(() => validateFilterField("field1", mixedConfig)).not.toThrow();
+      expect(validateFilterField("field1", mixedConfig)).toBe(true);
       expect(() => validateSortField("field2", mixedConfig)).not.toThrow();
       expect(() => validateExpandField("field3", mixedConfig)).not.toThrow();
 
-      expect(() => validateFilterField("field2", mixedConfig)).toThrow();
+      expect(validateFilterField("field2", mixedConfig)).toBe(false);
       expect(() => validateSortField("field1", mixedConfig)).toThrow();
     });
   });