Skip to main content
Home
Browse packagesDocsSign in

@byzanteam/taihaku-schemas@0.6.6
Built and signed on GitHub Actions

latest
Byzanteam/taihaku-schemas
This package works with Cloudflare Workers, Node.js, Deno, Bun, Browsers
This package works with Cloudflare Workers
This package works with Node.js
This package works with Deno
This package works with Bun
This package works with Browsers
JSR Score
76%
Published
4 days ago (0.6.6)

Schemas for taihaku

错误定义

Elixir 端给出的错误

在 Persistence Schema 执行的过程中会产生几种不同的错误，后文将通过下面的 Schema 进行说明。

Persistence Schema 
action = {
  schema: moviesSchema,
  paramsSchema: {
    type: 'object',
    properties: {
      title: { type: 'string' },
      release_date: { type: 'string' },
    },
    required: ['title'],
  },
  changeset: {
    changes: [
      {
        name: 'title',
        value: { $data: '/title' },
        schema: { type: 'string', minLength: 10 },
      },
      {
        name: 'release_date',
        value: { $data: '/release_date' },
      },
      { name: 'created_at', value: { $sql: 'now()' } },
      { name: 'updated_at', value: { $sql: 'now()' } },
    ],
    validator: {
      schema: {
        type: 'object',
        properties: {
          title: { type: 'string', maxLength: 255 },
          release_date: { type: 'string', format: 'date' },
        },
        required: ['title', 'release_date'],
      },
      validations: [
        {
          operator: 'custom',
          operands: [{ $data: '/release_date' }],
          expression: 'Date.parse(operands[0]) <= Date.now()',
          errorKey: '/release_date',
          errorMessage: 'Release date should be less than or equal to today',
        },
      ],
    },
  },
  returningSchema: {
    id: { $schema: '/id' },
    title: { $schema: '/title' },
    release_date: { $schema: '/release_date' },
    inserted_at: { $schema: '/inserted_at' },
    updated_at: { $schema: '/updated_at' },
  },
}

JSON Schema 校验出错

Persistence Schema 执行过程中会有多处涉及到 JSON Schema 的校验，当校验没有通过时 通过下面的数据结构将错误信息返回。

  • absoluteKeywordLocation - 指向 schema 中出错的关键词
  • instanceLocation - 指向数据中出错的值
paramsSchema 出错 
params = {
  release_date: '2024-05-14',
}

{
  "errors": [
    {
      "absoluteKeywordLocation": "#/paramsSchema/required/0",
      "instanceLocation": "/"
    }
  ]
}
changes 中字段校验失败 
params = {
  title: 'Title',
  release_date: '2024-05-14',
}

{
  "errors": [
    {
      "absoluteKeywordLocation": "#/changeset/changes/0/maxLength",
      "instanceLocation": "/title"
    }
  ]
}
validator schema 校验失败 
params = {
  title: 'This is a valid title',
  release_date: '2024-05-41',
}

{
  "errors": [
    {
      "absoluteKeywordLocation": "#/changeset/validator/schema/properties/release_date/format",
      "instanceLocation": "/release_date"
    }
  ]
}

Validation 执行时出错

Persistence Schema 中可能声明多个 validations，当 validation 的执行失败时，错误 信息将通过以下格式返回。

  • absoluteValidationLocation - 指出失败的 validation 位置
  • instanceLocation - 使用 validation 中定义的 errorKey
  • dependencies - 声明该 validation 中使用到的数据
  • errorMessage - validation 失败时给出的错误信息
paramsSchema 出错 
params = {
  title: 'This is a valid title',
  release_date: '4202-05-14',
}

{
  "errors": [
    {
      "absoluteValidationLocation": "#/changeset/validator/validations/0",
      "instanceLocation": "/release_date",
      "dependencies": ["/release_date"],
      "errorMessage": "excessive time"
    }
  ]
}

运行时错误

当这一类错误发生时，对用户来说相当于服务器内部错误，无法通过修改参数来解决。因此 不会用来决定页面的交互逻辑，只是返回一些信息能够帮助定位问题出现的原因。

  • location - 错误出现的位置
  • message - 错误信息的描述
returningSchema 中指定的列不存在 
params = {
  title: 'This is a valid title',
  release_date: '2024-05-14',
}

{
  "errors": [
    {
      "location": "#/returningSchema/inserted_at",
      "message": "column \"inserted_at\" does not exist"
    }
  ]
}

Next.js 后端给出的错误

在 Next.js 后端拿到 Elixir 给出的错误后结合 action 的定义给出更具体的错误，浏览器会接收到该错误并渲染到用户填写的表单中。

