@ftschopp/dynatable-core 1.0.0

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

@@ -0,0 +1,167 @@
+# TransactGet - Atomic Multi-Item Reads
+
+TransactGet provides atomic multi-item read operations in DynamoDB. Get multiple items with snapshot isolation.
+
+## Features
+
+- **Functional API**: Immutable builders using pure functions
+- **Type-safe**: Full TypeScript support
+- **Atomic**: Snapshot isolation across items
+- **Composable**: Chain operations fluently
+
+## Usage
+
+### Basic Example
+
+```typescript
+import { createTransactGetBuilder } from '@repo/core';
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+
+const client = new DynamoDBClient({});
+
+const [item1, item2] = await createTransactGetBuilder(client)
+  .addGet(getParams1)
+  .addGet(getParams2)
+  .execute();
+```
+
+### With Table API
+
+```typescript
+const table = new Table({
+  name: 'MyTable',
+  client: new DynamoDBClient({}),
+  schema: MySchema,
+});
+
+// Get user and photo atomically
+const [user, photo] = await table
+  .transactGet()
+  .addGet(table.entities.User.get({ username: 'alice' }).dbParams())
+  .addGet(
+    table.entities.Photo.get({
+      username: 'alice',
+      photoId: '123',
+    }).dbParams()
+  )
+  .execute();
+```
+
+## Real-World Examples
+
+### Get User + Photo + Comment
+
+```typescript
+const [user, photo, comment] = await table
+  .transactGet()
+  .addGet(table.entities.User.get({ username: 'alice' }).dbParams())
+  .addGet(
+    table.entities.Photo.get({
+      username: 'alice',
+      photoId: '123',
+    }).dbParams()
+  )
+  .addGet(
+    table.entities.Comment.get({
+      photoId: '123',
+      commentId: '456',
+    }).dbParams()
+  )
+  .execute();
+```
+
+### Verify Follow Relationship
+
+```typescript
+// Get follow relationship and both users atomically
+const [follow, follower, followed] = await table
+  .transactGet()
+  .addGet(
+    table.entities.Follow.get({
+      followedUsername: 'alice',
+      followingUsername: 'bob',
+    }).dbParams()
+  )
+  .addGet(table.entities.User.get({ username: 'bob' }).dbParams())
+  .addGet(table.entities.User.get({ username: 'alice' }).dbParams())
+  .execute();
+
+// Verify counters match
+console.log(follower.followingCount); // Includes alice
+console.log(followed.followerCount); // Includes bob
+```
+
+### Get Photo with Engagement
+
+```typescript
+const [photo, like, comment] = await table
+  .transactGet()
+  .addGet(
+    table.entities.Photo.get({
+      username: 'alice',
+      photoId: '123',
+    }).dbParams()
+  )
+  .addGet(
+    table.entities.Like.get({
+      photoId: '123',
+      likingUsername: 'bob',
+    }).dbParams()
+  )
+  .addGet(
+    table.entities.Comment.get({
+      photoId: '123',
+      commentId: '456',
+    }).dbParams()
+  )
+  .execute();
+```
+
+## With Projections
+
+```typescript
+const [user] = await table
+  .transactGet()
+  .addGet({
+    TableName: 'MyTable',
+    Key: { pk: 'USER#alice', sk: 'USER#alice' },
+    ProjectionExpression: 'username, name, followerCount',
+    ExpressionAttributeNames: {
+      '#username': 'username',
+      '#name': 'name',
+      '#followerCount': 'followerCount',
+    },
+  })
+  .execute();
+```
+
+## Functional Design
+
+The builder is immutable - each method returns a new instance:
+
+```typescript
+const builder1 = table.transactGet();
+const builder2 = builder1.addGet(params1);
+const builder3 = builder2.addGet(params2);
+
+builder1.dbParams().TransactItems.length; // 0
+builder2.dbParams().TransactItems.length; // 1
+builder3.dbParams().TransactItems.length; // 2
+```
+
+## Return Value
+
+`execute()` returns an array of items in the same order as the `addGet()` calls:
+
+```typescript
+const [user, photo, comment] = await builder.execute();
+```
+
+If an item doesn't exist, the corresponding array element will be `undefined`.
+
+## Limitations
+
+- Maximum **25 items** per transaction
+- Maximum **4 MB** total size
+- Single table only
+- Provides snapshot isolation (consistent reads across items)

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

