Euneus

An incredibly flexible and performant JSON parser, generator and formatter in pure Erlang.

Euneus is built on the top of the new OTP json module.

Both encoder and decoder fully conform to RFC 8259 and ECMA 404 standards and are tested using JSONTestSuite.

Detailed examples and further explanation can be found at hexdocs.

Installation

Erlang

% rebar.config
{deps, [
    json_polyfill, % Required only for OTP < 27
    {euneus, "2.3.0"}
]}.

Elixir

# mix.exs
defp deps do
  [
    {:json_polyfill, "~> 0.1"}, # Required only for OTP < 27
    {:euneus, "~> 2.3"}
  ]
end

Or consider using Exneus:

# mix.exs
defp deps do
  [
    {:json_polyfill, "~> 0.1"}, # Required only for OTP < 27
    {:exneus, "~> 0.1"}
  ]
end

Exneus is a wrapper of Euneus for Elixir.

Basic usage

1> euneus:encode(#{age => 68, name => <<"Joe Armstrong">>, nationality => <<"British">>}).
<<"{\"name\":\"Joe Armstrong\",\"age\":68,\"nationality\":\"British\"}">>
2> euneus:decode(v(1)).
#{<<"age">> => 68,<<"name">> => <<"Joe Armstrong">>,<<"nationality">> => <<"British">>}

Encode

The functions euneus:encode/1 euneus:encode/2 encodes an Erlang term into a binary JSON. The second argument of euneus:encode/2 are options.

Please see the m:euneus_encoder documentation for more examples and detailed explanation.

The data mapping and error reasons can be found in the OTP json encode function documentation.

Decode

The functions euneus:decode/1 and euneus:decode/2 decodes a binary JSON into an Erlang term. The second argument of euneus:decode/2 are options.

Please see the m:euneus_decoder documentation for more examples and detailed explanation.

The data mapping and error reasons can be found in the OTP json decode function documentation.

Stream

Three functions provide JSON decode streaming:

• euneus:decode_stream_start/1 - Equivalent to euneus:decode_stream_start(JSON, #{});
• euneus:decode_stream_start/2 - Begin parsing a stream of bytes of a JSON value;
• euneus:decode_stream_continue/2 - Continue parsing a stream of bytes of a JSON value.

Please see the m:euneus_decoder documentation for more examples and detailed explanation.

Format

Two functions provide JSON formatting:

• euneus:minify/1 - Removes any extra spaces and new line characters;
• euneus:format/2 - Formats the JSON by passing custom options.

Please see the m:euneus_formatter documentation for more examples and detailed explanation.

Benchmark

The benchmarks are implemented very simply, but they are a good start foroptimizing Euneus since no optimizations have been made. You will find the benchmark commands in euneus_benchmarker, and data and tests under the test folder.

Important

For the first benchmark run, bootstrapping erlperf is required:

$ rebar3 as benchmark shell

1> euneus_benchmarker:bootstrap().
===> Verifying dependencies...
===> Analyzing applications...
===> Compiling erlperf
===> Building escript for erlperf...
ok

Results

Setup:

• OS : Linux
• CPU: 12th Gen Intel(R) Core(TM) i9-12900HX
• VM : Erlang/OTP 27 [erts-15.0.1] [source] [64-bit] [smp:24:24] [ds:24:24:10] [async-threads:1] [jit:ns]

$ rebar3 as benchmark shell

1> euneus_benchmarker:encode_benchmark().
Code      ||   Samples       Avg   StdDev    Median      P99  Iteration    Rel
jiffy      1         3        26   36.69%        25       36   38474 us   100%
euneus     1         3        20   38.20%        18       29   49197 us    78%
thoas      1         3        10   36.06%         9       14     100 ms    38%

2> euneus_benchmarker:decode_benchmark().
Code       ||   Samples       Avg   StdDev    Median      P99  Iteration    Rel
euneus      1         3        24    2.44%        24       24   42268 us   100%
jiffy       1         3        19    3.09%        19       19   53589 us    79%
thoas       1         3        14    0.00%        14       14   71452 us    59%

Sponsors

If you like this tool, please consider sponsoring me. I'm thankful for your never-ending support ❤️

I also accept coffees ☕

License

Copyright (c) 2024 William Fank Thomé

Euneus is 100% open-source and community-driven. All components are available under the Apache 2 License on GitHub.

See LICENSE.md for more information.