refactor(devframe): inline per-call channel options into ws transports

Removes `makePerCallChannelOptions` from `rpc/serialization.ts` and
inlines the wire dispatch logic directly into `ws-server.ts` and
`ws-client.ts`. The helper had only two callers and the abstraction
wasn't pulling its weight — a single function name shouldn't need a
factory builder.

`STRUCTURED_CLONE_PREFIX`, `strictJsonStringify`, and the
`structuredClone*` re-exports remain — they're the actual reusable
primitives. The unit tests targeting `makePerCallChannelOptions`
are dropped; the dispatch behavior is now exercised end-to-end via
the existing static-rpc and static-dump tests.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: antfu

devframe/packages/devframe/src/rpc/serialization.test.ts

@@ -1,9 +1,5 @@
 import { describe, expect, it, vi } from 'vitest'
-import {
-  makePerCallChannelOptions,
-  strictJsonStringify,
-  STRUCTURED_CLONE_PREFIX,
-} from './serialization'
+import { strictJsonStringify } from './serialization'
 
 describe('strictJsonStringify', () => {
   it('matches JSON.stringify for plain JSON values', () => {
@@ -87,66 +83,3 @@ describe('strictJsonStringify', () => {
     expect(replacerCalls).toEqual(['', 'a', 'b', 'c', '0', '1'])
   })
 })
-
-describe('makePerCallChannelOptions', () => {
-  function makeChannel(jsonMethods: string[]) {
-    const defs = new Map(
-      jsonMethods.map(name => [name, { jsonSerializable: true as const }]),
-    )
-    return makePerCallChannelOptions(defs)
-  }
-
-  it('encodes JSON-flagged requests without a prefix', () => {
-    const ch = makeChannel(['fn'])
-    const wire = ch.serialize!({ t: 'q', i: '1', m: 'fn', a: [1, 2] })
-    expect(wire).toBe('{"t":"q","i":"1","m":"fn","a":[1,2]}')
-    expect(wire.startsWith('s:')).toBe(false)
-  })
-
-  it('encodes structured-clone requests with the s: prefix', () => {
-    const ch = makeChannel([])
-    const wire = ch.serialize!({ t: 'q', i: '1', m: 'fn', a: [new Map([['k', 1]])] })
-    expect(typeof wire).toBe('string')
-    expect((wire as string).startsWith(STRUCTURED_CLONE_PREFIX)).toBe(true)
-  })
-
-  it('decodes per the wire prefix without consulting defs', () => {
-    const ch = makeChannel([]) // no defs at all on this channel
-    // JSON-encoded request — no prefix.
-    const json = ch.deserialize!('{"t":"q","i":"1","m":"fn","a":[1]}')
-    expect(json).toEqual({ t: 'q', i: '1', m: 'fn', a: [1] })
-
-    // SC-encoded message: produce a real SC wire string from a sender
-    // that doesn't know `fn` (so it falls through to SC), then route
-    // that string through this channel's deserialize. Map round-trips.
-    const sender = makeChannel([])
-    const wire = sender.serialize!({ t: 'q', i: '2', m: 'fn', a: [new Map([['k', 1]])] }) as string
-    expect(wire.startsWith(STRUCTURED_CLONE_PREFIX)).toBe(true)
-    const decoded = ch.deserialize!(wire) as { t: 'q', a: [Map<string, number>] }
-    expect(decoded.a[0]).toBeInstanceOf(Map)
-    expect(decoded.a[0].get('k')).toBe(1)
-  })
-
-  it('mirrors the originating method to dispatch the response encoding', () => {
-    const ch = makeChannel(['fn'])
-    // Receive a request → record method
-    ch.deserialize!('{"t":"q","i":"abc","m":"fn","a":[]}')
-    // Send the response → uses JSON because fn is jsonSerializable: true
-    const wire = ch.serialize!({ t: 's', i: 'abc', r: { ok: 1 } }) as string
-    expect(wire.startsWith(STRUCTURED_CLONE_PREFIX)).toBe(false)
-    expect(JSON.parse(wire)).toEqual({ t: 's', i: 'abc', r: { ok: 1 } })
-  })
-
-  it('falls back to structured-clone for unknown methods', () => {
-    const ch = makeChannel(['known'])
-    const wire = ch.serialize!({ t: 'q', i: '1', m: 'unknown', a: [] }) as string
-    expect(wire.startsWith(STRUCTURED_CLONE_PREFIX)).toBe(true)
-  })
-
-  it('throws DF0019 when a JSON-flagged request carries non-JSON args', () => {
-    const ch = makeChannel(['fn'])
-    expect(() =>
-      ch.serialize!({ t: 'q', i: '1', m: 'fn', a: [new Map()] }),
-    ).toThrowError(/jsonSerializable: true/)
-  })
-})

devframe/packages/devframe/src/rpc/serialization.ts

@@ -1,4 +1,3 @@
-import type { ChannelOptions } from 'birpc'
 import {
   deserialize as structuredCloneDeserialize,
   parse as structuredCloneParse,
@@ -27,74 +26,6 @@ export { structuredCloneDeserialize, structuredCloneParse, structuredCloneString
  */
 export const STRUCTURED_CLONE_PREFIX = 's:'
 
-interface BirpcRequest {
-  t: 'q'
-  i?: string
-  m: string
-  a: unknown[]
-  o?: boolean
-}
-
-interface BirpcResponse {
-  t: 's'
-  i: string
-  r?: unknown
-  e?: unknown
-}
-
-type BirpcMessage = BirpcRequest | BirpcResponse
-
-function isJsonMethod(
-  defs: ReadonlyMap<string, { jsonSerializable?: boolean }>,
-  name: string | undefined,
-): boolean {
-  return !!name && defs.get(name)?.jsonSerializable === true
-}
-
-/**
- * Build a per-call `serialize`/`deserialize` pair for birpc channels.
- *
- * The returned options switch encoder per-message based on the
- * `jsonSerializable` flag of the dispatched function. Outgoing requests
- * read the method from `msg.m`; outgoing responses look the method back
- * up from a per-channel `pendingRequestMethods` map populated whenever
- * a request is observed in `deserialize`.
- *
- * Pass an empty/partial `defs` map on peers that don't have the full
- * registry — encoding falls back to structured-clone (the safer
- * superset), and decoding still routes correctly via the wire prefix.
- */
-export function makePerCallChannelOptions(
-  defs: ReadonlyMap<string, { jsonSerializable?: boolean }>,
-): Pick<ChannelOptions, 'serialize' | 'deserialize'> {
-  const pendingRequestMethods = new Map<string, string>()
-
-  return {
-    serialize(msg: BirpcMessage): string {
-      let method: string | undefined
-      if (msg.t === 'q') {
-        method = msg.m
-      }
-      else {
-        method = pendingRequestMethods.get(msg.i)
-        pendingRequestMethods.delete(msg.i)
-      }
-      const useJson = isJsonMethod(defs, method)
-      if (useJson)
-        return strictJsonStringify(msg, method ?? '')
-      return `${STRUCTURED_CLONE_PREFIX}${structuredCloneStringify(msg)}`
-    },
-    deserialize(raw: string): BirpcMessage {
-      const msg: BirpcMessage = raw.startsWith(STRUCTURED_CLONE_PREFIX)
-        ? (structuredCloneParse(raw.slice(STRUCTURED_CLONE_PREFIX.length)) as BirpcMessage)
-        : (JSON.parse(raw) as BirpcMessage)
-      if (msg.t === 'q' && msg.i && msg.m)
-        pendingRequestMethods.set(msg.i, msg.m)
-      return msg
-    },
-  }
-}
-
 /**
  * `JSON.stringify` with a single-pass strict replacer.
  *

devframe/packages/devframe/src/rpc/transports/ws-client.ts

@@ -1,6 +1,11 @@
 import type { ChannelOptions } from 'birpc'
 import type { RpcFunctionDefinitionAny } from '../types'
-import { makePerCallChannelOptions } from '../serialization'
+import {
+  strictJsonStringify,
+  STRUCTURED_CLONE_PREFIX,
+  structuredCloneParse,
+  structuredCloneStringify,
+} from '../serialization'
 
 export interface WsRpcChannelOptions {
   url: string
@@ -52,7 +57,10 @@ export function createWsRpcChannel(options: WsRpcChannelOptions): ChannelOptions
     onDisconnected(e)
   })
 
-  const perCall = makePerCallChannelOptions(definitions)
+  // Per-channel state: maps an incoming request id to its method name
+  // so the matching outgoing response can independently look the
+  // method up in `definitions` and pick the right encoder.
+  const pendingRequestMethods = new Map<string, string>()
   return {
     on: (handler: (data: string) => void) => {
       ws.addEventListener('message', (e) => {
@@ -71,7 +79,27 @@ export function createWsRpcChannel(options: WsRpcChannelOptions): ChannelOptions
         ws.addEventListener('open', handler)
       }
     },
-    serialize: perCall.serialize,
-    deserialize: perCall.deserialize,
+    serialize: (msg: any): string => {
+      let method: string | undefined
+      if (msg.t === 'q') {
+        method = msg.m
+      }
+      else {
+        method = pendingRequestMethods.get(msg.i)
+        pendingRequestMethods.delete(msg.i)
+      }
+      const useJson = !!method && definitions.get(method)?.jsonSerializable === true
+      if (useJson)
+        return strictJsonStringify(msg, method ?? '')
+      return `${STRUCTURED_CLONE_PREFIX}${structuredCloneStringify(msg)}`
+    },
+    deserialize: (raw: string): any => {
+      const msg: any = raw.startsWith(STRUCTURED_CLONE_PREFIX)
+        ? structuredCloneParse(raw.slice(STRUCTURED_CLONE_PREFIX.length))
+        : JSON.parse(raw)
+      if (msg.t === 'q' && msg.i && msg.m)
+        pendingRequestMethods.set(msg.i, msg.m)
+      return msg
+    },
   }
 }

devframe/packages/devframe/src/rpc/transports/ws-server.ts

@@ -5,7 +5,12 @@ import type { WebSocket } from 'ws'
 import type { RpcFunctionDefinitionAny } from '../types'
 import { createServer as createHttpsServer } from 'node:https'
 import { WebSocketServer } from 'ws'
-import { makePerCallChannelOptions } from '../serialization'
+import {
+  strictJsonStringify,
+  STRUCTURED_CLONE_PREFIX,
+  structuredCloneParse,
+  structuredCloneStringify,
+} from '../serialization'
 
 export interface DevToolsNodeRpcSessionMeta {
   id: number
@@ -91,10 +96,11 @@ export function attachWsRpcTransport<
       subscribedStates: new Set(),
     }
 
-    // Per-connection serializer state (the pending request-id map that
-    // mirrors method metadata from request to response). Each WS gets
-    // its own so request-id spaces don't collide across sessions.
-    const perCall = makePerCallChannelOptions(definitions)
+    // Per-connection state: maps an incoming request id to its method
+    // name so the matching outgoing response can look the method back
+    // up in `definitions` and pick the right encoder. One map per WS
+    // session — request-id spaces don't collide across sessions.
+    const pendingRequestMethods = new Map<string, string>()
     const channel: ChannelOptions = {
       post: (data) => {
         ws.send(data)
@@ -104,8 +110,28 @@ export function attachWsRpcTransport<
           fn(data.toString())
         })
       },
-      serialize: serializeOverride ?? perCall.serialize,
-      deserialize: deserializeOverride ?? perCall.deserialize,
+      serialize: serializeOverride ?? ((msg: any): string => {
+        let method: string | undefined
+        if (msg.t === 'q') {
+          method = msg.m
+        }
+        else {
+          method = pendingRequestMethods.get(msg.i)
+          pendingRequestMethods.delete(msg.i)
+        }
+        const useJson = !!method && definitions.get(method)?.jsonSerializable === true
+        if (useJson)
+          return strictJsonStringify(msg, method ?? '')
+        return `${STRUCTURED_CLONE_PREFIX}${structuredCloneStringify(msg)}`
+      }),
+      deserialize: deserializeOverride ?? ((raw: string): any => {
+        const msg: any = raw.startsWith(STRUCTURED_CLONE_PREFIX)
+          ? structuredCloneParse(raw.slice(STRUCTURED_CLONE_PREFIX.length))
+          : JSON.parse(raw)
+        if (msg.t === 'q' && msg.i && msg.m)
+          pendingRequestMethods.set(msg.i, msg.m)
+        return msg
+      }),
       meta,
     }
 

devframe/tests/__snapshots__/tsnapi/devframe/rpc.snapshot.d.ts

@@ -12,7 +12,6 @@ export { EntriesToObject }
 export { getDefinitionsWithDumps }
 export { getRpcHandler }
 export { getRpcResolvedSetupResult }
-export { makePerCallChannelOptions }
 export { RpcArgsSchema }
 export { RpcCacheManager }
 export { RpcCacheOptions }

devframe/tests/__snapshots__/tsnapi/devframe/rpc.snapshot.js

@@ -9,7 +9,6 @@ export { dumpFunctions }
 export { getDefinitionsWithDumps }
 export { getRpcHandler }
 export { getRpcResolvedSetupResult }
-export { makePerCallChannelOptions }
 export { RpcCacheManager }
 export { RpcFunctionsCollectorBase }
 export { strictJsonStringify }