dyno-table 0.1.7 → 0.2.0-0

package/dist/{index.js → table.cjs}

@@ -1,3 +1,5 @@
+'use strict';
+
 // src/conditions.ts
 var createComparisonCondition = (type) => (attr, value) => ({
   type,
@@ -365,30 +367,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 +397,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,41 +406,9 @@ 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
@@ -475,7 +439,7 @@ 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
@@ -488,15 +452,15 @@ var QueryBuilder = class _QueryBuilder {
    * - 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();
@@ -510,35 +474,7 @@ 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
@@ -594,34 +530,7 @@ 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
@@ -663,11 +572,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,11 +673,6 @@ 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
@@ -718,11 +697,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
@@ -747,92 +721,8 @@ 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())
@@ -872,11 +762,6 @@ 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.
@@ -967,13 +852,24 @@ 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"
+    };
+  }
+  set(valuesOrPath, value) {
+    if (typeof valuesOrPath === "object") {
+      Object.assign(this.item, valuesOrPath);
+    } else {
+      this.item[valuesOrPath] = value;
+    }
+    return this;
   }
   /**
    * Adds a condition that must be satisfied for the put operation to succeed.
@@ -1002,10 +898,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 +954,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 +979,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 +1067,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
@@ -1227,10 +1115,6 @@ var DeleteBuilder = class {
   }
   /**
    * Adds a condition that must be satisfied for the delete operation to succeed.
-   * Use this method when you need to:
-   * - Ensure safe removal conditions
-   * - Verify habitat status before deletion
-   * - Implement safety protocols
    *
    * @example
    * ```typescript
@@ -1282,10 +1166,6 @@ var DeleteBuilder = class {
   }
   /**
    * 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
@@ -1326,10 +1206,6 @@ var DeleteBuilder = class {
   }
   /**
    * Adds this delete operation to a transaction.
-   * Use this method when you need to:
-   * - Coordinate dinosaur transfers
-   * - Manage habitat decommissioning
-   * - Handle species relocations
    *
    * @example
    * ```ts
@@ -1380,11 +1256,6 @@ var DeleteBuilder = class {
   /**
    * 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
@@ -1443,10 +1314,6 @@ var UpdateBuilder = class {
   }
   /**
    * Removes an attribute from the item.
-   * Use this method when you need to:
-   * - Delete attributes completely
-   * - Remove nested attributes
-   * - Clean up deprecated fields
    *
    * @example
    * ```typescript
@@ -1473,10 +1340,6 @@ var UpdateBuilder = class {
   }
   /**
    * Adds a value to a number attribute or adds elements to a set.
-   * Use this method when you need to:
-   * - Increment counters
-   * - Add elements to a set atomically
-   * - Update numerical statistics
    *
    * @example
    * ```typescript
@@ -1505,10 +1368,6 @@ var UpdateBuilder = class {
   }
   /**
    * Removes elements from a set attribute.
-   * Use this method when you need to:
-   * - Remove specific elements from a set
-   * - Update set-based attributes atomically
-   * - Maintain set membership
    *
    * @example
    * ```typescript
@@ -1518,7 +1377,7 @@ var UpdateBuilder = class {
    *   ['JUNGLE', 'COASTAL']
    * );
    *
-   * // Remove from sets using Set objects
+   * // Remove from sets using Set DynamoItems
    * builder.deleteElementsFromSet(
    *   'knownBehaviors',
    *   new Set(['NOCTURNAL', 'TERRITORIAL'])
@@ -1551,11 +1410,6 @@ var UpdateBuilder = class {
   }
   /**
    * Adds a condition that must be satisfied for the update to succeed.
-   * Use this method when you need to:
-   * - Implement optimistic locking
-   * - Ensure item state before update
-   * - Validate business rules
-   * - Prevent concurrent modifications
    *
    * @example
    * ```typescript
@@ -1587,7 +1441,7 @@ var UpdateBuilder = class {
    * );
    * ```
    *
-   * @param condition - Either a Condition object or a callback function that builds the condition
+   * @param condition - Either a Condition DynamoItem or a callback function that builds the condition
    * @returns The builder instance for method chaining
    */
   condition(condition) {
@@ -1616,11 +1470,6 @@ var UpdateBuilder = class {
   }
   /**
    * Sets which item attributes to include in the response.
-   * 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
    *
    * Available options:
    * - ALL_NEW: All attributes after the update
@@ -1748,10 +1597,6 @@ var UpdateBuilder = class {
   }
   /**
    * Adds this update operation to a transaction.
-   * 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
    *
    * @example
    * ```typescript
@@ -1781,11 +1626,6 @@ var UpdateBuilder = class {
   }
   /**
    * Gets a human-readable representation of the update command.
-   * Use this method when you need to:
-   * - Debug complex update expressions
-   * - Verify attribute names and values
-   * - Log update operations
-   * - Troubleshoot condition expressions
    *
    * @example
    * ```typescript
@@ -1812,10 +1652,6 @@ var UpdateBuilder = class {
   }
   /**
    * Executes the update operation against DynamoDB.
-   * Use this method when you need to:
-   * - Apply updates immediately
-   * - Get the updated item values
-   * - Handle conditional update failures
    *
    * @example
    * ```typescript
@@ -1850,7 +1686,7 @@ var UpdateBuilder = class {
    * }
    * ```
    *
-   * @returns A promise that resolves to an object containing the updated item (if returnValues is set)
+   * @returns A promise that resolves to an DynamoItem containing the updated item (if returnValues is set)
    * @throws {ConditionalCheckFailedException} If the condition check fails
    * @throws {Error} If the update operation fails for other reasons
    */
@@ -1904,7 +1740,7 @@ var TransactionBuilder = class {
    */
   checkForDuplicateItem(tableName, newItem) {
     const pkName = this.indexConfig.partitionKey;
-    const skName = this.indexConfig.sortKey || "";
+    const skName = this.indexConfig.sortKey ?? "";
     const pkValue = newItem[pkName];
     const skValue = skName ? newItem[skName] : void 0;
     if (!pkValue) {
@@ -1945,6 +1781,18 @@ var TransactionBuilder = class {
       );
     }
   }
+  createKeyForPrimaryIndex(key) {
+    const keyCondition = {
+      [this.indexConfig.partitionKey]: key.pk
+    };
+    if (this.indexConfig.sortKey) {
+      if (key.sk === void 0) {
+        throw new Error("Sort key is required for delete operation");
+      }
+      keyCondition[this.indexConfig.sortKey] = key.sk;
+    }
+    return keyCondition;
+  }
   /**
    * Adds a put operation to the transaction.
    * Use this method when you need to:
@@ -2084,15 +1932,13 @@ var TransactionBuilder = class {
    * @throws {Error} If a duplicate item is detected in the transaction
    */
   delete(tableName, key, condition) {
-    this.checkForDuplicateItem(tableName, key);
+    const keyCondition = this.createKeyForPrimaryIndex(key);
+    this.checkForDuplicateItem(tableName, keyCondition);
     const transactionItem = {
       type: "Delete",
       params: {
         tableName,
-        key: {
-          pk: key.pk,
-          sk: key.sk
-        }
+        key: keyCondition
       }
     };
     if (condition) {
@@ -2134,10 +1980,14 @@ var TransactionBuilder = class {
    * @see DeleteBuilder for creating delete commands
    */
   deleteWithCommand(command) {
-    this.checkForDuplicateItem(command.tableName, command.key);
+    const keyCondition = this.createKeyForPrimaryIndex(command.key);
+    this.checkForDuplicateItem(command.tableName, keyCondition);
     const transactionItem = {
       type: "Delete",
-      params: command
+      params: {
+        ...command,
+        key: keyCondition
+      }
     };
     this.items.push(transactionItem);
     return this;
@@ -2197,15 +2047,13 @@ var TransactionBuilder = class {
    * @throws {Error} If a duplicate item is detected in the transaction
    */
   update(tableName, key, updateExpression, expressionAttributeNames, expressionAttributeValues, condition) {
-    this.checkForDuplicateItem(tableName, key);
+    const keyCondition = this.createKeyForPrimaryIndex(key);
+    this.checkForDuplicateItem(tableName, keyCondition);
     const transactionItem = {
       type: "Update",
       params: {
         tableName,
-        key: {
-          pk: key.pk,
-          sk: key.sk
-        },
+        key: keyCondition,
         updateExpression,
         expressionAttributeNames,
         expressionAttributeValues
@@ -2259,10 +2107,14 @@ var TransactionBuilder = class {
    * @see UpdateBuilder for creating update commands
    */
   updateWithCommand(command) {
-    this.checkForDuplicateItem(command.tableName, command.key);
+    const keyCondition = this.createKeyForPrimaryIndex(command.key);
+    this.checkForDuplicateItem(command.tableName, keyCondition);
     const transactionItem = {
       type: "Update",
-      params: command
+      params: {
+        ...command,
+        key: keyCondition
+      }
     };
     this.items.push(transactionItem);
     return this;
@@ -2319,7 +2171,8 @@ var TransactionBuilder = class {
    * @throws {Error} If condition expression generation fails
    */
   conditionCheck(tableName, key, condition) {
-    this.checkForDuplicateItem(tableName, key);
+    const keyCondition = this.createKeyForPrimaryIndex(key);
+    this.checkForDuplicateItem(tableName, keyCondition);
     const { expression, names, values } = prepareExpressionParams(condition);
     if (!expression) {
       throw new Error("Failed to generate condition expression");
@@ -2328,10 +2181,7 @@ var TransactionBuilder = class {
       type: "ConditionCheck",
       params: {
         tableName,
-        key: {
-          pk: key.pk,
-          sk: key.sk
-        },
+        key: keyCondition,
         conditionExpression: expression,
         expressionAttributeNames: names,
         expressionAttributeValues: values
@@ -2371,10 +2221,14 @@ var TransactionBuilder = class {
    * @see ConditionCheckBuilder for creating condition check commands
    */
   conditionCheckWithCommand(command) {
-    this.checkForDuplicateItem(command.tableName, command.key);
+    const keyCondition = this.createKeyForPrimaryIndex(command.key);
+    this.checkForDuplicateItem(command.tableName, keyCondition);
     const transactionItem = {
       type: "ConditionCheck",
-      params: command
+      params: {
+        ...command,
+        key: keyCondition
+      }
     };
     this.items.push(transactionItem);
     return this;
@@ -2607,7 +2461,7 @@ var ConditionCheckBuilder = class {
    * );
    * ```
    *
-   * @param condition - Either a Condition object or a callback function that builds the condition
+   * @param condition - Either a Condition DynamoItem or a callback function that builds the condition
    * @returns The builder instance for method chaining
    */
   condition(condition) {
@@ -2833,18 +2687,84 @@ var GetBuilder = class {
    *          - item: The retrieved dinosaur or undefined if not found
    */
   async execute() {
-    if (this.selectedFields.size > 0) {
-      const expressionAttributeNames = {};
-      const projectionParts = [];
-      for (const path of this.selectedFields) {
-        const attrName = `#attr${projectionParts.length}`;
-        expressionAttributeNames[attrName] = path;
-        projectionParts.push(attrName);
-      }
-      this.params.projectionExpression = projectionParts.join(", ");
-      this.params.expressionAttributeNames = expressionAttributeNames;
-    }
-    return this.executor(this.params);
+    const expressionParams = {
+      expressionAttributeNames: {},
+      expressionAttributeValues: {},
+      valueCounter: { count: 0 }
+    };
+    const projectionExpression = Array.from(this.selectedFields).map((p) => generateAttributeName(expressionParams, p)).join(", ");
+    const { expressionAttributeNames } = expressionParams;
+    return this.executor({
+      ...this.params,
+      projectionExpression: projectionExpression.length > 0 ? projectionExpression : void 0,
+      expressionAttributeNames: Object.keys(expressionAttributeNames).length > 0 ? expressionAttributeNames : void 0
+    });
+  }
+};
+
+// 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);
   }
 };
 
@@ -2854,8 +2774,17 @@ 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;
@@ -2864,6 +2793,16 @@ var Table = class {
     this.sortKey = config.indexes.sortKey;
     this.gsis = config.indexes.gsis || {};
   }
+  createKeyForPrimaryIndex(keyCondition) {
+    const primaryCondition = { [this.partitionKey]: keyCondition.pk };
+    if (this.sortKey) {
+      if (!keyCondition.sk) {
+        throw new Error("Sort key has not been provided but the Table has a sort key");
+      }
+      primaryCondition[this.sortKey] = keyCondition.sk;
+    }
+    return primaryCondition;
+  }
   /**
    * Creates a new item in the table, it will fail if the item already exists
    *
@@ -2878,7 +2817,7 @@ var Table = class {
       try {
         const result = await this.dynamoClient.get({
           TableName: params.tableName,
-          Key: params.key,
+          Key: this.createKeyForPrimaryIndex(keyCondition),
           ProjectionExpression: params.projectionExpression,
           ExpressionAttributeNames: params.expressionAttributeNames,
           ConsistentRead: params.consistentRead
@@ -2902,15 +2841,28 @@ 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 getResult = await this.dynamoClient.get({
+            TableName: params.tableName,
+            Key: this.createKeyForPrimaryIndex({
+              pk: params.item[this.partitionKey],
+              ...this.sortKey && { sk: params.item[this.sortKey] }
+            }),
+            ConsistentRead: true
+          });
+          return getResult.Item;
+        }
+        return result.Attributes;
       } catch (error) {
         console.error("Error creating item:", error);
         throw error;
@@ -3036,12 +2988,60 @@ 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 {
         const result = await this.dynamoClient.delete({
           TableName: params.tableName,
-          Key: params.key,
+          Key: this.createKeyForPrimaryIndex(keyCondition),
           ConditionExpression: params.conditionExpression,
           ExpressionAttributeNames: params.expressionAttributeNames,
           ExpressionAttributeValues: params.expressionAttributeValues,
@@ -3068,7 +3068,7 @@ var Table = class {
       try {
         const result = await this.dynamoClient.update({
           TableName: params.tableName,
-          Key: params.key,
+          Key: this.createKeyForPrimaryIndex(keyCondition),
           UpdateExpression: params.updateExpression,
           ConditionExpression: params.conditionExpression,
           ExpressionAttributeNames: params.expressionAttributeNames,
@@ -3196,10 +3196,7 @@ var Table = class {
         }
         return {
           DeleteRequest: {
-            Key: {
-              [this.partitionKey]: operation.key.pk,
-              ...this.sortKey ? { [this.sortKey]: operation.key.sk } : {}
-            }
+            Key: this.createKeyForPrimaryIndex(operation.key)
           }
         };
       });
@@ -3242,28 +3239,7 @@ var Table = class {
     };
   }
 };
-export {
-  ConditionCheckBuilder,
-  DeleteBuilder,
-  Paginator,
-  PutBuilder,
-  QueryBuilder,
-  Table,
-  TransactionBuilder,
-  UpdateBuilder,
-  and,
-  attributeExists,
-  attributeNotExists,
-  beginsWith,
-  between,
-  contains,
-  createComparisonCondition,
-  eq,
-  gt,
-  gte,
-  lt,
-  lte,
-  ne,
-  not,
-  or
-};
+
+exports.Table = Table;
+//# sourceMappingURL=table.cjs.map
+//# sourceMappingURL=table.cjs.map