dyno-table 1.6.0 → 1.8.0-next.1

package/dist/{query-builder-BhrR31oO.d.ts → query-builder-CaHzZmDf.d.ts}

@@ -1,7 +1,7 @@
 import { C as Condition, q as ConditionOperator } from './conditions-BtynAviC.js';
 import { Paginator } from './builders/paginator.js';
 import { DynamoItem, TableConfig, GSINames } from './types.js';
-import { F as FilterBuilderInterface, Q as QueryBuilderInterface } from './builder-types-B_tCpn9F.js';
+import { F as FilterBuilderInterface, R as ResultIterator, Q as QueryBuilderInterface } from './builder-types-CzuLR4Th.js';
 
 /**
  * Configuration options for DynamoDB filter operations.
@@ -40,10 +40,6 @@ declare abstract class FilterBuilder<T extends DynamoItem, TConfig extends Table
     protected selectedFields: Set<string>;
     /**
      * Sets the maximum number of items to return.
-     * Use this method when you need to:
-     * - 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.
@@ -69,11 +65,6 @@ declare abstract class FilterBuilder<T extends DynamoItem, TConfig extends Table
     getLimit(): number | undefined;
     /**
      * Specifies a Global Secondary Index (GSI) to use for the operation.
-     * Use this method when you need to:
-     * - Find dinosaurs by species or status
-     * - Search habitats by security level
-     * - Find incidents by date
-     * - List feeding schedules by time
      *
      * @example
      * ```typescript
@@ -99,11 +90,6 @@ declare abstract class FilterBuilder<T extends DynamoItem, TConfig extends Table
     useIndex<I extends GSINames<TConfig>>(indexName: I): this;
     /**
      * 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
@@ -131,11 +117,6 @@ declare abstract class FilterBuilder<T extends DynamoItem, TConfig extends Table
     consistentRead(consistentRead?: boolean): this;
     /**
      * 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
@@ -164,11 +145,6 @@ declare abstract class FilterBuilder<T extends DynamoItem, TConfig extends Table
     filter(condition: Condition | ((op: ConditionOperator<T>) => Condition)): this;
     /**
      * 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
@@ -203,11 +179,16 @@ declare abstract class FilterBuilder<T extends DynamoItem, TConfig extends Table
      *
      * @example
      * ```typescript
-     * // Create a paginator for dinosaur records
+     * // Create a paginator for dinosaur records with specific page size
      * const paginator = builder
      *   .filter(op => op.eq('status', 'ACTIVE'))
      *   .paginate(10);
      *
+     * // Create a paginator with automatic DynamoDB paging (no page size limit)
+     * const autoPaginator = builder
+     *   .filter(op => op.eq('status', 'ACTIVE'))
+     *   .paginate();
+     *
      * // Process pages of dinosaur results
      * while (paginator.hasNextPage()) {
      *   const page = await paginator.getNextPage();
@@ -216,18 +197,13 @@ declare abstract class FilterBuilder<T extends DynamoItem, TConfig extends Table
      * }
      * ```
      *
-     * @param pageSize - The number of items to return per page
+     * @param pageSize - The number of items to return per page. If not provided, DynamoDB will automatically determine page sizes.
      * @returns A Paginator instance that manages the pagination state
      * @see Paginator for more pagination control options
      */
-    paginate(pageSize: number): Paginator<T, TConfig>;
+    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.
@@ -240,15 +216,17 @@ declare abstract class FilterBuilder<T extends DynamoItem, TConfig extends Table
      *   .limit(5)
      *   .execute();
      *
