chore: replace hardcoded error codes with rpc error constants

[lwin-kyaw]

Motivation and Context

The JRPC layer had several issues: loosely-typed interfaces allowed invalid param shapes to pass through without compile-time checks, error serialization could silently drop the original error message, hardcoded error codes were scattered across the codebase, and engine streams did not clean up event listeners on close—causing potential memory leaks.

Jira Link: https://consensyssoftware.atlassian.net/browse/W3APD-5273?atlOrigin=eyJpIjoiOWMxNTliMjI3ZGFjNGRmZjk0MTcyZDkzMjAwODAxZDMiLCJwIjoiaiJ9

Description

Type Safety Improvements

• Introduced JRPCParams type (Json[] | Record<string, Json>) and constrained all generic parameters on JRPCRequest, JRPCMiddleware, AsyncJRPCMiddleware, and ExtendedJsonRpcRequest to extend JRPCParams, enforcing JSON-RPC-compliant param shapes at compile time.
• Added a new JRPCNotification interface to properly distinguish notifications (no id) from requests.
• Added default type parameters so that callers not specifying explicit generics are unaffected.

New Utility Functions

• Added type guards: isJRPCNotification, isJRPCRequest, isJRPCSuccess, isJRPCFailure, isValidMethod.
• Added general-purpose helpers: isObject, hasProperty, isValidNumber.
• Moved isObject from jrpc/errors/utils.ts to utils/utils.ts for broader reuse.

Error Handling Improvements

• Replaced hardcoded error code integers with errorCodes.rpc.* constants throughout.
• Added shouldPreserveMessage option to serializeJrpcError (defaults to true) so original error messages are preserved in the serialized output instead of being replaced by the fallback.
• Improved error messages in JRPCEngine._handle to include the actual received type (e.g., "Must specify a string method. Received: undefined").
• Fixed constructFallbackError to validate code with isValidNumber instead of blindly parsing, avoiding NaN codes.

Engine & Stream Fixes

• Added empty batch request handling in _handleBatch—returns an invalidRequest error instead of silently returning an empty array.
• Added cleanup of the notification event listener when the engine stream is closed, preventing memory leaks.
• Replaced inline !res.id notification check with the isJRPCNotification type guard.

How has this been tested?

• Added 264-line jrpcEngine.test.ts covering: single request handling, batch requests (including empty batch), error propagation, async middleware, asMiddleware(), mergeMiddleware, and engine stream creation/cleanup.
• Added 239-line jrpcMiddleware.test.ts covering: createErrorMiddleware, createStreamMiddleware, createScaffoldMiddleware, createIdRemapMiddleware, createLoggerMiddleware, and createAsyncMiddleware.
• Extended jrpcUtils.test.ts with 106 new lines covering: isJRPCNotification, isJRPCRequest, isValidMethod, isJRPCSuccess, isJRPCFailure, isValidNumber, isObject, and hasProperty.

Screenshots (if appropriate):

N/A

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)

Checklist:

• My code follows the code style of this project. (run lint)
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have added tests to cover my changes.
• All new and existing tests passed.
• My code requires a db migration.

---

Note

Medium Risk
Touches core JSON-RPC engine/middleware and error serialization behavior, which can subtly change error messages/codes and batch/notification handling. Risk is mitigated by extensive new tests covering the updated edge cases.

Overview
Standardizes the JRPC layer around shared errorCodes.rpc.* constants and stronger runtime validation, including improved request validation errors and safer fallback error construction (avoids NaN codes).

Tightens typings by introducing JRPCParams and JRPCNotification, constraining middleware/request generics, and adding src/utils/jrpc.ts type guards (isJRPCNotification, isJRPCRequest, isJRPCSuccess/isJRPCFailure, isValidMethod) used throughout the engine/stream middleware.

Improves error serialization to optionally preserve original error messages (shouldPreserveMessage, default on) while still attaching a JSON-safe data.cause, handles empty batch requests as invalidRequest, and fixes an engine stream notification listener leak by removing the listener on stream close. Adds new Vitest coverage for engine behavior, middleware helpers, and the new guards.

^{Written by Cursor Bugbot for commit 3bef878. This will update automatically on new commits. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.