Schema：保留 JSON 声明与实际解析的同一合同

Support 生成规范的 SchemaAdapter，Core 只要求 jsonSchema 与同步 parse 合同。

defineSchema 固定声明快照并绑定原 parser 接收者。它不会根据 JSON Schema 自动猜出 TypeScript 类型，也不是内置通用验证器。JSON Schema 向模型说明允许的结构，parse 在真实运行边界验证该结构，两者都必须有效。

已有解析库可以使用 fromParserSchema，显式提供 toJsonSchema；只有 JSON Schema 时，fromJsonSchema 接受调用者拥有的 compile 函数。编译返回的校验器必须同步返回 boolean。不能用始终返回 true 的 parser 冒充验证，不能把泛型参数当作运行时校验。

由简到繁的同业务示例

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

入门 · 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 快照与同步校验规则