ruby-ulid 0.0.10 → 0.0.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce2bb6c517e9fee4f758577e57d2c5eddfd16db9ee3c0d17ad41db8d9f1de383
-  data.tar.gz: 1cfb027a652e2035445483bdff2511c2837441e2e664286d60682fec6769cd17
+  metadata.gz: 6a620e80f82e91c778329ccf7da8cca96bda4b12e047610b9543768c5ec85d22
+  data.tar.gz: ea28469d63348758f52e1460b5330ce177ad2281e63060800a0669054758f3ee
 SHA512:
-  metadata.gz: ea00703256bc218a1e022dd732da22b37b9caeec30bdbdb4df945f9f185d408f0b746c36b36377dba2d4acaae5d2cf0b4db8b574ecc9da0e6e4b9b0af5c2404f
-  data.tar.gz: 6cd088ae1d539d8cb1d2690eb4248be413e527a87db7eb67b3c1adfc167c285cf2b90bb5701e82208586996649d56d1ef6c7c30396d1fbf0fc68220487711a54
+  metadata.gz: acb07ae797c3a06a6626d34e15dc1056a30586e8bc151a3773770259d2f4047d0708593e702fbd67a7609758165f20a15f208fede068717a5555733535ed4bde
+  data.tar.gz: 57c9819d86f2a0f002cf3b9a7b76b3a36bc412fa874d50136ec296f1217fb905fa19feb52de2c9d5250547da384580cf882121f0e331054cd665bd113d1f10e3

data/README.md

@@ -2,11 +2,9 @@
 
 A handy `ULID` library
 
