@ftschopp/dynatable-core 1.0.0

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

@@ -0,0 +1,140 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { GetCommand, GetCommandInput, GetCommandOutput } from '@aws-sdk/lib-dynamodb';
+import { GetBuilder } from './types';
+import { DynamoDBLogger } from '../../utils/dynamodb-logger';
+
+/**
+ * Builds a ProjectionExpression with proper ExpressionAttributeNames
+ * to handle reserved words and special characters.
+ */
+function buildProjectionExpression(attrs: string[]): {
+  ProjectionExpression: string;
+  ExpressionAttributeNames: Record<string, string>;
+} {
+  const names: Record<string, string> = {};
+  const projectionParts: string[] = [];
+
+  attrs.forEach((attr) => {
+    // Use a placeholder for the attribute name to avoid reserved word conflicts
+    const placeholder = `#${attr}`;
+    names[placeholder] = attr;
+    projectionParts.push(placeholder);
+  });
+
+  return {
+    ProjectionExpression: projectionParts.join(', '),
+    ExpressionAttributeNames: names,
+  };
+}
+
+/**
+ * Creates a GetBuilder to retrieve an item by its key.
+ */
+export function createGetBuilder<KeyInput, Model>(
+  tableName: string,
+  key: Record<string, any>,
+  client: DynamoDBClient,
+  options?: {
+    projection?: (keyof Model)[];
+    consistentRead?: boolean;
+    returnConsumedCapacity?: 'INDEXES' | 'TOTAL' | 'NONE';
+  },
+  logger?: DynamoDBLogger
+): GetBuilder<KeyInput, Model> {
+  const projection = options?.projection ?? [];
+  const isConsistent = options?.consistentRead ?? false;
+  const consumedCapacity = options?.returnConsumedCapacity;
+
+  return {
+    /**
+     * Select only specific attributes to retrieve.
+     */
+    select(attrs) {
+      return createGetBuilder(
+        tableName,
+        key,
+        client,
+        {
+          projection: attrs,
+          consistentRead: isConsistent,
+          returnConsumedCapacity: consumedCapacity,
+        },
+        logger
+      );
+    },
+
+    /**
+     * Enable strongly consistent read.
+     */
+    consistentRead() {
+      return createGetBuilder(
+        tableName,
+        key,
+        client,
+        {
+          projection,
+          consistentRead: true,
+          returnConsumedCapacity: consumedCapacity,
+        },
+        logger
+      );
+    },
+
+    /**
+     * Configure ReturnConsumedCapacity parameter.
+     */
+    returnConsumedCapacity(mode) {
+      return createGetBuilder(
+        tableName,
+        key,
+        client,
+        {
+          projection,
+          consistentRead: isConsistent,
+          returnConsumedCapacity: mode,
+        },
+        logger
+      );
+    },
+
+    /**
+     * Build the underlying DynamoDB input parameters.
+     */
+    dbParams(): GetCommandInput {
+      const params: GetCommandInput = {
+        TableName: tableName,
+        Key: key,
+      };
+
+      // Add projection with proper ExpressionAttributeNames
+      if (projection.length > 0) {
+        const projectionExpr = buildProjectionExpression(projection as string[]);
+        params.ProjectionExpression = projectionExpr.ProjectionExpression;
+        params.ExpressionAttributeNames = projectionExpr.ExpressionAttributeNames;
+      }
+
+      // Add consistent read if enabled
+      if (isConsistent) {
+        params.ConsistentRead = true;
+      }
+
+      // Add ReturnConsumedCapacity if specified
+      if (consumedCapacity) {
+        params.ReturnConsumedCapacity = consumedCapacity;
+      }
+
+      return params;
+    },
+
+    /**
+     * Execute the GetItem command and return the item if found.
+     */
+    async execute(): Promise<Model | undefined> {
+      const params = this.dbParams();
+      const result: GetCommandOutput = await client.send(new GetCommand(params));
+      logger?.log('GetCommand', params, result);
+      return result.Item as unknown as Model | undefined;
+    },
+  };
+}

package/src/builders/get/index.ts

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

package/src/builders/get/types.ts

