dyno-table 1.5.0 → 1.7.0

package/README.md

@@ -45,10 +45,14 @@ await dinoTable
   </td>
 </tr>
 <tr>
-  <td>
+  <td width="50%">
     <h3>⚡ Velociraptor-fast API</h3>
     <p>Intuitive chainable builder pattern for complex operations that feels natural and reduces boilerplate</p>
   </td>
+  <td width="50%">
+    <h3>🎯 Semantic data access patterns</h3>
+    <p>Encourages meaningful, descriptive method names like <code>getUserByEmail()</code> instead of cryptic <code>gsi1</code> references</p>
+  </td>
 </tr>
 <tr>
   <td width="50%">
@@ -65,6 +69,10 @@ await dinoTable
 ## 📑 Table of Contents
 
 - [📦 Installation](#-installation)
+- [🎯 DynamoDB Best Practices](#-dynamodb-best-practices)
+  - [Semantic Data Access Patterns](#semantic-data-access-patterns)
+  - [The Problem with Generic Index Names](#the-problem-with-generic-index-names)
+  - [The Solution: Meaningful Method Names](#the-solution-meaningful-method-names)
 - [🚀 Quick Start](#-quick-start)
   - [1. Configure Your Jurassic Table](#1-configure-your-jurassic-table)
   - [2. Perform Type-Safe Dinosaur Operations](#2-perform-type-safe-dinosaur-operations)
@@ -93,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)
@@ -137,6 +145,133 @@ pnpm add dyno-table @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
 ```
 </details>
 
+## 🎯 DynamoDB Best Practices
+
+<div align="center">
+
+### **Design Your Data Access Patterns First, Name Them Meaningfully**
+
+</div>
+
+dyno-table follows DynamoDB best practices by encouraging developers to **define their data access patterns upfront** and assign them **meaningful, descriptive names**. This approach ensures that when writing business logic, developers call semantically clear methods instead of cryptic index references.
+
+### Semantic Data Access Patterns
+
+The core principle is simple: **your code should read like business logic, not database implementation details**.
+
+<table>
+<tr>
+<th>❌ Cryptic Implementation</th>
+<th>✅ Semantic Business Logic</th>
+</tr>
+<tr>
+<td>
+
+```ts
+// Hard to understand what this does - using raw AWS Document Client
+import { DynamoDBDocument } from "@aws-sdk/lib-dynamodb";
+import { QueryCommand } from "@aws-sdk/lib-dynamodb";
+
+const docClient = DynamoDBDocument.from(new DynamoDBClient({}));
+
+const users = await docClient.send(new QueryCommand({
+  TableName: "MyTable",
+  IndexName: "gsi1", 
+  KeyConditionExpression: "#pk = :pk",
+  ExpressionAttributeNames: { "#pk": "pk" },
+  ExpressionAttributeValues: { ":pk": "STATUS#active" }
+}));
+
+const orders = await docClient.send(new QueryCommand({
+  TableName: "MyTable",
+  IndexName: "gsi2",
+  KeyConditionExpression: "#pk = :pk",
+  ExpressionAttributeNames: { "#pk": "pk" },
+  ExpressionAttributeValues: { ":pk": "CUSTOMER#123" }
+}));
+
+const products = await docClient.send(new QueryCommand({
+  TableName: "MyTable",
+  IndexName: "gsi3",
+  KeyConditionExpression: "#pk = :pk",
+  ExpressionAttributeNames: { "#pk": "pk" },
+  ExpressionAttributeValues: { ":pk": "CATEGORY#electronics" }
+}));
+```
+
+</td>
+<td>
+
+```ts
+// Clear business intent
+const activeUsers = await userRepo.query
+  .getActiveUsers()
+  .execute();
+
+const customerOrders = await orderRepo.query
+  .getOrdersByCustomer({ customerId: "123" })
+  .execute();
+
+const electronics = await productRepo.query
+  .getProductsByCategory({ category: "electronics" })
+  .execute();
+```
+
+</td>
+</tr>
+</table>
+
+### The Problem with Generic Index Names
+
+When you use generic names like `gsi1`, `gsi2`, `gsi3`, you create several problems:
+
+- **🧠 Cognitive Load**: Developers must remember what each index does
+- **📚 Poor Documentation**: Code doesn't self-document its purpose
+- **🐛 Error-Prone**: Easy to use the wrong index for a query
+- **👥 Team Friction**: New team members struggle to understand data access patterns
+- **🔄 Maintenance Issues**: Refactoring becomes risky and unclear
+
+### The Solution: Meaningful Method Names
+
+dyno-table encourages you to define your access patterns with descriptive names that reflect their business purpose:
+
+```ts
+// Define your access patterns with meaningful names
+const UserEntity = defineEntity({
+  name: "User",
+  schema: userSchema,
+  primaryKey,
+  queries: {
+    // ✅ Clear business purpose
+    getActiveUsers: createQuery
+      .input(z.object({}))
+      .query(({ entity }) => entity.query({ pk: "STATUS#active" }).useIndex("gsi1")),
+
+    getUsersByEmail: createQuery
+      .input(z.object({ email: z.string() }))
+      .query(({ input, entity }) => entity.query({ pk: `EMAIL#${input.email}` }).useIndex("gsi1")),
+
+    getUsersByDepartment: createQuery
+      .input(z.object({ department: z.string() }))
+      .query(({ input, entity }) => entity.query({ pk: `DEPT#${input.department}` }).useIndex("gsi2")),
+  },
+});
+
+// Usage in business logic is now self-documenting
+const activeUsers = await userRepo.query.getActiveUsers().execute();
+const engineeringTeam = await userRepo.query.getUsersByDepartment({ department: "engineering" }).execute();
+const user = await userRepo.query.getUsersByEmail({ email: "john@company.com" }).execute();
+```
+
+**This pattern promotes:**
+- ✅ **Better code readability and maintainability**
+- ✅ **Self-documenting API design**
+- ✅ **Easier onboarding for new team members**
+- ✅ **Reduced cognitive load when understanding data access patterns**
+- ✅ **Clear separation between business logic and database implementation**
+
+> **🏗️ Important Note**: Keep your actual DynamoDB table GSI names generic (`gsi1`, `gsi2`, etc.) for flexibility across different entities. The meaningful, descriptive names should live at the entity/repository level, not at the table level. This allows multiple entities to share the same GSIs while maintaining semantic clarity in your business logic.
+
 ## 🚀 Quick Start
 
 <div align="center">
@@ -177,6 +312,8 @@ const dinoTable = new Table({
 
 ### 2. Perform Type-Safe Operations directly on the table instance
 
+> **💡 Pro Tip**: While you can use the table directly, we recommend using the [Entity Pattern](#-entity-pattern-with-standard-schema-validators) with meaningful, descriptive method names like `getUserByEmail()` instead of generic index references. This follows DynamoDB best practices and makes your code self-documenting.
+
 <table>
 <tr>
 <td>
@@ -271,28 +408,17 @@ await dinoTable.transaction((tx) => {
 
 <table>
 <tr>
-<th>With dyno-table</th>
-<th>Without dyno-table</th>
+<th>❌ Without dyno-table</th>
+<th>✅ With dyno-table (Entity Pattern)</th>
 </tr>
 <tr>
 <td>
 
-```ts
-// Type-safe, clean, and intuitive
-await dinoTable
-  .query<Dinosaur>({ 
-    pk: "SPECIES#trex"
-  })
-  .filter(op => 
-    op.contains("features", "feathers")
-  )
-  .execute();
-```
-
 ```ts
 // Verbose, error-prone, no type safety
 await docClient.send(new QueryCommand({
   TableName: "JurassicPark",
+  IndexName: "gsi1", // What does gsi1 do?
   KeyConditionExpression: "#pk = :pk",
   FilterExpression: "contains(#features, :feathers)",
   ExpressionAttributeNames: {
@@ -306,10 +432,37 @@ await docClient.send(new QueryCommand({
 }));
 ```
 
+</td>
+<td>
+
+```ts
+// Self-documenting, type-safe, semantic
+const featheredTRexes = await dinosaurRepo.query
+  .getFeatheredDinosaursBySpecies({
+    species: "trex"
+  })
+  .execute();
+
+// Or using table directly (still better than raw SDK)
+await dinoTable
+  .query<Dinosaur>({
+    pk: "SPECIES#trex"
+  })
+  .filter(op =>
+    op.contains("features", "feathers")
+  )
+  .execute();
+```
+
 </td>
 </tr>
 </table>
 
+**Key improvements:**
+- 🛡️ **Type Safety**: Compile-time error checking prevents runtime failures
+- 📖 **Self-Documenting**: Code clearly expresses business intent
+- 🧠 **Reduced Complexity**: No manual expression building or attribute mapping
+
 ## 🏗️ Entity Pattern with Standard Schema validators
 
 <div align="center">
@@ -336,7 +489,6 @@ await docClient.send(new QueryCommand({
 - 🔑 **Automatic key generation**
 - 📦 **Repository pattern**
 - 🔍 **Custom query builders**
-- 🔄 **Lifecycle hooks**
 
 </td>
 </tr>
@@ -460,7 +612,7 @@ await dinosaurRepo.delete({
 
 #### 3. Custom Queries
 
-Define custom queries with input validation:
+Define custom queries with **meaningful, descriptive names** that reflect their business purpose. This follows DynamoDB best practices by making your data access patterns self-documenting:
 
 ```ts
 import { createQueries } from "dyno-table/entity";
@@ -472,7 +624,8 @@ const DinosaurEntity = defineEntity({
   schema: dinosaurSchema,
   primaryKey,
   queries: {
-    byDiet: createQuery
+    // ✅ Semantic method names that describe business intent
+    getDinosaursByDiet: createQuery
       .input(
         z.object({
           diet: z.enum(["carnivore", "herbivore", "omnivore"]),
@@ -485,7 +638,7 @@ const DinosaurEntity = defineEntity({
           });
       }),
 
-    bySpecies: createQuery
+    findDinosaursBySpecies: createQuery
       .input(
         z.object({
           species: z.string(),
@@ -496,40 +649,89 @@ const DinosaurEntity = defineEntity({
           .scan()
           .filter((op) => op.eq("species", input.species));
       }),
+
+    getActiveCarnivores: createQuery
+      .input(z.object({}))
+      .query(({ entity }) => {
+        return entity
+          .query({
+            pk: dinosaurPK({diet: "carnivore"})
+          })
+          .filter((op) => op.eq("status", "active"));
+      }),
+
+    getDangerousDinosaursInEnclosure: createQuery
+      .input(
+        z.object({
+          enclosureId: z.string(),
+          minDangerLevel: z.number().min(1).max(10),
+        })
+      )
+      .query(({ input, entity }) => {
+        return entity
+          .scan()
+          .filter((op) => op.and(
+            op.contains("enclosureId", input.enclosureId),
+            op.gte("dangerLevel", input.minDangerLevel)
+          ));
+      }),
   },
 });
 
-// Use the custom queries
-const carnivores = await dinosaurRepo.query.byDiet({ diet: "carnivore" }).execute();
-const trexes = await dinosaurRepo.query.bySpecies({ species: "Tyrannosaurus Rex" }).execute();
+// Usage in business logic is now self-documenting
+const carnivores = await dinosaurRepo.query.getDinosaursByDiet({ diet: "carnivore" }).execute();
+const trexes = await dinosaurRepo.query.findDinosaursBySpecies({ species: "Tyrannosaurus Rex" }).execute();
+const activeCarnivores = await dinosaurRepo.query.getActiveCarnivores().execute();
+const dangerousDinos = await dinosaurRepo.query.getDangerousDinosaursInEnclosure({
+  enclosureId: "PADDOCK-A",
+  minDangerLevel: 8
+}).execute();
 ```
 
-#### 4. Defining GSI access patterns
+**Benefits of semantic naming:**
+- 🎯 **Clear Intent**: Method names immediately convey what data you're accessing
+- 📖 **Self-Documenting**: No need to look up what `gsi1` or `gsi2` does
+- 🧠 **Reduced Cognitive Load**: Developers can focus on business logic, not database details
+- 👥 **Team Collaboration**: New team members understand the codebase faster
+- 🔍 **Better IDE Support**: Autocomplete shows meaningful method names
+
+#### 4. Defining GSI Access Patterns
 
-Define GSI (LSI support coming later)
+Define GSI access patterns with **meaningful names** that reflect their business purpose. This is crucial for maintaining readable, self-documenting code:
 
 ```ts
 import { createIndex } from "dyno-table/entity";
 
-// Define GSIs templates for querying by species
-const gsi1PK = partitionKey`SPECIES#${"species"}`
-const gsi1SK = sortKey`DINOSAUR#${"id"}`
+// Define GSI templates with descriptive names that reflect their purpose
+const speciesPK = partitionKey`SPECIES#${"species"}`
+const speciesSK = sortKey`DINOSAUR#${"id"}`
+
+const enclosurePK = partitionKey`ENCLOSURE#${"enclosureId"}`
+const enclosureSK = sortKey`DANGER#${"dangerLevel"}#ID#${"id"}`
 
-// Implement typesafe generator for the GSI - This is used in create calls to ensure the GSI is generated
+// Create indexes with meaningful names
 const speciesIndex = createIndex()
   .input(dinosaurSchema)
-  .partitionKey(({ species }) => gsi1PK({ species }))
-  .sortKey(({ id }) => gsi1SK({ id }));
+  .partitionKey(({ species }) => speciesPK({ species }))
+  .sortKey(({ id }) => speciesSK({ id }));
+
+const enclosureIndex = createIndex()
+  .input(dinosaurSchema)
+  .partitionKey(({ enclosureId }) => enclosurePK({ enclosureId }))
+  .sortKey(({ dangerLevel, id }) => enclosureSK({ dangerLevel, id }));
 
 const DinosaurEntity = defineEntity({
   name: "Dinosaur",
   schema: dinosaurSchema,
   primaryKey,
   indexes: {
-    species: speciesIndex,
+    // ✅ Map to generic GSI names for table flexibility
+    gsi1: speciesIndex,
+    gsi2: enclosureIndex,
   },
   queries: {
-    bySpecies: createQuery
+    // ✅ Semantic method names that describe business intent
+    getDinosaursBySpecies: createQuery
       .input(
         z.object({
           species: z.string(),
@@ -538,16 +740,59 @@ const DinosaurEntity = defineEntity({
       .query(({ input, entity }) => {
         return entity
           .query({
-            // Use the GSI template generator to avoid typos
-            pk: gsi1PK({species: input.species}),
+            pk: speciesPK({species: input.species}),
           })
-          // Use the template name as defined in the table instance
-          .useIndex("gsi1");
+          .useIndex("gsi1"); // Generic GSI name for table flexibility
+      }),
+
+    getDinosaursByEnclosure: createQuery
+      .input(
+        z.object({
+          enclosureId: z.string(),
+        })
+      )
+      .query(({ input, entity }) => {
+        return entity
+          .query({
+            pk: enclosurePK({enclosureId: input.enclosureId}),
+          })
+          .useIndex("gsi2");
+      }),
+
+    getMostDangerousInEnclosure: createQuery
+      .input(
+        z.object({
+          enclosureId: z.string(),
+          minDangerLevel: z.number().min(1).max(10),
+        })
+      )
+      .query(({ input, entity }) => {
+        return entity
+          .query({
+            pk: enclosurePK({enclosureId: input.enclosureId}),
+            sk: (op) => op.gte(`DANGER#${input.minDangerLevel}`)
+          })
+          .useIndex("gsi2")
+          .sortDescending(); // Get most dangerous first
       }),
   },
 });
+
+// Usage is now self-documenting
+const trexes = await dinosaurRepo.query.getDinosaursBySpecies({ species: "Tyrannosaurus Rex" }).execute();
+const paddockADinos = await dinosaurRepo.query.getDinosaursByEnclosure({ enclosureId: "PADDOCK-A" }).execute();
+const dangerousDinos = await dinosaurRepo.query.getMostDangerousInEnclosure({
+  enclosureId: "PADDOCK-A",
+  minDangerLevel: 8
+}).execute();
 ```
 
+**Key principles for access pattern naming:**
+- 🎯 **Generic GSI Names**: Keep table-level GSI names generic (`gsi1`, `gsi2`) for flexibility across entities
+- 🔍 **Business-Focused**: Method names should reflect what the query achieves, not how it works
+- 📚 **Self-Documenting**: Anyone reading the code should understand the purpose immediately
+- 🏗️ **Entity-Level Semantics**: The meaningful names live at the entity/repository level, not the table level
+
 ### Complete Entity Example
 
 Here's a complete example of using Zod schemas directly:
@@ -621,7 +866,8 @@ const DinosaurEntity = defineEntity({
     gsi2: enclosureIndex,
   },
   queries: {
-    bySpecies: createQuery
+    // ✅ Semantic method names that describe business intent
+    getDinosaursBySpecies: createQuery
       .input(
         z.object({
           species: z.string(),
@@ -635,7 +881,7 @@ const DinosaurEntity = defineEntity({
           .useIndex("gsi1");
       }),
 
-    byEnclosure: createQuery
+    getDinosaursByEnclosure: createQuery
       .input(
         z.object({
           enclosureId: z.string(),
@@ -649,7 +895,7 @@ const DinosaurEntity = defineEntity({
           .useIndex("gsi2");
       }),
 
-    dangerousInEnclosure: createQuery
+    getDangerousDinosaursInEnclosure: createQuery
       .input(
         z.object({
           enclosureId: z.string(),
@@ -688,27 +934,19 @@ async function main() {
     })
     .execute();
 
-  // Query dinosaurs by species
-  const trexes = await dinosaurRepo.query.bySpecies({ 
-    species: "Tyrannosaurus Rex" 
+  // Query dinosaurs by species using semantic method names
+  const trexes = await dinosaurRepo.query.getDinosaursBySpecies({
+    species: "Tyrannosaurus Rex"
   }).execute();
 
   // Query dangerous dinosaurs in an enclosure
-  const dangerousDinos = await dinosaurRepo.query.dangerousInEnclosure({
+  const dangerousDinos = await dinosaurRepo.query.getDangerousDinosaursInEnclosure({
     enclosureId: "enc-001",
     minDangerLevel: 8,
   }).execute();
 }
 ```
 
-**Key benefits:**
-- 🚫 Prevents accidental cross-type data access
-- 🔍 Automatically filters queries/scans to a repository type
-- 🛡️ Ensures consistent key structure across entities
-- 📦 Encapsulates domain-specific query logic
-- 🧪 Validates data with Zod schemas
-- 🔄 Provides type inference from schemas
-
 ## 🧩 Advanced Features
 
 ### Transactional Operations
@@ -812,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
 
@@ -995,11 +1131,12 @@ Dyno-table provides comprehensive query methods that match DynamoDB's capabiliti
 | **Greater Than**          | `.filter(op => op.gt("price", 50))`                     | `price > :v1`                     |
 | **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`         |
-| **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`              |
+| **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`              |
 
 ### Logical Operators
 
@@ -1101,12 +1238,12 @@ const oldDino = await table.put<Dinosaur>({
 
 The library supports a comprehensive set of type-safe condition operators:
 
-| Category       | Operators                               | Example                                                                 |
-|----------------|-----------------------------------------|-------------------------------------------------------------------------|
-| **Comparison** | `eq`, `ne`, `lt`, `lte`, `gt`, `gte`    | `.condition(op => op.gt("age", 18))`                                    |
-| **String/Set** | `between`, `beginsWith`, `contains`     | `.condition(op => op.beginsWith("email", "@example"))`                  |
-| **Existence**  | `attributeExists`, `attributeNotExists` | `.condition(op => op.attributeExists("email"))`                         |
-| **Logical**    | `and`, `or`, `not`                      | `.condition(op => op.and(op.eq("status", "active"), op.gt("age", 18)))` |
+| Category       | Operators                                    | Example                                                                 |
+|----------------|----------------------------------------------|-------------------------------------------------------------------------|
+| **Comparison** | `eq`, `ne`, `lt`, `lte`, `gt`, `gte`         | `.condition(op => op.gt("age", 18))`                                    |
+| **String/Set** | `between`, `beginsWith`, `contains`, `inArray` | `.condition(op => op.inArray("status", ["active", "pending"]))`         |
+| **Existence**  | `attributeExists`, `attributeNotExists`      | `.condition(op => op.attributeExists("email"))`                         |
+| **Logical**    | `and`, `or`, `not`                           | `.condition(op => op.and(op.eq("status", "active"), op.gt("age", 18)))` |
 
 All operators are type-safe and will provide proper TypeScript inference for nested attributes.
 
@@ -1191,6 +1328,8 @@ await table.query<DinosaurMonitoring>({
   op.lt("health", "90"), // ❌ TypeScript Error: health expects number
   op.gt("temperature", 38), // ✓ Valid
   op.contains("behavior", "aggressive"), // ✓ Valid
+  op.inArray("alertLevel", ["LOW", "MEDIUM", "HIGH"]), // ✓ Valid: matches union type
+  op.inArray("alertLevel", ["UNKNOWN", "INVALID"]), // ❌ TypeScript Error: invalid alert levels
   op.eq("alertLevel", "UNKNOWN") // ❌ TypeScript Error: invalid alert level
 ))
 .execute();
@@ -1198,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:
@@ -1285,6 +1458,7 @@ All condition operators are type-safe and will validate against your item type.
 - `gt(attr, value)` - Greater than (>)
 - `gte(attr, value)` - Greater than or equal to (≥)
 - `between(attr, lower, upper)` - Between two values (inclusive)
+- `inArray(attr, values)` - Checks if value is in a list of values (IN operator, max 100 values)
 - `beginsWith(attr, value)` - Checks if string begins with value
 - `contains(attr, value)` - Checks if string/set contains value
 
@@ -1300,6 +1474,18 @@ await dinoTable
     op.between("stats.weight", 1000, 5000)  // Medium-sized dinosaurs
   ))
   .execute();
+
+// Example: Filter dinosaurs by multiple status values using inArray
+await dinoTable
+  .query<Dinosaur>({
+    pk: "SPECIES#trex"
+  })
+  .filter((op) => op.and(
+    op.inArray("status", ["ACTIVE", "FEEDING", "RESTING"]),  // Multiple valid statuses
+    op.inArray("diet", ["carnivore", "omnivore"]),           // Meat-eating dinosaurs
+    op.gt("dangerLevel", 5)                                  // High danger level
+  ))
+  .execute();
 ```
 
 #### Attribute Operators
@@ -1349,6 +1535,11 @@ await dinoTable
       op.lt("care.feeding.lastFed", new Date(Date.now() - 8 * 60 * 60 * 1000).toISOString()),
       op.contains("behavior", "stressed")
     ),
+    // Alert: Critical status dinosaurs requiring immediate attention
+    op.and(
+      op.inArray("status", ["SICK", "INJURED", "QUARANTINE"]),  // Critical statuses
+      op.inArray("priority", ["HIGH", "URGENT"])                // High priority levels
+    ),
     // Alert: Enclosure climate issues
     op.and(
       op.not(op.eq("habitat.enclosure.climate", "Optimal")),
@@ -1397,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