-The `ULID` spec is defined on [ulid/spec](https://github.com/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.
+The `ULID` spec is defined on [ulid/spec](https://github.com/ulid/spec). It has useful specs for applications (e.g. `Database key`), especially possess all `uniqueness`, `randomness`, `extractable timestamps` and `sortable` features.
+This gem aims to provide the generator, monotonic generator, parser and handy manipulation features around the ULID.
+Also providing [ruby/rbs](https://github.com/ruby/rbs) signature files.
 
 ---
 
@@ -30,13 +28,15 @@ 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 for better efficiency and readability (5 bits per character)
+- 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)
 - Case insensitive
 - No special characters (URL safe)
 - Monotonic sort order (correctly detects and handles the same millisecond)
 
 ## Install
 
+Require Ruby 2.6 or later
+
 ```console
 $ gem install ruby-ulid
 #=> Installed
@@ -57,13 +57,14 @@ ulid.octets #=> [1, 121, 20, 95, 7, 202, 187, 60, 175, 51, 76, 60, 49, 73, 37, 7
 ulid.pattern #=> /(?<timestamp>01F4A5Y1YA)(?<randomness>QCYAYCTC7GRMJ9AA)/i
 ```
 
-You can parse from exists IDs
+You can get the objects from exists encoded ULIDs
 
 ```ruby
 ulid = ULID.parse('01ARZ3NDEKTSV4RRFFQ69G5FAV') #=> ULID(2016-07-30 23:54:10.259 UTC: 01ARZ3NDEKTSV4RRFFQ69G5FAV)
+ulid.to_time #=> 2016-07-30 23:54:10.259 UTC
 ```
 
-ULID is sortable when they are generated different timestamp in milliseconds precision
+ULIDs are sortable when they are generated in different timestamp with milliseconds precision
 
 ```ruby
 ulids = 1000.times.map do
@@ -74,29 +75,71 @@ ulids.sort == ulids #=> true
 ulids.uniq(&:to_time).size #=> 1000
 ```
 
-Providing monotonic generator for same milliseconds use-cases. It is called as [Monotonicity](https://github.com/ulid/spec/tree/d0c7170df4517939e70129b4d6462cc162f2d5bf#monotonicity) on the spec.
+`ULID.generate` can take fixed `Time` instance
+
+```ruby
+time = Time.at(946684800, in: 'UTC') #=> 2000-01-01 00:00:00 UTC
+ULID.generate(moment: time) #=> ULID(2000-01-01 00:00:00.000 UTC: 00VHNCZB00N018DCPJA4H9379P)
+ULID.generate(moment: time) #=> ULID(2000-01-01 00:00:00.000 UTC: 00VHNCZB006WQT3JTMN0T14EBP)
+
+ulids = 1000.times.map do |n|
+  ULID.generate(moment: time + n)
+end
+ulids.sort == ulids #=> true
+```
+
+The basic generator prefers `randomness`, it does not guarantee `sortable` for same milliseconds ULIDs.
 
 ```ruby
 ulids = 10000.times.map do
   ULID.generate
 end
-ulids.uniq(&:to_time).size #=> 35 (the number will be changed by every creation)
+ulids.uniq(&:to_time).size #=> 35 (the size is not fixed, might be changed in environment)
 ulids.sort == ulids #=> false
+```
 
+If you want to ensure `sortable`, Use `MonotonicGenerator` instead. It is called as [Monotonicity](https://github.com/ulid/spec/tree/d0c7170df4517939e70129b4d6462cc162f2d5bf#monotonicity) on the spec.
+(Though it starts with new random value when changed the timestamp)
 
+```ruby
 monotonic_generator = ULID::MonotonicGenerator.new
-monotonic_ulids = 10000.times.map do
+ulids = 10000.times.map do
   monotonic_generator.generate
 end
-monotonic_ulids.uniq(&:to_time).size #=> 34 (the number will be changed by every creation)
-monotonic_ulids.sort == monotonic_ulids #=> true
+sample_ulids_by_the_time = ulids.uniq(&:to_time)
+sample_ulids_by_the_time.size #=> 32 (the size is not fixed, might be changed in environment)
+
+# In same milliseconds creation, it just increments the end of randomness part
+ulids.take(5) #=>
+# [ULID(2021-05-02 15:23:48.917 UTC: 01F4PTVCSN9ZPFKYTY2DDJVRK4),
+#  ULID(2021-05-02 15:23:48.917 UTC: 01F4PTVCSN9ZPFKYTY2DDJVRK5),
+#  ULID(2021-05-02 15:23:48.917 UTC: 01F4PTVCSN9ZPFKYTY2DDJVRK6),
+#  ULID(2021-05-02 15:23:48.917 UTC: 01F4PTVCSN9ZPFKYTY2DDJVRK7),
+#  ULID(2021-05-02 15:23:48.917 UTC: 01F4PTVCSN9ZPFKYTY2DDJVRK8)]
+
+# When the milliseconds is updated, it starts with new randomness
+sample_ulids_by_the_time.take(5) #=>
+# [ULID(2021-05-02 15:23:48.917 UTC: 01F4PTVCSN9ZPFKYTY2DDJVRK4),
+#  ULID(2021-05-02 15:23:48.918 UTC: 01F4PTVCSPF2KXG4ABT7CK3204),
+#  ULID(2021-05-02 15:23:48.919 UTC: 01F4PTVCSQF1GERBPCQV6TCX2K),
+#  ULID(2021-05-02 15:23:48.920 UTC: 01F4PTVCSRBXN2H4P1EYWZ27AK),
+#  ULID(2021-05-02 15:23:48.921 UTC: 01F4PTVCSSK0ASBBZARV7013F8)]
+
+ulids.sort == ulids #=> true
 ```
 
-Providing converter for UUIDv4. (Of course the timestamp will be useless one.)
+When filtering ULIDs by `Time`, we should consider to handle the precision.
+So this gem provides `ULID.range` to generate `Range[ULID]` from given `Range[Time]`
 
 ```ruby
-ULID.from_uuidv4('0983d0a2-ff15-4d83-8f37-7dd945b5aa39')
-#=> ULID(2301-07-10 00:28:28.821 UTC: 09GF8A5ZRN9P1RYDVXV52VBAHS)
+# Both of below, The begin of `Range[ULID]` will be the minimum in the floored milliseconds of the time1
+include_end = ULID.range(time1..time2) #=> The end of `Range[ULID]` will be the maximum in the floored milliseconds of the time2
+exclude_end = ULID.range(time1...time2) #=> The end of `Range[ULID]` will be the minimum in the floored milliseconds of the time2
+
+# So you can use the generated range objects as below
+ulids.grep(include_end)
+ulids.grep(exclude_end)
+#=> I hope the results should be actually you want!
 ```
 
 For rough operations, `ULID.scan` might be useful.
@@ -150,50 +193,59 @@ ULID.min(moment: time) #=> ULID(2000-01-01 00:00:00.123 UTC: 00VHNCZB3V000000000
 ULID.max(moment: time) #=> ULID(2000-01-01 00:00:00.123 UTC: 00VHNCZB3VZZZZZZZZZZZZZZZZ)
 ```
 
-## Development
-
-At first, you should install development dependencies
+`ULID#next` and `ULID#succ` returns next(successor) ULID
 
-```console
-$ git clone git@github.com:kachick/ruby-ulid.git
-$ cd ./ruby-ulid
-$ bundle install
-# Executing first time might take longtime, because development mode dependent active_support via steep
+```ruby
+ULID.parse('01BX5ZZKBKZZZZZZZZZZZZZZZY').next.to_s #=> "01BX5ZZKBKZZZZZZZZZZZZZZZZ"
+ULID.parse('01BX5ZZKBKZZZZZZZZZZZZZZZZ').next.to_s #=> "01BX5ZZKBM0000000000000000"
+ULID.parse('7ZZZZZZZZZZZZZZZZZZZZZZZZZ').next #=> nil
 ```
 
-Play with the behaviors in REPL.
+`ULID#pred` returns predecessor ULID
 
-```console
-$ ./bin/console
-# Starting up IRB with loading developing ULID library
-irb(main):001:0>
+```ruby
+ULID.parse('01BX5ZZKBK0000000000000001').pred.to_s #=> "01BX5ZZKBK0000000000000000"
+ULID.parse('01BX5ZZKBK0000000000000000').pred.to_s #=> "01BX5ZZKBJZZZZZZZZZZZZZZZZ"
+ULID.parse('00000000000000000000000000').pred #=> nil
 ```
 
+### UUIDv4 converter for migration use-cases
+
+`ULID.from_uuidv4` and `ULID#to_uuidv4` is the converter.
+The imported timestamp is meaningless. So ULID's benefit will lost
+
 ```ruby
-# On IRB, you can check behaviors even if it is undocumented
-ulid = ULID.generate #=> ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GRMJ9AA)
-ls ULID
-```
+# 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"
 
-If you try to add/change/fix features, please update tests and ensure they are not broken.
+uuid_v4s = 10000.times.map { SecureRandom.uuid }
+uuid_v4s.uniq.size == 10000 #=> Probably `true`
 
-```console
-$ bundle exec rake test
-$ echo $?
-0
-```
+ulids = uuid_v4s.map { |uuid_v4| ULID.from_uuidv4(uuid_v4) }
+ulids.map(&:to_uuidv4) == uuid_v4s #=> **Probably** `true` except below examples.
 
-If you try to improve any performance issue, please add benchmarking and check the result of before and after.
+# NOTE: Some boundary values are not reversible. See below.
 
-```console
-$ bundle exec ruby benchmark/the_added_file.rb
-# Showing the results
+ULID.min.to_uuidv4 #=> "00000000-0000-4000-8000-000000000000"
+ULID.max.to_uuidv4 #=> "ffffffff-ffff-4fff-bfff-ffffffffffff"
+
+# These importing results are same as https://github.com/ahawker/ulid/tree/96bdb1daad7ce96f6db8c91ac0410b66d2e1c4c1 on CPython 3.9.4
+reversed_min = ULID.from_uuidv4('00000000-0000-4000-8000-000000000000') #=> ULID(1970-01-01 00:00:00.000 UTC: 00000000008008000000000000)
+reversed_max = ULID.from_uuidv4('ffffffff-ffff-4fff-bfff-ffffffffffff') #=> ULID(10889-08-02 05:31:50.655 UTC: 7ZZZZZZZZZ9ZZVZZZZZZZZZZZZ)
+
+# But they are not reversible! Need to consider this issue in https://github.com/kachick/ruby-ulid/issues/76
+ULID.min == reversed_min #=> false
+ULID.max == reversed_max #=> false
 ```
 
-## Documents
+## References
 
-- [API documents generated by YARD](https://kachick.github.io/ruby-ulid/)
+- [Repository](https://github.com/kachick/ruby-ulid)
+- [API documents](https://kachick.github.io/ruby-ulid/)
+- [ulid/spec](https://github.com/ulid/spec)
 
-## Author
+## Note
 
-Kenichi Kamiya - [@kachick](https://github.com/kachick)
+- 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

@@ -35,7 +35,7 @@ class ULID
   STRICT_PATTERN = /\A#{PATTERN.source}\z/i.freeze
 
   # Imported from https://stackoverflow.com/a/38191104/1212807, thank you!
-  UUIDV4_PATTERN = /\A[0-9A-F]{8}-[0-9A-F]{4}-[4][0-9A-F]{3}-[89AB][0-9A-F]{3}-[0-9A-F]{12}\z/i
+  UUIDV4_PATTERN = /\A[0-9A-F]{8}-[0-9A-F]{4}-[4][0-9A-F]{3}-[89AB][0-9A-F]{3}-[0-9A-F]{12}\z/i.freeze
 
   # Same as Time#inspect since Ruby 2.7, just to keep backward compatibility
   # @see https://bugs.ruby-lang.org/issues/15958
@@ -45,20 +45,19 @@ class ULID
   # @param [Integer] entropy
   # @return [ULID]
   def self.generate(moment: current_milliseconds, entropy: reasonable_entropy)
-    milliseconds = moment.kind_of?(Time) ? time_to_milliseconds(moment) : moment
-    new milliseconds: milliseconds, entropy: entropy
+    new milliseconds: milliseconds_from_moment(moment), entropy: entropy
   end
 
   # @param [Integer, Time] moment
   # @return [ULID]
   def self.min(moment: 0)
-    generate(moment: moment, entropy: 0)
+    0.equal?(moment) ? MIN : generate(moment: moment, entropy: 0)
   end
 
   # @param [Integer, Time] moment
   # @return [ULID]
   def self.max(moment: MAX_MILLISECONDS)
-    generate(moment: moment, entropy: MAX_ENTROPY)
+    MAX_MILLISECONDS.equal?(moment) ? MAX : generate(moment: moment, entropy: MAX_ENTROPY)
   end
 
   # @deprecated This method actually changes class state. Use {ULID::MonotonicGenerator} instead.
@@ -107,6 +106,7 @@ class ULID
   # @return [ULID]
   # @raise [OverflowError] if the given integer is larger than the ULID limit
   # @raise [ArgumentError] if the given integer is negative number
+  # @todo Need optimized for performance
   def self.from_integer(integer)
     integer = integer.to_int
     raise OverflowError, "integer overflow: given #{integer}, max: #{MAX_INTEGER}" unless integer <= MAX_INTEGER
@@ -121,17 +121,70 @@ class ULID
     new milliseconds: milliseconds, entropy: entropy
   end
 
+  # @param [Range<Time>, Range<nil>] time_range
+  # @return [Range<ULID>]
+  # @raise [ArgumentError] if the given time_range is not a `Range[Time]` or `Range[nil]`
+  def self.range(time_range)
+    raise argument_error_for_range_building(time_range) unless time_range.kind_of?(Range)
+    begin_time, end_time, exclude_end = time_range.begin, time_range.end, time_range.exclude_end?
+
+    case begin_time
+    when Time
+      begin_ulid = min(moment: begin_time)
+    when nil
+      begin_ulid = min
+    else
+      raise argument_error_for_range_building(time_range)
+    end
+
+    case end_time
+    when Time
+      if exclude_end
+        end_ulid = min(moment: end_time)
+      else
+        end_ulid = max(moment: end_time)
+      end
+    when nil
+      # The end should be max and include end, because nil end means to cover endless ULIDs until the limit
+      end_ulid = max
+      exclude_end = false
+    else
+      raise argument_error_for_range_building(time_range)
+    end
+
+    begin_ulid.freeze
+    end_ulid.freeze
+
+    Range.new(begin_ulid, end_ulid, exclude_end)
+  end
+
+  # @param [Time] time
+  # @return [Time]
+  def self.floor(time)
+    if RUBY_VERSION >= '2.7'
+      time.floor(3)
+    else
+      Time.at(0, milliseconds_from_time(time), :millisecond)
+    end
+  end
+
   # @return [Integer]
   def self.current_milliseconds
-    time_to_milliseconds(Time.now)
+    milliseconds_from_time(Time.now)
   end
 
   # @param [Time] time
   # @return [Integer]
-  def self.time_to_milliseconds(time)
+  def self.milliseconds_from_time(time)
     (time.to_r * 1000).to_i
   end
 
+  # @param [Time, Integer] moment
+  # @return [Integer]
+  def self.milliseconds_from_moment(moment)
+    moment.kind_of?(Time) ? milliseconds_from_time(moment) : moment.to_int
+  end
+
   # @return [Integer]
   def self.reasonable_entropy
     SecureRandom.random_number(MAX_ENTROPY)
@@ -167,6 +220,7 @@ class ULID
     true
   end
 
+  # @api private
   # @param [Integer] integer
   # @param [Integer] length
   # @return [Array<Integer>]
@@ -178,6 +232,7 @@ class ULID
     digits.reverse!
   end
 
+  # @api private
   # @see The logics taken from https://bugs.ruby-lang.org/issues/14401, thanks!
   # @param [Array<Integer>] reversed_digits
   # @return [Integer]
@@ -190,8 +245,14 @@ class ULID
     num
   end
 
+  # @return [ArgumentError]
+  private_class_method def self.argument_error_for_range_building(argument)
+    ArgumentError.new "ULID.range takes only `Range[Time]` or `Range[nil]`, given: #{argument.inspect}"
+  end
+
   attr_reader :milliseconds, :entropy
 
+  # @api private
   # @param [Integer] milliseconds
   # @param [Integer] entropy
   # @return [void]
@@ -209,10 +270,9 @@ class ULID
   end
 
   # @return [String]
-  def to_str
+  def to_s
     @string ||= Integer::Base.string_for(to_i, ENCODING_CHARS).rjust(ENCODED_ID_LENGTH, '0').upcase.freeze
   end
-  alias_method :to_s, :to_str
 
   # @return [Integer]
   def to_i
@@ -227,7 +287,7 @@ class ULID
 
   # @return [String]
   def inspect
-    @inspect ||= "ULID(#{to_time.strftime(TIME_FORMAT_IN_INSPECT)}: #{to_str})".freeze
+    @inspect ||= "ULID(#{to_time.strftime(TIME_FORMAT_IN_INSPECT)}: #{to_s})".freeze
   end
 
   # @return [Boolean]
@@ -254,7 +314,13 @@ class ULID
 
   # @return [Time]
   def to_time
-    @time ||= Time.at(0, @milliseconds, :millisecond).utc.freeze
+    @time ||= begin
+      if RUBY_VERSION >= '2.7'
+        Time.at(0, @milliseconds, :millisecond, in: 'UTC').freeze
+      else
+        Time.at(0, @milliseconds, :millisecond).utc.freeze
+      end
+    end
   end
 
   # @return [Array(Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer)]
@@ -292,21 +358,36 @@ class ULID
     @strict_pattern ||= /\A#{pattern.source}\z/i.freeze
   end
 
-  # @raise [OverflowError] if the next entropy part is larger than the ULID limit
-  # @return [ULID]
+  # @return [ULID, nil] when called on ULID as `7ZZZZZZZZZZZZZZZZZZZZZZZZZ`, returns `nil` instead of ULID
   def next
-    @next ||= self.class.new(milliseconds: @milliseconds, entropy: @entropy + 1)
+    next_int = to_i.next
+    return nil if next_int > MAX_INTEGER
+    @next ||= self.class.from_integer(next_int)
   end
   alias_method :succ, :next
 
+  # @return [ULID, nil] when called on ULID as `00000000000000000000000000`, returns `nil` instead of ULID
+  def pred
+    pre_int = to_i.pred
+    return nil if pre_int.negative?
+    @pred ||= self.class.from_integer(pre_int)
+  end
+
+  # @return [String]
+  def to_uuidv4
+    @uuidv4 ||= begin
+      # This code referenced https://github.com/ruby/ruby/blob/121fa24a3451b45c41ac0a661b64e9fc8600e589/lib/securerandom.rb#L221-L241
+      array = octets.pack('C*').unpack('NnnnnN')
+      array[2] = (array[2] & 0x0fff) | 0x4000
+      array[3] = (array[3] & 0x3fff) | 0x8000
+      ('%08x-%04x-%04x-%04x-%04x%08x' % array).freeze
+    end
+  end
+
   # @return [self]
   def freeze
-    # Evaluate all caching
-    inspect
-    octets
-    succ
-    to_i
-    strict_pattern
+    # Need to cache before freezing, because frozen objects can't assign instance variables
+    cache_all_instance_variables
     super
   end
 
@@ -314,7 +395,18 @@ class ULID
 
   # @return [MatchData]
   def matchdata
-    @matchdata ||= STRICT_PATTERN.match(to_str).freeze
+    @matchdata ||= STRICT_PATTERN.match(to_s).freeze
+  end
+
+  # @return [void]
+  def cache_all_instance_variables
+    inspect
+    octets
+    to_i
+    succ
+    pred
+    strict_pattern
+    to_uuidv4
   end
 end
 
@@ -322,7 +414,9 @@ require_relative 'ulid/version'
 require_relative 'ulid/monotonic_generator'
 
 class ULID
+  MIN = parse('00000000000000000000000000').freeze
+  MAX = parse('7ZZZZZZZZZZZZZZZZZZZZZZZZZ').freeze
   MONOTONIC_GENERATOR = MonotonicGenerator.new
 
-  private_constant :ENCODING_CHARS, :TIME_FORMAT_IN_INSPECT, :UUIDV4_PATTERN
+  private_constant :ENCODING_CHARS, :TIME_FORMAT_IN_INSPECT, :UUIDV4_PATTERN, :MIN, :MAX
 end

data/lib/ulid/monotonic_generator.rb

@@ -4,35 +4,37 @@
 
 class ULID
   class MonotonicGenerator
+    # @api private
     attr_accessor :latest_milliseconds, :latest_entropy
 
     def initialize
       reset
     end
 
-    # @raise [OverflowError] if the entropy part is larger than the ULID limit in same milliseconds
+    # @param [Time, Integer] moment
     # @return [ULID]
-    def generate
-      milliseconds = ULID.current_milliseconds
-      reasonable_entropy = ULID.reasonable_entropy
+    # @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
+    def generate(moment: ULID.current_milliseconds)
+      milliseconds = ULID.milliseconds_from_moment(moment)
+      raise ArgumentError, "milliseconds should not be negative: given: #{milliseconds}" if milliseconds.negative?
 
-      @latest_milliseconds ||= milliseconds
-      @latest_entropy ||= reasonable_entropy
-      if @latest_milliseconds != milliseconds
+      if @latest_milliseconds < milliseconds
         @latest_milliseconds = milliseconds
-        @latest_entropy = reasonable_entropy
+        @latest_entropy = ULID.reasonable_entropy
       else
         @latest_entropy += 1
       end
 
-      ULID.new milliseconds: milliseconds, entropy: @latest_entropy
+      ULID.new milliseconds: @latest_milliseconds, entropy: @latest_entropy
     end
 
-    # @return [self]
+    # @api private
+    # @return [void]
     def reset
-      @latest_milliseconds = nil
-      @latest_entropy = nil
-      self
+      @latest_milliseconds = 0
+      @latest_entropy = ULID.reasonable_entropy
+      nil
     end
 
     # @raise [TypeError] always raises exception and does not freeze self

data/lib/ulid/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 class ULID
-  VERSION = '0.0.10'
+  VERSION = '0.0.15'
 end

data/sig/ulid.rbs

@@ -16,8 +16,13 @@ class ULID
   STRICT_PATTERN: Regexp
   UUIDV4_PATTERN: Regexp
   MONOTONIC_GENERATOR: MonotonicGenerator
+  MIN: ULID
+  MAX: ULID
   include Comparable
 
+  # The `moment` is a `Time` or `Intger of the milliseconds`
+  type moment = Time | Integer
+
   class Error < StandardError
   end
 
@@ -28,15 +33,14 @@ class ULID
   end
 
   class MonotonicGenerator
-    attr_accessor latest_milliseconds: Integer?
-    attr_accessor latest_entropy: Integer?
+    attr_accessor latest_milliseconds: Integer
+    attr_accessor latest_entropy: Integer
     def initialize: -> void
-    def generate: -> ULID
+    def generate: (?moment: moment) -> ULID
     def reset: -> void
     def freeze: -> void
   end
 
-  type moment = Time | Integer
   type octets = [Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer]
   type timestamp_octets = [Integer, Integer, Integer, Integer, Integer, Integer]
   type randomness_octets = [Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer]
@@ -55,12 +59,16 @@ class ULID
   @next: ULID?
   @pattern: Regexp?
   @strict_pattern: Regexp?
+  @uuidv4: String?
   @matchdata: MatchData?
 
   def self.generate: (?moment: moment, ?entropy: Integer) -> ULID
   def self.monotonic_generate: -> ULID
   def self.current_milliseconds: -> Integer
-  def self.time_to_milliseconds: (Time time) -> Integer
+  def self.milliseconds_from_time: (Time time) -> Integer
+  def self.milliseconds_from_moment: (moment moment) -> Integer
+  def self.range: (Range[Time] | Range[nil] time_range) -> Range[ULID]
+  def self.floor: (Time time) -> Time
   def self.reasonable_entropy: -> Integer
   def self.parse: (String string) -> ULID
   def self.from_uuidv4: (String uuid) -> ULID
@@ -75,8 +83,7 @@ class ULID
   attr_reader milliseconds: Integer
   attr_reader entropy: Integer
   def initialize: (milliseconds: Integer, entropy: Integer) -> void
-  def to_str: -> String
-  alias to_s to_str
+  def to_s: -> String
   def to_i: -> Integer
   alias hash to_i
   def <=>: (ULID other) -> Integer
@@ -93,10 +100,14 @@ class ULID
   def octets: -> octets
   def timestamp_octets: -> timestamp_octets
   def randomness_octets: -> randomness_octets
-  def next: -> ULID
+  def to_uuidv4: -> String
+  def next: -> ULID?
   alias succ next
+  def pred: -> ULID?
   def freeze: -> self
 
   private
+  def self.argument_error_for_range_building: (untyped argument) -> ArgumentError
   def matchdata: -> MatchData
+  def cache_all_instance_variables: -> void
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-ulid
 version: !ruby/object:Gem::Version
-  version: 0.0.10
+  version: 0.0.15
 platform: ruby
 authors:
 - Kenichi Kamiya
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-05-01 00:00:00.000000000 Z
+date: 2021-05-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: integer-base
@@ -30,6 +30,20 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: 0.2.0
+- !ruby/object:Gem::Dependency
+  name: rbs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.0
 - !ruby/object:Gem::Dependency
   name: benchmark-ips
   requirement: !ruby/object:Gem::Requirement
@@ -70,11 +84,10 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '2'
-description: |2
-      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, parser and handy manipulation methods for the ID.
-      Also having rbs signature files.
+description: "    ULID(Universally Unique Lexicographically Sortable Identifier) has
+  useful specs for applications (e.g. `Database key`). \n    This gem aims to provide
+  the generator, monotonic generator, parser and handy manipulation features around
+  the ULID.\n    Also providing `rbs` signature files.\n"
 email:
 - kachick1+ruby@gmail.com
 executables: []
@@ -83,7 +96,6 @@ extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
-- Steepfile
 - lib/ulid.rb
 - lib/ulid/monotonic_generator.rb
 - lib/ulid/version.rb
@@ -103,7 +115,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: 2.6.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/Steepfile

@@ -1,7 +0,0 @@
-target :lib do
-  signature 'sig'
-
-  check 'lib'
-
-  library 'securerandom'
-end