dyno-table 1.6.0 → 1.8.0-next.1

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-# 🦖 dyno-table
+# 🦖 dyno-table ALPHA
 
 ### **Tame Your DynamoDB Data with Type-Safe Precision**
 
@@ -101,8 +101,8 @@ await dinoTable
   - [Nested Object Support](#nested-object-support)
   - [Type-Safe Conditions](#type-safe-conditions)
 - [🔄 Batch Operations](#-batch-operations)
-  - [Batch Get](#batch-get)
-  - [Batch Write](#batch-write)
+  - [Entity-Based Batch Operations](#-entity-based-batch-operations)
+  - [Table-Direct Batch Operations](#-table-direct-batch-operations)
 - [🔒 Transaction Operations](#-transaction-operations)
   - [Transaction Builder](#transaction-builder)
   - [Transaction Options](#transaction-options)
@@ -947,16 +947,6 @@ async function main() {
 }
 ```
 
-**Key benefits:**
-- 🎯 **Semantic Data Access**: Method names like `getDinosaursBySpecies()` clearly express business intent
-- 🚫 **Prevents Accidental Cross-Type Access**: Type-safe operations prevent data corruption
-- 🔍 **Self-Documenting Code**: No need to remember what `gsi1` or `gsi2` does
-- 🛡️ **Consistent Key Structure**: Ensures uniform key patterns across entities
-- 📦 **Encapsulated Domain Logic**: Business rules are contained within entity definitions
-- 🧪 **Schema Validation**: Automatic data validation with your preferred schema library
-- 🔄 **Full Type Inference**: Complete TypeScript support from schema to queries
-- 👥 **Team Collaboration**: New developers understand the codebase immediately
-
 ## 🧩 Advanced Features
 
 ### Transactional Operations
@@ -1060,108 +1050,6 @@ await dinoTable.transaction(
 );
 ```
 
-**Benefits of this transaction approach:**
-- 🔄 Uses the same familiar API as non-transactional operations
-- 🧠 Maintains consistent mental model for developers
-- 🔒 All operations within the callback are executed as a single transaction
-- 🛡️ Prevents race conditions and data inconsistencies
-- 📊 Supports up to 100 actions per transaction
-
-### Batch Processing
-
-**Efficient dinosaur park management with bulk operations**
-```ts
-// SCENARIO 1: Morning health check for multiple dinosaurs across enclosures
-// Retrieve health status for multiple dinosaurs in a single operation
-const healthCheckKeys = [
-  { pk: "ENCLOSURE#A", sk: "DINO#001" }, // T-Rex in Paddock A
-  { pk: "ENCLOSURE#B", sk: "DINO#002" }, // Velociraptor in Paddock B
-  { pk: "ENCLOSURE#C", sk: "DINO#003" }  // Stegosaurus in Paddock C
-];
-
-// Perform batch get operation to retrieve all dinosaurs at once
-// This is much more efficient than individual gets
-const { items: dinosaurs, unprocessedKeys } = await dinoTable.batchGet<Dinosaur>(healthCheckKeys);
-console.log(`Health check completed for ${dinosaurs.length} dinosaurs`);
-
-// Process health check results and identify any dinosaurs needing attention
-dinosaurs.forEach(dino => {
-  if (dino.health < 80) {
-    console.log(`Health alert for ${dino.name} in Enclosure ${dino.enclosureId}`);
-    // In a real application, you might trigger alerts or schedule veterinary visits
-  }
-});
-
-// SCENARIO 2: Adding new herbivores to the park after quarantine
-// Prepare data for multiple new herbivores joining the collection
-const newHerbivores = [
-  {
-    pk: "ENCLOSURE#D", sk: "DINO#004",
-    name: "Triceratops Alpha",      // Three-horned herbivore
-    species: "Triceratops",
-    diet: "Herbivore",
-    status: "HEALTHY",
-    health: 95,                     // Excellent health after quarantine
-    lastFed: new Date().toISOString() // Just fed before joining main enclosure
-  },
-  {
-    pk: "ENCLOSURE#D", sk: "DINO#005",
-    name: "Brachy",                 // Long-necked herbivore
-    species: "Brachiosaurus",
-    diet: "Herbivore",
-    status: "HEALTHY",
-    health: 90,
-    lastFed: new Date().toISOString()
-  }
-];
-
-// Add all new herbivores to the enclosure in a single batch operation
-// More efficient than individual writes and ensures consistent state
-await dinoTable.batchWrite(
-  newHerbivores.map(dino => ({
-    type: "put",                    // Create or replace operation
-    item: dino                      // Full dinosaur record
-  }))
-);
-
-// SCENARIO 3: Releasing a dinosaur from quarantine to general population
-// Multiple related operations performed as a batch
-await dinoTable.batchWrite([
-  // Step 1: Remove dinosaur from quarantine enclosure
-  { 
-    type: "delete", 
-    key: { pk: "ENCLOSURE#QUARANTINE", sk: "DINO#006" } 
-  },
-
-  // Step 2: Add recovered dinosaur to main raptor enclosure
-  { 
-    type: "put", 
-    item: {
-      pk: "ENCLOSURE#E", sk: "DINO#006",
-      name: "Raptor Beta",          // Juvenile Velociraptor
-      species: "Velociraptor",
-      diet: "Carnivore",
-      status: "HEALTHY",            // Now healthy after treatment
-      health: 100,
-      lastFed: new Date().toISOString()
-    }
-  },
-
-  // Step 3: Clear quarantine status record
-  { 
-    type: "delete", 
-    key: { pk: "ENCLOSURE#QUARANTINE", sk: "STATUS#DINO#006" } 
-  }
-]);
-
-// SCENARIO 4: Daily park-wide health monitoring
-// Handle large-scale operations across all dinosaurs
-// The library automatically handles chunking for large batches:
-// - 25 items per batch write
-// - 100 items per batch get
-const dailyHealthUpdates = generateDinosaurHealthUpdates(); // Hundreds of updates
-await dinoTable.batchWrite(dailyHealthUpdates); // Automatically chunked into multiple requests
-```
 
 ### Pagination Made Simple
 
@@ -1244,11 +1132,11 @@ Dyno-table provides comprehensive query methods that match DynamoDB's capabiliti
 | **Greater Than or Equal** | `.filter(op => op.gte("rating", 4))`                    | `rating >= :v1`                   |
 | **Between**               | `.filter(op => op.between("age", 18, 65))`              | `age BETWEEN :v1 AND :v2`         |
 | **In Array**              | `.filter(op => op.inArray("status", ["ACTIVE", "PENDING"]))` | `status IN (:v1, :v2)`            |
-| **Begins With**           | `.filter(op => op.beginsWith("email", "@example.com"))` | `begins_with(email, :v1)`         |
-| **Contains**              | `.filter(op => op.contains("tags", "important"))`       | `contains(tags, :v1)`             |
-| **Attribute Exists**      | `.filter(op => op.attributeExists("email"))`            | `attribute_exists(email)`         |
-| **Attribute Not Exists**  | `.filter(op => op.attributeNotExists("deletedAt"))`     | `attribute_not_exists(deletedAt)` |
-| **Nested Attributes**     | `.filter(op => op.eq("address.city", "London"))`        | `address.city = :v1`              |
+| **Begins With**           | `.filter(op => op.beginsWith("email", "@example.com"))`      | `begins_with(email, :v1)`         |
+| **Contains**              | `.filter(op => op.contains("tags", "important"))`            | `contains(tags, :v1)`             |
+| **Attribute Exists**      | `.filter(op => op.attributeExists("email"))`                 | `attribute_exists(email)`         |
+| **Attribute Not Exists**  | `.filter(op => op.attributeNotExists("deletedAt"))`          | `attribute_not_exists(deletedAt)` |
+| **Nested Attributes**     | `.filter(op => op.eq("address.city", "London"))`             | `address.city = :v1`              |
 
 ### Logical Operators
 
@@ -1449,24 +1337,58 @@ await table.query<DinosaurMonitoring>({
 
 ## 🔄 Batch Operations
 
-The library supports efficient batch operations for both reading and writing multiple items:
+Efficiently handle multiple items in a single request with automatic chunking and type safety.
+
+### 🏗️ Entity-Based Batch Operations
+
+**Type-safe batch operations with automatic entity type inference**
 
-### Batch Get
 ```ts
-const { items, unprocessedKeys } = await table.batchGet<User>([
-  { pk: "USER#1", sk: "PROFILE" },
-  { pk: "USER#2", sk: "PROFILE" }
-]);
+// Create a typed batch builder
+const batch = table.batchBuilder<{
+  Dinosaur: DinosaurEntity;
+  Fossil: FossilEntity;
+}>();
+
+// Add operations - entity type is automatically inferred
+dinosaurRepo.create(newDinosaur).withBatch(batch);
+dinosaurRepo.get({ id: 'dino-123', diet: 'carnivore', species: 'Tyrannosaurus Rex' }).withBatch(batch);
+fossilRepo.create(newFossil).withBatch(batch);
+
+// Execute and get typed results
+const result = await batch.execute();
+const dinosaurs: DinosaurEntity[] = result.reads.itemsByType.Dinosaur;
+const fossils: FossilEntity[] = result.reads.itemsByType.Fossil;
 ```
 
-### Batch Write
+### 📋 Table-Direct Batch Operations
+
+**Direct table access for maximum control**
+
 ```ts
-const { unprocessedItems } = await table.batchWrite<User>([
-  { type: "put", item: newUser },
-  { type: "delete", key: { pk: "USER#123", sk: "PROFILE" } }
-]);
+// Batch get - retrieve multiple items
+const keys = [
+  { pk: "DIET#carnivore", sk: "SPECIES#Tyrannosaurus Rex#ID#dino-123" },
+  { pk: "FOSSIL#456", sk: "DISCOVERY#2024" }
+];
+
+const { items, unprocessedKeys } = await table.batchGet<DynamoItem>(keys);
+
+// Batch write - mix of operations
+const operations = [
+  { type: "put" as const, item: { pk: "DIET#herbivore", sk: "SPECIES#Triceratops#ID#dino-789", name: "Spike", dangerLevel: 3 } },
+  { type: "delete" as const, key: { pk: "FOSSIL#OLD", sk: "DISCOVERY#1990" } }
+];
+
+const { unprocessedItems } = await table.batchWrite(operations);
+
+// Handle unprocessed items (retry if needed)
+if (unprocessedItems.length > 0) {
+  await table.batchWrite(unprocessedItems);
+}
 ```
 
+
 ## 🔒 Transaction Operations
 
 Perform multiple operations atomically with transaction support:
@@ -1666,15 +1588,6 @@ const quarantinedDinos = await dinoTable
   .execute();
 ```
 
-Available key conditions for dinosaur queries:
-- `eq(value)` - Exact match (e.g., specific enclosure)
-- `lt(value)` - Earlier than date/time
-- `lte(value)` - Up to and including date/time
-- `gt(value)` - Later than date/time
-- `gte(value)` - From date/time onwards
-- `between(lower, upper)` - Range (e.g., weight range, date range)
-- `beginsWith(value)` - Prefix match (e.g., all health checks today)
-
 ## 🔮 Future Roadmap
 
 - [ ] Enhanced query plan visualization

package/dist/batch-builder-BOBwOIUE.d.ts

@@ -0,0 +1,398 @@
+import { DynamoItem } from './types.js';
+import { r as PrimaryKeyWithoutExpression } from './conditions-BtynAviC.js';
+import { a as PutCommandParams, D as DeleteCommandParams } from './builder-types-CzuLR4Th.js';
+
+type BatchWriteOperation<T extends Record<string, unknown>> = {
+    type: "put";
+    item: T;
+} | {
+    type: "delete";
+    key: PrimaryKeyWithoutExpression;
+};
+
+/**
+ * Parameters for the DynamoDB get command.
+ */
+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
+ */
+declare class GetBuilder<T extends DynamoItem> {
+    private readonly executor;
+    private readonly params;
+    private options;
+    private selectedFields;
+    /**
+     * 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);
+    /**
+     * 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(fields: string | string[]): 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;
+    /**
+     * 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;
+    }>;
+}
+
+/**
+ * Configuration for batch operations
+ */
+interface BatchConfig {
+    partitionKey: string;
+    sortKey?: string;
+}
+/**
+ * Executor function for batch write operations
+ */
+type BatchWriteExecutor = (operations: Array<BatchWriteOperation<DynamoItem>>) => Promise<{
+    unprocessedItems: Array<BatchWriteOperation<DynamoItem>>;
+}>;
+/**
+ * Executor function for batch get operations
+ */
+type BatchGetExecutor = (keys: Array<PrimaryKeyWithoutExpression>) => Promise<{
+    items: DynamoItem[];
+    unprocessedKeys: PrimaryKeyWithoutExpression[];
+}>;
+/**
+ * Error class for batch operation failures
+ */
+declare class BatchError extends Error {
+    readonly operation: "write" | "read";
+    readonly cause?: Error;
+    constructor(message: string, operation: "write" | "read", cause?: Error);
+}
+/**
+ * Result structure for batch operations
+ */
+interface BatchResult {
+    /** Whether the batch operation completed successfully */
+    success: boolean;
+    /** Write operation results */
+    writes: {
+        /** Number of write operations processed successfully */
+        processed: number;
+        /** Write operations that were not processed and may need retry */
+        unprocessed: Array<BatchWriteOperation<DynamoItem>>;
+    };
+    /** Read operation results */
+    reads: {
+        /** Items retrieved from the batch get operations */
+        items: DynamoItem[];
+        /** Number of items found and returned */
+        found: number;
+        /** Keys that were not processed and may need retry */
+        unprocessed: PrimaryKeyWithoutExpression[];
+    };
+    /** Total number of operations in the batch */
+    totalOperations: number;
+    /** Any errors that occurred during batch processing */
+    errors?: BatchError[];
+}
+/**
+ * Typed result structure for batch operations with entity type information
+ */
+interface TypedBatchResult<TEntities extends Record<string, DynamoItem> = Record<string, DynamoItem>> {
+    /** Whether the batch operation completed successfully */
+    success: boolean;
+    /** Write operation results */
+    writes: {
+        /** Number of write operations processed successfully */
+        processed: number;
+        /** Write operations that were not processed and may need retry */
+        unprocessed: Array<BatchWriteOperation<DynamoItem>>;
+    };
+    /** Read operation results with typed items */
+    reads: {
+        /** Items retrieved from the batch get operations, grouped by entity type */
+        itemsByType: {
+            [K in keyof TEntities]: TEntities[K][];
+        };
+        /** All items retrieved (typed as union of all entity types) */
+        items: TEntities[keyof TEntities][];
+        /** Number of items found and returned */
+        found: number;
+        /** Keys that were not processed and may need retry */
+        unprocessed: PrimaryKeyWithoutExpression[];
+    };
+    /** Total number of operations in the batch */
+    totalOperations: number;
+    /** Any errors that occurred during batch execution */
+    errors?: BatchError[];
+}
+/**
+ * Builder for creating and executing DynamoDB batch operations with full entity support and type inference.
+ *
+ * Use BatchBuilder when you need to:
+ * - Perform multiple operations efficiently (up to 25 writes, 100 reads per batch)
+ * - Maintain entity validation, key generation, and type safety
+ * - Mix read and write operations in a single batch
+ * - Get typed results grouped by entity type
+ *
+ * @example Basic Usage
+ * ```typescript
+ * // Define entity types for the batch
+ * const batch = table.batchBuilder<{
+ *   User: UserEntity;
+ *   Order: OrderEntity;
+ * }>();
+ *
+ * // Add operations using entity repositories
+ * userRepo.create(newUser).withBatch(batch, 'User')
+ * userRepo.delete({ id: 'old-user' }).withBatch(batch, 'User')
+ * orderRepo.get({ id: 'existing-order' }).withBatch(batch, 'Order')
+ *
+ * // Execute all operations and get typed results
+ * const result = await batch.execute()
+ * const users: UserEntity[] = result.reads.itemsByType.User
+ * const orders: OrderEntity[] = result.reads.itemsByType.Order
+ * ```
+ *
+ * @example Error Handling
+ * ```typescript
+ * try {
+ *   const result = await batch.execute()
+ *
+ *   if (result.writes.unprocessed.length > 0) {
+ *     console.warn('Some writes were not processed:', result.writes.unprocessed)
+ *   }
+ * } catch (error) {
+ *   if (error instanceof BatchError) {
+ *     console.error('Batch operation failed:', error.message)
+ *   }
+ * }
+ * ```
+ */
+declare class BatchBuilder<TEntities extends Record<string, DynamoItem> = Record<string, DynamoItem>> {
+    private batchWriteExecutor;
+    private batchGetExecutor;
+    private config;
+    private writeItems;
+    private getItems;
+    constructor(batchWriteExecutor: BatchWriteExecutor, batchGetExecutor: BatchGetExecutor, config: BatchConfig);
+    /**
+     * Checks if the batch is empty (contains no operations)
+     *
+     * @returns true if the batch contains no operations
+     */
+    isEmpty(): boolean;
+    /**
+     * Gets the count of operations in the batch
+     *
+     * @returns Object containing the count of write and read operations
+     */
+    getOperationCount(): {
+        writes: number;
+        reads: number;
+    };
+    /**
+     * Validates that the batch is not empty before execution
+     *
+     * @throws {BatchError} If the batch is empty
+     */
+    private validateNotEmpty;
+    /**
+     * Adds a put operation to the batch with entity type information.
+     * This method is used internally by entity builders.
+     *
+     * @param command - The complete put command configuration
+     * @param entityType - The entity type name for type tracking
+     * @returns The batch builder for method chaining
+     * @internal
+     */
+    putWithCommand<K extends keyof TEntities>(command: PutCommandParams, entityType?: K): this;
+    /**
+     * Adds a delete operation to the batch with entity type information.
+     * This method is used internally by entity builders.
+     *
+     * @param command - The complete delete command configuration
+     * @param entityType - The entity type name for type tracking
+     * @returns The batch builder for method chaining
+     * @internal
+     */
+    deleteWithCommand<K extends keyof TEntities>(command: DeleteCommandParams, entityType?: K): this;
+    /**
+     * Adds a get operation to the batch with entity type information.
+     * This method is used internally by entity builders.
+     *
+     * @param command - The complete get command configuration
+     * @param entityType - The entity type name for type tracking
+     * @returns The batch builder for method chaining
+     * @internal
+     */
+    getWithCommand<K extends keyof TEntities>(command: GetCommandParams, entityType?: K): this;
+    /**
+     * Executes all write operations in the batch.
+     *
+     * @returns A promise that resolves to any unprocessed operations
+     * @private
+     */
+    private executeWrites;
+    /**
+     * Executes all get operations in the batch.
+     *
+     * @returns A promise that resolves to the retrieved items
+     * @private
+     */
+    private executeGets;
+    /**
+     * Groups retrieved items by their entity type.
+     * @private
+     */
+    private groupItemsByType;
+    /**
+     * Executes all operations in the batch with typed results.
+     * Performs write operations first, then get operations.
+     *
+     * @returns A promise that resolves to a TypedBatchResult with entity type information
+     * @throws {BatchError} If the batch is empty or if operations fail
+     */
+    execute(): Promise<TypedBatchResult<TEntities>>;
+}
+
+export { BatchBuilder as B, GetBuilder as G, BatchError as a, type BatchResult as b, type BatchWriteOperation as c };