xjson

Documentation

Overview

Copyright 2023 Meta Platforms, Inc. and affiliates.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Index

• func MarshalWithTypeIDs(obj any, typeIDOfer TypeIDOfer) ([]byte, error)
• func UnmarshalWithTypeIDs(b []byte, dst any, newByTypeIDer NewByTypeIDer) error
• type NewByTypeIDer
• type TypeID
• type TypeIDHandler
• type TypeIDOfer

Functions

func MarshalWithTypeIDs

func MarshalWithTypeIDs(obj any, typeIDOfer TypeIDOfer) ([]byte, error)

MarshalWithTypeIDs is similar to json.Marshal, but any interface field met in a structure is serialized as a structure containing the type identifier and the value. It allows to unmarshal the result without loosing typing.

If an interface is met, then instead of marshaling its content directly, we resolve its type ID through TypeIDOfer and putting:

{ResolvedTypeID: {...Content...}}

instead (where ResolvedTypeID is a string containing the TypeID).

For example:

type Struct {
    Field any
}
xjson.MarshalWithTypeIDs(Struct{Field: Struct{Field: int(1)}}, typeIDOfer)

might be marshalled to

{"Field": {"Struct": {"Field": {"int": 1}}}}

NOTE! This is not a drop-in replacement for standard json.Marshal.

It has incompatible behavior.

func UnmarshalWithTypeIDs

func UnmarshalWithTypeIDs(b []byte, dst any, newByTypeIDer NewByTypeIDer) error

UnmarshalWithTypeIDs is similar to json.Unmarshal, but any interface field met in a structure is unserialized as a structure containing the type identifier and the value. It allows to unmarshal a JSON (serialized by MarshalWithTypeIDs) without loosing typing.

This function is the inverse function for MarshalWithTypeIDs.

NOTE! This is not a drop-in replacement for standard json.Unmarshal.

It has incompatible behavior.

Types

type NewByTypeIDer

type NewByTypeIDer interface {
	// NewByTypeID returns a pointer to an object of the type specified through TypeID.
	NewByTypeID(TypeID) (any, error)
}

NewByTypeIDer is a factory of a value given its TypeID.

type TypeID

type TypeID string

TypeID is an unique identifier of a type

type TypeIDHandler

type TypeIDHandler interface {
	TypeIDOfer
	NewByTypeIDer
}

TypeIDHandler is a bidirectional handler which couples TypeID with a type.

type TypeIDOfer

type TypeIDOfer interface {
	// TypeIDOf returns TypeID of the type of the given sample.
	TypeIDOf(sample any) (TypeID, error)
}

TypeIDOfer is a converter of a sample to its TypeID.