dyno-table 2.5.2 → 2.6.1

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

@@ -0,0 +1,218 @@
+import type { Condition } from "../conditions";
+import type { DynamoItem, TableConfig } from "../types";
+import type { QueryBuilderInterface } from "./builder-types";
+import { FilterBuilder, type FilterOptions } from "./filter-builder";
+import { ResultIterator } from "./result-iterator";
+import type { Path } from "./types";
+/**
+ * Configuration options for DynamoDB query operations.
+ * Extends the base FilterOptions with query-specific options.
+ */
+export 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
+ */
+export 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>;
+    private includeIndexAttributes;
+    private readonly indexAttributeNames;
+    constructor(executor: QueryExecutor<T>, keyCondition: Condition, indexAttributeNames?: string[]);
+    /**
+     * 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;
+    /**
+     * Ensures index attributes are included in the result.
+     * By default, index attributes are removed from query responses.
+     */
+    includeIndexes(): this;
+    select<K extends Path<T>>(fields: K | K[]): 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>>;
+    private addIndexAttributesToSelection;
+    private omitIndexAttributes;
+}
+export {};

package/dist/builders/result-iterator.d.ts

@@ -0,0 +1,55 @@
+import type { DynamoItem, TableConfig } from "../types";
+import type { QueryBuilderInterface } from "./builder-types";
+/**
+ * Function type for executing DynamoDB operations and returning raw results.
+ */
+type DirectExecutor<T extends DynamoItem> = () => Promise<{
+    items: T[];
+    lastEvaluatedKey?: DynamoItem;
+}>;
+/**
+ * Minimal result generator that provides async iteration over DynamoDB results with automatic pagination.
+ *
+ * @example
+ * ```typescript
+ * const results = await queryBuilder.execute();
+ *
+ * for await (const item of results) {
+ *   console.log(item);
+ * }
+ * ```
+ */
+export declare class ResultIterator<T extends DynamoItem, TConfig extends TableConfig = TableConfig> {
+    private queryBuilder;
+    private directExecutor;
+    private lastEvaluatedKey?;
+    private itemsYielded;
+    private readonly overallLimit?;
+    constructor(queryBuilder: QueryBuilderInterface<T, TConfig>, directExecutor: DirectExecutor<T>);
+    /**
+     * Async iterator with automatic pagination
+     */
+    [Symbol.asyncIterator](): AsyncIterableIterator<T>;
+    /**
+     * 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
+     * }
+     * ```
+     */
+    toArray(): Promise<T[]>;
+    /**
+     * Get the last evaluated key
+     */
+    getLastEvaluatedKey(): DynamoItem | undefined;
+}
+export {};

package/dist/builders/scan-builder.d.ts

@@ -0,0 +1,109 @@
+import type { DynamoItem, TableConfig } from "../types";
+import type { ScanBuilderInterface } from "./builder-types";
+import { FilterBuilder, type FilterOptions } from "./filter-builder";
+import { ResultIterator } from "./result-iterator";
+/**
+ * Configuration options for DynamoDB scan operations.
+ * Extends the base FilterOptions.
+ */
+export type ScanOptions = FilterOptions;
+/**
+ * Function type for executing DynamoDB filter operations.
+ * @typeParam T - The type of items being filtered
+ */
+export type ScanExecutor<T extends DynamoItem> = (options: ScanOptions) => Promise<{
+    items: T[];
+    lastEvaluatedKey?: DynamoItem;
+}>;
+/**
+ * Builder for creating DynamoDB scan operations.
+ * Use this builder when you need to:
+ * - Scan all items in a table
+ * - Filter results based on non-key attributes
+ * - Scan items on a Secondary Index (GSI)
+ * - Implement pagination
+ * - Project specific attributes
+ *
+ * The builder supports:
+ * - Type-safe GSI selection
+ * - Complex filter conditions
+ * - Automatic pagination handling
+ * - Consistent reads
+ * - Attribute projection
+ *
+ * @example
+ * ```typescript
+ * // Simple scan with filtering
+ * const result = await new ScanBuilder(executor)
+ *   .filter(op => op.eq('status', 'ACTIVE'))
+ *   .execute();
+ *
+ * // Scan with GSI and filtering
+ * const result = await new ScanBuilder(executor)
+ *   .useIndex('status-index')
+ *   .filter(op => op.gt('securityLevel', 8))
+ *   .select(['id', 'capacity', 'currentOccupants'])
+ *   .limit(10)
+ *   .execute();
+ *
+ * // Scan with pagination
+ * const paginator = new ScanBuilder(executor)
+ *   .filter(op => op.eq('type', 'INCIDENT'))
+ *   .paginate(25);
+ *
+ * while (paginator.hasNextPage()) {
+ *   const page = await paginator.getNextPage();
+ *   // Process page.items
+ * }
+ * ```
+ *
+ * @typeParam T - The type of items being scanned
+ * @typeParam TConfig - The table configuration type for type-safe GSI selection
+ */
+export declare class ScanBuilder<T extends DynamoItem, TConfig extends TableConfig = TableConfig> extends FilterBuilder<T, TConfig> implements ScanBuilderInterface<T, TConfig> {
+    protected readonly executor: ScanExecutor<T>;
+    constructor(executor: ScanExecutor<T>);
+    /**
+     * Creates a deep clone of this ScanBuilder instance.
+     *
+     * @returns A new ScanBuilder instance with the same configuration
+     */
+    clone(): ScanBuilder<T, TConfig>;
+    private deepCloneFilter;
+    /**
+     * Executes the scan 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 all dinosaurs with high aggression levels with automatic pagination
+     *   const results = await new ScanBuilder(executor)
+     *     .filter(op =>
+     *       op.and([
+     *         op.eq('status', 'ACTIVE'),
+     *         op.gt('aggressionLevel', 7)
+     *       ])
+     *     )
+     *     .execute();
+     *
+     *   // Use like an array with automatic pagination
+     *   for await (const dinosaur of results) {
+     *     console.log(`Processing dangerous dinosaur: ${dinosaur.name}`);
+     *   }
+     *
+     *   // Or convert to array and use array methods
+     *   const allItems = await results.toArray();
+     *   const criticalThreats = 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>>;
+}