@ftschopp/dynatable-core 1.0.0

package/src/table.ts

@@ -0,0 +1,109 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import {
+  InferKeyInput,
+  InferModelFromSchema,
+  InferInputFromSchema,
+  SchemaDefinition,
+} from './core/types';
+import { createEntityAPI, EntityAPI } from './entity';
+import { createTransactWriteBuilder, TransactWriteBuilder } from './builders/transact-write';
+import { createTransactGetBuilder, TransactGetBuilder } from './builders/transact-get';
+import { DynamoDBLogger } from './utils/dynamodb-logger';
+
+/**
+ * Configuration options for the Table instance
+ */
+export type TableConfig<S extends SchemaDefinition> = {
+  /** The DynamoDB table name */
+  name: string;
+  /** AWS DynamoDB client instance */
+  client: DynamoDBClient;
+  /** Optional logger instance for DynamoDB operations */
+  logger?: DynamoDBLogger;
+  /** The schema definition for all models in the table */
+  schema: S;
+};
+
+/**
+ * Internal helper type to infer all entity APIs from schema definition
+ */
+type EntityMap<S extends SchemaDefinition> = {
+  [K in keyof S['models']]: EntityAPI<
+    InferModelFromSchema<S, K>,
+    InferInputFromSchema<S, K>,
+    InferKeyInput<S['models'][K]>
+  >;
+};
+
+/**
+ * Represents a typed DynamoDB Table with entity APIs
+ *
+ * Provides access to all entity operations (get, put, delete, etc.)
+ * via `table.entities.<EntityName>`.
+ */
+export class Table<S extends SchemaDefinition> {
+  /** Generated entity APIs */
+  public readonly entities: EntityMap<S>;
+
+  /** DynamoDB client */
+  private readonly client: DynamoDBClient;
+
+  constructor(config: TableConfig<S>) {
+    const { client, schema, logger, name: tableName } = config;
+
+    this.client = client;
+
+    const rawEntities: Record<string, any> = {};
+
+    for (const modelName in schema.models) {
+      const model = schema.models[modelName];
+      if (!model) {
+        throw new Error(`Model '${modelName}' is missing in schema`);
+      }
+
+      rawEntities[modelName] = createEntityAPI(tableName, modelName, model, client, {
+        logger,
+        timestamps: schema.params?.timestamps ?? false,
+      });
+    }
+
+    this.entities = rawEntities as EntityMap<S>;
+  }
+
+  /**
+   * Creates a new TransactWrite builder for atomic multi-item write operations
+   *
+   * @returns A TransactWriteBuilder instance
+   *
+   * @example
+   * ```typescript
+   * // Like a photo atomically
+   * await table.transactWrite()
+   *   .addPut(table.entities.Like.put({ photoId: "123", likingUsername: "alice" }).dbParams())
+   *   .addUpdate(table.entities.Photo.update({ username: "bob", photoId: "123" }).add("likesCount", 1).dbParams())
+   *   .execute();
+   * ```
+   */
+  transactWrite(): TransactWriteBuilder {
+    return createTransactWriteBuilder(this.client);
+  }
+
+  /**
+   * Creates a new TransactGet builder for atomic multi-item read operations
+   *
+   * @returns A TransactGetBuilder instance
+   *
+   * @example
+   * ```typescript
+   * // 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();
+   * ```
+   */
+  transactGet(): TransactGetBuilder {
+    return createTransactGetBuilder(this.client);
+  }
+}

package/src/utils/dynamodb-logger.test.ts

