tsid

package module
v1.0.4 Latest Latest
Warning

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

 Go to latest Published: Feb 22, 2023 License: MIT Imports: 11 Imported by: 0

README ΒΆ

TSID

GitHub GitHub go.mod Go version Go Reference Go Go Report Card codecov GitHub release (latest SemVer including pre-releases) GitHub last commit GitHub repo size GitHub repo file count GitHub Repo stars

English | δΈ­ζ–‡

A unique ID generator based on a timestamp or time series, inspired by Twitter's Snowflake.

The goal is to provide a unique identification (or UUID) solution that is reliable and flexible (configurable, extensible), but the performance is lower than the classical (fixed width and position) snowflake algorithm. Also provides the implementation of the classic snowflake algorithm(func Simple(server int64) func()int64). See Example 2

NOTES! ❗️Timestamp segment and sequence segment is REQUIRED!

HOWTO πŸ› οΈ

go get github.com/StarryLab/tsid.go

FEATURES ✨

  1. The maximum 126 bits
  2. Customize the width of each bit-segment
  3. Customize the order of bit-segments
  4. Support customize encoder
  5. BASE36 is default, using the go package strconv.FormatInt
  6. An improved BASE64 encoder to encode/decode identifiers
  7. Customize the options or use the provided default settings
  8. Supports random or auto-increment identifiers. Notes: auto-increment identifiers are still random and not strictly increment
  9. Provides a classic snowflake algorithm (fixed width and position), with better performance
  10. Data source types
    • Timestamps of various precision: nanosecond, millisecond, microsecond, and second
    • Various date and time values: year, month, day, week, hour, minute, second, millisecond, and the number of days and weeks in a year
    • 1 to 63 bits secure random number
    • Option value
    • Environment variables
    • Fixed value
    • Simple sequence/serial number, like a counter
    • Data sources
    • Parameter by caller

USAGE πŸš€

Example 1
package main

import (
  "flag"
  "fmt"

  . "github.com/StarryLab/tsid.go"
)

var (
  host,
  node int64
)

func init() {
  // $> ./tsid -host=8 -node=6
  host = *flag.Int64("host", 0, "data center(host) id")
  node = *flag.Int64("node", 0, "server node id")
}

func main() {
  b, e := Snowflake(host, node)
  if e != nil {
    fmt.Println("Error: ", e)
    return
  }
  fmt.Println("TSID: ", b.NextString()) // strconv.FormatInt
}
Example 2
package main

import (
  "flag"
  "fmt"

  . "github.com/StarryLab/tsid.go"
)

var (
  server int64
)

func init() {
  // $> ./tsid -server=8
  server = *flag.Int64("server", 0, "server id")
}

func main() {
  c, e := Simple(server)
  if e != nil {
    fmt.Println("Error: ", e)
    return
  }
  for i := 0; i < 100; i++ {
    fmt.Printf("%3d. %d", i+1, c())
  }
}
Example 3
  1. examples/demo.go
package examples

import (
  "errors"
  
  . "github.com/StarryLab/tsid.go"
)

func init() {
  Register("my_data_source", DemoDataSource{{
    "demo": 1,
    "other": 9,
  }})
}

type DemoDataSource struct{
  data map[string]int64
}

func(d *DemoDataSource)Read(query ...interface{}) (int64, error) {
  if len(query)>0 {
    if s, o := query[0].(string); o {
      if v, o := d.data[s]; o {
        return v, nil
      }
    }
  }
  return 0, errors.New("data not found")
}
  1. main.go
package main

import (
  "fmt"

  _ "examples"
  . "github.com/StarryLab/tsid.go"
)

func main() {
  // Environment variable: SERVER_HOST, SERVER_NODE
  opt := *O(
    Sequence(12),                         // 12 bits, REQUIRED!
    Env(6, "SERVER_HOST", 0),             // 6 bits [0, 31], data center id
    Env(4, "SERVER_NODE", 0),             // 4 bits [0, 15], server node id
    Data(10, "my_data_source", 2, "demo"),// 10 bits [0, 1023], data source
    Random(30),                           // 30 bits
    Timestamp(41, TimestampMilliseconds), // 41 bits, REQUIRED!
  )
  b, e := Make(opt)
  if e != nil {
    fmt.Println("Error: ", e)
    return
  }
  fmt.Println("TSID: ", b.NextString()) // strconv.FormatInt
}

Documentation ΒΆ

Index ΒΆ

Constants ΒΆ

