@ftschopp/dynatable-core 1.0.0

package/src/builders/README.md

@@ -0,0 +1,272 @@
+# Builders Architecture
+
+This directory contains the builder pattern implementation for DynamoDB operations.
+
+## Structure
+
+```
+builders/
+├── shared/           # Shared utilities and types
+│   ├── types.ts      # Base types (Condition, OpBuilder, etc.)
+│   ├── operators.ts  # Condition operators (eq, ne, lt, etc.)
+│   └── conditions.ts # Condition expression builders
+├── get/              # GET operation builder
+│   ├── types.ts
+│   ├── create-get-builder.ts
+│   └── index.ts
+├── put/              # PUT operation builder
+│   ├── types.ts
+│   ├── create-put-builder.ts
+│   └── index.ts
+└── query/            # QUERY operation builder
+    ├── types.ts
+    ├── create-query-builder.ts
+    └── index.ts
+```
+
+## Design Principles
+
+1. **Modularity**: Each operation has its own directory with dedicated types and implementation
+2. **Reusability**: Common utilities are centralized in `shared/`
+3. **Scalability**: Easy to add new operations (query, scan, delete, etc.) by following the same pattern
+4. **Type Safety**: Full TypeScript support with proper type inference
+
+## Adding a New Builder
+
+To add a new operation (e.g., `query`):
+
+1. Create a new directory: `builders/query/`
+2. Add three files:
+   - `types.ts` - Interface definition extending `OperationBuilder` or `ExecutableBuilder`
+   - `create-query-builder.ts` - Implementation with immutable builder pattern
+   - `index.ts` - Export all public APIs
+3. Import shared utilities from `../shared`
+4. Export from main `builders/index.ts`
+
+## Usage Examples
+
+### GET Operation
+
+```typescript
+import { createGetBuilder } from './builders';
+
+const getBuilder = createGetBuilder(tableName, key, client)
+  .select(['name', 'email'])
+  .consistentRead();
+
+const item = await getBuilder.execute();
+```
+
+### PUT Operation
+
+```typescript
+import { createPutBuilder } from './builders';
+
+const putBuilder = createPutBuilder(tableName, item, client).ifNotExists().returning('ALL_NEW');
+
+const result = await putBuilder.execute();
+```
+
+### QUERY Operation
+
+```typescript
+import { createQueryBuilder } from './builders';
+
+// Basic query with partition key
+const query1 = createQueryBuilder(tableName, client, model)
+  .where((attr, op) => op.eq(attr.username, 'juanca'))
+  .execute();
+
+// Query with AND filter
+const query2 = createQueryBuilder(tableName, client, model)
+  .where((attr, op) => op.and(op.eq(attr.username, 'juanca'), op.gt(attr.likesCount, 10)))
+  .limit(10)
+  .scanIndexForward(false)
+  .select(['id', 'title', 'createdAt'])
+  .execute();
+
+// Query with OR filter
+const query3 = createQueryBuilder(tableName, client, model)
+  .where((attr, op) =>
+    op.and(
+      op.eq(attr.username, 'juanca'),
+      op.or(op.gt(attr.likesCount, 100), op.gt(attr.commentCount, 50))
+    )
+  )
+  .execute();
+
+// Complex nested conditions
+const query4 = createQueryBuilder(tableName, client, model)
+  .where((attr, op) =>
+    op.and(
+      op.eq(attr.username, 'juanca'),
+      op.or(
+        op.and(op.gt(attr.likesCount, 100), op.lt(attr.commentCount, 10)),
+        op.gt(attr.likesCount, 500)
+      )
+    )
+  )
+  .execute();
+
+// Query using a secondary index
+const query5 = createQueryBuilder(tableName, client, model)
+  .where((attr, op) => op.eq(attr.status, 'active'))
+  .useIndex('GSI1')
+  .execute();
+```
+
+## Type-Safe Queries
+
+The Query Builder provides full TypeScript type safety with an intuitive API:
+
+```typescript
+// Your model type
+type Photo = {
+  username: string; // Used in partition key template
+  photoId: string; // Used in sort key template
+  url: string;
+  likesCount: number;
+  commentCount: number;
+};
+
+// Type-safe query - TypeScript knows all fields and their types!
+const photos = await createQueryBuilder<Photo>(tableName, client, model)
+  .where((attr, op) =>
+    op.and(
+      op.eq(attr.username, 'juanca'), // ✓ Key field - goes to KeyConditionExpression
+      op.gt(attr.likesCount, 10) // ✓ Non-key field - goes to FilterExpression
+    )
+  )
+  .select(['username', 'url', 'likesCount']) // ✓ Only Photo keys allowed
+  .execute();
+
+// TypeScript will catch errors at compile time:
+// .where((attr, op) => op.eq(attr.invalid, 'x'))     // ✗ Property 'invalid' does not exist
+// .where((attr, op) => op.eq(attr.username, 123))    // ✗ Argument of type 'number' not assignable
+// .select(['invalidField'])                          // ✗ Type error!
+```
+
+### Important: Automatic Separation of Key Conditions vs Filters
+
+The query builder **automatically separates** your conditions:
+
+**KeyConditionExpression** (efficient, uses indexes):
+
+- Fields used in partition key (pk) or sort key (sk) templates
+- Evaluated during the query at the index level
+- Very efficient - only reads matching items
+
+**FilterExpression** (less efficient, post-processing):
+
+- All other fields not in key templates
+- Applied AFTER items are retrieved
+- OR operators automatically go here (DynamoDB requirement)
+
+```typescript
+// ✓ The builder handles this automatically!
+.where((attr, op) => op.and(
+  op.eq(attr.username, 'juanca'),    // → KeyConditionExpression (username is in pk template)
+  op.gt(attr.likesCount, 10)         // → FilterExpression (likesCount is not a key)
+))
+
+// Generates:
+// KeyConditionExpression: "#username = :username_0"
+// FilterExpression: "#likesCount > :likesCount_1"
+```
+
+## Important: Operator Isolation
+
+Each builder creates its own isolated instance of operators with independent counters. This prevents naming conflicts when building multiple queries concurrently or reusing builder code.
+
+```typescript
+// ✓ Each builder has isolated state
+const query1 = createQueryBuilder(table, client).where((attr, op) => op.eq(attr.id, '1')); // Uses :id_0
+
+const query2 = createQueryBuilder(table, client).where((attr, op) => op.eq(attr.id, '2')); // Also uses :id_0 (isolated counter)
+
+// No conflicts! Each builder has its own counter starting at 0
+```
+
+For advanced use cases where you need to manually create operators, use `createOpBuilder()`:
+
+```typescript
+import { createOpBuilder } from './builders/shared';
+
+const op = createOpBuilder(); // Creates isolated operator instance
+const condition = op.eq(attr, value);
+```
+
+## Available Operators
+
+The `op` parameter in `.where()` provides these operators:
+
+**Comparison Operators:**
+
+- `op.eq(attr, value)` - Equals (=)
+- `op.ne(attr, value)` - Not equals (<>)
+- `op.lt(attr, value)` - Less than (<)
+- `op.lte(attr, value)` - Less than or equal (<=)
+- `op.gt(attr, value)` - Greater than (>)
+- `op.gte(attr, value)` - Greater than or equal (>=)
+- `op.between(attr, low, high)` - Between two values
+- `op.beginsWith(attr, prefix)` - Begins with a string (for string fields)
+
+**Logical Operators:**
+
+- `op.and(...conditions)` - Combines conditions with AND
+- `op.or(...conditions)` - Combines conditions with OR
+- `op.not(condition)` - Negates a condition
+
+### Example Usage
+
+```typescript
+// Basic equality
+.where((attr, op) => op.eq(attr.username, 'juanca'))
+
+// Comparison operators
+.where((attr, op) => op.and(
+  op.eq(attr.username, 'juanca'),
+  op.gt(attr.age, 18),
+  op.lt(attr.score, 100)
+))
+
+// String operations
+.where((attr, op) => op.beginsWith(attr.email, 'admin@'))
+
+// Between operator
+.where((attr, op) => op.between(attr.createdAt, '2024-01-01', '2024-12-31'))
+
+// OR conditions
+.where((attr, op) => op.or(
+  op.eq(attr.status, 'active'),
+  op.eq(attr.status, 'pending')
+))
+
+// Complex nested conditions
+.where((attr, op) => op.and(
+  op.eq(attr.org, 'acme'),
+  op.or(
+    op.and(
+      op.gt(attr.score, 80),
+      op.eq(attr.verified, true)
+    ),
+    op.eq(attr.role, 'admin')
+  )
+))
+
+// NOT operator
+.where((attr, op) => op.not(op.eq(attr.status, 'deleted')))
+
+// Complete example with all features
+await table.entities.Photo.query()
+  .where((attr, op) => op.and(
+    op.eq(attr.username, 'juanca'),              // Key field
+    op.or(
+      op.gt(attr.likesCount, 100),               // Filter field
+      op.gt(attr.commentCount, 50)               // Filter field
+    )
+  ))
+  .limit(50)
+  .scanIndexForward(false)
+  .execute();
+```

