Serialization Helpers

Overview

The MBC CQRS Serverless Framework provides helper functions for converting between internal DynamoDB structures and external flat structures. These helpers ensure consistent data transformation while maintaining type safety.

Data Structure Conversion

Internal DynamoDB Structure

{
  pk: "PROJECT",
  sk: "123",
  name: "Test Project",
  attributes: {
    details: {
      status: "active",
      category: "development"
    }
  }
}

External Flat Structure

{
  id: "PROJECT#123",    // Combination of pk and sk
  code: "123",         // Mainly sk
  name: "Test Project", // First level in DynamoDB
  details: {           // Flattened from attributes
    status: "active",
    category: "development"
  }
}

Usage

Converting Internal to External Format

import { serializeToExternal } from '@mbc-cqrs-serverless/core';

const internal = {
  pk: "PROJECT",
  sk: "123",
  name: "Test Project",
  attributes: {
    details: {
      status: "active",
      category: "development"
    }
  }
};

const external = serializeToExternal(internal);

Converting External to Internal Format

import { deserializeToInternal, DataEntity } from '@mbc-cqrs-serverless/core';

const external = {
  id: "PROJECT#123",
  code: "123",
  name: "Test Project",
  details: {
    status: "active",
    category: "development"
  }
};

// Use DataEntity for data table entities, CommandEntity for command table entities
const internal = deserializeToInternal(external, DataEntity);

Fallback Behavior

When deserializing, if the id field doesn't contain the # separator to split into pk and sk, the code field is used as the sk value. Any fields not in the metadata field list are automatically placed in the attributes object.

API Reference

serializeToExternal

function serializeToExternal<T extends CommandEntity | DataEntity>(
  item: T | null | undefined,
  options?: SerializerOptions
): Record<string, any> | null

interface SerializerOptions {
  keepAttributes?: boolean;  // Reserved for future use
  flattenDepth?: number;     // Reserved for future use
}

Parameters:

• item: Internal entity (CommandEntity or DataEntity).
• options: Optional serialization options (reserved for future use).

Returns:

• Flattened external structure or null if input is null/undefined

note

The SerializerOptions interface is defined for future extensibility but is not currently used by the function. The function always flattens attributes to the top level.

deserializeToInternal

function deserializeToInternal<T extends CommandEntity | DataEntity>(
  data: Record<string, any> | null | undefined,
  EntityClass: new () => T
): T | null

Parameters:

• data: External flat structure
• EntityClass: Entity class to instantiate (CommandEntity or DataEntity)

Returns:

• Internal entity instance or null if input is null/undefined

Field Mapping

Metadata Fields

Field	Description
id	Primary key
cpk	Command table primary key
csk	Command table sort key
pk	Data table primary key
sk	Data table sort key
tenantCode	Tenant code
type	Entity type (embedded in pk, e.g., "PROJECT")
seq	Sort order
code	Code (may be used as part of sk)
name	Name
version	Version number
isDeleted	Deletion flag
createdBy	Creator's user ID or username
createdIp	Creator's IP address
createdAt	Creation timestamp
updatedBy	Updater's user ID or username (set at creation)
updatedIp	Updater's IP address (set at creation)
updatedAt	Update timestamp (set at creation).
status	Status (for CQRS processing).
ttl	DynamoDB TTL timestamp (Unix epoch seconds)

Serialization Mapping

Internal Field	External Field	Description
pk + sk	id	Combined primary key for unique identification
cpk	cpk	Command table primary key
csk	csk	Command table sort key
pk	pk	Data table primary key
sk	sk	Data table sort key
sk	code	Sort key used as code identifier
tenantCode	tenantCode	Tenant identifier
type	type	Entity type (e.g., PROJECT)
seq	seq	Sequence number for ordering
name	name	Entity name (first level property)
version	version	Entity version for optimistic locking
isDeleted	isDeleted	Soft delete flag
createdBy	createdBy	User ID or name of creator
createdIp	createdIp	IP address of creator
createdAt	createdAt	Creation timestamp
updatedBy	updatedBy	User ID or name of last updater
updatedIp	updatedIp	IP address of last updater
updatedAt	updatedAt	Last update timestamp
status	status	CQRS processing status
ttl	ttl	DynamoDB TTL timestamp (Unix epoch seconds)
attributes.*	*	Flattened attributes from internal structure