fromJsonSchema

SUPPORT · function · 运行时值

Build an adapter from a caller-owned typed JSON Schema compiler.

The schema is cloned and frozen before it reaches the compiler, so later mutation of the input cannot change validation. Compilation and validation must both be synchronous.

导入

TypeScript

import { fromJsonSchema } from '@jangts/agent-core/support';

JavaScript

import { fromJsonSchema } from '@jangts/agent-core/support';

其他公开入口：@jangts/agent-core/support。

定义

泛型参数

类型参数	约束	默认类型
Value	—	unknown

调用

fromJsonSchema<Value = unknown>(schema: JsonSchema, options: JsonSchemaOptions<Value>): SchemaAdapter<Value>

Build an adapter from a caller-owned typed JSON Schema compiler.

The schema is cloned and frozen before it reaches the compiler, so later mutation of the input cannot change validation. Compilation and validation must both be synchronous.

类型参数	约束	默认类型
Value	—	unknown

参数	类型	传递	说明
schema	Readonly<Record<string, unknown>>	必需	—
options	JsonSchemaOptions<Value>	必需	—

options 的字段

字段	类型	必需	说明
compile	(schema: Record<string, unknown>) => JsonSchemaValidator<Value>	必需	Compiles a frozen schema copy into a validator; must return synchronously.
error	((value: unknown, errors: unknown) => Error) | undefined	可省略	Builds the thrown error for an invalid value; defaults to a TypeError.

返回： SchemaAdapter<Value>。

返回值结构

字段	类型	必需	说明
jsonSchema	Readonly<Record<string, unknown>>	必需	只读。Schema advertised to the model and used for documentation.
parse	(input: unknown) => Value	必需	Validates or coerces untrusted input into Value; throws when the input is invalid.

使用示例

• Schema：保留 JSON 声明与实际解析的同一合同：Support 生成规范的 SchemaAdapter，Core 只要求 jsonSchema 与同步 parse 合同。

一个有实际校验的字符串对象

入门 · Node.js

TypeScript

import { Support } from '@jangts/agent-core';
const nameSchema = Support.defineSchema({
  jsonSchema: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'], additionalProperties: false },
  parse(value: unknown) {
    if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).length !== 1 || !('name' in value) || typeof value.name !== 'string') throw new TypeError('需要 name 字符串');
    return { name: value.name };
  },
});
console.log(nameSchema.parse({ name: 'Ivan' }));

JavaScript

import { Support } from '@jangts/agent-core';
const nameSchema = Support.defineSchema({
    jsonSchema: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'], additionalProperties: false },
    parse(value) {
        if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).length !== 1 || !('name' in value) || typeof value.name !== 'string')
            throw new TypeError('需要 name 字符串');
        return { name: value.name };
    },
});
console.log(nameSchema.parse({ name: 'Ivan' }));

复用已经拥有的解析对象

配置 · Node.js

实际接解析库时，toJsonSchema 必须准确表达该 parser；不是库名称决定可信度。

TypeScript

import { Support } from '@jangts/agent-core';
class NameParser {
  parse(value: unknown) { if (typeof value !== 'string' || !value.trim()) throw new TypeError('需要非空姓名'); return value.trim(); }
}
const schema = Support.fromParserSchema(new NameParser(), {
  toJsonSchema: () => ({ type: 'string', minLength: 1 }),
});
console.log(schema.parse(' Ivan '));

JavaScript

import { Support } from '@jangts/agent-core';
class NameParser {
    parse(value) { if (typeof value !== 'string' || !value.trim())
        throw new TypeError('需要非空姓名'); return value.trim(); }
}
const schema = Support.fromParserSchema(new NameParser(), {
    toJsonSchema: () => ({ type: 'string', minLength: 1 }),
});
console.log(schema.parse(' Ivan '));

使用已有 JSON Schema 编译端口

扩展 · Node.js

演示显式编译端口，不是一个通用 JSON Schema 编译器；生产可接入 App 已有的成熟编译器。

TypeScript

import { Support } from '@jangts/agent-core';
const schema = Support.fromJsonSchema<number>({ type: 'integer', minimum: 0 }, {
  compile(jsonSchema) {
    if (jsonSchema.type !== 'integer' || jsonSchema.minimum !== 0) throw new Error('本例编译器只处理该规则');
    return (value: unknown): value is number => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
  },
});
console.log(schema.parse(3));

JavaScript

import { Support } from '@jangts/agent-core';
const schema = Support.fromJsonSchema({ type: 'integer', minimum: 0 }, {
    compile(jsonSchema) {
        if (jsonSchema.type !== 'integer' || jsonSchema.minimum !== 0)
            throw new Error('本例编译器只处理该规则');
        return (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
    },
});
console.log(schema.parse(3));

相关策略源码

• Schema 快照与同步校验规则

相关定义

• JsonSchema
• JsonSchemaOptions
• SchemaAdapter