@ftschopp/dynatable-core 1.0.0 → 1.2.0

package/src/core/types.ts

@@ -28,20 +28,68 @@
 // -------------------- Type Definitions --------------------
 
 /**
- * Attribute definition for model attributes
- *
- * @property type - The JavaScript constructor for the attribute type
- * @property [required] - Whether the attribute is required
- * @property [generate] - Auto-generation strategy ('ulid', 'uuid')
- * @property [default] - Default value or generator function
+ * Scalar attribute definition (String, Number, Boolean, Date)
  */
-export type AttributeDefinition = {
+export type ScalarAttributeDefinition = {
   type: StringConstructor | NumberConstructor | BooleanConstructor | DateConstructor;
   required?: boolean;
   generate?: 'ulid' | 'uuid';
   default?: any;
+  nulls?: boolean;
+};
+
+/**
+ * Object attribute definition with a nested schema
+ *
+ * @example
+ * address: {
+ *   type: Object,
+ *   schema: {
+ *     street: { type: String },
+ *     city: { type: String, required: true },
+ *   }
+ * }
+ */
+export type ObjectAttributeDefinition = {
+  type: ObjectConstructor;
+  schema: Record<string, AttributeDefinition>;
+  required?: boolean;
+  default?: any;
+  nulls?: boolean;
 };
 
+/**
+ * Array attribute definition with a typed items schema
+ *
+ * @example
+ * history: {
+ *   type: Array,
+ *   default: [],
+ *   items: {
+ *     type: Object,
+ *     schema: {
+ *       date: { type: String },
+ *       status: { type: String },
+ *     }
+ *   }
+ * }
+ */
+export type ArrayAttributeDefinition = {
+  type: ArrayConstructor;
+  items: AttributeDefinition;
+  required?: boolean;
+  default?: any;
+  nulls?: boolean;
+};
+
+/**
+ * Attribute definition for model attributes — supports scalars, nested objects, and arrays
+ */
+export type AttributeDefinition =
+  | ScalarAttributeDefinition
+  | ObjectAttributeDefinition
+  | ArrayAttributeDefinition;
+
 /**
  * Key definition for primary and secondary indexes
  *
@@ -95,6 +143,7 @@ export type ModelDefinition = {
 export type SchemaParams = {
   isoDates?: boolean;
   timestamps?: boolean;
+  cleanInternalKeys?: boolean;
 };
 
 /**
@@ -113,17 +162,34 @@ export type SchemaDefinition = {
   params?: SchemaParams;
 };
 
-type InferAttr<T> = T extends StringConstructor
-  ? string
-  : T extends NumberConstructor
-    ? number
-    : T extends BooleanConstructor
-      ? boolean
-      : T extends DateConstructor
-        ? Date
-        : unknown;
+/**
+ * Recursively infers the TypeScript type from an AttributeDefinition.
+ * - Object → infers the nested schema shape
+ * - Array  → infers an array of the items type
+ * - Scalars → maps to the corresponding primitive
+ */
+type InferAttr<A> = A extends { type: ObjectConstructor; schema: infer S }
+  ? InferObjectSchema<S>
+  : A extends { type: ArrayConstructor; items: infer I }
+    ? Array<InferAttr<I>>
+    : A extends { type: StringConstructor }
+      ? string
+      : A extends { type: NumberConstructor }
+        ? number
+        : A extends { type: BooleanConstructor }
+          ? boolean
+          : A extends { type: DateConstructor }
+            ? Date
+            : unknown;
 
-type IsOptional<T> = undefined extends T ? true : false;
+/**
+ * Infers the shape of a nested object schema, respecting required/optional fields.
+ */
+type InferObjectSchema<S> = {
+  [K in keyof S as S[K] extends { required: true } ? K : never]: InferAttr<S[K]>;
+} & {
+  [K in keyof S as S[K] extends { required: true } ? never : K]?: InferAttr<S[K]>;
+};
 
 /**
  * Non-generated attributes for input
@@ -134,7 +200,7 @@ type NonGeneratedAttributes<M extends ModelDefinition> = {
     ? never
     : M['attributes'][K] extends { required: true }
       ? K
-      : never]: InferAttr<M['attributes'][K]['type']>;
+      : never]: InferAttr<M['attributes'][K]>;
 } & {
   [K in keyof M['attributes'] as M['attributes'][K] extends { generate: string }
     ? never
@@ -142,7 +208,7 @@ type NonGeneratedAttributes<M extends ModelDefinition> = {
       ? K
       : M['attributes'][K] extends { required: true }
         ? never
-        : K]?: InferAttr<M['attributes'][K]['type']>;
+        : K]?: InferAttr<M['attributes'][K]>;
 };
 
 /**
@@ -151,7 +217,7 @@ type NonGeneratedAttributes<M extends ModelDefinition> = {
 type GeneratedAttributes<M extends ModelDefinition> = {
   [K in keyof M['attributes'] as M['attributes'][K] extends { generate: string }
     ? K
-    : never]: InferAttr<M['attributes'][K]['type']>;
+    : never]: InferAttr<M['attributes'][K]>;
 };
 
 /**
@@ -288,3 +354,14 @@ type KeyTemplateVars<M extends ModelDefinition> = PrimaryKeyVars<M>;
 export type InferKeyInput<M extends ModelDefinition> = {
   [K in KeyTemplateVars<M>]: string;
 };
+
+/**
+ * Extracts the item type from an array attribute.
+ *
+ * @example
+ * type StoryFrame = ArrayItem<StoryEntity['frames']>;
+ * // → { url: string; duration?: number; mediaType?: string }
+ *
+ * type HistoryEntry = ArrayItem<TransactionEntity['history']>;
+ */
+export type ArrayItem<T extends readonly unknown[] | undefined> = NonNullable<T>[number];

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/index.ts

@@ -14,6 +14,7 @@ export {
   type InferModelFromSchema,
   type InferInputFromSchema,
   type TimestampFields,
+  type ArrayItem,
 } from './core/types';
 export {
   createDynamoDBLogger,

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,
       });
     }