betterddb 0.8.2 → 1.0.0

package/API_REFERENCE.md

@@ -17,10 +17,10 @@ This document provides a comprehensive reference for the BetterDDB library, expl
   - [Filtering](#filtering)
 - [Scan Operations](#scan-operations)
 - [Batch Operations](#batch-operations)
-- [Transaction Operations](#transaction-operations)
+- [Transaction Support](#transaction-support)
 - [Advanced Features](#advanced-features)
   - [Automatic Timestamps](#automatic-timestamps)
-  - [Versioning](#versioning)
+  - [Counter Support](#counter-support)
 
 ## Initialization
 
@@ -42,16 +42,23 @@ export interface BetterDDBOptions<T> {
   keys: KeysConfig<T>;
   client: DynamoDBDocumentClient;
   counter?: boolean;
+  /**
+   * If true, automatically inject timestamp fields:
+   * - On create, sets both `createdAt` and `updatedAt`
+   * - On update, sets `updatedAt`
+   *
+   * (T should include these fields if enabled.)
+   */
   timestamps?: boolean;
 }
 ```
 
-- **schema**: Zod schema for validation
+- **schema**: Zod schema for validation and TypeScript type inference
 - **tableName**: Your DynamoDB table name
 - **entityType**: Optional type discriminator for multi-entity tables
 - **keys**: Configuration for primary key, sort key, and GSIs
 - **client**: AWS SDK v3 DynamoDB document client
-- **counter**: Whether to use a counter field for optimistic locking
+- **counter**: Feature flag for counter support (future feature)
 - **timestamps**: Whether to automatically manage `createdAt` and `updatedAt` timestamps
 
 #### Example
@@ -61,19 +68,22 @@ import { BetterDDB } from "betterddb";
 import { z } from "zod";
 import { DynamoDBDocumentClient, DynamoDB } from "@aws-sdk/lib-dynamodb";
 
-// Define schema
-const UserSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-  email: z.string().email(),
-  createdAt: z.string().optional(),
-  updatedAt: z.string().optional(),
-});
+// Define schema with optional timestamp fields
+const UserSchema = z
+  .object({
+    id: z.string(),
+    name: z.string(),
+    email: z.string().email(),
+    createdAt: z.string().optional(),
+    updatedAt: z.string().optional(),
+  })
+  .passthrough(); // Allow computed fields (pk, sk, gsi keys)
 
-// Init client
+// Initialize DynamoDB client
 const client = DynamoDBDocumentClient.from(
   new DynamoDB({
     region: "us-east-1",
+    // For local development, add: endpoint: "http://localhost:4566"
   }),
 );
 
@@ -81,6 +91,7 @@ const client = DynamoDBDocumentClient.from(
 const userDdb = new BetterDDB({
   schema: UserSchema,
   tableName: "Users",
+  entityType: "USER",
   keys: {
     primary: {
       name: "pk",
@@ -88,14 +99,18 @@ const userDdb = new BetterDDB({
     },
     sort: {
       name: "sk",
-      definition: { build: (raw) => `PROFILE` },
+      definition: { build: (raw) => `EMAIL#${raw.email}` },
     },
     gsis: {
       EmailIndex: {
         name: "EmailIndex",
         primary: {
           name: "gsi1pk",
-          definition: "email",
+          definition: { build: (raw) => `USER#${raw.email}` },
+        },
+        sort: {
+          name: "gsi1sk",
+          definition: { build: (raw) => `USER#${raw.email}` },
         },
       },
     },
@@ -107,34 +122,49 @@ const userDdb = new BetterDDB({
 
 ## Schema Definition
 
-BetterDDB uses [Zod](https://github.com/colinhacks/zod) for schema validation and type inference. Your schema defines both runtime validation rules and TypeScript types.
+BetterDDB uses [Zod](https://github.com/colinhacks/zod) for schema validation and TypeScript type inference. Your schema defines both runtime validation rules and TypeScript types.
 
-### Basic Schema
+### Basic Schema with Type Inference
 
 ```typescript
-const Schema = z.object({
+import { z } from "zod";
+
+const UserSchema = z.object({
   id: z.string(),
   name: z.string(),
   email: z.string().email(),
   age: z.number().optional(),
 });
 
-type Entity = z.infer<typeof Schema>; // TypeScript type inference
+type User = z.infer<typeof UserSchema>; // TypeScript type inference
 ```
 
 ### Schema with Computed Fields
 
-To allow for computed fields (like keys), use `.passthrough()`:
+DynamoDB tables often have computed fields like partition keys, sort keys, and GSI keys. Use `.passthrough()` to allow these fields while still validating your core attributes:
 
 ```typescript
-const Schema = z
+const UserSchema = z
   .object({
     id: z.string(),
     name: z.string(),
+    email: z.string().email(),
+    // Optional fields for automatic timestamps
+    createdAt: z.string().optional(),
+    updatedAt: z.string().optional(),
   })
-  .passthrough();
+  .passthrough(); // Allow computed fields like pk, sk, gsi1pk, etc.
+
+type User = z.infer<typeof UserSchema>;
 ```
 
+### Schema Best Practices
+
+- Use `.passthrough()` to allow DynamoDB keys and indexes
+- Include optional `createdAt` and `updatedAt` fields if using `timestamps: true`
+- Define strict validation rules for your core business data
+- Use Zod's rich validation API (`.email()`, `.min()`, `.max()`, etc.)
+
 ## CRUD Operations
 
 ### Create
@@ -147,13 +177,14 @@ create(item: T): CreateBuilder<T>
 
 #### CreateBuilder Methods
 
-- **execute()**: Performs the create operation and returns the created item
-- **withCondition(condition: string, expressionAttrs?: Record<string, any>)**: Adds a condition expression
+- **execute()**: Performs the create operation, validates the item, computes keys and indexes, and returns the created item
+- **transactWrite(ops: TransactWriteItem | TransactWriteItem[])**: Adds additional transaction items to include when executing this create as part of a transaction
+- **toTransactPut()**: Converts the create operation to a `TransactWriteItem` for use in DynamoDB transactions
 
 #### Example
 
 ```typescript
-// Simple create
+// Simple create with automatic validation
 const user = await userDdb
   .create({
     id: "123",
@@ -162,20 +193,26 @@ const user = await userDdb
   })
   .execute();
 
-// Create with condition
-const user = await userDdb
+// Create as part of a transaction
+const createItem = userDdb
   .create({
-    id: "123",
-    name: "Alice",
-    email: "alice@example.com",
+    id: "456",
+    name: "Bob",
+    email: "bob@example.com",
   })
-  .withCondition("attribute_not_exists(#pk)", { "#pk": "pk" })
-  .execute();
+  .toTransactPut();
+
+// Use with transactWrite (AWS SDK TransactWriteCommand)
+await client.send(
+  new TransactWriteCommand({
+    TransactItems: [createItem /* other transaction items */],
+  }),
+);
 ```
 
 ### Read
 
-Retrieves items from the DynamoDB table.
+Retrieves an item from the DynamoDB table by its primary key.
 
 ```typescript
 get(key: Partial<T>): GetBuilder<T>
@@ -183,71 +220,106 @@ get(key: Partial<T>): GetBuilder<T>
 
 #### GetBuilder Methods
 
-- **execute()**: Performs the get operation and returns the item
-- **withProjection(attributes: string[])**: Specifies which attributes to return
-- **withConsistentRead(consistent: boolean)**: Uses consistent read
+- **execute()**: Performs the get operation and returns the item or `null` if not found
+- **withProjection(attributes: (keyof T)[])**: Specifies which attributes to return using type-safe property names
+- **transactGet(ops: TransactGetItem | TransactGetItem[])**: Adds additional transaction items for use in DynamoDB transactions
+- **toTransactGet()**: Converts the get operation to a `TransactGetItem` for use in DynamoDB transactions
 
 #### Example
 
 ```typescript
-// Simple get
+// Simple get - returns null if item doesn't exist
 const user = await userDdb.get({ id: "123" }).execute();
+if (user) {
+  console.log(user.name);
+}
 
-// Get with projection
-const userNameOnly = await userDdb
+// Get with projection (type-safe)
+const partialUser = await userDdb
   .get({ id: "123" })
-  .withProjection(["name", "email"])
+  .withProjection(["name", "email"]) // Only these attributes are returned
   .execute();
+
+// Get as part of a transaction
+const getItem = userDdb.get({ id: "123" }).toTransactGet();
 ```
 
 ### Batch Get
 
-Retrieves multiple items in a single operation.
+Retrieves multiple items in a single operation. Duplicate keys are automatically deduplicated.
 
 ```typescript
 batchGet(keys: Partial<T>[]): BatchGetBuilder<T>
 ```
 
+#### BatchGetBuilder Methods
+
+- **execute()**: Performs the batch get operation and returns an array of items
+
 #### Example
 
 ```typescript
-const users = await userDdb.batchGet([{ id: "123" }, { id: "456" }]).execute();
+// Retrieve multiple users
+const users = await userDdb
+  .batchGet([
+    { id: "123" },
+    { id: "456" },
+    { id: "123" }, // Duplicate - will be deduplicated automatically
+  ])
+  .execute();
+
+// Returns an array of User objects
+users.forEach((user) => {
+  console.log(user.name);
+});
 ```
 
 ### Update
 
-Updates an existing item with automatic validation.
+Updates an existing item with automatic validation and type safety.
 
 ```typescript
-update(key: Partial<T>, expectedVersion?: number): UpdateBuilder<T>
+update(key: Partial<T>): UpdateBuilder<T>
 ```
 
 #### UpdateBuilder Methods
 
-- **set(attributes: Partial<T>)**: Sets attributes to specific values
-- **remove(attributes: string[])**: Removes attributes
-- **add(attributes: Record<string, number>)**: Adds numeric values to attributes
-- **delete(attributes: Record<string, any[]>)**: Removes elements from sets
-- **withCondition(condition: string, expressionAttrs?: Record<string, any>)**: Adds a condition expression
+- **set(attributes: Partial<T>)**: Sets attributes to specific values (empty strings and undefined values for optional fields are automatically removed)
+- **remove(attributes: (keyof T)[])**: Removes attributes from the item
+- **add(attributes: Partial<Record<keyof T, number | Set<NativeAttributeValue>>>)**: Adds numeric values to attributes or elements to sets
+- **delete(attributes: Partial<Record<keyof T, Set<NativeAttributeValue>>>)**: Removes elements from sets
+- **setCondition(expression: string, attributeValues: Record<string, NativeAttributeValue>, attributeNames: Record<string, string>)**: Adds a condition expression with attribute names and values
+- **transactWrite(ops: TransactWriteItem | TransactWriteItem[])**: Adds additional transaction items
+- **toTransactUpdate()**: Converts the update to a `TransactWriteItem` for use in DynamoDB transactions
 - **execute()**: Performs the update operation and returns the updated item
-- **toTransactUpdate()**: Converts the update to a transaction operation
 
 #### Example
 
 ```typescript
 // Simple update
 const user = await userDdb
-  .update({ id: "123" })
+  .update({ id: "123", email: "alice@example.com" })
   .set({ name: "Alice Smith" })
   .execute();
 
-// Complex update
+// Update with multiple operations
 const user = await userDdb
-  .update({ id: "123" }, 1) // Version check
-  .set({ name: "Alice Smith" })
+  .update({ id: "123", email: "alice@example.com" })
+  .set({ name: "Alice Smith", age: 30 })
   .remove(["oldField"])
-  .add({ age: 1 })
-  .withCondition("attribute_exists(#id)", { "#id": "id" })
+  .add({ points: 10 }) // Increment numeric attribute
+  .delete({ tags: new Set(["old"]) }) // Remove elements from a set
+  .execute();
+
+// Update with condition
+const user = await userDdb
+  .update({ id: "123", email: "alice@example.com" })
+  .set({ name: "Alice Smith" })
+  .setCondition(
+    "attribute_exists(#id) AND #status = :active",
+    { ":active": "active" },
+    { "#id": "id", "#status": "status" },
+  )
   .execute();
 ```
 
@@ -262,28 +334,33 @@ delete(key: Partial<T>): DeleteBuilder<T>
 #### DeleteBuilder Methods
 
 - **execute()**: Performs the delete operation
-- **withCondition(condition: string, expressionAttrs?: Record<string, any>)**: Adds a condition expression
-- **toTransactDelete()**: Converts the delete to a transaction operation
+- **withCondition(expression: string, attributeValues: Record<string, NativeAttributeValue>)**: Adds a condition expression with attribute values
+- **transactWrite(ops: TransactWriteItem | TransactWriteItem[])**: Adds additional transaction items
+- **toTransactDelete()**: Converts the delete to a `TransactWriteItem` for use in DynamoDB transactions
 
 #### Example
 
 ```typescript
 // Simple delete
-await userDdb.delete({ id: "123" }).execute();
+await userDdb.delete({ id: "123", email: "alice@example.com" }).execute();
 
 // Delete with condition
 await userDdb
-  .delete({ id: "123" })
+  .delete({ id: "123", email: "alice@example.com" })
   .withCondition("#status = :status", {
-    "#status": "status",
     ":status": "inactive",
   })
   .execute();
+
+// Delete as part of a transaction
+const deleteItem = userDdb
+  .delete({ id: "123", email: "alice@example.com" })
+  .toTransactDelete();
 ```
 
 ## Query Operations
 
-Performs a DynamoDB query operation with a fluent interface.
+Performs a DynamoDB query operation with a fluent, type-safe interface.
 
 ```typescript
 query(keyCondition: Partial<T>): QueryBuilder<T>
@@ -291,60 +368,84 @@ query(keyCondition: Partial<T>): QueryBuilder<T>
 
 ### QueryBuilder Methods
 
-- **execute()**: Performs the query operation and returns the results
-- **where(operator: string, value: any)**: Adds a condition on the sort key
-- **filter(attribute: keyof T, operator: string, value: any)**: Adds a filter condition
-- **usingIndex(indexName: string)**: Specifies a GSI to query
+- **execute()**: Performs the query operation and returns a `PaginatedResult<T>` with `items` and `lastEvaluatedKey`
+- **usingIndex(indexName: string)**: Specifies a Global Secondary Index (GSI) to query
+- **sortAscending()**: Changes the sort order to ascending (default)
+- **sortDescending()**: Changes the sort order to descending
+- **where(operator: Operator, values: Partial<T> | [Partial<T>, Partial<T>])**: Adds a condition on the sort key using the `Operator` enum
+- **filter(attribute: keyof T, operator: Operator, values: unknown)**: Adds a filter condition using the `Operator` enum
 - **limitResults(limit: number)**: Limits the number of results
-- **scanDescending()**: Changes the scan direction to descending
-- **startFrom(lastEvaluatedKey: Record<string, any>)**: Enables pagination
+- **startFrom(lastKey: Record<string, NativeAttributeValue>)**: Enables pagination using the `lastEvaluatedKey` from a previous result
 
 ### Basic Queries
 
 ```typescript
+import { Operator } from "betterddb";
+
 // Query by primary key
 const results = await userDdb.query({ id: "123" }).execute();
 
-// Query with sort key condition
+// Query with sort key condition using Operator enum
+const results = await userDdb
+  .query({ id: "123" })
+  .where(Operator.BEGINS_WITH, { email: "alice" })
+  .execute();
+
+// Query with multiple filters
 const results = await userDdb
   .query({ id: "123" })
-  .where("begins_with", { email: "a" })
+  .filter("name", Operator.BEGINS_WITH, "Alice")
+  .filter("age", Operator.GT, 21)
+  .limitResults(10)
   .execute();
 ```
 
 ### Using Indexes
 
 ```typescript
-// Query using GSI
+// Query using a Global Secondary Index (GSI)
+const results = await userDdb
+  .query({ email: "alice@example.com" })
+  .usingIndex("EmailIndex") // Must be defined in keys.gsis
+  .limitResults(5)
+  .execute();
+
+// Query using GSI with sort key condition
 const results = await userDdb
   .query({ email: "alice@example.com" })
   .usingIndex("EmailIndex")
+  .where(Operator.BEGINS_WITH, { email: "alice" })
   .execute();
 ```
 
 ### Filtering
 
+Supported operators: `EQ`, `NE`, `LT`, `LTE`, `GT`, `GTE`, `BEGINS_WITH`, `BETWEEN`, `CONTAINS`.
+
 ```typescript
-// Query with filter
+// Query with various filter operators
 const results = await userDdb
   .query({ id: "123" })
-  .filter("age", ">", 21)
-  .limitResults(10)
+  .filter("status", Operator.EQ, "active")
+  .filter("age", Operator.BETWEEN, [18, 65])
+  .filter("tags", Operator.CONTAINS, "premium")
   .execute();
 
-// Multiple filters
+// Multiple filters are ANDed together
 const results = await userDdb
   .query({ id: "123" })
-  .filter("age", ">", 21)
-  .filter("name", "begins_with", "A")
+  .filter("name", Operator.BEGINS_WITH, "A")
+  .filter("email", Operator.CONTAINS, "example.com")
   .execute();
 ```
 
 ### Pagination
 
 ```typescript
+// First page
 const firstPage = await userDdb.query({ id: "123" }).limitResults(10).execute();
 
+// Second page using lastEvaluatedKey
 if (firstPage.lastEvaluatedKey) {
   const secondPage = await userDdb
     .query({ id: "123" })
@@ -356,7 +457,7 @@ if (firstPage.lastEvaluatedKey) {
 
 ## Scan Operations
 
-Performs a DynamoDB scan operation.
+Performs a DynamoDB scan operation with filtering and pagination.
 
 ```typescript
 scan(): ScanBuilder<T>
@@ -364,60 +465,95 @@ scan(): ScanBuilder<T>
 
 ### ScanBuilder Methods
 
-- **execute()**: Performs the scan operation and returns the results
-- **filter(attribute: keyof T, operator: string, value: any)**: Adds a filter condition
+- **execute()**: Performs the scan operation and returns a `PaginatedResult<T>` with `items` and `lastEvaluatedKey`
+- **where(attribute: keyof T, operator: Operator, values: unknown)**: Adds a filter condition using the `Operator` enum
 - **limitResults(limit: number)**: Limits the number of results
-- **startFrom(lastEvaluatedKey: Record<string, any>)**: Enables pagination
-- **usingIndex(indexName: string)**: Specifies a GSI to scan
+- **startFrom(lastKey: Record<string, NativeAttributeValue>)**: Enables pagination using the `lastEvaluatedKey` from a previous result
 
 ### Example
 
 ```typescript
+import { Operator } from "betterddb";
+
 // Simple scan
 const results = await userDdb.scan().execute();
 
-// Scan with filter
+// Scan with filter using Operator enum
 const results = await userDdb
   .scan()
-  .filter("status", "==", "active")
+  .where("status", Operator.EQ, "active")
   .limitResults(100)
   .execute();
+
+// Scan with multiple filters
+const results = await userDdb
+  .scan()
+  .where("age", Operator.GTE, 18)
+  .where("name", Operator.BEGINS_WITH, "A")
+  .execute();
+
+// Paginated scan
+const firstPage = await userDdb.scan().limitResults(50).execute();
+if (firstPage.lastEvaluatedKey) {
+  const secondPage = await userDdb
+    .scan()
+    .limitResults(50)
+    .startFrom(firstPage.lastEvaluatedKey)
+    .execute();
+}
 ```
 
 ## Batch Operations
 
-Performs multiple write operations in a single request.
+### Batch Get
+
+Retrieves multiple items by their primary keys in a single operation. Duplicate keys are automatically deduplicated.
 
 ```typescript
-batchWrite(operations: {
-  puts?: T[];
-  deletes?: Partial<T>[]
-}): Promise<void>
+batchGet(keys: Partial<T>[]): BatchGetBuilder<T>
 ```
 
-### Example
+#### Example
 
 ```typescript
-await userDdb.batchWrite({
-  puts: [
-    { id: "123", name: "Alice", email: "alice@example.com" },
-    { id: "456", name: "Bob", email: "bob@example.com" },
-  ],
-  deletes: [{ id: "789" }],
+// Retrieve multiple users
+const users = await userDdb
+  .batchGet([
+    { id: "123", email: "alice@example.com" },
+    { id: "456", email: "bob@example.com" },
+  ])
+  .execute();
+
+// Batch get returns an array of items
+users.forEach((user) => {
+  console.log(user.name);
 });
 ```
 
-## Transaction Operations
+> **Note**: BetterDDB currently only supports batch get operations. Batch write operations are not yet implemented.
 
-Performs multiple operations atomically.
+## Transaction Support
 
-```typescript
-transactWrite(transactItems: any[]): Promise<void>
-```
+BetterDDB provides builder methods to create transaction items that can be used with AWS SDK's `TransactWriteCommand` and `TransactGetCommand`.
 
-### Example
+### Transaction Item Builders
+
+Each builder class provides methods to convert operations to transaction items:
+
+- **CreateBuilder**: `toTransactPut()` – Creates a `Put` transaction item
+- **UpdateBuilder**: `toTransactUpdate()` – Creates an `Update` transaction item
+- **DeleteBuilder**: `toTransactDelete()` – Creates a `Delete` transaction item
+- **GetBuilder**: `toTransactGet()` – Creates a `Get` transaction item
+
+### Adding Additional Transaction Items
+
+Each builder also has a `transactWrite` method (or `transactGet` for GetBuilder) to include additional transaction items when executing the operation as part of a transaction.
+
+### Example: Transaction Write
 
 ```typescript
+import { TransactWriteCommand } from "@aws-sdk/lib-dynamodb";
+
 // Build transaction items
 const createItem = userDdb
   .create({
@@ -428,24 +564,71 @@ const createItem = userDdb
   .toTransactPut();
 
 const updateItem = userDdb
-  .update({ id: "456" })
+  .update({ id: "456", email: "bob@example.com" })
   .set({ name: "Bob Smith" })
   .toTransactUpdate();
 
-const deleteItem = userDdb.delete({ id: "789" }).toTransactDelete();
+const deleteItem = userDdb
+  .delete({ id: "789", email: "charlie@example.com" })
+  .toTransactDelete();
 
-// Execute transaction
-await userDdb.transactWrite([createItem, updateItem, deleteItem]);
+// Execute transaction using AWS SDK
+await client.send(
+  new TransactWriteCommand({
+    TransactItems: [createItem, updateItem, deleteItem],
+  }),
+);
+```
+
+### Example: Transaction Get
+
+```typescript
+import { TransactGetCommand } from "@aws-sdk/lib-dynamodb";
+
+const getItem1 = userDdb
+  .get({ id: "123", email: "alice@example.com" })
+  .toTransactGet();
+
+const getItem2 = userDdb
+  .get({ id: "456", email: "bob@example.com" })
+  .toTransactGet();
+
+await client.send(
+  new TransactGetCommand({
+    TransactItems: [getItem1, getItem2],
+  }),
+);
+```
+
+### Example: Builder with Additional Transaction Items
+
+```typescript
+// Create an item while also updating another item in the same transaction
+const createBuilder = userDdb
+  .create({
+    id: "123",
+    name: "Alice",
+    email: "alice@example.com",
+  })
+  .transactWrite([
+    userDdb
+      .update({ id: "456", email: "bob@example.com" })
+      .set({ referrer: "alice" })
+      .toTransactUpdate(),
+  ]);
+
+// This will execute both operations as a single transaction
+await createBuilder.execute();
 ```
 
 ## Advanced Features
 
 ### Automatic Timestamps
 
-When enabled, BetterDDB automatically manages:
+When enabled, BetterDDB automatically manages timestamp fields:
 
-- **createdAt**: Set on item creation
-- **updatedAt**: Set on item creation and updated on every update
+- **createdAt**: Set to current ISO timestamp on item creation
+- **updatedAt**: Set to current ISO timestamp on item creation and updated on every update
 
 Enable with:
 
@@ -456,31 +639,32 @@ const ddb = new BetterDDB({
 });
 ```
 
-### Versioning
-
-Enables optimistic locking with version numbers.
+Your schema should include these optional fields:
 
 ```typescript
-// Update with version checking
-const user = await userDdb
-  .update({ id: "123" }, 1) // Expected version
-  .set({ name: "Alice Smith" })
-  .execute();
+const UserSchema = z
+  .object({
+    id: z.string(),
+    name: z.string(),
+    createdAt: z.string().optional(),
+    updatedAt: z.string().optional(),
+  })
+  .passthrough();
 ```
 
-This will only update if the current version is 1, then increment it to 2.
-
-### Counter
+### Counter Support
 
-Enables automatic counter incrementing for items.
+The `counter` option is a feature flag for future counter functionality. When enabled, it may provide automatic counter incrementing for items.
 
 ```typescript
 const ddb = new BetterDDB({
   // ...other options
-  counter: true,
+  counter: true, // Feature flag for counter support
 });
 ```
 
+> **Note**: Counter functionality is not yet implemented. This option is reserved for future development.
+
 ## Key Management
 
 ### Key Definitions