Part of the grest-ts framework. Documentation | All packages

@grest-ts/struct

Binary struct definitions with code generation. Define memory-efficient, strongly-typed data structures using a fluent TypeScript API, then generate optimized classes backed by typed arrays (Int16Array, Uint32Array, etc.).

Ideal for game engines, real-time simulations, and any scenario where you need to manage large pools of objects with minimal memory overhead, fast iteration, and efficient network/worker serialization.

The generated getters and setters are simple one-liner typed array accesses. V8 and other JS engines inline and optimize these away at JIT time, so you get effectively raw typed array access speed — as fast as JavaScript can go. There is no faster way to do it in JS.

The generated code has zero runtime dependencies and can be used as a standalone package — @grest-ts/struct is only needed at code generation time.

Install

npm install @grest-ts/struct

How it works

1. You define a struct schema in a *.struct.ts file using the fluent Struct builder.
2. You run the code generator, which parses the schema and writes a corresponding *.ts file with fully typed classes.
3. You import and use the generated classes in your application.

Defining a struct

Create a file with the .struct.ts suffix. The filename becomes the generated class name.

// MyEntity.struct.ts
import {ADD_MATH, MUST_EXIST, Struct, typed} from "@grest-ts/struct";

type tEntityRef = number & { tEntityRef: never };
type tSpriteId = number & { tSpriteId: never };

new Struct({useNew: true, useExport: true, useDirty: true})
    .ref<tEntityRef>()
    .buffer()
    .int16("x", ADD_MATH)
    .int16("y", ADD_MATH)
    .buffer()
    .uint32("spriteId", MUST_EXIST, typed<tSpriteId>())
    .bool("isHighlighted")
    .bit("isAnimated")

This generates a MyEntity.ts file with MyEntity, MyEntityReader, MyEntityConfig, and MyEntityExport types.

Running the code generator

The generator scans a directory for all *.struct.ts files and writes the corresponding *.ts output files next to them.

Programmatic usage

import {StructParser} from "@grest-ts/struct";

StructParser.build("./src/structs/");

CLI usage

npx tsx node_modules/@grest-ts/struct/src/generate.ts ./src/structs/

The generator only rewrites files whose content has actually changed, so it is safe to run on every build.

Configuration options

Pass a config object to new Struct(config):

| Option | Default | Description | |---|---|---| | useNew | false | Enables new() and free() methods for dynamic object allocation and deallocation. When false, the pool is fixed-size (all slots are always valid). | | useExport | false | Generates export() / import() methods and a Reader class for transferring data across workers or network. | | useDirty | false | Tracks which objects changed so only deltas are exported. Requires useExport. |

The combination of these flags determines which template is used for generation:

| useNew | useExport | useDirty | Use case | |---|---|---|---| | - | - | - | Fixed-size pool (e.g. map terrain tiles) | | yes | - | - | Dynamic pool without serialization | | - | yes | - | Read-only data transfer | | - | yes | yes | Change-tracked data transfer | | yes | yes | - | Dynamic pool with full-sync export | | yes | yes | yes | Full-featured: dynamic pool with dirty tracking |

Data types

| Method | Bits | TypedArray | TypeScript type | |---|---|---|---| | int8 | 8 | Int8Array | number | | uint8 | 8 | Uint8Array | number | | int16 | 16 | Int16Array | number | | uint16 | 16 | Uint16Array | number | | int32 | 32 | Int32Array | number | | uint32 | 32 | Uint32Array | number | | float32 | 32 | Float32Array | number | | float64 | 64 | Float64Array | number | | bool | 1 | Uint8Array (bitmask) | boolean | | bit | 1 | Uint8Array (bitmask) | number |

Multiple bool and bit fields are automatically packed into shared bytes.

Field modifiers

Each field method accepts optional modifiers after the name:

• ADD_MATH - Generates an addFieldName(ref, value) method in addition to the setter, allowing += style updates.
• MUST_EXIST - Marks the field as an existence indicator. Used with existenceCheck() so forEach / exists can skip empty slots by checking this field is non-zero.
• typed<T>() - Attaches a branded TypeScript type to the field. The getter returns T and the setter requires T. Works with type aliases, enums, and imported types.

.int16("x", ADD_MATH)                          // generates setX + addX
.uint32("spriteId", MUST_EXIST, typed<tSpriteId>())  // branded type + existence check
.int8("kind", typed<MyEnum>())                  // enum-typed field

Memory layout — AoS, SoA, and AoSoA

The .buffer() call controls how fields are laid out in memory. By choosing how you group fields into buffers, you get all three classic data layouts:

AoS (Array of Structures) — One buffer, all fields interleaved. Good when you always access all fields together.

new Struct()
    .buffer()
    .int16("x")
    .int16("y")
    .uint32("spriteId")
    .uint8("opacity")
// Memory: [x0,y0,spriteId0,opacity0, x1,y1,spriteId1,opacity1, ...]