package/src/builders/batch-get/README.md

@@ -0,0 +1,98 @@
+# BatchGet Builder
+
+The `BatchGetBuilder` allows retrieving multiple items from one or more tables in a single request to DynamoDB.
+
+## Features
+
+- Retrieve multiple items by their keys
+- Supports attribute projection (select only specific fields)
+- Supports consistent read
+- Can retrieve items from multiple tables in a single request
+
+## Basic Usage
+
+```typescript
+import { createBatchGetBuilder } from './builders/batch-get';
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+
+const client = new DynamoDBClient({});
+
+// Retrieve multiple users
+const result = await createBatchGetBuilder(
+  {
+    Users: {
+      Keys: [
+        { pk: 'USER#alice', sk: 'USER#alice' },
+        { pk: 'USER#bob', sk: 'USER#bob' },
+        { pk: 'USER#charlie', sk: 'USER#charlie' },
+      ],
+    },
+  },
+  client
+).execute();
+```
+
+## With Attribute Projection
+
+```typescript
+interface User {
+  username: string;
+  name: string;
+  followerCount: number;
+}
+
+const result = await createBatchGetBuilder<User>(
+  {
+    Users: {
+      Keys: [
+        { pk: 'USER#alice', sk: 'USER#alice' },
+        { pk: 'USER#bob', sk: 'USER#bob' },
+      ],
+    },
+  },
+  client
+)
+  .select(['username', 'name', 'followerCount'])
+  .execute();
+```
+
+## With Consistent Read
+
+```typescript
+const result = await createBatchGetBuilder(
+  {
+    Users: {
+      Keys: [
+        { pk: 'USER#alice', sk: 'USER#alice' },
+        { pk: 'USER#bob', sk: 'USER#bob' },
+      ],
+    },
+  },
+  client
+)
+  .consistentRead()
+  .execute();
+```
+
+## Using the Table Class
+
+```typescript
+// Retrieve multiple users using the Table class
+const result = await table
+  .batchGet({
+    InstagramClone: {
+      Keys: [
+        { pk: 'USER#alice', sk: 'USER#alice' },
+        { pk: 'USER#bob', sk: 'USER#bob' },
+      ],
+    },
+  })
+  .select(['username', 'name'])
+  .execute();
+```
+
+## DynamoDB Limitations
+
+- Maximum 100 items per request
+- Maximum 16 MB of data per request
+- Unprocessed items are returned in `UnprocessedKeys` and must be retried

