@ftschopp/dynatable-core 1.0.0

package/dist/utils/dynamodb-logger.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Configuration for DynamoDB operation logging
+ */
+export interface DynamoDBLoggerConfig {
+    /**
+     * Enable/disable logging. Default: false
+     */
+    enabled: boolean;
+    /**
+     * Log the request parameters. Default: true
+     */
+    logParams?: boolean;
+    /**
+     * Log the response data. Default: false
+     */
+    logResponse?: boolean;
+    /**
+     * Custom logger function. Default: console.log
+     */
+    loggerFn?: (message: string) => void;
+}
+/**
+ * DynamoDB Logger interface
+ */
+export type DynamoDBLogger = {
+    /**
+     * Log a DynamoDB operation with its parameters and optionally the response
+     */
+    log: <TParams, TResponse>(operationName: string, params: TParams, response?: TResponse) => void;
+};
+/**
+ * Creates a DynamoDB logger instance with the given configuration
+ * This is the main factory function for creating loggers
+ *
+ * @example Basic logger with request parameters only
+ * ```typescript
+ * const logger = createDynamoDBLogger({
+ *   enabled: true,
+ *   logParams: true,
+ *   logResponse: false,
+ * });
+ * ```
+ *
+ * @example Full logging (params + response)
+ * ```typescript
+ * const logger = createDynamoDBLogger({
+ *   enabled: true,
+ *   logParams: true,
+ *   logResponse: true,
+ * });
+ * ```
+ *
+ * @example Using with a table
+ * ```typescript
+ * const logger = createDynamoDBLogger({
+ *   enabled: true,
+ *   logParams: true,
+ *   logResponse: true,
+ * });
+ *
+ * const userTable = createTable({
+ *   tableName: 'Users',
+ *   client: dynamoDBClient,
+ *   schema: userSchema,
+ *   logger, // Pass logger to table
+ * });
+ *
+ * // Operations will be logged automatically
+ * const user = await userTable.get({ username: 'johndoe' }).execute();
+ * ```
+ *
+ * @example Custom logger function (Winston, Pino, etc.)
+ * ```typescript
+ * import winston from 'winston';
+ *
+ * const winstonLogger = winston.createLogger({
+ *   level: 'info',
+ *   format: winston.format.json(),
+ *   transports: [new winston.transports.Console()],
+ * });
+ *
+ * const logger = createDynamoDBLogger({
+ *   enabled: true,
+ *   logParams: true,
+ *   logResponse: true,
+ *   loggerFn: (message) => winstonLogger.info(message),
+ * });
+ * ```
+ *
+ * @example Output format
+ * ```
+ * ================================================================================
+ * [DynamoDB] GetCommand - 2025-12-29T10:30:45.123Z
+ * ================================================================================
+ *
+ * 📤 Request Parameters:
+ * {
+ *   "TableName": "Users",
+ *   "Key": {
+ *     "PK": "USER#johndoe",
+ *     "SK": "PROFILE"
+ *   }
+ * }
+ *
+ * 📥 Response:
+ * {
+ *   "Item": {
+ *     "PK": "USER#johndoe",
+ *     "SK": "PROFILE",
+ *     "username": "johndoe",
+ *     "email": "john@example.com"
+ *   }
+ * }
+ * ================================================================================
+ * ```
+ */
+export declare const createDynamoDBLogger: (config: DynamoDBLoggerConfig) => DynamoDBLogger;
+//# sourceMappingURL=dynamodb-logger.d.ts.map

package/dist/utils/dynamodb-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamodb-logger.d.ts","sourceRoot":"","sources":["../../src/utils/dynamodb-logger.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;OAEG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;OAEG;IACH,GAAG,EAAE,CAAC,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS,KAAK,IAAI,CAAC;CACjG,CAAC;AAkCF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AACH,eAAO,MAAM,oBAAoB,GAAI,QAAQ,oBAAoB,KAAG,cAmBnE,CAAC"}

package/dist/utils/dynamodb-logger.js

