# @faceteer/expression-builder 中文文档

规范地址：https://npmcn.com/package/%40faceteer/expression-builder/

版本：2\.0\.1
npm 元数据更新时间：2026-08-22T15:56:38.993Z
中文译文更新时间：2026-11-14T08:13:47.701Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40faceteer/expression-builder
原文对照：https://npmcn.com/package/%40faceteer/expression-builder/?lang=original
项目主页：https://github.com/faceteer/expression-builder#readme
源码仓库：https://github.com/faceteer/expression-builder

弃用说明：Merged into @faceteer/facet 6\.1\.0\. Install @faceteer/facet instead\.

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

- 包体积（解压后）：17 kB，5 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=12\.4\.0
- 运行依赖：1 个
- 首次发布：2021-07-10T00:55:48.364Z
- 最新版本发布：2022-01-11T04:54:19.277Z
- 近 30 天下载量：3344（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 0 个）

## 中文简介

Dynamo DB 的表达式构建器

## 安装

```sh
npm install @faceteer/expression-builder
```

也可以使用：`pnpm add @faceteer/expression-builder`、`yarn add @faceteer/expression-builder`、`bun add @faceteer/expression-builder`

## README

# Faceteer 表达式构建器

Faceteer 表达式构建器是一组可用于创建的函数 [过滤表达式](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html#Query.FilterExpression) 用于 Dynamo DB 查询,或 [条件表达式](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ConditionExpressions.html) 页:1 `PutItem`, (中文(简体) ), `UpdateItem`,以及 `DeleteItem` 操作.

## 安装

用 npm 安装 :

```bash
npm i @faceteer/expression-builder --save
```

用纱线安装 :

```
yarn add @faceteer/expression-builder
```

## 条件表达式

条件表达式用于要有条件地放置,更新,或从DynatomDB删除某个项目时.

条件表达式构建器将在代表条件表达式的数组中取出,并会用占位符生成属性名称和值的表达式.

条件表达式支持下列操作:

### `=`, (中文(简体) ), `<`, (中文(简体) ), `<=`, (中文(简体) ), `>`, (中文(简体) ), `>=`, (中文(简体) ), `<>`

```ts
// The status is active
["status", "=", "active"];
// Age is greater than or equal to 65
["age", ">=", 65];
// The last updated time was before Jan 5, 2020
["lastUpdated", "<", new Date("2020-01-05")];
```

### `between`

```ts
// Ids between 57242 and 99980
["id", "between", 57242, 99980];
// Last name starts with "m", "n", or "o"
["lastName", "between", "m", "O"];
```

### `begins_with`

```ts
// The industry begins with marketing
["industry", "begins_with", "marketing"];
// Zip code begins with 11
["zipCode", "begins_with", "11"];
```

### `exists`

```ts
// The attribute billingPlan exists
["billingPlan", "exists"];
```

### `not_exists`

```ts
// The attribute deletedAt does not exist
["deletedAt", "not_exists"];
```

### `contains`

```ts
// The company name contains the letters "LLC"
["companyName", "contains", "LLC"];
// The array of users contains the name "larry"
["users", "contains", "larry"];
```

### `size`

```ts
// Users where the first name is greater than 20 characters
["firstName", "size", ">=", 20];
// Images where the size is less than 2048 bytes
["image", "size", "<", 2048];
// Products where there is only one review
["reviews", "size", "=", 1];
```

### `in`

```ts
// Posts that have a status of draft or queued
["postStatus", "in", ["draft", "queued"]];
```

### `AND`, (中文(简体) ), `OR`

```ts
// An active user with a billing plan
[["billingPlan", "exists"], "AND", ["status", "=", "active"]];
// Users with a first name longer than 20 characters or a missing first name
[["firstName", "size", ">=", 20], "OR", ["firstName", "not_exists"]];
```

## 过滤表达式

要查询 Dynamo DB 时会使用过滤表达式, 但只想要被询问结果的子集 .

滤波器表达式构建器将采用代表滤波器表达式的阵列,并生成属性名称和值的占位符表达式.

下列操作用于过滤表达式:

-   `=`
-   `<`
-   `<=`
-   `>=`
-   `<>`
-   `between`
-   `begins_with`

除了所有操作 `between` 过滤表达式阵列的结构为 `[{attribute}, {operand}, {value}]`。 。 。 .

```ts
// Users that signed during or after 2020
const newUsersFilter = expressionBuilder.filter(["signedUpDate", ">=", "2020"]);

// Active users
const activeUsersFilter = expressionBuilder.filter(["status", "=", "active"]);

// Users who's industry begins with marketing
const industryFilter = expressionBuilder.filter([
  "industry",
  "begins_with",
  "marketing",
]);
```

对于 `between` 过滤表达式阵列的结构为 `[{attribute}, "between", {start}, {end}]`。 。 。 .

```ts
// Users that signed up between 2015 and 2016
const signUpRangeFilter = expressionBuilder.filter([
  "signedUpDate",
  "between",
  "2015",
  "2016",
]);
```

您也可以使用 `AND` 财务报告和审定财务报表 `OR` 将多个语句连在一起的操作.

```ts
// Active users who signed up before 2010
const signUpFilter = builder.filter([
  ["signedUpDate", ">", "2010"],
  "AND",
  ["status", "=", "active"],
]);
```

## 使用量

编译的表达式将返回具有三个属性的对象.

| 财产 | 说明 |
| --- | --- |
| `names` | 包含由占位符索引的属性名的地图. |
| `values` | 包含由他们的占位符索引的Dynamo DB格式中的属性值的地图. |
| `expression` | 过滤表达式字符串 . |

这些可以直接与 `DynamoDB` 客户端在 `aws-sdk`

```ts
// Using a condition expression for a put
import * as builder from "./condition";
import { DynamoDB } from "aws-sdk";
import { Converter } from "@faceteer/converter";

const ddb = new DynamoDB();

const statusCondition = builder.condition([
  "postStatus",
  "in",
  ["Retry", "Pending"],
]);

ddb.putItem({
  TableName: "Posts",
  Item: Converter.marshall(post),
  ConditionExpression: statusCondition.expression,
  ExpressionAttributeNames: statusCondition.names,
  ExpressionAttributeValues: statusCondition.values,
});
```

```ts
// Using a filter expression for a query
import * as expressionBuilder from "@faceteer/expression-builder";
import { DynamoDB } from "aws-sdk";

const ddb = new DynamoDB();

// Filter for users that signed during or after 2020
const signUpFilter = expressionBuilder.filter(["signedUpDate", ">=", "2020"]);

// Query the Dynamo DB table and add the placeholder
// names, values, and the filter expression
ddb.query({
  TableName: "MyOrganizationTable",
  KeyConditionExpression: `#PK = :partition AND #SK begins_with (:sort)`,
  ExpressionAttributeNames: {
    // The expression builder will generate bindings for
    // expression attribute names
    ...signUpFilter.names,
    "#PK": "PK",
    "#SK": "SK",
  },
  ExpressionAttributeValues: {
    // The expression builder will generate bindings for
    // expression attribute values
    ...signUpFilter.values,
    ":partition": {
      S: "#ORG_5753732",
    },
    ":sort": {
      S: "#USER",
    },
  },
  FilterExpression: signUpFilter.expression,
});
```

## 常见问题

### @faceteer/expression-builder 是什么？

Dynamo DB 的表达式构建器注意：该包已被作者标记为弃用——Merged into @faceteer/facet 6\.1\.0\. Install @faceteer/facet instead\.

### 如何安装 @faceteer/expression-builder？

在项目目录运行 npm install @faceteer/expression-builder，或使用 pnpm add / yarn add / bun add。

### @faceteer/expression-builder 支持 TypeScript 吗？

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

### @faceteer/expression-builder 支持 ESM 还是 CommonJS？

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

### @faceteer/expression-builder 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=12\.4\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @faceteer/expression-builder 可以商用吗？

@faceteer/expression-builder 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @faceteer/expression-builder 的下载量有多少？

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

### @faceteer/expression-builder 还在维护吗？

最新版本 2\.0\.1 发布于 2022/01/11（4 年前）；至今共发布 6 个版本，其中过去 12 个月发布了 0 个；首次发布于 2021/07/10。作者已将其标记为弃用，新项目建议寻找替代方案。