dyno-table 0.0.2 → 0.1.3

package/README.md

@@ -1,344 +1,784 @@
-# 🦖 dyno-table
+# 🦖 dyno-table [![npm version](https://img.shields.io/npm/v/dyno-table.svg?style=flat-square)](https://www.npmjs.com/package/dyno-table) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 
-A powerful, type-safe, and fluent DynamoDB table abstraction layer for Node.js applications.
+**A type-safe, fluent interface for DynamoDB single-table designs**  
+*Tame the NoSQL wilderness with a robust abstraction layer that brings order to DynamoDB operations*
 
-Allows you to work with DynamoDB in a single table design pattern
+<img src="docs/images/geoff-the-dyno.png" width="400" height="250" alt="Geoff the Dyno" style="float: right; margin-left: 20px; margin-bottom: 20px;">
 
-## ✨ Features
+```ts
+// Type-safe DynamoDB operations made simple
+await table
+  .update<Dinosaur>({
+    pk: 'SPECIES#trex',
+    sk: 'PROFILE#001'
+  })
+  .set('diet', 'Carnivore')
+  .add('sightings', 1)
+  .condition(op => op.eq('status', 'ACTIVE'))
+  .execute();
+```
 
-- **Type-safe operations**: Ensures type safety for all DynamoDB operations.
-- **Builders for operations**: Provides builders for put, update, delete, query, and scan operations.
-- **Transaction support**: Supports transactional operations.
-- **Batch operations**: Handles batch write operations with automatic chunking for large datasets.
-- **Conditional operations**: Supports conditional puts, updates, and deletes.
-- **Repository pattern**: Provides a base repository class for implementing the repository pattern.
-- **Error handling**: Custom error classes for handling DynamoDB errors gracefully.
+## 🌟 Why dyno-table?
+
+- **🧩 Single-table design made simple** - Clean abstraction layer for complex DynamoDB patterns
+- **🛡️ Type-safe operations** - Full TypeScript support with strict type checking
+- **⚡ Fluent API** - Chainable builder pattern for complex operations
+- **🔒 Transactional safety** - ACID-compliant operations with easy-to-use transactions
+- **📈 Scalability built-in** - Automatic batch chunking and pagination handling
+
+## 📑 Table of Contents
+
+- [Installation](#-installation)
+- [Quick Start](#-quick-start)
+- [Query](#-type-safe-query-building)
+- [Update](#update-operations)
+  - [Condition Operators](#condition-operators)
+  - [Multiple Operations](#multiple-operations)
+- [Type Safety Features](#-type-safety-features)
+  - [Nested Object Support](#nested-object-support)
+  - [Type-Safe Conditions](#type-safe-conditions)
+- [Batch Operations](#-batch-operations)
+  - [Batch Get](#batch-get)
+  - [Batch Write](#batch-write)
+- [Transaction Operations](#-transaction-operations)
+  - [Transaction Builder](#transaction-builder)
+  - [Transaction Options](#transaction-options)
+- [Error Handling](#-error-handling)
+- [API Reference](#-api-reference)
 
 ## 📦 Installation
 
-Get started with Dyno Table by installing it via npm:
-
 ```bash
 npm install dyno-table
 ```
 
-## 🦕 Getting Started
+*Note: Requires AWS SDK v3 as peer dependency*
+
+```bash
+npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
+```
 
-### Setting Up the Table
+## 🚀 Quick Start
 
-First, set up the `Table` instance with your DynamoDB client and table configuration.
+### 1. Configure Your Table
 
 ```ts
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
 import { DynamoDBDocument } from "@aws-sdk/lib-dynamodb";
 import { Table } from "dyno-table";
-import { docClient } from "./ddb-client"; // Your DynamoDB client instance
-
-const table = new Table({
-  client: docClient,
-  tableName: "DinoTable",
-  tableIndexes: {
-    primary: {
-      pkName: "pk",
-      skName: "sk",
-    },
-    GSI1: {
-      pkName: "GSI1PK",
-      skName: "GSI1SK",
+
+// Configure AWS SDK clients
+const client = new DynamoDBClient({ region: "us-west-2" });
+const docClient = DynamoDBDocument.from(client);
+
+// Initialize table with single-table design schema
+const dinoTable = new Table(docClient, {
+  name: "DinosaurPark",
+  partitionKey: "pk",
+  sortKey: "sk",
+  gsis: [
+    {
+      name: "GSI1",
+      keySchema: {
+        pk: "GSI1PK",
+        sk: "GSI1SK",
+      },
     },
-  },
+  ],
 });
 ```
 
-### CRUD Operations
+### 2. Perform Type-Safe Operations
 
-#### Create (Put)
+**🦖 Creating a new dinosaur**
+```ts
+const rex = await dinoTable
+  .create<Dinosaur>({
+    pk: "SPECIES#trex",
+    sk: "PROFILE#trex",
+    speciesId: "trex",
+    name: "Tyrannosaurus Rex",
+    diet: "carnivore",
+    length: 12.3,
+    discoveryYear: 1902
+  })
+  .execute();
+```
 
+**🔍 Query with conditions**
 ```ts
-// Simple put
-const dino = {
-  pk: "SPECIES#trex",
-  sk: "PROFILE#001",
-  name: "Rex",
-  diet: "Carnivore",
-  length: 40,
-  type: "DINOSAUR",
-};
-
-await table.put(dino).execute();
-
-// Conditional put
-await table
-  .put(dino)
-  .whereNotExists("pk")  // Only insert if dinosaur doesn't exist
-  .whereNotExists("sk")
+const largeDinos = await dinoTable
+  .query<Dinosaur>({ 
+    pk: "SPECIES#trex",
+    sk: (op) => op.beginsWith("PROFILE#")
+  })
+  .filter((op) => op.and(
+    op.gte("length", 10),
+    op.eq("diet", "carnivore")
+  ))
+  .limit(10)
   .execute();
 ```
 
-#### Read (Get)
+**🔄 Complex update operation**
+```ts
+await dinoTable
+  .update<Dinosaur>({ 
+    pk: "SPECIES#trex", 
+    sk: "PROFILE#trex" 
+  })
+  .set("diet", "omnivore")
+  .add("discoveryYear", 1)
+  .remove("outdatedField")
+  .condition((op) => op.attributeExists("discoverySite"))
+  .execute();
+```
 
+## 🧩 Advanced Features
+
+### Transactional Operations
+
+**Safe dinosaur transfer between enclosures**
 ```ts
-const key = { pk: "SPECIES#trex", sk: "PROFILE#001" };
-const result = await table.get(key);
-console.log(result);
+// Start a transaction session for transferring a dinosaur
+await dinoTable.transaction(async (tx) => {
+  // All operations are executed as a single transaction (up to 100 operations)
+
+  // Check if destination enclosure is ready and compatible
+  await dinoTable
+    .conditionCheck({ 
+      pk: "ENCLOSURE#B", 
+      sk: "STATUS" 
+    })
+    .condition(op => op.and(
+      op.eq("status", "READY"),
+      op.eq("diet", "Carnivore")  // Ensure enclosure matches dinosaur diet
+    ))
+    .withTransaction(tx);
+
+  // Remove dinosaur from current enclosure
+  await dinoTable
+    .delete<Dinosaur>({ 
+      pk: "ENCLOSURE#A", 
+      sk: "DINO#001" 
+    })
+    .condition(op => op.and(
+      op.eq("status", "HEALTHY"),
+      op.gte("health", 80)  // Only transfer healthy dinosaurs
+    ))
+    .withTransaction(tx);
+
+  // Add dinosaur to new enclosure
+  await dinoTable
+    .create<Dinosaur>({
+      pk: "ENCLOSURE#B",
+      sk: "DINO#001",
+      name: "Rex",
+      species: "Tyrannosaurus",
+      diet: "Carnivore",
+      status: "HEALTHY",
+      health: 100,
+      enclosureId: "B",
+      lastFed: new Date().toISOString()
+    })
+    .withTransaction(tx);
+
+  // Update enclosure occupancy tracking
+  await dinoTable
+    .update<Dinosaur>({ 
+      pk: "ENCLOSURE#B", 
+      sk: "OCCUPANCY" 
+    })
+    .add("currentOccupants", 1)
+    .set("lastUpdated", new Date().toISOString())
+    .withTransaction(tx);
+});
 
-// Get with specific index
-const result = await table.get(key, { indexName: "GSI1" });
+// Transaction with feeding and health monitoring
+await dinoTable.transaction(
+  async (tx) => {
+    // Update dinosaur health and feeding status
+    await dinoTable
+      .update<Dinosaur>({
+        pk: "ENCLOSURE#D",
+        sk: "DINO#003"
+      })
+      .set({
+        status: "HEALTHY",
+        lastFed: new Date().toISOString(),
+        health: 100
+      })
+      .deleteElementsFromSet("tags", ["needs_feeding"])
+      .withTransaction(tx);
+
+    // Update enclosure feeding schedule
+    await dinoTable
+      .update<Dinosaur>({
+        pk: "ENCLOSURE#D",
+        sk: "SCHEDULE"
+      })
+      .set("nextFeedingTime", new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString())
+      .withTransaction(tx);
+  },
+  {
+    clientRequestToken: "feeding-session-001",
+    returnConsumedCapacity: "TOTAL"
+  }
+);
 ```
 
-#### Update
+**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
+- ✅ All-or-nothing operations (ACID compliance)
+- 🛡️ Prevents race conditions and data inconsistencies
+- 📊 Supports up to 100 actions per transaction
+
+### Batch Processing
 
+**Efficient dinosaur park management with bulk operations**
 ```ts
-// Simple update
-const updates = { length: 42, diet: "Carnivore" };
-await table.update(key).setMany(updates).execute();
+// Batch health check for multiple dinosaurs
+const healthCheckKeys = [
+  { pk: "ENCLOSURE#A", sk: "DINO#001" }, // T-Rex
+  { pk: "ENCLOSURE#B", sk: "DINO#002" }, // Velociraptor
+  { pk: "ENCLOSURE#C", sk: "DINO#003" }  // Stegosaurus
+];
 
-// Advanced update operations
-await table
-  .update(key)
-  .set("diet", "Omnivore")              // Set a single field
-  .set({ length: 45, name: "Rexy" })    // Set multiple fields
-  .remove("optional_field")              // Remove fields
-  .increment("sightings", 1)             // Increment a number
-  .whereEquals("length", 42)             // Conditional update
-  .execute();
+const { items: dinosaurs, unprocessedKeys } = await dinoTable.batchGet<Dinosaur>(healthCheckKeys);
+console.log(`Health check completed for ${dinosaurs.length} dinosaurs`);
+dinosaurs.forEach(dino => {
+  if (dino.health < 80) {
+    console.log(`Health alert for ${dino.name} in Enclosure ${dino.enclosureId}`);
+  }
+});
+
+// Batch update feeding schedule for herbivore group
+const newHerbivores = [
+  {
+    pk: "ENCLOSURE#D", sk: "DINO#004",
+    name: "Triceratops Alpha",
+    species: "Triceratops",
+    diet: "Herbivore",
+    status: "HEALTHY",
+    health: 95,
+    lastFed: new Date().toISOString()
+  },
+  {
+    pk: "ENCLOSURE#D", sk: "DINO#005",
+    name: "Brachy",
+    species: "Brachiosaurus",
+    diet: "Herbivore",
+    status: "HEALTHY",
+    health: 90,
+    lastFed: new Date().toISOString()
+  }
+];
+
+// Add new herbivores to enclosure
+await dinoTable.batchWrite(
+  newHerbivores.map(dino => ({
+    type: "put",
+    item: dino
+  }))
+);
+
+// Mixed operations: relocate dinosaurs and update enclosure status
+await dinoTable.batchWrite([
+  // Remove dinosaur from quarantine
+  { type: "delete", key: { pk: "ENCLOSURE#QUARANTINE", sk: "DINO#006" } },
+  // Add recovered dinosaur to main enclosure
+  { 
+    type: "put", 
+    item: {
+      pk: "ENCLOSURE#E", sk: "DINO#006",
+      name: "Raptor Beta",
+      species: "Velociraptor",
+      diet: "Carnivore",
+      status: "HEALTHY",
+      health: 100,
+      lastFed: new Date().toISOString()
+    }
+  },
+  // Clear quarantine status
+  { type: "delete", key: { pk: "ENCLOSURE#QUARANTINE", sk: "STATUS#DINO#006" } }
+]);
+
+// Handle large-scale park operations
+// (25 items per batch write, 100 items per batch get)
+const dailyHealthUpdates = generateDinosaurHealthUpdates(); // Hundreds of updates
+await dinoTable.batchWrite(dailyHealthUpdates); // Automatically chunked
 ```
 
-#### Delete
+### Pagination Made Simple
 
+**Efficient dinosaur record browsing**
 ```ts
-// Simple delete
-await table.delete(key).execute();
+// Create a paginator for viewing herbivores by health status
+const healthyHerbivores = dinoTable
+  .query<Dinosaur>({
+    pk: "DIET#herbivore",
+    sk: op => op.beginsWith("STATUS#HEALTHY")
+  })
+  .filter((op) => op.and(
+    op.gte("health", 90),
+    op.attributeExists("lastFed")
+  ))
+  .paginate(5); // View 5 dinosaurs at a time
+
+// Monitor all enclosures page by page
+while (healthyHerbivores.hasNextPage()) {
+  const page = await healthyHerbivores.getNextPage();
+  console.log(`Checking herbivores page ${page.page}, found ${page.items.length} dinosaurs`);
+  page.items.forEach(dino => {
+    console.log(`${dino.name}: Health ${dino.health}%, Last fed: ${dino.lastFed}`);
+  });
+}
 
-// Conditional delete
-await table
-  .delete(key)
-  .whereExists("pk")
-  .whereEquals("type", "DINOSAUR")
-  .execute();
+// Get all carnivores for daily feeding schedule
+const carnivoreSchedule = await dinoTable
+  .query<Dinosaur>({
+    pk: "DIET#carnivore",
+    sk: op => op.beginsWith("ENCLOSURE#")
+  })
+  .filter(op => op.attributeExists("lastFed"))
+  .paginate(10)
+  .getAllPages();
+
+console.log(`Scheduling feeding for ${carnivoreSchedule.length} carnivores`);
+
+// Limited view for visitor information kiosk
+const visitorKiosk = dinoTable
+  .query<Dinosaur>({ 
+    pk: "VISITOR_VIEW",
+    sk: op => op.beginsWith("SPECIES#")
+  })
+  .filter(op => op.eq("status", "ON_DISPLAY"))
+  .limit(12) // Show max 12 dinosaurs per view
+  .paginate(4); // Display 4 at a time
+
+// Get first page for kiosk display
+const firstPage = await visitorKiosk.getNextPage();
+console.log(`Now showing: ${firstPage.items.map(d => d.name).join(", ")}`);
 ```
 
+## 🛡️ Type-Safe Query Building
+
+Dyno-table provides comprehensive query methods that match DynamoDB's capabilities while maintaining type safety:
+
+### Comparison Operators
+
+| Operation                 | Method Example                                          | Generated Expression              |
+|---------------------------|---------------------------------------------------------|-----------------------------------|
+| **Equals**                | `.filter(op => op.eq("status", "ACTIVE"))`              | `status = :v1`                    |
+| **Not Equals**            | `.filter(op => op.ne("status", "DELETED"))`             | `status <> :v1`                   |
+| **Less Than**             | `.filter(op => op.lt("age", 18))`                       | `age < :v1`                       |
+| **Less Than or Equal**    | `.filter(op => op.lte("score", 100))`                   | `score <= :v1`                    |
+| **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`              |
+
+### Logical Operators
+
+| Operation | Method Example                                                                    | Generated Expression           |
+|-----------|-----------------------------------------------------------------------------------|--------------------------------|
+| **AND**   | `.filter(op => op.and(op.eq("status", "ACTIVE"), op.gt("age", 18)))`              | `status = :v1 AND age > :v2`   |
+| **OR**    | `.filter(op => op.or(op.eq("status", "PENDING"), op.eq("status", "PROCESSING")))` | `status = :v1 OR status = :v2` |
+| **NOT**   | `.filter(op => op.not(op.eq("status", "DELETED")))`                               | `NOT status = :v1`             |
+
 ### Query Operations
 
+| Operation                | Method Example                                                                       | Generated Expression                  |
+|--------------------------|--------------------------------------------------------------------------------------|---------------------------------------|
+| **Partition Key Equals** | `.query({ pk: "USER#123" })`                                                         | `pk = :pk`                            |
+| **Sort Key Begins With** | `.query({ pk: "USER#123", sk: op => op.beginsWith("ORDER#2023") })`                  | `pk = :pk AND begins_with(sk, :v1)`   |
+| **Sort Key Between**     | `.query({ pk: "USER#123", sk: op => op.between("ORDER#2023-01", "ORDER#2023-12") })` | `pk = :pk AND sk BETWEEN :v1 AND :v2` |
+
+Additional query options:
 ```ts
-// Basic query
-const result = await table
-  .query({ pk: "SPECIES#trex" })
+// Sort order
+const ascending = await table
+  .query({ pk: "USER#123" })
+  .sortAscending()
   .execute();
 
-// Advanced query with conditions
-const result = await table
-  .query({
-    pk: "SPECIES#velociraptor",
-    sk: { operator: "begins_with", value: "PROFILE#" }
-  })
-  .where("type", "=", "DINOSAUR")
-  .whereGreaterThan("length", 6)
-  .limit(10)
-  .useIndex("GSI1")
+const descending = await table
+  .query({ pk: "USER#123" })
+  .sortDescending()
+  .execute();
+
+// Projection (select specific attributes)
+const partial = await table
+  .query({ pk: "USER#123" })
+  .select(["name", "email"])
   .execute();
 
-// Available query conditions:
-// .where(field, operator, value)        // Generic condition
-// .whereEquals(field, value)            // Equality check
-// .whereBetween(field, start, end)      // Range check
-// .whereIn(field, values)               // IN check
-// .whereLessThan(field, value)          // < check
-// .whereLessThanOrEqual(field, value)   // <= check
-// .whereGreaterThan(field, value)       // > check
-// .whereGreaterThanOrEqual(field, value) // >= check
-// .whereNotEqual(field, value)          // <> check
-// .whereBeginsWith(field, value)        // begins_with check
-// .whereContains(field, value)          // contains check
-// .whereNotContains(field, value)       // not_contains check
-// .whereExists(field)                   // attribute_exists check
-// .whereNotExists(field)                // attribute_not_exists check
-// .whereAttributeType(field, type)      // attribute_type check
+// Limit results
+const limited = await table
+  .query({ pk: "USER#123" })
+  .limit(10)
+  .execute();
 ```
 
-### Scan Operations
+### Update Operations
 
-```ts
-// Basic scan
-const result = await table.scan().execute();
+| Operation            | Method Example                                        | Generated Expression |
+|----------------------|-------------------------------------------------------|----------------------|
+| **Set Attributes**   | `.update(key).set("name", "New Name")`                | `SET #name = :v1`    |
+| **Add to Number**    | `.update(key).add("score", 10)`                       | `ADD #score :v1`     |
+| **Remove Attribute** | `.update(key).remove("temporary")`                    | `REMOVE #temporary`  |
+| **Delete From Set**  | `.update(key).deleteElementsFromSet("tags", ["old"])` | `DELETE #tags :v1`   |
 
-// Filtered scan
+#### Condition Operators
+
+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)))` |
+
+All operators are type-safe and will provide proper TypeScript inference for nested attributes.
+
+#### Multiple Operations
+Operations can be combined in a single update:
+```ts
 const result = await table
-  .scan()
-  .whereEquals("type", "DINOSAUR")
-  .where("length", ">", 20)
-  .limit(20)
+  .update({ pk: "USER#123", sk: "PROFILE" })
+  .set("name", "Updated Name")
+  .add("loginCount", 1)
+  .remove("temporaryFlag")
+  .condition(op => op.attributeExists("email"))
   .execute();
-
-// Scan supports all the same conditions as Query operations
 ```
 
-### Batch Operations
+## 🔄 Type Safety Features
+
+The library provides comprehensive type safety for all operations:
 
+### Nested Object Support
 ```ts
-// Batch write (put)
-const dinos = [
-  { pk: "SPECIES#trex", sk: "PROFILE#001", name: "Rex", length: 40 },
-  { pk: "SPECIES#raptor", sk: "PROFILE#001", name: "Blue", length: 6 },
-];
+interface Dinosaur {
+  pk: string;
+  sk: string;
+  name: string;
+  species: string;
+  stats: {
+    health: number;
+    weight: number;
+    length: number;
+    age: number;
+  };
+  habitat: {
+    enclosure: {
+      id: string;
+      section: string;
+      climate: string;
+    };
+    requirements: {
+      temperature: number;
+      humidity: number;
+    };
+  };
+  care: {
+    feeding: {
+      schedule: string;
+      diet: string;
+      lastFed: string;
+    };
+    medical: {
+      lastCheckup: string;
+      vaccinations: string[];
+    };
+  };
+}
 
-await table.batchWrite(
-  dinos.map((dino) => ({ type: "put", item: dino }))
-);
+// TypeScript ensures type safety for all nested dinosaur attributes
+await table.update<Dinosaur>({ pk: "ENCLOSURE#F", sk: "DINO#007" })
+  .set("stats.health", 95) // ✓ Valid
+  .set("habitat.enclosure.climate", "Tropical") // ✓ Valid
+  .set("care.feeding.lastFed", new Date().toISOString()) // ✓ Valid
+  .set("stats.invalid", true) // ❌ TypeScript Error: property doesn't exist
+  .execute();
+```
 
-// Batch write (delete)
-await table.batchWrite([
-  { type: "delete", key: { pk: "SPECIES#trex", sk: "PROFILE#001" } },
-  { type: "delete", key: { pk: "SPECIES#raptor", sk: "PROFILE#001" } },
-]);
+### Type-Safe Conditions
+```ts
+interface DinosaurMonitoring {
+  species: string;
+  health: number;
+  lastFed: string;
+  temperature: number;
+  behavior: string[];
+  alertLevel: "LOW" | "MEDIUM" | "HIGH";
+}
 
-// Batch operations automatically handle chunking for large datasets
+await table.query<DinosaurMonitoring>({
+  pk: "MONITORING",
+  sk: op => op.beginsWith("ENCLOSURE#")
+})
+.filter(op => op.and(
+  op.lt("health", "90"), // ❌ TypeScript Error: health expects number
+  op.gt("temperature", 38), // ✓ Valid
+  op.contains("behavior", "aggressive"), // ✓ Valid
+  op.eq("alertLevel", "UNKNOWN") // ❌ TypeScript Error: invalid alert level
+))
+.execute();
 ```
 
-### Pagination
+## 🔄 Batch Operations
 
-```ts
-// Limit to 10 items per page
-const paginator = await table.query({ pk: "SPECIES#trex" }).limit(10).paginate();
-// const paginator = await table.scan().limit(10).paginate();
+The library supports efficient batch operations for both reading and writing multiple items:
 
-while (paginator.hasNextPage()) {
-  const page = await paginator.getPage();
-  console.log(page);
-}
+### Batch Get
+```ts
+const { items, unprocessedKeys } = await table.batchGet<User>([
+  { pk: "USER#1", sk: "PROFILE" },
+  { pk: "USER#2", sk: "PROFILE" }
+]);
 ```
 
-### Transaction Operations
+### Batch Write
+```ts
+const { unprocessedItems } = await table.batchWrite<User>([
+  { type: "put", item: newUser },
+  { type: "delete", key: { pk: "USER#123", sk: "PROFILE" } }
+]);
+```
 
-Two ways to perform transactions:
+## 🔒 Transaction Operations
 
-#### Using withTransaction
+Perform multiple operations atomically with transaction support:
 
+### Transaction Builder
 ```ts
-await table.withTransaction(async (trx) => {
-  table.put(trex).withTransaction(trx);
-  table.put(raptor).withTransaction(trx);
-  table.delete(brontoKey).withTransaction(trx);
+const result = await table.transaction(async (tx) => {
+  // Building the expression manually
+  tx.put("TableName", { pk: "123", sk: "123"}, and(op.attributeNotExists("pk"), op.attributeExists("sk")));
+
+  // Using table to build the operation
+  table
+    .put({ pk: "123", sk: "123" })
+    .condition((op) => {
+      return op.and(op.attributeNotExists("pk"), op.attributeExists("sk"));
+    })
+    .withTransaction(tx);
+
+  // Building raw condition check
+  tx.conditionCheck(
+    "TestTable",
+    { pk: "transaction#test", sk: "condition#item" },
+    eq("status", "active"),
+  );
+
+  // Using table to build the condition check
+  table
+    .conditionCheck({
+      pk: "transaction#test",
+      sk: "conditional#item",
+    })
+    .condition((op) => op.eq("status", "active"));
 });
 ```
 
-#### Using TransactionBuilder
-
+### Transaction Options
 ```ts
-const transaction = new TransactionBuilder();
+const result = await table.transaction(
+  async (tx) => {
+    // ... transaction operations
+  },
+  {
+    // Optional transaction settings
+    idempotencyToken: "unique-token",
+    returnValuesOnConditionCheckFailure: true
+  }
+);
+```
 
-transaction
-  .addOperation({
-    put: { item: trex }
-  })
-  .addOperation({
-    put: { item: raptor }
-  })
-  .addOperation({
-    delete: { key: brontoKey }
-  });
+## 🏗️ Entity Pattern Best Practices (Coming Soon TM)
 
-await table.transactWrite(transaction);
+The entity implementation provides automatic type isolation:
+
+```ts
+// All operations are automatically scoped to DINOSAUR type
+const dinosaur = await dinoEntity.get("SPECIES#trex", "PROFILE#trex"); 
+// Returns Dinosaur | undefined
+
+// Cross-type operations are prevented at compile time
+dinoEntity.create({ /* invalid shape */ }); // TypeScript error
 ```
 
-## Repository Pattern
+**Key benefits:**
+- 🚫 Prevents accidental cross-type data access
+- 🔍 Automatically filters queries/scans to repository type
+- 🛡️ Ensures consistent key structure across entities
+- 📦 Encapsulates domain-specific query logic
 
-Create a repository by extending the `BaseRepository` class.
+## 🚨 Error Handling
 
-```ts
-import { BaseRepository } from "dyno-table";
+**TODO:**
+to provide a more clear set of error classes and additional information to allow for an easier debugging experience
 
-type DinoRecord = {
-  id: string;
-  name: string;
-  diet: string;
-  length: number;
-};
-
-class DinoRepository extends BaseRepository<DinoRecord> {
-  protected createPrimaryKey(data: DinoRecord) {
-    return {
-      pk: `SPECIES#${data.id}`,
-      sk: `PROFILE#${data.id}`,
-    };
-  }
+## 📚 API Reference
 
-  protected getType() {
-    return "DINOSAUR";
-  }
+### Condition Operators
 
-  // Add custom methods
-  async findByDiet(diet: string) {
-    return this.scan()
-      .whereEquals("diet", diet)
-      .execute();
-  }
+All condition operators are type-safe and will validate against your item type. For detailed information about DynamoDB conditions and expressions, see the [AWS DynamoDB Developer Guide](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html).
 
-  async findLargerThan(length: number) {
-    return this.scan()
-      .whereGreaterThan("length", length)
-      .execute();
-  }
-}
-```
+#### Comparison Operators
+- `eq(attr, value)` - Equals (=)
+- `ne(attr, value)` - Not equals (≠)
+- `lt(attr, value)` - Less than (<)
+- `lte(attr, value)` - Less than or equal to (≤)
+- `gt(attr, value)` - Greater than (>)
+- `gte(attr, value)` - Greater than or equal to (≥)
+- `between(attr, lower, upper)` - Between two values (inclusive)
+- `beginsWith(attr, value)` - Checks if string begins with value
+- `contains(attr, value)` - Checks if string/set contains value
 
-### Repository Operations
+```ts
+// Example: Health and feeding monitoring
+await dinoTable
+  .query<Dinosaur>({
+    pk: "ENCLOSURE#G"
+  })
+  .filter((op) => op.and(
+    op.lt("stats.health", 85),  // Health below 85%
+    op.lt("care.feeding.lastFed", new Date(Date.now() - 12 * 60 * 60 * 1000).toISOString()),  // Not fed in 12 hours
+    op.between("stats.weight", 1000, 5000)  // Medium-sized dinosaurs
+  ))
+  .execute();
+```
 
-The repository pattern in dyno-table not only provides a clean abstraction but also ensures data isolation through type-scoping. All operations available on the `Table` class are also available on your repository, but they're automatically scoped to the repository's type.
+#### Attribute Operators
+- `attributeExists(attr)` - Checks if attribute exists
+- `attributeNotExists(attr)` - Checks if attribute does not exist
 
 ```ts
-const dinoRepo = new DinoRepository(table);
+// Example: Validate required attributes for dinosaur transfer
+await dinoTable
+  .update<Dinosaur>({
+    pk: "ENCLOSURE#H", 
+    sk: "DINO#008"
+  })
+  .set("habitat.enclosure.id", "ENCLOSURE#J")
+  .condition((op) => op.and(
+    // Ensure all required health data is present
+    op.attributeExists("stats.health"),
+    op.attributeExists("care.medical.lastCheckup"),
+    // Ensure not already in transfer
+    op.attributeNotExists("transfer.inProgress"),
+    // Verify required monitoring tags
+    op.attributeExists("care.medical.vaccinations")
+  ))
+  .execute();
+```
+
+#### Logical Operators
+- `and(...conditions)` - Combines conditions with AND
+- `or(...conditions)` - Combines conditions with OR
+- `not(condition)` - Negates a condition
 
-// Query all T-Rexes - automatically includes type="DINOSAUR" condition
-const rexes = await dinoRepo
-  .query({ pk: "SPECIES#trex" })
+```ts
+// Example: Complex safety monitoring conditions
+await dinoTable
+  .query<Dinosaur>({
+    pk: "MONITORING#ALERTS"
+  })
+  .filter((op) => op.or(
+    // Alert: Aggressive carnivores with low health
+    op.and(
+      op.eq("care.feeding.diet", "Carnivore"),
+      op.lt("stats.health", 70),
+      op.contains("behavior", "aggressive")
+    ),
+    // Alert: Any dinosaur not fed recently and showing stress
+    op.and(
+      op.lt("care.feeding.lastFed", new Date(Date.now() - 8 * 60 * 60 * 1000).toISOString()),
+      op.contains("behavior", "stressed")
+    ),
+    // Alert: Enclosure climate issues
+    op.and(
+      op.not(op.eq("habitat.enclosure.climate", "Optimal")),
+      op.or(
+        op.gt("habitat.requirements.temperature", 40),
+        op.lt("habitat.requirements.humidity", 50)
+      )
+    )
+  ))
   .execute();
+```
 
-// Scan for large carnivores - automatically includes type="DINOSAUR"
-const largeCarnivores = await dinoRepo
-  .scan()
-  .whereEquals("diet", "Carnivore")
-  .whereGreaterThan("length", 30)
+### Key Condition Operators
+
+Special operators for sort key conditions in queries. See [AWS DynamoDB Key Condition Expressions](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html#Query.KeyConditionExpressions) for more details.
+
+```ts
+// Example: Query recent health checks by enclosure
+const recentHealthChecks = await dinoTable
+  .query<Dinosaur>({
+    pk: "ENCLOSURE#K",
+    sk: (op) => op.beginsWith(`HEALTH#${new Date().toISOString().slice(0, 10)}`)  // Today's checks
+  })
   .execute();
 
-// Put operation, the type attribute is automatically along with the primary key/secondary key is created
-await dinoRepo.create({
-  id: "trex",
-  name: "Rex",
-  diet: "Carnivore",
-  length: 40
-}).execute();
-
-// Update operation
-await dinoRepo
-  .update({ pk: "SPECIES#trex", sk: "PROFILE#001" })
-  .set("diet", "Omnivore")
+// Example: Query dinosaurs by weight range in specific enclosure
+const largeHerbivores = await dinoTable
+  .query<Dinosaur>({
+    pk: "DIET#herbivore",
+    sk: (op) => op.between(
+      `WEIGHT#${5000}`,  // 5 tons minimum
+      `WEIGHT#${15000}`  // 15 tons maximum
+    )
+  })
   .execute();
 
-// Delete operation
-await dinoRepo
-  .delete({ pk: "SPECIES#trex", sk: "PROFILE#001" })
+// Example: Find all dinosaurs in quarantine by date range
+const quarantinedDinos = await dinoTable
+  .query<Dinosaur>({
+    pk: "STATUS#quarantine",
+    sk: (op) => op.between(
+      `DATE#${new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString().slice(0, 10)}`,  // Last 7 days
+      `DATE#${new Date().toISOString().slice(0, 10)}`  // Today
+    )
+  })
   .execute();
 ```
 
-This type-scoping ensures that:
-- Each repository only accesses its own data type
-- Queries automatically include type filtering
-- Put operations automatically include the type attribute
-- Updates and deletes are constrained to the correct type
+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)
 
-This pattern is particularly useful in single-table designs where multiple entity types share the same table. Each repository provides a type-safe, isolated view of its own data while preventing accidental cross-type operations.
-
-## Contributing 🤝
-```bash
-# Installing the dependencies
-pnpm i
+## 🔮 Future Roadmap
 
-# Installing the peerDependencies manually
-pnpm i @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
-```
+- [ ] Enhanced query plan visualization
+- [ ] Migration tooling
+- [ ] Local secondary index support
+- [ ] Multi-table transaction support
 
-### Developing
+## 🤝 Contributing
 
 ```bash
-docker run -p 8000:8000 amazon/dynamodb-local
-```
+# Set up development environment
+pnpm install
+
+# Run tests (requires local DynamoDB)
+pnpm run ddb:start
+pnpm test
+
+# Build the project
+pnpm build
+```