note: 我们会将所有的错误都转换，但是前端可能只能处理其中的一部分。

非运行时错误

把 Elixir 端给出的错误与 action 的定义结合后得到的精确到表单字段路径上的错误，这一类错误为 jsonSchema 校验错误和 Validation 错误的集合，均会把错误定位到具体的表单字段路径上。

JSON Schema 校验出错

该错误是由自己的值通过 jsonSchema 校验失败得到的。

  • errorLocation - 产生的错误在 jsonSchema 中的位置
  • errorKeyword - 校验错误的类型，都属于 jsonSchema 的校验 keyword
  • keywordSchema - 错误类型在 jsonSchema 中对应的值，通过 errorKeyword 和 keywordSchema 让前端页面实现错误的显示
jsonSchema 字段校验失败 
params = {
  release_date: '2024-05-74',
}

{
  "errors": [
    {
      "errorLocation": "/title",
      "errorKeyword": "required",
      "keywordSchema": null,
      "dependencies": ["/title"]
    },
    {
      "errorLocation": "/release_data",
      "errorKeyword": "format",
      "keywordSchema": "date",
      "dependencies": ["/release_data"]
    }
  ]
}

Validation 校验错误

  • errorLocation - 产生的错误在 jsonSchema 中的位置
  • errorMessage - 错误信息
  • dependencies - 产生该错误的依赖字段的位置
params = {
  title: 'a title',
  release_date: '4024-05-14',
}

{
  "errors": [
    {
      "errorLocation": "/release_date",
      "errorMessage": "excessive time",
      "dependencies": ["/release_date"]
    }
  ]
}

运行时错误

和 Elixir 给出的错误和含义均相同。

当这一类错误发生时，对用户来说相当于服务器内部错误，无法通过修改参数来解决。因此 不会用来决定页面的交互逻辑，只是返回一些信息能够帮助定位问题出现的原因。

  • location - 错误出现的位置
  • message - 错误信息的描述
returningSchema 中指定的列不存在 
params = {
  title: 'This is a valid title',
  release_date: '2024-05-14',
}

{
  "errors": [
    {
      "location": "#/returningSchema/inserted_at",
      "message": "column \"inserted_at\" does not exist"
    }
  ]
}

类型使用

JSONSchema

FormSchema

定义 FormSchema 的格式，用来约束 Form 类(创建表单，详情表单，更新用的表单) Schema 的格式

Usage

{
  "$schema": "https://cdn.jsdelivr.net/gh/byzanteam/taihaku-schemas/ui-schemas/form/schema.json",
  "schema": {...},
  "uiSchema": {...}
}

TableSchema

定义 TableSchema 的格式，用来约束 Table 类 Schema 的格式

Usage

{
  "$schema": "https://cdn.jsdelivr.net/gh/byzanteam/taihaku-schemas/ui-schemas/table/schema.json",
  "columns": {...},
  "uiSchema": {...}
}

TS 类型

通常在通过请求取得 Schema 的 json 实例后，通过断言成 FormSchema<TData, TCustomUIOptionMap> 或 TableSchema<TData, TCustomUIOptionMap> 类型来使用。 在 json -> ts 的过程中无需校验，校验服务应由 schemas 的伺服器解决，保证取得的数据一定符合对应的格式

Built and signed on
GitHub Actions
View transparency log

New Ticket: Report package

Please provide a reason for reporting this package. We will review your report and take appropriate action.

Please review the JSR usage policy before submitting a report.

Add Package

deno add jsr:@byzanteam/taihaku-schemas

Import symbol

import * as taihaku_schemas from "@byzanteam/taihaku-schemas";
or

Import directly with a jsr specifier

import * as taihaku_schemas from "jsr:@byzanteam/taihaku-schemas";

Add Package

pnpm i jsr:@byzanteam/taihaku-schemas
or (using pnpm 10.8 or older)
pnpm dlx jsr add @byzanteam/taihaku-schemas

Import symbol

import * as taihaku_schemas from "@byzanteam/taihaku-schemas";

Add Package

yarn add jsr:@byzanteam/taihaku-schemas
or (using Yarn 4.8 or older)
yarn dlx jsr add @byzanteam/taihaku-schemas

Import symbol

import * as taihaku_schemas from "@byzanteam/taihaku-schemas";

Add Package

npx jsr add @byzanteam/taihaku-schemas

Import symbol

import * as taihaku_schemas from "@byzanteam/taihaku-schemas";

Add Package

bunx jsr add @byzanteam/taihaku-schemas

Import symbol

import * as taihaku_schemas from "@byzanteam/taihaku-schemas";