# @effected/schemastore 中文文档

规范地址：https://npmcn.com/package/%40effected/schemastore/

版本：0\.33\.0
npm 元数据更新时间：2026-11-12T19:05:25.598Z
中文译文更新时间：2026-11-13T09:18:37.636Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40effected/schemastore
原文对照：https://npmcn.com/package/%40effected/schemastore/?lang=original
项目主页：https://github.com/spencerbeggs/effected/tree/main/packages/schemastore#readme
源码仓库：https://github.com/spencerbeggs/effected

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

- 包体积（解压后）：233 kB，23 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.11\.0
- 运行依赖：2 个
- peer 依赖：effect ~4\.1\.0
- 首次发布：2026-08-03T00:02:01.390Z
- 最新版本发布：2026-11-12T19:05:25.186Z
- 近 30 天下载量：7396（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：52（近 12 个月 52 个）

## 中文简介

从 Effect Schema 来源建立,验证,版本并发布 SchemaStore-形状的 Draft-07 JSON Schema 文档:文档组装, ajv 严格模式验证,结构线条,目录条目,canonical JSON 和一个内容相仿的放出管.

## 安装

```sh
npm install @effected/schemastore
```

也可以使用：`pnpm add @effected/schemastore`、`yarn add @effected/schemastore`、`bun add @effected/schemastore`

## README

# @ 受影响/ 计划

