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

package/dist/query-builder-Csror9Iu.d.ts

@@ -1,507 +0,0 @@
-import { C as Condition, b as ConditionOperator } from './conditions--ld9a78i.js';
-import { Paginator } from './builders/paginator.js';
-import { DynamoItem, TableConfig, GSINames } from './types.js';
-import { F as FilterBuilderInterface, Q as QueryBuilderInterface } from './builder-types-C_PDZhnP.js';
-
-/**
- * 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.
-     * 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: 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.
-     * 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<I extends GSINames<TConfig>>(indexName: I): 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?: boolean): 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: Condition | ((op: ConditionOperator<T>) => Condition)): 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: string | string[]): 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: number): Paginator<T, TConfig>;
-    /**
-     * 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: DynamoItem): this;
-    /**
-     * Creates a deep clone of this builder instance.
-     * Use this method when you need to:
-     * - Query different dinosaur statuses
-     * - Check multiple habitat conditions
-     * - Monitor various security levels
-     * - Create report templates
-     *
-     * 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.
-     * This method must be implemented by subclasses to handle
-     * their specific execution logic.
-     */
-    abstract execute(): Promise<{
-        items: T[];
-        lastEvaluatedKey?: DynamoItem;
-    }>;
-}
-
-/**
- * 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>;
-    /**
-     * 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
-     */
-    execute(): Promise<{
-        items: T[];
-        lastEvaluatedKey?: Record<string, unknown>;
-    }>;
-}
-
-export { FilterBuilder as F, QueryBuilder as Q, type FilterOptions as a, type QueryOptions as b };