@ftschopp/dynatable-core 1.4.2 → 1.4.3

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

@@ -1,202 +0,0 @@
-# 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 with AWS SDK types
-- **Composable**: Chain operations fluently
-- **Idempotent**: Support for client request tokens
-- **Flexible**: Accepts both entity builder outputs and raw DynamoDB parameters
-
-## 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();
-```
-
-## Type Safety
-
-All operations are fully typed using AWS SDK types:
-
-```typescript
-import type {
-  TransactPutParams,
-  TransactUpdateParams,
-  TransactDeleteParams,
-  TransactConditionCheckParams,
-} from '@ftschopp/dynatable-core';
-
-// addPut accepts PutCommandInput from @aws-sdk/lib-dynamodb
-const putParams: TransactPutParams = {
-  TableName: 'MyTable',
-  Item: { pk: 'USER#123', sk: 'USER#123', name: 'John' },
-};
-
-// TypeScript validates all parameters at compile time
-table.transactWrite().addPut(putParams).execute();
-```
-
-### Using Entity Builders
-
-Entity builders automatically provide correctly typed parameters via `.dbParams()`:
-
-```typescript
-// The entity builder's dbParams() returns PutCommandInput
-const params = table.entities.User.put({ username: 'john' }).ifNotExists().dbParams();
-// params is typed as PutCommandInput
-
-// Pass it to the transaction builder
-table.transactWrite().addPut(params).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

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

