import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
import { DeleteCommand, DeleteCommandInput, DeleteCommandOutput, DynamoDBDocumentClient, QueryCommand, QueryCommandInput, QueryCommandOutput, ScanCommand, ScanCommandInput, ScanCommandOutput, GetCommand, GetCommandInput, GetCommandOutput, PutCommand, PutCommandInput, PutCommandOutput, UpdateCommand, UpdateCommandInput, UpdateCommandOutput } from '@aws-sdk/lib-dynamodb';
/**
 * Re-exporting commands to be helpful so clients may not have to import the AWS SDK directly.
 */
export { DynamoDBDocumentClient, DynamoDBClient, DeleteCommand, DeleteCommandInput, DeleteCommandOutput, GetCommand, GetCommandInput, GetCommandOutput, QueryCommand, QueryCommandInput, QueryCommandOutput, ScanCommand, ScanCommandInput, ScanCommandOutput, PutCommand, PutCommandInput, PutCommandOutput, UpdateCommand, UpdateCommandInput, UpdateCommandOutput, };
export declare function getDynamoDBClient(region?: string): DynamoDBClient;
export declare function getDynamoDBDocumentClient(region?: string): DynamoDBDocumentClient;
export interface PaginationParams {
    cursor?: string | null | undefined;
    direction?: 'next' | 'prev' | null | undefined;
    limit?: number | null | undefined;
}
export interface PaginatedResult<T> {
    items: T[];
    cursor: string;
    hasNext: boolean;
    page: number;
}
/**
 * Executes a paginated DynamoDB query with full cursor-based pagination support.
 *
 * This helper encapsulates all pagination logic including:
 * - Cursor encoding/decoding
 * - ExclusiveStartKey calculation
 * - Bidirectional pagination (next/prev)
 * - First/last key tracking
 * - Automatic item ordering
 *
 * @param params Configuration for the query and item mapping
 * @param params.client DynamoDB Document Client instance
 * @param params.query QueryCommand input (without ExclusiveStartKey, Limit, ScanIndexForward)
 * @param params.keyAttributes Array of key attribute names for the table/index being queried
 * @param params.mapItem Function to transform raw DynamoDB items into desired format
 * @param pagination Pagination parameters from the client
 * @param pagination.cursor Base64-encoded cursor from previous request
 * @param pagination.direction Direction to paginate ('next' or 'prev')
 * @param pagination.limit Number of items per page (locked after first request)
 * @param defaultScanForward Controls the default scan direction. When true, 'next' scans forward (ascending) and 'prev' scans backward (descending). When false, the behavior is inverted.
 * @returns Paginated result with items, cursor, hasNext flag, and page number
 *
 * @example
 * ```typescript
 * return executePaginatedQuery(
 *   {
 *     client: getDynamoDBDocumentClient(),
 *     query: {
 *       TableName: 'MyTable',
 *       IndexName: 'Gs1',
 *       KeyConditionExpression: 'Gs1Pk = :pk',
 *       ExpressionAttributeValues: { ':pk': 'Agency#123' },
 *     },
 *     keyAttributes: ['Pk', 'Sk', 'Gs1Pk', 'Gs1Sk'],
 *     mapItem: (item) => item.Detail,
 *   },
 *   { cursor: '...', direction: 'next', limit: 10 },
 *   true // defaultScanForward
 * );
 * ```
 */
