betterddb 0.2.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/betterddb.d.ts

@@ -1,5 +1,11 @@
 import { ZodSchema } from 'zod';
 import { DynamoDB } from 'aws-sdk';
+import { QueryBuilder } from './builders/query-builder';
+import { ScanBuilder } from './builders/scan-builder';
+import { UpdateBuilder } from './builders/update-builder';
+import { CreateBuilder } from './builders/create-builder';
+import { GetBuilder } from './builders/get-builder';
+import { DeleteBuilder } from './builders/delete-builder';
 export type PrimaryKeyValue = string | number;
 /**
  * A key definition can be either a simple key (a property name)
@@ -56,6 +62,7 @@ export interface KeysConfig<T> {
 export interface BetterDDBOptions<T> {
     schema: ZodSchema<T>;
     tableName: string;
+    entityName: string;
     keys: KeysConfig<T>;
     client: DynamoDB.DocumentClient;
     /**
@@ -73,64 +80,50 @@ export interface BetterDDBOptions<T> {
 export declare class BetterDDB<T> {
     protected schema: ZodSchema<T>;
     protected tableName: string;
+    protected entityName: string;
     protected client: DynamoDB.DocumentClient;
     protected keys: KeysConfig<T>;
     protected autoTimestamps: boolean;
     constructor(options: BetterDDBOptions<T>);
+    getKeys(): KeysConfig<T>;
+    getTableName(): string;
+    getClient(): DynamoDB.DocumentClient;
+    getSchema(): ZodSchema<T>;
+    getAutoTimestamps(): boolean;
     protected getKeyValue(def: KeyDefinition<T>, rawKey: Partial<T>): string;
     /**
      * Build the primary key from a raw key object.
      */
-    protected buildKey(rawKey: Partial<T>): Record<string, any>;
+    buildKey(rawKey: Partial<T>): Record<string, any>;
     /**
      * Build index attributes for each defined GSI.
      */
-    protected buildIndexes(rawItem: Partial<T>): Record<string, any>;
+    buildIndexes(rawItem: Partial<T>): Record<string, any>;
     /**
      * Create an item:
      * - Computes primary key and index attributes,
      * - Optionally injects timestamps,
      * - Validates the item and writes it to DynamoDB.
      */
-    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[]>;
+    create(item: T): CreateBuilder<T>;
     /**
-     * Query by primary key (using the computed primary key) and an optional sort key condition.
+     * Get an item by its primary key.
      */
-    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>;
-    }>;
-    buildTransactPut(item: T): DynamoDB.DocumentClient.TransactWriteItem;
-    buildTransactUpdate(rawKey: Partial<T>, update: Partial<T>, options?: {
-        expectedVersion?: number;
-    }): DynamoDB.DocumentClient.TransactWriteItem;
-    buildTransactDelete(rawKey: Partial<T>): DynamoDB.DocumentClient.TransactWriteItem;
-    transactWrite(operations: DynamoDB.DocumentClient.TransactWriteItemList): Promise<void>;
-    transactGetByKeys(rawKeys: Partial<T>[]): Promise<T[]>;
-    transactGet(getItems: {
-        TableName: string;
-        Key: any;
-    }[]): Promise<T[]>;
-    batchWrite(ops: {
-        puts?: T[];
-        deletes?: Partial<T>[];
-    }): Promise<void>;
-    private batchWriteChunk;
-    private retryBatchWrite;
-    batchGet(rawKeys: Partial<T>[]): Promise<T[]>;
+    get(rawKey: Partial<T>): GetBuilder<T>;
+    /**
+     * Update an item.
+     */
+    update(key: Partial<T>, expectedVersion?: number): UpdateBuilder<T>;
+    /**
+     * Delete an item.
+     */
+    delete(rawKey: Partial<T>): DeleteBuilder<T>;
+    /**
+     * Query items.
+     */
+    query(key: Partial<T>): QueryBuilder<T>;
+    /**
+     * Scan for items.
+     */
+    scan(): ScanBuilder<T>;
 }