@ftschopp/dynatable-core 1.4.2 → 1.4.3

package/src/builders/shared/types.ts

@@ -1,101 +0,0 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-/**
- * Shared types for DynamoDB builders
- */
-
-/**
- * Condition object for DynamoDB expressions
- */
-export type Condition = {
-  expression: string;
-  names?: Record<string, string>;
-  values?: Record<string, any>;
-  operator?: 'AND' | 'OR';
-  keyOperator?: 'eq' | 'ne' | 'lt' | 'lte' | 'gt' | 'gte' | 'between' | 'beginsWith';
-  isNegated?: boolean;
-  children?: Condition[];
-};
-
-/**
- * Attribute reference for building expressions
- */
-export type AttrRef = {
-  name: string;
-  path?: string;
-};
-
-/**
- * Type-safe attribute builder for models
- * Note: All properties are required (non-optional) to ensure type safety in expressions
- */
-export type AttrBuilder<Model> = {
-  [K in keyof Model]-?: AttrRef;
-};
-
-/**
- * Available operators for building conditions
- */
-export type OpBuilder = {
-  // Comparison operators
-  eq: (attr: AttrRef, value: any) => Condition;
-  ne: (attr: AttrRef, value: any) => Condition;
-  lt: (attr: AttrRef, value: any) => Condition;
-  lte: (attr: AttrRef, value: any) => Condition;
-  gt: (attr: AttrRef, value: any) => Condition;
-  gte: (attr: AttrRef, value: any) => Condition;
-  between: (attr: AttrRef, low: any, high: any) => Condition;
-
-  // String/Set operators
-  beginsWith: (attr: AttrRef, value: string) => Condition;
-  contains: (attr: AttrRef, value: any) => Condition;
-
-  // Attribute existence operators
-  exists: (attr: AttrRef) => Condition;
-  notExists: (attr: AttrRef) => Condition;
-
-  // Type checking
-  attributeType: (
-    attr: AttrRef,
-    type: 'S' | 'N' | 'B' | 'SS' | 'NS' | 'BS' | 'M' | 'L' | 'NULL' | 'BOOL'
-  ) => Condition;
-
-  // IN operator
-  in: (attr: AttrRef, values: any[]) => Condition;
-
-  // Size function
-  size: (attr: AttrRef) => SizeRef;
-
-  // Logical operators
-  and: (...conditions: Condition[]) => Condition;
-  or: (...conditions: Condition[]) => Condition;
-  not: (condition: Condition) => Condition;
-};
-
-/**
- * Reference to the size() function result for comparisons
- */
-export type SizeRef = {
-  eq: (value: number) => Condition;
-  ne: (value: number) => Condition;
-  lt: (value: number) => Condition;
-  lte: (value: number) => Condition;
-  gt: (value: number) => Condition;
-  gte: (value: number) => Condition;
-};
-
-/**
- * Base interface for executable builders
- */
-export interface ExecutableBuilder<Result> {
-  dbParams(): any;
-  execute(): Promise<Result>;
-}
-
-/**
- * Base interface for operation builders with conditions
- */
-export interface OperationBuilder<Model> {
-  where(fn: (attr: AttrBuilder<Model>, op: OpBuilder) => Condition): this;
-  dbParams(): any;
-  execute(): Promise<Model>;
-}

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

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

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

@@ -1,67 +0,0 @@
-/* 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

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

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

@@ -1,31 +0,0 @@
-/* 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[]>;
-};