@bigmistqke/rpc 0.1.3 → 0.1.4

package/dist/handle-18d6fe9b.d.ts

@@ -0,0 +1,24 @@
+/** Type for values returned by handle() - unwrapped to RPC<T> by RPC system */
+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),
+ *     })
+ *   }
+ * })
+ * ```
+ */
+declare function handle<T extends object>(methods: T): Handled<T>;
+
+export { Handled as H, handle as h };

package/dist/messenger.d.ts

@@ -1,5 +1,6 @@
 import * as v from 'valibot';
-import { R as RPC } from './types-a5ce9c9a.js';
+import { R as RPC } from './types-9f54da43.js';
+export { H as Handled, h as handle } from './handle-18d6fe9b.js';
 
 declare const requestSchema: v.ObjectSchema<{
     readonly RPC_PROXY_REQUEST: v.NumberSchema<undefined>;
@@ -37,12 +38,32 @@ declare function createResponder(messenger: Messenger, callback: (data: RequestD
 /**********************************************************************************/
 /**********************************************************************************/
 /**
- * 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),
+ *     })
+ *   }
+ * })
+ * ```
  */
-declare function expose<T extends object>(methods: T, { to, signal }?: {
+declare function expose<TMethods extends object>(methods: TMethods, { to, signal }?: {
     to?: Messenger;
     signal?: AbortSignal;
 }): void;
@@ -51,18 +72,19 @@ declare function expose<T extends object>(methods: T, { to, signal }?: {
  *
  * @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()
  * ```
  */
 declare function rpc<T extends object>(messenger: Worker, options?: {
@@ -96,4 +118,4 @@ declare function rpc<T extends object, M extends Messenger = Messenger>(messenge
     [$MESSENGER]: M;
 };
 
-export { $MESSENGER, $TRANSFER, RPC, Transferred, createResponder, expose, rpc, transfer };
+export { $MESSENGER, $TRANSFER, Transferred, createResponder, expose, rpc, transfer };

package/dist/messenger.js

@@ -1,3 +1,17 @@
+// src/handle.ts
+var $HANDLE_MARKER = Symbol("RPC-HANDLE-MARKER");
+function handle(methods) {
+  return { [$HANDLE_MARKER]: true, methods };
+}
+function isHandleMarker(value) {
+  return !!value && typeof value === "object" && $HANDLE_MARKER in value;
+}
+var HANDLE_NAMESPACE_PREFIX = "__rpc_handle_";
+var handleNamespaceCounter = 0;
+function nextHandleNamespaceId() {
+  return `${HANDLE_NAMESPACE_PREFIX}${handleNamespaceCounter++}`;
+}
+
 // ../../node_modules/.pnpm/valibot@1.0.0_typescript@5.7.2/node_modules/valibot/dist/index.js
 var store;
 function getGlobalConfig(config2) {
@@ -292,6 +306,32 @@ function object(entries, message) {
     }
   };
 }
+function optional(wrapped, default_) {
+  return {
+    kind: "schema",
+    type: "optional",
+    reference: optional,
+    expects: `(${wrapped.expects} | undefined)`,
+    async: false,
+    wrapped,
+    default: default_,
+    get "~standard"() {
+      return _getStandardProps(this);
+    },
+    "~run"(dataset, config2) {
+      if (dataset.value === void 0) {
+        if (this.default !== void 0) {
+          dataset.value = getDefault(this, dataset, config2);
+        }
+        if (dataset.value === void 0) {
+          dataset.typed = true;
+          return dataset;
+        }
+      }
+      return this.wrapped["~run"](dataset, config2);
+    }
+  };
+}
 function string(message) {
   return {
     kind: "schema",
@@ -379,40 +419,14 @@ function defer() {
     reject
   };
 }
-function createCommander(apply) {
-  function _createCommander(topics, apply2) {
-    return new Proxy(function() {
-    }, {
-      get(target, topic) {
-        if (typeof topic === "symbol")
-          return target[topic];
-        return _createCommander([...topics, topic], apply2);
-      },
-      apply(_, __, args) {
-        return apply2(topics, args);
-      }
-    });
-  }
-  return _createCommander([], apply);
-}
 function createShape(schema, create) {
   return {
     validate: (value) => safeParse(schema, value).success,
     create
   };
 }
-function callMethod(methods, topics, args) {
-  const method = topics.reduce((acc, topic) => {
-    const result = acc?.[topic];
-    return result;
-  }, methods);
-  if (typeof method !== "function") {
-    throw new Error(`Topics did not resolve to a function: [${topics.join(",")}]`);
-  }
-  return method(...args);
-}
 
-// src/message-protocol.ts
+// src/protocol.ts
 var $MESSENGER_REQUEST = "RPC_PROXY_REQUEST";
 var requestSchema = object({
   [$MESSENGER_REQUEST]: number(),
@@ -426,7 +440,7 @@ var $MESSENGER_RESPONSE = "RPC_PROXY_RESPONSE";
 var ResponseShape = createShape(
   object({
     [$MESSENGER_RESPONSE]: number(),
-    payload: unknown()
+    payload: optional(unknown())
   }),
   (request, payload) => ({
     [$MESSENGER_RESPONSE]: request[$MESSENGER_REQUEST],
@@ -453,10 +467,89 @@ var RPCPayloadShape = createShape(
   }),
   (topics, args) => ({ [$MESSENGER_RPC_REQUEST]: true, topics, args })
 );
+var $MESSENGER_HANDLE = "RPC_PROXY_HANDLE";
+var HandleResponseShape = createShape(
+  object({
+    [$MESSENGER_HANDLE]: string()
+    // namespace ID
+  }),
+  (namespaceId) => ({ [$MESSENGER_HANDLE]: namespaceId })
+);
 
-// src/messenger.ts
+// src/core.ts
+function createCommander(apply) {
+  function _createCommander(topics, apply2) {
+    return new Proxy(function() {
+    }, {
+      get(target, topic) {
+        if (typeof topic === "symbol")
+          return target[topic];
+        if (topic === "then")
+          return void 0;
+        return _createCommander([...topics, topic], apply2);
+      },
+      apply(_, __, args) {
+        return apply2(topics, args);
+      }
+    });
+  }
+  return _createCommander([], apply);
+}
+function callMethod(methods, topics, args) {
+  const method = topics.reduce((acc, topic) => {
+    const result = acc?.[topic];
+    return result;
+  }, methods);
+  if (typeof method !== "function") {
+    throw new Error(`Topics did not resolve to a function: [${topics.join(",")}]`);
+  }
+  return method(...args);
+}
+function isHandleResponse(value) {
+  return !!value && typeof value === "object" && $MESSENGER_HANDLE in value && typeof value[$MESSENGER_HANDLE] === "string";
+}
+function createExposeRequestHandler(methods) {
+  const namespaceHandlers = /* @__PURE__ */ new Map();
+  const processResult = (result) => {
+    if (isHandleMarker(result)) {
+      const namespaceId = nextHandleNamespaceId();
+      namespaceHandlers.set(namespaceId, result.methods);
+      return HandleResponseShape.create(namespaceId);
+    }
+    return result;
+  };
+  return async (topics, args) => {
+    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 result2 = await callMethod(handler, topics.slice(1), args);
+      return processResult(result2);
+    }
+    const result = await callMethod(methods, topics, args);
+    return processResult(result);
+  };
+}
+function createRpcCommander(request, topicPrefix = []) {
+  return createCommander((topics, methodArgs) => {
+    const fullTopics = [...topicPrefix, ...topics];
+    return request(fullTopics, methodArgs).then((result) => {
+      if (isHandleResponse(result)) {
+        return createRpcCommander(
+          request,
+          result[$MESSENGER_HANDLE] ? [result[$MESSENGER_HANDLE]] : []
+        );
+      }
+      return result;
+    });
+  });
+}
+
+// src/messenger/index.ts
 var $TRANSFER = "RPC-TRANSFER";
-var $MESSENGER = Symbol("RPC-MESSENGER");
+var $MESSENGER = Symbol.for("RPC-MESSENGER");
 function transfer(value) {
   return Object.assign(value, { [$TRANSFER]: true });
 }
@@ -529,7 +622,10 @@ function createResponder(messenger, callback, options = {}) {
       if (RequestShape.validate(data)) {
         try {
           const result = await callback(data);
-          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));
@@ -543,24 +639,37 @@ function createResponder(messenger, callback, options = {}) {
   }
 }
 function expose(methods, { to = self, signal } = {}) {
-  createResponder(
-    to,
-    (data) => {
-      if (RPCPayloadShape.validate(data.payload)) {
+  const postMessage = usePostMessage(to);
+  const handleRequest = createExposeRequestHandler(methods);
+  to.addEventListener(
+    "message",
+    async (event) => {
+      const data = event.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?.();
+  }
 }
 function rpc(messenger, options) {
   const request = createRequester(messenger, options);
-  const proxy = createCommander((topics, args) => {
+  const proxy = createRpcCommander((topics, args) => {
     const { args: processedArgs, transferables } = extractTransferables(args);
     return request(RPCPayloadShape.create(topics, processedArgs), transferables);
   });
@@ -571,6 +680,7 @@ export {
   $TRANSFER,
   createResponder,
   expose,
+  handle,
   rpc,
   transfer
 };