dyno-table 0.1.7 → 0.1.8

package/dist/index.d.ts

@@ -375,7 +375,13 @@ interface DeleteCommandParams extends DynamoCommandWithExpressions {
 }
 /**
  * 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;
@@ -383,7 +389,7 @@ interface PutCommandParams extends DynamoCommandWithExpressions {
     conditionExpression?: string;
     expressionAttributeNames?: Record<string, string>;
     expressionAttributeValues?: Record<string, unknown>;
-    returnValues?: "ALL_OLD" | "NONE";
+    returnValues?: "ALL_OLD" | "NONE" | "CONSISTENT";
 }
 /**
  * Parameters for the DynamoDB update command.
@@ -413,19 +419,37 @@ interface ConditionCheckCommandParams extends DynamoCommandWithExpressions {
     expressionAttributeValues?: Record<string, unknown>;
 }
 /**
- * Interface for the QueryBuilder class to be used by Paginator
- * without creating a circular dependency.
+ * Base interface for all builder classes that support pagination
+ * to be used by Paginator without creating circular dependencies.
  */
-interface QueryBuilderInterface<T extends Record<string, unknown>, TConfig extends TableConfig = TableConfig> {
-    clone(): QueryBuilderInterface<T, TConfig>;
-    limit(limit: number): QueryBuilderInterface<T, TConfig>;
+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>): QueryBuilderInterface<T, TConfig>;
+    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
@@ -617,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> implements QueryBuilderInterface<T, TConfig> {
-    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();
      * ```
@@ -758,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
@@ -827,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
@@ -842,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();
@@ -859,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
@@ -920,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
@@ -979,13 +830,177 @@ 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.
+     * 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: number): Paginator<T, TConfig>;
+    /**
+     * Sets the starting point 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 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: Record<string, unknown>): this;
+    /**
+     * Creates a deep clone of this builder instance.
      * Use this method when you need to:
-     * - Retrieve items in natural order (e.g., timestamps, versions)
-     * - Implement chronological ordering
-     * - Get oldest items first
+     * - 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
+     * // Create base dinosaur query
+     * const baseBuilder = builder
+     *   .useIndex('status-index')
+     *   .select(['id', 'status', 'location']);
+     *
+     * // Check active dinosaurs
+     * const activeRaptors = baseBuilder.clone()
+     *   .filter(op => op.eq('status', 'HUNTING'))
+     *   .execute();
+     *
+     * // Check contained dinosaurs
+     * const containedRaptors = baseBuilder.clone()
+     *   .filter(op => op.eq('status', 'CONTAINED'))
+     *   .execute();
+     * ```
+     *
+     * @returns A new builder instance with the same configuration
+     */
+    abstract clone(): FilterBuilderInterface<T, TConfig>;
+    /**
+     * Executes the operation against DynamoDB.
+     * 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.
      *
      * Note: This is the default behavior if no sort order is specified.
      *
@@ -1007,11 +1022,6 @@ declare class QueryBuilder<T extends Record<string, unknown>, TConfig extends Ta
      */
     /**
      * 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
@@ -1033,11 +1043,6 @@ declare class QueryBuilder<T extends Record<string, unknown>, TConfig extends Ta
     sortAscending(): QueryBuilder<T>;
     /**
      * 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
@@ -1059,87 +1064,8 @@ declare class QueryBuilder<T extends Record<string, unknown>, TConfig extends Ta
      * @returns The builder instance for method chaining
      */
     sortDescending(): QueryBuilder<T>;
-    /**
-     * 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: 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.
-     *
-     * @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: Record<string, unknown>): 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())
@@ -1174,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.
@@ -1728,17 +1649,17 @@ declare class TransactionBuilder {
 interface PutOptions {
     /** Optional condition that must be satisfied for the put operation to succeed */
     condition?: Condition;
-    /** Determines whether to return the item's previous state (if it existed) */
-    returnValues?: "ALL_OLD" | "NONE";
+    /** 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 PutExecutor<T extends Record<string, unknown>> = (params: PutCommandParams) => Promise<T>;
 /**
  * Builder for creating DynamoDB put operations.
- * Use this builder when you need to:
- * - Add new dinosaurs to the registry
- * - Create new habitats
- * - Update dinosaur profiles completely
- * - Initialize tracking records
  *
  * @example
  * ```typescript
@@ -1801,10 +1722,6 @@ declare class PutBuilder<T extends Record<string, unknown>> {
      */
     /**
      * 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
@@ -1835,13 +1752,14 @@ 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(condition: Condition | ((op: ConditionOperator<T>) => Condition)): this;
     /**
      * 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
@@ -1862,10 +1780,10 @@ declare class PutBuilder<T extends Record<string, unknown>> {
      * }
      * ```
      *
-     * @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: "ALL_OLD" | "NONE"): PutBuilder<T>;
+    returnValues(returnValues: "ALL_OLD" | "NONE" | "CONSISTENT"): this;
     /**
      * Generate the DynamoDB command parameters
      */
@@ -1903,7 +1821,7 @@ declare class PutBuilder<T extends Record<string, unknown>> {
      * @param transaction - The transaction builder to add this operation to
      * @returns The builder instance for method chaining
      */
-    withTransaction(transaction: TransactionBuilder): PutBuilder<T>;
+    withTransaction(transaction: TransactionBuilder): this;
     /**
      * Executes the put operation against DynamoDB.
      *
@@ -1926,15 +1844,10 @@ declare class PutBuilder<T extends Record<string, unknown>> {
      * @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>;
+    execute(): Promise<T | undefined>;
     /**
      * 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
@@ -2843,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);
     /**
@@ -2870,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