jp

jp is a byte buffer oriented library for parsing and manipulating JSON.

jp is a fork of jsonparser. It keeps the fast zero-allocation method for accessing individual values in a JSON document, and adds a few new features:

• Index allows you to parse a buffer full of JSON once and then read and manipulate it in various ways with minimal additional CPU and memory overhead.

• Patch allows you to create, manipulate, and apply JSON patches without needing excess remarshalling or memory allocation.

Rationale

The original jsonparser library is great for retrieving arbitrary values from JSON documents, but when you have to do a lot of it to the same (potentially large) document or make a lot of modifications to the document (which may be interspersed with additional reads), the overhead of reparsing the JSON can start to outweigh the benefits of having zero allocations.

Otherwise, it maintains the original jsonparser virtues of being easy to use, low overhead, and high performance when you don't want to marshal to and from a structure or a map.

Example

For the given JSON our goal is to extract the user's full name, number of github followers and avatar.

import "gitlab.com/rackn/jp"

...

data := []byte(`{
  "person": {
    "name": {
      "first": "Leonid",
      "last": "Bugaev",
      "fullName": "Leonid Bugaev"
    },
    "github": {
      "handle": "buger",
      "followers": 109
    },
    "avatars": [
      { "url": "https://avatars1.githubusercontent.com/u/14009?v=3&s=460", "type": "thumbnail" }
    ]
  },
  "company": {
    "name": "Acme"
  }
}`)

// You can specify key path by providing arguments to Get function
jp.Get(data, "person", "name", "fullName")

// There is `GetInt` and `GetBoolean` helpers if you exactly know key data type
jp.GetInt(data, "person", "github", "followers")

// When you try to get object, it will return you []byte slice pointer to data containing it
// In `company` it will be `{"name": "Acme"}`
jp.Get(data, "company")

// If the key doesn't exist it will throw an error
var size int64
if value, err := jp.GetInt(data, "company", "size"); err == nil {
  size = value
}

// You can use `ArrayEach` helper to iterate items [item1, item2 .... itemN]
jp.ArrayEach(data, func(value []byte, dataType jp.ValueType, offset int, err error) {
	fmt.Println(jp.Get(value, "url"))
}, "person", "avatars")

// Or use can access fields by index!
jp.GetString(data, "person", "avatars", "[0]", "url")

// Non-braced numeric indexes work too
jp.GetString(data, "person", "avatars", "0", "url")

// So do negative indexes -- they count from the end of the array, but incur additional overhead.
jp.GetString(data, "person", "avatars", "-1", "url")

// You can use `ObjectEach` helper to iterate objects { "key1":object1, "key2":object2, .... "keyN":objectN }
jp.ObjectEach(data, func(key []byte, value []byte, dataType jp.ValueType, offset int) error {
        fmt.Printf("Key: '%s'\n Value: '%s'\n Type: %s\n", string(key), string(value), dataType)
	return nil
}, "person", "name")

// If you want to fold, spindle, or mutilate your JSON, make an Index out of it:
idx, err := jp.MakeIndex(data)

// Now, you can make whatever changes you want in a lazy fashion:
idx.Delete("person","github")
idx.Add(`{"handle":"rackn","followers":0}`,"person","gitlab")

// And then create a new document with the changes:
data,_ = index.MarshalJSON()
// For more information see docs below

Reference

You can view the API on pkg.go.dev.

On keys ...string parameters

You will see that most of the functions take a parameter named keys as their final variable, with a type signature of ...string. All these functions can descend to arbitrary locations in a set of nested JSON objects and arrays in any combination.

When one of the functions is descending into a JSON object, it interprets whatever member of keys (the key) it is considering as a string that should match an object key.

When descending into an Array, the key must be in one of the following forms:

• A positive or negative integer. Values from 0 up refer to array indexes from the beginning of an array, and values from -1 down refer to indexes from the end of the array.
• As above but surrounded by []. This is the format that jsonparser supported, presumably for disambiguation.
• [-] or - when calling index.Add. This allows callers to append a value at the end of an array without knowing its length beforehand.

What makes it so fast?

• All of the core functions do not allocate and only parse through byte buffers. The values they return are slices of the byte buffer they were passed
• Creating Index values using IndexValue is single-pass and only parses enough to create a full Index of a single JSON object. It allocates the minimum amount of memory necessary to hold the key indexes, and initially maps all values directly to the buffer it was originally created from.
• Modifying values using Index methods do not modify the backing byte array.
• No automatic type conversions, by default everything is a []byte, but it provides you value type, so you can convert by yourself using provided helpers.
• Does not parse full record, only keys you specified when using the core functions.