CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-aws-sdk--util-dynamodb

Utilities for marshalling and unmarshalling data between JavaScript objects and DynamoDB AttributeValue format

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

@aws-sdk/util-dynamodb

@aws-sdk/util-dynamodb provides essential utilities for marshalling and unmarshalling data between JavaScript objects and DynamoDB AttributeValue format. It offers both high-level convenience functions for complete records and low-level utilities for individual values, with comprehensive support for JavaScript data types including numbers, booleans, lists, maps, sets, and binary data.

Package Information

  • Package Name: @aws-sdk/util-dynamodb
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @aws-sdk/util-dynamodb

Core Imports

import { marshall, unmarshall, convertToAttr, convertToNative, NumberValueImpl as NumberValue } from "@aws-sdk/util-dynamodb";

For CommonJS:

const { marshall, unmarshall, convertToAttr, convertToNative, NumberValueImpl: NumberValue } = require("@aws-sdk/util-dynamodb");

Basic Usage

import { DynamoDB } from "@aws-sdk/client-dynamodb";
import { marshall, unmarshall } from "@aws-sdk/util-dynamodb";

const client = new DynamoDB(clientParams);

// Marshall JavaScript object to DynamoDB format
const params = {
  TableName: "Users",
  Item: marshall({
    id: "user-123",
    name: "Alice Johnson",
    age: 25,
    active: true,
    scores: [95, 87, 92],
    metadata: { level: "premium", joinDate: "2024-01-15" },
    tags: new Set(["vip", "active"]),
    avatar: null,
  }),
};

await client.putItem(params);

// Unmarshall DynamoDB record back to JavaScript
const getParams = {
  TableName: "Users", 
  Key: marshall({ id: "user-123" }),
};

const { Item } = await client.getItem(getParams);
const user = unmarshall(Item); // Returns plain JavaScript object

Architecture

The package is organized around two main patterns:

  • High-level Functions: marshall() and unmarshall() for complete record conversion between JavaScript objects and DynamoDB format
  • Low-level Utilities: convertToAttr() and convertToNative() for individual value conversion with fine-grained control
  • Precision Handling: NumberValue class for numbers that exceed JavaScript's safe integer limits
  • Type Safety: Full TypeScript support with comprehensive type definitions for all data transformations

Capabilities

Record Marshalling

High-level functions for converting complete JavaScript objects to and from DynamoDB record format. Handles nested objects, arrays, sets, and all DynamoDB-supported data types.

function marshall(data: unknown, options?: marshallOptions): AttributeValue | Record<string, AttributeValue> | AttributeValue[];

function unmarshall(
  data: Record<string, AttributeValue> | AttributeValue,
  options?: unmarshallOptions
): Record<string, NativeAttributeValue>;

Record Marshalling

Value Conversion

Low-level utilities for converting individual JavaScript values to DynamoDB AttributeValue format and vice versa. Provides fine-grained control over the conversion process.

function convertToAttr(data: NativeAttributeValue, options?: marshallOptions): AttributeValue;

function convertToNative(data: AttributeValue, options?: unmarshallOptions): NativeAttributeValue;

Value Conversion

Precision Numbers

Specialized handling for numbers that exceed JavaScript's Number.MAX_SAFE_INTEGER and MIN_SAFE_INTEGER limits, maintaining full precision as strings.

class NumberValue {
  constructor(value: number | Number | BigInt | string | { N: string });
  static from(value: number | Number | BigInt | string | { N: string }): NumberValue;
  toAttributeValue(): { N: string };
  toBigInt(): bigint;
  toString(): string;
  valueOf(): string;
  readonly value: string;
}

Precision Numbers

Types

interface marshallOptions {
  convertEmptyValues?: boolean;
  removeUndefinedValues?: boolean;
  convertClassInstanceToMap?: boolean;
  convertTopLevelContainer?: boolean;
  allowImpreciseNumbers?: boolean;
}

interface unmarshallOptions {
  wrapNumbers?: boolean | ((value: string) => number | bigint | NumberValue | any);
  convertWithoutMapWrapper?: boolean;
}

type NativeAttributeValue =
  | NativeScalarAttributeValue
  | { [key: string]: NativeAttributeValue }
  | NativeAttributeValue[]
  | Set<number | bigint | NumberValue | string | NativeAttributeBinary | undefined>
  | InstanceType<{ new (...args: any[]): any }>;

type NativeScalarAttributeValue =
  | null
  | undefined
  | boolean
  | number
  | NumberValue
  | bigint
  | NativeAttributeBinary
  | string;

type NativeAttributeBinary =
  | ArrayBuffer
  | Blob
  | Buffer
  | DataView
  | File
  | Int8Array
  | Uint8Array
  | Uint8ClampedArray
  | Int16Array
  | Uint16Array
  | Int32Array
  | Uint32Array
  | Float32Array
  | Float64Array
  | BigInt64Array
  | BigUint64Array;
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@aws-sdk/util-dynamodb@3.879.x
Publish Source
CLI
Badge
tessl/npm-aws-sdk--util-dynamodb badge