csid

README

csid

An ID generator losely derived from the snowflake format used by twitter and discord though with some differences. a CSID consists of a 42 bit timestamp measured in centseconds (equal to 10ms, rather than miliseconds to allow for lower volume more long term use) a 10 bit process identifier, and a 12 bit increment. and CSIDs are canonically displayed in Base16 rather than Base10.

Traits

• Lasts over 1000 years before the timestamp runs out
• Dependency free
• At scale some setup may be required for the machine ID (but at small scales it can be randomly set)
• Code generator for statically typed IDs
• Lockless and Concurrency Safe

Documentation

Index

• Constants
• Variables
• func IDTime(i ID) time.Time
• type Generator
  • func New(worker uint64, epoch time.Time) *Generator
  • func (g *Generator) Get() ID
  • func (g *Generator) IDTime(i RelativeTime) time.Time
• type ID
  • func Get() ID
  • func Parse(id string) (ID, error)
  • func (i ID) IsZero() bool
  • func (i ID) MarshalBinary() ([]byte, error)
  • func (i ID) MarshalJSON() ([]byte, error)
  • func (i ID) MarshalText() ([]byte, error)
  • func (i ID) RelativeTime() time.Duration
  • func (i ID) String() string
  • func (i ID) Time(epoch time.Time) time.Time
  • func (i *ID) UnmarshalBinary(b []byte) error
  • func (i *ID) UnmarshalJSON(b []byte) error
  • func (i *ID) UnmarshalText(b []byte) error
• type RelativeTime

Constants

const CentiSecond = time.Millisecond * 10

const MaxWorker = 0b11111_11111

Variables

var Default = Generator{
	Epoch: Epoch,

	Worker: rand.New(rand.NewSource(time.Now().UnixNano())).Uint64() & MaxWorker,
	// contains filtered or unexported fields
}

Default is a default Generator, useful for low volume projects for higher volumes its recommended to create one yourself however

var Epoch = time.Unix(1645568542, 0)

Epoch is the Epoch for the default generator set to 2022-02-22 22:22:22 UTC aka "twosday"

var Epoch2000 = time.Unix(978220800, 0)

Epoch2000 is an alternate default epoch set to 2000-01-01 00:00:00 UTC for a more typical/practical date requires setting up your own Generator object to use it though

Functions

func IDTime

func IDTime(i ID) time.Time

IDTime returns the time of an ID relative to the default Epoch

Types

type Generator

type Generator struct {
	Epoch time.Time

	Worker uint64
	// contains filtered or unexported fields
}

Generator contains some settings for id generation

func New

func New(worker uint64, epoch time.Time) *Generator

func (*Generator) Get

func (g *Generator) Get() ID

Get returns a new ID

func (*Generator) IDTime

func (g *Generator) IDTime(i RelativeTime) time.Time

IDTime gets the time of an ID relative to this generators epoch

type ID

type ID uint64

ID is a CSID, which is akin to a snowflake as seen in twitter or discord but slightly different. instead of miliseconds the timestamp is stored in centiseconds (10ms) giving the ID format a much longer lifespan (over 1000 years) and to differentiate itself visually is canonically formatted in hexadecimal instead of decimal

func Get

func Get() ID

Get a new ID from the default generator

func Parse

func Parse(id string) (ID, error)

Parse parses a CSID from a String

func (ID) IsZero

func (i ID) IsZero() bool

IsZero returns true if an ID is blank (0)

func (ID) MarshalBinary

func (i ID) MarshalBinary() ([]byte, error)

func (ID) MarshalJSON

func (i ID) MarshalJSON() ([]byte, error)

func (ID) MarshalText

func (i ID) MarshalText() ([]byte, error)

func (ID) RelativeTime

func (i ID) RelativeTime() time.Duration

RelativeTime returns a time.RelativeTime of the time in an ID, note with timestamps over 270 years from the epoch it will overflow and not return correctly

func (ID) String

func (i ID) String() string

func (ID) Time

func (i ID) Time(epoch time.Time) time.Time

Time returns the time of the ID relative to an epoch

func (*ID) UnmarshalBinary

func (i *ID) UnmarshalBinary(b []byte) error

func (*ID) UnmarshalJSON

func (i *ID) UnmarshalJSON(b []byte) error

func (*ID) UnmarshalText

func (i *ID) UnmarshalText(b []byte) error

type RelativeTime

type RelativeTime interface {
	Time(epoch time.Time) time.Time
}