@@ -0,0 +1,30 @@
+import { ExecutableBuilder } from '../shared';
+
+/**
+ * Builder for DynamoDB GetItem operations.
+ * Supports projection, consistent read, and inspection of the final parameters.
+ */
+export interface GetBuilder<KeyInput, Model> extends ExecutableBuilder<Model | undefined> {
+  /**
+   * Adds a projection expression to only return specific attributes.
+   * Returns a new immutable builder.
+   */
+  select(attrs: (keyof Model)[]): GetBuilder<KeyInput, Model>;
+
+  /**
+   * Enables strongly consistent read (eventual consistency is default).
+   * Returns a new immutable builder.
+   */
+  consistentRead(): GetBuilder<KeyInput, Model>;
+
+  /**
+   * Configures the ReturnConsumedCapacity parameter.
+   * Returns a new immutable builder.
+   *
+   * @param mode - 'INDEXES' | 'TOTAL' | 'NONE'
+   * - INDEXES: Returns consumed capacity for table and indexes
+   * - TOTAL: Returns total consumed capacity
+   * - NONE: No consumed capacity data returned (default)
+   */
+  returnConsumedCapacity(mode: 'INDEXES' | 'TOTAL' | 'NONE'): GetBuilder<KeyInput, Model>;
+}

package/src/builders/index.ts

@@ -0,0 +1,14 @@
+// Shared utilities and types
+export * from './shared';
+
+// Operation builders
+export * from './get';
+export * from './put';
+export * from './query';
+export * from './scan';
+export * from './update';
+export * from './delete';
+export * from './batch-get';
+export * from './batch-write';
+export * from './transact-write';
+export * from './transact-get';

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