@@ -0,0 +1,239 @@
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { createTransactGetBuilder } from './create-transact-get-builder';
+
+const client = new DynamoDBClient({});
+
+describe('TransactGet Builder - Functional API', () => {
+  test('should create empty transaction', () => {
+    const params = createTransactGetBuilder(client).dbParams();
+
+    expect(params).toEqual({
+      TransactItems: [],
+    });
+  });
+
+  test('should add single Get operation', () => {
+    const getParams = {
+      TableName: 'InstagramClone',
+      Key: {
+        pk: 'USER#alice',
+        sk: 'USER#alice',
+      },
+    };
+
+    const params = createTransactGetBuilder(client).addGet(getParams).dbParams();
+
+    expect(params).toEqual({
+      TransactItems: [{ Get: getParams }],
+    });
+  });
+
+  test('should chain multiple Get operations', () => {
+    const getUserParams = {
+      TableName: 'InstagramClone',
+      Key: { pk: 'USER#alice', sk: 'USER#alice' },
+    };
+
+    const getPhotoParams = {
+      TableName: 'InstagramClone',
+      Key: { pk: 'UP#alice', sk: 'PHOTO#photo123' },
+    };
+
+    const params = createTransactGetBuilder(client)
+      .addGet(getUserParams)
+      .addGet(getPhotoParams)
+      .dbParams();
+
+    expect(params).toEqual({
+      TransactItems: [{ Get: getUserParams }, { Get: getPhotoParams }],
+    });
+    expect(params.TransactItems).toHaveLength(2);
+  });
+
+  test('should get User + Photo + Comment atomically', () => {
+    const getUserParams = {
+      TableName: 'InstagramClone',
+      Key: { pk: 'USER#alice', sk: 'USER#alice' },
+    };
+
+    const getPhotoParams = {
+      TableName: 'InstagramClone',
+      Key: { pk: 'UP#alice', sk: 'PHOTO#photo123' },
+    };
+
+    const getCommentParams = {
+      TableName: 'InstagramClone',
+      Key: { pk: 'PC#photo123', sk: 'COMMENT#comment456' },
+    };
+
+    const params = createTransactGetBuilder(client)
+      .addGet(getUserParams)
+      .addGet(getPhotoParams)
+      .addGet(getCommentParams)
+      .dbParams();
+
+    expect(params.TransactItems).toHaveLength(3);
+    expect(params.TransactItems[0]).toEqual({ Get: getUserParams });
+    expect(params.TransactItems[1]).toEqual({ Get: getPhotoParams });
+    expect(params.TransactItems[2]).toEqual({ Get: getCommentParams });
+  });
+
+  test('should support projection expressions', () => {
+    const getParams = {
+      TableName: 'InstagramClone',
+      Key: { pk: 'USER#alice', sk: 'USER#alice' },
+      ProjectionExpression: 'username, name, followerCount',
+      ExpressionAttributeNames: {
+        '#username': 'username',
+        '#name': 'name',
+        '#followerCount': 'followerCount',
+      },
+    };
+
+    const params = createTransactGetBuilder(client).addGet(getParams).dbParams();
+
+    expect(params.TransactItems[0]?.Get).toEqual(getParams);
+    expect(params.TransactItems[0]?.Get.ProjectionExpression).toBe('username, name, followerCount');
+  });
+
+  test('should get Follow relationship + both Users', () => {
+    const getFollowParams = {
+      TableName: 'InstagramClone',
+      Key: { pk: 'FOLLOW#alice', sk: 'FOLLOW#bob' },
+    };
+
+    const getFollowerParams = {
+      TableName: 'InstagramClone',
+      Key: { pk: 'USER#bob', sk: 'USER#bob' },
+    };
+
+    const getFollowedParams = {
+      TableName: 'InstagramClone',
+      Key: { pk: 'USER#alice', sk: 'USER#alice' },
+    };
+
+    const params = createTransactGetBuilder(client)
+      .addGet(getFollowParams)
+      .addGet(getFollowerParams)
+      .addGet(getFollowedParams)
+      .dbParams();
+
+    expect(params.TransactItems).toHaveLength(3);
+  });
+
+  test('should preserve immutability - original builder unchanged', () => {
+    const builder1 = createTransactGetBuilder(client);
+    const getParams1 = {
+      TableName: 'InstagramClone',
+      Key: { pk: 'USER#alice', sk: 'USER#alice' },
+    };
+    const getParams2 = {
+      TableName: 'InstagramClone',
+      Key: { pk: 'USER#bob', sk: 'USER#bob' },
+    };
+
+    const builder2 = builder1.addGet(getParams1);
+    const builder3 = builder2.addGet(getParams2);
+
+    // Each builder should be independent
+    expect(builder1.dbParams().TransactItems).toHaveLength(0);
+    expect(builder2.dbParams().TransactItems).toHaveLength(1);
+    expect(builder3.dbParams().TransactItems).toHaveLength(2);
+  });
+
+  test('should handle max operations (25 items limit)', () => {
+    let builder = createTransactGetBuilder(client);
+
+    // Add 25 Get operations (DynamoDB limit for TransactGet)
+    for (let i = 0; i < 25; i++) {
+      builder = builder.addGet({
+        TableName: 'InstagramClone',
+        Key: { pk: `USER#user${i}`, sk: `USER#user${i}` },
+      });
+    }
+
+    const params = builder.dbParams();
+    expect((params.TransactItems as any).length).toBe(25);
+  });
+
+  test('should get multiple Likes for a Photo', () => {
+    const params = createTransactGetBuilder(client)
+      .addGet({
+        TableName: 'InstagramClone',
+        Key: { pk: 'PL#photo123', sk: 'LIKE#alice' },
+      })
+      .addGet({
+        TableName: 'InstagramClone',
+        Key: { pk: 'PL#photo123', sk: 'LIKE#bob' },
+      })
+      .addGet({
+        TableName: 'InstagramClone',
+        Key: { pk: 'PL#photo123', sk: 'LIKE#charlie' },
+      })
+      .dbParams();
+
+    expect(params.TransactItems).toHaveLength(3);
+    expect(params.TransactItems.every((item: any) => item.Get.Key.pk === 'PL#photo123')).toBe(true);
+  });
+
+  test('should get Photo + its Comments', () => {
+    const params = createTransactGetBuilder(client)
+      .addGet({
+        TableName: 'InstagramClone',
+        Key: { pk: 'UP#alice', sk: 'PHOTO#photo123' },
+      })
+      .addGet({
+        TableName: 'InstagramClone',
+        Key: { pk: 'PC#photo123', sk: 'COMMENT#comment1' },
+      })
+      .addGet({
+        TableName: 'InstagramClone',
+        Key: { pk: 'PC#photo123', sk: 'COMMENT#comment2' },
+      })
+      .dbParams();
+
+    expect(params.TransactItems).toHaveLength(3);
+  });
+
+  test('should build complex cross-entity read', () => {
+    // Get User + their Photo + Like on that photo + Comment on that photo
+    const params = createTransactGetBuilder(client)
+      .addGet({
+        TableName: 'InstagramClone',
+        Key: { pk: 'USER#alice', sk: 'USER#alice' },
+      })
+      .addGet({
+        TableName: 'InstagramClone',
+        Key: { pk: 'UP#alice', sk: 'PHOTO#photo123' },
+      })
+      .addGet({
+        TableName: 'InstagramClone',
+        Key: { pk: 'PL#photo123', sk: 'LIKE#bob' },
+      })
+      .addGet({
+        TableName: 'InstagramClone',
+        Key: { pk: 'PC#photo123', sk: 'COMMENT#comment456' },
+      })
+      .dbParams();
+
+    expect(params.TransactItems).toHaveLength(4);
+
+    // Verify each entity type
+    expect(params.TransactItems[0]?.Get.Key).toEqual({
+      pk: 'USER#alice',
+      sk: 'USER#alice',
+    });
+    expect(params.TransactItems[1]?.Get.Key).toEqual({
+      pk: 'UP#alice',
+      sk: 'PHOTO#photo123',
+    });
+    expect(params.TransactItems[2]?.Get.Key).toEqual({
+      pk: 'PL#photo123',
+      sk: 'LIKE#bob',
+    });
+    expect(params.TransactItems[3]?.Get.Key).toEqual({
+      pk: 'PC#photo123',
+      sk: 'COMMENT#comment456',
+    });
+  });
+});

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

