@geekmidas/schema

中文文档
9.6.1发布于 2026/11/16TypeScriptESM + CJS构建来源已验证近 30 天下载 1.5万

Type utilities for working with StandardSchema-compatible validation libraries. Provides type inference helpers that work with any validation library implementing the StandardSchema specification (Zod, Valibot, ArkType, etc.).

原始使用文档
文档目录20 节
  1. Features
  2. Installation
  3. What is StandardSchema?
  4. API Reference
  5. InferStandardSchema<T>
  6. ComposableStandardSchema
  7. InferComposableStandardSchema<T>
  8. Usage with Zod
  9. Usage with Valibot
  10. Composable Schemas
  11. Generic Functions
  12. Factory Pattern
  13. API Endpoint Validation
  14. Type Guards
  15. Integration with @geekmidas/constructs
  16. Why Use This Package?
  17. Supported Validation Libraries
  18. TypeScript Configuration
  19. Related Packages
  20. License

@geekmidas/schema

Type utilities for working with StandardSchema-compatible validation libraries. Provides type inference helpers that work with any validation library implementing the StandardSchema specification (Zod, Valibot, ArkType, etc.).

Features

  • ✅ Type Inference: Extract output types from StandardSchema instances
  • ✅ Composable Schemas: Support for object-based schema composition
  • ✅ Zero Runtime Overhead: Pure TypeScript types with no runtime code
  • ✅ Universal Compatibility: Works with any StandardSchema-compatible library
  • ✅ Type Safety: Full TypeScript type inference and checking

Installation

pnpm add @geekmidas/schema

What is StandardSchema?

StandardSchema is a standard for schema validation libraries in TypeScript/JavaScript. It provides a unified interface that allows different validation libraries (Zod, Valibot, ArkType, etc.) to be used interchangeably.

This package provides TypeScript utilities to work with StandardSchema-compatible types.

API Reference

InferStandardSchema<T>

Infers the output type from a StandardSchema instance.

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

ComposableStandardSchema

Type for composable schemas - can be a single schema or an object of schemas.

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

InferComposableStandardSchema<T>

Infers types from composable schemas, supporting both single schemas and schema objects.

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;
      }
    : {};

Usage with Zod

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);
}

Usage with Valibot

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;
// }

Composable Schemas

Use ComposableStandardSchema and InferComposableStandardSchema to work with multiple schemas:

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'];

Generic Functions

Create generic functions that work with any StandardSchema:

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

Factory Pattern

Use composable schemas in factory patterns:

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 Endpoint Validation

Common pattern for API endpoint validation:

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
  };
}

Type Guards

Create type guards using schema inference:

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: '[email protected]' };

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

Integration with @geekmidas/constructs

This package is used internally by @geekmidas/constructs for type-safe endpoint validation:

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' };
  });

Why Use This Package?

  1. Type Safety: Ensures your types match your runtime validation schemas
  2. DRY Principle: Define schemas once, derive types automatically
  3. Refactoring Safety: Changing schemas automatically updates types
  4. Universal: Works with any StandardSchema-compatible library
  5. Zero Cost: Pure TypeScript types with no runtime overhead

Supported Validation Libraries

Any library implementing the StandardSchema specification, including:

TypeScript Configuration

Requires TypeScript 5.0 or higher with strict mode enabled:

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

License

MIT

版本与发布记录

@geekmidas/schema 共发布 203 个版本,首次发布于 2025/10/20;过去 12 个月发布了 201 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
9.6.1latest2026/11/16今天
10.0.0-alpha.185alpha2026/11/16今天
10.0.0-alpha.1842026/11/16今天
10.0.0-alpha.1832026/11/16今天
10.0.0-alpha.1822026/11/132 天前
10.0.0-alpha.1812026/11/133 天前

关于 @geekmidas/schema 的常见问题

@geekmidas/schema 是什么?

Type utilities for working with StandardSchema-compatible validation libraries. Provides type inference helpers that work with any validation library implementing the StandardSchema specification (Zod, Valibot, ArkType, etc.).

如何安装 @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 和提交记录判断。