dynamo-query-engine 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,434 @@
+# 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,
+    query: {
+      sort: { type: "key" },
+      filter: {
+        type: "key",
+        operators: ["between", "gte", "lte"],
+      },
+    },
+  },
+  status: {
+    type: String,
+    index: {
+      name: "status-createdAt-index",
+      global: true,
+      rangeKey: "createdAt",
+    },
+    query: {
+      filter: {
+        type: "key",
+        operators: ["eq"],
+        index: "status-createdAt-index",
+      },
+    },
+  },
+  teamIds: {
+    type: Array,
+    schema: [String],
+    query: {
+      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
+query: {
+  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
+query: {
+  sort: { type: "key" } // Only range keys can be sorted
+}
+```
+
+> **Note**: DynamoDB only supports sorting by one field (the range key).
+
+### Expand Configuration
+
+```javascript
+query: {
+  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",
+  },
+  query: {
+    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
+
+## Testing
+
+The package includes comprehensive unit tests with Vitest.
+
+### Run Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run tests with UI
+npm run test:ui
+
+# Run tests once (CI mode)
+npm run test:run
+
+# Generate coverage report
+npm run coverage
+```
+
+### Test Coverage
+
+- **Cursor Utils**: ~80% coverage
+- **Validation**: ~70% coverage  
+- **GridQueryBuilder**: ~50% coverage
+- **Overall**: ~50-60% coverage
+
+See [tests/README.md](./tests/README.md) for detailed testing documentation.
+
+## Contributing
+
+Contributions are welcome! Please open an issue or pull request.
+
+### Development Setup
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Check coverage
+npm run coverage
+```
+
+## 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,52 @@
 {
   "name": "dynamo-query-engine",
-  "version": "1.0.0",
+  "version": "1.0.2",
+  "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"
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:run": "vitest run",
+    "coverage": "vitest --coverage"
   },
-  "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"
+  },
+  "devDependencies": {
+    "@vitest/ui": "^2.1.8",
+    "vitest": "^2.1.8"
+  },
+  "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, import("../types/jsdoc.js").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);
+}