@@ -1,288 +0,0 @@
-import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
-import { createTransactWriteBuilder } from './create-transact-write-builder';
-
-const client = new DynamoDBClient({});
-
-describe('TransactWrite Builder - Functional API', () => {
-  test('should create empty transaction', () => {
-    const params = createTransactWriteBuilder(client).dbParams();
-
-    expect(params).toEqual({
-      TransactItems: [],
-    });
-  });
-
-  test('should add single Put operation', () => {
-    const putParams = {
-      TableName: 'InstagramClone',
-      Item: {
-        pk: 'USER#alice',
-        sk: 'USER#alice',
-        username: 'alice',
-        name: 'Alice Smith',
-        followerCount: 0,
-        followingCount: 0,
-      },
-    };
-
-    const params = createTransactWriteBuilder(client).addPut(putParams).dbParams();
-
-    expect(params).toEqual({
-      TransactItems: [{ Put: putParams }],
-    });
-  });
-
-  test('should add single Update operation', () => {
-    const updateParams = {
-      TableName: 'InstagramClone',
-      Key: { pk: 'USER#alice', sk: 'USER#alice' },
-      UpdateExpression: 'ADD #followerCount :followerCount_0',
-      ExpressionAttributeNames: { '#followerCount': 'followerCount' },
-      ExpressionAttributeValues: { ':followerCount_0': 1 },
-    };
-
-    const params = createTransactWriteBuilder(client).addUpdate(updateParams).dbParams();
-
-    expect(params).toEqual({
-      TransactItems: [{ Update: updateParams }],
-    });
-  });
-
-  test('should add single Delete operation', () => {
-    const deleteParams = {
-      TableName: 'InstagramClone',
-      Key: { pk: 'USER#alice', sk: 'USER#alice' },
-    };
-
-    const params = createTransactWriteBuilder(client).addDelete(deleteParams).dbParams();
-
-    expect(params).toEqual({
-      TransactItems: [{ Delete: deleteParams }],
-    });
-  });
-
-  test('should add ConditionCheck operation', () => {
-    const conditionCheckParams = {
-      TableName: 'InstagramClone',
-      Key: { pk: 'USER#admin', sk: 'USER#admin' },
-      ConditionExpression: 'attribute_exists(#username)',
-      ExpressionAttributeNames: { '#username': 'username' },
-    };
-
-    const params = createTransactWriteBuilder(client)
-      .addConditionCheck(conditionCheckParams)
-      .dbParams();
-
-    expect(params).toEqual({
-      TransactItems: [{ ConditionCheck: conditionCheckParams }],
-    });
-  });
-
-  test('should chain multiple operations - Like a Photo', () => {
-    // Like a Photo: Create Like + Increment Photo.likesCount
-    const putLikeParams = {
-      TableName: 'InstagramClone',
-      Item: {
-        pk: 'PL#photo123',
-        sk: 'LIKE#juanca',
-        photoId: 'photo123',
-        likingUsername: 'juanca',
-        likeId: '01K16ZP43BRX67DG50SHGZ11DS',
-      },
-      ConditionExpression: '(attribute_not_exists(#PK)) AND (attribute_not_exists(#SK))',
-      ExpressionAttributeNames: { '#PK': 'pk', '#SK': 'sk' },
-    };
-
-    const updatePhotoParams = {
-      TableName: 'InstagramClone',
-      Key: { pk: 'UP#alice', sk: 'PHOTO#photo123' },
-      UpdateExpression: 'ADD #likesCount :likesCount_0',
-      ExpressionAttributeNames: { '#likesCount': 'likesCount' },
-      ExpressionAttributeValues: { ':likesCount_0': 1 },
-    };
-
-    const params = createTransactWriteBuilder(client)
-      .addPut(putLikeParams)
-      .addUpdate(updatePhotoParams)
-      .dbParams();
-
-    expect(params).toEqual({
-      TransactItems: [{ Put: putLikeParams }, { Update: updatePhotoParams }],
-    });
-    expect(params.TransactItems).toHaveLength(2);
-  });
-
-  test('should chain multiple operations - Follow a User', () => {
-    // Follow: Create Follow + Update both user counts
-    const putFollowParams = {
-      TableName: 'InstagramClone',
-      Item: {
-        pk: 'FOLLOW#alice',
-        sk: 'FOLLOW#bob',
-        followedUsername: 'alice',
-        followingUsername: 'bob',
-      },
-      ConditionExpression: '(attribute_not_exists(#PK)) AND (attribute_not_exists(#SK))',
-      ExpressionAttributeNames: { '#PK': 'pk', '#SK': 'sk' },
-    };
-
-    const updateFollowedParams = {
-      TableName: 'InstagramClone',
-      Key: { pk: 'USER#alice', sk: 'USER#alice' },
-      UpdateExpression: 'ADD #followerCount :followerCount_0',
-      ExpressionAttributeNames: { '#followerCount': 'followerCount' },
-      ExpressionAttributeValues: { ':followerCount_0': 1 },
-    };
-
-    const updateFollowingParams = {
-      TableName: 'InstagramClone',
-      Key: { pk: 'USER#bob', sk: 'USER#bob' },
-      UpdateExpression: 'ADD #followingCount :followingCount_0',
-      ExpressionAttributeNames: { '#followingCount': 'followingCount' },
-      ExpressionAttributeValues: { ':followingCount_0': 1 },
-    };
-
-    const params = createTransactWriteBuilder(client)
-      .addPut(putFollowParams)
-      .addUpdate(updateFollowedParams)
-      .addUpdate(updateFollowingParams)
-      .dbParams();
-
-    expect(params.TransactItems).toHaveLength(3);
-    expect(params.TransactItems[0]).toEqual({ Put: putFollowParams });
-    expect(params.TransactItems[1]).toEqual({ Update: updateFollowedParams });
-    expect(params.TransactItems[2]).toEqual({ Update: updateFollowingParams });
-  });
-
-  test('should chain multiple operations - Comment on Photo', () => {
-    const putCommentParams = {
-      TableName: 'InstagramClone',
-      Item: {
-        pk: 'PC#photo123',
-        sk: 'COMMENT#comment456',
-        photoId: 'photo123',
-        commentId: 'comment456',
-        commentingUsername: 'bob',
-        content: 'Great photo!',
-      },
-    };
-
-    const updatePhotoParams = {
-      TableName: 'InstagramClone',
-      Key: { pk: 'UP#alice', sk: 'PHOTO#photo123' },
-      UpdateExpression: 'ADD #commentCount :commentCount_0',
-      ExpressionAttributeNames: { '#commentCount': 'commentCount' },
-      ExpressionAttributeValues: { ':commentCount_0': 1 },
-    };
-
-    const params = createTransactWriteBuilder(client)
-      .addPut(putCommentParams)
-      .addUpdate(updatePhotoParams)
-      .dbParams();
-
-    expect(params.TransactItems).toHaveLength(2);
-    expect(params.TransactItems[0]).toEqual({ Put: putCommentParams });
-    expect(params.TransactItems[1]).toEqual({ Update: updatePhotoParams });
-  });
-
-  test('should support client request token for idempotency', () => {
-    const putParams = {
-      TableName: 'InstagramClone',
-      Item: { pk: 'USER#alice', sk: 'USER#alice', username: 'alice' },
-    };
-
-    const params = createTransactWriteBuilder(client)
-      .addPut(putParams)
-      .withClientRequestToken('my-unique-token-123')
-      .dbParams();
-
-    expect(params).toEqual({
-      TransactItems: [{ Put: putParams }],
-      ClientRequestToken: 'my-unique-token-123',
-    });
-  });
-
-  test('should preserve immutability - original builder unchanged', () => {
-    const builder1 = createTransactWriteBuilder(client);
-    const putParams = {
-      TableName: 'InstagramClone',
-      Item: { pk: 'USER#alice', sk: 'USER#alice' },
-    };
-
-    const builder2 = builder1.addPut(putParams);
-    const builder3 = builder2.withClientRequestToken('token');
-
-    // Each builder should be independent
-    expect(builder1.dbParams().TransactItems).toHaveLength(0);
-    expect(builder2.dbParams().TransactItems).toHaveLength(1);
-    expect(builder3.dbParams().ClientRequestToken).toBe('token');
-    expect(builder2.dbParams().ClientRequestToken).toBeUndefined();
-  });
-
-  test('should handle complex transaction - Delete Photo only if no engagement', () => {
-    const deletePhotoParams = {
-      TableName: 'InstagramClone',
-      Key: { pk: 'UP#alice', sk: 'PHOTO#photo123' },
-      ConditionExpression: '(#likesCount = :likesCount_0) AND (#commentCount = :commentCount_1)',
-      ExpressionAttributeNames: {
-        '#likesCount': 'likesCount',
-        '#commentCount': 'commentCount',
-      },
-      ExpressionAttributeValues: {
-        ':likesCount_0': 0,
-        ':commentCount_1': 0,
-      },
-    };
-
-    const params = createTransactWriteBuilder(client).addDelete(deletePhotoParams).dbParams();
-
-    expect(params.TransactItems).toHaveLength(1);
-    expect(params.TransactItems[0]).toEqual({ Delete: deletePhotoParams });
-  });
-
-  test('should handle max operations (100 items limit)', () => {
-    let builder = createTransactWriteBuilder(client);
-
-    // Add 100 Put operations (DynamoDB limit)
-    for (let i = 0; i < 100; i++) {
-      builder = builder.addPut({
-        TableName: 'InstagramClone',
-        Item: { pk: `USER#user${i}`, sk: `USER#user${i}` },
-      });
-    }
-
-    const params = builder.dbParams();
-    expect(params.TransactItems).toHaveLength(100);
-  });
-
-  test('should mix all operation types', () => {
-    const params = createTransactWriteBuilder(client)
-      .addPut({
-        TableName: 'InstagramClone',
-        Item: { pk: 'USER#alice', sk: 'USER#alice' },
-      })
-      .addUpdate({
-        TableName: 'InstagramClone',
-        Key: { pk: 'USER#bob', sk: 'USER#bob' },
-        UpdateExpression: 'ADD #count :val',
-        ExpressionAttributeNames: { '#count': 'followerCount' },
-        ExpressionAttributeValues: { ':val': 1 },
-      })
-      .addDelete({
-        TableName: 'InstagramClone',
-        Key: { pk: 'PHOTO#old', sk: 'PHOTO#old' },
-      })
-      .addConditionCheck({
-        TableName: 'InstagramClone',
-        Key: { pk: 'USER#admin', sk: 'USER#admin' },
-        ConditionExpression: 'attribute_exists(pk)',
-      })
-      .dbParams();
-
-    expect(params.TransactItems).toHaveLength(4);
-    expect(params.TransactItems[0]).toHaveProperty('Put');
-    expect(params.TransactItems[1]).toHaveProperty('Update');
-    expect(params.TransactItems[2]).toHaveProperty('Delete');
-    expect(params.TransactItems[3]).toHaveProperty('ConditionCheck');
-  });
-});

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

