JSON-RPC over postMessage
npm install channel-rpcpostMessage
Channel-rpc is a TypeScript library that simplifies JSON-RPC communication between different windows or iframes using the postMessage API. This library is designed to make inter-window communication a breeze, ensuring that only windows with matching channelId can exchange data and optionally validating the allowed origins.
- Simple and Lightweight: A minimalistic library that abstracts away the complexities of postMessage and JSON-RPC.
- Strongly Typed: Leverages TypeScript to ensure type safety in your communications.
- Secure: Channels can only communicate with windows or iframes having the same channelId, and optionally validate the allowed origins.
- Controlled Communication: Utilize the start() and stop() methods to manage when the server accepts messages.
- Error Handling: Error responses from client.stub conform to the JSON-RPC standard, including well-defined error codes and messages.
To get started with channel-rpc, you can install it via npm:
``shell`
npm install channel-rpc
`typescript
import { ChannelServer } from "channel-rpc";
// Define your message handlers
const handler = {
add: (a: number, b: number): number => a + b,
};
// Create a ChannelServer instance
const server = new ChannelServer({
channelId: "channel-1", // Must match the channelId in the child window
handler: handler, // Your message handler
allowOrigins: ["https://yourwebsite.com", "https://anotherwebsite.com"], // Optional allowed origins
});
// Start accepting messages
server.start();
export type HandlerType = typeof handler;
`
`typescript
import { ChannelClient, ChannelErrors } from "channel-rpc";
import type { HandlerType } from "./main.ts";
// Create a ChannelClient instance
const client = new ChannelClient({
target: window.top,
channel: "channel-1", // Must match the channelId in the main window
});
// Use the stub to call methods on the main window
try {
const result = await client.stub.add(2, 3);
} catch (error) {
if (error.code === ChannelErrors.MethodNotFound.code) {
// Handle the "Method not found" error
} else if (error.code === ChannelErrors.InvalidRequest.code) {
// Handle the "Invalid Request" error
}
}
`
- channelId (string): A unique identifier for the channel.handler
- (object): The message handler object.allowOrigins
- (string[], optional): An array of allowed origins.start()
- : Starts accepting messages.stop()
- : Stops accepting messages.
- target (Window): The target window for communication.channel
- (string): The channel identifier to match with the main window.
- InvalidRequest: Error object representing an "Invalid Request."MethodNotFound
- : Error object representing a "Method not found."InternalError
- : Error object representing an "Internal error."Timeout
- : Error object representing a "Timeout."
This project is licensed under the MIT License. See the LICENSE file for details.
To get started with channel-rpc, follow the installation and usage instructions provided above. Explore the examples folder for more usage examples.
If you encounter any issues or have questions, please open an issue. We're here to help!
Check out the Release Notes for information on the latest updates and features.
- kouhin
Give channel-rpc` a try, and simplify your inter-window communication in web applications. We look forward to your feedback and contributions!