vmihailenco/msgpack

Use msgpack.Marshal to encode a Go value into MessagePack bytes, and msgpack.Unmarshal to decode MessagePack bytes back into a Go value.

import "github.com/vmihailenco/msgpack/v5"

func ExampleMarshal() {
    type Item struct {
        Foo string
    }

    b, err := msgpack.Marshal(&Item{Foo: "bar"})
    if err != nil {
        panic(err)
    }

    var item Item
    err = msgpack.Unmarshal(b, &item)
    if err != nil {
        panic(err)
    }
    fmt.Println(item.Foo)
    // Output: bar
}

msgpack requires Go modules. First, initialize your Go module, then install the v5 package. Note that you must include v5 in the import path; omitting it is a common mistake.

go mod init github.com/my/repo
go get github.com/vmihailenco/msgpack/v5

The msgpappengine package automatically registers custom encoders and decoders for Google App Engine Datastore types with the msgpack library via its init() function. This allows msgpack.Encoder and msgpack.Decoder to handle these types transparently when they are part of a larger structure.

Supported types:

• *ds.Key (via encodeDatastoreKeyValue and decodeDatastoreKeyValue)
• ds.Cursor (via encodeDatastoreCursorValue and decodeDatastoreCursorValue)

You can control how struct fields are encoded using msgpack tags:

• Renaming: Use msgpack:"my_field_name" to change the field name.
• Aliasing: Use msgpack:"alias:another_name" to provide an alias.
• Omitting empty fields: Use msgpack:",omitempty" to omit individual empty fields, or configure the encoder to omit all empty fields in a struct.

msgpack provides several advanced configuration options for encoders and decoders:

• Custom Encoding/Decoding: Implement CustomEncoder or CustomDecoder interfaces for custom logic.
• Extensions: Use the RegisterExt mechanism to encode type information.
• Map Key Sorting: Use Encoder.SetSortMapKeys to ensure deterministic map encoding.
• Array Encoding: Use Encoder.UseArrayEncodedStructs to encode structs as arrays instead of maps.
• Custom Struct Tags: Use Encoder.SetCustomStructTag and Decoder.SetCustomStructTag to allow msgpack to act as a drop-in replacement for other tag systems (like json).
• Queries: Use Decoder.Query for efficient data extraction.

Use RegisterExt to associate a specific MessagePack extension ID (int8) with a type that implements both Marshaler and Unmarshaler interfaces. This allows the library to automatically handle encoding and decoding for that type using its own MarshalMsgpack and UnmarshalMsgpack methods.

Requirements:

• extID: A unique int8 identifier for the extension.
• value: An instance of the type that implements the MarshalerUnmarshaler interface.

Use EncodeMap to encode a map[string]interface{} into MessagePack format. If the map is nil, it encodes a MessagePack nil value. The method iterates through the map, encoding each key as a string and then encoding the corresponding value using the encoder's standard encoding logic.

func (e *Encoder) EncodeMap(m map[string]interface{}) error

Use EncodeInt(n int64) to encode a signed integer using the smallest possible number of bytes (1, 2, 3, 5, or 9 bytes).

Note: The specific type of the number is lost during encoding, as it will be optimized to the smallest representation.