orderedmap

README

OrderedMap

orderedmap is useful when JSON field ordering is relevant. encoding/json has no way to preserve the order of map keys. See https://github.com/golang/go/issues/27179.

Using JSONv2 is the future goal, which solves field order, other issues, and has other best practices.When Go Coze is migrated to JSONv2, as long as JSONv2 provides ordering, orderedmap will be deprecated. See https://github.com/Cyphrme/Coze/issues/15

Contributors

Thank you to peterbourgon for contributing!

---

Attribution, Trademark Notice, and License

OrderedMap is released under The 3-Clause BSD License.

"Cyphr.me" is a trademark of Cypherpunk, LLC. The Cyphr.me logo is all rights reserved Cypherpunk, LLC and may not be used without permission.

Documentation

Index

• func CheckDuplicate(d *json.Decoder) error
• type ErrJSONDuplicate
• type OrderedMap
  • func New() *OrderedMap
  • func (o *OrderedMap) Delete(key string)
  • func (o *OrderedMap) Get(key string) any
  • func (o *OrderedMap) GetKeyAt(pos int) string
  • func (o *OrderedMap) GetValueAt(pos int) any
  • func (o *OrderedMap) Keys() []string
  • func (o *OrderedMap) KeysValues() map[string]any
  • func (o *OrderedMap) Len() int
  • func (o OrderedMap) MarshalJSON() ([]byte, error)
  • func (o *OrderedMap) Set(key string, value any)
  • func (o *OrderedMap) Sort(lessFunc func(a *pair, b *pair) bool)
  • func (o *OrderedMap) SortKeys(sortFunc func(keys []string))
  • func (o *OrderedMap) UnmarshalJSON(b []byte) error
  • func (o *OrderedMap) Values() []any

Functions

func CheckDuplicate

func CheckDuplicate(d *json.Decoder) error

CheckDuplicate checks for JSON duplicates on ingest (unmarshal). Note that Go maps and structs and Javascript objects (ES6) already require unique JSON names. See the Coze FAQ on duplicates.

Duplicate JSON fields are a security issue that wasn't addressed by the original spec that results in surprising behavior and is a source of bugs. See the article, "[An Exploration of JSON Interoperability Vulnerabilities](https://bishopfox.com/blog/json-interoperability-vulnerabilities)" and control-f "duplicate".

Until Go releases the planned revision to the JSON package (See https://github.com/go-json-experiment/json), or adds support for erroring on duplicates to the current package, this function is needed.

After JSON was widely adopted, Douglas Crockford (JSON's inventor), tried to fix this by updating JSON to define "must error on duplicates" as the correct behavior, but it was decided it was too late (https://esdiscuss.org/topic/json-duplicate-keys).

Although Douglas Crockford couldn't change the JSON spec to force implementations to error on duplicate, his Java JSON implementation errors on duplicates. Others implementations behaviors are `last-value-wins`, support duplicate keys, or other non-standard behavior. The [JSON RFC](https://datatracker.ietf.org/doc/html/rfc8259#section-4) states that implementations should not allow duplicate keys. It then notes the varying behavior of existing implementations.

Disallowing duplicates conforms to the small I-JSON RFC. The author of I-JSON, Tim Bray, is also the author of current JSON specification (RFC 8259). See also https://github.com/json5/json5-spec/issues/38.

Types

type ErrJSONDuplicate

type ErrJSONDuplicate error

ErrJSONDuplicate allows applications to check for JSON duplicate error.

type OrderedMap

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

func New

func New() *OrderedMap

func (*OrderedMap) Delete

func (o *OrderedMap) Delete(key string)

func (*OrderedMap) Get

func (o *OrderedMap) Get(key string) any

func (*OrderedMap) GetKeyAt

func (o *OrderedMap) GetKeyAt(pos int) string

func (*OrderedMap) GetValueAt

func (o *OrderedMap) GetValueAt(pos int) any

func (*OrderedMap) Keys

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

func (*OrderedMap) KeysValues

func (o *OrderedMap) KeysValues() map[string]any

func (*OrderedMap) Len

func (o *OrderedMap) Len() int

func (OrderedMap) MarshalJSON

func (o OrderedMap) MarshalJSON() ([]byte, error)

MarshalJSON must return no duplicates, and should since orderedMap keys are unique.

func (*OrderedMap) Set

func (o *OrderedMap) Set(key string, value any)

func (*OrderedMap) Sort

func (o *OrderedMap) Sort(lessFunc func(a *pair, b *pair) bool)

Sort sorts the map using the provided less func.

func (*OrderedMap) SortKeys

func (o *OrderedMap) SortKeys(sortFunc func(keys []string))

SortKeys sorts the map keys using the provided sort func.

func (*OrderedMap) UnmarshalJSON

func (o *OrderedMap) UnmarshalJSON(b []byte) error

func (*OrderedMap) Values

func (o *OrderedMap) Values() []any