@ftschopp/dynatable-core 1.0.0

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

@@ -0,0 +1,204 @@
+# BatchWrite Builder
+
+The `BatchWriteBuilder` allows writing (put) or deleting (delete) multiple items from one or more tables in a single request to DynamoDB.
+
+## Features
+
+- Create multiple items (PutRequest)
+- Delete multiple items (DeleteRequest)
+- Mix Put and Delete operations in a single request
+- Supports multiple tables in a single request
+- Handles unprocessed items (UnprocessedItems)
+
+## Basic Usage - Create Items
+
+```typescript
+import { createBatchWriteBuilder } from './builders/batch-write';
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+
+const client = new DynamoDBClient({});
+
+// Create multiple users
+const result = await createBatchWriteBuilder(
+  {
+    Users: [
+      {
+        PutRequest: {
+          Item: {
+            pk: 'USER#alice',
+            sk: 'USER#alice',
+            username: 'alice',
+            name: 'Alice Smith',
+            followerCount: 0,
+            followingCount: 0,
+          },
+        },
+      },
+      {
+        PutRequest: {
+          Item: {
+            pk: 'USER#bob',
+            sk: 'USER#bob',
+            username: 'bob',
+            name: 'Bob Jones',
+            followerCount: 0,
+            followingCount: 0,
+          },
+        },
+      },
+    ],
+  },
+  client
+).execute();
+```
+
+## Delete Items
+
+```typescript
+const result = await createBatchWriteBuilder(
+  {
+    Users: [
+      {
+        DeleteRequest: {
+          Key: {
+            pk: 'USER#alice',
+            sk: 'USER#alice',
+          },
+        },
+      },
+      {
+        DeleteRequest: {
+          Key: {
+            pk: 'USER#bob',
+            sk: 'USER#bob',
+          },
+        },
+      },
+    ],
+  },
+  client
+).execute();
+```
+
+## Mix Put and Delete
+
+```typescript
+const result = await createBatchWriteBuilder(
+  {
+    Users: [
+      {
+        PutRequest: {
+          Item: {
+            pk: 'USER#alice',
+            sk: 'USER#alice',
+            username: 'alice',
+            name: 'Alice Smith Updated',
+          },
+        },
+      },
+      {
+        DeleteRequest: {
+          Key: {
+            pk: 'USER#bob',
+            sk: 'USER#bob',
+          },
+        },
+      },
+    ],
+  },
+  client
+).execute();
+```
+
+## Using the Table Class
+
+```typescript
+// Create multiple items using the Table class
+const result = await table
+  .batchWrite({
+    InstagramClone: [
+      {
+        PutRequest: {
+          Item: {
+            pk: 'USER#alice',
+            sk: 'USER#alice',
+            username: 'alice',
+            name: 'Alice Smith',
+          },
+        },
+      },
+      {
+        DeleteRequest: {
+          Key: {
+            pk: 'USER#bob',
+            sk: 'USER#bob',
+          },
+        },
+      },
+    ],
+  })
+  .execute();
+
+// Handle unprocessed items
+if (result.unprocessedItems) {
+  console.log('Unprocessed items:', result.unprocessedItems);
+  // Retry unprocessed items
+}
+```
+
+## Bulk Operations
+
+```typescript
+// Create multiple photos and likes in a single request
+await table
+  .batchWrite({
+    InstagramClone: [
+      {
+        PutRequest: {
+          Item: {
+            pk: 'UP#alice',
+            sk: 'PHOTO#photo1',
+            username: 'alice',
+            photoId: 'photo1',
+            url: 'https://example.com/photo1.jpg',
+            likesCount: 0,
+            commentCount: 0,
+          },
+        },
+      },
+      {
+        PutRequest: {
+          Item: {
+            pk: 'UP#alice',
+            sk: 'PHOTO#photo2',
+            username: 'alice',
+            photoId: 'photo2',
+            url: 'https://example.com/photo2.jpg',
+            likesCount: 0,
+            commentCount: 0,
+          },
+        },
+      },
+      {
+        PutRequest: {
+          Item: {
+            pk: 'PL#photo1',
+            sk: 'LIKE#bob',
+            photoId: 'photo1',
+            likingUsername: 'bob',
+            likeId: 'like123',
+          },
+        },
+      },
+    ],
+  })
+  .execute();
+```
+
+## DynamoDB Limitations
+
+- Maximum 25 items per request
+- Maximum 16 MB of data per request
+- Does not support conditions (ConditionExpression)
+- Unprocessed items are returned in `UnprocessedItems` and must be retried
+- Put operations completely overwrite the existing item

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

