encode

Documentation

Overview

Package encode provides a collection of helper functions for safe serialization and deserialization across system boundaries such as databases, queues, caches, and RPC payloads.

It solves the common problem of reliably encoding Go values into transport-safe formats and decoding them back without losing structure or introducing unsafe byte streams.

The package supports two main modes:

- Gob + Base64 encoding for arbitrary Go values - JSON + Base64 encoding for interoperable text-based payloads

Top features:

- encode/decode helpers for strings, byte slices, buffers, and io.Reader/io.Writer flows - consistent Base64 wrapping to keep binary payloads safe for text-only channels - explicit error wrapping at encode/decode/serialize/deserialize boundaries - parallel API families for Gob (Encode/Decode) and JSON (Serialize/Deserialize) - support for arbitrary serializable Go values, with clear failures for unsupported types

Benefits:

• reduce boilerplate for common serialization flows
• avoid accidental misuse of raw binary in text-only transports
• simplify data exchange between services and storage layers

Caveats:

• Decoding reads a single encoded value; any trailing bytes are ignored.
• The reader- and buffer-based decoders do not bound their input. When decoding from an untrusted source, wrap the reader with io.LimitReader.
• Gob is not designed to decode adversarial input; prefer the JSON family (Serialize/Deserialize) for untrusted, interoperable payloads.
• The JSON encoding appends a trailing newline, which is included in the encoded output.

Index

• func Base64DecodeString(s string) ([]byte, error)
• func Base64Decoder(r io.Reader) io.Reader
• func Base64EncodeString(s string) string
• func Base64Encoder(w io.Writer) io.WriteCloser
• func BufferDecode(reader io.Reader, data any) error
• func BufferDeserialize(reader io.Reader, data any) error
• func BufferEncode(data any) (*bytes.Buffer, error)
• func BufferSerialize(data any) (*bytes.Buffer, error)
• func ByteDecode(msg []byte, data any) error
• func ByteDeserialize(msg []byte, data any) error
• func ByteEncode(data any) ([]byte, error)
• func ByteSerialize(data any) ([]byte, error)
• func Decode(msg string, data any) error
• func Deserialize(msg string, data any) error
• func Encode(data any) (string, error)
• func GobEncoder(enc io.WriteCloser, data any) error
• func JSONEncoder(enc io.WriteCloser, data any) error
• func JsonEncoder(enc io.WriteCloser, data any) error
• func Serialize(data any) (string, error)

Examples

• Decode
• Deserialize
• Encode
• Serialize

Functions

func Base64DecodeString

func Base64DecodeString(s string) ([]byte, error)

Base64DecodeString decodes the Base64 string s into its raw bytes.

It is the inverse of Base64EncodeString. The decoded bytes need not be valid UTF-8, so they are returned as a byte slice.

func Base64Decoder

func Base64Decoder(r io.Reader) io.Reader

Base64Decoder wraps r with a streaming Base64 decoder.

It is the read-side counterpart to Base64Encoder.

func Base64EncodeString

func Base64EncodeString(s string) string

Base64EncodeString returns the Base64 representation of s.

Use it when text-safe transport is required for arbitrary bytes.

func Base64Encoder

func Base64Encoder(w io.Writer) io.WriteCloser

Base64Encoder wraps w with a streaming Base64 encoder.

The caller should close the returned writer to flush buffered output.

func BufferDecode

func BufferDecode(reader io.Reader, data any) error

BufferDecode reads gob+Base64 content from reader into data.

data must be a pointer to the destination type. Only the first encoded value is read; any trailing bytes are ignored. When reading from an untrusted source, wrap reader with io.LimitReader to bound the input.

func BufferDeserialize

func BufferDeserialize(reader io.Reader, data any) error

BufferDeserialize reads JSON+Base64 content from reader into data.

data must be a pointer to the destination type. Only the first encoded value is read; any trailing bytes are ignored. When reading from an untrusted source, wrap reader with io.LimitReader to bound the input.

func BufferEncode

func BufferEncode(data any) (*bytes.Buffer, error)

BufferEncode encodes data as gob+Base64 and returns an in-memory buffer.

