# @geekmidas/schema 中文文档

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

版本：9\.6\.1
npm 元数据更新时间：2026-11-16T09:29:28.178Z
中文译文更新时间：2026-11-16T09:32:43.860Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：120 kB，58 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：zod ^4\.1\.13，zod-to-json-schema ~3\.25\.1，@valibot/to-json-schema \>=1\.3\.0
- 首次发布：2025-10-19T18:21:38.630Z
- 最新版本发布：2026-11-16T09:29:27.772Z
- 近 30 天下载量：14524（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：203（近 12 个月 201 个）

## 中文简介

与标准Schema兼容验证库合作的公用事业类型。 提供与执行标准Schema规格的任何验证库(Zod、Valibot、ArkType等)合作的类型的推论帮助.

## 安装

```sh
npm install @geekmidas/schema
```

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

## README

# @geekmidas/ schema (原始内容存档于2012-09-31)

与标准Schema兼容验证库合作的公用事业类型。 提供与执行标准Schema规格的任何验证库(Zod、Valibot、ArkType等)合作的类型的推论帮助.

## 特征

-   ✅ **类型推论**: 从标准Schema实例中提取输出类型
-   ✅ **可编译的Schemas**: 支持基于对象的构件
-   ✅ **0 运行时间超时**: 无运行时代码的纯类型脚本
-   ✅ **通用兼容性**: 任何标准Schema兼容库的工程
-   ✅ **类型安全**: 完整类型Script类型推断和检查

## 安装

```bash
pnpm add @geekmidas/schema
```

## 标准计划是什么?

