@zhin.js/schema 1.1.0 → 1.1.2

package/README.md

@@ -124,21 +124,51 @@ const formatter = Schema.resolve('number')
 
 ## 与 Zhin.js 集成
 
-在插件中使用 `defineSchema` 定义配置（自动注册到 Web 控制台表单渲染）：
+Plugin Runtime 可以直接使用同一份声明推导类型、生成标准 JSON Schema、校验配置、填充默认值并向 Console 提供表单元信息：
 
 ```typescript
-import { usePlugin, Schema } from 'zhin.js'
+import { definePlugin, Schema } from 'zhin.js'
 
-const { defineSchema } = usePlugin()
+const configSchema = Schema.object({
+  interval: Schema.number().min(1).default(300).description('轮询间隔，秒').effect('reload'),
+  enabled: Schema.boolean().default(true),
+  apiKey: Schema.string().required().secret().component('password'),
+  label: Schema.string(),
+})
 
-const getConfig = defineSchema(Schema.object({
-  port: Schema.number().default(8080).description('服务端口'),
-  enabled: Schema.boolean().default(true).description('是否启用'),
-}))
+type Config = Schema.Output<typeof configSchema>
+// interval、enabled、apiKey 为必有字段；label 为 string | undefined。
+
+export default definePlugin({
+  name: 'subscription',
+  config: configSchema,
+  setup({ config }) {
+    const current = config.get() // 自动推导 Config，不再手写泛型
+    console.log(current.interval, current.enabled)
+  },
+})
+```
+
+应用配置的密钥仍使用环境引用：
 
-const config = getConfig()
+```yaml
+plugins:
+  subscription:
+    apiKey: ${SUBSCRIPTION_API_KEY}
 ```
 
+`secret()` 声明仅用于表单和数据处理提示，不储存密钥、也不负责读取环境变量；它会导出标准 `writeOnly: true` 与 `x-zhin-config.secret` 元信息，并拒绝密钥默认值。环境展开和配置校验由现有 Runtime 完成。`.effect('reload')` 表明插件更新后重载；系统配置的进程重启由 Root Host 决定。
+
+`schema.toJsonSchema()` 返回标准 JSON Schema 2020-12；默认值、范围、枚举、描述与 `x-zhin-config` 表单提示均从同一声明生成。Runtime 的现有校验器负责校验与默认值，不增加第二套配置引擎。对象默认不接受未知属性；字典使用 `Schema.dict()`。配置只能使用 JSON 值；业务 `date/regexp` 无法导出为配置契约。
+
+这份内联声明适用于 trusted 插件；isolated 插件保持根目录 `schema.json`，Host 不执行其入口。单个插件不能同时声明 `config` 与 `schema.json`，避免两个来源漂移。`schema.json` 仍支持只有 JSON 配置契约的插件。
+
+插件配置根必须是对象；没有自有字段时可省略 `properties`，`{}` 是合法的空配置声明。声明字段使用 `properties`，不能只依赖根级组合或引用来提供字段。Console 支持基础嵌套对象、列表、字典及字段元信息；`union`、`intersect`、`tuple` 可以导出标准校验契约，但组合类型和 `$ref` 的完整表单编辑仍需独立 Console 前端协同验收，当前 Console 对不支持的形态明确报错。
+
+`union` 的默认值应声明在联合字段自身（例如 `Schema.union([...]).default(...)`）；联合分支内部的默认值无法由 Runtime 确定应用到哪一分支，因此导出时明确拒绝。直接作为联合选项的 `Schema.const(...)` 可以使用，但分支对象内的 `Schema.const(...)` 也携带默认值，同样受此限制。
+
+现有业务输入解析和 `schema.toJSON()` / `Schema.fromJSON()` 保持各自的内部序列化格式；使用标准配置契约请调用 `.toJsonSchema()`。
+
 ## 工具函数
 
 - `isEmpty(value)` - 检查值是否为空（`undefined`、`null`、空字符串、空数组、空对象）
@@ -181,7 +211,10 @@ const config = getConfig()
 | `.max(value)` | 设置最大值 |
 | `.step(value)` | 设置步长 |
 | `.component(name)` | 指定渲染组件 |
-| `.toJSON()` | 序列化为 JSON |
+| `.toJSON()` | 业务 Schema 的内部序列化 |
+| `.toJsonSchema()` | 导出标准配置 JSON Schema |
+| `.secret()` | 密钥表单元信息，配置继续使用环境引用 |
+| `.effect('reload')` | 配置生效方式提示 |
 
 ## License
 

