tinypack

README

TinyPack

TinyPack is a self-made serialization protocol+library designed specially for keeping data as concise as possible. In contrast to protobuf/cbor/flatbuffers/capnp/etc:

• There's no field tags in resulting data (schema is static, though supports nullable fields).
• No reflection is used.
• Fixed-length arrays are supported.

In order to keep data as short as possible, two tricks are applied:

• Integers are encoded as varints - the smaller the value, the less memory it will take.
• Final message goes through capnp "packing" encoding - it compresses a byte-array efficiently and very quickly, utilizing the fact that statistically a lot of bytes are actually zeros.

Supported types

Type class	Golang type	Requirements	Binary representation
Boolean	bool		[0;1]-valued byte
Integer	int64		varint
Unsigned integer	uint64		varint
Float	float64		Straight binary representation
Pointer	tinypack.Pointer[T]	pointer.Ptr must never be nil	Binary representation of T
Nullable	tinypack.Nullable[T]	nullable.Ptr can be nil	[0;1]-valued byte, followed by binary representation of T
Fixed list	tinypack.List[tinypack.LengthDescriptor, T]	list.Content length must be same length that provided descriptor gives	Ordered concatenation of T items
Variadic list	tinypack.VarList[T]		Varint-encoded length, followed by ordered concatenation of T items
Fixed data	tinypack.Data[tinypack.LengthDescriptor]	data.Content length must be same length that provided descriptor gives	Content-bytes
Variadic data	tinypack.VarData		Varint-encoded length, followed by content-bytes
Composite	Any type that implements tinypack.Composite interface		Ordered concatenation of provided fields
Custom	Any type that implements tinypack.TinyPackable interface		User-implemented

Documentation

Index

• type Composite
• type Data
  • func CreateData[LD LengthDescriptor](content ...byte) (result Data[LD])
• type Decoder
  • func DefaultDecoder() *Decoder
  • func (d *Decoder) Read(r Reader, v ...any) error
  • func (d *Decoder) ReadBool(r Reader) (bool, error)
  • func (d *Decoder) ReadFloat(r Reader) (float64, error)
  • func (d *Decoder) ReadUvarint(r Reader) (uint64, error)
  • func (d *Decoder) ReadVarint(r Reader) (int64, error)
  • func (d *Decoder) Unmarshal(data []byte, v interface{}) error
• type Encoder
  • func DefaultEncoder() *Encoder
  • func (e *Encoder) Marshal(v interface{}) ([]byte, error)
  • func (e *Encoder) Write(w Writer, v ...any) error
  • func (e *Encoder) WriteBool(w Writer, v bool) error
  • func (e *Encoder) WriteFloat(w Writer, v float64) error
  • func (e *Encoder) WriteUvarint(w Writer, v uint64) error
  • func (e *Encoder) WriteVarint(w Writer, v int64) error
• type LengthDescriptor
• type List
  • func CreateList[LD LengthDescriptor, T any](content ...T) (result List[LD, T])
  • func (l *List[LD, T]) ReadTinyPack(r Reader, d *Decoder) error
  • func (l *List[LD, T]) WriteTinyPack(w Writer, e *Encoder) error
• type Nullable
  • func CreateNullable[T any](ptr *T) (result Nullable[T])
  • func (opt *Nullable[T]) ReadTinyPack(r Reader, d *Decoder) error
  • func (opt *Nullable[T]) WriteTinyPack(w Writer, e *Encoder) error
• type Pointer
  • func CreatePointer[T any](ptr *T) (result Pointer[T])
  • func (p *Pointer[T]) ReadTinyPack(r Reader, d *Decoder) error
  • func (p *Pointer[T]) WriteTinyPack(w Writer, e *Encoder) error
• type Reader
• type TinyPackable
• type VarData
  • func CreateVarData(content ...byte) (result VarData)
• type VarList
  • func CreateVarList[T any](content ...T) (result VarList[T])
• type VariadicLength
  • func (VariadicLength) GetTinyPackLength() int
• type Writer

Types

