ruby-ulid 0.1.0 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0aff39d0f8044f373d8dcdea149f26501e0118dfc0876f060b1b757a4d2a49e
-  data.tar.gz: 02df0ea7a5fe5f8dabd1179988cfe4c2574debf3ad7200d11445eef932dd7443
+  metadata.gz: 01dca4f18f5bb3168b135847b6a1171d00a6ceb03b1d2ef68b6df212975cafc1
+  data.tar.gz: e1b0cb033ded88591d4817395507f517f46b7d3dd3d3a72021a216dcfef09d12
 SHA512:
-  metadata.gz: ab036ed40e4f2740de9d37e44d2c6d4d233fa0071f95383accb2334c4d1f85b30b24eea902e0e29c34fefc8749b8caf5d1f9df6c52f93fe2e76c89aa0912d11e
-  data.tar.gz: d8ac11f63e5b301ed8b1eacd0d1211fd4b3a0bd79ccae8fe87050833cf305a7345da1dc136b95ecccfcafc6110cf9a281afb0f15db1fe2e01984bf320f82b7e5
+  metadata.gz: c9c1a60687c05cfa99ce37f4e692938bff96dd15afa6b0adce40de5b897303b6e57301f069299c06d726bdd7a425e1ed581b7b60e15efc88d69abc417c577005
+  data.tar.gz: 71f333e7a6d6169f346b0e8fba65c9413fa24c32ce6799623e11b789544fb057fa0f67f83ed94a896cbac9df123ee4f9c9598735953217bd6fec332df659ee9f

data/README.md

