Code Monkey home page Code Monkey logo

ulid's Introduction

Ruby Gem Downloads GitHub License

ulid

Universally Unique Lexicographically Sortable Identifier implementation for Ruby

Official specification page: https://github.com/ulid/spec



ulid


Universally Unique Lexicographically Sortable Identifier

UUID can be suboptimal for many uses-cases because:

  • It isn't the most character efficient way of encoding 128 bits of randomness
  • The string format itself is apparently based on the original MAC & time version (UUIDv1 from Wikipedia)
  • It provides no other information than randomness

Instead, herein is proposed ULID:

  • 128-bit compatibility with UUID
  • 1.21e+24 unique ULIDs per millisecond
  • Lexicographically sortable!
  • Canonically encoded as a 26 character string, as opposed to the 36 character UUID
  • Uses Crockford's base32 for better efficiency and readability (5 bits per character)
  • Case insensitive
  • No special characters (URL safe)

Installation

gem install ulid

Usage

require 'ulid'

ULID.generate # 01ARZ3NDEKTSV4RRFFQ69G5FAV

I want to generate a ULID using an arbitrary timestamp

You can optionally pass a Time instance to ULID.generate to set an arbitrary timestamp component, i.e. the prefix of the ULID.

time_t1 = Time.now
ulid = ULID.generate(time_t1)

I want to generate a ULID using an arbitrary suffix, i.e. without the randomness component

You can optionally pass a 80-bit hex-encodable String on the argument suffix to ULID.generate. This will replace the randomness component by the suffix provided. This allows for fully deterministic ULIDs.

require 'securerandom'

time = Time.now
an_event_identifier = SecureRandom.uuid
ulid1 = ULID.generate(time, suffix: an_event_identifier)
ulid2 = ULID.generate(time, suffix: an_event_identifier)
ulid1 == ulid2 # true

Specification

Below is the current specification of ULID as implemented in this repository. Note: the binary format has not been implemented.

 01AN4Z07BY      79KA1307SR9X4MV3

|----------|    |----------------|
 Timestamp          Randomness
  10 chars           16 chars
   48bits             80bits
   base32             base32

Components

Timestamp

  • 48 bit integer
  • UNIX-time in milliseconds
  • Won't run out of space till the year 10895 AD.

Randomness

  • 80 bits
  • Cryptographically secure source of randomness, if possible

Sorting

The left-most character must be sorted first, and the right-most character sorted last. The default ASCII order is used for sorting.

Binary Layout and Byte Order

The components are encoded as 16 octets. Each component is encoded with the Most Significant Byte first (network byte order).

0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                      32_bit_uint_time_high                    |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|     16_bit_uint_time_low      |       16_bit_uint_random      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                       32_bit_uint_random                      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                       32_bit_uint_random                      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

String Representation

ttttttttttrrrrrrrrrrrrrrrr

where
t is Timestamp
r is Randomness

Test Suite

bundle exec rake test

Credits and references:

ulid's People

Contributors

bquorning avatar dcuddeback avatar dependabot[bot] avatar filipebarcos avatar jamescook avatar joshbeckman avatar kachick avatar olleolleolle avatar owst avatar pocke avatar rafaelsales avatar sakuro avatar seamusabshere avatar seuros avatar shmokmt avatar tsenart avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

ulid's Issues

Sort order does not respect millisecond ordering

As I read the spec in this repo, the lexicographical sort ordering of ULIDs should respect the timestamp ordering to millisecond precision. However, this does not appear to always be the case:

require 'ulid'

times = Array.new(5) { |i| Time.new(2020, 9, 3, 13, 9, Rational(i, 10**3)) }

puts 'Times:'
puts times.map { |t| t.strftime('%F %T.%N') }

ulids = times.map { |t| ULID.generate(t) }
puts 'ULIDs:'
puts ulids

sorted = ulids.sort
puts 'Sorted:'
puts sorted

