Comctx is a cross-context RPC (Remote Procedure Call) communication library that enables type-safe, bidirectional communication between different JavaScript execution contexts. The library provides a unified interface for communicating across Web Workers, Browser Extensions, iframes, Service Workers, and other isolated JavaScript environments.
This document provides an architectural overview of the Comctx library, covering its core components, communication patterns, and example implementations. For detailed API documentation, see Core API. For information about specific adapter implementations, see Example Applications. For development workflows and project setup, see Development Guide.
Comctx follows a factory pattern centered around the defineProxy function, which generates provider and injector functions for establishing RPC communication between contexts. The architecture is built on three main pillars: a proxy factory system, an adapter interface for environment abstraction, and a message protocol for reliable communication.
Sources: README.md11-28 README.md33-65 package.json2-4
The defineProxy function serves as the central factory for creating RPC communication pairs. It accepts a service factory function and configuration options, returning a tuple of [provideProxy, injectProxy] functions that establish the provider-consumer relationship.
Sources: README.md62-64 README.md87 README.md112
The adapter system abstracts communication mechanisms across different JavaScript environments. Each adapter implements the Adapter interface with sendMessage and onMessage methods, enabling environment-agnostic communication.
Sources: README.md225-232 README.md249-287 README.md327-375
The communication flow in Comctx follows a request-response pattern with support for callbacks and transferable objects. The provider hosts the actual service instance, while the injector creates a proxy that forwards method calls across the communication boundary.
Sources: README.md114-120 README.md69-90 README.md95-110
Comctx includes comprehensive example applications demonstrating usage across different JavaScript contexts. Each example follows a consistent pattern with shared service definitions and context-specific adapters.
Sources: README.md236-242 examples/browser-extension/package.json4 examples/web-worker/package.json4 examples/iframe/package.json4 examples/service-worker/package.json4
The project follows a monorepo structure with pnpm workspaces, separating the core library from example applications and development tooling.
Sources: package.json6-25 pnpm-lock.yaml73-141 CHANGELOG.md1-159