dyno-table 1.6.0 → 1.8.0-next.1

package/dist/builders/query-builder.cjs

@@ -61,10 +61,6 @@ var Paginator = class {
   }
   /**
    * Gets the current page number (1-indexed).
-   * Use this method when you need to:
-   * - Track progress through dinosaur lists
-   * - Display habitat inspection status
-   * - Monitor security sweep progress
    *
    * @example
    * ```ts
@@ -82,11 +78,6 @@ var Paginator = class {
   }
   /**
    * Checks if there are more pages of dinosaurs or habitats to process.
-   * Use this method when you need to:
-   * - Check for more dinosaurs to review
-   * - Continue habitat inspections
-   * - Process security incidents
-   * - Complete feeding schedules
    *
    * This method takes into account both:
    * - DynamoDB's lastEvaluatedKey mechanism
@@ -118,11 +109,6 @@ var Paginator = class {
   }
   /**
    * Retrieves the next page of dinosaurs or habitats from DynamoDB.
-   * Use this method when you need to:
-   * - Process dinosaur groups systematically
-   * - Review habitat inspections in batches
-   * - Monitor security incidents in sequence
-   * - Schedule feeding rotations
    *
    * This method handles:
    * - Automatic continuation between groups
@@ -174,13 +160,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;
@@ -194,16 +198,6 @@ var Paginator = class {
   }
   /**
    * Gets all remaining dinosaurs or habitats and combines them into a single array.
-   * Use this method when you need to:
-   * - Generate complete park inventory
-   * - Perform full security audit
-   * - Create comprehensive feeding schedule
-   * - Run park-wide health checks
-   *
-   * Note: Use with caution! This method:
-   * - Could overwhelm systems with large dinosaur populations
-   * - Makes multiple database requests
-   * - May cause system strain during peak hours
    *
    * @example
    * ```ts
@@ -245,10 +239,6 @@ var FilterBuilder = class {
   selectedFields = /* @__PURE__ */ new Set();
   /**
    * 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.
@@ -279,11 +269,6 @@ var FilterBuilder = class {
   }
   /**
    * 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
@@ -312,11 +297,6 @@ var FilterBuilder = class {
   }
   /**
    * 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
@@ -347,11 +327,6 @@ var FilterBuilder = class {
   }
   /**
    * 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
@@ -404,11 +379,6 @@ var FilterBuilder = class {
   }
   /**
    * 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
@@ -453,11 +423,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();
@@ -466,7 +441,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
    */
@@ -475,11 +450,6 @@ var FilterBuilder = class {
   }
   /**
    * 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.
@@ -492,15 +462,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);
    * }
    * ```
    *
@@ -513,6 +485,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;
@@ -634,16 +672,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([
@@ -653,25 +691,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);
   }
 };