jsony

package module
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 1, 2025 License: MIT Imports: 5 Imported by: 2

README

jsony

[ 📄 docs ] [ 🐙 github ]

A blazing fast and safe Go package for serializing JSON.

Features:

  • 2-3 times faster than stdlib
  • type safe and with no runtime errors or panics
  • pure go
  • reflection-free
  • objects preserve elements' order
  • objects can be constructed dynamically

📦 Installation

go get github.com/orsinium-labs/jsony

🔧 Usage

obj := jsony.Object{
   {"name", jsony.String("Aragorn")},
   {"age", jsony.Int(87)},
}
s := jsony.EncodeString(obj)
fmt.Println(s)

See documentation.

🐎 Benchmarks

Each value is time (in ns) per operation, as reported by the Go built-in benchmark framework. Lower is better.

category jsony stdlib
Int 15 🏆 54
Float64 63 🏆 122
String 22 🏆 88
Object 134 🏆 136
Map 246 🏆 662
MixedArray 125 🏆 271
IntArray 88 🏆 183
BigArray 64262 🏆 115994

To reproduce, run task bench

Documentation

Overview

There are 3 functions for generating JSON:

  • EncodeString serializes data into a string.
  • EncodeBytes serializes data into a slice of bytes.
  • AppendBytes is like EncodeBytes but allows you to provide a buffer to use.

Primitive types are constructed by:

Each of the above has a nullable version that serializes to null if the value is nil:

Collections are constructed by:

Lastly, there are 2 bridges between jsony and stdlib encoding/json:

Example 
package main

import (
	"fmt"

	"github.com/orsinium-labs/jsony"
)

func main() {
	user := jsony.Object{
		jsony.Field{"name", jsony.String("aragorn")},
		jsony.Field{"age", jsony.Int(87)},
		jsony.Field{"admin", jsony.Bool(true)},
	}
	res := jsony.EncodeString(user)
	fmt.Println(res)
}

Output:

{"name":"aragorn","age":87,"admin":true}

Index

Examples

Constants

View Source 
const (
	True  = Bool(true)
	False = Bool(false)
)
View Source 
const Null null = false

Variables

This section is empty.

Functions

func AppendBytes 

func AppendBytes(buf []byte, e Encoder) []byte

Marshal JSON into the end of the given slice of bytes.

Useful if you want to reduce allocations by reusing an existing buffer.

Example 
package main

import (
	"fmt"

	"github.com/orsinium-labs/jsony"
)

func main() {
	buf := make([]byte, 0, 1024)
	res := jsony.AppendBytes(buf, jsony.Object{})
	fmt.Printf("%v\n", res)
}

Output:

[123 125]

func Comment 

func Comment(s comment) comment

func EncodeBytes 

func EncodeBytes(e Encoder) []byte

Marshal JSON as a slice of bytes.

Example 
package main

import (
	"fmt"

	"github.com/orsinium-labs/jsony"
)

func main() {
	res := jsony.EncodeBytes(jsony.Object{})
	fmt.Printf("%v\n", res)
}

Output:

[123 125]

func EncodeString 

func EncodeString(e Encoder) string

Marshal JSON as a string.

Example 
package main

import (
	"fmt"

	"github.com/orsinium-labs/jsony"
)

func main() {
	res := jsony.EncodeString(jsony.Object{})
	fmt.Printf("%v\n", res)
}

Output:

{}

func SafeString 

func SafeString(s safeString) safeString
Example 
package main

import (
	"fmt"

	"github.com/orsinium-labs/jsony"
)

func main() {
	user := jsony.Object{
		jsony.Field{"name", jsony.SafeString("johny")},
	}
	res := jsony.EncodeString(user)
	fmt.Println(res)
}

Output:

{"name":"johny"}

Types

type A 

type A = MixedArray

One-letter aliases for people living on the edge.

type Array 

type Array[T Encoder] []T

Array of elements of the same type.

Example 
package main

import (
	"fmt"

	"github.com/orsinium-labs/jsony"
)

func main() {
	user := jsony.Array[jsony.Int]{
		jsony.Int(13), jsony.Int(14), jsony.Int(15),
	}
	res := jsony.EncodeString(user)
	fmt.Println(res)
}

Output:

[13,14,15]

func (Array[T]) EncodeJSON 

func (v Array[T]) EncodeJSON(w *Bytes)

EncodeJSON implements Encoder.

func (Array[T]) With added in v1.1.0 

func (v Array[T]) With(es ...T) Array[T]

Create a copy of the array with the given elements added to the end.

type B 

type B = Bool

One-letter aliases for people living on the edge.

type Bool 

type Bool bool
Example 
package main

import (
	"fmt"

	"github.com/orsinium-labs/jsony"
)

