TCTF's DynamoDB Framework, Part 2: Building a Fluent Query Builder in TypeScript

01The Problem with Raw DynamoDB Expressions

DynamoDB's query API is powerful but verbose. To query users by status with a date filter, you write something like: KeyConditionExpression set to GSI1PK equals colon status, FilterExpression set to createdAt greater than colon date, ExpressionAttributeNames mapping hash GSI1PK to GSI1PK and hash createdAt to createdAt, ExpressionAttributeValues mapping colon status to the status value and colon date to the date value.

This is four separate objects that must be kept in sync. If you add a filter condition, you update the FilterExpression string, add to ExpressionAttributeNames, and add to ExpressionAttributeValues. Miss any one of them and the query fails.

In a platform with 34 services and hundreds of Lambda functions, this pattern is repeated thousands of times. Every repetition is a chance for a typo, a missing attribute name, or a mismatched value placeholder. The errors are subtle — a wrong attribute name in ExpressionAttributeNames does not throw an error, it just returns no results.

The fluent query builder eliminates this entire class of bugs. Instead of four objects, you write one chain: service.query('Users').index('status-index').where('GSI1PK', '=', status).filter('createdAt', '>', date).execute(). The builder constructs the expression strings, attribute names, and attribute values internally. You never see them.

🐛

Raw DynamoDB expressions require four objects kept in sync. One typo returns wrong results silently. The fluent builder eliminates this entire class of bugs.

02The Fluent API: Chainable Query Construction

The query builder uses the fluent pattern — every method returns the builder itself, so methods can be chained. The chain reads like a sentence describing what you want.

Start with the table: service.query('Users'). Add an index: .index('email-index'). Add key conditions: .where('email', '=', 'user@example.com'). Add filters: .filter('status', '=', 'active'). Select specific attributes: .select(['userId', 'name', 'email']). Limit results: .limit(50). Set pagination: .startFrom(nextToken). Control sort direction: .setScanDirection(false) for descending. Execute: .execute().

The chain is composable. You can build a base query and add conditions dynamically based on request parameters. If the request includes a status filter, add .filter('status', '=', status). If it includes a date range, add .where('createdAt', 'BETWEEN', startDate, endDate). The builder accumulates conditions and constructs the final expression when execute() is called.

The .first() method is a convenience that adds .limit(1) and returns the first item or null — useful for lookups where you expect exactly one result. The .count() method returns the number of matching items without fetching the items themselves.

03Query Operators and Filter Operators

The builder supports the full range of DynamoDB operators, typed as TypeScript union types so the compiler catches invalid operators at build time.

Query operators (used in .where() for key conditions): equals, less than, less than or equal, greater than, greater than or equal, BETWEEN (two values), and begins_with. These operate on the partition key and sort key — the indexed attributes that DynamoDB can evaluate efficiently.

Filter operators (used in .filter() for post-query filtering): all the query operators plus contains, not_equals, attribute_exists, attribute_not_exists, and IN (membership in a list). Filters run after the query retrieves items from the index, so they do not reduce the amount of data read — but they reduce the amount of data returned to the caller.

The distinction matters for performance. Key conditions in .where() determine which items DynamoDB reads from the index — they are efficient. Filters in .filter() are applied after the read — they reduce network transfer but not read capacity consumption. The builder enforces this distinction: .where() only accepts query operators, .filter() accepts filter operators. Using a filter operator in .where() is a compile-time error.

⚡

.where() conditions are efficient — they determine what DynamoDB reads. .filter() conditions reduce what is returned but not what is read. The builder enforces this distinction at compile time.

04Secure Pagination with Encrypted Tokens

DynamoDB pagination uses lastEvaluatedKey — a raw object containing the partition key, sort key, and any GSI keys of the last item in the result set. Returning this to the client is a security risk. It exposes the DynamoDB key structure, the attribute names, and the actual key values. A malicious client could modify the key to skip items, access unauthorized data, or probe the table structure.

