dyno-table 0.1.6 → 0.1.8

package/dist/index.d.ts

@@ -108,6 +108,26 @@ interface Condition {
     /** Single condition for the 'not' operator */
     condition?: Condition;
 }
+/**
+ * Parameters used to build DynamoDB expression strings.
+ * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ExpressionAttributeNames.html Expression Attribute Names}
+ * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ExpressionAttributeValues.html Expression Attribute Values}
+ */
+interface ExpressionParams {
+    /** Map of attribute name placeholders to actual attribute names */
+    expressionAttributeNames: Record<string, string>;
+    /** Map of value placeholders to actual values */
+    expressionAttributeValues: Record<string, unknown>;
+    /** Counter for generating unique value placeholders */
+    valueCounter: {
+        count: number;
+    };
+}
+/**
+ * Creates a comparison condition builder function for the specified operator.
+ * @internal
+ */
+declare const createComparisonCondition: (type: ComparisonOperator) => (attr: string, value: unknown) => Condition;
 /**
  * Creates an equals (=) condition
  * @example
@@ -331,6 +351,105 @@ type PrimaryKeyWithoutExpression = {
     sk?: string;
 };
 
+/**
+ * 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;
+}
+
+interface DeleteCommandParams extends DynamoCommandWithExpressions {
+    tableName: string;
+    key: PrimaryKeyWithoutExpression;
+    conditionExpression?: string;
+    expressionAttributeNames?: Record<string, string>;
+    expressionAttributeValues?: Record<string, unknown>;
+    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
+ */
+interface PutCommandParams extends DynamoCommandWithExpressions {
+    tableName: string;
+    item: Record<string, unknown>;
+    conditionExpression?: string;
+    expressionAttributeNames?: Record<string, string>;
+    expressionAttributeValues?: Record<string, unknown>;
+    returnValues?: "ALL_OLD" | "NONE" | "CONSISTENT";
+}
+/**
+ * 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: PrimaryKeyWithoutExpression;
+    /** 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?: Record<string, unknown>;
+    /** 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: PrimaryKeyWithoutExpression;
+    conditionExpression: string;
+    expressionAttributeNames?: Record<string, string>;
+    expressionAttributeValues?: Record<string, unknown>;
+}
+/**
+ * Base interface for all builder classes that support pagination
+ * to be used by Paginator without creating circular dependencies.
+ */
+interface BaseBuilderInterface<T extends Record<string, unknown>, TConfig extends TableConfig = TableConfig, B = unknown> {
+    clone(): B;
+    limit(limit: number): B;
+    getLimit(): number | undefined;
+    startFrom(lastEvaluatedKey: Record<string, unknown>): B;
+    execute(): Promise<{
+        items: T[];
+        lastEvaluatedKey?: Record<string, unknown>;
+    }>;
+}
+/**
+ * Interface for the QueryBuilder class to be used by Paginator
+ * without creating a circular dependency.
+ */
+interface QueryBuilderInterface<T extends Record<string, unknown>, 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 Record<string, unknown>, 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 Record<string, unknown>, 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
@@ -346,6 +465,7 @@ interface PaginationResult<T> {
     /** The current page number (1-indexed) */
     page: number;
 }
+
 /**
  * A utility class for handling DynamoDB pagination.
  * Use this class when you need to:
@@ -388,7 +508,7 @@ declare class Paginator<T extends Record<string, unknown>, TConfig extends Table
     private hasMorePages;
     private totalItemsRetrieved;
     private readonly overallLimit?;
-    constructor(queryBuilder: QueryBuilder<T, TConfig>, pageSize: number);
+    constructor(queryBuilder: QueryBuilderInterface<T, TConfig>, pageSize: number);
     /**
      * Gets the current page number (1-indexed).
      * Use this method when you need to:
@@ -521,140 +641,54 @@ declare class Paginator<T extends Record<string, unknown>, TConfig extends Table
 }
 
 /**
- * Configuration options for DynamoDB query operations.
+ * Configuration options for DynamoDB filter operations.
+ * These are common options shared between query and scan operations.
  */
