dyno-table 2.2.1 → 2.3.1

package/dist/query-builder-D3URwK9k.d.cts

@@ -1,477 +0,0 @@
-import { a as Condition, b as ConditionOperator, s as Path } from './conditions-CcZL0sR2.cjs';
-import { DynamoItem, TableConfig, GSINames } from './types.cjs';
-import { F as FilterBuilderInterface, R as ResultIterator, Q as QueryBuilderInterface } from './builder-types-BTVhQSHI.cjs';
-import { Paginator } from './builders/paginator.cjs';
-
-/**
- * Configuration options for DynamoDB filter operations.
- * These are common options shared between query and scan operations.
- */
-interface FilterOptions {
-    /** Filter conditions applied to results */
-    filter?: Condition;
-    /** Maximum number of items to return */
-    limit?: number;
-    /** Name of the Global Secondary Index to use */
-    indexName?: string;
-    /** Whether to use strongly consistent reads */
-    consistentRead?: boolean;
-    /** List of attributes to return in the result */
-    projection?: string[];
-    /** Token for starting the operation from a specific point */
-    lastEvaluatedKey?: DynamoItem;
-}
-/**
- * Abstract base builder for creating DynamoDB filter operations.
- * This class provides common functionality for both Query and Scan operations.
- *
- * The builder supports:
- * - Type-safe GSI selection
- * - Complex filter conditions
- * - Pagination
- * - Consistent reads
- * - Attribute projection
- *
- * @typeParam T - The type of items being filtered
- * @typeParam TConfig - The table configuration type for type-safe GSI selection
- */
-declare abstract class FilterBuilder<T extends DynamoItem, TConfig extends TableConfig = TableConfig> implements FilterBuilderInterface<T, TConfig> {
-    protected options: FilterOptions;
-    protected selectedFields: Set<string>;
-    /**
-     * 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: number): 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(): number | undefined;
-    /**
-     * 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<I extends GSINames<TConfig>>(indexName: I): 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?: boolean): 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: Condition | ((op: ConditionOperator<T>) => Condition)): this;
-    private getConditionOperator;
-    /**
-     * 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<K extends Path<T>>(fields: K | K[]): 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?: number): Paginator<T, TConfig>;
-    /**
-     * 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: DynamoItem): this;
-    /**
-     * Creates a deep clone of this builder instance.
-     *
-     * This is particularly useful when:
-     * - Implementing pagination (used internally by paginate())
-     * - Creating operation templates
-     * - Running multiple variations of an operation
-     *
-     * @example
-     * ```typescript
-     * // Create base dinosaur query
-     * const baseBuilder = builder
-     *   .useIndex('status-index')
-     *   .select(['id', 'status', 'location']);
-     *
-     * // Check active dinosaurs
-     * const activeRaptors = baseBuilder.clone()
-     *   .filter(op => op.eq('status', 'HUNTING'))
-     *   .execute();
-     *
-     * // Check contained dinosaurs
-     * const containedRaptors = baseBuilder.clone()
-     *   .filter(op => op.eq('status', 'CONTAINED'))
-     *   .execute();
-     * ```
-     *
-     * @returns A new builder instance with the same configuration
-     */
-    abstract clone(): FilterBuilderInterface<T, TConfig>;
-    /**
-     * Executes the operation against DynamoDB and returns a generator that behaves like an array.
-     * This method must be implemented by subclasses to handle
-     * their specific execution logic.
-     */
-    abstract execute(): Promise<ResultIterator<T, TConfig>>;
-}
-
-/**
- * Configuration options for DynamoDB query operations.
- * Extends the base FilterOptions with query-specific options.
- */
-interface QueryOptions extends FilterOptions {
-    /** Condition for the sort key in the table or index */
-    sortKeyCondition?: Condition;
-    /** Direction of sort key traversal (true for ascending, false for descending) */
-    scanIndexForward?: boolean;
-}
-/**
- * Function type for executing DynamoDB query operations.
- * @typeParam T - The type of items being queried
- */
-type QueryExecutor<T extends DynamoItem> = (keyCondition: Condition, options: QueryOptions) => Promise<{
-    items: T[];
-    lastEvaluatedKey?: Record<string, unknown>;
-}>;
-/**
- * Builder for creating DynamoDB query operations.
- *
- * The builder supports:
- * - Type-safe GSI selection
- * - Complex filter conditions
- * - Automatic pagination handling
- * - Consistent reads
- * - Forward and reverse sorting
- *
- * @example
- * ```typescript
- * // Simple query
- * const result = await new QueryBuilder(executor, eq('userId', '123'))
- *   .execute();
- *
- * // Complex query with GSI and filtering
- * const result = await new QueryBuilder(executor, eq('status', 'ACTIVE'))
- *   .useIndex('status-index')
- *   .filter(op => op.beginsWith('name', 'John'))
- *   .select(['id', 'name', 'email'])
- *   .sortDescending()
- *   .limit(10)
- *   .execute();
- *
- * // Query with pagination
- * const paginator = new QueryBuilder(executor, eq('type', 'order'))
- *   .paginate(25);
- *
- * while (paginator.hasNextPage()) {
- *   const page = await paginator.getNextPage();
- *   // Process page.items
- * }
- * ```
- *
- * @typeParam T - The type of items being queried
- * @typeParam TConfig - The table configuration type for type-safe GSI selection
- */
-declare class QueryBuilder<T extends DynamoItem, TConfig extends TableConfig = TableConfig> extends FilterBuilder<T, TConfig> implements QueryBuilderInterface<T, TConfig> {
-    private readonly keyCondition;
-    protected options: QueryOptions;
-    protected readonly executor: QueryExecutor<T>;
-    constructor(executor: QueryExecutor<T>, keyCondition: Condition);
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * 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(): QueryBuilder<T, TConfig>;
-    private deepCloneFilter;
-    /**
-     * 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
-     */
-    execute(): Promise<ResultIterator<T, TConfig>>;
-}
-
-export { FilterBuilder as F, QueryBuilder as Q, type QueryOptions as a, type FilterOptions as b };