# @aws/dynamodb-auto-marshaller 中文文档

规范地址：https://npmcn.com/package/%40aws/dynamodb-auto-marshaller/

版本：0\.7\.1
npm 元数据更新时间：2026-10-15T22:06:39.398Z
中文译文更新时间：2026-11-07T10:44:21.476Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40aws/dynamodb-auto-marshaller
原文对照：https://npmcn.com/package/%40aws/dynamodb-auto-marshaller/?lang=original
项目主页：https://awslabs.github.io/dynamodb-data-mapper-js/packages/dynamodb-auto-marshaller/
源码仓库：https://github.com/awslabs/dynamodb-data-mapper-js

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：50.8 kB，17 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：aws-sdk ^2\.7\.0
- 首次发布：2017-11-20T23:37:24.901Z
- 最新版本发布：2018-07-21T00:24:31.814Z
- 近 30 天下载量：311455（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 0 个）

## 中文简介

将 JavaScript 类型转换成 Amazon DynamODB 属性Values 的数据交换器

## 安装

```sh
npm install @aws/dynamodb-auto-marshaller
```

也可以使用：`pnpm add @aws/dynamodb-auto-marshaller`、`yarn add @aws/dynamodb-auto-marshaller`、`bun add @aws/dynamodb-auto-marshaller`

## README

# Amazon DynamoDB 自动售货机

