Repository files navigation

npm i struct-compile --save

This project is used internally byover-the-wire. I'm not sure if it has any use outside its main purpose.

The goal of this project is to provide a convenient function for creating a JavaScript class from a C structure, allowing for easy parsing or construction of binary data.

I chose to implement it myself instead of using an existing alternative because of the lazy reading feature: when the struct is initialized with aBuffer instance, it doesn't immediately read all the fields—only those that are accessed.

This approach is especially useful for parsing network packets, where many fields are often unnecessary to read. I also believe it can slightly improve overall performance.

• Node.js >= 16.18.0

The main function iscompile with the signature:

compile(string, [arch], [BufferImpl]) => object

import{compile}from'struct-compile';// also available for commonJS// const { compile } = require('struct-compile');const{ Data,PDU}=compile(`  //simple example  struct Data {    uint8_t c;    int v;    unsigned long da;  };  //@NE Network-endiannes for all members of this struct  struct __attribute__((__packed__)) PDU {    //Some useful comment    char name /*in-between comment*/ [16];    double dbl;    int p;  };`);// creating objectsconstobj=newPDU();obj.name='seva';obj.dbl=1.1;console.log('PDU size: ',obj.length);console.log('PDU buffer example: ',obj.buffer);// parsing raw binary dataconstparsed=newPDU(Buffer.from([0x73,0x65,0x76,0x61,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x3f,0xf1,0x99,0x99,0x99,0x99,0x99,0x9a,0x00,0x00,0x00,0x00]));console.log(parsed.name.toString());console.log(parsed.dbl);

The syntax for creating structures takes into account C rules for aligning objects within a structure, and auxiliary comments help to automatically set the endianness of the field. Learn more about alignmenthere andhere.

An important note is that the input syntax is thesubset of the C syntax, current syntax rules can be viewedhere.

This project has been tailored with specific compatibilities and limitations. Below is a checklist highlighting the current state of support for various features:

Please note that while some features like bitfields, nested structures, and enums are not currently supported, the project is continually evolving. Contributions or suggestions for these areas are welcome.

If you have any ideas, or something is not working correctly, feel free to open an issue.