@ftschopp/dynatable-core 1.0.0

package/src/core/types.ts

@@ -0,0 +1,290 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/**
+ * Type definitions for DynamoDB schema and model inference
+ *
+ * Provides comprehensive type utilities for:
+ * - Defining DynamoDB table schemas with primary and secondary indexes
+ * - Inferring strongly-typed input and output models from schema definitions
+ * - Automatic key generation and template variable extraction
+ * - Type-safe attribute handling with support for defaults and auto-generation
+ *
+ * @example
+ * ```typescript
+ * const schema: SchemaDefinition = {
+ *   format: 'dynatable:1.0.0',
+ *   version: '1.0.0',
+ *   indexes: { primary: { hash: "PK", sort: "SK" } },
+ *   models: {
+ *     User: {
+ *       key: { PK: { type: String, value: "USER#${id}" }, SK: { type: String, value: "PROFILE" } },
+ *       attributes: { id: { type: String, required: true }, name: { type: String } }
+ *     }
+ *   }
+ * };
+ * ```
+ */
+
+// -------------------- 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
+ */
+export type AttributeDefinition = {
+  type: StringConstructor | NumberConstructor | BooleanConstructor | DateConstructor;
+  required?: boolean;
+  generate?: 'ulid' | 'uuid';
+  default?: any;
+};
+
+/**
+ * Key definition for primary and secondary indexes
+ *
+ * @property type - Always String for DynamoDB keys
+ * @property value - Template string for key generation
+ */
+export type KeyDefinition = {
+  type: StringConstructor;
+  value: string;
+};
+
+/**
+ * Primary key definition - requires both PK and SK (uppercase)
+ */
+export type PrimaryKeyDefinition = {
+  PK: KeyDefinition;
+  SK: KeyDefinition;
+};
+
+/**
+ * Index definition with hash and optional sort key
+ */
+export type IndexDefinition = {
+  hash: string;
+  sort?: string;
+};
+
+/**
+ * Indexes configuration - requires at least a primary index
+ */
+export type IndexesDefinition = {
+  primary: IndexDefinition;
+  [indexName: string]: IndexDefinition;
+};
+
+/**
+ * Model definition containing keys, indexes, and attributes
+ * - key: REQUIRED, must have pk and sk
+ * - attributes: REQUIRED, model attributes
+ * - index: OPTIONAL, secondary index keys
+ */
+export type ModelDefinition = {
+  key: PrimaryKeyDefinition;
+  index?: Record<string, KeyDefinition>;
+  attributes: Record<string, AttributeDefinition>;
+};
+
+/**
+ * Schema parameters configuration
+ */
+export type SchemaParams = {
+  isoDates?: boolean;
+  timestamps?: boolean;
+};
+
+/**
+ * Complete schema definition for a DynamoDB table
+ * - format: Table schema format version (e.g., "dynatable:1.0.0")
+ * - version: Schema version (e.g., "1.0.0")
+ * - indexes: Index definitions (requires at least 'primary')
+ * - models: Model definitions (each requires 'key' and 'attributes')
+ * - params: Optional schema parameters
+ */
+export type SchemaDefinition = {
+  format: string;
+  version: string;
+  indexes: IndexesDefinition;
+  models: Record<string, ModelDefinition>;
+  params?: SchemaParams;
+};
+
+type InferAttr<T> = T extends StringConstructor
+  ? string
+  : T extends NumberConstructor
+    ? number
+    : T extends BooleanConstructor
+      ? boolean
+      : T extends DateConstructor
+        ? Date
+        : unknown;
+
+type IsOptional<T> = undefined extends T ? true : false;
+
+/**
+ * Non-generated attributes for input
+ * Splits into required and optional based on the 'required' field
+ */
+type NonGeneratedAttributes<M extends ModelDefinition> = {
+  [K in keyof M['attributes'] as M['attributes'][K] extends { generate: string }
+    ? never
+    : M['attributes'][K] extends { required: true }
+      ? K
+      : never]: InferAttr<M['attributes'][K]['type']>;
+} & {
+  [K in keyof M['attributes'] as M['attributes'][K] extends { generate: string }
+    ? never
+    : M['attributes'][K] extends { required: false }
+      ? K
+      : M['attributes'][K] extends { required: true }
+        ? never
+        : K]?: InferAttr<M['attributes'][K]['type']>;
+};
+
+/**
+ * Generated-only attributes for internal use
+ */
+type GeneratedAttributes<M extends ModelDefinition> = {
+  [K in keyof M['attributes'] as M['attributes'][K] extends { generate: string }
+    ? K
+    : never]: InferAttr<M['attributes'][K]['type']>;
+};
+
+/**
+ * Template string variable extraction
+ */
+type ExtractTemplateVars<S extends string> = S extends `${string}\${${infer Var}}${infer Rest}`
+  ? Var | ExtractTemplateVars<Rest>
+  : never;
+
+/**
+ * Extract template variables from primary keys (PK and SK)
+ */
+type PrimaryKeyVars<M extends ModelDefinition> =
+  | ExtractTemplateVars<M['key']['PK']['value']>
+  | ExtractTemplateVars<M['key']['SK']['value']>;
+
+/**
+ * Extract template variables from index keys (if they exist)
+ */
+type IndexKeyVars<M extends ModelDefinition> =
+  M['index'] extends Record<string, KeyDefinition>
+    ? {
+        [K in keyof M['index']]: ExtractTemplateVars<M['index'][K]['value']>;
+      }[keyof M['index']]
+    : never;
+
+/**
+ * Extract all template variables from primary and index keys
+ */
+type KeyVars<M extends ModelDefinition> = PrimaryKeyVars<M> | IndexKeyVars<M>;
+
+type IsGenerated<M extends ModelDefinition, K extends string> = K extends keyof M['attributes']
+  ? M['attributes'][K] extends { generate: string }
+    ? true
+    : false
+  : false;
+
+type FilterNonGeneratedKeyVars<
+  M extends ModelDefinition,
+  K extends string = KeyVars<M>,
+> = K extends string ? (IsGenerated<M, K> extends true ? never : K) : never;
+
+/**
+ * Keys required in input
+ */
+type RequiredKeys<M extends ModelDefinition> = {
+  [K in keyof NonGeneratedAttributes<M>]: M['attributes'][K] extends {
+    required: true;
+  }
+    ? K
+    : never;
+}[keyof NonGeneratedAttributes<M>];
+
+/**
+ * Input type used for put/update
+ *
+ * @deprecated Use InferInputFromSchema when possible to get timestamp inference
+ */
+export type InferInput<M extends ModelDefinition> = {
+  [K in keyof NonGeneratedAttributes<M> as K extends RequiredKeys<M>
+    ? K
+    : never]: NonGeneratedAttributes<M>[K];
+} & {
+  [K in keyof NonGeneratedAttributes<M> as K extends RequiredKeys<M>
+    ? never
+    : K]?: NonGeneratedAttributes<M>[K];
+} & {
+  [K in FilterNonGeneratedKeyVars<M>]: string;
+};
+
+/**
+ * Infers the input type from a complete schema definition
+ * When timestamps are enabled, createdAt and updatedAt are NOT included (auto-generated)
+ */
+export type InferInputFromSchema<
+  S extends SchemaDefinition,
+  ModelName extends keyof S['models'],
+> = InferInput<S['models'][ModelName]>;
+
+/**
+ * Full model type after applying defaults and keys
+ */
+type ModelAttributes<M extends ModelDefinition> = NonGeneratedAttributes<M> &
+  GeneratedAttributes<M>;
+
+/**
+ * Timestamp fields that are automatically added when timestamps are enabled
+ */
+export type TimestampFields = {
+  createdAt: string;
+  updatedAt: string;
+};
+
+/**
+ * Infers the model type without exposing internal DynamoDB keys (PK, SK, GSI1PK, etc.)
+ * Only includes business attributes and generated fields
+ *
+ * @deprecated Use InferModelFromSchema when possible to get timestamp inference
+ */
+export type InferModel<M extends ModelDefinition> = ModelAttributes<M>;
+
+/**
+ * Infers the model type from a complete schema definition
+ * Automatically includes timestamp fields (createdAt, updatedAt) when params.timestamps is true
+ */
+export type InferModelFromSchema<
+  S extends SchemaDefinition,
+  ModelName extends keyof S['models'],
+> = S['params'] extends { timestamps: true }
+  ? ModelAttributes<S['models'][ModelName]> & TimestampFields
+  : ModelAttributes<S['models'][ModelName]>;
+
+/**
+ * Internal type that includes DynamoDB keys - used internally by builders
+ * Includes pk, sk, and any index keys
+ * @internal
+ */
+export type InferModelWithKeys<M extends ModelDefinition> = ModelAttributes<M> & {
+  [K in keyof M['key']]: string;
+} & (M['index'] extends Record<string, KeyDefinition>
+    ? {
+        [K in keyof M['index']]: string;
+      }
+    : Record<string, never>);
+
+/**
+ * Extract template variables from primary keys only
+ */
+type KeyTemplateVars<M extends ModelDefinition> = PrimaryKeyVars<M>;
+
+/**
+ * Input for get/delete operations (only key template vars)
+ */
+export type InferKeyInput<M extends ModelDefinition> = {
+  [K in KeyTemplateVars<M>]: string;
+};

