better comments

Author: YieldRay

build.ts

@@ -43,7 +43,7 @@ Deno.writeTextFileSync('./package.json', JSON.stringify(packageJson, null, 4))
 console.log('New package.json created.')
 console.log(packageJson)
 
-const builderName = 'unbuild@3.5.0'
+const builderName = 'unbuild@3.6.1'
 console.log(`Building package using ${builderName}...`)
 new Deno.Command('npx', {
     args: ['-y', builderName],

deno.json

@@ -1,6 +1,6 @@
 {
     "name": "@yieldray/json-rpc-ts",
-    "version": "0.2.1",
+    "version": "0.2.2",
     "exports": "./mod.ts",
     "publish": {
         "include": [
@@ -20,7 +20,7 @@
         "useUnknownInCatchVariables": true,
         "noImplicitOverride": true
     },
-    "imports": { "@std/assert": "jsr:@std/assert@^1.0.13" },
+    "imports": { "@std/assert": "jsr:@std/assert@^1.0.14" },
     "tasks": {
         "lint": "deno lint",
         "fmt": "deno fmt",

deno.lock

@@ -13,36 +13,36 @@ import {
 } from './id.ts'
 
 /**
- * Provide a external `requestForResponse` function to the constructor,
- * it should accept a `string` (json encoded from one or more json rpc request)
- * and your customized function should send this string to a json rpc server
- * for any response represented as `string`
+ * Provide an external `requestForResponse` function to the constructor.
+ * This function should accept a `string` (JSON-encoded from one or more JSON-RPC requests),
+ * and your custom implementation should send this string to a JSON-RPC server,
+ * returning any response as a `string`.
  *
- * The constructor optionally accept a customized id generator, otherwise it use a
- * self added number
+ * The constructor optionally accepts a custom ID generator; otherwise, it uses
+ * an internally generated number.
  *
- * To customize the request or response, you can extend `JSONRPCClient`.
+ * To customize requests or responses, extend the `JSONRPCClient` class.
  *
- * To customize request, overwrite `createRequest` and `createNotification` methods.
+ * To customize requests, override the `createRequest` and `createNotification` methods.
  *
- * To customize response, overwrite `request` `notify` and `batch` methods.
+ * To customize responses, override the `request`, `notify`, and `batch` methods.
  */
 export class JSONRPCClient<
     Methods extends JSONRPCMethods = JSONRPCMethods,
 > {
     /**
-     * MUST be an infinite iterator
+     * MUST be an infinite iterator.
      */
     protected idGenerator: IDGenerator
     /**
-     * The external function to send the json string to any rpc server,
-     * and fetch for response as string
+     * The external function that sends the JSON string to any RPC server
+     * and fetches the response as a string.
      */
     protected requestForResponse: (input: string) => string | Promise<string>
 
     /**
-     * @param requestForResponse An external function to send the json string to any rpc server,
-     * and fetch for response as string
+     * @param requestForResponse An external function that sends the JSON string to any RPC server
+     * and fetches the response as a string.
      */
     public constructor(
         requestForResponse: (input: string) => string | Promise<string>,
@@ -68,6 +68,9 @@ export class JSONRPCClient<
         return request
     }
 
+    /**
+     * Creates a JSON-RPC notification object.
+     */
     public createNotification<T extends keyof Methods>(
         method: T extends string ? T : never,
         params: Parameters<Methods[T]>[0],
@@ -80,7 +83,8 @@ export class JSONRPCClient<
     }
 
     /**
-     * Send `JSONRPCRequest` to server, returns `JSONRPCValue` or throw `JSONRPCErrorInterface` (or `JSONRPCClientParseError`)
+     * Sends a `JSONRPCRequest` to the server and returns a `JSONRPCValue`,
+     * or throws a `JSONRPCErrorInterface` (or `JSONRPCClientParseError`).
      */
     public async request<T extends keyof Methods>(
         method: T extends string ? T : never,
@@ -120,8 +124,8 @@ export class JSONRPCClient<
     }
 
     /**
-     * Send `JSONRPCNotification` to server, no returns,
-     * only throws if your provided `processor` function throws
+     * Sends a `JSONRPCNotification` to the server. No return value.
+     * Throws only if your provided `processor` function throws.
      */
     public async notify<T extends keyof Methods>(
         method: T extends string ? T : never,
@@ -132,14 +136,13 @@ export class JSONRPCClient<
     }
 
     /**
-     * You should use the `createRequest()` or `createNotification()` method to
-     * create the requests array. Response order is always matched by id.
+     * Use the `createRequest()` or `createNotification()` method to create the requests array.
+     * Response order is always matched by ID.
      *
-     * Throws `JSONRPCClientParseError` if server response cannot be parsed,
-     * note that it does not throws for any `JSONRPCErrorResponse`, in this
-     * case it will be a single object: `{ status: 'rejected', reason: {...} }`
+     * Throws `JSONRPCClientParseError` if the server response cannot be parsed.
+     * Note: It does not throw for any `JSONRPCErrorResponse`; in this case, it will be a single object: `{ status: 'rejected', reason: {...} }`
      *
-     * Usually it returns be like (same as the `Promise.allSettled()` method):
+     * The return value is similar to the `Promise.allSettled()` method:
      * ```js
      * [
      *    { status: 'fulfilled', value: '...' },
@@ -152,8 +155,9 @@ export class JSONRPCClient<
      *    },
      * ]
      * ```
-     * @throws `JSONRPCError` - when server return single JSONRPCErrorResponse
-     * @throws `JSONRPCClientParseError` - when server response cannot be parsed
+     * @throws `JSONRPCError` - when the server returns a single JSONRPCErrorResponse
+     * @throws `JSONRPCClientParseError` - when the server response cannot be parsed
+     * @see https://www.jsonrpc.org/specification#batch
      */
     public async batch(
         ...requests: Array<JSONRPCRequest | JSONRPCNotification>
@@ -244,13 +248,16 @@ export class JSONRPCClient<
     }
 }
 
+/**
+ * A union type representing any JSON-RPC request, either a notification or a request.
+ */
 type JSONRPCAnyRequest =
     | JSONRPCNotification
     | JSONRPCRequest
     | Array<JSONRPCNotification | JSONRPCRequest>
 
 /**
- * The client cannot parse the server response
+ * Indicates that the client cannot parse the server response.
  */
 export class JSONRPCClientParseError extends Error {
     override name = 'JSONRPCClientParseError'
@@ -262,7 +269,8 @@ export class JSONRPCClientParseError extends Error {
 }
 
 /**
- * Just wrap the JSON.parse function, with potential `JSONRPCClientParseError`
+ * Wraps JSON.parse to provide better error handling.
+ * Throws JSONRPCClientParseError if the response is not valid JSON.
  */
 function parseJSON(
     text: string,

src/client.ts

@@ -1,5 +1,9 @@
 import type { JSONRPCValue } from '../types.ts'
 
+/**
+ * @see https://www.jsonrpc.org/specification#error_object
+ * When a rpc call encounters an error, the Response Object MUST contain the error member with a value that is a Object with the following members:
+ */
 export interface JSONRPCErrorInterface {
     /**
      * A Number that indicates the error type that occurred.
@@ -19,6 +23,23 @@ export interface JSONRPCErrorInterface {
     data?: JSONRPCValue
 }
 
+/**
+ * To define your own JSON-RPC error, you can extend this class with your custom error code (in the range -32000 to -32099).
+ * @example
+ * ```ts
+ * // Reserved for implementation-defined server-errors.
+ * class MyCustomError extends JSONRPCError {
+ *   constructor(data?: JSONRPCValue) {
+ *     super({
+ *       code: -32001, // -32000 to -32099
+ *       message: 'Server error',
+ *       data: data,
+ *     })
+ *   }
+ * }
+ * ```
+ * @see https://www.jsonrpc.org/specification#error_object
+ */
 export class JSONRPCError extends Error implements JSONRPCErrorInterface {
     /**
      * 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
@@ -36,9 +57,9 @@ export class JSONRPCError extends Error implements JSONRPCErrorInterface {
 }
 
 /**
- * This function ONLY check that if `x` is `JSONRPCErrorInterface`
+ * This function ONLY checks whether `x` is a `JSONRPCErrorInterface`.
  *
- * Because it'a shared method between client and server, but `JSONRPCError` is server side only
+ * `JSONRPCErrorInterface` is shared between client and server, but `JSONRPCError` is server-side only.
  */
 export function isJSONRPCError(x: unknown): x is JSONRPCErrorInterface {
     if (!x || typeof x !== 'object') {
@@ -54,6 +75,11 @@ export function isJSONRPCError(x: unknown): x is JSONRPCErrorInterface {
     return false
 }
 
+/**
+ * Invalid JSON was received by the server.
+ * An error occurred on the server while parsing the JSON text.
+ * @see https://www.jsonrpc.org/specification#error_object
+ */
 export class JSONRPCParseError extends JSONRPCError {
     constructor(data?: JSONRPCValue) {
         super({
@@ -64,6 +90,10 @@ export class JSONRPCParseError extends JSONRPCError {
     }
 }
 
+/**
+ * The JSON sent is not a valid Request object.
+ * @see https://www.jsonrpc.org/specification#error_object
+ */
 export class JSONRPCInvalidRequestError extends JSONRPCError {
     constructor(data?: JSONRPCValue) {
         super({
@@ -74,6 +104,10 @@ export class JSONRPCInvalidRequestError extends JSONRPCError {
     }
 }
 
+/**
+ * The method does not exist / is not available.
+ * @see https://www.jsonrpc.org/specification#error_object
+ */
 export class JSONRPCMethodNotFoundError extends JSONRPCError {
     constructor(data?: JSONRPCValue) {
         super({
@@ -84,6 +118,10 @@ export class JSONRPCMethodNotFoundError extends JSONRPCError {
     }
 }
 
+/**
+ * Invalid method parameter(s).
+ * @see https://www.jsonrpc.org/specification#error_object
+ */
 export class JSONRPCInvalidParamsError extends JSONRPCError {
     constructor(data?: JSONRPCValue) {
         super({
@@ -94,6 +132,10 @@ export class JSONRPCInvalidParamsError extends JSONRPCError {
     }
 }
 
+/**
+ * Internal JSON-RPC error.
+ * @see https://www.jsonrpc.org/specification#error_object
+ */
 export class JSONRPCInternalError extends JSONRPCError {
     constructor(data?: JSONRPCValue) {
         super({

src/dto/errors.ts

@@ -2,9 +2,9 @@ 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.
+ * You should create this object using a method from `JSONRPCClient`, which generates the ID for you.
  *
- * It's less likely that you need to create this object manually.
+ * It is unlikely that you will need to create this object manually.
  */
 export class JSONRPCNotification {
     public jsonrpc = '2.0' as const
@@ -34,9 +34,10 @@ export class JSONRPCNotification {
 }
 
 /**
- * You should create this object via method from `JSONRPCClient`, it generate id for you.
+ * You should create this object using a method from `JSONRPCClient`, which generates the ID for you.
  *
- * It's less likely that you need to create this object manually.
+ * It is unlikely that you will need to create this object manually.
+ * @see https://www.jsonrpc.org/specification#request_object
  */
 export class JSONRPCRequest extends JSONRPCNotification {
     /**
@@ -60,9 +61,9 @@ export class JSONRPCRequest extends JSONRPCNotification {
 }
 
 /**
- * WARN: this check if `x` is `JSONRPCNotification` or `JSONRPCRequest`
+ * WARNING: This function checks if `x` is a `JSONRPCNotification` or a `JSONRPCRequest`.
  *
- * To check if `x` is `JSONRPCRequest`, ONLY need to check `'id' in x`
+ * To determine if `x` is a `JSONRPCRequest`, you ONLY need to check if `'id' in x`.
  */
 export function isJSONRPCRequest(
     x: unknown,

src/dto/request.ts

@@ -2,6 +2,9 @@ import type { JSONRPCValue, WithOptionalJSONRPCVersion } from '../types.ts'
 import { isJSONRPCID, type JSONRPCID } from '../id.ts'
 import { isJSONRPCError, type JSONRPCErrorInterface } from './errors.ts'
 
+/**
+ * @see https://www.jsonrpc.org/specification#response_object
+ */
 export class JSONRPCSuccessResponse {
     public jsonrpc = '2.0' as const
     public id: JSONRPCID
@@ -26,6 +29,9 @@ export class JSONRPCSuccessResponse {
     }
 }
 
+/**
+ * @see https://www.jsonrpc.org/specification#response_object
+ */
 export class JSONRPCErrorResponse {
     public jsonrpc = '2.0' as const
     /**
@@ -54,8 +60,14 @@ export class JSONRPCErrorResponse {
     }
 }
 
+/**
+ * @see https://www.jsonrpc.org/specification#response_object
+ */
 export type JSONRPCResponse = JSONRPCSuccessResponse | JSONRPCErrorResponse
 
+/**
+ * Checks whether the given value is a valid JSON-RPC 2.0 Response object.
+ */
 export function isJSONRPCResponse(x: unknown): x is JSONRPCResponse {
     if (!x || typeof x !== 'object') {
         return false

src/dto/response.ts

@@ -14,8 +14,8 @@ export function* selfAddIdGenerator(): Generator<number, void, unknown> {
 }
 
 /**
- * This can be but not mean to javascript Generator
- * Just means a source of ID
+ * This does not necessarily refer to a JavaScript Generator;
+ * it simply represents any source of IDs.
  */
 export type IDGenerator = Iterator<JSONRPCID> | (() => JSONRPCID)