dyno-table 1.0.0-alpha.1 → 1.1.0

package/dist/builders/paginator.cjs

@@ -0,0 +1,199 @@
+'use strict';
+
+// src/builders/paginator.ts
+var Paginator = class {
+  queryBuilder;
+  pageSize;
+  currentPage = 0;
+  lastEvaluatedKey;
+  hasMorePages = true;
+  totalItemsRetrieved = 0;
+  overallLimit;
+  constructor(queryBuilder, pageSize) {
+    this.queryBuilder = queryBuilder;
+    this.pageSize = pageSize;
+    this.overallLimit = queryBuilder.getLimit();
+  }
+  /**
+   * 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
+   * const paginator = new QueryBuilder(executor, eq('species', 'Tyrannosaurus'))
+   *   .paginate(5);
+   *
+   * await paginator.getNextPage();
+   * console.log(`Reviewing T-Rex group ${paginator.getCurrentPage()}`);
+   * ```
+   *
+   * @returns The current page number, starting from 1
+   */
+  getCurrentPage() {
+    return this.currentPage;
+  }
+  /**
+   * 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
+   * - Any overall limit set on the query
+   *
+   * @example
+   * ```ts
+   * // Process all security incidents
+   * const paginator = new QueryBuilder(executor, eq('type', 'SECURITY_BREACH'))
+   *   .sortDescending()
+   *   .paginate(10);
+   *
+   * while (paginator.hasNextPage()) {
+   *   const page = await paginator.getNextPage();
+   *   for (const incident of page.items) {
+   *     await processSecurityBreach(incident);
+   *   }
+   *   console.log(`Processed incidents page ${page.page}`);
+   * }
+   * ```
+   *
+   * @returns true if there are more pages available, false otherwise
+   */
+  hasNextPage() {
+    if (this.overallLimit !== void 0 && this.totalItemsRetrieved >= this.overallLimit) {
+      return false;
+    }
+    return this.hasMorePages;
+  }
+  /**
+   * 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
+   * - Respect for park capacity limits
+   * - Group size adjustments for safety
+   *
+   * @example
+   * ```ts
+   * const paginator = new QueryBuilder(executor, eq('species', 'Velociraptor'))
+   *   .filter(op => op.eq('status', 'ACTIVE'))
+   *   .paginate(5);
+   *
+   * // Check first raptor group
+   * const page1 = await paginator.getNextPage();
+   * console.log(`Found ${page1.items.length} active raptors`);
+   *
+   * // Continue inspection if more groups exist
+   * if (page1.hasNextPage) {
+   *   const page2 = await paginator.getNextPage();
+   *   console.log(`Inspecting raptor group ${page2.page}`);
+   *
+   *   for (const raptor of page2.items) {
+   *     await performHealthCheck(raptor);
+   *   }
+   * }
+   * ```
+   *
+   * @returns A promise that resolves to a PaginationResult containing:
+   *          - items: The dinosaurs/habitats for this page
+   *          - hasNextPage: Whether more groups exist
+   *          - page: The current group number
+   *          - lastEvaluatedKey: DynamoDB's continuation token
+   */
+  async getNextPage() {
+    if (!this.hasNextPage()) {
+      return {
+        items: [],
+        hasNextPage: false,
+        page: this.currentPage
+      };
+    }
+    let effectivePageSize = this.pageSize;
+    if (this.overallLimit !== void 0) {
+      const remainingItems = this.overallLimit - this.totalItemsRetrieved;
+      if (remainingItems <= 0) {
+        return {
+          items: [],
+          hasNextPage: false,
+          page: this.currentPage
+        };
+      }
+      effectivePageSize = Math.min(effectivePageSize, remainingItems);
+    }
+    const query = this.queryBuilder.clone().limit(effectivePageSize);
+    if (this.lastEvaluatedKey) {
+      query.startFrom(this.lastEvaluatedKey);
+    }
+    const result = await query.execute();
+    this.currentPage += 1;
+    this.lastEvaluatedKey = result.lastEvaluatedKey;
+    this.totalItemsRetrieved += result.items.length;
+    this.hasMorePages = !!result.lastEvaluatedKey && (this.overallLimit === void 0 || this.totalItemsRetrieved < this.overallLimit);
+    return {
+      items: result.items,
+      lastEvaluatedKey: result.lastEvaluatedKey,
+      hasNextPage: this.hasNextPage(),
+      page: this.currentPage
+    };
+  }
+  /**
+   * 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
+   * // Get complete carnivore inventory
+   * const paginator = new QueryBuilder(executor, eq('diet', 'CARNIVORE'))
+   *   .filter(op => op.eq('status', 'ACTIVE'))
+   *   .paginate(10);
+   *
+   * try {
+   *   const allCarnivores = await paginator.getAllPages();
+   *   console.log(`Park contains ${allCarnivores.length} active carnivores`);
+   *
+   *   // Calculate total threat level
+   *   const totalThreat = allCarnivores.reduce(
+   *     (sum, dino) => sum + dino.stats.threatLevel,
+   *     0
+   *   );
+   *   console.log(`Total threat level: ${totalThreat}`);
+   * } catch (error) {
+   *   console.error('Failed to complete carnivore census:', error);
+   * }
+   * ```
+   *
+   * @returns A promise that resolves to an array containing all remaining items
+   */
+  async getAllPages() {
+    const allItems = [];
+    while (this.hasNextPage()) {
+      const result = await this.getNextPage();
+      allItems.push(...result.items);
+    }
+    return allItems;
+  }
+};
+
+exports.Paginator = Paginator;
+//# sourceMappingURL=paginator.cjs.map
+//# sourceMappingURL=paginator.cjs.map