[![Apache 2 License](https://img.shields.io/github/license/awslabs/dynamodb-data-mapper-js.svg?style=flat)](http://aws.amazon.com/apache-2-0/)

这个图书馆提供 `Marshaller` 转换本地 JavaScript 的类 到 DynamoDB 属性变量和返回值。 它的设计与工作 ES6功能,如集、地图和可移动性,可以配置为支持 仅由 JavaScript( 如空的二进制缓冲器) 或由 亚马逊DynatomDB(如任意大小的数字),取舍最小.

## 开始

用来使用 `Marshaller` 将 JavaScript 对象转换为需要的数据类型 由亚马逊DynamoDB制作 `marshallItem`数字 :

```typescript
import {BinarySet, Marshaller} from '@aws/dynamodb-auto-marshaller';

const marshaller = new Marshaller();
const original = {
    string: 'a string',
    number: 1234,
    list: [
        'a',
        'list',
        'of',
        'values',
    ],
    buffer: Buffer.from([0xde, 0xad, 0xbe, 0xef]),
    setOfBuffers: new BinarySet([
        Uint8Array.from([0xde, 0xad]),
        Uint8Array.from([0xbe, 0xef]),
        Uint8Array.from([0xfa, 0xce]),
    ] as Iterable<ArrayBufferView>),
    stringSet: new Set<string>([
        'foo',
        'bar',
        'baz',
    ]),
    any: {
        level: {
            of: {
                nesting: {
                    is: {
                        supported: true
                    }
                }
            }
        }
    },
}

// create a variable ready to be used with DynamoDB's low-level API 
const marshalled = marshaller.marshallItem(original);

// the output of `.marshallItem` can be converted back to a JavaScript type with
// `.unmarshallItem`
const unmarshalled = marshaller.unmarshallItem(original);

// With a few caveats (listed below), the unmarshalled value should have the
// same structure and data as the original value.
deepEqual(original, unmarshalled); // true
```

值可以转换为属性变量对象,也可以转换自属性参数 `.marshallValue` 财务报告和审定财务报表 `.unmarshallValue` 直接 :

```typescript
import {Marshaller} from '@aws/dynamodb-auto-marshaller';

const marshaller = new Marshaller();
const marshalled = marshaller.marshallValue('string'); // returns {S: 'string'}
const unmarshalled = marshaller.unmarshallValue(marshalled); // returns 'string'
```

## 洞穴

有几类数值不能在 JavaScript和DynamoDB,如"大数字","空值",和"混合类型"等.

### 数字支持

默认情况下, Marxler 将会解开 DynamoDB 返回的数值 输入 `NumberValue` 而不是输入本地 JavaScript 数字. DynamoDB中的数字的精确度可能高达38位,超过了 在 JavaScript 中可用的精度 `number`。 。 。 . `NumberValue` 因此,实例 将 DynamoDB 返回的值作为字符串存储,并且只强制值 当实例以算术表达式出现时, 输入 JavaScript 编号, 当它传递给 `JSON.stringify`,或何时 `valueOf` 方法被称为.

同样,数字集作为 `NumberValueSet` 实例 与数字和 `NumberValue`编号.

要禁用此行为, 将配置选项参数传递到 `Marshaller` 带有 `unwrapNumbers` 设置为 `true`数字 :

```typescript
import {Marshaller} from '@aws/dynamodb-auto-marshaller';

const marshaller = new Marshaller({unwrapNumbers: true});
```

### 空值支持

DynamoDB的数据模型要求字符串,集和二进制属性具有 长度大于0,而JavaScript没有这样的要求. 以 默认时, marxler 将不会试图更改空值, 如 marshaller 无法分解一个字段所使用的任何西格值 本来是要合法地抑制这种价值的.

Marxler提供了两个处理空值的选入选项,这两个选项都是 使用 `onEmpty` 配置选项.

设置 `onEmpty` 改为 `'nullify'` 将指示 marxler 转换为空 值改为无属性值(`{NULL: true}`并坚持到DynamoDB. 这使得项目的消费者知道空值已被保存, 尽管 将稍作改动。 从 DynamoDB 获取时, 值会是 未终止为 `null`数字 :

```typescript
import {Marshaller} from '@aws/dynamodb-auto-marshaller';

const marshaller = new Marshaller({onEmpty: 'nullify'});
const marshalled = marshaller.marshallValue(''); // returns {NULL: true}
const unmarshalled = marshaller.unmarshallValue(marshalled); // returns null
```

设置 `onEmpty` 改为 `'omit'` 将引导 marxler 删除空值 摘自序列项目:

```typescript
import {Marshaller} from '@aws/dynamodb-auto-marshaller';

const marshaller = new Marshaller({onEmpty: 'omit'});
const marshalled = marshaller.marshallValue(''); // returns undefined
const unmarshalled = marshaller.unmarshallValue(marshalled); // returns undefined
```

### 符号和函数

默认情况下,Marxler在遇到符号时会出错,或者 函数。 您可以指示 Marxler 而不是从它的 通过设置 `onInvalid` 配置选项到 `'omit'`数字 :

```typescript
import {Marshaller} from '@aws/dynamodb-auto-marshaller';

const marshaller = new Marshaller({onInvalid: 'omit'});
const marshalled = marshaller.marshallValue(Symbol.iterator); // returns undefined
const unmarshalled = marshaller.unmarshallValue(marshalled); // returns undefined
```

## 常见问题

### @aws/dynamodb-auto-marshaller 是什么？

将 JavaScript 类型转换成 Amazon DynamODB 属性Values 的数据交换器

### 如何安装 @aws/dynamodb-auto-marshaller？

在项目目录运行 npm install @aws/dynamodb-auto-marshaller，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：aws-sdk（^2\.7\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aws/dynamodb-auto-marshaller 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @aws/dynamodb-auto-marshaller 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @aws/dynamodb-auto-marshaller 可以商用吗？

@aws/dynamodb-auto-marshaller 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @aws/dynamodb-auto-marshaller 的下载量有多少？

根据 npm 官方下载统计，@aws/dynamodb-auto-marshaller 在 2026/10/08 – 2026/11/06 这 30 天内被下载 311,455 次，日均约 10,382 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aws/dynamodb-auto-marshaller 还在维护吗？

最新版本 0\.7\.1 发布于 2018/07/21（8 年前）；至今共发布 11 个版本，其中过去 12 个月发布了 0 个；首次发布于 2017/11/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。