@ftschopp/dynatable-core 1.0.0 → 1.1.0

package/src/builders/update/types.ts

@@ -1,3 +1,4 @@
+import type { UpdateCommandInput } from '@aws-sdk/lib-dynamodb';
 import { OperationBuilder, AttrRef } from '../shared';
 
 /**
@@ -12,11 +13,12 @@ export type UpdateAction = {
 /**
  * Builder interface for DynamoDB UpdateItem operations
  */
-export interface UpdateBuilder<Model> extends OperationBuilder<Model> {
+export interface UpdateBuilder<Model> extends Omit<OperationBuilder<Model>, 'dbParams'> {
   /**
-   * Sets an attribute to a specific value
+   * Sets an attribute to a specific value, or sets multiple attributes at once
    */
   set(attr: keyof Model | AttrRef, value: any): UpdateBuilder<Model>;
+  set(updates: Partial<Model>): UpdateBuilder<Model>;
 
   /**
    * Removes an attribute from the item
@@ -39,4 +41,9 @@ export interface UpdateBuilder<Model> extends OperationBuilder<Model> {
   returning(
     mode: 'NONE' | 'ALL_OLD' | 'ALL_NEW' | 'UPDATED_OLD' | 'UPDATED_NEW'
   ): UpdateBuilder<Model>;
+
+  /**
+   * Converts the builder state to DynamoDB UpdateItem parameters
+   */
+  dbParams(): UpdateCommandInput;
 }

package/src/core/types.ts

@@ -95,6 +95,7 @@ export type ModelDefinition = {
 export type SchemaParams = {
   isoDates?: boolean;
   timestamps?: boolean;
+  cleanInternalKeys?: boolean;
 };
 
 /**

package/src/entity/create-entity-api.ts

@@ -0,0 +1,212 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { InferInput, InferKeyInput, InferModel, ModelDefinition } from '@/core/types';
+import { applyPostDefaults, resolveKeys } from '@/utils/model-utils';
+import { modelToZod } from '@/utils/zod-utils';
+import {
+  createGetBuilder,
+  createPutBuilder,
+  createQueryBuilder,
+  createUpdateBuilder,
+  createDeleteBuilder,
+  createScanBuilder,
+  createBatchGetBuilder,
+  createBatchWriteBuilder,
+  WriteRequest,
+} from '@/builders';
+import { EntityAPI, EntityAPIOptions } from './types';
+import { withMiddleware } from './middleware/with-middleware';
+import { createCleanKeysMiddleware } from './middleware/factories';
+import { validateKeyFields } from './validation/key-validation';
+
+/**
+ * Creates an entity API instance with validation, key resolution, and builder creation.
+ *
+ * @param tableName - The name of the DynamoDB table
+ * @param modelName - The name of the model/entity
+ * @param model - The model definition
+ * @param client - DynamoDB client instance
+ * @param options - Optional configuration (logger, timestamps, cleanInternalKeys)
+ * @returns EntityAPI with get, put, query, scan, update, delete, batchGet, and batchWrite methods
+ */
+export const createEntityAPI = <Model extends ModelDefinition>(
+  tableName: string,
+  modelName: string,
+  model: Model,
+  client: DynamoDBClient,
+  options: EntityAPIOptions = {}
+): EntityAPI<InferModel<Model>, InferInput<Model>, InferKeyInput<Model>> => {
+  const { logger, timestamps = false, cleanInternalKeys = false } = options;
+
+  // Build a Zod schema from the model
+  const zodSchema = modelToZod(model);
+
+  return {
+    get(key) {
+      // Validate key fields
+      validateKeyFields(modelName, model, key as Record<string, unknown>, 'get()');
+
+      // Resolve any key defaults or computed keys
+      const fullKey = resolveKeys(model, key);
+
+      const builder = createGetBuilder<InferKeyInput<Model>, InferModel<Model>>(
+        tableName,
+        fullKey,
+        client,
+        undefined,
+        logger
+      );
+
+      return withMiddleware(builder, createCleanKeysMiddleware(cleanInternalKeys));
+    },
+
+    put(item) {
+      // Validate full input data
+      const parsed = zodSchema.parse(item);
+
+      // Apply post-processing defaults from the model (including timestamps for new items)
+      const withDefaults = applyPostDefaults(model, parsed, {
+        isUpdate: false,
+        timestamps,
+      });
+
+      // Resolve keys again with defaults
+      const fullKey = resolveKeys(model, withDefaults);
+
+      // Combine keys and data into full item, adding _type field
+      const fullItem = {
+        ...withDefaults,
+        ...fullKey,
+        _type: modelName, // Add entity type identifier
+      };
+
+      return createPutBuilder(tableName, fullItem, client, [], false, 'NONE', false, logger);
+    },
+
+    query() {
+      // Query builder doesn't have execute() until after .where() is called
+      // The cleanInternalKeys will be handled in the builder itself
+      return createQueryBuilder<InferModel<Model>>(tableName, client, model, logger);
+    },
+
+    scan() {
+      const builder = createScanBuilder<InferModel<Model>>(
+        tableName,
+        client,
+        [],
+        [],
+        undefined,
+        false,
+        undefined,
+        undefined,
+        undefined,
+        logger
+      );
+
+      return withMiddleware(builder, createCleanKeysMiddleware(cleanInternalKeys));
+    },
+
+    update(key) {
+      // Validate key fields
+      validateKeyFields(modelName, model, key as Record<string, unknown>, 'update()');
+
+      // Resolve any key defaults or computed keys
+      const fullKey = resolveKeys(model, key);
+
+      const builder = createUpdateBuilder<InferModel<Model>>(
+        tableName,
+        fullKey as Partial<InferModel<Model>>,
+        client,
+        [],
+        { set: [], remove: [], add: [], delete: [] },
+        'NONE',
+        0,
+        timestamps,
+        logger
+      );
+
+      return withMiddleware(builder, createCleanKeysMiddleware(cleanInternalKeys));
+    },
+
+    delete(key) {
+      // Validate key fields
+      validateKeyFields(modelName, model, key as Record<string, unknown>, 'delete()');
+
+      // Resolve any key defaults or computed keys
+      const fullKey = resolveKeys(model, key);
+
+      const builder = createDeleteBuilder<InferModel<Model>>(
+        tableName,
+        fullKey as Partial<InferModel<Model>>,
+        client,
+        [],
+        'NONE',
+        logger
+      );
+
+      return withMiddleware(builder, createCleanKeysMiddleware(cleanInternalKeys));
+    },
+
+    batchGet(keys) {
+      // Process all keys and validate them
+      const resolvedKeys = keys.map((key) => {
+        // Validate key fields
+        validateKeyFields(modelName, model, key as Record<string, unknown>, 'batchGet()');
+
+        // Resolve any key defaults or computed keys
+        return resolveKeys(model, key);
+      });
+
+      // Create the request items in the format expected by BatchGetItem
+      const requestItems = {
+        [tableName]: {
+          Keys: resolvedKeys,
+        },
+      };
+
+      const builder = createBatchGetBuilder<InferModel<Model>>(
+        requestItems,
+        client,
+        undefined,
+        logger
+      );
+
+      return withMiddleware(builder, createCleanKeysMiddleware(cleanInternalKeys));
+    },
+
+    batchWrite(items) {
+      // Validate and process all items
+      const processedItems = items.map((item) => {
+        // Validate full input data
+        const parsed = zodSchema.parse(item);
+
+        // Apply post-processing defaults from the model (including timestamps for new items)
+        const withDefaults = applyPostDefaults(model, parsed, {
+          isUpdate: false,
+          timestamps,
+        });
+
+        // Resolve keys again with defaults
+        const fullKey = resolveKeys(model, withDefaults);
+
+        // Combine keys and data into full item, adding _type field
+        return {
+          ...withDefaults,
+          ...fullKey,
+          _type: modelName, // Add entity type identifier
+        };
+      });
+
+      // Create the request items in the format expected by BatchWriteItem
+      const requestItems: Record<string, WriteRequest[]> = {
+        [tableName]: processedItems.map((item) => ({
+          PutRequest: {
+            Item: item,
+          },
+        })),
+      };
+
+      return createBatchWriteBuilder(requestItems, client, logger);
+    },
+  };
+};

package/src/entity/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Entity API module
+ *
+ * Provides high-level entity management with validation, key resolution, and builder creation.
+ */
+
+// Core types
+export type { EntityAPI, EntityAPIOptions } from './types';
+
+// Middleware types and utilities
+export type { ExecutionMiddleware } from './middleware/types';
+export { withMiddleware } from './middleware/with-middleware';
+export { createCleanKeysMiddleware } from './middleware/factories';
+
+// Validation utilities
+export { validateKeyFields } from './validation/key-validation';
+
+// Main entity API factory
+export { createEntityAPI } from './create-entity-api';

package/src/entity/middleware/factories.ts

@@ -0,0 +1,15 @@
+import { stripInternalKeys } from '@/utils/model-utils';
+import { ExecutionMiddleware } from './types';
+
+/**
+ * Creates middleware configuration for cleaning internal keys
+ */
+export function createCleanKeysMiddleware(shouldClean: boolean): ExecutionMiddleware {
+  if (!shouldClean) {
+    return {};
+  }
+
+  return {
+    after: (result) => stripInternalKeys(result),
+  };
+}

package/src/entity/middleware/types.ts

@@ -0,0 +1,7 @@
+/**
+ * Middleware hooks for builder execution
+ */
+export type ExecutionMiddleware<T = any> = {
+  before?: () => void | Promise<void>;
+  after?: (result: T) => T | Promise<T>;
+};

package/src/entity/middleware/with-middleware.ts

@@ -0,0 +1,37 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { ExecutionMiddleware } from './types';
+
+/**
+ * Applies middleware hooks to a builder's execute method
+ */
+export function withMiddleware<B extends { execute: () => Promise<any> }>(
+  builder: B,
+  middleware: ExecutionMiddleware
+): B {
+  const { before, after } = middleware;
+
+  // If no middleware hooks provided, return builder as-is
+  if (!before && !after) {
+    return builder;
+  }
+
+  return {
+    ...builder,
+    execute: async () => {
+      // Before execution hook
+      if (before) {
+        await before();
+      }
+
+      // Execute original builder
+      const result = await builder.execute();
+
+      // After execution hook
+      if (after) {
+        return await after(result);
+      }
+
+      return result;
+    },
+  };
+}

package/src/entity/types.ts

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

@@ -0,0 +1,34 @@
+/* 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/table.ts

@@ -25,14 +25,20 @@ export type TableConfig<S extends SchemaDefinition> = {
   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<
-    InferModelFromSchema<S, K>,
-    InferInputFromSchema<S, K>,
-    InferKeyInput<S['models'][K]>
+    Simplify<InferModelFromSchema<S, K>>,
+    Simplify<InferInputFromSchema<S, K>>,
+    Simplify<InferKeyInput<S['models'][K]>>
   >;
 };
 
@@ -65,6 +71,7 @@ export class Table<S extends SchemaDefinition> {
       rawEntities[modelName] = createEntityAPI(tableName, modelName, model, client, {
         logger,
         timestamps: schema.params?.timestamps ?? false,
+        cleanInternalKeys: schema.params?.cleanInternalKeys ?? false,
       });
     }
 

package/src/utils/model-utils.test.ts

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { applyPostDefaults } from './model-utils';
+import { applyPostDefaults, stripInternalKeys } from './model-utils';
 import { ModelDefinition } from '../core/types';
 
 describe('applyPostDefaults - Timestamps', () => {
@@ -230,3 +230,133 @@ describe('applyPostDefaults - Timestamps', () => {
     });
   });
 });
+
+describe('stripInternalKeys', () => {
+  test('should remove PK, SK, and _type from object', () => {
+    const input = {
+      PK: 'USER#alice',
+      SK: 'USER#alice',
+      _type: 'User',
+      username: 'alice',
+      name: 'Alice',
+      email: 'alice@example.com',
+    };
+
+    const result = stripInternalKeys(input);
+
+    expect(result).toEqual({
+      username: 'alice',
+      name: 'Alice',
+      email: 'alice@example.com',
+    });
+  });
+
+  test('should handle object without internal keys', () => {
+    const input = {
+      username: 'alice',
+      name: 'Alice',
+      email: 'alice@example.com',
+    };
+
+    const result = stripInternalKeys(input);
+
+    expect(result).toEqual(input);
+  });
+
+  test('should handle array of objects', () => {
+    const input = [
+      {
+        PK: 'USER#alice',
+        SK: 'USER#alice',
+        _type: 'User',
+        username: 'alice',
+        name: 'Alice',
+      },
+      {
+        PK: 'USER#bob',
+        SK: 'USER#bob',
+        _type: 'User',
+        username: 'bob',
+        name: 'Bob',
+      },
+    ];
+
+    const result = stripInternalKeys(input);
+
+    expect(result).toEqual([
+      { username: 'alice', name: 'Alice' },
+      { username: 'bob', name: 'Bob' },
+    ]);
+  });
+
+  test('should handle undefined', () => {
+    const result = stripInternalKeys(undefined);
+    expect(result).toBeUndefined();
+  });
+
+  test('should handle null', () => {
+    const result = stripInternalKeys(null);
+    expect(result).toBeNull();
+  });
+
+  test('should handle empty object', () => {
+    const input = {};
+    const result = stripInternalKeys(input);
+    expect(result).toEqual({});
+  });
+
+  test('should handle empty array', () => {
+    const input: any[] = [];
+    const result = stripInternalKeys(input);
+    expect(result).toEqual([]);
+  });
+
+  test('should preserve other fields with similar names', () => {
+    const input = {
+      PK: 'USER#alice',
+      SK: 'USER#alice',
+      _type: 'User',
+      PKG: 'package-name',
+      SKIP: 'skip-value',
+      type: 'customer',
+      username: 'alice',
+    };
+
+    const result = stripInternalKeys(input);
+
+    expect(result).toEqual({
+      PKG: 'package-name',
+      SKIP: 'skip-value',
+      type: 'customer',
+      username: 'alice',
+    });
+  });
+
+  test('should handle nested objects (does not recurse)', () => {
+    const input = {
+      PK: 'USER#alice',
+      SK: 'USER#alice',
+      _type: 'User',
+      username: 'alice',
+      metadata: {
+        PK: 'METADATA#1',
+        SK: 'METADATA#1',
+        _type: 'Metadata',
+        value: 'test',
+      },
+    };
+
+    const result = stripInternalKeys(input);
+
+    // stripInternalKeys does not recurse into nested objects
+    expect(result).toEqual({
+      username: 'alice',
+      metadata: {
+        PK: 'METADATA#1',
+        SK: 'METADATA#1',
+        _type: 'Metadata',
+        value: 'test',
+      },
+    });
+  });
+});

package/src/utils/model-utils.ts

@@ -99,3 +99,35 @@ export const applyPostDefaults = <M extends ModelDefinition>(
 
   return result as InferModel<M>;
 };
+
+/**
+ * Internal DynamoDB keys that should be stripped when cleanInternalKeys is enabled
+ */
+const INTERNAL_KEYS = ['PK', 'SK', '_type'] as const;
+
+/**
+ * Removes internal DynamoDB keys from an item or array of items
+ * @param data - Single item or array of items from DynamoDB
+ * @returns Data with internal keys removed
+ */
+export const stripInternalKeys = <T>(data: T | T[] | undefined): T | T[] | undefined => {
+  if (data === undefined || data === null) {
+    return data;
+  }
+
+  if (Array.isArray(data)) {
+    return data.map((item) => stripInternalKeys(item)) as T[];
+  }
+
+  if (typeof data === 'object') {
+    const cleaned: any = {};
+    for (const [key, value] of Object.entries(data)) {
+      if (!INTERNAL_KEYS.includes(key as any)) {
+        cleaned[key] = value;
+      }
+    }
+    return cleaned as T;
+  }
+
+  return data;
+};

package/dist/entity.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../src/entity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAGtF,OAAO,EASL,UAAU,EACV,UAAU,EACV,YAAY,EACZ,aAAa,EACb,aAAa,EACb,WAAW,EACX,eAAe,EACf,iBAAiB,EAElB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAEzD;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,SAAS,eAAe,GAAG,GAAG,IAAI;IACtF;;;;OAIG;IACH,GAAG,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,UAAU,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAEpD;;;;OAIG;IACH,GAAG,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,UAAU,CAAC,KAAK,CAAC,CAAC;IAExC;;;OAGG;IACH,KAAK,EAAE,MAAM,YAAY,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAE3C;;;OAGG;IACH,IAAI,EAAE,MAAM,WAAW,CAAC,KAAK,CAAC,CAAC;IAE/B;;;;OAIG;IACH,MAAM,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,aAAa,CAAC,KAAK,CAAC,CAAC;IAEhD;;;;OAIG;IACH,MAAM,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,aAAa,CAAC,KAAK,CAAC,CAAC;IAEhD;;;;OAIG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,eAAe,CAAC,KAAK,CAAC,CAAC;IAEvD;;;;OAIG;IACH,UAAU,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,iBAAiB,CAAC;CACnD,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,GAAI,KAAK,SAAS,eAAe,EAC3D,WAAW,MAAM,EACjB,WAAW,MAAM,EACjB,OAAO,KAAK,EACZ,QAAQ,cAAc,EACtB,UAAS,gBAAqB,KAC7B,SAAS,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,KAAK,CAAC,EAAE,KAAK,CAqO7E,CAAC"}