@@ -0,0 +1,213 @@
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { mockClient } from 'aws-sdk-client-mock';
+import { PutCommand } from '@aws-sdk/lib-dynamodb';
+import { createPutBuilder } from './create-put-builder';
+
+const ddbMock = mockClient(DynamoDBClient);
+
+describe('createPutBuilder', () => {
+  const tableName = 'test-table';
+  const client = new DynamoDBClient({});
+
+  beforeEach(() => {
+    ddbMock.reset();
+  });
+
+  describe('Basic functionality', () => {
+    it('should create a put builder with minimal config', () => {
+      const item = { id: '123', name: 'Test' };
+      const builder = createPutBuilder(tableName, item, client);
+
+      const params = builder.dbParams();
+
+      expect(params).toEqual({
+        TableName: tableName,
+        Item: item,
+      });
+    });
+
+    it('should build params with conditions', () => {
+      const item = { id: '123', name: 'Test' };
+      const builder = createPutBuilder(tableName, item, client).where((attrs, ops) =>
+        ops.eq(attrs.id, '123')
+      );
+
+      const params = builder.dbParams();
+
+      expect(params.ConditionExpression).toBe('#id = :id_0');
+      expect(params.ExpressionAttributeNames).toEqual({ '#id': 'id' });
+      expect(params.ExpressionAttributeValues).toEqual({ ':id_0': '123' });
+    });
+  });
+
+  describe('Timestamps support', () => {
+    it('should add createdAt and updatedAt when enableTimestamps is true', () => {
+      const item = { id: '123', name: 'Test' };
+      const builder = createPutBuilder(tableName, item, client, [], false, 'NONE', true);
+
+      const params = builder.dbParams();
+
+      expect(params.Item).toHaveProperty('createdAt');
+      expect(params.Item).toHaveProperty('updatedAt');
+      expect(typeof params.Item.createdAt).toBe('string');
+      expect(typeof params.Item.updatedAt).toBe('string');
+      expect(params.Item.createdAt).toBe(params.Item.updatedAt);
+    });
+
+    it('should not add timestamps when enableTimestamps is false', () => {
+      const item = { id: '123', name: 'Test' };
+      const builder = createPutBuilder(tableName, item, client, [], false, 'NONE', false);
+
+      const params = builder.dbParams();
+
+      expect(params.Item).not.toHaveProperty('createdAt');
+      expect(params.Item).not.toHaveProperty('updatedAt');
+    });
+
+    it('should preserve original item data with timestamps', () => {
+      const item = { id: '123', name: 'Test', value: 42 };
+      const builder = createPutBuilder(tableName, item, client, [], false, 'NONE', true);
+
+      const params = builder.dbParams();
+
+      expect(params.Item.id).toBe('123');
+      expect(params.Item.name).toBe('Test');
+      expect(params.Item.value).toBe(42);
+    });
+  });
+
+  describe('ifNotExists functionality', () => {
+    it('should add attribute_not_exists conditions for PK and SK', () => {
+      const item = { PK: 'user#123', SK: 'profile', name: 'Test' };
+      const builder = createPutBuilder(tableName, item, client).ifNotExists();
+
+      const params = builder.dbParams();
+
+      expect(params.ConditionExpression).toContain('attribute_not_exists(#PK)');
+      expect(params.ConditionExpression).toContain('attribute_not_exists(#SK)');
+      expect(params.ExpressionAttributeNames).toHaveProperty('#PK');
+      expect(params.ExpressionAttributeNames).toHaveProperty('#SK');
+    });
+
+    it('should handle lowercase pk and sk', () => {
+      const item = { pk: 'user#123', sk: 'profile', name: 'Test' };
+      const builder = createPutBuilder(tableName, item, client).ifNotExists();
+
+      const params = builder.dbParams();
+
+      expect(params.ConditionExpression).toContain('attribute_not_exists(#pk)');
+      expect(params.ConditionExpression).toContain('attribute_not_exists(#sk)');
+    });
+
+    it('should combine ifNotExists with other conditions', () => {
+      const item = { PK: 'user#123', SK: 'profile', name: 'Test' };
+      const builder = createPutBuilder(tableName, item, client)
+        .where((attrs, ops) => ops.eq(attrs.name, 'Test'))
+        .ifNotExists();
+
+      const params = builder.dbParams();
+
+      expect(params.ConditionExpression).toContain('attribute_not_exists(#PK)');
+      expect(params.ConditionExpression).toContain('#name = :name_0');
+    });
+  });
+
+  describe('returning functionality', () => {
+    it('should set ReturnValues to NONE by default', () => {
+      const item = { id: '123', name: 'Test' };
+      const builder = createPutBuilder(tableName, item, client);
+
+      const params = builder.dbParams();
+
+      expect(params.ReturnValues).toBeUndefined();
+    });
+
+    it('should set ReturnValues to ALL_OLD when specified', () => {
+      const item = { id: '123', name: 'Test' };
+      const builder = createPutBuilder(tableName, item, client).returning('ALL_OLD');
+
+      const params = builder.dbParams();
+
+      expect(params.ReturnValues).toBe('ALL_OLD');
+    });
+  });
+
+  describe('execute functionality', () => {
+    it('should return the new item when returnMode is NONE', async () => {
+      const item = { id: '123', name: 'Test' };
+
+      ddbMock.on(PutCommand).resolves({});
+
+      const builder = createPutBuilder(tableName, item, client);
+      const result = await builder.execute();
+
+      expect(result).toEqual(item);
+    });
+
+    it('should return the old item when returnMode is ALL_OLD and item was replaced', async () => {
+      const item = { id: '123', name: 'New Name' };
+      const oldItem = { id: '123', name: 'Old Name' };
+
+      ddbMock.on(PutCommand).resolves({
+        Attributes: oldItem,
+      });
+
+      const builder = createPutBuilder(tableName, item, client).returning('ALL_OLD');
+      const result = await builder.execute();
+
+      expect(result).toEqual(oldItem);
+    });
+
+    it('should return the new item when returnMode is ALL_OLD but no old item existed', async () => {
+      const item = { id: '123', name: 'Test' };
+
+      ddbMock.on(PutCommand).resolves({});
+
+      const builder = createPutBuilder(tableName, item, client).returning('ALL_OLD');
+      const result = await builder.execute();
+
+      expect(result).toEqual(item);
+    });
+
+    it('should return item with timestamps when timestamps are enabled', async () => {
+      const item = { id: '123', name: 'Test' };
+
+      ddbMock.on(PutCommand).resolves({});
+
+      const builder = createPutBuilder(tableName, item, client, [], false, 'NONE', true);
+      const result = await builder.execute();
+
+      expect(result).toHaveProperty('createdAt');
+      expect(result).toHaveProperty('updatedAt');
+      expect(result.id).toBe('123');
+      expect(result.name).toBe('Test');
+    });
+  });
+
+  describe('Method chaining', () => {
+    it('should allow chaining multiple methods', () => {
+      const item = { PK: 'user#123', SK: 'profile', name: 'Test' };
+      const builder = createPutBuilder(tableName, item, client)
+        .where((attrs, ops) => ops.eq(attrs.name, 'Test'))
+        .ifNotExists()
+        .returning('ALL_OLD');
+
+      const params = builder.dbParams();
+
+      expect(params.ConditionExpression).toBeTruthy();
+      expect(params.ReturnValues).toBe('ALL_OLD');
+    });
+
+    it('should preserve timestamps through chaining', () => {
+      const item = { id: '123', name: 'Test' };
+      const builder = createPutBuilder(tableName, item, client, [], false, 'NONE', true)
+        .where((attrs, ops) => ops.eq(attrs.id, '123'))
+        .returning('ALL_OLD');
+
+      const params = builder.dbParams();
+
+      expect(params.Item).toHaveProperty('createdAt');
+      expect(params.Item).toHaveProperty('updatedAt');
+    });
+  });
+});

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

