nulid

README

NULID

nulid is a dependency-free Go implementation of NULID, a 128-bit lexicographically sortable identifier. It is a nanosecond-resolution descendant of ULID: while a ULID carries a 48-bit millisecond timestamp, a NULID carries a 68-bit nanosecond timestamp. That gives you much tighter ordering when you're generating IDs at high throughput, but it still keeps the same 128-bit / 26-character footprint.

Install

go get github.com/yzevm/nulid

Usage

import "github.com/yzevm/nulid"

func main() {
	id := nulid.Make()         // crypto/rand entropy, current time
	fmt.Println((id.String())) // e.g. 01H1CD7M59WM8N000000000C1S

	fmt.Println(id.Random()) // 60-bit random component
	fmt.Println(id.Time())   // time.Time, full precision
}

Documentation

Index

• Constants
• Variables
• type MonotonicEntropy
  • func Monotonic(entropy io.Reader, inc uint64) *MonotonicEntropy
  • func (m *MonotonicEntropy) MonotonicRead(timestampNanos uint64, p []byte) error
  • func (m *MonotonicEntropy) MonotonicReadBig(timestampNanos *big.Int, p []byte) error
• type MonotonicReader
• type MonotonicReaderBig
• type NULID
  • func FromNanos(timestampNanos uint64, random uint64) NULID
  • func FromNanosBig(timestampNanos *big.Int, random uint64) (NULID, error)
  • func FromTime(t time.Time, random uint64) (NULID, error)
  • func Make() (id NULID)
  • func MustParse(ulid string) NULID
  • func New() (NULID, error)
  • func NewWithEntropy(timestampNanos uint64, r io.Reader) (NULID, error)
  • func NewWithEntropyBig(timestampNanos *big.Int, r io.Reader) (NULID, error)
  • func NewWithTime(t time.Time, r io.Reader) (NULID, error)
  • func Parse(id string) (NULID, error)
  • func (id NULID) Bytes() [16]byte
  • func (id NULID) Compare(other NULID) int
  • func (id NULID) IsNil() bool
  • func (id NULID) Less(other NULID) bool
  • func (id NULID) MarshalBinary() ([]byte, error)
  • func (id NULID) MarshalText() ([]byte, error)
  • func (id NULID) Random() uint64
  • func (id *NULID) Scan(src any) error
  • func (id NULID) String() string
  • func (id NULID) Time() time.Time
  • func (id *NULID) UnmarshalBinary(data []byte) error
  • func (id *NULID) UnmarshalText(text []byte) error
  • func (id NULID) Value() (driver.Value, error)

Constants

const EntropyLen = 8

Variables

var (
	ErrEntropyUnavailable = errors.New("nulid: secure entropy unavailable")
	ErrMonotonicOverflow  = errors.New("nulid: monotonic entropy overflow")
)

var (
	ErrScanValue = errors.New("nulid: unsupported value type for Scan")
)

Types

type MonotonicEntropy

type MonotonicEntropy struct {
	io.Reader
	// contains filtered or unexported fields
}

func Monotonic

func Monotonic(entropy io.Reader, inc uint64) *MonotonicEntropy

func (*MonotonicEntropy) MonotonicRead

func (m *MonotonicEntropy) MonotonicRead(timestampNanos uint64, p []byte) error

func (*MonotonicEntropy) MonotonicReadBig

func (m *MonotonicEntropy) MonotonicReadBig(timestampNanos *big.Int, p []byte) error

type MonotonicReader

type MonotonicReader interface {
	io.Reader

	MonotonicRead(timestampNanos uint64, p []byte) error
}

type MonotonicReaderBig

type MonotonicReaderBig interface {
	MonotonicReader

	MonotonicReadBig(timestampNanos *big.Int, p []byte) error
}

type NULID

type NULID [16]byte

func FromNanos

func FromNanos(timestampNanos uint64, random uint64) NULID

func FromNanosBig

func FromNanosBig(timestampNanos *big.Int, random uint64) (NULID, error)

func FromTime

func FromTime(t time.Time, random uint64) (NULID, error)

func Make

func Make() (id NULID)

func MustParse

func MustParse(ulid string) NULID

func New

func New() (NULID, error)

func NewWithEntropy

func NewWithEntropy(timestampNanos uint64, r io.Reader) (NULID, error)

func NewWithEntropyBig

func NewWithEntropyBig(timestampNanos *big.Int, r io.Reader) (NULID, error)

func NewWithTime

func NewWithTime(t time.Time, r io.Reader) (NULID, error)

func Parse

func Parse(id string) (NULID, error)

func (NULID) Bytes

func (id NULID) Bytes() [16]byte

func (NULID) Compare

func (id NULID) Compare(other NULID) int

func (NULID) IsNil

func (id NULID) IsNil() bool

func (NULID) Less

func (id NULID) Less(other NULID) bool

func (NULID) MarshalBinary

func (id NULID) MarshalBinary() ([]byte, error)

MarshalBinary implements encoding.BinaryMarshaler

func (NULID) MarshalText

func (id NULID) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler

func (NULID) Random

func (id NULID) Random() uint64

func (*NULID) Scan

func (id *NULID) Scan(src any) error

Scan implements database/sql.Scanner

func (NULID) String

func (id NULID) String() string

func (NULID) Time

func (id NULID) Time() time.Time

func (*NULID) UnmarshalBinary

func (id *NULID) UnmarshalBinary(data []byte) error

UnmarshalBinary implements encoding.BinaryUnmarshaler

func (*NULID) UnmarshalText

func (id *NULID) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler

func (NULID) Value

func (id NULID) Value() (driver.Value, error)

Value implements database/sql/driver.Valuer