ruby-ulid 0.0.19 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 646d2a4b433ffbe28d4801483d3f1c43cfb5839bf5f80e759447304a1c8dad52
-  data.tar.gz: 1e4ddc37266eb09f3635ba5509e66e6ff93e15fad3e6574fb3b50e8ad9322b10
+  metadata.gz: 2a390455a27395fd77ef398b0613e72b321b96d44e8454c8ab9346ae15eddfdc
+  data.tar.gz: 1150658ae26cc591f3946898ccb356ce1c6135292de0600ef0604aceb7a00554
 SHA512:
-  metadata.gz: 9a564dbad8c3c88b729353826c599e618cd8963806759ce8a6bf041a95aef60044c8f75873560129bcef7550eec226c3bf04bcfec339c4b07fb72c3372342811
-  data.tar.gz: 187c475f9332cb69827e2664193faa7f001cb14a5709b3c28600286ac9e6c1fb3176e14e3a7ae3a658d232af6157a3dea83ad992cee75db966ff80213c3a0e52
+  metadata.gz: 4ffb5c69ec1327bacbb54b4afdd6718f8cc9b5afd450f739588d8e414c645eca9c1090c77efb464293f0e8e1b960cf4df75289785d3cd7b489404e31c24ecc8a
+  data.tar.gz: bf6a08216e0745d0727c356a5a239126bac8518f8fbb57f295b417e14ed0878c8f0c32774b83137b1feb58d8230140492cb469bb18dc9d5df5db5aa088410ffb

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.0.19'
+gem 'ruby-ulid', '>= 0.1.4', '< 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
 
@@ -243,13 +245,15 @@ ULID.parse('01F4GNBXW1AM2KWW52PVT3ZY9X').patterns
 
 `ULID.min` and `ULID.max` return termination values for ULID spec.
 
+It can take `Time` instance as an optional argument. Then returns min/max ID that has limit of randomness part in the time.
+
 ```ruby
 ULID.min #=> ULID(1970-01-01 00:00:00.000 UTC: 00000000000000000000000000)
 ULID.max #=> ULID(10889-08-02 05:31:50.655 UTC: 7ZZZZZZZZZZZZZZZZZZZZZZZZZ)
 
 time = Time.at(946684800, Rational('123456.789')).utc #=> 2000-01-01 00:00:00.123456789 UTC
-ULID.min(moment: time) #=> ULID(2000-01-01 00:00:00.123 UTC: 00VHNCZB3V0000000000000000)
-ULID.max(moment: time) #=> ULID(2000-01-01 00:00:00.123 UTC: 00VHNCZB3VZZZZZZZZZZZZZZZZ)
+ULID.min(time) #=> ULID(2000-01-01 00:00:00.123 UTC: 00VHNCZB3V0000000000000000)
+ULID.max(time) #=> ULID(2000-01-01 00:00:00.123 UTC: 00VHNCZB3VZZZZZZZZZZZZZZZZ)
 ```
 
 `ULID#next` and `ULID#succ` returns next(successor) ULID.
@@ -309,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),
@@ -322,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.
@@ -331,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"
 
@@ -388,9 +420,9 @@ Major methods can be replaced as below.
 -ULID.time(string)
 +ULID.parse(string).to_time
 -ULID.min_ulid_at(time)
-+ULID.min(moment: time).to_s
++ULID.min(time).to_s
 -ULID.max_ulid_at(time)
-+ULID.max(moment: time).to_s
++ULID.max(time).to_s
 ```
 
 NOTE: It is still having precision issue similar as `ulid gem` in the both generator and parser. I sent PRs.
@@ -399,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)
@@ -408,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

@@ -15,6 +15,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.
@@ -51,7 +52,7 @@ class ULID
   # @param [Integer] entropy
   # @return [ULID]
   def self.generate(moment: current_milliseconds, entropy: reasonable_entropy)
-    new milliseconds: milliseconds_from_moment(moment), entropy: entropy
+    from_milliseconds_and_entropy(milliseconds: milliseconds_from_moment(moment), entropy: entropy)
   end
 
   # Short hand of `ULID.generate(moment: time)`
@@ -59,18 +60,18 @@ class ULID
   # @return [ULID]
   def self.at(time)
     raise ArgumentError, 'ULID.at takes only `Time` instance' unless Time === time
-    new milliseconds: milliseconds_from_time(time), entropy: reasonable_entropy
+    from_milliseconds_and_entropy(milliseconds: milliseconds_from_time(time), entropy: reasonable_entropy)
   end
 
-  # @param [Integer, Time] moment
+  # @param [Time, Integer] moment
   # @return [ULID]
-  def self.min(moment: 0)
+  def self.min(moment=0)
     0.equal?(moment) ? MIN : generate(moment: moment, entropy: 0)
   end
 
-  # @param [Integer, Time] moment
+  # @param [Time, Integer] moment
   # @return [ULID]
-  def self.max(moment: MAX_MILLISECONDS)
+  def self.max(moment=MAX_MILLISECONDS)
     MAX_MILLISECONDS.equal?(moment) ? MAX : generate(moment: moment, entropy: MAX_ENTROPY)
   end
 
@@ -112,11 +113,11 @@ class ULID
       raise ArgumentError, 'accepts no argument or integer only' unless Integer === number
 
       if number > MAX_INTEGER || number.negative?
-        raise ArgumentError, "given number #{number} is larger than ULID limit #{MAX_INTEGER} or negative: #{number.inspect}"
+        raise ArgumentError, "given number `#{number}` is larger than ULID limit `#{MAX_INTEGER}` or negative"
       end
 
       if period && (number > possibilities)
