dyno-table 0.1.6 → 0.1.8

package/dist/index.js

@@ -191,16 +191,16 @@ var Paginator = class {
    * - Track progress through dinosaur lists
    * - Display habitat inspection status
    * - Monitor security sweep progress
-   * 
+   *
    * @example
    * ```ts
    * const paginator = new QueryBuilder(executor, eq('species', 'Tyrannosaurus'))
    *   .paginate(5);
-   * 
+   *
    * await paginator.getNextPage();
    * console.log(`Reviewing T-Rex group ${paginator.getCurrentPage()}`);
    * ```
-   * 
+   *
    * @returns The current page number, starting from 1
    */
   getCurrentPage() {
@@ -213,18 +213,18 @@ var Paginator = class {
    * - Continue habitat inspections
    * - Process security incidents
    * - Complete feeding schedules
-   * 
+   *
    * This method takes into account both:
    * - DynamoDB's lastEvaluatedKey mechanism
    * - Any overall limit set on the query
-   * 
+   *
    * @example
    * ```ts
    * // Process all security incidents
    * const paginator = new QueryBuilder(executor, eq('type', 'SECURITY_BREACH'))
    *   .sortDescending()
    *   .paginate(10);
-   * 
+   *
    * while (paginator.hasNextPage()) {
    *   const page = await paginator.getNextPage();
    *   for (const incident of page.items) {
@@ -233,7 +233,7 @@ var Paginator = class {
    *   console.log(`Processed incidents page ${page.page}`);
    * }
    * ```
-   * 
+   *
    * @returns true if there are more pages available, false otherwise
    */
   hasNextPage() {
@@ -249,33 +249,33 @@ var Paginator = class {
    * - Review habitat inspections in batches
    * - Monitor security incidents in sequence
    * - Schedule feeding rotations
-   * 
+   *
    * This method handles:
    * - Automatic continuation between groups
    * - Respect for park capacity limits
    * - Group size adjustments for safety
-   * 
+   *
    * @example
    * ```ts
    * const paginator = new QueryBuilder(executor, eq('species', 'Velociraptor'))
    *   .filter(op => op.eq('status', 'ACTIVE'))
    *   .paginate(5);
-   * 
+   *
    * // Check first raptor group
    * const page1 = await paginator.getNextPage();
    * console.log(`Found ${page1.items.length} active raptors`);
-   * 
+   *
    * // Continue inspection if more groups exist
    * if (page1.hasNextPage) {
    *   const page2 = await paginator.getNextPage();
    *   console.log(`Inspecting raptor group ${page2.page}`);
-   *   
+   *
    *   for (const raptor of page2.items) {
    *     await performHealthCheck(raptor);
    *   }
    * }
    * ```
-   * 
+   *
    * @returns A promise that resolves to a PaginationResult containing:
    *          - items: The dinosaurs/habitats for this page
    *          - hasNextPage: Whether more groups exist
@@ -325,23 +325,23 @@ var Paginator = class {
    * - Perform full security audit
    * - Create comprehensive feeding schedule
    * - Run park-wide health checks
-   * 
+   *
    * Note: Use with caution! This method:
    * - Could overwhelm systems with large dinosaur populations
    * - Makes multiple database requests
    * - May cause system strain during peak hours
-   * 
+   *
    * @example
    * ```ts
    * // Get complete carnivore inventory
    * const paginator = new QueryBuilder(executor, eq('diet', 'CARNIVORE'))
    *   .filter(op => op.eq('status', 'ACTIVE'))
    *   .paginate(10);
-   * 
+   *
    * try {
    *   const allCarnivores = await paginator.getAllPages();
    *   console.log(`Park contains ${allCarnivores.length} active carnivores`);
-   *   
+   *
    *   // Calculate total threat level
    *   const totalThreat = allCarnivores.reduce(
    *     (sum, dino) => sum + dino.stats.threatLevel,
@@ -352,7 +352,7 @@ var Paginator = class {
    *   console.error('Failed to complete carnivore census:', error);
    * }
    * ```
-   * 
+   *
    * @returns A promise that resolves to an array containing all remaining items
    */
   async getAllPages() {
@@ -365,30 +365,24 @@ var Paginator = class {
   }
 };
 
-// src/builders/query-builder.ts
-var QueryBuilder = class _QueryBuilder {
-  keyCondition;
+// src/builders/filter-builder.ts
+var FilterBuilder = class {
   options = {};
   selectedFields = /* @__PURE__ */ new Set();
-  executor;
-  constructor(executor, keyCondition) {
-    this.executor = executor;
-    this.keyCondition = keyCondition;
-  }
   /**
-   * 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();
    * ```
@@ -401,7 +395,7 @@ var QueryBuilder = class _QueryBuilder {
     return 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
@@ -410,63 +404,31 @@ var QueryBuilder = class _QueryBuilder {
     return this.options.limit;
   }
   /**
-   * 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
-   * 
+   *
    * @example
    * ```typescript
    * // Find all dinosaurs of a specific species
    * builder
    *   .useIndex('species-status-index')
    *   .filter(op => op.eq('status', 'ACTIVE'));
-   * 
+   *
    * // Search high-security habitats
    * builder
    *   .useIndex('security-level-index')
-   *   .filter(op => 
+   *   .filter(op =>
    *     op.and([
    *       op.gt('securityLevel', 8),
    *       op.eq('status', 'OPERATIONAL')
    *     ])
    *   );
    * ```
-   * 
+   *
    * @param indexName - The name of the GSI to use (type-safe based on table configuration)
    * @returns The builder instance for method chaining
    */
@@ -475,33 +437,33 @@ var QueryBuilder = class _QueryBuilder {
     return 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
    * - Track immediate habitat changes
    * - Verify containment protocols
-   * 
+   *
    * Note:
    * - Consistent reads are not available on GSIs
    * - Consistent reads consume twice the throughput
    * - 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();
    * ```
-   * 
+   *
    * @param consistentRead - Whether to use consistent reads (defaults to true)
    * @returns The builder instance for method chaining
    */
@@ -510,54 +472,26 @@ var QueryBuilder = class _QueryBuilder {
     return this;
   }
   /**
-   * 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
-   */
-  /**
-   * 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
    * - Search for security incidents
    * - Monitor feeding patterns
-   * 
+   *
    * @example
    * ```typescript
    * // Find aggressive carnivores
-   * builder.filter(op => 
+   * builder.filter(op =>
    *   op.and([
    *     op.eq('diet', 'CARNIVORE'),
    *     op.gt('aggressionLevel', 7),
    *     op.eq('status', 'ACTIVE')
    *   ])
    * );
-   * 
+   *
    * // Search suitable breeding habitats
-   * builder.filter(op => 
+   * builder.filter(op =>
    *   op.and([
    *     op.between('temperature', 25, 30),
    *     op.lt('currentOccupants', 3),
@@ -565,7 +499,7 @@ var QueryBuilder = class _QueryBuilder {
    *   ])
    * );
    * ```
-   * 
+   *
    * @param condition - Either a Condition object or a callback function that builds the condition
    * @returns The builder instance for method chaining
    */
@@ -594,40 +528,13 @@ var QueryBuilder = class _QueryBuilder {
     return this;
   }
   /**
-   * 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
-   */
-  /**
-   * 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
    * - Monitor security metrics
    * - Optimize response size
-   * 
+   *
    * @example
    * ```typescript
    * // Get basic dinosaur info
@@ -637,7 +544,7 @@ var QueryBuilder = class _QueryBuilder {
    *   'stats.health',
    *   'stats.aggressionLevel'
    * ]);
-   * 
+   *
    * // Monitor habitat conditions
    * builder
    *   .select('securityStatus')
@@ -647,7 +554,7 @@ var QueryBuilder = class _QueryBuilder {
    *     'lastInspectionDate'
    *   ]);
    * ```
-   * 
+   *
    * @param fields - A single field name or an array of field names to return
    * @returns The builder instance for method chaining
    */
@@ -663,11 +570,86 @@ var QueryBuilder = class _QueryBuilder {
     return this;
   }
   /**
-   * Sets the query to return items in ascending order by sort key.
+   * Creates a paginator that handles DynamoDB pagination automatically.
+   * The paginator handles:
+   * - Tracking the last evaluated key
+   * - Managing page boundaries
+   * - Respecting overall query limits
+   *
+   * @example
+   * ```typescript
+   * // Create a paginator for dinosaur records
+   * const paginator = builder
+   *   .filter(op => op.eq('status', 'ACTIVE'))
+   *   .paginate(10);
+   *
+   * // Process pages of dinosaur results
+   * while (paginator.hasNextPage()) {
+   *   const page = await paginator.getNextPage();
+   *   console.log(`Processing page ${page.page}, count: ${page.items.length}`);
+   *   // Process dinosaur data
+   * }
+   * ```
+   *
+   * @param pageSize - The number of items to return per page
+   * @returns A Paginator instance that manages the pagination state
+   * @see Paginator for more pagination control options
+   */
+  paginate(pageSize) {
+    return new Paginator(this, pageSize);
+  }
+  /**
+   * Sets the starting point using a previous lastEvaluatedKey.
    * Use this method when you need to:
-   * - Retrieve items in natural order (e.g., timestamps, versions)
-   * - Implement chronological ordering
-   * - Get oldest items first
+   * - 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
+   * // First batch of dinosaurs
+   * const result1 = await builder
+   *   .filter(op => op.eq('status', 'ACTIVE'))
+   *   .limit(5)
+   *   .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
+   */
+  startFrom(lastEvaluatedKey) {
+    this.options.lastEvaluatedKey = lastEvaluatedKey;
+    return this;
+  }
+};
+
+// src/builders/query-builder.ts
+var QueryBuilder = class _QueryBuilder extends FilterBuilder {
+  keyCondition;
+  options = {};
+  executor;
+  constructor(executor, keyCondition) {
+    super();
+    this.executor = executor;
+    this.keyCondition = keyCondition;
+  }
+  /**
+   * Sets the maximum number of items to return from the query.
    *
    * Note: This is the default behavior if no sort order is specified.
    *
@@ -689,12 +671,7 @@ var QueryBuilder = class _QueryBuilder {
    */
   /**
    * Sets the query to return items in ascending order by sort key.
-   * Use this method when you need to:
-   * - List dinosaurs by age (youngest first)
-   * - View incidents chronologically
-   * - Track feeding schedule progression
-   * - Monitor habitat inspections
-   * 
+   *
    * @example
    * ```typescript
    * // List dinosaurs by age
@@ -702,14 +679,14 @@ var QueryBuilder = class _QueryBuilder {
    *   .useIndex('age-index')
    *   .sortAscending()
    *   .execute();
-   * 
+   *
    * // View incidents chronologically
    * const result = await new QueryBuilder(executor, eq('type', 'SECURITY_BREACH'))
    *   .useIndex('date-index')
    *   .sortAscending()
    *   .execute();
    * ```
-   * 
+   *
    * @returns The builder instance for method chaining
    */
   sortAscending() {
@@ -718,11 +695,6 @@ var QueryBuilder = class _QueryBuilder {
   }
   /**
    * Sets the query to return items in descending order by sort key.
-   * Use this method when you need to:
-   * - Get most recent security breaches
-   * - Find oldest dinosaurs first
-   * - Check latest habitat modifications
-   * - Monitor recent feeding events
    *
    * @example
    * ```typescript
@@ -732,7 +704,7 @@ var QueryBuilder = class _QueryBuilder {
    *   .sortDescending()
    *   .limit(10)
    *   .execute();
-   * 
+   *
    * // Check latest dinosaur activities
    * const result = await new QueryBuilder(executor, eq('species', 'Velociraptor'))
    *   .useIndex('activity-time-index')
@@ -747,121 +719,37 @@ var QueryBuilder = class _QueryBuilder {
     this.options.scanIndexForward = false;
     return this;
   }
-  /**
-   * 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
-   * 
-   * The paginator handles:
-   * - Tracking the last evaluated key
-   * - Managing page boundaries
-   * - Respecting overall query limits
-   * 
-   * @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);
-   * 
-   * while (paginator.hasNextPage()) {
-   *   const page = await paginator.getNextPage();
-   *   console.log(`Processing incidents page ${page.page}, count: ${page.items.length}`);
-   *   // Handle security incidents
-   * }
-   * ```
-   * 
-   * @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) {
-    return new Paginator(this, pageSize);
-  }
-  /**
-   * 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.
-   * 
-   * @example
-   * ```typescript
-   * // First batch of dinosaurs
-   * const result1 = await new QueryBuilder(executor, eq('species', 'Velociraptor'))
-   *   .filter(op => op.eq('status', 'ACTIVE'))
-   *   .limit(5)
-   *   .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();
-   * 
-   *   console.log('Additional dinosaurs:', result2.items);
-   * }
-   * ```
-   * 
-   * @param lastEvaluatedKey - The exclusive start key from a previous query result
-   * @returns The builder instance for method chaining
-   */
-  startFrom(lastEvaluatedKey) {
-    this.options.lastEvaluatedKey = lastEvaluatedKey;
-    return this;
-  }
   /**
    * 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())
    * - Creating query templates
    * - Running multiple variations of a query
-   * 
+   *
    * @example
    * ```typescript
    * // Create base dinosaur query
    * const baseQuery = new QueryBuilder(executor, eq('species', 'Velociraptor'))
    *   .useIndex('status-index')
    *   .select(['id', 'status', 'location']);
-   * 
+   *
    * // Check active dinosaurs
    * const activeRaptors = baseQuery.clone()
    *   .filter(op => op.eq('status', 'HUNTING'))
    *   .execute();
-   * 
+   *
    * // Check contained dinosaurs
    * const containedRaptors = baseQuery.clone()
    *   .filter(op => op.eq('status', 'CONTAINED'))
    *   .execute();
-   * 
+   *
    * // Check sedated dinosaurs
    * const sedatedRaptors = baseQuery.clone()
    *   .filter(op => op.eq('status', 'SEDATED'))
    *   .execute();
    * ```
-   * 
+   *
    * @returns A new QueryBuilder instance with the same configuration
    */
   clone() {
@@ -872,22 +760,17 @@ var QueryBuilder = class _QueryBuilder {
   }
   /**
    * 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.
-   * 
+   *
    * @example
    * ```typescript
    * try {
    *   // Find active carnivores in specific habitat
    *   const result = await new QueryBuilder(executor, eq('habitatId', 'PADDOCK-A'))
    *     .useIndex('species-status-index')
-   *     .filter(op => 
+   *     .filter(op =>
    *       op.and([
    *         op.eq('diet', 'CARNIVORE'),
    *         op.eq('status', 'ACTIVE'),
@@ -897,9 +780,9 @@ var QueryBuilder = class _QueryBuilder {
    *     .sortDescending()
    *     .limit(5)
    *     .execute();
-   * 
+   *
    *   console.log(`Found ${result.items.length} dangerous dinosaurs`);
-   * 
+   *
    *   if (result.lastEvaluatedKey) {
    *     console.log('Additional threats detected');
    *   }
@@ -907,7 +790,7 @@ var QueryBuilder = class _QueryBuilder {
    *   console.error('Security scan failed:', error);
    * }
    * ```
-   * 
+   *
    * @returns A promise that resolves to an object containing:
    *          - items: Array of items matching the query
    *          - lastEvaluatedKey: Token for continuing the query, if more items exist
@@ -967,13 +850,16 @@ function debugCommand(command) {
 // src/builders/put-builder.ts
 var PutBuilder = class {
   item;
-  options = {};
+  options;
   executor;
   tableName;
   constructor(executor, item, tableName) {
     this.executor = executor;
     this.item = item;
     this.tableName = tableName;
+    this.options = {
+      returnValues: "NONE"
+    };
   }
   /**
    * Adds a condition that must be satisfied for the put operation to succeed.
@@ -1002,10 +888,6 @@ var PutBuilder = class {
    */
   /**
    * Adds a condition that must be satisfied for the put operation to succeed.
-   * Use this method when you need to:
-   * - Prevent duplicate dinosaur entries
-   * - Ensure habitat requirements
-   * - Validate security protocols
    *
    * @example
    * ```typescript
@@ -1062,10 +944,11 @@ var PutBuilder = class {
   }
   /**
    * 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
+   *
+   * @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
@@ -1086,7 +969,7 @@ var PutBuilder = class {
    * }
    * ```
    *
-   * @param returnValues - Use 'ALL_OLD' to return previous values, or 'NONE' (default)
+   * @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) {
@@ -1174,11 +1057,6 @@ var PutBuilder = class {
   /**
    * 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 dinosaur transfers
-   * - Verify habitat assignments
-   * - Log security protocols
-   * - Troubleshoot breeding program conditions
    *
    * @example
    * ```ts
@@ -1447,20 +1325,20 @@ var UpdateBuilder = class {
    * - Delete attributes completely
    * - Remove nested attributes
    * - Clean up deprecated fields
-   * 
+   *
    * @example
    * ```typescript
    * // Remove simple attributes
    * builder
    *   .remove('temporaryTag')
    *   .remove('previousLocation');
-   * 
+   *
    * // Remove nested attributes
    * builder
    *   .remove('metadata.testData')
    *   .remove('stats.experimentalMetrics');
    * ```
-   * 
+   *
    * @param path - The path to the attribute to remove
    * @returns The builder instance for method chaining
    */
@@ -1477,20 +1355,20 @@ var UpdateBuilder = class {
    * - Increment counters
    * - Add elements to a set atomically
    * - Update numerical statistics
-   * 
+   *
    * @example
    * ```typescript
    * // Increment counters
    * builder
    *   .add('escapeAttempts', 1)
    *   .add('feedingCount', 1);
-   * 
+   *
    * // Add to sets
    * builder
    *   .add('knownBehaviors', new Set(['PACK_HUNTING', 'AMBUSH_TACTICS']))
    *   .add('visitedZones', new Set(['ZONE_A', 'ZONE_B']));
    * ```
-   * 
+   *
    * @param path - The path to the attribute to update
    * @param value - The value to add (number or set)
    * @returns The builder instance for method chaining
@@ -1509,7 +1387,7 @@ var UpdateBuilder = class {
    * - Remove specific elements from a set
    * - Update set-based attributes atomically
    * - Maintain set membership
-   * 
+   *
    * @example
    * ```typescript
    * // Remove from sets using arrays
@@ -1517,20 +1395,20 @@ var UpdateBuilder = class {
    *   'allowedHabitats',
    *   ['JUNGLE', 'COASTAL']
    * );
-   * 
+   *
    * // Remove from sets using Set objects
    * builder.deleteElementsFromSet(
    *   'knownBehaviors',
    *   new Set(['NOCTURNAL', 'TERRITORIAL'])
    * );
-   * 
+   *
    * // Remove from nested sets
    * builder.deleteElementsFromSet(
    *   'stats.compatibleSpecies',
    *   ['VELOCIRAPTOR', 'DILOPHOSAURUS']
    * );
    * ```
-   * 
+   *
    * @param path - The path to the set attribute
    * @param value - Elements to remove (array or Set)
    * @returns The builder instance for method chaining
@@ -1556,37 +1434,37 @@ var UpdateBuilder = class {
    * - Ensure item state before update
    * - Validate business rules
    * - Prevent concurrent modifications
-   * 
+   *
    * @example
    * ```typescript
    * // Simple condition
-   * builder.condition(op => 
+   * builder.condition(op =>
    *   op.eq('status', 'ACTIVE')
    * );
-   * 
+   *
    * // Health check condition
-   * builder.condition(op => 
+   * builder.condition(op =>
    *   op.and([
    *     op.gt('health', 50),
    *     op.eq('status', 'HUNTING')
    *   ])
    * );
-   * 
+   *
    * // Complex security condition
-   * builder.condition(op => 
+   * builder.condition(op =>
    *   op.and([
    *     op.attributeExists('securitySystem'),
    *     op.eq('containmentStatus', 'SECURE'),
    *     op.lt('aggressionLevel', 8)
    *   ])
    * );
-   * 
+   *
    * // Version check (optimistic locking)
-   * builder.condition(op => 
+   * builder.condition(op =>
    *   op.eq('version', currentVersion)
    * );
    * ```
-   * 
+   *
    * @param condition - Either a Condition object or a callback function that builds the condition
    * @returns The builder instance for method chaining
    */
@@ -1621,14 +1499,14 @@ var UpdateBuilder = class {
    * - Track changes to specific attributes
    * - Compare old and new values
    * - Monitor attribute modifications
-   * 
+   *
    * 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
    * // Get complete updated dinosaur
@@ -1636,7 +1514,7 @@ var UpdateBuilder = class {
    *   .set('status', 'SLEEPING')
    *   .returnValues('ALL_NEW')
    *   .execute();
-   * 
+   *
    * // Track specific attribute changes
    * const result = await builder
    *   .set({
@@ -1645,12 +1523,12 @@ var UpdateBuilder = class {
    *   })
    *   .returnValues('UPDATED_OLD')
    *   .execute();
-   * 
+   *
    * if (result.item) {
    *   console.log('Previous health:', result.item.stats?.health);
    * }
    * ```
-   * 
+   *
    * @param returnValues - Which attributes to return in the response
    * @returns The builder instance for method chaining
    */
@@ -1752,26 +1630,26 @@ var UpdateBuilder = class {
    * - Update items as part of a larger transaction
    * - Ensure multiple updates are atomic
    * - Coordinate updates across multiple items
-   * 
+   *
    * @example
    * ```typescript
    * const transaction = new TransactionBuilder(executor);
-   * 
+   *
    * // Update dinosaur status and habitat occupancy atomically
    * new UpdateBuilder(executor, 'dinosaurs', { id: 'TREX-001' })
    *   .set('location', 'PADDOCK_A')
    *   .set('status', 'CONTAINED')
    *   .withTransaction(transaction);
-   * 
+   *
    * new UpdateBuilder(executor, 'habitats', { id: 'PADDOCK-A' })
    *   .add('occupants', 1)
    *   .set('lastOccupied', new Date().toISOString())
    *   .withTransaction(transaction);
-   * 
+   *
    * // Execute all operations atomically
    * await transaction.execute();
    * ```
-   * 
+   *
    * @param transaction - The transaction builder to add this operation to
    * @returns The builder instance for method chaining
    */
@@ -1786,7 +1664,7 @@ var UpdateBuilder = class {
    * - Verify attribute names and values
    * - Log update operations
    * - Troubleshoot condition expressions
-   * 
+   *
    * @example
    * ```typescript
    * // Create complex update
@@ -1798,12 +1676,12 @@ var UpdateBuilder = class {
    *   })
    *   .add('huntingSuccesses', 1)
    *   .condition(op => op.gt('health', 50));
-   * 
+   *
    * // Debug the update
    * const debugInfo = builder.debug();
    * console.log('Update operation:', debugInfo);
    * ```
-   * 
+   *
    * @returns A readable representation of the update command with resolved expressions
    */
   debug() {
@@ -1816,7 +1694,7 @@ var UpdateBuilder = class {
    * - Apply updates immediately
    * - Get the updated item values
    * - Handle conditional update failures
-   * 
+   *
    * @example
    * ```typescript
    * try {
@@ -1828,7 +1706,7 @@ var UpdateBuilder = class {
    *       'stats.hunger': 0
    *     })
    *     .add('feedingCount', 1)
-   *     .condition(op => 
+   *     .condition(op =>
    *       op.and([
    *         op.gt('stats.hunger', 80),
    *         op.eq('status', 'HUNTING')
@@ -1836,7 +1714,7 @@ var UpdateBuilder = class {
    *     )
    *     .returnValues('ALL_NEW')
    *     .execute();
-   * 
+   *
    *   if (result.item) {
    *     console.log('Updated dinosaur:', result.item);
    *   }
@@ -1849,7 +1727,7 @@ var UpdateBuilder = class {
    *   }
    * }
    * ```
-   * 
+   *
    * @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
@@ -1951,10 +1829,10 @@ var TransactionBuilder = class {
    * - 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
    * // Simple put operation
@@ -1963,14 +1841,14 @@ var TransactionBuilder = class {
    *   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',
@@ -1981,7 +1859,7 @@ var TransactionBuilder = class {
    *   ])
    * );
    * ```
-   * 
+   *
    * @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
@@ -2012,21 +1890,21 @@ var TransactionBuilder = class {
    * - 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
@@ -2047,10 +1925,10 @@ var TransactionBuilder = class {
    * - 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
    * // Simple delete operation
@@ -2058,14 +1936,14 @@ var TransactionBuilder = class {
    *   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',
@@ -2076,7 +1954,7 @@ var TransactionBuilder = class {
    *   ])
    * );
    * ```
-   * 
+   *
    * @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
@@ -2110,10 +1988,10 @@ var TransactionBuilder = class {
    * - 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
    * // Create a delete command with DeleteBuilder
@@ -2123,11 +2001,11 @@ var TransactionBuilder = class {
    *     op.eq('status', 'INACTIVE')
    *   ]))
    *   .toDynamoCommand();
-   * 
+   *
    * // Add the command to the transaction
    * transaction.deleteWithCommand(deleteCommand);
    * ```
-   * 
+   *
    * @param command - The complete delete command configuration
    * @returns The transaction builder for method chaining
    * @throws {Error} If a duplicate item is detected in the transaction
@@ -2149,13 +2027,13 @@ var TransactionBuilder = class {
    * - 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
    * // Simple update
@@ -2166,7 +2044,7 @@ var TransactionBuilder = class {
    *   { '#status': 'status' },
    *   { ':status': 'PROCESSING' }
    * );
-   * 
+   *
    * // Complex update with multiple operations
    * transaction.update(
    *   'products',
@@ -2175,7 +2053,7 @@ var TransactionBuilder = class {
    *   { '#qty': 'quantity', '#status': 'status', '#oldAttr': 'deprecated_field' },
    *   { ':amount': 1, ':status': 'LOW_STOCK' }
    * );
-   * 
+   *
    * // Conditional update
    * transaction.update(
    *   'users',
@@ -2186,7 +2064,7 @@ var TransactionBuilder = class {
    *   op => op.attributeExists('pk')
    * );
    * ```
-   * 
+   *
    * @param tableName - The name of the DynamoDB table
    * @param key - The primary key of the item to update
    * @param updateExpression - The update expression (SET, REMOVE, ADD, DELETE)
@@ -2232,10 +2110,10 @@ var TransactionBuilder = class {
    * - 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
    * // Create an update command with UpdateBuilder
@@ -2248,11 +2126,11 @@ var TransactionBuilder = class {
    *   })
    *   .condition(op => op.gt('quantity', 0))
    *   .toDynamoCommand();
-   * 
+   *
    * // Add the command to the transaction
    * transaction.updateWithCommand(updateCommand);
    * ```
-   * 
+   *
    * @param command - The complete update command configuration
    * @returns The transaction builder for method chaining
    * @throws {Error} If a duplicate item is detected in the transaction
@@ -2274,12 +2152,12 @@ var TransactionBuilder = class {
    * - 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
@@ -2288,7 +2166,7 @@ var TransactionBuilder = class {
    *   { pk: 'ORDER#123' },
    *   op => op.eq('status', 'PENDING')
    * );
-   * 
+   *
    * // Complex condition check
    * transaction.conditionCheck(
    *   'inventory',
@@ -2299,7 +2177,7 @@ var TransactionBuilder = class {
    *     op.attributeExists('lastRestockDate')
    *   ])
    * );
-   * 
+   *
    * // Check with multiple attributes
    * transaction.conditionCheck(
    *   'users',
@@ -2310,7 +2188,7 @@ var TransactionBuilder = class {
    *   ])
    * );
    * ```
-   * 
+   *
    * @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
@@ -2346,10 +2224,10 @@ var TransactionBuilder = class {
    * - Reuse condition checks from ConditionCheckBuilder
    * - Add complex condition checks with pre-configured parameters
    * - Integrate with existing condition check configurations
-   * 
+   *
    * This method is particularly useful when working with ConditionCheckBuilder
    * to maintain consistency in condition checks across your application.
-   * 
+   *
    * @example
    * ```typescript
    * // Create a condition check with ConditionCheckBuilder
@@ -2360,11 +2238,11 @@ var TransactionBuilder = class {
    *     op.attributeExists('lastAuditDate')
    *   ]))
    *   .toDynamoCommand();
-   * 
+   *
    * // Add the command to the transaction
    * transaction.conditionCheckWithCommand(checkCommand);
    * ```
-   * 
+   *
    * @param command - The complete condition check command configuration
    * @returns The transaction builder for method chaining
    * @throws {Error} If a duplicate item is detected in the transaction
@@ -2385,7 +2263,7 @@ var TransactionBuilder = class {
    * - Enable idempotent transactions
    * - Track consumed capacity
    * - Monitor item collection metrics
-   * 
+   *
    * @example
    * ```typescript
    * // Enable idempotency and capacity tracking
@@ -2393,16 +2271,16 @@ var TransactionBuilder = class {
    *   clientRequestToken: 'unique-request-id-123',
    *   returnConsumedCapacity: 'TOTAL'
    * });
-   * 
+   *
    * // Track item collection metrics
    * transaction.withOptions({
    *   returnItemCollectionMetrics: 'SIZE'
    * });
    * ```
-   * 
+   *
    * Note: ClientRequestToken can be used to make transactions idempotent,
    * ensuring the same transaction is not executed multiple times.
-   * 
+   *
    * @param options - Configuration options for the transaction
    * @returns The transaction builder for method chaining
    */
@@ -2417,27 +2295,27 @@ var TransactionBuilder = class {
    * - 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
    * // Add multiple operations
    * transaction
    *   .put('orders', { orderId: '123', status: 'PENDING' })
-   *   .update('inventory', 
+   *   .update('inventory',
    *     { productId: 'ABC' },
    *     'SET quantity = quantity - :amount',
    *     undefined,
    *     { ':amount': 1 }
    *   );
-   * 
+   *
    * // Debug the transaction
    * const debugInfo = transaction.debug();
    * console.log('Transaction operations:', debugInfo);
    * ```
-   * 
+   *
    * @returns An array of readable representations of the transaction items
    */
   debug() {
@@ -2449,17 +2327,17 @@ var TransactionBuilder = class {
    * - 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 {
    *   // Build and execute transaction
    *   await transaction
    *     .put('orders', newOrder)
-   *     .update('inventory', 
+   *     .update('inventory',
    *       { productId: 'ABC' },
    *       'SET quantity = quantity - :qty',
    *       undefined,
@@ -2470,14 +2348,14 @@ var TransactionBuilder = class {
    *       op => op.eq('status', 'ACTIVE')
    *     )
    *     .execute();
-   *     
+   *
    *   console.log('Transaction completed successfully');
    * } catch (error) {
    *   // Handle transaction failure
    *   console.error('Transaction failed:', error);
    * }
    * ```
-   * 
+   *
    * @throws {Error} If no transaction items are specified
    * @throws {Error} If any operation in the transaction fails
    * @returns A promise that resolves when the transaction completes
@@ -2576,29 +2454,29 @@ var ConditionCheckBuilder = class {
    * - Validate complex item states
    * - Check multiple attributes together
    * - Ensure safety conditions are met
-   * 
+   *
    * @example
    * ```typescript
    * // Check dinosaur health and behavior
-   * builder.condition(op => 
+   * builder.condition(op =>
    *   op.and([
    *     op.gt('stats.health', 50),
    *     op.not(op.eq('status', 'SEDATED')),
    *     op.lt('aggressionLevel', 8)
    *   ])
    * );
-   * 
+   *
    * // Verify habitat conditions
-   * builder.condition(op => 
+   * builder.condition(op =>
    *   op.and([
    *     op.eq('powerStatus', 'ONLINE'),
    *     op.between('temperature', 20, 30),
    *     op.attributeExists('lastMaintenance')
    *   ])
    * );
-   * 
+   *
    * // Check breeding conditions
-   * builder.condition(op => 
+   * builder.condition(op =>
    *   op.and([
    *     op.eq('species', 'VELOCIRAPTOR'),
    *     op.gte('age', 3),
@@ -2606,7 +2484,7 @@ var ConditionCheckBuilder = class {
    *   ])
    * );
    * ```
-   * 
+   *
    * @param condition - Either a Condition object or a callback function that builds the condition
    * @returns The builder instance for method chaining
    */
@@ -2848,14 +2726,89 @@ var GetBuilder = class {
   }
 };
 
+// src/builders/scan-builder.ts
+var ScanBuilder = class _ScanBuilder extends FilterBuilder {
+  executor;
+  constructor(executor) {
+    super();
+    this.executor = executor;
+  }
+  /**
+   * 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() {
+    const clone = new _ScanBuilder(this.executor);
+    clone.options = { ...this.options };
+    clone.selectedFields = new Set(this.selectedFields);
+    return clone;
+  }
+  /**
+   * 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
+   */
+  async execute() {
+    return this.executor(this.options);
+  }
+};
+
 // src/table.ts
 var DDB_BATCH_WRITE_LIMIT = 25;
 var DDB_BATCH_GET_LIMIT = 100;
 var Table = class {
   dynamoClient;
   tableName;
+  /**
+   * The column name of the partitionKey for the Table
+   */
   partitionKey;
+  /**
+   * The column name of the sortKey for the Table
+   */
   sortKey;
+  /**
+   * The Global Secondary Indexes that are configured on this table
+   */
   gsis;
   constructor(config) {
     this.dynamoClient = config.client;
@@ -2902,15 +2855,29 @@ var Table = class {
   put(item) {
     const executor = async (params) => {
       try {
-        await this.dynamoClient.put({
+        const result = await this.dynamoClient.put({
           TableName: params.tableName,
           Item: params.item,
           ConditionExpression: params.conditionExpression,
           ExpressionAttributeNames: params.expressionAttributeNames,
           ExpressionAttributeValues: params.expressionAttributeValues,
-          ReturnValues: params.returnValues
+          // CONSISTENT is not a valid ReturnValue for DDB, so we set NONE as we are not interested in its
+          // response and will be reloading the item from the DB through a get instead
+          ReturnValues: params.returnValues === "CONSISTENT" ? "NONE" : params.returnValues
         });
-        return params.item;
+        if (params.returnValues === "CONSISTENT") {
+          const key = {
+            pk: params.item[this.partitionKey],
+            ...this.sortKey && { sk: params.item[this.sortKey] }
+          };
+          const getResult = await this.dynamoClient.get({
+            TableName: params.tableName,
+            Key: key,
+            ConsistentRead: true
+          });
+          return getResult.Item;
+        }
+        return result.Attributes;
       } catch (error) {
         console.error("Error creating item:", error);
         throw error;
@@ -3036,6 +3003,54 @@ var Table = class {
     };
     return new QueryBuilder(executor, keyConditionExpression);
   }
+  /**
+   * 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() {
+    const executor = async (options) => {
+      const expressionParams = {
+        expressionAttributeNames: {},
+        expressionAttributeValues: {},
+        valueCounter: { count: 0 }
+      };
+      let filterExpression;
+      if (options.filter) {
+        filterExpression = buildExpression(options.filter, expressionParams);
+      }
+      const projectionExpression = options.projection?.map((p) => generateAttributeName(expressionParams, p)).join(", ");
+      const { expressionAttributeNames, expressionAttributeValues } = expressionParams;
+      const { indexName, limit, consistentRead, lastEvaluatedKey } = options;
+      const params = {
+        TableName: this.tableName,
+        FilterExpression: filterExpression,
+        ExpressionAttributeNames: Object.keys(expressionAttributeNames).length > 0 ? expressionAttributeNames : void 0,
+        ExpressionAttributeValues: Object.keys(expressionAttributeValues).length > 0 ? expressionAttributeValues : void 0,
+        IndexName: indexName,
+        Limit: limit,
+        ConsistentRead: consistentRead,
+        ProjectionExpression: projectionExpression,
+        ExclusiveStartKey: lastEvaluatedKey
+      };
+      try {
+        const result = await this.dynamoClient.scan(params);
+        return {
+          items: result.Items,
+          lastEvaluatedKey: result.LastEvaluatedKey
+        };
+      } catch (error) {
+        console.log(debugCommand(params));
+        console.error("Error scanning items:", error);
+        throw error;
+      }
+    };
+    return new ScanBuilder(executor);
+  }
   delete(keyCondition) {
     const executor = async (params) => {
       try {
@@ -3257,6 +3272,7 @@ export {
   beginsWith,
   between,
   contains,
+  createComparisonCondition,
   eq,
   gt,
   gte,