This document provides a high-level introduction to the comctx library, explaining its purpose as a cross-context RPC communication framework and its core architecture. For specific implementation details of the core API, see Core API. For detailed adapter implementations, see Adapter Implementations. For step-by-step usage instructions, see Installation and Quick Start.
Comctx is a lightweight RPC (Remote Procedure Call) library that enables transparent method invocation across different JavaScript execution contexts. It provides a unified API for communication between web workers, browser extensions, iframes, Electron processes, and other isolated JavaScript environments. README.md1-5
The library solves the fundamental challenge of cross-context communication by abstracting transport mechanisms through an adapter pattern, allowing developers to write context-agnostic service definitions that work across any environment. README.md11-15
Sources: README.md1-15 package.json1-7
JavaScript applications frequently need to communicate across isolated execution contexts. However, each environment provides different communication APIs:
| Environment | Communication API | Limitations |
|---|---|---|
| Web Workers | Worker.postMessage() | Dedicated worker instance |
| Shared Workers | SharedWorker.port.postMessage() | Requires MessagePort |
| Browser Extensions | browser.runtime.sendMessage() | Extension-specific API |
| iframes | window.postMessage() | Requires window reference |
| Electron | ipcMain/ipcRenderer | Process-specific |
| Service Workers | clients.claim() + messaging | Client-based routing |
Existing solutions like Comlink are tightly coupled to MessagePort-based communication, making adaptation to other environments difficult (e.g., Comlink Issue 438). Comctx decouples RPC logic from transport mechanisms through the Adapter interface. README.md11-15
Sources: README.md11-15
The comctx architecture consists of three primary layers: the proxy definition layer (defineProxy), the adapter abstraction layer (Adapter interface), and the message protocol layer.
The defineProxy function creates matched provide and inject functions that share a namespace. The provider side exposes the actual service instance, while the injector side receives a Proxy object that forwards method calls through the adapter. README.md33-65
Sources: README.md33-65 README.md199-211
The following diagram maps the conceptual components to their actual implementations in the codebase:
Sources: README.md67-83 README.md199-211 CHANGELOG.md25
The following diagram illustrates the complete RPC flow from injector to provider, showing the actual message types and functions involved:
When the injector calls a method on the proxy, the Proxy.apply trap intercepts the call, creates a Message with type APPLY, and sends it through the adapter's sendMessage method. The provider's adapter receives the message via its onMessage callback, validates it using checkMessage, invokes the actual method, and sends back a response message. README.md99-112
Sources: README.md99-112 README.md283-300
The defineProxy function is the primary entry point for creating RPC service pairs. README.md33-65
Parameters:
factory: Function that creates the service instance (executed only on provider side).options.namespace: Unique string identifier for message routing.options.heartbeatCheck: Enable PING/PONG connection monitoring (default: true). README.md27options.heartbeatInterval: Heartbeat frequency in milliseconds (default: 5000).options.heartbeatTimeout: Connection timeout in milliseconds (default: 30000). CHANGELOG.md128options.transfer: Auto-extract transferable objects for zero-copy transfer (default: false). README.md152-175options.backup: Create static backup instance on injector for Reflect.has support (default: false). README.md118Returns:
provide: Function that registers service on provider side and returns original instance.inject: Function that creates Proxy on injector side.Sources: README.md33-65 README.md118 README.md158-183 CHANGELOG.md128
Every environment adapter must implement the Adapter interface. README.md67-83
| Method | Type | Description |
|---|---|---|
sendMessage | SendMessage | Send message to remote context. |
onMessage | OnMessage | Register message listener, return cleanup function. |
The Message structure includes metadata like type (MessageType enum), id, path, sender, and namespace. CHANGELOG.md72
Sources: README.md67-83 CHANGELOG.md72
transfer: true is enabled, transferable objects (ArrayBuffer, ReadableStream, etc.) are automatically extracted and transferred. README.md24 README.md152-175Sources: README.md20-27 README.md152-175
| Aspect | Comctx | Comlink |
|---|---|---|
| Bundle Size | ~1KB gzipped | ~4KB gzipped |
| Transport Abstraction | Adapter interface | MessagePort-based |
| Environment Support | Any (via adapters) | MessagePort-compatible only |
| Transferable Objects | Auto-extraction with transfer: true | Manual Comlink.transfer() |
| Connection Management | Built-in heartbeat | Manual implementation required |
Comctx's adapter-based architecture makes it easier to support environments that don't natively provide MessagePort, such as browser extensions using browser.runtime APIs. README.md11-15
Sources: README.md11-15