dyno-table 2.2.0 → 2.3.0

package/dist/builders/query-builder.cjs

@@ -1,743 +0,0 @@
-'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 inArray = (attr, values) => ({
-  type: "in",
-  attr,
-  value: values
-});
-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).
-   *
-   * @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.
-   *
-   * 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.
-   *
-   * 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
-        };
-      }
-      if (effectivePageSize !== void 0) {
-        effectivePageSize = Math.min(effectivePageSize, remainingItems);
-      } else {
-        effectivePageSize = remainingItems;
-      }
-    }
-    const query = this.queryBuilder.clone();
-    if (effectivePageSize !== void 0) {
-      query.limit(effectivePageSize);
-    }
-    if (this.lastEvaluatedKey) {
-      query.startFrom(this.lastEvaluatedKey);
-    }
-    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;
-    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.
-   *
-   * @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.
-   *
-   * 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.
-   *
-   * @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.
-   *
-   * 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.
-   *
-   * @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) {
-    const newCondition = typeof condition === "function" ? condition(this.getConditionOperator()) : condition;
-    if (this.options.filter) {
-      if (this.options.filter.type === "and" && this.options.filter.conditions) {
-        this.options.filter = {
-          type: "and",
-          conditions: [...this.options.filter.conditions, newCondition]
-        };
-      } else {
-        this.options.filter = and(this.options.filter, newCondition);
-      }
-    } else {
-      this.options.filter = newCondition;
-    }
-    return this;
-  }
-  getConditionOperator() {
-    return {
-      eq,
-      ne,
-      lt,
-      lte,
-      gt,
-      gte,
-      between,
-      inArray,
-      beginsWith,
-      contains,
-      attributeExists,
-      attributeNotExists,
-      and,
-      or,
-      not
-    };
-  }
-  /**
-   * Specifies which attributes to return in the results.
-   *
-   * @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 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();
-   *   console.log(`Processing page ${page.page}, count: ${page.items.length}`);
-   *   // Process dinosaur data
-   * }
-   * ```
-   *
-   * @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
-   */
-  paginate(pageSize) {
-    return new Paginator(this, pageSize);
-  }
-  /**
-   * Sets the starting point using a previous lastEvaluatedKey.
-   *
-   * 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();
-   *
-   * const lastKey = result1.getLastEvaluatedKey();
-   * if (lastKey) {
-   *   // Continue listing dinosaurs
-   *   const result2 = await builder
-   *     .filter(op => op.eq('status', 'ACTIVE'))
-   *     .startFrom(lastKey)
-   *     .limit(5)
-   *     .execute();
-   *
-   *   const items = await result2.toArray();
-   *   console.log('Additional dinosaurs:', 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/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;
-  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,
-      filter: this.deepCloneFilter(this.options.filter)
-    };
-    clone.selectedFields = new Set(this.selectedFields);
-    return clone;
-  }
-  deepCloneFilter(filter) {
-    if (!filter) return filter;
-    if (filter.type === "and" || filter.type === "or") {
-      return {
-        ...filter,
-        conditions: filter.conditions?.map((condition) => this.deepCloneFilter(condition)).filter((c) => c !== void 0)
-      };
-    }
-    return { ...filter };
-  }
-  /**
-   * Executes the query against DynamoDB and returns a generator that behaves like an array.
-   *
-   * 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 with automatic pagination
-   *   const results = 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()
-   *     .execute();
-   *
-   *   // 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 a ResultGenerator that behaves like an array
-   */
-  async execute() {
-    const directExecutor = () => this.executor(this.keyCondition, this.options);
-    return new ResultIterator(this, directExecutor);
-  }
-};
-
-exports.QueryBuilder = QueryBuilder;
-//# sourceMappingURL=query-builder.cjs.map
-//# sourceMappingURL=query-builder.cjs.map