kkrpc 0.1.2 → 0.2.0-beta.2

package/README.md

@@ -12,6 +12,8 @@
 - [Documentation by JSR](https://jsr.io/@kunkun/kkrpc/doc)
 - [Typedoc Documentation](https://kunkunsh.github.io/kkrpc/)
 
+[Excalidraw Diagrams](https://excalidraw.com/#json=otqFU25B2sSjweA4Sbq9l,7-eY_bzFrGAXLNkOVpQ2Tg)
+
 ![](https://imgur.com/vR3Lmv0.png)
 ![](https://imgur.com/u728aVv.png)
 ![](https://imgur.com/2ycWgVQ.png)

package/dist/browser-mod.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // browser-mod.ts
@@ -337,29 +347,14 @@ var IframeChildIO = class {
 var import_node_buffer = require("buffer");
 
 // src/serialization.ts
-function replacer(key, value) {
-  if (value instanceof Uint8Array) {
-    return {
-      type: "Uint8Array",
-      data: Array.from(value)
-      // Convert to regular array
-    };
-  }
-  return value;
-}
-function reviver(key, value) {
-  if (value && value.type === "Uint8Array" && Array.isArray(value.data)) {
-    return new Uint8Array(value.data);
-  }
-  return value;
-}
+var import_superjson = __toESM(require("superjson"), 1);
 function serializeMessage(message) {
-  return JSON.stringify(message, replacer) + "\n";
+  return import_superjson.default.stringify(message) + "\n";
 }
 function deserializeMessage(message) {
   return new Promise((resolve, reject) => {
     try {
-      const parsed = JSON.parse(message, reviver);
+      const parsed = import_superjson.default.parse(message);
       resolve(parsed);
     } catch (error) {
       console.error("failed to parse message", typeof message, message, error);
@@ -368,12 +363,12 @@ function deserializeMessage(message) {
   });
 }
 function serializeResponse(response) {
-  return JSON.stringify(response) + "\n";
+  return import_superjson.default.stringify(response) + "\n";
 }
 function deserializeResponse(response) {
   return new Promise((resolve, reject) => {
     try {
-      const parsed = JSON.parse(response);
+      const parsed = import_superjson.default.parse(response);
       resolve(parsed);
     } catch (error) {
       console.error("failed to parse response", response);
@@ -400,12 +395,25 @@ var RPCChannel = class {
   count = 0;
   messageStr = "";
   apiImplementation;
+  /**
+   * Exposes a local API implementation that can be called remotely
+   * @param api The local API implementation to expose
+   */
   expose(api) {
     this.apiImplementation = api;
   }
+  /**
+   * Returns the IO interface used by this channel
+   * @returns The IO interface instance
+   */
   getIO() {
     return this.io;
   }
+  /**
+   * Listens for incoming messages on the IO interface
+   * Handles message buffering and parsing
+   * @private
+   */
   async listen() {
     while (true) {
       const buffer = await this.io.read();
@@ -430,6 +438,11 @@ var RPCChannel = class {
       }
     }
   }
+  /**
+   * Handles a single message string by parsing and routing it
+   * @param messageStr The message string to handle
+   * @private 
+   */
   async handleMessageStr(messageStr) {
     this.count++;
     return deserializeMessage(messageStr).then((parsedMessage) => {
@@ -446,7 +459,12 @@ var RPCChannel = class {
       console.log(`(kkrpc stdout passthrough):`, messageStr);
     });
   }
-  // Send a method call to the other process
+  /**
+   * Calls a method on the remote API
+   * @param method The name of the method to call
+   * @param args Arguments to pass to the remote method
+   * @returns Promise that resolves with the result of the remote call
+   */
   callMethod(method, args) {
     return new Promise((resolve, reject) => {
       const messageId = generateUUID();
@@ -476,7 +494,11 @@ var RPCChannel = class {
       this.io.write(serializeMessage(message));
     });
   }
-  // Handle response to a request we sent
+  /**
+   * Handles responses received from remote method calls
+   * @param response The response message to handle
+   * @private
+   */
   handleResponse(response) {
     const { id } = response;
     const { result, error } = response.args;
@@ -489,7 +511,11 @@ var RPCChannel = class {
       delete this.pendingRequests[id];
     }
   }
-  // Handle incoming requests from the other process using a Proxy
+  /**
+   * Handles incoming method call requests from the remote endpoint
+   * @param request The request message to handle
+   * @private
+   */
   handleRequest(request) {
     const { id, method, args } = request;
     const methodPath = method.split(".");
@@ -526,6 +552,12 @@ var RPCChannel = class {
       this.sendError(id, error.message ?? error.toString());
     }
   }
+  /**
+   * Invokes a callback on the remote endpoint
+   * @param callbackId The ID of the callback to invoke
+   * @param args Arguments to pass to the callback
+   * @private
+   */
   invokeCallback(callbackId, args) {
     const message = {
       id: generateUUID(),
@@ -535,6 +567,11 @@ var RPCChannel = class {
     };
     this.io.write(serializeMessage(message));
   }
+  /**
+   * Handles callback invocations received from the remote endpoint
+   * @param message The callback message to handle
+   * @private
+   */
   handleCallback(message) {
     const { method: callbackId, args } = message;
     const callback = this.callbacks[callbackId];
@@ -544,7 +581,12 @@ var RPCChannel = class {
       console.error(`Callback with id ${callbackId} not found`);
     }
   }
-  // Send a response to a request
+  /**
+   * Sends a successful response back to the remote endpoint
+   * @param id The ID of the request being responded to
+   * @param result The result to send back
+   * @private
+   */
   sendResponse(id, result) {
     const response = {
       id,
@@ -554,7 +596,12 @@ var RPCChannel = class {
     };
     this.io.write(serializeMessage(response));
   }
-  // Send an error response
+  /**
+   * Sends an error response back to the remote endpoint
+   * @param id The ID of the request being responded to
+   * @param error The error message to send back
+   * @private
+   */
   sendError(id, error) {
     const response = {
       id,
@@ -564,6 +611,12 @@ var RPCChannel = class {
     };
     this.io.write(serializeMessage(response));
   }
+  /**
+   * Creates a nested proxy object for chaining remote method calls
+   * @param chain Array of method names in the chain
+   * @returns Proxy object that transforms property access into remote method calls
+   * @private
+   */
   createNestedProxy(chain = []) {
     return new Proxy(() => {
     }, {
@@ -579,16 +632,17 @@ var RPCChannel = class {
       }
     });
   }
+  /**
+   * Returns a proxy object that represents the remote API
+   * Methods called on this proxy will be executed on the remote endpoint
+   * @returns Proxy object representing the remote API
+   */
   getAPI() {
     return this.createNestedProxy();
   }
   /**
-   * Free up the callback map and cache
-   * If you use callbacks a lot, you could get memory leak.
-   * e.g. If you use anonymous callback function in a 5000 iterations loop,
-   * you will get 5000 callbacks in cache. It's a better idea to free them.
-   *
-   * If you use a named callback function, there will be only one entry in the cache.
+   * Frees up memory by clearing stored callbacks and callback cache
+   * Useful when dealing with many anonymous callback functions to prevent memory leaks
    */
   freeCallbacks() {
     this.callbacks = {};

package/dist/browser-mod.d.cts

@@ -1,7 +1,7 @@
-export { a as WorkerChildIO, W as WorkerParentIO } from './worker-ByZFWF48.cjs';
+export { a as WorkerChildIO, W as WorkerParentIO } from './worker-72MNjMgj.cjs';
 export { ChromeBackgroundIO, ChromeContentIO, Message, Response, deserializeMessage, deserializeResponse, generateUUID, serializeMessage, serializeResponse } from './chrome.cjs';
-import { D as DestroyableIoInterface } from './channel-CGr_xSbe.cjs';
-export { I as IoInterface, R as RPCChannel } from './channel-CGr_xSbe.cjs';
+import { D as DestroyableIoInterface } from './channel-D6ZClufP.cjs';
+export { I as IoInterface, R as RPCChannel } from './channel-D6ZClufP.cjs';
 import 'node:buffer';
 
 /**

package/dist/browser-mod.d.ts

@@ -1,7 +1,7 @@
-export { a as WorkerChildIO, W as WorkerParentIO } from './worker-sUTyf1YL.js';
+export { a as WorkerChildIO, W as WorkerParentIO } from './worker-DiYJxxHW.js';
 export { ChromeBackgroundIO, ChromeContentIO, Message, Response, deserializeMessage, deserializeResponse, generateUUID, serializeMessage, serializeResponse } from './chrome.js';
-import { D as DestroyableIoInterface } from './channel-CGr_xSbe.js';
-export { I as IoInterface, R as RPCChannel } from './channel-CGr_xSbe.js';
+import { D as DestroyableIoInterface } from './channel-D6ZClufP.js';
+export { I as IoInterface, R as RPCChannel } from './channel-D6ZClufP.js';
 import 'node:buffer';
 
 /**

package/dist/browser-mod.js

@@ -13,7 +13,7 @@ import {
   generateUUID,
   serializeMessage,
   serializeResponse
-} from "./chunk-ASRFS3R2.js";
+} from "./chunk-ZSSFWNSX.js";
 
 // src/adapters/iframe.ts
 var DESTROY_SIGNAL = "__DESTROY__";

package/dist/channel-D6ZClufP.d.cts

@@ -0,0 +1,128 @@
+import { Buffer } from 'node:buffer';
+
+/**
+ * This file contains the common interface for building a bidirectional communication channel.
+ */
+
+/**
+ * Theoretically, any bidirectional channel with read and write can be used to build a RPC interface.
+ */
+interface IoInterface {
+    name: string;
+    read(): Promise<Buffer | Uint8Array | string | null>;
+    write(data: string): Promise<void>;
+}
+/**
+ * A destroyable IoInterface, mainly for iframe and web worker communication
+ * Used for cleaning up resources, e.g. MessageChannel
+ */
+interface DestroyableIoInterface extends IoInterface {
+    destroy(): void;
+    signalDestroy(): void;
+}
+
+/**
+ * A bidirectional Stdio IPC channel in RPC style.
+ * This allows 2 JS/TS processes to call each other's API like using libraries in RPC style,
+ * without needing to deal with `argv`, `stdin`, `stdout` directly.
+ */
+declare class RPCChannel<LocalAPI extends Record<string, any>, RemoteAPI extends Record<string, any>, Io extends IoInterface = IoInterface> {
+    private io;
+    private pendingRequests;
+    private callbacks;
+    private callbackCache;
+    private count;
+    private messageStr;
+    private apiImplementation?;
+    constructor(io: Io, options?: {
+        expose?: LocalAPI;
+    });
+    /**
+     * Exposes a local API implementation that can be called remotely
+     * @param api The local API implementation to expose
+     */
+    expose(api: LocalAPI): void;
+    /**
+     * Returns the IO interface used by this channel
+     * @returns The IO interface instance
+     */
+    getIO(): Io;
+    /**
+     * Listens for incoming messages on the IO interface
+     * Handles message buffering and parsing
+     * @private
+     */
+    private listen;
+    /**
+     * Handles a single message string by parsing and routing it
+     * @param messageStr The message string to handle
+     * @private
+     */
+    private handleMessageStr;
+    /**
+     * Calls a method on the remote API
+     * @param method The name of the method to call
+     * @param args Arguments to pass to the remote method
+     * @returns Promise that resolves with the result of the remote call
+     */
+    callMethod<T extends keyof RemoteAPI>(method: T, args: any[]): Promise<void>;
+    /**
+     * Handles responses received from remote method calls
+     * @param response The response message to handle
+     * @private
+     */
+    private handleResponse;
+    /**
+     * Handles incoming method call requests from the remote endpoint
+     * @param request The request message to handle
+     * @private
+     */
+    private handleRequest;
+    /**
+     * Invokes a callback on the remote endpoint
+     * @param callbackId The ID of the callback to invoke
+     * @param args Arguments to pass to the callback
+     * @private
+     */
+    private invokeCallback;
+    /**
+     * Handles callback invocations received from the remote endpoint
+     * @param message The callback message to handle
+     * @private
+     */
+    private handleCallback;
+    /**
+     * Sends a successful response back to the remote endpoint
+     * @param id The ID of the request being responded to
+     * @param result The result to send back
+     * @private
+     */
+    private sendResponse;
+    /**
+     * Sends an error response back to the remote endpoint
+     * @param id The ID of the request being responded to
+     * @param error The error message to send back
+     * @private
+     */
+    private sendError;
+    /**
+     * Creates a nested proxy object for chaining remote method calls
+     * @param chain Array of method names in the chain
+     * @returns Proxy object that transforms property access into remote method calls
+     * @private
+     */
+    private createNestedProxy;
+    /**
+     * Returns a proxy object that represents the remote API
+     * Methods called on this proxy will be executed on the remote endpoint
+     * @returns Proxy object representing the remote API
+     */
+    getAPI(): RemoteAPI;
+    /**
+     * Frees up memory by clearing stored callbacks and callback cache
+     * Useful when dealing with many anonymous callback functions to prevent memory leaks
+     */
+    freeCallbacks(): void;
+}
+
+export { type DestroyableIoInterface as D, type IoInterface as I, RPCChannel as R };

package/dist/channel-D6ZClufP.d.ts

@@ -0,0 +1,128 @@
+import { Buffer } from 'node:buffer';
+
+/**
+ * This file contains the common interface for building a bidirectional communication channel.
+ */
+
+/**
+ * Theoretically, any bidirectional channel with read and write can be used to build a RPC interface.
+ */
+interface IoInterface {
+    name: string;
+    read(): Promise<Buffer | Uint8Array | string | null>;
+    write(data: string): Promise<void>;
+}
+/**
+ * A destroyable IoInterface, mainly for iframe and web worker communication
+ * Used for cleaning up resources, e.g. MessageChannel
+ */
+interface DestroyableIoInterface extends IoInterface {
+    destroy(): void;
+    signalDestroy(): void;
+}
+
+/**
+ * A bidirectional Stdio IPC channel in RPC style.
+ * This allows 2 JS/TS processes to call each other's API like using libraries in RPC style,
+ * without needing to deal with `argv`, `stdin`, `stdout` directly.
+ */
+declare class RPCChannel<LocalAPI extends Record<string, any>, RemoteAPI extends Record<string, any>, Io extends IoInterface = IoInterface> {
+    private io;
+    private pendingRequests;
+    private callbacks;
+    private callbackCache;
+    private count;
+    private messageStr;
+    private apiImplementation?;
+    constructor(io: Io, options?: {
+        expose?: LocalAPI;
+    });
+    /**
+     * Exposes a local API implementation that can be called remotely
+     * @param api The local API implementation to expose
+     */
+    expose(api: LocalAPI): void;
+    /**
+     * Returns the IO interface used by this channel
+     * @returns The IO interface instance
+     */
+    getIO(): Io;
+    /**
+     * Listens for incoming messages on the IO interface
+     * Handles message buffering and parsing
+     * @private
+     */
+    private listen;
+    /**
+     * Handles a single message string by parsing and routing it
+     * @param messageStr The message string to handle
+     * @private
+     */
+    private handleMessageStr;
+    /**
+     * Calls a method on the remote API
+     * @param method The name of the method to call
+     * @param args Arguments to pass to the remote method
+     * @returns Promise that resolves with the result of the remote call
+     */
+    callMethod<T extends keyof RemoteAPI>(method: T, args: any[]): Promise<void>;
+    /**
+     * Handles responses received from remote method calls
+     * @param response The response message to handle
+     * @private
+     */
+    private handleResponse;
+    /**
+     * Handles incoming method call requests from the remote endpoint
+     * @param request The request message to handle
+     * @private
+     */
+    private handleRequest;
+    /**
+     * Invokes a callback on the remote endpoint
+     * @param callbackId The ID of the callback to invoke
+     * @param args Arguments to pass to the callback
+     * @private
+     */
+    private invokeCallback;
+    /**
+     * Handles callback invocations received from the remote endpoint
+     * @param message The callback message to handle
+     * @private
+     */
+    private handleCallback;
+    /**
+     * Sends a successful response back to the remote endpoint
+     * @param id The ID of the request being responded to
+     * @param result The result to send back
+     * @private
+     */
+    private sendResponse;
+    /**
+     * Sends an error response back to the remote endpoint
+     * @param id The ID of the request being responded to
+     * @param error The error message to send back
+     * @private
+     */
+    private sendError;
+    /**
+     * Creates a nested proxy object for chaining remote method calls
+     * @param chain Array of method names in the chain
+     * @returns Proxy object that transforms property access into remote method calls
+     * @private
+     */
+    private createNestedProxy;
+    /**
+     * Returns a proxy object that represents the remote API
+     * Methods called on this proxy will be executed on the remote endpoint
+     * @returns Proxy object representing the remote API
+     */
+    getAPI(): RemoteAPI;
+    /**
+     * Frees up memory by clearing stored callbacks and callback cache
+     * Useful when dealing with many anonymous callback functions to prevent memory leaks
+     */
+    freeCallbacks(): void;
+}
+
+export { type DestroyableIoInterface as D, type IoInterface as I, RPCChannel as R };