[![npm](https://img.shields.io/npm/v/@effected%2Fschemastore?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/schemastore) [![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT) [![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/) [![TypeScript 7.0](https://img.shields.io/badge/TypeScript-7.0-3178c6.svg)](https://www.typescriptlang.org/)

以 SchemaStore 形状的 Draft-07 JSON Schema 文档发布效果 Schemas 。 核心 `effect` 已经生成 JSON Schema (`Schema.toJsonSchemaDocument`)并降低到草案07(`JsonSchema.toDocumentDraft07`); 此软件包拥有什么 [司马斯托尔](https://www.schemastore.org/) 编辑们期望这一产出——出版形状、主机身份文件发表在下面、关键词-家庭门、目录条目、插图、版本、Cononic JSON和内容比较文件IO——和 [`effected schema`](https://www.npmjs.com/package/@effected/plugin) 命令从一个配置文件中运行全部.

> **预`1.0.0`。 。 。 .** 此软件包是 `@effected/*` 在稳定基础上建造的工具包 效应v4(`effect` `~4.1.0`) 并仍在 `0.x` 发展。 稳定效果 制作一个工具箱 `1.0.0` 可能,不是自动的。 为了保持你的 `effect` 财务报告和审定财务报表 `@effect/*` 该工具包在线上构建和测试、安装 [`@effected/pnpm-plugin-effected`](https://www.npmjs.com/package/@effected/pnpm-plugin-effected)。 。 。 .
> 
> **稳定:不稳定.** 此软件包的 API 表面尚未考虑 完成并可能改变 `0.x` 释放 定一个确切的版本——甚至 标记软件包 _稳定_ 在此之前 `1.0.0` 可以引入突破性更改 和精确的针 变成一个类型检查错误 而不是一个 跑步时间惊喜。 完全政策: [释放策略](https://github.com/spencerbeggs/effected#release-strategy)。 。 。 .

## 安装

两个角色:这个库是发布 schema(它的代码读取 schema 的身份在运行时)的应用程序的常规依赖,以及 `@effected/plugin` 是提供 `effected schema` 命令,用于构建和检查文档.

```bash
pnpm add @effected/schemastore effect
pnpm add -D @effected/plugin
```

要求节点.js >=24.11.0. 仅限无害环境管理. `effect` v4是唯一的对等者; `@effected/semver` (版本命令)是唯一的运行时间依赖. 这里没有验证引擎—— `SchemaValidator` 是合同,运出ajv严格型号的发动机是 `AjvValidator` 内 `@effected/engine/schema` ——在运行时导入此软件包从不安装或捆绑 ajv.

## 这两套东西怎么搭配的

模式有三个部分。 申请宣布每个计划 **主机身份** 一次,在计划旁边,阅读 `$schema` URL,它从中写入自己的输出. 配置文件将相同的值交到 `defineConfig`命令产生每一个路径, `$id` 和目录 URL 从他们, 所以没有拼写两次.

```ts
// src/schema/output.ts — the application
import { HostedSchema } from "@effected/schemastore";
import { Schema } from "effect";

export const OUTPUT_SCHEMA_VERSION = "5.2";

export const OutputSchemaIdentity = HostedSchema.github({
  repo: "savvy-web/silk-release-action",
  path: "schemas",
  name: "silk-release-action.output",
  versions: [OUTPUT_SCHEMA_VERSION],
});

// Every payload the application emits names the document it was written against.
export const ReleaseOutput = Schema.Struct({
  $schema: Schema.Literal(OutputSchemaIdentity.$id),
  status: Schema.Literals(["released", "skipped"]),
});
```

```ts
// schemastore.config.ts — the config
import { defineConfig } from "@effected/schemastore";
import { OutputSchemaIdentity, ReleaseOutput } from "./src/schema/output.js";

export default defineConfig({
  name: "silk-release-action",
  outputDir: "schemas",
  schemas: {
    [OutputSchemaIdentity.name]: { schema: ReleaseOutput, hosted: OutputSchemaIdentity },
  },
});
```

```json
{
  "scripts": {
    "schema:build": "effected schema build",
    "schema:check": "effected schema check"
  }
}
```

`effected schema build` 写入 `schemas/5.2/silk-release-action.output-5.2.json` 与 `$id` 等于 `OutputSchemaIdentity.$id`,封闭对象(`additionalProperties: false`页:1 `$schema` 说明申请所声称的内容. `effected schema check` 是 CI 门: 当一个建筑会写出任何东西时, 它失败 。 弹出版本为一常. 命令所做的一切——漂移政策 `published` 旗帜、被冻结的标签、目录文件、退出代码——记录在 [工具的页面](https://www.npmjs.com/package/@effected/plugin)。 。 。 .

`HostedSchema.github({ repo, branch?, path?, ... })` 从寄存器中服务原始文件( e)`branch` 默认为 `main`(三); `HostedSchema.schemastore({ name, ... })` 向SchemaStore出版(`$id` 打开 `json.schemastore.org`,打开目录 URL `www.schemastore.org`平面布局; `HostedSchema.custom({ baseUrl, ... })` 使用任意 `https://` 作为字符串或 `URL`每一个都验证身份—— `current` 必须是其中之一 `versions`,两个拼写一个标签被拒绝——并扔出平地 `Error` 命名原因. `$id`, (中文(简体) ), `url` 财务报告和审定财务报表 `fileName` 答复当前文件; `idFor`, (中文(简体) ), `urlFor` 财务报告和审定财务报表 `fileNameFor` 回答任何广告版本。 版本文件带有 SchemaStore 的 `-<version>` 默认后缀; 当版本目录只命名文件时(`schemas/6.0/output.json`,自然当寄存器已经命名工具时),通过 `appendVersion: false` -它需要的就是... -我需要... - it needs the `"versioned"` 版式,因为 `"flat"` 每个版本都会共享一个文件名. 消费者测试针 `target.path === \`${outputDir}/${身份. file {}`to catch a swapped`主办方:\`国家行动倡议看不到.

## 直接使用库

命令所编作的一切都是输出的,对于一个需要一块或想自己驱动管道的程序.

`StoreDocument.fromSchema` 运行一个组件——2020-12代,Draft-07降低 `#/definitions` → `#/$defs` 重写和关键词 - 家门—— 所以每个 `$ref` 在已建文件中 `$defs` 池内 :

```ts
import { StoreDocument } from "@effected/schemastore";
import { Effect, Schema } from "effect";

const Config = Schema.Struct({ name: Schema.String });

const program = Effect.gen(function* () {
  const document = yield* StoreDocument.fromSchema(Config, {
    $id: "https://example.com/config.schema.json",
  });
  return yield* Effect.fromResult(document.serializeResult());
});
// { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "…", "type": "object", …, "additionalProperties": false }
```

对象默认关闭——一个已发布的文档是合同,而这个软件包并不遵循核心的开放默认. `jsonSchema: { onExcessProperty: "ignore" }` 一个目标(或一个) `defineConfig` )重新打开文档.

`SchemaPipeline.run(targets)` 是一个目标显示的发射回路——生成、涂抹、验证、门、写——需要 `SchemaFile` 财务报告和审定财务报表 `SchemaValidator` 内 `R`。在边缘提供文件服务和引擎;引擎是 `@effected/engine/schema`':

```ts
import { SchemaFile, SchemaPipeline, SchemaTarget } from "@effected/schemastore";
import { AjvValidator } from "@effected/engine/schema";
import * as NodeServices from "@effect/platform-node/NodeServices";
import { Effect, Layer, Schema } from "effect";

const targets = [
  SchemaTarget.make({
    schema: Schema.Struct({ name: Schema.String }),
    $id: "https://example.com/config.schema.json",
    path: "schemas/config.schema.json",
  }),
];

const program = SchemaPipeline.run(targets).pipe(
  Effect.provide(Layer.mergeAll(SchemaFile.layer, AjvValidator.layer).pipe(Layer.provide(NodeServices.layer))),
);
```

`run` 目标分为两相或全相或全相:每个目标都是生成的、有门的和——为固定版本——在撰写任何文件之前按其前身分类。 阻断查找失败 `SchemaGateError`; 绑定的、已公布版本的合同更改失败 `SchemaContractChangeError` 携带 `nextVersion` 改为:`contractChanges: "allow"` 仅分类和报告). `check` 和没有写作的一样 调查结果是数值,从不记录,以及指向上游(`blocking`)是你的替换.

## 图书馆拥有的

-   `HostedSchema` ——一个schema的主机身份(`github`, (中文(简体) ), `schemastore`, (中文(简体) ), `custom`),产生 `$id`,当前版本或任何广告版本的目录 URL和文件名.
-   `defineConfig` - 那个 `schemastore.config.ts` 合同:经一个合同确认 `Schema.Struct` 每个关卡(一个打字"d"键被命名,一个条目上的每期一次报告),一个需要的配置 `name` (其目录片的基名),来自条目密钥及其身份的每一个路径和URL,一个可选的 `catalog.name` 显示名称( 默认为密钥, 在配置中独有) , 重新命名目录条目, 没有其它名称, 冻结的标签被解析 , 这是 CLI 识别的品牌结果 .
-   `StoreDocument` - 组装: `fromSchema` 编号 : `fromSchemaResult`,则 `draft07` 手建文件的构造器,平面 `toJson()` 出版物形状, `serializeResult()`, (中文(简体) ), `DRAFT_07_META_SCHEMA`。 。 。 .
-   `KeywordFamilies` 申报的非标准关键字家族登记册(vscode 5, `x-taplo`, (中文(简体) ), `x-tombi-`, (中文(简体) ), `x-intellij-`还有房子 `x-ai-` 机器命名空间)。 外面的任何东西都失败了 `fromSchema` 与 `UndeclaredAnnotationKeyError`;没有什么是默默地放弃的.
-   `SchemaVersioning` 编号 : `SchemaVersion` 1至3个组件版本标签, `Order`, (中文(简体) ), `latest`, (中文(简体) ), `isPinned`, (中文(简体) ), `next`,则 `fileName` 编号 : `schemaUrl` 编号 : `catalogUrls` 衍生物.
-   `CatalogEntry` - 那个 `catalog.json` 作为条目 `Schema.Class`, (中文(简体) ), `assemble` 用于目录模式和目录模式 `fileMatch` 卫生用品.
-   `DocumentLint` ——总结构线条`UnresolvedRef`, (中文(简体) ), `UnknownKeyword`, (中文(简体) ), `DepthExceeded`, (中文(简体) ), `DescriptionWithoutUrl`),发现作为价值.
-   `SchemaValidator` 审定合同: `noop` 关掉它, `makeTest` 编号 : `layerTest` 是双倍的; `ValidationFinding` 财务报告和审定财务报表 `SchemaValidatorError` 是它的价值观。 发动机是 `AjvValidator` 内 `@effected/engine/schema`。 。 。 .
-   `DocumentDiff` —— 说 `classify` 两个文件作为 `"none"` 编号 : `"annotations"` 编号 : `"contract"`,表示更改是否需要新版本.
-   `DriftPolicy` ——适用CLI的生命周期规则: `published` 文档为容忍(`strict` 编号 : `semantic` 编号 : `allow`),未出版的被重新生成.
-   `SchemaPipeline` ——出环: `run` 编号 : `check`, (中文(简体) ), `runOne` 编号 : `checkOne`大门和合同警卫.
-   `SchemaFile` ——写出-如果修改了IO于核心 `FileSystem` 编号 : `Path`,通过解析内容进行比较,所以拥有文件文本的前题不会切入; `check` 是非写入的一半.
-   `CanonicalJson` 确定序列器(插入顺序、制表符、一条后继新行、打出故障)和 `equals`一个内容平等规则.

## 许可证

麻省理工学院

## 常见问题

### @effected/schemastore 是什么？

从 Effect Schema 来源建立,验证,版本并发布 SchemaStore-形状的 Draft-07 JSON Schema 文档:文档组装, ajv 严格模式验证,结构线条,目录条目,canonical JSON 和一个内容相仿的放出管\.

### 如何安装 @effected/schemastore？

在项目目录运行 npm install @effected/schemastore，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：effect（~4\.1\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @effected/schemastore 支持 TypeScript 吗？

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

### @effected/schemastore 支持 ESM 还是 CommonJS？

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

### @effected/schemastore 需要什么版本的 Node\.js？

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

### @effected/schemastore 可以商用吗？

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

### @effected/schemastore 的下载量有多少？

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

### @effected/schemastore 还在维护吗？

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