GitHub - cognitect/transit-js: Transit for JavaScript (original) (raw)

transit-js

Transit is a data format and a set of libraries for conveying values between applications written in different languages. This library provides support for marshalling Transit data to/from JavaScript. transit-js will work with anyECMAScript-262 Edition 3or newer JavaScript implementation provided that a JSONmodule that supplies parse and stringify methods is present. transit-js does not currently support encoding to MessagePack. Unlike the Java and Clojure implementations it relies on the non-streaming JSON parsing mechanism of the host JavaScript environment.

• Rationale
• Getting Started, Get up and running ASAP
• API docs
• Specification
• Take a tour!
• FAQ, for common transit-js specific questions

This implementation's major.minor version number corresponds to the version of the Transit specification it supports.

NOTE: Transit is intended primarily as a wire protocol for transferring data between applications. If storing Transit data durably, readers and writers are expected to use the same version of Transit and you are responsible for migrating/transforming/re-storing that data when and if the transit format changes.

Releases and Dependency Information

• Latest release: 0.8.874
• All Released Versions

JavaScript

You can include either therelease (10K gzipped) or development build of transit-js on your webpage. We also provide Require.jscompatiblerelease anddev builds.

Node.js

transit-js is released to npm. Add transit-js to yourpackage.json dependencies:

{... "dependencies": { "transit-js": "0.8.874" } ...}

Bower

You can also include transit-js in your bower.json dependencies:

{... "dependencies": { "transit-js": "0.8.874" } ...}

Maven

Maven dependency information:

Documentation

Comprehensive documentation can be found here.

Overview

transit-js supports the conveyance of semantically rich and extensible data between heterogenous software systems whose components include JavaScript servers and clients.

Beyond JSON

The Transit rationale covers many of the reasons to put aside the limitations of JSON. As with the other Transit implementations, transit-js supports conveying a larger range of scalar and non-scalar values than permitted by JSON. Of these types, the transit-js handling of the map representation is the most novel from the perspective of a JavaScript applications developer.

Transit Maps

Transit representations of maps are decoded by transit-js into a high performance data structure that largely mirrors the ECMAScript Edition 6 Mapdata type. Doing so allows natural indexing of data using common scalars like 64 bit integers and dates without requiring the out of band application logic often encountered in systems that marshal JSON.

The adaptive implementation of transit-js maps delivers performance comparable to plain JavaScript objects and native ES6 Map implementations.

Usage

Please see the Getting Started page. For an interactive guide check out thetour.

From the browser transit-js is available at the top level:

var t = transit;

function roundtrip(x) { var r = t.reader("json"), w = t.writer("json"); return r.read(w.write(x)); }

function testRoundtrip() { var arr1 = ["red", "green", "blue"], arr2 = ["apple", "pear", "grape"], data = t.map(); data.set(t.integer(1), arr1); data.set(t.integer(2), arr2); return t.equals(data, roundtrip(data)); }

From Node.js you must require transit-js (assuming you've included it in your project dependencies):

var t = require("transit-js");

function roundtrip(x) { var r = t.reader("json"), w = t.writer("json"); return r.read(w.write(x)); }

function testRoundtrip() { var arr1 = ["red", "green", "blue"], arr2 = ["apple", "pear", "grape"], data = t.map(); data.set(t.integer(1), arr1); data.set(t.integer(2), arr2); return t.equals(data, roundtrip(data)); }

Default Type Mapping

Abbreviations:

• t = transit

Contributing

This library is open source, developed internally by Cognitect. We welcome discussions of potential problems and enhancement suggestions on thetransit-format mailing list. Issues can be filed using GitHub issues for this project. Because transit is incorporated into products and client projects, we prefer to do development internally and are not accepting pull requests or patches.

Development

Dependencies

Building and testing transit-js requiresNode.js. Install the project's additional development dependencies with the following command from the repo directory:

In order to build transit-js forClojureScript,Maven must be installed.

Running the tests

In order to run the bin/verify tests fromtransit-format, you must first clone transit-format into the same parent directory as your transit-js checkout. Then build the production Node.js build:

Build

Version

The build version is automatically incremented. To determine the current build version:

Build for Node.js

Build for Browser

bin/build_release_browser

Building the documentation

Build JAR for ClojureScript

Assuming you have aJDKand Maven installed, the following will install a JAR suitable for use from ClojureScript into your local Maven repository.

Copyright and License

Copyright © 2014-2020 Cognitect

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.