betterddb 0.3.0 → 0.4.0

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,33 @@
+# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
+# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
+
+name: Node.js Package
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm test
+
+  publish-npm:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org/
+      - run: npm ci
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{secrets.npm_token}}

package/README.md

@@ -1,6 +1,8 @@
-# betterddb
+# betterddb [IN DEVELOPMENT - NOT READY FOR PRODUCTION - BREAKING CHANGES - PLEASE FOR THE LOVE OF GOD DO NOT USE]
 
-**betterddb** is a definition-based DynamoDB wrapper library written in TypeScript. It provides a generic, schema-driven Data Access Layer (DAL) using [Zod](https://github.com/colinhacks/zod) for runtime validation and the AWS SDK for DynamoDB operations. With built-in support for compound keys, computed indexes, automatic timestamp injection, transactional and batch operations, and pagination for queries, **betterddb** lets you work with DynamoDB using definitions instead of ad hoc query code.
+**betterddb** is a definition-based DynamoDB wrapper library written in TypeScript. It provides a generic, schema-driven Data Access Layer (DAL) using [Zod](https://github.com/colinhacks/zod) for runtime validation and the AWS SDK for DynamoDB operations. With built-in support for compound keys, computed indexes, automatic timestamp injection, transactional and batch operations, and a fluent builder API for all CRUD operations (create, get, update, delete) as well as queries and scans, **betterddb** lets you work with DynamoDB using definitions instead of ad hoc query code.
+
+---
 
 ## Installation
 
@@ -8,15 +10,18 @@
 npm install betterddb
 ```
 
+---
+
 ## Usage Example
-Below is an example of using betterddb for a User entity with a compound key.
+
+Below is an example of using **betterddb** for a User entity with a compound key, and using the new fluent builder APIs for create, get, update, and delete, as well as for query and scan operations.
 
 ```ts
 import { BetterDDB } from 'betterddb';
 import { z } from 'zod';
 import { DynamoDB } from 'aws-sdk';
 
-// Define the User schema. Use .passthrough() if you want to allow extra keys (e.g. computed keys).
+// Define the User schema. Use .passthrough() to allow computed keys.
 const UserSchema = z.object({
   tenantId: z.string(),
   userId: z.string(),
@@ -25,9 +30,9 @@ const UserSchema = z.object({
   createdAt: z.string(),
   updatedAt: z.string(),
   version: z.number().optional()
-});
+}).passthrough();
 
-// Configure the DynamoDB DocumentClient (for example, using LocalStack)
+// Configure the DynamoDB DocumentClient (example using LocalStack)
 const client = new DynamoDB.DocumentClient({
   region: 'us-east-1',
   endpoint: 'http://localhost:4566'
@@ -40,72 +45,173 @@ const userDdb = new BetterDDB({
   keys: {
     primary: {
       name: 'pk',
-      // Compute the partition key from tenantId
+      // Compute the partition key from tenantId.
       definition: { build: (raw) => `TENANT#${raw.tenantId}` }
     },
     sort: {
       name: 'sk',
-      // Compute the sort key from userId
+      // Compute the sort key from userId.
       definition: { build: (raw) => `USER#${raw.userId}` }
     },
     gsis: {
       // Example: a Global Secondary Index on email.
       EmailIndex: {
-        primary: {
-          name: 'email',
-          definition: 'email'
-        }
+        primary: { name: 'email', definition: 'email' }
       }
     }
   },
   client,
-  autoTimestamps: true
+  autoTimestamps: true,
+  entityName: 'USER'
 });
 
-// Use the BetterDDB instance to create and query items.
 (async () => {
-  // Create a new user.
-  const newUser = await userDdb.create({
+  // ### Create Operation ###
+  // Use the CreateBuilder to build and execute a create operation.
+  const newUser = await userDdb.createBuilder({
     tenantId: 'tenant1',
     userId: 'user123',
     email: 'user@example.com',
     name: 'Alice'
-  });
+  }).execute();
   console.log('Created User:', newUser);
 
-  // Query by primary key with an optional sort key condition.
-  const { items, lastKey } = await userDdb.queryByPrimaryKey(
-    { tenantId: 'tenant1' },
-    { operator: 'begins_with', values: 'USER#user' },
-    { limit: 10 }
-  );
-  console.log('Queried Items:', items);
-  if (lastKey) {
-    console.log('More items available. Use lastKey for pagination:', lastKey);
-  }
+  // ### Get Operation ###
+  // Use the GetBuilder to retrieve an item. Optionally, use a projection.
+  const user = await userDdb.getBuilder({ id: 'user123' })
+    .withProjection(['name', 'email'])
+    .execute();
+  console.log('Retrieved User:', user);
+
+  // ### Update Operation ###
+  // Use the UpdateBuilder to perform a fluent update.
+  const updatedUser = await userDdb.update({ tenantId: 'tenant1', userId: 'user123' }, 1)
+    .set({ name: 'Jane Doe' })
+    .remove(['obsoleteAttribute'])
+    .execute();
+  console.log('Updated User (immediate):', updatedUser);
+
+  // Or build a transaction update item and include it in a transaction:
+  const transactionUpdateItem = userDdb.update({ tenantId: 'tenant1', userId: 'user123' }, 1)
+    .set({ name: 'Jane Doe' })
+    .remove(['obsoleteAttribute'])
+    .toTransactUpdate();
+  // Assume transactWrite is available on BetterDDB for executing a transaction.
+  await userDdb.transactWrite([transactionUpdateItem]);
+  console.log('Updated User (transaction) executed.');
+
+  // ### Delete Operation ###
+  // Use the DeleteBuilder to delete an item with an optional condition.
+  await userDdb.deleteBuilder({ id: 'user123' })
+    .withCondition('#status = :expected', { ':expected': 'inactive' })
+    .execute();
+  console.log('User deleted');
+
+  // ### Query Operation ###
+  // Use the fluent QueryBuilder to query items.
+  const queryResults = await userDdb.query({ tenantId: 'tenant1' })
+    .where('name', 'begins_with', 'John')
+    .limitResults(10);
+  console.log('Query Results:', queryResults);
+
+  // ### Scan Operation ###
+  // Use the fluent ScanBuilder to scan the table with a filter.
+  const scanResults = await userDdb.scan()
+    .where('tenantId', 'eq', 'tenant1')
+    .limitResults(50);
+  console.log('Scan Results:', scanResults);
 })();
 ```
 
-## API
-betterddb exposes a generic class BetterDDB<T> with methods for:
+---
+
+## API Overview
+
+**betterddb** exposes a generic class `BetterDDB<T>` with the following methods:
+
+### Fluent CRUD Builders
+
+- **CreateBuilder**  
+  - `createBuilder(item: T): CreateBuilder<T>`  
+  - Builds a put request with automatic timestamp and key computation.
+  - Usage:  
+    ```ts
+    await betterDdb.createBuilder(item).execute();
+    ```
+
+- **GetBuilder**  
+  - `getBuilder(key: Partial<T>): GetBuilder<T>`  
+  - Builds a get request. Supports projections via `.withProjection()`.
+  - Usage:  
+    ```ts
+    const result = await betterDdb.getBuilder({ id: 'user123' })
+      .withProjection(['name', 'email'])
+      .execute();
+    ```
+
+- **DeleteBuilder**  
+  - `deleteBuilder(key: Partial<T>): DeleteBuilder<T>`  
+  - Builds a delete request. Supports condition expressions via `.withCondition()`.
+  - Usage:  
+    ```ts
+    await betterDdb.deleteBuilder({ id: 'user123' })
+      .withCondition('#status = :expected', { ':expected': 'inactive' })
+      .execute();
+    ```
+
+### Fluent Update Builder
+
+- `update(key: Partial<T>, expectedVersion?: number): UpdateBuilder<T>`  
+  - Provides chainable methods such as `.set()`, `.remove()`, `.add()`, and `.delete()`.
+  - Also supports transaction mode:
+    - `.toTransactUpdate()` returns a transaction item.
+    - `.transactWrite([...])` allows you to combine update items in a transaction.
+  - Usage:
+    ```ts
+    await betterDdb.update({ id: 'user123' }, 1)
+      .set({ name: 'Jane Doe' })
+      .remove(['obsoleteAttribute'])
+      .execute();
+    ```
+
+### Fluent Query & Scan Builders
+
+- **QueryBuilder**  
+  - `query(key: Partial<T>): QueryBuilder<T>`  
+  - Allows you to chain conditions (via `.where()`), sort direction, limits, and pagination.
+  - Usage:
+    ```ts
+    const results = await betterDdb.query({ tenantId: 'tenant1' })
+      .where('name', 'begins_with', 'John')
+      .limitResults(10);
+    ```
+
+- **ScanBuilder**  
+  - `scan(): ScanBuilder<T>`  
+  - Provides a fluent API to filter and paginate scan operations.
+  - Usage:
+    ```ts
+    const results = await betterDdb.scan()
+      .where('tenantId', 'eq', 'tenant1')
+      .limitResults(50);
+    ```
+
+### Batch and Transaction Operations
+
+- **Batch Operations:**
+  - `batchWrite(ops: { puts?: T[]; deletes?: Partial<T>[] }): Promise<void>`
+  - `batchGet(rawKeys: Partial<T>[]): Promise<T[]>`
+
+- **Transaction Helpers:**
+  - `buildTransactPut(item: T)`
+  - `buildTransactUpdate(rawKey: Partial<T>, update: Partial<T>, options?: { expectedVersion?: number })`
+  - `buildTransactDelete(rawKey: Partial<T>)`
+  - `transactWrite(...)` and `transactGetByKeys(...)`
 
-```ts
-create(item: T): Promise<T>
-get(rawKey: Partial<T>): Promise<T | null>
-update(rawKey: Partial<T>, update: Partial<T>, options?: { expectedVersion?: number }): Promise<T>
-delete(rawKey: Partial<T>): Promise<void>
-queryByGsi(gsiName: string, key: Partial<T>, sortKeyCondition?: { operator: "eq" | "begins_with" | "between"; values: any | [any, any] }): Promise<T[]>
-queryByPrimaryKey(rawKey: Partial<T>, sortKeyCondition?: { operator: "eq" | "begins_with" | "between"; values: any | [any, any] }, options?: { limit?: number; lastKey?: Record<string, any> }): Promise<{ items: T[]; lastKey?: Record<string, any> }>
-Batch operations:
-batchWrite(ops: { puts?: T[]; deletes?: Partial<T>[] }): Promise<void>
-batchGet(rawKeys: Partial<T>[]): Promise<T[]>
-Transaction helper methods:
-buildTransactPut(item: T)
-buildTransactUpdate(rawKey: Partial<T>, update: Partial<T>, options?: { expectedVersion?: number })
-buildTransactDelete(rawKey: Partial<T>)
-transactWrite(...) and transactGetByKeys(...)
 For complete details, please refer to the API documentation.
-```
 
-License
+---
+
+## License
+
 MIT

package/lib/builders/query-builder.js

@@ -90,7 +90,7 @@ class QueryBuilder {
             params.FilterExpression = this.filters.join(' AND ');
         }
         const result = await this.parent.getClient().query(params).promise();
-        return (result.Items || []).map(item => this.parent.getSchema().parse(item));
+        return this.parent.getSchema().array().parse(result.Items);
     }
     // Thenable implementation.
     then(onfulfilled, onrejected) {

package/lib/builders/scan-builder.js

@@ -60,7 +60,7 @@ class ScanBuilder {
             params.FilterExpression = this.filters.join(' AND ');
         }
         const result = await this.parent.getClient().scan(params).promise();
-        return (result.Items || []).map(item => this.parent.getSchema().parse(item));
+        return this.parent.getSchema().array().parse(result.Items);
     }
     // Thenable implementation.
     then(onfulfilled, onrejected) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "betterddb",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "A definition-based DynamoDB wrapper library that provides a schema-driven and fully typesafe DAL.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/src/betterddb.ts

@@ -1,5 +1,4 @@
-// src/dynamo-dal.ts
-import { z, ZodSchema } from 'zod';
+import { ZodSchema } from 'zod';
 import { DynamoDB } from 'aws-sdk';
 import { QueryBuilder } from './builders/query-builder';
 import { ScanBuilder } from './builders/scan-builder';

package/src/builders/query-builder.ts

@@ -106,7 +106,7 @@ export class QueryBuilder<T> {
     }
 
     const result = await this.parent.getClient().query(params).promise();
-    return (result.Items || []).map(item => this.parent.getSchema().parse(item));
+    return this.parent.getSchema().array().parse(result.Items);
   }
 
   // Thenable implementation.

package/src/builders/scan-builder.ts

@@ -69,7 +69,7 @@ export class ScanBuilder<T> {
     }
 
     const result = await this.parent.getClient().scan(params).promise();
-    return (result.Items || []).map(item => this.parent.getSchema().parse(item));
+    return this.parent.getSchema().array().parse(result.Items);
   }
 
   // Thenable implementation.

package/test/create.test.ts

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+import { BetterDDB } from '../src/betterddb';
+import { DynamoDB } from 'aws-sdk';
+import { createTestTable, deleteTestTable } from './utils/table-setup';
+
+const TEST_TABLE = "create-test-table";
+const ENDPOINT = 'http://localhost:4566';
+const REGION = 'us-east-1';
+const ENTITY_NAME = 'USER';
+const PRIMARY_KEY = 'id';
+const PRIMARY_KEY_TYPE = 'S';
+const SORT_KEY = 'email';
+const SORT_KEY_TYPE = 'S';
+const KEY_SCHEMA = [{ AttributeName: PRIMARY_KEY, KeyType: 'HASH' }, { AttributeName: SORT_KEY, KeyType: 'RANGE' }];
+const ATTRIBUTE_DEFINITIONS = [{ AttributeName: PRIMARY_KEY, AttributeType: PRIMARY_KEY_TYPE }, { AttributeName: SORT_KEY, AttributeType: SORT_KEY_TYPE }];
+const client = new DynamoDB.DocumentClient({
+  region: REGION,
+  endpoint: ENDPOINT,
+});
+
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+}).passthrough();
+
+const userDdb = new BetterDDB({
+  schema: UserSchema,
+  tableName: TEST_TABLE,
+  entityName: ENTITY_NAME,
+  keys: {
+    primary: { name: PRIMARY_KEY, definition: { build: (raw) => raw.id! } },
+    sort: { name: SORT_KEY, definition: { build: (raw) => raw.email! } },
+  },
+  client,
+  autoTimestamps: true,
+});
+
+beforeAll(async () => {
+  await createTestTable(TEST_TABLE, KEY_SCHEMA, ATTRIBUTE_DEFINITIONS);
+});
+
+afterAll(async () => {
+  await deleteTestTable(TEST_TABLE);
+});
+
+describe('BetterDDB - Create Operation', () => {
+  it('should insert an item using CreateBuilder', async () => {
+    const user = { id: 'user-123', name: 'John Doe', email: 'john@example.com' };
+    await userDdb.create(user as any).execute();
+    const createdUser = await userDdb.get({ id: 'user-123', email: 'john@example.com' }).execute();
+    expect(createdUser).not.toBeNull();
+    expect(createdUser?.id).toBe('user-123');
+    expect(createdUser).toHaveProperty('createdAt');
+    expect(createdUser).toHaveProperty('updatedAt');
+  });
+});

package/test/delete.test.ts

@@ -0,0 +1,58 @@
+// __tests__/delete.test.ts
+import { z } from 'zod';
+import { BetterDDB } from '../src/betterddb';
+import { DynamoDB } from 'aws-sdk';
+import { createTestTable, deleteTestTable } from './utils/table-setup';
+
+const TEST_TABLE = "delete-test-table";
+const ENDPOINT = 'http://localhost:4566';
+const REGION = 'us-east-1';
+const ENTITY_NAME = 'USER';
+const PRIMARY_KEY = 'id';
+const PRIMARY_KEY_TYPE = 'S';
+const SORT_KEY = 'email';
+const SORT_KEY_TYPE = 'S';
+const KEY_SCHEMA = [{ AttributeName: PRIMARY_KEY, KeyType: 'HASH' }, { AttributeName: SORT_KEY, KeyType: 'RANGE' }];
+const ATTRIBUTE_DEFINITIONS = [{ AttributeName: PRIMARY_KEY, AttributeType: PRIMARY_KEY_TYPE }, { AttributeName: SORT_KEY, AttributeType: SORT_KEY_TYPE }];
+const client = new DynamoDB.DocumentClient({
+  region: REGION,
+  endpoint: ENDPOINT,
+});
+
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+}).passthrough();
+
+const userDdb = new BetterDDB({
+  schema: UserSchema,
+  tableName: TEST_TABLE,
+  entityName: ENTITY_NAME,
+  keys: {
+    primary: { name: PRIMARY_KEY, definition: { build: (raw) => raw.id! } },
+    sort: { name: SORT_KEY, definition: { build: (raw) => raw.email! } },
+  },
+  client,
+  autoTimestamps: true,
+});
+
+beforeAll(async () => {
+  await createTestTable(TEST_TABLE, KEY_SCHEMA, ATTRIBUTE_DEFINITIONS);
+  await userDdb.create({ id: 'user-123', name: 'John Doe', email: 'john@example.com' } as any).execute();
+});
+
+afterAll(async () => {
+  await deleteTestTable(TEST_TABLE);
+});
+
+describe('BetterDDB - Delete Operation', () => {
+  it('should delete an item using DeleteBuilder', async () => {
+    await userDdb.delete({ id: 'user-123', email: 'john@example.com' })
+      .execute();
+    const deletedUser = await userDdb.get({ id: 'user-123', email: 'john@example.com' }).execute();
+    expect(deletedUser).toBeNull();
+  });
+});

package/test/get.test.ts

@@ -0,0 +1,58 @@
+// __tests__/get.test.ts
+import { z } from 'zod';
+import { BetterDDB } from '../src/betterddb';
+import { DynamoDB } from 'aws-sdk';
+import { createTestTable, deleteTestTable } from './utils/table-setup';
+
+const TEST_TABLE = "get-test-table";
+const ENDPOINT = 'http://localhost:4566';
+const REGION = 'us-east-1';
+const ENTITY_NAME = 'USER';
+const PRIMARY_KEY = 'id';
+const PRIMARY_KEY_TYPE = 'S';
+const SORT_KEY = 'email';
+const SORT_KEY_TYPE = 'S';
+const KEY_SCHEMA = [{ AttributeName: PRIMARY_KEY, KeyType: 'HASH' }, { AttributeName: SORT_KEY, KeyType: 'RANGE' }];
+const ATTRIBUTE_DEFINITIONS = [{ AttributeName: PRIMARY_KEY, AttributeType: PRIMARY_KEY_TYPE }, { AttributeName: SORT_KEY, AttributeType: SORT_KEY_TYPE }];
+const client = new DynamoDB.DocumentClient({
+  region: REGION,
+  endpoint: ENDPOINT,
+});
+
+
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+}).passthrough();
+
+const userDdb = new BetterDDB({
+  schema: UserSchema,
+  tableName: TEST_TABLE,
+  entityName: ENTITY_NAME,
+  keys: {
+    primary: { name: PRIMARY_KEY, definition: { build: (raw) => raw.id! } },
+    sort: { name: SORT_KEY, definition: { build: (raw) => raw.email! } },
+  },
+  client,
+  autoTimestamps: true,
+});
+
+beforeAll(async () => {
+  await createTestTable(TEST_TABLE, KEY_SCHEMA, ATTRIBUTE_DEFINITIONS);
+  await userDdb.create({ id: 'user-123', name: 'John Doe', email: 'john@example.com' } as any).execute();
+});
+
+afterAll(async () => {
+  await deleteTestTable(TEST_TABLE);
+});
+
+describe('BetterDDB - Get Operation', () => {
+  it('should retrieve an item using GetBuilder', async () => {
+    const user = await userDdb.get({ id: 'user-123', email: 'john@example.com' }).execute();
+    expect(user).not.toBeNull();
+    expect(user?.id).toBe('user-123');
+  });
+});

package/test/query.test.ts

@@ -0,0 +1,73 @@
+import { z } from 'zod';
+import { BetterDDB } from '../src/betterddb';
+import { DynamoDB } from 'aws-sdk';
+import { createTestTable, deleteTestTable } from './utils/table-setup';
+
+const TEST_TABLE = "query-test-table";
+const ENDPOINT = 'http://localhost:4566';
+const REGION = 'us-east-1';
+const ENTITY_NAME = 'USER';
+const PRIMARY_KEY = 'id';
+const PRIMARY_KEY_TYPE = 'S';
+const SORT_KEY = 'email';
+const SORT_KEY_TYPE = 'S';
+const KEY_SCHEMA = [{ AttributeName: PRIMARY_KEY, KeyType: 'HASH' }, { AttributeName: SORT_KEY, KeyType: 'RANGE' }];
+const ATTRIBUTE_DEFINITIONS = [{ AttributeName: PRIMARY_KEY, AttributeType: PRIMARY_KEY_TYPE }, { AttributeName: SORT_KEY, AttributeType: SORT_KEY_TYPE }];
+const client = new DynamoDB.DocumentClient({
+  region: REGION,
+  endpoint: ENDPOINT,
+});
+
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+}).passthrough();
+
+const userDdb = new BetterDDB({
+  schema: UserSchema,
+  tableName: TEST_TABLE,
+  entityName: ENTITY_NAME,
+  keys: {
+    primary: { name: PRIMARY_KEY, definition: PRIMARY_KEY },
+    gsis: {
+      EmailIndex: {
+        name: 'EmailIndex',
+        primary: { name: 'email', definition: 'email' }
+      }
+    }
+  },
+  client,
+  autoTimestamps: true,
+});
+
+beforeAll(async () => {
+  await createTestTable(TEST_TABLE, KEY_SCHEMA, ATTRIBUTE_DEFINITIONS);
+  // Insert multiple items.
+  const items = [
+    { id: 'user-1', name: 'Alice', email: 'alice@example.com' },
+    { id: 'user-2', name: 'Alice B', email: 'alice@example.com' },
+    { id: 'user-3', name: 'Bob', email: 'bob@example.com' }
+  ];
+  for (const item of items) {
+    await userDdb.create(item as any).execute();
+  }
+});
+
+afterAll(async () => {
+  await deleteTestTable(TEST_TABLE);
+});
+
+describe('BetterDDB - Query Operation', () => {
+  it('should query items using QueryBuilder', async () => {
+    const results = await userDdb.query({ id: 'user-1' })
+      .where('name', 'begins_with', 'Alice')
+      .limitResults(5);
+    expect(results.length).toBeGreaterThanOrEqual(1);
+    results.forEach(result => {
+      expect(result.name).toMatch(/^Alice/);
+    });
+  });
+});

package/test/scan.test.ts

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+import { BetterDDB } from '../src/betterddb';
+import { DynamoDB } from 'aws-sdk';
+import { createTestTable, deleteTestTable } from './utils/table-setup';
+
+const TEST_TABLE = "scan-test-table";
+const ENDPOINT = 'http://localhost:4566';
+const REGION = 'us-east-1';
+const ENTITY_NAME = 'USER';
+const PRIMARY_KEY = 'id';
+const PRIMARY_KEY_TYPE = 'S';
+const SORT_KEY = 'email';
+const SORT_KEY_TYPE = 'S';
+const KEY_SCHEMA = [{ AttributeName: PRIMARY_KEY, KeyType: 'HASH' }, { AttributeName: SORT_KEY, KeyType: 'RANGE' }];
+const ATTRIBUTE_DEFINITIONS = [{ AttributeName: PRIMARY_KEY, AttributeType: PRIMARY_KEY_TYPE }, { AttributeName: SORT_KEY, AttributeType: SORT_KEY_TYPE }];
+const client = new DynamoDB.DocumentClient({
+  region: REGION,
+  endpoint: ENDPOINT,
+});
+
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+}).passthrough();
+
+const userDdb = new BetterDDB({
+  schema: UserSchema,
+  tableName: TEST_TABLE,
+  entityName: ENTITY_NAME,
+  keys: {
+    primary: { name: PRIMARY_KEY, definition: PRIMARY_KEY },
+  },
+  client,
+  autoTimestamps: true,
+});
+
+beforeAll(async () => {
+  await createTestTable(TEST_TABLE, KEY_SCHEMA, ATTRIBUTE_DEFINITIONS);
+  // Insert multiple items.
+  const items = [
+    { id: 'user-4', name: 'Charlie', email: 'charlie@example.com' },
+    { id: 'user-5', name: 'Dave', email: 'dave@example.com' }
+  ];
+  for (const item of items) {
+    await userDdb.create(item as any).execute();
+  }
+});
+
+afterAll(async () => {
+  await deleteTestTable(TEST_TABLE);
+});
+
+describe('BetterDDB - Scan Operation', () => {
+  it('should scan items using ScanBuilder', async () => {
+    const results = await userDdb.scan()
+      .where('email', 'begins_with', 'char')
+      .limitResults(10);
+    expect(results.length).toBeGreaterThanOrEqual(1);
+    results.forEach(result => {
+      expect(result.email).toMatch(/^char/i);
+    });
+  });
+});

package/test/update.test.ts

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+import { BetterDDB } from '../src/betterddb';
+import { DynamoDB } from 'aws-sdk';
+import { createTestTable, deleteTestTable } from './utils/table-setup';
+
+const TEST_TABLE = "update-test-table";
+const ENDPOINT = 'http://localhost:4566';
+const REGION = 'us-east-1';
+const ENTITY_NAME = 'USER';
+const PRIMARY_KEY = 'id';
+const PRIMARY_KEY_TYPE = 'S';
+const SORT_KEY = 'email';
+const SORT_KEY_TYPE = 'S';
+const KEY_SCHEMA = [{ AttributeName: PRIMARY_KEY, KeyType: 'HASH' }, { AttributeName: SORT_KEY, KeyType: 'RANGE' }];
+const ATTRIBUTE_DEFINITIONS = [{ AttributeName: PRIMARY_KEY, AttributeType: PRIMARY_KEY_TYPE }, { AttributeName: SORT_KEY, AttributeType: SORT_KEY_TYPE }];
+const client = new DynamoDB.DocumentClient({
+  region: REGION,
+  endpoint: ENDPOINT,
+});
+
+
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  version: z.number().optional(),
+}).passthrough();
+
+const userDdb = new BetterDDB({
+  schema: UserSchema,
+  tableName: TEST_TABLE,
+  entityName: ENTITY_NAME,
+  keys: {
+    primary: { name: PRIMARY_KEY, definition: { build: (raw) => raw.id! } },
+    sort: { name: SORT_KEY, definition: { build: (raw) => raw.email! } },
+  },
+  client,
+  autoTimestamps: true,
+});
+
+beforeAll(async () => {
+  await createTestTable(TEST_TABLE, KEY_SCHEMA, ATTRIBUTE_DEFINITIONS);
+  await userDdb.create({ id: 'user-123', name: 'John Doe', email: 'john@example.com' } as any).execute();
+});
+
+afterAll(async () => {
+  await deleteTestTable(TEST_TABLE);
+});
+
+describe('BetterDDB - Update Operation', () => {
+  it('should update an existing item using UpdateBuilder', async () => {
+    const updatedUser = await userDdb.update({ id: 'user-123', email: 'john@example.com' }).set({ name: 'Jane Doe' }).execute();
+    expect(updatedUser.name).toBe('Jane Doe');
+    expect(updatedUser.email).toBe('john@example.com');
+  });
+});

package/test/utils/table-setup.ts

@@ -0,0 +1,55 @@
+import { DynamoDB } from 'aws-sdk';
+
+export const createTestTable = async (tableName: string, keySchema: DynamoDB.CreateTableInput['KeySchema'], attributeDefinitions: DynamoDB.CreateTableInput['AttributeDefinitions']) => {
+  const dynamoDB = new DynamoDB({
+    region: 'us-east-1',
+    endpoint: 'http://localhost:4566',
+  });
+
+  console.log('Creating DynamoDB table in LocalStack...');
+
+  try {
+    await dynamoDB.createTable({
+      TableName: tableName,
+      KeySchema: keySchema,
+      AttributeDefinitions: attributeDefinitions,
+      BillingMode: 'PAY_PER_REQUEST',
+    }).promise();
+  } catch (error: any) {
+    if (error.code === 'ResourceInUseException') {
+      console.log('Table already exists, skipping creation.');
+    } else {
+      throw error;
+    }
+  }
+
+  // Wait for the table to become active.
+  let attempts = 0;
+  while (attempts < 60) { // wait up to 60 seconds
+    const { Table } = await dynamoDB.describeTable({ TableName: tableName }).promise();
+    if (Table?.TableStatus === 'ACTIVE') {
+      console.log('DynamoDB table is ready.');
+      return;
+    }
+    console.log('Waiting for table to become ACTIVE...');
+    await new Promise((res) => setTimeout(res, 1000));
+    attempts++;
+  }
+  throw new Error('Table did not become active in time.');
+};
+
+export const deleteTestTable = async (tableName: string) => {
+  const dynamoDB = new DynamoDB({
+    region: 'us-east-1',
+    endpoint: 'http://localhost:4566',
+  });
+  try {
+    await dynamoDB.deleteTable({ TableName: tableName }).promise();
+  } catch (error: any) {
+    if (error.code === 'ResourceNotFoundException') {
+      console.log('Table not found during deletion.');
+    } else {
+      throw error;
+    }
+  }
+};

package/test/placeholder.test.ts

@@ -1,99 +0,0 @@
-import { z } from 'zod';
-import { BetterDDB } from '../src/betterddb';
-import { DynamoDB } from 'aws-sdk';
-
-const TEST_TABLE = 'TestTable';
-
-// LocalStack Configuration
-const client = new DynamoDB.DocumentClient({
-  region: 'us-east-1',
-  endpoint: 'http://localhost:4566'
-});
-
-// Table Schema
-const UserSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-  email: z.string().email(),
-  createdAt: z.string(),
-  updatedAt: z.string()
-});
-
-const userDal = new BetterDDB({
-  schema: UserSchema,
-  tableName: TEST_TABLE,
-  keys: {
-    primary: { name: 'pk', definition: 'id' }
-  },
-  entityName: 'USER',
-  client,
-  autoTimestamps: true
-});
-
-beforeAll(async () => {
-  const dynamoDB = new DynamoDB({
-    region: 'us-east-1',
-    endpoint: 'http://localhost:4566'
-  });
-
-  console.log('Creating DynamoDB table in LocalStack...');
-
-  await dynamoDB.createTable({
-    TableName: TEST_TABLE,
-    KeySchema: [{ AttributeName: 'pk', KeyType: 'HASH' }],
-    AttributeDefinitions: [{ AttributeName: 'pk', AttributeType: 'S' }],
-    BillingMode: 'PAY_PER_REQUEST'
-  }).promise();
-
-  // Wait for the table to become active
-  while (true) {
-    const { Table } = await dynamoDB.describeTable({ TableName: TEST_TABLE }).promise();
-    if (Table?.TableStatus === 'ACTIVE') {
-      console.log('DynamoDB table is ready.');
-      break;
-    }
-    console.log('Waiting for table to become ACTIVE...');
-    await new Promise(res => setTimeout(res, 1000)); // Wait 1 sec before retrying
-  }
-});
-
-afterAll(async () => {
-  // Cleanup: delete the table
-  const dynamoDB = new DynamoDB({
-    region: 'us-east-1',
-    endpoint: 'http://localhost:4566'
-  });
-
-  await dynamoDB.deleteTable({ TableName: TEST_TABLE }).promise();
-});
-
-describe('BetterDDB - Integration Tests', () => {
-  it('should insert an item into DynamoDB', async () => {
-    const user = {
-      id: 'user-123',
-      name: 'John Doe',
-      email: 'john@example.com'
-    };
-
-    const createdUser = await userDal.create(user as any).execute();
-    expect(createdUser).toHaveProperty('createdAt');
-    expect(createdUser).toHaveProperty('updatedAt');
-  });
-
-  it('should retrieve an item by ID', async () => {
-    const user = await userDal.get({ id: 'user-123' }).execute();
-    expect(user).not.toBeNull();
-    expect(user?.id).toBe('user-123');
-  });
-
-  it('should update an existing item', async () => {
-    const updatedUser = await userDal.update({ id: 'user-123' }).set({ name: 'Jane Doe' }).execute();
-    expect(updatedUser.name).toBe('Jane Doe');
-  });
-
-  it('should delete an item', async () => {
-    await userDal.delete({ id: 'user-123' }).execute();
-    const deletedUser = await userDal.get({ id: 'user-123' }).execute();
-    expect(deletedUser).toBeNull();
-  });
-});