dyno-table 2.2.1 → 2.3.0

package/dist/index-DlN8G9hd.d.cts

@@ -0,0 +1,2797 @@
+import { c as PrimaryKeyWithoutExpression, s as Path, a as Condition, b as ConditionOperator, t as PathType } from './conditions-CcZL0sR2.cjs';
+import { DynamoItem, TableConfig, GSINames } from './types.cjs';
+import { TransactWriteCommandInput } from '@aws-sdk/lib-dynamodb';
+
+type BatchWriteOperation<T extends Record<string, unknown>> = {
+    type: "put";
+    item: T;
+} | {
+    type: "delete";
+    key: PrimaryKeyWithoutExpression;
+};
+
+/**
+ * Interface for DynamoDB command objects that can contain expressions
+ */
+interface DynamoCommandWithExpressions {
+    conditionExpression?: string;
+    updateExpression?: string;
+    filterExpression?: string;
+    keyConditionExpression?: string;
+    projectionExpression?: string;
+    expressionAttributeNames?: Record<string, string>;
+    expressionAttributeValues?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+
+/**
+ * Function type for executing DynamoDB operations and returning raw results.
+ */
+type DirectExecutor<T extends DynamoItem> = () => Promise<{
+    items: T[];
+    lastEvaluatedKey?: DynamoItem;
+}>;
+/**
+ * Minimal result generator that provides async iteration over DynamoDB results with automatic pagination.
+ *
+ * @example
+ * ```typescript
+ * const results = await queryBuilder.execute();
+ *
+ * for await (const item of results) {
+ *   console.log(item);
+ * }
+ * ```
+ */
+declare class ResultIterator<T extends DynamoItem, TConfig extends TableConfig = TableConfig> {
+    private queryBuilder;
+    private directExecutor;
+    private lastEvaluatedKey?;
+    private itemsYielded;
+    private readonly overallLimit?;
+    constructor(queryBuilder: QueryBuilderInterface<T, TConfig>, directExecutor: DirectExecutor<T>);
+    /**
+     * Async iterator with automatic pagination
+     */
+    [Symbol.asyncIterator](): AsyncIterableIterator<T>;
+    /**
+     * Convert to array (loads all pages).
+     *
+     * ```ts
+     * const result = await table.query({ pk: "foo" }).execute();
+     * const allItemsFromDynamo = await result.toArray();
+     * ```
+     *
+     * Note: This will load all pages into memory. For large datasets, consider using async iteration instead.
+     *```ts
+     * const result = await table.query({ pk: "foo" }).execute();
+     * for await (const item of result) {
+     *   // Process each item
+     * }
+     * ```
+     */
+    toArray(): Promise<T[]>;
+    /**
+     * Get the last evaluated key
+     */
+    getLastEvaluatedKey(): DynamoItem | undefined;
+}
+
+interface DeleteCommandParams extends DynamoCommandWithExpressions {
+    tableName: string;
+    key: Record<string, unknown>;
+    conditionExpression?: string;
+    expressionAttributeNames?: Record<string, string>;
+    expressionAttributeValues?: DynamoItem;
+    returnValues?: "ALL_OLD";
+}
+/**
+ * Parameters for the DynamoDB put command.
+ *
+ * These parameters are used when executing the operation against DynamoDB.
+ *
+ * The `returnValues` property can be:
+ * - `"ALL_OLD"`: Return the attributes of the item as they were before the operation
+ * - `"NONE"`: Return nothing
+ * - `"CONSISTENT"`: Triggers a GET operation after the put to retrieve the updated item state
+ * - `"INPUT"`: Return the input values that were passed to the operation (useful for create operations)
+ */
+interface PutCommandParams extends DynamoCommandWithExpressions {
+    tableName: string;
+    item: DynamoItem;
+    conditionExpression?: string;
+    expressionAttributeNames?: Record<string, string>;
+    expressionAttributeValues?: Record<string, unknown>;
+    returnValues?: "ALL_OLD" | "NONE" | "CONSISTENT" | "INPUT";
+}
+/**
+ * Parameters for the DynamoDB update command.
+ * These parameters are used when executing the operation against DynamoDB.
+ */
+interface UpdateCommandParams extends DynamoCommandWithExpressions {
+    /** The name of the DynamoDB table */
+    tableName: string;
+    /** The primary key of the item to update */
+    key: Record<string, unknown>;
+    /** The update expression (SET, REMOVE, ADD, DELETE clauses) */
+    updateExpression: string;
+    /** Optional condition expression that must be satisfied */
+    conditionExpression?: string;
+    /** Map of expression attribute name placeholders to actual names */
+    expressionAttributeNames?: Record<string, string>;
+    /** Map of expression attribute value placeholders to actual values */
+    expressionAttributeValues?: DynamoItem;
+    /** Which item attributes to include in the response */
+    returnValues?: "ALL_NEW" | "UPDATED_NEW" | "ALL_OLD" | "UPDATED_OLD" | "NONE";
+}
+interface ConditionCheckCommandParams extends DynamoCommandWithExpressions {
+    tableName: string;
+    key: Record<string, unknown>;
+    conditionExpression: string;
+    expressionAttributeNames?: Record<string, string>;
+    expressionAttributeValues?: DynamoItem;
+}
+/**
+ * Base interface for all builder classes that support pagination
+ * to be used by Paginator without creating circular dependencies.
+ */
+interface BaseBuilderInterface<T extends DynamoItem, TConfig extends TableConfig = TableConfig, B = unknown> {
+    clone(): B;
+    limit(limit: number): B;
+    getLimit(): number | undefined;
+    startFrom(lastEvaluatedKey: DynamoItem): B;
+    execute(): Promise<ResultIterator<T, TConfig>>;
+}
+/**
+ * Interface for the QueryBuilder class to be used by Paginator
+ * without creating a circular dependency.
+ */
+interface QueryBuilderInterface<T extends DynamoItem, TConfig extends TableConfig = TableConfig> extends BaseBuilderInterface<T, TConfig, QueryBuilderInterface<T, TConfig>> {
+}
+/**
+ * Interface for the ScanBuilder class to be used by Paginator
+ * without creating a circular dependency.
+ */
+interface ScanBuilderInterface<T extends DynamoItem, TConfig extends TableConfig = TableConfig> extends BaseBuilderInterface<T, TConfig, ScanBuilderInterface<T, TConfig>> {
+}
+/**
+ * Interface for the FilterBuilder class to be used by Paginator
+ * without creating a circular dependency.
+ */
+interface FilterBuilderInterface<T extends DynamoItem, TConfig extends TableConfig = TableConfig> extends BaseBuilderInterface<T, TConfig, FilterBuilderInterface<T, TConfig>> {
+}
+/**
+ * Represents the result of a single page query operation.
+ * This interface provides all necessary information about the current page
+ * and the availability of subsequent pages.
+ */
+interface PaginationResult<T> {
+    /** The items (dinosaurs, habitats, etc.) retrieved for the current page */
+    items: T[];
+    /** DynamoDB's last evaluated key, used internally for pagination */
+    lastEvaluatedKey?: DynamoItem;
+    /** Indicates whether there are more pages available */
+    hasNextPage: boolean;
+    /** The current page number (1-indexed) */
+    page: number;
+}
+/**
+ * Represents a single operation within a DynamoDB transaction.
+ * Each operation can be one of:
+ * - Put: Insert or replace an item
+ * - Update: Modify an existing item
+ * - Delete: Remove an item
+ * - ConditionCheck: Verify item state without modification
+ */
+type TransactionItem = {
+    type: "Put";
+    params: PutCommandParams;
+} | {
+    type: "Update";
+    params: UpdateCommandParams;
+} | {
+    type: "Delete";
+    params: DeleteCommandParams;
+} | {
+    type: "ConditionCheck";
+    params: ConditionCheckCommandParams;
+};
+
+/**
+ * Parameters for the DynamoDB get command.
+ */
+interface GetCommandParams {
+    /** The name of the DynamoDB table */
+    tableName: string;
+    /** The primary key of the item to get */
+    key: PrimaryKeyWithoutExpression;
+    /** Comma-separated list of attributes to return */
+    projectionExpression?: string;
+    /** Map of expression attribute name placeholders to actual names */
+    expressionAttributeNames?: Record<string, string>;
+    /** Whether to use strongly consistent reads */
+    consistentRead?: boolean;
+}
+/**
+ * Function type for executing DynamoDB get operations.
+ * @typeParam T - The type of item being retrieved
+ */
+type GetExecutor<T extends DynamoItem> = (params: GetCommandParams) => Promise<{
+    item: T | undefined;
+}>;
+/**
+ * Builder for creating DynamoDB get operations.
+ * Use this builder when you need to:
+ * - Retrieve a single dinosaur by its primary key
+ * - Project specific dinosaur attributes
+ * - Use consistent reads for critical dinosaur data
+ *
+ * @example
+ * ```typescript
+ * // Simple get
+ * const result = await new GetBuilder(executor, { pk: 'dinosaur#123', sk: 'profile' })
+ *   .execute();
+ *
+ * // Get with projection and consistent read
+ * const result = await new GetBuilder(executor, { pk: 'dinosaur#123', sk: 'profile' })
+ *   .select(['species', 'name', 'diet'])
+ *   .consistentRead()
+ *   .execute();
+ * ```
+ *
+ * @typeParam T - The type of item being retrieved
+ */
+declare class GetBuilder<T extends DynamoItem> {
+    private readonly executor;
+    private readonly params;
+    private options;
+    private selectedFields;
+    /**
+     * Creates a new GetBuilder instance.
+     *
+     * @param executor - Function that executes the get operation
+     * @param key - Primary key of the item to retrieve
+     * @param tableName - Name of the DynamoDB table
+     */
+    constructor(executor: GetExecutor<T>, key: PrimaryKeyWithoutExpression, tableName: string);
+    /**
+     * Specifies which attributes to return in the get results.
+     *
+     * @example
+     * ```typescript
+     * // Select single attribute
+     * builder.select('species')
+     *
+     * // Select multiple attributes
+     * builder.select(['id', 'species', 'diet'])
+     *
+     * // Chain multiple select calls
+     * builder
+     *   .select('id')
+     *   .select(['species', 'diet'])
+     * ```
+     *
+     * @param fields - A single field name or an array of field names to return
+     * @returns The builder instance for method chaining
+     */
+    select<K extends Path<T>>(fields: K | K[]): GetBuilder<T>;
+    /**
+     * Sets whether to use strongly consistent reads for the get operation.
+     * Use this method when you need:
+     * - The most up-to-date dinosaur data
+     * - To ensure you're reading the latest dinosaur status
+     * - Critical safety information about dangerous species
+     *
+     * Note: Consistent reads consume twice the throughput
+     *
+     * @example
+     * ```typescript
+     * // Get the latest T-Rex data
+     * const result = await new GetBuilder(executor, { pk: 'dinosaur#123', sk: 'profile' })
+     *   .consistentRead()
+     *   .execute();
+     * ```
+     *
+     * @param consistentRead - Whether to use consistent reads (defaults to true)
+     * @returns The builder instance for method chaining
+     */
+    consistentRead(consistentRead?: boolean): GetBuilder<T>;
+    /**
+     * Adds this get operation to a batch with optional entity type information.
+     *
+     * @example Basic Usage
+     * ```ts
+     * const batch = table.batchBuilder();
+     *
+     * // Add multiple get operations to batch
+     * dinosaurRepo.get({ id: 'dino-1' }).withBatch(batch);
+     * dinosaurRepo.get({ id: 'dino-2' }).withBatch(batch);
+     * dinosaurRepo.get({ id: 'dino-3' }).withBatch(batch);
+     *
+     * // Execute all gets efficiently
+     * const results = await batch.execute();
+     * ```
+     *
+     * @example Typed Usage
+     * ```ts
+     * const batch = table.batchBuilder<{
+     *   User: UserEntity;
+     *   Order: OrderEntity;
+     * }>();
+     *
+     * // Add operations with type information
+     * userRepo.get({ id: 'user-1' }).withBatch(batch, 'User');
+     * orderRepo.get({ id: 'order-1' }).withBatch(batch, 'Order');
+     *
+     * // Execute and get typed results
+     * const result = await batch.execute();
+     * const users: UserEntity[] = result.reads.itemsByType.User;
+     * const orders: OrderEntity[] = result.reads.itemsByType.Order;
+     * ```
+     *
+     * @param batch - The batch builder to add this operation to
+     * @param entityType - Optional entity type key for type tracking
+     */
+    withBatch<TEntities extends Record<string, DynamoItem> = Record<string, DynamoItem>, K extends keyof TEntities = keyof TEntities>(batch: BatchBuilder<TEntities>, entityType?: K): void;
+    /**
+     * Converts the builder configuration to a DynamoDB command
+     */
+    private toDynamoCommand;
+    /**
+     * Executes the get operation against DynamoDB.
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const result = await new GetBuilder(executor, { pk: 'dinosaur#123', sk: 'profile' })
+     *     .select(['species', 'name', 'diet'])
+     *     .consistentRead()
+     *     .execute();
+     *
+     *   if (result.item) {
+     *     console.log('Dinosaur found:', result.item);
+     *   } else {
+     *     console.log('Dinosaur not found');
+     *   }
+     * } catch (error) {
+     *   console.error('Error getting dinosaur:', error);
+     * }
+     * ```
+     *
+     * @returns A promise that resolves to an object containing:
+     *          - item: The retrieved dinosaur or undefined if not found
+     */
+    execute(): Promise<{
+        item: T | undefined;
+    }>;
+}
+
+/**
+ * Configuration for batch operations
+ */
+interface BatchConfig {
+    partitionKey: string;
+    sortKey?: string;
+}
+/**
+ * Executor function for batch write operations
+ */
+type BatchWriteExecutor = (operations: Array<BatchWriteOperation<DynamoItem>>) => Promise<{
+    unprocessedItems: Array<BatchWriteOperation<DynamoItem>>;
+}>;
+/**
+ * Executor function for batch get operations
+ */
+type BatchGetExecutor = (keys: Array<PrimaryKeyWithoutExpression>) => Promise<{
+    items: DynamoItem[];
+    unprocessedKeys: PrimaryKeyWithoutExpression[];
+}>;
+/**
+ * Error class for batch operation failures
+ */
+declare class BatchError extends Error {
+    readonly operation: "write" | "read";
+    readonly cause?: Error;
+    constructor(message: string, operation: "write" | "read", cause?: Error);
+}
+/**
+ * Result structure for batch operations
+ */
+interface BatchResult {
+    /** Whether the batch operation completed successfully */
+    success: boolean;
+    /** Write operation results */
+    writes: {
+        /** Number of write operations processed successfully */
+        processed: number;
+        /** Write operations that were not processed and may need retry */
+        unprocessed: Array<BatchWriteOperation<DynamoItem>>;
+    };
+    /** Read operation results */
+    reads: {
+        /** Items retrieved from the batch get operations */
+        items: DynamoItem[];
+        /** Number of items found and returned */
+        found: number;
+        /** Keys that were not processed and may need retry */
+        unprocessed: PrimaryKeyWithoutExpression[];
+    };
+    /** Total number of operations in the batch */
+    totalOperations: number;
+    /** Any errors that occurred during batch processing */
+    errors?: BatchError[];
+}
+/**
+ * Typed result structure for batch operations with entity type information
+ */
+interface TypedBatchResult<TEntities extends Record<string, DynamoItem> = Record<string, DynamoItem>> {
+    /** Whether the batch operation completed successfully */
+    success: boolean;
+    /** Write operation results */
+    writes: {
+        /** Number of write operations processed successfully */
+        processed: number;
+        /** Write operations that were not processed and may need retry */
+        unprocessed: Array<BatchWriteOperation<DynamoItem>>;
+    };
+    /** Read operation results with typed items */
+    reads: {
+        /** Items retrieved from the batch get operations, grouped by entity type */
+        itemsByType: {
+            [K in keyof TEntities]: TEntities[K][];
+        };
+        /** All items retrieved (typed as union of all entity types) */
+        items: TEntities[keyof TEntities][];
+        /** Number of items found and returned */
+        found: number;
+        /** Keys that were not processed and may need retry */
+        unprocessed: PrimaryKeyWithoutExpression[];
+    };
+    /** Total number of operations in the batch */
+    totalOperations: number;
+    /** Any errors that occurred during batch execution */
+    errors?: BatchError[];
+}
+/**
+ * Builder for creating and executing DynamoDB batch operations with full entity support and type inference.
+ *
+ * Use BatchBuilder when you need to:
+ * - Perform multiple operations efficiently (up to 25 writes, 100 reads per batch)
+ * - Maintain entity validation, key generation, and type safety
+ * - Mix read and write operations in a single batch
+ * - Get typed results grouped by entity type
+ *
+ * @example Basic Usage
+ * ```typescript
+ * // Define entity types for the batch
+ * const batch = table.batchBuilder<{
+ *   User: UserEntity;
+ *   Order: OrderEntity;
+ * }>();
+ *
+ * // Add operations using entity repositories
+ * userRepo.create(newUser).withBatch(batch, 'User')
+ * userRepo.delete({ id: 'old-user' }).withBatch(batch, 'User')
+ * orderRepo.get({ id: 'existing-order' }).withBatch(batch, 'Order')
+ *
+ * // Execute all operations and get typed results
+ * const result = await batch.execute()
+ * const users: UserEntity[] = result.reads.itemsByType.User
+ * const orders: OrderEntity[] = result.reads.itemsByType.Order
+ * ```
+ *
+ * @example Error Handling
+ * ```typescript
+ * try {
+ *   const result = await batch.execute()
+ *
+ *   if (result.writes.unprocessed.length > 0) {
+ *     console.warn('Some writes were not processed:', result.writes.unprocessed)
+ *   }
+ * } catch (error) {
+ *   if (error instanceof BatchError) {
+ *     console.error('Batch operation failed:', error.message)
+ *   }
+ * }
+ * ```
+ */
+declare class BatchBuilder<TEntities extends Record<string, DynamoItem> = Record<string, DynamoItem>> {
+    private batchWriteExecutor;
+    private batchGetExecutor;
+    private config;
+    private writeItems;
+    private getItems;
+    constructor(batchWriteExecutor: BatchWriteExecutor, batchGetExecutor: BatchGetExecutor, config: BatchConfig);
+    /**
+     * Checks if the batch is empty (contains no operations)
+     *
+     * @returns true if the batch contains no operations
+     */
+    isEmpty(): boolean;
+    /**
+     * Gets the count of operations in the batch
+     *
+     * @returns Object containing the count of write and read operations
+     */
+    getOperationCount(): {
+        writes: number;
+        reads: number;
+    };
+    /**
+     * Validates that the batch is not empty before execution
+     *
+     * @throws {BatchError} If the batch is empty
+     */
+    private validateNotEmpty;
+    /**
+     * Adds a put operation to the batch with entity type information.
+     * This method is used internally by entity builders.
+     *
+     * @param command - The complete put command configuration
+     * @param entityType - The entity type name for type tracking
+     * @returns The batch builder for method chaining
+     * @internal
+     */
+    putWithCommand<K extends keyof TEntities>(command: PutCommandParams, entityType?: K): this;
+    /**
+     * Adds a delete operation to the batch with entity type information.
+     * This method is used internally by entity builders.
+     *
+     * @param command - The complete delete command configuration
+     * @param entityType - The entity type name for type tracking
+     * @returns The batch builder for method chaining
+     * @internal
+     */
+    deleteWithCommand<K extends keyof TEntities>(command: DeleteCommandParams, entityType?: K): this;
+    /**
+     * Adds a get operation to the batch with entity type information.
+     * This method is used internally by entity builders.
+     *
+     * @param command - The complete get command configuration
+     * @param entityType - The entity type name for type tracking
+     * @returns The batch builder for method chaining
+     * @internal
+     */
+    getWithCommand<K extends keyof TEntities>(command: GetCommandParams, entityType?: K): this;
+    /**
+     * Executes all write operations in the batch.
+     *
+     * @returns A promise that resolves to any unprocessed operations
+     * @private
+     */
+    private executeWrites;
+    /**
+     * Executes all get operations in the batch.
+     *
+     * @returns A promise that resolves to the retrieved items
+     * @private
+     */
+    private executeGets;
+    /**
+     * Groups retrieved items by their entity type.
+     * @private
+     */
+    private groupItemsByType;
+    /**
+     * Executes all operations in the batch with typed results.
+     * Performs write operations first, then get operations.
+     *
+     * @returns A promise that resolves to a TypedBatchResult with entity type information
+     * @throws {BatchError} If the batch is empty or if operations fail
+     */
+    execute(): Promise<TypedBatchResult<TEntities>>;
+}
+
+/**
+ * Configuration options for DynamoDB transactions.
+ */
+interface TransactionOptions {
+    /** Unique identifier for the transaction request (idempotency token) */
+    clientRequestToken?: string;
+    /** Level of consumed capacity details to return */
+    returnConsumedCapacity?: "INDEXES" | "TOTAL" | "NONE";
+    /** Whether to return item collection metrics */
+    returnItemCollectionMetrics?: "SIZE" | "NONE";
+}
+/**
+ * Configuration for table indexes used in duplicate detection.
+ * Defines the key structure for checking uniqueness constraints.
+ */
+interface IndexConfig {
+    /** The partition key attribute name */
+    partitionKey: string;
+    /** Optional sort key attribute name */
+    sortKey?: string;
+}
+/**
+ * Function type for executing DynamoDB transaction operations.
+ * @param params - The complete transaction command input
+ * @returns A promise that resolves when the transaction completes
+ */
+type TransactionExecutor = (params: TransactWriteCommandInput) => Promise<void>;
+/**
+ * Builder for creating and executing DynamoDB transactions.
+ * Use this builder when you need to:
+ * - Perform multiple operations atomically
+ * - Ensure data consistency across operations
+ * - Implement complex business logic that requires atomic updates
+ * - Prevent duplicate items across tables
+ *
+ * The builder supports:
+ * - Put operations (insert/replace items)
+ * - Delete operations
+ * - Update operations
+ * - Condition checks
+ * - Duplicate detection
+ * - Transaction-wide options
+ *
+ * @example
+ * ```typescript
+ * // Create a transaction with multiple operations
+ * const transaction = new TransactionBuilder(executor, {
+ *   partitionKey: 'id',
+ *   sortKey: 'type'
+ * });
+ *
+ * // Add a new order
+ * transaction.put('orders', {
+ *   orderId: '123',
+ *   status: 'PENDING'
+ * });
+ *
+ * // Update inventory with condition
+ * transaction.update(
+ *   'inventory',
+ *   { productId: 'ABC' },
+ *   'set quantity = quantity - :amount',
+ *   { ':amount': 1 },
+ *   op => op.gte('quantity', 1)
+ * );
+ *
+ * // Execute the transaction atomically
+ * await transaction.execute();
+ * ```
+ *
+ * Note: DynamoDB transactions have some limitations:
+ * - Maximum 25 operations per transaction
+ * - All operations must be in the same AWS region
+ * - Cannot include table scans or queries
+ */
+declare class TransactionBuilder {
+    private items;
+    private options;
+    private indexConfig;
+    private readonly executor;
+    constructor(executor: TransactionExecutor, indexConfig: IndexConfig);
+    /**
+     * Checks if an item with the same primary key already exists in the transaction
+     * @private
+     */
+    private checkForDuplicateItem;
+    createKeyForPrimaryIndex(key: PrimaryKeyWithoutExpression): {
+        [x: string]: string;
+    };
+    /**
+     * Adds a put operation to the transaction.
+     *
+     * The method automatically checks for duplicate items within the transaction
+     * to prevent multiple operations on the same item.
+     *
+     * @example
+     * ```typescript
+     * // Simple put operation
+     * transaction.put('orders', {
+     *   orderId: '123',
+     *   status: 'PENDING',
+     *   amount: 100
+     * });
+     *
+     * // Conditional put operation
+     * transaction.put(
+     *   'inventory',
+     *   { productId: 'ABC', quantity: 50 },
+     *   op => op.attributeNotExists('productId')
+     * );
+     *
+     * // Put with complex condition
+     * transaction.put(
+     *   'users',
+     *   { userId: '123', status: 'ACTIVE' },
+     *   op => op.and([
+     *     op.attributeNotExists('userId'),
+     *     op.beginsWith('status', 'ACTIVE')
+     *   ])
+     * );
+     * ```
+     *
+     * @param tableName - The name of the DynamoDB table
+     * @param item - The item to put into the table
+     * @param condition - Optional condition that must be satisfied
+     * @returns The transaction builder for method chaining
+     * @throws {Error} If a duplicate item is detected in the transaction
+     */
+    put<T extends DynamoItem>(tableName: string, item: T, condition?: Condition): this;
+    /**
+     * Adds a pre-configured put operation to the transaction.
+     *
+     * This method is particularly useful when working with PutBuilder
+     * to maintain consistency in put operations across your application.
+     *
+     * @example
+     * ```typescript
+     * // Create a put command with PutBuilder
+     * const putCommand = new PutBuilder(executor, newItem, 'users')
+     *   .condition(op => op.attributeNotExists('userId'))
+     *   .toDynamoCommand();
+     *
+     * // Add the command to the transaction
+     * transaction.putWithCommand(putCommand);
+     * ```
+     *
+     * @param command - The complete put command configuration
+     * @returns The transaction builder for method chaining
+     * @throws {Error} If a duplicate item is detected in the transaction
+     * @see PutBuilder for creating put commands
+     */
+    putWithCommand(command: PutCommandParams): TransactionBuilder;
+    /**
+     * Adds a delete operation to the transaction.
+     *
+     * The method automatically checks for duplicate items within the transaction
+     * to prevent multiple operations on the same item.
+     *
+     * @example
+     * ```typescript
+     * // Simple delete operation
+     * transaction.delete('orders', {
+     *   pk: 'ORDER#123',
+     *   sk: 'METADATA'
+     * });
+     *
+     * // Conditional delete operation
+     * transaction.delete(
+     *   'users',
+     *   { pk: 'USER#123' },
+     *   op => op.eq('status', 'INACTIVE')
+     * );
+     *
+     * // Delete with complex condition
+     * transaction.delete(
+     *   'products',
+     *   { pk: 'PROD#ABC' },
+     *   op => op.and([
+     *     op.eq('status', 'DRAFT'),
+     *     op.lt('version', 5)
+     *   ])
+     * );
+     * ```
+     *
+     * @param tableName - The name of the DynamoDB table
+     * @param key - The primary key of the item to delete
+     * @param condition - Optional condition that must be satisfied
+     * @returns The transaction builder for method chaining
+     * @throws {Error} If a duplicate item is detected in the transaction
+     */
+    delete(tableName: string, key: PrimaryKeyWithoutExpression, condition?: Condition): TransactionBuilder;
+    /**
+     * Adds a pre-configured delete operation to the transaction.
+     *
+     * This method is particularly useful when working with DeleteBuilder
+     * to maintain consistency in delete operations across your application.
+     *
+     * @example
+     * ```typescript
+     * // Create a delete command with DeleteBuilder
+     * const deleteCommand = new DeleteBuilder(executor, 'users', { pk: 'USER#123' })
+     *   .condition(op => op.and([
+     *     op.attributeExists('pk'),
+     *     op.eq('status', 'INACTIVE')
+     *   ]))
+     *   .toDynamoCommand();
+     *
+     * // Add the command to the transaction
+     * transaction.deleteWithCommand(deleteCommand);
+     * ```
+     *
+     * @param command - The complete delete command configuration
+     * @returns The transaction builder for method chaining
+     * @throws {Error} If a duplicate item is detected in the transaction
+     * @see DeleteBuilder for creating delete commands
+     */
+    deleteWithCommand(command: DeleteCommandParams): this;
+    /**
+     * Adds an update operation to the transaction.
+     *
+     * The method supports all DynamoDB update expressions:
+     * - SET: Modify or add attributes
+     * - REMOVE: Delete attributes
+     * - ADD: Update numbers and sets
+     * - DELETE: Remove elements from a set
+     *
+     * @example
+     * ```typescript
+     * // Simple update
+     * transaction.update(
+     *   'orders',
+     *   { pk: 'ORDER#123' },
+     *   'SET #status = :status',
+     *   { '#status': 'status' },
+     *   { ':status': 'PROCESSING' }
+     * );
+     *
+     * // Complex update with multiple operations
+     * transaction.update(
+     *   'products',
+     *   { pk: 'PROD#ABC' },
+     *   'SET #qty = #qty - :amount, #status = :status REMOVE #oldAttr',
+     *   { '#qty': 'quantity', '#status': 'status', '#oldAttr': 'deprecated_field' },
+     *   { ':amount': 1, ':status': 'LOW_STOCK' }
+     * );
+     *
+     * // Conditional update
+     * transaction.update(
+     *   'users',
+     *   { pk: 'USER#123' },
+     *   'SET #lastLogin = :now',
+     *   { '#lastLogin': 'lastLoginDate' },
+     *   { ':now': new Date().toISOString() },
+     *   op => op.attributeExists('pk')
+     * );
+     * ```
+     *
+     * @param tableName - The name of the DynamoDB table
+     * @param key - The primary key of the item to update
+     * @param updateExpression - The update expression (SET, REMOVE, ADD, DELETE)
+     * @param expressionAttributeNames - Map of attribute name placeholders to actual names
+     * @param expressionAttributeValues - Map of value placeholders to actual values
+     * @param condition - Optional condition that must be satisfied
+     * @returns The transaction builder for method chaining
+     * @throws {Error} If a duplicate item is detected in the transaction
+     */
+    update<T extends DynamoItem>(tableName: string, key: PrimaryKeyWithoutExpression, updateExpression: string, expressionAttributeNames?: Record<string, string>, expressionAttributeValues?: Record<string, unknown>, condition?: Condition): this;
+    /**
+     * Adds a pre-configured update operation to the transaction.
+     *
+     * This method is particularly useful when working with UpdateBuilder
+     * to maintain consistency in update operations across your application.
+     *
+     * @example
+     * ```typescript
+     * // Create an update command with UpdateBuilder
+     * const updateCommand = new UpdateBuilder(executor, 'inventory', { pk: 'PROD#ABC' })
+     *   .set('quantity', ':qty')
+     *   .set('lastUpdated', ':now')
+     *   .values({
+     *     ':qty': 100,
+     *     ':now': new Date().toISOString()
+     *   })
+     *   .condition(op => op.gt('quantity', 0))
+     *   .toDynamoCommand();
+     *
+     * // Add the command to the transaction
+     * transaction.updateWithCommand(updateCommand);
+     * ```
+     *
+     * @param command - The complete update command configuration
+     * @returns The transaction builder for method chaining
+     * @throws {Error} If a duplicate item is detected in the transaction
+     * @see UpdateBuilder for creating update commands
+     */
+    updateWithCommand(command: UpdateCommandParams): TransactionBuilder;
+    /**
+     * Adds a condition check operation to the transaction.
+     *
+     * Condition checks are particularly useful for:
+     * - Implementing optimistic locking
+     * - Ensuring referential integrity
+     * - Validating business rules atomically
+     *
+     * @example
+     * ```typescript
+     * // Check if order is in correct state
+     * transaction.conditionCheck(
+     *   'orders',
+     *   { pk: 'ORDER#123' },
+     *   op => op.eq('status', 'PENDING')
+     * );
+     *
+     * // Complex condition check
+     * transaction.conditionCheck(
+     *   'inventory',
+     *   { pk: 'PROD#ABC' },
+     *   op => op.and([
+     *     op.gt('quantity', 0),
+     *     op.eq('status', 'ACTIVE'),
+     *     op.attributeExists('lastRestockDate')
+     *   ])
+     * );
+     *
+     * // Check with multiple attributes
+     * transaction.conditionCheck(
+     *   'users',
+     *   { pk: 'USER#123' },
+     *   op => op.or([
+     *     op.eq('status', 'PREMIUM'),
+     *     op.gte('credits', 100)
+     *   ])
+     * );
+     * ```
+     *
+     * @param tableName - The name of the DynamoDB table
+     * @param key - The primary key of the item to check
+     * @param condition - The condition that must be satisfied
+     * @returns The transaction builder for method chaining
+     * @throws {Error} If a duplicate item is detected in the transaction
+     * @throws {Error} If condition expression generation fails
+     */
+    conditionCheck(tableName: string, key: PrimaryKeyWithoutExpression, condition: Condition): TransactionBuilder;
+    /**
+     * Adds a pre-configured condition check operation to the transaction.
+     *
+     * This method is particularly useful when working with ConditionCheckBuilder
+     * to maintain consistency in condition checks across your application.
+     *
+     * @example
+     * ```typescript
+     * // Create a condition check with ConditionCheckBuilder
+     * const checkCommand = new ConditionCheckBuilder('inventory', { pk: 'PROD#ABC' })
+     *   .condition(op => op.and([
+     *     op.between('quantity', 10, 100),
+     *     op.beginsWith('category', 'ELECTRONICS'),
+     *     op.attributeExists('lastAuditDate')
+     *   ]))
+     *   .toDynamoCommand();
+     *
+     * // Add the command to the transaction
+     * transaction.conditionCheckWithCommand(checkCommand);
+     * ```
+     *
+     * @param command - The complete condition check command configuration
+     * @returns The transaction builder for method chaining
+     * @throws {Error} If a duplicate item is detected in the transaction
+     * @see ConditionCheckBuilder for creating condition check commands
+     */
+    conditionCheckWithCommand(command: ConditionCheckCommandParams): TransactionBuilder;
+    /**
+     * Sets options for the transaction execution.
+     *
+     * @example
+     * ```typescript
+     * // Enable idempotency and capacity tracking
+     * transaction.withOptions({
+     *   clientRequestToken: 'unique-request-id-123',
+     *   returnConsumedCapacity: 'TOTAL'
+     * });
+     *
+     * // Track item collection metrics
+     * transaction.withOptions({
+     *   returnItemCollectionMetrics: 'SIZE'
+     * });
+     * ```
+     *
+     * Note: ClientRequestToken can be used to make transactions idempotent,
+     * ensuring the same transaction is not executed multiple times.
+     *
+     * @param options - Configuration options for the transaction
+     * @returns The transaction builder for method chaining
+     */
+    withOptions(options: TransactionOptions): TransactionBuilder;
+    /**
+     * Gets a human-readable representation of the transaction items.
+     *
+     * The method resolves all expression placeholders with their actual values,
+     * making it easier to understand the transaction's operations.
+     *
+     * @example
+     * ```typescript
+     * // Add multiple operations
+     * transaction
+     *   .put('orders', { orderId: '123', status: 'PENDING' })
+     *   .update('inventory',
+     *     { productId: 'ABC' },
+     *     'SET quantity = quantity - :amount',
+     *     undefined,
+     *     { ':amount': 1 }
+     *   );
+     *
+     * // Debug the transaction
+     * const debugInfo = transaction.debug();
+     * console.log('Transaction operations:', debugInfo);
+     * ```
+     *
+     * @returns An array of readable representations of the transaction items
+     */
+    debug(): Record<string, unknown>[];
+    /**
+     * Executes all operations in the transaction atomically.
+     *
+     * The transaction will only succeed if all operations succeed.
+     * If any operation fails, the entire transaction is rolled back.
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   // Build and execute transaction
+     *   await transaction
+     *     .put('orders', newOrder)
+     *     .update('inventory',
+     *       { productId: 'ABC' },
+     *       'SET quantity = quantity - :qty',
+     *       undefined,
+     *       { ':qty': 1 }
+     *     )
+     *     .conditionCheck('products',
+     *       { productId: 'ABC' },
+     *       op => op.eq('status', 'ACTIVE')
+     *     )
+     *     .execute();
+     *
+     *   console.log('Transaction completed successfully');
+     * } catch (error) {
+     *   // Handle transaction failure
+     *   console.error('Transaction failed:', error);
+     * }
+     * ```
+     *
+     * @throws {Error} If no transaction items are specified
+     * @throws {Error} If any operation in the transaction fails
+     * @returns A promise that resolves when the transaction completes
+     */
+    execute(): Promise<void>;
+}
+
+interface DeleteOptions {
+    condition?: Condition;
+    returnValues?: "ALL_OLD";
+}
+type DeleteExecutor = (params: DeleteCommandParams) => Promise<{
+    item?: DynamoItem;
+}>;
+/**
+ * Builder for creating DynamoDB delete operations.
+ *
+ * @example
+ * ```typescript
+ * // Simple delete
+ * const result = await new DeleteBuilder(executor, 'dinosaurs', { id: 'TREX-001' })
+ *   .execute();
+ *
+ * // Conditional delete with old value retrieval
+ * const result = await new DeleteBuilder(executor, 'habitats', { id: 'PADDOCK-A' })
+ *   .condition(op =>
+ *     op.and([
+ *       op.eq('status', 'DECOMMISSIONED'),
+ *       op.eq('occupants', 0),
+ *       op.lt('securityIncidents', 1)
+ *     ])
+ *   )
+ *   .returnValues('ALL_OLD')
+ *   .execute();
+ * ```
+ */
+declare class DeleteBuilder {
+    private options;
+    private readonly executor;
+    private readonly tableName;
+    private readonly key;
+    constructor(executor: DeleteExecutor, tableName: string, key: PrimaryKeyWithoutExpression);
+    /**
+     * Adds a condition that must be satisfied for the delete operation to succeed.
+     *
+     * @example
+     * ```typescript
+     * // Ensure dinosaur can be safely removed
+     * builder.condition(op =>
+     *   op.and([
+     *     op.eq('status', 'SEDATED'),
+     *     op.eq('location', 'MEDICAL_BAY'),
+     *     op.attributeExists('lastCheckup')
+     *   ])
+     * );
+     *
+     * // Verify habitat is empty
+     * builder.condition(op =>
+     *   op.and([
+     *     op.eq('occupants', 0),
+     *     op.eq('maintenanceStatus', 'COMPLETE'),
+     *     op.not(op.attributeExists('activeAlerts'))
+     *   ])
+     * );
+     * ```
+     *
+     * @param condition - Either a Condition object or a callback function that builds the condition
+     * @returns The builder instance for method chaining
+     */
+    condition<T extends DynamoItem>(condition: Condition | ((op: ConditionOperator<T>) => Condition)): DeleteBuilder;
+    /**
+     * Sets whether to return the item's attribute values before deletion.
+     *
+     * @example
+     * ```ts
+     * // Archive dinosaur data before removal
+     * const result = await builder
+     *   .returnValues('ALL_OLD')
+     *   .execute();
+     *
+     * if (result.item) {
+     *   console.log('Removed dinosaur data:', {
+     *     species: result.item.species,
+     *     age: result.item.age,
+     *     lastLocation: result.item.location
+     *   });
+     * }
+     * ```
+     *
+     * @param returnValues - Use 'ALL_OLD' to return all attributes of the deleted item
+     * @returns The builder instance for method chaining
+     */
+    returnValues(returnValues: "ALL_OLD"): DeleteBuilder;
+    /**
+     * Generate the DynamoDB command parameters
+     */
+    private toDynamoCommand;
+    /**
+     * Adds this delete operation to a transaction.
+     *
+     * @example
+     * ```ts
+     * const transaction = new TransactionBuilder();
+     *
+     * // Remove dinosaur from old habitat
+     * new DeleteBuilder(executor, 'dinosaurs', { id: 'RAPTOR-001' })
+     *   .condition(op => op.eq('status', 'SEDATED'))
+     *   .withTransaction(transaction);
+     *
+     * // Update old habitat occupancy
+     * new UpdateBuilder(executor, 'habitats', { id: 'PADDOCK-A' })
+     *   .add('occupants', -1)
+     *   .withTransaction(transaction);
+     *
+     * // Execute transfer atomically
+     * await transaction.execute();
+     * ```
+     *
+     * @param transaction - The transaction builder to add this operation to
+     */
+    withTransaction(transaction: TransactionBuilder): void;
+    /**
+     * Adds this delete operation to a batch with optional entity type information.
+     *
+     * @example Basic Usage
+     * ```ts
+     * const batch = table.batchBuilder();
+     *
+     * // Remove multiple dinosaurs in batch
+     * dinosaurRepo.delete({ id: 'old-dino-1' }).withBatch(batch);
+     * dinosaurRepo.delete({ id: 'old-dino-2' }).withBatch(batch);
+     * dinosaurRepo.delete({ id: 'old-dino-3' }).withBatch(batch);
+     *
+     * // Execute all deletions efficiently
+     * await batch.execute();
+     * ```
+     *
+     * @example Typed Usage
+     * ```ts
+     * const batch = table.batchBuilder<{
+     *   User: UserEntity;
+     *   Order: OrderEntity;
+     * }>();
+     *
+     * // Add operations with type information
+     * userRepo.delete({ id: 'user-1' }).withBatch(batch, 'User');
+     * orderRepo.delete({ id: 'order-1' }).withBatch(batch, 'Order');
+     *
+     * // Execute batch operations
+     * await batch.execute();
+     * ```
+     *
+     * @param batch - The batch builder to add this operation to
+     * @param entityType - Optional entity type key for type tracking
+     */
+    withBatch<TEntities extends Record<string, DynamoItem> = Record<string, DynamoItem>, K extends keyof TEntities = keyof TEntities>(batch: BatchBuilder<TEntities>, entityType?: K): void;
+    /**
+     * Executes the delete operation against DynamoDB.
+     *
+     * @example
+     * ```ts
+     * // Delete with condition and retrieve old values
+     * const result = await new DeleteBuilder(executor, 'myTable', { id: '123' })
+     *   .condition(op => op.eq('status', 'INACTIVE'))
+     *   .returnValues('ALL_OLD')
+     *   .execute();
+     *
+     * if (result.item) {
+     *   console.log('Deleted item:', result.item);
+     * }
+     * ```
+     *
+     * @returns A promise that resolves to an object containing the deleted item's attributes (if returnValues is 'ALL_OLD')
+     */
+    execute(): Promise<{
+        item?: DynamoItem;
+    }>;
+    /**
+     * Gets a human-readable representation of the delete command
+     * with all expression placeholders replaced by their actual values.
+     *
+     * @example
+     * ```ts
+     * const debugInfo = new DeleteBuilder(executor, 'dinosaurs', { id: 'TREX-001' })
+     *   .condition(op => op.and([
+     *     op.eq('status', 'SEDATED'),
+     *     op.eq('location', 'MEDICAL_BAY'),
+     *     op.gt('sedationLevel', 8)
+     *     op.eq('version', 1),
+     *     op.attributeExists('status')
+     *   ]))
+     *   .debug();
+     *
+     * console.log('Delete command:', debugInfo);
+     * ```
+     *
+     * @returns A readable representation of the delete command with resolved expressions
+     */
+    debug(): {
+        raw: DeleteCommandParams;
+        readable: {
+            conditionExpression?: string;
+            updateExpression?: string;
+            filterExpression?: string;
+            keyConditionExpression?: string;
+            projectionExpression?: string;
+        };
+    };
+}
+
+/**
+ * Configuration options for DynamoDB put operations.
+ */
+interface PutOptions {
+    /** Optional condition that must be satisfied for the put operation to succeed */
+    condition?: Condition;
+    /** Determines how to handle the return value of the put operation
+     * @options
+     *  - NONE: No return value
+     *  - ALL_OLD: Returns the item's previous state if it existed
+     *  - CONSISTENT: Performs a GET operation after the put to retrieve the item's new state
+     *  - INPUT: Returns the input values that were passed to the operation
+     */
+    returnValues?: "ALL_OLD" | "NONE" | "CONSISTENT" | "INPUT";
+}
+type PutExecutor<T extends DynamoItem> = (params: PutCommandParams) => Promise<T>;
+/**
+ * Builder for creating DynamoDB put operations.
+ *
+ * @example
+ * ```typescript
+ * // Add new dinosaur
+ * const result = await new PutBuilder(executor, {
+ *   id: 'RAPTOR-001',
+ *   species: 'Velociraptor',
+ *   status: 'ACTIVE',
+ *   stats: {
+ *     health: 100,
+ *     age: 5,
+ *     threatLevel: 8
+ *   }
+ * }, 'dinosaurs').execute();
+ *
+ * // Create new habitat with conditions
+ * const result = await new PutBuilder(executor, {
+ *   id: 'PADDOCK-C',
+ *   type: 'CARNIVORE',
+ *   securityLevel: 'MAXIMUM',
+ *   capacity: 3,
+ *   environmentType: 'TROPICAL'
+ * }, 'habitats')
+ *   .condition(op => op.attributeNotExists('id'))
+ *   .execute();
+ * ```
+ *
+ * @typeParam T - The type of item being put into the table
+ */
+declare class PutBuilder<T extends DynamoItem> {
+    private readonly item;
+    private options;
+    private readonly executor;
+    private readonly tableName;
+    constructor(executor: PutExecutor<T>, item: T, tableName: string);
+    /**
+     * Sets multiple attributes of an item using an DynamoItem.
+     *
+     * @example
+     * ```typescript
+     * // Update multiple attributes
+     * builder.set({
+     *   species: 'Tyrannosaurus Rex',
+     *   height: 20,
+     *   diet: 'CARNIVORE',
+     *   'stats.threatLevel': 10
+     * });
+     * ```
+     */
+    set(values: Partial<T>): this;
+    /**
+     * Sets a single attribute to a specific value.
+     *
+     * @example
+     * ```typescript
+     * // Set simple attributes
+     * builder
+     *   .set('status', 'SLEEPING')
+     *   .set('lastFeeding', new Date().toISOString());
+     *
+     * // Set nested attributes
+     * builder
+     *   .set('location.zone', 'RESTRICTED')
+     *   .set('stats.health', 100);
+     * ```
+     */
+    set<K extends Path<T>>(path: K, value: PathType<T, K>): this;
+    /**
+     * Adds a condition that must be satisfied for the put operation to succeed.
+     *
+     * @example
+     * ```ts
+     * // Ensure item doesn't exist (insert only)
+     * builder.condition(op => op.attributeNotExists('id'))
+     *
+     * // Complex condition with version check
+     * builder.condition(op =>
+     *   op.and([
+     *     op.attributeExists('id'),
+     *     op.eq('version', currentVersion),
+     *     op.eq('status', 'ACTIVE')
+     *   ])
+     * )
+     * ```
+     *
+     * @param condition - Either a Condition object or a callback function that builds the condition
+     * @returns The builder instance for method chaining
+     */
+    /**
+     * Adds a condition that must be satisfied for the put operation to succeed.
+     *
+     * @example
+     * ```typescript
+     * // Ensure unique dinosaur ID
+     * builder.condition(op =>
+     *   op.attributeNotExists('id')
+     * );
+     *
+     * // Verify habitat requirements
+     * builder.condition(op =>
+     *   op.and([
+     *     op.eq('securityStatus', 'READY'),
+     *     op.attributeExists('lastInspection'),
+     *     op.gt('securityLevel', 5)
+     *   ])
+     * );
+     *
+     * // Check breeding facility conditions
+     * builder.condition(op =>
+     *   op.and([
+     *     op.between('temperature', 25, 30),
+     *     op.between('humidity', 60, 80),
+     *     op.eq('quarantineStatus', 'CLEAR')
+     *   ])
+     * );
+     * ```
+     *
+     * @param condition - Either a Condition object or a callback function that builds the condition
+     * @returns The builder instance for method chaining
+     */
+    condition(condition: Condition | ((op: ConditionOperator<T>) => Condition)): this;
+    /**
+     * Sets whether to return the item's previous values (if it existed).
+     *
+     * @options
+     *  - NONE: No return value
+     *  - ALL_OLD: Returns the item's previous state if it existed, no read capacity units are consumed
+     *  - CONSISTENT: Performs a GET operation after the put to retrieve the item's new state
+     *  - INPUT: Returns the input values that were passed to the operation
+     *
+     * @example
+     * ```ts
+     * // Get previous dinosaur state
+     * const result = await builder
+     *   .returnValues('ALL_OLD')
+     *   .execute();
+     *
+     * if (result) {
+     *   console.log('Previous profile:', {
+     *     species: result.species,
+     *     status: result.status,
+     *     stats: {
+     *       health: result.stats.health,
+     *       threatLevel: result.stats.threatLevel
+     *     }
+     *   });
+     * }
+     *
+     * // Return input values for create operations
+     * const createResult = await builder
+     *   .returnValues('INPUT')
+     *   .execute();
+     * ```
+     *
+     * @param returnValues - Use 'ALL_OLD' to return previous values, 'INPUT' to return input values, 'CONSISTENT' for fresh data, or 'NONE' (default).
+     * @returns The builder instance for method chaining
+     */
+    returnValues(returnValues: "ALL_OLD" | "NONE" | "CONSISTENT" | "INPUT"): this;
+    /**
+     * Generate the DynamoDB command parameters
+     */
+    private toDynamoCommand;
+    /**
+     * Adds this put operation to a transaction.
+     *
+     * @example
+     * ```ts
+     * const transaction = new TransactionBuilder();
+     *
+     * // Add dinosaur to new habitat
+     * new PutBuilder(executor, {
+     *   id: 'TREX-002',
+     *   location: 'PADDOCK-B',
+     *   status: 'ACTIVE',
+     *   transferDate: new Date().toISOString()
+     * }, 'dinosaurs')
+     *   .withTransaction(transaction);
+     *
+     * // Update habitat records
+     * new UpdateBuilder(executor, 'habitats', { id: 'PADDOCK-B' })
+     *   .add('occupants', 1)
+     *   .set('lastTransfer', new Date().toISOString())
+     *   .withTransaction(transaction);
+     *
+     * // Execute transfer atomically
+     * await transaction.execute();
+     * ```
+     *
+     * @param transaction - The transaction builder to add this operation to
+     * @returns The builder instance for method chaining
+     */
+    withTransaction(transaction: TransactionBuilder): this;
+    /**
+     * Adds this put operation to a batch with optional entity type information.
+     *
+     * @example Basic Usage
+     * ```ts
+     * const batch = table.batchBuilder();
+     *
+     * // Add multiple dinosaurs to batch
+     * dinosaurRepo.create(newDino1).withBatch(batch);
+     * dinosaurRepo.create(newDino2).withBatch(batch);
+     * dinosaurRepo.create(newDino3).withBatch(batch);
+     *
+     * // Execute all operations efficiently
+     * await batch.execute();
+     * ```
+     *
+     * @example Typed Usage
+     * ```ts
+     * const batch = table.batchBuilder<{
+     *   User: UserEntity;
+     *   Order: OrderEntity;
+     * }>();
+     *
+     * // Add operations with type information
+     * userRepo.create(newUser).withBatch(batch, 'User');
+     * orderRepo.create(newOrder).withBatch(batch, 'Order');
+     *
+     * // Execute and get typed results
+     * const result = await batch.execute();
+     * const users: UserEntity[] = result.reads.itemsByType.User;
+     * ```
+     *
+     * @param batch - The batch builder to add this operation to
+     * @param entityType - Optional entity type key for type tracking
+     */
+    withBatch<TEntities extends Record<string, DynamoItem> = Record<string, DynamoItem>, K extends keyof TEntities = keyof TEntities>(batch: BatchBuilder<TEntities>, entityType?: K): void;
+    /**
+     * Executes the put operation against DynamoDB.
+     *
+     * @example
+     * ```ts
+     * try {
+     *   // Put with condition and return old values
+     *   const result = await new PutBuilder(executor, newItem, 'myTable')
+     *     .condition(op => op.eq('version', 1))
+     *     .returnValues('ALL_OLD')
+     *     .execute();
+     *
+     *   console.log('Put successful, old item:', result);
+     * } catch (error) {
+     *   // Handle condition check failure or other errors
+     *   console.error('Put failed:', error);
+     * }
+     * ```
+     *
+     * @returns A promise that resolves to the operation result (type depends on returnValues setting)
+     * @throws Will throw an error if the condition check fails or other DynamoDB errors occur
+     */
+    execute(): Promise<T | undefined>;
+    /**
+     * Gets a human-readable representation of the put command
+     * with all expression placeholders replaced by their actual values.
+     *
+     * @example
+     * ```ts
+     * const debugInfo = new PutBuilder(executor, {
+     *   id: 'RAPTOR-003',
+     *   species: 'Velociraptor',
+     *   status: 'QUARANTINE',
+     *   stats: {
+     *     health: 100,
+     *     aggressionLevel: 7,
+     *     age: 2
+     *   }
+     * }, 'dinosaurs')
+     *   .condition(op =>
+     *     op.and([
+     *       op.attributeNotExists('id'),
+     *       op.eq('quarantineStatus', 'READY'),
+     *       op.gt('securityLevel', 8)
+     *     ])
+     *   )
+     *   .debug();
+     *
+     * console.log('Dinosaur transfer command:', debugInfo);
+     * ```
+     *
+     * @returns A readable representation of the put command with resolved expressions
+     */
+    debug(): {
+        raw: PutCommandParams;
+        readable: {
+            conditionExpression?: string;
+            updateExpression?: string;
+            filterExpression?: string;
+            keyConditionExpression?: string;
+            projectionExpression?: string;
+        };
+    };
+}
+
+/**
+ * A utility class for handling DynamoDB pagination.
+ * Use this class when you need to:
+ * - Browse large collections of dinosaurs
+ * - Review extensive security logs
+ * - Analyze habitat inspection history
+ * - Process feeding schedules
+ *
+ * The paginator maintains internal state and automatically handles:
+ * - Page boundaries
+ * - Result set limits
+ * - Continuation tokens
+ *
+ * @example
+ * ```typescript
+ * // List all velociraptors with pagination
+ * const paginator = new QueryBuilder(executor, eq('species', 'Velociraptor'))
+ *   .filter(op => op.eq('status', 'ACTIVE'))
+ *   .paginate(10);
+ *
+ * // Process each page of dinosaurs
+ * while (paginator.hasNextPage()) {
+ *   const page = await paginator.getNextPage();
+ *   console.log(`Processing page ${page.page} of velociraptors`);
+ *
+ *   for (const raptor of page.items) {
+ *     console.log(`- ${raptor.id}: Health=${raptor.stats.health}`);
+ *   }
+ * }
+ * ```
+ *
+ * @typeParam T - The type of items being paginated
+ * @typeParam TConfig - The table configuration type
+ */
+declare class Paginator<T extends DynamoItem, TConfig extends TableConfig = TableConfig> {
+    private queryBuilder;
+    private readonly pageSize?;
+    private currentPage;
+    private lastEvaluatedKey?;
+    private hasMorePages;
+    private totalItemsRetrieved;
+    private readonly overallLimit?;
+    constructor(queryBuilder: QueryBuilderInterface<T, TConfig>, pageSize?: number);
+    /**
+     * Gets the current page number (1-indexed).
+     *
+     * @example
+     * ```ts
+     * const paginator = new QueryBuilder(executor, eq('species', 'Tyrannosaurus'))
+     *   .paginate(5);
+     *
+     * await paginator.getNextPage();
+     * console.log(`Reviewing T-Rex group ${paginator.getCurrentPage()}`);
+     * ```
+     *
+     * @returns The current page number, starting from 1
+     */
+    getCurrentPage(): number;
+    /**
+     * Checks if there are more pages of dinosaurs or habitats to process.
+     *
+     * This method takes into account both:
+     * - DynamoDB's lastEvaluatedKey mechanism
+     * - Any overall limit set on the query
+     *
+     * @example
+     * ```ts
+     * // Process all security incidents
+     * const paginator = new QueryBuilder(executor, eq('type', 'SECURITY_BREACH'))
+     *   .sortDescending()
+     *   .paginate(10);
+     *
+     * while (paginator.hasNextPage()) {
+     *   const page = await paginator.getNextPage();
+     *   for (const incident of page.items) {
+     *     await processSecurityBreach(incident);
+     *   }
+     *   console.log(`Processed incidents page ${page.page}`);
+     * }
+     * ```
+     *
+     * @returns true if there are more pages available, false otherwise
+     */
+    hasNextPage(): boolean;
+    /**
+     * Retrieves the next page of dinosaurs or habitats from DynamoDB.
+     *
+     * This method handles:
+     * - Automatic continuation between groups
+     * - Respect for park capacity limits
+     * - Group size adjustments for safety
+     *
+     * @example
+     * ```ts
+     * const paginator = new QueryBuilder(executor, eq('species', 'Velociraptor'))
+     *   .filter(op => op.eq('status', 'ACTIVE'))
+     *   .paginate(5);
+     *
+     * // Check first raptor group
+     * const page1 = await paginator.getNextPage();
+     * console.log(`Found ${page1.items.length} active raptors`);
+     *
+     * // Continue inspection if more groups exist
+     * if (page1.hasNextPage) {
+     *   const page2 = await paginator.getNextPage();
+     *   console.log(`Inspecting raptor group ${page2.page}`);
+     *
+     *   for (const raptor of page2.items) {
+     *     await performHealthCheck(raptor);
+     *   }
+     * }
+     * ```
+     *
+     * @returns A promise that resolves to a PaginationResult containing:
+     *          - items: The dinosaurs/habitats for this page
+     *          - hasNextPage: Whether more groups exist
+     *          - page: The current group number
+     *          - lastEvaluatedKey: DynamoDB's continuation token
+     */
+    getNextPage(): Promise<PaginationResult<T>>;
+    /**
+     * Gets all remaining dinosaurs or habitats and combines them into a single array.
+     *
+     * @example
+     * ```ts
+     * // Get complete carnivore inventory
+     * const paginator = new QueryBuilder(executor, eq('diet', 'CARNIVORE'))
+     *   .filter(op => op.eq('status', 'ACTIVE'))
+     *   .paginate(10);
+     *
+     * try {
+     *   const allCarnivores = await paginator.getAllPages();
+     *   console.log(`Park contains ${allCarnivores.length} active carnivores`);
+     *
+     *   // Calculate total threat level
+     *   const totalThreat = allCarnivores.reduce(
+     *     (sum, dino) => sum + dino.stats.threatLevel,
+     *     0
+     *   );
+     *   console.log(`Total threat level: ${totalThreat}`);
+     * } catch (error) {
+     *   console.error('Failed to complete carnivore census:', error);
+     * }
+     * ```
+     *
+     * @returns A promise that resolves to an array containing all remaining items
+     */
+    getAllPages(): Promise<T[]>;
+}
+
+/**
+ * Configuration options for DynamoDB filter operations.
+ * These are common options shared between query and scan operations.
+ */
+interface FilterOptions {
+    /** Filter conditions applied to results */
+    filter?: Condition;
+    /** Maximum number of items to return */
+    limit?: number;
+    /** Name of the Global Secondary Index to use */
+    indexName?: string;
+    /** Whether to use strongly consistent reads */
+    consistentRead?: boolean;
+    /** List of attributes to return in the result */
+    projection?: string[];
+    /** Token for starting the operation from a specific point */
+    lastEvaluatedKey?: DynamoItem;
+}
+/**
+ * Abstract base builder for creating DynamoDB filter operations.
+ * This class provides common functionality for both Query and Scan operations.
+ *
+ * The builder supports:
+ * - Type-safe GSI selection
+ * - Complex filter conditions
+ * - Pagination
+ * - Consistent reads
+ * - Attribute projection
+ *
+ * @typeParam T - The type of items being filtered
+ * @typeParam TConfig - The table configuration type for type-safe GSI selection
+ */
+declare abstract class FilterBuilder<T extends DynamoItem, TConfig extends TableConfig = TableConfig> implements FilterBuilderInterface<T, TConfig> {
+    protected options: FilterOptions;
+    protected selectedFields: Set<string>;
+    /**
+     * Sets the maximum number of items to return.
+     *
+     * Note: This limit applies to the items that match the key condition
+     * before any filter expressions are applied.
+     *
+     * @example
+     * ```typescript
+     * // Get first 10 dinosaurs
+     * const result = await builder
+     *   .limit(10)
+     *   .execute();
+     * ```
+     *
+     * @param limit - Maximum number of items to return
+     * @returns The builder instance for method chaining
+     */
+    limit(limit: number): this;
+    /**
+     * Gets the current limit set on the operation.
+     * This is used internally by the paginator to manage result sets.
+     *
+     * @returns The current limit or undefined if no limit is set
+     */
+    getLimit(): number | undefined;
+    /**
+     * Specifies a Global Secondary Index (GSI) to use for the operation.
+     *
+     * @example
+     * ```typescript
+     * // Find all dinosaurs of a specific species
+     * builder
+     *   .useIndex('species-status-index')
+     *   .filter(op => op.eq('status', 'ACTIVE'));
+     *
+     * // Search high-security habitats
+     * builder
+     *   .useIndex('security-level-index')
+     *   .filter(op =>
+     *     op.and([
+     *       op.gt('securityLevel', 8),
+     *       op.eq('status', 'OPERATIONAL')
+     *     ])
+     *   );
+     * ```
+     *
+     * @param indexName - The name of the GSI to use (type-safe based on table configuration)
+     * @returns The builder instance for method chaining
+     */
+    useIndex<I extends GSINames<TConfig>>(indexName: I): this;
+    /**
+     * Sets whether to use strongly consistent reads for the operation.
+     *
+     * Note:
+     * - Consistent reads are not available on GSIs
+     * - Consistent reads consume twice the throughput
+     * - Default is eventually consistent reads
+     *
+     * @example
+     * ```typescript
+     * // Check immediate dinosaur status
+     * const result = await builder
+     *   .filter(op => op.eq('status', 'ACTIVE'))
+     *   .consistentRead()
+     *   .execute();
+     *
+     * // Monitor security breaches
+     * const result = await builder
+     *   .useIndex('primary-index')
+     *   .consistentRead(isEmergencyMode)
+     *   .execute();
+     * ```
+     *
+     * @param consistentRead - Whether to use consistent reads (defaults to true)
+     * @returns The builder instance for method chaining
+     */
+    consistentRead(consistentRead?: boolean): this;
+    /**
+     * Adds a filter expression to refine the operation results.
+     *
+     * @example
+     * ```typescript
+     * // Find aggressive carnivores
+     * builder.filter(op =>
+     *   op.and([
+     *     op.eq('diet', 'CARNIVORE'),
+     *     op.gt('aggressionLevel', 7),
+     *     op.eq('status', 'ACTIVE')
+     *   ])
+     * );
+     *
+     * // Search suitable breeding habitats
+     * builder.filter(op =>
+     *   op.and([
+     *     op.between('temperature', 25, 30),
+     *     op.lt('currentOccupants', 3),
+     *     op.eq('quarantineStatus', 'CLEAR')
+     *   ])
+     * );
+     * ```
+     *
+     * @param condition - Either a Condition object or a callback function that builds the condition
+     * @returns The builder instance for method chaining
+     */
+    filter(condition: Condition | ((op: ConditionOperator<T>) => Condition)): this;
+    private getConditionOperator;
+    /**
+     * Specifies which attributes to return in the results.
+     *
+     * @example
+     * ```typescript
+     * // Get basic dinosaur info
+     * builder.select([
+     *   'species',
+     *   'status',
+     *   'stats.health',
+     *   'stats.aggressionLevel'
+     * ]);
+     *
+     * // Monitor habitat conditions
+     * builder
+     *   .select('securityStatus')
+     *   .select([
+     *     'currentOccupants',
+     *     'temperature',
+     *     'lastInspectionDate'
+     *   ]);
+     * ```
+     *
+     * @param fields - A single field name or an array of field names to return
+     * @returns The builder instance for method chaining
+     */
+    select<K extends Path<T>>(fields: K | K[]): this;
+    /**
+     * Creates a paginator that handles DynamoDB pagination automatically.
+     * The paginator handles:
+     * - Tracking the last evaluated key
+     * - Managing page boundaries
+     * - Respecting overall query limits
+     *
+     * @example
+     * ```typescript
+     * // Create a paginator for dinosaur records with specific page size
+     * const paginator = builder
+     *   .filter(op => op.eq('status', 'ACTIVE'))
+     *   .paginate(10);
+     *
+     * // Create a paginator with automatic DynamoDB paging (no page size limit)
+     * const autoPaginator = builder
+     *   .filter(op => op.eq('status', 'ACTIVE'))
+     *   .paginate();
+     *
+     * // Process pages of dinosaur results
+     * while (paginator.hasNextPage()) {
+     *   const page = await paginator.getNextPage();
+     *   console.log(`Processing page ${page.page}, count: ${page.items.length}`);
+     *   // Process dinosaur data
+     * }
+     * ```
+     *
+     * @param pageSize - The number of items to return per page. If not provided, DynamoDB will automatically determine page sizes.
+     * @returns A Paginator instance that manages the pagination state
+     * @see Paginator for more pagination control options
+     */
+    paginate(pageSize?: number): Paginator<T, TConfig>;
+    /**
+     * Sets the starting point using a previous lastEvaluatedKey.
+     *
+     * Note: This method is typically used for manual pagination.
+     * For automatic pagination, use the paginate() method instead.
+     *
+     * @example
+     * ```typescript
+     * // First batch of dinosaurs
+     * const result1 = await builder
+     *   .filter(op => op.eq('status', 'ACTIVE'))
+     *   .limit(5)
+     *   .execute();
+     *
+     * const lastKey = result1.getLastEvaluatedKey();
+     * if (lastKey) {
+     *   // Continue listing dinosaurs
+     *   const result2 = await builder
+     *     .filter(op => op.eq('status', 'ACTIVE'))
+     *     .startFrom(lastKey)
+     *     .limit(5)
+     *     .execute();
+     *
+     *   const items = await result2.toArray();
+     *   console.log('Additional dinosaurs:', items);
+     * }
+     * ```
+     *
+     * @param lastEvaluatedKey - The exclusive start key from a previous result
+     * @returns The builder instance for method chaining
+     */
+    startFrom(lastEvaluatedKey: DynamoItem): this;
+    /**
+     * Creates a deep clone of this builder instance.
+     *
+     * This is particularly useful when:
+     * - Implementing pagination (used internally by paginate())
+     * - Creating operation templates
+     * - Running multiple variations of an operation
+     *
+     * @example
+     * ```typescript
+     * // Create base dinosaur query
+     * const baseBuilder = builder
+     *   .useIndex('status-index')
+     *   .select(['id', 'status', 'location']);
+     *
+     * // Check active dinosaurs
+     * const activeRaptors = baseBuilder.clone()
+     *   .filter(op => op.eq('status', 'HUNTING'))
+     *   .execute();
+     *
+     * // Check contained dinosaurs
+     * const containedRaptors = baseBuilder.clone()
+     *   .filter(op => op.eq('status', 'CONTAINED'))
+     *   .execute();
+     * ```
+     *
+     * @returns A new builder instance with the same configuration
+     */
+    abstract clone(): FilterBuilderInterface<T, TConfig>;
+    /**
+     * Executes the operation against DynamoDB and returns a generator that behaves like an array.
+     * This method must be implemented by subclasses to handle
+     * their specific execution logic.
+     */
+    abstract execute(): Promise<ResultIterator<T, TConfig>>;
+}
+
+/**
+ * Configuration options for DynamoDB query operations.
+ * Extends the base FilterOptions with query-specific options.
+ */
+interface QueryOptions extends FilterOptions {
+    /** Condition for the sort key in the table or index */
+    sortKeyCondition?: Condition;
+    /** Direction of sort key traversal (true for ascending, false for descending) */
+    scanIndexForward?: boolean;
+}
+/**
+ * Function type for executing DynamoDB query operations.
+ * @typeParam T - The type of items being queried
+ */
+type QueryExecutor<T extends DynamoItem> = (keyCondition: Condition, options: QueryOptions) => Promise<{
+    items: T[];
+    lastEvaluatedKey?: Record<string, unknown>;
+}>;
+/**
+ * Builder for creating DynamoDB query operations.
+ *
+ * The builder supports:
+ * - Type-safe GSI selection
+ * - Complex filter conditions
+ * - Automatic pagination handling
+ * - Consistent reads
+ * - Forward and reverse sorting
+ *
+ * @example
+ * ```typescript
+ * // Simple query
+ * const result = await new QueryBuilder(executor, eq('userId', '123'))
+ *   .execute();
+ *
+ * // Complex query with GSI and filtering
+ * const result = await new QueryBuilder(executor, eq('status', 'ACTIVE'))
+ *   .useIndex('status-index')
+ *   .filter(op => op.beginsWith('name', 'John'))
+ *   .select(['id', 'name', 'email'])
+ *   .sortDescending()
+ *   .limit(10)
+ *   .execute();
+ *
+ * // Query with pagination
+ * const paginator = new QueryBuilder(executor, eq('type', 'order'))
+ *   .paginate(25);
+ *
+ * while (paginator.hasNextPage()) {
+ *   const page = await paginator.getNextPage();
+ *   // Process page.items
+ * }
+ * ```
+ *
+ * @typeParam T - The type of items being queried
+ * @typeParam TConfig - The table configuration type for type-safe GSI selection
+ */
+declare class QueryBuilder<T extends DynamoItem, TConfig extends TableConfig = TableConfig> extends FilterBuilder<T, TConfig> implements QueryBuilderInterface<T, TConfig> {
+    private readonly keyCondition;
+    protected options: QueryOptions;
+    protected readonly executor: QueryExecutor<T>;
+    constructor(executor: QueryExecutor<T>, keyCondition: Condition);
+    /**
+     * Sets the maximum number of items to return from the query.
+     *
+     * Note: This is the default behavior if no sort order is specified.
+     *
+     * @example
+     * ```typescript
+     * // Get orders in chronological order
+     * const result = await new QueryBuilder(executor, eq('userId', '123'))
+     *   .sortAscending()
+     *   .execute();
+     *
+     * // Get events from oldest to newest
+     * const result = await new QueryBuilder(executor, eq('entityId', 'order-123'))
+     *   .useIndex('entity-timestamp-index')
+     *   .sortAscending()
+     *   .execute();
+     * ```
+     *
+     * @returns The builder instance for method chaining
+     */
+    /**
+     * Sets the query to return items in ascending order by sort key.
+     *
+     * @example
+     * ```typescript
+     * // List dinosaurs by age
+     * const result = await new QueryBuilder(executor, eq('species', 'Velociraptor'))
+     *   .useIndex('age-index')
+     *   .sortAscending()
+     *   .execute();
+     *
+     * // View incidents chronologically
+     * const result = await new QueryBuilder(executor, eq('type', 'SECURITY_BREACH'))
+     *   .useIndex('date-index')
+     *   .sortAscending()
+     *   .execute();
+     * ```
+     *
+     * @returns The builder instance for method chaining
+     */
+    sortAscending(): this;
+    /**
+     * Sets the query to return items in descending order by sort key.
+     *
+     * @example
+     * ```typescript
+     * // Get most recent security incidents
+     * const result = await new QueryBuilder(executor, eq('type', 'SECURITY_BREACH'))
+     *   .useIndex('date-index')
+     *   .sortDescending()
+     *   .limit(10)
+     *   .execute();
+     *
+     * // Check latest dinosaur activities
+     * const result = await new QueryBuilder(executor, eq('species', 'Velociraptor'))
+     *   .useIndex('activity-time-index')
+     *   .filter(op => op.eq('status', 'ACTIVE'))
+     *   .sortDescending()
+     *   .execute();
+     * ```
+     *
+     * @returns The builder instance for method chaining
+     */
+    sortDescending(): this;
+    /**
+     * Creates a deep clone of this QueryBuilder instance.
+     *
+     * This is particularly useful when:
+     * - Implementing pagination (used internally by paginate())
+     * - Creating query templates
+     * - Running multiple variations of a query
+     *
+     * @example
+     * ```typescript
+     * // Create base dinosaur query
+     * const baseQuery = new QueryBuilder(executor, eq('species', 'Velociraptor'))
+     *   .useIndex('status-index')
+     *   .select(['id', 'status', 'location']);
+     *
+     * // Check active dinosaurs
+     * const activeRaptors = baseQuery.clone()
+     *   .filter(op => op.eq('status', 'HUNTING'))
+     *   .execute();
+     *
+     * // Check contained dinosaurs
+     * const containedRaptors = baseQuery.clone()
+     *   .filter(op => op.eq('status', 'CONTAINED'))
+     *   .execute();
+     *
+     * // Check sedated dinosaurs
+     * const sedatedRaptors = baseQuery.clone()
+     *   .filter(op => op.eq('status', 'SEDATED'))
+     *   .execute();
+     * ```
+     *
+     * @returns A new QueryBuilder instance with the same configuration
+     */
+    clone(): QueryBuilder<T, TConfig>;
+    private deepCloneFilter;
+    /**
+     * Executes the query against DynamoDB and returns a generator that behaves like an array.
+     *
+     * The generator automatically handles pagination and provides array-like methods
+     * for processing results efficiently without loading everything into memory at once.
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   // Find active carnivores with automatic pagination
+     *   const results = await new QueryBuilder(executor, eq('habitatId', 'PADDOCK-A'))
+     *     .useIndex('species-status-index')
+     *     .filter(op =>
+     *       op.and([
+     *         op.eq('diet', 'CARNIVORE'),
+     *         op.eq('status', 'ACTIVE'),
+     *         op.gt('aggressionLevel', 7)
+     *       ])
+     *     )
+     *     .sortDescending()
+     *     .execute();
+     *
+     *   // Use like an array with automatic pagination
+     *   for await (const dinosaur of results) {
+     *     console.log(`Processing ${dinosaur.name}`);
+     *   }
+     *
+     *   // Or convert to array and use array methods
+     *   const allItems = await results.toArray();
+     *   const dangerousOnes = allItems.filter(dino => dino.aggressionLevel > 9);
+     *   const totalCount = allItems.length;
+     * } catch (error) {
+     *   console.error('Security scan failed:', error);
+     * }
+     * ```
+     *
+     * @returns A promise that resolves to a ResultGenerator that behaves like an array
+     */
+    execute(): Promise<ResultIterator<T, TConfig>>;
+}
+
+/**
+ * Configuration options for DynamoDB update operations.
+ */
+interface UpdateOptions {
+    /** Optional condition that must be satisfied for the update to succeed */
+    condition?: Condition;
+    /** Determines which item attributes to include in the response */
+    returnValues?: "ALL_NEW" | "UPDATED_NEW" | "ALL_OLD" | "UPDATED_OLD" | "NONE";
+}
+/**
+ * Function type for executing DynamoDB update operations.
+ * @typeParam T - The type of the item being updated
+ */
+type UpdateExecutor<T extends DynamoItem> = (params: UpdateCommandParams) => Promise<{
+    item?: T;
+}>;
+/**
+ * Represents a single update action within an update operation.
+ * Each action modifies the item in a specific way:
+ * - SET: Modify or add attributes
+ * - REMOVE: Delete attributes
+ * - ADD: Update numbers and sets
+ * - DELETE: Remove elements from a set
+ */
+type UpdateAction = {
+    /** The type of update action */
+    type: "SET" | "REMOVE" | "ADD" | "DELETE";
+    /** The attribute path to update */
+    path: string;
+    /** The value to use in the update (not used for REMOVE actions) */
+    value?: unknown;
+};
+/**
+ * Type utility to get the element type of a set.
+ * Extracts the element type from either a Set or Array type.
+ * @typeParam T - The set or array type
+ */
+type SetElementType<T> = T extends Set<infer U> ? U : T extends Array<infer U> ? U : never;
+/**
+ * Type utility to get the element type from a path that points to a set.
+ * Combines PathType and SetElementType to get the element type at a specific path.
+ * @typeParam T - The type of the item
+ * @typeParam K - The path within the item
+ */
+type PathSetElementType<T, K extends Path<T>> = SetElementType<PathType<T, K>>;
+/**
+ * Builder for creating DynamoDB update operations.
+ *
+ * The builder supports all DynamoDB update operations:
+ * - SET: Modify or add attributes
+ * - REMOVE: Delete attributes
+ * - ADD: Update numbers and sets
+ * - DELETE: Remove elements from a set
+ *
+ * @example
+ * ```typescript
+ * // Simple update
+ * const result = await new UpdateBuilder(executor, 'dinosaurs', { id: 'TREX-001' })
+ *   .set('status', 'HUNTING')
+ *   .set('lastFed', new Date().toISOString())
+ *   .execute();
+ *
+ * // Complex update with multiple operations
+ * const result = await new UpdateBuilder(executor, 'habitats', { id: 'PADDOCK-A' })
+ *   .set({
+ *     status: 'OCCUPIED',
+ *     occupants: 3,
+ *     'metadata.lastInspection': new Date().toISOString()
+ *   })
+ *   .add('securityBreaches', 1)
+ *   .deleteElementsFromSet('suitableDinosaurs', ['VELOCIRAPTOR'])
+ *   .condition(op => op.gt('securityLevel', 8))
+ *   .returnValues('ALL_NEW')
+ *   .execute();
+ * ```
+ *
+ * @typeParam T - The type of item being updated
+ */
+declare class UpdateBuilder<T extends DynamoItem> {
+    protected updates: UpdateAction[];
+    protected options: UpdateOptions;
+    protected readonly executor: UpdateExecutor<T>;
+    protected readonly tableName: string;
+    protected readonly key: PrimaryKeyWithoutExpression;
+    constructor(executor: UpdateExecutor<T>, tableName: string, key: PrimaryKeyWithoutExpression);
+    /**
+     * Sets multiple attributes of an item using an object.
+     *
+     * @example
+     * ```typescript
+     * // Update multiple attributes
+     * builder.set({
+     *   species: 'Tyrannosaurus Rex',
+     *   height: 20,
+     *   diet: 'CARNIVORE',
+     *   'stats.threatLevel': 10
+     * });
+     * ```
+     */
+    set(values: Partial<T>): UpdateBuilder<T>;
+    /**
+     * Sets a single attribute to a specific value.
+     *
+     * @example
+     * ```typescript
+     * // Set simple attributes
+     * builder
+     *   .set('status', 'SLEEPING')
+     *   .set('lastFeeding', new Date().toISOString());
+     *
+     * // Set nested attributes
+     * builder
+     *   .set('location.zone', 'RESTRICTED')
+     *   .set('stats.health', 100);
+     * ```
+     */
+    set<K extends Path<T>>(path: K, value: PathType<T, K>): UpdateBuilder<T>;
+    /**
+     * Removes an attribute from the item.
+     *
+     * @example
+     * ```typescript
+     * // Remove simple attributes
+     * builder
+     *   .remove('temporaryTag')
+     *   .remove('previousLocation');
+     *
+     * // Remove nested attributes
+     * builder
+     *   .remove('metadata.testData')
+     *   .remove('stats.experimentalMetrics');
+     * ```
+     *
+     * @param path - The path to the attribute to remove
+     * @returns The builder instance for method chaining
+     */
+    remove<K extends Path<T>>(path: K): this;
+    /**
+     * Adds a value to a number attribute or adds elements to a set.
+     *
+     * @example
+     * ```typescript
+     * // Increment counters
+     * builder
+     *   .add('escapeAttempts', 1)
+     *   .add('feedingCount', 1);
+     *
+     * // Add to sets
+     * builder
+     *   .add('knownBehaviors', new Set(['PACK_HUNTING', 'AMBUSH_TACTICS']))
+     *   .add('visitedZones', new Set(['ZONE_A', 'ZONE_B']));
+     * ```
+     *
+     * @param path - The path to the attribute to update
+     * @param value - The value to add (number or set)
+     * @returns The builder instance for method chaining
+     */
+    add<K extends Path<T>>(path: K, value: PathType<T, K>): this;
+    /**
+     * Removes elements from a set attribute.
+     *
+     * @example
+     * ```typescript
+     * // Remove from sets using arrays
+     * builder.deleteElementsFromSet(
+     *   'allowedHabitats',
+     *   ['JUNGLE', 'COASTAL']
+     * );
+     *
+     * // Remove from sets using Set DynamoItems
+     * builder.deleteElementsFromSet(
+     *   'knownBehaviors',
+     *   new Set(['NOCTURNAL', 'TERRITORIAL'])
+     * );
+     *
+     * // Remove from nested sets
+     * builder.deleteElementsFromSet(
+     *   'stats.compatibleSpecies',
+     *   ['VELOCIRAPTOR', 'DILOPHOSAURUS']
+     * );
+     * ```
+     *
+     * @param path - The path to the set attribute
+     * @param value - Elements to remove (array or Set)
+     * @returns The builder instance for method chaining
+     */
+    deleteElementsFromSet<K extends Path<T>>(path: K, value: PathSetElementType<T, K>[] | Set<PathSetElementType<T, K>>): this;
+    /**
+     * Adds a condition that must be satisfied for the update to succeed.
+     *
+     * @example
+     * ```typescript
+     * // Simple condition
+     * builder.condition(op =>
+     *   op.eq('status', 'ACTIVE')
+     * );
+     *
+     * // Health check condition
+     * builder.condition(op =>
+     *   op.and([
+     *     op.gt('health', 50),
+     *     op.eq('status', 'HUNTING')
+     *   ])
+     * );
+     *
+     * // Complex security condition
+     * builder.condition(op =>
+     *   op.and([
+     *     op.attributeExists('securitySystem'),
+     *     op.eq('containmentStatus', 'SECURE'),
+     *     op.lt('aggressionLevel', 8)
+     *   ])
+     * );
+     *
+     * // Version check (optimistic locking)
+     * builder.condition(op =>
+     *   op.eq('version', currentVersion)
+     * );
+     * ```
+     *
+     * @param condition - Either a Condition DynamoItem or a callback function that builds the condition
+     * @returns The builder instance for method chaining
+     */
+    condition(condition: Condition | ((op: ConditionOperator<T>) => Condition)): this;
+    /**
+     * Sets which item attributes to include in the response.
+     *
+     * Available options:
+     * - ALL_NEW: All attributes after the update (default)
+     * - UPDATED_NEW: Only updated attributes, new values
+     * - ALL_OLD: All attributes before the update
+     * - UPDATED_OLD: Only updated attributes, old values
+     * - NONE: No attributes returned
+     *
+     * @example
+     * ```typescript
+     * // Get complete updated dinosaur
+     * const result = await builder
+     *   .set('status', 'SLEEPING')
+     *   .returnValues('ALL_NEW')
+     *   .execute();
+     *
+     * // Track specific attribute changes
+     * const result = await builder
+     *   .set({
+     *     'stats.health': 100,
+     *     'stats.energy': 95
+     *   })
+     *   .returnValues('UPDATED_OLD')
+     *   .execute();
+     *
+     * if (result.item) {
+     *   console.log('Previous health:', result.item.stats?.health);
+     * }
+     * ```
+     *
+     * @param returnValues - Which attributes to return in the response
+     * @returns The builder instance for method chaining
+     */
+    returnValues(returnValues: "ALL_NEW" | "UPDATED_NEW" | "ALL_OLD" | "UPDATED_OLD" | "NONE"): this;
+    /**
+     * Generate the DynamoDB command parameters
+     */
+    toDynamoCommand(): UpdateCommandParams;
+    /**
+     * Adds this update operation to a transaction.
+     *
+     * @example
+     * ```typescript
+     * const transaction = new TransactionBuilder(executor);
+     *
+     * // Update dinosaur status and habitat occupancy atomically
+     * new UpdateBuilder(executor, 'dinosaurs', { id: 'TREX-001' })
+     *   .set('location', 'PADDOCK_A')
+     *   .set('status', 'CONTAINED')
+     *   .withTransaction(transaction);
+     *
+     * new UpdateBuilder(executor, 'habitats', { id: 'PADDOCK-A' })
+     *   .add('occupants', 1)
+     *   .set('lastOccupied', new Date().toISOString())
+     *   .withTransaction(transaction);
+     *
+     * // Execute all operations atomically
+     * await transaction.execute();
+     * ```
+     *
+     * @param transaction - The transaction builder to add this operation to
+     * @returns The builder instance for method chaining
+     */
+    withTransaction(transaction: TransactionBuilder): void;
+    /**
+     * Gets a human-readable representation of the update command.
+     *
+     * @example
+     * ```typescript
+     * // Create complex update
+     * const builder = new UpdateBuilder(executor, 'dinosaurs', { id: 'RAPTOR-001' })
+     *   .set({
+     *     status: 'HUNTING',
+     *     'stats.health': 95,
+     *     'behavior.lastObserved': new Date().toISOString()
+     *   })
+     *   .add('huntingSuccesses', 1)
+     *   .condition(op => op.gt('health', 50));
+     *
+     * // Debug the update
+     * const debugInfo = builder.debug();
+     * console.log('Update operation:', debugInfo);
+     * ```
+     *
+     * @returns A readable representation of the update command with resolved expressions
+     */
+    debug(): {
+        raw: UpdateCommandParams;
+        readable: {
+            conditionExpression?: string;
+            updateExpression?: string;
+            filterExpression?: string;
+            keyConditionExpression?: string;
+            projectionExpression?: string;
+        };
+    };
+    /**
+     * Executes the update operation against DynamoDB.
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   // Update dinosaur status with conditions
+     *   const result = await new UpdateBuilder(executor, 'dinosaurs', { id: 'TREX-001' })
+     *     .set({
+     *       status: 'FEEDING',
+     *       lastMeal: new Date().toISOString(),
+     *       'stats.hunger': 0
+     *     })
+     *     .add('feedingCount', 1)
+     *     .condition(op =>
+     *       op.and([
+     *         op.gt('stats.hunger', 80),
+     *         op.eq('status', 'HUNTING')
+     *       ])
+     *     )
+     *     .returnValues('ALL_NEW')
+     *     .execute();
+     *
+     *   if (result.item) {
+     *     console.log('Updated dinosaur:', result.item);
+     *   }
+     * } catch (error) {
+     *   // Handle condition check failure
+     *   console.error('Failed to update dinosaur:', error);
+     *   // Check if dinosaur wasn't hungry enough
+     *   if (error.name === 'ConditionalCheckFailedException') {
+     *     console.log('Dinosaur not ready for feeding');
+     *   }
+     * }
+     * ```
+     *
+     * @returns A promise that resolves to an DynamoItem containing the updated item (if returnValues is set)
+     * @throws {ConditionalCheckFailedException} If the condition check fails
+     * @throws {Error} If the update operation fails for other reasons
+     */
+    execute(): Promise<{
+        item?: T;
+    }>;
+}
+
+/**
+ * Builder for creating DynamoDB condition check operations.
+ * Use this builder when you need to:
+ * - Verify item state without modifying it
+ * - Ensure preconditions in transactions
+ * - Implement optimistic locking patterns
+ * - Validate business rules
+ *
+ * @example
+ * ```typescript
+ * // Check if dinosaur is ready for feeding
+ * const check = new ConditionCheckBuilder('dinosaurs', { id: 'TREX-001' })
+ *   .condition(op =>
+ *     op.and([
+ *       op.eq('status', 'HUNTING'),
+ *       op.gt('stats.hunger', 80),
+ *       op.lt('stats.health', 100)
+ *     ])
+ *   )
+ *   .toDynamoCommand();
+ *
+ * // Check habitat security status
+ * const securityCheck = new ConditionCheckBuilder('habitats', { id: 'PADDOCK-A' })
+ *   .condition(op =>
+ *     op.and([
+ *       op.eq('securityStatus', 'ACTIVE'),
+ *       op.attributeExists('lastInspection'),
+ *       op.lt('threatLevel', 5)
+ *     ])
+ *   )
+ *   .toDynamoCommand();
+ * ```
+ */
+declare class ConditionCheckBuilder {
+    private readonly key;
+    private readonly tableName;
+    private conditionExpression?;
+    constructor(tableName: string, key: PrimaryKeyWithoutExpression);
+    /**
+     * Adds a condition that must be satisfied for the check to succeed.
+     *
+     * @example
+     * ```typescript
+     * // Check dinosaur health and behavior
+     * builder.condition(op =>
+     *   op.and([
+     *     op.gt('stats.health', 50),
+     *     op.not(op.eq('status', 'SEDATED')),
+     *     op.lt('aggressionLevel', 8)
+     *   ])
+     * );
+     *
+     * // Verify habitat conditions
+     * builder.condition(op =>
+     *   op.and([
+     *     op.eq('powerStatus', 'ONLINE'),
+     *     op.between('temperature', 20, 30),
+     *     op.attributeExists('lastMaintenance')
+     *   ])
+     * );
+     *
+     * // Check breeding conditions
+     * builder.condition(op =>
+     *   op.and([
+     *     op.eq('species', 'VELOCIRAPTOR'),
+     *     op.gte('age', 3),
+     *     op.eq('geneticPurity', 100)
+     *   ])
+     * );
+     * ```
+     *
+     * @param condition - Either a Condition DynamoItem or a callback function that builds the condition
+     * @returns The builder instance for method chaining
+     */
+    condition<T extends DynamoItem>(condition: Condition | ((op: ConditionOperator<T>) => Condition)): this;
+    /**
+     * Generates the DynamoDB command parameters for direct execution.
+     * Use this method when you want to:
+     * - Execute the condition check as a standalone operation
+     * - Get the raw DynamoDB command for custom execution
+     * - Inspect the generated command parameters
+     *
+     * @example
+     * ```ts
+     * const command = new ConditionCheckBuilder('myTable', { id: '123' })
+     *   .condition(op => op.attributeExists('status'))
+     *   .toDynamoCommand();
+     * // Use command with DynamoDB client
+     * ```
+     *
+     * @throws {Error} If no condition has been set
+     * @returns The DynamoDB command parameters
+     */
+    private toDynamoCommand;
+    /**
+     * Adds this condition check operation to a transaction.
+     *
+     * @example
+     * ```ts
+     * const transaction = new TransactionBuilder();
+     * new ConditionCheckBuilder('habitats', { id: 'PADDOCK-B' })
+     *   .condition(op => op.and([
+     *     op.eq('securityStatus', 'ACTIVE'),
+     *     op.lt('currentOccupants', 3),
+     *     op.eq('habitatType', 'CARNIVORE')
+     *   ]))
+     *   .withTransaction(transaction);
+     * // Add dinosaur transfer operations
+     * ```
+     *
+     * @param transaction - The transaction builder to add this operation to
+     * @throws {Error} If no condition has been set
+     * @returns The builder instance for method chaining
+     */
+    withTransaction(transaction: TransactionBuilder): this;
+    /**
+     * Gets a human-readable representation of the condition check command
+     * with all expression placeholders replaced by their actual values.
+     *
+     * @example
+     * ```ts
+     * const debugInfo = new ConditionCheckBuilder('dinosaurs', { id: 'TREX-001' })
+     *   .condition(op => op.and([
+     *     op.between('stats.health', 50, 100),
+     *     op.not(op.eq('status', 'SEDATED')),
+     *     op.attributeExists('lastFeedingTime')
+     *     op.eq('version', 1)
+     *   ]))
+     *   .debug();
+     * console.log(debugInfo);
+     * ```
+     *
+     * @returns A readable representation of the condition check command with resolved expressions
+     */
+    debug(): {
+        raw: ConditionCheckCommandParams;
+        readable: {
+            conditionExpression?: string;
+            updateExpression?: string;
+            filterExpression?: string;
+            keyConditionExpression?: string;
+            projectionExpression?: string;
+        };
+    };
+}
+
+/**
+ * Configuration options for DynamoDB scan operations.
+ * Extends the base FilterOptions.
+ */
+type ScanOptions = FilterOptions;
+/**
+ * Function type for executing DynamoDB filter operations.
+ * @typeParam T - The type of items being filtered
+ */
+type ScanExecutor<T extends DynamoItem> = (options: ScanOptions) => Promise<{
+    items: T[];
+    lastEvaluatedKey?: DynamoItem;
+}>;
+/**
+ * Builder for creating DynamoDB scan operations.
+ * Use this builder when you need to:
+ * - Scan all items in a table
+ * - Filter results based on non-key attributes
+ * - Scan items on a Secondary Index (GSI)
+ * - Implement pagination
+ * - Project specific attributes
+ *
+ * The builder supports:
+ * - Type-safe GSI selection
+ * - Complex filter conditions
+ * - Automatic pagination handling
+ * - Consistent reads
+ * - Attribute projection
+ *
+ * @example
+ * ```typescript
+ * // Simple scan with filtering
+ * const result = await new ScanBuilder(executor)
+ *   .filter(op => op.eq('status', 'ACTIVE'))
+ *   .execute();
+ *
+ * // Scan with GSI and filtering
+ * const result = await new ScanBuilder(executor)
+ *   .useIndex('status-index')
+ *   .filter(op => op.gt('securityLevel', 8))
+ *   .select(['id', 'capacity', 'currentOccupants'])
+ *   .limit(10)
+ *   .execute();
+ *
+ * // Scan with pagination
+ * const paginator = new ScanBuilder(executor)
+ *   .filter(op => op.eq('type', 'INCIDENT'))
+ *   .paginate(25);
+ *
+ * while (paginator.hasNextPage()) {
+ *   const page = await paginator.getNextPage();
+ *   // Process page.items
+ * }
+ * ```
+ *
+ * @typeParam T - The type of items being scanned
+ * @typeParam TConfig - The table configuration type for type-safe GSI selection
+ */
+declare class ScanBuilder<T extends DynamoItem, TConfig extends TableConfig = TableConfig> extends FilterBuilder<T, TConfig> implements ScanBuilderInterface<T, TConfig> {
+    protected readonly executor: ScanExecutor<T>;
+    constructor(executor: ScanExecutor<T>);
+    /**
+     * Creates a deep clone of this ScanBuilder instance.
+     *
+     * @returns A new ScanBuilder instance with the same configuration
+     */
+    clone(): ScanBuilder<T, TConfig>;
+    private deepCloneFilter;
+    /**
+     * Executes the scan against DynamoDB and returns a generator that behaves like an array.
+     *
+     * The generator automatically handles pagination and provides array-like methods
+     * for processing results efficiently without loading everything into memory at once.
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   // Find all dinosaurs with high aggression levels with automatic pagination
+     *   const results = await new ScanBuilder(executor)
+     *     .filter(op =>
+     *       op.and([
+     *         op.eq('status', 'ACTIVE'),
+     *         op.gt('aggressionLevel', 7)
+     *       ])
+     *     )
+     *     .execute();
+     *
+     *   // Use like an array with automatic pagination
+     *   for await (const dinosaur of results) {
+     *     console.log(`Processing dangerous dinosaur: ${dinosaur.name}`);
+     *   }
+     *
+     *   // Or convert to array and use array methods
+     *   const allItems = await results.toArray();
+     *   const criticalThreats = allItems.filter(dino => dino.aggressionLevel > 9);
+     *   const totalCount = allItems.length;
+     * } catch (error) {
+     *   console.error('Security scan failed:', error);
+     * }
+     * ```
+     *
+     * @returns A promise that resolves to a ResultGenerator that behaves like an array
+     */
+    execute(): Promise<ResultIterator<T, TConfig>>;
+}
+
+export { BatchBuilder as B, ConditionCheckBuilder as C, DeleteBuilder as D, FilterBuilder as F, GetBuilder as G, PutBuilder as P, QueryBuilder as Q, ResultIterator as R, ScanBuilder as S, TransactionBuilder as T, UpdateBuilder as U, BatchError as a, type BatchResult as b, type DeleteOptions as c, type PutOptions as d, type QueryOptions as e, type TransactionOptions as f, type UpdateOptions as g, type BatchWriteOperation as h, type UpdateCommandParams as i, Paginator as j, type DeleteCommandParams as k, type PutCommandParams as l, type ConditionCheckCommandParams as m, type BaseBuilderInterface as n, type QueryBuilderInterface as o, type ScanBuilderInterface as p, type FilterBuilderInterface as q, type PaginationResult as r, type TransactionItem as s };