Project

lsuuid

0.0
The project is in a healthy, maintained state
Universally Unique Lexicographically Sortable Identifier
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
 Dependencies
 Project Readme

LSUUID (Lexicographically Sortable Universally Unique Identifier)

LSUUID is a lexicographically sortable identifier with format similar to UUIDv4. UUID has some limitations which are already listed and addressed by ULID.

LSUUID provides the following improvements over ulid :-

  • The timestamp component in ulid is in milliseconds whereas LSUUID uses nanoseconds so that chance of collision is reduced 1000 times
  • Ability to bucket the generated identifiers with a prefix is provided by LSUUID
  • LSUUID adheres to the UUIDv4 format there by allowing the storage of the identifier in the UUID datatype of data stores which is more efficient than a string which is required for ulid.

Note: For use cases where format of the identifier is not a matter of concern, using ULID over LSUUID might be a better choice.

Specification

Below is the structure of LSUUID.

Without Prefix:

 Sample LSUUID: 619bd0ef-2a04-5068-d3c4-f6fac6809edb

 619bd0ef-2a04-5068-      d3c4-f6fac6809edb

|------------------|     |-----------------|
     Timestamp                Randomness
       64bits                   64bits

With Prefix:

 Sample LSUUID: 619bd0ef-2a04-5068-d3c4-f6fac6809edb

 619bd0      ef-2a04-5068-d3c4-f6      fac6809edb

|------|    |--------------------|    |----------|
 Prefix            Timestamp           Randomness
 24bits             64bits               40bits

Components:

Timestamp

  • 64 bit integer
  • UNIX-time in nanoseconds

Randomness

  • 64 bits (40 bits in case a prefix is specified)
  • Cryptographically secure source of randomness, if possible

Installation

Add this line to your application's Gemfile:

gem 'lsuuid'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install lsuuid

Usage

Generate a UUID:

irb(main):001:0> LSUUID.generate
=> "619bd0ef-2a04-5068-d3c4-f6fac6809edb"

Generates a UUID based on the method call time.

Timestamp specific UUIDs:

irb(main):001:0> t = Time.now     
=> 2021-11-22 22:49:02 +0530
irb(main):002:0> LSUUID.generate(time: t)
=> "619bd106-0c6b-ba28-7811-f5787dab02d4"

Modes:

ceil

irb(main):001:0> LSUUID.generate(time: t, mode: :ceil)
=> "619bd106-0c6b-ba28-ffff-ffffffffffff"
irb(main):002:0>  LSUUID.generate(time: t, mode: :ceil, prefix: 0)
=> "00000061-9bd1-060c-6bba-28ffffffffff"

floor

irb(main):001:0> LSUUID.generate(time: t, mode: :floor)
=> "619bd106-0c6b-ba28-0000-000000000000"
irb(main):002:0>  LSUUID.generate(time: t, mode: :ceil, prefix: 0)
=> "00000061-9bd1-060c-6bba-280000000000"

Prefix

irb(main):001:0> LSUUID.generate(prefix: 0, time: t)
=> "00000061-9bd1-060c-6bba-28428c7e196d"
irb(main):002:0> LSUUID.generate(prefix: 1000, time: t)
=> "0003e861-9bd1-060c-6bba-28d9cb973352"
irb(main):003:0> LSUUID.generate(prefix: 16_777_215, time: t)
=> "ffffff61-9bd1-060c-6bba-2826264c51e0"

Note: Prefix can be an integer between 0 and 16,777,215

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/hwslabs/lsuuid.

License

The gem is available as open source under the terms of the MIT License.