README
¶
orderedobject
A generic ordered JSON object for Go that preserves insertion order during mutation, iteration, and JSON encoding
Features
- Ordered keys: Preserve top-level insertion order when encoding JSON.
- Generic values: Store
anyor concrete types with the same API. - Stable updates: Updating an existing key keeps its original position.
- Streaming hooks: Use
MarshalJSONToandUnmarshalJSONFromfor token-based JSON work. - Map bridges: Convert to and from
map[string]Vwhen order does not matter. - Runnable examples: Explore focused programs under
examples/.
Installation
Requires Go 1.26+.
go get github.com/kaptinlin/orderedobject
Quick Start
package main
import (
"fmt"
"log"
"github.com/kaptinlin/orderedobject"
)
func main() {
person := orderedobject.NewObject[any]().
Set("name", "Alice").
Set("age", 30).
Set("city", "New York")
data, err := person.ToJSON()
if err != nil {
log.Fatal(err)
}
fmt.Println(string(data))
}
Output:
{"name":"Alice","age":30,"city":"New York"}
API Overview
| API | Purpose |
|---|---|
NewObject[V](capacity...) |
Create a new ordered object with optional capacity. |
FromMap[V](m) |
Build an object from a map; resulting order follows Go's map iteration order. |
FromJSON[V](data) |
Decode a JSON object while preserving member order. |
Set, Get, Has, Delete |
Mutate and query keys. |
Keys, Values, Entries, ForEach |
Iterate in insertion order. |
Clone |
Copy the entries slice without deep-copying stored values. |
ToMap |
Convert to a plain map and drop ordering semantics. |
ToJSON, MarshalJSON, MarshalJSONTo |
Encode ordered content to JSON. |
UnmarshalJSON, UnmarshalJSONFrom |
Decode ordered content from JSON. |
Examples
Preserve order while updating values
obj := orderedobject.NewObject[int]().
Set("first", 1).
Set("second", 2)
obj.Set("first", 99)
fmt.Println(obj.Keys())
// [first second]
Use concrete value types
type User struct {
Name string
Age int
}
users := orderedobject.NewObject[User]().
Set("alice", User{Name: "Alice", Age: 30}).
Set("bob", User{Name: "Bob", Age: 25})
user, _ := users.Get("alice")
fmt.Println(user.Name)
// Alice
Run the bundled examples
go run ./examples/basic
go run ./examples/json
go run ./examples/nested
See examples/README.md for the full example list.
Development
task test
task lint
For development guidelines, see AGENTS.md.
Contributing
Run task fmt, task test, and task lint before sending changes.
License
This project is licensed under the MIT License. See LICENSE for details.
Documentation
¶
Overview ¶
Package orderedobject provides an ordered JSON object that preserves key insertion order during JSON marshaling and unmarshaling.
Index ¶
- Variables
- type Entry
- type Object
- func (o *Object[V]) Clone() *Object[V]
- func (o *Object[V]) Delete(key string) *Object[V]
- func (o *Object[V]) Entries() []Entry[V]
- func (o *Object[V]) ForEach(fn func(key string, value V))
- func (o *Object[V]) Get(key string) (V, bool)
- func (o *Object[V]) Has(key string) bool
- func (o *Object[V]) Keys() []string
- func (o *Object[V]) Len() int
- func (o *Object[V]) MarshalJSON() ([]byte, error)
- func (o *Object[V]) MarshalJSONTo(enc *jsontext.Encoder) error
- func (o *Object[V]) Set(key string, value V) *Object[V]
- func (o *Object[V]) ToJSON() ([]byte, error)
- func (o *Object[V]) ToMap() map[string]V
- func (o *Object[V]) UnmarshalJSON(data []byte) error
- func (o *Object[V]) UnmarshalJSONFrom(dec *jsontext.Decoder) error
- func (o *Object[V]) Values() []V
- type OrderedMarshaler
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrExpectedObjectStart is returned when the next JSON token is not '{'. ErrExpectedObjectStart = errors.New("expected object start") // ErrExpectedStringKey is returned when the next JSON token is not a string key. ErrExpectedStringKey = errors.New("expected string key") )
Functions ¶
This section is empty.
Types ¶
type Entry ¶
type Entry[V any] struct { // Key is the object member name. Key string // Value is the value associated with Key. Value V }
Entry holds one key-value pair in an Object.
type Object ¶
type Object[V any] struct { // contains filtered or unexported fields }
Object stores key-value pairs in insertion order.
func FromJSON ¶
FromJSON decodes data into an Object, preserving key order from the input. FromJSON returns an error if data is not valid JSON or does not encode an object.
func FromMap ¶
FromMap returns an Object containing the entries in m. The resulting entry order matches Go's randomized map iteration order.
func (*Object[V]) Delete ¶
Delete removes key and returns o. Delete is a no-op if key is not present.
func (*Object[V]) Get ¶
Get returns the value for key and whether key is present. If key is not present, Get returns the zero value of V and false.
func (*Object[V]) MarshalJSON ¶
MarshalJSON returns the JSON encoding of o.
func (*Object[V]) MarshalJSONTo ¶
MarshalJSONTo writes the JSON encoding of o to enc. Nested map values are encoded with deterministic key order.
func (*Object[V]) Set ¶
Set stores value under key and returns o. If key already exists, Set updates its value without changing its position.
func (*Object[V]) ToJSON ¶
ToJSON returns the JSON encoding of o.
Example ¶
package main
import (
"fmt"
"github.com/kaptinlin/orderedobject"
)
func main() {
person := orderedobject.NewObject[any]().
Set("name", "Alice").
Set("age", 30).
Set("city", "New York")
data, err := person.ToJSON()
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(data))
}
Output: {"name":"Alice","age":30,"city":"New York"}
func (*Object[V]) ToMap ¶
ToMap returns a new map containing o's entries. The returned map does not preserve insertion order.
func (*Object[V]) UnmarshalJSON ¶
UnmarshalJSON decodes a JSON object into o.
func (*Object[V]) UnmarshalJSONFrom ¶
UnmarshalJSONFrom decodes a JSON object from dec into o. UnmarshalJSONFrom replaces any existing entries in o.
type OrderedMarshaler ¶ added in v0.1.2
type OrderedMarshaler interface {
// MarshalJSONTo writes the JSON encoding of the value to enc.
MarshalJSONTo(enc *jsontext.Encoder) error
}
OrderedMarshaler marshals a value to JSON while preserving key order.
Source Files
Directories