@xxxaz/json-rpc-schema-typing 0.10.30 → 0.11.0

package/src/JsonRpcMethod.ts

@@ -1,6 +1,6 @@
-import { type JSONSchema, type FromSchema } from "./types.js";
 import { InvalidContext } from './JsonRpcException.js';
 import { $Object, $Tuple } from './schemas/Structure.js';
+import type { FromSchema, JSONSchema } from './types.js';
 
 type ByPositionSchema = {
     readonly type: 'array';
@@ -13,36 +13,118 @@ type ByNameSchema = {
     readonly type: 'object';
     readonly properties: ObjectProperties;
 };
-export type ParameterSchema = ByPositionSchema|ByNameSchema|undefined;
+export type ParameterSchema = ByPositionSchema | ByNameSchema | undefined;
 
-export interface JsonRpcMethodSchema<PrmSch extends ParameterSchema, RtnSch extends JSONSchema|undefined> {
+export interface JsonRpcMethodSchema<
+    PrmSch extends ParameterSchema,
+    RtnSch extends JSONSchema | undefined,
+> {
     readonly $params?: PrmSch;
     readonly $return?: RtnSch;
 }
 
-export type Params<Schema>
-    = Schema extends ByPositionSchema
-        ? FromSchema<Schema>
+/**
+ * クライアント generic (`Schema`) の受け口となる leaf 型。
+ * - 素の method schema (`$params`/`$return`) … 従来の JsonRpcSchema 経路 (WS/MessagePort 等)
+ * - `JsonRpcMethodDefinition` … StaticRouter に直接埋めた定義
+ * - `() => Promise<...>` / `Promise<...>` … route thunk map (lazy import) 経路
+ */
+type SchemaLeaf =
+    | JsonRpcMethodSchema<any, any>
+    | JsonRpcMethodDefinition<any, any, any>
+    | (() => Promise<unknown>)
+    | Promise<unknown>;
+
+/**
+ * クライアント generic の**適合検証用の固定上限型**。
+ * 自己参照 (`Schema extends Conforms<Schema>`) や厳密な `RouteMap<Ctx>` は
+ * 巨大な route リテラルで TS2589 (instantiation too deep) を誘発するため、
+ * 「各 path が leaf か、さらに入れ子の schema 形」という**非自己参照の再帰上限**にして
+ * 適合検証を必ず通しつつ再帰爆発を避ける。primitive / 非 method 形の leaf は弾かれる。
+ */
+export type AnySchemaShape = {
+    readonly [path: string]: SchemaLeaf | AnySchemaShape;
+};
+
+export type Params<Schema> = Schema extends ByPositionSchema
+    ? FromSchema<Schema>
     : Schema extends ByNameSchema
-        ? [FromSchema<Schema>]
-    : Schema extends undefined
+      ? [FromSchema<Schema>]
+      : Schema extends undefined
         ? []
-    : never;
-export type Return<Schema>
-    = Schema extends undefined
-        ? void
+        : never;
+export type Return<Schema> = Schema extends undefined
+    ? void
     : Schema extends JSONSchema
-        ? FromSchema<Schema>
-    : never;
-
-export type JsonRpcMethod<Context, PrmSch extends ParameterSchema, RtnSch extends JSONSchema|undefined>
-    = (this: Context, ...params: Params<PrmSch>) => Promise<Return<RtnSch>>|Return<RtnSch>;
-
-type ContextClass<Ctx> = { new(...args: any[]): Ctx };
+      ? FromSchema<Schema>
+      : never;
+
+export type JsonRpcMethod<
+    Context,
+    PrmSch extends ParameterSchema,
+    RtnSch extends JSONSchema | undefined,
+> = (
+    this: Context,
+    ...params: Params<PrmSch>
+) => Promise<Return<RtnSch>> | Return<RtnSch>;
+
+type ContextClass<Ctx> = { new (...args: any[]): Ctx };
 type Context<Cls, FB> = Cls extends ContextClass<infer Ctx> ? Ctx : FB;
 
+/**
+ * OpenRPC 準拠のメソッドメタ情報。
+ * 型 (JsonRpcCaller 等) は $params/$return のみ参照するため、メタは呼び出し型に影響しない。
+ */
+export type JsonRpcParameterMeta = {
+    readonly summary?: string;
+    readonly description?: string;
+    readonly required?: boolean;
+    readonly deprecated?: boolean;
+};
+export type JsonRpcResultMeta = {
+    readonly name: string;
+    readonly summary?: string;
+    readonly description?: string;
+};
+export type JsonRpcErrorMeta = {
+    readonly code: number;
+    readonly message: string;
+    readonly data?: unknown;
+};
+export type JsonRpcExampleMeta = {
+    readonly name: string;
+    readonly summary?: string;
+    readonly description?: string;
+    readonly params: readonly unknown[] | Readonly<Record<string, unknown>>;
+    readonly result?: unknown;
+};
+export type JsonRpcExternalDocsMeta = {
+    readonly url: string;
+    readonly description?: string;
+};
+export type JsonRpcMethodMeta = {
+    readonly summary?: string;
+    readonly description?: string;
+    readonly tags?: readonly string[];
+    readonly result?: JsonRpcResultMeta;
+    /**
+     * パラメータ別メタ。paramsByName の場合キーは $Object のプロパティ名。
+     * paramsByPosition の場合はキーの記述順が位置に対応する (キー名が param name になる)。
+     */
+    readonly params?: Readonly<Record<string, JsonRpcParameterMeta>>;
+    readonly errors?: readonly JsonRpcErrorMeta[];
+    readonly examples?: readonly JsonRpcExampleMeta[];
+    readonly deprecated?: boolean;
+    readonly externalDocs?: JsonRpcExternalDocsMeta;
+};
+
 const methodKey = Symbol('JsonRpcMethodDefinition.method');
-export class JsonRpcMethodDefinition<Context, PrmSch extends ParameterSchema, RtnSch extends JSONSchema|undefined> implements JsonRpcMethodSchema<PrmSch, RtnSch> {
+export class JsonRpcMethodDefinition<
+    Context,
+    PrmSch extends ParameterSchema,
+    RtnSch extends JSONSchema | undefined,
+> implements JsonRpcMethodSchema<PrmSch, RtnSch>
+{
     static readonly method: typeof methodKey = methodKey;
     readonly [methodKey]: JsonRpcMethod<Context, PrmSch, RtnSch>;
 
@@ -51,53 +133,111 @@ export class JsonRpcMethodDefinition<Context, PrmSch extends ParameterSchema, Rt
         readonly $params: PrmSch,
         readonly $return: RtnSch,
         readonly $contextClass?: ContextClass<Context>,
+        readonly $meta?: JsonRpcMethodMeta,
     ) {
         this[methodKey] = method;
     }
 
+    // instanceof はモジュール実体が二重ロードされた際に一致しないため、duck-typing でも判定する
+    static isDefinition(
+        obj: unknown,
+    ): obj is JsonRpcMethodDefinition<any, any, any> {
+        if (obj instanceof JsonRpcMethodDefinition) return true;
+        const key = (obj as any)?.constructor?.method;
+        return typeof key === 'symbol' && (obj as any)[key] instanceof Function;
+    }
+
     $apply(ctx: Context, params: any) {
-        if(this.$contextClass && !(ctx instanceof this.$contextClass)) {
+        if (this.$contextClass && !(ctx instanceof this.$contextClass)) {
             const passedCtxType = (ctx as any)?.constructor?.name ?? typeof ctx;
-            throw new InvalidContext(`Invalid context: expected ${this.$contextClass.name} but got ${passedCtxType}`);
+            throw new InvalidContext(
+                `Invalid context: expected ${this.$contextClass.name} but got ${passedCtxType}`,
+            );
         }
         if (this.$params?.type === 'object') params = [params];
         return this[methodKey].apply(ctx, params);
     }
 
-    static get builder(){
+    static get builder() {
         return new DefinitionBuilder(undefined, undefined, undefined);
     }
 }
 
-class DefinitionBuilder<CtxCls extends ContextClass<any>|undefined, PrmSch extends ParameterSchema, RtnSch extends JSONSchema|undefined> implements JsonRpcMethodSchema<PrmSch, RtnSch> {
+class DefinitionBuilder<
+    CtxCls extends ContextClass<any> | undefined,
+    PrmSch extends ParameterSchema,
+    RtnSch extends JSONSchema | undefined,
+> implements JsonRpcMethodSchema<PrmSch, RtnSch>
+{
     constructor(
         readonly $contextClass: CtxCls,
         readonly $params: PrmSch,
         readonly $return: RtnSch,
+        readonly $meta?: JsonRpcMethodMeta,
     ) {}
 
-    define<Ctx = {}>(method: JsonRpcMethod<Context<CtxCls, Ctx>, PrmSch, RtnSch>) {
-        return new JsonRpcMethodDefinition<Context<CtxCls, Ctx>, PrmSch, RtnSch>(method, this.$params, this.$return, this.$contextClass);
+    define<Ctx = {}>(
+        method: JsonRpcMethod<Context<CtxCls, Ctx>, PrmSch, RtnSch>,
+    ) {
+        return new JsonRpcMethodDefinition<
+            Context<CtxCls, Ctx>,
+            PrmSch,
+            RtnSch
+        >(method, this.$params, this.$return, this.$contextClass, this.$meta);
     }
 
     contextClass<CtxCls extends ContextClass<any>>(contextClass: CtxCls) {
-        return new DefinitionBuilder(contextClass, this.$params, this.$return);
+        return new DefinitionBuilder(
+            contextClass,
+            this.$params,
+            this.$return,
+            this.$meta,
+        );
+    }
+
+    meta(meta: JsonRpcMethodMeta) {
+        return new DefinitionBuilder(
+            this.$contextClass,
+            this.$params,
+            this.$return,
+            meta,
+        );
     }
 
     params<NewPrm extends ParameterSchema>(params: NewPrm) {
-        return new DefinitionBuilder(this.$contextClass, params, this.$return);
+        return new DefinitionBuilder(
+            this.$contextClass,
+            params,
+            this.$return,
+            this.$meta,
+        );
     }
 
     paramsByName<NewPrm extends ObjectProperties>(params: NewPrm) {
-        return new DefinitionBuilder(this.$contextClass, $Object(params), this.$return);
+        return new DefinitionBuilder(
+            this.$contextClass,
+            $Object(params),
+            this.$return,
+            this.$meta,
+        );
     }
 
     paramsByPosition<NewPrm extends readonly JSONSchema[]>(...params: NewPrm) {
-        return new DefinitionBuilder(this.$contextClass, $Tuple(...params), this.$return);
+        return new DefinitionBuilder(
+            this.$contextClass,
+            $Tuple(...params),
+            this.$return,
+            this.$meta,
+        );
     }
 
-    return<NewRtn extends JSONSchema|undefined>(rtn: NewRtn) {
-        return new DefinitionBuilder(this.$contextClass, this.$params, rtn);
+    return<NewRtn extends JSONSchema | undefined>(rtn: NewRtn) {
+        return new DefinitionBuilder(
+            this.$contextClass,
+            this.$params,
+            rtn,
+            this.$meta,
+        );
     }
 
     /** @deprecated paramsByPosition を使用してください */
@@ -105,7 +245,7 @@ class DefinitionBuilder<CtxCls extends ContextClass<any>|undefined, PrmSch exten
         return this.paramsByPosition(...params);
     }
     /** @deprecated return を使用してください */
-    returnSchema<NewRtn extends JSONSchema|undefined>(rtn: NewRtn) {
+    returnSchema<NewRtn extends JSONSchema | undefined>(rtn: NewRtn) {
         return this.return(rtn);
     }
 }

package/src/JsonRpcValidator.ts

@@ -1,41 +1,54 @@
-import { FromSchema } from 'json-schema-to-ts';
-import { JsonRpcMethodSchema, ParameterSchema } from "./JsonRpcMethod.js";
-import { JSONSchema } from "./types.js";
+import type { FromSchema } from 'json-schema-to-ts';
 import { InvalidParams, InvalidReturn } from './JsonRpcException.js';
+import type { JsonRpcMethodSchema, ParameterSchema } from './JsonRpcMethod.js';
 import { JsonSchemaValidator } from './JsonSchemaValidator.js';
+import type { JSONSchema } from './types.js';
 
 type Valid<S> = S extends JSONSchema ? FromSchema<S> : never;
 
 export class JsonRpcValidator<
     P extends ParameterSchema,
     R extends JSONSchema | undefined,
-    Sch extends JsonRpcMethodSchema<P, R>
+    Sch extends JsonRpcMethodSchema<P, R>,
 > {
     constructor(readonly schema: Sch) {
-        this.#paramValidator = schema.$params ? new JsonSchemaValidator(schema.$params): null;
-        this.#returnValidator = schema.$return ? new JsonSchemaValidator(schema.$return) : null;
+        this.#paramValidator = schema.$params
+            ? new JsonSchemaValidator(schema.$params)
+            : null;
+        this.#returnValidator = schema.$return
+            ? new JsonSchemaValidator(schema.$return)
+            : null;
     }
-    #paramValidator:JsonSchemaValidator | null;
-    #returnValidator:JsonSchemaValidator | null;
+    #paramValidator: JsonSchemaValidator | null;
+    #returnValidator: JsonSchemaValidator | null;
 
     validateParams(params: unknown): Valid<Sch['$params']> {
-        if(!this.#paramValidator) return params as Valid<Sch['$params']>;
+        if (!this.#paramValidator) return params as Valid<Sch['$params']>;
         const validated = this.#paramValidator.validate(params);
-        if(!validated.valid && validated.errors.length > 0) {
-            const message = validated.errors.map(({ instancePath, message }) => `params${instancePath ?? ''}: ${message}`).join('\n');
+        if (!validated.valid && validated.errors.length > 0) {
+            const message = validated.errors
+                .map(
+                    ({ instancePath, message }) =>
+                        `params${instancePath ?? ''}: ${message}`,
+                )
+                .join('\n');
             throw new InvalidParams(message, validated.errors);
         }
         return params as Valid<Sch['$params']>;
     }
 
     validateReturn(result: unknown): Valid<Sch['$return']> {
-        if(!this.#returnValidator) return result as Valid<Sch['$return']>;
+        if (!this.#returnValidator) return result as Valid<Sch['$return']>;
         const validated = this.#returnValidator.validate(result);
         if (!validated.valid && validated.errors.length > 0) {
-            const message = validated.errors.map(({ instancePath, message }) => `return.${instancePath ?? ''}: ${message}`).join('\n');
+            const message = validated.errors
+                .map(
+                    ({ instancePath, message }) =>
+                        `return.${instancePath ?? ''}: ${message}`,
+                )
+                .join('\n');
             throw new InvalidReturn(message, validated.errors);
         }
         return result as Valid<Sch['$return']>;
     }
-
-}
+}

package/src/JsonSchemaValidator.ts

@@ -1,5 +1,10 @@
-import { Ajv, Options as AjvOptions, ValidateFunction, ErrorObject } from 'ajv';
-import { type JSONSchema } from 'json-schema-to-ts';
+import {
+    Ajv,
+    type Options as AjvOptions,
+    type ErrorObject,
+    type ValidateFunction,
+} from 'ajv';
+import type { JSONSchema } from 'json-schema-to-ts';
 import type { Worker as NodeWorker } from 'worker_threads';
 
 const isBrowser =
@@ -16,12 +21,14 @@ function currentFile() {
         return globalThis.__filename;
     }
     try {
-        return Function("return import.meta.filename")();
+        return Function('return import.meta.filename')();
     } catch (err) {
         if (!(err instanceof SyntaxError)) throw err;
     }
 
-    const script = globalThis.document?.currentScript as HTMLScriptElement | undefined;
+    const script = globalThis.document?.currentScript as
+        | HTMLScriptElement
+        | undefined;
     if (script?.src) {
         return script?.src;
     }
@@ -29,7 +36,6 @@ function currentFile() {
     return null;
 }
 
-
 type SerializedError = {
     propertyName?: string;
     message?: string;
@@ -39,26 +45,35 @@ type SerializedError = {
     schemaPath?: string;
 };
 
-function * serializeErrors(error?: ErrorObject[]|null) : Generator<SerializedError> {
-    if(!error) return;
-    for(const { propertyName, message, schemaPath, data, keyword, instancePath, params } of error) {
+function* serializeErrors(
+    error?: ErrorObject[] | null,
+): Generator<SerializedError> {
+    if (!error) return;
+    for (const {
+        propertyName,
+        message,
+        schemaPath,
+        data,
+        keyword,
+        instancePath,
+        params,
+    } of error) {
         const err = {} as SerializedError;
-        if(propertyName) err.propertyName = propertyName;
-        if(message) err.message = message;
-        if(data) err.data = data;
-        if(keyword) err.keyword = keyword;
-        if(instancePath) err.instancePath = instancePath;
-        if(schemaPath) err.schemaPath = schemaPath;
+        if (propertyName) err.propertyName = propertyName;
+        if (message) err.message = message;
+        if (data) err.data = data;
+        if (keyword) err.keyword = keyword;
+        if (instancePath) err.instancePath = instancePath;
+        if (schemaPath) err.schemaPath = schemaPath;
         if (Object.keys(err).length > 0) {
             yield err;
         }
         if (params.errors) {
-            yield * serializeErrors(params.errors);
+            yield* serializeErrors(params.errors);
         }
     }
 }
 
-
 type ValidationResult =
     | { valid: true }
     | {
@@ -72,7 +87,7 @@ const methodName = '@xxxaz/json-schema-typing.JsonSchemaValidator.validate';
 export class JsonSchemaValidator {
     constructor(
         readonly schema: JSONSchema & object,
-        ajvOptions?: AjvOptions
+        ajvOptions?: AjvOptions,
     ) {
         this.#ajv = new Ajv(ajvOptions);
         this.#validate = this.#ajv.compile(this.schema);
@@ -106,13 +121,18 @@ export class JsonSchemaValidator {
         const id = crypto.randomUUID();
         const listener = Promise.withResolvers<ValidationResult>();
         listeners[id] = listener;
-        worker.postMessage({ method: methodName, schema: this.schema, data, id });
+        worker.postMessage({
+            method: methodName,
+            schema: this.schema,
+            data,
+            id,
+        });
         return listener.promise;
     }
 }
 
 type WorkerType = NodeWorker | Worker;
-let workers: WeakMap<object, WorkerType> = new WeakMap();
+const workers: WeakMap<object, WorkerType> = new WeakMap();
 let listeners: Record<string, PromiseWithResolvers<ValidationResult>> = {};
 async function getWorker(key: object): Promise<WorkerType | null> {
     if (workers.has(key)) return workers.get(key) ?? null;
@@ -138,7 +158,11 @@ async function getWorker(key: object): Promise<WorkerType | null> {
     workers.set(key, worker);
     return worker;
 }
-function onMessage(data: {id: string, result?: ValidationResult, error?: any}) {
+function onMessage(data: {
+    id: string;
+    result?: ValidationResult;
+    error?: any;
+}) {
     const listener = listeners[data.id];
     if (listener) {
         if (data.error) {
@@ -150,7 +174,9 @@ function onMessage(data: {id: string, result?: ValidationResult, error?: any}) {
     }
 }
 function onError(err: Error) {
-    Object.values(listeners).forEach(({ reject }) => reject(err));
+    Object.values(listeners).forEach(({ reject }) => {
+        reject(err);
+    });
     listeners = {};
 }
 function onFaild(data: { id: string }) {
@@ -162,7 +188,12 @@ function onFaild(data: { id: string }) {
 }
 
 (async function kickValidateInWorker(): Promise<void> {
-    type ReceiveMesg = { method: string; id: string; schema: JSONSchema & object; data: unknown };
+    type ReceiveMesg = {
+        method: string;
+        id: string;
+        schema: JSONSchema & object;
+        data: unknown;
+    };
     const onMessage = (msg: ReceiveMesg, callback: (result: {}) => void) => {
         const { id, schema, data } = msg;
         try {
@@ -180,7 +211,7 @@ function onFaild(data: { id: string }) {
             if (msg.method !== methodName) return;
             onMessage(msg, (result) => parentPort.postMessage(result));
         });
-    } 
+    }
     if (isWebWorker) {
         self.addEventListener('message', (ev) => {
             const msg = ev.data as ReceiveMesg;
@@ -191,5 +222,3 @@ function onFaild(data: { id: string }) {
         });
     }
 })();
-
-

package/src/WebSocketWrapper.ts

@@ -1,12 +1,20 @@
-import { type WebSocket as NodeWebSocket, type RawData } from 'ws';
-import { type JsonSerializable } from "@xxxaz/stream-api-json";
-
-export type WrapableWebSocket = WebSocket|NodeWebSocket;
-export function wrapWebSocket(socket: WrapableWebSocket, listener: SocketListener, closedListener: ScokcetClosedListener) {
+import type { JsonSerializable } from '@xxxaz/stream-api-json';
+import type { WebSocket as NodeWebSocket, RawData } from 'ws';
+
+export type WrapableWebSocket = WebSocket | NodeWebSocket;
+export function wrapWebSocket(
+    socket: WrapableWebSocket,
+    listener: SocketListener,
+    closedListener: ScokcetClosedListener,
+) {
     if ('WebSocket' in globalThis && socket instanceof WebSocket) {
         return new BrowserWebSocketWrapper(socket, listener, closedListener);
     }
-    return new NodeWebSocketWrapper(socket as NodeWebSocket, listener, closedListener);
+    return new NodeWebSocketWrapper(
+        socket as NodeWebSocket,
+        listener,
+        closedListener,
+    );
 }
 
 type ClosedData = {
@@ -19,10 +27,12 @@ type ClosedData = {
 type SocketListener = (data: JsonSerializable) => void;
 type ScokcetClosedListener = (data: ClosedData) => void;
 
-type ConnectionState = 'CONNECTING'|'OPEN'|'CLOSING'|'CLOSED';
+type ConnectionState = 'CONNECTING' | 'OPEN' | 'CLOSING' | 'CLOSED';
 export type WebSocketState = (typeof WebSocket)[ConnectionState];
 
-export interface WebSocketWrapper<Socket extends WrapableWebSocket = WrapableWebSocket> {
+export interface WebSocketWrapper<
+    Socket extends WrapableWebSocket = WrapableWebSocket,
+> {
     readonly socket: Socket;
     readonly listener: SocketListener;
     readonly readyState: WebSocketState;
@@ -35,7 +45,7 @@ export class NodeWebSocketWrapper implements WebSocketWrapper<NodeWebSocket> {
     constructor(
         readonly socket: NodeWebSocket,
         readonly listener: SocketListener,
-        readonly closedListener: ScokcetClosedListener
+        readonly closedListener: ScokcetClosedListener,
     ) {
         socket.on('message', this.#onMessage);
         socket.on('close', (code, reasonBuffer) => {
@@ -67,14 +77,14 @@ export class NodeWebSocketWrapper implements WebSocketWrapper<NodeWebSocket> {
         this.listener(parsed);
     };
 
-    async #parseMessage(data: RawData) : Promise<JsonSerializable> {
+    async #parseMessage(data: RawData): Promise<JsonSerializable> {
         if (data instanceof ArrayBuffer) {
             return JSON.parse(await new Blob([data]).text());
         }
-        const json
-            = data instanceof Array
-            ? data.map(d=>JSON.parse(d.toString())).join('')
-            : data.toString()
+        const json =
+            data instanceof Array
+                ? data.map((d) => JSON.parse(d.toString())).join('')
+                : data.toString();
         return JSON.parse(json);
     }
 }
@@ -83,11 +93,16 @@ export class BrowserWebSocketWrapper implements WebSocketWrapper<WebSocket> {
     constructor(
         readonly socket: WebSocket,
         readonly listener: SocketListener,
-        readonly closedListener: ScokcetClosedListener
+        readonly closedListener: ScokcetClosedListener,
     ) {
         socket.addEventListener('message', this.#onMessage);
-        socket.addEventListener('close', ev => {
-            closedListener({ code: ev.code, reason: ev.reason, wasClean: ev.wasClean, wrapper: this });
+        socket.addEventListener('close', (ev) => {
+            closedListener({
+                code: ev.code,
+                reason: ev.reason,
+                wasClean: ev.wasClean,
+                wrapper: this,
+            });
             this.socket.removeEventListener('message', this.#onMessage);
         });
     }
@@ -101,7 +116,9 @@ export class BrowserWebSocketWrapper implements WebSocketWrapper<WebSocket> {
         this.listener(parsed);
     };
 
-    async #parseMessage(data: ArrayBuffer|string|object) : Promise<JsonSerializable> {
+    async #parseMessage(
+        data: ArrayBuffer | string | object,
+    ): Promise<JsonSerializable> {
         if (data instanceof ArrayBuffer) {
             return JSON.parse(await new Blob([data]).text());
         }
@@ -127,4 +144,4 @@ export class BrowserWebSocketWrapper implements WebSocketWrapper<WebSocket> {
         this.detach();
         this.socket.close();
     }
-}
+}