@@ -0,0 +1,125 @@
+"use strict";
+/* eslint-disable @typescript-eslint/no-explicit-any */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDynamoDBLogger = void 0;
+/**
+ * Pure function to format log message
+ * This function has no side effects and is easily testable
+ */
+const formatLogMessage = (operationName, timestamp, params, response, config) => {
+    const parts = [
+        '\n' + '='.repeat(80),
+        `[DynamoDB] ${operationName} - ${timestamp}`,
+        '='.repeat(80),
+    ];
+    if (config.logParams && params) {
+        parts.push('\n📤 Request Parameters:');
+        parts.push(JSON.stringify(params, null, 2));
+    }
+    if (config.logResponse && response) {
+        parts.push('\n📥 Response:');
+        parts.push(JSON.stringify(response, null, 2));
+    }
+    parts.push('='.repeat(80) + '\n');
+    return parts.join('\n');
+};
+/**
+ * Creates a DynamoDB logger instance with the given configuration
+ * This is the main factory function for creating loggers
+ *
+ * @example Basic logger with request parameters only
+ * ```typescript
+ * const logger = createDynamoDBLogger({
+ *   enabled: true,
+ *   logParams: true,
+ *   logResponse: false,
+ * });
+ * ```
+ *
+ * @example Full logging (params + response)
+ * ```typescript
+ * const logger = createDynamoDBLogger({
+ *   enabled: true,
+ *   logParams: true,
+ *   logResponse: true,
+ * });
+ * ```
+ *
+ * @example Using with a table
+ * ```typescript
+ * const logger = createDynamoDBLogger({
+ *   enabled: true,
+ *   logParams: true,
+ *   logResponse: true,
+ * });
+ *
+ * const userTable = createTable({
+ *   tableName: 'Users',
+ *   client: dynamoDBClient,
+ *   schema: userSchema,
+ *   logger, // Pass logger to table
+ * });
+ *
+ * // Operations will be logged automatically
+ * const user = await userTable.get({ username: 'johndoe' }).execute();
+ * ```
+ *
+ * @example Custom logger function (Winston, Pino, etc.)
+ * ```typescript
+ * import winston from 'winston';
+ *
+ * const winstonLogger = winston.createLogger({
+ *   level: 'info',
+ *   format: winston.format.json(),
+ *   transports: [new winston.transports.Console()],
+ * });
+ *
+ * const logger = createDynamoDBLogger({
+ *   enabled: true,
+ *   logParams: true,
+ *   logResponse: true,
+ *   loggerFn: (message) => winstonLogger.info(message),
+ * });
+ * ```
+ *
+ * @example Output format
+ * ```
+ * ================================================================================
+ * [DynamoDB] GetCommand - 2025-12-29T10:30:45.123Z
+ * ================================================================================
+ *
+ * 📤 Request Parameters:
+ * {
+ *   "TableName": "Users",
+ *   "Key": {
+ *     "PK": "USER#johndoe",
+ *     "SK": "PROFILE"
+ *   }
+ * }
+ *
+ * 📥 Response:
+ * {
+ *   "Item": {
+ *     "PK": "USER#johndoe",
+ *     "SK": "PROFILE",
+ *     "username": "johndoe",
+ *     "email": "john@example.com"
+ *   }
+ * }
+ * ================================================================================
+ * ```
+ */
+const createDynamoDBLogger = (config) => {
+    const logFn = config.loggerFn || console.log;
+    return {
+        log: (operationName, params, response) => {
+            if (!config.enabled) {
+                return;
+            }
+            const timestamp = new Date().toISOString();
+            const message = formatLogMessage(operationName, timestamp, params, response, config);
+            logFn(message);
+        },
+    };
+};
+exports.createDynamoDBLogger = createDynamoDBLogger;

package/dist/utils/model-utils.d.ts

@@ -0,0 +1,24 @@
+import { InferModel, ModelDefinition } from '@/core/types';
+/**
+ * Extracts all variable names from a template string
+ * @param template - Template string with ${variable} syntax
+ * @returns Array of variable names found in the template
+ */
+export declare const extractTemplateVars: (template: string) => string[];
+/**
+ * Resolves a string template with provided data
+ * @throws Error if any required template variable is missing from data
+ */
+export declare const resolveTemplate: (template: string, data: Record<string, any>) => string;
+/**
+ * Resolves all keys or indexes for a model
+ */
+export declare const resolveKeys: <M extends ModelDefinition>(model: M, input: Record<string, any>, type?: "key" | "index" | "both") => Record<string, string>;
+/**
+ * Applies default and generated values to validated input
+ */
+export declare const applyPostDefaults: <M extends ModelDefinition>(model: M, validatedItem: Record<string, any>, options?: {
+    isUpdate?: boolean;
+    timestamps?: boolean;
+}) => InferModel<M>;
+//# sourceMappingURL=model-utils.d.ts.map

