feat: deprecate JRPC V1

src/jrpc/basePostMessageStream.ts

@@ -23,6 +23,9 @@ export interface PostMessageEvent {
   source: typeof window;
 }
 
+/**
+ * @deprecated Part of the JRPC V1 stream API. Use {@link createEngineStreamV2} instead.
+ */
 export function isValidStreamMessage(message: unknown): message is StreamMessage {
   return (
     typeof message === "object" &&
@@ -34,6 +37,9 @@ export function isValidStreamMessage(message: unknown): message is StreamMessage
   );
 }
 
+/**
+ * @deprecated Part of the JRPC V1 stream API. Use {@link createEngineStreamV2} instead.
+ */
 export abstract class BasePostMessageStream extends Duplex {
   private _init: boolean;
 

src/jrpc/index.ts

@@ -1,3 +1,11 @@
+// ──────────────────────────────────────────────────────────────────────────────
+// JRPC V1 exports — DEPRECATED
+//
+// The V1 engine, middleware types, and stream utilities below are deprecated.
+// Migrate to the JRPC V2 API exported from "./v2" (e.g. JRPCEngineV2,
+// JRPCMiddlewareV2, createEngineStreamV2, providerFromEngineV2, etc.).
+// ──────────────────────────────────────────────────────────────────────────────
+
 export type { PostMessageEvent, StreamData, StreamMessage } from "./basePostMessageStream";
 export { BasePostMessageStream, isValidStreamMessage } from "./basePostMessageStream";
 export * from "./errors";
@@ -13,6 +21,6 @@ export type { SubstreamOptions } from "./substream";
 export { Substream } from "./substream";
 
 /**
- * Export the v2 module.
+ * JRPC V2 API — preferred.
  */
 export * from "./v2";

src/jrpc/interfaces.ts

@@ -31,28 +31,50 @@ export interface JRPCRequest<Params extends JRPCParams = JRPCParams> extends JRP
   params?: Params;
 }
 
+/**
+ * @deprecated Part of the JRPC V1 middleware signature. Use {@link JRPCMiddlewareV2} instead.
+ */
 export type JRPCEngineNextCallback = (cb?: (done: (error?: Error) => void) => void) => void;
+/**
+ * @deprecated Part of the JRPC V1 middleware signature. Use {@link JRPCMiddlewareV2} instead.
+ */
 export type JRPCEngineEndCallback = (error?: Error) => void;
+/**
+ * @deprecated Part of the JRPC V1 middleware signature. Use {@link JRPCMiddlewareV2} instead.
+ */
 export type JRPCEngineReturnHandler = (done: (error?: Error) => void) => void;
 
+/**
+ * @deprecated Part of the JRPC V1 stream middleware. Use {@link createEngineStreamV2} instead.
+ */
 interface IdMapValue {
   req: JRPCRequest<JRPCParams>;
   res: JRPCResponse<unknown>;
   next: JRPCEngineNextCallback;
   end: JRPCEngineEndCallback;
 }
 
+/**
+ * @deprecated Part of the JRPC V1 stream middleware. Use {@link createEngineStreamV2} instead.
+ */
 export interface IdMap {
   [requestId: string]: IdMapValue;
 }
 
+/**
+ * @deprecated Use {@link JRPCMiddlewareV2} instead. V2 middleware receives a single
+ * params object `{ request, context, next }` and returns the result directly.
+ */
 export type JRPCMiddleware<T extends JRPCParams = JRPCParams, U = unknown> = (
   req: JRPCRequest<T>,
   res: JRPCResponse<U>,
   next: JRPCEngineNextCallback,
   end: JRPCEngineEndCallback
 ) => void;
 
+/**
+ * @deprecated Use {@link JRPCMiddlewareV2} instead — V2 middleware is async by default.
+ */
 export type AsyncJRPCEngineNextCallback = () => Promise<void>;
 
 export type Maybe<T> = T | Partial<T> | null | undefined;
@@ -93,6 +115,9 @@ export interface JRPCError {
   stack?: string;
 }
 
