https://github.com/bare-ts/bare
A TypeScript code generator for the BARE binary format
https://github.com/bare-ts/bare
bare binary-format cli code-generator compiler schema serialization tools
Last synced: 15 days ago
JSON representation
A TypeScript code generator for the BARE binary format
- Host: GitHub
- URL: https://github.com/bare-ts/bare
- Owner: bare-ts
- License: mit
- Created: 2022-01-03T21:49:14.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2025-11-10T13:32:03.000Z (3 months ago)
- Last Synced: 2025-11-10T15:20:56.653Z (3 months ago)
- Topics: bare, binary-format, cli, code-generator, compiler, schema, serialization, tools
- Language: TypeScript
- Homepage:
- Size: 1.36 MB
- Stars: 27
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Notice: NOTICE
Awesome Lists containing this project
README
A TypeScript code generator for the BARE binary format
[![NPM package][npm-img]][npm-bare-ts-tools]
[![bundle size - minified and gzipped][bundlejs-img]][bundlejs]
[![Coverage][coveralls-img]][coveralls]
[Binary Application Record Encoding](https://baremessages.org/) (_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
[![@bare-ts/tools NPM version][npm-bare-ts-tools-img]][npm-bare-ts-tools]
[![@bare-ts/lib NPM version][npm-bare-ts-lib-img]][npm-bare-ts-lib]
First, install _@bare-ts/tools_ and _@bare-ts/lib_:
```sh
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_](https://github.com/bare-ts/tools/releases).
Then, write a schema:
```zig
type Gender enum {
FEMALE
FLUID
MALE
}
type Person struct {
name: str
email: str
gender: optional
}
type Organization struct {
name: str
email: str
}
type Contact union { Person | Organization }
type Contacts list
```
Compile your schema into code:
```sh
bare schema.bare --out=code.ts
```
Once the code is generated, encode and decode messages:
```ts
import { Gender, decodeContacts, encodeContacts } from "./code.js"
import { strict } from "node:assert"
const contacts = [
{
tag: "Person",
val: {
name: "Seldon",
email: "seldon@foundation.org",
gender: Gender.Male,
},
},
]
const payload = encodeContacts(contacts)
const contacts2 = decodeContacts(payload)
strict.deepEqual(contacts, contacts2)
```
Refer to our [`types` documentation page](./docs/types.md) 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](https://nodejs.org/api/cli.html#-c-condition---conditionscondition) 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.
[npm-img]: https://flat.badgen.net/npm/v/@bare-ts/tools
[npm-bare-ts-tools-img]: https://flat.badgen.net/npm/v/@bare-ts/tools?label=npm:@bare-ts/tools
[npm-bare-ts-tools]: https://www.npmjs.com/package/@bare-ts/tools
[npm-bare-ts-lib-img]: https://flat.badgen.net/npm/v/@bare-ts/lib?label=npm:@bare-ts/lib
[npm-bare-ts-lib]: https://www.npmjs.com/package/@bare-ts/lib
[coveralls-img]: https://flat.badgen.net/coveralls/c/github/bare-ts/bare
[coveralls]: https://coveralls.io/github/bare-ts/bare?branch=main
[bundlejs-img]: https://img.shields.io/badge/dynamic/json?style=flat-square&label=minzipped&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=@bare-ts/tools
[bundlejs]: https://bundlejs.com/?q=%40bare-ts%2Ftools