The query builder integrates with the PaginationEncryption utility from the crypto module. When a query returns results with a lastEvaluatedKey, the builder encrypts it into an opaque token using the pluggable encryption service. The client receives a string like eyJhbGciOiJBMjU2R0NNIi... — they cannot see the key structure, cannot modify it, and cannot forge a token for a different page.

When the client sends the token back for the next page, the builder decrypts it, validates its integrity, and uses the original lastEvaluatedKey to continue the query. If the token has been tampered with, decryption fails and the request is rejected.

The encryption context binds the token to the pagination purpose — a pagination token cannot be replayed as a session token or API key. This is the same pluggable encryption service covered in Framework Series #8, using the same provider-agnostic interface.

05Fresh Instances: Preventing State Leaks

The query builder accumulates state as you chain methods — table name, index, key conditions, filters, projection, limit, pagination token, sort direction. This state must not leak between queries.

In early versions, the builder was cached for performance. Two queries in the same Lambda invocation shared the same builder instance. The second query inherited conditions from the first. This caused subtle bugs — a filter from one query appearing in another, a limit from one query constraining another.

The fix: every query gets a fresh builder instance. The DynamoDBFactory.createQueryBuilder() method always returns a new instance. The ProductionDynamoDBService uses withQueryBuilder() internally, which creates a fresh builder for every operation and cleans it up afterward.

The performance cost is negligible — creating a builder is a few object allocations. The correctness benefit is enormous — no state leaks, no cross-query contamination, no subtle bugs that only appear when two queries run in the same invocation.

The ProductionDynamoDBService takes this further with a state tracker pattern. When you chain methods on the service's query builder, the state is accumulated in a separate state object. When execute() is called, a fresh EnhancedQueryBuilder is created, the accumulated state is applied, and the query runs. This ensures that even the service-level builder is stateless between operations.

🔒

Every query gets a fresh builder instance. No state leaks between queries. The performance cost is negligible. The correctness benefit is enormous.

06Validation at Every Step

The ProductionDynamoDBService wraps the query builder with validation at every step. Table names are checked for valid characters and length. Index names are validated. Key condition values are sanitized for injection patterns. Filter values are type-checked. Projection attributes are validated as non-empty arrays. Limits are enforced between 1 and 1000. Pagination tokens are verified for integrity before use.

This validation catches errors early — at the point where the developer writes the query, not deep inside DynamoDB's API where the error message is cryptic. A missing table name throws INVALID_TABLE_NAME. A limit of 0 throws INVALID_LIMIT. A tampered pagination token throws INVALID_PAGINATION_TOKEN.

The validation also provides security. String values are checked for script injection patterns. Attribute names are length-limited to prevent abuse. The combination of type-safe operators (compile-time) and runtime validation (execution-time) creates a defense-in-depth approach where bugs are caught at the earliest possible point.

07Scan Operations: The Necessary Evil

DynamoDB scans read every item in the table. They are expensive, slow, and should be avoided in production code. But sometimes they are necessary — data migrations, analytics queries, admin tools, and cleanup operations all need to scan.

The query builder provides a separate scan path: service.scan('Users'). Scans support filters (.filter()), projections (.select()), limits (.limit()), and pagination (.startFrom()). They do not support key conditions (.where()) — calling .where() on a scan throws an error, because scans do not use key conditions.

The scan builder uses scanSecure() internally, which applies the same pagination encryption as queries. Even scan results get encrypted pagination tokens.

The separation between query and scan is deliberate. Queries are the normal path — efficient, indexed, fast. Scans are the exception — expensive, full-table, slow. By making them separate methods with different capabilities, the builder makes it obvious when code is scanning instead of querying. A scan in production code should always prompt the question: is there an index that could make this a query instead?

⚠️

Scans read every item in the table. The builder makes scans a separate, obvious path. If you are scanning in production, ask: is there an index that could make this a query?