Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

refactor: readme improvements #16

Merged
merged 2 commits into from
Dec 21, 2023
Merged

refactor: readme improvements #16

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
05d4adc
refactor: readme improvements
mrrubinos Dec 3, 2023
5b2ba7e
refactor: readme improvements commented by Javi.
mrrubinos Dec 18, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 22 additions & 12 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,26 @@
# njson
[![njson](https://github.com/nomasystems/njson/actions/workflows/ci.yml/badge.svg)](https://github.com/nomasystems/njson/actions/workflows/ci.yml)

`njson` is an OTP library to pragmatically and efficiently encode and decode JSON to Erlang maps.
`njson` is a robust and efficient Erlang library that seamlessly encodes and decodes JSON
data into Erlang terms, encoding JSON objects as Erlang maps.
It is designed to be pragmatic and efficient, making it an ideal choice for a wide range
of Erlang applications.


## Features and implementation decisions

njson offers a comprehensive set of features for handling JSON data in Erlang:

- **Easy-to-use API**: njson provides a straightforward API that makes it easy to encode
and decode JSON data.
- **Efficient decoding**: njson's decoding is optimized for performance, ensuring
efficient processing of large JSON payloads.
- **Binary key support**: njson encodes and decodes JSON data using binary keys,
improving memory usage and performance. This also avoids atom table overflow vulnerability.
- **Duplicated key handling**: njson adheres to the [RFC recommendation](https://datatracker.ietf.org/doc/html/rfc8259#section-4)
that object keys should be unique, eliminating potential conflicts.
- **Flexible encoding options**: njson supports encoding as both binary and iolist,
catering to different performance requirements.

## Setup

Expand All @@ -14,24 +33,15 @@ Add `njson` to your project dependencies.
]}.
```

## Features
## Usage

`njson` exposes utilities via its API that allows you to:
`njson` provides two primary functions for encoding and decoding JSON data:

| Function | Description |
| -------- | ------------ |
| `njson:decode/1` | Decodes a JSON binary as Erlang map |
| `njson:encode/2` | Encodes a map with binary keys as JSON |


## Implementation

`njson` aims to be pragmatic and efficient.
To do so, it decodes JSON to erlang maps with binary keys.
Someone might argue about duplicated keys.
We don't see any practical use for this feature,
and the [RFC support this claim](https://datatracker.ietf.org/doc/html/rfc8259#section-4) ``The names within an object SHOULD be unique.``

## A simple example

```erl
Expand Down