@@ -1,124 +0,0 @@
-import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
-import { TransactWriteCommand } from '@aws-sdk/lib-dynamodb';
-import {
-  TransactWriteBuilder,
-  TransactWriteState,
-  TransactPutParams,
-  TransactUpdateParams,
-  TransactDeleteParams,
-  TransactConditionCheckParams,
-} from './types';
-
-/**
- * Creates the initial state for a TransactWrite builder
- */
-const createInitialState = (client: DynamoDBClient): TransactWriteState => ({
-  client,
-  items: [],
-});
-
-/**
- * Adds a Put operation to the transaction
- */
-const addPutItem =
-  (state: TransactWriteState) =>
-  (params: TransactPutParams): TransactWriteState => ({
-    ...state,
-    items: [...state.items, { Put: params }],
-  });
-
-/**
- * Adds an Update operation to the transaction
- */
-const addUpdateItem =
-  (state: TransactWriteState) =>
-  (params: TransactUpdateParams): TransactWriteState => ({
-    ...state,
-    items: [...state.items, { Update: params }],
-  });
-
-/**
- * Adds a Delete operation to the transaction
- */
-const addDeleteItem =
-  (state: TransactWriteState) =>
-  (params: TransactDeleteParams): TransactWriteState => ({
-    ...state,
-    items: [...state.items, { Delete: params }],
-  });
-
-/**
- * Adds a ConditionCheck operation to the transaction
- */
-const addConditionCheckItem =
-  (state: TransactWriteState) =>
-  (params: TransactConditionCheckParams): TransactWriteState => ({
-    ...state,
-    items: [...state.items, { ConditionCheck: params }],
-  });
-
-/**
- * Sets the client request token for idempotency
- */
-const setClientRequestToken =
-  (state: TransactWriteState) =>
-  (token: string): TransactWriteState => ({
-    ...state,
-    clientRequestToken: token,
-  });
-
-/**
- * Converts the builder state to DynamoDB parameters
- */
-const toDbParams = (state: TransactWriteState): ReturnType<TransactWriteBuilder['dbParams']> => {
-  const params: ReturnType<TransactWriteBuilder['dbParams']> = {
-    TransactItems: [...state.items],
-  };
-
-  if (state.clientRequestToken) {
-    params.ClientRequestToken = state.clientRequestToken;
-  }
-
-  return params;
-};
-
-/**
- * Executes the transaction
- */
-const execute = async (state: TransactWriteState) => {
-  const params = toDbParams(state);
-  const command = new TransactWriteCommand(params);
-  return await state.client.send(command);
-};
-
-/**
- * Creates a builder from the current state
- */
-const createBuilder = (state: TransactWriteState): TransactWriteBuilder => ({
-  addPut: (params) => createBuilder(addPutItem(state)(params)),
-  addUpdate: (params) => createBuilder(addUpdateItem(state)(params)),
-  addDelete: (params) => createBuilder(addDeleteItem(state)(params)),
-  addConditionCheck: (params) => createBuilder(addConditionCheckItem(state)(params)),
-  withClientRequestToken: (token) => createBuilder(setClientRequestToken(state)(token)),
-  dbParams: () => toDbParams(state),
-  execute: () => execute(state),
-});
-
-/**
- * Creates a new TransactWrite builder
- *
- * @param client - DynamoDB client instance
- * @returns A TransactWriteBuilder
- *
- * @example
- * ```typescript
- * const result = await createTransactWriteBuilder(client)
- *   .addPut(putParams)
- *   .addUpdate(updateParams)
- *   .execute();
- * ```
- */
-export const createTransactWriteBuilder = (client: DynamoDBClient): TransactWriteBuilder => {
-  const initialState = createInitialState(client);
-  return createBuilder(initialState);
-};

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

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

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

