dyno-table 2.5.2 → 2.6.0

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

@@ -0,0 +1,191 @@
+import type { PrimaryKeyWithoutExpression } from "../conditions";
+import type { DynamoItem } from "../types";
+import type { BatchBuilder } from "./batch-builder";
+import type { Path } from "./types";
+/**
+ * Configuration options for DynamoDB get operations.
+ */
+export interface GetOptions {
+    /** List of attributes to return in the result */
+    projection?: string[];
+    /** Whether to use strongly consistent reads */
+    consistentRead?: boolean;
+}
+/**
+ * Parameters for the DynamoDB get command.
+ */
+export interface GetCommandParams {
+    /** The name of the DynamoDB table */
+    tableName: string;
+    /** The primary key of the item to get */
+    key: PrimaryKeyWithoutExpression;
+    /** Comma-separated list of attributes to return */
+    projectionExpression?: string;
+    /** Map of expression attribute name placeholders to actual names */
+    expressionAttributeNames?: Record<string, string>;
+    /** Whether to use strongly consistent reads */
+    consistentRead?: boolean;
+}
+/**
+ * Function type for executing DynamoDB get operations.
+ * @typeParam T - The type of item being retrieved
+ */
+type GetExecutor<T extends DynamoItem> = (params: GetCommandParams) => Promise<{
+    item: T | undefined;
+}>;
+/**
+ * Builder for creating DynamoDB get operations.
+ * Use this builder when you need to:
+ * - Retrieve a single dinosaur by its primary key
+ * - Project specific dinosaur attributes
+ * - Use consistent reads for critical dinosaur data
+ *
+ * @example
+ * ```typescript
+ * // Simple get
+ * const result = await new GetBuilder(executor, { pk: 'dinosaur#123', sk: 'profile' })
+ *   .execute();
+ *
+ * // Get with projection and consistent read
+ * const result = await new GetBuilder(executor, { pk: 'dinosaur#123', sk: 'profile' })
+ *   .select(['species', 'name', 'diet'])
+ *   .consistentRead()
+ *   .execute();
+ * ```
+ *
+ * @typeParam T - The type of item being retrieved
+ */
+export declare class GetBuilder<T extends DynamoItem> {
+    private readonly executor;
+    private readonly params;
+    private options;
+    private selectedFields;
+    private includeIndexAttributes;
+    private readonly indexAttributeNames;
+    /**
+     * Creates a new GetBuilder instance.
+     *
+     * @param executor - Function that executes the get operation
+     * @param key - Primary key of the item to retrieve
+     * @param tableName - Name of the DynamoDB table
+     */
+    constructor(executor: GetExecutor<T>, key: PrimaryKeyWithoutExpression, tableName: string, indexAttributeNames?: string[]);
+    /**
+     * Specifies which attributes to return in the get results.
+     *
+     * @example
+     * ```typescript
+     * // Select single attribute
+     * builder.select('species')
+     *
+     * // Select multiple attributes
+     * builder.select(['id', 'species', 'diet'])
+     *
+     * // Chain multiple select calls
+     * builder
+     *   .select('id')
+     *   .select(['species', 'diet'])
+     * ```
+     *
+     * @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[]): GetBuilder<T>;
+    /**
+     * Ensures index attributes are included in the result.
+     * By default, index attributes are removed from get responses.
+     */
+    includeIndexes(): GetBuilder<T>;
+    /**
+     * Sets whether to use strongly consistent reads for the get operation.
+     * Use this method when you need:
+     * - The most up-to-date dinosaur data
+     * - To ensure you're reading the latest dinosaur status
+     * - Critical safety information about dangerous species
+     *
+     * Note: Consistent reads consume twice the throughput
+     *
+     * @example
+     * ```typescript
+     * // Get the latest T-Rex data
+     * const result = await new GetBuilder(executor, { pk: 'dinosaur#123', sk: 'profile' })
+     *   .consistentRead()
+     *   .execute();
+     * ```
+     *
+     * @param consistentRead - Whether to use consistent reads (defaults to true)
+     * @returns The builder instance for method chaining
+     */
+    consistentRead(consistentRead?: boolean): GetBuilder<T>;
+    /**
+     * Adds this get operation to a batch with optional entity type information.
+     *
+     * @example Basic Usage
+     * ```ts
+     * const batch = table.batchBuilder();
+     *
+     * // Add multiple get operations to batch
+     * dinosaurRepo.get({ id: 'dino-1' }).withBatch(batch);
+     * dinosaurRepo.get({ id: 'dino-2' }).withBatch(batch);
+     * dinosaurRepo.get({ id: 'dino-3' }).withBatch(batch);
+     *
+     * // Execute all gets efficiently
+     * const results = await batch.execute();
+     * ```
+     *
+     * @example Typed Usage
+     * ```ts
+     * const batch = table.batchBuilder<{
+     *   User: UserEntity;
+     *   Order: OrderEntity;
+     * }>();
+     *
+     * // Add operations with type information
+     * userRepo.get({ id: 'user-1' }).withBatch(batch, 'User');
+     * orderRepo.get({ id: 'order-1' }).withBatch(batch, 'Order');
+     *
+     * // Execute and get typed results
+     * const result = await batch.execute();
+     * const users: UserEntity[] = result.reads.itemsByType.User;
+     * const orders: OrderEntity[] = result.reads.itemsByType.Order;
+     * ```
+     *
+     * @param batch - The batch builder to add this operation to
+     * @param entityType - Optional entity type key for type tracking
+     */
+    withBatch<TEntities extends Record<string, DynamoItem> = Record<string, DynamoItem>, K extends keyof TEntities = keyof TEntities>(batch: BatchBuilder<TEntities>, entityType?: K): void;
+    /**
+     * Converts the builder configuration to a DynamoDB command
+     */
+    private toDynamoCommand;
+    private addIndexAttributesToSelection;
+    private omitIndexAttributes;
+    /**
+     * Executes the get operation against DynamoDB.
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const result = await new GetBuilder(executor, { pk: 'dinosaur#123', sk: 'profile' })
+     *     .select(['species', 'name', 'diet'])
+     *     .consistentRead()
+     *     .execute();
+     *
+     *   if (result.item) {
+     *     console.log('Dinosaur found:', result.item);
+     *   } else {
+     *     console.log('Dinosaur not found');
+     *   }
+     * } catch (error) {
+     *   console.error('Error getting dinosaur:', error);
+     * }
+     * ```
+     *
+     * @returns A promise that resolves to an object containing:
+     *          - item: The retrieved dinosaur or undefined if not found
+     */
+    execute(): Promise<{
+        item: T | undefined;
+    }>;
+}
+export {};

