@zhin.js/schema 1.1.4 → 1.1.6

package/README.md

@@ -207,8 +207,8 @@ plugins:
 | `.default(value)` | 设置默认值 |
 | `.option(label, value)` | 添加可选项 |
 | `.multiple()` | 允许多选 |
-| `.min(value)` | 设置最小值 |
-| `.max(value)` | 设置最大值 |
+| `.min(value)` | 设置最小值（数字下限 / 字符串最小长度 / 列表最少项）；写入导出的 JSON Schema，由 Runtime 配置校验执行，`schema(value)` 与 `safeParse` 只做结构校验 |
+| `.max(value)` | 设置最大值，规则同 `.min` |
 | `.step(value)` | 设置步长 |
 | `.component(name)` | 指定渲染组件 |
 | `.toJSON()` | 业务 Schema 的内部序列化 |

package/lib/json-schema.d.ts

@@ -12,6 +12,15 @@ export interface ConfigFieldMetadata {
     readonly component?: string;
     readonly options?: readonly Schema.Option[];
     readonly effect?: 'reload';
+    /** Property-level narrowing of the Plugin's feature levels (ADR 0050 §2). */
+    readonly levels?: readonly ('global' | 'adapter' | 'endpoint' | 'conversation')[];
+}
+/** Root `x-zhin-config` of a Plugin schema: layered levels (ADR 0050 / 0055). */
+export interface ConfigFeatureLevels {
+    readonly levels: readonly ('global' | 'adapter' | 'endpoint' | 'conversation')[];
+    readonly conversationFields?: readonly string[];
+    readonly selfServiceFields?: readonly string[];
+    readonly chatAdminFields?: readonly string[];
 }
 export type ConfigJsonSchema = Readonly<Record<string, unknown>>;
 /** Export serializable configuration declarations; non-JSON business types are explicit errors. */

package/lib/json-schema.js

@@ -100,6 +100,8 @@ export function toJsonSchema(schema) {
         ...(meta.component !== undefined ? { component: meta.component } : {}),
         ...(meta.options !== undefined ? { options: structuredClone(meta.options) } : {}),
         ...(meta.effect !== undefined ? { effect: meta.effect } : {}),
+        ...(meta.feature !== undefined ? structuredClone(meta.feature) : {}),
+        ...(meta.fieldLevels !== undefined ? { levels: [...meta.fieldLevels] } : {}),
     };
     if (Object.keys(annotations).length)
         result['x-zhin-config'] = annotations;

package/lib/schema.d.ts

@@ -1,5 +1,5 @@
 import { safeParseSchema, type SchemaSafeParseResult } from './validate.js';
-import { type ConfigFieldMetadata, type ConfigFieldI18n } from './json-schema.js';
+import { type ConfigFeatureLevels, type ConfigFieldMetadata, type ConfigFieldI18n } from './json-schema.js';
 export { SchemaValidationError, type SchemaSafeParseResult, type SchemaValidationIssue } from './validate.js';
 export { safeParseSchema };
 declare const configPresent: unique symbol;
