TypeScript icon, indicating that this package has built-in type declarations

1.1.1 • Public • Published

UBJSON encoder/decoder

npm npm bundle size (minified + gzip) Bitbucket Pipelines Codecov

Lightweight, quick and dirty UBJSON encoder/decoder for the browser and node.js.

This library implements Universal Binary JSON Draft 12 encoder/decoder in JavaScript.

There are some changes between unstable versions and version 1.0.0. Please have a look at the CHANGELOG.md.

Encoding and decoding working as far as I know. If you encounter an bug, please create an issue.

Example (browser)

import { Ubjson } from '@shelacek/ubjson';
const buffer = Ubjson.encode({ hello: 'world', from: ['UBJSON'] });
const obj = Ubjson.decode(buffer);
console.log(obj); // { hello: 'world', from: ['UBJSON'] }

Example (node.js)

const ubjson = require('@shelacek/ubjson');
const buffer = ubjson.encode({ hello: 'world', from: ['UBJSON'] });
const obj = ubjson.decode(buffer);
console.log(obj); // { hello: 'world', from: ['UBJSON'] }


Note: For full API and exported symbols, please see typings at https://bitbucket.org/shelacek/ubjson/src/master/src/ubjson.d.ts.

Ubjson.encode(value, [options])

  • value: any - input value/object/array to serialize.
  • options: Object (optional) - encoding options.
    • options.optimizeArrays: boolean | 'onlyTypedArrays' (default false) - enable use optimized format for arrays. If 'onlyTypedArrays' is used, only TypedArrays use strongly typed container.
    • options.optimizeObjects: boolean (default false) - enable use optimized format for objects.

Method returns ArrayBuffer with UBJSON data.

Ubjson.decode(buffer, [options])

  • buffer: ArrayBuffer - input buffer with UBJSON data.
  • options: Object (optional) - decoding options.
    • options.int64Handling: 'error' | 'skip' | 'raw' | UbjsonDecoderCustomHandler (default error) - Handling of unsupported int64 values. 'error' throws exception, 'skip' ignore that value (or key/value pair) and 'raw' returns Uint8Array with int64 bytes.
    • options.highPrecisionNumberHandling: 'error' | 'skip' | 'raw' | UbjsonDecoderCustomHandler (default error) - Handling of unsupported high-precision numbers. 'error' throws exception, 'skip' ignore that value (or key/value pair) and 'raw' returns string represents of that number.
    • options.useTypedArrays: boolean (default false) - enable use of TypedArrays for strongly typed containers.

Method returns decoded UBJSON value/object/array (any).

UbjsonDecoderCustomHandler is function:

(storage: { array: Uint8Array, view: DataView }, offset: number, byteLength: number) => UbjsonValue;


Javascript not support 64-bit integers (yet) and high-precision numbers as well as the library. You can use 'raw' option in int64Handling/highPrecisionNumberHandling to retrive original data or custom handling function.


The library needs a TextEncoder and TextDecoder (or util.TextEncoder/util.TextDecoder on node.js), support for TypedArrays and class keyword. Library should work on Firefox >=45, Chrome >=49, Safari >=10.1, Opera >=36, Node >=8.11.3. Edge needs TextEncoder/TextDecoder polyfill.

In case of interest, I can reduce requirements.


There are some great alternatives:

[Please correct me if this information is obsolete or wrong.]

This library was created because I needed to work with UBJSON in browser - and there are no reasonable draft 12 implementation :-(.

Package Sidebar


npm i @shelacek/ubjson

Weekly Downloads






Unpacked Size

65.9 kB

Total Files


Last publish


  • shelacek