or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md precision-numbers.md record-marshalling.md value-conversion.md

tile.json

Value Conversion

Low-level utilities for converting individual JavaScript values to DynamoDB AttributeValue format and vice versa. These functions provide fine-grained control over the conversion process and are used internally by the higher-level marshall/unmarshall functions.

Capabilities

Convert To Attribute

Converts a single JavaScript value to its equivalent DynamoDB AttributeValue format.

/**
 * Convert a JavaScript value to its equivalent DynamoDB AttributeValue type
 * @param data - The data to convert to a DynamoDB AttributeValue
 * @param options - Optional configuration for convertToAttr
 */
function convertToAttr(data: NativeAttributeValue, options?: marshallOptions): AttributeValue;

Usage Examples:

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

// Convert primitive values
convertToAttr("hello");           // {S: "hello"}
convertToAttr(42);                // {N: "42"}
convertToAttr(true);              // {BOOL: true}
convertToAttr(null);              // {NULL: true}

// Convert complex values
convertToAttr([1, 2, 3]);         // {L: [{N: "1"}, {N: "2"}, {N: "3"}]}
convertToAttr({name: "Alice"});   // {M: {name: {S: "Alice"}}}
convertToAttr(new Set([1, 2]));   // {NS: ["1", "2"]}

// Convert binary data
const buffer = new Uint8Array([1, 2, 3]);
convertToAttr(buffer);            // {B: Uint8Array([1, 2, 3])}

// With options
convertToAttr("", { convertEmptyValues: true });        // {NULL: true}
convertToAttr([1, undefined, 3], { removeUndefinedValues: true }); // {L: [{N: "1"}, {N: "3"}]}

Convert To Native

Converts a DynamoDB AttributeValue back to its equivalent JavaScript type.

/**
 * Convert a DynamoDB AttributeValue object to its equivalent JavaScript type
 * @param data - The DynamoDB record to convert to JavaScript type
 * @param options - Optional configuration for convertToNative
 */
function convertToNative(data: AttributeValue, options?: unmarshallOptions): NativeAttributeValue;

Usage Examples:

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

// Convert primitive AttributeValues
convertToNative({S: "hello"});    // "hello"
convertToNative({N: "42"});       // 42
convertToNative({BOOL: true});    // true
convertToNative({NULL: true});    // null

// Convert complex AttributeValues
convertToNative({L: [{N: "1"}, {N: "2"}]});           // [1, 2]
convertToNative({M: {name: {S: "Alice"}}});           // {name: "Alice"}
convertToNative({NS: ["1", "2", "3"]});               // Set([1, 2, 3])
convertToNative({SS: ["a", "b", "c"]});               // Set(["a", "b", "c"])

// Handle large numbers
convertToNative({N: "12345678901234567890"});         // 12345678901234567890n (BigInt)
convertToNative({N: "123.456"}, {wrapNumbers: true}); // NumberValue {value: "123.456"}

// Custom number conversion
convertToNative({N: "999"}, {
  wrapNumbers: (str) => parseFloat(str) * 2           // 1998
});

Supported Data Type Conversions

The conversion functions handle all DynamoDB-supported data types:

Scalar Types:

string ↔ {S: string}
number ↔ {N: string}
boolean ↔ {BOOL: boolean}
null ↔ {NULL: true}
BigInt ↔ {N: string}
NumberValue ↔ {N: string}

Binary Types:

ArrayBuffer, Uint8Array, Buffer, etc. ↔ {B: binary}

Collection Types:

Array ↔ {L: AttributeValue[]}
Object ↔ {M: Record<string, AttributeValue>}
Map ↔ {M: Record<string, AttributeValue>}
Set<string> ↔ {SS: string[]}
Set<number> ↔ {NS: string[]}
Set<binary> ↔ {BS: binary[]}

Number Handling

Special handling for JavaScript numbers and precision:

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

// Safe integers convert normally
convertToAttr(42);                    // {N: "42"}
convertToAttr(Number.MAX_SAFE_INTEGER); // {N: "9007199254740991"}

// Large numbers require special handling
try {
  convertToAttr(Number.MAX_SAFE_INTEGER + 1); // Throws error by default
} catch (error) {
  console.error(error.message); // "Number ... is greater than Number.MAX_SAFE_INTEGER"
}

// Allow imprecise numbers
convertToAttr(Number.MAX_SAFE_INTEGER + 1, { allowImpreciseNumbers: true }); // {N: "9007199254740992"}

// Use NumberValue for precision
const preciseNumber = new NumberValue("12345678901234567890.123456789");
convertToAttr(preciseNumber);         // {N: "12345678901234567890.123456789"}

// Converting back preserves precision
const attr = {N: "12345678901234567890.123456789"};
convertToNative(attr);                // 12345678901234567890n (BigInt if integer)
convertToNative(attr, {wrapNumbers: true}); // NumberValue {value: "12345678901234567890.123456789"}

Binary Data Support

Comprehensive support for various binary data types:

import { convertToAttr, convertToNative } from "@aws-sdk/util-dynamodb";

// Supported binary types
const arrayBuffer = new ArrayBuffer(8);
const uint8Array = new Uint8Array([1, 2, 3, 4]);
const int16Array = new Int16Array([1000, 2000]);
const float32Array = new Float32Array([1.5, 2.5]);

convertToAttr(uint8Array);   // {B: Uint8Array([1, 2, 3, 4])}
convertToAttr(int16Array);   // {B: Int16Array([1000, 2000])}

// Binary sets
const binarySet = new Set([
  new Uint8Array([1, 2]),
  new Uint8Array([3, 4])
]);
convertToAttr(binarySet);    // {BS: [Uint8Array([1, 2]), Uint8Array([3, 4])]}

Error Handling

The conversion functions throw errors for unsupported or invalid data:

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

try {
  convertToAttr(undefined); // Throws unless removeUndefinedValues option
} catch (error) {
  console.error(error.message);
}

try {
  convertToAttr(new Set()); // Throws: Pass a non-empty set, or options.convertEmptyValues=true
} catch (error) {
  console.error(error.message);
}

// convertToNative() errors
try {
  convertToNative({INVALID: "type"}); // Throws: Unsupported type passed
} catch (error) {
  console.error(error.message);
}

try {
  convertToNative({}); // Throws: No value defined
} catch (error) {
  console.error(error.message);
}

Version

Tile

Files