dynamo-query-engine 1.0.0 → 1.0.2

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 {Object.<string, import("../types/jsdoc.js").GridConfig>} Extracted grid configuration
+ */
+export function extractGridConfig(schema) {
+  const attributes = schema.getAttributes();
+  const gridConfig = {};
+
+  for (const [field, definition] of Object.entries(attributes)) {
+    if (definition.query) {
+      gridConfig[field] = definition.query;
+    }
+  }
+
+  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 {Object.<string, import("../types/jsdoc.js").GridConfig>} gridConfig - Extracted grid configuration
+ * @throws {Error} If filtering is not allowed on this field
+ */
+export function validateFilterField(field, gridConfig) {
+  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 {Object.<string, import("../types/jsdoc.js").GridConfig>} gridConfig - Extracted grid configuration
+ * @throws {Error} If sorting is not allowed on this field
+ */
+export function validateSortField(field, gridConfig) {
+  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 {Object.<string, import("../types/jsdoc.js").GridConfig>} gridConfig - Extracted grid configuration
+ * @throws {Error} If operator is not allowed for this field
+ */
+export function validateFilterOperator(field, operator, gridConfig) {
+  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 {Object.<string, import("../types/jsdoc.js").GridConfig>} gridConfig - Extracted grid configuration
+ * @throws {Error} If expand is not allowed on this field
+ */
+export function validateExpandField(field, gridConfig) {
+  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)"
+    );
+  }
+}