Documentation
¶
Overview ¶
Package jsonjs normalizes serialized JSON using JavaScript value semantics. It is shared by native AI, agent and telemetry code and uses only Go.
Index ¶
- Constants
- func ArrayIndex(key string) (uint64, bool)
- func DecodeJSON(raw []byte) (any, error)
- func DecodeJSONContainers(raw []byte, object func([]Property) any, array func([]any) any) (any, error)
- func DecodeOptional(raw []byte) (any, error)
- func DecodeValue(raw []byte) (any, error)
- func IsNull(value any) bool
- func IsNullish(value any) bool
- func IsUndefined(value any) bool
- func MarshalOptional(value any, key ...string) ([]byte, error)
- func MarshalValue(value any) ([]byte, error)
- func PropertyReadError(present bool, expression string) error
- func QuoteString(value string) []byte
- func StringCodePoints(value string) []rune
- func StringifyJSON(raw []byte) ([]byte, error)
- func StringifyProperty(value any, key string) ([]byte, error)
- func StringifyValue(value any) ([]byte, error)
- func SupportedValue(value any) bool
- func ValidateJSON(raw []byte) error
- type Array
- func (a *Array) Append(values ...any) int
- func (a *Array) Delete(index int)
- func (a *Array) DeleteProperty(name string)
- func (a *Array) Get(index int) any
- func (a *Array) GetProperty(name string) (any, bool)
- func (a *Array) Has(index int) bool
- func (a *Array) Keys() []int
- func (a *Array) Len() int
- func (a *Array) MarshalJSON() ([]byte, error)
- func (a *Array) Pop() any
- func (a *Array) PropertyKeys() []string
- func (a *Array) Set(index int, value any)
- func (a *Array) SetLength(length int)
- func (a *Array) SetProperty(name string, value any)
- func (a *Array) Values() []any
- type JSONMethod
- type Object
- type ObjectFields
- type ObjectValue
- func (a ObjectValue) Delete(name string)
- func (a ObjectValue) Entries() []Property
- func (a ObjectValue) Get(name string) any
- func (a ObjectValue) IsZero() bool
- func (a ObjectValue) Len() int
- func (a ObjectValue) Lookup(name string) (any, bool)
- func (o ObjectValue) MarshalJSON() ([]byte, error)
- func (a *ObjectValue) Set(name string, value any)
- func (object *ObjectValue) UnmarshalJSON(raw []byte) error
- type Property
- type RawObject
- type RawProperty
- type ValueCloner
Constants ¶
const Null nullValue = 0
Null represents explicit null at optional Go fields whose nil zero value means absent. Nested JSON null values continue to use ordinary nil.
const Undefined undefinedValue = 0
Variables ¶
This section is empty.
Functions ¶
func ArrayIndex ¶
ArrayIndex recognizes the own-property index keys sorted first by JS.
func DecodeJSON ¶
DecodeJSON reads JSON into nil, bool, float64, string, []any and map[string]any. Numbers use JavaScript's binary64 domain, including overflow. Strings retain lone UTF-16 surrogates as their three-byte WTF-8 encoding; valid pairs use ordinary UTF-8. QuoteString must be used to export those strings losslessly. Maps retain key identity and last duplicate values, but not insertion order.
func DecodeJSONContainers ¶
func DecodeJSONContainers(raw []byte, object func([]Property) any, array func([]any) any) (any, error)
DecodeJSONContainers supplies explicit object/array constructors. Nil constructors retain the ordinary Go map/slice representation. Children are constructed before their parent, after the entire input has been validated.
func DecodeOptional ¶
DecodeOptional retains absence versus null at optional JSON-value fields.
func DecodeValue ¶
DecodeValue constructs live ordered objects and reference arrays from JSON.
func IsUndefined ¶
func MarshalOptional ¶
MarshalOptional exports an optional object property. nil/Undefined/functions are omitted; Null exports an explicit JSON null.
func MarshalValue ¶
MarshalValue adapts export to Go's json.Marshaler, which requires a JSON value: an undefined root becomes null. StringifyValue preserves root omission instead.
func PropertyReadError ¶
PropertyReadError retains the pinned runtime's diagnostic for reading a property on null (present) or undefined (absent).
func QuoteString ¶
QuoteString exports UTF-8 and decoded WTF-8 strings using JSON.stringify's escaping. Surrogate code units remain escaped; other invalid UTF-8 uses the replacement character, matching the shared serialized-JSON parser.
func StringCodePoints ¶
StringCodePoints follows JavaScript string iteration. A lone surrogate is one code point, represented by WTF-8 in Go; valid pairs are ordinary UTF-8.
func StringifyJSON ¶
StringifyJSON normalizes serialized JSON using the value semantics of Pi's JSON.parse/JSON.stringify boundary. It preserves insertion order, applies JS index-key and duplicate-key rules, converts numbers to binary64, and retains lone UTF-16 surrogates. Invalid JSON returns the Go decoder's error.
func StringifyProperty ¶
StringifyProperty exports a value at a known property boundary. It lets typed Go host serializers retain the toJSON key and omit undefined hook results.
func StringifyValue ¶
StringifyValue follows JSON.stringify for the supported value graph. An undefined/function root, including a hook result, returns no bytes and no error.
func SupportedValue ¶
func ValidateJSON ¶
ValidateJSON checks strict JSON syntax using the pinned Bun/JavaScriptCore diagnostics. It does not repair input, coerce values, or construct a graph. The explicit parser stack also avoids recursive descent on nested input.
Types ¶
type Array ¶
type Array struct {
// contains filtered or unexported fields
}
Array retains JavaScript-style identity and length across shared references. Absent indices (holes) differ from present Undefined values in Has/Keys, but both read as Undefined and export as null. Enumerable own data properties outside array indices retain insertion order and do not affect length or JSON. An explicit JSONMethod stored as toJSON can replace the array during export. Custom prototypes and accessors are not represented. Callers must synchronize concurrent reads and writes.
func (*Array) DeleteProperty ¶
func (*Array) GetProperty ¶
GetProperty reads an indexed or named own data property. Inherited properties and the reserved length property are excluded; use Len for length.
func (*Array) MarshalJSON ¶
func (*Array) PropertyKeys ¶
PropertyKeys follows Object.keys order: numeric indices, then named own data properties in insertion order. The non-enumerable length property is excluded.
func (*Array) SetProperty ¶
SetProperty defines an enumerable own data property. It bypasses prototype setters (including __proto__) and accessors. Use SetLength to change length.
type JSONMethod ¶
JSONMethod is an explicit own toJSON hook. Export passes the current object or array as receiver and its containing property key (empty at the root). Recording/cloning never invoke it. Returned errors and panics propagate. Other Go function types and arbitrary serialization methods remain passive.
type Object ¶
type Object struct {
// contains filtered or unexported fields
}
Object retains own-property insertion order and shared nested identity. Set overwrites in place; Delete followed by Set appends a new property. Entries enumerates numeric index keys first, as Object.entries does in Pi. Callers must synchronize concurrent access. Recording and JSON export never invoke arbitrary user serializers.
func (*Object) MarshalJSON ¶
type ObjectFields ¶
type ObjectFields struct {
// contains filtered or unexported fields
}
ObjectFields builds an object from canonical JSON keys, retaining UTF-16 identity without converting lone surrogates into replacement characters.
func (*ObjectFields) Marshal ¶
func (o *ObjectFields) Marshal() []byte
Marshal orders index keys numerically and retains other insertion positions.
func (*ObjectFields) Set ¶
func (o *ObjectFields) Set(name, value []byte)
Set replaces duplicate values without changing the first insertion position. The name must be a canonical JSON string produced by StringifyJSON.
type ObjectValue ¶
type ObjectValue struct {
// contains filtered or unexported fields
}
ObjectValue is a rebindable reference to an ordered object. Value copies share the object; decoding replaces this reference without changing aliases.
func NewObjectValue ¶
func NewObjectValue(properties ...Property) ObjectValue
NewObjectValue preserves the order of the supplied properties. Its copies share the input object.
func (ObjectValue) Delete ¶
func (a ObjectValue) Delete(name string)
func (ObjectValue) Entries ¶
func (a ObjectValue) Entries() []Property
func (ObjectValue) Get ¶
func (a ObjectValue) Get(name string) any
func (ObjectValue) IsZero ¶
func (a ObjectValue) IsZero() bool
func (ObjectValue) Len ¶
func (a ObjectValue) Len() int
func (ObjectValue) MarshalJSON ¶
func (o ObjectValue) MarshalJSON() ([]byte, error)
func (*ObjectValue) Set ¶
func (a *ObjectValue) Set(name string, value any)
func (*ObjectValue) UnmarshalJSON ¶
func (object *ObjectValue) UnmarshalJSON(raw []byte) error
UnmarshalJSON reads an object using JSON.parse's number domain. Valid numeric overflow becomes infinity, underflow keeps its sign, and all numbers round to binary64. Export remains the responsibility of MarshalJSON; converting overflow to null here would lose the recorded in-memory value. Lone UTF-16 surrogates use WTF-8 within Go strings, including map keys; ObjectValue.MarshalJSON restores their original JSON escapes. Objects and arrays use *Object and *Array, retaining key order and shared nested identity, including array length edits through retained references. Each successful decode replaces the object, including on a reused receiver. A rejected payload leaves the receiver and any aliases untouched.
type Property ¶
Property is one JSON object entry. DecodeJSONContainers supplies entries in source order, including duplicates; the builder owns duplicate-key handling.
type RawObject ¶
type RawObject map[string]json.RawMessage
RawObject is a JSON object whose keys retain UTF-16 identity and whose values stay serialized. It is for typed envelopes that must preserve opaque fields, without decoding their numbers or interpreting nested values. Like Go maps, it has no insertion order; export sorts keys for deterministic output.
func (RawObject) MarshalJSON ¶
func (*RawObject) UnmarshalJSON ¶
Successful decoding replaces the object and owns its raw value bytes. Invalid input leaves the receiver untouched. Repeated keys keep their final value; distinct lone surrogate keys do not collapse into the replacement character.
type RawProperty ¶
type RawProperty struct {
Name string
Value json.RawMessage
}
RawProperty retains a decoded UTF-16 key and its original serialized value.
func DecodeObjectProperties ¶
func DecodeObjectProperties(raw []byte) ([]RawProperty, error)
DecodeObjectProperties reads own properties in source order, including duplicates. Values borrow raw; callers retaining them must not mutate raw. Non-object JSON returns no properties. Invalid JSON returns a decoder error.
type ValueCloner ¶
type ValueCloner struct {
// contains filtered or unexported fields
}
ValueCloner detaches mutable JSON-shaped containers without serialization. One cloner preserves repeated references and cycles across multiple roots. Callers synchronize access to the source graph and to the cloner.
func (*ValueCloner) Clone ¶
func (c *ValueCloner) Clone(value any) any
Source Files