dyno-table 0.2.0-0 → 1.0.0-alpha.1

package/README.md

@@ -6,46 +6,35 @@
 <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;">
 
 ```ts
-// Type-safe dinosaur tracking operations made simple
-await dinoTable
+// Type-safe DynamoDB operations made simple
+await table
   .update<Dinosaur>({
     pk: 'SPECIES#trex',
     sk: 'PROFILE#001'
   })
-  .set('diet', 'Carnivore')      // Update dietary classification
-  .add('sightings', 1)           // Increment sighting counter
-  .condition(op => op.eq('status', 'ACTIVE'))  // Only if dinosaur is active
+  .set('diet', 'Carnivore')
+  .add('sightings', 1)
+  .condition(op => op.eq('status', 'ACTIVE'))
   .execute();
 ```
 
-> This README provides a concise overview of dyno-table's features with dinosaur-themed examples. For detailed documentation on specific features, please refer to the individual markdown files in the `docs/` directory.
-
-## 🌟 Why dyno-table for your Dinosaur Data?
+## 🌟 Why dyno-table?
 
-- **🦕 Dinosaur-sized data made manageable** - Clean abstraction layer for complex DynamoDB patterns
-- **🛡️ Extinction-proof type safety** - Full TypeScript support with strict type checking
-- **⚡ Velociraptor-fast API** - Chainable builder pattern for complex operations
-- **🔒 T-Rex-proof transactional safety** - ACID-compliant operations with easy-to-use transactions
-- **📈 Jurassic-scale performance** - Automatic batch chunking and pagination handling
+- **🧩 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
 
 - [🦖 dyno-table  ](#-dyno-table--)
-  - [🌟 Why dyno-table for your Dinosaur Data?](#-why-dyno-table-for-your-dinosaur-data)
+  - [🌟 Why dyno-table?](#-why-dyno-table)
   - [📑 Table of Contents](#-table-of-contents)
   - [📦 Installation](#-installation)
   - [🚀 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)
-  - [🏗️ Entity Pattern](#️-entity-pattern-with-standard-schema-validators)
-    - [Defining Entities](#defining-entities)
-    - [Entity Features](#entity-features)
-      - [1. Schema Validation](#1-schema-validation)
-      - [2. CRUD Operations](#2-crud-operations)
-      - [3. Custom Queries](#3-custom-queries)
-      - [4. Indexes for Efficient Querying](#4-indexes-for-efficient-querying)
-      - [5. Lifecycle Hooks](#5-lifecycle-hooks)
-    - [Complete Entity Example](#complete-entity-example)
+    - [1. Configure Your Table](#1-configure-your-table)
+    - [2. Perform Type-Safe Operations](#2-perform-type-safe-operations)
   - [🧩 Advanced Features](#-advanced-features)
     - [Transactional Operations](#transactional-operations)
     - [Batch Processing](#batch-processing)
@@ -67,6 +56,7 @@ await dinoTable
   - [🔒 Transaction Operations](#-transaction-operations)
     - [Transaction Builder](#transaction-builder)
     - [Transaction Options](#transaction-options)
+  - [🏗️ Entity Pattern Best Practices (Coming Soon TM)](#️-entity-pattern-best-practices-coming-soon-tm)
   - [🚨 Error Handling](#-error-handling)
   - [📚 API Reference](#-api-reference)
     - [Condition Operators](#condition-operators-1)
@@ -92,26 +82,25 @@ npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
 
 ## 🚀 Quick Start
 
-### 1. Configure Your Jurassic Table
+### 1. Configure Your Table
 
 ```ts
 import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
 import { DynamoDBDocument } from "@aws-sdk/lib-dynamodb";
-import { Table } from "dyno-table/table";
+import { Table } from "dyno-table";
 
-// Configure AWS SDK clients - your gateway to the prehistoric database
+// Configure AWS SDK clients
 const client = new DynamoDBClient({ region: "us-west-2" });
 const docClient = DynamoDBDocument.from(client);
 
-// Initialize table with single-table design schema - your dinosaur park database
+// Initialize table with single-table design schema
 const dinoTable = new Table({
   client: docClient,
-  tableName: "JurassicPark", // Your central dinosaur tracking system
+  tableName: "DinosaurPark",
   indexes: {
-    partitionKey: "pk",      // Primary partition key for fast dinosaur lookups
-    sortKey: "sk",           // Sort key for organizing dinosaur data
+    partitionKey: "pk",
+    sortKey: "sk",
     gsis: {
-      // Global Secondary Index for querying dinosaurs by species
       speciesId: {
         partitionKey: "gsi1pk",
         sortKey: "gsi1sk",
@@ -121,538 +110,141 @@ const dinoTable = new Table({
 });
 ```
 
-### 2. Perform Type-Safe Dinosaur Operations
+### 2. Perform Type-Safe Operations
 
-**🦖 Creating a new dinosaur specimen**
+**🦖 Creating a new dinosaur**
 ```ts
-// Add a new T-Rex to your collection with complete type safety
 const rex = await dinoTable
   .create<Dinosaur>({
-    pk: "SPECIES#trex",           // Partition key identifies the species
-    sk: "PROFILE#trex",           // Sort key for the specific profile
-    speciesId: "trex",            // For GSI queries
-    name: "Tyrannosaurus Rex",    // Display name
-    diet: "carnivore",            // Dietary classification
-    length: 12.3,                 // Size in meters
-    discoveryYear: 1902           // When first discovered
+    pk: "SPECIES#trex",
+    sk: "PROFILE#trex",
+    speciesId: "trex",
+    name: "Tyrannosaurus Rex",
+    diet: "carnivore",
+    length: 12.3,
+    discoveryYear: 1902
   })
   .execute();
 ```
 
-**🔍 Query for specific dinosaurs with conditions**
+**🔍 Query with conditions**
 ```ts
-// Find large carnivorous dinosaurs in the T-Rex species
 const largeDinos = await dinoTable
   .query<Dinosaur>({ 
-    pk: "SPECIES#trex",                    // Target the T-Rex species
-    sk: (op) => op.beginsWith("PROFILE#")  // Look in profile records
+    pk: "SPECIES#trex",
+    sk: (op) => op.beginsWith("PROFILE#")
   })
   .filter((op) => op.and(
-    op.gte("length", 10),                  // Only dinosaurs longer than 10 meters
-    op.eq("diet", "carnivore")             // Must be carnivores
+    op.gte("length", 10),
+    op.eq("diet", "carnivore")
   ))
-  .limit(10)                               // Limit to 10 results
+  .limit(10)
   .execute();
 ```
 
-**🔄 Update dinosaur classification**
+**🔄 Complex update operation**
 ```ts
-// Update a dinosaur's diet classification based on new research
 await dinoTable
   .update<Dinosaur>({ 
-    pk: "SPECIES#trex",           // Target the T-Rex species
-    sk: "PROFILE#trex"            // Specific profile to update
+    pk: "SPECIES#trex", 
+    sk: "PROFILE#trex" 
   })
-  .set("diet", "omnivore")        // New diet classification based on fossil evidence
-  .add("discoveryYear", 1)        // Adjust discovery year with new findings
-  .remove("outdatedField")        // Remove deprecated information
-  .condition((op) => op.attributeExists("discoverySite"))  // Only if discovery site is documented
+  .set("diet", "omnivore")
+  .add("discoveryYear", 1)
+  .remove("outdatedField")
+  .condition((op) => op.attributeExists("discoverySite"))
   .execute();
 ```
 
-## 🏗️ Entity Pattern with Standard Schema validators
-
-The entity pattern provides a structured, type-safe way to work with DynamoDB items.
-It combines schema validation, key management, and repository operations into a cohesive abstraction.
-
-✨ This library supports all standard schema validation libraries, including **zod**, **arktype**, and **valibot**,
-allowing you to choose your preferred validation tool!
-
-### Defining Entities
-
-Entities are defined using the `defineEntity` function, which takes a configuration object that includes a schema, primary key definition, and optional indexes and queries.
-
-```ts
-import { z } from "zod";
-import { defineEntity, createIndex } from "dyno-table/entity";
-
-// Define your schema using Zod
-const dinosaurSchema = z.object({
-  id: z.string(),
-  species: z.string(),
-  name: z.string(),
-  diet: z.enum(["carnivore", "herbivore", "omnivore"]),
-  dangerLevel: z.number().int().min(1).max(10),
-  height: z.number().positive(),
-  weight: z.number().positive(),
-  status: z.enum(["active", "inactive", "sick", "deceased"]),
-  createdAt: z.string().optional(),
-  updatedAt: z.string().optional(),
-});
-
-// Infer the type from the schema
-type Dinosaur = z.infer<typeof dinosaurSchema>;
-
-// Define key templates for Dinosaur entity
-const dinosaurPK = partitionKey`ENTITY#DINOSAUR#DIET#${"diet"}`;
-const dinosaurSK = sortKey`ID#${"id"}#SPECIES#${"species"}`;
-
-// Create a primary index for Dinosaur entity
-const primaryKey = createIndex()
-  .input(z.object({ id: z.string(), diet: z.string(), species: z.string() }))
-  .partitionKey(({ diet }) => dinosaurPK({ diet }))
-  .sortKey(({ id, species }) => dinosaurSK({ species, id }));
-
-// Define the entity
-const DinosaurEntity = defineEntity({
-  name: "Dinosaur",
-  schema: dinosaurSchema,
-  primaryKey,
-});
-
-// Create a repository
-const dinosaurRepo = DinosaurEntity.createRepository(table);
-```
-
-### Entity Features
-
-#### 1. Schema Validation
-
-Entities use Zod schemas to validate data before operations:
-
-```ts
-// Define a schema with Zod
-const dinosaurSchema = z.object({
-  id: z.string(),
-  species: z.string(),
-  name: z.string(),
-  diet: z.enum(["carnivore", "herbivore", "omnivore"]),
-  dangerLevel: z.number().int().min(1).max(10),
-  height: z.number().positive(),
-  weight: z.number().positive(),
-  status: z.enum(["active", "inactive", "sick", "deceased"]),
-  tags: z.array(z.string()).optional(),
-});
-
-// Create an entity with the schema
-const DinosaurEntity = defineEntity({
-  name: "Dinosaur",
-  schema: dinosaurSchema,
-  primaryKey: createIndex()
-          .input(z.object({ id: z.string(), diet: z.string(), species: z.string() }))
-          .partitionKey(({ diet }) => dinosaurPK({ diet }))
-          .sortKey(({ id, species }) => dinosaurSK({ species, id }))
-});
-```
-
-#### 2. CRUD Operations
-
-Entities provide type-safe CRUD operations:
-
-```ts
-// Create a new dinosaur
-await dinosaurRepo.create({
-  id: "dino-001",
-  species: "Tyrannosaurus Rex",
-  name: "Rexy",
-  diet: "carnivore",
-  dangerLevel: 10,
-  height: 5.2,
-  weight: 7000,
-  status: "active",
-}).execute();
-
-// Get a dinosaur
-const dino = await dinosaurRepo.get({
-  id: "dino-001",
-  diet: "carnivore",
-  species: "Tyrannosaurus Rex",
-}).execute();
-
-// Update a dinosaur
-await dinosaurRepo.update(
-  { id: "dino-001", diet: "carnivore", species: "Tyrannosaurus Rex" },
-  { weight: 7200, status: "sick" }
-).execute();
-
-// Delete a dinosaur
-await dinosaurRepo.delete({
-  id: "dino-001",
-  diet: "carnivore",
-  species: "Tyrannosaurus Rex",
-}).execute();
-```
-
-#### 3. Custom Queries
-
-Define custom queries with input validation:
-
-```ts
-import { createQueries } from "dyno-table/entity";
-
-const createQuery = createQueries<Dinosaur>();
-
-const DinosaurEntity = defineEntity({
-  name: "Dinosaur",
-  schema: dinosaurSchema,
-  primaryKey,
-  queries: {
-    byDiet: createQuery
-      .input(
-        z.object({
-          diet: z.enum(["carnivore", "herbivore", "omnivore"]),
-        })
-      )
-      .query(({ input, entity }) => {
-        return entity
-          .scan()
-          .filter((op) => op.eq("diet", input.diet));
-      }),
-
-    bySpecies: createQuery
-      .input(
-        z.object({
-          species: z.string(),
-        })
-      )
-      .query(({ input, entity }) => {
-        return entity
-          .scan()
-          .filter((op) => op.eq("species", input.species));
-      }),
-  },
-});
-
-// Use the custom queries
-const carnivores = await dinosaurRepo.query.byDiet({ diet: "carnivore" }).execute();
-const trexes = await dinosaurRepo.query.bySpecies({ species: "Tyrannosaurus Rex" }).execute();
-```
-
-#### 4. Indexes for Efficient Querying
-
-Define indexes for efficient access patterns:
-
-```ts
-import { createIndex } from "dyno-table/entity";
-
-// Define GSI for querying by species
-const speciesIndex = createIndex()
-  .input(dinosaurSchema)
-  .partitionKey(({ species }) => `SPECIES#${species}`)
-  .sortKey(({ id }) => `DINOSAUR#${id}`);
-
-const DinosaurEntity = defineEntity({
-  name: "Dinosaur",
-  schema: dinosaurSchema,
-  primaryKey,
-  indexes: {
-    species: speciesIndex,
-  },
-  queries: {
-    bySpecies: createQuery
-      .input(
-        z.object({
-          species: z.string(),
-        })
-      )
-      .query(({ input, entity }) => {
-        return entity
-          .queryBuilder({
-            pk: `SPECIES#${input.species}`,
-          })
-          .useIndex("species");
-      }),
-  },
-});
-```
-
-#### 5. Lifecycle Hooks
-
-Add hooks for pre/post processing:
-
-```ts
-const dinosaurHooks = {
-  afterGet: async (data: Dinosaur | undefined) => {
-    if (data) {
-      return {
-        ...data,
-        displayName: `${data.name} (${data.species})`,
-        threatLevel: data.dangerLevel > 7 ? "HIGH" : "MODERATE",
-      };
-    }
-    return data;
-  },
-};
-
-const DinosaurEntity = defineEntity({
-  name: "Dinosaur",
-  schema: dinosaurSchema,
-  primaryKey,
-  hooks: dinosaurHooks,
-});
-```
-
-### Complete Entity Example
-
-Here's a complete example using Zod schemas directly:
-
-```ts
-import { z } from "zod";
-import { defineEntity, createQueries, createIndex } from "dyno-table/entity";
-import { Table } from "dyno-table/table";
-
-// Define the schema with Zod
-const dinosaurSchema = z.object({
-  id: z.string(),
-  species: z.string(),
-  name: z.string(),
-  enclosureId: z.string(),
-  diet: z.enum(["carnivore", "herbivore", "omnivore"]),
-  dangerLevel: z.number().int().min(1).max(10),
-  height: z.number().positive(),
-  weight: z.number().positive(),
-  status: z.enum(["active", "inactive", "sick", "deceased"]),
-  trackingChipId: z.string().optional(),
-  lastFed: z.string().optional(),
-  createdAt: z.string().optional(),
-  updatedAt: z.string().optional(),
-});
-
-// Infer the type from the schema
-type Dinosaur = z.infer<typeof dinosaurSchema>;
-
-// Define key templates
-const dinosaurPK = (id: string) => `DINOSAUR#${id}`;
-const dinosaurSK = (status: string) => `STATUS#${status}`;
-
-// Create a primary index
-const primaryKey = createIndex()
-  .input(dinosaurSchema)
-  .partitionKey(({ id }) => dinosaurPK(id))
-  .sortKey(({ status }) => dinosaurSK(status));
-
-// Create a GSI for querying by species
-const speciesIndex = createIndex()
-  .input(dinosaurSchema)
-  .partitionKey(({ species }) => `SPECIES#${species}`)
-  .sortKey(({ id }) => `DINOSAUR#${id}`);
-
-// Create a GSI for querying by enclosure
-const enclosureIndex = createIndex()
-  .input(dinosaurSchema)
-  .partitionKey(({ enclosureId }) => `ENCLOSURE#${enclosureId}`)
-  .sortKey(({ id }) => `DINOSAUR#${id}`);
-
-// Create query builders
-const createQuery = createQueries<Dinosaur>();
-
-// Define the entity
-const DinosaurEntity = defineEntity({
-  name: "Dinosaur",
-  schema: dinosaurSchema,
-  primaryKey,
-  indexes: {
-    species: speciesIndex,
-    enclosure: enclosureIndex,
-  },
-  queries: {
-    bySpecies: createQuery
-      .input(
-        z.object({
-          species: z.string(),
-        })
-      )
-      .query(({ input, entity }) => {
-        return entity
-          .queryBuilder({
-            pk: `SPECIES#${input.species}`,
-          })
-          .useIndex("species");
-      }),
-
-    byEnclosure: createQuery
-      .input(
-        z.object({
-          enclosureId: z.string(),
-        })
-      )
-      .query(({ input, entity }) => {
-        return entity
-          .queryBuilder({
-            pk: `ENCLOSURE#${input.enclosureId}`,
-          })
-          .useIndex("enclosure");
-      }),
-
-    dangerousInEnclosure: createQuery
-      .input(
-        z.object({
-          enclosureId: z.string(),
-          minDangerLevel: z.number().int().min(1).max(10),
-        })
-      )
-      .query(({ input, entity }) => {
-        return entity
-          .queryBuilder({
-            pk: `ENCLOSURE#${input.enclosureId}`,
-          })
-          .useIndex("enclosure")
-          .filter((op) => op.gte("dangerLevel", input.minDangerLevel));
-      }),
-  },
-});
-
-// Create a repository
-const dinosaurRepo = DinosaurEntity.createRepository(table);
-
-// Use the repository
-async function main() {
-  // Create a dinosaur
-  await dinosaurRepo
-    .create({
-      id: "dino-001",
-      species: "Tyrannosaurus Rex",
-      name: "Rexy",
-      enclosureId: "enc-001",
-      diet: "carnivore",
-      dangerLevel: 10,
-      height: 5.2,
-      weight: 7000,
-      status: "active",
-      trackingChipId: "TRX-001",
-    })
-    .execute();
-
-  // Query dinosaurs by species
-  const trexes = await dinosaurRepo.query.bySpecies({ 
-    species: "Tyrannosaurus Rex" 
-  }).execute();
-
-  // Query dangerous dinosaurs in an enclosure
-  const dangerousDinos = await dinosaurRepo.query.dangerousInEnclosure({
-    enclosureId: "enc-001",
-    minDangerLevel: 8,
-  }).execute();
-}
-```
-
-**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
-- 🧪 Validates data with Zod schemas
-- 🔄 Provides type inference from schemas
-
 ## 🧩 Advanced Features
 
 ### Transactional Operations
 
 **Safe dinosaur transfer between enclosures**
 ```ts
-// Start a transaction session for transferring a T-Rex to a new enclosure
-// Critical for safety: All operations must succeed or none will be applied
+// 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)
-  // This ensures the dinosaur transfer is atomic - preventing half-completed transfers
 
-  // STEP 1: Check if destination enclosure is ready and compatible with the dinosaur
-  // We must verify the enclosure is prepared and suitable for a carnivore
+  // Check if destination enclosure is ready and compatible
   await dinoTable
     .conditionCheck({ 
-      pk: "ENCLOSURE#B",          // Target enclosure B
-      sk: "STATUS"                // Check the enclosure status record
+      pk: "ENCLOSURE#B", 
+      sk: "STATUS" 
     })
     .condition(op => op.and(
-      op.eq("status", "READY"),   // Enclosure must be in READY state
-      op.eq("diet", "Carnivore")  // Must support carnivorous dinosaurs
+      op.eq("status", "READY"),
+      op.eq("diet", "Carnivore")  // Ensure enclosure matches dinosaur diet
     ))
     .withTransaction(tx);
 
-  // STEP 2: Remove dinosaur from current enclosure
-  // Only proceed if the dinosaur is healthy enough for transfer
+  // Remove dinosaur from current enclosure
   await dinoTable
     .delete<Dinosaur>({ 
-      pk: "ENCLOSURE#A",          // Source enclosure A
-      sk: "DINO#001"              // T-Rex with ID 001
+      pk: "ENCLOSURE#A", 
+      sk: "DINO#001" 
     })
     .condition(op => op.and(
-      op.eq("status", "HEALTHY"), // Dinosaur must be in HEALTHY state
-      op.gte("health", 80)        // Health must be at least 80%
+      op.eq("status", "HEALTHY"),
+      op.gte("health", 80)  // Only transfer healthy dinosaurs
     ))
     .withTransaction(tx);
 
-  // STEP 3: Add dinosaur to new enclosure
-  // Create a fresh record in the destination enclosure
+  // Add dinosaur to new enclosure
   await dinoTable
     .create<Dinosaur>({
-      pk: "ENCLOSURE#B",          // Destination enclosure B
-      sk: "DINO#001",             // Same dinosaur ID for tracking
-      name: "Rex",                // Dinosaur name
-      species: "Tyrannosaurus",   // Species classification
-      diet: "Carnivore",          // Dietary requirements
-      status: "HEALTHY",          // Current health status
-      health: 100,                // Reset health to 100% after transfer
-      enclosureId: "B",           // Update enclosure reference
-      lastFed: new Date().toISOString() // Reset feeding clock
+      pk: "ENCLOSURE#B",
+      sk: "DINO#001",
+      name: "Rex",
+      species: "Tyrannosaurus",
+      diet: "Carnivore",
+      status: "HEALTHY",
+      health: 100,
+      enclosureId: "B",
+      lastFed: new Date().toISOString()
     })
     .withTransaction(tx);
 
-  // STEP 4: Update enclosure occupancy tracking
-  // Keep accurate count of dinosaurs in each enclosure
+  // Update enclosure occupancy tracking
   await dinoTable
     .update<Dinosaur>({ 
-      pk: "ENCLOSURE#B",          // Target enclosure B
-      sk: "OCCUPANCY"             // Occupancy tracking record
+      pk: "ENCLOSURE#B", 
+      sk: "OCCUPANCY" 
     })
-    .add("currentOccupants", 1)   // Increment occupant count
-    .set("lastUpdated", new Date().toISOString()) // Update timestamp
+    .add("currentOccupants", 1)
+    .set("lastUpdated", new Date().toISOString())
     .withTransaction(tx);
 });
 
-// Transaction for dinosaur feeding and health monitoring
-// Ensures feeding status and schedule are updated atomically
+// Transaction with feeding and health monitoring
 await dinoTable.transaction(
   async (tx) => {
-    // STEP 1: Update Stegosaurus health and feeding status
-    // Record that the dinosaur has been fed and update its health metrics
+    // Update dinosaur health and feeding status
     await dinoTable
       .update<Dinosaur>({
-        pk: "ENCLOSURE#D",           // Herbivore enclosure D
-        sk: "DINO#003"               // Stegosaurus with ID 003
+        pk: "ENCLOSURE#D",
+        sk: "DINO#003"
       })
       .set({
-        status: "HEALTHY",           // Update health status
-        lastFed: new Date().toISOString(), // Record feeding time
-        health: 100                  // Reset health to 100%
+        status: "HEALTHY",
+        lastFed: new Date().toISOString(),
+        health: 100
       })
-      .deleteElementsFromSet("tags", ["needs_feeding"]) // Remove feeding alert tag
+      .deleteElementsFromSet("tags", ["needs_feeding"])
       .withTransaction(tx);
 
-    // STEP 2: Update enclosure feeding schedule
-    // Schedule next feeding time for tomorrow
+    // Update enclosure feeding schedule
     await dinoTable
       .update<Dinosaur>({
-        pk: "ENCLOSURE#D",           // Same herbivore enclosure
-        sk: "SCHEDULE"               // Feeding schedule record
+        pk: "ENCLOSURE#D",
+        sk: "SCHEDULE"
       })
-      .set("nextFeedingTime", new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString()) // 24 hours from now
+      .set("nextFeedingTime", new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString())
       .withTransaction(tx);
   },
   {
-    // Transaction options for tracking and idempotency
-    clientRequestToken: "feeding-session-001", // Prevents duplicate feeding operations
-    returnConsumedCapacity: "TOTAL"            // Track capacity usage for park operations
+    clientRequestToken: "feeding-session-001",
+    returnConsumedCapacity: "TOTAL"
   }
 );
 ```
@@ -669,42 +261,35 @@ await dinoTable.transaction(
 
 **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
+// Batch health check for multiple dinosaurs
 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
+  { pk: "ENCLOSURE#A", sk: "DINO#001" }, // T-Rex
+  { pk: "ENCLOSURE#B", sk: "DINO#002" }, // Velociraptor
+  { pk: "ENCLOSURE#C", sk: "DINO#003" }  // Stegosaurus
 ];
 
-// 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
+// Batch update feeding schedule for herbivore group
 const newHerbivores = [
   {
     pk: "ENCLOSURE#D", sk: "DINO#004",
-    name: "Triceratops Alpha",      // Three-horned herbivore
+    name: "Triceratops Alpha",
     species: "Triceratops",
     diet: "Herbivore",
     status: "HEALTHY",
-    health: 95,                     // Excellent health after quarantine
-    lastFed: new Date().toISOString() // Just fed before joining main enclosure
+    health: 95,
+    lastFed: new Date().toISOString()
   },
   {
     pk: "ENCLOSURE#D", sk: "DINO#005",
-    name: "Brachy",                 // Long-necked herbivore
+    name: "Brachy",
     species: "Brachiosaurus",
     diet: "Herbivore",
     status: "HEALTHY",
@@ -713,117 +298,91 @@ const newHerbivores = [
   }
 ];
 
-// Add all new herbivores to the enclosure in a single batch operation
-// More efficient than individual writes and ensures consistent state
+// Add new herbivores to enclosure
 await dinoTable.batchWrite(
   newHerbivores.map(dino => ({
-    type: "put",                    // Create or replace operation
-    item: dino                      // Full dinosaur record
+    type: "put",
+    item: dino
   }))
 );
 
-// SCENARIO 3: Releasing a dinosaur from quarantine to general population
-// Multiple related operations performed as a batch
+// Mixed operations: relocate dinosaurs and update enclosure status
 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
+  // 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",          // Juvenile Velociraptor
+      name: "Raptor Beta",
       species: "Velociraptor",
       diet: "Carnivore",
-      status: "HEALTHY",            // Now healthy after treatment
+      status: "HEALTHY",
       health: 100,
       lastFed: new Date().toISOString()
     }
   },
-
-  // Step 3: Clear quarantine status record
-  { 
-    type: "delete", 
-    key: { pk: "ENCLOSURE#QUARANTINE", sk: "STATUS#DINO#006" } 
-  }
+  // Clear quarantine status
+  { 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
+// 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 into multiple requests
+await dinoTable.batchWrite(dailyHealthUpdates); // Automatically chunked
 ```
 
 ### Pagination Made Simple
 
-**Efficient dinosaur record browsing for park management**
+**Efficient dinosaur record browsing**
 ```ts
-// SCENARIO 1: Herbivore health monitoring with pagination
-// Create a paginator for viewing healthy herbivores in manageable chunks
-// Perfect for veterinary staff doing routine health checks
+// Create a paginator for viewing herbivores by health status
 const healthyHerbivores = dinoTable
   .query<Dinosaur>({
-    pk: "DIET#herbivore",                    // Target all herbivorous dinosaurs
-    sk: op => op.beginsWith("STATUS#HEALTHY") // Only those with HEALTHY status
+    pk: "DIET#herbivore",
+    sk: op => op.beginsWith("STATUS#HEALTHY")
   })
   .filter((op) => op.and(
-    op.gte("health", 90),                    // Only those with excellent health (90%+)
-    op.attributeExists("lastFed")            // Must have feeding records
+    op.gte("health", 90),
+    op.attributeExists("lastFed")
   ))
-  .paginate(5);                              // Process in small batches of 5 dinosaurs
+  .paginate(5); // View 5 dinosaurs at a time
 
-// Iterate through all pages of results - useful for processing large datasets
-// without loading everything into memory at once
-console.log("🦕 Beginning herbivore health inspection rounds...");
+// Monitor all enclosures page by page
 while (healthyHerbivores.hasNextPage()) {
-  // Get the next page of dinosaurs
   const page = await healthyHerbivores.getNextPage();
   console.log(`Checking herbivores page ${page.page}, found ${page.items.length} dinosaurs`);
-
-  // Process each dinosaur in the current page
   page.items.forEach(dino => {
     console.log(`${dino.name}: Health ${dino.health}%, Last fed: ${dino.lastFed}`);
-    // In a real app, you might update health records or schedule next checkup
   });
 }
 
-// SCENARIO 2: Preparing carnivore feeding schedule
-// Get all carnivores at once for daily feeding planning
-// This approach loads all matching items into memory
+// Get all carnivores for daily feeding schedule
 const carnivoreSchedule = await dinoTable
   .query<Dinosaur>({
-    pk: "DIET#carnivore",                    // Target all carnivorous dinosaurs
-    sk: op => op.beginsWith("ENCLOSURE#")    // Organized by enclosure
+    pk: "DIET#carnivore",
+    sk: op => op.beginsWith("ENCLOSURE#")
   })
-  .filter(op => op.attributeExists("lastFed")) // Only those with feeding records
-  .paginate(10)                              // Process in pages of 10
-  .getAllPages();                            // But collect all results at once
+  .filter(op => op.attributeExists("lastFed"))
+  .paginate(10)
+  .getAllPages();
 
 console.log(`Scheduling feeding for ${carnivoreSchedule.length} carnivores`);
-// Now we can sort and organize feeding times based on species, size, etc.
 
-// SCENARIO 3: Visitor information kiosk with limited display
-// Create a paginated view for the public-facing dinosaur information kiosk
+// Limited view for visitor information kiosk
 const visitorKiosk = dinoTable
   .query<Dinosaur>({ 
-    pk: "VISITOR_VIEW",                      // Special partition for visitor-facing data
-    sk: op => op.beginsWith("SPECIES#")      // Organized by species
+    pk: "VISITOR_VIEW",
+    sk: op => op.beginsWith("SPECIES#")
   })
-  .filter(op => op.eq("status", "ON_DISPLAY")) // Only show dinosaurs currently on display
-  .limit(12)                                 // Show maximum 12 dinosaurs total
-  .paginate(4);                              // Display 4 at a time for easy viewing
+  .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 initial kiosk display
+// Get first page for kiosk display
 const firstPage = await visitorKiosk.getNextPage();
-console.log(`🦖 Now showing: ${firstPage.items.map(d => d.name).join(", ")}`);
-// Visitors can press "Next" to see more dinosaurs in the collection
+console.log(`Now showing: ${firstPage.items.map(d => d.name).join(", ")}`);
 ```
 
 ## 🛡️ Type-Safe Query Building
@@ -1111,6 +670,24 @@ const result = await table.transaction(
 );
 ```
 
+## 🏗️ Entity Pattern Best Practices (Coming Soon TM)
+
+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
+```
+
+**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
 
 ## 🚨 Error Handling
 
@@ -1273,6 +850,41 @@ pnpm test
 pnpm build
 ```
 
+## 📦 Release Process
+
+This project uses [semantic-release](https://github.com/semantic-release/semantic-release) for automated versioning and package publishing. The configuration is maintained in the `.releaserc.json` file. Releases are automatically triggered by commits to specific branches:
+
+- **Main Channel**: Stable releases from the `main` branch
+- **Alpha Channel**: Pre-releases from the `alpha` branch
+
+### Commit Message Format
+
+We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification for commit messages, which determines the release type:
+
+- `fix: ...` - Patch release (bug fixes)
+- `feat: ...` - Minor release (new features)
+- `feat!: ...` or `fix!: ...` or any commit with `BREAKING CHANGE:` in the footer - Major release
+
+### Release Workflow
+
+1. For regular features and fixes:
+   - Create a PR against the `main` branch
+   - Once merged, a new release will be automatically published
+
+2. For experimental features:
+   - Create a PR against the `alpha` branch
+   - Once merged, a new alpha release will be published with an alpha tag
+
+### Installing Specific Channels
+
+```bash
+# Install the latest stable version
+npm install dyno-table
+
+# Install the latest alpha version
+npm install dyno-table@alpha
+```
+
 ## 🦔 Running Examples
 
 There's a few pre-configured example scripts in the `examples` directory.
@@ -1296,10 +908,3 @@ npx tsx examples/[EXAMPLE_NAME].ts
 ```
 
 To view the test table GUI in action: [DynamoDB Admin](http://localhost:8001/)
-
-<br />
-To teardown the test table when you're done, run the following command:
-
-```bash
-pnpm run local:teardown
-```