SoA (Structure of Arrays) — Separate buffer per field. Best for iterating over a single field across all objects (cache-friendly).

new Struct()
    .buffer().int16("x")
    .buffer().int16("y")
    .buffer().uint32("spriteId")
    .buffer().uint8("opacity")
// Memory: [x0,x1,x2,...] [y0,y1,y2,...] [spriteId0,spriteId1,...] [opacity0,opacity1,...]

AoSoA (Array of Structures of Arrays) — Multiple buffers, each grouping related fields. A hybrid that keeps related data together while separating unrelated groups.

new Struct()
    .buffer()
    .int16("x")        // position chunk - accessed together during movement
    .int16("y")
    .buffer()
    .uint32("spriteId")  // rendering chunk - accessed together during draw
    .uint8("opacity")
// Memory: [x0,y0, x1,y1, ...] [spriteId0,opacity0, spriteId1,opacity1, ...]

Each .buffer() call starts a new chunk backed by its own ArrayBuffer. Within a chunk, fields for each object are interleaved. Choose the layout that matches your access patterns.

Branded reference types

Use .ref<T>() to give the pool a branded reference type. This prevents accidentally mixing references from different pools.

type tEntityRef = number & { tEntityRef: never };

new Struct()
    .ref<tEntityRef>()
    .buffer()
    .int16("x")

The generated getters and setters will require tEntityRef instead of plain number.

Using generated code

Basic (fixed-size pool)

import {BasicStruct, tRef} from "./BasicStruct";

const pool = new BasicStruct({initialNumberOfObjects: 1000});

const ref = 0 as tRef;
pool.setX(ref, 100).setY(ref, 200);

console.log(pool.getX(ref)); // 100

pool.forEach(ref => {
    // iterates over all slots (0..999)
});

Addable (dynamic allocation)

When useNew: true, objects are allocated and freed dynamically:

const pool = new MyStruct({initialNumberOfObjects: 100});

const ref = pool.new();       // allocate
pool.setX(ref, 42);
pool.free(ref);               // deallocate (slot is reused)

The pool automatically doubles its backing buffer when capacity is exceeded.

Exportable (data transfer)

When useExport: true, the generated code includes export() / import() and a Reader class:

// Writer side (e.g. main thread / server)
const writer = new MyStruct({initialNumberOfObjects: 100});
const ref = writer.new();
writer.setX(ref, 10);

const message = writer.export();
// send `message` to worker or over network

// Reader side (e.g. worker / client)
const reader = new MyStructReader();
reader.import(message);

reader.forEach(ref => {
    console.log(reader.getX(ref));
});

Dirty tracking

When useDirty: true, only modified objects are included in delta exports:

const pool = new MyStruct({initialNumberOfObjects: 100, fullSyncRatio: 0.7});

const ref = pool.new();
pool.setX(ref, 10);
pool.dirty(ref);        // mark as changed

const msg = pool.export();  // only includes dirty objects (delta sync)

Call dirty(ref) after modifying an object to include it in the next export. If the number of dirty objects exceeds fullSyncRatio * maxObjects, the export automatically falls back to a full sync.

The import() method on the reader accepts optional callbacks:

reader.import(message,
    (ref) => { /* called for each changed object */ },
    () => { /* called on full sync instead of per-object */ }
);

Complete example

// GameEntity.struct.ts
import {ADD_MATH, MUST_EXIST, Struct, typed} from "@grest-ts/struct";

type tEntityRef = number & { tEntityRef: never };
type tSpriteId = number & { tSpriteId: never };

export enum Direction { Up = 0, Down = 1, Left = 2, Right = 3 }

new Struct({useNew: true, useExport: true, useDirty: true})
    .ref<tEntityRef>()
    .buffer()
    .int16("x", ADD_MATH)
    .int16("y", ADD_MATH)
    .uint16("width")
    .uint16("height")
    .buffer()
    .uint32("spriteId", MUST_EXIST, typed<tSpriteId>())
    .uint8("opacity")
    .bool("isHighlighted")
    .bit("isAnimated")
    .int8("direction", typed<Direction>())

# Generate
npx tsx node_modules/@grest-ts/struct/src/generate.ts ./src/

// app.ts
import {GameEntity, GameEntityReader} from "./GameEntity";

const entities = new GameEntity({initialNumberOfObjects: 10000, fullSyncRatio: 0.5});

const e = entities.new();
entities.setSpriteId(e, 1 as tSpriteId);
entities.setX(e, 100);
entities.addY(e, 50);  // += 50
entities.dirty(e);

// Transfer to render worker
const snapshot = entities.export();
postMessage(snapshot);

// In the render worker
const view = new GameEntityReader();
onmessage = (msg) => {
    view.import(msg.data, (ref) => {
        updateSprite(ref, view.getX(ref), view.getY(ref), view.getSpriteId(ref));
    });
};