jsonx

Documentation

Overview

SPDX-License-Identifier: Apache-2.0 Deterministic JSON that is byte-identical to the Node reference implementation.

src/core/util.mjs writes every record with stableStringify: JSON.stringify of a value whose object keys have been sorted, two-space indent, trailing newline. Matching that exactly is what lets a .fridge/ written by this binary be read, rewritten and diffed by the Node CLI without churn, so this file reimplements JSON.stringify's number formatting and string escaping rather than leaning on encoding/json, whose HTML escaping and float formatting differ.

Index

• func Compact(v any) string
• func FormatNumber(f float64) string
• func Indent(v any, ord Ordering) string
• func LessUTF16(a, b string) bool
• func Normalize(v any) any
• func Parse(data []byte) (any, error)
• func Stable(v any) string
• type Arr
• type Obj
  • func DeepMerge(base, over Obj) Obj
  • func ParseObj(data []byte) (Obj, error)
  • func (o Obj) ArrAt(dotted string) Arr
  • func (o Obj) Bool(dotted string) bool
  • func (o Obj) Clone() Obj
  • func (o Obj) Get(dotted string) any
  • func (o Obj) Int(dotted string) int
  • func (o Obj) Num(dotted string) float64
  • func (o Obj) ObjAt(dotted string) Obj
  • func (o Obj) Set(dotted string, value any) error
  • func (o Obj) Str(dotted string) string
  • func (o Obj) Strings(dotted string) []string
  • func (o Obj) With(fields Obj) Obj
• type Ordering

Functions

func Compact

func Compact(v any) string

Compact renders a value with no indentation and no trailing newline, the equivalent of JSON.stringify(value) after key sorting.

func FormatNumber

func FormatNumber(f float64) string

FormatNumber implements the ECMAScript Number::toString algorithm, which is what JSON.stringify uses. Go's %g would print 1e+21 as 1e+21 but 100000 as 100000 with different thresholds, so the rules are spelled out here.

func Indent

func Indent(v any, ord Ordering) string

Indent renders a value the way JSON.stringify(value, null, 2) does, with no trailing newline and with the key order the Ordering supplies. It exists so that human-facing text can reproduce the Node writer's insertion order.

func LessUTF16

func LessUTF16(a, b string) bool

LessUTF16 orders strings the way Array.prototype.sort does, by UTF-16 code unit. For the ASCII keys this protocol uses it is plain byte order; the slow path only runs when a record carries a non-ASCII key.

func Normalize

func Normalize(v any) any

Normalize converts ordinary Go values into the small JSON value model, so callers can write Obj{"pid": 42, "include": []string{"src/**"}} directly.

func Parse

func Parse(data []byte) (any, error)

Parse decodes JSON text into the value model. Numbers become float64, which is exactly the precision JSON.parse gives the Node implementation.

func Stable

func Stable(v any) string

Stable renders a value the way stableStringify does: sorted keys, two-space indent, trailing newline.

Types

type Arr

type Arr []any

Arr is a JSON array.

type Obj

type Obj map[string]any

Obj is a JSON object. Keys are sorted on the way out, never on the way in.

func DeepMerge

func DeepMerge(base, over Obj) Obj

DeepMerge layers `over` on top of `base`, recursing into objects and replacing arrays wholesale. It matches the deepMerge in src/core/store.mjs.

func ParseObj

func ParseObj(data []byte) (Obj, error)

ParseObj decodes JSON text that must be an object.

func (Obj) ArrAt

func (o Obj) ArrAt(dotted string) Arr

ArrAt returns a nested array, or nil.

func (Obj) Bool

func (o Obj) Bool(dotted string) bool

Bool returns a boolean field, or false when it is missing or another type.

func (Obj) Clone

func (o Obj) Clone() Obj

Clone deep-copies an object so a rewrite never mutates a shared record.

func (Obj) Get

func (o Obj) Get(dotted string) any

Get walks a dotted path and returns nil when any hop is missing.

func (Obj) Int

func (o Obj) Int(dotted string) int

Int returns a numeric field truncated to an int.

func (Obj) Num

func (o Obj) Num(dotted string) float64

Num returns a numeric field, or 0 when it is missing or another type.

func (Obj) ObjAt

func (o Obj) ObjAt(dotted string) Obj

ObjAt returns a nested object, or nil.

func (Obj) Set

func (o Obj) Set(dotted string, value any) error

Set writes a value at a dotted path. It reports an error when an intermediate hop is missing or is not an object, which is what `fridge config a.b c` surfaces as E_NOT_FOUND.

func (Obj) Str

func (o Obj) Str(dotted string) string

Str returns a string field, or "" when it is missing or another type.

func (Obj) Strings

func (o Obj) Strings(dotted string) []string

Strings returns a nested array as a []string, skipping non-strings.

func (Obj) With

func (o Obj) With(fields Obj) Obj

With returns a copy with the given fields replaced, the Go spelling of the `{ ...claim, state: 'released' }` idiom the Node code uses everywhere.

type Ordering

type Ordering func(path string) []string

Ordering supplies an explicit key order for the object at a dotted path. Returning nil for a path falls back to sorted order.