GoJay

GoJay is a performant JSON encoder/decoder for Golang (currently the most performant, see benchmarks).

It has a simple API and doesn't use reflection. It relies on small interfaces to decode/encode structures and slices.

Gojay also comes with powerful stream decoding features and an even faster Unsafe API.

There is also a code generation tool to make usage easier and faster.

Why another JSON parser?

I looked at other fast decoder/encoder and realised it was mostly hardly readable static code generation or a lot of reflection, poor streaming features, and not so fast in the end.

Also, I wanted to build a decoder that could consume an io.Reader of line or comma delimited JSON, in a JIT way. To consume a flow of JSON objects from a TCP connection for example or from a standard output. Same way I wanted to build an encoder that could encode a flow of data to a io.Writer.

This is how GoJay aims to be a very fast, JIT stream parser with 0 reflection, low allocation with a friendly API.

Get started

go get github.com/francoispqt/gojay

Encoder
Decoder
Stream API
Code Generation

Decoding

Decoding is done through two different API similar to standard encoding/json:

Unmarshal
Decode

Example of basic stucture decoding with Unmarshal:

import "github.com/francoispqt/gojay"

type user struct {
    id int
    name string
    email string
}
// implement gojay.UnmarshalerJSONObject
func (u *user) UnmarshalJSONObject(dec *gojay.Decoder, key string) error {
    switch key {
    case "id":
        return dec.Int(&u.id)
    case "name":
        return dec.String(&u.name)
    case "email":
        return dec.String(&u.email)
    }
    return nil
}
func (u *user) NKeys() int {
    return 3
}

func main() {
    u := &user{}
    d := []byte(`{"id":1,"name":"gojay","email":"gojay@email.com"}`)
    err := gojay.UnmarshalJSONObject(d, u)
    if err != nil {
        log.Fatal(err)
    }
}

with Decode:

func main() {
    u := &user{}
    dec := gojay.NewDecoder(bytes.NewReader([]byte(`{"id":1,"name":"gojay","email":"gojay@email.com"}`)))
    err := dec.DecodeObject(d, u)
    if err != nil {
        log.Fatal(err)
    }
}

Unmarshal API

Unmarshal API decodes a []byte to a given pointer with a single function.

Behind the doors, Unmarshal API borrows a *gojay.Decoder resets its settings and decodes the data to the given pointer and releases the *gojay.Decoder to the pool when it finishes, whether it encounters an error or not.

If it cannot find the right Decoding strategy for the type of the given pointer, it returns an InvalidUnmarshalError. You can test the error returned by doing if ok := err.(InvalidUnmarshalError); ok {}.

Unmarshal API comes with three functions:

Unmarshal

func Unmarshal(data []byte, v interface{}) error

UnmarshalJSONObject

func UnmarshalJSONObject(data []byte, v gojay.UnmarshalerJSONObject) error

UnmarshalJSONArray

func UnmarshalJSONArray(data []byte, v gojay.UnmarshalerJSONArray) error

Decode API

Decode API decodes a []byte to a given pointer by creating or borrowing a *gojay.Decoder with an io.Reader and calling Decode methods.

Getting a *gojay.Decoder or Borrowing

You can either get a fresh *gojay.Decoder calling dec := gojay.NewDecoder(io.Reader) or borrow one from the pool by calling dec := gojay.BorrowDecoder(io.Reader).

After using a decoder, you can release it by calling dec.Release(). Beware, if you reuse the decoder after releasing it, it will panic with an error of type InvalidUsagePooledDecoderError. If you want to fully benefit from the pooling, you must release your decoders after using.

Example getting a fresh an releasing:

str := ""
dec := gojay.NewDecoder(strings.NewReader(`"test"`))
defer dec.Release()
if err := dec.Decode(&str); err != nil {
    log.Fatal(err)
}

Example borrowing a decoder and releasing:

str := ""
dec := gojay.BorrowDecoder(strings.NewReader(`"test"`))
defer dec.Release()
if err := dec.Decode(&str); err != nil {
    log.Fatal(err)
}

*gojay.Decoder has multiple methods to decode to specific types:

Decode

func (dec *gojay.Decoder) Decode(v interface{}) error

DecodeObject

func (dec *gojay.Decoder) DecodeObject(v gojay.UnmarshalerJSONObject) error

DecodeArray

func (dec *gojay.Decoder) DecodeArray(v gojay.UnmarshalerJSONArray) error

DecodeInt

func (dec *gojay.Decoder) DecodeInt(v *int) error

DecodeBool

func (dec *gojay.Decoder) DecodeBool(v *bool) error

