dpuid

README

Delta-Pack UUID (DPUID)

Delta-Pack UUID packs a same-sign integer sequence into one UUID-sized value using the format described in SPEC.md. It is optimized for sequences where neighboring absolute values have small deltas.

Russian README: README.ru.md.

Features

• RFC 9562 UUIDv8 mode by default, using github.com/google/uuid.UUID.
• Raw 128-bit mode for closed systems that do not need RFC UUID markers.
• Generic input and output for int, int8..int64, uint, and uint8..uint64.
• Three SPEC variants: general deltas, sequential unit-step values, and identical values.
• No runtime dependencies except github.com/google/uuid.
• Go 1.20 module target.

Install

go get github.com/Vitalick/dpuid

Usage

package main

import (
	"fmt"
	"log"

	"github.com/Vitalick/dpuid"
)

func main() {
	id, err := dpuid.Pack([]int64{1_000_040, 1_000_010, 1_000_030, 1_000_000})
	if err != nil {
		log.Fatal(err)
	}

	values, err := dpuid.Unpack(id)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(id.String())
	fmt.Println(values) // [1000000 1000010 1000030 1000040]
}

Pack and Unpack use UUIDv8 mode. Use PackMode and UnpackMode for raw mode:

id, err := dpuid.PackMode(values, dpuid.ModeRaw)
values, err = dpuid.UnpackMode(id, dpuid.ModeRaw)

Use the generic API for other integer types, including unsigned values:

id, err := dpuid.PackValues([]uint64{1<<63 + 6, 1<<63 + 2, 1<<63 + 4})
if err != nil {
	log.Fatal(err)
}

values, err := dpuid.UnpackValues[uint64](id)
if err != nil {
	log.Fatal(err)
}

fmt.Println(values) // [9223372036854775810 9223372036854775812 9223372036854775814]

Important Behavior

Input values must be sign-homogeneous: all values are non-negative or all values are non-positive. Zero can be encoded with either group. Mixed positive and negative values are rejected.

Unsigned values are always treated as non-negative. When unpacking into a typed slice, every decoded value must fit into the requested type or ErrValueOverflow is returned.

The input order is not preserved. Decoded values are sorted by absolute value, as required by the SPEC.

Raw mode uses all 128 bits for DPUID data and does not produce an RFC-compliant UUID. UUIDv8 mode is the recommended default for UUID-aware systems.

Validation

The package exposes sentinel errors such as ErrEmptyInput, ErrMixedSigns, ErrDeltaOverflow, ErrCountOverflow, ErrTotalOverflow, ErrInvalidMode, ErrInvalidUUIDv8, and ErrPayloadOverflow. Returned errors can be checked with errors.Is.

Benchmarks

Snapshot from go test -bench=. ./... on linux/amd64, AMD Ryzen 9 3900X:

BenchmarkPackVariant1-24                   1703496     709.6 ns/op
BenchmarkUnpackVariant1-24                 1517302     807.5 ns/op
BenchmarkPackSequentialVariant2-24         1759216     730.2 ns/op
BenchmarkUnpackSequentialVariant2-24        917816      1140 ns/op
BenchmarkPackIdenticalVariant3-24          1751436     673.4 ns/op
BenchmarkUnpackIdenticalVariant3-24         963639      1144 ns/op

Development

go test ./...
go test -bench=. ./...
gofmt -w .

Documentation

Overview

Package dpuid packs same-sign integer sequences into UUID-compatible Delta-Pack UUID values and unpacks them back to absolute-value sorted slices.

Index

• Variables
• func Pack(values []int64) (uuid.UUID, error)
• func PackMode(values []int64, mode Mode) (uuid.UUID, error)
• func PackValues[T Integer](values []T) (uuid.UUID, error)
• func PackValuesMode[T Integer](values []T, mode Mode) (uuid.UUID, error)
• func Unpack(id uuid.UUID) ([]int64, error)
• func UnpackMode(id uuid.UUID, mode Mode) ([]int64, error)
• func UnpackValues[T Integer](id uuid.UUID) ([]T, error)
• func UnpackValuesMode[T Integer](id uuid.UUID, mode Mode) ([]T, error)
• type Integer
• type Mode

Variables

var (
	ErrEmptyInput      = errors.New("dpuid: empty input")
	ErrMixedSigns      = errors.New("dpuid: mixed signs")
	ErrDeltaOverflow   = errors.New("dpuid: max delta too large")
	ErrCountOverflow   = errors.New("dpuid: too many numbers")
	ErrTotalOverflow   = errors.New("dpuid: encoded payload exceeds output size")
	ErrInvalidMode     = errors.New("dpuid: invalid mode")
	ErrInvalidUUIDv8   = errors.New("dpuid: invalid UUIDv8 markers")
	ErrPayloadOverflow = errors.New("dpuid: payload exceeds input size")
	ErrValueOverflow   = errors.New("dpuid: value overflows target integer type")
)

Functions

func Pack

func Pack(values []int64) (uuid.UUID, error)

Pack encodes values in UUIDv8 mode.

func PackMode

func PackMode(values []int64, mode Mode) (uuid.UUID, error)

PackMode encodes values according to SPEC.md.

The input order is not preserved. Decoding returns values sorted ascending by absolute value. Values must be sign-homogeneous: all non-negative or all non-positive.

func PackValues

func PackValues[T Integer](values []T) (uuid.UUID, error)

PackValues encodes signed or unsigned integer values in UUIDv8 mode.

func PackValuesMode

func PackValuesMode[T Integer](values []T, mode Mode) (uuid.UUID, error)

PackValuesMode encodes signed or unsigned integer values according to SPEC.md.

func Unpack

func Unpack(id uuid.UUID) ([]int64, error)

Unpack decodes a UUIDv8 DPUID value.

func UnpackMode

func UnpackMode(id uuid.UUID, mode Mode) ([]int64, error)

UnpackMode decodes a DPUID value encoded in the selected mode.

func UnpackValues

func UnpackValues[T Integer](id uuid.UUID) ([]T, error)

UnpackValues decodes a UUIDv8 DPUID value into the requested integer type.

func UnpackValuesMode

func UnpackValuesMode[T Integer](id uuid.UUID, mode Mode) ([]T, error)

UnpackValuesMode decodes a DPUID value encoded in the selected mode into the requested integer type.

Types

type Integer

type Integer interface {
	~int | ~int8 | ~int16 | ~int32 | ~int64 |
		~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64
}

Integer is any built-in signed or unsigned integer type up to 64 bits.

type Mode

type Mode int

Mode selects how DPUID data is embedded into the returned UUID value.

const (
	// ModeUUIDv8 stores 122 DPUID bits around RFC 9562 UUID version and variant
	// marker bits. This is the recommended default.
	ModeUUIDv8 Mode = iota

	// ModeRaw uses all 128 UUID bits for DPUID data and does not produce an
	// RFC-compliant UUID.
	ModeRaw
)