serde

    Attribute-driven static JSON codec generation for MoonBit

    serde
    json
    codegen
    Download zip
    Author
    Version
    0.1.0
    License
    MIT
    Last updated
    18 hours ago
    Downloads
    8

    #Serde for MoonBit

    Serde generates JSON encoders and decoders for MoonBit types. Add #custom.serde to a type to control how it reads and writes JSON.

    #Usage

    After setup, put this code in src/models.mbt:

    ///|
    #custom.serde(rename_all="camelCase")
    struct Profile {
    display_name : String
    #custom.serde(skip_serializing_if="Option::is_none")
    avatar_url : String?
    }

    Put this test in src/models_wbtest.mbt:

    ///|
    test "encode a profile without an avatar" {
    let profile : Profile = @json.from_json({ "displayName": "Aki" })
    assert_eq(ToJson::to_json(profile), { "displayName": "Aki" })
    }

    Run moon test src. Moon generates src/models.generated.mbt and the test checks the JSON output.

    #Key features

    • Use the standard MoonBit ToJson and @json.FromJson traits.
    • Generate codecs for records, enums, newtypes, and tuple structs, including generic types.
    • Set JSON field names, aliases, defaults, and nested object paths.
    • Select external, internal, adjacent, or untagged enum representations.
    • Get source locations for generation errors and JSON paths for decoding errors.

    #Prerequisites

    • MoonBit: Use version 0.1.20261117 or a compatible version.
    • Nix: Enable flakes to run the generator on Apple Silicon macOS or x86-64 Linux.

    #Setup

    [!NOTE] These instructions apply to the published release. Serde is not yet available on Mooncakes.

    From the root of your MoonBit module, add the library:

    moon add totto2727/serde

    #Run without installing

    moonx totto2727/serde-gen --help nix run github:totto2727-org/serde -- --help

    #Install

    nix profile add github:totto2727-org/serde

    Add the bin directory of your Nix profile to PATH if your shell cannot find serde-gen.

    #Nix flake

    Use the Serde overlay to add serde-gen to your development shell. Set system to aarch64-darwin or x86_64-linux.

    { inputs = { nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; serde.url = "github:totto2727-org/serde"; }; outputs = { nixpkgs, serde, ... }: let system = "aarch64-darwin"; pkgs = import nixpkgs { inherit system; overlays = [ serde.overlays.default ]; }; in { devShells.${system}.default = pkgs.mkShell { packages = [ pkgs.serde-gen ]; }; }; }

    #Generate code before a build

    src/moon.pkg:

    import {
    "moonbitlang/core/json",
    "totto2727/serde",
    }

    rule(name: "serde", command: "moonx totto2727/serde-gen $input --output $output")
    dev_build(rule: "serde", input: "models.mbt", output: "models.generated.mbt")

    #API

    #Development

    For project structure and development commands, see AGENTS.md.

    #License

    This README follows the share-artifact guidance and README template.

    deny_unknown

    Reject unexpected keys without changing the caller's object.

    deny_unknown_paths

    Check unknown keys at each object implied by fixed paths. Leaf decoders validate their own values.

    discriminator

    Read an internal or adjacent string discriminator.

    external

    Decode the externally tagged representation. None distinguishes a unit tag from an explicit null payload.

    field

    Resolve a field and its aliases, rejecting ambiguous input.

    invalid

    Report a wire-format error at the supplied JSON path.

    missing_field

    Report the key at the first absent path segment.

    object

    Codecs operate on dynamic JSON values because this package implements the serialization boundary itself.

    payload

    Require a variant's content, preserving the difference between absent and null.

    read_path

    Read fixed object keys and return the value, its location, and the first missing key or leaf key.

    unit

    Require the string form of an external unit variant or an absent adjacent content field.

    untagged

    Try candidates in declaration order. If none match, report each candidate's location and reason.

    write_path

    fn write_path(fields : Map[String,
    Json
    ], keys : Array[String], value :
    Json
    ) -> Unit

    Write a leaf into the generated object's already-validated, non-overlapping paths.

    Source Files