Note
This is one of 199 standalone projects, maintained as part of the @thi.ng/umbrella monorepo and anti-framework.
🚀 Please help me to work full-time on these projects by sponsoring me on GitHub. Thank you! ❤️
C-style struct, union and bitfield read/write views of ArrayBuffers.
Features:
- Construct memory mapped JS objects based on given typedef specs
- Nested structs & unions
- Packed bitfields (signed / unsigned)
- Auto-alignment of fields to respective word boundaries (can be disabled)
- Configurable endianness (bitfields currently assume network order / big endian)
- No runtime dependencies, works in node & browser
- Small: 2.35KB minified, 1.14KB gzipped
Currently does not support array fields (incl. strings).
STABLE - used in production
Search or submit any issues for this package
yarn add @thi.ng/unionstructESM import:
import * as us from "@thi.ng/unionstruct";Browser ESM import:
<script type="module" src="https://esm.run/@thi.ng/unionstruct"></script>For Node.js REPL:
const us = await import("@thi.ng/unionstruct");Package sizes (brotli'd, pre-treeshake): ESM: 1008 bytes
None
import { struct, union, sizeOf } from "@thi.ng/unionstruct";C-style union types define alternate views of the same data. For example
this C snippet below defines such a type, of which the first 32-bits can
be accessed either via individual bitfields or as combined value. Fields
in this union type can be accessed like x.flags (combined) or
x.state.cache (only bits 9-11 of x.flags). Since all views share the
same memory, value changes of one view are reflected in all others too
(of course updating bitfields only modifies a field's allocated bit
range).
// C
typedef union {
uint32_t flags;
struct {
uint32_t type : 9;
uint32_t cache : 3;
uint32_t enabled : 1;
uint32_t visible : 1;
uint32_t selected : 1;
uint32_t locked : 1;
int32_t scheduled : 18;
uint16_t tag;
} state;
} Header;This library provides this similarly in JS. The field spec format, bitfields and alignment are described further below.
import { union } from "@thi.ng/unionstruct";
typedef_header = [
["flags", "u32"],
["state", "struct", [
["type", "u32", 9],
["cache", "u32", 3],
["enabled", "u32", 1],
["visible", "u32", 1],
["selected", "u32", 1],
["locked", "u32", 1],
["scheduled", "i32", 18],
["tag", "u16"]]]
];
// pre-loaded binary data
buf = new Uint32Array([0x807cc0, 0x40000000, 0x3930]);
// create instance, see list of header arguments below
header = union(typedef_header, buf.buffer);
// { __buffer: ArrayBuffer { byteLength: 12 },
// __spec: [['flags', 'u32'], ['state', 'struct', [...]]],
// __size: 80,
// __offsets: { flags: 0, state: 0 },
// flags: [Getter/Setter],
// state: [Getter] }
header.state
// { __buffer: ArrayBuffer { byteLength: 12 },
// __spec: [...],
// __size: 80,
// __offsets:
// { type: 0,
// cache: 9,
// enabled: 12,
// visible: 13,
// selected: 14,
// locked: 15,
// scheduled: 16,
// tag: 64 },
// ... }
header.flags.toString(16) // "c07c8000"
header.state.type // 384
header.state.enabled // 1
header.state.visible // 1
header.state.selected // 0
header.state.locked // 0
header.state.scheduled // -131072
header.state.tag // 12345union(spec: Field[], buf?: ArrayBuffer, offset = 0, align = true, littleEndian = false) => any
Takes an array of field specs (as in example above) and optional ArrayBuffer, offset etc. If no buffer is given, constructs a new one with minimum size required by this field spec. Returns an object with enumerable field accessors and the following additional keys (largely for introspection purposes):
__buffer- backing ArrayBuffer instance__offsets- bit offset in buffer for each field__spec- original field spec array provided__size- computed bit size of whole type
All top-level fields in a union share the same start address. Also see note about alignment below.
struct(spec: Field[], buf?: ArrayBuffer, offset = 0, align = true, littleEndian = false) => any
Same as union, but field start addresses are arranged sequentially (and aligned individually).
sizeOf(spec: Field[], union = false, doAlign = true) => number
Returns bit size of given field spec, taking into account alignment.
import { sizeOf } from "@thi.ng/unionstruct";
// struct
sizeOf([["a", "u32", 14], ["b", "u32", 6], ["c","u8"]]);
// 40
// union
sizeOf([["a", "u32", 14], ["b", "u32", 6], ["c","u8"]], true);
// 14For unions, if align is enabled (default), the entire type's offset
will be aligned to the largest required width. E.g. If any of the
top-level fields is of type f64, alignment will be to 8-byte
boundaries. If the union contains nested types, they will be checked
recursively and aligned to largest type found (for structs only the
first field has an impact on whole struct alignment).
| Type | Alignment |
|---|---|
| f64 | 8 |
| f32 | 4 |
| u32 / i32 | 4 |
| u16 / i16 | 2 |
| u8 / i8 | 1 |
Bitfields can only use integer types and support both signed / unsigned flavors. Successive bitfields are densely packed (no alignment in between). The max. width of a single field is 32 bits, but an arbitrary number of successive bitfields can be defined.
If align is enabled and the last bitfield in a group does not end at a
word boundary, the field will be padded invisibly, based on its type
(has no impact on size of last field).
import { struct } from "@thi.ng/unionstruct";
bitfields = struct([
// 2 packed bitfields (20 bits)
["a", "u32", 14],
["b", "u32", 6],
// 32 - 20 = 12 bit padding here
["c", "u8"] // providing no bit width forces alignment
]);
bitfields.__offsets
// { a: 0, b: 14, c: 32 }
// without padding, field `c` would incorrectly start at bit offset 24
// (since u8 aligns itself to 8-bit boundaries)If this project contributes to an academic publication, please cite it as:
@misc{thing-unionstruct,
title = "@thi.ng/unionstruct",
author = "Karsten Schmidt",
note = "https://thi.ng/unionstruct",
year = 2017
}© 2017 - 2024 Karsten Schmidt // Apache License 2.0