dyno-table 1.0.0-alpha.1 → 1.1.0

package/dist/builders/query-builder.cjs

@@ -0,0 +1,674 @@
+'use strict';
+
+// src/conditions.ts
+var createComparisonCondition = (type) => (attr, value) => ({
+  type,
+  attr,
+  value
+});
+var eq = createComparisonCondition("eq");
+var ne = createComparisonCondition("ne");
+var lt = createComparisonCondition("lt");
+var lte = createComparisonCondition("lte");
+var gt = createComparisonCondition("gt");
+var gte = createComparisonCondition("gte");
+var between = (attr, lower, upper) => ({
+  type: "between",
+  attr,
+  value: [lower, upper]
+});
+var beginsWith = createComparisonCondition("beginsWith");
+var contains = createComparisonCondition("contains");
+var attributeExists = (attr) => ({
+  type: "attributeExists",
+  attr
+});
+var attributeNotExists = (attr) => ({
+  type: "attributeNotExists",
+  attr
+});
+var and = (...conditions) => ({
+  type: "and",
+  conditions
+});
+var or = (...conditions) => ({
+  type: "or",
+  conditions
+});
+var not = (condition) => ({
+  type: "not",
+  condition
+});
+
+// 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;
+  }
+};
+
+// src/builders/filter-builder.ts
+var FilterBuilder = class {
+  options = {};
+  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.
+   *
+   * @example
+   * ```typescript
+   * // Get first 10 dinosaurs
+   * const result = await builder
+   *   .limit(10)
+   *   .execute();
+   * ```
+   *
+   * @param limit - Maximum number of items to return
+   * @returns The builder instance for method chaining
+   */
+  limit(limit) {
+    this.options.limit = limit;
+    return this;
+  }
+  /**
+   * Gets the current limit set on the operation.
+   * This is used internally by the paginator to manage result sets.
+   *
+   * @returns The current limit or undefined if no limit is set
+   */
+  getLimit() {
+    return this.options.limit;
+  }
+  /**
+   * 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
+   * // Find all dinosaurs of a specific species
+   * builder
+   *   .useIndex('species-status-index')
+   *   .filter(op => op.eq('status', 'ACTIVE'));
+   *
+   * // Search high-security habitats
+   * builder
+   *   .useIndex('security-level-index')
+   *   .filter(op =>
+   *     op.and([
+   *       op.gt('securityLevel', 8),
+   *       op.eq('status', 'OPERATIONAL')
+   *     ])
+   *   );
+   * ```
+   *
+   * @param indexName - The name of the GSI to use (type-safe based on table configuration)
+   * @returns The builder instance for method chaining
+   */
+  useIndex(indexName) {
+    this.options.indexName = indexName;
+    return 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
+   * - Consistent reads consume twice the throughput
+   * - Default is eventually consistent reads
+   *
+   * @example
+   * ```typescript
+   * // Check immediate dinosaur status
+   * const result = await builder
+   *   .filter(op => op.eq('status', 'ACTIVE'))
+   *   .consistentRead()
+   *   .execute();
+   *
+   * // Monitor security breaches
+   * const result = await builder
+   *   .useIndex('primary-index')
+   *   .consistentRead(isEmergencyMode)
+   *   .execute();
+   * ```
+   *
+   * @param consistentRead - Whether to use consistent reads (defaults to true)
+   * @returns The builder instance for method chaining
+   */
+  consistentRead(consistentRead = true) {
+    this.options.consistentRead = consistentRead;
+    return 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
+   * // Find aggressive carnivores
+   * builder.filter(op =>
+   *   op.and([
+   *     op.eq('diet', 'CARNIVORE'),
+   *     op.gt('aggressionLevel', 7),
+   *     op.eq('status', 'ACTIVE')
+   *   ])
+   * );
+   *
+   * // Search suitable breeding habitats
+   * builder.filter(op =>
+   *   op.and([
+   *     op.between('temperature', 25, 30),
+   *     op.lt('currentOccupants', 3),
+   *     op.eq('quarantineStatus', 'CLEAR')
+   *   ])
+   * );
+   * ```
+   *
+   * @param condition - Either a Condition object or a callback function that builds the condition
+   * @returns The builder instance for method chaining
+   */
+  filter(condition) {
+    if (typeof condition === "function") {
+      const conditionOperator = {
+        eq,
+        ne,
+        lt,
+        lte,
+        gt,
+        gte,
+        between,
+        beginsWith,
+        contains,
+        attributeExists,
+        attributeNotExists,
+        and,
+        or,
+        not
+      };
+      this.options.filter = condition(conditionOperator);
+    } else {
+      this.options.filter = condition;
+    }
+    return 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
+   * // Get basic dinosaur info
+   * builder.select([
+   *   'species',
+   *   'status',
+   *   'stats.health',
+   *   'stats.aggressionLevel'
+   * ]);
+   *
+   * // Monitor habitat conditions
+   * builder
+   *   .select('securityStatus')
+   *   .select([
+   *     'currentOccupants',
+   *     'temperature',
+   *     'lastInspectionDate'
+   *   ]);
+   * ```
+   *
+   * @param fields - A single field name or an array of field names to return
+   * @returns The builder instance for method chaining
+   */
+  select(fields) {
+    if (typeof fields === "string") {
+      this.selectedFields.add(fields);
+    } else if (Array.isArray(fields)) {
+      for (const field of fields) {
+        this.selectedFields.add(field);
+      }
+    }
+    this.options.projection = Array.from(this.selectedFields);
+    return this;
+  }
+  /**
+   * Creates a paginator that handles DynamoDB pagination automatically.
+   * The paginator handles:
+   * - Tracking the last evaluated key
+   * - Managing page boundaries
+   * - Respecting overall query limits
+   *
+   * @example
+   * ```typescript
+   * // Create a paginator for dinosaur records
+   * const paginator = builder
+   *   .filter(op => op.eq('status', 'ACTIVE'))
+   *   .paginate(10);
+   *
+   * // Process pages of dinosaur results
+   * while (paginator.hasNextPage()) {
+   *   const page = await paginator.getNextPage();
+   *   console.log(`Processing page ${page.page}, count: ${page.items.length}`);
+   *   // Process dinosaur data
+   * }
+   * ```
+   *
+   * @param pageSize - The number of items to return per page
+   * @returns A Paginator instance that manages the pagination state
+   * @see Paginator for more pagination control options
+   */
+  paginate(pageSize) {
+    return new Paginator(this, pageSize);
+  }
+  /**
+   * 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.
+   *
+   * @example
+   * ```typescript
+   * // First batch of dinosaurs
+   * const result1 = await builder
+   *   .filter(op => op.eq('status', 'ACTIVE'))
+   *   .limit(5)
+   *   .execute();
+   *
+   * if (result1.lastEvaluatedKey) {
+   *   // Continue listing dinosaurs
+   *   const result2 = await builder
+   *     .filter(op => op.eq('status', 'ACTIVE'))
+   *     .startFrom(result1.lastEvaluatedKey)
+   *     .limit(5)
+   *     .execute();
+   *
+   *   console.log('Additional dinosaurs:', result2.items);
+   * }
+   * ```
+   *
+   * @param lastEvaluatedKey - The exclusive start key from a previous result
+   * @returns The builder instance for method chaining
+   */
+  startFrom(lastEvaluatedKey) {
+    this.options.lastEvaluatedKey = lastEvaluatedKey;
+    return this;
+  }
+};
+
+// src/builders/query-builder.ts
+var QueryBuilder = class _QueryBuilder extends FilterBuilder {
+  keyCondition;
+  options = {};
+  executor;
+  constructor(executor, keyCondition) {
+    super();
+    this.executor = executor;
+    this.keyCondition = keyCondition;
+  }
+  /**
+   * Sets the maximum number of items to return from the query.
+   *
+   * Note: This is the default behavior if no sort order is specified.
+   *
+   * @example
+   * ```typescript
+   * // Get orders in chronological order
+   * const result = await new QueryBuilder(executor, eq('userId', '123'))
+   *   .sortAscending()
+   *   .execute();
+   *
+   * // Get events from oldest to newest
+   * const result = await new QueryBuilder(executor, eq('entityId', 'order-123'))
+   *   .useIndex('entity-timestamp-index')
+   *   .sortAscending()
+   *   .execute();
+   * ```
+   *
+   * @returns The builder instance for method chaining
+   */
+  /**
+   * Sets the query to return items in ascending order by sort key.
+   *
+   * @example
+   * ```typescript
+   * // List dinosaurs by age
+   * const result = await new QueryBuilder(executor, eq('species', 'Velociraptor'))
+   *   .useIndex('age-index')
+   *   .sortAscending()
+   *   .execute();
+   *
+   * // View incidents chronologically
+   * const result = await new QueryBuilder(executor, eq('type', 'SECURITY_BREACH'))
+   *   .useIndex('date-index')
+   *   .sortAscending()
+   *   .execute();
+   * ```
+   *
+   * @returns The builder instance for method chaining
+   */
+  sortAscending() {
+    this.options.scanIndexForward = true;
+    return this;
+  }
+  /**
+   * Sets the query to return items in descending order by sort key.
+   *
+   * @example
+   * ```typescript
+   * // Get most recent security incidents
+   * const result = await new QueryBuilder(executor, eq('type', 'SECURITY_BREACH'))
+   *   .useIndex('date-index')
+   *   .sortDescending()
+   *   .limit(10)
+   *   .execute();
+   *
+   * // Check latest dinosaur activities
+   * const result = await new QueryBuilder(executor, eq('species', 'Velociraptor'))
+   *   .useIndex('activity-time-index')
+   *   .filter(op => op.eq('status', 'ACTIVE'))
+   *   .sortDescending()
+   *   .execute();
+   * ```
+   *
+   * @returns The builder instance for method chaining
+   */
+  sortDescending() {
+    this.options.scanIndexForward = false;
+    return this;
+  }
+  /**
+   * Creates a deep clone of this QueryBuilder instance.
+   *
+   * This is particularly useful when:
+   * - Implementing pagination (used internally by paginate())
+   * - Creating query templates
+   * - Running multiple variations of a query
+   *
+   * @example
+   * ```typescript
+   * // Create base dinosaur query
+   * const baseQuery = new QueryBuilder(executor, eq('species', 'Velociraptor'))
+   *   .useIndex('status-index')
+   *   .select(['id', 'status', 'location']);
+   *
+   * // Check active dinosaurs
+   * const activeRaptors = baseQuery.clone()
+   *   .filter(op => op.eq('status', 'HUNTING'))
+   *   .execute();
+   *
+   * // Check contained dinosaurs
+   * const containedRaptors = baseQuery.clone()
+   *   .filter(op => op.eq('status', 'CONTAINED'))
+   *   .execute();
+   *
+   * // Check sedated dinosaurs
+   * const sedatedRaptors = baseQuery.clone()
+   *   .filter(op => op.eq('status', 'SEDATED'))
+   *   .execute();
+   * ```
+   *
+   * @returns A new QueryBuilder instance with the same configuration
+   */
+  clone() {
+    const clone = new _QueryBuilder(this.executor, this.keyCondition);
+    clone.options = { ...this.options };
+    clone.selectedFields = new Set(this.selectedFields);
+    return clone;
+  }
+  /**
+   * Executes the query against DynamoDB.
+   *
+   * 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.
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   // Find active carnivores in specific habitat
+   *   const result = await new QueryBuilder(executor, eq('habitatId', 'PADDOCK-A'))
+   *     .useIndex('species-status-index')
+   *     .filter(op =>
+   *       op.and([
+   *         op.eq('diet', 'CARNIVORE'),
+   *         op.eq('status', 'ACTIVE'),
+   *         op.gt('aggressionLevel', 7)
+   *       ])
+   *     )
+   *     .sortDescending()
+   *     .limit(5)
+   *     .execute();
+   *
+   *   console.log(`Found ${result.items.length} dangerous dinosaurs`);
+   *
+   *   if (result.lastEvaluatedKey) {
+   *     console.log('Additional threats detected');
+   *   }
+   * } 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
+   */
+  async execute() {
+    return this.executor(this.keyCondition, this.options);
+  }
+};
+
+exports.QueryBuilder = QueryBuilder;
+//# sourceMappingURL=query-builder.cjs.map
+//# sourceMappingURL=query-builder.cjs.map