ulid 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c072f00beeac3732fbbee2fe32af5f95e14a4eb516e659f70e9e08c0bc525e01
-  data.tar.gz: f8d7ad8d5e714c142c0309a6e814be406c61519cc6e36adcaccae4982d94b96f
+  metadata.gz: 8cbdba2a6645c66ab28595928ff1121cb32b15de3a687b865678c00903e9379e
+  data.tar.gz: e5b1d117960ba3babdf3c73f067529f9f501bba90a7a8401625f0555c6b97b38
 SHA512:
-  metadata.gz: 0e7aaedb437ae82765ec74cf36ddbeb5b529948c9c65c077a0e648156c21ebb23dc26f2e85b3430434dd1babfaaa1b4b1d8bfd00c8dbf9f09f332bad33b93f97
-  data.tar.gz: 01f353360ca4b82534de75f8e715d872b9c976a85655a9f419dfc1a93b6e867d0bea342ad970a3b4653048f3484bba1bc8842f75980142869d13005d3fabc1e7
+  metadata.gz: 07d641b18cabe49adb75117b744b03b442f5d9be7a97d433927265ec9cae1031e6ba51626860bcd2289be68a228971282e0ae45db37940697437c5a79c158d35
+  data.tar.gz: 823d8b48de6d9eda3eaad2955384c8d9fc4251f8c1b447ec7c743c731d6dd5c942880d9e93aacd97ea7c9f66cc755e1f3ab2031307377be24a5abd2fb262606f

data/.github/workflows/ruby.yml

@@ -1,20 +1,26 @@
 name: Ruby
 
-on: [push]
+on:
+  pull_request: ~
+  push:
+    branches:
+      - master
 
 jobs:
   build:
 
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['2.6', '2.7', '3.0', '3.1', '3.2']
 
     steps:
     - uses: actions/checkout@v2
-    - name: Set up Ruby 2.6
-      uses: actions/setup-ruby@v1
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
       with:
-        ruby-version: 2.6.x
-    - name: Build and test with Rake
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true # Run "bundle install", and cache the result automatically.
+    - name: Run tests
       run: |
-        gem install bundler
-        bundle install --jobs 4 --retry 3
         bundle exec rake test

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+# 1.4.0
+
+- PR #32 - Allow fully deterministic ULID generation by providing both the timestamp
+  component and a string suffix to replace the randomness component. Thanks @andjosh
+
 # 1.2.0
 
 - PR #20 - Use an array to improve speed / reduce memory allocations. Thanks, @jamescook

data/Gemfile

@@ -3,7 +3,7 @@ source 'https://rubygems.org'
 gemspec
 
 group :development, :test do
-  gem 'pry-byebug'
+  gem 'byebug'
   gem 'rake'
   gem 'rubocop'
 end

data/Gemfile.lock

@@ -1,50 +1,48 @@
 PATH
   remote: .
   specs:
