typed-cstruct

Read and write a binary C struct, Use it as a JavaScript object (Off course, it's fully typed).

Installation

1npm install typed-cstruct

Usage

Basic

1import {
2  Struct,
3  u8, i16, f32,
4  sizedArray, sizedCharArrayAsString, enumLike, convert, defineBuilder
5} from "typed-cstruct";
6
7// 0. Check the struct definition
8// struct {
9//   uint8_t a;
10//   int16_t b;
11//   float c;
12// } buf = { 1, 0x0302, 1.0f };
13const buf = new Uint8Array([
14  0x01, // a
15  0x02, 0x03, // b
16  0x00, 0x00, 0x80, 0x3f // c
17]);
18
19// 1. Define a struct
20const struct = new Struct()
21  .field("a", u8) // unsigned 8-bit(1-byte) integer
22  .field("b", i16) // 16-bit(2-byte) integer
23  .field("c", f32); // 32-bit(4-byte) float
24
25// 2a. Read a struct from a buffer
26const obj = struct.read({ buf });
27console.log(obj); // => { a: 1, b: 770, c: 1 } == { a: 1, b: 0x0302, c: 1.0 }
28
29// 2b. Write a struct to a buffer
30const newBuf = new Uint8Array(7);
31struct.write({ a: 2, b: 0x0403, c: 2.0 }, { buf: newBuf });
32console.log(newBuf); // => Uint8Array [ 2, 4, 3, 0, 0, 0, 64 ]
33
34// 2c. Overwrite a field
35struct.proxy({ buf: newBuf }).a = 3;
36console.log(newBuf); // => Uint8Array [ 3, 4, 3, 0, 0, 0, 64 ]
37
38// 2d. Get size of a struct
39console.log(struct.size); // => 7

Advanced

Offset

You can specify the offset to read a struct from a buffer.

1struct.read({ buf, offset: 1 }); // Skip the first byte

Endian

You can specify the endian of a struct. (default: little)

1const struct = new Struct({ buf, endian: "big" });

Array

You can define an array field.

1// struct {
2//   uint8_t a;
3//   int16_t b[3];
4// } buf = { 1, { 0x0102, 0x0304, 0x0506 } };
5const struct = new Struct()
6  .field("a", u8)
7  .field("b", sizedArray(i16, 3)); // 3 x 16-bit(2-byte) integers

Nested

You can define a nested struct.

1// struct {
2//   uint8_t a;
3//   struct {
4//     int16_t b;
5//     float c;
6//   } d;
7// } buf = { 1, { 0x0203, 1.0f } };
8const struct = new Struct()
9  .field("a", u8)
10  .field("d", new Struct()
11    .field("b", i16)
12    .field("c", f32));

String

You can define a string field.

1// struct {
2//   uint8_t a;
3//   char b[4];
4// } buf = { 1, "foo" };
5const struct = new Struct()
6  .field("a", u8)
7  .field("b", sizedCharArrayAsString(4)); // 4-byte string

Default encoding is utf8. You can specify the encoding and decoding functions.

1const encode = (str) => new Uint8Array(str.split("").map((c) => c.charCodeAt(0)));
2const decode = (buf) => buf.map((c) => String.fromCharCode(c)).join("");
3const struct = new Struct()
4  .field("a", u8)
5  .field("b", sizedCharArrayAsString(4, { encode, decode })); // 4-byte string

Enum

You can define an enum field.

1// struct {
2//   uint8_t a;
3//   enum {
4//     FOO = 1,
5//     BAR = 2,
6//     BAZ = 3
7//   } b;
8// } buf = { 1, 2 };
9const struct = new Struct()
10  .field("a", u8)
11  .field("b", enumLike(u8, { 1: 'FOO', 2: 'BAR', 3: 'BAZ' } as const));
12const buf = new Uint8Array([0x01, 0x02]);
13const obj = struct.read({ buf });
14console.log(obj); // => { a: 1, b: 'BAR' }

Custom

You can define a custom field.

1// struct {
2//   uint8_t a;
3//   uint8_t pos[2];
4// }
5const position = defineBuilder({ // define custom builder
6  size: 2,
7  read(opts) {
8    const offset = opts.offset || 0;
9    return { x: u8.read({ ...opts, offset }), y: u8.read({ ...opts, offset: offset + 1 }) };
10  },
11});
12const struct = new Struct()
13  .field("a", u8)
14  .field("pos", position);
15const buf = new Uint8Array([0x01, 0x02, 0x03]);
16const obj = struct.read({ buf });
17console.log(obj); // => { a: 1, pos: { x: 2, y: 3 } }

You can use convert function to convert a value (readonly).

1const struct = new Struct()
2  .field("a", u8)
3  .field("pos", convert(sizedArray(u8, 2), ([x, y]) => ({ x, y })));
4const buf = new Uint8Array([0x01, 0x02, 0x03]);
5const obj = struct.read({ buf });
6console.log(obj); // => { a: 1, pos: { x: 2, y: 3 } }

License

MIT