dyno-table 1.7.0 → 2.0.0

package/dist/{query-builder-C6XjVEFH.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.
@@ -179,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();
@@ -192,11 +197,11 @@ 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.
      *
@@ -211,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);
      * }
      * ```
      *
@@ -257,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>>;
 }
 
 /**
@@ -428,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([
@@ -447,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-BDuHHrb-.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.
@@ -179,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();
@@ -192,11 +197,11 @@ 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.
      *
@@ -211,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);
      * }
      * ```
      *
@@ -257,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>>;
 }
 
 /**
@@ -428,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([
@@ -447,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/{table-DAKlzQsK.d.cts → table-CHitMHXE.d.cts}

@@ -1,13 +1,13 @@
 import { DynamoItem, TableConfig, Index } from './types.cjs';
 import { r as PrimaryKeyWithoutExpression, P as PrimaryKey } from './conditions-3ae5znV_.cjs';
-import { F as FilterBuilder, b as FilterOptions, Q as QueryBuilder } from './query-builder-BDuHHrb-.cjs';
+import { F as FilterBuilder, b as FilterOptions, Q as QueryBuilder } from './query-builder-DFkxojBM.cjs';
 import { PutBuilder } from './builders/put-builder.cjs';
 import { DeleteBuilder } from './builders/delete-builder.cjs';
 import { UpdateBuilder } from './builders/update-builder.cjs';
 import { TransactionBuilder, TransactionOptions } from './builders/transaction-builder.cjs';
-import { G as GetBuilder, B as BatchBuilder, c as BatchWriteOperation } from './batch-builder-DNsz6zvh.cjs';
+import { G as GetBuilder, B as BatchBuilder, c as BatchWriteOperation } from './batch-builder-CKYnMRyz.cjs';
 import { ConditionCheckBuilder } from './builders/condition-check-builder.cjs';
-import { S as ScanBuilderInterface } from './builder-types-DlaUSc-b.cjs';
+import { S as ScanBuilderInterface, R as ResultIterator } from './builder-types-BTVhQSHI.cjs';
 
 /**
  * Configuration options for DynamoDB scan operations.
@@ -77,43 +77,41 @@ declare class ScanBuilder<T extends DynamoItem, TConfig extends TableConfig = Ta
      */
     clone(): ScanBuilder<T, TConfig>;
     /**
-     * Executes the scan against DynamoDB.
+     * Executes the scan 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 scan.
+     * 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 all dinosaurs with high aggression levels
-     *   const result = await new ScanBuilder(executor)
+     *   // Find all dinosaurs with high aggression levels with automatic pagination
+     *   const results = 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');
+     *   // Use like an array with automatic pagination
+     *   for await (const dinosaur of results) {
+     *     console.log(`Processing dangerous dinosaur: ${dinosaur.name}`);
      *   }
+     *
+     *   // Or convert to array and use array methods
+     *   const allItems = await results.toArray();
+     *   const criticalThreats = 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 scan criteria
-     *          - lastEvaluatedKey: Token for continuing the scan, 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>>;
 }
 
 declare class Table<TConfig extends TableConfig = TableConfig> {

package/dist/{table-BWa4tx63.d.ts → table-m7DQk5dK.d.ts}

@@ -1,13 +1,13 @@
 import { DynamoItem, TableConfig, Index } from './types.js';
 import { r as PrimaryKeyWithoutExpression, P as PrimaryKey } from './conditions-BtynAviC.js';
-import { F as FilterBuilder, b as FilterOptions, Q as QueryBuilder } from './query-builder-C6XjVEFH.js';
+import { F as FilterBuilder, b as FilterOptions, Q as QueryBuilder } from './query-builder-CaHzZmDf.js';
 import { PutBuilder } from './builders/put-builder.js';
 import { DeleteBuilder } from './builders/delete-builder.js';
 import { UpdateBuilder } from './builders/update-builder.js';
 import { TransactionBuilder, TransactionOptions } from './builders/transaction-builder.js';
-import { G as GetBuilder, B as BatchBuilder, c as BatchWriteOperation } from './batch-builder-Dz1yPGrJ.js';
+import { G as GetBuilder, B as BatchBuilder, c as BatchWriteOperation } from './batch-builder-BOBwOIUE.js';
 import { ConditionCheckBuilder } from './builders/condition-check-builder.js';
-import { S as ScanBuilderInterface } from './builder-types-B_tCpn9F.js';
+import { S as ScanBuilderInterface, R as ResultIterator } from './builder-types-CzuLR4Th.js';
 
 /**
  * Configuration options for DynamoDB scan operations.
@@ -77,43 +77,41 @@ declare class ScanBuilder<T extends DynamoItem, TConfig extends TableConfig = Ta
      */
     clone(): ScanBuilder<T, TConfig>;
     /**
-     * Executes the scan against DynamoDB.
+     * Executes the scan 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 scan.
+     * 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 all dinosaurs with high aggression levels
-     *   const result = await new ScanBuilder(executor)
+     *   // Find all dinosaurs with high aggression levels with automatic pagination
+     *   const results = 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');
+     *   // Use like an array with automatic pagination
+     *   for await (const dinosaur of results) {
+     *     console.log(`Processing dangerous dinosaur: ${dinosaur.name}`);
      *   }
+     *
+     *   // Or convert to array and use array methods
+     *   const allItems = await results.toArray();
+     *   const criticalThreats = 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 scan criteria
-     *          - lastEvaluatedKey: Token for continuing the scan, 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>>;
 }
 
 declare class Table<TConfig extends TableConfig = TableConfig> {