@@ -31,13 +31,31 @@ export declare class Schema<S = any, T = S> {
     secret(): this;
     /** Declare the effect shown in configuration forms. */
     effect(effect: ConfigFieldMetadata['effect']): this;
+    /**
+     * Plugin root only: layered feature levels (ADR 0050 / 0055) and the fields editable at the
+     * conversation level, in chat by group admins, and in chat above the conversation level.
+     */
+    featureLevels(levels: ConfigFeatureLevels['levels'], fields?: Omit<ConfigFeatureLevels, 'levels'>): this;
+    /**
+     * Plugin property only: narrow the feature levels that may override this field (ADR 0050 §2),
+     * e.g. `.fieldLevels(['global'])` for secrets and process-wide resources. It can never widen
+     * the root `featureLevels` declaration; the Runtime rejects a wider list at startup.
+     */
+    fieldLevels(levels: ConfigFeatureLevels['levels']): this;
     /** Export the standard JSON Schema consumed by Runtime and Console. */
     toJsonSchema(): Readonly<Record<string, unknown>>;
     /** 设置选项列表 */
     option(list: (T | Schema.Option<T>)[]): this;
     /** 设置是否允许多选 */
     multiple(): this;
-    /** 设置最小值 */
+    /**
+     * 设置最小值。
+     * `min` / `max` / `step` are range constraints of the exported JSON Schema
+     * (minimum/minLength/minItems, maximum/…, multipleOf) and are enforced where that
+     * schema is compiled (Runtime config validation). The callable schema and
+     * `safeParse` are structural only; `toJsonSchema` relies on that when it matches
+     * union branches (see assertPublicDefault).
+     */
     min(value: number): this;
     /** 设置最大值 */
     max(value: number): this;
@@ -57,7 +75,9 @@ 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.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 object<X extends Record<string, Schema<any, any>>>(input: X, key?: string): Schema<Schema.InputRecord<X>, Schema.RecordTypes<X>> & {
+        readonly output?: Schema.RecordTypes<X>;
+    };
     /** 声明一个列表类型 */
     static list<X extends Schema>(inner: X, key?: string): Schema<Schema.Input<X>[], Schema.Output<X>[]>;
     /** 声明一个元组类型 */
@@ -123,6 +143,8 @@ export declare namespace Schema {
         step?: number;
         secret?: boolean;
         effect?: ConfigFieldMetadata['effect'];
+        feature?: ConfigFeatureLevels;
+        fieldLevels?: ConfigFeatureLevels['levels'];
     }
     interface Options {
         object?: Record<string, Schema>;
@@ -130,11 +152,11 @@ export declare namespace Schema {
         list?: readonly Schema[];
     }
     type Types<T> = Output<T>;
-    type RecordTypes<T> = T extends Record<string, Schema> ? {
+    type RecordTypes<T extends Record<string, any>> = {
         [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;
     type Tuple<T extends readonly any[]> = T extends readonly [infer L, ...infer R] ? [Types<L>, ...Tuple<R>] : [];

package/lib/schema.js

@@ -24,6 +24,9 @@ export class Schema {
             set(target, p, value, receiver) {
                 return Reflect.set(_this, p, value, receiver);
             },
+            has(target, p) {
+                return Reflect.has(_this, p) || Reflect.has(target, p);
+            },
         });
     }
     static fromJSON(json) {
@@ -99,6 +102,27 @@ export class Schema {
         this.meta.effect = effect;
         return this;
     }
+    /**
+     * Plugin root only: layered feature levels (ADR 0050 / 0055) and the fields editable at the
+     * conversation level, in chat by group admins, and in chat above the conversation level.
+     */
+    featureLevels(levels, fields = {}) {
+        if (this.meta.type !== 'object')
+            throw new TypeError('featureLevels only supports the plugin root object');
+        this.meta.feature = structuredClone({ levels, ...fields });
+        return this;
+    }
+    /**
+     * Plugin property only: narrow the feature levels that may override this field (ADR 0050 §2),
+     * e.g. `.fieldLevels(['global'])` for secrets and process-wide resources. It can never widen
+     * the root `featureLevels` declaration; the Runtime rejects a wider list at startup.
+     */
+    fieldLevels(levels) {
+        if (!levels.length || !levels.includes('global'))
+            throw new TypeError('fieldLevels must include global');
+        this.meta.fieldLevels = [...levels];
+        return this;
+    }
     /** Export the standard JSON Schema consumed by Runtime and Console. */
     toJsonSchema() {
         return toJsonSchema(this);
@@ -115,7 +139,14 @@ export class Schema {
         this.meta.multiple = true;
         return this;
     }
-    /** 设置最小值 */
+    /**
+     * 设置最小值。
+     * `min` / `max` / `step` are range constraints of the exported JSON Schema
+     * (minimum/minLength/minItems, maximum/…, multipleOf) and are enforced where that
+     * schema is compiled (Runtime config validation). The callable schema and
+     * `safeParse` are structural only; `toJsonSchema` relies on that when it matches
+     * union branches (see assertPublicDefault).
+     */
     min(value) {
         this.meta.min = value;
         return this;
@@ -221,7 +252,7 @@ export class Schema {
                         throw new TypeError(`${key} is not a string`);
                     break;
                 case 'number':
-                    if (!['number', 'undefined'].includes(typeof value))
+                    if (!['number', 'undefined'].includes(typeof value) || (typeof value === 'number' && Number.isNaN(value)))
                         throw new TypeError(`${key} is not a number`);
                     break;
                 case 'boolean':
@@ -239,11 +270,11 @@ export class Schema {
                         throw new TypeError(`${key} is not a valid Date`);
                     break;
                 case 'dict':
-                    if (!['object', 'undefined', 'null'].includes(typeof value))
+                    if (!['object', 'undefined'].includes(typeof value) || value === null || Array.isArray(value))
                         throw new TypeError(`${key} is not a object`);
                     break;
                 case 'object':
-                    if (!['object', 'undefined', 'null'].includes(typeof value))
+                    if (!['object', 'undefined'].includes(typeof value) || value === null || Array.isArray(value))
                         throw new TypeError(`${key} is not a object`);
                     break;
                 case 'list':
@@ -310,19 +341,27 @@ Schema.extend('dict', function (key, value) {
 Schema.extend('object', function (key, value) {
     const getDefault = (schema) => {
         const result = Object.create(null);
-        for (const key in schema.options.object) {
-            const propSchema = schema.options.object[key];
-            result[key] = propSchema.default !== undefined ? propSchema.default : undefined;
+        for (const propKey in schema.options.object) {
+            const propSchema = schema.options.object[propKey];
+            result[propKey] = propSchema.meta.default !== undefined ? propSchema.meta.default : undefined;
         }
         return result;
     };
     value = Schema.checkDefault(this, key, value, getDefault(this));
+    if (value === undefined)
+        return value;
     const result = Object.create(null);
-    for (const [k, val] of Object.entries(value)) {
-        const propSchema = this.options.object[k];
+    const shape = this.options.object || {};
+    const allKeys = new Set([...Object.keys(shape), ...Object.keys(value)]);
+    for (const k of allKeys) {
+        const val = value[k];
+        const propSchema = shape[k];
         if (propSchema) {
             // propSchema是一个可调用的Schema实例
-            result[k] = propSchema(val, `${key}.${k}`);
+            const evaluated = propSchema(val, `${key}.${k}`);
+            if (evaluated !== undefined || k in value) {
+                result[k] = evaluated;
+            }
         }
         else {
             result[k] = val;
@@ -355,8 +394,12 @@ Schema.extend('const', function (key, value) {
     return value;
 });
 Schema.extend('tuple', function (key, value) {
-    value = Schema.checkDefault(this, key, value, []);
-    if (value.length > 0 && value.length !== this.options.list.length)
+    // No `[]` fallback: an empty array is not a valid tuple (JSON Schema exports
+    // minItems = maxItems = length, and safeParse rejects it), so absent stays absent.
+    value = Schema.checkDefault(this, key, value);
+    if (value === undefined)
+        return value;
+    if (value.length !== this.options.list.length)
         throw new TypeError(`${key} tuple length mismatch`);
     return value.map((item, index) => this.options.list[index](item, `${key}[${index}]`));
 });

package/lib/validate.js

@@ -29,7 +29,7 @@ function validateOnly(schema, path, value) {
             }
             return value;
         case 'number':
-            if (value !== undefined && typeof value !== 'number') {
+            if (value !== undefined && (typeof value !== 'number' || Number.isNaN(value))) {
                 throw issue(path, `${path} is not a number`);
             }
             return value;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/schema",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "description": "Configuration validation and schema system for Zhin.js",
   "type": "module",
   "main": "./lib/index.js",
@@ -14,6 +14,10 @@
   "files": [
     "lib"
   ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "license": "MIT",
   "devDependencies": {
     "@types/node": "^26.1.2",
     "typescript": "^6.0.3"