-        raise ArgumentError, "given number #{number} is larger than given possibilities #{possibilities}"
+        raise ArgumentError, "given number `#{number}` is larger than given possibilities `#{possibilities}`"
       end
 
       Array.new(number) { from_integer(int_generator.call) }
@@ -139,12 +140,12 @@ class ULID
     self
   end
 
-  # @param [Integer, #to_int] integer
+  # @param [Integer] integer
   # @return [ULID]
   # @raise [OverflowError] if the given integer is larger than the ULID limit
   # @raise [ArgumentError] if the given integer is negative number
   def self.from_integer(integer)
-    integer = integer.to_int
+    raise ArgumentError, 'ULID.from_integer takes only `Integer`' unless Integer === integer
     raise OverflowError, "integer overflow: given #{integer}, max: #{MAX_INTEGER}" unless integer <= MAX_INTEGER
     raise ArgumentError, "integer should not be negative: given: #{integer}" if integer.negative?
 
@@ -160,29 +161,29 @@ class ULID
 
   # @param [Range<Time>, Range<nil>, Range[ULID]] period
   # @return [Range<ULID>]
-  # @raise [ArgumentError] if the given period is not a `Range[Time]` or `Range[nil]`
+  # @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]` or `Range[nil]`' unless 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
 
     case begin_element
     when Time
-      begin_ulid = min(moment: begin_element)
+      begin_ulid = min(begin_element)
     when nil
       begin_ulid = MIN
     when self
       begin_ulid = begin_element
     else
-      raise ArgumentError, "ULID.range takes only `Range[Time]` or `Range[nil]`, given: #{period.inspect}"
+      raise ArgumentError, "ULID.range takes only `Range[Time]`, `Range[nil]` or `Range[ULID]`, given: #{period.inspect}"
     end
 
     case end_element
     when Time
       if exclude_end
-        end_ulid = min(moment: end_element)
+        end_ulid = min(end_element)
       else
-        end_ulid = max(moment: end_element)
+        end_ulid = max(end_element)
       end
     when nil
       # The end should be max and include end, because nil end means to cover endless ULIDs until the limit
@@ -191,7 +192,7 @@ class ULID
     when self
       end_ulid = end_element
     else
-      raise ArgumentError, "ULID.range takes only `Range[Time]` or `Range[nil]`, given: #{period.inspect}"
+      raise ArgumentError, "ULID.range takes only `Range[Time]`, `Range[nil]` or `Range[ULID]`, given: #{period.inspect}"
     end
 
     begin_ulid.freeze
@@ -218,6 +219,7 @@ class ULID
     milliseconds_from_time(Time.now)
   end
 
+  # @api private
   # @param [Time] time
   # @return [Integer]
   private_class_method def self.milliseconds_from_time(time)
@@ -238,9 +240,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
 
@@ -259,18 +260,82 @@ 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 [MonotonicGenerator] generator
+  # @param [Integer] milliseconds
+  # @param [Integer] entropy
   # @return [ULID]
