@ftschopp/dynatable-core 1.0.0 → 1.2.0

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

@@ -71,9 +71,10 @@ export const applyPostDefaults = <M extends ModelDefinition>(
 
   for (const [key, attr] of Object.entries(model.attributes)) {
     if (result[key] === undefined) {
-      if (attr.generate === 'ulid') {
+      const generate = 'generate' in attr ? attr.generate : undefined;
+      if (generate === 'ulid') {
         result[key] = ulid();
-      } else if (attr.generate === 'uuid') {
+      } else if (generate === 'uuid') {
         result[key] = crypto.randomUUID();
       } else if (attr.default !== undefined) {
         result[key] = typeof attr.default === 'function' ? attr.default() : attr.default;
@@ -99,3 +100,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/src/utils/zod-utils.test.ts

@@ -71,9 +71,9 @@ describe('zod-utils', () => {
       expect(() => zodType.parse(undefined)).toThrow();
     });
 
-    it('should return z.unknown() for unknown types', () => {
+    it('should return z.unknown() for unrecognized types', () => {
       const attr: AttributeDefinition = {
-        type: Array as any,
+        type: Map as any,
         required: true,
       };
       const zodType = typeToZod(attr);
@@ -83,6 +83,101 @@ describe('zod-utils', () => {
       expect(() => zodType.parse(123)).not.toThrow();
       expect(() => zodType.parse([])).not.toThrow();
     });
+
+    it('should convert Object type with schema to z.looseObject()', () => {
+      const attr: AttributeDefinition = {
+        type: Object,
+        schema: {
+          city: { type: String, required: true },
+          zip: { type: String },
+        },
+        required: true,
+      };
+      const zodType = typeToZod(attr);
+
+      expect(() => zodType.parse({ city: 'BA' })).not.toThrow();
+      expect(() => zodType.parse({ city: 'BA', zip: '1000' })).not.toThrow();
+      expect(() => zodType.parse({ zip: '1000' })).toThrow(); // city required
+      expect(() => zodType.parse({})).toThrow();
+    });
+
+    it('should convert Object type without schema to z.record()', () => {
+      const attr: AttributeDefinition = {
+        type: Object,
+        schema: {},
+      };
+      const zodType = typeToZod(attr);
+      expect(() => zodType.parse({})).not.toThrow();
+    });
+
+    it('should convert Array type with scalar items', () => {
+      const attr: AttributeDefinition = {
+        type: Array,
+        items: { type: String },
+        required: true,
+      };
+      const zodType = typeToZod(attr);
+
+      expect(() => zodType.parse(['a', 'b'])).not.toThrow();
+      expect(() => zodType.parse([])).not.toThrow();
+      expect(() => zodType.parse([1, 2])).toThrow(); // numbers, not strings
+    });
+
+    it('should convert Array type with object items (like history)', () => {
+      const attr: AttributeDefinition = {
+        type: Array,
+        items: {
+          type: Object,
+          schema: {
+            date: { type: String },
+            status: { type: String, required: true },
+          },
+        },
+        required: true,
+      };
+      const zodType = typeToZod(attr);
+
+      expect(() => zodType.parse([{ status: 'PENDING' }])).not.toThrow();
+      expect(() =>
+        zodType.parse([{ date: '2024-01-01', status: 'DONE' }])
+      ).not.toThrow();
+      expect(() => zodType.parse([{ date: '2024-01-01' }])).toThrow(); // missing status
+    });
+
+    it('should handle optional Object attribute', () => {
+      const attr: AttributeDefinition = {
+        type: Object,
+        schema: { name: { type: String, required: true } },
+      };
+      const zodType = typeToZod(attr);
+
+      expect(() => zodType.parse(undefined)).not.toThrow();
+      expect(() => zodType.parse({ name: 'test' })).not.toThrow();
+    });
+
+    it('should handle deeply nested objects', () => {
+      const attr: AttributeDefinition = {
+        type: Object,
+        required: true,
+        schema: {
+          value: { type: Number, required: true },
+          breakdown: {
+            type: Object,
+            schema: {
+              base: { type: Number, required: true },
+              fees: { type: Number, required: true },
+            },
+          },
+        },
+      };
+      const zodType = typeToZod(attr);
+
+      expect(() =>
+        zodType.parse({ value: 100, breakdown: { base: 90, fees: 10 } })
+      ).not.toThrow();
+      expect(() => zodType.parse({ value: 100 })).not.toThrow(); // breakdown optional
+      expect(() => zodType.parse({})).toThrow(); // value required
+    });
   });
 
   describe('modelToZod', () => {

package/src/utils/zod-utils.ts

@@ -5,19 +5,38 @@ import { AttributeDefinition, ModelDefinition } from '@/core/types';
 import { z, ZodObject, ZodType } from 'zod';
 
 /**
- * Converts an attribute definition to a Zod schema type
+ * Converts an attribute definition to a Zod schema type.
+ * Supports scalars, nested objects (with schema), and arrays (with items).
  */
 export const typeToZod = (attr: AttributeDefinition): ZodType => {
-  const zodType: ZodType =
-    attr.type === String
-      ? z.string()
-      : attr.type === Number
-        ? z.number()
-        : attr.type === Boolean
-          ? z.boolean()
-          : attr.type === Date
-            ? z.date()
-            : z.unknown();
+  let zodType: ZodType;
+
+  if (attr.type === Object) {
+    const schema = (attr as { schema?: Record<string, AttributeDefinition> }).schema;
+    if (schema) {
+      const shape: Record<string, ZodType> = {};
+      for (const [key, nestedAttr] of Object.entries(schema)) {
+        shape[key] = typeToZod(nestedAttr);
+      }
+      zodType = z.looseObject(shape);
+    } else {
+      zodType = z.record(z.string(), z.unknown());
+    }
+  } else if (attr.type === Array) {
+    const items = (attr as { items?: AttributeDefinition }).items;
+    zodType = items ? z.array(typeToZod(items)) : z.array(z.unknown());
+  } else {
+    zodType =
+      attr.type === String
+        ? z.string()
+        : attr.type === Number
+          ? z.number()
+          : attr.type === Boolean
+            ? z.boolean()
+            : attr.type === Date
+              ? z.date()
+              : z.unknown();
+  }
 
   return attr.required ? zodType : zodType.optional();
 };
@@ -32,5 +51,5 @@ export const modelToZod = (model: ModelDefinition): ZodObject<any> => {
   for (const [key, attr] of Object.entries(model.attributes)) {
     shape[key] = typeToZod(attr);
   }
-  return z.object(shape).passthrough();
+  return z.looseObject(shape);
 };

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"}

package/dist/entity.js

@@ -1,161 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createEntityAPI = void 0;
-const model_utils_1 = require("./utils/model-utils");
-const zod_utils_1 = require("./utils/zod-utils");
-const builders_1 = require("./builders");
-/**
- * Creates an entity API instance with validation, key resolution, and builder creation.
- *
- * @param modelName - The name of the model/entity
- * @param model - The model definition
- * @param client - DynamoDB client instance
- * @param options - Optional configuration (logger, timestamps)
- * @returns EntityAPI with get and put methods
- */
-const createEntityAPI = (tableName, modelName, model, client, options = {}) => {
-    const { logger, timestamps = false } = options;
-    // Build a Zod schema from the model
-    const zodSchema = (0, zod_utils_1.modelToZod)(model);
-    return {
-        get(key) {
-            // Extract required fields from key templates
-            const requiredFields = new Set();
-            if (model.key) {
-                for (const keyDef of Object.values(model.key)) {
-                    (0, model_utils_1.extractTemplateVars)(keyDef.value).forEach((field) => requiredFields.add(field));
-                }
-            }
-            // Check if all required fields are present
-            const keyRecord = key;
-            const missingFields = Array.from(requiredFields).filter((field) => keyRecord[field] === undefined);
-            if (missingFields.length > 0) {
-                throw new Error(`[${modelName}] Missing required key field(s) for get(): ${missingFields.join(', ')}. ` +
-                    `Required fields: ${Array.from(requiredFields).join(', ')}`);
-            }
-            // Resolve any key defaults or computed keys
-            const fullKey = (0, model_utils_1.resolveKeys)(model, key);
-            return (0, builders_1.createGetBuilder)(tableName, fullKey, client, undefined, logger);
-        },
-        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 = (0, model_utils_1.applyPostDefaults)(model, parsed, {
-                isUpdate: false,
-                timestamps,
-            });
-            // Resolve keys again with defaults
-            const fullKey = (0, model_utils_1.resolveKeys)(model, withDefaults);
-            // Combine keys and data into full item, adding _type field
-            const fullItem = {
-                ...withDefaults,
-                ...fullKey,
-                _type: modelName, // Add entity type identifier
-            };
-            return (0, builders_1.createPutBuilder)(tableName, fullItem, client, [], false, 'NONE', false, logger);
-        },
-        query() {
-            return (0, builders_1.createQueryBuilder)(tableName, client, model, logger);
-        },
-        scan() {
-            return (0, builders_1.createScanBuilder)(tableName, client, [], [], undefined, false, undefined, undefined, undefined, logger);
-        },
-        update(key) {
-            // Extract required fields from key templates
-            const requiredFields = new Set();
-            if (model.key) {
-                for (const keyDef of Object.values(model.key)) {
-                    (0, model_utils_1.extractTemplateVars)(keyDef.value).forEach((field) => requiredFields.add(field));
-                }
-            }
-            // Check if all required fields are present
-            const keyRecord = key;
-            const missingFields = Array.from(requiredFields).filter((field) => keyRecord[field] === undefined);
-            if (missingFields.length > 0) {
-                throw new Error(`[${modelName}] Missing required key field(s) for update(): ${missingFields.join(', ')}. ` +
-                    `Required fields: ${Array.from(requiredFields).join(', ')}`);
-            }
-            // Resolve any key defaults or computed keys
-            const fullKey = (0, model_utils_1.resolveKeys)(model, key);
-            return (0, builders_1.createUpdateBuilder)(tableName, fullKey, client, [], { set: [], remove: [], add: [], delete: [] }, 'NONE', 0, timestamps, logger);
-        },
-        delete(key) {
-            // Extract required fields from key templates
-            const requiredFields = new Set();
-            if (model.key) {
-                for (const keyDef of Object.values(model.key)) {
-                    (0, model_utils_1.extractTemplateVars)(keyDef.value).forEach((field) => requiredFields.add(field));
-                }
-            }
-            // Check if all required fields are present
-            const keyRecord = key;
-            const missingFields = Array.from(requiredFields).filter((field) => keyRecord[field] === undefined);
-            if (missingFields.length > 0) {
-                throw new Error(`[${modelName}] Missing required key field(s) for delete(): ${missingFields.join(', ')}. ` +
-                    `Required fields: ${Array.from(requiredFields).join(', ')}`);
-            }
-            // Resolve any key defaults or computed keys
-            const fullKey = (0, model_utils_1.resolveKeys)(model, key);
-            return (0, builders_1.createDeleteBuilder)(tableName, fullKey, client, [], 'NONE', logger);
-        },
-        batchGet(keys) {
-            // Extract required fields from key templates
-            const requiredFields = new Set();
-            if (model.key) {
-                for (const keyDef of Object.values(model.key)) {
-                    (0, model_utils_1.extractTemplateVars)(keyDef.value).forEach((field) => requiredFields.add(field));
-                }
-            }
-            // Process all keys and validate them
-            const resolvedKeys = keys.map((key) => {
-                // Check if all required fields are present
-                const keyRecord = key;
-                const missingFields = Array.from(requiredFields).filter((field) => keyRecord[field] === undefined);
-                if (missingFields.length > 0) {
-                    throw new Error(`[${modelName}] Missing required key field(s) for batchGet(): ${missingFields.join(', ')}. ` +
-                        `Required fields: ${Array.from(requiredFields).join(', ')}`);
-                }
-                // Resolve any key defaults or computed keys
-                return (0, model_utils_1.resolveKeys)(model, key);
-            });
-            // Create the request items in the format expected by BatchGetItem
-            const requestItems = {
-                [tableName]: {
-                    Keys: resolvedKeys,
-                },
-            };
-            return (0, builders_1.createBatchGetBuilder)(requestItems, client, undefined, logger);
-        },
-        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 = (0, model_utils_1.applyPostDefaults)(model, parsed, {
-                    isUpdate: false,
-                    timestamps,
-                });
-                // Resolve keys again with defaults
-                const fullKey = (0, model_utils_1.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 = {
-                [tableName]: processedItems.map((item) => ({
-                    PutRequest: {
-                        Item: item,
-                    },
-                })),
-            };
-            return (0, builders_1.createBatchWriteBuilder)(requestItems, client, logger);
-        },
-    };
-};
-exports.createEntityAPI = createEntityAPI;