construct-js
Advanced tools
`construct-js` is a library for creating byte level data structures. It focuses on a declarative API and simplicity of use.
construct-js is a library for creating byte level data structures. It focuses on a declarative API and simplicity of use.
npm i construct-js
There are more examples in the examples folder.
The following example builds a completely valid zip archive with one file inside - helloworld.txt.
const fs = require('fs');
const {
RawString,
U16,
U32,
Struct,
Pointer32
} = require('construct-js');
const data = RawString('helloworldhelloworldhelloworldhelloworldhelloworldhelloworldhelloworldhelloworld');
const filename = RawString('helloworld.txt');
// Create a stub for the top level struct that can be referenced by other structs
const zipFile = Struct('ZipFile');
const sharedHeaderInfo = Struct('sharedHeaderInfo')
.field('minVersion', U16(10))
.field('gpFlag', U16(0))
.field('compressionMethod', U16(0))
.field('lastModifiedTime', U16(0))
.field('lastModifiedDate', U16(0))
.field('crc32', U32(0))
.field('compressedSized', U32(data.byteLength))
.field('uncompressedSized', U32(data.byteLength))
.field('filenameSize', U16(filename.byteLength))
.field('extraFieldLength', U16(0));
const localHeader = Struct('localHeader')
.field('header', U32(0x04034b50))
.field('sharedHeaderInfo', sharedHeaderInfo)
.field('filename', filename);
const centralDirectory = Struct('centralDirectory')
.field('header', U32(0x02014b50))
.field('madeByVersion', U16(10))
.field('sharedHeaderInfo', sharedHeaderInfo)
.field('fileCommentSize', U16(0))
.field('diskNumber', U16(0))
.field('internalFileAttributes', U16(0))
.field('externalFileAttributes', U32(0))
.field('relativeOffset', U32(0))
.field('filename', filename);
const endOfCentralDirectory = Struct('endOfCentralDirectory')
.field('header', U32(0x06054b50))
.field('diskNumber', U16(0))
.field('centralDirDiskStart', U16(0))
.field('numberOfCentralDirsOnDisk', U16(1))
.field('totalNumberOfCentralDirs', U16(1))
.field('centralDirSize', U32(0))
.field('offsetToStart', Pointer32(zipFile, 'centralDirectory'))
.field('commentLength', U16(0));
// Finalise the top level struct
zipFile
.field('localHeader', localHeader)
.field('data', data)
.field('centralDirectory', centralDirectory)
.field('endOfCentralDirectory', endOfCentralDirectory);
const fileBuffer = zipFile.toBuffer();
fs.writeFileSync('./test.zip', fileBuffer);
NullTerminatedString fieldgetDeep that allowed requesting nonsense values in the pathPointer8, Pointer16, Pointer32, SizeOf8, SizeOf16 and SizeOf32 fieldsStructs. All endianness information comes directly from the Fields themselvesI8, I16, I32, I8s, I16s, I32s -> S8, S16, S32, S8s, S16s, S32sStruct(name)
Creates a Struct object.
.field(name, value)
Adds a field to the struct. name is used to lookup the field using struct.get(name). value must be either a Struct or one of the other data types provided by construct-js.
.get(name)
Returns the field with that name.
.getOffset(name)
Returns the byte offset within the struct of the field with that name.
.getDeep(path)
Returns the field within multiple structs, where path is a . separated string. For example:
const struct = Struct('firstStruct')
.field('aRawString', RawString('ABC'));
const struct2 = Struct('secondStruct')
.field('deeperStruct', struct);
struct2.getDeep('deeperStruct.aRawString');
.getDeepOffset(path)
Returns the byte offset within multiple structs, where path is a . separated string.
.computeBufferSize()
Returns the size of the struct in bytes.
.toArrayBuffer()
Returns an ArrayBuffer representation of the Struct. You should use this if working in the browser.
.toBuffer()
Returns a Buffer representation of the Struct.
.toBytes()
Returns a regular Array representation of the Struct.
BitStruct(name, lsbFirst = true)
Creates a BitStruct object, for storing and addressing data on the sub-byte level. If lsbFirst is true, the resulting buffer will consider the fields to be ordered from the 0th bit i.e. the first field in the BitStruct will be the least significant bit in the Buffer. If lsbFirst is false, the Buffer will contain the fields in the order they are specified.
Note: When bitStruct.toBuffer() is used, the resulting buffer will be byte aligned. This means if the size of the BitStruct is 12-bits, the resulting buffer will be 16-bits (2 bytes). When lsbFirst is true, the most significant bits will be padded.
.flag(name, value)
Sets a 1-bit flag in the structure.
.multiBit(name, size, value)
Sets a multi-bit flag of size.
.getOffset(name)
Gets the bit offset of the data with name.
.computeBufferSize()
Returns the size of the BitStruct in bytes.
.toBuffer()
Returns a byte-aligned Buffer representing the BitStruct.
.toArrayBuffer()
Returns a byte-aligned ArrayBuffer representing the BitStruct.
.toArray()
Returns a byte-aligned Array representing the BitStruct.
All fields contain some common properties and methods. These are:
.set(value | values)
Which sets either the value or values of the field.
.setIsLittleEndian(trueOrFalse)
Manually sets this field to little or big endian.
The rest of the properties should be considered private and not modified directly.
U8(value)
A single 8-bit unsigned value.
U16(value, littleEndian = true)
A single 16-bit unsigned value.
U32(value, littleEndian = true)
A single 32-bit unsigned value.
S8(value)
A single 8-bit signed value.
S16(value, littleEndian = true)
A single 16-bit signed value.
S32(value, littleEndian = true)
A single 32-bit signed value.
RawString(string)
A collection of 8-bit unsigned values, interpreted directly from the string provided. The size of the field is the byte length of the string (which is not always the string.length when considering unicode).
(Re)sets the value using the provided string.
NullTerminatedString(string)
A collection of 8-bit unsigned values, interpreted directly from the string provided. The size of the field is the byte length of the string (which is not always the string.length when considering unicode). This field appends a single 0x00 byte to the end of the data.
(Re)sets the value using the provided string. Automatically adds a new null termination byte.
U8s(array | number)
A collection of 8-bit unsigned values.
If the argument provided is an array, then the size of the field is array.length bytes, with each value corresponding to an 8-bit interpretation of that value.
U16s(array | number, littleEndian = true)
A collection of 16-bit unsigned values.
If the argument provided is an array, then the size of the field is array.length * 2 bytes, with each value corresponding to an 16-bit interpretation of that value.
U32s(array | number, littleEndian = true)
A collection of 32-bit unsigned values.
If the argument provided is an array, then the size of the field is array.length * 4 bytes, with each value corresponding to an 32-bit interpretation of that value.
S8s(array | number)
A collection of 8-bit signed values.
If the argument provided is an array, then the size of the field is array.length bytes, with each value corresponding to an 8-bit interpretation of that value.
S16s(array | number, littleEndian = true)
A collection of 16-bit signed values.
If the argument provided is an array, then the size of the field is array.length * 2 bytes, with each value corresponding to an 16-bit interpretation of that value.
S32s(array | number, littleEndian = true)
A collection of 32-bit signed values.
If the argument provided is an array, then the size of the field is array.length * 4 bytes, with each value corresponding to an 32-bit interpretation of that value.
Pointer8(struct, path)
Pointer8 takes a Struct and a path, and represents an 8-bit pointer (offset) to the field specified by the path in the provided struct.
Pointer16(struct, path, littleEndian = true)
Pointer16 takes a Struct, a path, and an endianness flag, and represents a 16-bit pointer (offset) to the field specified by the path in the provided struct.
Pointer32(struct, path, littleEndian = true)
Pointer32 takes a Struct, a path, and an endianness flag, and represents a 32-bit pointer (offset) to the field specified by the path in the provided struct.
SizeOf8(structOrField)
SizeOf8 takes a Struct or a Field, and represents the size of the Struct or the Field as an 8-bit unsigned integer.
SizeOf16(structOrField, littleEndian = true)
SizeOf16 takes a Struct or a Field, and an endianness flag, and represents the size of the Struct or the Field as a 16-bit unsigned integer.
SizeOf32(structOrField, littleEndian = true)
SizeOf32 takes a Struct or a Field, and an endianness flag, and represents the size of the Struct or the Field as a 32-bit unsigned integer.
FAQs
`construct-js` is a library for creating byte level data structures.
The npm package construct-js receives a total of 11 weekly downloads. As such, construct-js popularity was classified as not popular.
We found that construct-js demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Company News
Socket is joining TC54 to help develop standards for software supply chain security, contributing to the evolution of SBOMs, CycloneDX, and Package URL specifications.
Security News
PyPI now allows maintainers to archive projects, improving security and helping users make informed decisions about their dependencies.
Research
Security News
Malicious npm package postcss-optimizer delivers BeaverTail malware, targeting developer systems; similarities to past campaigns suggest a North Korean connection.