[标准计划](https://github.com/standard-schema/standard-schema) 是TypeScript/JavaScript中用于计划验证库的标准. 它提供了一个统一的界面,可以让不同的验证库(Zod,Valibot,ArkType等)被互换使用.

这个软件包提供TypeScript公用设备,用于与标准Schema相兼容的类型相配合.

## API 参考

### `InferStandardSchema<T>`

从标准Schema实例推断输出类型.

```typescript
type InferStandardSchema<T> = T extends StandardSchemaV1
  ? StandardSchemaV1.InferOutput<T>
  : never;
```

### `ComposableStandardSchema`

可堆肥的生化子-可以是单生化子或生化子的对象.

```typescript
type ComposableStandardSchema =
  | StandardSchemaV1
  | {
      [key: string]: StandardSchemaV1 | undefined;
    };
```

### `InferComposableStandardSchema<T>`

推断出从可混凝土的生平图中分出的类型,支持单生平图和生平图对象.

```typescript
type InferComposableStandardSchema<T> = T extends StandardSchemaV1
  ? StandardSchemaV1.InferOutput<T>
  : T extends { [key: string]: StandardSchemaV1 | undefined }
    ? {
        [K in keyof T as T[K] extends StandardSchemaV1
          ? K
          : never]: T[K] extends StandardSchemaV1
          ? StandardSchemaV1.InferOutput<T[K]>
          : never;
      }
    : {};
```

## 对 Zod 的使用

```typescript
import type { InferStandardSchema } from '@geekmidas/schema';
import { z } from 'zod';

// Define a schema
const userSchema = z.object({
  id: z.string(),
  email: z.string().email(),
  age: z.number().min(18),
  role: z.enum(['admin', 'user'])
});

// Infer the type
type User = InferStandardSchema<typeof userSchema>;
// type User = {
//   id: string;
//   email: string;
//   age: number;
//   role: 'admin' | 'user';
// }

// Use the type
function processUser(user: User) {
  console.log(user.email);
}
```

## 用瓦利博特语

```typescript
import type { InferStandardSchema } from '@geekmidas/schema';
import * as v from 'valibot';

const productSchema = v.object({
  id: v.string(),
  name: v.string(),
  price: v.number(),
  inStock: v.boolean()
});

type Product = InferStandardSchema<typeof productSchema>;
// type Product = {
//   id: string;
//   name: string;
//   price: number;
//   inStock: boolean;
// }
```

## 可编译的Schemas

使用 `ComposableStandardSchema` 财务报告和审定财务报表 `InferComposableStandardSchema` 与多个计划合作:

```typescript
import type {
  ComposableStandardSchema,
  InferComposableStandardSchema
} from '@geekmidas/schema';
import { z } from 'zod';

// Define multiple schemas
const schemas = {
  user: z.object({
    id: z.string(),
    email: z.string().email()
  }),
  post: z.object({
    id: z.string(),
    title: z.string(),
    authorId: z.string()
  }),
  comment: z.object({
    id: z.string(),
    content: z.string(),
    postId: z.string()
  })
} satisfies Record<string, ComposableStandardSchema>;

// Infer types from all schemas
type Schemas = InferComposableStandardSchema<typeof schemas>;
// type Schemas = {
//   user: { id: string; email: string };
//   post: { id: string; title: string; authorId: string };
//   comment: { id: string; content: string; postId: string };
// }

// Use individual types
type User = Schemas['user'];
type Post = Schemas['post'];
type Comment = Schemas['comment'];
```

## 一般函数

创建与任何标准Schema合作的通用函数 :

```typescript
import type { InferStandardSchema } from '@geekmidas/schema';
import type { StandardSchemaV1 } from '@standard-schema/spec';

function validateData<T extends StandardSchemaV1>(
  schema: T,
  data: unknown
): InferStandardSchema<T> | null {
  const result = schema['~standard'].validate(data);

  if (result.issues) {
    console.error('Validation failed:', result.issues);
    return null;
  }

  return result.value as InferStandardSchema<T>;
}

// Usage with any schema
const userSchema = z.object({ name: z.string() });
const validatedUser = validateData(userSchema, { name: 'John' });
// validatedUser is typed as { name: string } | null
```

## 工厂模式

在工厂图案中使用可混凝土图案:

```typescript
import type {
  ComposableStandardSchema,
  InferComposableStandardSchema
} from '@geekmidas/schema';

class SchemaFactory<T extends Record<string, ComposableStandardSchema>> {
  constructor(private schemas: T) {}

  validate<K extends keyof T>(
    key: K,
    data: unknown
  ): InferComposableStandardSchema<T>[K] | null {
    const schema = this.schemas[key];
    if (!schema) return null;

    const result = schema['~standard'].validate(data);
    return result.issues ? null : result.value;
  }

  getSchema<K extends keyof T>(key: K): T[K] {
    return this.schemas[key];
  }
}

// Usage
const schemas = {
  user: z.object({ name: z.string() }),
  product: z.object({ sku: z.string(), price: z.number() })
};

const factory = new SchemaFactory(schemas);
const user = factory.validate('user', { name: 'John' });
// user is typed as { name: string } | null
```

## API 终点验证

API 端点验证的共同模式 :

```typescript
import type { InferStandardSchema } from '@geekmidas/schema';
import { z } from 'zod';

const createUserEndpoint = {
  body: z.object({
    name: z.string().min(1),
    email: z.string().email(),
    age: z.number().int().min(18)
  }),
  response: z.object({
    id: z.string(),
    name: z.string(),
    email: z.string()
  })
};

type CreateUserBody = InferStandardSchema<typeof createUserEndpoint.body>;
type CreateUserResponse = InferStandardSchema<typeof createUserEndpoint.response>;

async function createUser(
  data: CreateUserBody
): Promise<CreateUserResponse> {
  // Implementation with fully typed request and response
  return {
    id: '123',
    name: data.name,
    email: data.email
  };
}
```

## 类型警卫

使用策略推断创建类型守护 :

```typescript
import type { InferStandardSchema } from '@geekmidas/schema';
import { z } from 'zod';

const userSchema = z.object({
  id: z.string(),
  email: z.string().email()
});

type User = InferStandardSchema<typeof userSchema>;

function isUser(value: unknown): value is User {
  const result = userSchema.safeParse(value);
  return result.success;
}

// Usage
const data: unknown = { id: '123', email: 'user@example.com' };

if (isUser(data)) {
  // data is now typed as User
  console.log(data.email);
}
```

## 与 @geekmidas/ 构建

此软件包由内部使用 `@geekmidas/constructs` 用于类型安全终点验证:

```typescript
import { e } from '@geekmidas/constructs/endpoints';
import { z } from 'zod';

// The constructs package uses InferStandardSchema internally
const endpoint = e
  .post('/users')
  .body(z.object({ name: z.string() }))
  .output(z.object({ id: z.string() }))
  .handle(async ({ body }) => {
    // body is automatically typed as { name: string }
    return { id: '123' };
  });
```

## 为什么使用这个软件包?

1.  **类型安全**: 确保您的类型符合您的运行时间验证计划
2.  **饮用原则**: 定义一次计划, 自动生成类型
3.  **重构安全性**: 更改计划自动更新类型
4.  **通用**: 任何标准Schema兼容库的工程
5.  **零成本**: 无运行时间的纯类型脚本类型

## 支持的验证库

执行标准Schema规格的任何图书馆,包括:

-   [佐德语Name](https://github.com/colinhacks/zod)
-   [维利博特](https://github.com/fabian-hiller/valibot)
-   [ArkType 密码](https://github.com/arktypeio/arktype)
-   和任何未来的标准Schema兼容的库

## 类型脚本配置

需要使用严格模式的 5.0 或更高类型脚本 :

```json
{
  "compilerOptions": {
    "strict": true,
    "strictNullChecks": true
  }
}
```

## 相关软件包

-   [@geekmidas/ 构造](https://npmcn.com/package/%40geekmidas/constructs) - 使用这个包进行终点验证
-   [@geekmidas/envkit (英语)](https://npmcn.com/package/%40geekmidas/envkit) - 具有计划验证的环境配置
-   [@ standard-schema/ spec](https://github.com/standard-schema/standard-schema) - 标准计划规格

## 许可证

麻省理工学院

## 常见问题

### @geekmidas/schema 是什么？

与标准Schema兼容验证库合作的公用事业类型。 提供与执行标准Schema规格的任何验证库\(Zod、Valibot、ArkType等\)合作的类型的推论帮助\.

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

在项目目录运行 npm install @geekmidas/schema，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：zod（^4\.1\.13）、zod-to-json-schema（~3\.25\.1）、@valibot/to-json-schema（\>=1\.3\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

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

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

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

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

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

@geekmidas/schema 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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