package/lib/index.d.ts

@@ -1,3 +1,4 @@
 export * from './schema.js';
 export * from './validate.js';
 export * from './utils.js';
+export * from './json-schema.js';

package/lib/index.js

@@ -1,3 +1,4 @@
 export * from './schema.js';
 export * from './validate.js';
 export * from './utils.js';
+export * from './json-schema.js';

package/lib/json-schema.d.ts

@@ -0,0 +1,12 @@
+import type { Schema } from './schema.js';
+/** Form annotations on the same JSON Schema used for configuration validation. */
+export interface ConfigFieldMetadata {
+    readonly secret?: boolean;
+    readonly hidden?: boolean;
+    readonly component?: string;
+    readonly options?: readonly Schema.Option[];
+    readonly effect?: 'reload';
+}
+export type ConfigJsonSchema = Readonly<Record<string, unknown>>;
+/** Export serializable configuration declarations; non-JSON business types are explicit errors. */
+export declare function toJsonSchema(schema: Schema): ConfigJsonSchema;

package/lib/json-schema.js

@@ -0,0 +1,183 @@
+/** Export serializable configuration declarations; non-JSON business types are explicit errors. */
+export function toJsonSchema(schema) {
+    const { meta, options } = schema;
+    const result = {};
+    switch (meta.type) {
+        case 'string':
+        case 'number':
+        case 'boolean':
+            result.type = meta.type;
+            break;
+        case 'object': {
+            result.type = 'object';
+            result.additionalProperties = false;
+            const shape = options.object ?? {};
+            result.properties = Object.fromEntries(Object.entries(shape).map(([key, field]) => [key, toJsonSchema(field)]));
+            const required = Object.entries(shape).filter(([, field]) => field.meta.required).map(([key]) => key);
+            if (required.length)
+                result.required = required;
+            break;
+        }
+        case 'dict':
+            result.type = 'object';
+            result.additionalProperties = toJsonSchema(options.inner);
+            break;
+        case 'list':
+            result.type = 'array';
+            result.items = toJsonSchema(options.inner);
+            break;
+        case 'tuple':
+            result.type = 'array';
+            result.prefixItems = (options.list ?? []).map(toJsonSchema);
+            result.items = false;
+            result.minItems = result.maxItems = options.list?.length ?? 0;
+            break;
+        case 'union':
+            for (const branch of options.list ?? [])
+                assertUnionBranchDefaults(branch, true);
+            result.anyOf = (options.list ?? []).map(toJsonSchema);
+            break;
+        case 'intersect': {
+            const branches = (options.list ?? []).map(toJsonSchema);
+            if (branches.every(branch => branch.type === 'object')) {
+                result.type = 'object';
+                // Close the combined shape, rather than making each object reject
+                // properties contributed by the other intersection branches.
+                result.unevaluatedProperties = false;
+                result.allOf = branches.map(branch => {
+                    // The outer intersection owns closure, including nested intersections.
+                    const { additionalProperties, unevaluatedProperties, ...rest } = branch;
+                    const openBranch = { ...rest };
+                    if (additionalProperties !== false && additionalProperties !== undefined) {
+                        openBranch.additionalProperties = additionalProperties;
+                    }
+                    if (unevaluatedProperties !== false && unevaluatedProperties !== undefined) {
+                        openBranch.unevaluatedProperties = unevaluatedProperties;
+                    }
+                    return openBranch;
+                });
+            }
+            else
+                result.allOf = branches;
+            break;
+        }
+        case 'const':
+            result.const = meta.default;
+            break;
+        case 'any': break;
+        default: throw new TypeError(`Schema type ${meta.type} cannot describe JSON configuration`);
+    }
+    if (meta.description !== undefined)
+        result.description = meta.description;
+    if (meta.default !== undefined) {
+        assertJsonValue(meta.default);
+        assertPublicDefault(schema, meta.default);
+        result.default = structuredClone(meta.default);
+    }
+    const minKey = meta.type === 'number' ? 'minimum' : meta.type === 'string' ? 'minLength' : meta.type === 'list' ? 'minItems' : undefined;
+    const maxKey = meta.type === 'number' ? 'maximum' : meta.type === 'string' ? 'maxLength' : meta.type === 'list' ? 'maxItems' : undefined;
+    if (meta.min !== undefined && minKey)
+        result[minKey] = meta.min;
+    if (meta.max !== undefined && maxKey)
+        result[maxKey] = meta.max;
+    if (meta.step !== undefined && meta.type === 'number') {
+        if (!Number.isFinite(meta.step) || meta.step <= 0)
+            throw new TypeError('Configuration step must be a positive finite number');
+        result.multipleOf = meta.step;
+    }
+    if (meta.options?.length) {
+        for (const option of meta.options)
+            assertJsonValue(option.value);
+        result.enum = structuredClone(meta.options.map(option => option.value));
+    }
+    if (meta.secret)
+        result.writeOnly = true;
+    const annotations = {
+        ...(meta.secret ? { secret: true } : {}),
+        ...(meta.hidden ? { hidden: true } : {}),
+        ...(meta.component !== undefined ? { component: meta.component } : {}),
+        ...(meta.options !== undefined ? { options: structuredClone(meta.options) } : {}),
+        ...(meta.effect !== undefined ? { effect: meta.effect } : {}),
+    };
+    if (Object.keys(annotations).length)
+        result['x-zhin-config'] = annotations;
+    return result;
+}
+/** Ajv cannot apply defaults inside anyOf alternatives without choosing a branch. */
+function assertUnionBranchDefaults(schema, branchRoot = false) {
+    // A literal alternative carries its value as an intrinsic const annotation;
+    // it never fills a nested property and must remain usable in literal unions.
+    if (schema.meta.default !== undefined && !(branchRoot && schema.meta.type === 'const')) {
+        throw new TypeError('Defaults inside union alternatives cannot be applied by Runtime; place the default on the union field');
+    }
+    for (const field of Object.values(schema.options.object ?? {}))
+        assertUnionBranchDefaults(field);
+    if (schema.options.inner)
+        assertUnionBranchDefaults(schema.options.inner);
+    for (const item of schema.options.list ?? [])
+        assertUnionBranchDefaults(item, schema.meta.type === 'union');
+}
+/** Defaults on an enclosing object/list must not smuggle a secret into forms. */
+function assertPublicDefault(schema, value) {
+    if (value === undefined)
+        return;
+    if (schema.meta.secret) {
+        throw new TypeError('Secret configuration fields cannot contain default values; reference an environment variable');
+    }
+    switch (schema.meta.type) {
+        case 'object':
+            if (value && typeof value === 'object' && !Array.isArray(value)) {
+                for (const [key, field] of Object.entries(schema.options.object ?? {})) {
+                    assertPublicDefault(field, value[key]);
+                }
+            }
+            break;
+        case 'dict':
+            if (value && typeof value === 'object' && !Array.isArray(value)) {
+                for (const item of Object.values(value))
+                    assertPublicDefault(schema.options.inner, item);
+            }
+            break;
+        case 'list':
+        case 'tuple':
+            if (Array.isArray(value))
+                value.forEach((item, index) => {
+                    const inner = schema.meta.type === 'list' ? schema.options.inner : schema.options.list?.[index];
+                    if (inner)
+                        assertPublicDefault(inner, item);
+                });
+            break;
+        case 'union':
+            // Validate-only matching is deliberately broader than JSON constraints:
+            // inspect every structurally matching branch, including overlaps, so a
+            // secret branch can never be bypassed by choosing a public alternative.
+            for (const branch of schema.options.list ?? []) {
+                if (branch.safeParse(value).success)
+                    assertPublicDefault(branch, value);
+            }
+            break;
+        case 'intersect':
+            for (const branch of schema.options.list ?? [])
+                assertPublicDefault(branch, value);
+            break;
+    }
+}
+function assertJsonValue(value, parents = new Set()) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return;
+    if (typeof value === 'object') {
+        if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+            throw new TypeError('Configuration defaults must contain only JSON values');
+        }
+        if (parents.has(value))
+            throw new TypeError('Configuration defaults cannot be cyclic');
+        parents.add(value);
+        for (const item of Object.values(value))
+            assertJsonValue(item, parents);
+        parents.delete(value);
+        return;
+    }
+    throw new TypeError('Configuration defaults must contain only JSON values');
+}

