transit-js

transit-js is Cognitect’s JavaScript implementation of Transit, a self-describing data-interchange format for conveying values between applications written in different languages. It marshals rich data types to and from Transit’s JSON-based encoding, preserving semantics that plain JSON loses, such as maps with composite keys, sets, keywords, symbols, and typed scalars.

Built on the host environment’s JSON parser, transit-js works in browsers and Node.js and interoperates with the Transit implementations for Clojure, Java, Ruby, Python, and others. It provides readers and writers plus a handler system for registering custom types, making it a natural serialization layer for ClojureScript and polyglot systems.

What You Get

• Transit readers and writers for encoding and decoding JavaScript values
• Support for rich types JSON cannot represent: maps with composite keys, sets, keywords, symbols, and typed scalars
• A handler system for registering custom read/write handlers for application types
• Interoperability with Transit implementations in Clojure, Java, Ruby, Python, and more
• Equality and hashing helpers for Transit value types

Common Use Cases

• Serializing ClojureScript/JavaScript data for exchange with a Clojure or Java backend
• Preserving rich data semantics (sets, keyword keys) across service boundaries
• Registering custom handlers to serialize domain-specific types
• Interchanging data between polyglot services using a shared Transit format

Under The Hood

Architecture - The implementation lives under src/com/cognitect/transit/, split into a public entry point (transit.js, plus an AMD variant) and an impl/ layer with a reader, writer, and decoder. Supporting modules cover the core value types (types.js), read/write handlers (handlers.js), caching of repeated keys (caching.js), delimiters, equality (eq.js), and utilities. Encoding is layered: handlers map application values to Transit’s ground types, the writer emits the JSON representation, and the reader/decoder reverse the process, with a caching layer compressing repeated map keys and tags.

Tech Stack - Plain JavaScript targeting ECMAScript 3+ with zero runtime dependencies, relying on the host environment’s JSON parse/stringify. The build uses Grunt with concat and uglify to produce distributable bundles (Gruntfile.js), jshint for linting, and nodeunit for tests; a pom.xml and Google Closure resources support the original Clojure-based build lineage. Distribution artifacts are checked into build/.

Code Quality - The code is mature and stable (version 0.8.x, last touched in 2024, otherwise inactive) with a consolidated test suite in test/tests.js run via nodeunit, plus benchmarks under bench/. The namespaced com/cognitect directory layout mirrors the Java/Clojure Transit implementations, reflecting a deliberately consistent cross-language design rather than idiomatic modern JS module structure.

API Design - The public API is small: transit.reader(‘json’) and transit.writer(‘json’) produce objects whose read()/write() methods convert between strings and values, and transit.map, transit.set, and transit.keyword construct the rich types. Registering custom handlers requires understanding the Transit ground-type model and tag system, which raises the learning curve for advanced use, but basic encode/decode is straightforward once the reader/writer pattern is grasped.