package/dist/builders/index.d.ts

@@ -0,0 +1,14 @@
+export { BatchBuilder } from "./batch-builder.js";
+export type * from "./builder-types.js";
+export { ConditionCheckBuilder } from "./condition-check-builder.js";
+export { DeleteBuilder } from "./delete-builder.js";
+export { FilterBuilder } from "./filter-builder.js";
+export { GetBuilder } from "./get-builder.js";
+export { Paginator } from "./paginator.js";
+export { PutBuilder } from "./put-builder.js";
+export { QueryBuilder } from "./query-builder.js";
+export { ResultIterator } from "./result-iterator.js";
+export { ScanBuilder } from "./scan-builder.js";
+export { TransactionBuilder } from "./transaction-builder.js";
+export type * from "./types.js";
+export { UpdateBuilder } from "./update-builder.js";

package/dist/builders/paginator.d.ts

@@ -0,0 +1,151 @@
+import type { DynamoItem, TableConfig } from "../types";
+import type { PaginationResult, QueryBuilderInterface } from "./builder-types";
+/**
+ * A utility class for handling DynamoDB pagination.
+ * Use this class when you need to:
+ * - Browse large collections of dinosaurs
+ * - Review extensive security logs
+ * - Analyze habitat inspection history
+ * - Process feeding schedules
+ *
+ * The paginator maintains internal state and automatically handles:
+ * - Page boundaries
+ * - Result set limits
+ * - Continuation tokens
+ *
+ * @example
+ * ```typescript
+ * // List all velociraptors with pagination
+ * const paginator = new QueryBuilder(executor, eq('species', 'Velociraptor'))
+ *   .filter(op => op.eq('status', 'ACTIVE'))
+ *   .paginate(10);
+ *
+ * // Process each page of dinosaurs
+ * while (paginator.hasNextPage()) {
+ *   const page = await paginator.getNextPage();
+ *   console.log(`Processing page ${page.page} of velociraptors`);
+ *
+ *   for (const raptor of page.items) {
+ *     console.log(`- ${raptor.id}: Health=${raptor.stats.health}`);
+ *   }
+ * }
+ * ```
+ *
+ * @typeParam T - The type of items being paginated
+ * @typeParam TConfig - The table configuration type
+ */
+export declare class Paginator<T extends DynamoItem, TConfig extends TableConfig = TableConfig> {
+    private queryBuilder;
+    private readonly pageSize?;
+    private currentPage;
+    private lastEvaluatedKey?;
+    private hasMorePages;
+    private totalItemsRetrieved;
+    private readonly overallLimit?;
+    constructor(queryBuilder: QueryBuilderInterface<T, TConfig>, pageSize?: number);
+    /**
+     * 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(): number;
+    /**
+     * 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(): boolean;
+    /**
+     * 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
+     */
+    getNextPage(): Promise<PaginationResult<T>>;
+    /**
+     * 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
+     */
+    getAllPages(): Promise<T[]>;
+}

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