@@ -0,0 +1,246 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { createDynamoDBLogger } from './dynamodb-logger';
+
+describe('DynamoDB Logger', () => {
+  describe('createDynamoDBLogger', () => {
+    it('should not log when disabled', () => {
+      const mockLoggerFn = jest.fn();
+      const logger = createDynamoDBLogger({
+        enabled: false,
+        logParams: true,
+        logResponse: true,
+        loggerFn: mockLoggerFn,
+      });
+
+      logger.log('GetCommand', { TableName: 'Users' }, { Item: { id: '123' } });
+
+      expect(mockLoggerFn).not.toHaveBeenCalled();
+    });
+
+    it('should log when enabled', () => {
+      const mockLoggerFn = jest.fn();
+      const logger = createDynamoDBLogger({
+        enabled: true,
+        logParams: true,
+        logResponse: false,
+        loggerFn: mockLoggerFn,
+      });
+
+      logger.log('GetCommand', { TableName: 'Users' });
+
+      expect(mockLoggerFn).toHaveBeenCalledTimes(1);
+      const loggedMessage = mockLoggerFn.mock.calls[0][0];
+      expect(loggedMessage).toContain('[DynamoDB] GetCommand');
+      expect(loggedMessage).toContain('📤 Request Parameters:');
+      expect(loggedMessage).toContain('"TableName": "Users"');
+    });
+
+    it('should log both params and response when configured', () => {
+      const mockLoggerFn = jest.fn();
+      const logger = createDynamoDBLogger({
+        enabled: true,
+        logParams: true,
+        logResponse: true,
+        loggerFn: mockLoggerFn,
+      });
+
+      const params = { TableName: 'Users', Key: { PK: 'USER#123' } };
+      const response = { Item: { PK: 'USER#123', username: 'johndoe' } };
+
+      logger.log('GetCommand', params, response);
+
+      expect(mockLoggerFn).toHaveBeenCalledTimes(1);
+      const loggedMessage = mockLoggerFn.mock.calls[0][0];
+
+      expect(loggedMessage).toContain('[DynamoDB] GetCommand');
+      expect(loggedMessage).toContain('📤 Request Parameters:');
+      expect(loggedMessage).toContain('"TableName": "Users"');
+      expect(loggedMessage).toContain('📥 Response:');
+      expect(loggedMessage).toContain('"username": "johndoe"');
+    });
+
+    it('should log only response when logParams is false', () => {
+      const mockLoggerFn = jest.fn();
+      const logger = createDynamoDBLogger({
+        enabled: true,
+        logParams: false,
+        logResponse: true,
+        loggerFn: mockLoggerFn,
+      });
+
+      const params = { TableName: 'Users' };
+      const response = { Item: { id: '123' } };
+
+      logger.log('GetCommand', params, response);
+
+      expect(mockLoggerFn).toHaveBeenCalledTimes(1);
+      const loggedMessage = mockLoggerFn.mock.calls[0][0];
+
+      expect(loggedMessage).toContain('[DynamoDB] GetCommand');
+      expect(loggedMessage).not.toContain('📤 Request Parameters:');
+      expect(loggedMessage).toContain('📥 Response:');
+    });
+
+    it('should log only params when logResponse is false', () => {
+      const mockLoggerFn = jest.fn();
+      const logger = createDynamoDBLogger({
+        enabled: true,
+        logParams: true,
+        logResponse: false,
+        loggerFn: mockLoggerFn,
+      });
+
+      const params = { TableName: 'Users' };
+      const response = { Item: { id: '123' } };
+
+      logger.log('GetCommand', params, response);
+
+      expect(mockLoggerFn).toHaveBeenCalledTimes(1);
+      const loggedMessage = mockLoggerFn.mock.calls[0][0];
+
+      expect(loggedMessage).toContain('[DynamoDB] GetCommand');
+      expect(loggedMessage).toContain('📤 Request Parameters:');
+      expect(loggedMessage).not.toContain('📥 Response:');
+    });
+
+    it('should use console.log by default when no loggerFn is provided', () => {
+      const consoleLogSpy = jest.spyOn(console, 'log').mockImplementation();
+
+      const logger = createDynamoDBLogger({
+        enabled: true,
+        logParams: true,
+        logResponse: false,
+      });
+
+      logger.log('GetCommand', { TableName: 'Users' });
+
+      expect(consoleLogSpy).toHaveBeenCalledTimes(1);
+
+      consoleLogSpy.mockRestore();
+    });
+
+    it('should include operation name and timestamp in log', () => {
+      const mockLoggerFn = jest.fn();
+      const logger = createDynamoDBLogger({
+        enabled: true,
+        logParams: true,
+        logResponse: false,
+        loggerFn: mockLoggerFn,
+      });
+
+      logger.log('QueryCommand', { TableName: 'Posts' });
+
+      expect(mockLoggerFn).toHaveBeenCalledTimes(1);
+      const loggedMessage = mockLoggerFn.mock.calls[0][0];
+
+      expect(loggedMessage).toContain('[DynamoDB] QueryCommand');
+      // Timestamp should be in ISO format
+      expect(loggedMessage).toMatch(/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/);
+    });
+
+    it('should format log with proper separators', () => {
+      const mockLoggerFn = jest.fn();
+      const logger = createDynamoDBLogger({
+        enabled: true,
+        logParams: true,
+        logResponse: false,
+        loggerFn: mockLoggerFn,
+      });
+
+      logger.log('GetCommand', { TableName: 'Users' });
+
+      const loggedMessage = mockLoggerFn.mock.calls[0][0];
+
+      // Should have separators (80 equal signs)
+      expect(loggedMessage).toContain('='.repeat(80));
+    });
+
+    it('should handle undefined response gracefully', () => {
+      const mockLoggerFn = jest.fn();
+      const logger = createDynamoDBLogger({
+        enabled: true,
+        logParams: true,
+        logResponse: true,
+        loggerFn: mockLoggerFn,
+      });
+
+      logger.log('GetCommand', { TableName: 'Users' }, undefined);
+
+      expect(mockLoggerFn).toHaveBeenCalledTimes(1);
+      const loggedMessage = mockLoggerFn.mock.calls[0][0];
+
+      expect(loggedMessage).toContain('📤 Request Parameters:');
+      expect(loggedMessage).not.toContain('📥 Response:');
+    });
+
+    it('should work with different operation types', () => {
+      const mockLoggerFn = jest.fn();
+      const logger = createDynamoDBLogger({
+        enabled: true,
+        logParams: true,
+        logResponse: false,
+        loggerFn: mockLoggerFn,
+      });
+
+      const operations = [
+        'GetCommand',
+        'PutCommand',
+        'UpdateCommand',
+        'DeleteCommand',
+        'QueryCommand',
+        'ScanCommand',
+      ];
+
+      operations.forEach((op) => {
+        logger.log(op, { TableName: 'Test' });
+      });
+
+      expect(mockLoggerFn).toHaveBeenCalledTimes(operations.length);
+
+      operations.forEach((op, index) => {
+        const loggedMessage = mockLoggerFn.mock.calls[index][0];
+        expect(loggedMessage).toContain(`[DynamoDB] ${op}`);
+      });
+    });
+
+    it('should handle complex nested objects in params and response', () => {
+      const mockLoggerFn = jest.fn();
+      const logger = createDynamoDBLogger({
+        enabled: true,
+        logParams: true,
+        logResponse: true,
+        loggerFn: mockLoggerFn,
+      });
+
+      const params = {
+        TableName: 'Users',
+        Item: {
+          PK: 'USER#123',
+          SK: 'PROFILE',
+          nested: {
+            level1: {
+              level2: {
+                value: 'deep',
+              },
+            },
+          },
+        },
+      };
+
+      const response = {
+        Items: [
+          { id: '1', data: { nested: 'value1' } },
+          { id: '2', data: { nested: 'value2' } },
+        ],
+      };
+
+      logger.log('QueryCommand', params, response);
+
+      const loggedMessage = mockLoggerFn.mock.calls[0][0];
+
+      expect(loggedMessage).toContain('"value": "deep"');
+      expect(loggedMessage).toContain('"nested": "value1"');
+      expect(loggedMessage).toContain('"nested": "value2"');
+    });
+  });
+});

