What are Structures?

Structures are data objects that can be encoded (converted to plain objects) and decoded (converted back to class instances). They are essential for:

• Storing JSON data in databases
• Sending data across networks (API)
• Storing data in the browser for caching and offline access
• Versioning: allowing data structure changes without breaking old clients
• Ensuring type safety when receiving data from the API or storage.

In Stamhoofd all structures are currently stored in the shared/structures folder. They are used by the backend and frontend. This facilitates seamless communication over the network and ensures secure data storage in both the database and browser.

The encoding and decoding behavior is mostly implemented in the @simonbackx/simple-encoding package.

Usage

Creating structures

The easiest way to create encodable and decodable structures is by extending the AutoEncoder class. Here's a basic example:

import { AutoEncoder, StringDecoder, NumberDecoder, field } from "@simonbackx/simple-encoding";

class MyClass extends AutoEncoder {
    @field({ decoder: NumberDecoder })
    id: number;

    @field({ decoder: StringDecoder })
    name: string;

    @field({ decoder: MyClass, nullable: true })
    other: MyClass | null = null;
}

Writing AutoEncoder classes

An alternative is manually implementing the encode and decode methods (more difficult + doesn’t provide patching behaviour out of the box): Manually implementing encode and decode

Encoding and decoding data

You can encode structures so you can store them as JSON in a file, in the database or send it over via the API.