package/src/entity.ts

@@ -0,0 +1,337 @@
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { InferInput, InferKeyInput, InferModel, ModelDefinition } from './core/types';
+import { applyPostDefaults, resolveKeys, extractTemplateVars } from './utils/model-utils';
+import { modelToZod } from './utils/zod-utils';
+import {
+  createGetBuilder,
+  createPutBuilder,
+  createQueryBuilder,
+  createUpdateBuilder,
+  createDeleteBuilder,
+  createScanBuilder,
+  createBatchGetBuilder,
+  createBatchWriteBuilder,
+  GetBuilder,
+  PutBuilder,
+  QueryBuilder,
+  UpdateBuilder,
+  DeleteBuilder,
+  ScanBuilder,
+  BatchGetBuilder,
+  BatchWriteBuilder,
+  WriteRequest,
+} from './builders';
+import { DynamoDBLogger } from './utils/dynamodb-logger';
+
+/**
+ * Options for creating the Entity API
+ */
+export type EntityAPIOptions = {
+  logger?: DynamoDBLogger;
+  timestamps?: boolean;
+};
+
+/**
+ * Entity API interface for a model
+ */
+export type EntityAPI<Model, Input, KeyInput, ModelDef extends ModelDefinition = any> = {
+  /**
+   * 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, ModelDef>;
+
+  /**
+   * 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;
+};
+
+/**
+ * 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
+ */
+export const createEntityAPI = <Model extends ModelDefinition>(
+  tableName: string,
+  modelName: string,
+  model: Model,
+  client: DynamoDBClient,
+  options: EntityAPIOptions = {}
+): EntityAPI<InferModel<Model>, InferInput<Model>, InferKeyInput<Model>, Model> => {
+  const { logger, timestamps = false } = options;
+
+  // Build a Zod schema from the model
+  const zodSchema = modelToZod(model);
+
+  return {
+    get(key) {
+      // 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 keyRecord = key as Record<string, unknown>;
+      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 = resolveKeys(model, key);
+
+      return createGetBuilder<InferKeyInput<Model>, InferModel<Model>>(
+        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 = 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() {
+      return createQueryBuilder<InferModel<Model>, Model>(tableName, client, model, logger);
+    },
+
+    scan() {
+      return createScanBuilder<InferModel<Model>>(
+        tableName,
+        client,
+        [],
+        [],
+        undefined,
+        false,
+        undefined,
+        undefined,
+        undefined,
+        logger
+      );
+    },
+
+    update(key) {
+      // 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 keyRecord = key as Record<string, unknown>;
+      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 = resolveKeys(model, key);
+
+      return createUpdateBuilder<InferModel<Model>>(
+        tableName,
+        fullKey as Partial<InferModel<Model>>,
+        client,
+        [],
+        { set: [], remove: [], add: [], delete: [] },
+        'NONE',
+        0,
+        timestamps,
+        logger
+      );
+    },
+
+    delete(key) {
+      // 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 keyRecord = key as Record<string, unknown>;
+      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 = resolveKeys(model, key);
+
+      return createDeleteBuilder<InferModel<Model>>(
+        tableName,
+        fullKey as Partial<InferModel<Model>>,
+        client,
+        [],
+        'NONE',
+        logger
+      );
+    },
+
+    batchGet(keys) {
+      // 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));
+        }
+      }
+
+      // Process all keys and validate them
+      const resolvedKeys = keys.map((key) => {
+        // Check if all required fields are present
+        const keyRecord = key as Record<string, unknown>;
+        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 resolveKeys(model, key);
+      });
+
+      // Create the request items in the format expected by BatchGetItem
+      const requestItems = {
+        [tableName]: {
+          Keys: resolvedKeys,
+        },
+      };
+
+      return createBatchGetBuilder<InferModel<Model>>(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 = 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/index.ts

@@ -0,0 +1,22 @@
+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,
+} from './core/types';
+export {
+  createDynamoDBLogger,
+  type DynamoDBLogger,
+  type DynamoDBLoggerConfig,
+} from './utils/dynamodb-logger';