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.