@@ -0,0 +1,151 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { PutCommand } from '@aws-sdk/lib-dynamodb';
+import { buildExpression, AttrBuilder, Condition, createOpBuilder } from '../shared';
+import { PutBuilder } from './types';
+import { DynamoDBLogger } from '../../utils/dynamodb-logger';
+
+/**
+ * Utility to infer if attribute exists in the item and returns condition.
+ */
+function buildNotExistsConditions(item: any): Condition[] {
+  // Check for common key names (both uppercase and lowercase)
+  const possibleKeys = ['PK', 'SK', 'pk', 'sk'];
+  const foundKeys = possibleKeys.filter((key) => key in item);
+
+  return foundKeys.map((key) => ({
+    expression: `attribute_not_exists(#${key})`,
+    names: { [`#${key}`]: key },
+  }));
+}
+
+/**
+ * Creates a PutBuilder for an item and table.
+ */
+export function createPutBuilder<Model>(
+  tableName: string,
+  item: Model,
+  client: DynamoDBClient,
+  prevConditions: Condition[] = [],
+  shouldCheckNotExists = false,
+  returnMode: 'NONE' | 'ALL_OLD' = 'NONE',
+  enableTimestamps = false,
+  logger?: DynamoDBLogger
+): PutBuilder<Model> {
+  const conditions = [...prevConditions];
+
+  const build = (): PutBuilder<Model> => ({
+    where(fn) {
+      const attrs = new Proxy({} as AttrBuilder<Model>, {
+        get(_, prop: string) {
+          return { name: prop };
+        },
+      });
+      // Create a scoped opBuilder for this operation to avoid global state
+      const opBuilder = createOpBuilder();
+      const condition = fn(attrs, opBuilder);
+      return createPutBuilder(
+        tableName,
+        item,
+        client,
+        [...conditions, condition],
+        shouldCheckNotExists,
+        returnMode,
+        enableTimestamps,
+        logger
+      );
+    },
+
+    ifNotExists() {
+      return createPutBuilder(tableName, item, client, conditions, true, returnMode, enableTimestamps, logger);
+    },
+
+    returning(mode) {
+      return createPutBuilder(
+        tableName,
+        item,
+        client,
+        conditions,
+        shouldCheckNotExists,
+        mode,
+        enableTimestamps,
+        logger
+      );
+    },
+
+    dbParams() {
+      let finalConditions = [...conditions];
+
+      if (shouldCheckNotExists) {
+        finalConditions = [...finalConditions, ...buildNotExistsConditions(item)];
+      }
+
+      // Add timestamps if enabled
+      let finalItem = item;
+      if (enableTimestamps) {
+        const now = new Date().toISOString();
+        finalItem = {
+          ...item,
+          createdAt: now,
+          updatedAt: now,
+        } as Model;
+      }
+
+      // Build ConditionExpression from condition tree
+      let conditionExpression = '';
+      let expressionAttributeNames = {};
+      let expressionAttributeValues = {};
+
+      if (finalConditions.length > 0) {
+        // If there's only one condition, use it directly
+        // Otherwise, combine with AND
+        const combinedCondition =
+          finalConditions.length === 1 && finalConditions[0]
+            ? finalConditions[0]
+            : {
+                expression: '',
+                operator: 'AND' as const,
+                children: finalConditions,
+              };
+
+        const result = buildExpression(combinedCondition);
+        conditionExpression = result.expression;
+        expressionAttributeNames = result.names;
+        expressionAttributeValues = result.values;
+      }
+
+      const extra: any = returnMode !== 'NONE' ? { ReturnValues: returnMode } : {};
+
+      return {
+        TableName: tableName,
+        Item: finalItem,
+        ...(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 PutCommand(params));
+      logger?.log('PutCommand', params, response);
+
+      // Return the old item if returnMode is ALL_OLD and it was replaced
+      if (returnMode === 'ALL_OLD' && response.Attributes) {
+        return response.Attributes as Model;
+      }
+
+      // For NONE mode or when no old item existed, return the new item with timestamps
+      return params.Item as Model;
+    },
+  });
+
+  return build();
+}

package/src/builders/put/index.ts

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

package/src/builders/put/types.ts

@@ -0,0 +1,18 @@
+import { OperationBuilder } from '../shared';
+
+/**
+ * Builder interface for DynamoDB PutItem operations
+ */
+export interface PutBuilder<Model> extends OperationBuilder<Model> {
+  /**
+   * Adds a condition that the item must not exist (checks pk and sk)
+   */
+  ifNotExists(): PutBuilder<Model>;
+
+  /**
+   * Configures what values should be returned after the put operation.
+   * - NONE: Nothing is returned (default)
+   * - ALL_OLD: Returns the item as it was before being replaced (if it existed)
+   */
+  returning(mode: 'NONE' | 'ALL_OLD'): PutBuilder<Model>;
+}