@yuhere/js-jsonrpc2 2.1.13 → 2.1.15

package/README.md

@@ -72,7 +72,7 @@ The descriptor has three fields:
 | `grantTo` | `string[]` | Optional list of permissions required to call the method. |
 | `signature` | `[returnSchema, ...parameterSchema[]]` | Return type first, then parameters. |
 
-`signature[0]` is the return schema (`s.Schema` or `s.void()`).
+`signature[0]` is the return schema (`s.Schema`, `s.void()`, or `s.stream(inner)`).
 Every later slot is either a `s.Schema` (client-supplied) or
 `s.injectable(key)` (server-injected). Injectable slots may appear at any
 position except index `0`.
@@ -97,8 +97,12 @@ repository.register(
 
 ## Schemas
 
-Schemas are built with the `s` factory. They validate at runtime and derive
-TypeScript types.
+Schemas serve two roles:
+
+1. **Description** — document the RPC signature (`toJSON` / `system.methodSignature` / WebUI).
+2. **Validation** — check client parameters at invoke time (`parse` / `safeParse`, used by `convertParams`).
+
+They are built with the `s` factory. They validate at runtime (unless turned off) and derive TypeScript types.
 
 ```ts
 s.string()                 // string
@@ -108,29 +112,134 @@ s.boolean()                // boolean
 s.literal('2.0')           // exact literal (string | number | boolean only)
 s.null()                   // exactly null
 s.array(s.string())        // string[]
-s.object({ id: s.number() })          // open object
-s.object({ id: s.number() }).strict() // all props required, no extras
+s.object({ id: s.number() })          // open object (default: all props optional, extra props kept)
+s.object({ id: s.number() }).strict() // all declared props required, no extras
 s.record(s.number())       // Record<string, number>
 s.union([s.string(), s.number()])
 s.tuple([s.string(), s.number()])
 s.enum(['pending', 'success', 'failed'])
 s.unknown()                // any JSON value (already includes null)
 s.void()                   // RPC-only: no return value
+s.stream(s.string())       // RPC-only: streaming return (AsyncGenerator)
 s.injectable('request')    // RPC-only: server-injected parameter
 ```
 
-Chainable modifiers: `.min()`, `.max()`, `.nullable()`, `.strict()`,
-`.describe(text)`. Validation: `.parse(input)` (throws
-`SchemaValidationError`) and `.safeParse(input)` (returns a result object).
+### Chainable modifiers
+
+| Modifier | Applies to | Meaning |
+| --- | --- | --- |
+| `.min(n)` / `.max(n)` | string (length), number (bounds), array / record (size) | Inclusive bounds. |
+| `.nullable()` / `.nullable(true)` | most schemas | Allow `null`. Immutable; returns a new schema. |
+| `.nullable(false)` | same | Clear a previous nullable flag. |
+| `.describe(text)` | all schemas | Human-readable description (shown in WebUI / docs). |
+| `.validate(false)` / `.validate(true)` | all schemas | Toggle runtime validation. Default is **on**. When off, `parse` / `safeParse` accept any value and return it unchanged; the schema still describes the type for signatures and the WebUI. |
+| `.optionalProperties(keys)` | object | Whitelist of declared keys that may be missing. |
+| `.allowUnknownProperties(bool)` | object | Whether undeclared keys are kept (`true`) or rejected (`false`). |
+| `.strict()` / `.strict(true)` | object | Shortcut: no missing declared keys + reject extras. |
+| `.strict(false)` | object | Restore the default permissive object config. |
+
+Validation: `.parse(input)` (throws `SchemaValidationError` when validation is on)
+and `.safeParse(input)` (returns a result object).
 Introspection: `.toJSON()` returns a `SchemaDescription`.
 
-Nullability notes:
+### Disabling validation
+
+Schemas always participate in **signature description**. Runtime **parameter
+checks** can be turned off per schema when the server trusts the caller or the
+shape is only documentary:
+
+```ts
+// Still appears as string in system.methodSignature / WebUI,
+// but convertParams will not reject non-strings.
+s.string().validate(false)
+
+// Nested: only the inner schema skips checks
+s.object({
+  id: s.number(),
+  payload: s.unknown().validate(false),
+})
+```
+
+- Default is `validate: true` (omitted from `toJSON()` to keep descriptions small).
+- `.validate(false)` writes `validate: false` into the description.
+- `.validate(true)` restores the default; the flag is not emitted.
+- Calls are immutable (same pattern as `.nullable()`).
+
+Return-type slots are not run through `convertParams`; turning validation off on
+a return schema only affects direct `.parse` / `.safeParse` use and the
+description flag.
+
+### Object defaults and strictness
+
+By default an object schema is **permissive**:
+
+- every declared property may be omitted;
+- undeclared properties are allowed and preserved (if they are valid JSON).
+
+```ts
+const open = s.object({ name: s.string(), age: s.number() });
+open.parse({});                         // {}
+open.parse({ name: 'Ada', extra: 1 });  // { name: 'Ada', extra: 1 }
+
+const closed = open.strict();
+closed.parse({ name: 'Ada', age: 30 }); // ok
+// missing age → error; extra keys → error
+```
+
+Finer control without the all-or-nothing `strict()`:
+
+```ts
+// only `age` may be missing; still allow unknown keys
+s.object({ name: s.string(), age: s.number() }).optionalProperties(['age']);
+
+// all declared keys may be missing, but reject extras
+s.object({ name: s.string() }).allowUnknownProperties(false);
+```
+
+`optionalProperties` rejects key names that are not in the shape (throws
+`TypeError`).
+
+### Nullability notes
 
 - `.nullable()` / `.nullable(true)` allow `null`; `.nullable(false)` clears it. All calls are immutable.
 - `s.unknown()` and `s.null()` do not expose `.nullable()`; they already accept / are `null`.
 - `s.literal(v)` accepts `string | number | boolean`. Use `s.null()` for exact null, or `.nullable()` for "literal or null".
 - `s.union([...])` strips member-level nullability; only the union's own `.nullable()` decides whether `null` is accepted.
 
+### `toJSON()` / `SchemaDescription`
+
+Descriptions are a discriminated union on `kind`. There is **no** generic
+`children` bag for ordinary schemas:
+
+| kind | Child field(s) |
+| --- | --- |
+| `array` | `element` (single schema) |
+| `record` | `value` (single schema) |
+| `object` | `properties` (map) |
+| `union` | `options` (array) |
+| `tuple` | `elements` (array) |
+
+Object constraints are reported as:
+
+```ts
+constraints: {
+  optionalProps: string[];      // keys allowed to be missing
+  allowUnknownProps: boolean;   // whether extra keys are kept
+}
+```
+
+Empty constraint objects are omitted (no `constraints: {}`).
+
+When validation is disabled, the description includes `validate: false`.
+The default enabled state is not serialized.
+
+Stream returns from `system.methodSignature` / `signatureOf` currently use a
+small exception for the marker shape:
+
+```ts
+{ kind: 'stream', inner: <SchemaDescription> }
+```
+
 ## Transports
 
 ### Express

package/SKILL.md

@@ -30,8 +30,26 @@ Hard constraints (by design, do not work around):
    `s.literal(v)` (`v` is `string | number | boolean` only), `s.null()`,
    `s.array(item)`, `s.object(shape)`, `s.record(v)`, `s.union([...])`,
    `s.tuple([...])`, `s.enum([...])`, `s.unknown()`.
-7. Chain modifiers before registering: `.min()`, `.max()`, `.nullable(bool)`,
-   `.strict()`, `.describe(text)`.
+7. Chain modifiers before registering:
+   - Bounds / docs: `.min()`, `.max()`, `.describe(text)`.
+   - Nullability: `.nullable()` / `.nullable(true)` / `.nullable(false)` (immutable).
+   - Validation gate: `.validate(true|false)` (immutable; default **on**).
+     - Schemas serve two roles: **describe** the RPC signature and **validate**
+       client params at runtime.
+     - `.validate(false)` keeps the schema in `signature` / `system.methodSignature`
+       / WebUI / docs, but `parse` / `safeParse` become no-ops (return the input
+       unchanged). `convertParams` therefore will not reject bad values for that
+       slot.
+     - Prefer this only when a param is intentionally untrusted-schema or
+       validated elsewhere; do not use it as a substitute for `s.unknown()`.
+   - Object shape control:
+     - Default object is **permissive**: every declared key may be missing;
+       undeclared keys are kept if they are valid JSON.
+     - `.optionalProperties(keys)` — whitelist of declared keys that may be
+       missing (unknown names throw `TypeError`).
+     - `.allowUnknownProperties(bool)` — keep (`true`) or reject (`false`) extras.
+     - `.strict()` / `.strict(true)` — no missing declared keys + reject extras.
+     - `.strict(false)` — restore the default permissive config.
 8. Nullability rules:
    - `.nullable()` / `.nullable(true)` allow `null`; `.nullable(false)` clears it. Calls are immutable.
    - `s.unknown()` and `s.null()` already handle `null`; they do not expose `.nullable()`.
@@ -46,6 +64,57 @@ repository.register(
   { namespace: 'add', document: 'a + b', signature: [s.number(), s.number(), s.number()] },
   (a: number, b: number) => a + b,
 );
+
+// Describe shape for clients / WebUI, but skip runtime checks on this param:
+repository.register(
+  {
+    namespace: 'legacy.passthrough',
+    signature: [
+      s.unknown(),
+      s.object({ id: s.number(), tags: s.array(s.string()) }).validate(false),
+    ],
+  },
+  (payload) => payload,
+);
+```
+
+### Schema descriptions (`toJSON` / `system.methodSignature`)
+
+Ordinary schemas use a discriminated union on `kind`. There is **no** generic
+`children` bag:
+
+| kind | Child field(s) |
+| --- | --- |
+| `array` | `element` |
+| `record` | `value` |
+| `object` | `properties` |
+| `union` | `options` |
+| `tuple` | `elements` |
+
+Object constraints in the description:
+
+```ts
+constraints: {
+  optionalProps: string[];
+  allowUnknownProps: boolean;
+}
+```
+
+Empty constraint objects are omitted (no `constraints: {}`).
+
+When validation is turned off, the description includes an explicit flag
+(default is on and omitted to keep noise low):
+
+```ts
+{ kind: 'object', validate: false, properties: { ... } }
+```
+
+Do **not** read legacy paths such as `children.items` or `children.values`.
+
+Stream returns are the exception (marker path in `signatureOf`):
+
+```ts
+{ kind: 'stream', inner: <SchemaDescription> }
 ```
 
 ## Stream a return value
@@ -205,8 +274,17 @@ Keep `withSystemMethods` on (default) to expose `system.listMethods`,
 `system.methodSignature`, `system.methodHelp`. Set `document` on a descriptor
 so `system.methodHelp` returns useful text.
 
-`system.methodSignature` reports a stream return as
-`{ kind: 'stream', children: { inner: <schema> } }`.
+`system.methodSignature` reports ordinary containers with semantic fields
+(`element` / `value` / `properties` / `options` / `elements`). A stream return
+is reported as:
+
+```ts
+{ kind: 'stream', children: { inner: <schema> } }
+```
+
+Schemas with `.validate(false)` appear with `validate: false` in the signature
+description so clients and the WebUI can show that the server will not enforce
+that slot at runtime.
 
 ## Common mistakes
 
@@ -253,3 +331,16 @@ so `system.methodHelp` returns useful text.
 - **Calling `s.literal(null)`.** `literal` only accepts `string | number |
   boolean`; construction throws `TypeError`. Use `s.null()` for exact null, or
   `.nullable()` for "literal or null".
+- **Treating default `s.object(...)` as strict.** By default all declared keys
+  may be missing and unknown keys are kept. Use `.strict()` or
+  `.optionalProperties` / `.allowUnknownProperties` for tighter rules.
+- **Reading schema descriptions via `children.items` / `children.values`.**
+  Those paths are gone. Use `element`, `value`, `properties`, `options`,
+  `elements`. Only stream markers still use `children.inner`.
+- **Assuming `.validate(false)` still type-checks or coerces.** It only skips
+  runtime validation; TypeScript types and the published description stay as
+  declared. Use `s.unknown()` when the value truly has no schema.
+- **Turning off validation on the return schema and expecting the server to
+  enforce the handler result.** Return schemas are for description / WebUI;
+  the server does not re-validate handler return values against them (except
+  stream declaration checks for `AsyncGenerator`).

package/dist/cli/demo-methods.js

@@ -472,4 +472,81 @@ export function installDemoMethods(repository) {
             await new Promise((r) => setTimeout(r, 100));
         }
     });
+    // ─────────────────────────────────────────────────────────────
+    // 14. validate(false)：只描述、不校验
+    // ─────────────────────────────────────────────────────────────
+    // Schema 同时用于签名描述与运行时校验。默认两者都开；
+    // .validate(false) 后 convertParams 仍接受任意 JSON，但
+    // system.methodSignature / WebUI 仍展示完整类型信息。
+    // 14.1 对比：同一形状，一边校验一边不校验
+    repository.register({
+        namespace: 'validate.on',
+        document: '默认开启校验：params[0] 必须是非空字符串，否则 INVALID_PARAMS。',
+        signature: [
+            s.string().describe('回显'),
+            s.string().min(1).max(32).describe('非空短字符串'),
+        ],
+    }, (msg) => msg);
+    repository.register({
+        namespace: 'validate.off',
+        document: '与 validate.on 同形，但参数 schema 关闭了运行时校验。' +
+            '任意 JSON 都能进 handler；类型信息仍出现在 methodSignature / WebUI。',
+        signature: [
+            s.unknown().describe('原样返回（可能并非 string）'),
+            s
+                .string()
+                .min(1)
+                .max(32)
+                .describe('文档上仍是非空短字符串')
+                .validate(false),
+        ],
+    }, (msg) => msg);
+    // 14.2 对象：严格描述 + 关闭校验（信任上游已洗过数据）
+    repository.register({
+        namespace: 'validate.offObject',
+        document: '对象签名写了 strict，但 validate(false)：缺字段 / 多余字段 / 类型错误都不会在 convertParams 阶段失败。',
+        signature: [
+            s.unknown(),
+            s
+                .object({
+                id: s.number().describe('用户 ID'),
+                name: s.string().min(1).describe('名称'),
+            })
+                .strict()
+                .describe('文档上的严格用户对象')
+                .validate(false),
+        ],
+    }, (payload) => payload);
+    // 14.3 嵌套：仅内层关闭校验
+    repository.register({
+        namespace: 'validate.nestedPartial',
+        document: '外层 array 仍校验「必须是数组」；元素 schema 关闭校验，元素内容任意。',
+        signature: [
+            s.array(s.unknown()).describe('原样返回'),
+            s
+                .array(s
+                .object({
+                code: s.string().min(1),
+                qty: s.number().min(0),
+            })
+                .strict()
+                .validate(false))
+                .min(1)
+                .describe('至少 1 个元素；元素内部不校验'),
+        ],
+    }, (items) => items);
+    // 14.4 可再打开：链式 validate(false).validate(true) 与默认等价（演示可撤销）
+    repository.register({
+        namespace: 'validate.reenabled',
+        document: '先 validate(false) 再 validate(true)，效果与默认开启校验相同。',
+        signature: [
+            s.number().describe('原样数字'),
+            s
+                .number()
+                .min(0)
+                .describe('非负数字')
+                .validate(false)
+                .validate(true),
+        ],
+    }, (n) => n);
 }

package/dist/core/llm-tools.js

@@ -50,12 +50,12 @@ function convert(desc) {
                 out.minItems = c.min;
             if (c.max !== undefined)
                 out.maxItems = c.max;
-            out.items = convert(desc.children.items);
+            out.items = convert(desc.element);
             break;
         }
         case 'tuple': {
             out.type = 'array';
-            const items = desc.children.items;
+            const items = desc.elements;
             out.items = items.map(convert);
             out.minItems = items.length;
             out.maxItems = items.length;
@@ -63,19 +63,19 @@ function convert(desc) {
         }
         case 'object': {
             out.type = 'object';
-            const strict = Boolean(desc.constraints.strict);
-            const props = desc.children
-                .properties;
+            const optional = new Set((desc.constraints
+                ?.optionalProps) ?? []);
+            const allowUnknown = (desc.constraints
+                ?.allowUnknownProps) ?? true;
+            const props = desc.properties;
             out.properties = {};
             for (const [k, v] of Object.entries(props))
                 out.properties[k] = convert(v);
-            if (strict) {
-                out.required = Object.keys(props);
+            const required = Object.keys(props).filter((k) => !optional.has(k));
+            if (required.length > 0)
+                out.required = required;
+            if (!allowUnknown)
                 out.additionalProperties = false;
-            }
-            else {
-                out.additionalProperties = true;
-            }
             break;
         }
         case 'record': {
@@ -85,12 +85,11 @@ function convert(desc) {
                 out.minProperties = c.min;
             if (c.max !== undefined)
                 out.maxProperties = c.max;
-            out.additionalProperties = convert(desc.children.values);
+            out.additionalProperties = convert(desc.value);
             break;
         }
         case 'union': {
-            const options = desc.children.options;
-            out.anyOf = options.map(convert);
+            out.anyOf = desc.options.map(convert);
             break;
         }
         case 'unknown': {
@@ -101,8 +100,10 @@ function convert(desc) {
             out.type = 'null';
             break;
         }
-        default:
-            throw new Error(`Unsupported schema kind for JSON Schema: ${desc.kind}`);
+        default: {
+            const _exhaustive = desc;
+            throw new Error(`Unsupported schema kind for JSON Schema: ${JSON.stringify(_exhaustive)}`);
+        }
     }
     if (desc.nullable) {
         if (desc.kind === 'unknown' || desc.kind === 'null') {
@@ -150,7 +151,6 @@ function renderSchema(schema, indent = 0) {
     if (c)
         head += ` \`${c}\``;
     lines.push(head);
-    const ch = schema.children ?? {};
     const pushChild = (label, child) => {
         const sub = renderSchema(child, indent + 1);
         if (sub.length) {
@@ -158,36 +158,35 @@ function renderSchema(schema, indent = 0) {
             lines.push(...sub);
         }
     };
-    if (isSchema(ch.inner))
-        pushChild('inner', ch.inner);
-    if (Array.isArray(ch.items)) {
-        ch.items.forEach((it, i) => {
-            if (isSchema(it))
-                pushChild(`[${i}]`, it);
-        });
-    }
-    else if (isSchema(ch.items)) {
-        pushChild('items', ch.items);
-    }
-    if (Array.isArray(ch.options)) {
-        ch.options.forEach((opt, i) => {
-            if (isSchema(opt))
-                pushChild(`option[${i}]`, opt);
-        });
-    }
-    if (ch.properties && typeof ch.properties === 'object') {
-        for (const [k, v] of Object.entries(ch.properties)) {
-            if (isSchema(v))
+    switch (schema.kind) {
+        case 'array': {
+            pushChild('element', schema.element);
+            break;
+        }
+        case 'record': {
+            pushChild('value', schema.value);
+            break;
+        }
+        case 'object': {
+            for (const [k, v] of Object.entries(schema.properties)) {
                 pushChild(k, v);
+            }
+            break;
+        }
+        case 'union': {
+            schema.options.forEach((opt, i) => pushChild(`option[${i}]`, opt));
+            break;
         }
+        case 'tuple': {
+            schema.elements.forEach((it, i) => pushChild(`[${i}]`, it));
+            break;
+        }
+        default:
+            // 叶子类型：无子节点。
+            break;
     }
-    if (isSchema(ch.values))
-        pushChild('values', ch.values);
     return lines;
 }
-function isSchema(v) {
-    return !!v && typeof v === 'object' && typeof v.kind === 'string';
-}
 /** 渲染返回值槽位（Schema / VoidMarker / StreamMarker）。 */
 function renderReturnSlot(slot) {
     if (slot instanceof VoidMarker)

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

@@ -6,7 +6,7 @@ export declare const s: {
     boolean: () => import("./primitives.js").BooleanSchema;
     literal: <const T extends import("./primitives.js").LiteralValue>(value: T) => import("./primitives.js").LiteralSchema<T>;
     array: <T>(item: import("./primitives.js").Schema<T>) => import("./primitives.js").ArraySchema<T>;
-    object: <S extends import("./primitives.js").ObjectShape>(shape: S) => import("./primitives.js").ObjectSchema<S, false>;
+    object: <S extends import("./primitives.js").ObjectShape>(shape: S) => import("./primitives.js").ObjectSchema<S>;
     record: <T>(value: import("./primitives.js").Schema<T>) => import("./primitives.js").RecordSchema<T>;
     union: <const S extends readonly [import("./primitives.js").Schema<unknown>, ...import("./primitives.js").Schema<unknown>[]]>(schemas: S) => import("./primitives.js").UnionSchema<S>;
     tuple: <const S extends readonly [import("./primitives.js").Schema<unknown>, ...import("./primitives.js").Schema<unknown>[]]>(schemas: S) => import("./primitives.js").TupleSchema<S>;