@moicky/dynamodb/dist/operations/query.d.ts

Contains a collection of convenience functions for working with AWS DynamoDB

import { QueryCommandInput, QueryCommandOutput } from "@aws-sdk/client-dynamodb";
import { DynamoDBItem } from "../types";
/**
 * Query a single item in a DynamoDB table using a key condition.
 * @param keyCondition - The condition for the key in DynamoDB QueryCommand.
 * @param key - Definitions for the attributes used in keyCondition and FilterExpression
 * @param args - The additional arguments to override or specify for {@link QueryCommandInput}
 * @returns A promise that resolves to the output of {@link QueryCommandOutput}
 *
 * @example
 * Query a single item using a key condition
 * ```javascript
 * const booksResponse = await query("#PK = :PK and begins_with(#SK, :SK)", {
 *   PK: "User/1",
 *   SK: "Book/",
 * });
 * ```
 */
export declare function query(keyCondition: string, key: Record<string, any>, args?: Partial<QueryCommandInput>): Promise<QueryCommandOutput>;
/**
 * Query multiple items from the DynamoDB table using a key condition and unmarshalls the result.
 * @param keyCondition - The condition for the key in DynamoDB QueryCommand.
 * @param key - Definitions for the attributes used in keyCondition and FilterExpression
 * @param args - The additional arguments to override or specify for {@link QueryCommandInput}
 * @returns A promise that resolves to an array of unmarshalled items.
 *
 * @example
 * Query multiple items using a key condition
 * ```javascript
 * const books = await queryItems("#PK = :PK and begins_with(#SK, :SK)", {
 *   PK: "User/1",
 *   SK: "Book/",
 * });
 * ```
 */
export declare function queryItems<T extends DynamoDBItem = DynamoDBItem>(keyCondition: string, key: Record<string, any>, args?: Partial<QueryCommandInput>): Promise<T[]>;
/**
 * Query all items from the DynamoDB table using a key condition and unmarshalls the result.
 * This function retries until all items are retrieved due to the AWS limit of 1MB per query.
 * @param keyCondition - The condition for the key in DynamoDB QueryCommand.
 * @param key - Definitions for the attributes used in keyCondition and FilterExpression
 * @param args - The additional arguments to override or specify for {@link QueryCommandInput}
 * @returns A promise that resolves to an array of unmarshalled items.
 *
 * @example
 * Query all items using a key condition
 * ```javascript
 * const allBooks = await queryAllItems("#PK = :PK and begins_with(#SK, :SK)", {
 *   PK: "User/1",
 *   SK: "Book/",
 * });
 * const booksWithFilter = await queryAllItems(
 *   "#PK = :PK and begins_with(#SK, :SK)", // keyCondition
 *   {
 *     // definition for all attributes
 *     PK: "User/1",
 *     SK: "Book/",
 *     from: 1950,
 *     to: 2000,
 *   },
 *   // additional args with FilterExpression for example
 *   { FilterExpression: "#released BETWEEN :from AND :to" }
 * );
 * ```
 */
export declare function queryAllItems<T extends DynamoDBItem = DynamoDBItem>(keyCondition: string, key: Record<string, any>, args?: Partial<QueryCommandInput>): Promise<T[]>;
/**
 * The structure for the PaginationPage type.
 * @property number - The page number. Cannot be set manually.
 * @property firstKey - The key for the first item on the page.
 * @property lastKey - The key for the last item on the page.
 */
export type PaginationPage = {
    number?: number;
    firstKey: Record<string, any>;
    lastKey: Record<string, any>;
};
/**
 * The structure for the PaginationResult type.
 * @property items - The items on the current page.
 * @property hasPreviousPage - Whether there is a previous page.
 * @property hasNextPage - Whether there is a next page.
 * @property currentPage - The current page.
 */
export type PaginationResult<T extends DynamoDBItem = DynamoDBItem> = {
    items: T[];
    hasPreviousPage: boolean;
    hasNextPage: boolean;
    currentPage: PaginationPage;
};
/**
 * The arguments for the queryPaginatedItems function.
 * @property pageSize - The size of each page.
 * @property direction - The direction of pagination, 'next' or 'previous'. Default is 'next'.
 * @property currentPage - The current page.
 */
export interface PaginationArgs extends Partial<Omit<QueryCommandInput, "Limit">> {
    pageSize: number;
    direction?: "next" | "previous";
    currentPage?: PaginationPage;
}
/**
 * Query items from the DynamoDB table using a key condition in a paginated manner.
 * @param keyCondition - The condition for the key in DynamoDB QueryCommand.
 * @param key - Definitions for the attributes used in keyCondition and FilterExpression
 * @param args- The pagination arguments, including pageSize and direction. {@link PaginationArgs}
 * @returns A promise that resolves to a {@link PaginationResult}.
 * @example
 * Query the first page of items using a key condition
 * ```javascript
 * const { items, hasNextPage, hasPreviousPage, currentPage } =
 *   await queryPaginatedItems(
 *     "#PK = :PK and begins_with(#SK, :SK)",
 *     { PK: "User/1", SK: "Book/" },
 *     { pageSize: 100 }
 *   );
 * // items: The items on the current page.
 * // currentPage: { number: 1, firstKey: { ... }, lastKey: { ... } }
 *
 * const { items: nextItems, currentPage: nextPage } = await queryPaginatedItems(
 *   "#PK = :PK and begins_with(#SK, :SK)",
 *   { PK: "User/1", SK: "Book/" },
 *   { pageSize: 100, currentPage }
 * );
 * // items: The items on the second page.
 * // currentPage: { number: 2, firstKey: { ... }, lastKey: { ... } }
 * ```
 */
export declare function queryPaginatedItems<T extends DynamoDBItem = DynamoDBItem>(keyCondition: string, key: Record<string, any>, args: PaginationArgs): Promise<PaginationResult<T>>;