orderedjson

package
v0.5.3 Latest Latest
Warning

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

Go to latest
Published: Oct 23, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package orderedjson holds JSON objects that keep their keys in the order they were read or set, the way a JavaScript object does. MCP schemas and tool arguments cross the client unchanged, so their key order must survive a merge such as `{...schema, type: "object"}`.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AppendMembers

func AppendMembers(object []byte, members map[string]json.RawMessage) ([]byte, error)

AppendMembers returns the encoded JSON object with members added after its own, in sorted key order. No key of members may already be in object. With no members it returns object unchanged; otherwise the result does not alias object.

func IsObject

func IsObject(data []byte) bool

IsObject reports whether data is a JSON object.

func JSONNames

func JSONNames(t reflect.Type) map[string]struct{}

JSONNames returns the member names encoding/json reads and writes for the exported fields of the struct type t, which has no embedded fields: each field's json tag name, or its Go name when the tag gives none. A field tagged "-" has no member.

func Map

func Map(value any) (map[string]any, bool)

Map returns the members of a JSON object value, whether it is held as a map or as raw JSON.

func Marshal

func Marshal(value any) ([]byte, error)

Marshal is json.Marshal without HTML escaping. A MarshalJSON method returns text the encoder that called it then writes as it is or HTML-escapes as its own setting says, so text a method produces must not be escaped already: Pi's JSON.stringify never escapes `<`, `>` or `&`.

func MarshalArray

func MarshalArray(items []any, first ...string) ([]byte, error)

MarshalArray writes items as a JSON array in which each map item is written by MarshalMap with first; other items are written as encoding/json writes them. A nil slice is `[]`.

func MarshalInSourceOrder

func MarshalInSourceOrder(value any, source []byte) ([]byte, error)

MarshalInSourceOrder encodes value with the object member order of the JSON text source, as a JavaScript object holds the members its handlers edited: a member the source lists keeps its place, a member it does not list follows in sorted order, a removed member is gone, and integer-like keys come first in ascending order, as in every JavaScript object. A map has no insertion order, so two members added after the source was taken are sorted. An array matches its source element by element. A source that is not the same shape as value orders nothing, and the members are sorted.

func MarshalMap

func MarshalMap(members map[string]any, first ...string) ([]byte, error)

MarshalMap writes a map's members with the keys of first in that order when present, then the rest sorted: the order a JavaScript object built member by member has when its creator is known.

func UnmarshalFields

func UnmarshalFields(data []byte, v any, members ...string) error

UnmarshalFields decodes data into v, a pointer to a struct, like encoding/json, then replaces each named member of an `any` field with Value of its raw JSON, so an object an extension supplied is not reordered by a Go map. A named member absent from data leaves its field as it is. v must not have an UnmarshalJSON method that calls UnmarshalFields: decode into a local alias type.

It decodes data once: each named field (an `any` holding nil) is pointed at a placeholder that keeps the decoder from building the member as a map, and the member's raw JSON is found by a walk over the top-level object. Anything that walk cannot settle exactly as the three decodes did (an error, a field already set or not an `any`, a key that matches a member only case-insensitively) takes those decodes.

func Value

func Value(raw []byte) any

Value and UnmarshalFields use the shared host/Go-SDK codec, which keeps an unmatched UTF-16 unit as the WTF-8 representation (extensions/sdk/json/README.md); a raw container keeps a lone surrogate as its lowercase escape, as JSON.stringify writes it.

Value decodes one JSON value a JavaScript object would hold. A container stays a json.RawMessage holding JSON.stringify(JSON.parse(raw)): the member order it was written in (integer-like keys first, ascending, as a JavaScript object orders them), and numbers and strings in the form JSON.stringify writes, whichever SDK encoded it (Python writes `1.0` and `\u00e9`, the Go SDK `\u003c`). A scalar decodes as encoding/json decodes it into an `any`. Absent, empty, null and invalid input is nil. The result does not alias raw.

Types

type Object

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

Object is a JSON object with its keys in JavaScript enumeration order: the array-index keys ("0", "7", "42") in ascending order, then the other keys in insertion order. Values stay raw, so numbers and nested objects keep their exact text.

func New

func New() *Object

New returns an empty object.

func Parse

func Parse(data []byte) (*Object, error)

Parse decodes data as a JSON object. It returns an error for any other JSON value, including null.

func (*Object) Clone

func (o *Object) Clone() *Object

Clone returns a copy that shares no key storage.

func (*Object) Delete

func (o *Object) Delete(key string)

Delete removes key.

func (*Object) Get

func (o *Object) Get(key string) (json.RawMessage, bool)

Get returns the raw value of key.

func (*Object) Has

func (o *Object) Has(key string) bool

Has reports whether key is present, even with a null value.

func (*Object) Keys

func (o *Object) Keys() []string

Keys returns the keys in order.

func (*Object) Len

func (o *Object) Len() int

Len is the number of keys.

func (*Object) MarshalJSON

func (o *Object) MarshalJSON() ([]byte, error)

MarshalJSON writes the keys in order.

func (*Object) Set

func (o *Object) Set(key string, value json.RawMessage)

Set replaces the value of an existing key in place or adds a new key: after the other keys, or among the array-index keys at its ascending place.

func (*Object) SetValue

func (o *Object) SetValue(key string, value any) error

SetValue marshals value and sets it under key.

func (*Object) UnmarshalJSON

func (o *Object) UnmarshalJSON(data []byte) error

UnmarshalJSON reads an object and keeps its key order. A repeated key keeps its first position and its last value, as JSON.parse does.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL