struct-buffer

Add structure to ArrayBuffer

Install

$ npm i struct-buffer

how to use

1import { float, string_t, StructBuffer, pack } from "struct-buffer";
2
3const struct = new StructBuffer("Player", {
4  hp: float,
5  mp: float,
6  name: string_t[3],
7});
8
9const buffer: DataView = pack("2f3s", 10, 100, "abc");
10
11// decode
12const data = struct.decode(buffer);
13// data => { hp: 10, mp: 100, name: 'abc' }
14
15// encode
16const view = struct.encode({
17  hp: 10,
18  mp: 100,
19  name: "abc",
20});
21// view => <41 20 00 00 42 c8 00 00 61 62 63>

Use in browser

1<script src="struct-buffer.js"></script>
2<script>
3  const { DWORD, string_t, StructBuffer, uint32_t } = window.StructBuffer;
4</script>

Use "type" for conversion

1import { DWORD } from "struct-buffer";
2
3// encode
4const view = DWORD[2].encode([1, 2]); 
5// view => <00 00 00 01 00 00 00 02>
6
7// decode
8const data = DWORD[2].decode(view);
9// data => [ 1, 2 ]

register Type

1const myShort = registerType("short", 2, false);
2
3const struct = new StructBuffer("Player", {
4  hp: myShort,
5  mp: myShort,
6  pos: myShort[2],
7});
8
9// encode
10const view = struct.encode({
11  hp: 2,
12  mp: 10,
13  pos: [100, 200],
14});
15// view => <00 02 00 0a 00 64 00 c8>
16
17// decode
18const data = struct.decode(view);
19// data => { hp: 2, mp: 10, pos: [ 100, 200 ] }

typedef

1const HANDLE = typedef("HANDLE", DWORD);
2HANDLE.size // 4
3HANDLE.unsigned // true

Nested struct

1/*
2typedef struct _XINPUT_STATE {
3  DWORD          dwPacketNumber;
4  XINPUT_GAMEPAD Gamepad;
5} XINPUT_STATE, *PXINPUT_STATE;
6
7
8typedef struct _XINPUT_GAMEPAD {
9  WORD  wButtons;
10  BYTE  bLeftTrigger;
11  BYTE  bRightTrigger;
12  SHORT sThumbLX;
13  SHORT sThumbLY;
14  SHORT sThumbRX;
15  SHORT sThumbRY;
16} XINPUT_GAMEPAD, *PXINPUT_GAMEPAD;
17*/
18
19XINPUT_GAMEPAD = new StructBuffer("XINPUT_GAMEPAD", {
20  wButtons: WORD,
21  bLeftTrigger: BYTE,
22  bRightTrigger: BYTE,
23  sThumbLX: int16_t,
24  sThumbLY: int16_t,
25  sThumbRX: int16_t,
26  sThumbRY: int16_t,
27});
28
29XINPUT_STATE = new StructBuffer("XINPUT_STATE", {
30  dwPacketNumber: DWORD,
31  Gamepad: XINPUT_GAMEPAD,
32});
33
34// decode
35XINPUT_STATE.decode(
36    new Uint8Array([
37      0, 0, 0, 0, // dwPacketNumber
38      0, 1, // wButtons
39      0,    // bLeftTrigger
40      0,    // bRightTrigger
41      0, 1, // sThumbLX
42      0, 2, // sThumbLY
43      0, 3, // sThumbRX
44      0, 4, // sThumbRY
45    ])
46);
47
48// encode
49XINPUT_STATE.encode({
50  dwPacketNumber: 0,
51  Gamepad: {
52    wButtons: 1,
53    bLeftTrigger: 0,
54    bRightTrigger: 0,
55    sThumbLX: 1,
56    sThumbLY: 2,
57    sThumbRX: 3,
58    sThumbRY: 4,
59  },
60});

parse c-struct

1import { CStruct } from "struct-buffer";
2
3const cStruct = `
4//
5// Structures used by XInput APIs
6//
7typedef struct _XINPUT_GAMEPAD
8{
9    WORD                                wButtons;
10    BYTE                                bLeftTrigger;
11    BYTE                                bRightTrigger;
12    SHORT                               sThumbLX;
13    SHORT                               sThumbLY;
14    SHORT                               sThumbRX;
15    SHORT                               sThumbRY;
16} XINPUT_GAMEPAD, *PXINPUT_GAMEPAD;
17
18typedef struct _XINPUT_STATE
19{
20    DWORD                               dwPacketNumber;
21    XINPUT_GAMEPAD                      Gamepad;
22} XINPUT_STATE, *PXINPUT_STATE;
23
24typedef struct _XINPUT_VIBRATION
25{
26    WORD                                wLeftMotorSpeed;
27    WORD                                wRightMotorSpeed;
28} XINPUT_VIBRATION, *PXINPUT_VIBRATION;
29
30typedef struct _XINPUT_BATTERY_INFORMATION
31{
32    BYTE BatteryType;
33    BYTE BatteryLevel;
34} XINPUT_BATTERY_INFORMATION, *PXINPUT_BATTERY_INFORMATION;
35`;
36
37const structs = CStruct.parse(cStruct);
38sizeof(structs.XINPUT_GAMEPAD) // 12
39sizeof(structs.XINPUT_STATE) // 16
40sizeof(structs.XINPUT_VIBRATION) // 4
41sizeof(structs.XINPUT_BATTERY_INFORMATION) // 2

struct list