package/lib/schema.d.ts

@@ -1,9 +1,14 @@
 import { safeParseSchema, type SchemaSafeParseResult } from './validate.js';
+import { type ConfigFieldMetadata } from './json-schema.js';
 export { SchemaValidationError, type SchemaSafeParseResult, type SchemaValidationIssue } from './validate.js';
 export { safeParseSchema };
+declare const configPresent: unique symbol;
+declare const inputRequired: unique symbol;
 export declare class Schema<S = any, T = S> {
     meta: Schema.Meta<S, T>;
     options: Schema.Options;
+    /** Type-only output witness used by Plugin configuration inference. */
+    readonly output?: T;
     [Symbol.toStringTag]: string;
     constructor(meta: Schema.Meta<S, T>, options?: Schema.Options);
     static fromJSON<S, T>(json: Schema.JSON<S, T>): Schema<S, T>;
@@ -13,13 +18,19 @@ export declare class Schema<S = any, T = S> {
         meta: boolean;
     };
     /** 设置是否必填 */
-    required(): this;
+    required(): this & Schema.Present & Schema.Required;
     /** 是否隐藏 */
     hidden(): this;
     /** 设置描述 */
     description(description: string): this;
     /** 设置默认值 */
-    default(defaultValue: T): this;
+    default(defaultValue: T): this & Schema.Present;
+    /** Secret values remain environment references in application configuration. */
+    secret(): this;
+    /** Declare the effect shown in configuration forms. */
+    effect(effect: ConfigFieldMetadata['effect']): this;
+    /** Export the standard JSON Schema consumed by Runtime and Console. */
+    toJsonSchema(): Readonly<Record<string, unknown>>;
     /** 设置选项列表 */
     option(list: (T | Schema.Option<T>)[]): this;
     /** 设置是否允许多选 */
@@ -43,18 +54,18 @@ export declare class Schema<S = any, T = S> {
     /** 声明一个日期类型 */
     static date(key?: string): Schema<number | Date, Date>;
     /** 声明一个字典类型 */
-    static dict<X extends Schema>(input: X, key?: string): Schema<Record<string, Schema.Types<X>>, Record<string, Schema.Types<X>>>;
-    static object<X extends Record<string, Schema<any, any>>>(input: X, key?: string): Schema<Schema.RecordTypes<X>, Schema.RecordTypes<X>>;
+    static dict<X extends Schema>(input: X, key?: string): Schema<Record<string, Schema.Input<X>>, Record<string, Schema.Output<X>>>;
+    static object<X extends Record<string, Schema<any, any>>>(input: X, key?: string): Schema<Schema.InputRecord<X>, Schema.RecordTypes<X>>;
     /** 声明一个列表类型 */
-    static list<X extends Schema>(inner: X, key?: string): Schema<Schema.Types<X>[], Schema.Types<X>[]>;
+    static list<X extends Schema>(inner: X, key?: string): Schema<Schema.Input<X>[], Schema.Output<X>[]>;
     /** 声明一个元组类型 */
-    static tuple<X extends readonly any[]>(list: X, key?: string): Schema<Schema.Tuple<X>, Schema.Tuple<X>>;
+    static tuple<const X extends readonly any[]>(list: X, key?: string): Schema<Schema.InputTuple<X>, Schema.Tuple<X>>;
     /** 声明一个联合类型 */
-    static union<X extends readonly Schema[]>(list: X, key?: string): Schema<Schema.Union<X>>;
+    static union<const X extends readonly Schema[]>(list: X, key?: string): Schema<Schema.InputUnion<X>, Schema.Union<X>>;
     /** 声明一个交叉类型 */
-    static intersect<X extends readonly any[]>(list: X, key?: string): Schema<Schema.Intersect<X>, Schema.Intersect<X>>;
+    static intersect<const X extends readonly any[]>(list: X, key?: string): Schema<Schema.InputIntersect<X>, Schema.Intersect<X>>;
     /** 声明一个常量 */
-    static const<X extends string | number | boolean>(value: X, key?: string): Schema<X, X>;
+    static const<X extends string | number | boolean>(value: X, key?: string): Schema<X> & Schema.Present;
     /** 声明任意类型 */
     static any(key?: any): Schema<any, any>;
     /**
@@ -63,7 +74,7 @@ export declare class Schema<S = any, T = S> {
      */
     static discriminatedUnion<D extends string, V extends Record<string, Record<string, Schema<any, any>>>>(discriminator: D, variants: V, key?: string): Schema<any>;
     /** validate-only：不填默认值、不 throw */
-    safeParse(value?: unknown): SchemaSafeParseResult<T>;
+    safeParse(value?: unknown): SchemaSafeParseResult<S | undefined>;
     static resolve<T extends string>(type: T): Schema.Formatter;
     static extend<T extends string>(type: T, formatter: Schema.Formatter): void;
 }
@@ -71,6 +82,22 @@ export interface Schema<S = any> {
     (value?: S, key?: string): S;
 }
 export declare namespace Schema {
+    interface Present {
+        readonly [configPresent]: true;
+    }
+    interface Required {
+        readonly [inputRequired]: true;
+    }
+    type Input<T> = T extends Schema<infer I, any> ? I : never;
+    type Output<T> = T extends Schema<any, infer O> ? O : never;
+    type InputRecord<X extends Record<string, Schema>> = {
+        [K in keyof X as X[K] extends Required ? K : never]-?: Input<X[K]>;
+    } & {
+        [K in keyof X as X[K] extends Required ? never : K]?: Input<X[K]>;
+    };
+    type InputUnion<X extends readonly any[]> = X extends readonly [infer L, ...infer R] ? Input<L> | InputUnion<R> : never;
+    type InputIntersect<X extends readonly any[]> = X extends readonly [infer L, ...infer R] ? Input<L> & InputIntersect<R> : unknown;
+    type InputTuple<X extends readonly any[]> = X extends readonly [infer L, ...infer R] ? [Input<L>, ...InputTuple<R>] : [];
     const formatters: Map<string, Formatter>;
     type Formatter<S = any, T = S> = (this: Schema, key: string, value: S) => T;
     type JSON<S = any, T = S> = Meta<S, T> & {
@@ -91,15 +118,19 @@ export declare namespace Schema {
         min?: number;
         max?: number;
         step?: number;
+        secret?: boolean;
+        effect?: ConfigFieldMetadata['effect'];
     }
     interface Options {
         object?: Record<string, Schema>;
         inner?: Schema;
         list?: readonly Schema[];
     }
-    type Types<T> = T extends Schema<infer S> ? S : never;
+    type Types<T> = Output<T>;
     type RecordTypes<T> = T extends Record<string, Schema> ? {
-        [K in keyof T]?: Types<T[K]>;
+        [K in keyof T as T[K] extends Present ? K : never]-?: Output<T[K]>;
+    } & {
+        [K in keyof T as T[K] extends Present ? never : K]?: Output<T[K]>;
     } : unknown;
     type Union<T extends readonly any[]> = T extends readonly [infer L, ...infer R] ? Types<L> | Union<R> : never;
     type Intersect<T extends readonly any[]> = T extends readonly [infer L, ...infer R] ? Types<L> & Intersect<R> : unknown;

package/lib/schema.js

@@ -1,5 +1,6 @@
 import { isEmpty } from './utils.js';
 import { safeParseSchema } from './validate.js';
+import { toJsonSchema } from './json-schema.js';
 export { SchemaValidationError } from './validate.js';
 export { safeParseSchema };
 export class Schema {
@@ -79,6 +80,24 @@ export class Schema {
         this.meta.default = defaultValue;
         return this;
     }
+    /** Secret values remain environment references in application configuration. */
+    secret() {
+        if (this.meta.type !== 'string')
+            throw new TypeError('secret only supports string fields');
+        this.meta.secret = true;
+        return this;
+    }
+    /** Declare the effect shown in configuration forms. */
+    effect(effect) {
+        if (effect !== 'reload')
+            throw new TypeError('Plugin configuration fields support only reload');
+        this.meta.effect = effect;
+        return this;
+    }
+    /** Export the standard JSON Schema consumed by Runtime and Console. */
+    toJsonSchema() {
+        return toJsonSchema(this);
+    }
     /** 设置选项列表 */
     option(list) {
         this.meta.options = Schema.formatOptionList(list);
@@ -255,7 +274,7 @@ export class Schema {
     Schema.checkDefault = checkDefault;
     function formatOptionList(list) {
         return list.map(item => {
-            if (typeof item === 'string') {
+            if (typeof item === 'string' || typeof item === 'number' || typeof item === 'boolean') {
                 return {
                     label: `${item}`,
                     value: item,

package/lib/validate.d.ts

@@ -15,4 +15,4 @@ export type SchemaSafeParseResult<T> = {
     success: false;
     error: SchemaValidationError;
 };
-export declare function safeParseSchema<T>(schema: Schema<T>, value: unknown): SchemaSafeParseResult<T>;
+export declare function safeParseSchema<S, T>(schema: Schema<S, T>, value: unknown): SchemaSafeParseResult<S | undefined>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/schema",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Configuration validation and schema system for Zhin.js",
   "type": "module",
   "main": "./lib/index.js",