# @nodescript/protocomm

> Bi-directional transport-agnostic JSON-based messaging

Latest version **1.2.0** (published 2025-02-12) · ISC license · 0 weekly downloads

## Install

```sh
npm install @nodescript/protocomm
pnpm add @nodescript/protocomm
yarn add @nodescript/protocomm
bun add @nodescript/protocomm
```

## Health

**Score 30/100 (F)** — status: maintenance-mode.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.2.0 |
| Published | 2025-02-12 |
| First published | 2022-06-15 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | ESM |
| Node | >=18 |
| Dependencies | 2 |
| Unpacked size | 41.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | UBIO |
| Maintainers | inca, danielolaviobr, mattscarthsaunders |
| Keywords | protocol |

## Links

- npm: https://www.npmjs.com/package/@nodescript/protocomm
- Repository: https://github.com/nodescript/protocomm
- Homepage: https://github.com/nodescript/protocomm#readme
- Issues: https://github.com/nodescript/protocomm/issues
- npm.io page: https://npm.io/package/@nodescript/protocomm

## Dependencies (2)

- [airtight](https://npm.io/package/airtight.md) ^5.7.2
- [nanoevent](https://npm.io/package/nanoevent.md) ^1.0.0

## Recent versions

- 1.2.0 (latest) — 2025-02-12
- 1.1.0 — 2024-07-12
- 1.0.2 — 2024-05-17
- 1.0.1 — 2024-05-17
- 1.0.0 — 2023-09-18
- 0.7.0 — 2023-07-13
- 0.6.4 — 2023-07-13
- 0.6.3 — 2023-06-09
- 0.6.2 — 2023-03-15
- 0.6.1 — 2023-02-21
- 0.6.0 — 2023-02-21
- 0.5.5 — 2022-12-15
- 0.5.4 — 2022-12-15
- 0.5.3 — 2022-12-08
- 0.5.2 — 2022-11-29
- … 7 more at https://npm.io/package/@nodescript/protocomm/versions

## README

# Protocomm

Bi-directional transport-agnostic JSON-based messaging.

**Status:** experimental, subject to change.

## Introduction

In software engineering communication protocols are defined as formal rules for transmitting the information. Modern systems tend to deal with application-level protocols such as HTTP which are already considered high level in the [OSI stack](https://en.wikipedia.org/wiki/OSI_model). However, in practice the need often arises for implementing even more application- or domain-specific protocols on top of the existing ones.

One widely known example would be a typical RESTful API which is in fact a protocol between the application server providing the functionality and the frontend application using such functionality.

Protocols aren't cheap. Good protocols try to address a lot of concerns and have to deal with a fair amounts of trade-offs. This drives a lot of initiatives to further standardize the application protocols written on top of other application protocols (e.g. Swagger/OpenAPI, JSON-RPC, gRPC-over-HTTP, etc). Such initiatives oftentimes have different goals, limitations and implications.

This library is one such initiative with following key considerations:

- It is designed for modern web applications written in TypeScript.
- Such applications may consist of many different components "talking" to each other.
- Such components may or may not exist in the same runtime/process/node. They may or may not have networking layer to communicate over.
- Some example of communications:
    - frontend application talking to a backend via HTTP (i.e. your typical webapp)
    - frontend application sending requests to a backend via WebSocket and receiving the responses and events asynchronously
    - a web page sending and receiving messages to/from the isolated iframe
    - multiple processes communicating with each other using IPC
    - two different systems talking to each other via TCP
- Protocols need to be transport-agnostic. The transport is abstracted as a readable/writeable streams. Protocomm will take care of serializing and deserializing the payloads.
- Protocols should be fully typesafe on both sides of the communication. We rely on TypeScript to provide both Client and Handler with compile-time type safety guarantees.
- Protocol messages and payload need to be validated in runtime. Runtime validation should fully correspond to compile-time validation.
- Protocol messages should have a reasonable strategy for dealing with protocol evolution.
- It should be possible to generate the documentation from the protocol definitions.

Protocomm is loosely based on [JSON-RPC](https://en.wikipedia.org/wiki/JSON-RPC) and is inspired by [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) and [Protobuf](https://developers.google.com/protocol-buffers).

## Concepts

- Communication always happen between a **Client** and a **Handler**.

    Their roles in a particular communication are not equal: client is always an initiator, and the handler is typically expected to handle multiple clients (although this is not enforced in any way).

- **Protocol** is an interface that both Client and Handler need to adhere to. It consists of one or more **domains**.

- **Domain** is an interface that defines **methods** and **events**.

- Each domain needs a corresponding **Domain Definition** — a static JSON object with metadata available in runtime. It describes the schema of methods and events and is used to automatically generate the client, validate the payloads, as well as for other meta purposes (such as documentation).

- **Protocol Index** is a collection of Domain Definition objects, corresponding to a particular protocol.

A protocol is typically implemented as a standalone isomorphic package shared between both parties and contains type definitions, schema and domain definitions of all entities and DTOs used in communication. Such package is then used on the "backend" side to implement the necessary functionality and on the "consumer" side to generate the client.

## Usage

Please refer to the [tests setup](src/test) for an example of fictional service. More examples are under construction.

---
_Source: https://npm.io/package/@nodescript/protocomm · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._