dyno-table 1.0.0-alpha.1 → 1.0.0

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

@@ -0,0 +1,507 @@
+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 };