Record Marshalling

/**
 * Convert a JavaScript object into a DynamoDB record
 * @param data - The data to convert to a DynamoDB record
 * @param options - Optional configuration for marshall
 */
function marshall(data: null, options?: marshallOptions): AttributeValue.NULLMember;
function marshall(
  data: Set<bigint> | Set<number> | Set<NumberValue>,
  options?: marshallOptions
): AttributeValue.NSMember;
function marshall(data: Set<string>, options?: marshallOptions): AttributeValue.SSMember;
function marshall(data: Set<NativeAttributeBinary>, options?: marshallOptions): AttributeValue.BSMember;
function marshall(data: NativeAttributeBinary, options?: marshallOptions): AttributeValue.BMember;
function marshall(data: boolean, options?: marshallOptions): AttributeValue.BOOLMember;
function marshall(data: number | NumberValue | bigint, options?: marshallOptions): AttributeValue.NMember;
function marshall(data: string, options?: marshallOptions): AttributeValue.SMember;
function marshall(data: NativeAttributeValue[], options?: marshallOptions): AttributeValue[] | AttributeValue.LMember;
function marshall(
  data: Map<string, NativeAttributeValue> | Record<string, NativeAttributeValue>,
  options?: marshallOptions
): Record<string, AttributeValue> | AttributeValue.MMember;
function marshall(data: unknown, options?: marshallOptions): any;

interface marshallOptions {
  /** Whether to automatically convert empty strings, blobs, and sets to null */
  convertEmptyValues?: boolean;
  /** Whether to remove undefined values from JS arrays/Sets/objects when marshalling */
  removeUndefinedValues?: boolean;
  /** Whether to convert typeof object to map attribute */
  convertClassInstanceToMap?: boolean;
  /** Whether to convert the top level container if it is a map or list */
  convertTopLevelContainer?: boolean;
  /** Whether to allow numbers beyond Number.MAX_SAFE_INTEGER during marshalling */
  allowImpreciseNumbers?: boolean;
}

import { marshall } from "@aws-sdk/util-dynamodb";

// Basic object marshalling
const item = marshall({
  id: "user-123",
  name: "Alice",
  age: 25,
  active: true,
});
// Result: {id: {S: "user-123"}, name: {S: "Alice"}, age: {N: "25"}, active: {BOOL: true}}

// Complex nested structure
const complexItem = marshall({
  user: {
    profile: {
      name: "Bob",
      preferences: {
        theme: "dark",
        notifications: true,
      },
    },
    scores: [95, 87, 92],
    tags: new Set(["premium", "active"]),
    metadata: null,
  },
});

// With options
const itemWithOptions = marshall(
  {
    name: "Charlie",
    email: "",
    tags: new Set([]),
    scores: [1, undefined, 3],
  },
  {
    convertEmptyValues: true,    // Convert empty string and set to null
    removeUndefinedValues: true, // Remove undefined from array
  }
);
// Result: {name: {S: "Charlie"}, email: {NULL: true}, tags: {NULL: true}, scores: {L: [{N: "1"}, {N: "3"}]}}

/**
 * Convert a DynamoDB record into a JavaScript object
 * @param data - The DynamoDB record
 * @param options - Optional configuration for unmarshall
 */
function unmarshall(
  data: Record<string, AttributeValue> | AttributeValue,
  options?: unmarshallOptions
): Record<string, NativeAttributeValue>;

interface unmarshallOptions {
  /** 
   * Whether to modify how numbers are unmarshalled from DynamoDB.
   * When true, returns numbers as NumberValue instances.
   * When a function, calls it with string representation for custom conversion.
   */
  wrapNumbers?: boolean | ((value: string) => number | bigint | NumberValue | any);
  /** When true, skip wrapping the data in { M: data } before converting */
  convertWithoutMapWrapper?: boolean;
}

import { unmarshall } from "@aws-sdk/util-dynamodb";

// Basic unmarshalling
const dynamoRecord = {
  id: { S: "user-123" },
  name: { S: "Alice" },
  age: { N: "25" },
  active: { BOOL: true },
  scores: { L: [{ N: "95" }, { N: "87" }, { N: "92" }] },
};

const jsObject = unmarshall(dynamoRecord);
// Result: {id: "user-123", name: "Alice", age: 25, active: true, scores: [95, 87, 92]}

// Handling large numbers
const largeNumberRecord = {
  id: { S: "item-1" },
  largeNumber: { N: "12345678901234567890" },
};

const withNumberWrapping = unmarshall(largeNumberRecord, {
  wrapNumbers: true, // Returns NumberValue instances for large numbers
});
// Result: {id: "item-1", largeNumber: NumberValue {value: "12345678901234567890"}}

// Custom number handling
const withCustomNumbers = unmarshall(largeNumberRecord, {
  wrapNumbers: (numString) => BigInt(numString), // Convert to BigInt
});
// Result: {id: "item-1", largeNumber: 12345678901234567890n}

// marshall() errors
try {
  marshall({ value: NaN }); // Throws: Special numeric value NaN is not allowed
} catch (error) {
  console.error(error.message);
}

try {
  marshall({ value: Number.MAX_SAFE_INTEGER + 1 }); // Throws unless allowImpreciseNumbers: true
} catch (error) {
  console.error(error.message);
}

try {
  marshall({ tags: new Set() }); // Throws unless convertEmptyValues: true
} catch (error) {
  console.error(error.message);
}

// unmarshall() errors
try {
  unmarshall({ invalid: { UNKNOWN: "value" } }); // Throws: Unsupported type passed
} catch (error) {
  console.error(error.message);
}