Project

ruby-ulid

0.0
There's a lot of open issues
ULID(Universally Unique Lexicographically Sortable Identifier) is defined on https://github.com/ulid/spec. It has useful specs for actual applications. This gem aims to provide the generator, monotonic generator and handy manipulation methods for the ID.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
 Project Readme

ruby-ulid

A handy ULID library

The ULID spec is defined on ulid/spec. Formal name is Universally Unique Lexicographically Sortable Identifier. It has useful specs for actual applications. This gem aims to provide the generator, monotonic generator, parser and handy manipulation methods for the ID. Also having rbs signature files.


ULIDlogo

Build Status Gem Version

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
  • UUID v1/v2 is impractical in many environments, as it requires access to a unique, stable MAC address
  • UUID v3/v5 requires a unique seed and produces randomly distributed IDs, which can cause fragmentation in many data structures
  • UUID v4 provides no other information than randomness which can cause fragmentation in many data structures

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)
  • Monotonic sort order (correctly detects and handles the same millisecond)

Install

gem install ruby-ulid

Usage

The generated ULID is an object not just a string. It means easily get the timestamps and binary formats.

require 'ulid'

ulid = ULID.generate #=> ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GRMJ9AA)
ulid.to_time #=> 2021-04-27 17:27:22.826 UTC
ulid.to_s #=> "01F4A5Y1YAQCYAYCTC7GRMJ9AA"
ulid.octets #=> [1, 121, 20, 95, 7, 202, 187, 60, 175, 51, 76, 60, 49, 73, 37, 74]

You can parse from exists IDs

ulid = ULID.parse('01ARZ3NDEKTSV4RRFFQ69G5FAV') #=> ULID(2016-07-30 23:54:10.259 UTC: 01ARZ3NDEKTSV4RRFFQ69G5FAV)

Providing monotonic generator. It is called as Monotonicity on the spec.

ulids = 10000.times.map do
  ULID.generate
end
ulids.sort == ulids #=> false

monotonic_generator = ULID::MonotonicGenerator.new
monotonic_ulids = 10000.times.map do
  monotonic_generator.generate
end
monotonic_ulids.sort == monotonic_ulids #=> true

Development

At first, you should install development dependencies

git clone git@github.com:kachick/ruby-ulid.git
cd ./ruby-ulid
bundle install

Play with the behaviors in REPL.

$ ./bin/console
ulid = ULID.generate #=> ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GRMJ9AA)

If you try to add/change/fix features, please update tests and ensure they are not broken.

bundle exec rake test

If you try to improve any performance issue, please add benchmarking and check the result of before and after.

bundle exec ruby benchmark/*

Documents

Author

Kenichi Kamiya - @kachick