package/dist/utils/model-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-utils.d.ts","sourceRoot":"","sources":["../../src/utils/model-utils.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAiB,eAAe,EAAE,MAAM,cAAc,CAAC;AAG1E;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAI,UAAU,MAAM,KAAG,MAAM,EAG5D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAI,UAAU,MAAM,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAG,MAoB7E,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,eAAe,EACnD,OAAO,CAAC,EACR,OAAO,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC1B,OAAM,KAAK,GAAG,OAAO,GAAG,MAAc,KACrC,MAAM,CAAC,MAAM,EAAE,MAAM,CAWvB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,eAAe,EACzD,OAAO,CAAC,EACR,eAAe,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAClC,UAAU;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,KACrD,UAAU,CAAC,CAAC,CAgCd,CAAC"}

package/dist/utils/model-utils.js

@@ -0,0 +1,88 @@
+"use strict";
+/* eslint-disable @typescript-eslint/no-explicit-any */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyPostDefaults = exports.resolveKeys = exports.resolveTemplate = exports.extractTemplateVars = void 0;
+const ulid_1 = require("ulid");
+/**
+ * Extracts all variable names from a template string
+ * @param template - Template string with ${variable} syntax
+ * @returns Array of variable names found in the template
+ */
+const extractTemplateVars = (template) => {
+    const matches = template.matchAll(/\${(.*?)}/g);
+    return Array.from(matches, (m) => m[1]).filter((v) => v !== undefined);
+};
+exports.extractTemplateVars = extractTemplateVars;
+/**
+ * Resolves a string template with provided data
+ * @throws Error if any required template variable is missing from data
+ */
+const resolveTemplate = (template, data) => {
+    const missing = [];
+    const result = template.replace(/\${(.*?)}/g, (_, key) => {
+        const value = data[key];
+        if (value === undefined) {
+            missing.push(key);
+            return `\${${key}}`; // Keep placeholder for error message
+        }
+        return String(value);
+    });
+    if (missing.length > 0) {
+        throw new Error(`Missing required field(s) for key template: ${missing.join(', ')}. ` +
+            `Template: "${template}"`);
+    }
+    return result;
+};
+exports.resolveTemplate = resolveTemplate;
+/**
+ * Resolves all keys or indexes for a model
+ */
+const resolveKeys = (model, input, type = 'key') => {
+    const out = {};
+    const process = (keys) => {
+        if (!keys)
+            return;
+        for (const [k, def] of Object.entries(keys)) {
+            out[k] = (0, exports.resolveTemplate)(def.value, input);
+        }
+    };
+    if (type === 'key' || type === 'both')
+        process(model.key);
+    if (type === 'index' || type === 'both')
+        process(model.index);
+    return out;
+};
+exports.resolveKeys = resolveKeys;
+/**
+ * Applies default and generated values to validated input
+ */
+const applyPostDefaults = (model, validatedItem, options) => {
+    const result = { ...validatedItem };
+    for (const [key, attr] of Object.entries(model.attributes)) {
+        if (result[key] === undefined) {
+            if (attr.generate === 'ulid') {
+                result[key] = (0, ulid_1.ulid)();
+            }
+            else if (attr.generate === 'uuid') {
+                result[key] = crypto.randomUUID();
+            }
+            else if (attr.default !== undefined) {
+                result[key] = typeof attr.default === 'function' ? attr.default() : attr.default;
+            }
+        }
+    }
+    // Apply timestamps if enabled
+    const enableTimestamps = options?.timestamps ?? false;
+    const isUpdate = options?.isUpdate ?? false;
+    if (enableTimestamps) {
+        const now = new Date().toISOString();
+        // Only set createdAt on new items (not updates)
+        if (!isUpdate && result.createdAt === undefined) {
+            result.createdAt = now;
+        }
+        // Always set updatedAt
+        result.updatedAt = now;
+    }
+    return result;
+};
+exports.applyPostDefaults = applyPostDefaults;