@@ -0,0 +1,317 @@
+import type { Condition, ConditionOperator } from "../conditions";
+import type { DynamoItem } from "../types";
+import type { BatchBuilder } from "./batch-builder";
+import type { PutCommandParams } from "./builder-types";
+import type { TransactionBuilder } from "./transaction-builder";
+import type { Path, PathType } from "./types";
+/**
+ * Configuration options for DynamoDB put operations.
+ */
+export interface PutOptions {
+    /** Optional condition that must be satisfied for the put operation to succeed */
+    condition?: Condition;
+    /** Determines how to handle the return value of the put operation
+     * @options
+     *  - NONE: No return value
+     *  - ALL_OLD: Returns the item's previous state if it existed
+     *  - CONSISTENT: Performs a GET operation after the put to retrieve the item's new state
+     *  - INPUT: Returns the input values that were passed to the operation
+     */
+    returnValues?: "ALL_OLD" | "NONE" | "CONSISTENT" | "INPUT";
+}
+type PutExecutor<T extends DynamoItem> = (params: PutCommandParams) => Promise<T>;
+/**
+ * Builder for creating DynamoDB put operations.
+ *
+ * @example
+ * ```typescript
+ * // Add new dinosaur
+ * const result = await new PutBuilder(executor, {
+ *   id: 'RAPTOR-001',
+ *   species: 'Velociraptor',
+ *   status: 'ACTIVE',
+ *   stats: {
+ *     health: 100,
+ *     age: 5,
+ *     threatLevel: 8
+ *   }
+ * }, 'dinosaurs').execute();
+ *
+ * // Create new habitat with conditions
+ * const result = await new PutBuilder(executor, {
+ *   id: 'PADDOCK-C',
+ *   type: 'CARNIVORE',
+ *   securityLevel: 'MAXIMUM',
+ *   capacity: 3,
+ *   environmentType: 'TROPICAL'
+ * }, 'habitats')
+ *   .condition(op => op.attributeNotExists('id'))
+ *   .execute();
+ * ```
+ *
+ * @typeParam T - The type of item being put into the table
+ */
+export declare class PutBuilder<T extends DynamoItem> {
+    private readonly item;
+    private options;
+    private readonly executor;
+    private readonly tableName;
+    constructor(executor: PutExecutor<T>, item: T, tableName: string);
+    /**
+     * Sets multiple attributes of an item using an DynamoItem.
+     *
+     * @example
+     * ```typescript
+     * // Update multiple attributes
+     * builder.set({
+     *   species: 'Tyrannosaurus Rex',
+     *   height: 20,
+     *   diet: 'CARNIVORE',
+     *   'stats.threatLevel': 10
+     * });
+     * ```
+     */
+    set(values: Partial<T>): this;
+    /**
+     * Sets a single attribute to a specific value.
+     *
+     * @example
+     * ```typescript
+     * // Set simple attributes
+     * builder
+     *   .set('status', 'SLEEPING')
+     *   .set('lastFeeding', new Date().toISOString());
+     *
+     * // Set nested attributes
+     * builder
+     *   .set('location.zone', 'RESTRICTED')
+     *   .set('stats.health', 100);
+     * ```
+     */
+    set<K extends Path<T>>(path: K, value: PathType<T, K>): this;
+    /**
+     * Adds a condition that must be satisfied for the put operation to succeed.
+     *
+     * @example
+     * ```ts
+     * // Ensure item doesn't exist (insert only)
+     * builder.condition(op => op.attributeNotExists('id'))
+     *
+     * // Complex condition with version check
+     * builder.condition(op =>
+     *   op.and([
+     *     op.attributeExists('id'),
+     *     op.eq('version', currentVersion),
+     *     op.eq('status', 'ACTIVE')
+     *   ])
+     * )
+     * ```
+     *
+     * @param condition - Either a Condition object or a callback function that builds the condition
+     * @returns The builder instance for method chaining
+     */
+    /**
+     * Adds a condition that must be satisfied for the put operation to succeed.
+     *
+     * @example
+     * ```typescript
+     * // Ensure unique dinosaur ID
+     * builder.condition(op =>
+     *   op.attributeNotExists('id')
+     * );
+     *
+     * // Verify habitat requirements
+     * builder.condition(op =>
+     *   op.and([
+     *     op.eq('securityStatus', 'READY'),
+     *     op.attributeExists('lastInspection'),
+     *     op.gt('securityLevel', 5)
+     *   ])
+     * );
+     *
+     * // Check breeding facility conditions
+     * builder.condition(op =>
+     *   op.and([
+     *     op.between('temperature', 25, 30),
+     *     op.between('humidity', 60, 80),
+     *     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
+     */
+    condition(condition: Condition | ((op: ConditionOperator<T>) => Condition)): this;
+    /**
+     * Sets whether to return the item's previous values (if it existed).
+     *
+     * @options
+     *  - NONE: No return value
+     *  - ALL_OLD: Returns the item's previous state if it existed, no read capacity units are consumed
+     *  - CONSISTENT: Performs a GET operation after the put to retrieve the item's new state
+     *  - INPUT: Returns the input values that were passed to the operation
+     *
+     * @example
+     * ```ts
+     * // Get previous dinosaur state
+     * const result = await builder
+     *   .returnValues('ALL_OLD')
+     *   .execute();
+     *
+     * if (result) {
+     *   console.log('Previous profile:', {
+     *     species: result.species,
+     *     status: result.status,
+     *     stats: {
+     *       health: result.stats.health,
+     *       threatLevel: result.stats.threatLevel
+     *     }
+     *   });
+     * }
+     *
+     * // Return input values for create operations
+     * const createResult = await builder
+     *   .returnValues('INPUT')
+     *   .execute();
+     * ```
+     *
+     * @param returnValues - Use 'ALL_OLD' to return previous values, 'INPUT' to return input values, 'CONSISTENT' for fresh data, or 'NONE' (default).
+     * @returns The builder instance for method chaining
+     */
+    returnValues(returnValues: "ALL_OLD" | "NONE" | "CONSISTENT" | "INPUT"): this;
+    /**
+     * Generate the DynamoDB command parameters
+     */
+    private toDynamoCommand;
+    /**
+     * Adds this put operation to a transaction.
+     *
+     * @example
+     * ```ts
+     * const transaction = new TransactionBuilder();
+     *
+     * // Add dinosaur to new habitat
+     * new PutBuilder(executor, {
+     *   id: 'TREX-002',
+     *   location: 'PADDOCK-B',
+     *   status: 'ACTIVE',
+     *   transferDate: new Date().toISOString()
+     * }, 'dinosaurs')
+     *   .withTransaction(transaction);
+     *
+     * // Update habitat records
+     * new UpdateBuilder(executor, 'habitats', { id: 'PADDOCK-B' })
+     *   .add('occupants', 1)
+     *   .set('lastTransfer', new Date().toISOString())
+     *   .withTransaction(transaction);
+     *
+     * // Execute transfer atomically
+     * await transaction.execute();
+     * ```
+     *
+     * @param transaction - The transaction builder to add this operation to
+     * @returns The builder instance for method chaining
+     */
+    withTransaction(transaction: TransactionBuilder): this;
+    /**
+     * Adds this put operation to a batch with optional entity type information.
+     *
+     * @example Basic Usage
+     * ```ts
+     * const batch = table.batchBuilder();
+     *
+     * // Add multiple dinosaurs to batch
+     * dinosaurRepo.create(newDino1).withBatch(batch);
+     * dinosaurRepo.create(newDino2).withBatch(batch);
+     * dinosaurRepo.create(newDino3).withBatch(batch);
+     *
+     * // Execute all operations efficiently
+     * await batch.execute();
+     * ```
+     *
+     * @example Typed Usage
+     * ```ts
+     * const batch = table.batchBuilder<{
+     *   User: UserEntity;
+     *   Order: OrderEntity;
+     * }>();
+     *
+     * // Add operations with type information
+     * userRepo.create(newUser).withBatch(batch, 'User');
+     * orderRepo.create(newOrder).withBatch(batch, 'Order');
+     *
+     * // Execute and get typed results
+     * const result = await batch.execute();
+     * const users: UserEntity[] = result.reads.itemsByType.User;
+     * ```
+     *
+     * @param batch - The batch builder to add this operation to
+     * @param entityType - Optional entity type key for type tracking
+     */
+    withBatch<TEntities extends Record<string, DynamoItem> = Record<string, DynamoItem>, K extends keyof TEntities = keyof TEntities>(batch: BatchBuilder<TEntities>, entityType?: K): void;
+    /**
+     * Executes the put operation against DynamoDB.
+     *
+     * @example
+     * ```ts
+     * try {
+     *   // Put with condition and return old values
+     *   const result = await new PutBuilder(executor, newItem, 'myTable')
+     *     .condition(op => op.eq('version', 1))
+     *     .returnValues('ALL_OLD')
+     *     .execute();
+     *
+     *   console.log('Put successful, old item:', result);
+     * } catch (error) {
+     *   // Handle condition check failure or other errors
+     *   console.error('Put failed:', error);
+     * }
+     * ```
+     *
+     * @returns A promise that resolves to the operation result (type depends on returnValues setting)
+     * @throws Will throw an error if the condition check fails or other DynamoDB errors occur
+     */
+    execute(): Promise<T | undefined>;
+    /**
+     * Gets a human-readable representation of the put command
+     * with all expression placeholders replaced by their actual values.
+     *
+     * @example
+     * ```ts
+     * const debugInfo = new PutBuilder(executor, {
+     *   id: 'RAPTOR-003',
+     *   species: 'Velociraptor',
+     *   status: 'QUARANTINE',
+     *   stats: {
+     *     health: 100,
+     *     aggressionLevel: 7,
+     *     age: 2
+     *   }
+     * }, 'dinosaurs')
+     *   .condition(op =>
+     *     op.and([
+     *       op.attributeNotExists('id'),
+     *       op.eq('quarantineStatus', 'READY'),
+     *       op.gt('securityLevel', 8)
+     *     ])
+     *   )
+     *   .debug();
+     *
+     * console.log('Dinosaur transfer command:', debugInfo);
+     * ```
+     *
+     * @returns A readable representation of the put command with resolved expressions
+     */
+    debug(): {
+        raw: PutCommandParams;
+        readable: {
+            conditionExpression?: string;
+            updateExpression?: string;
+            filterExpression?: string;
+            keyConditionExpression?: string;
+            projectionExpression?: string;
+        };
+    };
+}
+export {};