arrow-code

Arrow Code

Arrow Code use unicode combining character "͢ " in string to store types that normally not allowed in JSON

examples

// import Arrow from 'arrow-code';
const Arrow = require('arrow-code').default;

// encode as JSON
Arrow.encodeJSON( [
  NaN,
  -Infinity, 
  9007199254740997n,
  new Date(),
  new Uint8Array([1,2,3,4]), 
  undefined
], 1);
// returns:
[
 "͢NaN",
 "͢-Inf",
 "͢n:9007199254740997",  // BigInt
 "͢Date:2018-02-07T19:07:18.207Z",  // Date
 "͢Bin:wFg{A",  // Uint8Array
 "͢"  // undefined
]

Advantage

(Arrow.encodeJSON vs MsgPack and BSON)

Arrow Code allows additional data types to be serialized in JSON, such as binary date (Uint8Array) and Date, while still keeps the verbose nature of JSON.
The output string is still a 100% valid JSON, and compatible with any JSON editing/parsing tool or library. This makes Arrow Code much easier to debug and trouble shoot than binary formats like BSON and MsgPack

Performance

Modern browsers and nodejs are highly optimized for JSON. This allows Arrow Code to be encoded and decoded faster than the other 2 formats in most of the cases.

benchmark result

Benchmark with sample data on Chrome 77, Firefox 69

Time are all in ms, smaller is better

	Chrome Encode	Chrome Decode	Firefox Encode	Firefox Decode
Arrow Code	0.1434	0.1742	0.1708	0.1301
MsgPack	0.2893	0.1818	0.6689	0.1933
BSON	0.1573	0.1879	0.3945	0.5648

Constructor

new Arrow({
  // whether to encode Binary ( Uint8Array ), default true, which uses Base93 encoding
  encodeBinary?: boolean | 'base64',

  // whether to encode Date, default true
  encodeDate?: boolean,

  // whether to encode BigInt, default true
  encodeBigInt?: boolean,
})

API

API	comments
encodeJSON( inpt: unknown, space?: number, sortKeys = false)	encode as JSON, can be used as static api
decodeJSON( inpt: string)	decode JSON, can be used as static api
encode( inpt: unknown)	encode to String, can be used as static api
decode( inpt: string)	decode String, can be used as static api
register( key: string, type: Constructor, encoder, decoder)	register a custom type

Custom Types

Arrow Code's register API make it really easy to add custom type

// custom type
class MyClass {
  constructor(str) {
    this.myStr = str;
  }
}

let arrow = new Arrow();
arrow.register(
  'My', // prefix
  MyClass,  // type
  (obj) => obj.myStr, // custom encoder
  (str) => new MyClass(str) // custom decoder
);

myJson.encodeJSON(new MyClass("hello"));
// "͢My:hello"

Base93 encoding

Arrow Code use Base93 by default to encode binary data, it's more compact than Base64.

If you prefer Base64, set binaryFormat to base64 in the Arrow Code constructor

const Arrow = require('arrow-code').default;

// use Base64 instead of Base93
const arrow = new Arrow({binaryFormat: 'base64'});

arrow.encodeJSON({binary: new Uint8Array([1,2,3,4])});
// {"binary":"͢B64:AQIDBA=="}