func main() {
	user := jsony.Object{
		jsony.Field{"admin", jsony.Bool(true)},
	}
	res := jsony.EncodeString(user)
	fmt.Println(res)
}

Output:

{"admin":true}

func (Bool) EncodeJSON 

func (v Bool) EncodeJSON(w *Bytes)

EncodeJSON implements Encoder.

type Bytes 

type Bytes struct {
	// contains filtered or unexported fields
}

Bytes is a slice of bytes that wraps [append] to require no assignment.

func (*Bytes) Append 

func (w *Bytes) Append(b byte)

func (*Bytes) Extend 

func (w *Bytes) Extend(b []byte)

type Encoder 

type Encoder interface {
	EncodeJSON(*Bytes)
}

Encoder is an interface describing objects that can be serialized to JSON.

func FromMarshaller 

func FromMarshaller(m marshaller) Encoder

FromMarshaller wraps an [json.Marshaller] to make it Encoder.

func PBool 

func PBool(v *bool) Encoder

PBool is a pointer version of Bool.

If the given value is nil, it will be serialized to null. Otherwise, behaves exactly as Bool.

func PFloat32 

func PFloat32(v *float32) Encoder

PFloat32 is a pointer version of Float32.

If the given value is nil, it will be serialized to null. Otherwise, behaves exactly as Float32.

func PFloat64 

func PFloat64(v *float64) Encoder

PFloat64 is a pointer version of Float64.

If the given value is nil, it will be serialized to null. Otherwise, behaves exactly as Float64.

func PInt 

func PInt(v *int) Encoder

PInt is a pointer version of Int.

If the given value is nil, it will be serialized to null. Otherwise, behaves exactly as Int.

func PInt16 

func PInt16(v *int16) Encoder

PInt16 is a pointer version of Int16.

If the given value is nil, it will be serialized to null. Otherwise, behaves exactly as Int16.

func PInt32 

func PInt32(v *int32) Encoder

PInt32 is a pointer version of Int32.

If the given value is nil, it will be serialized to null. Otherwise, behaves exactly as Int32.

func PInt64 

func PInt64(v *int64) Encoder

PInt64 is a pointer version of Int64.

If the given value is nil, it will be serialized to null. Otherwise, behaves exactly as Int64.

func PInt8 

func PInt8(v *int8) Encoder

PInt8 is a pointer version of Int8.

If the given value is nil, it will be serialized to null. Otherwise, behaves exactly as Int8.

func PString 

func PString(v *string) Encoder

PString is a pointer version of String.

If the given value is nil, it will be serialized to null. Otherwise, behaves exactly as String.

func PUInt 

func PUInt(v *uint) Encoder

PUInt is a pointer version of UInt.

If the given value is nil, it will be serialized to null. Otherwise, behaves exactly as UInt.

func PUInt16 

func PUInt16(v *uint16) Encoder

PUInt16 is a pointer version of UInt16.

If the given value is nil, it will be serialized to null. Otherwise, behaves exactly as UInt16.

func PUInt32 

func PUInt32(v *uint32) Encoder

PUInt32 is a pointer version of UInt32.

If the given value is nil, it will be serialized to null. Otherwise, behaves exactly as UInt32.

func PUInt64 

func PUInt64(v *uint64) Encoder

PUInt64 is a pointer version of UInt64.

If the given value is nil, it will be serialized to null. Otherwise, behaves exactly as UInt64.

func PUInt8 

func PUInt8(v *uint8) Encoder

PUInt8 is a pointer version of UInt8.

If the given value is nil, it will be serialized to null. Otherwise, behaves exactly as UInt8.

func PUIntPtr 

func PUIntPtr(v *uintptr) Encoder

PUIntPtr is a pointer version of UIntPtr.

If the given value is nil, it will be serialized to null. Otherwise, behaves exactly as UIntPtr.

type F 

type F = Float64

One-letter aliases for people living on the edge.

type Field 

type Field struct {
	K safeString
	V Encoder
}

A key-value pair, an Object's field.

type Float32 

type Float32 float32
Example 
package main

import (
	"fmt"

	"github.com/orsinium-labs/jsony"
)

func main() {
	user := jsony.Object{
		jsony.Field{"weight", jsony.Float32(62.3)},
	}
	res := jsony.EncodeString(user)
	fmt.Println(res)
}

Output:

{"weight":62.3}

func (Float32) EncodeJSON 

func (v Float32) EncodeJSON(w *Bytes)

EncodeJSON implements Encoder.

type Float64 

type Float64 float64
Example 
package main

import (
	"fmt"

	"github.com/orsinium-labs/jsony"
)