export declare function executePaginatedQuery<T = any>(params: {
    client?: DynamoDBDocumentClient;
    query: Omit<QueryCommandInput, 'ExclusiveStartKey' | 'Limit' | 'ScanIndexForward'>;
    keyAttributes: string[];
    mapItem: (item: Record<string, any>) => T;
}, pagination: PaginationParams, defaultScanForward?: boolean): Promise<PaginatedResult<T>>;
/**
 * Executes a paginated DynamoDB scan with cursor-based pagination support.
 *
 * Similar to executePaginatedQuery but for Scan operations. Note that Scan operations
 * are unordered by nature and do not support scan direction control (unlike Query operations).
 * Scan operations only support forward pagination (no bidirectional navigation).
 *
 * @param params Configuration for the scan and item mapping
 * @param params.client DynamoDB Document Client instance
 * @param params.scan ScanCommand input (without ExclusiveStartKey or Limit)
 * @param params.keyNames Array of key attribute names for the table
 * @param params.mapItem Function to transform raw DynamoDB items into desired format
 * @param pagination Pagination parameters from the client
 * @param pagination.cursor Base64-encoded cursor from previous request
 * @param pagination.limit Number of items per page (locked after first request)
 * @returns Paginated result with items, cursor, hasNext flag, and page number
 *
 * @example
 * ```typescript
 * return executePaginatedScan(
 *   {
 *     client: getDynamoDBDocumentClient(),
 *     scan: {
 *       TableName: 'MyTable',
 *       FilterExpression: 'attribute_exists(#attr)',
 *       ExpressionAttributeNames: { '#attr': 'myAttribute' },
 *     },
 *     keyNames: ['Pk', 'Sk'],
 *     mapItem: (item) => item.Detail,
 *   },
 *   { cursor: '...', limit: 10 }
 * );
 * ```
 */
export declare function executePaginatedScan<T = any>(params: {
    client: DynamoDBDocumentClient;
    scan: Omit<QueryCommandInput, 'ExclusiveStartKey' | 'Limit'>;
    keyNames: string[];
    mapItem: (item: Record<string, any>) => T;
}, pagination: PaginationParams): Promise<PaginatedResult<T>>;
/**
 * Builds a dynamic DynamoDB update expression from an input object.
 * Only includes fields that are defined (not undefined) and not in the excluded list.
 *
 * @param input - The input object containing fields to update
 * @param options - Configuration options
 * @param options.excludedFields - Fields to exclude from the update expression (e.g., 'id', 'createdAt')
 * @param options.prefix - Prefix for nested objects (e.g., 'Detail', 'Data'). Set to empty string for no prefix. Default: 'Detail'
 * @returns Object containing UpdateExpression, ExpressionAttributeNames, and ExpressionAttributeValues
 */
export declare function buildUpdateExpression(input: Record<string, unknown>, options?: {
    excludedFields?: string[];
    prefix?: string;
}): {
    UpdateExpression: string;
    ExpressionAttributeNames: Record<string, string>;
    ExpressionAttributeValues: Record<string, unknown>;
};
/**
 * Executes a DynamoDB update operation that only succeeds if the item already exists.
 *
 * This function builds a dynamic update expression from the input object and applies
 * an existence check condition. Unlike DynamoDB's default upsert behavior, this function
 * will throw an error if you attempt to update a non-existent item.
 *
 * @template T - The type of the returned item or nested object
 * @param input - Object containing the fields to update. Only defined values are included.
 * @param tableName - The name of the DynamoDB table
 * @param key - The primary key of the item to update (e.g., `{ Pk: 'User#123', Sk: 'Profile' }`)
 * @param options - Configuration options
 * @param options.client - Custom DynamoDB Document Client instance (defaults to singleton client)
 * @param options.excludedFields - Fields to exclude from the update (e.g., `['id', 'createdAt']`)
 * @param options.prefix - Prefix for nested object updates (default: 'Detail'). Set to empty string for no prefix.
 * @returns The updated item or nested object (based on prefix setting)
 *
 * @throws {ConditionalCheckFailedException} When the item doesn't exist in the table
 * @throws {Error} When the key object is empty
 *
 * @example
 * ```typescript
 * // Update a user profile (with default 'Detail' prefix)
 * const updated = await executeUpdate<UserProfile>(
 *   { name: 'John Doe', email: 'john@example.com', updatedAt: new Date().toISOString() },
 *   'MyTable',
 *   { Pk: 'User#123', Sk: 'Profile' }
 * );
 * // Returns: updated.name, updated.email, etc. from the Detail object
 *
 * // Update without prefix (top-level attributes)
 * const updated = await executeUpdate<User>(
 *   { status: 'active', lastLogin: Date.now() },
 *   'MyTable',
 *   { Pk: 'User#123', Sk: 'Metadata' },
 *   { prefix: '' }
 * );
 * // Returns: full item with top-level attributes
 *
 * // Exclude certain fields and add timestamp
 * const updated = await executeUpdate<Product>(
 *   { ...productData, updatedAt: new Date().toISOString() },
 *   'Products',
 *   { Pk: 'Product#456' },
 *   { excludedFields: ['id', 'createdAt'] }
 * );
 * ```
 */
