Fason 0.8.0

Fason

An F# code generator that generates optimized (and Thoth-compatible) JSON encoders and decoders for F# types, without using reflection. Supports F# types (records, unions, tuples, collections, etc.) and .NET primitives and core types. See Supported types below for the full list. Compatible with Fable.

Usage

First, add Fason as a dependency to your project via NuGet. You need to also install the Fason code generation tool by running dotnet tool install Fason.Tool.

Then, annotate any types you want JSON encoders / decoders to be generated for with the FasonSerializable attribute. For example:

open Fason

[<FasonSerializable>]
type MyRecord = {
    hello: string
    world: int
}

To generate the encoders / decoders, run dotnet fason MyProject.fsproj, where MyProject.fsproj is the path to your F# project. This will create a Fason.Generated.fs file next to your project file. You can pass several projects at once by separating them with spaces.

Include the generated file in your project and call the generated Codecs.Register() once at startup, before any JSON conversion. Then use Json.serialize, Json.deserialize<'T>, Json.serializeObj, and Json.deserializeObj from the Fason namespace to convert your values between JSON and back. The Obj-suffixed functions take a Type and an obj instead of a concrete object, for cases where it might not be known at runtime.

open Fason

MyProject.Serialization.Codecs.Register()

let json = Json.serialize { hello = "hi"; world = 1 }
let value = Json.deserialize<MyRecord> json
let jsonObj = Json.serializeObj typeof<MyRecord> (box value)

Attributes

Fason looks for three attributes, all in the Fason namespace:

For example, this makes Fason generate codecs for Request, Response and ServerStatus, but not for Session, Audit or Deferred<'T>:

namespace MyNamespace

open System.Threading.Tasks
open Fason

type ServerStatus = { ok: bool }

[<FasonSerializable>]
module Api =
    type Request = { id: int }
    type Response = { ok: bool }

    [<FasonIgnore>]
    type Session = { token: string }

    type Audit = { session: Session; at: System.DateTime }

    [<FasonUnwrap>]
    type Deferred<'T>(compute: unit -> 'T) =
        member _.Value = compute ()

    type IApi =
        abstract member Send: request: Request -> Task<Response>
        abstract member Status: unit -> Deferred<ServerStatus>

Supported types

Fason supports generating encoders / decoders for these types, and for any combination of them:

Options

The Fason tool has the following options:

dotnet fason MyProject.fsproj... [--namespace <name>] [--output <path>] [--configuration <name>] [--hermes] [--watch] [--version]

Instead of --namespace and --output, a project can set the FasonNamespace and FasonOutput MSBuild properties. A relative FasonOutput is resolved against the project directory. This is the way to configure several projects in one run.

Benchmarks

Below are some benchmarks compared to Thoth's auto coders on different runtimes, averaged across 5 runs with many iterations. Those are against several documents of varying complexities and sizes (most are from sensitive production data and are not included in this repo). Keep in mind that this is just runtime encoding / decoding performance. Since this tool generates code, you're basically trading build time for this. In a real-world project I've been testing this on, the generated file added ~2s to the build time. Generating the code itself took an additional ~10s.

.NET 10

Fable + Node 22

Fable + Hermes