func main() {
	user := jsony.Object{
		jsony.Field{"weight", jsony.Float64(62.3)},
	}
	res := jsony.EncodeString(user)
	fmt.Println(res)
}

Output:

{"weight":62.3}

func (Float64) EncodeJSON 

func (v Float64) EncodeJSON(w *Bytes)

EncodeJSON implements Encoder.

type I 

type I = Int64

One-letter aliases for people living on the edge.

type Int 

type Int int
Example 
package main

import (
	"fmt"

	"github.com/orsinium-labs/jsony"
)

func main() {
	user := jsony.Object{
		jsony.Field{"age", jsony.Int(123)},
	}
	res := jsony.EncodeString(user)
	fmt.Println(res)
}

Output:

{"age":123}

func (Int) EncodeJSON 

func (v Int) EncodeJSON(w *Bytes)

EncodeJSON implements Encoder.

type Int16 

type Int16 int16
Example 
package main

import (
	"fmt"

	"github.com/orsinium-labs/jsony"
)

func main() {
	user := jsony.Object{
		jsony.Field{"age", jsony.Int16(123)},
	}
	res := jsony.EncodeString(user)
	fmt.Println(res)
}

Output:

{"age":123}

func (Int16) EncodeJSON 

func (v Int16) EncodeJSON(w *Bytes)

EncodeJSON implements Encoder.

type Int32 

type Int32 int32
Example 
package main

import (
	"fmt"

	"github.com/orsinium-labs/jsony"
)

func main() {
	user := jsony.Object{
		jsony.Field{"age", jsony.Int32(123)},
	}
	res := jsony.EncodeString(user)
	fmt.Println(res)
}

Output:

{"age":123}

func (Int32) EncodeJSON 

func (v Int32) EncodeJSON(w *Bytes)

EncodeJSON implements Encoder.

type Int64 

type Int64 int64
Example 
package main

import (
	"fmt"

	"github.com/orsinium-labs/jsony"
)

func main() {
	user := jsony.Object{
		jsony.Field{"age", jsony.Int64(123)},
	}
	res := jsony.EncodeString(user)
	fmt.Println(res)
}

Output:

{"age":123}

func (Int64) EncodeJSON 

func (v Int64) EncodeJSON(w *Bytes)

EncodeJSON implements Encoder.

type Int8 

type Int8 int8
Example 
package main

import (
	"fmt"

	"github.com/orsinium-labs/jsony"
)

func main() {
	user := jsony.Object{
		jsony.Field{"age", jsony.Int8(123)},
	}
	res := jsony.EncodeString(user)
	fmt.Println(res)
}

Output:

{"age":123}

func (Int8) EncodeJSON 

func (v Int8) EncodeJSON(w *Bytes)

EncodeJSON implements Encoder.

type M 

type M = Map

One-letter aliases for people living on the edge.

type Map 

type Map map[Encoder]Encoder

An object with dynamically set elements.

The order of items is non-deterministic. If the order is important, use UnsafeObject.

Unlike UnsafeObject, Map guarantees that there is only one element for each key.

Make sure the keys are either String or SafeString. JSON doesn't support non-string keys.

func (Map) EncodeJSON 

func (v Map) EncodeJSON(w *Bytes)

EncodeJSON implements Encoder.

type Marshaller 

type Marshaller struct {
	Encoder
}

Marshaller wraps an Encoder to make it [json.Marshaller].

Might be useful if you, for some reason, want to mix json with stdlib json.

func (Marshaller) MarshalJSON 

func (m Marshaller) MarshalJSON() ([]byte, error)

type MixedArray 

type MixedArray = Array[Encoder]

Array where every element can be of different type.

Example 
package main

import (
	"fmt"

	"github.com/orsinium-labs/jsony"
)

func main() {
	user := jsony.MixedArray{
		jsony.String("johny"), jsony.Int(14), jsony.Null,
	}
	res := jsony.EncodeString(user)
	fmt.Println(res)
}

Output:

["johny",14,null]

type O 

type O = Object

One-letter aliases for people living on the edge.

type Object 

type Object []Field

An object with fixed keys.

Example 
package main

import (
	"fmt"

	"github.com/orsinium-labs/jsony"
)

func main() {
	user := jsony.Object{
		jsony.Field{"name", jsony.String("aragorn")},
		jsony.Field{"age", jsony.Int(87)},
		jsony.Field{"admin", jsony.Bool(true)},
	}
	res := jsony.EncodeString(user)
	fmt.Println(res)
}

Output:

{"name":"aragorn","age":87,"admin":true}

func (Object) EncodeJSON 

func (v Object) EncodeJSON(w *Bytes)

EncodeJSON implements Encoder.

func (Object) With added in v1.1.0 