It is a single-buffer building block reused by Encode and ByteEncode.

func BufferSerialize

func BufferSerialize(data any) (*bytes.Buffer, error)

BufferSerialize encodes data as JSON+Base64 and returns an in-memory buffer.

It is a single-buffer building block reused by Serialize and ByteSerialize.

func ByteDecode

func ByteDecode(msg []byte, data any) error

ByteDecode decodes gob+Base64 bytes into data.

data must be a pointer to the destination type.

func ByteDeserialize

func ByteDeserialize(msg []byte, data any) error

ByteDeserialize decodes JSON+Base64 bytes into data.

data must be a pointer to the destination type.

func ByteEncode

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

ByteEncode encodes data as gob+Base64 bytes.

This format is convenient for binary channels while still staying text-safe.

func ByteSerialize

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

ByteSerialize encodes data as JSON+Base64 bytes.

func Decode

func Decode(msg string, data any) error

Decode decodes a gob+Base64 string into data.

data must be a pointer to the destination type. Only the first encoded value is read; any trailing bytes are ignored.

Example

package main

import (
	"fmt"
	"log"

	"github.com/tecnickcom/nurago/pkg/encode"
)

func main() {
	type TestData struct {
		Alpha string
		Beta  int
	}

	var data TestData

	msg := "Kf+BAwEBCFRlc3REYXRhAf+CAAECAQVBbHBoYQEMAAEEQmV0YQEEAAAAD/+CAQZhYmMxMjMB/gLtAA=="

	err := encode.Decode(msg, &data)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(data)

}

Output:
{abc123 -375}

func Deserialize

func Deserialize(msg string, data any) error

Deserialize decodes a JSON+Base64 string into data.

data must be a pointer to the destination type. Only the first encoded value is read; any trailing bytes are ignored.

Example

package main

import (
	"fmt"
	"log"

	"github.com/tecnickcom/nurago/pkg/encode"
)

func main() {
	type TestData struct {
		Alpha string
		Beta  int
	}

	var data TestData

	msg := "eyJBbHBoYSI6ImFiYzEyMyIsIkJldGEiOi0zNzV9Cg=="

	err := encode.Deserialize(msg, &data)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(data)

}

Output:
{abc123 -375}

func Encode

func Encode(data any) (string, error)

Encode encodes data as gob+Base64 string.

It is useful for storing typed payloads in text-only fields.

Example

The gob wire format embeds process-global type IDs, so the encoded output is not stable across runs; this example is intentionally not output-testable.

package main

import (
	"fmt"
	"log"

	"github.com/tecnickcom/nurago/pkg/encode"
)

func main() {
	type TestData struct {
		Alpha string
		Beta  int
	}

	data := &TestData{Alpha: "test_string", Beta: -9876}

	v, err := encode.Encode(data)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(v)
}

func GobEncoder

func GobEncoder(enc io.WriteCloser, data any) error

GobEncoder gob-encodes data into enc and closes enc.

It centralizes gob encoding and close handling for stream-based pipelines.

func JSONEncoder

func JSONEncoder(enc io.WriteCloser, data any) error

JSONEncoder JSON-encodes data into enc and closes enc.

It is useful for stream-friendly JSON pipelines with explicit close semantics.

func JsonEncoder

func JsonEncoder(enc io.WriteCloser, data any) error

JsonEncoder JSON-encodes data into enc and closes enc.

Deprecated: use JSONEncoder.

func Serialize

func Serialize(data any) (string, error)

Serialize encodes data as JSON+Base64 string.

Choose this over Encode when interoperability with non-Go systems matters.

Example

package main

import (
	"fmt"
	"log"

	"github.com/tecnickcom/nurago/pkg/encode"
)

func main() {
	type TestData struct {
		Alpha string
		Beta  int
	}

	data := &TestData{Alpha: "test_string", Beta: -9876}

	v, err := encode.Serialize(data)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(v)

}

Output:
eyJBbHBoYSI6InRlc3Rfc3RyaW5nIiwiQmV0YSI6LTk4NzZ9Cg==