export declare function executeUpdate<T>(input: Record<string, unknown>, tableName: string, key: Record<string, unknown>, options?: {
    client?: DynamoDBDocumentClient;
    excludedFields?: string[];
    prefix?: string;
}): Promise<T>;
/**
 * Executes a DynamoDB put operation to create or replace an item in the table.
 *
 * This function puts an entire item into DynamoDB. By default, it will NOT overwrite
 * existing items (preventOverwrite is true by default). Set preventOverwrite to false
 * if you want to allow replacing existing items.
 *
 * @template T - The type of the returned item
 * @param params - Configuration parameters
 * @param params.item - The complete item to put into the table, including the primary key
 * @param params.tableName - The name of the DynamoDB table
 * @param params.key - The primary key of the item (e.g., `{ Pk: 'User#123', Sk: 'Profile' }`). Used for the preventOverwrite condition.
 * @param params.client - Custom DynamoDB Document Client instance (defaults to singleton client)
 * @param params.preventOverwrite - If true, the put will fail if an item with the same key already exists (default: true)
 * @param params.returnValues - Specify what values to return. 'NONE' (default) or 'ALL_OLD' to return the previous item
 * @returns The item that was put (or the old item if returnValues is 'ALL_OLD')
 *
 * @throws {ConditionalCheckFailedException} When preventOverwrite is true and the item already exists
 * @throws {Error} When the key object is empty
 *
 * @example
 * ```typescript
 * // Create a new user (will fail if already exists - default behavior)
 * const user = await executePut<User>({
 *   item: {
 *     Pk: 'User#123',
 *     Sk: 'Profile',
 *     Detail: {
 *       name: 'John Doe',
 *       email: 'john@example.com',
 *       createdAt: new Date().toISOString()
 *     }
 *   },
 *   tableName: 'MyTable',
 *   key: { Pk: 'User#123', Sk: 'Profile' }
 * });
 * // Throws ConditionalCheckFailedException if User#123 already exists
 *
 * // Allow overwriting existing item
 * const user = await executePut<User>({
 *   item: {
 *     Pk: 'User#456',
 *     Sk: 'Profile',
 *     Detail: { name: 'Jane Doe', email: 'jane@example.com' }
 *   },
 *   tableName: 'MyTable',
 *   key: { Pk: 'User#456', Sk: 'Profile' },
 *   preventOverwrite: false
 * });
 * // Will replace the item if User#456 already exists
 *
 * // Replace item and return the old version
 * const oldUser = await executePut<User>({
 *   item: {
 *     Pk: 'User#789',
 *     Sk: 'Profile',
 *     Detail: { name: 'Updated Name', email: 'updated@example.com' }
 *   },
 *   tableName: 'MyTable',
 *   key: { Pk: 'User#789', Sk: 'Profile' },
 *   preventOverwrite: false,
 *   returnValues: 'ALL_OLD'
 * });
 * // Returns the previous item data
 * ```
 */
export declare function executePut<T>(params: {
    item: Record<string, unknown>;
    tableName: string;
    key: Record<string, unknown>;
    client?: DynamoDBDocumentClient;
    preventOverwrite?: boolean;
    returnValues?: 'NONE' | 'ALL_OLD';
}): Promise<T | undefined>;
/**
 * Executes a DynamoDB delete operation to remove an item from the table.
 *
 * @param params - Configuration parameters
 * @param params.tableName - The name of the DynamoDB table
 * @param params.key - The primary key of the item to delete (e.g., `{ Pk: 'User#123', Sk: 'Profile' }`)
 * @param params.client - Custom DynamoDB Document Client instance (defaults to singleton client)
 *
 * @example
 * ```typescript
 * await executeDelete({ tableName: 'MyTable', key: { Pk: 'User#123', Sk: 'Profile' } });
 * ```
 */
