dyno-table 2.5.1 → 2.6.0

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

@@ -0,0 +1,208 @@
+import type { Condition, ConditionOperator, PrimaryKeyWithoutExpression } from "../conditions";
+import type { DynamoItem } from "../types";
+import type { BatchBuilder } from "./batch-builder";
+import type { DeleteCommandParams } from "./builder-types";
+import type { TransactionBuilder } from "./transaction-builder";
+export interface DeleteOptions {
+    condition?: Condition;
+    returnValues?: "ALL_OLD";
+}
+type DeleteExecutor = (params: DeleteCommandParams) => Promise<{
+    item?: DynamoItem;
+}>;
+/**
+ * Builder for creating DynamoDB delete operations.
+ *
+ * @example
+ * ```typescript
+ * // Simple delete
+ * const result = await new DeleteBuilder(executor, 'dinosaurs', { id: 'TREX-001' })
+ *   .execute();
+ *
+ * // Conditional delete with old value retrieval
+ * const result = await new DeleteBuilder(executor, 'habitats', { id: 'PADDOCK-A' })
+ *   .condition(op =>
+ *     op.and([
+ *       op.eq('status', 'DECOMMISSIONED'),
+ *       op.eq('occupants', 0),
+ *       op.lt('securityIncidents', 1)
+ *     ])
+ *   )
+ *   .returnValues('ALL_OLD')
+ *   .execute();
+ * ```
+ */
+export declare class DeleteBuilder {
+    private options;
+    private readonly executor;
+    private readonly tableName;
+    private readonly key;
+    constructor(executor: DeleteExecutor, tableName: string, key: PrimaryKeyWithoutExpression);
+    /**
+     * Adds a condition that must be satisfied for the delete operation to succeed.
+     *
+     * @example
+     * ```typescript
+     * // Ensure dinosaur can be safely removed
+     * builder.condition(op =>
+     *   op.and([
+     *     op.eq('status', 'SEDATED'),
+     *     op.eq('location', 'MEDICAL_BAY'),
+     *     op.attributeExists('lastCheckup')
+     *   ])
+     * );
+     *
+     * // Verify habitat is empty
+     * builder.condition(op =>
+     *   op.and([
+     *     op.eq('occupants', 0),
+     *     op.eq('maintenanceStatus', 'COMPLETE'),
+     *     op.not(op.attributeExists('activeAlerts'))
+     *   ])
+     * );
+     * ```
+     *
+     * @param condition - Either a Condition object or a callback function that builds the condition
+     * @returns The builder instance for method chaining
+     */
+    condition<T extends DynamoItem>(condition: Condition | ((op: ConditionOperator<T>) => Condition)): DeleteBuilder;
+    /**
+     * Sets whether to return the item's attribute values before deletion.
+     *
+     * @example
+     * ```ts
+     * // Archive dinosaur data before removal
+     * const result = await builder
+     *   .returnValues('ALL_OLD')
+     *   .execute();
+     *
+     * if (result.item) {
+     *   console.log('Removed dinosaur data:', {
+     *     species: result.item.species,
+     *     age: result.item.age,
+     *     lastLocation: result.item.location
+     *   });
+     * }
+     * ```
+     *
+     * @param returnValues - Use 'ALL_OLD' to return all attributes of the deleted item
+     * @returns The builder instance for method chaining
+     */
+    returnValues(returnValues: "ALL_OLD"): DeleteBuilder;
+    /**
+     * Generate the DynamoDB command parameters
+     */
+    private toDynamoCommand;
+    /**
+     * Adds this delete operation to a transaction.
+     *
+     * @example
+     * ```ts
+     * const transaction = new TransactionBuilder();
+     *
+     * // Remove dinosaur from old habitat
+     * new DeleteBuilder(executor, 'dinosaurs', { id: 'RAPTOR-001' })
+     *   .condition(op => op.eq('status', 'SEDATED'))
+     *   .withTransaction(transaction);
+     *
+     * // Update old habitat occupancy
+     * new UpdateBuilder(executor, 'habitats', { id: 'PADDOCK-A' })
+     *   .add('occupants', -1)
+     *   .withTransaction(transaction);
+     *
+     * // Execute transfer atomically
+     * await transaction.execute();
+     * ```
+     *
+     * @param transaction - The transaction builder to add this operation to
+     */
+    withTransaction(transaction: TransactionBuilder): void;
+    /**
+     * Adds this delete operation to a batch with optional entity type information.
+     *
+     * @example Basic Usage
+     * ```ts
+     * const batch = table.batchBuilder();
+     *
+     * // Remove multiple dinosaurs in batch
+     * dinosaurRepo.delete({ id: 'old-dino-1' }).withBatch(batch);
+     * dinosaurRepo.delete({ id: 'old-dino-2' }).withBatch(batch);
+     * dinosaurRepo.delete({ id: 'old-dino-3' }).withBatch(batch);
+     *
+     * // Execute all deletions efficiently
+     * await batch.execute();
+     * ```
+     *
+     * @example Typed Usage
+     * ```ts
+     * const batch = table.batchBuilder<{
+     *   User: UserEntity;
+     *   Order: OrderEntity;
+     * }>();
+     *
+     * // Add operations with type information
+     * userRepo.delete({ id: 'user-1' }).withBatch(batch, 'User');
+     * orderRepo.delete({ id: 'order-1' }).withBatch(batch, 'Order');
+     *
+     * // Execute batch operations
+     * await batch.execute();
+     * ```
+     *
+     * @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 delete operation against DynamoDB.
+     *
+     * @example
+     * ```ts
+     * // Delete with condition and retrieve old values
+     * const result = await new DeleteBuilder(executor, 'myTable', { id: '123' })
+     *   .condition(op => op.eq('status', 'INACTIVE'))
+     *   .returnValues('ALL_OLD')
+     *   .execute();
+     *
+     * if (result.item) {
+     *   console.log('Deleted item:', result.item);
+     * }
+     * ```
+     *
+     * @returns A promise that resolves to an object containing the deleted item's attributes (if returnValues is 'ALL_OLD')
+     */
+    execute(): Promise<{
+        item?: DynamoItem;
+    }>;
+    /**
+     * Gets a human-readable representation of the delete command
+     * with all expression placeholders replaced by their actual values.
+     *
+     * @example
+     * ```ts
+     * const debugInfo = new DeleteBuilder(executor, 'dinosaurs', { id: 'TREX-001' })
+     *   .condition(op => op.and([
+     *     op.eq('status', 'SEDATED'),
+     *     op.eq('location', 'MEDICAL_BAY'),
+     *     op.gt('sedationLevel', 8)
+     *     op.eq('version', 1),
+     *     op.attributeExists('status')
+     *   ]))
+     *   .debug();
+     *
+     * console.log('Delete command:', debugInfo);
+     * ```
+     *
+     * @returns A readable representation of the delete command with resolved expressions
+     */
+    debug(): {
+        raw: DeleteCommandParams;
+        readable: {
+            conditionExpression?: string;
+            updateExpression?: string;
+            filterExpression?: string;
+            keyConditionExpression?: string;
+            projectionExpression?: string;
+        };
+    };
+}
+export {};

