@ftschopp/dynatable-core 1.4.2 → 1.4.4

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

@@ -1,43 +0,0 @@
-# BatchGet Builder
-
-The `BatchGetBuilder` retrieves multiple items by key in a single DynamoDB `BatchGetItem` request. It is consumed via the entity API (`table.entities.<Entity>.batchGet([...])`), and `execute()` returns a flat `Model[]`.
-
-## Features
-
-- Retrieve multiple items by their keys
-- Supports attribute projection (select only specific fields)
-- Supports consistent read
-
-## Basic Usage
-
-```typescript
-const users = await table.entities.User.batchGet([
-  { username: 'alice' },
-  { username: 'bob' },
-  { username: 'charlie' },
-]).execute();
-
-users.forEach((user) => console.log(user.username));
-```
-
-## With Attribute Projection
-
-```typescript
-const users = await table.entities.User.batchGet([{ username: 'alice' }, { username: 'bob' }])
-  .select(['username', 'name', 'followerCount'])
-  .execute();
-```
-
-## With Consistent Read
-
-```typescript
-const users = await table.entities.User.batchGet([{ username: 'alice' }, { username: 'bob' }])
-  .consistentRead()
-  .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

@@ -1,193 +0,0 @@
-/* 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',
-            ExpressionAttributeNames: {
-              '#username': 'username',
-              '#name': 'name',
-              '#followerCount': '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',
-            ExpressionAttributeNames: {
-              '#username': 'username',
-              '#name': 'name',
-            },
-            ConsistentRead: true,
-          },
-        },
-      });
-    });
-
-    test('reserved DynamoDB words like "name", "date", "status" can be projected', () => {
-      const requestItems = {
-        Users: {
-          Keys: [{ pk: 'USER#alice', sk: 'USER#alice' }],
-        },
-      };
-
-      const builder = createBatchGetBuilder<User>(requestItems, client).select(['name']);
-      const params = builder.dbParams();
-
-      expect(params.RequestItems!['Users']).toEqual({
-        Keys: [{ pk: 'USER#alice', sk: 'USER#alice' }],
-        ProjectionExpression: '#name',
-        ExpressionAttributeNames: {
-          '#name': 'name',
-        },
-      });
-    });
-  });
-});

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

@@ -1,108 +0,0 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
-import {
-  BatchGetCommand,
-  BatchGetCommandInput,
-  BatchGetCommandOutput,
-} from '@aws-sdk/lib-dynamodb';
-import { buildProjectionExpression } from '../shared';
-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 {
-      // Build the projection once (with #-placeholders so reserved words
-      // like name/date/status/type don't blow up at DynamoDB) and reuse
-      // it per-table.
-      const proj =
-        projection.length > 0 ? buildProjectionExpression(projection.map(String)) : undefined;
-
-      const enhancedRequestItems = Object.entries(requestItems).reduce(
-        (acc, [tableName, tableRequest]) => {
-          acc[tableName] = {
-            Keys: tableRequest.Keys,
-            ...(proj && {
-              ProjectionExpression: proj.ProjectionExpression,
-              ExpressionAttributeNames: proj.ExpressionAttributeNames,
-            }),
-            ...(isConsistent && { ConsistentRead: true }),
-          };
-          return acc;
-        },
-        {} as Record<string, any>
-      );
-
-      return {
-        RequestItems: enhancedRequestItems,
-      };
-    },
-
-    /**
-     * Execute the BatchGetItem command and return the items as a flat array.
-     */
-    async execute(): Promise<Model[]> {
-      const params = this.dbParams();
-      const result: BatchGetCommandOutput = await client.send(new BatchGetCommand(params));
-      logger?.log('BatchGetCommand', params, result);
-
-      if (!result.Responses) {
-        return [];
-      }
-
-      return Object.values(result.Responses).flat() as unknown as Model[];
-    },
-  };
-}

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

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

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

@@ -1,28 +0,0 @@
-/* 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 as a flat array.
-   */
-  execute(): Promise<Model[]>;
-};

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

@@ -1,204 +0,0 @@
-# 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