export declare function executeDelete(params: {
    tableName: string;
    key: Record<string, unknown>;
    client?: DynamoDBDocumentClient;
}): Promise<void>;
/**
 * Executes a DynamoDB get operation to retrieve an item from the table.
 *
 * @template T - The type of the returned item
 * @param params - Configuration parameters
 * @param params.tableName - The name of the DynamoDB table
 * @param params.key - The primary key of the item to retrieve (e.g., `{ Pk: 'User#123', Sk: 'Profile' }`)
 * @param params.client - Custom DynamoDB Document Client instance (defaults to singleton client)
 * @param params.prefix - Prefix for nested object retrieval. Set to null for full item, or specify a prefix like 'Detail' (default)
 * @returns The item if found, or null if not found
 *
 * @example
 * ```typescript
 * const user = await executeGet<User>({ tableName: 'MyTable', key: { Pk: 'User#123', Sk: 'Profile' } });
 * ```
 */
export declare function executeGet<T>(params: {
    tableName: string;
    key: Record<string, unknown>;
    client?: DynamoDBDocumentClient;
    prefix?: string | null;
    consistentRead?: boolean;
}): Promise<T | null>;
/**
 * Executes a DynamoDB query.
 *
 * @param params Configuration for the scan and item mapping
 * @param params.client DynamoDB Document Client instance
 * @param params.scan ScanCommand input (without ExclusiveStartKey or Limit)
 * @param params.keyNames Array of key attribute names for the table
 * @param params.mapItem Function to transform raw DynamoDB items into desired format
 * @param limit Number of items per page (locked after first request)
 * @param scanIndexForward Optional flag to control the scan direction (default: true)
 * @returns The items retrieved from the query
 */
export declare function executeQuery<T = any>(params: {
    client?: DynamoDBDocumentClient;
    query: Omit<QueryCommandInput, 'ExclusiveStartKey' | 'Limit' | 'ScanIndexForward'>;
    mapItem: (item: Record<string, any>) => T;
}, limit?: number, scanIndexForward?: boolean): Promise<T[]>;
/**
 * Executes a DynamoDB query on a secondary index and returns the first matching item.
 *
 * @template T - The type of the returned item
 * @param params - Configuration parameters
 * @param params.tableName - The name of the DynamoDB table
 * @param params.indexName - The name of the secondary index to query
 * @param params.key - The key attributes to query (e.g., `{ Gs1Pk: 'User#123' }` or `{ Gs1Pk: 'User#123', Gs1Sk: 'Profile' }`)
 * @param params.client - Custom DynamoDB Document Client instance (defaults to singleton client)
 * @param params.prefix - Prefix for nested object retrieval. Set to null for full item, or specify a prefix like 'Detail' (default)
 * @returns The first matching item if found, or null if not found
 *
 * @example
 * ```typescript
 * // Query with just partition key
 * const user = await executeGetFromIndex<User>({
 *   tableName: 'MyTable',
 *   indexName: 'Gs1',
 *   key: { Gs1Pk: 'User#123' }
 * });
 *
 * // Query with partition and sort key
 * const user = await executeGetFromIndex<User>({
 *   tableName: 'MyTable',
 *   indexName: 'Gs1',
 *   key: { Gs1Pk: 'User#123', Gs1Sk: 'Profile' }
 * });
 * ```
 */
export declare function executeGetFromIndex<T>(params: {
    tableName: string;
    indexName: string;
    key: Record<string, unknown>;
    client?: DynamoDBDocumentClient;
    prefix?: string | null;
}): Promise<T | null>;
//# sourceMappingURL=dynamodb.d.ts.map