package/dist/utils/zod-utils.d.ts

@@ -0,0 +1,13 @@
+import { AttributeDefinition, ModelDefinition } from '@/core/types';
+import { ZodObject, ZodType } from 'zod';
+/**
+ * Converts an attribute definition to a Zod schema type
+ */
+export declare const typeToZod: (attr: AttributeDefinition) => ZodType;
+/**
+ * Converts a model definition to a Zod object schema
+ * Uses passthrough mode to allow additional fields like createdAt/updatedAt
+ * that are added by applyPostDefaults when timestamps are enabled
+ */
+export declare const modelToZod: (model: ModelDefinition) => ZodObject<any>;
+//# sourceMappingURL=zod-utils.d.ts.map

package/dist/utils/zod-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-utils.d.ts","sourceRoot":"","sources":["../../src/utils/zod-utils.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpE,OAAO,EAAK,SAAS,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAE5C;;GAEG;AACH,eAAO,MAAM,SAAS,GAAI,MAAM,mBAAmB,KAAG,OAarD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO,eAAe,KAAG,SAAS,CAAC,GAAG,CAMhE,CAAC"}

package/dist/utils/zod-utils.js

@@ -0,0 +1,35 @@
+"use strict";
+/* eslint-disable @typescript-eslint/no-explicit-any */
+// -------------------- Zod Conversion --------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.modelToZod = exports.typeToZod = void 0;
+const zod_1 = require("zod");
+/**
+ * Converts an attribute definition to a Zod schema type
+ */
+const typeToZod = (attr) => {
+    const zodType = attr.type === String
+        ? zod_1.z.string()
+        : attr.type === Number
+            ? zod_1.z.number()
+            : attr.type === Boolean
+                ? zod_1.z.boolean()
+                : attr.type === Date
+                    ? zod_1.z.date()
+                    : zod_1.z.unknown();
+    return attr.required ? zodType : zodType.optional();
+};
+exports.typeToZod = typeToZod;
+/**
+ * Converts a model definition to a Zod object schema
+ * Uses passthrough mode to allow additional fields like createdAt/updatedAt
+ * that are added by applyPostDefaults when timestamps are enabled
+ */
+const modelToZod = (model) => {
+    const shape = {};
+    for (const [key, attr] of Object.entries(model.attributes)) {
+        shape[key] = (0, exports.typeToZod)(attr);
+    }
+    return zod_1.z.object(shape).passthrough();
+};
+exports.modelToZod = modelToZod;

package/eslint.config.mjs

@@ -0,0 +1,4 @@
+import { config } from "@repo/eslint-config/react-internal";
+
+/** @type {import("eslint").Linter.Config} */
+export default config;

package/jest.config.js

@@ -0,0 +1,11 @@
+/** @type {import('jest').Config} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  testMatch: ['**/?(*.)+(test).[tj]s'],
+  testPathIgnorePatterns: ['/node_modules/', '/dist/'],
+  roots: ['<rootDir>/src', '<rootDir>/tests'],
+  moduleNameMapper: {
+    '^@/(.*)$': '<rootDir>/src/$1',
+  },
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@ftschopp/dynatable-core",
+  "version": "1.0.0",
+  "description": "Core library for DynamoDB single table design",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf .turbo && rm -rf node_modules && rm -rf dist",
+    "test": "jest"
+  },
+  "devDependencies": {
+    "@repo/eslint-config": "*",
+    "@repo/typescript-config": "*",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.0.3",
+    "aws-sdk-client-mock": "^4.1.0",
+    "eslint": "^9.39.2",
+    "jest": "^30.2.0",
+    "ts-jest": "^29.4.6",
+    "ts-node": "^10.9.2",
+    "typescript": "5.9.3"
+  },
+  "dependencies": {
+    "@aws-sdk/client-dynamodb": "^3.965.0",
+    "@aws-sdk/lib-dynamodb": "^3.965.0",
+    "@aws-sdk/util-dynamodb": "^3.965.0",
+    "@types/ramda": "^0.31.1",
+    "ramda": "^0.32.0",
+    "ulid": "^3.0.2",
+    "zod": "^4.3.5"
+  }
+}