@ftschopp/dynatable-core 1.4.2 → 1.4.3

package/src/core/types.ts

@@ -1,366 +0,0 @@
-/* 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 --------------------
-
-/**
- * Scalar attribute definition (String, Number, Boolean, Date)
- */
-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
- *
- * @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 = {
-  timestamps?: boolean;
-  cleanInternalKeys?: 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;
-};
-
-/**
- * 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;
-
-/**
- * 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
- * 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]>;
-} & {
-  [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]>;
-};
-
-/**
- * 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]>;
-};
-
-/**
- * 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;
-};
-
-/**
- * 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

@@ -1,224 +0,0 @@
-/* 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';
-import { Condition } from '@/builders/shared/types';
-
-/**
- * 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 (including GSI index keys)
-      const fullKey = resolveKeys(model, withDefaults, 'both');
-
-      // 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() {
-      // Auto-filter by entity type so query() only returns items for this
-      // entity. Without this, queries on shared GSIs return items from other
-      // entities that share the same partition key.
-      return createQueryBuilder<InferModel<Model>>(tableName, client, model, logger, modelName);
-    },
-
-    scan() {
-      // Auto-filter by entity type so scan only returns items for this entity
-      const typeFilter: Condition = {
-        expression: '#_type = :_type',
-        names: { '#_type': '_type' },
-        values: { ':_type': modelName },
-      };
-
-      const builder = createScanBuilder<InferModel<Model>>(
-        tableName,
-        client,
-        [typeFilter],
-        [],
-        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,
-        // Carry the original template-vars-bearing key (e.g. { username: 'jane' })
-        // so the builder can recompute index keys when .set() touches their template fields.
-        { model, keyVars: key as Record<string, unknown> }
-      );
-
-      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 (including GSI index keys)
-        const fullKey = resolveKeys(model, withDefaults, 'both');
-
-        // 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

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

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

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

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