dynamo-query-engine 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,392 @@
+# DynamoDB Query Engine
+
+Type-safe DynamoDB query builder for GraphQL with support for filtering, sorting, pagination, and relation expansion. Built on top of Dynamoose for seamless integration with AWS Lambda and serverless applications.
+
+## Features
+
+- **DynamoDB-native**: Only keys can be filtered/sorted (following DynamoDB best practices)
+- **Cursor-based pagination**: Efficient pagination with query hash validation
+- **Type-safe**: JSDoc type definitions for excellent IntelliSense support
+- **Expand support**: Declarative relation expansion with configurable limits
+- **Zero external config**: All metadata defined in your Dynamoose schemas
+- **AWS Lambda ready**: Optimized for serverless environments
+- **GraphQL integration**: Works seamlessly with GraphQL resolvers
+
+## Installation
+
+```bash
+npm install dynamo-query-engine
+```
+
+### Peer Dependencies
+
+```bash
+npm install dynamoose graphql graphql-parse-resolve-info
+```
+
+## Quick Start
+
+### 1. Define Models with Grid Configuration
+
+```javascript
+import dynamoose from "dynamoose";
+
+const UserSchema = new dynamoose.Schema({
+  pk: {
+    type: String,
+    hashKey: true,
+  },
+  createdAt: {
+    type: String,
+    rangeKey: true,
+    grid: {
+      sort: { type: "key" },
+      filter: {
+        type: "key",
+        operators: ["between", "gte", "lte"],
+      },
+    },
+  },
+  status: {
+    type: String,
+    index: {
+      name: "status-createdAt-index",
+      global: true,
+      rangeKey: "createdAt",
+    },
+    grid: {
+      filter: {
+        type: "key",
+        operators: ["eq"],
+        index: "status-createdAt-index",
+      },
+    },
+  },
+  teamIds: {
+    type: Array,
+    schema: [String],
+    grid: {
+      expand: {
+        type: "Team",
+        relation: "MANY",
+        defaultLimit: 5,
+        maxLimit: 20,
+      },
+    },
+  },
+});
+
+export const UserModel = dynamoose.model("Users", UserSchema);
+```
+
+### 2. Register Models
+
+```javascript
+import { modelRegistry } from "dynamo-query-engine";
+import { UserModel } from "./models/user.model.js";
+import { TeamModel } from "./models/team.model.js";
+
+modelRegistry.register("User", UserModel);
+modelRegistry.register("Team", TeamModel);
+```
+
+### 3. Use in Lambda Resolver
+
+```javascript
+import { 
+  buildGridQuery, 
+  resolveExpands, 
+  encodeCursor 
+} from "dynamo-query-engine";
+import { parseResolveInfo } from "graphql-parse-resolve-info";
+
+export const handler = async (event) => {
+  const args = event.arguments;
+
+  // Build query
+  const { query, queryHash } = buildGridQuery({
+    model: UserModel,
+    partitionKeyValue: "ORG#123",
+    filterModel: args.filterModel,
+    sortModel: args.sortModel,
+    paginationModel: args.paginationModel,
+    cursor: args.cursor,
+  });
+
+  // Execute
+  const users = await query.exec();
+
+  // Resolve relations
+  const parsed = parseResolveInfo(event.info);
+  await resolveExpands(users, UserModel, parsed?.fieldsByTypeName);
+
+  // Return with cursor
+  return {
+    rows: users,
+    nextCursor: users.lastKey 
+      ? encodeCursor(users.lastKey, queryHash) 
+      : null,
+  };
+};
+```
+
+### 4. Query from Client
+
+```graphql
+query UsersGrid(
+  $paginationModel: PaginationInput!
+  $sortModel: [SortInput!]
+  $filterModel: FilterModelInput
+  $cursor: String
+) {
+  usersGrid(
+    paginationModel: $paginationModel
+    sortModel: $sortModel
+    filterModel: $filterModel
+    cursor: $cursor
+  ) {
+    rows {
+      firstName
+      lastName
+      email
+      teamIds {
+        name
+        status
+      }
+    }
+    nextCursor
+  }
+}
+```
+
+```javascript
+{
+  paginationModel: { pageSize: 20 },
+  sortModel: [{ field: "createdAt", sort: "desc" }],
+  filterModel: {
+    items: [
+      { field: "status", operator: "eq", value: "active" }
+    ]
+  }
+}
+```
+
+## Grid Configuration Options
+
+### Filter Configuration
+
+```javascript
+grid: {
+  filter: {
+    type: "key",                    // Only "key" supported
+    operators: ["eq", "gte", "lte"], // Allowed operators
+    index: "status-index"           // Optional GSI
+  }
+}
+```
+
+**Supported Operators**: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `between`, `beginsWith`, `contains`
+
+### Sort Configuration
+
+```javascript
+grid: {
+  sort: { type: "key" } // Only range keys can be sorted
+}
+```
+
+> **Note**: DynamoDB only supports sorting by one field (the range key).
+
+### Expand Configuration
+
+```javascript
+grid: {
+  expand: {
+    type: "Team",           // Model name (must be registered)
+    relation: "MANY",       // "ONE" or "MANY"
+    defaultLimit: 5,        // Default fetch limit
+    maxLimit: 20            // Maximum allowed limit
+  }
+}
+```
+
+## API Reference
+
+### Core Functions
+
+#### `buildGridQuery(options)`
+
+Builds a DynamoDB query from grid parameters.
+
+**Parameters:**
+- `model` - Dynamoose model
+- `partitionKeyValue` - Partition key value
+- `filterModel` - Filter configuration (optional)
+- `sortModel` - Sort configuration (optional)
+- `paginationModel` - Pagination configuration (required)
+- `cursor` - Pagination cursor (optional)
+
+**Returns:** `{ query, queryHash }`
+
+#### `resolveExpand(options)`
+
+Resolves a single relation expansion.
+
+**Parameters:**
+- `parentItems` - Array of parent items
+- `parentModel` - Parent Dynamoose model
+- `field` - Field name to expand
+- `args` - Expansion arguments (filter, sort, pagination)
+
+#### `resolveExpands(parentItems, parentModel, fieldsByTypeName)`
+
+Resolves multiple expansions from GraphQL resolve info.
+
+**Parameters:**
+- `parentItems` - Array of parent items
+- `parentModel` - Parent Dynamoose model
+- `fieldsByTypeName` - Parsed GraphQL resolve info fields
+
+### Utilities
+
+#### `encodeCursor(lastKey, queryHash)`
+
+Encodes pagination cursor to Base64.
+
+#### `decodeCursor(cursor)`
+
+Decodes Base64 cursor.
+
+#### `modelRegistry.register(name, model)`
+
+Registers a Dynamoose model.
+
+#### `modelRegistry.get(name)`
+
+Retrieves a registered model.
+
+## Architecture
+
+```
+┌─────────────┐
+│ GraphQL     │
+│ Query       │
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐
+│ Lambda      │
+│ Resolver    │
+└──────┬──────┘
+       │
+       ├──────► buildGridQuery() ──► DynamoDB
+       │                              │
+       │                              ▼
+       │                          ┌──────┐
+       │                          │ Items│
+       │                          └───┬──┘
+       │                              │
+       └──────► resolveExpands() ◄────┘
+                     │
+                     ├──► ModelRegistry
+                     │
+                     └──► buildGridQuery() ──► DynamoDB (nested)
+```
+
+## Examples
+
+Check out the [examples directory](./examples) for complete working examples:
+
+- **[User Model](./examples/models/user.model.js)** - Model with expand configuration
+- **[Team Model](./examples/models/team.model.js)** - Model with filter/sort configuration
+- **[Lambda Resolver](./examples/resolvers/usersGrid.resolver.js)** - Complete resolver implementation
+- **[GraphQL Queries](./examples/queries/graphql.js)** - Query examples and variables
+
+See the [examples README](./examples/README.md) for detailed documentation.
+
+## Best Practices
+
+### 1. Use Global Secondary Indexes for Filters
+
+```javascript
+status: {
+  type: String,
+  index: {
+    name: "status-createdAt-index",
+    global: true,
+    rangeKey: "createdAt",
+  },
+  grid: {
+    filter: {
+      type: "key",
+      operators: ["eq"],
+      index: "status-createdAt-index", // Use the GSI
+    },
+  },
+}
+```
+
+### 2. Validate User Input
+
+```javascript
+if (args.paginationModel.pageSize > 100) {
+  throw new Error("Page size cannot exceed 100");
+}
+```
+
+### 3. Handle Errors Gracefully
+
+```javascript
+try {
+  const { query } = buildGridQuery({...});
+  return await query.exec();
+} catch (error) {
+  console.error("Query failed:", error);
+  throw new Error(`Failed to fetch data: ${error.message}`);
+}
+```
+
+### 4. Limit Expand Depth
+
+Don't allow deeply nested expansions as they can cause performance issues and high DynamoDB costs.
+
+### 5. Monitor DynamoDB Costs
+
+Each expand creates additional queries. Use CloudWatch to monitor your read capacity units.
+
+## DynamoDB Limitations
+
+This library respects DynamoDB's constraints:
+
+- **Only key attributes** (hash key, range key, or GSI keys) can be filtered
+- **Only range keys** can be sorted
+- **Only one sort field** is allowed per query
+- **No attribute-level filters** (use scan sparingly for those cases)
+
+These limitations ensure efficient queries and predictable performance.
+
+## Error Handling
+
+The library provides descriptive errors:
+
+- `"Filtering not allowed on field 'X'"` - Field doesn't have filter config
+- `"Sorting not allowed on field 'X'"` - Field doesn't have sort config
+- `"Operator 'X' not allowed for field 'Y'"` - Operator not in allowed list
+- `"Only one sort field supported"` - Multiple sort fields specified
+- `"Cursor does not match query"` - Query params changed between pages
+- `"Model 'X' not found in registry"` - Model not registered
+
+## Contributing
+
+Contributions are welcome! Please open an issue or pull request.
+
+## License
+
+MIT © Sascha Eckstein
+
+## Links
+
+- [GitHub Repository](https://github.com/saschaeckstein/dynamo-query-engine)
+- [Examples](./examples)
+- [Dynamoose Documentation](https://dynamoosejs.com/)
+- [AWS DynamoDB Best Practices](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/best-practices.html)

package/index.js

@@ -0,0 +1,31 @@
+/**
+ * @fileoverview DynamoDB Query Engine - Main entry point
+ * Type-safe DynamoDB query builder for GraphQL with support for
+ * filtering, sorting, pagination, and relation expansion
+ */
+
+// Core functionality
+export { modelRegistry, ModelRegistry } from "./src/core/modelRegistry.js";
+export {
+  buildGridQuery,
+  extractGridConfig,
+} from "./src/core/gridQueryBuilder.js";
+export {
+  resolveExpand,
+  resolveExpands,
+  extractExpandPolicy,
+} from "./src/core/expandResolver.js";
+
+// Utilities
+export { encodeCursor, decodeCursor, validateCursor } from "./src/utils/cursor.js";
+export {
+  validateSingleSort,
+  validateFilterField,
+  validateSortField,
+  validateFilterOperator,
+  validateExpandField,
+  validatePaginationModel,
+} from "./src/utils/validation.js";
+
+// Types (for JSDoc imports)
+export {} from "./src/types/jsdoc.js";

package/package.json

@@ -1,12 +1,45 @@
 {
   "name": "dynamo-query-engine",
-  "version": "1.0.0",
+  "version": "1.0.1",
+  "description": "Type-safe DynamoDB query builder for GraphQL with support for filtering, sorting, pagination, and relation expansion",
   "type": "module",
   "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./core": "./src/core/index.js",
+    "./utils": "./src/utils/index.js"
+  },
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },
-  "author": "",
+  "keywords": [
+    "dynamodb",
+    "graphql",
+    "query-builder",
+    "dynamoose",
+    "pagination",
+    "filter",
+    "sort",
+    "expand",
+    "relations",
+    "aws",
+    "serverless",
+    "lambda"
+  ],
+  "author": "Sascha Eckstein",
   "license": "MIT",
-  "description": ""
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/saschaeckstein/dynamo-query-engine"
+  },
+  "peerDependencies": {
+    "dynamoose": "^4.0.0",
+    "graphql": "^16.0.0"
+  },
+  "dependencies": {
+    "graphql-parse-resolve-info": "^4.13.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
 }