DecodeString

func (dec *gojay.Decoder) DecodeString(v *string) error

All DecodeXxx methods are used to decode top level JSON values. If you are decoding keys or items of a JSON object or array, don't use the Decode methods.

Example:

reader := strings.NewReader(`"John Doe"`)
dec := NewDecoder(reader)

var str string
err := dec.DecodeString(&str)
if err != nil {
    log.Fatal(err)
}

fmt.Println(str) // John Doe

Structs and Maps

UnmarshalerJSONObject Interface

To unmarshal a JSON object to a structure, the structure must implement the UnmarshalerJSONObject interface:

type UnmarshalerJSONObject interface {
	UnmarshalJSONObject(*gojay.Decoder, string) error
	NKeys() int
}

UnmarshalJSONObject method takes two arguments, the first one is a pointer to the Decoder (*gojay.Decoder) and the second one is the string value of the current key being parsed. If the JSON data is not an object, the UnmarshalJSONObject method will never be called.

NKeys method must return the number of keys to Unmarshal in the JSON object or 0. If zero is returned, all keys will be parsed.

Example of implementation for a struct:

type user struct {
    id int
    name string
    email string
}
// implement UnmarshalerJSONObject
func (u *user) UnmarshalJSONObject(dec *gojay.Decoder, key string) error {
    switch key {
    case "id":
        return dec.Int(&u.id)
    case "name":
        return dec.String(&u.name)
    case "email":
        return dec.String(&u.email)
    }
    return nil
}
func (u *user) NKeys() int {
    return 3
}

Example of implementation for a map[string]string:

// define our custom map type implementing UnmarshalerJSONObject
type message map[string]string

// Implementing Unmarshaler
func (m message) UnmarshalJSONObject(dec *gojay.Decoder, k string) error {
	str := ""
	err := dec.String(&str)
	if err != nil {
		return err
	}
	m[k] = str
	return nil
}

// we return 0, it tells the Decoder to decode all keys
func (m message) NKeys() int {
	return 0
}

Arrays, Slices and Channels

To unmarshal a JSON object to a slice an array or a channel, it must implement the UnmarshalerJSONArray interface:

type UnmarshalerJSONArray interface {
	UnmarshalJSONArray(*gojay.Decoder) error
}

UnmarshalJSONArray method takes one argument, a pointer to the Decoder (*gojay.Decoder). If the JSON data is not an array, the Unmarshal method will never be called.

Example of implementation with a slice:

type testSlice []string
// implement UnmarshalerJSONArray
func (t *testSlice) UnmarshalJSONArray(dec *gojay.Decoder) error {
	str := ""
	if err := dec.String(&str); err != nil {
		return err
	}
	*t = append(*t, str)
	return nil
}

func main() {
	dec := gojay.BorrowDecoder(strings.NewReader(`["Tom", "Jim"]`))
	var slice testSlice
	err := dec.DecodeArray(&slice)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(slice) // [Tom Jim]
	dec.Release()
}

Example of implementation with a channel:

type testChannel chan string
// implement UnmarshalerJSONArray
func (c testChannel) UnmarshalJSONArray(dec *gojay.Decoder) error {
	str := ""
	if err := dec.String(&str); err != nil {
		return err
	}
	c <- str
	return nil
}

func main() {
	dec := gojay.BorrowDecoder(strings.NewReader(`["Tom", "Jim"]`))
	c := make(testChannel, 2)
	err := dec.DecodeArray(c)
	if err != nil {
		log.Fatal(err)
	}
	for i := 0; i < 2; i++ {
		fmt.Println(<-c)
	}
	close(c)
	dec.Release()
}

Example of implementation with an array:

type testArray [3]string
// implement UnmarshalerJSONArray
func (a *testArray) UnmarshalJSONArray(dec *Decoder) error {
	var str string
	if err := dec.String(&str); err != nil {
		return err
	}
	a[dec.Index()] = str
	return nil
}

func main() {
	dec := gojay.BorrowDecoder(strings.NewReader(`["Tom", "Jim", "Bob"]`))
	var a testArray
	err := dec.DecodeArray(&a)
	fmt.Println(a) // [Tom Jim Bob]
	dec.Release()
}

Other types

To decode other types (string, int, int32, int64, uint32, uint64, float, booleans), you don't need to implement any interface.

Example of encoding strings:

func main() {
    json := []byte(`"Jay"`)
    var v string
    err := gojay.Unmarshal(json, &v)
    if err != nil {
        log.Fatal(err)
    }

Gojay

Install / Use

README