-    ulid (1.2.0)
+    ulid (1.3.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    ast (2.3.0)
+    ast (2.4.2)
     base32-crockford (0.1.0)
-    byebug (9.1.0)
-    coderay (1.1.2)
-    method_source (0.9.0)
-    minitest (5.10.3)
-    parallel (1.12.0)
-    parser (2.4.0.0)
-      ast (~> 2.2)
-    powerpack (0.1.1)
-    pry (0.11.3)
-      coderay (~> 1.1.0)
-      method_source (~> 0.9.0)
-    pry-byebug (3.5.1)
-      byebug (~> 9.1)
-      pry (~> 0.10)
-    rainbow (2.2.2)
-      rake
-    rake (13.0.1)
-    rubocop (0.50.0)
+    byebug (11.1.3)
+    json (2.6.3)
+    minitest (5.18.0)
+    parallel (1.22.1)
+    parser (3.2.1.0)
+      ast (~> 2.4.1)
+    rainbow (3.1.1)
+    rake (13.0.6)
+    regexp_parser (2.7.0)
+    rexml (3.2.5)
+    rubocop (1.47.0)
+      json (~> 2.3)
       parallel (~> 1.10)
-      parser (>= 2.3.3.1, < 3.0)
-      powerpack (~> 0.1)
-      rainbow (>= 2.2.2, < 3.0)
+      parser (>= 3.2.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.26.0, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (~> 1.0, >= 1.0.1)
-    ruby-progressbar (1.8.3)
-    unicode-display_width (1.3.0)
+      unicode-display_width (>= 2.4.0, < 3.0)
+    rubocop-ast (1.27.0)
+      parser (>= 3.2.1.0)
+    ruby-progressbar (1.13.0)
+    unicode-display_width (2.4.2)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   base32-crockford
+  byebug
   minitest
-  pry-byebug
   rake
   rubocop
   ulid!
 
 BUNDLED WITH
-   2.0.1
+   2.4.7

data/README.md

@@ -48,6 +48,30 @@ 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.*

data/lib/ulid/generator.rb

@@ -1,52 +1,60 @@
 # frozen-string-literal: true
 
-if RUBY_VERSION >= '2.5'
-  require 'securerandom'
-else
-  require 'sysrandom/securerandom'
-end
+require 'securerandom'
 
 module ULID
   module Generator
     ENCODING = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'.bytes.freeze # Crockford's Base32
-    RANDOM_BYTES = 10
+    RANDOM_BITS = 80
     ENCODED_LENGTH = 26
-    BIT_LENGTH = 128
     BITS_PER_B32_CHAR = 5
     ZERO = '0'.ord
-
     MASK = 0x1f
 
-    def generate(time = Time.now)
-      input = octo_word(time)
+    # Generates a 128-bit ULID string.
+    # @param [Time] time (Time.now) Timestamp - first 48 bits
+    # @param [String] suffix (80 random bits) - the remaining 80 bits as hex encodable string
+    def generate(time = Time.now, suffix: nil)
+      (hi, lo) = generate_bytes(time, suffix: suffix).unpack('Q>Q>')
+      if hi.nil? || lo.nil?
+        raise ArgumentError, 'suffix string without hex encoding passed to ULID generator'
+      end
 
-      encode(input, ENCODED_LENGTH)
+      integer = (hi << 64) | lo
+      encode(integer, ENCODED_LENGTH)
     end
 
-    def generate_bytes(time = Time.now)
-      time_48bit(time) + random_bytes
+    # Generates a 128-bit ULID.
+    # @param [Time] time (Time.now) Timestamp - first 48 bits
+    # @param [String] suffix (80 random bits) - the remaining 80 bits as hex encodable string
+    def generate_bytes(time = Time.now, suffix: nil)
+      suffix_bytes =
+        if suffix
+          suffix.split('').map { |char| char.to_i(32) }.pack('C*')
+        else
+          SecureRandom.random_bytes(RANDOM_BITS / 8)
+        end
+
+      time_48bit(time) + suffix_bytes
     end
 
     private
 
+    # Encodes a 128-bit integer input as a 26-character ULID string using Crockford's Base32.
     def encode(input, length)
-      e = Array.new(length, ZERO)
+      encoded = Array.new(length, ZERO)
       i = length - 1
 
       while input > 0
-        e[i] = ENCODING[input & MASK]
-        input >>= 5
+        encoded[i] = ENCODING[input & MASK]
+        input >>= BITS_PER_B32_CHAR
         i -= 1
       end
 
-      e.pack('c*')
-    end
-
-    def octo_word(time = Time.now)
-      (hi, lo) = generate_bytes(time).unpack('Q>Q>')
-      (hi << 64) | lo
+      encoded.pack('c*')
     end
 
+    # Returns the first 6 bytes of a timestamp (in milliseconds since the Unix epoch) as a 48-bit byte string
     def time_48bit(time = Time.now)
       # Avoid `time.to_f` since we want to accurately represent a whole number of milliseconds:
       #
@@ -62,9 +70,5 @@ module ULID
       time_ms = (time.to_r * 1000).to_i
       [time_ms].pack('Q>')[2..-1]
     end
-
-    def random_bytes
-      SecureRandom.random_bytes(RANDOM_BYTES)
-    end
   end
 end

data/lib/ulid/version.rb

@@ -1,3 +1,4 @@
+# frozen-string-literal: true
 module ULID
-  VERSION = '1.3.0'.freeze
+  VERSION = '1.4.0'
 end

data/spec/lib/ulid_spec.rb

@@ -6,7 +6,7 @@ describe ULID do
     it 'ensures it has 26 chars' do
       ulid = ULID.generate
 
-      ulid.length.must_equal 26
+      assert_equal ulid.length, 26
     end
 
     it 'is sortable' do
@@ -49,6 +49,41 @@ describe ULID do
 
       assert_equal(ulids, ulids.sort)
     end
+
+    it 'is deterministic based on time' do
+      input_time = Time.now
+      ulid1 = ULID.generate(input_time)
+      ulid2 = ULID.generate(input_time)
+      assert_equal ulid2.slice(0, 10), ulid1.slice(0, 10)
+      assert ulid2 != ulid1
+    end
+
+    it 'is deterministic based on suffix' do
+      input_time = Time.now
+      suffix = SecureRandom.uuid
+      ulid1 = ULID.generate(input_time, suffix: suffix)
+      ulid2 = ULID.generate(input_time + 1, suffix: suffix)
+      assert_equal ulid2.slice(10, 26), ulid1.slice(10, 26)
+      assert ulid2 != ulid1
+    end
+
+    it 'is fully deterministic based on time and suffix' do
+      input_time = Time.now
+      suffix = SecureRandom.uuid
+      ulid1 = ULID.generate(input_time, suffix: suffix)
+      ulid2 = ULID.generate(input_time, suffix: suffix)
+      assert_equal ulid2, ulid1
+    end
+
+    it 'raises exception when non-encodable 80-bit suffix string is used' do
+      input_time = Time.now
+      suffix = SecureRandom.uuid
+      assert_raises(ArgumentError) do
+        ULID.generate(input_time, suffix: suffix[0...9])
+      end
+
+      ULID.generate(input_time, suffix: suffix[0...10])
+    end
   end
 
   describe 'underlying binary' do
@@ -61,8 +96,8 @@ describe ULID do
     end
 
     it 'encodes the remaining 80 bits as random' do
-      random_bytes = SecureRandom.random_bytes(ULID::Generator::RANDOM_BYTES)
-      ULID.stub(:random_bytes, random_bytes) do
+      random_bytes = SecureRandom.random_bytes(ULID::Generator::RANDOM_BITS / 8)
+      SecureRandom.stub(:random_bytes, random_bytes) do
         bytes = ULID.generate_bytes
         assert bytes[6..-1] == random_bytes
       end

data/spec/spec_helper.rb

@@ -1,4 +1,4 @@
-require 'pry'
+require 'byebug'
 require 'minitest/autorun'
 require 'minitest/pride'
 require 'ulid'

data/ulid.gemspec

@@ -1,6 +1,6 @@
 lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'ulid/version'
+require_relative 'lib/ulid/version'
 
 Gem::Specification.new do |spec|
   spec.name          = 'ulid'
@@ -12,12 +12,6 @@ Gem::Specification.new do |spec|
   spec.license       = 'MIT'
 
   spec.files         = `git ls-files -z`.split("\x0")
-  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
-  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ['lib']
-
-  spec.post_install_message = '
-ulid gem needs to install sysrandom gem if you use Ruby 2.4 or older.
-Execute `gem install sysrandom` or add `gem "sysrandom"` to Gemfile.
-'
+  spec.required_ruby_version = '>= 2.6.8'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ulid
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Rafael Sales
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-03-01 00:00:00.000000000 Z
+date: 2023-03-05 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -38,10 +38,7 @@ homepage: https://github.com/rafaelsales/ulid
 licenses:
 - MIT
 metadata: {}
-post_install_message: |2
-
-  ulid gem needs to install sysrandom gem if you use Ruby 2.4 or older.
-  Execute `gem install sysrandom` or add `gem "sysrandom"` to Gemfile.
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -49,18 +46,16 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.6.8
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
+rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
 summary: Universally Unique Lexicographically Sortable Identifier implementation for
   Ruby
-test_files:
-- spec/lib/ulid_spec.rb
-- spec/spec_helper.rb
+test_files: []