@ftschopp/dynatable-core 1.4.2 → 1.4.4

package/src/entity/types.ts

@@ -1,79 +0,0 @@
-import { DynamoDBLogger } from '@/utils/dynamodb-logger';
-import {
-  GetBuilder,
-  PutBuilder,
-  QueryBuilder,
-  UpdateBuilder,
-  DeleteBuilder,
-  ScanBuilder,
-  BatchGetBuilder,
-  BatchWriteBuilder,
-} from '@/builders';
-
-/**
- * Options for creating the Entity API
- */
-export type EntityAPIOptions = {
-  logger?: DynamoDBLogger;
-  timestamps?: boolean;
-  cleanInternalKeys?: boolean;
-};
-
-/**
- * Entity API interface for a model
- */
-export type EntityAPI<Model, Input, KeyInput> = {
-  /**
-   * Retrieves an item by its key.
-   * @param key - Partial or full key object to identify the item
-   * @returns GetBuilder configured for the item
-   */
-  get: (key: KeyInput) => GetBuilder<KeyInput, Model>;
-
-  /**
-   * Puts an item into the table after validation and applying defaults.
-   * @param item - The input data to put
-   * @returns PutBuilder configured for the item
-   */
-  put: (item: Input) => PutBuilder<Model>;
-
-  /**
-   * Queries items using key conditions.
-   * @returns QueryBuilder for building and executing the query
-   */
-  query: () => QueryBuilder<Model>;
-
-  /**
-   * Scans the entire table or index without key conditions.
-   * @returns ScanBuilder for building and executing the scan
-   */
-  scan: () => ScanBuilder<Model>;
-
-  /**
-   * Updates an item by its key.
-   * @param key - Partial or full key object to identify the item
-   * @returns UpdateBuilder configured for the item
-   */
-  update: (key: KeyInput) => UpdateBuilder<Model>;
-
-  /**
-   * Deletes an item by its key.
-   * @param key - Partial or full key object to identify the item
-   * @returns DeleteBuilder configured for the item
-   */
-  delete: (key: KeyInput) => DeleteBuilder<Model>;
-
-  /**
-   * Retrieves multiple items by their keys in a single batch operation.
-   * @param keys - Array of key objects to retrieve
-   * @returns BatchGetBuilder configured for the items
-   */
-  batchGet: (keys: KeyInput[]) => BatchGetBuilder<Model>;
-
-  /**
-   * Writes multiple items in a single batch operation (puts or deletes).
-   * @param items - Array of items to put
-   * @returns BatchWriteBuilder configured for the items
-   */
-  batchWrite: (items: Input[]) => BatchWriteBuilder;
-};

package/src/entity/validation/key-validation.ts

@@ -1,34 +0,0 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-
-import { ModelDefinition } from '@/core/types';
-import { extractTemplateVars } from '@/utils/model-utils';
-
-/**
- * Validates that all required key fields are present in the key object
- * @throws Error if any required key fields are missing
- */
-export function validateKeyFields(
-  modelName: string,
-  model: ModelDefinition,
-  key: Record<string, unknown>,
-  operation?: string
-): void {
-  // Extract required fields from key templates
-  const requiredFields = new Set<string>();
-  if (model.key) {
-    for (const keyDef of Object.values(model.key)) {
-      extractTemplateVars(keyDef.value).forEach((field) => requiredFields.add(field));
-    }
-  }
-
-  // Check if all required fields are present
-  const missingFields = Array.from(requiredFields).filter((field) => key[field] === undefined);
-
-  if (missingFields.length > 0) {
-    const operationSuffix = operation ? ` for ${operation}` : '';
-    throw new Error(
-      `[${modelName}] Missing required key field(s)${operationSuffix}: ${missingFields.join(', ')}. ` +
-        `Required fields: ${Array.from(requiredFields).join(', ')}`
-    );
-  }
-}

package/src/index.ts

@@ -1,23 +0,0 @@
-export * from './table';
-export {
-  type SchemaDefinition,
-  type ModelDefinition,
-  type PrimaryKeyDefinition,
-  type KeyDefinition,
-  type AttributeDefinition,
-  type IndexDefinition,
-  type IndexesDefinition,
-  type SchemaParams,
-  type InferInput,
-  type InferModel,
-  type InferKeyInput,
-  type InferModelFromSchema,
-  type InferInputFromSchema,
-  type TimestampFields,
-  type ArrayItem,
-} from './core/types';
-export {
-  createDynamoDBLogger,
-  type DynamoDBLogger,
-  type DynamoDBLoggerConfig,
-} from './utils/dynamodb-logger';

package/src/table.ts

@@ -1,116 +0,0 @@
-/* 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;
-};
-
-/**
- * Helper type to force TypeScript to expand/simplify a type.
- * This helps with type inference in callbacks by making the type "concrete".
- */
-type Simplify<T> = { [K in keyof T]: T[K] } & {};
-
-/**
- * Internal helper type to infer all entity APIs from schema definition
- */
-type EntityMap<S extends SchemaDefinition> = {
-  [K in keyof S['models']]: EntityAPI<
-    Simplify<InferModelFromSchema<S, K>>,
-    Simplify<InferInputFromSchema<S, K>>,
-    Simplify<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,
-        cleanInternalKeys: schema.params?.cleanInternalKeys ?? 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

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

@@ -1,175 +0,0 @@
-/* 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);
-    },
-  };
-};