bytestreamjs reads, writes and searches single bytes and bits in ArrayBuffer/Uint8Array data, in Node.js and browsers.
Install
npm install bytestreamjs
Breaking Changes In v3
v3 ships ESM only. The CommonJS build is removed: v2 published three parallel trees, build/cjs/*.js (CommonJS), build/mjs/*.js (ESM) and build/types/*.d.ts; v3 publishes ES modules in build/, with build/index.js and build/index.d.ts as the entry point, behind an exports map.
Node.js ^20.19.0 || >=22.12.0 is required (previously >=6.0.0). These versions support require() of ES modules, so CommonJS code can keep using require("bytestreamjs") without changes. Node.js 22.0–22.11 is not supported: it can't require() ESM.
TypeScript projects that compile to CommonJS need "module": "node20" or "nodenext" (TypeScript 5.9+). With "module": "node16" the compiler reports TS1479.
ESM and bundler setups ("module": "preserve", "moduleResolution": "bundler") work without changes.
Legacy "moduleResolution": "node" (node10) resolves the package through types; bytestreamjs has no subpath exports, so nothing else changes.
Jest in CommonJS mode can't load ESM packages. Use Jest's ESM mode, add bytestreamjs to the transformIgnorePatterns exceptions, or switch to Vitest.
Deep imports are blocked. The exports map allows only bytestreamjs and bytestreamjs/package.json. Imports of bytestreamjs/build/cjs/..., bytestreamjs/build/mjs/... or bytestreamjs/build/types/... must change to bytestreamjs. Import maps and other setups that point at node_modules/bytestreamjs/build/mjs/index.js must use build/index.js.
The public API is unchanged; only packaging and runtime requirements changed.
ByteStream class
ByteStream class is the major class for all others. It provides many useful function for making search for patterns and data transformation. Optimized for fast as possible data processing.
Method
Description
clear
Clear existing stream
fromArrayBuffer
Initialize "Stream" object from existing "ArrayBuffer"
fromUint8Array
Initialize "Stream" object from existing "Uint8Array"
fromString
Initialize "Stream" object from existing string
toString
Represent "Stream" object content as a string
fromHexString
Initialize "Stream" object from existing hexdecimal string
toHexString
Represent "Stream" object content as a hexdecimal string
copy
Return copy of existing "Stream"
slice
Return slice of existing "Stream"
SeqStream class
SeqStream class is the aux class for sequential reading/writing data from/to ByteStream underline class.
Method
Description
resetPosition
Reset current position of the "SeqStream"
findPattern
Find any byte pattern in "ByteStream"
findFirstIn
Find first position of any pattern from input array
findAllIn
Find all positions of any pattern from input array
findFirstNotIn
Find first position of data, not included in patterns from input array
findAllNotIn
Find all positions of data, not included in patterns from input array
findFirstSequence
Find position of a sequence of any patterns from input array
findAllSequences
Find position of a sequence of any patterns from input array
BitStream class
Main purpose of the BitStream is manipulating of each bit inside any ByteStream data.
Method
Description
clear
Clear existing stream
fromByteStream
Initialize "BitStream" by data from existing "ByteStream"
fromArrayBuffer
Initialize "BitStream" object from existing "ArrayBuffer"
fromUint8Array
Initialize "BitStream" object from existing "Uint8Array"
fromString
Initialize "BitStream" object from existing bit string
toString
Represent "BitStream" object content as a string
shiftRight
Shift entire "BitStream" value right to number of bits
shiftLeft
Shift entire "BitStream" value left to number of bits
slice
SeqBitStream class
SeqBitStream class is the aux class for sequential reading/writing data from/to BitStream underline class.
Method
Description
getBits
Get next "length" bits from the stream
getBitsString
Get string representation for the next "length" bits from the stream
getBitsReversedValue
Get number value representation of the next "length" bits from the stream, preliminary reversed
toString
Represent remaining bits in "BitStream" as a string
parseByteMap functionality
The parseByteMap function is intended to parse and check byte streams with determinated structure.
Example of map used as a kind of template. Exactly this map is using for parsing PDF xref table:
let map = [ { type: "string", name: "type", minlength: 1, maxlength: 1, func: function (array) { let result = { status: -1, length: 1, }; switch (array[0]) { case 0x6e: // "n" result.value = "n"; break; case 0x66: // "f" result.value =
Contributing
See CONTRIBUTING.md for development setup, commit conventions and the release flow.
Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
Neither the name of the copyright holder nor the names of its contributors
may be used to endorse or promote products derived from this software without
specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
OF SUCH DAMAGE.
microshine
microshine@mail.ru
realloc
Change size of existing "Stream"
append
Append a new "Stream" content to the current "Stream"
insert
Insert "Stream" content to the current "Stream" at specific position
isEqual
Check that two "Stream" objects has equal content
isEqualView
Check that current "Stream" objects has equal content with input "Uint8Array"
findPattern
Find any byte pattern in "Stream"
findFirstIn
Find first position of any pattern from input array
findAllIn
Find all positions of any pattern from input array
findAllPatternIn
Find all positions of a pattern
findFirstNotIn
Find first position of data, not included in patterns from input array
findAllNotIn
Find all positions of data, not included in patterns from input array
findFirstSequence
Find position of a sequence of any patterns from input array
findAllSequences
Find all positions of a sequence of any patterns from input array
findPairedPatterns
Find all paired patterns in the stream
findPairedArrays
Find all paired patterns in the stream
replacePattern
Replace one patter with other
skipPatterns
Skip any pattern from input array
skipNotPatterns
Skip any pattern not from input array
findPairedPatterns
Find all paired patterns in the stream
findPairedArrays
Find all paired patterns in the stream
replacePattern
Replace one patter with other
skipPatterns
Skip of any pattern from input array
skipNotPatterns
Skip of any pattern from input array
append
Append a new "Stream" content to the current "Stream"
appendView
Append a "view" content to the current "Stream"
appendChar
Append a new char to the current "Stream"
getBlock
Get a block of data
getUint32
Get 4-byte unsigned integer value
Return slice of existing "BitStream"
copy
Return copy of existing "BitStream"
shrink
Shrink unnecessary bytes in current stream accordingly to "bitsCount" value
reverseBytes
Reverse bits order in each byte in the stream
reverseValue
Reverse all bits in entire "BitStream"
getNumberValue
Trying to represent entire "BitStream" as an unsigned integer
findPattern
Find any bit pattern in "BitStream"
findFirstIn
Find first position of any pattern from input array
findAllIn
Find all positions of any pattern from input array
findAllPatternIn
Find all positions of a pattern
findFirstNotIn
Find first position of data, not included in patterns from input array
findAllNotIn
Find all positions of data, not included in patterns from input array
findFirstSequence
Find position of a sequence of any patterns from input array
findAllSequences
Find position of a sequence of any patterns from input array
findPairedPatterns
Find all paired patterns in the stream
findPairedArrays
Find all paired patterns in the stream
replacePattern
Replace one pattern with other
skipPatterns
Skip any pattern from input array
skipNotPatterns
Skip any pattern not from input array
append
Append a new "BitStream" content to the current "BitStream"