package/src/builders/batch-get/create-batch-get-builder.test.ts

@@ -0,0 +1,165 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { createBatchGetBuilder } from './create-batch-get-builder';
+
+interface User {
+  pk: string;
+  sk: string;
+  username: string;
+  name: string;
+  followerCount: number;
+  followingCount: number;
+}
+
+describe('BatchGetBuilder', () => {
+  const client = new DynamoDBClient({});
+
+  describe('dbParams', () => {
+    test('should build basic BatchGetItem params', () => {
+      const requestItems = {
+        Users: {
+          Keys: [
+            { pk: 'USER#alice', sk: 'USER#alice' },
+            { pk: 'USER#bob', sk: 'USER#bob' },
+          ],
+        },
+      };
+
+      const builder = createBatchGetBuilder(requestItems, client);
+      const params = builder.dbParams();
+
+      expect(params).toEqual({
+        RequestItems: {
+          Users: {
+            Keys: [
+              { pk: 'USER#alice', sk: 'USER#alice' },
+              { pk: 'USER#bob', sk: 'USER#bob' },
+            ],
+          },
+        },
+      });
+    });
+
+    test('should build BatchGetItem params with projection', () => {
+      const requestItems = {
+        Users: {
+          Keys: [
+            { pk: 'USER#alice', sk: 'USER#alice' },
+            { pk: 'USER#bob', sk: 'USER#bob' },
+          ],
+        },
+      };
+
+      const builder = createBatchGetBuilder<User>(requestItems, client).select([
+        'username',
+        'name',
+        'followerCount',
+      ]);
+      const params = builder.dbParams();
+
+      expect(params).toEqual({
+        RequestItems: {
+          Users: {
+            Keys: [
+              { pk: 'USER#alice', sk: 'USER#alice' },
+              { pk: 'USER#bob', sk: 'USER#bob' },
+            ],
+            ProjectionExpression: 'username, name, followerCount',
+          },
+        },
+      });
+    });
+
+    test('should build BatchGetItem params with consistent read', () => {
+      const requestItems = {
+        Users: {
+          Keys: [
+            { pk: 'USER#alice', sk: 'USER#alice' },
+            { pk: 'USER#bob', sk: 'USER#bob' },
+          ],
+        },
+      };
+
+      const builder = createBatchGetBuilder(requestItems, client).consistentRead();
+      const params = builder.dbParams();
+
+      expect(params).toEqual({
+        RequestItems: {
+          Users: {
+            Keys: [
+              { pk: 'USER#alice', sk: 'USER#alice' },
+              { pk: 'USER#bob', sk: 'USER#bob' },
+            ],
+            ConsistentRead: true,
+          },
+        },
+      });
+    });
+
+    test('should build BatchGetItem params with multiple tables', () => {
+      const requestItems = {
+        Users: {
+          Keys: [
+            { pk: 'USER#alice', sk: 'USER#alice' },
+            { pk: 'USER#bob', sk: 'USER#bob' },
+          ],
+        },
+        Photos: {
+          Keys: [
+            { pk: 'UP#alice', sk: 'PHOTO#photo1' },
+            { pk: 'UP#bob', sk: 'PHOTO#photo2' },
+          ],
+        },
+      };
+
+      const builder = createBatchGetBuilder(requestItems, client);
+      const params = builder.dbParams();
+
+      expect(params).toEqual({
+        RequestItems: {
+          Users: {
+            Keys: [
+              { pk: 'USER#alice', sk: 'USER#alice' },
+              { pk: 'USER#bob', sk: 'USER#bob' },
+            ],
+          },
+          Photos: {
+            Keys: [
+              { pk: 'UP#alice', sk: 'PHOTO#photo1' },
+              { pk: 'UP#bob', sk: 'PHOTO#photo2' },
+            ],
+          },
+        },
+      });
+    });
+
+    test('should build BatchGetItem params with projection and consistent read', () => {
+      const requestItems = {
+        Users: {
+          Keys: [
+            { pk: 'USER#alice', sk: 'USER#alice' },
+            { pk: 'USER#bob', sk: 'USER#bob' },
+          ],
+        },
+      };
+
+      const builder = createBatchGetBuilder<User>(requestItems, client)
+        .select(['username', 'name'])
+        .consistentRead();
+      const params = builder.dbParams();
+
+      expect(params).toEqual({
+        RequestItems: {
+          Users: {
+            Keys: [
+              { pk: 'USER#alice', sk: 'USER#alice' },
+              { pk: 'USER#bob', sk: 'USER#bob' },
+            ],
+            ProjectionExpression: 'username, name',
+            ConsistentRead: true,
+          },
+        },
+      });
+    });
+  });
+});