View Source 
const (
	DecodeErrorEmpty decodeErrorType = iota
	DecodeErrorInvalidDigit
	DecodeErrorOverflow
	DecodeErrorOutOfRange
)
View Source 
const (
	// SegmentsLimit is the maximum number of segments
	SegmentsLimit = 63
	// EpochReservedDays indicates the minimum days approaching the end
	EpochReservedDays = 7
	// EpochMS is the default start timestamp,
	// measured in milliseconds starting
	// at midnight on December 12, 2022
	EpochMS = 1_670_774_400_000
)
View Source 
const (
	// HostWidth is the default width of the bit-segment,
	// value range [0, 63]
	HostWidth = 6
	// NodeWidth is the default width of the bit-segment,
	// value range [0, 15]
	NodeWidth = 4
	// TimestampWidth is the default width of the bit-segment.
	// It measures time by the number of seconds that have
	// elapsed since EpochMS, value range [0, 68 years after]
	TimestampWidth = 41
	// SequenceWidth is the default width of the bit-segment,
	// value range [0, 4095]
	SequenceWidth = 12
)
View Source 
const (
	// EnvServerHost is data center id, type: byte, value range [0, 31], 6 bits
	EnvServerHost = "SERVER_HOST_ID"
	// EnvServerNode is server node id, type: byte, value range [0, 15], 4 bits
	EnvServerNode = "SERVER_NODE_ID"
	// EnvDomainId is geo region id, type: int32, value range [0, 65535], 16 bits
	EnvDomainId = "SERVER_DOMAIN_ID"
	// EnvTimeEpoch is server epoch timestamp, type: int64, [0, 9_223_372_036_854_775_807]
	EnvTimeEpoch = "SERVER_EPOCH_TIMESTAMP"
)

Variables ΒΆ

This section is empty.

Functions ΒΆ

func Define ΒΆ 

func Define(scene string, options Options) bool

Define adds the predefined options

func Play ΒΆ 

func Play(count int)

func Rand ΒΆ 

func Rand(w byte) int64

Rand generates a secure random number with a width specified by w, which is the expected bit width, value range is [1, 63].

func Register ΒΆ 

func Register(name string, d DataProvider)

Register to register a data provider

func Simple ΒΆ 

func Simple(server int64) (func() int64, error)

Simple implements a classic snowflake algorithm(fixed width and position). The value range of server is [0, 1023]. 

if b, e := Simple(16); e == nil {
  fmt.Println("ID:")
  for i := 0; i < 100; i++ {
    fmt.Println(i+1, ". ", b())
  }
} else {
  fmt.Println("Error: ", e)
}

Types ΒΆ

type Base64 ΒΆ 

type Base64 struct {
	Aligned bool
}

func (*Base64) Decode ΒΆ 

func (e *Base64) Decode(no string) (id *ID, err error)

func (*Base64) Encode ΒΆ 

func (e *Base64) Encode(id *ID) string

type Bits ΒΆ 

type Bits struct {
	// Source indicates that bit-segment data source
	Source DataSourceType
	Width  byte
	Value  int64
	// Key indicates the data source key
	Key string
	// Index indicates the data source index
	Index int
	// contains filtered or unexported fields
}

func Arg ΒΆ 

func Arg(width byte, index int, fallback int64) Bits

Arg to make a bit-segment, which value from caller arguments

func Data ΒΆ 

func Data(width byte, source string, fallback int64, query ...interface{}) Bits

Data to make a bit-segment, which value from data provider

func Env ΒΆ 

func Env(width byte, name string, fallback int64) Bits

Env to make a bit-segment, which value from OS environment variable

func Fixed ΒΆ 

func Fixed(width byte, value int64) Bits

Fixed to make a bit-segment, which value is fixed

func Host ΒΆ 

func Host(width byte, fallback int64) Bits

Host to make the bit-segment of data center id, which value from settings

func Node ΒΆ 

func Node(width byte, fallback int64) Bits

Node to make the bit-segments of server node, which value from settings

func Option ΒΆ 

func Option(width byte, key string, fallback int64) Bits

Option to make a bit-segment, which value from settings in options

func Random ΒΆ 

func Random(width byte) Bits

Random to make a bit-segment, which value from random number

func Sequence ΒΆ 

func Sequence(width byte) Bits

Sequence to make a bit-segment, which value from runtime sequence

func Timestamp ΒΆ 

func Timestamp(width byte, t DateTimeType) Bits

Timestamp to make a bit-segment, which value from system unix timestamp

type Builder ΒΆ 

type Builder struct {
	sync.Mutex

	Encoder Encoder
	Debug   bool
	// contains filtered or unexported fields
}

func Make ΒΆ 

func Make(opt Options) (m *Builder, err error)

Make returns a new Builder instance.

func New ΒΆ 

func New(opt Options) (m *Builder, err error)

New returns a new Builder instance.

func Snowflake ΒΆ 

func Snowflake(host, node int64) (*Builder, error)

Snowflake implements the common snowflake algorithm. The value range of host is [0, 63]. The value range of node is [0, 15].

func (*Builder) DebugInfo ΒΆ 

func (b *Builder) DebugInfo() *DebugInfo

DebugInfo is used to obtain the debugging information of the latest ID

func (*Builder) Next ΒΆ 

func (b *Builder) Next(argv ...int64) (id *ID)

func (*Builder) NextInt64 ΒΆ 

func (b *Builder) NextInt64(argv ...int64) int64

func (*Builder) NextString ΒΆ 

func (b *Builder) NextString(argv ...int64) string