@@ -10,7 +10,7 @@ Also providing [ruby/rbs](https://github.com/ruby/rbs) signature files.
 
 ![ULIDlogo](https://raw.githubusercontent.com/kachick/ruby-ulid/main/logo.png)
 
-![Build Status](https://github.com/kachick/ruby-ulid/actions/workflows/test.yml/badge.svg?branch=main)
+![Build Status](https://github.com/kachick/ruby-ulid/actions/workflows/test_behaviors.yml/badge.svg?branch=main)
 [![Gem Version](https://badge.fury.io/rb/ruby-ulid.png)](http://badge.fury.io/rb/ruby-ulid)
 
 ## Universally Unique Lexicographically Sortable Identifier
@@ -28,7 +28,7 @@ Instead, herein is proposed ULID:
 - 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](https://www.crockford.com/base32.html) for better efficiency and readability (5 bits per character) # See also exists issues in [Note](#note)
+- Uses [Crockford's base32](https://www.crockford.com/base32.html) 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)
@@ -49,7 +49,7 @@ Should be installed!
 Add this line to your application/library's `Gemfile` is needed in basic use-case
 
 ```ruby
-gem 'ruby-ulid', '>= 0.1.0', '< 0.2.0'
+gem 'ruby-ulid', '>= 0.1.5', '< 0.2.0'
 ```
 
 ### Generator and Parser
@@ -146,6 +146,8 @@ sample_ulids_by_the_time.take(5) #=>
 ulids.sort == ulids #=> true
 ```
 
+Same generator does not generate duplicated ULIDs even in multi threads environment. It is implemented with [Monitor](https://bugs.ruby-lang.org/issues/16255)
+
 ### Filtering IDs with `Time`
 
 `ULID` can be element of the `Range`. If you generated the IDs in monotonic generator, ID based filtering is easy and reliable
@@ -168,7 +170,7 @@ exclude_end = ULID.range(time1...time2) #=> The end of `Range[ULID]` will be the
 
 # Below patterns are acceptable
 pinpointing = ULID.range(time1..time1) #=> This will match only for all IDs in `time1`
-until_the_end = ULID.range(..time1) #=> This will match only for all IDs upto `time1` (The `nil` starting `Range` can be used since Ruby 2.7)
+# until_the_end = ULID.range(..time1) #=> This will match only for all IDs upto `time1` (The `nil` starting `Range` can be used since Ruby 2.7)
 until_the_end = ULID.range(ULID.min.to_time..time1) #=> This is same as above for Ruby 2.6
 until_the_ulid_limit = ULID.range(time1..) # This will match only for all IDs from `time1` to max value of the ULID limit
 
@@ -190,7 +192,7 @@ ULID.floor(time) #=> 2000-01-01 00:00:00.123 UTC
 For rough operations, `ULID.scan` might be useful.
 
 ```ruby
-json =<<'EOD'
+json = <<'JSON'
 {
   "id": "01F4GNAV5ZR6FJQ5SFQC7WDSY3",
   "author": {
@@ -215,7 +217,7 @@ json =<<'EOD'
     }
   ]
 }
-EOD
+JSON
 
 ULID.scan(json).to_a
 #=>
@@ -311,7 +313,7 @@ ulids.take(10)
 # ULID(2021-04-29 03:18:24.152 UTC: 01F4DT4Z4RA0QV8WFQGRAG63EH),
 # ULID(2021-05-02 13:27:16.394 UTC: 01F4PM605ABF5SDVMEHBH8JJ9R)]
 ULID.sample(10, period: ulid1.to_time..ulid2.to_time)
-#=> 
+#=>
 # [ULID(2021-04-29 06:44:41.513 UTC: 01F4E5YPD9XQ3MYXWK8ZJKY8SW),
 #  ULID(2021-05-01 00:35:06.629 UTC: 01F4JNKD85SVK1EAEYSJGF53A2),
 #  ULID(2021-05-02 12:45:28.408 UTC: 01F4PHSEYRG9BWBEWMRW1XE6WW),
@@ -324,6 +326,34 @@ ULID.sample(10, period: ulid1.to_time..ulid2.to_time)
 #  ULID(2021-04-28 15:05:06.808 UTC: 01F4CG68ZRST94T056KRZ5K9S4)]
 ```
 
+### ULID specification ambiguity around orthographical variants of the format
+
+I'm afraid so, we should consider [Current ULID spec](https://github.com/ulid/spec/tree/d0c7170df4517939e70129b4d6462cc162f2d5bf#universally-unique-lexicographically-sortable-identifier) has `orthographical variants of the format` possibilities.
+
+>Uses Crockford's base32 for better efficiency and readability (5 bits per character)
+
+The original `Crockford's base32` maps `I`, `L` to `1`, `O` to `0`.
+And accepts freestyle inserting `Hyphens (-)`.
+To consider this patterns or not is different in each implementations.
+
+Current parser/validator/matcher aims to cover `subset of Crockford's base32`.
+I have suggested it would be clarified in [ulid/spec#57](https://github.com/ulid/spec/pull/57).
+
+>Case insensitive
+
+I can understand it might be considered in actual use-case.
+But it is a controversial point, discussing in [ulid/spec#3](https://github.com/ulid/spec/issues/3).
+
+Be that as it may, this gem provides API for handling the nasty possibilities.
+
+`ULID.normalize` and `ULID.normalized?`
+
+```ruby
+ULID.normalize('-olarz3-noekisv4rrff-q6ig5fav--') #=> "01ARZ3N0EK1SV4RRFFQ61G5FAV"
+ULID.normalized?('-olarz3-noekisv4rrff-q6ig5fav--') #=> false
+ULID.normalized?('01ARZ3N0EK1SV4RRFFQ61G5FAV') #=> true
+```
+
 ### UUIDv4 converter for migration use-cases
 
 `ULID.from_uuidv4` and `ULID#to_uuidv4` is the converter.
@@ -333,7 +363,7 @@ The imported timestamp is meaningless. So ULID's benefit will lost.
 # Currently experimental feature, so needed to load the extension.
 require 'ulid/uuid'
 
-# Basically reversible 
+# Basically reversible
 ulid = ULID.from_uuidv4('0983d0a2-ff15-4d83-8f37-7dd945b5aa39') #=> ULID(2301-07-10 00:28:28.821 UTC: 09GF8A5ZRN9P1RYDVXV52VBAHS)
 ulid.to_uuidv4 #=> "0983d0a2-ff15-4d83-8f37-7dd945b5aa39"
 
@@ -401,6 +431,12 @@ NOTE: It is still having precision issue similar as `ulid gem` in the both gener
 1. [Fix to handle timestamp precision in parser](https://github.com/abachman/ulid-ruby/pull/5)
 1. [Fix to handle timestamp precision in generator](https://github.com/abachman/ulid-ruby/pull/4)
 
+### Compare performance with them
+
+See [Benchmark](https://github.com/kachick/ruby-ulid/wiki/Benchmark).
+
+The results are not something to be proud of.
+
 ## References
 
 - [Repository](https://github.com/kachick/ruby-ulid)
@@ -410,4 +446,3 @@ NOTE: It is still having precision issue similar as `ulid gem` in the both gener
 ## Note
 
 - Another choices for sortable and randomness IDs, [UUIDv6, UUIDv7, UUIDv8 might be the one. (But they are still in draft state)](https://www.ietf.org/archive/id/draft-peabody-dispatch-new-uuid-format-01.html), I will track them in [ruby-ulid#37](https://github.com/kachick/ruby-ulid/issues/37)
-- Current parser/validator/matcher aims to cover `subset of Crockford's base32`. Suggesting it in [ulid/spec#57](https://github.com/ulid/spec/pull/57). Be that as it may, I might provide special handler or converter for the exception in [ruby-ulid#57](https://github.com/kachick/ruby-ulid/issues/57) and/or [ruby-ulid#78](https://github.com/kachick/ruby-ulid/issues/78)

data/lib/ulid.rb

@@ -1,5 +1,6 @@
 # coding: us-ascii
 # frozen_string_literal: true
+
 # Copyright (C) 2021 Kenichi Kamiya
 
 require 'securerandom'
@@ -15,6 +16,7 @@ class ULID
   class Error < StandardError; end
   class OverflowError < Error; end
   class ParserError < Error; end
+  class UnexpectedError < Error; end
 
   # Excluded I, L, O, U, -.
   # This is the encoding patterns.
@@ -59,6 +61,7 @@ class ULID
   # @return [ULID]
   def self.at(time)
     raise ArgumentError, 'ULID.at takes only `Time` instance' unless Time === time
+
     from_milliseconds_and_entropy(milliseconds: milliseconds_from_time(time), entropy: reasonable_entropy)
   end
 
@@ -90,19 +93,21 @@ class ULID
   #   * Do not take random generator for the arguments
   #   * Raising error instead of truncating elements for the given number
   def self.sample(*args, period: nil)
-    int_generator = if period
-      ulid_range = range(period)
-      min, max, exclude_end = ulid_range.begin.to_i, ulid_range.end.to_i, ulid_range.exclude_end?
+    int_generator = (
+      if period
+        ulid_range = range(period)
+        min, max, exclude_end = ulid_range.begin.to_i, ulid_range.end.to_i, ulid_range.exclude_end?
 
-      possibilities = (max - min) + (exclude_end ? 0 : 1)
-      raise ArgumentError, "given range `#{ulid_range.inspect}` does not have possibilities" unless possibilities.positive?
+        possibilities = (max - min) + (exclude_end ? 0 : 1)
+        raise ArgumentError, "given range `#{ulid_range.inspect}` does not have possibilities" unless possibilities.positive?
 
-      -> {
-        SecureRandom.random_number(possibilities) + min
-      }
-    else
-      RANDOM_INTEGER_GENERATOR
-    end
+        -> {
+          SecureRandom.random_number(possibilities) + min
+        }
+      else
+        RANDOM_INTEGER_GENERATOR
+      end
+    )
 
     case args.size
     when 0
@@ -133,6 +138,7 @@ class ULID
     string = String.try_convert(string)
     raise ArgumentError, 'ULID.scan takes only strings' unless string
     return to_enum(__callee__, string) unless block_given?
+
     string.scan(SCANNING_PATTERN) do |matched|
       yield parse(matched)
     end
@@ -155,7 +161,7 @@ class ULID
     milliseconds = n32encoded_timestamp.to_i(32)
     entropy = n32encoded_randomness.to_i(32)
 
-    new milliseconds: milliseconds, entropy: entropy, integer: integer
+    new(milliseconds: milliseconds, entropy: entropy, integer: integer)
   end
 
   # @param [Range<Time>, Range<nil>, Range[ULID]] period
@@ -163,6 +169,7 @@ class ULID
   # @raise [ArgumentError] if the given period is not a `Range[Time]`, `Range[nil]` or `Range[ULID]`
   def self.range(period)
     raise ArgumentError, 'ULID.range takes only `Range[Time]`, `Range[nil]` or `Range[ULID]`' unless Range === period
+
     begin_element, end_element, exclude_end = period.begin, period.end, period.exclude_end?
     return period if self === begin_element && self === end_element
 
@@ -179,11 +186,7 @@ class ULID
 
     case end_element
     when Time
-      if exclude_end
-        end_ulid = min(end_element)
-      else
-        end_ulid = max(end_element)
-      end
+      end_ulid = exclude_end ? min(end_element) : max(end_element)
     when nil
       # The end should be max and include end, because nil end means to cover endless ULIDs until the limit
       end_ulid = MAX
@@ -239,9 +242,8 @@ class ULID
     end
   end
 
-  # @api private
   # @return [Integer]
-  def self.reasonable_entropy
+  private_class_method def self.reasonable_entropy
     SecureRandom.random_number(MAX_ENTROPY)
   end
 
@@ -260,12 +262,65 @@ class ULID
   end
 
   # @param [String, #to_str] string
-  # @return [Boolean]
-  def self.valid?(string)
+  # @return [String]
+  # @raise [ParserError] if the given format is not correct for ULID specs, even if ignored `orthographical variants of the format`
+  def self.normalize(string)
     string = String.try_convert(string)
+    raise ArgumentError, 'ULID.normalize takes only strings' unless string
+
+    normalized_in_crockford = CrockfordBase32.normalize(string)
+    # Ensure the ULID correctness, because CrockfordBase32 does not always mean to satisfy ULID format
+    parse(normalized_in_crockford).to_s
+  end
+
+  # @return [Boolean]
+  def self.normalized?(object)
+    normalized = normalize(object)
+  rescue Exception
+    false
+  else
+    normalized == object
+  end
+
+  # @return [Boolean]
+  def self.valid?(object)
+    string = String.try_convert(object)
     string ? STRICT_PATTERN_WITH_CROCKFORD_BASE32_SUBSET.match?(string) : false
   end
 
+  # @param [ULID, #to_ulid] object
+  # @return [ULID, nil]
+  # @raise [TypeError] if `object.to_ulid` did not return ULID instance
+  def self.try_convert(object)
+    begin
+      converted = object.to_ulid
+    rescue NoMethodError
+      nil
+    else
+      if ULID === converted
+        converted
+      else
+        object_class_name = safe_get_class_name(object)
+        converted_class_name = safe_get_class_name(converted)
+        raise TypeError, "can't convert #{object_class_name} to ULID (#{object_class_name}#to_ulid gives #{converted_class_name})"
+      end
+    end
+  end
+
+  # @param [BasicObject] object
+  # @return [String]
+  private_class_method def self.safe_get_class_name(object)
+    fallback = 'UnknownObject'
+
+    begin
+      name = String.try_convert(object.class.name)
+    rescue Exception
+      fallback
+    else
+      name || fallback
+    end
+  end
+
   # @api private
   # @param [Integer] milliseconds
   # @param [Integer] entropy
@@ -282,7 +337,7 @@ class ULID
     n32encoded_randomness = entropy.to_s(32).rjust(RANDOMNESS_ENCODED_LENGTH, '0')
     integer = (n32encoded_timestamp + n32encoded_randomness).to_i(32)
 
-    new milliseconds: milliseconds, entropy: entropy, integer: integer
+    new(milliseconds: milliseconds, entropy: entropy, integer: integer)
   end
 
   attr_reader :milliseconds, :entropy
@@ -353,7 +408,7 @@ class ULID
   def octets
     digits = @integer.digits(256)
     (OCTETS_LENGTH - digits.size).times do
-      digits.push 0
+      digits.push(0)
     end
     digits.reverse!
   end
@@ -424,6 +479,25 @@ class ULID
     super
   end
 
+  # @api private
+  # @return [Integer]
+  def marshal_dump
+    @integer
+  end
+
+  # @api private
+  # @param [Integer] integer
+  # @return [void]
+  def marshal_load(integer)
+    unmarshaled = ULID.from_integer(integer)
+    initialize(integer: unmarshaled.to_i, milliseconds: unmarshaled.milliseconds, entropy: unmarshaled.entropy)
+  end
+
+  # @return [self]
+  def to_ulid
+    self
+  end
+
   # @return [self]
   def dup
     self

data/lib/ulid/crockford_base32.rb

@@ -1,9 +1,12 @@
 # coding: us-ascii
 # frozen_string_literal: true
+
 # Copyright (C) 2021 Kenichi Kamiya
 
 class ULID
-  # Currently supporting only for `subset` for actual use-case`
+  # @see https://www.crockford.com/base32.html
+  #
+  # This module supporting only `subset of original crockford for actual use-case` in ULID context.
   # Original decoding spec allows other characters.
   # But I think ULID should allow `subset` of Crockford's Base32.
   # See below
@@ -46,11 +49,24 @@ class ULID
       end
     end.freeze
     raise SetupError, 'obvious bug exists in the mapping algorithm' unless N32_CHAR_BY_CROCKFORD_BASE32_CHAR.keys == crockford_base32_mappings.keys
+
     CROCKFORD_BASE32_CHAR_PATTERN = /[#{N32_CHAR_BY_CROCKFORD_BASE32_CHAR.keys.join}]/.freeze
 
     CROCKFORD_BASE32_CHAR_BY_N32_CHAR = N32_CHAR_BY_CROCKFORD_BASE32_CHAR.invert.freeze
     N32_CHAR_PATTERN = /[#{CROCKFORD_BASE32_CHAR_BY_N32_CHAR.keys.join}]/.freeze
 
+    STANDARD_BY_VARIANT = {
+      'L' => '1',
+      'l' => '1',
+      'I' => '1',
+      'i' => '1',
+      'O' => '0',
+      'o' => '0',
+      '-' => ''
+    }.freeze
+    VARIANT_PATTERN = /[#{STANDARD_BY_VARIANT.keys.join}]/.freeze
+
+    # @api private
     # @param [String] string
     # @return [Integer]
     def self.decode(string)
@@ -58,11 +74,19 @@ class ULID
       n32encoded.to_i(32)
     end
 
+    # @api private
     # @param [Integer] integer
     # @return [String]
     def self.encode(integer)
       n32encoded = integer.to_s(32)
       n32encoded.upcase.gsub(N32_CHAR_PATTERN, CROCKFORD_BASE32_CHAR_BY_N32_CHAR).rjust(ENCODED_LENGTH, '0')
     end
+
+    # @api private
+    # @param [String] string
+    # @return [String]
+    def self.normalize(string)
+      string.gsub(VARIANT_PATTERN, STANDARD_BY_VARIANT)
+    end
   end
 end

data/lib/ulid/monotonic_generator.rb

@@ -1,43 +1,69 @@
 # coding: us-ascii
 # frozen_string_literal: true
+
 # Copyright (C) 2021 Kenichi Kamiya
 
 class ULID
   class MonotonicGenerator
-    # @api private
-    attr_accessor :latest_milliseconds, :latest_entropy
+    include MonitorMixin
+
+    # @return [ULID, nil]
+    attr_reader :prev
+
+    undef_method :instance_variable_set
 
     def initialize
-      @mutex = Thread::Mutex.new
-      reset
+      super()
+      @prev = nil
     end
 
+    # @return [String]
+    def inspect
+      "ULID::MonotonicGenerator(prev: #{@prev.inspect})"
+    end
+    alias_method :to_s, :inspect
+
     # @param [Time, Integer] moment
     # @return [ULID]
     # @raise [OverflowError] if the entropy part is larger than the ULID limit in same milliseconds
-    # @raise [ArgumentError] if the given moment(milliseconds) is negative number
+    # @raise [UnexpectedError] if the generated ULID is an invalid value in monotonicity spec.
+    #   Basically will not happen. Just means this feature prefers error rather than invalid value.
     def generate(moment: ULID.current_milliseconds)
-      milliseconds = ULID.milliseconds_from_moment(moment)
-      raise ArgumentError, "milliseconds should not be negative: given: #{milliseconds}" if milliseconds.negative?
-
-      @mutex.synchronize do
-        if @latest_milliseconds < milliseconds
-          @latest_milliseconds = milliseconds
-          @latest_entropy = ULID.reasonable_entropy
-        else
-          @latest_entropy += 1
+      synchronize do
+        unless @prev
+          @prev = ULID.generate(moment: moment)
+          return @prev
         end
-        ULID.from_milliseconds_and_entropy(milliseconds: @latest_milliseconds, entropy: @latest_entropy)
+
+        milliseconds = ULID.milliseconds_from_moment(moment)
+
+        ulid = (
+          if @prev.milliseconds < milliseconds
+            ULID.generate(moment: milliseconds)
+          else
+            ULID.from_milliseconds_and_entropy(milliseconds: @prev.milliseconds, entropy: @prev.entropy.succ)
+          end
+        )
+
+        unless ulid > @prev
+          base_message = "monotonicity broken from unexpected reasons # generated: #{ulid.inspect}, prev: #{@prev.inspect}"
+          additional_information = (
+            if Thread.list == [Thread.main]
+              '# NOTE: looks single thread only exist'
+            else
+              '# NOTE: ran on multi threads, so this might from concurrency issue'
+            end
+          )
+
+          raise UnexpectedError, base_message + additional_information
+        end
+
+        @prev = ulid
+        ulid
       end
     end
 
-    # @api private
-    # @return [void]
-    def reset
-      @latest_milliseconds = 0
-      @latest_entropy = ULID.reasonable_entropy
-      nil
-    end
+    undef_method :freeze
 
     # @raise [TypeError] always raises exception and does not freeze self
     # @return [void]