Examples

The Twilic Examples repository is a collection of runnable projects that show how Twilic works in real applications. Each example compares payload sizes against JSON and MessagePack where useful, and demonstrates a specific profile or encoding pattern.

Use these examples to evaluate Twilic before adopting it, or as starting points for your own integrations.

Prerequisites

• Node.js 24+
• pnpm (recommended)

Setup

Clone the repository and install dependencies:

git clone https://github.com/twilic/examples.git
cd examples
pnpm install

Overview

Example	Profile	Command
API response	Stateless Batch	pnpm example:api-response
HTTP round-trip	Stateless Dynamic	pnpm example:http-roundtrip
WebSocket session	Stateful	pnpm example:websocket:simulate
Batch records	Batch	pnpm example:batch-records
Telemetry	Batch (col_batch)	pnpm example:telemetry
Logs	Dynamic + Batch	pnpm example:logs
Cache payload	Dynamic (stateless)	pnpm example:cache-payload

API Response

Return paginated user lists as compact Twilic batch payloads over HTTP.

Profile: Stateless Batch — encodeBatch with shape and string interning across same-shape records.

Run

# terminal 1
pnpm example:api-response

# terminal 2
pnpm example:api-response:client

Endpoints

Route	Format
GET /users	Twilic batch (application/vnd.twilic)
GET /users.json	JSON (size comparison)

What it shows

50 user records with 8 fields each. Field names are sent once; repeated strings like "admin" and "us-east" are interned. The server prints a size table on startup; the client compares Twilic vs JSON byte counts.

The server is a small Hono app that sets Content-Type: application/vnd.twilic on the batch response. The client uses @twilic/fetch plus decode() for the size comparison.

When this fits

• REST list endpoints with repeated object shapes
• Mobile or edge clients that fetch many pages
• APIs where bandwidth matters more than human-readable JSON

Use stateless Dynamic or Batch profiles for HTTP. Stateful session compression requires an ordered stream and is not used here. :::

See also: Cookbook — API Response with Repeated Structure.

HTTP Round-Trip

POST Twilic bodies with the official HTTP adapters — Express, Hono, or Fastify on the server; fetch or Axios on the client.

Profile: Stateless Dynamic.

Run

# terminal 1 — pick one server
pnpm example:http-roundtrip
pnpm example:http-roundtrip:hono
pnpm example:http-roundtrip:fastify

# terminal 2 — pick one client
pnpm example:http-roundtrip:client
pnpm example:http-roundtrip:axios

Endpoint

Route	Format
POST /echo	Twilic request and response (application/vnd.twilic)

What it shows

• Server: twilicParser() + twilicSend / twilicResponse / twilicReply
• Client: twilicFetchJson({ twilicBody }) or createTwilicAxios with twilicBody
• Echo payload { ok, via, received } so you can see which server handled the call

When this fits

• Internal service-to-service APIs
• Dropping Twilic into an existing Express / Hono / Fastify route
• Pairing a Node server with a browser or Node client helper

See also: Web Integrations, Integrations overview.

WebSocket Session

Stream live dashboard metrics over WebSocket with stateful Twilic compression.

Profile: Stateful — createSessionEncoder() with encode() for the first frame and encodePatch() when only a few fields change.

Run

Simulation (size comparison, recommended first):

pnpm example:websocket:simulate

Live WebSocket demo:

# terminal 1
pnpm example:websocket

# terminal 2
pnpm example:websocket:client

What it shows

• simulate.ts — 20 ticks of dashboard metrics; compares JSON, full encode(), and encodePatch() sizes per tick
• server.ts — sends binary frames every second; first tick is full, later ticks use patches
• client.ts — logs frame sizes and decodes when possible

When this fits

• Live dashboards and game state
• Ordered, reliable streams where most fields stay stable
• Scenarios where 2–3 of 15 fields change per update

Session recovery

Call session.reset() after a disconnect so the next frame is a full stateless message, then resume patching.

JS SDK note The current @twilic/core SDK exposes session encode APIs. Patch frame decoding on the client may require a matching session decoder in your language SDK. Use simulate.ts to evaluate payload savings; treat the WebSocket demo as a binary transport example. :::

See also: Cookbook — WebSocket Streaming.

Batch Records

Send many homogeneous records in one payload using Twilic batch encoding.

Profile: Batch — encodeBatch picks row_batch for smaller same-shape sets and col_batch for larger tabular data.

Run

pnpm example:batch-records

What it shows

1. 64 same-shape records — row batch with shape interning
2. 256 telemetry-shaped records — column batch with per-column codecs

Each scenario prints encoded sizes for JSON, MessagePack, and Twilic.

When this fits

• Bulk exports and queue messages
• API endpoints that return many records at once
• Pipelines that flush records in groups instead of one-by-one

Telemetry

Batch high-frequency telemetry events with column-oriented compression.

Profile: Batch — col_batch compresses each column independently (DELTA_BITPACK, RLE, etc.).

Run

pnpm example:telemetry

What it shows

Telemetry events with repeated service and level values, batched at 16, 64, and 256 records. The script prints JSON, MessagePack, and Twilic sizes for each batch size.

When this fits

• Metrics and observability pipelines
• Time series with stable field shapes
• Throughput-optimized ingestion where larger batches are acceptable

Batch size tuning

• 16–64 records — lower latency per flush
• 256+ records — better compression on numeric and enum-like columns

See also: Cookbook — Telemetry Pipeline.

Logs

Structured log shipping with string and shape interning.

Profile: Dynamic + Batch — repeated level, service, and field names compress well when events are grouped.

Run

pnpm example:logs

What it shows

1,000 structured log events compared as:

• NDJSON (one JSON object per line)
• Twilic encode per event
• Twilic encodeBatch in 100-event flushes
• Twilic encodeMicroBatch in 50-event bursts

When this fits

• Log agents that flush on an interval
• Bursty application logging
• Pipelines where the same strings appear across many events

Trade-off

Per-event encoding is simple but repeats field names and common strings. Batching or micro-batching amortizes that overhead across each flush.

Cache Payload

Store compact binary session blobs in a key-value cache.

Profile: Dynamic (stateless) — each value is encoded independently with encode and decoded with decode.

Run

pnpm example:cache-payload

What it shows

100 user session objects stored in an in-memory Map<string, Uint8Array>, with total size compared against JSON strings. A roundtrip decode verifies data integrity.

When this fits

• Redis, Memcached, or CDN edge caches
• Session stores with stable object shapes
• Config snapshots that are read more often than they change

Use stateless encoding per cache key. Stateful session compression is for ordered streams, not unrelated KV entries. :::

When Twilic Fits Well

Twilic is designed for data with repeated patterns. It can be a good fit when:

• Many messages share the same object shape
• The same strings appear repeatedly
• Records are sent in batches
• Only small changes need to be sent after the first message

These examples make the trade-offs visible so you can choose Twilic for the right use cases. Twilic is not intended to replace every serialization format in every situation.

Related resources

Resource	Description
Cookbook	Practical patterns with code snippets across languages
Playground	Interactive size comparison in the browser
Benchmark	Encode/decode throughput measurements
@twilic/core	JavaScript / TypeScript SDK used by all examples

Source

github.com/twilic/examples