dyno-table 1.7.0 → 2.0.0

package/dist/table.cjs

@@ -309,13 +309,31 @@ var Paginator = class {
           page: this.currentPage
         };
       }
-      effectivePageSize = Math.min(effectivePageSize, remainingItems);
+      if (effectivePageSize !== void 0) {
+        effectivePageSize = Math.min(effectivePageSize, remainingItems);
+      } else {
+        effectivePageSize = remainingItems;
+      }
+    }
+    const query = this.queryBuilder.clone();
+    if (effectivePageSize !== void 0) {
+      query.limit(effectivePageSize);
     }
-    const query = this.queryBuilder.clone().limit(effectivePageSize);
     if (this.lastEvaluatedKey) {
       query.startFrom(this.lastEvaluatedKey);
     }
-    const result = await query.execute();
+    const generator = await query.execute();
+    const items = [];
+    let itemCount = 0;
+    for await (const item of generator) {
+      if (effectivePageSize !== void 0 && itemCount >= effectivePageSize) {
+        break;
+      }
+      items.push(item);
+      itemCount++;
+    }
+    const lastEvaluatedKey = generator.getLastEvaluatedKey();
+    const result = { items, lastEvaluatedKey };
     this.currentPage += 1;
     this.lastEvaluatedKey = result.lastEvaluatedKey;
     this.totalItemsRetrieved += result.items.length;
@@ -554,11 +572,16 @@ var FilterBuilder = class {
    *
    * @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();
@@ -567,7 +590,7 @@ var FilterBuilder = class {
    * }
    * ```
    *
-   * @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
    */
@@ -588,15 +611,17 @@ var FilterBuilder = class {
    *   .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);
    * }
    * ```
    *
@@ -609,6 +634,72 @@ var FilterBuilder = class {
   }
 };
 
+// src/builders/result-iterator.ts
+var ResultIterator = class {
+  constructor(queryBuilder, directExecutor) {
+    this.queryBuilder = queryBuilder;
+    this.directExecutor = directExecutor;
+    this.overallLimit = queryBuilder.getLimit();
+  }
+  lastEvaluatedKey;
+  itemsYielded = 0;
+  overallLimit;
+  /**
+   * Async iterator with automatic pagination
+   */
+  async *[Symbol.asyncIterator]() {
+    let hasMorePages = true;
+    while (hasMorePages) {
+      const result = await this.directExecutor();
+      for (const item of result.items) {
+        if (this.overallLimit !== void 0 && this.itemsYielded >= this.overallLimit) {
+          return;
+        }
+        yield item;
+        this.itemsYielded++;
+      }
+      if (result.lastEvaluatedKey !== null && result.lastEvaluatedKey !== void 0) {
+        this.lastEvaluatedKey = result.lastEvaluatedKey;
+        this.queryBuilder.startFrom(result.lastEvaluatedKey);
+      } else if (result.lastEvaluatedKey === null) {
+        if (this.lastEvaluatedKey === void 0) {
+          this.lastEvaluatedKey = null;
+        }
+      }
+      hasMorePages = !!result.lastEvaluatedKey && (this.overallLimit === void 0 || this.itemsYielded < this.overallLimit);
+    }
+  }
+  /**
+   * Convert to array (loads all pages).
+   *
+   * ```ts
+   * const result = await table.query({ pk: "foo" }).execute();
+   * const allItemsFromDynamo = await result.toArray();
+   * ```
+   *
+   * Note: This will load all pages into memory. For large datasets, consider using async iteration instead.
+   *```ts
+   * const result = await table.query({ pk: "foo" }).execute();
+   * for await (const item of result) {
+   *   // Process each item
+   * }
+   * ```
+   */
+  async toArray() {
+    const items = [];
+    for await (const item of this) {
+      items.push(item);
+    }
+    return items;
+  }
+  /**
+   * Get the last evaluated key
+   */
+  getLastEvaluatedKey() {
+    return this.lastEvaluatedKey === null ? void 0 : this.lastEvaluatedKey;
+  }
+};
+
 // src/builders/query-builder.ts
 var QueryBuilder = class _QueryBuilder extends FilterBuilder {
   keyCondition;
@@ -730,16 +821,16 @@ var QueryBuilder = class _QueryBuilder extends FilterBuilder {
     return clone;
   }
   /**
-   * 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([
@@ -749,25 +840,27 @@ var QueryBuilder = class _QueryBuilder extends FilterBuilder {
    *       ])
    *     )
    *     .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
    */
   async execute() {
-    return this.executor(this.keyCondition, this.options);
+    const directExecutor = () => this.executor(this.keyCondition, this.options);
+    return new ResultIterator(this, directExecutor);
   }
 };
 
@@ -3050,41 +3143,43 @@ var ScanBuilder = class _ScanBuilder extends FilterBuilder {
     return clone;
   }
   /**
-   * 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
    */
   async execute() {
-    return this.executor(this.options);
+    const directExecutor = () => this.executor(this.options);
+    return new ResultIterator(this, directExecutor);
   }
 };