package/dist/builders/paginator.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/builders/paginator.ts"],"names":[],"mappings":"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","file":"paginator.cjs","sourcesContent":["import type { DynamoItem, TableConfig } from \"../types\";\nimport type { PaginationResult, QueryBuilderInterface } from \"./builder-types\";\n\n/**\n * A utility class for handling DynamoDB pagination.\n * Use this class when you need to:\n * - Browse large collections of dinosaurs\n * - Review extensive security logs\n * - Analyze habitat inspection history\n * - Process feeding schedules\n *\n * The paginator maintains internal state and automatically handles:\n * - Page boundaries\n * - Result set limits\n * - Continuation tokens\n *\n * @example\n * ```typescript\n * // List all velociraptors with pagination\n * const paginator = new QueryBuilder(executor, eq('species', 'Velociraptor'))\n *   .filter(op => op.eq('status', 'ACTIVE'))\n *   .paginate(10);\n *\n * // Process each page of dinosaurs\n * while (paginator.hasNextPage()) {\n *   const page = await paginator.getNextPage();\n *   console.log(`Processing page ${page.page} of velociraptors`);\n *\n *   for (const raptor of page.items) {\n *     console.log(`- ${raptor.id}: Health=${raptor.stats.health}`);\n *   }\n * }\n * ```\n *\n * @typeParam T - The type of items being paginated\n * @typeParam TConfig - The table configuration type\n */\nexport class Paginator<T extends DynamoItem, TConfig extends TableConfig = TableConfig> {\n  private queryBuilder: QueryBuilderInterface<T, TConfig>;\n  private readonly pageSize: number;\n  private currentPage = 0;\n  private lastEvaluatedKey?: DynamoItem;\n  private hasMorePages = true;\n  private totalItemsRetrieved = 0;\n  private readonly overallLimit?: number;\n\n  constructor(queryBuilder: QueryBuilderInterface<T, TConfig>, pageSize: number) {\n    this.queryBuilder = queryBuilder;\n    this.pageSize = pageSize;\n    // Store the overall limit from the query builder if it exists\n    this.overallLimit = queryBuilder.getLimit();\n  }\n\n  /**\n   * Gets the current page number (1-indexed).\n   * Use this method when you need to:\n   * - Track progress through dinosaur lists\n   * - Display habitat inspection status\n   * - Monitor security sweep progress\n   *\n   * @example\n   * ```ts\n   * const paginator = new QueryBuilder(executor, eq('species', 'Tyrannosaurus'))\n   *   .paginate(5);\n   *\n   * await paginator.getNextPage();\n   * console.log(`Reviewing T-Rex group ${paginator.getCurrentPage()}`);\n   * ```\n   *\n   * @returns The current page number, starting from 1\n   */\n  public getCurrentPage(): number {\n    return this.currentPage;\n  }\n\n  /**\n   * Checks if there are more pages of dinosaurs or habitats to process.\n   * Use this method when you need to:\n   * - Check for more dinosaurs to review\n   * - Continue habitat inspections\n   * - Process security incidents\n   * - Complete feeding schedules\n   *\n   * This method takes into account both:\n   * - DynamoDB's lastEvaluatedKey mechanism\n   * - Any overall limit set on the query\n   *\n   * @example\n   * ```ts\n   * // Process all security incidents\n   * const paginator = new QueryBuilder(executor, eq('type', 'SECURITY_BREACH'))\n   *   .sortDescending()\n   *   .paginate(10);\n   *\n   * while (paginator.hasNextPage()) {\n   *   const page = await paginator.getNextPage();\n   *   for (const incident of page.items) {\n   *     await processSecurityBreach(incident);\n   *   }\n   *   console.log(`Processed incidents page ${page.page}`);\n   * }\n   * ```\n   *\n   * @returns true if there are more pages available, false otherwise\n   */\n  public hasNextPage(): boolean {\n    // If we have an overall limit and we've already retrieved that many items, there are no more pages\n    if (this.overallLimit !== undefined && this.totalItemsRetrieved >= this.overallLimit) {\n      return false;\n    }\n    return this.hasMorePages;\n  }\n\n  /**\n   * Retrieves the next page of dinosaurs or habitats from DynamoDB.\n   * Use this method when you need to:\n   * - Process dinosaur groups systematically\n   * - Review habitat inspections in batches\n   * - Monitor security incidents in sequence\n   * - Schedule feeding rotations\n   *\n   * This method handles:\n   * - Automatic continuation between groups\n   * - Respect for park capacity limits\n   * - Group size adjustments for safety\n   *\n   * @example\n   * ```ts\n   * const paginator = new QueryBuilder(executor, eq('species', 'Velociraptor'))\n   *   .filter(op => op.eq('status', 'ACTIVE'))\n   *   .paginate(5);\n   *\n   * // Check first raptor group\n   * const page1 = await paginator.getNextPage();\n   * console.log(`Found ${page1.items.length} active raptors`);\n   *\n   * // Continue inspection if more groups exist\n   * if (page1.hasNextPage) {\n   *   const page2 = await paginator.getNextPage();\n   *   console.log(`Inspecting raptor group ${page2.page}`);\n   *\n   *   for (const raptor of page2.items) {\n   *     await performHealthCheck(raptor);\n   *   }\n   * }\n   * ```\n   *\n   * @returns A promise that resolves to a PaginationResult containing:\n   *          - items: The dinosaurs/habitats for this page\n   *          - hasNextPage: Whether more groups exist\n   *          - page: The current group number\n   *          - lastEvaluatedKey: DynamoDB's continuation token\n   */\n  public async getNextPage(): Promise<PaginationResult<T>> {\n    if (!this.hasNextPage()) {\n      return {\n        items: [],\n        hasNextPage: false,\n        page: this.currentPage,\n      };\n    }\n\n    // Calculate how many items to fetch for this page\n    let effectivePageSize = this.pageSize;\n\n    // If we have an overall limit, make sure we don't fetch more than what's left\n    if (this.overallLimit !== undefined) {\n      const remainingItems = this.overallLimit - this.totalItemsRetrieved;\n      if (remainingItems <= 0) {\n        return {\n          items: [],\n          hasNextPage: false,\n          page: this.currentPage,\n        };\n      }\n      effectivePageSize = Math.min(effectivePageSize, remainingItems);\n    }\n\n    // Clone the query builder to avoid modifying the original\n    const query = this.queryBuilder.clone().limit(effectivePageSize);\n\n    // Apply the last evaluated key if we have one\n    if (this.lastEvaluatedKey) {\n      query.startFrom(this.lastEvaluatedKey);\n    }\n\n    // Execute the query\n    const result = await query.execute();\n\n    // Update pagination state\n    this.currentPage += 1;\n    this.lastEvaluatedKey = result.lastEvaluatedKey;\n    this.totalItemsRetrieved += result.items.length;\n\n    // Determine if there are more pages\n    // We have more pages if:\n    // 1. DynamoDB returned a lastEvaluatedKey AND\n    // 2. We haven't hit our overall limit (if one exists)\n    this.hasMorePages =\n      !!result.lastEvaluatedKey && (this.overallLimit === undefined || this.totalItemsRetrieved < this.overallLimit);\n\n    return {\n      items: result.items,\n      lastEvaluatedKey: result.lastEvaluatedKey,\n      hasNextPage: this.hasNextPage(),\n      page: this.currentPage,\n    };\n  }\n\n  /**\n   * Gets all remaining dinosaurs or habitats and combines them into a single array.\n   * Use this method when you need to:\n   * - Generate complete park inventory\n   * - Perform full security audit\n   * - Create comprehensive feeding schedule\n   * - Run park-wide health checks\n   *\n   * Note: Use with caution! This method:\n   * - Could overwhelm systems with large dinosaur populations\n   * - Makes multiple database requests\n   * - May cause system strain during peak hours\n   *\n   * @example\n   * ```ts\n   * // Get complete carnivore inventory\n   * const paginator = new QueryBuilder(executor, eq('diet', 'CARNIVORE'))\n   *   .filter(op => op.eq('status', 'ACTIVE'))\n   *   .paginate(10);\n   *\n   * try {\n   *   const allCarnivores = await paginator.getAllPages();\n   *   console.log(`Park contains ${allCarnivores.length} active carnivores`);\n   *\n   *   // Calculate total threat level\n   *   const totalThreat = allCarnivores.reduce(\n   *     (sum, dino) => sum + dino.stats.threatLevel,\n   *     0\n   *   );\n   *   console.log(`Total threat level: ${totalThreat}`);\n   * } catch (error) {\n   *   console.error('Failed to complete carnivore census:', error);\n   * }\n   * ```\n   *\n   * @returns A promise that resolves to an array containing all remaining items\n   */\n  public async getAllPages(): Promise<T[]> {\n    const allItems: T[] = [];\n\n    while (this.hasNextPage()) {\n      const result = await this.getNextPage();\n      allItems.push(...result.items);\n    }\n\n    return allItems;\n  }\n}\n"]}

