insaneJSON

Insane JSON

Fast, zero-allocation JSON library for Go. Decode, navigate, mutate, and encode JSON without unmarshalling into Go structs. Designed for high-throughput pipelines where performance matters.

Installation

go get github.com/ozontech/insane-json

Quick Start

root, err := insaneJSON.DecodeString(`{"name":"John","age":30}`)
if err != nil {
    panic(err)
}
defer insaneJSON.Release(root)

name := root.Dig("name").AsString()   // "John"
age := root.Dig("age").AsInt()        // 30

root.Dig("age").MutateToInt(31)
root.AddField("active").MutateToBool(true)

output := root.Encode(nil) // []byte: {"name":"John","age":31,"active":true}

Examples

Extracting fields from API response

root, err := insaneJSON.DecodeBytes(responseBody)
if err != nil {
    return err
}
defer insaneJSON.Release(root)

status := root.Dig("response", "status").AsString()
code := root.Dig("response", "code").AsInt()
items := root.Dig("response", "data", "items")

if items.IsArray() {
    for _, item := range items.AsArray() {
        id := item.Dig("id").AsInt()
        name := item.Dig("name").AsString()
        fmt.Printf("id=%d name=%s\n", id, name)
    }
}

Transforming JSON logs

root, err := insaneJSON.DecodeBytes(logLine)
if err != nil {
    return err
}
defer insaneJSON.Release(root)

// add tracing info
root.AddField("trace_id").MutateToString(traceID)
root.AddField("processed_at").MutateToString(time.Now().Format(time.RFC3339))

// remove sensitive data
root.Dig("request", "headers", "Authorization").Suicide()
root.Dig("request", "body", "password").Suicide()

// rename field
root.DigField("level").MutateToField("log_level")

output = root.Encode(output[:0])

Filtering array elements

root, err := insaneJSON.DecodeString(`{"users":[{"name":"Alice","active":true},{"name":"Bob","active":false},{"name":"Carol","active":true}]}`)
if err != nil {
    return err
}
defer insaneJSON.Release(root)

users := root.Dig("users")
for _, user := range users.AsArray() {
    if !user.Dig("active").AsBool() {
        user.Suicide()
    }
}

fmt.Println(root.EncodeToString())
// {"users":[{"name":"Alice","active":true},{"name":"Carol","active":true}]}

High-throughput processing with Root reuse

root := insaneJSON.Spawn()
defer insaneJSON.Release(root)

buf := make([]byte, 0, 4096)

scanner := bufio.NewScanner(file)
for scanner.Scan() {
    if err := root.DecodeBytes(scanner.Bytes()); err != nil {
        continue
    }

    root.AddField("source").MutateToString("pipeline-v2")

    buf = root.Encode(buf[:0])
    writer.Write(buf)
}

Working with nested JSON

root, err := insaneJSON.DecodeString(`{"a":{"b":{"c":"deep"}}}`)
if err != nil {
    return err
}
defer insaneJSON.Release(root)

// Dig traverses nested objects
value := root.Dig("a", "b", "c").AsString() // "deep"

// array elements accessed by string index
root2, _ := insaneJSON.DecodeString(`{"items":["zero","one","two"]}`)
defer insaneJSON.Release(root2)

second := root2.Dig("items", "1").AsString() // "one"

Strict mode with error handling

root, err := insaneJSON.DecodeString(`{"count":"not a number"}`)
if err != nil {
    return err
}
defer insaneJSON.Release(root)

node, err := root.DigStrict("count")
if err != nil {
    return err // insaneJSON.ErrNotFound
}

count, err := node.AsInt()
if err != nil {
    return err // insaneJSON.ErrNotNumber
}

Merging objects

root, _ := insaneJSON.DecodeString(`{"a":"1","b":"2"}`)
defer insaneJSON.Release(root)

patch, _ := root.DecodeStringAdditional(`{"b":"updated","c":"3"}`)

root.MergeWith(patch)
fmt.Println(root.EncodeToString())
// {"a":"1","b":"updated","c":"3"}

API Overview

Decode

Navigate

Read Values

Type Checks

Modify

Encode

Important Notes

Pool and Lifecycle

Decoded nodes live inside a pool managed by the Root. After calling Release(root), the Root and all its nodes are returned to the pool and must not be used. Accessing nodes after Release leads to undefined behavior.

root, _ := insaneJSON.DecodeString(`{"a":"b"}`)
node := root.Dig("a")

insaneJSON.Release(root)

// BUG: node belongs to the released root, this is undefined behavior
fmt.Println(node.AsString())

Always use defer insaneJSON.Release(root) right after decode.

Thread Safety

The top-level functions DecodeString, DecodeBytes, and Spawn are safe to call from multiple goroutines — they use sync.Pool internally.

However, a specific Root and its Nodes are not thread-safe. Do not share a Root between goroutines without synchronization. The typical pattern is one Root per goroutine:

// correct: each goroutine gets its own Root
for _, data := range items {
    go func(d []byte) {
        root, err := insaneJSON.DecodeBytes(d)
        if err != nil {
            return
        }
        defer insaneJSON.Release(root)
        // work with root...
    }(data)
}

Nil-safe Navigation

Dig on a nil node returns nil without panicking. This allows safe chaining:

// even if "a" doesn't exist, this won't panic — returns 0
value := root.Dig("a", "b", "c").AsInt()

As* methods on nil nodes return zero values ("", 0, false).

Use DigStrict when you need to distinguish "field not found" from "field is zero value":

node, err := root.DigStrict("user", "email")
if err != nil {
    // field doesn't exist
}
email, err := node.AsString()
if err != nil {
    // field exists but is not a string
}

Memory Management

For best performance, reuse Root objects instead of decoding into new ones:

root := insaneJSON.Spawn()
defer insaneJSON.Release(root)

for _, msg := range messages {
    root.DecodeBytes(msg)   // reuses internal buffers
    process(root)
}

Use root.ReleaseMem() after processing an unusually large JSON to free internal buffers:

root.DecodeBytes(hugeJSON)
process(root)
root.ReleaseMem() // release internal buffers to GC

Configuration

func init() {
    insaneJSON.StartNodePoolSize = 256
    insaneJSON.MapUseThreshold = 32
    insaneJSON.DisableBeautifulErrors = true
}