dyno-table 0.2.0-0 → 1.0.0-alpha.1

package/dist/builders/query-builder.js

@@ -1,672 +0,0 @@
-// 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);
-  }
-};
-
-export { QueryBuilder };
-//# sourceMappingURL=query-builder.js.map
-//# sourceMappingURL=query-builder.js.map