Interfaces

QueryParams

Defined in: dynamo-db/query.ts:16

Parameters for querying a DynamoDB table.

Properties

consistentRead?

optional consistentRead: boolean

Defined in: dynamo-db/query.ts:36

Whether to use strongly consistent reads

delayInSeconds?

optional delayInSeconds: number

Defined in: dynamo-db/query.ts:45

Delay between retry attempts in seconds (default: 2)

expressionAttributeNames?

optional expressionAttributeNames: Record<string, string>

Defined in: dynamo-db/query.ts:25

Optional mapping of expression attribute name placeholders

expressionAttributeValues

expressionAttributeValues: Record<string, any>

Defined in: dynamo-db/query.ts:23

Values for the key condition expression placeholders

filterAttributeValues?

optional filterAttributeValues: Record<string, any>

Defined in: dynamo-db/query.ts:34

Values for filter expression placeholders

filterExpression?

optional filterExpression: string

Defined in: dynamo-db/query.ts:31

Optional filter expression applied after the query

indexName?

optional indexName: string

Defined in: dynamo-db/query.ts:27

Optional GSI or LSI name to query

keyConditionExpression

keyConditionExpression: string

Defined in: dynamo-db/query.ts:20

The key condition expression (e.g., 'pk = :pk AND sk BEGINS_WITH :prefix')

lastEvaluatedKey?

optional lastEvaluatedKey: Record<string, any>

Defined in: dynamo-db/query.ts:39

Pagination token from a previous query

limit?

optional limit: number

Defined in: dynamo-db/query.ts:29

Maximum number of items to return

maxIterations?

optional maxIterations: number

Defined in: dynamo-db/query.ts:43

Maximum number of retry attempts (default: 10)

scanIndexForward?

optional scanIndexForward: boolean

Defined in: dynamo-db/query.ts:41

Sort order - true for ascending, false for descending (default: true)

tableName

tableName: string

Defined in: dynamo-db/query.ts:18

The name of the DynamoDB table to query

Functions

query()

query<T>(params): Promise<{ items: T[]; lastEvaluatedKey?: Record<string, any>; }>

Defined in: dynamo-db/query.ts:91

Queries a DynamoDB table with automatic retry logic.

Designed for E2E and integration tests where you need to verify that records exist in DynamoDB after triggering an async flow. The function will poll the table until results are found or max retries are exhausted.

Type Parameters

T

T

The expected type of items returned

Parameters

params

QueryParams

Query parameters including table name, key conditions, and retry settings

Returns

Promise<{ items: T[]; lastEvaluatedKey?: Record<string, any>; }>

Object containing the matched items and optional pagination token

Throws

Error if no results are found after all retry attempts

Examples

// Query for all orders belonging to a user after triggering order creation
const { items } = await query<Order>({
  tableName: 'orders-table',
  keyConditionExpression: 'pk = :pk AND begins_with(sk, :prefix)',
  expressionAttributeValues: {
    ':pk': 'USER#123',
    ':prefix': 'ORDER#'
  },
  maxIterations: 15,
  delayInSeconds: 2
});

expect(items).toHaveLength(1);
expect(items[0].status).toBe('CONFIRMED');

// Query with a filter and using a GSI
const { items } = await query<Event>({
  tableName: 'events-table',
  indexName: 'status-index',
  keyConditionExpression: 'status = :status',
  expressionAttributeValues: { ':status': 'PENDING' },
  filterExpression: 'createdAt > :date',
  filterAttributeValues: { ':date': '2024-01-01' }
});