-interface QueryOptions {
-    /** Condition for the sort key in the table or index */
-    sortKeyCondition?: Condition;
-    /** Additional filter conditions applied after the key condition */
+interface FilterOptions {
+    /** Filter conditions applied to results */
     filter?: Condition;
     /** Maximum number of items to return */
     limit?: number;
-    /** Name of the Global Secondary Index to query */
+    /** Name of the Global Secondary Index to use */
     indexName?: string;
     /** Whether to use strongly consistent reads */
     consistentRead?: boolean;
-    /** Direction of sort key traversal (true for ascending, false for descending) */
-    scanIndexForward?: boolean;
     /** List of attributes to return in the result */
     projection?: string[];
-    /** Number of items to fetch per page when using pagination */
-    paginationSize?: number;
-    /** Token for starting the query from a specific point */
+    /** Token for starting the operation from a specific point */
     lastEvaluatedKey?: Record<string, unknown>;
 }
 /**
- * Function type for executing DynamoDB query operations.
- * @typeParam T - The type of items being queried
- */
-type QueryExecutor<T extends Record<string, unknown>> = (keyCondition: Condition, options: QueryOptions) => Promise<{
-    items: T[];
-    lastEvaluatedKey?: Record<string, unknown>;
-}>;
-/**
- * Builder for creating DynamoDB query operations.
- * Use this builder when you need to:
- * - Query items using partition key (and optionally sort key)
- * - Filter results based on non-key attributes
- * - Use Global Secondary Indexes (GSIs)
- * - Implement pagination
- * - Control result ordering
- * - Project specific attributes
+ * 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
- * - Automatic pagination handling
+ * - Pagination
  * - Consistent reads
- * - Forward and reverse sorting
- *
- * @example
- * ```ts
- * // 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
- */
-/**
- * Builder for creating DynamoDB query operations.
- * Use this builder when you need to:
- * - Find dinosaurs by species or status
- * - Search habitats by type or region
- * - List incidents by date range
- * - Retrieve feeding schedules
- *
- * The builder supports:
- * - Complex filtering conditions
- * - Sorting and pagination
- * - Global Secondary Indexes
  * - Attribute projection
  *
- * @example
- * ```typescript
- * // Find active carnivores
- * const result = await new QueryBuilder(executor, eq('species', 'Tyrannosaurus'))
- *   .filter(op => op.eq('status', 'ACTIVE'))
- *   .execute();
- *
- * // Search habitats by security level
- * const result = await new QueryBuilder(executor, eq('type', 'CARNIVORE'))
- *   .useIndex('security-level-index')
- *   .filter(op => op.gt('securityLevel', 8))
- *   .select(['id', 'capacity', 'currentOccupants'])
- *   .sortDescending()
- *   .execute();
- *
- * // List recent incidents
- * const result = await new QueryBuilder(executor, eq('type', 'INCIDENT'))
- *   .useIndex('date-index')
- *   .filter(op => op.gt('severityLevel', 5))
- *   .paginate(10);
- * ```
- *
- * @typeParam T - The type of items being queried
+ * @typeParam T - The type of items being filtered
  * @typeParam TConfig - The table configuration type for type-safe GSI selection
  */
-declare class QueryBuilder<T extends Record<string, unknown>, TConfig extends TableConfig = TableConfig> {
-    private readonly keyCondition;
-    private options;
-    private selectedFields;
-    private readonly executor;
-    constructor(executor: QueryExecutor<T>, keyCondition: Condition);
+declare abstract class FilterBuilder<T extends Record<string, unknown>, TConfig extends TableConfig = TableConfig> implements FilterBuilderInterface<T, TConfig> {
+    protected options: FilterOptions;
+    protected selectedFields: Set<string>;
     /**
-     * Sets the maximum number of items to return from the query.
+     * Sets the maximum number of items to return.
      * Use this method when you need to:
-     * - Limit the result set size
-     * - Implement manual pagination
-     * - Control data transfer size
+     * - Limit the number of dinosaurs returned
+     * - Control the size of habitat reports
+     * - Implement manual pagination of security logs
      *
      * Note: This limit applies to the items that match the key condition
      * before any filter expressions are applied.
      *
      * @example
-     * ```ts
-     * // Get first 10 orders for a user
-     * const result = await new QueryBuilder(executor, eq('userId', '123'))
+     * ```typescript
+     * // Get first 10 dinosaurs
+     * const result = await builder
      *   .limit(10)
      *   .execute();
      * ```
@@ -662,50 +696,18 @@ declare class QueryBuilder<T extends Record<string, unknown>, TConfig extends Ta
      * @param limit - Maximum number of items to return
      * @returns The builder instance for method chaining
      */
-    limit(limit: number): QueryBuilder<T>;
+    limit(limit: number): this;
     /**
-     * Gets the current limit set on the query.
+     * 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 query.
-     * Use this method when you need to:
-     * - Query data using non-primary key attributes
-     * - Access data through alternate access patterns
-     * - Optimize query performance for specific access patterns
-     *
-     * This method provides type safety by only allowing valid GSI names
-     * defined in your table configuration.
-     *
-     * @example
-     * ```ts
-     * // Query by status using a GSI
-     * const result = await new QueryBuilder(executor, eq('status', 'ACTIVE'))
-     *   .useIndex('status-index')
-     *   .execute();
-     *
-     * // Query by category and date range
-     * const result = await new QueryBuilder(executor, eq('category', 'books'))
-     *   .useIndex('category-date-index')
-     *   .filter(op => op.between('date', startDate, endDate))
-     *   .execute();
-     * ```
-     *
-     * Note: Be aware that GSIs:
-     * - May have different projected attributes
-     * - Have eventually consistent reads only
-     * - May have different provisioned throughput
-     *
-     * @param indexName - The name of the GSI to use (type-safe based on table configuration)
-     * @returns The builder instance for method chaining
-     */
-    /**
-     * Specifies a Global Secondary Index (GSI) to use for the query.
+     * Specifies a Global Secondary Index (GSI) to use for the operation.
      * Use this method when you need to:
-     * - Query dinosaurs by species or status
+     * - Find dinosaurs by species or status
      * - Search habitats by security level
      * - Find incidents by date
      * - List feeding schedules by time
@@ -731,9 +733,9 @@ declare class QueryBuilder<T extends Record<string, unknown>, TConfig extends Ta
      * @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): QueryBuilder<T, TConfig>;
+    useIndex<I extends GSINames<TConfig>>(indexName: I): this;
     /**
-     * Sets whether to use strongly consistent reads for the query.
+     * Sets whether to use strongly consistent reads for the operation.
      * Use this method when you need to:
      * - Get real-time dinosaur status updates
      * - Monitor critical security systems
@@ -746,15 +748,15 @@ declare class QueryBuilder<T extends Record<string, unknown>, TConfig extends Ta
      * - Default is eventually consistent reads
      *
      * @example
-     * ```ts
+     * ```typescript
      * // Check immediate dinosaur status
-     * const result = await new QueryBuilder(executor, eq('species', 'Velociraptor'))
+     * const result = await builder
      *   .filter(op => op.eq('status', 'ACTIVE'))
      *   .consistentRead()
      *   .execute();
      *
      * // Monitor security breaches
-     * const result = await new QueryBuilder(executor, eq('type', 'SECURITY_ALERT'))
+     * const result = await builder
      *   .useIndex('primary-index')
      *   .consistentRead(isEmergencyMode)
      *   .execute();
@@ -763,37 +765,9 @@ declare class QueryBuilder<T extends Record<string, unknown>, TConfig extends Ta
      * @param consistentRead - Whether to use consistent reads (defaults to true)
      * @returns The builder instance for method chaining
      */
-    consistentRead(consistentRead?: boolean): QueryBuilder<T>;
-    /**
-     * Adds a filter expression to the query.
-     * Use this method when you need to:
-     * - Filter results based on non-key attributes
-     * - Apply complex filtering conditions
-     * - Combine multiple filter conditions
-     *
-     * Note: Filter expressions are applied after the key condition,
-     * so they don't reduce the amount of data read from DynamoDB.
-     *
-     * @example
-     * ```ts
-     * // Simple filter
-     * builder.filter(op => op.eq('status', 'ACTIVE'))
-     *
-     * // Complex filter with multiple conditions
-     * builder.filter(op =>
-     *   op.and([
-     *     op.gt('amount', 1000),
-     *     op.beginsWith('category', 'ELECTRONICS'),
-     *     op.attributeExists('reviewDate')
-     *   ])
-     * )
-     * ```
-     *
-     * @param condition - Either a Condition object or a callback function that builds the condition
-     * @returns The builder instance for method chaining
-     */
+    consistentRead(consistentRead?: boolean): this;
     /**
-     * Adds a filter expression to refine the query results.
+     * Adds a filter expression to refine the operation results.
      * Use this method when you need to:
      * - Filter dinosaurs by behavior patterns
      * - Find habitats with specific conditions
@@ -824,36 +798,9 @@ declare class QueryBuilder<T extends Record<string, unknown>, TConfig extends Ta
      * @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)): QueryBuilder<T>;
-    /**
-     * Specifies which attributes to return in the query results.
-     * Use this method when you need to:
-     * - Reduce data transfer by selecting specific attributes
-     * - Optimize response size
-     * - Focus on relevant attributes only
-     *
-     * Note: Using projection can significantly reduce the amount
-     * of data returned and lower your costs.
-     *
-     * @example
-     * ```ts
-     * // Select single attribute
-     * builder.select('email')
-     *
-     * // Select multiple attributes
-     * builder.select(['id', 'name', 'email'])
-     *
-     * // Chain multiple select calls
-     * builder
-     *   .select('id')
-     *   .select(['name', 'email'])
-     * ```
-     *
-     * @param fields - A single field name or an array of field names to return
-     * @returns The builder instance for method chaining
-     */
+    filter(condition: Condition | ((op: ConditionOperator<T>) => Condition)): this;
     /**
-     * Specifies which attributes to return in the query results.
+     * Specifies which attributes to return in the results.
      * Use this method when you need to:
      * - Get specific dinosaur attributes
      * - Retrieve habitat statistics
@@ -883,167 +830,242 @@ declare class QueryBuilder<T extends Record<string, unknown>, TConfig extends Ta
      * @param fields - A single field name or an array of field names to return
      * @returns The builder instance for method chaining
      */
-    select(fields: string | string[]): QueryBuilder<T>;
+    select(fields: string | string[]): this;
     /**
-     * Sets the query to return items in ascending order by sort key.
-     * Use this method when you need to:
-     * - Retrieve items in natural order (e.g., timestamps, versions)
-     * - Implement chronological ordering
-     * - Get oldest items first
-     *
-     * Note: This is the default behavior if no sort order is specified.
+     * 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
-     * // Get orders in chronological order
-     * const result = await new QueryBuilder(executor, eq('userId', '123'))
-     *   .sortAscending()
-     *   .execute();
+     * // Create a paginator for dinosaur records
+     * const paginator = builder
+     *   .filter(op => op.eq('status', 'ACTIVE'))
+     *   .paginate(10);
      *
-     * // Get events from oldest to newest
-     * const result = await new QueryBuilder(executor, eq('entityId', 'order-123'))
-     *   .useIndex('entity-timestamp-index')
-     *   .sortAscending()
-     *   .execute();
+     * // 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
+     * }
      * ```
      *
-     * @returns The builder instance for method chaining
+     * @param pageSize - The number of items to return per page
+     * @returns A Paginator instance that manages the pagination state
+     * @see Paginator for more pagination control options
      */
+    paginate(pageSize: number): Paginator<T, TConfig>;
     /**
-     * Sets the query to return items in ascending order by sort key.
+     * Sets the starting point using a previous lastEvaluatedKey.
      * Use this method when you need to:
-     * - List dinosaurs by age (youngest first)
-     * - View incidents chronologically
-     * - Track feeding schedule progression
-     * - Monitor habitat inspections
+     * - Implement manual dinosaur list pagination
+     * - Resume habitat inspection reviews
+     * - Continue security incident analysis
+     * - Store operation position between sessions
+     *
+     * Note: This method is typically used for manual pagination.
+     * For automatic pagination, use the paginate() method instead.
      *
      * @example
      * ```typescript
-     * // List dinosaurs by age
-     * const result = await new QueryBuilder(executor, eq('species', 'Velociraptor'))
-     *   .useIndex('age-index')
-     *   .sortAscending()
+     * // First batch of dinosaurs
+     * const result1 = await builder
+     *   .filter(op => op.eq('status', 'ACTIVE'))
+     *   .limit(5)
      *   .execute();
      *
-     * // View incidents chronologically
-     * const result = await new QueryBuilder(executor, eq('type', 'SECURITY_BREACH'))
-     *   .useIndex('date-index')
-     *   .sortAscending()
-     *   .execute();
+     * if (result1.lastEvaluatedKey) {
+     *   // Continue listing dinosaurs
+     *   const result2 = await builder
+     *     .filter(op => op.eq('status', 'ACTIVE'))
+     *     .startFrom(result1.lastEvaluatedKey)
+     *     .limit(5)
+     *     .execute();
+     *
+     *   console.log('Additional dinosaurs:', result2.items);
+     * }
      * ```
      *
+     * @param lastEvaluatedKey - The exclusive start key from a previous result
      * @returns The builder instance for method chaining
      */
-    sortAscending(): QueryBuilder<T>;
+    startFrom(lastEvaluatedKey: Record<string, unknown>): this;
     /**
-     * Sets the query to return items in descending order by sort key.
+     * Creates a deep clone of this builder instance.
      * Use this method when you need to:
-     * - Get most recent security breaches
-     * - Find oldest dinosaurs first
-     * - Check latest habitat modifications
-     * - Monitor recent feeding events
+     * - Query different dinosaur statuses
+     * - Check multiple habitat conditions
+     * - Monitor various security levels
+     * - Create report templates
+     *
+     * This is particularly useful when:
+     * - Implementing pagination (used internally by paginate())
+     * - Creating operation templates
+     * - Running multiple variations of an operation
      *
      * @example
      * ```typescript
-     * // Get most recent security incidents
-     * const result = await new QueryBuilder(executor, eq('type', 'SECURITY_BREACH'))
-     *   .useIndex('date-index')
-     *   .sortDescending()
-     *   .limit(10)
+     * // 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 latest dinosaur activities
-     * const result = await new QueryBuilder(executor, eq('species', 'Velociraptor'))
-     *   .useIndex('activity-time-index')
-     *   .filter(op => op.eq('status', 'ACTIVE'))
-     *   .sortDescending()
+     * // Check contained dinosaurs
+     * const containedRaptors = baseBuilder.clone()
+     *   .filter(op => op.eq('status', 'CONTAINED'))
      *   .execute();
      * ```
      *
-     * @returns The builder instance for method chaining
+     * @returns A new builder instance with the same configuration
      */
-    sortDescending(): QueryBuilder<T>;
+    abstract clone(): FilterBuilderInterface<T, TConfig>;
     /**
-     * Creates a paginator that handles DynamoDB pagination automatically.
-     * Use this method when you need to:
-     * - Browse large dinosaur collections
-     * - View habitat inspection history
-     * - Monitor security incidents
-     * - Track feeding patterns
+     * Executes the operation against DynamoDB.
+     * This method must be implemented by subclasses to handle
+     * their specific execution logic.
+     */
+    abstract execute(): Promise<{
+        items: T[];
+        lastEvaluatedKey?: Record<string, unknown>;
+    }>;
+}
+
+/**
+ * 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 Record<string, unknown>> = (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 Record<string, unknown>, 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.
      *
-     * The paginator handles:
-     * - Tracking the last evaluated key
-     * - Managing page boundaries
-     * - Respecting overall query limits
+     * Note: This is the default behavior if no sort order is specified.
      *
      * @example
      * ```typescript
-     * // List dinosaurs by species
-     * const paginator = new QueryBuilder(executor, eq('species', 'Velociraptor'))
-     *   .filter(op => op.eq('status', 'ACTIVE'))
-     *   .useIndex('species-index')
-     *   .paginate(10);
-     *
-     * // Process pages of security incidents
-     * const paginator = new QueryBuilder(executor, eq('type', 'SECURITY_BREACH'))
-     *   .filter(op => op.gt('severityLevel', 7))
-     *   .sortDescending()
-     *   .paginate(25);
+     * // Get orders in chronological order
+     * const result = await new QueryBuilder(executor, eq('userId', '123'))
+     *   .sortAscending()
+     *   .execute();
      *
-     * while (paginator.hasNextPage()) {
-     *   const page = await paginator.getNextPage();
-     *   console.log(`Processing incidents page ${page.page}, count: ${page.items.length}`);
-     *   // Handle security incidents
-     * }
+     * // Get events from oldest to newest
+     * const result = await new QueryBuilder(executor, eq('entityId', 'order-123'))
+     *   .useIndex('entity-timestamp-index')
+     *   .sortAscending()
+     *   .execute();
      * ```
      *
-     * @param pageSize - The number of items to return per page
-     * @returns A Paginator instance that manages the pagination state
-     * @see Paginator for more pagination control options
+     * @returns The builder instance for method chaining
      */
-    paginate(pageSize: number): Paginator<T, TConfig>;
     /**
-     * Sets the starting point for the query using a previous lastEvaluatedKey.
-     * Use this method when you need to:
-     * - Implement manual dinosaur list pagination
-     * - Resume habitat inspection reviews
-     * - Continue security incident analysis
-     * - Store query position between sessions
-     *
-     * Note: This method is typically used for manual pagination.
-     * For automatic pagination, use the paginate() method instead.
+     * Sets the query to return items in ascending order by sort key.
      *
      * @example
      * ```typescript
-     * // First batch of dinosaurs
-     * const result1 = await new QueryBuilder(executor, eq('species', 'Velociraptor'))
-     *   .filter(op => op.eq('status', 'ACTIVE'))
-     *   .limit(5)
+     * // List dinosaurs by age
+     * const result = await new QueryBuilder(executor, eq('species', 'Velociraptor'))
+     *   .useIndex('age-index')
+     *   .sortAscending()
      *   .execute();
      *
-     * if (result1.lastEvaluatedKey) {
-     *   // Continue listing dinosaurs
-     *   const result2 = await new QueryBuilder(executor, eq('species', 'Velociraptor'))
-     *     .filter(op => op.eq('status', 'ACTIVE'))
-     *     .startFrom(result1.lastEvaluatedKey)
-     *     .limit(5)
-     *     .execute();
+     * // View incidents chronologically
+     * const result = await new QueryBuilder(executor, eq('type', 'SECURITY_BREACH'))
+     *   .useIndex('date-index')
+     *   .sortAscending()
+     *   .execute();
+     * ```
      *
-     *   console.log('Additional dinosaurs:', result2.items);
-     * }
+     * @returns The builder instance for method chaining
+     */
+    sortAscending(): QueryBuilder<T>;
+    /**
+     * 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();
      * ```
      *
-     * @param lastEvaluatedKey - The exclusive start key from a previous query result
      * @returns The builder instance for method chaining
      */
-    startFrom(lastEvaluatedKey: Record<string, unknown>): QueryBuilder<T>;
+    sortDescending(): QueryBuilder<T>;
     /**
      * Creates a deep clone of this QueryBuilder instance.
-     * Use this method when you need to:
-     * - Query different dinosaur statuses
-     * - Check multiple habitat conditions
-     * - Monitor various security levels
-     * - Create report templates
      *
      * This is particularly useful when:
      * - Implementing pagination (used internally by paginate())
@@ -1078,11 +1100,6 @@ declare class QueryBuilder<T extends Record<string, unknown>, TConfig extends Ta
     clone(): QueryBuilder<T, TConfig>;
     /**
      * Executes the query against DynamoDB.
-     * Use this method when you need to:
-     * - Find specific dinosaur groups
-     * - Check habitat conditions
-     * - Monitor security incidents
-     * - Track feeding patterns
      *
      * The method returns both the matched items and, if there are more results,
      * a lastEvaluatedKey that can be used with startFrom() to continue the query.
@@ -1125,489 +1142,609 @@ declare class QueryBuilder<T extends Record<string, unknown>, TConfig extends Ta
 }
 
 /**
- * Interface for DynamoDB command objects that can contain expressions
+ * Configuration options for DynamoDB transactions.
  */
-interface DynamoCommandWithExpressions {
-    conditionExpression?: string;
-    updateExpression?: string;
-    filterExpression?: string;
-    keyConditionExpression?: string;
-    projectionExpression?: string;
-    expressionAttributeNames?: Record<string, string>;
-    expressionAttributeValues?: Record<string, unknown>;
-    [key: string]: unknown;
+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";
 }
-
 /**
- * Parameters for the DynamoDB update command.
- * These parameters are used when executing the operation against DynamoDB.
+ * Configuration for table indexes used in duplicate detection.
+ * Defines the key structure for checking uniqueness constraints.
  */
-interface UpdateCommandParams extends DynamoCommandWithExpressions {
-    /** The name of the DynamoDB table */
-    tableName: string;
-    /** The primary key of the item to update */
-    key: PrimaryKeyWithoutExpression;
-    /** 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?: Record<string, unknown>;
-    /** Which item attributes to include in the response */
-    returnValues?: "ALL_NEW" | "UPDATED_NEW" | "ALL_OLD" | "UPDATED_OLD" | "NONE";
+interface IndexConfig {
+    /** The partition key attribute name */
+    partitionKey: string;
+    /** Optional sort key attribute name */
+    sortKey?: string;
 }
 /**
- * Function type for executing DynamoDB update operations.
- * @typeParam T - The type of the item being updated
+ * Function type for executing DynamoDB transaction operations.
+ * @param params - The complete transaction command input
+ * @returns A promise that resolves when the transaction completes
  */
-type UpdateExecutor<T extends Record<string, unknown>> = (params: UpdateCommandParams) => Promise<{
-    item?: T;
-}>;
+type TransactionExecutor = (params: TransactWriteCommandInput) => Promise<void>;
 /**
- * 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.
+ * Builder for creating and executing DynamoDB transactions.
  * Use this builder when you need to:
- * - Modify existing items in DynamoDB
- * - Update multiple attributes atomically
- * - Perform conditional updates
- * - Work with nested attributes
- * - Update sets and lists
+ * - 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 all DynamoDB update operations:
- * - SET: Modify or add attributes
- * - REMOVE: Delete attributes
- * - ADD: Update numbers and sets
- * - DELETE: Remove elements from a set
+ * The builder supports:
+ * - Put operations (insert/replace items)
+ * - Delete operations
+ * - Update operations
+ * - Condition checks
+ * - Duplicate detection
+ * - Transaction-wide options
  *
  * @example
  * ```typescript
- * // Simple update
- * const result = await new UpdateBuilder(executor, 'dinosaurs', { id: 'TREX-001' })
- *   .set('status', 'HUNTING')
- *   .set('lastFed', new Date().toISOString())
- *   .execute();
+ * // Create a transaction with multiple operations
+ * const transaction = new TransactionBuilder(executor, {
+ *   partitionKey: 'id',
+ *   sortKey: 'type'
+ * });
  *
- * // 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();
+ * // 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();
  * ```
  *
- * @typeParam T - The type of item being updated
+ * 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 UpdateBuilder<T extends Record<string, unknown>> {
-    private updates;
+declare class TransactionBuilder {
+    private items;
     private options;
+    private indexConfig;
     private readonly executor;
-    private readonly tableName;
-    private readonly key;
-    constructor(executor: UpdateExecutor<T>, tableName: string, key: PrimaryKeyWithoutExpression);
+    constructor(executor: TransactionExecutor, indexConfig: IndexConfig);
     /**
-     * Sets multiple attributes of an item using an object.
+     * Checks if an item with the same primary key already exists in the transaction
+     * @private
+     */
+    private checkForDuplicateItem;
+    /**
+     * Adds a put operation to the transaction.
      * Use this method when you need to:
-     * - Update multiple attributes at once
-     * - Set nested attribute values
-     * - Modify complex data structures
+     * - Insert new items as part of a transaction
+     * - Replace existing items atomically
+     * - Ensure items meet certain conditions before insertion
+     *
+     * The method automatically checks for duplicate items within the transaction
+     * to prevent multiple operations on the same item.
      *
      * @example
      * ```typescript
-     * // Update multiple attributes
-     * builder.set({
-     *   species: 'Tyrannosaurus Rex',
-     *   height: 20,
-     *   diet: 'CARNIVORE',
-     *   'stats.threatLevel': 10
+     * // 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
      */
-    set(values: Partial<T>): UpdateBuilder<T>;
+    put<T extends Record<string, unknown>>(tableName: string, item: T, condition?: Condition): TransactionBuilder;
     /**
-     * Sets a single attribute to a specific value.
+     * Adds a pre-configured put operation to the transaction.
      * Use this method when you need to:
-     * - Update one attribute at a time
-     * - Set values with type safety
-     * - Update nested attributes
+     * - Reuse put commands from PutBuilder
+     * - Add complex put operations with pre-configured parameters
+     * - Integrate with existing put command configurations
+     *
+     * This method is particularly useful when working with PutBuilder
+     * to maintain consistency in put operations across your application.
      *
      * @example
      * ```typescript
-     * // Set simple attributes
-     * builder
-     *   .set('status', 'SLEEPING')
-     *   .set('lastFeeding', new Date().toISOString());
+     * // Create a put command with PutBuilder
+     * const putCommand = new PutBuilder(executor, newItem, 'users')
+     *   .condition(op => op.attributeNotExists('userId'))
+     *   .toDynamoCommand();
      *
-     * // Set nested attributes
-     * builder
-     *   .set('location.zone', 'RESTRICTED')
-     *   .set('stats.health', 100);
+     * // 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
      */
-    set<K extends Path<T>>(path: K, value: PathType<T, K>): UpdateBuilder<T>;
+    putWithCommand(command: PutCommandParams): TransactionBuilder;
     /**
-     * Removes an attribute from the item.
+     * Adds a delete operation to the transaction.
      * Use this method when you need to:
-     * - Delete attributes completely
-     * - Remove nested attributes
-     * - Clean up deprecated fields
+     * - Remove items as part of a transaction
+     * - Conditionally delete items
+     * - Ensure items exist before deletion
+     *
+     * The method automatically checks for duplicate items within the transaction
+     * to prevent multiple operations on the same item.
      *
      * @example
      * ```typescript
-     * // Remove simple attributes
-     * builder
-     *   .remove('temporaryTag')
-     *   .remove('previousLocation');
+     * // Simple delete operation
+     * transaction.delete('orders', {
+     *   pk: 'ORDER#123',
+     *   sk: 'METADATA'
+     * });
      *
-     * // Remove nested attributes
-     * builder
-     *   .remove('metadata.testData')
-     *   .remove('stats.experimentalMetrics');
+     * // 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 path - The path to the attribute to remove
-     * @returns The builder instance for method chaining
+     * @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
      */
-    remove<K extends Path<T>>(path: K): UpdateBuilder<T>;
+    delete(tableName: string, key: PrimaryKeyWithoutExpression, condition?: Condition): TransactionBuilder;
     /**
-     * Adds a value to a number attribute or adds elements to a set.
+     * Adds a pre-configured delete operation to the transaction.
      * Use this method when you need to:
-     * - Increment counters
-     * - Add elements to a set atomically
-     * - Update numerical statistics
+     * - Reuse delete commands from DeleteBuilder
+     * - Add complex delete operations with pre-configured parameters
+     * - Integrate with existing delete command configurations
+     *
+     * This method is particularly useful when working with DeleteBuilder
+     * to maintain consistency in delete operations across your application.
      *
      * @example
      * ```typescript
-     * // Increment counters
-     * builder
-     *   .add('escapeAttempts', 1)
-     *   .add('feedingCount', 1);
+     * // 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 to sets
-     * builder
-     *   .add('knownBehaviors', new Set(['PACK_HUNTING', 'AMBUSH_TACTICS']))
-     *   .add('visitedZones', new Set(['ZONE_A', 'ZONE_B']));
+     * // Add the command to the transaction
+     * transaction.deleteWithCommand(deleteCommand);
      * ```
      *
-     * @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
+     * @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
      */
-    add<K extends Path<T>>(path: K, value: PathType<T, K>): UpdateBuilder<T>;
+    deleteWithCommand(command: DeleteCommandParams): TransactionBuilder;
     /**
-     * Removes elements from a set attribute.
+     * Adds an update operation to the transaction.
      * Use this method when you need to:
-     * - Remove specific elements from a set
-     * - Update set-based attributes atomically
-     * - Maintain set membership
+     * - Modify existing items as part of a transaction
+     * - Update multiple attributes atomically
+     * - Apply conditional updates
+     * - Perform complex attribute manipulations
+     *
+     * 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
-     * // Remove from sets using arrays
-     * builder.deleteElementsFromSet(
-     *   'allowedHabitats',
-     *   ['JUNGLE', 'COASTAL']
+     * // Simple update
+     * transaction.update(
+     *   'orders',
+     *   { pk: 'ORDER#123' },
+     *   'SET #status = :status',
+     *   { '#status': 'status' },
+     *   { ':status': 'PROCESSING' }
      * );
      *
-     * // Remove from sets using Set objects
-     * builder.deleteElementsFromSet(
-     *   'knownBehaviors',
-     *   new Set(['NOCTURNAL', 'TERRITORIAL'])
+     * // 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' }
      * );
      *
-     * // Remove from nested sets
-     * builder.deleteElementsFromSet(
-     *   'stats.compatibleSpecies',
-     *   ['VELOCIRAPTOR', 'DILOPHOSAURUS']
+     * // Conditional update
+     * transaction.update(
+     *   'users',
+     *   { pk: 'USER#123' },
+     *   'SET #lastLogin = :now',
+     *   { '#lastLogin': 'lastLoginDate' },
+     *   { ':now': new Date().toISOString() },
+     *   op => op.attributeExists('pk')
      * );
      * ```
      *
-     * @param path - The path to the set attribute
-     * @param value - Elements to remove (array or Set)
-     * @returns The builder instance for method chaining
+     * @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
      */
-    deleteElementsFromSet<K extends Path<T>>(path: K, value: PathSetElementType<T, K>[] | Set<PathSetElementType<T, K>>): UpdateBuilder<T>;
+    update<T extends Record<string, unknown>>(tableName: string, key: PrimaryKeyWithoutExpression, updateExpression: string, expressionAttributeNames?: Record<string, string>, expressionAttributeValues?: Record<string, unknown>, condition?: Condition): TransactionBuilder;
     /**
-     * Adds a condition that must be satisfied for the update to succeed.
+     * Adds a pre-configured update operation to the transaction.
      * Use this method when you need to:
-     * - Implement optimistic locking
-     * - Ensure item state before update
-     * - Validate business rules
-     * - Prevent concurrent modifications
+     * - Reuse update commands from UpdateBuilder
+     * - Add complex update operations with pre-configured parameters
+     * - Integrate with existing update command configurations
+     *
+     * This method is particularly useful when working with UpdateBuilder
+     * to maintain consistency in update operations across your application.
      *
      * @example
      * ```typescript
-     * // Simple condition
-     * builder.condition(op =>
-     *   op.eq('status', 'ACTIVE')
-     * );
+     * // 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();
      *
-     * // Health check condition
-     * builder.condition(op =>
-     *   op.and([
-     *     op.gt('health', 50),
-     *     op.eq('status', 'HUNTING')
-     *   ])
+     * // 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.
+     * Use this method when you need to:
+     * - Validate item state without modifying it
+     * - Ensure data consistency across tables
+     * - Implement complex business rules
+     * - Verify preconditions for other operations
+     *
+     * 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 security condition
-     * builder.condition(op =>
-     *   op.and([
-     *     op.attributeExists('securitySystem'),
-     *     op.eq('containmentStatus', 'SECURE'),
-     *     op.lt('aggressionLevel', 8)
+     * // Complex condition check
+     * transaction.conditionCheck(
+     *   'inventory',
+     *   { pk: 'PROD#ABC' },
+     *   op => op.and([
+     *     op.gt('quantity', 0),
+     *     op.eq('status', 'ACTIVE'),
+     *     op.attributeExists('lastRestockDate')
      *   ])
      * );
      *
-     * // Version check (optimistic locking)
-     * builder.condition(op =>
-     *   op.eq('version', currentVersion)
+     * // Check with multiple attributes
+     * transaction.conditionCheck(
+     *   'users',
+     *   { pk: 'USER#123' },
+     *   op => op.or([
+     *     op.eq('status', 'PREMIUM'),
+     *     op.gte('credits', 100)
+     *   ])
      * );
      * ```
      *
-     * @param condition - Either a Condition object or a callback function that builds the condition
-     * @returns The builder instance for method chaining
+     * @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
      */
-    condition(condition: Condition | ((op: ConditionOperator<T>) => Condition)): UpdateBuilder<T>;
+    conditionCheck(tableName: string, key: PrimaryKeyWithoutExpression, condition: Condition): TransactionBuilder;
     /**
-     * Sets which item attributes to include in the response.
+     * Adds a pre-configured condition check operation to the transaction.
      * Use this method when you need to:
-     * - Get the complete updated item
-     * - Track changes to specific attributes
-     * - Compare old and new values
-     * - Monitor attribute modifications
+     * - Reuse condition checks from ConditionCheckBuilder
+     * - Add complex condition checks with pre-configured parameters
+     * - Integrate with existing condition check configurations
      *
-     * Available options:
-     * - ALL_NEW: All attributes after the update
-     * - 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 (default)
+     * This method is particularly useful when working with ConditionCheckBuilder
+     * to maintain consistency in condition checks across your application.
      *
      * @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();
+     * // 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();
      *
-     * if (result.item) {
-     *   console.log('Previous health:', result.item.stats?.health);
-     * }
+     * // Add the command to the transaction
+     * transaction.conditionCheckWithCommand(checkCommand);
      * ```
      *
-     * @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"): UpdateBuilder<T>;
-    /**
-     * Generate the DynamoDB command parameters
+     * @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
      */
-    toDynamoCommand(): UpdateCommandParams;
+    conditionCheckWithCommand(command: ConditionCheckCommandParams): TransactionBuilder;
     /**
-     * Adds this update operation to a transaction.
+     * Sets options for the transaction execution.
      * Use this method when you need to:
-     * - Update items as part of a larger transaction
-     * - Ensure multiple updates are atomic
-     * - Coordinate updates across multiple items
+     * - Enable idempotent transactions
+     * - Track consumed capacity
+     * - Monitor item collection metrics
      *
      * @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);
+     * // Enable idempotency and capacity tracking
+     * transaction.withOptions({
+     *   clientRequestToken: 'unique-request-id-123',
+     *   returnConsumedCapacity: 'TOTAL'
+     * });
      *
-     * // Execute all operations atomically
-     * await transaction.execute();
+     * // Track item collection metrics
+     * transaction.withOptions({
+     *   returnItemCollectionMetrics: 'SIZE'
+     * });
      * ```
      *
-     * @param transaction - The transaction builder to add this operation to
-     * @returns The builder instance for method chaining
+     * 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
      */
-    withTransaction(transaction: TransactionBuilder): void;
+    withOptions(options: TransactionOptions): TransactionBuilder;
     /**
-     * Gets a human-readable representation of the update command.
+     * Gets a human-readable representation of the transaction items.
      * Use this method when you need to:
-     * - Debug complex update expressions
-     * - Verify attribute names and values
-     * - Log update operations
+     * - Debug complex transactions
+     * - Verify operation parameters
+     * - Log transaction details
      * - Troubleshoot condition expressions
      *
+     * The method resolves all expression placeholders with their actual values,
+     * making it easier to understand the transaction's operations.
+     *
      * @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));
+     * // Add multiple operations
+     * transaction
+     *   .put('orders', { orderId: '123', status: 'PENDING' })
+     *   .update('inventory',
+     *     { productId: 'ABC' },
+     *     'SET quantity = quantity - :amount',
+     *     undefined,
+     *     { ':amount': 1 }
+     *   );
      *
-     * // Debug the update
-     * const debugInfo = builder.debug();
-     * console.log('Update operation:', debugInfo);
+     * // Debug the transaction
+     * const debugInfo = transaction.debug();
+     * console.log('Transaction operations:', debugInfo);
      * ```
      *
-     * @returns A readable representation of the update command with resolved expressions
+     * @returns An array of readable representations of the transaction items
      */
-    debug(): Record<string, unknown>;
+    debug(): Record<string, unknown>[];
     /**
-     * Executes the update operation against DynamoDB.
+     * Executes all operations in the transaction atomically.
      * Use this method when you need to:
-     * - Apply updates immediately
-     * - Get the updated item values
-     * - Handle conditional update failures
+     * - Perform multiple operations atomically
+     * - Ensure all-or-nothing execution
+     * - Maintain data consistency across operations
+     *
+     * The transaction will only succeed if all operations succeed.
+     * If any operation fails, the entire transaction is rolled back.
      *
      * @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')
-     *       ])
+     *   // 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')
      *     )
-     *     .returnValues('ALL_NEW')
      *     .execute();
      *
-     *   if (result.item) {
-     *     console.log('Updated dinosaur:', result.item);
-     *   }
+     *   console.log('Transaction completed successfully');
      * } 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');
-     *   }
+     *   // Handle transaction failure
+     *   console.error('Transaction failed:', error);
      * }
      * ```
      *
-     * @returns A promise that resolves to an object 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
+     * @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<{
-        item?: T;
-    }>;
+    execute(): Promise<void>;
 }
 
-interface DeleteCommandParams extends DynamoCommandWithExpressions {
-    tableName: string;
-    key: PrimaryKeyWithoutExpression;
-    conditionExpression?: string;
-    expressionAttributeNames?: Record<string, string>;
-    expressionAttributeValues?: Record<string, unknown>;
-    returnValues?: "ALL_OLD";
+/**
+ * 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: (default) Performs a GET operation after the put to retrieve the item's new state
+     */
+    returnValues?: "ALL_OLD" | "NONE" | "CONSISTENT";
 }
-type DeleteExecutor = (params: DeleteCommandParams) => Promise<{
-    item?: Record<string, unknown>;
-}>;
+type PutExecutor<T extends Record<string, unknown>> = (params: PutCommandParams) => Promise<T>;
 /**
- * Builder for creating DynamoDB delete operations.
- * Use this builder when you need to:
- * - Remove dinosaurs from the registry
- * - Clean up abandoned habitats
- * - Delete historical tracking data
- * - Remove deprecated classifications
+ * Builder for creating DynamoDB put operations.
  *
  * @example
  * ```typescript
- * // Simple delete
- * const result = await new DeleteBuilder(executor, 'dinosaurs', { id: 'TREX-001' })
- *   .execute();
+ * // 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();
  *
- * // 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')
+ * // 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 DeleteBuilder {
+declare class PutBuilder<T extends Record<string, unknown>> {
+    private readonly item;
     private options;
     private readonly executor;
     private readonly tableName;
-    private readonly key;
-    constructor(executor: DeleteExecutor, tableName: string, key: PrimaryKeyWithoutExpression);
+    constructor(executor: PutExecutor<T>, item: T, tableName: string);
     /**
-     * Adds a condition that must be satisfied for the delete operation to succeed.
+     * Adds a condition that must be satisfied for the put operation to succeed.
      * Use this method when you need to:
-     * - Ensure safe removal conditions
-     * - Verify habitat status before deletion
-     * - Implement safety protocols
+     * - Prevent overwriting existing items (optimistic locking)
+     * - Ensure items meet certain criteria before replacement
+     * - Implement complex business rules for item updates
+     *
+     * @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 dinosaur can be safely removed
+     * // Ensure unique dinosaur ID
+     * builder.condition(op =>
+     *   op.attributeNotExists('id')
+     * );
+     *
+     * // Verify habitat requirements
      * builder.condition(op =>
      *   op.and([
-     *     op.eq('status', 'SEDATED'),
-     *     op.eq('location', 'MEDICAL_BAY'),
-     *     op.attributeExists('lastCheckup')
+     *     op.eq('securityStatus', 'READY'),
+     *     op.attributeExists('lastInspection'),
+     *     op.gt('securityLevel', 5)
      *   ])
      * );
      *
-     * // Verify habitat is empty
+     * // Check breeding facility conditions
      * builder.condition(op =>
      *   op.and([
-     *     op.eq('occupants', 0),
-     *     op.eq('maintenanceStatus', 'COMPLETE'),
-     *     op.not(op.attributeExists('activeAlerts'))
+     *     op.between('temperature', 25, 30),
+     *     op.between('humidity', 60, 80),
+     *     op.eq('quarantineStatus', 'CLEAR')
      *   ])
      * );
      * ```
@@ -1615,57 +1752,66 @@ declare class DeleteBuilder {
      * @param condition - Either a Condition object or a callback function that builds the condition
      * @returns The builder instance for method chaining
      */
-    condition<T extends Record<string, unknown>>(condition: Condition | ((op: ConditionOperator<T>) => Condition)): DeleteBuilder;
+    condition(condition: Condition | ((op: ConditionOperator<T>) => Condition)): this;
     /**
-     * Sets whether to return the item's attribute values before deletion.
-     * Use this method when you need to:
-     * - Archive removed dinosaur data
-     * - Track habitat decommissioning history
-     * - Maintain removal audit logs
+     * 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: (default) Performs a GET operation after the put to retrieve the item's new state
      *
      * @example
      * ```ts
-     * // Archive dinosaur data before removal
+     * // Get previous dinosaur state
      * 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
+     * if (result) {
+     *   console.log('Previous profile:', {
+     *     species: result.species,
+     *     status: result.status,
+     *     stats: {
+     *       health: result.stats.health,
+     *       threatLevel: result.stats.threatLevel
+     *     }
      *   });
      * }
      * ```
      *
-     * @param returnValues - Use 'ALL_OLD' to return all attributes of the deleted item
+     * @param returnValues - Use 'ALL_OLD' to return previous values if the item was overwritten, or 'NONE' (default).
      * @returns The builder instance for method chaining
      */
-    returnValues(returnValues: "ALL_OLD"): DeleteBuilder;
+    returnValues(returnValues: "ALL_OLD" | "NONE" | "CONSISTENT"): this;
     /**
      * Generate the DynamoDB command parameters
      */
     private toDynamoCommand;
     /**
-     * Adds this delete operation to a transaction.
+     * Adds this put operation to a transaction.
      * Use this method when you need to:
-     * - Coordinate dinosaur transfers
-     * - Manage habitat decommissioning
-     * - Handle species relocations
+     * - Transfer dinosaurs between habitats
+     * - Initialize new breeding programs
+     * - Update multiple facility records
      *
      * @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)
+     * // 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
@@ -1673,136 +1819,129 @@ declare class DeleteBuilder {
      * ```
      *
      * @param transaction - The transaction builder to add this operation to
+     * @returns The builder instance for method chaining
      */
-    withTransaction(transaction: TransactionBuilder): void;
+    withTransaction(transaction: TransactionBuilder): this;
     /**
-     * Executes the delete operation against DynamoDB.
+     * Executes the put 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();
+     * 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();
      *
-     * if (result.item) {
-     *   console.log('Deleted item:', result.item);
+     *   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 an object containing the deleted item's attributes (if returnValues is 'ALL_OLD')
+     * @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<{
-        item?: Record<string, unknown>;
-    }>;
+    execute(): Promise<T | undefined>;
     /**
-     * Gets a human-readable representation of the delete command
+     * Gets a human-readable representation of the put command
      * with all expression placeholders replaced by their actual values.
-     * Use this method when you need to:
-     * - Debug complex deletion conditions
-     * - Verify safety checks
-     * - Log removal operations
-     * - Troubleshoot failed deletions
      *
      * @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')
-     *   ]))
+     * 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('Delete command:', debugInfo);
+     * console.log('Dinosaur transfer command:', debugInfo);
      * ```
      *
-     * @returns A readable representation of the delete command with resolved expressions
+     * @returns A readable representation of the put command with resolved expressions
      */
     debug(): Record<string, unknown>;
 }
 
-interface ConditionCheckCommandParams extends DynamoCommandWithExpressions {
-    tableName: string;
-    key: PrimaryKeyWithoutExpression;
-    conditionExpression: string;
-    expressionAttributeNames?: Record<string, string>;
-    expressionAttributeValues?: Record<string, unknown>;
+interface DeleteOptions {
+    condition?: Condition;
+    returnValues?: "ALL_OLD";
 }
+type DeleteExecutor = (params: DeleteCommandParams) => Promise<{
+    item?: Record<string, unknown>;
+}>;
 /**
- * Builder for creating DynamoDB condition check operations.
+ * Builder for creating DynamoDB delete 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
+ * - Remove dinosaurs from the registry
+ * - Clean up abandoned habitats
+ * - Delete historical tracking data
+ * - Remove deprecated classifications
  *
  * @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();
+ * // Simple delete
+ * const result = await new DeleteBuilder(executor, 'dinosaurs', { id: 'TREX-001' })
+ *   .execute();
  *
- * // Check habitat security status
- * const securityCheck = new ConditionCheckBuilder('habitats', { id: 'PADDOCK-A' })
+ * // Conditional delete with old value retrieval
+ * const result = await new DeleteBuilder(executor, 'habitats', { id: 'PADDOCK-A' })
  *   .condition(op =>
  *     op.and([
- *       op.eq('securityStatus', 'ACTIVE'),
- *       op.attributeExists('lastInspection'),
- *       op.lt('threatLevel', 5)
+ *       op.eq('status', 'DECOMMISSIONED'),
+ *       op.eq('occupants', 0),
+ *       op.lt('securityIncidents', 1)
  *     ])
  *   )
- *   .toDynamoCommand();
+ *   .returnValues('ALL_OLD')
+ *   .execute();
  * ```
  */
-declare class ConditionCheckBuilder {
-    private readonly key;
+declare class DeleteBuilder {
+    private options;
+    private readonly executor;
     private readonly tableName;
-    private conditionExpression?;
-    constructor(tableName: string, key: PrimaryKeyWithoutExpression);
+    private readonly key;
+    constructor(executor: DeleteExecutor, tableName: string, key: PrimaryKeyWithoutExpression);
     /**
-     * Adds a condition that must be satisfied for the check to succeed.
+     * Adds a condition that must be satisfied for the delete operation to succeed.
      * Use this method when you need to:
-     * - Validate complex item states
-     * - Check multiple attributes together
-     * - Ensure safety conditions are met
+     * - Ensure safe removal conditions
+     * - Verify habitat status before deletion
+     * - Implement safety protocols
      *
      * @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
+     * // Ensure dinosaur can be safely removed
      * builder.condition(op =>
      *   op.and([
-     *     op.eq('powerStatus', 'ONLINE'),
-     *     op.between('temperature', 20, 30),
-     *     op.attributeExists('lastMaintenance')
+     *     op.eq('status', 'SEDATED'),
+     *     op.eq('location', 'MEDICAL_BAY'),
+     *     op.attributeExists('lastCheckup')
      *   ])
      * );
      *
-     * // Check breeding conditions
+     * // Verify habitat is empty
      * builder.condition(op =>
      *   op.and([
-     *     op.eq('species', 'VELOCIRAPTOR'),
-     *     op.gte('age', 3),
-     *     op.eq('geneticPurity', 100)
+     *     op.eq('occupants', 0),
+     *     op.eq('maintenanceStatus', 'COMPLETE'),
+     *     op.not(op.attributeExists('activeAlerts'))
      *   ])
      * );
      * ```
@@ -1810,689 +1949,602 @@ declare class ConditionCheckBuilder {
      * @param condition - Either a Condition object or a callback function that builds the condition
      * @returns The builder instance for method chaining
      */
-    condition<T extends Record<string, unknown>>(condition: Condition | ((op: ConditionOperator<T>) => Condition)): ConditionCheckBuilder;
+    condition<T extends Record<string, unknown>>(condition: Condition | ((op: ConditionOperator<T>) => Condition)): DeleteBuilder;
     /**
-     * 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
+     * Sets whether to return the item's attribute values before deletion.
+     * Use this method when you need to:
+     * - Archive removed dinosaur data
+     * - Track habitat decommissioning history
+     * - Maintain removal audit logs
      *
      * @example
      * ```ts
-     * const command = new ConditionCheckBuilder('myTable', { id: '123' })
-     *   .condition(op => op.attributeExists('status'))
-     *   .toDynamoCommand();
-     * // Use command with DynamoDB client
+     * // 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
+     *   });
+     * }
      * ```
      *
-     * @throws {Error} If no condition has been set
-     * @returns The DynamoDB command parameters
+     * @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 condition check operation to a transaction.
+     * Adds this delete operation to a transaction.
      * Use this method when you need to:
-     * - Verify habitat safety before transfers
-     * - Ensure proper feeding conditions
-     * - Validate security protocols
+     * - Coordinate dinosaur transfers
+     * - Manage habitat decommissioning
+     * - Handle species relocations
      *
      * @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')
-     *   ]))
+     *
+     * // Remove dinosaur from old habitat
+     * new DeleteBuilder(executor, 'dinosaurs', { id: 'RAPTOR-001' })
+     *   .condition(op => op.eq('status', 'SEDATED'))
      *   .withTransaction(transaction);
-     * // Add dinosaur transfer operations
+     *
+     * // 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
-     * @throws {Error} If no condition has been set
-     * @returns The builder instance for method chaining
      */
-    withTransaction(transaction: TransactionBuilder): ConditionCheckBuilder;
+    withTransaction(transaction: TransactionBuilder): void;
     /**
-     * Gets a human-readable representation of the condition check command
-     * with all expression placeholders replaced by their actual values.
-     * Use this method when you need to:
-     * - Debug complex condition expressions
-     * - Verify condition parameters
-     * - Log safety checks
-     * - Troubleshoot condition failures
+     * Executes the delete operation against DynamoDB.
      *
      * @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);
+     * // 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 readable representation of the condition check command with resolved expressions
+     * @returns A promise that resolves to an object containing the deleted item's attributes (if returnValues is 'ALL_OLD')
      */
-    debug(): Record<string, unknown>;
-}
-
+    execute(): Promise<{
+        item?: Record<string, unknown>;
+    }>;
+    /**
+     * Gets a human-readable representation of the delete command
+     * with all expression placeholders replaced by their actual values.
+     * Use this method when you need to:
+     * - Debug complex deletion conditions
+     * - Verify safety checks
+     * - Log removal operations
+     * - Troubleshoot failed deletions
+     *
+     * @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(): Record<string, unknown>;
+}
+
 /**
- * Configuration options for DynamoDB transactions.
+ * Configuration options for DynamoDB update operations.
  */
-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";
+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";
 }
 /**
- * Configuration for table indexes used in duplicate detection.
- * Defines the key structure for checking uniqueness constraints.
+ * Function type for executing DynamoDB update operations.
+ * @typeParam T - The type of the item being updated
  */
-interface IndexConfig {
-    /** The partition key attribute name */
-    partitionKey: string;
-    /** Optional sort key attribute name */
-    sortKey?: string;
-}
+type UpdateExecutor<T extends Record<string, unknown>> = (params: UpdateCommandParams) => Promise<{
+    item?: T;
+}>;
 /**
- * Function type for executing DynamoDB transaction operations.
- * @param params - The complete transaction command input
- * @returns A promise that resolves when the transaction completes
+ * 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 TransactionExecutor = (params: TransactWriteCommandInput) => Promise<void>;
+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;
+};
 /**
- * Builder for creating and executing DynamoDB transactions.
+ * 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.
  * 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
+ * - Modify existing items in DynamoDB
+ * - Update multiple attributes atomically
+ * - Perform conditional updates
+ * - Work with nested attributes
+ * - Update sets and lists
  *
- * The builder supports:
- * - Put operations (insert/replace items)
- * - Delete operations
- * - Update operations
- * - Condition checks
- * - Duplicate detection
- * - Transaction-wide options
+ * 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
- * // 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)
- * );
+ * // Simple update
+ * const result = await new UpdateBuilder(executor, 'dinosaurs', { id: 'TREX-001' })
+ *   .set('status', 'HUNTING')
+ *   .set('lastFed', new Date().toISOString())
+ *   .execute();
  *
- * // Execute the transaction atomically
- * await transaction.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();
  * ```
  *
- * 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
+ * @typeParam T - The type of item being updated
  */
-declare class TransactionBuilder {
-    private items;
+declare class UpdateBuilder<T extends Record<string, unknown>> {
+    private updates;
     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;
+    private readonly tableName;
+    private readonly key;
+    constructor(executor: UpdateExecutor<T>, tableName: string, key: PrimaryKeyWithoutExpression);
     /**
-     * Adds a put operation to the transaction.
+     * Sets multiple attributes of an item using an object.
      * Use this method when you need to:
-     * - Insert new items as part of a transaction
-     * - Replace existing items atomically
-     * - Ensure items meet certain conditions before insertion
-     *
-     * The method automatically checks for duplicate items within the transaction
-     * to prevent multiple operations on the same item.
+     * - Update multiple attributes at once
+     * - Set nested attribute values
+     * - Modify complex data structures
      *
      * @example
      * ```typescript
-     * // Simple put operation
-     * transaction.put('orders', {
-     *   orderId: '123',
-     *   status: 'PENDING',
-     *   amount: 100
+     * // Update multiple attributes
+     * builder.set({
+     *   species: 'Tyrannosaurus Rex',
+     *   height: 20,
+     *   diet: 'CARNIVORE',
+     *   'stats.threatLevel': 10
      * });
-     *
-     * // 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 Record<string, unknown>>(tableName: string, item: T, condition?: Condition): TransactionBuilder;
-    /**
-     * Adds a pre-configured put operation to the transaction.
-     * Use this method when you need to:
-     * - Reuse put commands from PutBuilder
-     * - Add complex put operations with pre-configured parameters
-     * - Integrate with existing put command configurations
-     *
-     * 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;
+    set(values: Partial<T>): UpdateBuilder<T>;
     /**
-     * Adds a delete operation to the transaction.
+     * Sets a single attribute to a specific value.
      * Use this method when you need to:
-     * - Remove items as part of a transaction
-     * - Conditionally delete items
-     * - Ensure items exist before deletion
-     *
-     * The method automatically checks for duplicate items within the transaction
-     * to prevent multiple operations on the same item.
+     * - Update one attribute at a time
+     * - Set values with type safety
+     * - Update nested attributes
      *
      * @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)
-     *   ])
-     * );
-     * ```
+     * // Set simple attributes
+     * builder
+     *   .set('status', 'SLEEPING')
+     *   .set('lastFeeding', new Date().toISOString());
      *
-     * @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
+     * // Set nested attributes
+     * builder
+     *   .set('location.zone', 'RESTRICTED')
+     *   .set('stats.health', 100);
+     * ```
      */
-    delete(tableName: string, key: PrimaryKeyWithoutExpression, condition?: Condition): TransactionBuilder;
+    set<K extends Path<T>>(path: K, value: PathType<T, K>): UpdateBuilder<T>;
     /**
-     * Adds a pre-configured delete operation to the transaction.
+     * Removes an attribute from the item.
      * Use this method when you need to:
-     * - Reuse delete commands from DeleteBuilder
-     * - Add complex delete operations with pre-configured parameters
-     * - Integrate with existing delete command configurations
-     *
-     * This method is particularly useful when working with DeleteBuilder
-     * to maintain consistency in delete operations across your application.
+     * - Delete attributes completely
+     * - Remove nested attributes
+     * - Clean up deprecated fields
      *
      * @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();
+     * // Remove simple attributes
+     * builder
+     *   .remove('temporaryTag')
+     *   .remove('previousLocation');
      *
-     * // Add the command to the transaction
-     * transaction.deleteWithCommand(deleteCommand);
+     * // Remove nested attributes
+     * builder
+     *   .remove('metadata.testData')
+     *   .remove('stats.experimentalMetrics');
      * ```
      *
-     * @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
+     * @param path - The path to the attribute to remove
+     * @returns The builder instance for method chaining
      */
-    deleteWithCommand(command: DeleteCommandParams): TransactionBuilder;
+    remove<K extends Path<T>>(path: K): UpdateBuilder<T>;
     /**
-     * Adds an update operation to the transaction.
+     * Adds a value to a number attribute or adds elements to a set.
      * Use this method when you need to:
-     * - Modify existing items as part of a transaction
-     * - Update multiple attributes atomically
-     * - Apply conditional updates
-     * - Perform complex attribute manipulations
-     *
-     * 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
+     * - Increment counters
+     * - Add elements to a set atomically
+     * - Update numerical statistics
      *
      * @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' }
-     * );
+     * // Increment counters
+     * builder
+     *   .add('escapeAttempts', 1)
+     *   .add('feedingCount', 1);
      *
-     * // Conditional update
-     * transaction.update(
-     *   'users',
-     *   { pk: 'USER#123' },
-     *   'SET #lastLogin = :now',
-     *   { '#lastLogin': 'lastLoginDate' },
-     *   { ':now': new Date().toISOString() },
-     *   op => op.attributeExists('pk')
-     * );
+     * // Add to sets
+     * builder
+     *   .add('knownBehaviors', new Set(['PACK_HUNTING', 'AMBUSH_TACTICS']))
+     *   .add('visitedZones', new Set(['ZONE_A', 'ZONE_B']));
      * ```
      *
-     * @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
+     * @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
      */
-    update<T extends Record<string, unknown>>(tableName: string, key: PrimaryKeyWithoutExpression, updateExpression: string, expressionAttributeNames?: Record<string, string>, expressionAttributeValues?: Record<string, unknown>, condition?: Condition): TransactionBuilder;
+    add<K extends Path<T>>(path: K, value: PathType<T, K>): UpdateBuilder<T>;
     /**
-     * Adds a pre-configured update operation to the transaction.
+     * Removes elements from a set attribute.
      * Use this method when you need to:
-     * - Reuse update commands from UpdateBuilder
-     * - Add complex update operations with pre-configured parameters
-     * - Integrate with existing update command configurations
-     *
-     * This method is particularly useful when working with UpdateBuilder
-     * to maintain consistency in update operations across your application.
+     * - Remove specific elements from a set
+     * - Update set-based attributes atomically
+     * - Maintain set membership
      *
      * @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();
+     * // Remove from sets using arrays
+     * builder.deleteElementsFromSet(
+     *   'allowedHabitats',
+     *   ['JUNGLE', 'COASTAL']
+     * );
      *
-     * // Add the command to the transaction
-     * transaction.updateWithCommand(updateCommand);
+     * // Remove from sets using Set objects
+     * builder.deleteElementsFromSet(
+     *   'knownBehaviors',
+     *   new Set(['NOCTURNAL', 'TERRITORIAL'])
+     * );
+     *
+     * // Remove from nested sets
+     * builder.deleteElementsFromSet(
+     *   'stats.compatibleSpecies',
+     *   ['VELOCIRAPTOR', 'DILOPHOSAURUS']
+     * );
      * ```
      *
-     * @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
+     * @param path - The path to the set attribute
+     * @param value - Elements to remove (array or Set)
+     * @returns The builder instance for method chaining
      */
-    updateWithCommand(command: UpdateCommandParams): TransactionBuilder;
+    deleteElementsFromSet<K extends Path<T>>(path: K, value: PathSetElementType<T, K>[] | Set<PathSetElementType<T, K>>): UpdateBuilder<T>;
     /**
-     * Adds a condition check operation to the transaction.
+     * Adds a condition that must be satisfied for the update to succeed.
      * Use this method when you need to:
-     * - Validate item state without modifying it
-     * - Ensure data consistency across tables
-     * - Implement complex business rules
-     * - Verify preconditions for other operations
-     *
-     * Condition checks are particularly useful for:
-     * - Implementing optimistic locking
-     * - Ensuring referential integrity
-     * - Validating business rules atomically
+     * - Implement optimistic locking
+     * - Ensure item state before update
+     * - Validate business rules
+     * - Prevent concurrent modifications
      *
      * @example
      * ```typescript
-     * // Check if order is in correct state
-     * transaction.conditionCheck(
-     *   'orders',
-     *   { pk: 'ORDER#123' },
-     *   op => op.eq('status', 'PENDING')
+     * // Simple condition
+     * builder.condition(op =>
+     *   op.eq('status', 'ACTIVE')
      * );
      *
-     * // Complex condition check
-     * transaction.conditionCheck(
-     *   'inventory',
-     *   { pk: 'PROD#ABC' },
-     *   op => op.and([
-     *     op.gt('quantity', 0),
-     *     op.eq('status', 'ACTIVE'),
-     *     op.attributeExists('lastRestockDate')
+     * // Health check condition
+     * builder.condition(op =>
+     *   op.and([
+     *     op.gt('health', 50),
+     *     op.eq('status', 'HUNTING')
      *   ])
      * );
      *
-     * // Check with multiple attributes
-     * transaction.conditionCheck(
-     *   'users',
-     *   { pk: 'USER#123' },
-     *   op => op.or([
-     *     op.eq('status', 'PREMIUM'),
-     *     op.gte('credits', 100)
+     * // 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 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
+     * @param condition - Either a Condition object or a callback function that builds the condition
+     * @returns The builder instance for method chaining
      */
-    conditionCheck(tableName: string, key: PrimaryKeyWithoutExpression, condition: Condition): TransactionBuilder;
+    condition(condition: Condition | ((op: ConditionOperator<T>) => Condition)): UpdateBuilder<T>;
     /**
-     * Adds a pre-configured condition check operation to the transaction.
+     * Sets which item attributes to include in the response.
      * Use this method when you need to:
-     * - Reuse condition checks from ConditionCheckBuilder
-     * - Add complex condition checks with pre-configured parameters
-     * - Integrate with existing condition check configurations
+     * - Get the complete updated item
+     * - Track changes to specific attributes
+     * - Compare old and new values
+     * - Monitor attribute modifications
      *
-     * This method is particularly useful when working with ConditionCheckBuilder
-     * to maintain consistency in condition checks across your application.
+     * Available options:
+     * - ALL_NEW: All attributes after the update
+     * - 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 (default)
      *
      * @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();
+     * // 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();
      *
-     * // Add the command to the transaction
-     * transaction.conditionCheckWithCommand(checkCommand);
+     * if (result.item) {
+     *   console.log('Previous health:', result.item.stats?.health);
+     * }
      * ```
      *
-     * @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
+     * @param returnValues - Which attributes to return in the response
+     * @returns The builder instance for method chaining
      */
-    conditionCheckWithCommand(command: ConditionCheckCommandParams): TransactionBuilder;
+    returnValues(returnValues: "ALL_NEW" | "UPDATED_NEW" | "ALL_OLD" | "UPDATED_OLD" | "NONE"): UpdateBuilder<T>;
     /**
-     * Sets options for the transaction execution.
+     * Generate the DynamoDB command parameters
+     */
+    toDynamoCommand(): UpdateCommandParams;
+    /**
+     * Adds this update operation to a transaction.
      * Use this method when you need to:
-     * - Enable idempotent transactions
-     * - Track consumed capacity
-     * - Monitor item collection metrics
+     * - Update items as part of a larger transaction
+     * - Ensure multiple updates are atomic
+     * - Coordinate updates across multiple items
      *
      * @example
      * ```typescript
-     * // Enable idempotency and capacity tracking
-     * transaction.withOptions({
-     *   clientRequestToken: 'unique-request-id-123',
-     *   returnConsumedCapacity: 'TOTAL'
-     * });
+     * const transaction = new TransactionBuilder(executor);
      *
-     * // Track item collection metrics
-     * transaction.withOptions({
-     *   returnItemCollectionMetrics: 'SIZE'
-     * });
-     * ```
+     * // Update dinosaur status and habitat occupancy atomically
+     * new UpdateBuilder(executor, 'dinosaurs', { id: 'TREX-001' })
+     *   .set('location', 'PADDOCK_A')
+     *   .set('status', 'CONTAINED')
+     *   .withTransaction(transaction);
      *
-     * Note: ClientRequestToken can be used to make transactions idempotent,
-     * ensuring the same transaction is not executed multiple times.
+     * new UpdateBuilder(executor, 'habitats', { id: 'PADDOCK-A' })
+     *   .add('occupants', 1)
+     *   .set('lastOccupied', new Date().toISOString())
+     *   .withTransaction(transaction);
      *
-     * @param options - Configuration options for the transaction
-     * @returns The transaction builder for method chaining
+     * // Execute all operations atomically
+     * await transaction.execute();
+     * ```
+     *
+     * @param transaction - The transaction builder to add this operation to
+     * @returns The builder instance for method chaining
      */
-    withOptions(options: TransactionOptions): TransactionBuilder;
+    withTransaction(transaction: TransactionBuilder): void;
     /**
-     * Gets a human-readable representation of the transaction items.
+     * Gets a human-readable representation of the update command.
      * Use this method when you need to:
-     * - Debug complex transactions
-     * - Verify operation parameters
-     * - Log transaction details
+     * - Debug complex update expressions
+     * - Verify attribute names and values
+     * - Log update operations
      * - Troubleshoot condition expressions
      *
-     * 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 }
-     *   );
+     * // 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 transaction
-     * const debugInfo = transaction.debug();
-     * console.log('Transaction operations:', debugInfo);
+     * // Debug the update
+     * const debugInfo = builder.debug();
+     * console.log('Update operation:', debugInfo);
      * ```
      *
-     * @returns An array of readable representations of the transaction items
+     * @returns A readable representation of the update command with resolved expressions
      */
-    debug(): Record<string, unknown>[];
+    debug(): Record<string, unknown>;
     /**
-     * Executes all operations in the transaction atomically.
+     * Executes the update operation against DynamoDB.
      * Use this method when you need to:
-     * - Perform multiple operations atomically
-     * - Ensure all-or-nothing execution
-     * - Maintain data consistency across operations
-     *
-     * The transaction will only succeed if all operations succeed.
-     * If any operation fails, the entire transaction is rolled back.
+     * - Apply updates immediately
+     * - Get the updated item values
+     * - Handle conditional update failures
      *
      * @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')
+     *   // 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();
      *
-     *   console.log('Transaction completed successfully');
+     *   if (result.item) {
+     *     console.log('Updated dinosaur:', result.item);
+     *   }
      * } catch (error) {
-     *   // Handle transaction failure
-     *   console.error('Transaction failed:', 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');
+     *   }
      * }
      * ```
      *
-     * @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
+     * @returns A promise that resolves to an object 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<void>;
+    execute(): Promise<{
+        item?: T;
+    }>;
 }
 
+type BatchWriteOperation<T extends Record<string, unknown>> = {
+    type: "put";
+    item: T;
+} | {
+    type: "delete";
+    key: PrimaryKeyWithoutExpression;
+};
+
 /**
- * Parameters for the DynamoDB put command.
- * These parameters are used when executing the operation against DynamoDB.
- */
-interface PutCommandParams extends DynamoCommandWithExpressions {
-    tableName: string;
-    item: Record<string, unknown>;
-    conditionExpression?: string;
-    expressionAttributeNames?: Record<string, string>;
-    expressionAttributeValues?: Record<string, unknown>;
-    returnValues?: "ALL_OLD" | "NONE";
-}
-type PutExecutor<T extends Record<string, unknown>> = (params: PutCommandParams) => Promise<T>;
-/**
- * Builder for creating DynamoDB put operations.
+ * Builder for creating DynamoDB condition check operations.
  * Use this builder when you need to:
- * - Add new dinosaurs to the registry
- * - Create new habitats
- * - Update dinosaur profiles completely
- * - Initialize tracking records
+ * - Verify item state without modifying it
+ * - Ensure preconditions in transactions
+ * - Implement optimistic locking patterns
+ * - Validate business rules
  *
  * @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();
- * ```
+ * // 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();
  *
- * @typeParam T - The type of item being put into the table
- */
-declare class PutBuilder<T extends Record<string, unknown>> {
-    private readonly item;
-    private options;
-    private readonly executor;
-    private readonly tableName;
-    constructor(executor: PutExecutor<T>, item: T, tableName: string);
-    /**
-     * Adds a condition that must be satisfied for the put operation to succeed.
-     * Use this method when you need to:
-     * - Prevent overwriting existing items (optimistic locking)
-     * - Ensure items meet certain criteria before replacement
-     * - Implement complex business rules for item updates
-     *
-     * @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
-     */
+ * // 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 put operation to succeed.
+     * Adds a condition that must be satisfied for the check to succeed.
      * Use this method when you need to:
-     * - Prevent duplicate dinosaur entries
-     * - Ensure habitat requirements
-     * - Validate security protocols
+     * - Validate complex item states
+     * - Check multiple attributes together
+     * - Ensure safety conditions are met
      *
      * @example
      * ```typescript
-     * // Ensure unique dinosaur ID
+     * // Check dinosaur health and behavior
      * builder.condition(op =>
-     *   op.attributeNotExists('id')
+     *   op.and([
+     *     op.gt('stats.health', 50),
+     *     op.not(op.eq('status', 'SEDATED')),
+     *     op.lt('aggressionLevel', 8)
+     *   ])
      * );
      *
-     * // Verify habitat requirements
+     * // Verify habitat conditions
      * builder.condition(op =>
      *   op.and([
-     *     op.eq('securityStatus', 'READY'),
-     *     op.attributeExists('lastInspection'),
-     *     op.gt('securityLevel', 5)
+     *     op.eq('powerStatus', 'ONLINE'),
+     *     op.between('temperature', 20, 30),
+     *     op.attributeExists('lastMaintenance')
      *   ])
      * );
      *
-     * // Check breeding facility conditions
+     * // Check breeding conditions
      * builder.condition(op =>
      *   op.and([
-     *     op.between('temperature', 25, 30),
-     *     op.between('humidity', 60, 80),
-     *     op.eq('quarantineStatus', 'CLEAR')
+     *     op.eq('species', 'VELOCIRAPTOR'),
+     *     op.gte('age', 3),
+     *     op.eq('geneticPurity', 100)
      *   ])
      * );
      * ```
@@ -2500,144 +2552,78 @@ declare class PutBuilder<T extends Record<string, unknown>> {
      * @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)): PutBuilder<T>;
+    condition<T extends Record<string, unknown>>(condition: Condition | ((op: ConditionOperator<T>) => Condition)): ConditionCheckBuilder;
     /**
-     * Sets whether to return the item's previous values (if it existed).
-     * Use this method when you need to:
-     * - Track dinosaur profile updates
-     * - Monitor habitat modifications
-     * - Maintain change history
+     * 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
-     * // 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
-     *     }
-     *   });
-     * }
+     * const command = new ConditionCheckBuilder('myTable', { id: '123' })
+     *   .condition(op => op.attributeExists('status'))
+     *   .toDynamoCommand();
+     * // Use command with DynamoDB client
      * ```
      *
-     * @param returnValues - Use 'ALL_OLD' to return previous values, or 'NONE' (default)
-     * @returns The builder instance for method chaining
-     */
-    returnValues(returnValues: "ALL_OLD" | "NONE"): PutBuilder<T>;
-    /**
-     * Generate the DynamoDB command parameters
+     * @throws {Error} If no condition has been set
+     * @returns The DynamoDB command parameters
      */
     private toDynamoCommand;
     /**
-     * Adds this put operation to a transaction.
+     * Adds this condition check operation to a transaction.
      * Use this method when you need to:
-     * - Transfer dinosaurs between habitats
-     * - Initialize new breeding programs
-     * - Update multiple facility records
+     * - Verify habitat safety before transfers
+     * - Ensure proper feeding conditions
+     * - Validate security protocols
      *
      * @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())
+     * new ConditionCheckBuilder('habitats', { id: 'PADDOCK-B' })
+     *   .condition(op => op.and([
+     *     op.eq('securityStatus', 'ACTIVE'),
+     *     op.lt('currentOccupants', 3),
+     *     op.eq('habitatType', 'CARNIVORE')
+     *   ]))
      *   .withTransaction(transaction);
-     *
-     * // Execute transfer atomically
-     * await transaction.execute();
+     * // 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): PutBuilder<T>;
-    /**
-     * 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>;
+    withTransaction(transaction: TransactionBuilder): ConditionCheckBuilder;
     /**
-     * Gets a human-readable representation of the put command
+     * Gets a human-readable representation of the condition check command
      * with all expression placeholders replaced by their actual values.
      * Use this method when you need to:
-     * - Debug complex dinosaur transfers
-     * - Verify habitat assignments
-     * - Log security protocols
-     * - Troubleshoot breeding program conditions
+     * - Debug complex condition expressions
+     * - Verify condition parameters
+     * - Log safety checks
+     * - Troubleshoot condition failures
      *
      * @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)
-     *     ])
-     *   )
+     * 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('Dinosaur transfer command:', debugInfo);
+     * console.log(debugInfo);
      * ```
      *
-     * @returns A readable representation of the put command with resolved expressions
+     * @returns A readable representation of the condition check command with resolved expressions
      */
     debug(): Record<string, unknown>;
 }
 
-type BatchWriteOperation<T extends Record<string, unknown>> = {
-    type: "put";
-    item: T;
-} | {
-    type: "delete";
-    key: PrimaryKeyWithoutExpression;
-};
-
 /**
  * Parameters for the DynamoDB get command.
  */
@@ -2770,11 +2756,136 @@ declare class GetBuilder<T extends Record<string, unknown>> {
     }>;
 }
 
+/**
+ * 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 Record<string, unknown>> = (options: ScanOptions) => Promise<{
+    items: T[];
+    lastEvaluatedKey?: Record<string, unknown>;
+}>;
+/**
+ * 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 Record<string, unknown>, 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.
+     * Use this method when you need to:
+     * - Create scan templates
+     * - Run multiple variations of a scan
+     * - Implement pagination (used internally by paginate())
+     *
+     * @returns A new ScanBuilder instance with the same configuration
+     */
+    clone(): ScanBuilder<T, TConfig>;
+    /**
+     * Executes the scan against DynamoDB.
+     * Use this method when you need to:
+     * - Search across the entire table
+     * - Find items matching specific criteria
+     * - Perform full table analysis
+     * - Generate reports across all data
+     *
+     * The method returns both the matched items and, if there are more results,
+     * a lastEvaluatedKey that can be used with startFrom() to continue the scan.
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   // Find all dinosaurs with high aggression levels
+     *   const result = await new ScanBuilder(executor)
+     *     .filter(op =>
+     *       op.and([
+     *         op.eq('status', 'ACTIVE'),
+     *         op.gt('aggressionLevel', 7)
+     *       ])
+     *     )
+     *     .limit(20)
+     *     .execute();
+     *
+     *   console.log(`Found ${result.items.length} potentially dangerous dinosaurs`);
+     *
+     *   if (result.lastEvaluatedKey) {
+     *     console.log('More results available');
+     *   }
+     * } catch (error) {
+     *   console.error('Security scan failed:', error);
+     * }
+     * ```
+     *
+     * @returns A promise that resolves to an object containing:
+     *          - items: Array of items matching the scan criteria
+     *          - lastEvaluatedKey: Token for continuing the scan, if more items exist
+     */
+    execute(): Promise<{
+        items: T[];
+        lastEvaluatedKey?: Record<string, unknown>;
+    }>;
+}
+
 declare class Table<TConfig extends TableConfig = TableConfig> {
-    private dynamoClient;
+    private readonly dynamoClient;
     readonly tableName: string;
+    /**
+     * The column name of the partitionKey for the Table
+     */
     readonly partitionKey: string;
+    /**
+     * The column name of the sortKey for the Table
+     */
     readonly sortKey?: string;
+    /**
+     * The Global Secondary Indexes that are configured on this table
+     */
     readonly gsis: Record<string, Index>;
     constructor(config: TConfig);
     /**
@@ -2797,6 +2908,16 @@ declare class Table<TConfig extends TableConfig = TableConfig> {
      * If useIndex is called on the returned QueryBuilder, it will use the GSI configuration
      */
     query<T extends Record<string, unknown>>(keyCondition: PrimaryKey): QueryBuilder<T, TConfig>;
+    /**
+     * Creates a scan builder for scanning the entire table
+     * Use this when you need to:
+     * - Process all items in a table
+     * - Apply filters to a large dataset
+     * - Use a GSI for scanning
+     *
+     * @returns A ScanBuilder instance for chaining operations
+     */
+    scan<T extends Record<string, unknown>>(): ScanBuilder<T, TConfig>;
     delete(keyCondition: PrimaryKeyWithoutExpression): DeleteBuilder;
     /**
      * Updates an item in the table
@@ -2847,4 +2968,4 @@ declare class Table<TConfig extends TableConfig = TableConfig> {
     }>;
 }
 
-export { type Condition, ConditionCheckBuilder, type ConditionOperator, DeleteBuilder, type EntityConfig, type GSINames, type Index, type PaginationResult, Paginator, PutBuilder, QueryBuilder, Table, type TableConfig, TransactionBuilder, UpdateBuilder, and, attributeExists, attributeNotExists, beginsWith, between, contains, eq, gt, gte, lt, lte, ne, not, or };
+export { type ComparisonOperator, type Condition, ConditionCheckBuilder, type ConditionOperator, DeleteBuilder, type DeleteOptions, type EntityConfig, type ExpressionParams, type GSINames, type Index, type KeyConditionOperator, type LogicalOperator, Paginator, type PrimaryKey, type PrimaryKeyWithoutExpression, PutBuilder, type PutOptions, QueryBuilder, type QueryOptions, Table, type TableConfig, TransactionBuilder, type TransactionExecutor, type TransactionOptions, type UpdateAction, UpdateBuilder, type UpdateOptions, and, attributeExists, attributeNotExists, beginsWith, between, contains, createComparisonCondition, eq, gt, gte, lt, lte, ne, not, or };