func (v Object) With(fs ...Field) Object

Create a copy of the object with the given fields added to the end.

type S 

type S = String

One-letter aliases for people living on the edge.

type SA added in v1.1.0 

type SA = SafeArray

One-letter aliases for people living on the edge.

type SafeArray added in v1.1.0 

type SafeArray = Array[safeString]

Array of SafeString.

type String 

type String string
Example 
package main

import (
	"fmt"

	"github.com/orsinium-labs/jsony"
)

func main() {
	user := jsony.Object{
		jsony.Field{"name", jsony.String("johny")},
	}
	res := jsony.EncodeString(user)
	fmt.Println(res)
}

Output:

{"name":"johny"}

func (String) EncodeJSON 

func (v String) EncodeJSON(w *Bytes)

EncodeJSON implements Encoder.

type U 

type U = UInt64

One-letter aliases for people living on the edge.

type UInt 

type UInt uint
Example 
package main

import (
	"fmt"

	"github.com/orsinium-labs/jsony"
)

func main() {
	user := jsony.Object{
		jsony.Field{"age", jsony.UInt(123)},
	}
	res := jsony.EncodeString(user)
	fmt.Println(res)
}

Output:

{"age":123}

func (UInt) EncodeJSON 

func (v UInt) EncodeJSON(w *Bytes)

EncodeJSON implements Encoder.

type UInt16 

type UInt16 uint16
Example 
package main

import (
	"fmt"

	"github.com/orsinium-labs/jsony"
)

func main() {
	user := jsony.Object{
		jsony.Field{"age", jsony.UInt16(123)},
	}
	res := jsony.EncodeString(user)
	fmt.Println(res)
}

Output:

{"age":123}

func (UInt16) EncodeJSON 

func (v UInt16) EncodeJSON(w *Bytes)

EncodeJSON implements Encoder.

type UInt32 

type UInt32 uint32
Example 
package main

import (
	"fmt"

	"github.com/orsinium-labs/jsony"
)

func main() {
	user := jsony.Object{
		jsony.Field{"age", jsony.UInt32(123)},
	}
	res := jsony.EncodeString(user)
	fmt.Println(res)
}

Output:

{"age":123}

func (UInt32) EncodeJSON 

func (v UInt32) EncodeJSON(w *Bytes)

EncodeJSON implements Encoder.

type UInt64 

type UInt64 uint64
Example 
package main

import (
	"fmt"

	"github.com/orsinium-labs/jsony"
)

func main() {
	user := jsony.Object{
		jsony.Field{"age", jsony.UInt64(123)},
	}
	res := jsony.EncodeString(user)
	fmt.Println(res)
}

Output:

{"age":123}

func (UInt64) EncodeJSON 

func (v UInt64) EncodeJSON(w *Bytes)

EncodeJSON implements Encoder.

type UInt8 

type UInt8 uint8
Example 
package main

import (
	"fmt"

	"github.com/orsinium-labs/jsony"
)

func main() {
	user := jsony.Object{
		jsony.Field{"age", jsony.UInt8(123)},
	}
	res := jsony.EncodeString(user)
	fmt.Println(res)
}

Output:

{"age":123}

func (UInt8) EncodeJSON 

func (v UInt8) EncodeJSON(w *Bytes)

EncodeJSON implements Encoder.

type UIntPtr 

type UIntPtr uintptr
Example 
package main

import (
	"fmt"

	"github.com/orsinium-labs/jsony"
)

func main() {
	user := jsony.Object{
		jsony.Field{"age", jsony.UIntPtr(123)},
	}
	res := jsony.EncodeString(user)
	fmt.Println(res)
}

Output:

{"age":123}

func (UIntPtr) EncodeJSON 

func (v UIntPtr) EncodeJSON(w *Bytes)

EncodeJSON implements Encoder.

type UO added in v1.1.0 

type UO = UnsafeObject

One-letter aliases for people living on the edge.

type UnsafeField added in v1.1.0 

type UnsafeField struct {
	K Encoder
	V Encoder
}

A key-value pair, an UnsafeObject's field.

type UnsafeObject added in v1.1.0 

type UnsafeObject []UnsafeField

An object with dynamically set elements.

Unlike Object, kays don't have to be a string literal. And unlike Map, the order of elements is preserved.

Make sure the keys are either String or SafeString. JSON doesn't support non-string keys.

func (UnsafeObject) EncodeJSON added in v1.1.0 

func (v UnsafeObject) EncodeJSON(w *Bytes)

EncodeJSON implements Encoder.

func (UnsafeObject) With added in v1.1.0 

func (v UnsafeObject) With(fs ...UnsafeField) UnsafeObject

Create a copy of the object with the given fields added to the end.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.