-     * if (result1.lastEvaluatedKey) {
+     * const lastKey = result1.getLastEvaluatedKey();
+     * if (lastKey) {
      *   // Continue listing dinosaurs
      *   const result2 = await builder
      *     .filter(op => op.eq('status', 'ACTIVE'))
-     *     .startFrom(result1.lastEvaluatedKey)
+     *     .startFrom(lastKey)
      *     .limit(5)
      *     .execute();
      *
-     *   console.log('Additional dinosaurs:', result2.items);
+     *   const items = await result2.toArray();
+     *   console.log('Additional dinosaurs:', items);
      * }
      * ```
      *
@@ -258,11 +236,6 @@ declare abstract class FilterBuilder<T extends DynamoItem, TConfig extends Table
     startFrom(lastEvaluatedKey: DynamoItem): this;
     /**
      * Creates a deep clone of this builder 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())
@@ -291,14 +264,11 @@ declare abstract class FilterBuilder<T extends DynamoItem, TConfig extends Table
      */
     abstract clone(): FilterBuilderInterface<T, TConfig>;
     /**
-     * Executes the operation against DynamoDB.
+     * Executes the operation against DynamoDB and returns a generator that behaves like an array.
      * This method must be implemented by subclasses to handle
      * their specific execution logic.
      */
-    abstract execute(): Promise<{
-        items: T[];
-        lastEvaluatedKey?: DynamoItem;
-    }>;
+    abstract execute(): Promise<ResultIterator<T, TConfig>>;
 }
 
 /**
@@ -462,16 +432,16 @@ declare class QueryBuilder<T extends DynamoItem, TConfig extends TableConfig = T
      */
     clone(): QueryBuilder<T, TConfig>;
     /**
-     * Executes the query against DynamoDB.
+     * Executes the query against DynamoDB and returns a generator that behaves like an array.
      *
-     * 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.
+     * The generator automatically handles pagination and provides array-like methods
+     * for processing results efficiently without loading everything into memory at once.
      *
      * @example
      * ```typescript
      * try {
-     *   // Find active carnivores in specific habitat
-     *   const result = await new QueryBuilder(executor, eq('habitatId', 'PADDOCK-A'))
+     *   // Find active carnivores with automatic pagination
+     *   const results = await new QueryBuilder(executor, eq('habitatId', 'PADDOCK-A'))
      *     .useIndex('species-status-index')
      *     .filter(op =>
      *       op.and([
@@ -481,27 +451,25 @@ declare class QueryBuilder<T extends DynamoItem, TConfig extends TableConfig = T
      *       ])
      *     )
      *     .sortDescending()
-     *     .limit(5)
      *     .execute();
      *
-     *   console.log(`Found ${result.items.length} dangerous dinosaurs`);
-     *
-     *   if (result.lastEvaluatedKey) {
-     *     console.log('Additional threats detected');
+     *   // Use like an array with automatic pagination
+     *   for await (const dinosaur of results) {
+     *     console.log(`Processing ${dinosaur.name}`);
      *   }
+     *
+     *   // Or convert to array and use array methods
+     *   const allItems = await results.toArray();
+     *   const dangerousOnes = allItems.filter(dino => dino.aggressionLevel > 9);
+     *   const totalCount = allItems.length;
      * } catch (error) {
      *   console.error('Security scan failed:', error);
      * }
      * ```
      *
-     * @returns A promise that resolves to an object containing:
-     *          - items: Array of items matching the query
-     *          - lastEvaluatedKey: Token for continuing the query, if more items exist
+     * @returns A promise that resolves to a ResultGenerator that behaves like an array
      */
-    execute(): Promise<{
-        items: T[];
-        lastEvaluatedKey?: Record<string, unknown>;
-    }>;
+    execute(): Promise<ResultIterator<T, TConfig>>;
 }
 
 export { FilterBuilder as F, QueryBuilder as Q, type QueryOptions as a, type FilterOptions as b };

package/dist/{query-builder-CbHvimBk.d.cts → query-builder-DFkxojBM.d.cts}

@@ -1,7 +1,7 @@
 import { C as Condition, q as ConditionOperator } from './conditions-3ae5znV_.cjs';
 import { Paginator } from './builders/paginator.cjs';
 import { DynamoItem, TableConfig, GSINames } from './types.cjs';
-import { F as FilterBuilderInterface, Q as QueryBuilderInterface } from './builder-types-DlaUSc-b.cjs';
+import { F as FilterBuilderInterface, R as ResultIterator, Q as QueryBuilderInterface } from './builder-types-BTVhQSHI.cjs';
 
 /**
  * Configuration options for DynamoDB filter operations.
@@ -40,10 +40,6 @@ declare abstract class FilterBuilder<T extends DynamoItem, TConfig extends Table
     protected selectedFields: Set<string>;
     /**
      * Sets the maximum number of items to return.
-     * Use this method when you need to:
-     * - 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.
@@ -69,11 +65,6 @@ declare abstract class FilterBuilder<T extends DynamoItem, TConfig extends Table
     getLimit(): number | undefined;
     /**
      * Specifies a Global Secondary Index (GSI) to use for the operation.
-     * Use this method when you need to:
-     * - Find dinosaurs by species or status
-     * - Search habitats by security level
-     * - Find incidents by date
-     * - List feeding schedules by time
      *
      * @example
      * ```typescript
@@ -99,11 +90,6 @@ declare abstract class FilterBuilder<T extends DynamoItem, TConfig extends Table
     useIndex<I extends GSINames<TConfig>>(indexName: I): this;
     /**
      * 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
@@ -131,11 +117,6 @@ declare abstract class FilterBuilder<T extends DynamoItem, TConfig extends Table
     consistentRead(consistentRead?: boolean): this;
     /**
      * 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
@@ -164,11 +145,6 @@ declare abstract class FilterBuilder<T extends DynamoItem, TConfig extends Table
     filter(condition: Condition | ((op: ConditionOperator<T>) => Condition)): this;
     /**
      * 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
@@ -203,11 +179,16 @@ declare abstract class FilterBuilder<T extends DynamoItem, TConfig extends Table
      *
      * @example
      * ```typescript
-     * // Create a paginator for dinosaur records
+     * // Create a paginator for dinosaur records with specific page size
      * const paginator = builder
      *   .filter(op => op.eq('status', 'ACTIVE'))
      *   .paginate(10);
      *
+     * // Create a paginator with automatic DynamoDB paging (no page size limit)
+     * const autoPaginator = builder
+     *   .filter(op => op.eq('status', 'ACTIVE'))
+     *   .paginate();
+     *
      * // Process pages of dinosaur results
      * while (paginator.hasNextPage()) {
      *   const page = await paginator.getNextPage();
@@ -216,18 +197,13 @@ declare abstract class FilterBuilder<T extends DynamoItem, TConfig extends Table
      * }
      * ```
      *
-     * @param pageSize - The number of items to return per page
+     * @param pageSize - The number of items to return per page. If not provided, DynamoDB will automatically determine page sizes.
      * @returns A Paginator instance that manages the pagination state
      * @see Paginator for more pagination control options
      */
-    paginate(pageSize: number): Paginator<T, TConfig>;
+    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.
@@ -240,15 +216,17 @@ declare abstract class FilterBuilder<T extends DynamoItem, TConfig extends Table
      *   .limit(5)
      *   .execute();
      *
-     * if (result1.lastEvaluatedKey) {
+     * const lastKey = result1.getLastEvaluatedKey();
+     * if (lastKey) {
      *   // Continue listing dinosaurs
      *   const result2 = await builder
      *     .filter(op => op.eq('status', 'ACTIVE'))
-     *     .startFrom(result1.lastEvaluatedKey)
+     *     .startFrom(lastKey)
      *     .limit(5)
      *     .execute();
      *
-     *   console.log('Additional dinosaurs:', result2.items);
+     *   const items = await result2.toArray();
+     *   console.log('Additional dinosaurs:', items);
      * }
      * ```
      *
@@ -258,11 +236,6 @@ declare abstract class FilterBuilder<T extends DynamoItem, TConfig extends Table
     startFrom(lastEvaluatedKey: DynamoItem): this;
     /**
      * Creates a deep clone of this builder 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())
@@ -291,14 +264,11 @@ declare abstract class FilterBuilder<T extends DynamoItem, TConfig extends Table
      */
     abstract clone(): FilterBuilderInterface<T, TConfig>;
     /**
-     * Executes the operation against DynamoDB.
+     * Executes the operation against DynamoDB and returns a generator that behaves like an array.
      * This method must be implemented by subclasses to handle
      * their specific execution logic.
      */
-    abstract execute(): Promise<{
-        items: T[];
-        lastEvaluatedKey?: DynamoItem;
-    }>;
+    abstract execute(): Promise<ResultIterator<T, TConfig>>;
 }
 
 /**
@@ -462,16 +432,16 @@ declare class QueryBuilder<T extends DynamoItem, TConfig extends TableConfig = T
      */
     clone(): QueryBuilder<T, TConfig>;
     /**
-     * Executes the query against DynamoDB.
+     * Executes the query against DynamoDB and returns a generator that behaves like an array.
      *
-     * 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.
+     * The generator automatically handles pagination and provides array-like methods
+     * for processing results efficiently without loading everything into memory at once.
      *
      * @example
      * ```typescript
      * try {
-     *   // Find active carnivores in specific habitat
-     *   const result = await new QueryBuilder(executor, eq('habitatId', 'PADDOCK-A'))
+     *   // Find active carnivores with automatic pagination
+     *   const results = await new QueryBuilder(executor, eq('habitatId', 'PADDOCK-A'))
      *     .useIndex('species-status-index')
      *     .filter(op =>
      *       op.and([
@@ -481,27 +451,25 @@ declare class QueryBuilder<T extends DynamoItem, TConfig extends TableConfig = T
      *       ])
      *     )
      *     .sortDescending()
-     *     .limit(5)
      *     .execute();
      *
-     *   console.log(`Found ${result.items.length} dangerous dinosaurs`);
-     *
-     *   if (result.lastEvaluatedKey) {
-     *     console.log('Additional threats detected');
+     *   // Use like an array with automatic pagination
+     *   for await (const dinosaur of results) {
+     *     console.log(`Processing ${dinosaur.name}`);
      *   }
+     *
+     *   // Or convert to array and use array methods
+     *   const allItems = await results.toArray();
+     *   const dangerousOnes = allItems.filter(dino => dino.aggressionLevel > 9);
+     *   const totalCount = allItems.length;
      * } catch (error) {
      *   console.error('Security scan failed:', error);
      * }
      * ```
      *
-     * @returns A promise that resolves to an object containing:
-     *          - items: Array of items matching the query
-     *          - lastEvaluatedKey: Token for continuing the query, if more items exist
+     * @returns A promise that resolves to a ResultGenerator that behaves like an array
      */
-    execute(): Promise<{
-        items: T[];
-        lastEvaluatedKey?: Record<string, unknown>;
-    }>;
+    execute(): Promise<ResultIterator<T, TConfig>>;
 }
 
 export { FilterBuilder as F, QueryBuilder as Q, type QueryOptions as a, type FilterOptions as b };