@@ -0,0 +1,67 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { TransactGetCommand } from '@aws-sdk/lib-dynamodb';
+import { TransactGetBuilder, TransactGetState } from './types';
+
+/**
+ * Creates the initial state for a TransactGet builder
+ */
+const createInitialState = (client: DynamoDBClient): TransactGetState => ({
+  client,
+  items: [],
+});
+
+/**
+ * Adds a Get operation to the transaction
+ */
+const addGetItem =
+  (state: TransactGetState) =>
+  (params: any): TransactGetState => ({
+    ...state,
+    items: [...state.items, { Get: params }],
+  });
+
+/**
+ * Converts the builder state to DynamoDB parameters
+ */
+const toDbParams = (state: TransactGetState) => ({
+  TransactItems: [...state.items] as any,
+});
+
+/**
+ * Executes the transaction and returns the items
+ */
+const execute = async (state: TransactGetState): Promise<any[]> => {
+  const params = toDbParams(state);
+  const command = new TransactGetCommand(params);
+  const response = await state.client.send(command);
+  return response.Responses?.map((r: any) => r.Item) || [];
+};
+
+/**
+ * Creates a builder from the current state
+ */
+const createBuilder = (state: TransactGetState): TransactGetBuilder => ({
+  addGet: (params: any) => createBuilder(addGetItem(state)(params)),
+  dbParams: () => toDbParams(state),
+  execute: () => execute(state),
+});
+
+/**
+ * Creates a new TransactGet builder
+ *
+ * @param client - DynamoDB client instance
+ * @returns A TransactGetBuilder
+ *
+ * @example
+ * ```typescript
+ * const [user, photo] = await createTransactGetBuilder(client)
+ *   .addGet(getUserParams)
+ *   .addGet(getPhotoParams)
+ *   .execute();
+ * ```
+ */
+export const createTransactGetBuilder = (client: DynamoDBClient): TransactGetBuilder => {
+  const initialState = createInitialState(client);
+  return createBuilder(initialState);
+};

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

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

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

