iid

package module
Version: v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 26, 2019 License: MIT Imports: 5 Imported by: 0

README

iid

Small, globally unique IDs implemented in Go.

GoDoc

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

Examples

Constants

View Source
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

View Source
var Enc = base64.NewEncoding(encoder)

The encoding used for string serialization and deserialization of iids.

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

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

View Source
var RandReader = rand.Reader

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

View Source
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 added in v1.0.2

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 added in v1.0.2

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL