@ bezoar/ schema (英语)

贝佐尔合同的类型和运行时间验证。 验证用途 佐德语 从合同中创造出来的计划.

安装

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。 。 。 .

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。 。 。 .

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 的类型参数 轻而易举 Kysely 在定义的表格之上。 生成的一栏是 Generated,所以插入可以省去。 视图的一栏是 ColumnType 中选择,而不插入或更新. @bezoar/core 在此类型之上构建服务查询构建器 .

类型表格

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

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

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

定义计划

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

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。 。 。 .

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 构建定义 .