+/**
+ * @deprecated Part of the JRPC V1 API. V2 middleware returns results directly.
+ */
 export interface PendingJRPCResponse<T> extends JRPCBase {
   result?: T;
   error?: Error | JRPCError;
@@ -102,29 +127,47 @@ export interface JRPCFailure extends JRPCBase {
   error: JRPCError;
 }
 
+/**
+ * @deprecated Use {@link JRPCMiddlewareV2} instead — V2 middleware is async by default.
+ */
 export type AsyncJRPCMiddleware<T extends JRPCParams, U> = (
   req: JRPCRequest<T>,
   res: PendingJRPCResponse<U>,
   next: AsyncJRPCEngineNextCallback
 ) => Promise<void>;
 
+/**
+ * @deprecated Part of the JRPC V1 middleware signature. Use {@link JRPCMiddlewareV2} instead.
+ */
 export type ReturnHandlerCallback = (error: null | Error) => void;
 
 export type BlockData = string | string[];
 
 export type Block = Record<string, BlockData>;
 
+/**
+ * @deprecated Part of the JRPC V1 provider API. Use {@link providerFromEngineV2} instead.
+ */
 export type SendAsyncCallBack = (err: Error, providerRes: JRPCResponse<Block>) => void;
 
+/**
+ * @deprecated Part of the JRPC V1 provider API. Use {@link providerFromEngineV2} instead.
+ */
 export type SendCallBack<U> = (err: any, providerRes: U) => void;
 
+/**
+ * @deprecated Part of the JRPC V1 API.
+ */
 export type Payload = Partial<JRPCRequest<string[]>>;
 
 export interface RequestArguments<T> {
   method: string;
   params?: T;
 }
 
+/**
+ * @deprecated Part of the JRPC V1 API.
+ */
 export interface ExtendedJsonRpcRequest<T extends JRPCParams> extends JRPCRequest<T> {
   skipCache?: boolean;
 }

src/jrpc/jrpc.ts

@@ -17,6 +17,10 @@ import {
 import { SafeEventEmitter } from "./safeEventEmitter";
 import { SerializableError } from "./serializableError";
 
+/**
+ * @deprecated Part of the JRPC V1 API. Use {@link JRPCEngineV2} which returns
+ * results directly from `handle()` without requiring callbacks.
+ */
 export const getRpcPromiseCallback =
   (resolve: (value?: unknown) => void, reject: (error?: Error) => void, unwrapResult = true) =>
   (error: Error, response: JRPCResponse<unknown>): void => {
@@ -29,6 +33,10 @@ export const getRpcPromiseCallback =
     }
   };
 
+/**
+ * @deprecated Part of the JRPC V1 API. The V2 engine handles errors internally
+ * via {@link JRPCEngineV2}.
+ */
 export function createErrorMiddleware(log: ConsoleLike): JRPCMiddleware<JRPCParams, unknown> {
   return (req, res, next, end) => {
     try {
@@ -54,10 +62,16 @@ export function createErrorMiddleware(log: ConsoleLike): JRPCMiddleware<JRPCPara
   };
 }
 
+/**
+ * @deprecated Part of the JRPC V1 API. Use {@link createEngineStreamV2} instead.
+ */
 export type StreamEvents = {
   notification: (arg1: JRPCNotification) => boolean;
 };
 
+/**
+ * @deprecated Part of the JRPC V1 API. Use {@link createEngineStreamV2} instead.
+ */
 export function createStreamMiddleware(): {
   events: SafeEventEmitter<StreamEvents>;
   middleware: JRPCMiddleware<JRPCParams, unknown>;
@@ -121,8 +135,14 @@ export function createStreamMiddleware(): {
   return { events, middleware, stream };
 }
 
+/**
+ * @deprecated Use {@link createScaffoldMiddlewareV2} and its handler type instead.
+ */
 export type ScaffoldMiddlewareHandler<T extends JRPCParams, U> = JRPCMiddleware<T, U> | Json;
 
+/**
+ * @deprecated Use {@link createScaffoldMiddlewareV2} instead.
+ */
 export function createScaffoldMiddleware(handlers: {
   [methodName: string]: ScaffoldMiddlewareHandler<JRPCParams, unknown>;
 }): JRPCMiddleware<JRPCParams, unknown> {
@@ -142,6 +162,9 @@ export function createScaffoldMiddleware(handlers: {
   };
 }
 
+/**
+ * @deprecated Part of the JRPC V1 API. The V2 engine does not require ID remapping.
+ */
 export function createIdRemapMiddleware(): JRPCMiddleware<JRPCParams, unknown> {
   return (req, res, next, _end) => {
     const originalId = req.id;
@@ -156,13 +179,19 @@ export function createIdRemapMiddleware(): JRPCMiddleware<JRPCParams, unknown> {
   };
 }
 
+/**
+ * @deprecated Part of the JRPC V1 API. Write a {@link JRPCMiddlewareV2} instead.
+ */
 export function createLoggerMiddleware(logger: ConsoleLike): JRPCMiddleware<JRPCParams, unknown> {
   return (req, res, next, _) => {
     logger.debug("REQ", req, "RES", res);
     next();
   };
 }
 
+/**
+ * @deprecated Use {@link JRPCMiddlewareV2} directly — V2 middleware is async by default.
+ */
 export function createAsyncMiddleware<T extends JRPCParams, U>(asyncMiddleware: AsyncJRPCMiddleware<T, U>): JRPCMiddleware<T, U> {
   return async (req, res, next, end) => {
     // nextPromise is the key to the implementation