NextString returns the next ID as a string.

func (*Builder) ResetEpoch ΒΆ 

func (b *Builder) ResetEpoch(epoch int64) error

ResetEpoch resets the epoch.

type DataProvider ΒΆ 

type DataProvider interface {
	Read(query ...interface{}) (int64, error)
}

type DataSourceType ΒΆ 

type DataSourceType int
const (
	// Static indicates that the value is from default
	Static DataSourceType = iota
	// Args indicates that the value is from arguments of caller
	Args
	// OS indicates that the value is from OS environment
	OS
	// Settings indicates that the value is from options
	Settings
	// SequenceID indicates that the value is from sequence value
	SequenceID
	// DateTime indicates that the value is from system unix timestamp in nanoseconds
	DateTime
	// RandomID indicates that the value is from a random number
	RandomID
	// Provider indicates that the value is from data provider
	Provider
)

func (DataSourceType) String ΒΆ 

func (d DataSourceType) String() string

type DateTimeType ΒΆ 

type DateTimeType int
const (
	TimestampMilliseconds DateTimeType = iota
	TimestampNanoseconds
	TimestampMicroseconds
	TimestampSeconds
	TimeNanosecond
	TimeMicrosecond
	TimeMillisecond
	TimeSecond
	TimeMinute
	TimeHour
	TimeDay
	TimeMonth
	TimeYear
	TimeYearDay
	TimeWeekday
	TimeWeekNumber
)

func (DateTimeType) String ΒΆ 

func (d DateTimeType) String() string

type DebugInfo ΒΆ 

type DebugInfo struct {
	Sequence int64
	Raw      []int64
	Now      time.Time
}

type DecodeError ΒΆ 

type DecodeError struct {
	No   string
	Type decodeErrorType
	Err  error
}

func (*DecodeError) Error ΒΆ 

func (e *DecodeError) Error() string

func (*DecodeError) Unwrap ΒΆ 

func (e *DecodeError) Unwrap() error

type Encoder ΒΆ 

type Encoder interface {
	Encode(id *ID) string
	Decode(no string) (id *ID, err error)
}

type ID ΒΆ 

type ID struct {
	Main,
	Ext int64
	Signed bool
}

func (*ID) Bytes ΒΆ 

func (id *ID) Bytes() []byte

func (*ID) Equal ΒΆ 

func (id *ID) Equal(b *ID) bool

func (*ID) IsZero ΒΆ 

func (id *ID) IsZero() bool

func (*ID) String ΒΆ 

func (id *ID) String() string

type Options ΒΆ 

type Options struct {
	// ReservedDays indicates the minimum days approaching the end
	ReservedDays,

	EpochMS int64
	// Signed is used to on/off the sign bit
	Signed bool
	// contains filtered or unexported fields
}

Options MUST include DateTime segment AND SequenceID segment

func Config ΒΆ 

func Config(host, node int64, segments ...Bits) *Options

Config is a shortcut for make Options, segments MUST include DateTime segment AND SequenceID segment.

func Default ΒΆ 

func Default() Options

Default is a shortcut for make Options, which is the classic snowflake algorithm

func O ΒΆ 

func O(segments ...Bits) (o *Options)

O is a shortcut for make Options

func OpenID ΒΆ 

func OpenID() Options

OpenID is a shortcut for make Options, 126 bits

func Predefined ΒΆ 

func Predefined(scene string) (Options, bool)

Predefined obtains the predefined options specified by scope(case-insensitive), which includes "Default"(aliases: classic, snowflake), "Random"(aliases: shuffle), "OpenId", "SequenceId"(aliases: seq, seqid, increment, auto-increment), "Test"(aliases: testing) ... etc

func Segments ΒΆ 

func Segments(segments ...Bits) (o *Options)

Segments is a shortcut for make Options

func SeqId ΒΆ 

func SeqId() Options

SeqId is a shortcut for make Options

func Shuffle ΒΆ 

func Shuffle() Options

Shuffle return predefined options "shuffle"(alias: random), 126 bits

func (*Options) Add ΒΆ 

func (o *Options) Add(b Bits) *Options

Add to appends a bit-segment declaration

func (*Options) NewEpoch ΒΆ 

func (o *Options) NewEpoch(v int64) *Options

NewEpoch to set the start timestamp

func (*Options) Patch ΒΆ 

func (o *Options) Patch(offset byte, key string, index int, fallback int64) *Options

Patch is used to modify the settings of the bit field specified by w

func (*Options) Set ΒΆ 

func (o *Options) Set(k string, v int64) *Options

Set to set the settings key and value

type OptionsError ΒΆ 

type OptionsError struct {
	Name  string
	Extra []string
	Err   error
}

func (*OptionsError) Error ΒΆ 

func (e *OptionsError) Error() string

func (*OptionsError) SameAs ΒΆ 

func (e *OptionsError) SameAs(err error) bool

func (*OptionsError) Unwrap ΒΆ 

func (e *OptionsError) Unwrap() error

Source Files ΒΆ

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.