package/src/core/expandResolver.js

@@ -0,0 +1,154 @@
+/**
+ * @fileoverview Expand resolver for handling relations/expansions
+ */
+
+import "../types/jsdoc.js";
+import { modelRegistry } from "./modelRegistry.js";
+import { buildGridQuery } from "./gridQueryBuilder.js";
+import { validateExpandField } from "../utils/validation.js";
+import { extractGridConfig } from "./gridQueryBuilder.js";
+
+/**
+ * Extract expand policy from schema
+ * @param {*} schema - Dynamoose schema
+ * @returns {Object.<string, ExpandConfig>} Expand policies by field name
+ */
+export function extractExpandPolicy(schema) {
+  const gridConfig = extractGridConfig(schema);
+  const expandPolicy = {};
+
+  for (const [field, config] of Object.entries(gridConfig)) {
+    if (config.expand) {
+      expandPolicy[field] = config.expand;
+    }
+  }
+
+  return expandPolicy;
+}
+
+/**
+ * Resolve expand/relations for a field
+ * @param {ResolveExpandOptions} options - Resolve expand options
+ * @returns {Promise<void>}
+ */
+export async function resolveExpand({
+  parentItems,
+  parentModel,
+  field,
+  args = {},
+}) {
+  if (!parentItems || parentItems.length === 0) {
+    return;
+  }
+
+  if (!parentModel) {
+    throw new Error("parentModel is required");
+  }
+
+  if (!field) {
+    throw new Error("field is required");
+  }
+
+  // Extract expand policy from parent schema
+  const expandPolicy = extractExpandPolicy(parentModel.schema);
+  const policy = expandPolicy[field];
+
+  if (!policy) {
+    throw new Error(
+      `Field '${field}' does not have expand configuration in parent model`
+    );
+  }
+
+  // Get target model from registry
+  const targetModel = modelRegistry.get(policy.type);
+
+  // Determine limit based on args and policy
+  const requestedLimit = args.pagination?.pageSize ?? policy.defaultLimit;
+  const limit = Math.min(requestedLimit, policy.maxLimit);
+
+  // Resolve relations for each parent item
+  const expandPromises = parentItems.map(async (parent) => {
+    try {
+      // For MANY relations, we need a partition key value
+      // This should be either parent.pk or a specific field based on the relation
+      const partitionKeyValue = parent.pk || parent[Object.keys(parent)[0]];
+
+      if (!partitionKeyValue) {
+        console.warn(
+          `Cannot expand '${field}' for parent: missing partition key value`
+        );
+        parent[field] = [];
+        return;
+      }
+
+      // Build query for expanded items
+      const { query } = buildGridQuery({
+        model: targetModel,
+        partitionKeyValue,
+        filterModel: args.filter,
+        sortModel: args.sort,
+        paginationModel: { pageSize: limit },
+        // No cursor for nested expands
+      });
+
+      // Execute query
+      const results = await query.exec();
+
+      // Assign results to parent
+      if (policy.relation === "ONE") {
+        parent[field] = results.length > 0 ? results[0] : null;
+      } else {
+        parent[field] = results;
+      }
+    } catch (error) {
+      console.error(`Error expanding '${field}' for parent:`, error);
+      // Gracefully handle errors - set empty result
+      parent[field] = policy.relation === "ONE" ? null : [];
+    }
+  });
+
+  // Execute all expands in parallel for better performance
+  await Promise.all(expandPromises);
+}
+
+/**
+ * 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
+ * @returns {Promise<void>}
+ */
+export async function resolveExpands(
+  parentItems,
+  parentModel,
+  fieldsByTypeName
+) {
+  if (!fieldsByTypeName || Object.keys(fieldsByTypeName).length === 0) {
+    return;
+  }
+
+  // Get fields for the parent type
+  const typeName = Object.keys(fieldsByTypeName)[0];
+  const fields = fieldsByTypeName[typeName];
+
+  if (!fields) {
+    return;
+  }
+
+  // Get expand policy to filter only expandable fields
+  const expandPolicy = extractExpandPolicy(parentModel.schema);
+
+  // Resolve all expands in parallel
+  const expandPromises = Object.entries(fields)
+    .filter(([fieldName]) => expandPolicy[fieldName])
+    .map(([fieldName, fieldInfo]) =>
+      resolveExpand({
+        parentItems,
+        parentModel,
+        field: fieldName,
+        args: fieldInfo.args || {},
+      })
+    );
+
+  await Promise.all(expandPromises);
+}

