Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/rafaelsales/ulid
Universally Unique Lexicographically Sortable Identifier implementation for Ruby
https://github.com/rafaelsales/ulid
id primary-key ruby ulid uuid
Last synced: 7 days ago
JSON representation
Universally Unique Lexicographically Sortable Identifier implementation for Ruby
- Host: GitHub
- URL: https://github.com/rafaelsales/ulid
- Owner: rafaelsales
- License: mit
- Created: 2016-08-02T07:00:45.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2024-08-02T00:46:09.000Z (6 months ago)
- Last Synced: 2024-10-29T12:30:42.844Z (3 months ago)
- Topics: id, primary-key, ruby, ulid, uuid
- Language: Ruby
- Size: 67.4 KB
- Stars: 484
- Watchers: 9
- Forks: 30
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
[](https://rubygems.org/gems/ulid)
[](https://github.com/rafaelsales/ulid)
# ulid
Universally Unique Lexicographically Sortable Identifier implementation for Ruby
Official specification page: https://github.com/ulid/spec
# 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
```ruby
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.
```ruby
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.
```ruby
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:
* https://github.com/ulid/javascript