@esfx/struct-type Package

Define structured types using @"@esfx/ArrayBuffer!" and @"@esfx/SharedArrayBuffer!".

Installation

npm i @esfx/struct-type

Usage

Basic Usage

TypeScript
JavaScript (CommonJS)

import { StructType, int32 } from "@esfx/struct-type";

// simple types
const Point = StructType([
    { name: "x", type: int32 },
    { name: "y", type: int32 },
] as const);

// complex types
const Line = StructType([
    { name: "from", type: Point },
    { name: "to", type: Point },
] as const);

// inherited types
const Point3D = StructType(Point, [
    { name: "z", type: int32 }
] as const);

// create instances
const p1 = new Point({ x: 1, y: 2 }); // by field name
const p2 = new Point([3, 4]); // by field ordinal

// copy contents
const buffer = new ArrayBuffer(16);
const l1 = new Line([p1, p2]);
l1.writeTo(buffer);

// read from field names
console.log(l1.from.x); // 1
console.log(l1.from.y); // 2
console.log(l1.to.x); // 3
console.log(l1.to.y); // 4

// read from field ordinals
console.log(l1[0][0]); // 1
console.log(l1[0][1]); // 2
console.log(l1[1][0]); // 3
console.log(l1[1][1]); // 4

// create from a buffer
const l2 = new Line(buffer);

const { StructType, int32 } = require("@esfx/struct-type");

// simple types
const Point = StructType([
    { name: "x", type: int32 },
    { name: "y", type: int32 },
]);

// complex types
const Line = StructType([
    { name: "from", type: Point },
    { name: "to", type: Point },
]);

// inherited types
const Point3D = StructType(Point, [
    { name: "z", type: int32 }
]);

// create instances
const p1 = new Point({ x: 1, y: 2 }); // by field name
const p2 = new Point([3, 4]); // by field ordinal

// copy contents
const buffer = new ArrayBuffer(16);
const l1 = new Line([p1, p2]);
l1.writeTo(buffer);

// read from field names
console.log(l1.from.x); // 1
console.log(l1.from.y); // 2
console.log(l1.to.x); // 3
console.log(l1.to.y); // 4

// read from field ordinals
console.log(l1[0][0]); // 1
console.log(l1[0][1]); // 2
console.log(l1[1][0]); // 3
console.log(l1[1][1]); // 4

// create from a buffer
const l2 = new Line(buffer);

Using with Workers

TypeScript
JavaScript (CommonJS)

import { StructType, int32 } from "@esfx/struct-type";
import { Worker, isMainThread, parentPort, workerData } from "worker_threads";

const ThreadData = StructType([
    { name: "itemsRemaining", type: int32 },
] as const);

function worker_thread() {
    // this is running in a background worker...
    const data = new ThreadData(workerData); // allocate struct using the SharedArrayBuffer
    while (data.itemsRemaining) {
        // do some work...
        data.itemsRemaining--;
    }
    parentPort.postMessage("done");
}

function main() {
    // this is running on the main thread...
    const data = new ThreadData(/*shared*/ true); // allocate struct using a SharedArrayBuffer
    data.itemsRemaining = 5;

    const worker = new Worker(__filename, { workerData: data.buffer });
    worker.on("message", message => {
        if (message === "done") {
            console.log(data.itemsRemaining); // 0
        }
    });
}

if (isMainThread) {
    main();
}
else if (parentPort) {
    worker_thread();
}

const { StructType, int32 } = require("@esfx/struct-type");
const { Worker, isMainThread, parentPort, workerData } = require("worker_threads");

const ThreadData = StructType([
    { name: "itemsRemaining", type: int32 },
]);

function worker_thread() {
    // this is running in a background worker...
    const data = new ThreadData(workerData); // allocate struct using the SharedArrayBuffer
    while (data.itemsRemaining) {
        // do some work...
        data.itemsRemaining--;
    }
    parentPort.postMessage("done");
}

function main() {
    // this is running on the main thread...
    const data = new ThreadData(/*shared*/ true); // allocate struct using a SharedArrayBuffer
    data.itemsRemaining = 5;

    const worker = new Worker(__filename, { workerData: data.buffer });
    worker.on("message", message => {
        if (message === "done") {
            console.log(data.itemsRemaining); // 0
        }
    });
}

if (isMainThread) {
    main();
}
else if (parentPort) {
    worker_thread();
}

Interfaces

ArrayType<TType>

Represents the constructor for a TypedArray

ArrayTypeConstructor

FixedLengthArrayType<TType, TFixedLength>

Represents the constructor for a fixed-length TypedArray

PrimitiveType<K, T>

Represents a primitive type.

StructDefinition<TFields, TOrder>

StructFieldDefinition

StructType<TDef>

Represents the constructor for a struct.

StructTypeConstructor

Represents the constructor for a struct type.

TypedArray<TType, TFixedLength>

Variables

ArrayType

Creates a new TypedArray type for a provided type.

Declaration

ArrayType: ArrayTypeConstructor

bigint64

A primitive type representing an 8-byte signed integer.

Aliases: i64, long

Declaration

bigint64: PrimitiveType<"bigint64", bigint>

biguint64

A primitive type representing an 8-byte unsigned integer.

Aliases: u64, ulong

Declaration

biguint64: PrimitiveType<"biguint64", bigint>

bool32

A primitive type representing a 4-byte signed boolean value.

Declaration

bool32: PrimitiveType<"bool32", boolean>

bool8

A primitive type representing a 1-byte unsigned boolean value.

Declaration

bool8: PrimitiveType<"bool8", boolean>

endianness

Indicats the endianess of the system.

Declaration

endianness: Endianness

float32

A primitive type representing a 4-byte floating point number.

Aliases: f32, float

Declaration

