@bigmistqke/rpc 0.1.3 → 0.1.5

package/src/core.ts

@@ -0,0 +1,100 @@
+import { HANDLE_NAMESPACE_PREFIX, isHandleMarker, nextHandleNamespaceId } from './handle'
+import { $MESSENGER_HANDLE, HandleResponseShape } from './protocol'
+import type { RPC } from './types'
+
+export function createCommander<T extends object = object>(
+  apply: (topics: Array<string>, args: Array<any>) => void,
+): T {
+  function _createCommander(
+    topics: Array<string>,
+    apply: (topics: Array<string>, args: Array<any>) => void,
+  ): T {
+    return new Proxy(function () { } as T, {
+      get(target, topic) {
+        if (typeof topic === 'symbol') return (target as any)[topic]
+        // Return undefined for 'then' so proxy isn't treated as thenable
+        if (topic === 'then') return undefined
+        return _createCommander([...topics, topic], apply)
+      },
+      apply(_, __, args) {
+        return apply(topics, args)
+      },
+    })
+  }
+  return _createCommander([], apply)
+}
+
+export function callMethod(methods: object, topics: string[], args: unknown[]) {
+  const method = topics.reduce((acc, topic) => {
+    const result = (acc as any)?.[topic]
+    return result
+  }, methods)
+  if (typeof method !== 'function') {
+    throw new Error(`Topics did not resolve to a function: [${topics.join(',')}]`)
+  }
+  return method.call(methods, ...args)
+}
+
+/**
+ * Check if a response payload is a handle response
+ */
+export function isHandleResponse(value: unknown): value is { [$MESSENGER_HANDLE]: string } {
+  return (
+    !!value &&
+    typeof value === 'object' &&
+    $MESSENGER_HANDLE in value &&
+    typeof (value as any)[$MESSENGER_HANDLE] === 'string'
+  )
+}
+
+/**
+ * Creates a request handler for expose() that manages namespace routing and handle() sub-proxies.
+ * Returns the processed result ready to be sent back over the transport.
+ */
+export function createExposeRequestHandler(methods: object) {
+  const namespaceHandlers = new Map<string, object>()
+
+  const processResult = (result: unknown): unknown => {
+    if (isHandleMarker(result)) {
+      const namespaceId = nextHandleNamespaceId()
+      namespaceHandlers.set(namespaceId, result.methods)
+      return HandleResponseShape.create(namespaceId)
+    }
+    return result
+  }
+
+  return async (topics: string[], args: unknown[]): Promise<unknown> => {
+    const firstTopic = topics[0]
+    if (firstTopic && firstTopic.startsWith(HANDLE_NAMESPACE_PREFIX)) {
+      const handler = namespaceHandlers.get(firstTopic)
+      if (!handler) {
+        throw new Error(`Unknown namespace: ${firstTopic}`)
+      }
+      const result = await callMethod(handler, topics.slice(1), args)
+      return processResult(result)
+    }
+    const result = await callMethod(methods, topics, args)
+    return processResult(result)
+  }
+}
+
+/**
+ * Creates an RPC commander proxy that handles handle() sub-proxy responses.
+ */
+export function createRpcCommander<T extends object>(
+  request: (topics: string[], args: any[]) => Promise<unknown>,
+  topicPrefix: string[] = [],
+): RPC<T> {
+  return createCommander<RPC<T>>((topics, methodArgs) => {
+    const fullTopics = [...topicPrefix, ...topics]
+    return request(fullTopics, methodArgs).then((result: unknown) => {
+      if (isHandleResponse(result)) {
+        return createRpcCommander(
+          request,
+          result[$MESSENGER_HANDLE] ? [result[$MESSENGER_HANDLE]] : [],
+        )
+      }
+      return result
+    })
+  })
+}

package/src/fetch/index.ts

@@ -1,6 +1,7 @@
 import * as v from 'valibot'
 import { RPC } from '../types'
-import { callMethod, createCommander, createShape } from '../utils'
+import { callMethod, createCommander } from '../core'
+import { createShape } from '../utils'
 
 const $FETCH_HEADER = 'RPC_RR_PROXY'
 

package/src/fetch/node.ts

@@ -2,7 +2,7 @@
 
 import { IncomingMessage, ServerResponse } from 'http'
 import { Payload } from '.'