package/dist/builders/entity-aware-builders.d.ts

@@ -0,0 +1,127 @@
+import type { Condition, ConditionOperator } from "../conditions";
+import type { IndexDefinition } from "../entity/entity";
+import type { Table } from "../table";
+import type { DynamoItem } from "../types";
+import type { UpdateCommandParams } from "./builder-types";
+import type { DeleteBuilder } from "./delete-builder";
+import type { GetBuilder } from "./get-builder";
+import type { PutBuilder } from "./put-builder";
+import type { TransactionBuilder } from "./transaction-builder";
+import type { Path, PathType } from "./types";
+import type { UpdateBuilder } from "./update-builder";
+type SetElementType<T> = T extends Set<infer U> ? U : T extends Array<infer U> ? U : never;
+type PathSetElementType<T, K extends Path<T>> = SetElementType<PathType<T, K>>;
+/**
+ * Entity-aware wrapper for PutBuilder that automatically provides entity name to batch operations
+ */
+export type EntityAwarePutBuilder<T extends DynamoItem> = PutBuilder<T> & {
+    readonly entityName: string;
+};
+/**
+ * Creates an entity-aware PutBuilder
+ */
+export declare function createEntityAwarePutBuilder<T extends DynamoItem>(builder: PutBuilder<T>, entityName: string): EntityAwarePutBuilder<T>;
+/**
+ * Entity-aware wrapper for GetBuilder that automatically provides entity name to batch operations
+ */
+export type EntityAwareGetBuilder<T extends DynamoItem> = GetBuilder<T> & {
+    readonly entityName: string;
+};
+/**
+ * Creates an entity-aware GetBuilder
+ */
+export declare function createEntityAwareGetBuilder<T extends DynamoItem>(builder: GetBuilder<T>, entityName: string): EntityAwareGetBuilder<T>;
+/**
+ * Entity-aware wrapper for DeleteBuilder that automatically provides entity name to batch operations
+ */
+export type EntityAwareDeleteBuilder = DeleteBuilder & {
+    readonly entityName: string;
+};
+/**
+ * Creates an entity-aware DeleteBuilder
+ */
+export declare function createEntityAwareDeleteBuilder(builder: DeleteBuilder, entityName: string): EntityAwareDeleteBuilder;
+/**
+ * Entity-aware wrapper for UpdateBuilder that adds forceIndexRebuild functionality
+ * and automatically provides entity name to batch operations
+ */
+export declare class EntityAwareUpdateBuilder<T extends DynamoItem> {
+    private forceRebuildIndexes;
+    readonly entityName: string;
+    private builder;
+    private entityConfig?;
+    private updateDataApplied;
+    constructor(builder: UpdateBuilder<T>, entityName: string);
+    /**
+     * Configure entity-specific logic for automatic timestamp generation and index updates
+     */
+    configureEntityLogic(config: {
+        data: Partial<T>;
+        key: T;
+        table: Table;
+        indexes: Record<string, IndexDefinition<T>> | undefined;
+        generateTimestamps: () => Record<string, string | number>;
+        buildIndexUpdates: (currentData: T, updates: Partial<T>, table: Table, indexes: Record<string, IndexDefinition<T>> | undefined, forceRebuildIndexes?: string[]) => Record<string, string>;
+    }): void;
+    /**
+     * Forces a rebuild of one or more readonly indexes during the update operation.
+     *
+     * By default, readonly indexes are not updated during entity updates to prevent
+     * errors when required index attributes are missing. This method allows you to
+     * override that behavior and force specific indexes to be rebuilt.
+     *
+     * @example
+     * ```typescript
+     * // Force rebuild a single readonly index
+     * const result = await repo.update({ id: 'TREX-001' }, { status: 'ACTIVE' })
+     *   .forceIndexRebuild('gsi1')
+     *   .execute();
+     *
+     * // Force rebuild multiple readonly indexes
+     * const result = await repo.update({ id: 'TREX-001' }, { status: 'ACTIVE' })
+     *   .forceIndexRebuild(['gsi1', 'gsi2'])
+     *   .execute();
+     *
+     * // Chain with other update operations
+     * const result = await repo.update({ id: 'TREX-001' }, { status: 'ACTIVE' })
+     *   .set('lastUpdated', new Date().toISOString())
+     *   .forceIndexRebuild('gsi1')
+     *   .condition(op => op.eq('status', 'INACTIVE'))
+     *   .execute();
+     * ```
+     *
+     * @param indexes - A single index name or array of index names to force rebuild
+     * @returns The builder instance for method chaining
+     */
+    forceIndexRebuild(indexes: string | string[]): this;
+    /**
+     * Gets the list of indexes that should be force rebuilt.
+     * This is used internally by entity update logic.
+     *
+     * @returns Array of index names to force rebuild
+     */
+    getForceRebuildIndexes(): string[];
+    /**
+     * Apply entity-specific update data (timestamps and index updates)
+     * This is called automatically when needed
+     */
+    private applyEntityUpdates;
+    set(values: Partial<T>): this;
+    set<K extends Path<T>>(path: K, value: PathType<T, K>): this;
+    remove<K extends Path<T>>(path: K): this;
+    add<K extends Path<T>>(path: K, value: PathType<T, K>): this;
+    deleteElementsFromSet<K extends Path<T>>(path: K, value: PathSetElementType<T, K>[] | Set<PathSetElementType<T, K>>): this;
+    condition(condition: Condition | ((op: ConditionOperator<T>) => Condition)): this;
+    returnValues(returnValues: "ALL_NEW" | "UPDATED_NEW" | "ALL_OLD" | "UPDATED_OLD" | "NONE"): this;
+    toDynamoCommand(): UpdateCommandParams;
+    withTransaction(transaction: TransactionBuilder): void;
+    debug(): ReturnType<UpdateBuilder<T>["debug"]>;
+    execute(): Promise<{
+        item?: T;
+    }>;
+}
+/**
+ * Creates an entity-aware UpdateBuilder with force index rebuild functionality
+ */
+export declare function createEntityAwareUpdateBuilder<T extends DynamoItem>(builder: UpdateBuilder<T>, entityName: string): EntityAwareUpdateBuilder<T>;
+export {};

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

@@ -0,0 +1,294 @@
+import { type Condition, type ConditionOperator } from "../conditions";
+import type { DynamoItem, GSINames, TableConfig } from "../types";
+import type { FilterBuilderInterface } from "./builder-types";
+import { Paginator } from "./paginator";
+import type { ResultIterator } from "./result-iterator";
+import type { Path } from "./types";
+/**
+ * Configuration options for DynamoDB filter operations.
+ * These are common options shared between query and scan operations.
+ */
+export 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
+ */
+export 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>>;
+    /**
+     * Executes the operation and returns the first matching item, if any.
+     *
+     * This helper:
+     * - Applies an internal limit of 1
+     * - Streams results until a match is found or there are no more pages
+     * - Avoids mutating the current builder by using a clone
+     *
+     * @example
+     * ```typescript
+     * const latest = await table
+     *   .query(eq("moduleId", moduleId))
+     *   .useIndex("module-version-index")
+     *   .sortDescending()
+     *   .findOne();
+     * ```
+     *
+     * @returns The first matching item, or undefined if none found
+     */
+    findOne(): Promise<T | undefined>;
+}