package/dist/builders/paginator.d.cts

@@ -0,0 +1,179 @@
+import { DynamoItem, TableConfig } from '../types.cjs';
+import { Q as QueryBuilderInterface, P as PaginationResult } from '../builder-types-DtwbqMeF.cjs';
+import '@aws-sdk/lib-dynamodb';
+
+/**
+ * A utility class for handling DynamoDB pagination.
+ * Use this class when you need to:
+ * - Browse large collections of dinosaurs
+ * - Review extensive security logs
+ * - Analyze habitat inspection history
+ * - Process feeding schedules
+ *
+ * The paginator maintains internal state and automatically handles:
+ * - Page boundaries
+ * - Result set limits
+ * - Continuation tokens
+ *
+ * @example
+ * ```typescript
+ * // List all velociraptors with pagination
+ * const paginator = new QueryBuilder(executor, eq('species', 'Velociraptor'))
+ *   .filter(op => op.eq('status', 'ACTIVE'))
+ *   .paginate(10);
+ *
+ * // Process each page of dinosaurs
+ * while (paginator.hasNextPage()) {
+ *   const page = await paginator.getNextPage();
+ *   console.log(`Processing page ${page.page} of velociraptors`);
+ *
+ *   for (const raptor of page.items) {
+ *     console.log(`- ${raptor.id}: Health=${raptor.stats.health}`);
+ *   }
+ * }
+ * ```
+ *
+ * @typeParam T - The type of items being paginated
+ * @typeParam TConfig - The table configuration type
+ */
+declare class Paginator<T extends DynamoItem, TConfig extends TableConfig = TableConfig> {
+    private queryBuilder;
+    private readonly pageSize;
+    private currentPage;
+    private lastEvaluatedKey?;
+    private hasMorePages;
+    private totalItemsRetrieved;
+    private readonly overallLimit?;
+    constructor(queryBuilder: QueryBuilderInterface<T, TConfig>, pageSize: number);
+    /**
+     * 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
+     * const paginator = new QueryBuilder(executor, eq('species', 'Tyrannosaurus'))
+     *   .paginate(5);
+     *
+     * await paginator.getNextPage();
+     * console.log(`Reviewing T-Rex group ${paginator.getCurrentPage()}`);
+     * ```
+     *
+     * @returns The current page number, starting from 1
+     */
+    getCurrentPage(): number;
+    /**
+     * 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
+     * - Any overall limit set on the query
+     *
+     * @example
+     * ```ts
+     * // Process all security incidents
+     * const paginator = new QueryBuilder(executor, eq('type', 'SECURITY_BREACH'))
+     *   .sortDescending()
+     *   .paginate(10);
+     *
+     * while (paginator.hasNextPage()) {
+     *   const page = await paginator.getNextPage();
+     *   for (const incident of page.items) {
+     *     await processSecurityBreach(incident);
+     *   }
+     *   console.log(`Processed incidents page ${page.page}`);
+     * }
+     * ```
+     *
+     * @returns true if there are more pages available, false otherwise
+     */
+    hasNextPage(): boolean;
+    /**
+     * 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
+     * - Respect for park capacity limits
+     * - Group size adjustments for safety
+     *
+     * @example
+     * ```ts
+     * const paginator = new QueryBuilder(executor, eq('species', 'Velociraptor'))
+     *   .filter(op => op.eq('status', 'ACTIVE'))
+     *   .paginate(5);
+     *
+     * // Check first raptor group
+     * const page1 = await paginator.getNextPage();
+     * console.log(`Found ${page1.items.length} active raptors`);
+     *
+     * // Continue inspection if more groups exist
+     * if (page1.hasNextPage) {
+     *   const page2 = await paginator.getNextPage();
+     *   console.log(`Inspecting raptor group ${page2.page}`);
+     *
+     *   for (const raptor of page2.items) {
+     *     await performHealthCheck(raptor);
+     *   }
+     * }
+     * ```
+     *
+     * @returns A promise that resolves to a PaginationResult containing:
+     *          - items: The dinosaurs/habitats for this page
+     *          - hasNextPage: Whether more groups exist
+     *          - page: The current group number
+     *          - lastEvaluatedKey: DynamoDB's continuation token
+     */
+    getNextPage(): Promise<PaginationResult<T>>;
+    /**
+     * 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
+     * // Get complete carnivore inventory
+     * const paginator = new QueryBuilder(executor, eq('diet', 'CARNIVORE'))
+     *   .filter(op => op.eq('status', 'ACTIVE'))
+     *   .paginate(10);
+     *
+     * try {
+     *   const allCarnivores = await paginator.getAllPages();
+     *   console.log(`Park contains ${allCarnivores.length} active carnivores`);
+     *
+     *   // Calculate total threat level
+     *   const totalThreat = allCarnivores.reduce(
+     *     (sum, dino) => sum + dino.stats.threatLevel,
+     *     0
+     *   );
+     *   console.log(`Total threat level: ${totalThreat}`);
+     * } catch (error) {
+     *   console.error('Failed to complete carnivore census:', error);
+     * }
+     * ```
+     *
+     * @returns A promise that resolves to an array containing all remaining items
+     */
+    getAllPages(): Promise<T[]>;
+}
+
+export { Paginator };