@@ -0,0 +1,173 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { createBatchWriteBuilder } from './create-batch-write-builder';
+
+describe('BatchWriteBuilder', () => {
+  const client = new DynamoDBClient({});
+
+  describe('dbParams', () => {
+    test('should build basic BatchWriteItem params with PutRequests', () => {
+      const requestItems = {
+        Users: [
+          {
+            PutRequest: {
+              Item: {
+                pk: 'USER#alice',
+                sk: 'USER#alice',
+                username: 'alice',
+                name: 'Alice Smith',
+                followerCount: 0,
+                followingCount: 0,
+              },
+            },
+          },
+          {
+            PutRequest: {
+              Item: {
+                pk: 'USER#bob',
+                sk: 'USER#bob',
+                username: 'bob',
+                name: 'Bob Jones',
+                followerCount: 0,
+                followingCount: 0,
+              },
+            },
+          },
+        ],
+      };
+
+      const builder = createBatchWriteBuilder(requestItems, client);
+      const params = builder.dbParams();
+
+      expect(params).toEqual({
+        RequestItems: requestItems,
+      });
+    });
+
+    test('should build BatchWriteItem params with DeleteRequests', () => {
+      const requestItems = {
+        Users: [
+          {
+            DeleteRequest: {
+              Key: {
+                pk: 'USER#alice',
+                sk: 'USER#alice',
+              },
+            },
+          },
+          {
+            DeleteRequest: {
+              Key: {
+                pk: 'USER#bob',
+                sk: 'USER#bob',
+              },
+            },
+          },
+        ],
+      };
+
+      const builder = createBatchWriteBuilder(requestItems, client);
+      const params = builder.dbParams();
+
+      expect(params).toEqual({
+        RequestItems: requestItems,
+      });
+    });
+
+    test('should build BatchWriteItem params with mixed Put and Delete requests', () => {
+      const requestItems = {
+        Users: [
+          {
+            PutRequest: {
+              Item: {
+                pk: 'USER#alice',
+                sk: 'USER#alice',
+                username: 'alice',
+                name: 'Alice Smith',
+                followerCount: 0,
+                followingCount: 0,
+              },
+            },
+          },
+          {
+            DeleteRequest: {
+              Key: {
+                pk: 'USER#bob',
+                sk: 'USER#bob',
+              },
+            },
+          },
+        ],
+      };
+
+      const builder = createBatchWriteBuilder(requestItems, client);
+      const params = builder.dbParams();
+
+      expect(params).toEqual({
+        RequestItems: requestItems,
+      });
+    });
+
+    test('should build BatchWriteItem params with multiple tables', () => {
+      const requestItems = {
+        Users: [
+          {
+            PutRequest: {
+              Item: {
+                pk: 'USER#alice',
+                sk: 'USER#alice',
+                username: 'alice',
+                name: 'Alice Smith',
+              },
+            },
+          },
+        ],
+        Photos: [
+          {
+            PutRequest: {
+              Item: {
+                pk: 'UP#alice',
+                sk: 'PHOTO#photo1',
+                username: 'alice',
+                photoId: 'photo1',
+                url: 'https://example.com/photo1.jpg',
+                likesCount: 0,
+                commentCount: 0,
+              },
+            },
+          },
+          {
+            DeleteRequest: {
+              Key: {
+                pk: 'UP#alice',
+                sk: 'PHOTO#photo2',
+              },
+            },
+          },
+        ],
+      };
+
+      const builder = createBatchWriteBuilder(requestItems, client);
+      const params = builder.dbParams();
+
+      expect(params).toEqual({
+        RequestItems: requestItems,
+      });
+    });
+
+    test('should handle empty request items', () => {
+      const requestItems = {
+        Users: [],
+      };
+
+      const builder = createBatchWriteBuilder(requestItems, client);
+      const params = builder.dbParams();
+
+      expect(params).toEqual({
+        RequestItems: {
+          Users: [],
+        },
+      });
+    });
+  });
+});

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

@@ -0,0 +1,49 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import {
+  BatchWriteCommand,
+  BatchWriteCommandInput,
+  BatchWriteCommandOutput,
+} from '@aws-sdk/lib-dynamodb';
+import { BatchWriteBuilder, WriteRequest } from './types';
+import { DynamoDBLogger } from '../../utils/dynamodb-logger';
+
+/**
+ * Creates a BatchWriteBuilder to put or delete multiple items.
+ *
+ * @param requestItems - An object where keys are table names and values are arrays of WriteRequest
+ * @param client - DynamoDB client instance
+ * @param logger - Optional logger instance
+ */
+export function createBatchWriteBuilder(
+  requestItems: Record<string, WriteRequest[]>,
+  client: DynamoDBClient,
+  logger?: DynamoDBLogger
+): BatchWriteBuilder {
+  return {
+    /**
+     * Build the underlying DynamoDB input parameters.
+     */
+    dbParams(): BatchWriteCommandInput {
+      return {
+        RequestItems: requestItems,
+      };
+    },
+
+    /**
+     * Execute the BatchWriteItem command.
+     */
+    async execute(): Promise<{
+      unprocessedItems?: Record<string, WriteRequest[]>;
+    }> {
+      const params = this.dbParams();
+      const result: BatchWriteCommandOutput = await client.send(new BatchWriteCommand(params));
+      logger?.log('BatchWriteCommand', params, result);
+
+      // Return unprocessed items if any
+      return {
+        unprocessedItems: result.UnprocessedItems as Record<string, WriteRequest[]> | undefined,
+      };
+    },
+  };
+}

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

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

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

@@ -0,0 +1,33 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { BatchWriteItemCommandInput } from '@aws-sdk/client-dynamodb';
+
+/**
+ * A single write request that can be either a PutRequest or DeleteRequest
+ */
+export type WriteRequest = {
+  PutRequest?: {
+    Item: any;
+  };
+  DeleteRequest?: {
+    Key: any;
+  };
+};
+
+/**
+ * BatchWriteBuilder allows you to put or delete multiple items from one or more tables
+ * in a single request.
+ */
+export type BatchWriteBuilder = {
+  /**
+   * Build the underlying DynamoDB BatchWriteItem input parameters.
+   */
+  dbParams(): BatchWriteItemCommandInput;
+
+  /**
+   * Execute the BatchWriteItem command.
+   * Returns unprocessed items if any requests failed.
+   */
+  execute(): Promise<{
+    unprocessedItems?: Record<string, WriteRequest[]>;
+  }>;
+};