ruby-ulid 0.0.9 → 0.0.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc7674472c14c213d6fe01c6994520b33bc82ab164b538948a4f1b532d0d88f2
-  data.tar.gz: 85987c59ca6f119d40caaf69cc830a8e1b5cc2f9ea3250c315be2f9d8b7faa09
+  metadata.gz: fa89ecbb2a09940666b57e690d43a985872bb85f40b2b1175c79a762d79c8e45
+  data.tar.gz: 2404fe5e1efa77899262fbf8979529fc474e44ffa0a8572ee3cf71eb1caf941a
 SHA512:
-  metadata.gz: f56db0a74a7a6559189039a9f7f13a1f514b4fc956f7993a52ca16a7a978b4b93aa352b9f74b72da73c7b0485ebe1f80052d2e3c7b04a1baba231d06ba594f42
-  data.tar.gz: 597260a0eb43c0fdc187aeb961521fbce22c68fc75b35d445e73d60564b72208aaf1e83a8428daa99423e001572f187872f4077445d6bced8b35d197d7e700ff
+  metadata.gz: 1a86224846b27985d641bf485f952583c73dafc87a0ca8f65744cfdfa35371a6f5cfedb4246e7839da6e51fdcfd53632f20057c399038f3399f2986a9bf20085
+  data.tar.gz: 24daff089a2b0564a2e7a93c34fef4d44420d1e0bbc6a054c5bcdfac02986c66204515bc085a7dc6499257692682217a888d8a04e04a7ae8de36e884cc182965

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Kenichi Kamiya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,225 @@
+# ruby-ulid
+
+A handy `ULID` library
+
+The `ULID` spec is defined on [ulid/spec](https://github.com/ulid/spec).
+This gem aims to provide the generator, monotonic generator, parser and handy manipulation features around the ULID.
+Also providing 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)
+[![Gem Version](https://badge.fury.io/rb/ruby-ulid.png)](http://badge.fury.io/rb/ruby-ulid)
+
+## 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
+- UUID v1/v2 is impractical in many environments, as it requires access to a unique, stable MAC address
+- UUID v3/v5 requires a unique seed and produces randomly distributed IDs, which can cause fragmentation in many data structures
+- UUID v4 provides no other information than randomness which can cause fragmentation in many data structures
+
+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)
+- Monotonic sort order (correctly detects and handles the same millisecond)
+
+## Install
+
+Require Ruby 2.6 or later
+
+```console
+$ gem install ruby-ulid
+#=> Installed
+```
+
+## Usage
+
+The generated `ULID` is an object not just a string.
+It means easily get the timestamps and binary formats.
+
+```ruby
+require 'ulid'
+
+ulid = ULID.generate #=> ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GRMJ9AA)
+ulid.to_time #=> 2021-04-27 17:27:22.826 UTC
+ulid.to_s #=> "01F4A5Y1YAQCYAYCTC7GRMJ9AA"
+ulid.octets #=> [1, 121, 20, 95, 7, 202, 187, 60, 175, 51, 76, 60, 49, 73, 37, 74]
+ulid.pattern #=> /(?<timestamp>01F4A5Y1YA)(?<randomness>QCYAYCTC7GRMJ9AA)/i
+```
+
+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
+```
+
+ULIDs are sortable when they are generated in different timestamp with milliseconds precision
+
+```ruby
+ulids = 1000.times.map do
+  sleep(0.001)
+  ULID.generate
+end
+ulids.sort == ulids #=> true
+ulids.uniq(&:to_time).size #=> 1000
+```
+
+`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 size is not fixed, might be changed in environment)
+ulids.sort == ulids #=> false
+```
+
+If you want to prefer `sortable` rather than the `randomness`, 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
+  monotonic_generator.generate
+end
+sample_ulids_by_the_time = monotonic_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
+monotonic_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)]
+
+monotonic_ulids.sort == monotonic_ulids #=> true
+```
+
+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
+# 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.
+
+```ruby
+json =<<'EOD'
+{
+  "id": "01F4GNAV5ZR6FJQ5SFQC7WDSY3",
+  "author": {
+    "id": "01F4GNBXW1AM2KWW52PVT3ZY9X",
+    "name": "kachick"
+  },
+  "title": "My awesome blog post",
+  "comments": [
+    {
+      "id": "01F4GNCNC3CH0BCRZBPPDEKBKS",
+      "commenter": {
+        "id": "01F4GNBXW1AM2KWW52PVT3ZY9X",
+        "name": "kachick"
+      }
+    },
+    {
+      "id": "01F4GNCXAMXQ1SGBH5XCR6ZH0M",
+      "commenter": {
+        "id": "01F4GND4RYYSKNAADHQ9BNXAWJ",
+        "name": "pankona"
+      }
+    }
+  ]
+}
+EOD
+
+ULID.scan(json).to_a
+#=>
+[ULID(2021-04-30 05:51:57.119 UTC: 01F4GNAV5ZR6FJQ5SFQC7WDSY3),
+ ULID(2021-04-30 05:52:32.641 UTC: 01F4GNBXW1AM2KWW52PVT3ZY9X),
+ ULID(2021-04-30 05:52:56.707 UTC: 01F4GNCNC3CH0BCRZBPPDEKBKS),
+ ULID(2021-04-30 05:52:32.641 UTC: 01F4GNBXW1AM2KWW52PVT3ZY9X),
+ ULID(2021-04-30 05:53:04.852 UTC: 01F4GNCXAMXQ1SGBH5XCR6ZH0M),
+ ULID(2021-04-30 05:53:12.478 UTC: 01F4GND4RYYSKNAADHQ9BNXAWJ)]
+```
+
+`ULID.min` and `ULID.max` return termination values for ULID spec.
+
+```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#next` and `ULID#succ` returns next(successor) ULID
+
+```ruby
+ULID.parse('01BX5ZZKBKZZZZZZZZZZZZZZZY').next.to_s #=> "01BX5ZZKBKZZZZZZZZZZZZZZZZ"
+ULID.parse('01BX5ZZKBKZZZZZZZZZZZZZZZZ').next.to_s #=> "01BX5ZZKBM0000000000000000"
+ULID.parse('7ZZZZZZZZZZZZZZZZZZZZZZZZZ').next #=> nil
+```
+
+`ULID#pred` returns predecessor ULID
+
+```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. (Of course the timestamp will be useless one. Sortable benefit is lost.)
+
+```ruby
+ULID.from_uuidv4('0983d0a2-ff15-4d83-8f37-7dd945b5aa39')
+#=> ULID(2301-07-10 00:28:28.821 UTC: 09GF8A5ZRN9P1RYDVXV52VBAHS)
+```
+
+## References
+
+- [Repository](https://github.com/kachick/ruby-ulid)
+- [API documents](https://kachick.github.io/ruby-ulid/)
+- [ulid/spec](https://github.com/ulid/spec)
+- [Another choices are UUIDv6, UUIDv7, UUIDv8. 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 implementation aims `strict`, It might be changed in [ulid/spec#57](https://github.com/ulid/spec/pull/57) and [ruby-ulid#57](https://github.com/kachick/ruby-ulid/issues/57).

data/Steepfile

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

data/lib/ulid.rb

@@ -4,7 +4,6 @@
 
 require 'securerandom'
 require 'integer/base'
-require_relative 'ulid/version'
 
 # @see https://github.com/ulid/spec
 # @!attribute [r] milliseconds
@@ -23,16 +22,16 @@ class ULID
   # @see https://www.crockford.com/base32.html
   ENCODING_CHARS = encoding_string.chars.map(&:freeze).freeze
 
-  TIME_PART_LENGTH = 10
+  TIMESTAMP_PART_LENGTH = 10
   RANDOMNESS_PART_LENGTH = 16
-  ENCODED_ID_LENGTH = TIME_PART_LENGTH + RANDOMNESS_PART_LENGTH
+  ENCODED_ID_LENGTH = TIMESTAMP_PART_LENGTH + RANDOMNESS_PART_LENGTH
   TIMESTAMP_OCTETS_LENGTH = 6
   RANDOMNESS_OCTETS_LENGTH = 10
   OCTETS_LENGTH = TIMESTAMP_OCTETS_LENGTH + RANDOMNESS_OCTETS_LENGTH
   MAX_MILLISECONDS = 281474976710655
   MAX_ENTROPY = 1208925819614629174706175
   MAX_INTEGER = 340282366920938463463374607431768211455
-  PATTERN = /(?<timestamp>[0-7][#{encoding_string}]{#{TIME_PART_LENGTH - 1}})(?<randomness>[#{encoding_string}]{#{RANDOMNESS_PART_LENGTH}})/i.freeze
+  PATTERN = /(?<timestamp>[0-7][#{encoding_string}]{#{TIMESTAMP_PART_LENGTH - 1}})(?<randomness>[#{encoding_string}]{#{RANDOMNESS_PART_LENGTH}})/i.freeze
   STRICT_PATTERN = /\A#{PATTERN.source}\z/i.freeze
 
   # Imported from https://stackoverflow.com/a/38191104/1212807, thank you!
@@ -42,55 +41,23 @@ class ULID
   # @see https://bugs.ruby-lang.org/issues/15958
   TIME_FORMAT_IN_INSPECT = '%Y-%m-%d %H:%M:%S.%3N %Z'
 
-  class MonotonicGenerator
-    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
-    # @return [ULID]
-    def generate
-      milliseconds = ULID.current_milliseconds
-      reasonable_entropy = ULID.reasonable_entropy
-
-      @latest_milliseconds ||= milliseconds
-      @latest_entropy ||= reasonable_entropy
-      if @latest_milliseconds != milliseconds
-        @latest_milliseconds = milliseconds
-        @latest_entropy = reasonable_entropy
-      else
-        @latest_entropy += 1
-      end
-
-      ULID.new milliseconds: milliseconds, entropy: @latest_entropy
-    end
-
-    # @return [self]
-    def reset
-      @latest_milliseconds = nil
-      @latest_entropy = nil
-      self
-    end
-
-    # @raise [TypeError] always raises exception and does not freeze self
-    # @return [void]
-    def freeze
-      raise TypeError, "cannot freeze #{self.class}"
-    end
+  # @param [Integer, Time] moment
+  # @param [Integer] entropy
+  # @return [ULID]
+  def self.generate(moment: current_milliseconds, entropy: reasonable_entropy)
+    new milliseconds: milliseconds_from_moment(moment), entropy: entropy
   end
 
-  MONOTONIC_GENERATOR = MonotonicGenerator.new
-
-  private_constant :ENCODING_CHARS, :TIME_FORMAT_IN_INSPECT, :UUIDV4_PATTERN
+  # @param [Integer, Time] moment
+  # @return [ULID]
+  def self.min(moment: 0)
+    generate(moment: moment, entropy: 0)
+  end
 
   # @param [Integer, Time] moment
-  # @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
+  def self.max(moment: MAX_MILLISECONDS)
+    generate(moment: moment, entropy: MAX_ENTROPY)
   end
 
   # @deprecated This method actually changes class state. Use {ULID::MonotonicGenerator} instead.
@@ -139,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
@@ -153,17 +121,66 @@ class ULID
     new milliseconds: milliseconds, entropy: entropy
   end
 
+  # @param [Range<Time>] time_range
+  # @return [Range<ULID>]
+  def self.range(time_range)
+    raise ArgumentError, 'ULID.range takes only Range[Time]' 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 ArgumentError, 'ULID.range takes only Range[Time]'
+    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 ArgumentError, 'ULID.range takes only Range[Time]'
+    end
+
+    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)
@@ -179,8 +196,8 @@ class ULID
       unless string.size == ENCODED_ID_LENGTH
         raise "parsable string must be #{ENCODED_ID_LENGTH} characters, but actually given #{string.size} characters"
       end
-      timestamp = string.slice(0, TIME_PART_LENGTH)
-      randomness = string.slice(TIME_PART_LENGTH, RANDOMNESS_PART_LENGTH)
+      timestamp = string.slice(0, TIMESTAMP_PART_LENGTH)
+      randomness = string.slice(TIMESTAMP_PART_LENGTH, RANDOMNESS_PART_LENGTH)
       milliseconds = Integer::Base.parse(timestamp, ENCODING_CHARS)
       entropy = Integer::Base.parse(randomness, ENCODING_CHARS)
     rescue => err
@@ -199,6 +216,7 @@ class ULID
     true
   end
 
+  # @api private
   # @param [Integer] integer
   # @param [Integer] length
   # @return [Array<Integer>]
@@ -210,6 +228,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]
@@ -224,6 +243,7 @@ class ULID
 
   attr_reader :milliseconds, :entropy
 
+  # @api private
   # @param [Integer] milliseconds
   # @param [Integer] entropy
   # @return [void]
@@ -241,10 +261,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
@@ -259,7 +278,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]
@@ -286,7 +305,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)]
@@ -324,20 +349,29 @@ 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 [self]
   def freeze
     # Evaluate all caching
     inspect
     octets
-    succ
     to_i
+    succ
+    pred
     strict_pattern
     super
   end
@@ -346,6 +380,15 @@ class ULID
 
   # @return [MatchData]
   def matchdata
-    @matchdata ||= STRICT_PATTERN.match(to_str).freeze
+    @matchdata ||= STRICT_PATTERN.match(to_s).freeze
   end
 end
+
+require_relative 'ulid/version'
+require_relative 'ulid/monotonic_generator'
+
+class ULID
+  MONOTONIC_GENERATOR = MonotonicGenerator.new
+
+  private_constant :ENCODING_CHARS, :TIME_FORMAT_IN_INSPECT, :UUIDV4_PATTERN
+end

data/lib/ulid/monotonic_generator.rb

@@ -0,0 +1,46 @@
+# coding: us-ascii
+# frozen_string_literal: true
+# Copyright (C) 2021 Kenichi Kamiya
+
+class ULID
+  class MonotonicGenerator
+    # @api private
+    attr_accessor :latest_milliseconds, :latest_entropy
+
+    def initialize
+      reset
+    end
+
+    # @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
+    def generate(moment: ULID.current_milliseconds)
+      milliseconds = ULID.milliseconds_from_moment(moment)
+      raise ArgumentError, "milliseconds should not be negative: given: #{milliseconds}" if milliseconds.negative?
+
+      if @latest_milliseconds < milliseconds
+        @latest_milliseconds = milliseconds
+        @latest_entropy = ULID.reasonable_entropy
+      else
+        @latest_entropy += 1
+      end
+
+      ULID.new milliseconds: @latest_milliseconds, entropy: @latest_entropy
+    end
+
+    # @api private
+    # @return [void]
+    def reset
+      @latest_milliseconds = 0
+      @latest_entropy = ULID.reasonable_entropy
+      nil
+    end
+
+    # @raise [TypeError] always raises exception and does not freeze self
+    # @return [void]
+    def freeze
+      raise TypeError, "cannot freeze #{self.class}"
+    end
+  end
+end

data/lib/ulid/version.rb

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

data/sig/ulid.rbs

@@ -2,7 +2,7 @@
 class ULID
   VERSION: String
   ENCODING_CHARS: Array[String]
-  TIME_PART_LENGTH: 10
+  TIMESTAMP_PART_LENGTH: 10
   RANDOMNESS_PART_LENGTH: 16
   ENCODED_ID_LENGTH: 26
   TIMESTAMP_OCTETS_LENGTH: 6
@@ -18,6 +18,8 @@ class ULID
   MONOTONIC_GENERATOR: MonotonicGenerator
   include Comparable
 
+  type moment = Time | Integer
+
   class Error < StandardError
   end
 
@@ -28,10 +30,10 @@ 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
@@ -56,14 +58,19 @@ class ULID
   @strict_pattern: Regexp?
   @matchdata: MatchData?
 
-  def self.generate: (?moment: Time | Integer, ?entropy: Integer) -> ULID
+  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] 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
   def self.from_integer: (Integer integer) -> ULID
+  def self.min: (?moment: moment) -> ULID
+  def self.max: (?moment: moment) -> ULID
   def self.valid?: (untyped string) -> bool
   def self.scan:  (String string) -> Enumerator[ULID, singleton(ULID)]
                 | (String string) { (ULID ulid) -> void } -> singleton(ULID)
@@ -72,8 +79,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
@@ -90,8 +96,9 @@ class ULID
   def octets: -> octets
   def timestamp_octets: -> timestamp_octets
   def randomness_octets: -> randomness_octets
-  def next: -> ULID
+  def next: -> ULID?
   alias succ next
+  def pred: -> ULID?
   def freeze: -> self
 
   private

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-ulid
 version: !ruby/object:Gem::Version
-  version: 0.0.9
+  version: 0.0.14
 platform: ruby
 authors:
 - Kenichi Kamiya
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-04-30 00:00:00.000000000 Z
+date: 2021-05-03 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,18 +84,21 @@ 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: []
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
+- README.md
+- Steepfile
 - lib/ulid.rb
+- lib/ulid/monotonic_generator.rb
 - lib/ulid/version.rb
 - sig/ulid.rbs
 homepage: https://github.com/kachick/ruby-ulid
@@ -99,14 +116,14 @@ 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:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.15
+rubygems_version: 3.1.4
 signing_key:
 specification_version: 4
 summary: A handy ULID library