@@ -0,0 +1,31 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+
+/**
+ * Represents a single Get operation in a TransactGet
+ */
+export type TransactGetItem = {
+  Get: {
+    TableName: string;
+    Key: Record<string, any>;
+    ProjectionExpression?: string;
+    ExpressionAttributeNames?: Record<string, string>;
+  };
+};
+
+/**
+ * State for the TransactGet builder
+ */
+export type TransactGetState = {
+  readonly client: DynamoDBClient;
+  readonly items: readonly TransactGetItem[];
+};
+
+/**
+ * TransactGet builder interface
+ */
+export type TransactGetBuilder = {
+  readonly addGet: (params: any) => TransactGetBuilder;
+  readonly dbParams: () => any;
+  readonly execute: () => Promise<any[]>;
+};

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

@@ -0,0 +1,166 @@
+# TransactWrite - Atomic Multi-Item Writes
+
+TransactWrite provides atomic multi-item write operations in DynamoDB. All operations in a transaction either succeed together or fail together.
+
+## Features
+
+- **Functional API**: Immutable builders using pure functions
+- **Type-safe**: Full TypeScript support
+- **Composable**: Chain operations fluently
+- **Idempotent**: Support for client request tokens
+
+## Usage
+
+### Basic Example
+
+```typescript
+import { createTransactWriteBuilder } from '@repo/core';
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+
+const client = new DynamoDBClient({});
+
+await createTransactWriteBuilder(client).addPut(putParams).addUpdate(updateParams).execute();
+```
+
+### With Table API
+
+```typescript
+const table = new Table({
+  name: 'MyTable',
+  client: new DynamoDBClient({}),
+  schema: MySchema,
+});
+
+// Like a photo atomically
+await table
+  .transactWrite()
+  .addPut(
+    table.entities.Like.put({
+      photoId: '123',
+      likingUsername: 'alice',
+    })
+      .ifNotExists()
+      .dbParams()
+  )
+  .addUpdate(
+    table.entities.Photo.update({
+      username: 'bob',
+      photoId: '123',
+    })
+      .add('likesCount', 1)
+      .dbParams()
+  )
+  .execute();
+```
+
+## Real-World Examples
+
+### Follow a User
+
+```typescript
+await table
+  .transactWrite()
+  .addPut(
+    table.entities.Follow.put({
+      followedUsername: 'alice',
+      followingUsername: 'bob',
+    })
+      .ifNotExists()
+      .dbParams()
+  )
+  .addUpdate(table.entities.User.update({ username: 'alice' }).add('followerCount', 1).dbParams())
+  .addUpdate(table.entities.User.update({ username: 'bob' }).add('followingCount', 1).dbParams())
+  .execute();
+```
+
+### Comment on Photo
+
+```typescript
+await table
+  .transactWrite()
+  .addPut(
+    table.entities.Comment.put({
+      photoId: '123',
+      commentingUsername: 'charlie',
+      content: 'Great photo!',
+    }).dbParams()
+  )
+  .addUpdate(
+    table.entities.Photo.update({
+      username: 'alice',
+      photoId: '123',
+    })
+      .add('commentCount', 1)
+      .dbParams()
+  )
+  .execute();
+```
+
+### Delete with Safety Check
+
+```typescript
+// Only delete if photo has no engagement
+await table
+  .transactWrite()
+  .addDelete(
+    table.entities.Photo.delete({
+      username: 'alice',
+      photoId: '123',
+    })
+      .where((attr, op) => op.and(op.eq(attr.likesCount, 0), op.eq(attr.commentCount, 0)))
+      .dbParams()
+  )
+  .execute();
+```
+
+### Condition Check
+
+```typescript
+// Create user only if admin exists
+await table
+  .transactWrite()
+  .addPut(
+    table.entities.User.put({
+      username: 'newuser',
+      name: 'New User',
+    })
+      .ifNotExists()
+      .dbParams()
+  )
+  .addConditionCheck({
+    TableName: 'MyTable',
+    Key: { pk: 'USER#admin', sk: 'USER#admin' },
+    ConditionExpression: 'attribute_exists(#pk)',
+    ExpressionAttributeNames: { '#pk': 'pk' },
+  })
+  .execute();
+```
+
+## Idempotency
+
+Use client request tokens for idempotent operations:
+
+```typescript
+await table.transactWrite().addPut(params).withClientRequestToken('unique-id-12345').execute();
+```
+
+## Functional Design
+
+The builder is immutable - each method returns a new instance:
+
+```typescript
+const builder1 = table.transactWrite();
+const builder2 = builder1.addPut(params1);
+const builder3 = builder2.addPut(params2);
+
+builder1.dbParams().TransactItems.length; // 0
+builder2.dbParams().TransactItems.length; // 1
+builder3.dbParams().TransactItems.length; // 2
+```
+
+## Limitations
+
+- Maximum **100 items** per transaction
+- Maximum **4 MB** total size
+- Single table only
+- May fail with `TransactionCanceledException` if conditions fail