puts "Sort respects time? #{ulids == sorted}"

gives

Times:
2020-09-03 13:09:00.000000000
2020-09-03 13:09:00.001000000
2020-09-03 13:09:00.002000000
2020-09-03 13:09:00.003000000
2020-09-03 13:09:00.004000000
ULIDs:
01EH9XXEV0KCZV2TBC86EGT900
01EH9XXEV1NNSE20T5E9PDH4Q9
01EH9XXEV1HSVWPK0E776QR1ZX
01EH9XXEV3XYZH7SVCH8684MVV
01EH9XXEV4205AFCAVKAT9YH2V
Sorted:
01EH9XXEV0KCZV2TBC86EGT900
01EH9XXEV1HSVWPK0E776QR1ZX
01EH9XXEV1NNSE20T5E9PDH4Q9
01EH9XXEV3XYZH7SVCH8684MVV
01EH9XXEV4205AFCAVKAT9YH2V
Sort respects time? false

The problem being that (in this example run) that 01EH9XXEV1NNSE20T5E9PDH4Q9 sorts after 01EH9XXEV1HSVWPK0E776QR1ZX, despite the timestamp used to generate the former being 1 millisecond before that of the latter. Looking at the timestamp portion of the two ULIDs, they are the same: 01EH9XXEV1, which means both 2020-09-03 13:09:00.001 and 2020-09-03 13:09:00.002map to the same ULID prefix.

I think I broke ULID

It has been brought to my attention that ULID has a (sort of) standard associated with it, originating in this javascript repo: https://github.com/alizain/ulid. I honestly thought you had invented it.... Whoops! So, my changes actually break compatibility with the javascript implementation and use an incorrect binary layout in the binary format.

I'm thinking it makes the most sense to roll back the changes and call it a new release... I don't think gems can be un-released, so that may be the only option.

Lexicographic Sort Order?

Hello. I assumed that this meant that I could sort the ULID's - in other words, newer ID's should fall lexicographically after earlier ones:

In mathematics, the lexicographic or lexicographical order (also known as lexical order, dictionary order, alphabetical order or lexicographic(al) product) is a generalization of the way the alphabetical order of words is based on the alphabetical order of their component letters.

So:

Loading development environment (Rails 5.0.0.rc2)
irb(main):001:0> ULID.generate
=> "7S2SYCSA109VJ4Z2ZVB4PBRCDV"
irb(main):002:0> ULID.generate
=> "6K4SYCSA10EVAK6F5E32R1K50C"
irb(main):003:0> ULID.generate
=> "6J6SYCSA10186DZ41ZBV57PZFV"
irb(main):004:0> ULID.generate
=> "Z98SYCSA1036VDH0ANC31A9YNZ"
irb(main):005:0> ULID.generate
=> "EMASYCSA10NEYETVH1DQPPMKJM"
irb(main):006:0> ULID.generate
=> "8CAVYCSA104HS6BH2VBMBMK4TK"
irb(main):007:0> ULID.generate
=> "EYBVYCSA1078FH66T8TZKYV9EX"
irb(main):008:0> ULID.generate
=> "PWDVYCSA108QKE6F8W36TTDJX8"
irb(main):009:0> ULID.generate
=> "X2FVYCSA1031REQ1M1Y00GH33P"
irb(main):010:0> ULID.generate
=> "XDGVYCSA1088A9DZFK7A042GPX"
irb(main):011:0> ULID.generate
=> "XRHVYCSA10KXJ73TGCBCYPDWR7"
irb(main):012:0> ULID.generate
=> "6VJVYCSA100JB4D804HDBNPMVD"

You can see that those entries are not sortable (6VJVYCSA100JB4D804HDBNPMVD sorts before XRHVYCSA10KXJ73TGCBCYPDWR7, and if I'm wrong on that, then 8CAVYCSA104HS6BH2VBMBMK4TK is out of sequence).

Am I missing something?

renen.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.