The available downloads for binary-tools.js.
SHA-1 sums: binary-tools-sha1sums.txt MD5 sums: binary-tools-md5sums.txt
Version 2.x inroduced some API changes.
- calcSize no longer have a "includePads" param; pads are always included.
- read() and readTo() no longer have a 'safe' param. Now input buffers with
insufficient bytes cause a "Bad buffer length" error; extra bytes, if present,
are always ignored.
- Exceptions now include the value that caused the exception and its index in
the 'cause' property, not as a string in the exception message.
- Introduce setType() to create integer types. The types object is no longer
accessible.
- The type '?' now only work with booleans and throw TypeError on anything else;
set the "clamp" param to true to convert other types and values to boolean and
avoid TypeErrors.
- 'clamp' is now the first optional param on packTo() and writeTo().
- 'clamp' is now a optional param on unpack(), unpackTo() readTo() and read().
Version 1.12.0 introduces the # operator to align data and set sizes in a similar way @ does, but following a different set of rules.
- New operator # to control alignment and size.
Version 1.11.0 introduces the operators % and & to control padding at the end of structures.
- New operators % and & to control padding at the end of structures.
Version 1.10.0 introduces the new operator @ to control alignment and size. A value may be used with @ to control its behavior. The changes are listed below; detailed information about the new features can be found on the README file.
- New operator @ to control alignment and size.
- New types 'i' and 'I': 32-bit integers with fixed size.
Version 1.9.1 adds a TypeScript declarations file to the root folder: ./index.d.ts. The declarations file for the ES3 distribution ./dist/binary-tools.d.ts is copied from ./index.d.ts during the build process.
- Fix: Add TypeScript declarations to the root folder.
Version 1.9.0 introduces two new integer data types: N for 4-bit unsigned integers and M for 1024-bit unsigned integers, as well as bug fixes and minor improvements. The changes are listed below; detailed information about the new features can be found on the README file.
- New type 'N' for 4-bit integers (nibbles). Nibbles are packed and unpacked
in pairs as a single byte.
- New type 'M' for 1024-bit integers.
- Fix: check for overflows when unpacking bigints. This only affects types
with bit lengths that are not multiple of 8 (63-bit, for example).
- Fix: check for overflows when unpacking integers. This only affects types
with bit lengths that are not multiple of 8 (12-bit, for example).
- Fix: proper validation of typed array size when using write() or writeTo()
with typed arrays. If array size do not match the required size for the
type of input and the number of elements on the input array, now it throws
a Bad buffer length error.
- Avoid repeating the error type name on RangeError and TypeError messages.
- Changed the index informed on errors messages from single-byte character
encoding strings. It now informs the index of the string on the input array,
and not the index of the character on the string. Informing the index of the
character on the string when packing multiple types could lead to confusion
about what value caused the error. The character that originated the error
is informed on the error message, too, to made it easier to identify it on the
string. With this, SBCE string error messages now follow the same pattern
of error messages from other types.
- Repeat count numbers are removed from the format string when using write()
or writeTo(). The documentation already stated that repeat count numbers
should not be used with writing or reading functions, but if present
in the format string by mistake, they could cause problems to validate the
output buffer size when using typed arrays.
Previous versions had inconsitent behavior for strings of different types. This release aims to standardize the behavior for all types of strings, with special focus in Unicode edge cases.
While the API remains the same, this release introduces new validations and fixed some design flaws when handling Unicode strings that might need your consideration in case you were abusing those flaws for some reason.
- Now UTF-16 and UTF-32 behave the same as UTF-8 in regards to trimming
strings, as intended. The previos behavior was to throw an Error instead
of correctly trimming the string.
- Only valid UTF-16 and UTF-32 buffer slices can be used for reading.
On previous releases you could specify invalid buffer slices to read
as UTF-16 and UTF-32, which was a design flaw that could lead to
unexpected errors.
Unicode handling is much better documented on the README file, with examples detailing the behaviors that should be taken into consideration when dealing with Unicode.
- New feature: Support UTF-32 strings with new type 'V'.
- New feature: Function utf32BufferSize() to find how many bytes are
needed for a given UTF-32 string.
- New feature: Support UTF-16 strings with new type 'U'.
- New feature: Function utf16BufferSize() to find how many bytes are
needed for a given UTF-16 string.
- New feature: byte order operator '='.
- Fix: clamp param on packing now works for BigInts too
- Fix: Add BigInts to TypeScript declarations file
- New feature: utf8BufferSize(str) to find out how many bytes are
needed to pack a UTF-8 string.
- New feature: bytesToHex(byteArray) and hexToBytes(hexStr) to work
with hex strings in the input or output.
- New feature: type 'O' for unsigned 512-bit integers.
- Fix: packTo() now validates the size of the output buffer only if output
buffer is a typed array, the same way as writeTo().
- Fix: packTo() and writeTo() now have the same behaviour when packing or
writing UTF-8 strings to typed arrays with insufficient buffer size:
throw Bad buffer length error.
- Fix: TypeScript declarations to support chars and strings
- Expose the ES3 module both as binaryTools and btools
Fix: repeat count numbers for padding bytes now work properly
Fix: when packing UTF-8 strings, throw 'Invalid UTF-8 character' error on packing code points in the range U+D800..U+DFFF instead of using replacement characters, according to the latest version (as of August 2023) of the Unicode Standard, chapter 3, section 3.9: https://www.unicode.org/versions/Unicode15.0.0/ch03.pdf
Add types 'A' and 'Y' for 128-bit and 256-bit unsigned integers.
© 2023-2025 Rafael da Silva Rocha. All Rights Reserved.