Typescript Flatbuffers Codegen (flattsc)

This package aims to simplify the use of flatbuffers in javascript/typescript.

Requirements

• Flatbuffers compiler (flatc) https://github.com/google/flatbuffers

Installation

yarn add @mgit-at/typescript-flatbuffers-codegen

or

npm install @mgit-at/typescript-flatbuffers-codegen

Generator usage

npx flattsc [OPTIONS] FILES...

Example

npx flattsc schema.fbs

Generates code for the file 'schema.fbs'

Simple generated code usage

Schema file:

table RootTable {
    name: NameTable;
}

table NameTable {
    firstname: string;
    lastname: string;
}

import {RootTable} from 'schema_generated';

const flatbuffersObject = BINARY_DATA;

const data = RootTable.fromFlatbuffers(flatbuffersObject);

console.log(data.name.firstname);
console.log(data.name.lastname);

Performance

Typescript Flatbuffers Codegen brings multiple performance and memory benefits.

Especially in use-cases where all or nearly all the data in the flatbuffers objects get parsed anyway, flattsc brings improvements in parsing time and memory usage.

Features

Typescript Flatbuffers Codegen adds some unique features to it's generated files, which the default flatbuffer compiler doesn't add:

Object API

Flattsc generates what the flatbuffer compiler calls object api. The whole flatbuffers object gets decoded as a whole and can be easily accessed and modified in javascript/typescript.

Proxy

The proxy feature helps reduce the time spent for the initial decode of the flatbuffers object, the objects will only get decoded if they are accessed.

This feature can be used by adding the proxy attribute to a field:

attribute "proxy";

table RootTable {
    data: ExpensiveToDecode (proxy);
}

table ExpensiveToDecode {
    name: string;
}

This also works for arrays:

attribute "proxy";

table RootTable {
    data: [ExpensiveToDecode] (proxy);
}

table ExpensiveToDecode {
    name: string;
}

By default the first 2 elements get decoded, other elements only get decoded if they are accessed.

The amount of initially decoded elements can also be set. This decodes 10:

table RootTable {
    data: [ExpensiveToDecode] (proxy:10);
}

Unique identifier

The uid feature helps reduce the amount of object duplicates in memory. A badly crafted flatbuffers object my contain an object multiple times. By setting a field as the unique identifier field, the object with this uid is memoized for additional references.

attribute "uid";

table RootTable {
    data: DuplicatedTable;
}

table DuplicatedTable {
    id: number (uid);
}

Object memoization and cyclic reference support

The code generated by flattsc only decodes every element in a flatbuffers object once and supports cyclic references.

License

Apache-2.0 License

Author Information

This package was initially created in 2020 by Patrick Pichler (@aveexy) from mgit GmbH.

Copyright 2020 mgIT GmbH.