package/src/utils/dynamodb-logger.ts

@@ -0,0 +1,175 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/**
+ * Configuration for DynamoDB operation logging
+ */
+export interface DynamoDBLoggerConfig {
+  /**
+   * Enable/disable logging. Default: false
+   */
+  enabled: boolean;
+
+  /**
+   * Log the request parameters. Default: true
+   */
+  logParams?: boolean;
+
+  /**
+   * Log the response data. Default: false
+   */
+  logResponse?: boolean;
+
+  /**
+   * Custom logger function. Default: console.log
+   */
+  loggerFn?: (message: string) => void;
+}
+
+/**
+ * DynamoDB Logger interface
+ */
+export type DynamoDBLogger = {
+  /**
+   * Log a DynamoDB operation with its parameters and optionally the response
+   */
+  log: <TParams, TResponse>(operationName: string, params: TParams, response?: TResponse) => void;
+};
+
+/**
+ * Pure function to format log message
+ * This function has no side effects and is easily testable
+ */
+const formatLogMessage = <TParams, TResponse>(
+  operationName: string,
+  timestamp: string,
+  params: TParams,
+  response: TResponse | undefined,
+  config: DynamoDBLoggerConfig
+): string => {
+  const parts: string[] = [
+    '\n' + '='.repeat(80),
+    `[DynamoDB] ${operationName} - ${timestamp}`,
+    '='.repeat(80),
+  ];
+
+  if (config.logParams && params) {
+    parts.push('\n📤 Request Parameters:');
+    parts.push(JSON.stringify(params, null, 2));
+  }
+
+  if (config.logResponse && response) {
+    parts.push('\n📥 Response:');
+    parts.push(JSON.stringify(response, null, 2));
+  }
+
+  parts.push('='.repeat(80) + '\n');
+
+  return parts.join('\n');
+};
+
+/**
+ * Creates a DynamoDB logger instance with the given configuration
+ * This is the main factory function for creating loggers
+ *
+ * @example Basic logger with request parameters only
+ * ```typescript
+ * const logger = createDynamoDBLogger({
+ *   enabled: true,
+ *   logParams: true,
+ *   logResponse: false,
+ * });
+ * ```
+ *
+ * @example Full logging (params + response)
+ * ```typescript
+ * const logger = createDynamoDBLogger({
+ *   enabled: true,
+ *   logParams: true,
+ *   logResponse: true,
+ * });
+ * ```
+ *
+ * @example Using with a table
+ * ```typescript
+ * const logger = createDynamoDBLogger({
+ *   enabled: true,
+ *   logParams: true,
+ *   logResponse: true,
+ * });
+ *
+ * const userTable = createTable({
+ *   tableName: 'Users',
+ *   client: dynamoDBClient,
+ *   schema: userSchema,
+ *   logger, // Pass logger to table
+ * });
+ *
+ * // Operations will be logged automatically
+ * const user = await userTable.get({ username: 'johndoe' }).execute();
+ * ```
+ *
+ * @example Custom logger function (Winston, Pino, etc.)
+ * ```typescript
+ * import winston from 'winston';
+ *
+ * const winstonLogger = winston.createLogger({
+ *   level: 'info',
+ *   format: winston.format.json(),
+ *   transports: [new winston.transports.Console()],
+ * });
+ *
+ * const logger = createDynamoDBLogger({
+ *   enabled: true,
+ *   logParams: true,
+ *   logResponse: true,
+ *   loggerFn: (message) => winstonLogger.info(message),
+ * });
+ * ```
+ *
+ * @example Output format
+ * ```
+ * ================================================================================
+ * [DynamoDB] GetCommand - 2025-12-29T10:30:45.123Z
+ * ================================================================================
+ *
+ * 📤 Request Parameters:
+ * {
+ *   "TableName": "Users",
+ *   "Key": {
+ *     "PK": "USER#johndoe",
+ *     "SK": "PROFILE"
+ *   }
+ * }
+ *
+ * 📥 Response:
+ * {
+ *   "Item": {
+ *     "PK": "USER#johndoe",
+ *     "SK": "PROFILE",
+ *     "username": "johndoe",
+ *     "email": "john@example.com"
+ *   }
+ * }
+ * ================================================================================
+ * ```
+ */
+export const createDynamoDBLogger = (config: DynamoDBLoggerConfig): DynamoDBLogger => {
+  const logFn = config.loggerFn || console.log;
+
+  return {
+    log: <TParams, TResponse>(
+      operationName: string,
+      params: TParams,
+      response?: TResponse
+    ): void => {
+      if (!config.enabled) {
+        return;
+      }
+
+      const timestamp = new Date().toISOString();
+      const message = formatLogMessage(operationName, timestamp, params, response, config);
+
+      logFn(message);
+    },
+  };
+};