@ftschopp/dynatable-core 1.0.0

package/src/builders/delete/create-delete-builder.test.ts

@@ -0,0 +1,294 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { createDeleteBuilder } from './create-delete-builder';
+
+describe('DeleteBuilder', () => {
+  const client = new DynamoDBClient({});
+  const tableName = 'TestTable';
+
+  interface TestModel {
+    pk: string;
+    sk: string;
+    name?: string;
+    age?: number;
+    score?: number;
+    followerCount?: number;
+    status?: string;
+  }
+
+  describe('Basic delete operations', () => {
+    test('should build params with just key', () => {
+      const key: Partial<TestModel> = { pk: 'USER#1', sk: 'USER#1' };
+      const params = createDeleteBuilder<TestModel>(tableName, key, client).dbParams();
+
+      expect(params.TableName).toBe(tableName);
+      expect(params.Key).toEqual(key);
+      expect(params.ConditionExpression).toBeUndefined();
+      expect(params.ExpressionAttributeNames).toBeUndefined();
+      expect(params.ExpressionAttributeValues).toBeUndefined();
+      expect(params.ReturnValues).toBeUndefined();
+    });
+
+    test('should build params with partial key', () => {
+      const key: Partial<TestModel> = { pk: 'USER#1' };
+      const params = createDeleteBuilder<TestModel>(tableName, key, client).dbParams();
+
+      expect(params.Key).toEqual({ pk: 'USER#1' });
+    });
+  });
+
+  describe('Condition expressions', () => {
+    test('should build params with single where condition', () => {
+      const key: Partial<TestModel> = { pk: 'USER#1', sk: 'USER#1' };
+      const params = createDeleteBuilder<TestModel>(tableName, key, client)
+        .where((attr, op) => op.eq(attr.status, 'inactive'))
+        .dbParams();
+
+      expect(params.TableName).toBe(tableName);
+      expect(params.Key).toEqual(key);
+      expect(params.ConditionExpression).toMatch(/#status = :status_\d+/);
+      expect(params.ExpressionAttributeNames).toEqual({
+        '#status': 'status',
+      });
+      expect(Object.values(params.ExpressionAttributeValues || {})).toContain('inactive');
+    });
+
+    test('should build params with AND condition', () => {
+      const key: Partial<TestModel> = { pk: 'USER#1', sk: 'USER#1' };
+      const params = createDeleteBuilder<TestModel>(tableName, key, client)
+        .where((attr, op) => op.and(op.eq(attr.status, 'inactive'), op.lt(attr.followerCount, 10)))
+        .dbParams();
+
+      expect(params.ConditionExpression).toMatch(
+        /\(#status = :status_\d+\) AND \(#followerCount < :followerCount_\d+\)/
+      );
+      expect(params.ExpressionAttributeNames).toEqual({
+        '#status': 'status',
+        '#followerCount': 'followerCount',
+      });
+      expect(Object.values(params.ExpressionAttributeValues || {})).toContain('inactive');
+      expect(Object.values(params.ExpressionAttributeValues || {})).toContain(10);
+    });
+
+    test('should build params with OR condition', () => {
+      const key: Partial<TestModel> = { pk: 'USER#1', sk: 'USER#1' };
+      const params = createDeleteBuilder<TestModel>(tableName, key, client)
+        .where((attr, op) => op.or(op.eq(attr.status, 'inactive'), op.eq(attr.status, 'deleted')))
+        .dbParams();
+
+      expect(params.ConditionExpression).toMatch(
+        /\(#status = :status_\d+\) OR \(#status = :status_\d+\)/
+      );
+      expect(params.ExpressionAttributeNames).toEqual({
+        '#status': 'status',
+      });
+      expect(Object.values(params.ExpressionAttributeValues || {})).toContain('inactive');
+      expect(Object.values(params.ExpressionAttributeValues || {})).toContain('deleted');
+    });
+
+    test('should build params with multiple where conditions', () => {
+      const key: Partial<TestModel> = { pk: 'USER#1', sk: 'USER#1' };
+      const params = createDeleteBuilder<TestModel>(tableName, key, client)
+        .where((attr, op) => op.eq(attr.status, 'inactive'))
+        .where((attr, op) => op.lt(attr.followerCount, 10))
+        .dbParams();
+
+      expect(params.ConditionExpression).toMatch(
+        /\(#status = :status_\d+\) AND \(#followerCount < :followerCount_\d+\)/
+      );
+      expect(params.ExpressionAttributeNames).toEqual({
+        '#status': 'status',
+        '#followerCount': 'followerCount',
+      });
+    });
+
+    test('should build params with complex nested conditions', () => {
+      const key: Partial<TestModel> = { pk: 'USER#1', sk: 'USER#1' };
+      const params = createDeleteBuilder<TestModel>(tableName, key, client)
+        .where((attr, op) =>
+          op.and(
+            op.or(op.eq(attr.status, 'inactive'), op.eq(attr.status, 'banned')),
+            op.lt(attr.followerCount, 5)
+          )
+        )
+        .dbParams();
+
+      expect(params.ConditionExpression).toMatch(/\(/);
+      expect(params.ConditionExpression).toMatch(/AND/);
+      expect(params.ConditionExpression).toMatch(/OR/);
+      expect(params.ExpressionAttributeNames).toEqual({
+        '#status': 'status',
+        '#followerCount': 'followerCount',
+      });
+      expect(Object.values(params.ExpressionAttributeValues || {})).toContain('inactive');
+      expect(Object.values(params.ExpressionAttributeValues || {})).toContain('banned');
+      expect(Object.values(params.ExpressionAttributeValues || {})).toContain(5);
+    });
+
+    test('should support comparison operators', () => {
+      const key: Partial<TestModel> = { pk: 'USER#1', sk: 'USER#1' };
+
+      // Greater than
+      const gtParams = createDeleteBuilder<TestModel>(tableName, key, client)
+        .where((attr, op) => op.gt(attr.age, 18))
+        .dbParams();
+      expect(gtParams.ConditionExpression).toMatch(/#age > :age_\d+/);
+
+      // Greater than or equal
+      const gteParams = createDeleteBuilder<TestModel>(tableName, key, client)
+        .where((attr, op) => op.gte(attr.age, 18))
+        .dbParams();
+      expect(gteParams.ConditionExpression).toMatch(/#age >= :age_\d+/);
+
+      // Less than
+      const ltParams = createDeleteBuilder<TestModel>(tableName, key, client)
+        .where((attr, op) => op.lt(attr.age, 65))
+        .dbParams();
+      expect(ltParams.ConditionExpression).toMatch(/#age < :age_\d+/);
+
+      // Less than or equal
+      const lteParams = createDeleteBuilder<TestModel>(tableName, key, client)
+        .where((attr, op) => op.lte(attr.age, 65))
+        .dbParams();
+      expect(lteParams.ConditionExpression).toMatch(/#age <= :age_\d+/);
+
+      // Not equal
+      const neParams = createDeleteBuilder<TestModel>(tableName, key, client)
+        .where((attr, op) => op.ne(attr.status, 'active'))
+        .dbParams();
+      expect(neParams.ConditionExpression).toMatch(/#status <> :status_\d+/);
+    });
+
+    test('should support BETWEEN operator', () => {
+      const key: Partial<TestModel> = { pk: 'USER#1', sk: 'USER#1' };
+      const params = createDeleteBuilder<TestModel>(tableName, key, client)
+        .where((attr, op) => op.between(attr.age, 18, 65))
+        .dbParams();
+
+      expect(params.ConditionExpression).toMatch(/#age BETWEEN :age_low_\d+ AND :age_high_\d+/);
+      expect(Object.values(params.ExpressionAttributeValues || {})).toContain(18);
+      expect(Object.values(params.ExpressionAttributeValues || {})).toContain(65);
+    });
+
+    test('should support beginsWith operator', () => {
+      const key: Partial<TestModel> = { pk: 'USER#1', sk: 'USER#1' };
+      const params = createDeleteBuilder<TestModel>(tableName, key, client)
+        .where((attr, op) => op.beginsWith(attr.name, 'John'))
+        .dbParams();
+
+      expect(params.ConditionExpression).toMatch(/begins_with\(#name, :name_\d+\)/);
+      expect(Object.values(params.ExpressionAttributeValues || {})).toContain('John');
+    });
+  });
+
+  describe('ReturnValues', () => {
+    test('should default to NONE', () => {
+      const key: Partial<TestModel> = { pk: 'USER#1', sk: 'USER#1' };
+      const params = createDeleteBuilder<TestModel>(tableName, key, client).dbParams();
+
+      expect(params.ReturnValues).toBeUndefined();
+    });
+
+    test('should support ALL_OLD', () => {
+      const key: Partial<TestModel> = { pk: 'USER#1', sk: 'USER#1' };
+      const params = createDeleteBuilder<TestModel>(tableName, key, client)
+        .returning('ALL_OLD')
+        .dbParams();
+
+      expect(params.ReturnValues).toBe('ALL_OLD');
+    });
+
+    test('should support NONE explicitly', () => {
+      const key: Partial<TestModel> = { pk: 'USER#1', sk: 'USER#1' };
+      const params = createDeleteBuilder<TestModel>(tableName, key, client)
+        .returning('NONE')
+        .dbParams();
+
+      expect(params.ReturnValues).toBeUndefined();
+    });
+  });
+
+  describe('Immutability', () => {
+    test('should create new builder instance on each method call', () => {
+      const key: Partial<TestModel> = { pk: 'USER#1', sk: 'USER#1' };
+      const builder1 = createDeleteBuilder<TestModel>(tableName, key, client);
+      const builder2 = builder1.where((attr, op) => op.eq(attr.status, 'inactive'));
+      const builder3 = builder2.returning('ALL_OLD');
+
+      expect(builder1.dbParams().ConditionExpression).toBeUndefined();
+      expect(builder1.dbParams().ReturnValues).toBeUndefined();
+
+      expect(builder2.dbParams().ConditionExpression).toMatch(/#status = :status_\d+/);
+      expect(builder2.dbParams().ReturnValues).toBeUndefined();
+
+      expect(builder3.dbParams().ConditionExpression).toMatch(/#status = :status_\d+/);
+      expect(builder3.dbParams().ReturnValues).toBe('ALL_OLD');
+    });
+  });
+
+  describe('Complex scenarios', () => {
+    test('should handle delete with all features', () => {
+      const key: Partial<TestModel> = { pk: 'USER#1', sk: 'USER#1' };
+      const params = createDeleteBuilder<TestModel>(tableName, key, client)
+        .where((attr, op) =>
+          op.and(
+            op.eq(attr.status, 'inactive'),
+            op.or(op.lt(attr.followerCount, 5), op.gt(attr.age, 365))
+          )
+        )
+        .returning('ALL_OLD')
+        .dbParams();
+
+      expect(params.TableName).toBe(tableName);
+      expect(params.Key).toEqual(key);
+      expect(params.ConditionExpression).toBeTruthy();
+      expect(params.ConditionExpression).toMatch(/AND/);
+      expect(params.ConditionExpression).toMatch(/OR/);
+      expect(params.ReturnValues).toBe('ALL_OLD');
+      expect(params.ExpressionAttributeNames).toEqual({
+        '#status': 'status',
+        '#followerCount': 'followerCount',
+        '#age': 'age',
+      });
+      expect(Object.values(params.ExpressionAttributeValues || {})).toContain('inactive');
+      expect(Object.values(params.ExpressionAttributeValues || {})).toContain(5);
+      expect(Object.values(params.ExpressionAttributeValues || {})).toContain(365);
+    });
+
+    test('should handle conditional delete based on multiple attributes', () => {
+      const key: Partial<TestModel> = { pk: 'USER#1', sk: 'USER#1' };
+      const params = createDeleteBuilder<TestModel>(tableName, key, client)
+        .where((attr, op) => op.eq(attr.status, 'inactive'))
+        .where((attr, op) => op.lt(attr.followerCount, 10))
+        .where((attr, op) => op.between(attr.age, 0, 30))
+        .returning('ALL_OLD')
+        .dbParams();
+
+      expect(params.ConditionExpression).toBeTruthy();
+      expect(params.ConditionExpression).toMatch(/AND/);
+      expect(params.ExpressionAttributeNames).toEqual({
+        '#status': 'status',
+        '#followerCount': 'followerCount',
+        '#age': 'age',
+      });
+    });
+  });
+
+  describe('Edge cases', () => {
+    test('should handle empty conditions gracefully', () => {
+      const key: Partial<TestModel> = { pk: 'USER#1', sk: 'USER#1' };
+      const params = createDeleteBuilder<TestModel>(tableName, key, client).dbParams();
+
+      expect(params.ConditionExpression).toBeUndefined();
+      expect(params.ExpressionAttributeNames).toBeUndefined();
+      expect(params.ExpressionAttributeValues).toBeUndefined();
+    });
+
+    test('should handle key with only pk', () => {
+      const key: Partial<TestModel> = { pk: 'USER#1' };
+      const params = createDeleteBuilder<TestModel>(tableName, key, client).dbParams();
+
+      expect(params.Key).toEqual({ pk: 'USER#1' });
+    });
+  });
+});

package/src/builders/delete/create-delete-builder.ts

@@ -0,0 +1,100 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { DeleteCommand } from '@aws-sdk/lib-dynamodb';
+import { buildExpression, AttrBuilder, Condition, createOpBuilder } from '../shared';
+import { DeleteBuilder } from './types';
+import { DynamoDBLogger } from '../../utils/dynamodb-logger';
+
+/**
+ * Creates a DeleteBuilder for an item key and table.
+ */
+export function createDeleteBuilder<Model>(
+  tableName: string,
+  key: Partial<Model>,
+  client: DynamoDBClient,
+  prevConditions: Condition[] = [],
+  returnMode: 'NONE' | 'ALL_OLD' = 'NONE',
+  logger?: DynamoDBLogger
+): DeleteBuilder<Model> {
+  const conditions = [...prevConditions];
+
+  const build = (): DeleteBuilder<Model> => ({
+    where(fn) {
+      const attrs = new Proxy({} as AttrBuilder<Model>, {
+        get(_, prop: string) {
+          return { name: prop };
+        },
+      });
+      const opBuilder = createOpBuilder();
+      const condition = fn(attrs, opBuilder);
+      return createDeleteBuilder(
+        tableName,
+        key,
+        client,
+        [...conditions, condition],
+        returnMode,
+        logger
+      );
+    },
+
+    returning(mode) {
+      return createDeleteBuilder(tableName, key, client, conditions, mode, logger);
+    },
+
+    dbParams() {
+      // Build ConditionExpression from condition tree
+      let conditionExpression = '';
+      let expressionAttributeNames = {};
+      let expressionAttributeValues = {};
+
+      if (conditions.length > 0) {
+        const combinedCondition =
+          conditions.length === 1 && conditions[0]
+            ? conditions[0]
+            : {
+                expression: '',
+                operator: 'AND' as const,
+                children: conditions,
+              };
+
+        const result = buildExpression(combinedCondition);
+        conditionExpression = result.expression;
+        expressionAttributeNames = result.names;
+        expressionAttributeValues = result.values;
+      }
+
+      const extra: any = returnMode !== 'NONE' ? { ReturnValues: returnMode } : {};
+
+      return {
+        TableName: tableName,
+        Key: key,
+        ...(conditionExpression && {
+          ConditionExpression: conditionExpression,
+        }),
+        ...(Object.keys(expressionAttributeNames).length && {
+          ExpressionAttributeNames: expressionAttributeNames,
+        }),
+        ...(Object.keys(expressionAttributeValues).length && {
+          ExpressionAttributeValues: expressionAttributeValues,
+        }),
+        ...extra,
+      };
+    },
+
+    async execute() {
+      const params = build().dbParams();
+      const response = await client.send(new DeleteCommand(params));
+      logger?.log('DeleteCommand', params, response);
+
+      // Return the deleted item if returnMode is ALL_OLD
+      if (returnMode === 'ALL_OLD' && response.Attributes) {
+        return response.Attributes as Model;
+      }
+
+      // For NONE mode, return the key as a fallback
+      return key as Model;
+    },
+  });
+
+  return build();
+}

package/src/builders/delete/index.ts

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

package/src/builders/delete/types.ts

@@ -0,0 +1,11 @@
+import { OperationBuilder } from '../shared';
+
+/**
+ * Builder interface for DynamoDB DeleteItem operations
+ */
+export interface DeleteBuilder<Model> extends OperationBuilder<Model> {
+  /**
+   * Configures what values should be returned after the delete operation
+   */
+  returning(mode: 'NONE' | 'ALL_OLD'): DeleteBuilder<Model>;
+}

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

@@ -0,0 +1,272 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { GetCommand } from '@aws-sdk/lib-dynamodb';
+import { createGetBuilder } from './create-get-builder';
+import { mockClient } from 'aws-sdk-client-mock';
+
+const ddbMock = mockClient(DynamoDBClient);
+
+type TestUser = {
+  username: string;
+  email: string;
+  name: string;
+  status: string;
+  age: number;
+};
+
+describe('GetBuilder', () => {
+  let client: DynamoDBClient;
+
+  beforeEach(() => {
+    ddbMock.reset();
+    client = new DynamoDBClient({});
+  });
+
+  describe('ProjectionExpression with ExpressionAttributeNames', () => {
+    it('should use ExpressionAttributeNames for simple attributes', () => {
+      const builder = createGetBuilder<any, TestUser>(
+        'TestTable',
+        { PK: 'USER#alice', SK: 'USER#alice' },
+        client
+      );
+
+      const params = builder.select(['username', 'email']).dbParams();
+
+      expect(params.ProjectionExpression).toBe('#username, #email');
+      expect(params.ExpressionAttributeNames).toEqual({
+        '#username': 'username',
+        '#email': 'email',
+      });
+    });
+
+    it('should handle reserved words correctly', () => {
+      const builder = createGetBuilder<any, TestUser>(
+        'TestTable',
+        { PK: 'USER#alice', SK: 'USER#alice' },
+        client
+      );
+
+      // 'name' and 'status' are DynamoDB reserved words
+      const params = builder.select(['name', 'status']).dbParams();
+
+      expect(params.ProjectionExpression).toBe('#name, #status');
+      expect(params.ExpressionAttributeNames).toEqual({
+        '#name': 'name',
+        '#status': 'status',
+      });
+    });
+
+    it('should work with mixed reserved and non-reserved words', () => {
+      const builder = createGetBuilder<any, TestUser>(
+        'TestTable',
+        { PK: 'USER#alice', SK: 'USER#alice' },
+        client
+      );
+
+      const params = builder.select(['username', 'name', 'status', 'email']).dbParams();
+
+      expect(params.ProjectionExpression).toBe('#username, #name, #status, #email');
+      expect(params.ExpressionAttributeNames).toEqual({
+        '#username': 'username',
+        '#name': 'name',
+        '#status': 'status',
+        '#email': 'email',
+      });
+    });
+
+    it('should not add ExpressionAttributeNames when no projection', () => {
+      const builder = createGetBuilder<any, TestUser>(
+        'TestTable',
+        { PK: 'USER#alice', SK: 'USER#alice' },
+        client
+      );
+
+      const params = builder.dbParams();
+
+      expect(params.ProjectionExpression).toBeUndefined();
+      expect(params.ExpressionAttributeNames).toBeUndefined();
+    });
+  });
+
+  describe('returnConsumedCapacity()', () => {
+    it('should add ReturnConsumedCapacity with TOTAL', () => {
+      const builder = createGetBuilder<any, TestUser>(
+        'TestTable',
+        { PK: 'USER#alice', SK: 'USER#alice' },
+        client
+      );
+
+      const params = builder.returnConsumedCapacity('TOTAL').dbParams();
+
+      expect(params.ReturnConsumedCapacity).toBe('TOTAL');
+    });
+
+    it('should add ReturnConsumedCapacity with INDEXES', () => {
+      const builder = createGetBuilder<any, TestUser>(
+        'TestTable',
+        { PK: 'USER#alice', SK: 'USER#alice' },
+        client
+      );
+
+      const params = builder.returnConsumedCapacity('INDEXES').dbParams();
+
+      expect(params.ReturnConsumedCapacity).toBe('INDEXES');
+    });
+
+    it('should add ReturnConsumedCapacity with NONE', () => {
+      const builder = createGetBuilder<any, TestUser>(
+        'TestTable',
+        { PK: 'USER#alice', SK: 'USER#alice' },
+        client
+      );
+
+      const params = builder.returnConsumedCapacity('NONE').dbParams();
+
+      expect(params.ReturnConsumedCapacity).toBe('NONE');
+    });
+
+    it('should not add ReturnConsumedCapacity when not specified', () => {
+      const builder = createGetBuilder<any, TestUser>(
+        'TestTable',
+        { PK: 'USER#alice', SK: 'USER#alice' },
+        client
+      );
+
+      const params = builder.dbParams();
+
+      expect(params.ReturnConsumedCapacity).toBeUndefined();
+    });
+  });
+
+  describe('Method chaining with immutability', () => {
+    it('should chain select() and returnConsumedCapacity()', () => {
+      const builder = createGetBuilder<any, TestUser>(
+        'TestTable',
+        { PK: 'USER#alice', SK: 'USER#alice' },
+        client
+      );
+
+      const params = builder
+        .select(['username', 'email'])
+        .returnConsumedCapacity('TOTAL')
+        .dbParams();
+
+      expect(params.ProjectionExpression).toBe('#username, #email');
+      expect(params.ExpressionAttributeNames).toEqual({
+        '#username': 'username',
+        '#email': 'email',
+      });
+      expect(params.ReturnConsumedCapacity).toBe('TOTAL');
+    });
+
+    it('should chain consistentRead() and returnConsumedCapacity()', () => {
+      const builder = createGetBuilder<any, TestUser>(
+        'TestTable',
+        { PK: 'USER#alice', SK: 'USER#alice' },
+        client
+      );
+
+      const params = builder.consistentRead().returnConsumedCapacity('INDEXES').dbParams();
+
+      expect(params.ConsistentRead).toBe(true);
+      expect(params.ReturnConsumedCapacity).toBe('INDEXES');
+    });
+
+    it('should chain all methods together', () => {
+      const builder = createGetBuilder<any, TestUser>(
+        'TestTable',
+        { PK: 'USER#alice', SK: 'USER#alice' },
+        client
+      );
+
+      const params = builder
+        .select(['name', 'status'])
+        .consistentRead()
+        .returnConsumedCapacity('TOTAL')
+        .dbParams();
+
+      expect(params.ProjectionExpression).toBe('#name, #status');
+      expect(params.ExpressionAttributeNames).toEqual({
+        '#name': 'name',
+        '#status': 'status',
+      });
+      expect(params.ConsistentRead).toBe(true);
+      expect(params.ReturnConsumedCapacity).toBe('TOTAL');
+    });
+
+    it('should maintain immutability - original builder unchanged', () => {
+      const builder = createGetBuilder<any, TestUser>(
+        'TestTable',
+        { PK: 'USER#alice', SK: 'USER#alice' },
+        client
+      );
+
+      const builder2 = builder.select(['username']);
+      const builder3 = builder2.returnConsumedCapacity('TOTAL');
+
+      // Original builder should not have projection
+      const params1 = builder.dbParams();
+      expect(params1.ProjectionExpression).toBeUndefined();
+      expect(params1.ReturnConsumedCapacity).toBeUndefined();
+
+      // Builder2 should have projection but not returnConsumedCapacity
+      const params2 = builder2.dbParams();
+      expect(params2.ProjectionExpression).toBe('#username');
+      expect(params2.ReturnConsumedCapacity).toBeUndefined();
+
+      // Builder3 should have both
+      const params3 = builder3.dbParams();
+      expect(params3.ProjectionExpression).toBe('#username');
+      expect(params3.ReturnConsumedCapacity).toBe('TOTAL');
+    });
+  });
+
+  describe('execute()', () => {
+    it('should send GetCommand with correct parameters', async () => {
+      ddbMock.on(GetCommand).resolves({
+        Item: { username: 'alice', email: 'alice@example.com' },
+      });
+
+      const builder = createGetBuilder<any, TestUser>(
+        'TestTable',
+        { PK: 'USER#alice', SK: 'USER#alice' },
+        client
+      );
+
+      const result = await builder
+        .select(['username', 'email'])
+        .returnConsumedCapacity('TOTAL')
+        .execute();
+
+      expect(result).toEqual({ username: 'alice', email: 'alice@example.com' });
+
+      // Verify the command was called with correct params
+      const calls = ddbMock.commandCalls(GetCommand);
+      expect(calls).toHaveLength(1);
+      expect(calls[0]?.args[0]?.input).toMatchObject({
+        TableName: 'TestTable',
+        Key: { PK: 'USER#alice', SK: 'USER#alice' },
+        ProjectionExpression: '#username, #email',
+        ExpressionAttributeNames: {
+          '#username': 'username',
+          '#email': 'email',
+        },
+        ReturnConsumedCapacity: 'TOTAL',
+      });
+    });
+
+    it('should return undefined when item not found', async () => {
+      ddbMock.on(GetCommand).resolves({});
+
+      const builder = createGetBuilder<any, TestUser>(
+        'TestTable',
+        { PK: 'USER#notfound', SK: 'USER#notfound' },
+        client
+      );
+
+      const result = await builder.execute();
+
+      expect(result).toBeUndefined();
+    });
+  });
+});