# @bezoar/schema 中文文档

规范地址：https://npmcn.com/package/%40bezoar/schema/

版本：0\.0\.6
npm 元数据更新时间：2026-11-02T16:55:58.508Z
中文译文更新时间：2026-11-09T20:12:16.005Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：34.9 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2026-10-17T16:42:44.133Z
- 最新版本发布：2026-11-02T16:55:58.018Z
- 近 30 天下载量：1757（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

贝佐尔合同:查询模式、类型表和运行时间验证

## 安装

```sh
npm install @bezoar/schema
```

也可以使用：`pnpm add @bezoar/schema`、`yarn add @bezoar/schema`、`bun add @bezoar/schema`

## README

# @ bezoar/ schema (英语)

贝佐尔合同的类型和运行时间验证。 验证用途 [佐德语](https://zod.dev/) 从合同中创造出来的计划.

## 安装

```sh
pnpm add @bezoar/schema
```

## 合同

A 类 **定义** 宣布合同. `@bezoar/kit` 从 数据库包的 SQL 。 定义是纯数据,没有SQL.

-   **语句** 将数据库的每个enum类型映射到其标签,以 声明令.
-   **查询** 映射每个查询名称, 例如 `events.list`,改为: **语句**。 。 。 .
-   声明有其 **插槽** 联 合 国 **栏**。无 列返回无行 : `RETURNING`。 。 。 .
-   A 类 **插槽** 是 SQL 的一个已命名参数。 A 类 **栏** 每个字段 排队 每个都有 `name`页:1 `type`,则a `nullable` 旗帜。 档位在 位置顺序: 索引中的槽 `i` 绑定 `$i+1`。 。 。 .
-   A 类 **类型** 是类型表格的平面图,定义的缩略图,或 或带有 `[]` 后缀.
-   **图表** 将每个表格和数据库视图映射到其 **栏**, (中文(简体) ), 以搜索路径找到时的赤名命名, 并 `schema.name` 否则。 表格栏有 `name`页:1 `type`页:1 `nullable` 旗帜和a `generated` 旗帜:数据库是否能够通过默认方式填充 身份,或代表达式。 类型中的表格列 表格没有为 `unknown`。一个表格有一个 `kind`数字 : `table`,或 `view` 对于一个读而不写.
-   **角色** 将数据库中的每个角色绘制到查询的名称 拥有运行权限, 因为工具箱找到了它们。 成员可选: 在角色存在之前订立的合同不存在 `Role<D>` 那时 `never`。 。 。 .

```ts
const contract = {
  enums: { event_day: ["sunday", "monday" /* … */] },
  queries: {
    "events.list": {
      slots: [
        { name: "day", type: "event_day", nullable: false },
        { name: "location", type: "text", nullable: true },
      ],
      columns: [
        { name: "id", type: "int4", nullable: false },
        { name: "title", type: "text", nullable: false },
        { name: "weeks", type: "int4[]", nullable: true },
      ],
    },
  },
  tables: {
    events: {
      kind: "table",
      columns: [
        { name: "id", type: "int4", nullable: false, generated: true },
        { name: "title", type: "text", nullable: false, generated: false },
        { name: "weeks", type: "int4[]", nullable: true, generated: false },
      ],
    },
  },
} as const satisfies Definition;
```

论据和行的种类来源于定义. A 类 所需时间段是规定的成员。 无效的槽是可选的,也可以 带 `null`。可注销的一栏也持有 `null`。 。 。 .

```ts
type D = typeof contract;

Arguments<D, "events.list">; // { day: "sunday" | "monday" | …; location?: string | null }
Row<D, "events.list">; // { id: number; title: string; weeks: (number | null)[] | null }
Returns<D, "events.list">; // Row<D, "events.list">[]
Returns<D, "events.touch">; // number, for a query with no column
Database<D>; // { events: { id: Generated<number>; title: string; weeks: (number | null)[] | null } }
Role<D>; // the role names of the contract: "web" | "admin"
RoleQuery<D, "web">; // the queries the role may run: "events.list" | …
```

`Database<D>` 是 a 的类型参数 [轻而易举](https://kysely.dev/) `Kysely` 在定义的表格之上。 生成的一栏是 `Generated`,所以插入可以省去。 视图的一栏是 `ColumnType` 中选择,而不插入或更新. `@bezoar/core` 在此类型之上构建服务查询构建器 .

## 类型表格

一个表格将每个 Postgres 类型映射到它的 JavaScript 形式. `Scalars` 声明 工具箱的种类. `TABLE` 守着zod计划 每一个 编译器将两者相持.

| 邮资 | Java 脚本 | 司马 |
| --- | --- | --- |
| `bool` | `boolean` | `z.boolean()` |
| `int2`, (中文(简体) ), `int4`, (中文(简体) ), `int8` | `number` | `z.int()`如此不安全 `int8` 失败 |
| `float4`, (中文(简体) ), `float8` | `number` | 任何号码,所以 `NaN` 和无限的过去 |
| `numeric` | `string` | `z.string()`,所以没有数字丢失 |
| `text`, (中文(简体) ), `varchar`, (中文(简体) ), `bpchar` | `string` | `z.string()` |
| `uuid` | `string` | `z.uuid()` |
| `date`, (中文(简体) ), `time` | `string` | `z.iso.date()`, (中文(简体) ), `z.iso.time()` |
| `timetz`, (中文(简体) ), `timestamp`, (中文(简体) ), `interval` | `string` | `z.string()`,正如Postgres所写 |
| `timestamptz` | `Date` | `z.date()` |
| `json`, (中文(简体) ), `jsonb` | `unknown` | `z.json()`,一个 JSON 值 |
| `bytea` | `Uint8Array` | `z.instanceof(Uint8Array)` |

一个词是 `z.enum` 在它的标签上。 一个阵列是 `z.array` 及其要素, 由于 Postgres 允许一个无效元素。 邮递局没有 键入数组的维度,所以数组的图案是 一维.

驱动程序将 Postgres 文本解析为这些类型 。 没有区域的时间 没有瞬间,所以时间类型除了 `timestamptz` 保持绳子.

## 定义计划

`defineSchema(definition)` 返回 a `Schema<D>`。计划验证 与定义词汇相对的不信任数据. 数据通过是 受合同约束.

```ts
import { defineSchema } from "@bezoar/schema";

const schema = defineSchema(contract);

// Returns a boolean. The type of the value narrows on `true`.
if (!schema.check.query(name)) throw new Error("not a query");

// Throws a SchemaError that lists every issue.
schema.assert.arguments("events.list", await readBody(event));

// Throws on an invalid value. Returns the value with its narrowed type.
const row = schema.parse.row("events.list", candidate);

// Returns { success: true, data } or { success: false, issues }.
const result = schema.inspect.definition(candidate);
```

该函数在读取之前会检查定义. 无效的定义 呼叫时抛出 `defineSchema`。 。 。 .

这个 `Schema<D>` 这些成员:

-   `base` 定义.
-   `validators` 执行zod计划: `definition`, (中文(简体) ), `query`, (中文(简体) ), `bundle`,以及 每个查询在 `queries` 联合国 `arguments` 联 合 国 `row`。当 Zod 时使用它们 计划是通缉的,比如一个路由处理器. `z.infer` 计划是 键入服务使用.
-   `check` 每种都有一个布尔的上游.
-   `assert` 每种都有一个说法。 失败的断言会抛出 `SchemaError` 拥有每一个 `Issue`。 。 。 .
-   `parse` 表示一个值,并随同类类型返回.
-   `inspect` 返回 a `Result` 每种.

## 类型

每个成员 `check`, (中文(简体) ), `assert`, (中文(简体) ), `parse`,以及 `inspect` 验证一个 **类型**。一种查询首先使用查询名称.

-   `definition` 是一个完整的定义.
-   `query` 是合同的查询名称.
-   `bundle` 是 SQL 捆绑: 合同中每个查询的文本, 由 名字,没有其他名字.
-   `arguments(query, value)` 是一个对象,每个槽都有成员 查询。 必须有所需时间档,而不是 `null`。一个无效的槽可以 缺席, `null`,或者一个值。 查询不命名的密钥是一个问题 .
-   `row(query, value)` 是一个对象,每个列都有成员 查询和没有其他。 无效的列具有值或 `null`。 。 。 .

```ts
schema.assert.arguments("events.list", { day: "sunday" }); // passes
schema.assert.arguments("events.list", { day: "someday" }); // SchemaError: day: Invalid option …
schema.check.row("events.list", await res.json()); // true when the row fits the columns
```

## 类型

-   `Definition` 这是合同. `Statement`, (中文(简体) ), `Slot`, (中文(简体) ), `Column`, (中文(简体) ), `Table`, (中文(简体) ), `TableColumn`,以及 `TableKind` 是它的部件.
-   `Query<D>`, (中文(简体) ), `Enum<D>`,以及 `Label<D, E>` 是定义中的名称. `RowQuery<D>` 是带有列的查询的名称. `Type<D>` 是类型 名称定义可以表达.
-   `Scalars` 将每个scalar映射到它的JavaScript类型. `Scalar` 联盟 它的钥匙. `Value<D, T>` 是类型名称的 JavaScript 类型 .
-   `Arguments<D, Q>`, (中文(简体) ), `Row<D, Q>`,以及 `Returns<D, Q>` 是一个形状 调用查询 `Q`。 。 。 . `Returns` 是带有列的查询行 数一个没有.
-   `Database<D>` 是一个定义的表格,作为 kysely 类型.
-   `Bundle<D>` 是合同的 SQL 捆绑.
-   `Validators<D>` 是 zod 策略的形状.
-   `Schema<D>` 是捆绑 `defineSchema` 返回. `Check<D>`, (中文(简体) ), `Assert<D>`, (中文(简体) ), `Parse<D>`,以及 `Inspect<D>` 是其功能的组合.
-   `Result<V>` 的结果 `inspect`。 。 。 .
-   `Issue` 如zod所报告,是验证失败.
-   `SchemaError` 错误是 `assert` 财务报告和审定财务报表 `parse` 掷出. 它拿着 `Issue` 列表中选择一个选项.

## 相关

-   `@bezoar/core` 是使用此策略的运行时服务 .
-   `@bezoar/kit` 从 SQL 构建定义 .

## 常见问题

### @bezoar/schema 是什么？

贝佐尔合同:查询模式、类型表和运行时间验证

### 如何安装 @bezoar/schema？

在项目目录运行 npm install @bezoar/schema，或使用 pnpm add / yarn add / bun add。

### @bezoar/schema 支持 TypeScript 吗？

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

### @bezoar/schema 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @bezoar/schema 可以商用吗？

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

### @bezoar/schema 的下载量有多少？

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

### @bezoar/schema 还在维护吗？

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