package/dist/builders/paginator.d.ts

@@ -0,0 +1,179 @@
+import { DynamoItem, TableConfig } from '../types.js';
+import { Q as QueryBuilderInterface, P as PaginationResult } from '../builder-types-C_PDZhnP.js';
+import '@aws-sdk/lib-dynamodb';
+
+/**
+ * A utility class for handling DynamoDB pagination.
+ * Use this class when you need to:
+ * - Browse large collections of dinosaurs
+ * - Review extensive security logs
+ * - Analyze habitat inspection history
+ * - Process feeding schedules
+ *
+ * The paginator maintains internal state and automatically handles:
+ * - Page boundaries
+ * - Result set limits
+ * - Continuation tokens
+ *
+ * @example
+ * ```typescript
+ * // List all velociraptors with pagination
+ * const paginator = new QueryBuilder(executor, eq('species', 'Velociraptor'))
+ *   .filter(op => op.eq('status', 'ACTIVE'))
+ *   .paginate(10);
+ *
+ * // Process each page of dinosaurs
+ * while (paginator.hasNextPage()) {
+ *   const page = await paginator.getNextPage();
+ *   console.log(`Processing page ${page.page} of velociraptors`);
+ *
+ *   for (const raptor of page.items) {
+ *     console.log(`- ${raptor.id}: Health=${raptor.stats.health}`);
+ *   }
+ * }
+ * ```
+ *
+ * @typeParam T - The type of items being paginated
+ * @typeParam TConfig - The table configuration type
+ */
+declare class Paginator<T extends DynamoItem, TConfig extends TableConfig = TableConfig> {
+    private queryBuilder;
+    private readonly pageSize;
+    private currentPage;
+    private lastEvaluatedKey?;
+    private hasMorePages;
+    private totalItemsRetrieved;
+    private readonly overallLimit?;
+    constructor(queryBuilder: QueryBuilderInterface<T, TConfig>, pageSize: number);
+    /**
+     * 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
+     * const paginator = new QueryBuilder(executor, eq('species', 'Tyrannosaurus'))
+     *   .paginate(5);
+     *
+     * await paginator.getNextPage();
+     * console.log(`Reviewing T-Rex group ${paginator.getCurrentPage()}`);
+     * ```
+     *
+     * @returns The current page number, starting from 1
+     */
+    getCurrentPage(): number;
+    /**
+     * 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
+     * - Any overall limit set on the query
+     *
+     * @example
+     * ```ts
+     * // Process all security incidents
+     * const paginator = new QueryBuilder(executor, eq('type', 'SECURITY_BREACH'))
+     *   .sortDescending()
+     *   .paginate(10);
+     *
+     * while (paginator.hasNextPage()) {
+     *   const page = await paginator.getNextPage();
+     *   for (const incident of page.items) {
+     *     await processSecurityBreach(incident);
+     *   }
+     *   console.log(`Processed incidents page ${page.page}`);
+     * }
+     * ```
+     *
+     * @returns true if there are more pages available, false otherwise
+     */
+    hasNextPage(): boolean;
+    /**
+     * 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
+     * - Respect for park capacity limits
+     * - Group size adjustments for safety
+     *
+     * @example
+     * ```ts
+     * const paginator = new QueryBuilder(executor, eq('species', 'Velociraptor'))
+     *   .filter(op => op.eq('status', 'ACTIVE'))
+     *   .paginate(5);
+     *
+     * // Check first raptor group
+     * const page1 = await paginator.getNextPage();
+     * console.log(`Found ${page1.items.length} active raptors`);
+     *
+     * // Continue inspection if more groups exist
+     * if (page1.hasNextPage) {
+     *   const page2 = await paginator.getNextPage();
+     *   console.log(`Inspecting raptor group ${page2.page}`);
+     *
+     *   for (const raptor of page2.items) {
+     *     await performHealthCheck(raptor);
+     *   }
+     * }
+     * ```
+     *
+     * @returns A promise that resolves to a PaginationResult containing:
+     *          - items: The dinosaurs/habitats for this page
+     *          - hasNextPage: Whether more groups exist
+     *          - page: The current group number
+     *          - lastEvaluatedKey: DynamoDB's continuation token
+     */
+    getNextPage(): Promise<PaginationResult<T>>;
+    /**
+     * 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
+     * // Get complete carnivore inventory
+     * const paginator = new QueryBuilder(executor, eq('diet', 'CARNIVORE'))
+     *   .filter(op => op.eq('status', 'ACTIVE'))
+     *   .paginate(10);
+     *
+     * try {
+     *   const allCarnivores = await paginator.getAllPages();
+     *   console.log(`Park contains ${allCarnivores.length} active carnivores`);
+     *
+     *   // Calculate total threat level
+     *   const totalThreat = allCarnivores.reduce(
+     *     (sum, dino) => sum + dino.stats.threatLevel,
+     *     0
+     *   );
+     *   console.log(`Total threat level: ${totalThreat}`);
+     * } catch (error) {
+     *   console.error('Failed to complete carnivore census:', error);
+     * }
+     * ```
+     *
+     * @returns A promise that resolves to an array containing all remaining items
+     */
+    getAllPages(): Promise<T[]>;
+}
+
+export { Paginator };