package/src/core/gridQueryBuilder.js

@@ -0,0 +1,219 @@
+/**
+ * @fileoverview Grid query builder for DynamoDB queries with filtering, sorting, and pagination
+ */
+
+import crypto from "crypto";
+import "../types/jsdoc.js";
+import {
+  validateSingleSort,
+  validateFilterField,
+  validateSortField,
+  validateFilterOperator,
+  validatePaginationModel,
+} from "../utils/validation.js";
+import { decodeCursor, validateCursor } from "../utils/cursor.js";
+
+/**
+ * Generate a hash for query parameters to validate cursor consistency
+ * @param {Object} params - Query parameters
+ * @param {FilterModel} params.filterModel - Filter model
+ * @param {SortModel} params.sortModel - Sort model
+ * @param {number} params.pageSize - Page size
+ * @returns {string} SHA256 hash of the query parameters
+ */
+function hashQuery({ filterModel, sortModel, pageSize }) {
+  return crypto
+    .createHash("sha256")
+    .update(JSON.stringify({ filterModel, sortModel, pageSize }))
+    .digest("hex");
+}
+
+/**
+ * Extract grid configuration from Dynamoose schema
+ * @param {*} schema - Dynamoose schema
+ * @returns {ExtractedGridConfig} 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;
+    }
+  }
+
+  return gridConfig;
+}
+
+/**
+ * Determine which GSI to use based on filter model
+ * @param {FilterModel} filterModel - Filter model
+ * @param {ExtractedGridConfig} gridConfig - Grid configuration
+ * @returns {string|null} GSI name or null
+ */
+function determineIndex(filterModel, gridConfig) {
+  if (!filterModel || !filterModel.items || filterModel.items.length === 0) {
+    return null;
+  }
+
+  // Find the first filter with an index
+  for (const filterItem of filterModel.items) {
+    const fieldConfig = gridConfig[filterItem.field]?.filter;
+    if (fieldConfig && fieldConfig.index) {
+      return fieldConfig.index;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Apply filters to the query
+ * @param {*} query - Dynamoose query object
+ * @param {FilterModel} filterModel - Filter model
+ * @param {ExtractedGridConfig} gridConfig - Grid configuration
+ * @returns {*} Updated query object
+ */
+function applyFilters(query, filterModel, gridConfig) {
+  if (!filterModel || !filterModel.items || filterModel.items.length === 0) {
+    return query;
+  }
+
+  for (const filterItem of filterModel.items) {
+    validateFilterField(filterItem.field, gridConfig);
+    validateFilterOperator(filterItem.field, filterItem.operator, gridConfig);
+
+    // Apply the filter using Dynamoose query syntax
+    query = query.where(filterItem.field);
+
+    // Map operators to Dynamoose methods
+    switch (filterItem.operator) {
+      case "eq":
+        query = query.eq(filterItem.value);
+        break;
+      case "ne":
+        query = query.ne(filterItem.value);
+        break;
+      case "gt":
+        query = query.gt(filterItem.value);
+        break;
+      case "gte":
+        query = query.ge(filterItem.value);
+        break;
+      case "lt":
+        query = query.lt(filterItem.value);
+        break;
+      case "lte":
+        query = query.le(filterItem.value);
+        break;
+      case "between":
+        if (!Array.isArray(filterItem.value) || filterItem.value.length !== 2) {
+          throw new Error(
+            `'between' operator requires an array of two values for field '${filterItem.field}'`
+          );
+        }
+        query = query.between(filterItem.value[0], filterItem.value[1]);
+        break;
+      case "beginsWith":
+        query = query.beginsWith(filterItem.value);
+        break;
+      case "contains":
+        query = query.contains(filterItem.value);
+        break;
+      default:
+        throw new Error(
+          `Unsupported operator '${filterItem.operator}' for field '${filterItem.field}'`
+        );
+    }
+  }
+
+  return query;
+}
+
+/**
+ * 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) {
+  if (!sortModel || sortModel.length === 0) {
+    return query;
+  }
+
+  const sortItem = sortModel[0];
+  validateSortField(sortItem.field, gridConfig);
+
+  // Apply descending sort if specified
+  if (sortItem.sort === "desc") {
+    query = query.sort("descending");
+  }
+  // Default is ascending, no need to explicitly set
+
+  return query;
+}
+
+/**
+ * Build a DynamoDB query from grid parameters
+ * @param {BuildGridQueryOptions} options - Query build options
+ * @returns {QueryBuildResult} Query build result with query and hash
+ */
+export function buildGridQuery({
+  model,
+  partitionKeyValue,
+  filterModel,
+  sortModel,
+  paginationModel,
+  cursor,
+}) {
+  // Validate inputs
+  if (!model) {
+    throw new Error("model is required");
+  }
+  if (!partitionKeyValue) {
+    throw new Error("partitionKeyValue is required");
+  }
+  validatePaginationModel(paginationModel);
+  validateSingleSort(sortModel);
+
+  // Extract grid config from schema
+  const gridConfig = extractGridConfig(model.schema);
+
+  // Determine which index to use
+  const index = determineIndex(filterModel, gridConfig);
+
+  // Generate query hash for cursor validation
+  const queryHash = hashQuery({
+    filterModel,
+    sortModel,
+    pageSize: paginationModel.pageSize,
+  });
+
+  // Initialize query with partition key
+  let query = model.query("pk").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, gridConfig);
+
+  // Apply pagination limit
+  query = query.limit(paginationModel.pageSize);
+
+  // Handle cursor for pagination
+  if (cursor) {
+    const decoded = decodeCursor(cursor);
+    validateCursor(decoded.queryHash, queryHash);
+    query = query.startAt(decoded.lastKey);
+  }
+
+  return { query, queryHash };
+}

package/src/core/index.js

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview Core module exports
+ */
+
+export { modelRegistry, ModelRegistry } from "./modelRegistry.js";
+export { buildGridQuery, extractGridConfig } from "./gridQueryBuilder.js";
+export {
+  resolveExpand,
+  resolveExpands,
+  extractExpandPolicy,
+} from "./expandResolver.js";

package/src/core/modelRegistry.js

@@ -0,0 +1,87 @@
+/**
+ * @fileoverview Model registry for managing Dynamoose models
+ */
+
+/**
+ * Singleton registry for Dynamoose models
+ */
+class ModelRegistry {
+  constructor() {
+    /** @type {Map<string, *>} */
+    this.models = new Map();
+  }
+
+  /**
+   * Register a model in the registry
+   * @param {string} name - Model name (should match the type in expand config)
+   * @param {*} model - Dynamoose model instance
+   * @throws {Error} If model name or model is invalid
+   */
+  register(name, model) {
+    if (!name || typeof name !== "string") {
+      throw new Error("Model name must be a non-empty string");
+    }
+
+    if (!model) {
+      throw new Error("Model is required");
+    }
+
+    if (!model.schema) {
+      throw new Error(
+        "Invalid model: must be a Dynamoose model with a schema property"
+      );
+    }
+
+    if (this.models.has(name)) {
+      throw new Error(`Model '${name}' is already registered`);
+    }
+
+    this.models.set(name, model);
+  }
+
+  /**
+   * Get a model from the registry
+   * @param {string} name - Model name
+   * @returns {*} Dynamoose model instance
+   * @throws {Error} If model is not found
+   */
+  get(name) {
+    if (!this.models.has(name)) {
+      throw new Error(
+        `Model '${name}' not found in registry. Did you forget to register it?`
+      );
+    }
+
+    return this.models.get(name);
+  }
+
+  /**
+   * Check if a model is registered
+   * @param {string} name - Model name
+   * @returns {boolean} True if model is registered
+   */
+  has(name) {
+    return this.models.has(name);
+  }
+
+  /**
+   * Get all registered model names
+   * @returns {string[]} Array of model names
+   */
+  getRegisteredModels() {
+    return Array.from(this.models.keys());
+  }
+
+  /**
+   * Clear all registered models (useful for testing)
+   */
+  clear() {
+    this.models.clear();
+  }
+}
+
+// Export singleton instance
+export const modelRegistry = new ModelRegistry();
+
+// Also export the class for custom registries if needed
+export { ModelRegistry };

package/src/types/jsdoc.js

@@ -0,0 +1,125 @@
+/**
+ * @fileoverview Type definitions for DynamoDB Query Engine
+ * These JSDoc types provide IntelliSense support throughout the library
+ */
+
+/**
+ * Filter configuration for a field
+ * @typedef {Object} FilterConfig
+ * @property {"key"|"attribute"} type - Filter type (only "key" is supported for DynamoDB queries)
+ * @property {string[]} operators - Allowed comparison operators (e.g., ["eq", "between", "gte", "lte"])
+ * @property {string} [index] - Optional GSI name to use for this filter
+ */
+
+/**
+ * Sort configuration for a field
+ * @typedef {Object} SortConfig
+ * @property {"key"} type - Sort type (only "key" is supported for DynamoDB)
+ */
+
+/**
+ * Expand/relation configuration for a field
+ * @typedef {Object} ExpandConfig
+ * @property {string} type - Target model name to expand (must be registered in ModelRegistry)
+ * @property {"ONE"|"MANY"} relation - Relation type
+ * @property {number} defaultLimit - Default number of items to fetch
+ * @property {number} maxLimit - Maximum allowed items to fetch
+ */
+
+/**
+ * Grid configuration for a field
+ * @typedef {Object} GridConfig
+ * @property {FilterConfig} [filter] - Filter configuration
+ * @property {SortConfig} [sort] - Sort configuration
+ * @property {ExpandConfig} [expand] - Expand/relation configuration
+ */
+
+/**
+ * Complete grid configuration extracted from schema
+ * @typedef {Object.<string, GridConfig>} ExtractedGridConfig
+ */
+
+/**
+ * Single filter item
+ * @typedef {Object} FilterItem
+ * @property {string} field - Field name to filter on
+ * @property {string} operator - Comparison operator (eq, ne, gt, gte, lt, lte, between, contains, etc.)
+ * @property {*} value - Filter value
+ */
+
+/**
+ * Filter model following AG Grid format
+ * @typedef {Object} FilterModel
+ * @property {"AND"|"OR"} [logicOperator] - Logic operator for combining filters
+ * @property {FilterItem[]} items - Array of filter items
+ */
+
+/**
+ * Single sort item
+ * @typedef {Object} SortItem
+ * @property {string} field - Field name to sort by
+ * @property {"asc"|"desc"} sort - Sort direction
+ */
+
+/**
+ * Sort model (array of sort items)
+ * @typedef {SortItem[]} SortModel
+ */
+
+/**
+ * Pagination model
+ * @typedef {Object} PaginationModel
+ * @property {number} pageSize - Number of items per page
+ * @property {number} [page] - Current page number (not used with cursor pagination)
+ */
+
+/**
+ * Decoded cursor data
+ * @typedef {Object} CursorData
+ * @property {Object} lastKey - DynamoDB lastKey for pagination
+ * @property {string} queryHash - Hash of the query parameters for validation
+ */
+
+/**
+ * Query build result
+ * @typedef {Object} QueryBuildResult
+ * @property {*} query - Dynamoose query object
+ * @property {string} queryHash - Hash of the query parameters
+ */
+
+/**
+ * Expand arguments from GraphQL
+ * @typedef {Object} ExpandArgs
+ * @property {FilterModel} [filter] - Filter model for expanded items
+ * @property {SortModel} [sort] - Sort model for expanded items
+ * @property {PaginationModel} [pagination] - Pagination for expanded items
+ */
+
+/**
+ * Query result with pagination
+ * @typedef {Object} QueryResult
+ * @property {Array} rows - Query result items
+ * @property {string|null} nextCursor - Base64 encoded cursor for next page
+ */
+
+/**
+ * Build grid query options
+ * @typedef {Object} BuildGridQueryOptions
+ * @property {*} model - Dynamoose model
+ * @property {string} partitionKeyValue - Value for the partition key
+ * @property {FilterModel} [filterModel] - Filter model
+ * @property {SortModel} [sortModel] - Sort model
+ * @property {PaginationModel} paginationModel - Pagination model
+ * @property {string} [cursor] - Cursor for pagination
+ */
+
+/**
+ * Resolve expand options
+ * @typedef {Object} ResolveExpandOptions
+ * @property {Array} parentItems - Parent items to expand relations for
+ * @property {*} parentModel - Dynamoose parent model
+ * @property {string} field - Field name to expand
+ * @property {ExpandArgs} [args] - Expand arguments from GraphQL
+ */
+
+export {};

package/src/utils/cursor.js

@@ -0,0 +1,65 @@
+/**
+ * @fileoverview Cursor encoding/decoding utilities for pagination
+ */
+
+import "../types/jsdoc.js";
+
+/**
+ * Encodes cursor data to Base64 string
+ * @param {Object} lastKey - DynamoDB lastKey object
+ * @param {string} queryHash - Hash of the query parameters
+ * @returns {string} Base64 encoded cursor
+ */
+export function encodeCursor(lastKey, queryHash) {
+  if (!lastKey) {
+    throw new Error("lastKey is required to encode cursor");
+  }
+  if (!queryHash) {
+    throw new Error("queryHash is required to encode cursor");
+  }
+
+  const cursorData = {
+    lastKey,
+    queryHash,
+  };
+
+  return Buffer.from(JSON.stringify(cursorData)).toString("base64");
+}
+
+/**
+ * Decodes Base64 cursor string to cursor data
+ * @param {string} cursor - Base64 encoded cursor
+ * @returns {CursorData} Decoded cursor data
+ */
+export function decodeCursor(cursor) {
+  if (!cursor || typeof cursor !== "string") {
+    throw new Error("Invalid cursor: must be a non-empty string");
+  }
+
+  try {
+    const decoded = Buffer.from(cursor, "base64").toString("utf-8");
+    const cursorData = JSON.parse(decoded);
+
+    if (!cursorData.lastKey || !cursorData.queryHash) {
+      throw new Error("Invalid cursor structure");
+    }
+
+    return cursorData;
+  } catch (error) {
+    throw new Error(`Failed to decode cursor: ${error.message}`);
+  }
+}
+
+/**
+ * Validates that cursor matches the current query
+ * @param {string} decodedQueryHash - Query hash from decoded cursor
+ * @param {string} currentQueryHash - Hash of current query
+ * @throws {Error} If cursor does not match query
+ */
+export function validateCursor(decodedQueryHash, currentQueryHash) {
+  if (decodedQueryHash !== currentQueryHash) {
+    throw new Error(
+      "Cursor does not match current query. Filters, sort, or page size have changed."
+    );
+  }
+}

package/src/utils/index.js

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Utilities module exports
+ */
+
+export { encodeCursor, decodeCursor, validateCursor } from "./cursor.js";
+export {
+  validateSingleSort,
+  validateFilterField,
+  validateSortField,
+  validateFilterOperator,
+  validateExpandField,
+  validatePaginationModel,
+} from "./validation.js";

package/src/utils/validation.js

@@ -0,0 +1,104 @@
+/**
+ * @fileoverview Validation utilities for grid configurations
+ */
+
+import "../types/jsdoc.js";
+
+/**
+ * Validates that only one sort field is specified
+ * @param {SortModel} sortModel - Sort model to validate
+ * @throws {Error} If more than one sort field is specified
+ */
+export function validateSingleSort(sortModel) {
+  if (sortModel && sortModel.length > 1) {
+    throw new Error(
+      "DynamoDB only supports sorting by one field (range key). Multiple sort fields are not allowed."
+    );
+  }
+}
+
+/**
+ * Validates that a field can be filtered based on grid config
+ * @param {string} field - Field name to filter
+ * @param {ExtractedGridConfig} gridConfig - Extracted grid configuration
+ * @throws {Error} If filtering is not allowed on this field
+ */
+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.`
+    );
+  }
+}
+
+/**
+ * Validates that a field can be sorted based on grid config
+ * @param {string} field - Field name to sort
+ * @param {ExtractedGridConfig} gridConfig - Extracted grid configuration
+ * @throws {Error} If sorting is not allowed on this field
+ */
+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.`
+    );
+  }
+}
+
+/**
+ * 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
+ * @throws {Error} If operator is not allowed for this field
+ */
+export function validateFilterOperator(field, operator, gridConfig) {
+  const config = gridConfig[field]?.filter;
+  if (!config) {
+    throw new Error(`Field '${field}' does not have filter configuration`);
+  }
+
+  if (config.operators && !config.operators.includes(operator)) {
+    throw new Error(
+      `Operator '${operator}' not allowed for field '${field}'. Allowed operators: ${config.operators.join(", ")}`
+    );
+  }
+}
+
+/**
+ * Validates that a field can be expanded based on grid config
+ * @param {string} field - Field name to expand
+ * @param {ExtractedGridConfig} gridConfig - Extracted grid configuration
+ * @throws {Error} If expand is not allowed on this field
+ */
+export function validateExpandField(field, gridConfig) {
+  const config = gridConfig[field];
+  if (!config || !config.expand) {
+    throw new Error(
+      `Expand not allowed on field '${field}'. Only fields with grid.expand config can be expanded.`
+    );
+  }
+}
+
+/**
+ * Validates pagination model
+ * @param {PaginationModel} paginationModel - Pagination model to validate
+ * @throws {Error} If pagination model is invalid
+ */
+export function validatePaginationModel(paginationModel) {
+  if (!paginationModel) {
+    throw new Error("paginationModel is required");
+  }
+
+  if (!paginationModel.pageSize || paginationModel.pageSize < 1) {
+    throw new Error("paginationModel.pageSize must be a positive number");
+  }
+
+  if (paginationModel.pageSize > 1000) {
+    throw new Error(
+      "paginationModel.pageSize cannot exceed 1000 (DynamoDB limit)"
+    );
+  }
+}