@yuhere/js-jsonrpc2 2.1.13 → 2.1.15

package/dist/schema/json/primitives.d.ts

@@ -9,20 +9,37 @@ export type JSONValue = JSONPrimitive | JSONValue[] | {
     [key: string]: JSONValue;
 };
 export type SchemaKind = string;
-export interface SchemaDescription {
+export interface BaseSchemaDescription {
     kind: SchemaKind;
     description?: string;
-    /**
-     * 该值是否允许为 null。
-     *
-     * 唯一真相来源：由 `NullableSchema` 及其子类通过 `.nullable(bool)` 设置，
-     * `UnknownSchema` / `NullSchema` 不使用该字段（它们本身就接受 null）。
-     * `kind` 永远表示值的真实形状，不会被 nullability 污染。
-     */
     nullable?: boolean;
+    validate?: boolean;
     constraints?: Record<string, unknown>;
-    children?: Record<string, unknown>;
 }
+export interface LeafSchemaDescription extends BaseSchemaDescription {
+    kind: "string" | "number" | "boolean" | "literal" | "enum" | "unknown" | "null";
+}
+export interface ObjectSchemaDescription extends BaseSchemaDescription {
+    kind: "object";
+    properties: Record<string, SchemaDescription>;
+}
+export interface ArraySchemaDescription extends BaseSchemaDescription {
+    kind: "array";
+    element: SchemaDescription;
+}
+export interface RecordSchemaDescription extends BaseSchemaDescription {
+    kind: "record";
+    value: SchemaDescription;
+}
+export interface UnionSchemaDescription extends BaseSchemaDescription {
+    kind: "union";
+    options: SchemaDescription[];
+}
+export interface TupleSchemaDescription extends BaseSchemaDescription {
+    kind: "tuple";
+    elements: SchemaDescription[];
+}
+export type SchemaDescription = LeafSchemaDescription | ObjectSchemaDescription | ArraySchemaDescription | RecordSchemaDescription | UnionSchemaDescription | TupleSchemaDescription;
 export declare class SchemaValidationError extends Error {
     readonly path: string[];
     constructor(message: string, path?: string[]);
@@ -33,17 +50,19 @@ export declare class SchemaValidationError extends Error {
  * 只负责 description 与描述输出；nullability 由 `NullableSchema` 提供。
  * `UnknownSchema` / `NullSchema` 直接继承本类——它们天然接受 null，
  * 不需要 `.nullable()`。
+ *
+ * 运行时校验可通过 `.validate(false)` 关闭：关闭后 `parse` / `safeParse`
+ * 直接返回输入，不再调用 `_parse`（仍可用于签名描述）。
  */
 export declare abstract class Schema<T> {
     abstract readonly kind: SchemaKind;
-    private description?;
-    constructor(description?: string);
+    private description;
+    private _validateEnabled;
     describe(description: string): this;
-    /**
-     * 创建保留原型和现有字段的新实例，供不可变链式方法使用。
-     */
+    validate(value?: boolean): this;
+    isValidateEnabled(): boolean;
     protected cloneWith(updates: Record<string, unknown>): this;
-    getDescription(): string | undefined;
+    getDescription(): string;
     parse(input: unknown): T;
     safeParse(input: unknown): {
         success: true;
@@ -84,7 +103,7 @@ export declare class StringSchema<K extends string = "string"> extends NullableS
     min(value: number): this;
     max(value: number): this;
     protected _parseValue(input: unknown, path: string[]): string;
-    protected _describe(): SchemaDescription;
+    protected _describe(): LeafSchemaDescription;
     protected validateBound(value: number): void;
 }
 export declare class NumberSchema extends NullableSchema<number> {
@@ -95,28 +114,22 @@ export declare class NumberSchema extends NullableSchema<number> {
     min(value: number): this;
     max(value: number): this;
     protected _parseValue(input: unknown, path: string[]): number;
-    protected _describe(): SchemaDescription;
+    protected _describe(): LeafSchemaDescription;
     protected validateBound(value: number): void;
 }
 export declare class BooleanSchema extends NullableSchema<boolean> {
     readonly kind: "boolean";
     constructor();
     protected _parseValue(input: unknown, path: string[]): boolean;
-    protected _describe(): SchemaDescription;
+    protected _describe(): LeafSchemaDescription;
 }
-/**
- * 字面量只支持 string / number / boolean。
- *
- * null 由 `s.null()` 表达；需要「该字面量或 null」时，对字面量调用
- * `.nullable()`。`literal(null)` 会抛 TypeError。
- */
 export type LiteralValue = string | number | boolean;
 export declare class LiteralSchema<const T extends LiteralValue> extends NullableSchema<T> {
     private readonly expected;
     readonly kind: "literal";
     constructor(expected: T);
     protected _parseValue(input: unknown, path: string[]): T;
-    protected _describe(): SchemaDescription;
+    protected _describe(): LeafSchemaDescription;
 }
 export declare class ArraySchema<T> extends NullableSchema<T[]> {
     private readonly itemSchema;
@@ -127,28 +140,25 @@ export declare class ArraySchema<T> extends NullableSchema<T[]> {
     min(value: number): this;
     max(value: number): this;
     protected _parseValue(input: unknown, path: string[]): T[];
-    protected _describe(): SchemaDescription;
+    protected _describe(): ArraySchemaDescription;
     protected validateBound(value: number): void;
 }
 export type ObjectShape = Record<string, Schema<unknown>>;
 type SchemaValue<S> = S extends Schema<infer T> ? T : never;
-type ShapeOutput<S extends ObjectShape> = {
-    [K in keyof S]: SchemaValue<S[K]>;
-};
-type OptionalShapeOutput<S extends ObjectShape> = {
+export type ObjectOutput<S extends ObjectShape> = {
     [K in keyof S]?: SchemaValue<S[K]>;
 };
-export declare class ObjectSchema<S extends ObjectShape, Strict extends boolean = false> extends NullableSchema<Strict extends true ? ShapeOutput<S> : OptionalShapeOutput<S>> {
+export declare class ObjectSchema<S extends ObjectShape> extends NullableSchema<ObjectOutput<S>> {
     private readonly shape;
     readonly kind: "object";
-    private isStrict;
-    constructor(shape: S, strict?: Strict, description?: string);
-    /**
-     * strict() 要求所有声明属性存在，并拒绝未声明属性。
-     */
-    strict(): ObjectSchema<S, true>;
-    protected _parseValue(input: unknown, path: string[]): Strict extends true ? ShapeOutput<S> : OptionalShapeOutput<S>;
-    protected _describe(): SchemaDescription;
+    private optionalProps;
+    private allowUnknownProps;
+    constructor(shape: S);
+    optionalProperties(keys: string[]): this;
+    allowUnknownProperties(value?: boolean): this;
+    strict(value?: boolean): this;
+    protected _parseValue(input: unknown, path: string[]): ObjectOutput<S>;
+    protected _describe(): ObjectSchemaDescription;
 }
 export declare class RecordSchema<T> extends NullableSchema<Record<string, T>> {
     private readonly valueSchema;
@@ -159,68 +169,42 @@ export declare class RecordSchema<T> extends NullableSchema<Record<string, T>> {
     min(value: number): this;
     max(value: number): this;
     protected _parseValue(input: unknown, path: string[]): Record<string, T>;
-    protected _describe(): SchemaDescription;
+    protected _describe(): RecordSchemaDescription;
     protected validateBound(value: number): void;
 }
-/**
- * 联合。
- *
- * 传入的 member schemas 会被 clone 并 `nullable(false)`——因为「某个
- * 分支允许 null」这件事在 union 层面没有意义：null 是否允许应通过
- * `union(...).nullable()` 统一表达。
- */
 export declare class UnionSchema<const S extends readonly [Schema<unknown>, ...Schema<unknown>[]]> extends NullableSchema<SchemaValue<S[number]>> {
     readonly kind: "union";
     private readonly options;
     constructor(schemas: S);
     protected _parseValue(input: unknown, path: string[]): SchemaValue<S[number]>;
-    protected _describe(): SchemaDescription;
+    protected _describe(): UnionSchemaDescription;
 }
 export declare class TupleSchema<const S extends readonly [Schema<unknown>, ...Schema<unknown>[]]> extends NullableSchema<SchemaValue<S[number]>[]> {
     private readonly schemas;
     readonly kind: "tuple";
     constructor(schemas: S);
     protected _parseValue(input: unknown, path: string[]): SchemaValue<S[number]>[];
-    protected _describe(): SchemaDescription;
+    protected _describe(): TupleSchemaDescription;
 }
-/**
- * 字符串枚举。
- *
- * 继承 `NullableSchema`，因此可以 `s.enum([...]).nullable()`；
- * 它不包含嵌套 schema，所以不需要像 union 那样处理成员 nullability。
- */
 export declare class EnumSchema<const T extends readonly [string, ...string[]]> extends NullableSchema<T[number]> {
     private readonly values;
     readonly kind: "enum";
     private readonly allowedValues;
     constructor(values: T);
     protected _parseValue(input: unknown, path: string[]): T[number];
-    protected _describe(): SchemaDescription;
+    protected _describe(): LeafSchemaDescription;
 }
-/**
- * 校验任意 JSON 值。
- *
- * 不允许 undefined、非有限数字、循环引用等非 JSON 数据。
- * null 本身就在接受范围内，因此不继承 `NullableSchema`，也不提供
- * `.nullable()`——那是冗余的。
- */
 export declare class UnknownSchema extends Schema<JSONValue> {
     readonly kind: "unknown";
     constructor();
     protected _parse(input: unknown, path: string[]): JSONValue;
-    protected _describe(): SchemaDescription;
+    protected _describe(): LeafSchemaDescription;
 }
-/**
- * 精确的 null 值。
- *
- * 与 `UnknownSchema` 一样天然表达 null，不需要 `.nullable()`。
- * 想表达「某类型或 null」用 `.nullable()`；想表达「就是 null」用 `s.null()`。
- */
 export declare class NullSchema extends Schema<null> {
     readonly kind: "null";
     constructor();
     protected _parse(input: unknown, path: string[]): null;
-    protected _describe(): SchemaDescription;
+    protected _describe(): LeafSchemaDescription;
 }
 export type Infer<T extends Schema<unknown>> = T extends Schema<infer U> ? U : never;
 export declare const primitives: {
@@ -229,7 +213,7 @@ export declare const primitives: {
     boolean: () => BooleanSchema;
     literal: <const T extends LiteralValue>(value: T) => LiteralSchema<T>;
     array: <T>(item: Schema<T>) => ArraySchema<T>;
-    object: <S extends ObjectShape>(shape: S) => ObjectSchema<S, false>;
+    object: <S extends ObjectShape>(shape: S) => ObjectSchema<S>;
     record: <T>(value: Schema<T>) => RecordSchema<T>;
     union: <const S extends readonly [Schema<unknown>, ...Schema<unknown>[]]>(schemas: S) => UnionSchema<S>;
     tuple: <const S extends readonly [Schema<unknown>, ...Schema<unknown>[]]>(schemas: S) => TupleSchema<S>;

package/dist/schema/json/primitives.js

@@ -12,18 +12,22 @@ export class SchemaValidationError extends Error {
  * 只负责 description 与描述输出；nullability 由 `NullableSchema` 提供。
  * `UnknownSchema` / `NullSchema` 直接继承本类——它们天然接受 null，
  * 不需要 `.nullable()`。
+ *
+ * 运行时校验可通过 `.validate(false)` 关闭：关闭后 `parse` / `safeParse`
+ * 直接返回输入，不再调用 `_parse`（仍可用于签名描述）。
  */
 export class Schema {
-    description;
-    constructor(description) {
-        this.description = description;
-    }
+    description = "";
+    _validateEnabled = true;
     describe(description) {
         return this.cloneWith({ description });
     }
-    /**
-     * 创建保留原型和现有字段的新实例，供不可变链式方法使用。
-     */
+    validate(value = true) {
+        return this.cloneWith({ _validateEnabled: value });
+    }
+    isValidateEnabled() {
+        return this._validateEnabled;
+    }
     cloneWith(updates) {
         const clone = Object.assign(Object.create(Object.getPrototypeOf(this)), this);
         return Object.assign(clone, updates);
@@ -32,6 +36,9 @@ export class Schema {
         return this.description;
     }
     parse(input) {
+        if (!this._validateEnabled) {
+            return input;
+        }
         return this._parse(input, []);
     }
     safeParse(input) {
@@ -51,6 +58,9 @@ export class Schema {
         if (description !== undefined) {
             result.description = description;
         }
+        if (!this._validateEnabled) {
+            result.validate = false;
+        }
         return result;
     }
     fail(message, path) {
@@ -118,12 +128,13 @@ export class StringSchema extends NullableSchema {
         return input;
     }
     _describe() {
+        const constraints = buildConstraints({
+            min: this.minimum,
+            max: this.maximum,
+        });
         return {
             kind: this.kind,
-            constraints: {
-                ...(this.minimum !== undefined ? { min: this.minimum } : {}),
-                ...(this.maximum !== undefined ? { max: this.maximum } : {}),
-            },
+            ...(constraints ? { constraints } : {}),
         };
     }
     validateBound(value) {
@@ -160,12 +171,13 @@ export class NumberSchema extends NullableSchema {
         return input;
     }
     _describe() {
+        const constraints = buildConstraints({
+            min: this.minimum,
+            max: this.maximum,
+        });
         return {
             kind: this.kind,
-            constraints: {
-                ...(this.minimum !== undefined ? { min: this.minimum } : {}),
-                ...(this.maximum !== undefined ? { max: this.maximum } : {}),
-            },
+            ...(constraints ? { constraints } : {}),
         };
     }
     validateBound(value) {
@@ -259,13 +271,14 @@ export class ArraySchema extends NullableSchema {
         });
     }
     _describe() {
+        const constraints = buildConstraints({
+            min: this.minimum,
+            max: this.maximum,
+        });
         return {
             kind: this.kind,
-            constraints: {
-                ...(this.minimum !== undefined ? { min: this.minimum } : {}),
-                ...(this.maximum !== undefined ? { max: this.maximum } : {}),
-            },
-            children: { items: this.itemSchema.toJSON() },
+            ...(constraints ? { constraints } : {}),
+            element: this.itemSchema.toJSON(),
         };
     }
     validateBound(value) {
@@ -277,17 +290,29 @@ export class ArraySchema extends NullableSchema {
 export class ObjectSchema extends NullableSchema {
     shape;
     kind = "object";
-    isStrict;
-    constructor(shape, strict = false, description) {
-        super(description);
+    optionalProps;
+    allowUnknownProps = true;
+    constructor(shape) {
+        super();
         this.shape = shape;
-        this.isStrict = strict;
+        this.optionalProps = Object.keys(shape);
     }
-    /**
-     * strict() 要求所有声明属性存在，并拒绝未声明属性。
-     */
-    strict() {
-        return new ObjectSchema(this.shape, true, this.getDescription());
+    optionalProperties(keys) {
+        for (const key of keys) {
+            if (!Object.prototype.hasOwnProperty.call(this.shape, key)) {
+                throw new TypeError(`optionalProperties: unknown property "${key}"`);
+            }
+        }
+        return this.cloneWith({ optionalProps: [...new Set(keys)] });
+    }
+    allowUnknownProperties(value = true) {
+        return this.cloneWith({ allowUnknownProps: value });
+    }
+    strict(value = true) {
+        if (value) {
+            return this.optionalProperties([]).allowUnknownProperties(false);
+        }
+        return this.optionalProperties(Object.keys(this.shape)).allowUnknownProperties(true);
     }
     _parseValue(input, path) {
         if (input === null ||
@@ -297,16 +322,17 @@ export class ObjectSchema extends NullableSchema {
         }
         const source = input;
         const output = {};
-        if (this.isStrict) {
+        const optional = new Set(this.optionalProps);
+        if (!this.allowUnknownProps) {
             for (const key of Object.keys(source)) {
-                if (!(key in this.shape)) {
+                if (!Object.prototype.hasOwnProperty.call(this.shape, key)) {
                     this.fail(`Unknown property "${key}"`, [...path, key]);
                 }
             }
         }
         for (const [key, schema] of Object.entries(this.shape)) {
             if (!Object.prototype.hasOwnProperty.call(source, key)) {
-                if (this.isStrict) {
+                if (!optional.has(key)) {
                     this.fail(`Missing required property "${key}"`, [...path, key]);
                 }
                 continue;
@@ -324,10 +350,9 @@ export class ObjectSchema extends NullableSchema {
                 throw error;
             }
         }
-        // 非 strict 模式允许额外属性，并保留这些属性。
-        if (!this.isStrict) {
+        if (this.allowUnknownProps) {
             for (const [key, value] of Object.entries(source)) {
-                if (!(key in this.shape)) {
+                if (!Object.prototype.hasOwnProperty.call(this.shape, key)) {
                     assertJSONValue(value, [...path, key]);
                     output[key] = value;
                 }
@@ -338,13 +363,14 @@ export class ObjectSchema extends NullableSchema {
     _describe() {
         return {
             kind: this.kind,
-            constraints: { strict: this.isStrict },
-            children: {
-                properties: Object.fromEntries(Object.entries(this.shape).map(([key, schema]) => [
-                    key,
-                    schema.toJSON(),
-                ])),
+            constraints: {
+                optionalProps: [...this.optionalProps],
+                allowUnknownProps: this.allowUnknownProps,
             },
+            properties: Object.fromEntries(Object.entries(this.shape).map(([key, schema]) => [
+                key,
+                schema.toJSON(),
+            ])),
         };
     }
 }
@@ -396,13 +422,14 @@ export class RecordSchema extends NullableSchema {
         return output;
     }
     _describe() {
+        const constraints = buildConstraints({
+            min: this.minimum,
+            max: this.maximum,
+        });
         return {
             kind: this.kind,
-            constraints: {
-                ...(this.minimum !== undefined ? { min: this.minimum } : {}),
-                ...(this.maximum !== undefined ? { max: this.maximum } : {}),
-            },
-            children: { values: this.valueSchema.toJSON() },
+            ...(constraints ? { constraints } : {}),
+            value: this.valueSchema.toJSON(),
         };
     }
     validateBound(value) {
@@ -411,13 +438,6 @@ export class RecordSchema extends NullableSchema {
         }
     }
 }
-/**
- * 联合。
- *
- * 传入的 member schemas 会被 clone 并 `nullable(false)`——因为「某个
- * 分支允许 null」这件事在 union 层面没有意义：null 是否允许应通过
- * `union(...).nullable()` 统一表达。
- */
 export class UnionSchema extends NullableSchema {
     kind = "union";
     options;
@@ -452,9 +472,7 @@ export class UnionSchema extends NullableSchema {
     _describe() {
         return {
             kind: this.kind,
-            children: {
-                options: this.options.map((schema) => schema.toJSON()),
-            },
+            options: this.options.map((schema) => schema.toJSON()),
         };
     }
 }
@@ -483,7 +501,10 @@ export class TupleSchema extends NullableSchema {
             }
             catch (error) {
                 if (error instanceof SchemaValidationError) {
-                    return this.fail(error.message, [...path, "" + i]);
+                    throw new SchemaValidationError(error.message, [
+                        String(i),
+                        ...error.path,
+                    ]);
                 }
                 throw error;
             }
@@ -493,18 +514,10 @@ export class TupleSchema extends NullableSchema {
     _describe() {
         return {
             kind: this.kind,
-            children: {
-                items: this.schemas.map((schema) => schema.toJSON()),
-            },
+            elements: this.schemas.map((schema) => schema.toJSON()),
         };
     }
 }
-/**
- * 字符串枚举。
- *
- * 继承 `NullableSchema`，因此可以 `s.enum([...]).nullable()`；
- * 它不包含嵌套 schema，所以不需要像 union 那样处理成员 nullability。
- */
 export class EnumSchema extends NullableSchema {
     values;
     kind = "enum";
@@ -527,13 +540,6 @@ export class EnumSchema extends NullableSchema {
         };
     }
 }
-/**
- * 校验任意 JSON 值。
- *
- * 不允许 undefined、非有限数字、循环引用等非 JSON 数据。
- * null 本身就在接受范围内，因此不继承 `NullableSchema`，也不提供
- * `.nullable()`——那是冗余的。
- */
 export class UnknownSchema extends Schema {
     kind = "unknown";
     constructor() {
@@ -547,12 +553,6 @@ export class UnknownSchema extends Schema {
         return { kind: this.kind };
     }
 }
-/**
- * 精确的 null 值。
- *
- * 与 `UnknownSchema` 一样天然表达 null，不需要 `.nullable()`。
- * 想表达「某类型或 null」用 `.nullable()`；想表达「就是 null」用 `s.null()`。
- */
 export class NullSchema extends Schema {
     kind = "null";
     constructor() {
@@ -568,6 +568,13 @@ export class NullSchema extends Schema {
         return { kind: this.kind };
     }
 }
+function buildConstraints(values) {
+    const entries = Object.entries(values).filter(([, value]) => value !== undefined);
+    if (entries.length === 0) {
+        return undefined;
+    }
+    return Object.fromEntries(entries);
+}
 function assertJSONValue(value, path, ancestors = new Set()) {
     if (value === null ||
         typeof value === "string" ||

package/dist/schema/z/protocol.d.ts

@@ -5,4 +5,4 @@ export declare const RPCRequestSchema: import("../json/index.js").ObjectSchema<{
     method: import("../json/index.js").StringSchema<"string">;
     params: import("../json/index.js").ArraySchema<import("../json/index.js").JSONValue>;
     id: import("../json/index.js").UnionSchema<readonly [import("../json/index.js").StringSchema<"string">, import("../json/index.js").NumberSchema]>;
-}, true>;
+}>;