@bare-ts/tools

A TypeScript code generator for the BARE binary format

Binary Application Record Encoding (BARE) is a schema-based binary format that favors compactness and composability. @bare-ts/tools provides a compiler to generate Typescript and JavaScript codes from a BARE schema.

Warning: BARE specification is currently an IEF draft. The specification is now pretty stable. However, it may still evolve before its final release.

Getting started

First, install @bare-ts/tools and @bare-ts/lib:

npm install --save-dev @bare-ts/tools
npm install @bare-ts/lib

• @bare-ts/tools enables to generate decoders and encoders from a schema

• @bare-ts/lib provides basic decoders and encoders

Alternatively, you can download a bundled and executable version of @bare-ts/tools named bare in the section Assets of every release on GitHub.

Then, write a schema:

type Gender enum {
    FEMALE
    FLUID
    MALE
}

type Person struct {
    name: str
    email: str
    gender: optional<Gender>
}

type Organization struct {
    name: str
    email: str
}

type Contact union { Person | Organization }

type Contacts list<Contact>

Compile your schema into code:

bare schema.bare --out=code.ts

Once the code is generated, encode and decode messages:

import { Gender, decodeContacts, encodeContacts } from "./code.js"
import { strict } from "node:assert"

const contacts = [
    {
        tag: "Person",
        val: {
            name: "Seldon",
            email: "[e-mail]",
            gender: Gender.Male,
        },
    },
]

const payload = encodeContacts(contacts)
const contacts2 = decodeContacts(payload)

strict.deepEqual(contacts, contacts2)

Refer to our types documentation page to find the correspondence between BARE types and TypeScript types, as well as how some CLI options affect this.

Why BARE?

Compact messages: in contrast to BSON, CBOR, and MessagePack, BARE messages do not embed schema information.

Bijective encoding when possible: most of BARE values have a single binary representation. This makes easier the support of use-cases such as message deduplication.

Focus on modern platforms: messages are octet-aligned and use little-endian representation.

Simple: in contrast to Protocol Buffer and Flat Buffer, BARE doesn't constrain its binary format to support schema evolution. Protocol Buffer embeds metadata in every message and makes optional every field. BARE recommends using a tagged union as message type to support backward compatibility.

Why bare-ts?

Pragmatic error reporting: bare-ts distinguishes recoverable errors from API misuses. Decoders may emit recoverable errors (BareError) and provide enough information to understand why the message is malformed. An API misuse emits an AssertionError. AssertionError are only emitted when the development exports condition is set or when the NODE_ENV environment variable is set to development. Moreover, bare-ts assumes the use of TypeScript that reduces the number of API misuses to check.

Optimized bundle size: bare-ts adopts functional and procedural programming styles. This enables to take advantage of modern dead-code elimination techniques, such as tree-shaking. Using bundlers such as ESbuild, Rollup, or Webpack, your bundle contains only the functions which are actually used.

Generation of efficient code bare-ts takes care to generate code that modern JavaScript engines may optimize.