-import { callMethod } from '../utils'
+import { callMethod } from '../core'
 
 export function exposeNode<T extends object>(
   methods: T,

package/src/handle.ts

@@ -0,0 +1,48 @@
+const $HANDLE_MARKER = Symbol('RPC-HANDLE-MARKER')
+
+/** Internal marker type for handle() */
+interface HandleMarker<T extends object> {
+  [$HANDLE_MARKER]: true
+  methods: T
+}
+
+/** Type for values returned by handle() - unwrapped to RPC<T> by RPC system */
+export type Handled<T extends object> = T & { readonly ['__rpc_handled__']: T }
+
+/**
+ * Mark methods to be returned as a sub-proxy from an RPC method.
+ * Use this when a method needs to return an object with callable methods.
+ *
+ * @example
+ * ```ts
+ * expose({
+ *   init(canvas: OffscreenCanvas) {
+ *     const renderer = createRenderer(canvas)
+ *     return handle({
+ *       render: () => renderer.render(),
+ *       resize: (w, h) => renderer.resize(w, h),
+ *     })
+ *   }
+ * })
+ * ```
+ */
+export function handle<T extends object>(methods: T): Handled<T> {
+  return { [$HANDLE_MARKER]: true, methods } as unknown as Handled<T>
+}
+
+/**
+ * Check if a value is a handle marker
+ */
+export function isHandleMarker<T extends object>(value: unknown): value is HandleMarker<T> {
+  return !!value && typeof value === 'object' && $HANDLE_MARKER in value
+}
+
+// Prefix for namespace IDs to avoid collisions
+export const HANDLE_NAMESPACE_PREFIX = '__rpc_handle_'
+
+// Counter for generating unique namespace IDs
+export let handleNamespaceCounter = 0
+
+export function nextHandleNamespaceId(): string {
+  return `${HANDLE_NAMESPACE_PREFIX}${handleNamespaceCounter++}`
+}

package/src/{messenger.ts → messenger/index.ts}

@@ -1,3 +1,4 @@
+import { createExposeRequestHandler, createRpcCommander } from '../core'
 import {
   $MESSENGER_ERROR,
   $MESSENGER_RESPONSE,
@@ -6,13 +7,13 @@ import {
   RequestShape,
   ResponseShape,
   RPCPayloadShape,
-} from './message-protocol'
-import { RPC } from './types'
-export type { RPC } from './types'
-import { callMethod, createCommander, createIdRegistry, defer } from './utils'
+} from '../protocol'
+import type { RPC } from '../types'
+import { createIdRegistry, defer } from '../utils'
+export { handle, type Handled } from '../handle'
 
 export const $TRANSFER = 'RPC-TRANSFER'
-export const $MESSENGER = Symbol('RPC-MESSENGER')
+export const $MESSENGER = Symbol.for('RPC-MESSENGER')
 
 /** Wrapper type for transferable values */
 export type Transferred<T> = T & {
@@ -166,7 +167,10 @@ export function createResponder(
         try {
           const result = await callback(data)
           // Extract transferables from the result
-          const { args: [processedResult], transferables } = extractTransferables([result])
+          const {
+            args: [processedResult],
+            transferables,
+          } = extractTransferables([result])
           postMessage(ResponseShape.create(data, processedResult), transferables)
         } catch (error) {
           postMessage(ErrorShape.create(data, error))
@@ -188,29 +192,64 @@ export function createResponder(
 /**********************************************************************************/
 
 /**
- * Exposes a set of methods as an RPC endpoint over the given messenger.
+ * Exposes methods as an RPC endpoint over the given messenger.
  *
- * @param methods - An object containing functions to expose
+ * @param methods - Object containing methods to expose
  * @param options - Optional target Messenger and abort signal
+ *
+ * @example
+ * ```ts
+ * // Worker side - simple methods
+ * expose({
+ *   add: (a, b) => a + b,
+ *   multiply: (a, b) => a * b,
+ * })
+ *
+ * // Worker side - with initialization returning sub-proxy
+ * expose({
+ *   init(canvas: OffscreenCanvas) {
+ *     const renderer = createRenderer(canvas)
+ *     return handle({
+ *       render: () => renderer.render(),
+ *       resize: (w, h) => renderer.resize(w, h),
+ *     })
+ *   }
+ * })
+ * ```
  */
-export function expose<T extends object>(
-  methods: T,
+export function expose<TMethods extends object>(
+  methods: TMethods,
   { to = self, signal }: { to?: Messenger; signal?: AbortSignal } = {},
-) {
-  createResponder(
-    to,
-    data => {
-      if (RPCPayloadShape.validate(data.payload)) {
+): void {
+  const postMessage = usePostMessage(to)
+  const handleRequest = createExposeRequestHandler(methods)
+
+  to.addEventListener(
+    'message',
+    async event => {
+      const data = (event as MessageEvent).data
+      if (RequestShape.validate(data)) {
         try {
-          const { topics, args } = data.payload
-          return callMethod(methods, topics, args)
+          if (RPCPayloadShape.validate(data.payload)) {
+            const result = await handleRequest(data.payload.topics, data.payload.args)
+            const {
+              args: [finalResult],
+              transferables,
+            } = extractTransferables([result])
+            postMessage(ResponseShape.create(data, finalResult), transferables)
+          }
         } catch (error) {
-          console.error('Error while processing rpc request:', error, data.payload, methods)
+          console.error('Error while processing rpc request:', error, data.payload)
+          postMessage(ErrorShape.create(data, error))
         }
       }
     },
     { signal },
   )
+
+  if ('start' in to) {
+    to.start?.()
+  }
 }
 
 /**
@@ -218,18 +257,19 @@ export function expose<T extends object>(
  *
  * @param messenger - The Messenger to communicate with (e.g. Worker or Window)
  * @param options - Optional abort signal
- * @returns A proxy object that lets you call methods remotely
+ * @returns A proxy object for calling remote methods
  *
  * @example
  * ```ts
- * const worker = new Worker('worker.js')
- * const api = rpc<WorkerAPI>(worker)
+ * // Create RPC proxy (synchronous)
+ * const worker = rpc<WorkerMethods>(new Worker('worker.js'))
  *
- * // Call remote methods
- * await api.doSomething()
+ * // Call methods that return handle() get sub-proxies
+ * const renderer = await worker.init(transfer(canvas))
+ * await renderer.render()
  *
  * // Access underlying messenger
- * api[$MESSENGER].terminate()
+ * worker[$MESSENGER].terminate()
  * ```
  */
 // Overloads for specific messenger types to enable proper type inference
@@ -269,9 +309,11 @@ export function rpc<T extends object, M extends Messenger>(
   options?: { signal?: AbortSignal },
 ): RPC<T> & { [$MESSENGER]: M } {
   const request = createRequester(messenger, options)
-  const proxy = createCommander<RPC<T>>((topics, args) => {
+
+  const proxy = createRpcCommander<T>((topics, args) => {
     const { args: processedArgs, transferables } = extractTransferables(args)
     return request(RPCPayloadShape.create(topics, processedArgs), transferables)
   })
+
   return Object.assign(proxy, { [$MESSENGER]: messenger })
 }

package/src/{message-protocol.ts → protocol.ts}

@@ -22,7 +22,7 @@ export const $MESSENGER_RESPONSE = 'RPC_PROXY_RESPONSE'
 export const ResponseShape = createShape(
   v.object({
     [$MESSENGER_RESPONSE]: v.number(),
-    payload: v.unknown(),
+    payload: v.optional(v.unknown()),
   }),
   (request: RequestData, payload: any) => ({
     [$MESSENGER_RESPONSE]: request[$MESSENGER_REQUEST],
@@ -55,3 +55,13 @@ export const RPCPayloadShape = createShape(
   }),
   (topics: Array<string>, args: Array<any>) => ({ [$MESSENGER_RPC_REQUEST]: true, topics, args }),
 )
+
+// Handle response - when a method returns handle(), client creates sub-proxy
+export const $MESSENGER_HANDLE = 'RPC_PROXY_HANDLE'
+
+export const HandleResponseShape = createShape(
+  v.object({
+    [$MESSENGER_HANDLE]: v.string(), // namespace ID
+  }),
+  (namespaceId: string) => ({ [$MESSENGER_HANDLE]: namespaceId }),
+)

package/src/server-send-events/index.ts

@@ -1,7 +1,8 @@
-import { $MESSENGER_REQUEST, RequestShape, RPCPayloadShape } from '../message-protocol'
 import * as v from 'valibot'
+import { $MESSENGER_REQUEST, RequestShape, RPCPayloadShape } from '../protocol'
 import { RPC } from '../types'
-import { callMethod, createCommander, createIdRegistry, createShape, defer } from '../utils'
+import { callMethod, createCommander } from '../core'
+import { createIdRegistry, createShape, defer } from '../utils'
 
 const $SSE_RESPONSE_HEADER = 'RPC_SSE_RESPONSE'
 

package/src/stream/index.ts

@@ -1,18 +1,7 @@
-import {
-  $MESSENGER_RESPONSE,
-  RequestShape,
-  ResponseShape,
-  RPCPayloadShape,
-} from '../message-protocol'
+import { $MESSENGER_RESPONSE, RequestShape, ResponseShape, RPCPayloadShape } from '../protocol'
 import { RPC } from '../types'
-import {
-  callMethod,
-  createCommander,
-  createPromiseRegistry,
-  createReadableStream,
-  defer,
-  streamToAsyncIterable,
-} from '../utils'
+import { callMethod, createCommander } from '../core'
+import { createPromiseRegistry, createReadableStream, defer, streamToAsyncIterable } from '../utils'
 
 interface StreamCodec {
   serialize(value: any, onChunk: (chunk: any) => void): void

package/src/types.ts

@@ -1,6 +1,11 @@
 export type Fn = (...arg: Array<any>) => any
 export type MaybePromise<T> = T | Promise<T>
 
+/** Check if T is a Handled type and extract the inner type */
+type UnwrapHandled<T> = T extends { readonly ['__rpc_handled__']: infer U extends object }
+  ? RPC<U>
+  : T
+
 // To prevent error: `Type instantiation is excessively deep and possibly infinite.`
 type isObject<T> = T extends object ? true : false
 
@@ -47,7 +52,7 @@ type FilterNoResponseMethod<T> = {
 /**********************************************************************************/
 
 export interface ResponseMethod<T extends Fn> {
-  (...args: Parameters<T>): Promise<Awaited<ReturnType<T>>>
+  (...args: Parameters<T>): Promise<UnwrapHandled<Awaited<ReturnType<T>>>>
 }
 
 export type ResponseRPCNode<T> = T extends Fn

package/src/utils.ts

@@ -58,26 +58,6 @@ export function defer<T = void>() {
   }
 }
 
-export function createCommander<T extends object = object>(
-  apply: (topics: Array<string>, args: Array<any>) => void,
-): T {
-  function _createCommander(
-    topics: Array<string>,
-    apply: (topics: Array<string>, args: Array<any>) => void,
-  ): T {
-    return new Proxy(function () {} as T, {
-      get(target, topic) {
-        if (typeof topic === 'symbol') return (target as any)[topic]
-        return _createCommander([...topics, topic], apply)
-      },
-      apply(_, __, args) {
-        return apply(topics, args)
-      },
-    })
-  }
-  return _createCommander([], apply)
-}
-
 /**
  * Creates a schema-backed shape definition with a validator and constructor.
  *
@@ -94,18 +74,6 @@ export function createShape<
   }
 }
 
-// expose-core.ts
-export function callMethod(methods: object, topics: string[], args: unknown[]) {
-  const method = topics.reduce((acc, topic) => {
-    const result = (acc as any)?.[topic]
-    return result
-  }, methods)
-  if (typeof method !== 'function') {
-    throw new Error(`Topics did not resolve to a function: [${topics.join(',')}]`)
-  }
-  return method(...args)
-}
-
 // NOTE:  safari does not implement AsyncIterator for ReadableStream
 //        see https://caniuse.com/mdn-api_readablestream_--asynciterator
 export function streamToAsyncIterable<T>(stream: ReadableStream<T>): AsyncIterable<T> {

package/src/websocket/index.ts

@@ -0,0 +1,142 @@
+import * as v from 'valibot'
+import { createExposeRequestHandler, createRpcCommander } from '../core'
+import {
+  $MESSENGER_ERROR,
+  $MESSENGER_RESPONSE,
+  ErrorShape,
+  RequestShape,
+  ResponseShape,
+  RPCPayloadShape,
+} from '../protocol'
+import { RPC as BaseRPC } from '../types'
+import { createIdRegistry, createShape, defer } from '../utils'
+export { handle, type Handled } from '../handle'
+
+export const $WEBSOCKET = Symbol.for('RPC-WEBSOCKET')
+
+export interface WebSocketLike {
+  send(data: string): void
+  close(): void
+  addEventListener(type: string, listener: (event: unknown) => void): void
+}
+
+export type RPC<T extends object, WS extends WebSocketLike = WebSocketLike> = BaseRPC<T> & {
+  [$WEBSOCKET]: WS
+}
+
+/**********************************************************************************/
+/*                                                                                */
+/*                              Requester / Responder                             */
+/*                                                                                */
+/**********************************************************************************/
+
+const MessageEventShape = createShape(v.object({ data: v.unknown() }), (data: unknown) => ({
+  data,
+}))
+
+function parseData(raw: unknown): unknown {
+  return JSON.parse(typeof raw === 'string' ? raw : String(raw))
+}
+
+function createRequester(ws: WebSocketLike) {
+  const promiseRegistry = createIdRegistry<{
+    resolve(value: any): void
+    reject(value: unknown): void
+  }>()
+
+  ws.addEventListener('message', (event: unknown) => {
+    if (!MessageEventShape.validate(event)) return
+    try {
+      const data = parseData(event.data)
+      if (ErrorShape.validate(data)) {
+        promiseRegistry.free(data[$MESSENGER_ERROR])?.reject(data.error)
+      } else if (ResponseShape.validate(data)) {
+        promiseRegistry.free(data[$MESSENGER_RESPONSE])?.resolve(data.payload)
+      }
+    } catch (error) {
+      console.error(error)
+    }
+  })
+
+  return (payload: any) => {
+    const { promise, resolve, reject } = defer()
+    const id = promiseRegistry.register({ resolve, reject })
+    ws.send(JSON.stringify(RequestShape.create(id, payload)))
+    return promise
+  }
+}
+
+/**********************************************************************************/
+/*                                                                                */
+/*                                  Expose / Rpc                                  */
+/*                                                                                */
+/**********************************************************************************/
+
+/**
+ * Exposes methods as an RPC endpoint over the given WebSocket.
+ *
+ * @param methods - Object containing methods to expose
+ * @param options - Target WebSocket and optional abort signal
+ *
+ * @example
+ * ```ts
+ * expose({
+ *   add: (a, b) => a + b,
+ *   multiply: (a, b) => a * b,
+ * }, { to: ws })
+ * ```
+ */
+export function expose<TMethods extends object>(
+  methods: TMethods,
+  { to }: { to: WebSocketLike },
+): void {
+  const handleRequest = createExposeRequestHandler(methods)
+
+  to.addEventListener('message', async (event: unknown) => {
+    if (!MessageEventShape.validate(event)) return
+    try {
+      const data = parseData(event.data)
+      if (RequestShape.validate(data)) {
+        try {
+          if (RPCPayloadShape.validate(data.payload)) {
+            const result = await handleRequest(data.payload.topics, data.payload.args)
+            to.send(JSON.stringify(ResponseShape.create(data, result)))
+          }
+        } catch (error) {
+          console.error('Error while processing rpc request:', error, data.payload)
+          to.send(JSON.stringify(ErrorShape.create(data, error)))
+        }
+      }
+    } catch (error) {
+      console.error(error)
+    }
+  })
+}
+
+/**
+ * Creates an RPC proxy for calling remote methods on the given WebSocket.
+ *
+ * @param ws - The WebSocket to communicate with
+ * @param options - Optional abort signal
+ * @returns A proxy object for calling remote methods
+ *
+ * @example
+ * ```ts
+ * const server = rpc<ServerMethods>(ws)
+ * const result = await server.add(2, 3)
+ *
+ * // Access underlying WebSocket
+ * server[$WEBSOCKET].close()
+ * ```
+ */
+export function rpc<T extends object, WS extends WebSocketLike = WebSocketLike>(
+  ws: WS,
+): RPC<T, WS> {
+  const request = createRequester(ws)
+
+  const proxy = createRpcCommander<T>((topics, args) => {
+    return request(RPCPayloadShape.create(topics, args))
+  })
+
+  return Object.assign(proxy, { [$WEBSOCKET]: ws }) as RPC<T, WS>
+}