jsonrpc-client-websocket 1.5.4 → 1.6.0

package/README.md

@@ -1,4 +1,4 @@
-[![📦 Build](https://github.com/fabriciobastian/jsonrpc-client-websocket/actions/workflows/build.yml/badge.svg)](https://github.com/fabriciobastian/jsonrpc-client-websocket/actions/workflows/build.yml) [![License](https://img.shields.io/github/license/fabriciobastian/jsonrpc-client-websocket)](https://choosealicense.com/licenses/mit/) [![NPM downloads](https://img.shields.io/npm/dt/jsonrpc-client-websocket.svg)](https://www.npmjs.com/package/jsonrpc-client-websocket)
+[![✅ Continuous Integration](https://github.com/fabriciobastian/jsonrpc-client-websocket/actions/workflows/ci.yml/badge.svg)](https://github.com/fabriciobastian/jsonrpc-client-websocket/actions/workflows/ci.yml) [![License](https://img.shields.io/github/license/fabriciobastian/jsonrpc-client-websocket)](https://choosealicense.com/licenses/mit/) [![NPM downloads](https://img.shields.io/npm/dt/jsonrpc-client-websocket.svg)](https://www.npmjs.com/package/jsonrpc-client-websocket)
 
 ![jsonrpc-client-websocket](https://raw.githubusercontent.com/fabriciobastian/jsonrpc-client-websocket/main/assets/jsonrpc-client-websocket-banner-light-small.png)
 
@@ -74,33 +74,66 @@ The defined RPC methods can also be called with both positional and named parame
 
 ### Minification/Obfuscation
 
-When using code minification/obfuscation the parameter names may change, which can
-cause calls using named parameters to fail. To mitigate this you can do one or a
-combination of the following:
-- do not minify/obfuscate the code where `on` is used, so the function registration does not get modified
-- use positional parameters
-- register functions as following:
+For code that will be minified or obfuscated, pass the public parameter names as
+the optional third argument to `on`:
 
 ```typescript
-websocket.on('sum', (params: { a: number; b: number }) => {
-  return params.a + params.b;
-});
+websocket.on('subtract', (x: number, y: number) => x - y, ['a', 'b']);
 ```
 
-and then call the function using positional parameters using the object:
+The list follows the callback's argument order: `a` maps to `x`, and `b` maps to `y`.
+The order of keys in the request object does not matter:
 
 ```typescript
-websocket.call('sum', [{ a: 1, b: 2 }])
+websocket.call('subtract', { b: 2, a: 5 })
   .then((response) => {
-    // handle response
+    // response.result is 3
   })
   .catch((error) => {
     // handle error
   });
 ```
 
+Positional calls such as `websocket.call('subtract', [5, 2])` also work. The explicit
+list defines both the parameter order and the required argument count, even if
+minification renames or removes unused callback parameters. Names must be unique;
+use an empty list for a method that takes no arguments. The list is copied when
+the method is registered.
+
+Without the third argument, existing registrations continue to infer named
+parameters from the callback's source. Those names may change during minification
+or obfuscation, so use explicit names for named calls in production bundles.
+If property mangling is enabled, preserve the public keys in request objects too.
+
 ## Remove RPC method
 
 ```typescript
 websocket.off('sum');
 ```
+
+## Development
+
+Use the Node.js version in `.nvmrc` and its bundled npm, then run:
+
+```sh
+npm ci
+npm test
+npm run lint
+npm run format:check
+npm run build
+```
+
+TypeScript checks both the library and tests. ESLint uses native flat configuration
+with TypeScript and Jest rules. TypeScript stays on the latest 6.0 patch supported
+by `typescript-eslint`; upgrading to TypeScript 7 requires its official support.
+Tests live alongside the source and are excluded from build output.
+`npm run update-all` respects peer dependency requirements when selecting updates.
+
+These tooling requirements apply to development only. The published library still
+targets ES2020 and has no runtime dependencies.
+
+## Publishing
+
+Releases are staged through GitHub Actions using
+[npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) (OIDC).
+A maintainer approves each staged package on npm before it becomes publicly available.

package/lib/get-parameter-names.d.ts

@@ -0,0 +1 @@
+export declare function getParameterNames(callback: (...args: never[]) => unknown): string[];

package/lib/get-parameter-names.js

@@ -0,0 +1,5 @@
+export function getParameterNames(callback) {
+    const source = Function.prototype.toString.call(callback).replace(/\/\*[\s\S]*?\*\/|\/\/.*$/gm, ' ');
+    const parameters = source.match(/^(?:async\s+)?([^\s()=]+)\s*=>/)?.[1] ?? source.slice(source.indexOf('(') + 1, source.indexOf(')'));
+    return parameters.replace(/=[^,]+/g, '').match(/[^\s,]+/g) ?? [];
+}

package/lib/jsonrpc-websocket.d.ts

@@ -17,10 +17,14 @@ export declare class JsonRpcWebsocket {
     private pendingRequests;
     private rpcMethods;
     get state(): WebsocketReadyStates;
-    constructor(url: string, requestTimeoutMs: number, onError?: ErrorCallback);
+    constructor(url: string, requestTimeoutMs: number, onError?: ErrorCallback | undefined);
     open(): Promise<Event>;
     close(): Promise<CloseEvent>;
-    on(methodName: string, callback: (...args: any[]) => any): void;
+    /**
+     * Registers a callback, optionally declaring its public parameter names in argument order.
+     * Explicit names also determine the expected argument count, independently of the callback's signature.
+     */
+    on(methodName: string, callback: (...args: any[]) => any, parameterNames?: readonly string[]): void;
     off(methodName: string): void;
     call(method: string, params?: unknown): Promise<JsonRpcResponse>;
     notify(method: string, params?: unknown): void;
@@ -38,4 +42,5 @@ export declare class JsonRpcWebsocket {
     private callOnError;
     private getRequestId;
     private hasProperty;
+    private getErrorMessage;
 }

package/lib/jsonrpc-websocket.js

@@ -1,4 +1,4 @@
-import * as getParameterNames from 'get-parameter-names';
+import { getParameterNames } from './get-parameter-names';
 import { DeferredPromise } from './deferred-promise';
 import { JsonRpcErrorCodes } from './jsonrpc.model';
 export var WebsocketReadyStates;
@@ -35,9 +35,20 @@ export class JsonRpcWebsocket {
         this.websocket = undefined;
         return this.closeDeferredPromise.asPromise();
     }
+    /**
+     * Registers a callback, optionally declaring its public parameter names in argument order.
+     * Explicit names also determine the expected argument count, independently of the callback's signature.
+     */
+    on(methodName, 
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    on(methodName, callback) {
-        this.rpcMethods[methodName.toLowerCase()] = callback; // case-insensitive!
+    callback, parameterNames) {
+        if (parameterNames && new Set(parameterNames).size !== parameterNames.length) {
+            throw new Error('Parameter names must be unique');
+        }
+        this.rpcMethods[methodName.toLowerCase()] = {
+            callback,
+            parameterNames: parameterNames?.slice(),
+        }; // case-insensitive!
     }
     off(methodName) {
         delete this.rpcMethods[methodName.toLowerCase()]; // case-insensitive!
@@ -57,7 +68,10 @@ export class JsonRpcWebsocket {
         }
         catch (e) {
             // istanbul ignore next
-            return Promise.reject({ code: JsonRpcErrorCodes.INTERNAL_ERROR, message: `Internal error. ${e}` });
+            return Promise.reject({
+                code: JsonRpcErrorCodes.INTERNAL_ERROR,
+                message: `Internal error. ${this.getErrorMessage(e)}`,
+            });
         }
         return this.createPendingRequest(request);
     }
@@ -74,8 +88,7 @@ export class JsonRpcWebsocket {
             this.websocket.send(JSON.stringify(request));
         }
         catch (e) {
-            // istanbul ignore next
-            throw Error(e);
+            throw Error(this.getErrorMessage(e), { cause: e });
         }
     }
     createWebsocket() {
@@ -131,12 +144,11 @@ export class JsonRpcWebsocket {
             this.websocket.send(JSON.stringify(response));
         }
         catch (e) {
-            // istanbul ignore next
-            throw Error(e);
+            throw Error(this.getErrorMessage(e), { cause: e });
         }
     }
     handleMessage(msg) {
-        let data = null;
+        let data;
         try {
             data = JSON.parse(msg);
         }
@@ -167,52 +179,53 @@ export class JsonRpcWebsocket {
             this.handleError(JsonRpcErrorCodes.METHOD_NOT_FOUND, `Method '${request.method}' was not found`, request.id);
             return;
         }
-        let requestParams = [];
+        let requestParams;
         try {
             requestParams = this.getRequestParams(method, request);
         }
         catch (error) {
-            this.handleError(JsonRpcErrorCodes.INVALID_PARAMS, error.message, request.id);
+            this.handleError(JsonRpcErrorCodes.INVALID_PARAMS, this.getErrorMessage(error), request.id);
             return;
         }
         try {
-            const result = method(...requestParams);
+            const { callback } = method;
+            const result = callback(...requestParams);
             if (request.id) {
                 this.respondOk(request.id, result);
             }
         }
         catch (error) {
-            this.handleError(JsonRpcErrorCodes.REQUEST_FAILED, `Method '${request.method}' has thrown: '${error.message}'`, request.id);
+            this.handleError(JsonRpcErrorCodes.REQUEST_FAILED, `Method '${request.method}' has thrown: '${this.getErrorMessage(error)}'`, request.id);
         }
     }
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     getRequestParams(method, request) {
-        let requestParams = [];
-        if (request.params) {
-            if (request.params instanceof Array) {
-                if (method.length !== request.params.length) {
-                    throw new Error(`Invalid parameters. Method '${request.method}' expects ${method.length} parameters, but got ${request.params.length}`);
-                }
-                requestParams = request.params;
-            }
-            else if (request.params instanceof Object) {
-                const parameterNames = getParameterNames(method);
-                if (method.length !== Object.keys(request.params).length) {
-                    throw new Error(`Invalid parameters. Method '${request.method}' expects parameters [${parameterNames}], but got [${Object.keys(request.params)}]`);
-                }
-                parameterNames.forEach((paramName) => {
-                    const paramValue = request.params[paramName];
-                    if (paramValue === undefined) {
-                        throw new Error(`Invalid parameters. Method '${request.method}' expects parameters [${parameterNames}], but got [${Object.keys(request.params)}]`);
-                    }
-                    requestParams.push(paramValue);
-                });
+        if (!request.params && method.parameterNames === undefined) {
+            return [];
+        }
+        const params = request.params === undefined ? [] : request.params;
+        const parameterCount = method.parameterNames?.length ?? method.callback.length;
+        if (params instanceof Array) {
+            if (parameterCount !== params.length) {
+                throw new Error(`Invalid parameters. Method '${request.method}' expects ${parameterCount} parameters, but got ${params.length}`);
             }
-            else {
-                throw new Error(`Invalid parameters. Expected array or object, but got ${typeof request.params}`);
+            return params;
+        }
+        if (params instanceof Object) {
+            const parameterNames = method.parameterNames ?? getParameterNames(method.callback);
+            const requestParameterNames = Object.keys(params);
+            const invalidParametersMessage = `Invalid parameters. Method '${request.method}' expects parameters [${parameterNames}], but got [${requestParameterNames}]`;
+            if (parameterCount !== requestParameterNames.length) {
+                throw new Error(invalidParametersMessage);
             }
+            return parameterNames.map((paramName) => {
+                if (!this.hasProperty(params, paramName)) {
+                    throw new Error(invalidParametersMessage);
+                }
+                return params[paramName];
+            });
         }
-        return requestParams;
+        throw new Error(`Invalid parameters. Expected array or object, but got ${typeof params}`);
     }
     handleResponse(response) {
         const activeRequest = this.pendingRequests[response.id];
@@ -289,4 +302,23 @@ export class JsonRpcWebsocket {
     hasProperty(object, propertyName) {
         return !!Object.prototype.hasOwnProperty.call(object, propertyName);
     }
+    getErrorMessage(error) {
+        try {
+            if (typeof error === 'object' && error !== null && 'message' in error) {
+                const message = error.message;
+                if (typeof message === 'string') {
+                    return message;
+                }
+            }
+            return JSON.stringify(error) ?? String(error);
+        }
+        catch {
+            try {
+                return String(error);
+            }
+            catch {
+                return 'Unknown error';
+            }
+        }
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsonrpc-client-websocket",
-  "version": "1.5.4",
+  "version": "1.6.0",
   "description": "A simple JSON RPC 2.0 websocket client",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -8,17 +8,18 @@
     "lib/**/*"
   ],
   "scripts": {
-    "test": "jest",
-    "coverage": "jest --config jest.config.ts --coverage",
+    "test": "tsc --project tsconfig.spec.json && jest",
+    "coverage": "npm test -- --coverage",
     "build": "tsc",
     "format": "prettier --write \"src/**/*.ts\"",
-    "lint": "tsc --noEmit && eslint . --ext .js,.jsx,.ts,.tsx --fix",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "lint": "tsc --noEmit && eslint .",
     "prepublishOnly": "npm test && npm run lint",
     "prepare": "npm run build",
     "preversion": "npm run lint",
     "version": "npm run format && git add -A src",
     "postversion": "git push && git push --tags",
-    "updateAll": "npm-check-updates --upgrade"
+    "update-all": "npm-check-updates --upgrade --peer"
   },
   "repository": {
     "type": "git",
@@ -38,23 +39,19 @@
   "author": "Fabricio Bastian",
   "license": "MIT",
   "devDependencies": {
-    "@types/jest": "^29.5.1",
-    "@typescript-eslint/eslint-plugin": "^5.59.2",
-    "@typescript-eslint/parser": "^5.59.2",
-    "eslint": "^8.39.0",
-    "eslint-config-prettier": "^8.8.0",
-    "eslint-plugin-jest": "^27.2.1",
-    "jest": "^29.5.0",
-    "jest-environment-jsdom": "^29.5.0",
-    "jest-websocket-mock": "^2.4.0",
-    "mock-socket": "^9.2.1",
-    "npm-check-updates": "^16.10.9",
-    "prettier": "^2.8.8",
-    "ts-jest": "^29.1.0",
-    "ts-node": "^10.9.1",
-    "typescript": "^5.0.4"
-  },
-  "dependencies": {
-    "get-parameter-names": "^0.3.0"
+    "@eslint/js": "^10.0.1",
+    "@types/jest": "^30.0.0",
+    "eslint": "^10.14.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-jest": "^29.17.0",
+    "jest": "^30.5.2",
+    "jest-environment-jsdom": "^30.5.2",
+    "jest-websocket-mock": "^2.5.0",
+    "mock-socket": "^9.3.1",
+    "npm-check-updates": "^23.1.1",
+    "prettier": "^3.9.10",
+    "ts-jest": "^29.4.15",
+    "typescript": "~6.0.3",
+    "typescript-eslint": "^8.72.1"
   }
 }