@@ -1,71 +0,0 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
-import type {
-  TransactWriteCommandInput,
-  TransactWriteCommandOutput,
-  PutCommandInput,
-  UpdateCommandInput,
-  DeleteCommandInput,
-} from '@aws-sdk/lib-dynamodb';
-
-// Extract types from AWS SDK's TransactWriteCommandInput
-type TransactWriteItems = NonNullable<TransactWriteCommandInput['TransactItems']>;
-type StrictTransactPut = NonNullable<TransactWriteItems[number]['Put']>;
-type StrictTransactUpdate = NonNullable<TransactWriteItems[number]['Update']>;
-type StrictTransactDelete = NonNullable<TransactWriteItems[number]['Delete']>;
-type StrictTransactConditionCheck = NonNullable<TransactWriteItems[number]['ConditionCheck']>;
-
-/**
- * Parameters for a Put operation within a transaction
- * Accepts both regular PutCommandInput and strict transaction Put params
- */
-export type TransactPutParams = PutCommandInput | StrictTransactPut;
-
-/**
- * Parameters for an Update operation within a transaction
- * Accepts both regular UpdateCommandInput and strict transaction Update params
- */
-export type TransactUpdateParams = UpdateCommandInput | StrictTransactUpdate;
-
-/**
- * Parameters for a Delete operation within a transaction
- * Accepts both regular DeleteCommandInput and strict transaction Delete params
- */
-export type TransactDeleteParams = DeleteCommandInput | StrictTransactDelete;
-
-/**
- * Parameters for a ConditionCheck operation within a transaction
- */
-export type TransactConditionCheckParams = StrictTransactConditionCheck;
-
-/**
- * Represents a single item in a TransactWrite operation
- * Using any internally to allow flexibility between CommandInput and strict transaction types
- */
-export type TransactWriteItem =
-  | { Put: any }
-  | { Update: any }
-  | { Delete: any }
-  | { ConditionCheck: any };
-
-/**
- * State for the TransactWrite builder
- */
-export type TransactWriteState = {
-  readonly client: DynamoDBClient;
-  readonly items: readonly TransactWriteItem[];
-  readonly clientRequestToken?: string;
-};
-
-/**
- * TransactWrite builder interface
- */
-export type TransactWriteBuilder = {
-  readonly addPut: (params: TransactPutParams) => TransactWriteBuilder;
-  readonly addUpdate: (params: TransactUpdateParams) => TransactWriteBuilder;
-  readonly addDelete: (params: TransactDeleteParams) => TransactWriteBuilder;
-  readonly addConditionCheck: (params: TransactConditionCheckParams) => TransactWriteBuilder;
-  readonly withClientRequestToken: (token: string) => TransactWriteBuilder;
-  readonly dbParams: () => TransactWriteCommandInput;
-  readonly execute: () => Promise<TransactWriteCommandOutput>;
-};