fix json stringify bug && add docs

Author: YieldRay

src/client.ts

@@ -1,4 +1,4 @@
-import { type JSONRPCMethodSet } from './types.ts'
+import type { JSONRPCMethodSet, JSONRPCSettledResult } from './types.ts'
 import { JSONRPCNotification, JSONRPCRequest } from './dto/request.ts'
 import { JSONRPCErrorResponse, JSONRPCSuccessResponse } from './dto/response.ts'
 import { isJSONRPCResponse, JSONRPCResponse } from './dto/response.ts'
@@ -14,7 +14,7 @@ type JSONRPCAnyRequest =
     | Array<JSONRPCNotification | JSONRPCRequest>
 
 /**
- * the client cannot parse the server response
+ * The client cannot parse the server response
  */
 export class JSONRPCClientParseError extends Error {
     name = 'JSONRPCClientParseError'
@@ -26,7 +26,7 @@ export class JSONRPCClientParseError extends Error {
 }
 
 /**
- * just wrap the JSON.parse function
+ * Just wrap the JSON.parse function, with potential `JSONRPCClientParseError`
  */
 function parseJSON(
     text: string,
@@ -42,13 +42,22 @@ function parseJSON(
     }
 }
 
+/**
+ * Provide a external `processor` function to the constructor,
+ * it should accept a string (json encoded from one or more json rpc request)
+ * and your customized code should send this string to a json rpc server
+ * for any response represented as **string**
+ *
+ * The constructor optionally accept a customized id generator, otherwise it use a
+ * self added number
+ */
 export class JSONRPCClient<MethodSet extends JSONRPCMethodSet> {
     /**
      * MUST be an infinite iterator
      */
     private idGenerator: IDGenerator
     /**
-     * the extern function to request the server for response
+     * The extern function to request the server for response
      */
     private processor: (input: string) => Promise<string>
 
@@ -84,19 +93,9 @@ export class JSONRPCClient<MethodSet extends JSONRPCMethodSet> {
         return notification
     }
 
-    private processOneJsonValue(
-        jsonValue: unknown,
-        associatedRequest: JSONRPCAnyRequest,
-    ): JSONRPCResponse {
-        if (!isJSONRPCResponse(jsonValue)) {
-            throw new JSONRPCClientParseError(
-                `The server sent an incorrect response object`,
-                associatedRequest,
-            )
-        }
-        return jsonValue
-    }
-
+    /**
+     * Send `JSONRPCRequest` to server, returns `JSONRPCValue` or throw `JSONRPCErrorInterface` (or `JSONRPCClientParseError`)
+     */
     async request<T extends keyof MethodSet>(
         method: T extends string ? T : never,
         params?: Parameters<MethodSet[T]>[0],
@@ -105,15 +104,29 @@ export class JSONRPCClient<MethodSet extends JSONRPCMethodSet> {
         // responsed json string
         const jsonString = await this.processor(JSON.stringify(request))
         const jsonValue = parseJSON(jsonString, request)
+
         // parsed response
-        const response = this.processOneJsonValue(jsonValue, request)
+        if (!isJSONRPCResponse(jsonValue)) {
+            throw new JSONRPCClientParseError(
+                `The server sent an incorrect response object`,
+                request,
+            )
+        }
+        // now jsonValue become JSONRPCResponse
+        const response: JSONRPCResponse = jsonValue
+
         if ('error' in response) {
-            return Promise.reject(response.error)
+            throw response.error
         } else {
-            return response.result
+            // response.result is now JSONRPCValue
+            return response.result as ReturnType<MethodSet[T]>
         }
     }
 
+    /**
+     * Send `JSONRPCNotification` to server, no returns,
+     * only throws if your provided `processor` function throws
+     */
     async notify<T extends keyof MethodSet>(
         method: T extends string ? T : never,
         params?: Parameters<MethodSet[T]>[0],
@@ -123,13 +136,12 @@ export class JSONRPCClient<MethodSet extends JSONRPCMethodSet> {
     }
 
     /**
-     * You should use the createRequest() or createNotifaction() method to
+     * You should use the `createRequest()` or `createNotifaction()` method to
      * create the requests array
      */
     async batch(
         ...requests: Array<JSONRPCRequest | JSONRPCNotification>
-        // deno-lint-ignore no-explicit-any
-    ): Promise<PromiseSettledResult<any>[] | PromiseSettledResult<any>> {
+    ): Promise<JSONRPCSettledResult | JSONRPCSettledResult[]> {
         // responsed json string
         const jsonString = await this.processor(JSON.stringify(requests))
         const requestCount = requests.filter((r) => 'id' in r).length
@@ -166,7 +178,7 @@ export class JSONRPCClient<MethodSet extends JSONRPCMethodSet> {
 
         if (!jsonValue.every(isJSONRPCResponse)) {
             throw new JSONRPCClientParseError(
-                `The server returned batch response contains invalid value`,
+                `The server returned batch response contains invalid one`,
                 requests,
             )
         }

src/dto/errors.test.ts

@@ -4,21 +4,12 @@ import { isJSONRPCError } from './errors.ts'
 Deno.test('isJSONRPCError', () => {
     assertEquals(
         isJSONRPCError({
-            id: null,
             code: 6,
             message: 'null',
         }),
         true,
     )
 
-    assertEquals(
-        isJSONRPCError({
-            code: 6,
-            message: 'null',
-        }),
-        false,
-    )
-
     assertEquals(
         isJSONRPCError({
             id: 6,

src/dto/errors.ts

@@ -1,5 +1,4 @@
-// deno-lint-ignore-file no-explicit-any
-import { isJSONRPCID } from '../id.ts'
+import type { JSONRPCValue } from '../types.ts'
 /**
  * The error codes from and including -32768 to -32000 are reserved for pre-defined errors. Any code within this range, but not defined explicitly below is reserved for future use. The error codes are nearly the same as those suggested for XML-RPC at the following url: http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php
  */
@@ -19,45 +18,34 @@ export interface JSONRPCErrorInterface {
      * This may be omitted.
      * The value of this member is defined by the Server (e.g. detailed error information, nested errors etc.).
      */
-    data?: any
+    data?: JSONRPCValue
 }
 
 export class JSONRPCError extends Error implements JSONRPCErrorInterface {
     public code: number
     public message: string
-    public data?: any
+    public data?: JSONRPCValue
 
     public constructor(object: JSONRPCErrorInterface) {
         super(object.message)
         this.code = object.code
         this.message = object.message
         this.data = object.data
     }
-
-    public toString() {
-        return JSON.stringify({
-            code: this.code,
-            message: this.message,
-            data: this.data,
-        })
-    }
-
-    public toJSON() {
-        return this.toString()
-    }
 }
 
+/**
+ * This ONLY check if `x` is `JSONRPCErrorInterface`
+ *
+ * Because it'a shared method between client and server, but `JSONRPCError` is server side only
+ */
 export function isJSONRPCError(x: unknown): x is JSONRPCErrorInterface {
     if (!x || typeof x !== 'object') {
         return false
     }
-    if (x instanceof JSONRPCError) {
-        return true
-    }
     if (
         typeof Reflect.get(x, 'code') === 'number' &&
-        typeof Reflect.get(x, 'message') === 'string' &&
-        isJSONRPCID(Reflect.get(x, 'id'))
+        typeof Reflect.get(x, 'message') === 'string'
     ) {
         return true
     }
@@ -66,7 +54,7 @@ export function isJSONRPCError(x: unknown): x is JSONRPCErrorInterface {
 }
 
 export class JSONRPCParseError extends JSONRPCError {
-    constructor(data?: any) {
+    constructor(data?: JSONRPCValue) {
         super({
             code: -32700,
             message: 'Parse error',
@@ -76,7 +64,7 @@ export class JSONRPCParseError extends JSONRPCError {
 }
 
 export class JSONRPCInvalidRequestError extends JSONRPCError {
-    constructor(data?: any) {
+    constructor(data?: JSONRPCValue) {
         super({
             code: -32600,
             message: 'Invalid Request',
@@ -86,7 +74,7 @@ export class JSONRPCInvalidRequestError extends JSONRPCError {
 }
 
 export class JSONRPCMethodNotFoundError extends JSONRPCError {
-    constructor(data?: any) {
+    constructor(data?: JSONRPCValue) {
         super({
             code: -32601,
             message: 'Method not found',
@@ -96,7 +84,7 @@ export class JSONRPCMethodNotFoundError extends JSONRPCError {
 }
 
 export class JSONRPCInvalidParamsError extends JSONRPCError {
-    constructor(data?: any) {
+    constructor(data?: JSONRPCValue) {
         super({
             code: -32602,
             message: 'Invalid params',
@@ -106,7 +94,7 @@ export class JSONRPCInvalidParamsError extends JSONRPCError {
 }
 
 export class JSONRPCInternalError extends JSONRPCError {
-    constructor(data?: any) {
+    constructor(data?: JSONRPCValue) {
         super({
             code: -32603,
             message: 'Internal error',

src/dto/index.ts

@@ -0,0 +1,3 @@
+export * from './errors.ts'
+export * from './request.ts'
+export * from './response.ts'

src/dto/request.ts

@@ -1,5 +1,11 @@
+import type { JSONRPCValue, WithOptionalJSONRPCVersion } from '../types.ts'
 import { isJSONRPCID, type JSONRPCID } from '../id.ts'
 
+/**
+ * You should create this object via method from `JSONRPCClient`, it generate id for you.
+ *
+ * It's less likely that you need to create this object manually.
+ */
 export class JSONRPCNotification {
     public jsonrpc = '2.0' as const
     /**
@@ -9,15 +15,11 @@ export class JSONRPCNotification {
     /**
      * A Structured value that holds the parameter values to be used during the invocation of the method. This member MAY be omitted.
      */
-    // deno-lint-ignore no-explicit-any
-    public params?: any
+    public params?: JSONRPCValue
 
-    public constructor(object: {
-        jsonrpc?: '2.0'
-        method: string
-        // deno-lint-ignore no-explicit-any
-        params?: any
-    }) {
+    public constructor(
+        object: WithOptionalJSONRPCVersion<JSONRPCNotification>,
+    ) {
         this.method = object.method
         this.params = object.params
     }
@@ -31,19 +33,18 @@ export class JSONRPCNotification {
     }
 }
 
+/**
+ * You should create this object via method from `JSONRPCClient`, it generate id for you.
+ *
+ * It's less likely that you need to create this object manually.
+ */
 export class JSONRPCRequest extends JSONRPCNotification {
     /**
      * An identifier established by the Client that MUST contain a String, Number, or NULL value if included. If it is not included it is assumed to be a notification. The value SHOULD normally not be Null and Numbers SHOULD NOT contain fractional parts
      */
     public id: JSONRPCID
 
-    public constructor(object: {
-        jsonrpc?: '2.0'
-        method: string
-        // deno-lint-ignore no-explicit-any
-        params?: any
-        id: JSONRPCID
-    }) {
+    public constructor(object: WithOptionalJSONRPCVersion<JSONRPCRequest>) {
         super(object)
         this.id = object.id
     }
@@ -59,18 +60,17 @@ export class JSONRPCRequest extends JSONRPCNotification {
 }
 
 /**
- * WARN: this check if `x` is JSONRPCNotification or JSONRPCRequest
- * to check if `x` is `JSONRPCRequest`, ONLY need to check `'id' in x`
+ * WARN: this check if `x` is `JSONRPCNotification` or `JSONRPCRequest`
+ *
+ * To check if `x` is `JSONRPCRequest`, ONLY need to check `'id' in x`
  */
 export function isJSONRPCRequest(
     x: unknown,
 ): x is JSONRPCNotification | JSONRPCRequest {
     if (!x || typeof x !== 'object') {
         return false
     }
-    if (x instanceof JSONRPCNotification) {
-        return true
-    } else if (
+    if (
         Reflect.get(x, 'jsonrpc') === '2.0' &&
         typeof Reflect.get(x, 'method') === 'string'
     ) {