type Composite

type Composite interface {
	GetTinyPackChildrenPointers() ([]any, error)
}

type Data

type Data[LD LengthDescriptor] struct {
	List[LD, byte]
}

func CreateData

func CreateData[LD LengthDescriptor](content ...byte) (result Data[LD])

type Decoder

type Decoder struct {
	MaxVariadicLength int
}

func DefaultDecoder

func DefaultDecoder() *Decoder

func (*Decoder) Read

func (d *Decoder) Read(r Reader, v ...any) error

func (*Decoder) ReadBool

func (d *Decoder) ReadBool(r Reader) (bool, error)

func (*Decoder) ReadFloat

func (d *Decoder) ReadFloat(r Reader) (float64, error)

func (*Decoder) ReadUvarint

func (d *Decoder) ReadUvarint(r Reader) (uint64, error)

func (*Decoder) ReadVarint

func (d *Decoder) ReadVarint(r Reader) (int64, error)

func (*Decoder) Unmarshal

func (d *Decoder) Unmarshal(data []byte, v interface{}) error

type Encoder

type Encoder struct{}

func DefaultEncoder

func DefaultEncoder() *Encoder

func (*Encoder) Marshal

func (e *Encoder) Marshal(v interface{}) ([]byte, error)

func (*Encoder) Write

func (e *Encoder) Write(w Writer, v ...any) error

func (*Encoder) WriteBool

func (e *Encoder) WriteBool(w Writer, v bool) error

func (*Encoder) WriteFloat

func (e *Encoder) WriteFloat(w Writer, v float64) error

func (*Encoder) WriteUvarint

func (e *Encoder) WriteUvarint(w Writer, v uint64) error

func (*Encoder) WriteVarint

func (e *Encoder) WriteVarint(w Writer, v int64) error

type LengthDescriptor

type LengthDescriptor interface {
	GetTinyPackLength() int
}

type List

type List[LD LengthDescriptor, T any] struct {
	Content []T
}

func CreateList

func CreateList[LD LengthDescriptor, T any](content ...T) (result List[LD, T])

func (*List[LD, T]) ReadTinyPack

func (l *List[LD, T]) ReadTinyPack(r Reader, d *Decoder) error

func (*List[LD, T]) WriteTinyPack

func (l *List[LD, T]) WriteTinyPack(w Writer, e *Encoder) error

type Nullable

type Nullable[T any] struct {
	Ptr *T
}

func CreateNullable

func CreateNullable[T any](ptr *T) (result Nullable[T])

func (*Nullable[T]) ReadTinyPack

func (opt *Nullable[T]) ReadTinyPack(r Reader, d *Decoder) error

func (*Nullable[T]) WriteTinyPack

func (opt *Nullable[T]) WriteTinyPack(w Writer, e *Encoder) error

type Pointer

type Pointer[T any] struct {
	Ptr *T
}

func CreatePointer

func CreatePointer[T any](ptr *T) (result Pointer[T])

func (*Pointer[T]) ReadTinyPack

func (p *Pointer[T]) ReadTinyPack(r Reader, d *Decoder) error

func (*Pointer[T]) WriteTinyPack

func (p *Pointer[T]) WriteTinyPack(w Writer, e *Encoder) error

type Reader

type Reader interface {
	io.Reader
	io.ByteReader
}

type TinyPackable

type TinyPackable interface {
	WriteTinyPack(w Writer, e *Encoder) error
	ReadTinyPack(r Reader, d *Decoder) error
}

type VarData

type VarData struct {
	List[VariadicLength, byte]
}

func CreateVarData

func CreateVarData(content ...byte) (result VarData)

type VarList

type VarList[T any] struct {
	List[VariadicLength, T]
}

func CreateVarList

func CreateVarList[T any](content ...T) (result VarList[T])

type VariadicLength

type VariadicLength struct{}

func (VariadicLength) GetTinyPackLength

func (VariadicLength) GetTinyPackLength() int

type Writer

type Writer interface {
	io.Writer
	io.ByteWriter
}