package/src/builders/batch-get/create-batch-get-builder.ts

@@ -0,0 +1,106 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import {
+  BatchGetCommand,
+  BatchGetCommandInput,
+  BatchGetCommandOutput,
+} from '@aws-sdk/lib-dynamodb';
+import { BatchGetBuilder } from './types';
+import { DynamoDBLogger } from '../../utils/dynamodb-logger';
+
+/**
+ * Creates a BatchGetBuilder to retrieve multiple items by their keys.
+ *
+ * @param requestItems - An object where keys are table names and values are objects containing Keys array
+ * @param client - DynamoDB client instance
+ * @param options - Optional configuration (projection, consistentRead)
+ * @param logger - Optional logger instance
+ */
+export function createBatchGetBuilder<Model>(
+  requestItems: Record<string, { Keys: any[] }>,
+  client: DynamoDBClient,
+  options?: {
+    projection?: (keyof Model)[];
+    consistentRead?: boolean;
+  },
+  logger?: DynamoDBLogger
+): BatchGetBuilder<Model> {
+  const projection = options?.projection ?? [];
+  const isConsistent = options?.consistentRead ?? false;
+
+  return {
+    /**
+     * Select only specific attributes to retrieve.
+     */
+    select(attrs) {
+      return createBatchGetBuilder(
+        requestItems,
+        client,
+        {
+          projection: attrs,
+          consistentRead: isConsistent,
+        },
+        logger
+      );
+    },
+
+    /**
+     * Enable strongly consistent read.
+     */
+    consistentRead() {
+      return createBatchGetBuilder(
+        requestItems,
+        client,
+        {
+          projection,
+          consistentRead: true,
+        },
+        logger
+      );
+    },
+
+    /**
+     * Build the underlying DynamoDB input parameters.
+     */
+    dbParams(): BatchGetCommandInput {
+      // Apply projection and consistentRead to all tables
+      const enhancedRequestItems = Object.entries(requestItems).reduce(
+        (acc, [tableName, tableRequest]) => {
+          acc[tableName] = {
+            Keys: tableRequest.Keys,
+            ...(projection.length > 0 && {
+              ProjectionExpression: projection.join(', '),
+            }),
+            ...(isConsistent && { ConsistentRead: true }),
+          };
+          return acc;
+        },
+        {} as Record<string, any>
+      );
+
+      return {
+        RequestItems: enhancedRequestItems,
+      };
+    },
+
+    /**
+     * Execute the BatchGetItem command and return the items.
+     */
+    async execute(): Promise<Record<string, Model[]>> {
+      const params = this.dbParams();
+      const result: BatchGetCommandOutput = await client.send(new BatchGetCommand(params));
+      logger?.log('BatchGetCommand', params, result);
+
+      // Transform the response into a more usable format
+      const responses: Record<string, Model[]> = {};
+
+      if (result.Responses) {
+        for (const [tableName, items] of Object.entries(result.Responses)) {
+          responses[tableName] = items as unknown as Model[];
+        }
+      }
+
+      return responses;
+    },
+  };
+}

package/src/builders/batch-get/index.ts

@@ -0,0 +1,2 @@
+export * from './types';
+export * from './create-batch-get-builder';

package/src/builders/batch-get/types.ts

@@ -0,0 +1,29 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { BatchGetItemCommandInput } from '@aws-sdk/client-dynamodb';
+
+/**
+ * BatchGetBuilder allows you to retrieve multiple items from one or more tables
+ * in a single request.
+ */
+export type BatchGetBuilder<Model> = {
+  /**
+   * Select only specific attributes to retrieve for all items.
+   */
+  select(attrs: (keyof Model)[]): BatchGetBuilder<Model>;
+
+  /**
+   * Enable strongly consistent read for all items.
+   */
+  consistentRead(): BatchGetBuilder<Model>;
+
+  /**
+   * Build the underlying DynamoDB BatchGetItem input parameters.
+   */
+  dbParams(): BatchGetItemCommandInput;
+
+  /**
+   * Execute the BatchGetItem command and return the items.
+   * Returns an object mapping table names to arrays of items.
+   */
+  execute(): Promise<Record<string, Model[]>>;
+};