iid

README

iid

Small, globally unique IDs implemented in Go.

Features

• Can be sorted by creation time
• Globally unique
• Small size (can be stored in a 64 bit integer or an 11 byte string)
• base64url encoded string format: the ids can be used in URLs

ID Format

1 Bit	32 Bit	31 Bit
Not used	Timestamp in seconds	Cryptographically secure random bytes

The first bit is not used so the ID fits into 64 bit signed integers.

Usage Example

package main

import (
	"github.com/robojones/iid"
	"log"
	"reflect"
)

func main() {
	// Generate new iid
	id := iid.New()
	log.Printf("buffer format: %#v", id)
	
	// Export as base64url string
	str := id.String()
	log.Printf("base64 string: %s", str)
	
	// Import the id from the string
	parsed, err := iid.FromString(str)
	if err != nil {
		panic(err)
	}
	log.Printf("parsed iid from string is identical to the original: %t", reflect.DeepEqual(id, parsed))
	
	// Export as uint64
	i := id.Uint64()
	log.Printf("integer: %d", i)
	
	// Import the id from the integer
	parsed = iid.FromUint64(i)
	log.Printf("parsed iid from uint64 is identical to original: %t", reflect.DeepEqual(id, parsed))
}

Documentation

Overview

Package iid generates small, globally unique IDs.

Index

• Constants
• Variables
• func IsErrInvalid(err error) bool
• type Iid
  • func FromInt(i int64) Iid
  • func FromString(s string) (Iid, error)
  • func FromUint64(i uint64) Iid
  • func New() Iid
  • func (i Iid) Int() int64
  • func (i Iid) String() string
  • func (i Iid) Uint64() uint64

Examples

• FromInt
• FromString
• FromUint64
• New

Constants

const (
	// IidLen is the length of the byte slice used for the Iid type.
	IidLen = 8
	// StrLen is the length of iid string representations in bytes.
	StrLen = 11
)

Variables

var Enc = base64.NewEncoding(encoder)

The encoding used for string serialization and deserialization of iids.

var ErrInvalid = errors.New("invalid id")

ErrInvalid is returned when trying to import an invalid Iid from a string.

var RandReader = rand.Reader

RandReader is used to fill the 31 least significant bits of new iids with random values.

var Timestamp = func() uint32 {
	return uint32(time.Now().Unix())
}

Timestamp is used to get the current UNIX time in seconds when generating new iids.

Functions

func IsErrInvalid

func IsErrInvalid(err error) bool

IsErrInvalid returns true if the cause of the provided error is ErrInvalid.

Types

type Iid

type Iid []byte

Iid represents time sortable ID which can be exported as a base64url encoded string, int64 or uint64.

func FromInt

func FromInt(i int64) Iid

FromInt imports an existing Iid from its int64 representation.

Example

var i int64 = 6711382541547442289
id := FromInt(i)

fmt.Println(id.Int())

Output:

6711382541547442289

func FromString

func FromString(s string) (Iid, error)

FromString imports an existing Iid from its base64url encoded string representation.

Example

str := "MHDSedbNhXB"
s, err := FromString(str)
if err != nil {
	log.Fatal(err)
}
fmt.Println(s.String())

Output:

MHDSedbNhXB

func FromUint64

func FromUint64(i uint64) Iid

FromUint64 imports an existing Iid from its uint64 representation.

Example

var i uint64 = 6711382541547442289
id := FromUint64(i)

fmt.Println(id.Uint64())

Output:

6711382541547442289

func New

func New() Iid

New generates a completely new Iid containing: 1 bit empty, 32 bit current timestamp, 31 bit cryptographically secure random bits.

Example

id := New()
fmt.Println(id)

Output:

Ad7YmV-----

func (Iid) Int

func (i Iid) Int() int64

Int returns a int64 representing the Iid.

func (Iid) String

func (i Iid) String() string

String returns an 11 byte long, base64url encoded string representing the Iid.

func (Iid) Uint64

func (i Iid) Uint64() uint64

Uint64 returns a uint64 representing the Iid.