Package: @observertc/samples-deflate-codec on npm.

The Deflate Codec (@observertc/samples-deflate-codec) compresses successive ClientSample records for live delivery. Use it when repeated fields and sample size matter, and your runtime supports CompressionStream, DecompressionStream, and structuredClone. The documented Node.js minimum is 20; browser deployments need those platform APIs.

How it works#

The first message is a complete snapshot. Later messages contain structural changes, with peer-connection list entries matched by id. A field-name dictionary replaces repeated names with integer codes. Each envelope is independently deflate-compressed into a binary message with a one-byte codec header.

Compression is per message, but reconstruction is stateful: a later delta still depends on earlier samples and dictionary entries. Removed fields and list entries are preserved as removals rather than silently carrying old values forward.

Install and encode a sample#

npm install @observertc/samples-deflate-codec

The following illustrates a round trip for an existing sample and its client identifier. In a real integration, the encoder runs at the sender and the decoder at the receiver:

import {
  ClientSampleEncoder,
  ClientSampleDecoder,
} from '@observertc/samples-deflate-codec';

const encoder = new ClientSampleEncoder({ clientId });
const decoder = new ClientSampleDecoder();

const bytes = await encoder.encode(sample);
const decodedSample = await decoder.decode(bytes);

encode() and decode() are asynchronous. Process operations sequentially and preserve message order. encodeToBase64() and decodeBase64() support text-only transports. Decode to a complete sample before passing it to Observer; Observer does not accept compressed messages directly.

Preserve stream state#

• Keep one decoder per encoder/client stream.
• Use ordered, lossless delivery. An unreliable data channel is insufficient without your own recovery protocol.
• Reset both halves at the same stream boundary after reconnecting or starting a new receiver. The next encoded message is a snapshot.
• Treat decode failures as errors to investigate; do not continue as if the missing sample were successfully reconstructed.

tryDecode() returns a success/error result instead of throwing. DeflateCodecError exposes a code and context, including invalid input, unsupported options, or stream desynchronization. The decoded sample is independent of the decoder’s retained state, so downstream mutation does not change that state.

Choosing a codec#

Choose JSON Codec for readable delta messages, Protobuf Codec for its binary format, or Deflate Codec for dictionary-coded deltas with platform compression. Deflate has its own structural diff; it is not simply the JSON Codec with compression switched on. Measure your own streams before choosing a format.

The Deflate Codec package version is 3.7.0. Package version, sample schema version, and wire-envelope version are separate contracts; do not assume identical version numbers mean interchangeable wire formats.

Sources: usage and format, package and runtime requirements, and round-trip tests.