-  def self.from_monotonic_generator(generator)
-    raise ArgumentError, 'this method provided only for MonotonicGenerator' unless MonotonicGenerator === generator
-    new milliseconds: generator.latest_milliseconds, entropy: generator.latest_entropy
+  # @raise [OverflowError] if the given value is larger than the ULID limit
+  # @raise [ArgumentError] if the given milliseconds and/or entropy is negative number
+  def self.from_milliseconds_and_entropy(milliseconds:, entropy:)
+    raise ArgumentError, 'milliseconds and entropy should be an `Integer`' unless Integer === milliseconds && Integer === entropy
+    raise OverflowError, "timestamp overflow: given #{milliseconds}, max: #{MAX_MILLISECONDS}" unless milliseconds <= MAX_MILLISECONDS
+    raise OverflowError, "entropy overflow: given #{entropy}, max: #{MAX_ENTROPY}" unless entropy <= MAX_ENTROPY
+    raise ArgumentError, 'milliseconds and entropy should not be negative' if milliseconds.negative? || entropy.negative?
+
+    n32encoded_timestamp = milliseconds.to_s(32).rjust(TIMESTAMP_ENCODED_LENGTH, '0')
+    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
   end
 
   attr_reader :milliseconds, :entropy
@@ -280,42 +345,27 @@ class ULID
   # @param [Integer] entropy
   # @param [Integer] integer
   # @return [void]
-  # @raise [OverflowError] if the given value is larger than the ULID limit
-  # @raise [ArgumentError] if the given milliseconds and/or entropy is negative number
-  def initialize(milliseconds:, entropy:, integer: nil)
-    if integer
-      @integer = integer
-    else
-      milliseconds = milliseconds.to_int
-      entropy = entropy.to_int
-
-      raise OverflowError, "timestamp overflow: given #{milliseconds}, max: #{MAX_MILLISECONDS}" unless milliseconds <= MAX_MILLISECONDS
-      raise OverflowError, "entropy overflow: given #{entropy}, max: #{MAX_ENTROPY}" unless entropy <= MAX_ENTROPY
-      raise ArgumentError, 'milliseconds and entropy should not be negative' if milliseconds.negative? || entropy.negative?
-    end
-
+  def initialize(milliseconds:, entropy:, integer:)
+    # All arguments check should be done with each constructors, not here
+    @integer = integer
     @milliseconds = milliseconds
     @entropy = entropy
   end
 
   # @return [String]
   def to_s
-    @string ||= CrockfordBase32.encode(to_i).freeze
+    @string ||= CrockfordBase32.encode(@integer).freeze
   end
 
   # @return [Integer]
   def to_i
-    @integer ||= begin
-      n32encoded_timestamp = milliseconds.to_s(32).rjust(TIMESTAMP_ENCODED_LENGTH, '0')
-      n32encoded_randomness = entropy.to_s(32).rjust(RANDOMNESS_ENCODED_LENGTH, '0')
-      (n32encoded_timestamp + n32encoded_randomness).to_i(32)
-    end
+    @integer
   end
   alias_method :hash, :to_i
 
   # @return [Integer, nil]
   def <=>(other)
-    (ULID === other) ? (to_i <=> other.to_i) : nil
+    (ULID === other) ? (@integer <=> other.to_i) : nil
   end
 
   # @return [String]
@@ -325,7 +375,7 @@ class ULID
 
   # @return [Boolean]
   def eql?(other)
-    equal?(other) || (ULID === other && to_i == other.to_i)
+    equal?(other) || (ULID === other && @integer == other.to_i)
   end
   alias_method :==, :eql?
 
@@ -333,7 +383,7 @@ class ULID
   def ===(other)
     case other
     when ULID
-      to_i == other.to_i
+      @integer == other.to_i
     when String
       to_s == other.upcase
     else
@@ -354,7 +404,7 @@ class ULID
 
   # @return [Array(Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer)]
   def octets
-    digits = to_i.digits(256)
+    digits = @integer.digits(256)
     (OCTETS_LENGTH - digits.size).times do
       digits.push 0
     end
@@ -393,7 +443,7 @@ class ULID
 
   # @return [ULID, nil] when called on ULID as `7ZZZZZZZZZZZZZZZZZZZZZZZZZ`, returns `nil` instead of ULID
   def succ
-    succ_int = to_i.succ
+    succ_int = @integer.succ
     if succ_int >= MAX_INTEGER
       if succ_int == MAX_INTEGER
         MAX
@@ -408,7 +458,7 @@ class ULID
 
   # @return [ULID, nil] when called on ULID as `00000000000000000000000000`, returns `nil` instead of ULID
   def pred
-    pred_int = to_i.pred
+    pred_int = @integer.pred
     if pred_int <= 0
       if pred_int == 0
         MIN
@@ -427,6 +477,23 @@ class ULID
     super
   end
 
+  # @return [self]
+  def to_ulid
+    self
+  end
+
+  # @return [self]
+  def dup
+    self
+  end
+
+  # @return [self]
+  def clone(freeze: true)
+    self
+  end
+
+  undef_method :instance_variable_set
+
   private
 
   # @return [void]