dyno-table 1.0.0-alpha.1 → 1.0.0

package/README.md

@@ -1,107 +1,171 @@
-# 🦖 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)
+<div align="center">
 
-**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*
+# 🦖 dyno-table
+
+### **Tame Your DynamoDB Data with Type-Safe Precision**
+
+[![npm version](https://img.shields.io/npm/v/dyno-table.svg?style=for-the-badge)](https://www.npmjs.com/package/dyno-table) 
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-4.0%2B-blue?style=for-the-badge&logo=typescript)](https://www.typescriptlang.org/)
+[![AWS DynamoDB](https://img.shields.io/badge/AWS-DynamoDB-orange?style=for-the-badge&logo=amazon-aws)](https://aws.amazon.com/dynamodb/)
+
+</div>
+
+<p align="center"><strong>A powerful, type-safe abstraction layer for DynamoDB single-table designs</strong><br/>
+<em>Write cleaner, safer, and more maintainable DynamoDB code</em></p>
 
 <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;">
 
+## 🔥 Why Developers Choose dyno-table
+
 ```ts
-// Type-safe DynamoDB operations made simple
-await table
+// Type-safe dinosaur tracking operations made simple
+await dinoTable
   .update<Dinosaur>({
     pk: 'SPECIES#trex',
     sk: 'PROFILE#001'
   })
-  .set('diet', 'Carnivore')
-  .add('sightings', 1)
-  .condition(op => op.eq('status', 'ACTIVE'))
+  .set('diet', 'Carnivore')      // Update dietary classification
+  .add('sightings', 1)           // Increment sighting counter
+  .condition(op => op.eq('status', 'ACTIVE'))  // Only if dinosaur is active
   .execute();
 ```
 
-## 🌟 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
+## 🌟 Why dyno-table Stands Out From The Pack
+
+<table>
+<tr>
+  <td width="50%">
+    <h3>🦕 Dinosaur-sized data made manageable</h3>
+    <p>Clean abstraction layer that simplifies complex DynamoDB patterns and makes single-table design approachable</p>
+  </td>
+  <td width="50%">
+    <h3>🛡️ Extinction-proof type safety</h3>
+    <p>Full TypeScript support with strict type checking that catches errors at compile time, not runtime</p>
+  </td>
+</tr>
+<tr>
+  <td>
+    <h3>⚡ Velociraptor-fast API</h3>
+    <p>Intuitive chainable builder pattern for complex operations that feels natural and reduces boilerplate</p>
+  </td>
+</tr>
+<tr>
+  <td width="50%">
+    <h3>📈 Jurassic-scale performance</h3>
+    <p>Automatic batch chunking and pagination handling that scales with your data without extra code</p>
+  </td>
+  <td width="50%">
+    <h3>🧩 Flexible schema validation</h3>
+    <p>Works with your favorite validation libraries including Zod, ArkType, and Valibot</p>
+  </td>
+</tr>
+</table>
 
 ## 📑 Table of Contents
 
-- [🦖 dyno-table  ](#-dyno-table--)
-  - [🌟 Why dyno-table?](#-why-dyno-table)
-  - [📑 Table of Contents](#-table-of-contents)
-  - [📦 Installation](#-installation)
-  - [🚀 Quick Start](#-quick-start)
-    - [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)
-    - [Pagination Made Simple](#pagination-made-simple)
-  - [🛡️ Type-Safe Query Building](#️-type-safe-query-building)
-    - [Comparison Operators](#comparison-operators)
-    - [Logical Operators](#logical-operators)
-    - [Query Operations](#query-operations)
-    - [Put Operations](#put-operations)
-    - [Update Operations](#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)
-  - [🏗️ 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)
-      - [Comparison Operators](#comparison-operators-1)
-      - [Attribute Operators](#attribute-operators)
-      - [Logical Operators](#logical-operators-1)
-    - [Key Condition Operators](#key-condition-operators)
-  - [🔮 Future Roadmap](#-future-roadmap)
-  - [🤝 Contributing](#-contributing)
-  - [🦔 Running Examples](#-running-examples)
+- [📦 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. Defining GSI Access Patterns](#4-defining-gsi-access-patterns)
+    - [5. Lifecycle Hooks](#5-lifecycle-hooks)
+  - [Complete Entity Example](#complete-entity-example)
+- [🧩 Advanced Features](#-advanced-features)
+  - [Transactional Operations](#transactional-operations)
+  - [Batch Processing](#batch-processing)
+  - [Pagination Made Simple](#pagination-made-simple)
+- [🛡️ Type-Safe Query Building](#️-type-safe-query-building)
+  - [Comparison Operators](#comparison-operators)
+  - [Logical Operators](#logical-operators)
+  - [Query Operations](#query-operations)
+  - [Put Operations](#put-operations)
+  - [Update Operations](#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)
+  - [Condition Operators](#condition-operators-1)
+    - [Comparison Operators](#comparison-operators-1)
+    - [Attribute Operators](#attribute-operators)
+    - [Logical Operators](#logical-operators-1)
+  - [Key Condition Operators](#key-condition-operators)
+- [🔮 Future Roadmap](#-future-roadmap)
+- [🤝 Contributing](#-contributing)
+- [🦔 Running Examples](#-running-examples)
 
 ## 📦 Installation
 
+<div align="center">
+
+### Get Started in Seconds
+
+</div>
+
 ```bash
+# Install the core library
 npm install dyno-table
+
+# Install required AWS SDK v3 peer dependencies
+npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
 ```
 
-*Note: Requires AWS SDK v3 as peer dependency*
+<details>
+<summary><b>📋 Other Package Managers</b></summary>
 
 ```bash
-npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
+# Using Yarn
+yarn add dyno-table @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
+
+# Using PNPM
+pnpm add dyno-table @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
 ```
+</details>
 
 ## 🚀 Quick Start
 
-### 1. Configure Your Table
+<div align="center">
+
+### From Zero to DynamoDB Hero in Minutes
+
+</div>
+
+### 1. Configure Your Jurassic Table
 
 ```ts
 import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
 import { DynamoDBDocument } from "@aws-sdk/lib-dynamodb";
-import { Table } from "dyno-table";
+import { Table } from "dyno-table/table";
 
 // Configure AWS SDK clients
 const client = new DynamoDBClient({ region: "us-west-2" });
 const docClient = DynamoDBDocument.from(client);
 
-// Initialize table with single-table design schema
+// Initialise table
 const dinoTable = new Table({
   client: docClient,
-  tableName: "DinosaurPark",
+  tableName: "JurassicPark",
   indexes: {
     partitionKey: "pk",
     sortKey: "sk",
     gsis: {
-      speciesId: {
+      // Global Secondary Index setup in an abstract to allow unique access patterns per Entity Type for single table design
+      gsi1: {
         partitionKey: "gsi1pk",
         sortKey: "gsi1sk",
       },
@@ -110,10 +174,16 @@ const dinoTable = new Table({
 });
 ```
 
-### 2. Perform Type-Safe Operations
+### 2. Perform Type-Safe Operations directly on the table instance
+
+<table>
+<tr>
+<td>
+
+#### 🦖 Creating a new dinosaur specimen
 
-**🦖 Creating a new dinosaur**
 ```ts
+// Add a new T-Rex with complete type safety
 const rex = await dinoTable
   .create<Dinosaur>({
     pk: "SPECIES#trex",
@@ -127,8 +197,13 @@ const rex = await dinoTable
   .execute();
 ```
 
-**🔍 Query with conditions**
+</td>
+<td>
+
+#### 🔍 Query with powerful conditions
+
 ```ts
+// Find large carnivorous dinosaurs
 const largeDinos = await dinoTable
   .query<Dinosaur>({ 
     pk: "SPECIES#trex",
@@ -142,109 +217,599 @@ const largeDinos = await dinoTable
   .execute();
 ```
 
-**🔄 Complex update operation**
+</td>
+</tr>
+<tr>
+<td>
+
+#### 🔄 Update with type-safe operations
+
 ```ts
+// Update a dinosaur's classification
 await dinoTable
   .update<Dinosaur>({ 
-    pk: "SPECIES#trex", 
-    sk: "PROFILE#trex" 
+    pk: "SPECIES#trex",
+    sk: "PROFILE#trex"
   })
   .set("diet", "omnivore")
   .add("discoveryYear", 1)
   .remove("outdatedField")
-  .condition((op) => op.attributeExists("discoverySite"))
+  .condition((op) => 
+    op.attributeExists("discoverySite")
+  )
+  .execute();
+```
+
+</td>
+<td>
+
+#### 🔒 Transactional operations
+
+```ts
+// Perform multiple operations atomically
+await dinoTable.transaction(async (tx) => {
+  // Move dinosaur to new enclosure
+  await dinoTable
+    .delete({ pk: "ENCLOSURE#A", sk: "DINO#1" })
+    .withTransaction(tx);
+
+  await dinoTable
+    .create({ pk: "ENCLOSURE#B", sk: "DINO#1", 
+      status: "ACTIVE" })
+    .withTransaction(tx);
+});
+```
+
+</td>
+</tr>
+</table>
+
+<div align="center">
+<h3>💡 See the difference with dyno-table</h3>
+</div>
+
+<table>
+<tr>
+<th>With dyno-table</th>
+<th>Without dyno-table</th>
+</tr>
+<tr>
+<td>
+
+```ts
+// Type-safe, clean, and intuitive
+await dinoTable
+  .query<Dinosaur>({ 
+    pk: "SPECIES#trex"
+  })
+  .filter(op => 
+    op.contains("features", "feathers")
+  )
   .execute();
 ```
 
+</td>
+<td>
+
+```ts
+// Verbose, error-prone, no type safety
+await docClient.send(new QueryCommand({
+  TableName: "JurassicPark",
+  KeyConditionExpression: "#pk = :pk",
+  FilterExpression: "contains(#features, :feathers)",
+  ExpressionAttributeNames: {
+    "#pk": "pk",
+    "#features": "features"
+  },
+  ExpressionAttributeValues: {
+    ":pk": "SPECIES#trex",
+    ":feathers": "feathers"
+  }
+}));
+```
+
+</td>
+</tr>
+</table>
+
+## 🏗️ Entity Pattern with Standard Schema validators
+
+<div align="center">
+
+### The Most Type-Safe Way to Model Your DynamoDB Data
+
+</div>
+
+<table>
+<tr>
+<td width="70%">
+<p>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.</p>
+
+<p>✨ This library supports all <a href="https://github.com/standard-schema/standard-schema#what-schema-libraries-implement-the-spec">Standard Schema</a> validation libraries, including <strong>zod</strong>, <strong>arktype</strong>, and <strong>valibot</strong>, allowing you to choose your preferred validation tool!</p>
+
+<p>You can find a full example implementation here of <a href="https://github.com/Kysumi/dyno-table/blob/main/examples/entity-example/src/dinosaur-entity.ts">Entities</a></p>
+</td>
+<td width="30%">
+
+#### Entity Pattern Benefits
+
+- 🛡️ **Type-safe operations**
+- 🧪 **Schema validation**
+- 🔑 **Automatic key generation**
+- 📦 **Repository pattern**
+- 🔍 **Custom query builders**
+- 🔄 **Lifecycle hooks**
+
+</td>
+</tr>
+</table>
+
+### 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 }))
+          // could also be .withoutSortKey() if your table doesn't use sort keys
+          .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
+          .query({
+            pk: dinosaurPK({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. Defining GSI access patterns
+
+Define GSI (LSI support coming later)
+
+```ts
+import { createIndex } from "dyno-table/entity";
+
+// Define GSIs templates for querying by species
+const gsi1PK = partitionKey`SPECIES#${"species"}`
+const gsi1SK = sortKey`DINOSAUR#${"id"}`
+
+// Implement typesafe generator for the GSI - This is used in create calls to ensure the GSI is generated
+const speciesIndex = createIndex()
+  .input(dinosaurSchema)
+  .partitionKey(({ species }) => gsi1PK({ species }))
+  .sortKey(({ id }) => gsi1SK({ 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
+          .query({
+            // Use the GSI template generator to avoid typos
+            pk: gsi1PK({species: input.species}),
+          })
+          // Use the template name as defined in the table instance
+          .useIndex("gsi1");
+      }),
+  },
+});
+```
+
+### Complete Entity Example
+
+Here's a complete example of using Zod schemas directly:
+
+```ts
+import { z } from "zod";
+import { defineEntity, createQueries, createIndex } from "dyno-table/entity";
+import { Table } from "dyno-table/table";
+import { sortKey } from "dyno-table/utils/sort-key-template";
+import { partitionKey } from "dyno-table/utils/partition-key-template";
+
+// 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 = partitionKey`DINOSAUR#${"id"}`;
+const dinosaurSK = sortKey`STATUS#${"status"}`;
+
+const gsi1PK = partitionKey`SPECIES#${"species"}`
+const gsi1SK = sortKey`DINOSAUR#${"id"}`
+
+const gsi2PK = partitionKey`ENCLOSURE#${"enclosureId"}`
+const gsi2SK = sortKey`DINOSAUR#${"id"}`
+
+// 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 }) => gsi1PK({ species }))
+  .sortKey(({ id }) => gsiSK({ id }));
+
+// Create a GSI for querying by enclosure
+const enclosureIndex = createIndex()
+  .input(dinosaurSchema)
+  .partitionKey(({ enclosureId }) => gsi2PK({ enclosureId }))
+  .sortKey(({ id }) => gsi2SK({ id }));
+
+// Create query builders
+const createQuery = createQueries<Dinosaur>();
+
+// Define the entity
+const DinosaurEntity = defineEntity({
+  name: "Dinosaur",
+  schema: dinosaurSchema,
+  primaryKey,
+  indexes: {
+    // These keys need to be named after the name of the GSI that is defined in your table instance 
+    gsi1: speciesIndex,
+    gsi2: enclosureIndex,
+  },
+  queries: {
+    bySpecies: createQuery
+      .input(
+        z.object({
+          species: z.string(),
+        })
+      )
+      .query(({ input, entity }) => {
+        return entity
+          .query({
+            pk: gsi1PK({ species: input.species }),
+          })
+          .useIndex("gsi1");
+      }),
+
+    byEnclosure: createQuery
+      .input(
+        z.object({
+          enclosureId: z.string(),
+        })
+      )
+      .query(({ input, entity }) => {
+        return entity
+          .query({
+            pk: gsi2PK({ enclosureId: input.enclosureId }),
+          })
+          .useIndex("gsi2");
+      }),
+
+    dangerousInEnclosure: createQuery
+      .input(
+        z.object({
+          enclosureId: z.string(),
+          minDangerLevel: z.number().int().min(1).max(10),
+        })
+      )
+      .query(({ input, entity }) => {
+        return entity
+          .query({
+            pk: gsi2PK({ enclosureId: input.enclosureId }),
+          })
+          .useIndex("gsi2")
+          .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 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
 
 **Safe dinosaur transfer between enclosures**
 ```ts
-// Start a transaction session for transferring a dinosaur
+// 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
 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
 
-  // Check if destination enclosure is ready and compatible
+  // 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
   await dinoTable
     .conditionCheck({ 
-      pk: "ENCLOSURE#B", 
-      sk: "STATUS" 
+      pk: "ENCLOSURE#B",          // Target enclosure B
+      sk: "STATUS"                // Check the enclosure status record
     })
     .condition(op => op.and(
-      op.eq("status", "READY"),
-      op.eq("diet", "Carnivore")  // Ensure enclosure matches dinosaur diet
+      op.eq("status", "READY"),   // Enclosure must be in READY state
+      op.eq("diet", "Carnivore")  // Must support carnivorous dinosaurs
     ))
     .withTransaction(tx);
 
-  // Remove dinosaur from current enclosure
+  // STEP 2: Remove dinosaur from current enclosure
+  // Only proceed if the dinosaur is healthy enough for transfer
   await dinoTable
     .delete<Dinosaur>({ 
-      pk: "ENCLOSURE#A", 
-      sk: "DINO#001" 
+      pk: "ENCLOSURE#A",          // Source enclosure A
+      sk: "DINO#001"              // T-Rex with ID 001
     })
     .condition(op => op.and(
-      op.eq("status", "HEALTHY"),
-      op.gte("health", 80)  // Only transfer healthy dinosaurs
+      op.eq("status", "HEALTHY"), // Dinosaur must be in HEALTHY state
+      op.gte("health", 80)        // Health must be at least 80%
     ))
     .withTransaction(tx);
 
-  // Add dinosaur to new enclosure
+  // STEP 3: Add dinosaur to new enclosure
+  // Create a fresh record in the destination 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()
+      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
     })
     .withTransaction(tx);
 
-  // Update enclosure occupancy tracking
+  // STEP 4: Update enclosure occupancy tracking
+  // Keep accurate count of dinosaurs in each enclosure
   await dinoTable
     .update<Dinosaur>({ 
-      pk: "ENCLOSURE#B", 
-      sk: "OCCUPANCY" 
+      pk: "ENCLOSURE#B",          // Target enclosure B
+      sk: "OCCUPANCY"             // Occupancy tracking record
     })
-    .add("currentOccupants", 1)
-    .set("lastUpdated", new Date().toISOString())
+    .add("currentOccupants", 1)   // Increment occupant count
+    .set("lastUpdated", new Date().toISOString()) // Update timestamp
     .withTransaction(tx);
 });
 
-// Transaction with feeding and health monitoring
+// Transaction for dinosaur feeding and health monitoring
+// Ensures feeding status and schedule are updated atomically
 await dinoTable.transaction(
   async (tx) => {
-    // Update dinosaur health and feeding status
+    // STEP 1: Update Stegosaurus health and feeding status
+    // Record that the dinosaur has been fed and update its health metrics
     await dinoTable
       .update<Dinosaur>({
-        pk: "ENCLOSURE#D",
-        sk: "DINO#003"
+        pk: "ENCLOSURE#D",           // Herbivore enclosure D
+        sk: "DINO#003"               // Stegosaurus with ID 003
       })
       .set({
-        status: "HEALTHY",
-        lastFed: new Date().toISOString(),
-        health: 100
+        status: "HEALTHY",           // Update health status
+        lastFed: new Date().toISOString(), // Record feeding time
+        health: 100                  // Reset health to 100%
       })
-      .deleteElementsFromSet("tags", ["needs_feeding"])
+      .deleteElementsFromSet("tags", ["needs_feeding"]) // Remove feeding alert tag
       .withTransaction(tx);
 
-    // Update enclosure feeding schedule
+    // STEP 2: Update enclosure feeding schedule
+    // Schedule next feeding time for tomorrow
     await dinoTable
       .update<Dinosaur>({
-        pk: "ENCLOSURE#D",
-        sk: "SCHEDULE"
+        pk: "ENCLOSURE#D",           // Same herbivore enclosure
+        sk: "SCHEDULE"               // Feeding schedule record
       })
-      .set("nextFeedingTime", new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString())
+      .set("nextFeedingTime", new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString()) // 24 hours from now
       .withTransaction(tx);
   },
   {
-    clientRequestToken: "feeding-session-001",
-    returnConsumedCapacity: "TOTAL"
+    // Transaction options for tracking and idempotency
+    clientRequestToken: "feeding-session-001", // Prevents duplicate feeding operations
+    returnConsumedCapacity: "TOTAL"            // Track capacity usage for park operations
   }
 );
 ```
@@ -253,7 +818,6 @@ await dinoTable.transaction(
 - 🔄 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
 
@@ -261,35 +825,42 @@ await dinoTable.transaction(
 
 **Efficient dinosaur park management with bulk operations**
 ```ts
-// Batch health check for multiple dinosaurs
+// 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
-  { pk: "ENCLOSURE#B", sk: "DINO#002" }, // Velociraptor
-  { pk: "ENCLOSURE#C", sk: "DINO#003" }  // Stegosaurus
+  { 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
   }
 });
 
-// Batch update feeding schedule for herbivore group
+// 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",
+    name: "Triceratops Alpha",      // Three-horned herbivore
     species: "Triceratops",
     diet: "Herbivore",
     status: "HEALTHY",
-    health: 95,
-    lastFed: new Date().toISOString()
+    health: 95,                     // Excellent health after quarantine
+    lastFed: new Date().toISOString() // Just fed before joining main enclosure
   },
   {
     pk: "ENCLOSURE#D", sk: "DINO#005",
-    name: "Brachy",
+    name: "Brachy",                 // Long-necked herbivore
     species: "Brachiosaurus",
     diet: "Herbivore",
     status: "HEALTHY",
@@ -298,91 +869,117 @@ const newHerbivores = [
   }
 ];
 
-// Add new herbivores to enclosure
+// 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",
-    item: dino
+    type: "put",                    // Create or replace operation
+    item: dino                      // Full dinosaur record
   }))
 );
 
-// Mixed operations: relocate dinosaurs and update enclosure status
+// SCENARIO 3: Releasing a dinosaur from quarantine to general population
+// Multiple related operations performed as a batch
 await dinoTable.batchWrite([
-  // Remove dinosaur from quarantine
-  { type: "delete", key: { pk: "ENCLOSURE#QUARANTINE", sk: "DINO#006" } },
-  // Add recovered dinosaur to main enclosure
+  // 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",
+      name: "Raptor Beta",          // Juvenile Velociraptor
       species: "Velociraptor",
       diet: "Carnivore",
-      status: "HEALTHY",
+      status: "HEALTHY",            // Now healthy after treatment
       health: 100,
       lastFed: new Date().toISOString()
     }
   },
-  // Clear quarantine status
-  { type: "delete", key: { pk: "ENCLOSURE#QUARANTINE", sk: "STATUS#DINO#006" } }
+
+  // Step 3: Clear quarantine status record
+  { 
+    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)
+// 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
+await dinoTable.batchWrite(dailyHealthUpdates); // Automatically chunked into multiple requests
 ```
 
 ### Pagination Made Simple
 
-**Efficient dinosaur record browsing**
+**Efficient dinosaur record browsing for park management**
 ```ts
-// Create a paginator for viewing herbivores by health status
+// 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
 const healthyHerbivores = dinoTable
   .query<Dinosaur>({
-    pk: "DIET#herbivore",
-    sk: op => op.beginsWith("STATUS#HEALTHY")
+    pk: "DIET#herbivore",                    // Target all herbivorous dinosaurs
+    sk: op => op.beginsWith("STATUS#HEALTHY") // Only those with HEALTHY status
   })
   .filter((op) => op.and(
-    op.gte("health", 90),
-    op.attributeExists("lastFed")
+    op.gte("health", 90),                    // Only those with excellent health (90%+)
+    op.attributeExists("lastFed")            // Must have feeding records
   ))
-  .paginate(5); // View 5 dinosaurs at a time
+  .paginate(5);                              // Process in small batches of 5 dinosaurs
 
-// Monitor all enclosures page by page
+// 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...");
 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
   });
 }
 
-// Get all carnivores for daily feeding schedule
+// SCENARIO 2: Preparing carnivore feeding schedule
+// Get all carnivores at once for daily feeding planning
+// This approach loads all matching items into memory
 const carnivoreSchedule = await dinoTable
   .query<Dinosaur>({
-    pk: "DIET#carnivore",
-    sk: op => op.beginsWith("ENCLOSURE#")
+    pk: "DIET#carnivore",                    // Target all carnivorous dinosaurs
+    sk: op => op.beginsWith("ENCLOSURE#")    // Organized by enclosure
   })
-  .filter(op => op.attributeExists("lastFed"))
-  .paginate(10)
-  .getAllPages();
+  .filter(op => op.attributeExists("lastFed")) // Only those with feeding records
+  .paginate(10)                              // Process in pages of 10
+  .getAllPages();                            // But collect all results at once
 
 console.log(`Scheduling feeding for ${carnivoreSchedule.length} carnivores`);
+// Now we can sort and organize feeding times based on species, size, etc.
 
-// Limited view for visitor information kiosk
+// SCENARIO 3: Visitor information kiosk with limited display
+// Create a paginated view for the public-facing dinosaur information kiosk
 const visitorKiosk = dinoTable
   .query<Dinosaur>({ 
-    pk: "VISITOR_VIEW",
-    sk: op => op.beginsWith("SPECIES#")
+    pk: "VISITOR_VIEW",                      // Special partition for visitor-facing data
+    sk: op => op.beginsWith("SPECIES#")      // Organized by species
   })
-  .filter(op => op.eq("status", "ON_DISPLAY"))
-  .limit(12) // Show max 12 dinosaurs per view
-  .paginate(4); // Display 4 at a time
+  .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
 
-// Get first page for kiosk display
+// Get first page for initial kiosk display
 const firstPage = await visitorKiosk.getNextPage();
-console.log(`Now showing: ${firstPage.items.map(d => d.name).join(", ")}`);
+console.log(`🦖 Now showing: ${firstPage.items.map(d => d.name).join(", ")}`);
+// Visitors can press "Next" to see more dinosaurs in the collection
 ```
 
 ## 🛡️ Type-Safe Query Building
@@ -670,24 +1267,6 @@ 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