@bare-ts/lib

bare-ts library

BARE (Binary Application Record Encoding) is a schema-based binary format that favors compactness and simplicity. bare-ts/lib provides decoders and encoders for basic BARE types.

Please, take a look to bare-ts/tools for more information.

Warning: BARE specification is currently a IEF draft. The specification is likely to evolve before its final release. bare-ts implements an ongoing draft that is not published yet.

Changelog

0.4.0 (2023-06-19)

• BREAKING CHANGES: remove ByteCursor methods

  To make bare-ts/lib API uniform, methods of ByteCursor are replaced by regular functions.

    import * as bare from "@bare-ts/lib"
  
    const bc = new bare.ByteCursor(new Uint8Array(5), bare.Config({}))
  - bc.check(5)
  - bc.reserve(5)
  - bc.read(5)
  + bare.check(bc, 5)
  + bare.reserve(bc, 5)
  + bare.readUnsafeU8FixedArray(bc, 5)
  

• BREAKING CHANGES: remove textDecoderThreshold and textEncoderThreshold configuration

  Calls to native TextDecoder.decode and TextEncoder.encode have a fixed cost. This cost outperforms the native performance to decode and encode small strings.

  bare-ts uses a custom implementation to decode and encode small strings. The choice between the custom and the native codecs is based on thresholds. These threshold were configurable via textDecoderThreshold and textEncoderThreshold config.

  This is not clear whether this configuration is worth to expose. Most of decoded and encoded strings are small. Fixed thresholds seem fair enough.

• Add assertions and development mode

  Previously, bare-ts enabled a few assertions to check some function arguments. For instance, the following code could trigger an AssertionError:

  import * as bare from "@bare-ts/lib"
  
  const bc = new bare.ByteCursor(new Uint8Array(5), bare.Config({}))
  bare.writeU8(bc, 2**10) // AssertionError: too large number
  

  Assertions are now disabled by default. They are enabled under the following condition:

  • The code is executed under node with NODE_ENV=development

  • The code is executed or bundled under development condition.

  New assertions were added to improve error reporting on development. More assertions could be added in the future.

  Because assertions can be disabled, we improved the code robustness: All uint/int writters truncate their input to ensure that the number of written bytes is bounded.