float32: PrimitiveType<"float32", number>

float64

A primitive type representing an 8-byte floating point number.

Aliases: f64, double

Declaration

float64: PrimitiveType<"float64", number>

InitType

Declaration

InitType: unique symbol

int16

A primitive type representing a 2-byte signed integer.

Aliases: i16, short

Declaration

int16: PrimitiveType<"int16", number>

int32

A primitive type representing a 4-byte signed integer.

Aliases: i32, int

Declaration

int32: PrimitiveType<"int32", number>

int8

A primitive type representing a 1-byte signed integer.

Aliases: i8, sbyte

Declaration

int8: PrimitiveType<"int8", number>

isLittleEndian

Indicates whether the current system is little endian.

Declaration

isLittleEndian: boolean

RuntimeType

Declaration

RuntimeType: unique symbol

StructType

Creates a new Struct type from a provided field definition.

Declaration

StructType: StructTypeConstructor

uint16

A primitive type representing a 2-byte unsigned integer.

Aliases: u16, ushort

Declaration

uint16: PrimitiveType<"uint16", number>

uint32

A primitive type representing a 4-byte unsigned integer.

Aliases: u32, uint

Declaration

uint32: PrimitiveType<"uint32", number>

uint8

A primitive type representing a 1-byte unsigned integer.

Aliases: u8, byte

Declaration

uint8: PrimitiveType<"uint8", number>

Type Aliases

Endianness

Indicates whether the byte representation for an integer is either big-endian ("BE") or little-endian ("LE").

Declaration

export declare type Endianness = "BE" | "LE";

InitType

Gets a runtime type from a type definition that can be used to initialize a value of that type.

Declaration

export declare type InitType<TType extends Type> = TType[typeof InitType];

Type Parameters

TType

RuntimeType

Gets the runtime type from a type definition.

Declaration

export declare type RuntimeType<TType extends Type> = TType[typeof RuntimeType];

Type Parameters

TType

Struct

Represents an instance of a struct type.

Declaration

export declare type Struct<TDef extends StructDefinition = StructDefinition> = {
    readonly buffer: ArrayBufferLike;
    readonly byteOffset: number;
    readonly byteLength: number;
    get<K extends StructFieldLayoutKeys<TDef>>(key: K): StructFieldLayout<TDef>[K];
    set<K extends StructFieldLayoutKeys<TDef>>(key: K, value: StructFieldLayout<TDef>[K]): void;
    getIndex<I extends StructElementLayoutIndices<TDef>>(index: I): StructElementLayout<TDef>[I];
    setIndex<I extends StructElementLayoutIndices<TDef>>(index: I, value: StructElementLayout<TDef>[I]): boolean;
    writeTo(buffer: ArrayBufferLike, byteOffset?: number, byteOrder?: Endianness): void;
} & StructFieldLayout<TDef> & StructElementLayout<TDef>;

Type Parameters

TDef

StructArrayInit

Describes the ordered elements that can be used to initialize a struct.

Declaration

export declare type StructArrayInit<TDef extends StructDefinition> = TDef["order"] extends "unspecified" ? never : {
    [I in keyof TDef["order"]]: InitType<TDef["fields"][TDef["order"][I]]>;
};

Type Parameters

TDef

StructDefinitionOf

Declaration

export declare type StructDefinitionOf<TDef extends readonly StructFieldDefinition[]> = StructDefinition<{
    [I in Extract<numstr<keyof TDef>, number> as TDef[I]["name"]]: TDef[I]["type"];
}, {
    [I in keyof TDef]: TDef[I] extends StructFieldDefinition ? TDef[I]["name"] : TDef[I];
}>;

Type Parameters

TDef

StructElementLayout

Declaration

export declare type StructElementLayout<TDef extends StructDefinition> = {
    /**
     * Gets or sets a named field of the struct.
     */
    -readonly [I in StructElementLayoutIndices<TDef>]: RuntimeType<TDef["fields"][TDef["order"][I]]>;
};

Type Parameters

TDef

StructElementLayoutIndices

Declaration

export declare type StructElementLayoutIndices<TDef extends StructDefinition> = TDef["order"] extends "unspecified" ? never : numstr<keyof TDef["order"]>;

Type Parameters

TDef

StructFieldLayout

Declaration

export declare type StructFieldLayout<TDef extends StructDefinition> = {
    /**
     * Gets or sets a named field of the struct.
     */
    -readonly [K in StructFieldLayoutKeys<TDef>]: RuntimeType<TDef["fields"][K]>;
};

Type Parameters

TDef

StructFieldLayoutKeys

Declaration

export declare type StructFieldLayoutKeys<TDef extends StructDefinition> = keyof TDef["fields"];

Type Parameters

TDef

StructInheritedDefinition

Declaration

export declare type StructInheritedDefinition<TBaseDef extends StructDefinition, TFields extends {
    [key: string | symbol]: Type;
}, TOrder extends readonly (keyof TFields)[] | "unspecified"> = StructDefinition<TBaseDef["fields"] & TFields, TBaseDef["order"] extends "unspecified" ? TBaseDef["order"] : TOrder extends "unspecified" ? TBaseDef["order"] & "unspecified" : TOrder extends readonly (keyof TFields)[] ? [...TBaseDef["order"], ...TOrder] : "unspecified">;

Type Parameters

TBaseDef

TFields

TOrder

StructObjectInit

Describes the properties that can be used to initialize a struct.

Declaration

export declare type StructObjectInit<TDef extends StructDefinition> = {
    [P in keyof TDef["fields"]]: InitType<TDef["fields"][P]>;
};

Type Parameters

TDef

Type

Declaration

export declare type Type = PrimitiveType | StructType<any> | FixedLengthArrayType<any> | ArrayType<any>;