1const User = new StructBuffer("User", {
2  name: string_t[2],
3  name2: string_t[2],
4});
5
6const Users = new StructBuffer("Users", {
7  users: User[2],
8});
9
10const data = Users.decode(
11  new Uint8Array([0x61, 0x31, 0x61, 0x32, 0x62, 0x31, 0x62, 0x32])
12);
13// data.users.length => 2
14// data.users[0] => { name: "a1", name2: "a2" }
15// data.users[1] => { name: "b1", name2: "b2" }
16
17// or
18
19const users = User[2].decode(
20  new Uint8Array([0x61, 0x31, 0x61, 0x32, 0x62, 0x31, 0x62, 0x32])
21);
22// users => [ { name: 'a1', name2: 'a2' }, { name: 'b1', name2: 'b2' } ]

StructBuffer to c-struct

1import { CStruct } from "struct-buffer";
2
3const XINPUT_GAMEPAD = new StructBuffer("XINPUT_GAMEPAD", {
4  wButtons: WORD,
5  bLeftTrigger: BYTE,
6  bRightTrigger: BYTE,
7  sThumbLX: int16_t,
8  sThumbLY: int16_t,
9  sThumbRX: int16_t,
10  sThumbRY: int16_t[2],
11});
12const cStruct = CStruct.from(XINPUT_GAMEPAD);
13
14// console.log(cStruct) => 
15typedef struct _XINPUT_GAMEPAD
16{
17    WORD wButtons;
18    BYTE bLeftTrigger;
19    BYTE bRightTrigger;
20    int16_t sThumbLX;
21    int16_t sThumbLY;
22    int16_t sThumbRX;
23    int16_t sThumbRY[2];
24} XINPUT_GAMEPAD, *XINPUT_GAMEPAD;

"string_t" Truncate when encountering 0

1string_t[4].decode(new Uint8Array([0x61, 0x62, 0x63, 0x64]); // abcd
2string_t[4].decode(new Uint8Array([0x61, 0x62, 0x00, 0x64]); // ab

bits

1import { DWORD, bits, StructBuffer } from "struct-buffer";
2
3const EFLAG_DATA = 0x00000246;
4const littleEndian = true;
5const EFLAG = bits(DWORD, {
6  CF: 0,
7  PF: 2,
8  AF: 4,
9  ZF: 6,
10  SF: 7,
11  TF: 8,
12  IF: 9,
13  DF: 10,
14  OF: 11,
15});
16
17// decode
18const data = EFLAG.decode(new Uint32Array([EFLAG_DATA]), littleEndian);
19// => { CF: 0, PF: 1, AF: 0, ZF: 1, SF: 0, TF: 0, IF: 1, DF: 0, OF: 0 }
20
21// encode
22const view = EFLAG.encode(
23  {
24    PF: 1,
25    ZF: 1,
26    IF: 1,
27  },
28  littleEndian
29);
30// => <44 02 00 00>

bitFields

1import { uint8_t, bitFields, StructBuffer, sbytes as b, } from "struct-buffer";
2
3const bf = bitFields(uint8_t, {
4  a: 1,
5  b: 2,
6  c: 3,
7});
8
9const v = bf.encode({
10  a: 1,
11  b: 2,
12  c: 3,
13});
14// => <1D>
15
16const data = bf.decode(b("1D"));
17// => { a: 1, b: 2, c: 3 }

Inject

Customize the working content of decode and encode

1const c_str = new Inject(
2  // decode
3  (view: DataView, offset: number) => {
4    const buf: number[] = [];
5    let size = offset + 0;
6    while (true) {
7      let data = view.getUint8(size++);
8      if (data === 0) break;
9      buf.push(data);
10    }
11
12    return {
13      size: size - offset,
14      value: new TextDecoder().decode(new Uint8Array(buf)),
15    };
16  },
17
18  // encode
19  (value: string) => {
20    const bytes: Uint8Array = new TextEncoder().encode(value);
21    const res = realloc(bytes, bytes.byteLength + 1);
22    return res;
23  }
24);

See Inject.test.ts file.

pack and unpack

1import { pack, pack_into, unpack, unpack_from, iter_unpack, calcsize, Struct, sbytes as b } from "struct-buffer";
2
3pack("b2xb", 2, 1)
4// => <02 00 00 01>
5
6unpack("b2xb", b("02 00 00 01"))
7// => [ 2, 1 ]
8
9calcsize("hhl")
10// => 8
11
12
13const [hp, mp, name] = unpack(
14  ">II3s",
15  b("00 00 00 64 00 00 00 0A 61 62 63")
16);
17expect(hp).toBe(100);
18expect(mp).toBe(10);
19expect(name).toBe('abc');

Note: Without "@, =, P", the default byte order is ">"

Some utility functions

1import { createDataView, makeDataView, sbytes as b, sbytes2 as b2, sview, TEXT } from "struct-buffer";
2
3createDataView(3)
4// => <00 00 00>
5
6makeDataView([1, 2, 3])
7// => <01 02 03>
8
9b("01 02 03")
10// => <01 02 03>
11
12b2("abc\\x1\\x2\\x3")
13// => <61 62 63 01 02 03>
14
15TEXT(pack("3s2b3s2I", "abc", 1, 2, "xyz", 8, 9))
16// => "abc..xyz........"

test

$ npm test

build

$ npm run build

See also:

• See the test for more examples
• DataView
• C_data_types
• Built-in types (C++)
• C++ Bit Fields