ruby-ulid 0.0.8 → 0.0.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a1179379859a437f04ff904c941372fffc4aa3027d550ae50c67f744e4899d9a
-  data.tar.gz: 71781ee8481373bb7229f10f88a1703b2653c11a4f18cbc7b50eb4adbec58908
+  metadata.gz: 9e2d0489b211160618fc0ae6ecd30cbbbbaa411683162def97930ca95a860696
+  data.tar.gz: 0063c982795d2a42e2f6bac7b236d831753c685b36f4d047e2999dbe7368c6de
 SHA512:
-  metadata.gz: 6d48e489221851290a486ffe3a39847196e900bb54751fa7d0c808f7580c8838d1a6382b203da1b90ad4f74dd9e998239e0a6c996b06d99881c39489ff607697
-  data.tar.gz: fbef689db966901800b24e18820ee6744aeeaeb2476f14349b74d634ed1e5d359a4bff4abb3eb0eee94e4d0183f5db1420719d7e94afd3e803d21d62510087d7
+  metadata.gz: 825dab6b7e01f4e1dee5fcd03031ef27645de6a1b56e8392fd784a55c860268af5b84ae4ac3697cdf3eba630dbae197da28cde4b8fbef043c8d0ff48b587f992
+  data.tar.gz: f2039e401c77cf15bda81d10587085b7fa167c253a19a66bc0b14ee5fda71162325b7a278f2ebb185d53cbb3fd01563ccb4c6875ffbaebf7fc676a2a24c73767

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
@@ -18,72 +17,47 @@ class ULID
   class OverflowError < Error; end
   class ParserError < Error; end
 
+  encoding_string = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'
   # Crockford's Base32. Excluded I, L, O, U.
   # @see https://www.crockford.com/base32.html
-  ENCODING_CHARS = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'.chars.map(&:freeze).freeze
+  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
-  TIME_OCTETS_LENGTH = 6
+  ENCODED_ID_LENGTH = TIMESTAMP_PART_LENGTH + RANDOMNESS_PART_LENGTH
+  TIMESTAMP_OCTETS_LENGTH = 6
   RANDOMNESS_OCTETS_LENGTH = 10
-  OCTETS_LENGTH = TIME_OCTETS_LENGTH + RANDOMNESS_OCTETS_LENGTH
+  OCTETS_LENGTH = TIMESTAMP_OCTETS_LENGTH + RANDOMNESS_OCTETS_LENGTH
   MAX_MILLISECONDS = 281474976710655
   MAX_ENTROPY = 1208925819614629174706175
+  MAX_INTEGER = 340282366920938463463374607431768211455
+  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!
+  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
 
   # Same as Time#inspect since Ruby 2.7, just to keep backward compatibility
   # @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
+  # @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.
@@ -100,17 +74,113 @@ class ULID
     MONOTONIC_GENERATOR.generate
   end
 
+  # @param [String, #to_str] string
+  # @return [Enumerator]
+  # @yieldparam [ULID] ulid
+  # @yieldreturn [self]
+  def self.scan(string)
+    string = string.to_str
+    return to_enum(__callee__, string) unless block_given?
+    string.scan(PATTERN) do |pair|
+      yield parse(pair.join)
+    end
+    self
+  end
+
+  # @param [String, #to_str] uuid
+  # @return [ULID]
+  # @raise [ParserError] if the given format is not correct for UUIDv4 specs
+  def self.from_uuidv4(uuid)
+    begin
+      uuid = uuid.to_str
+      prefix_trimmed = uuid.sub(/\Aurn:uuid:/, '')
+      raise "given string is not matched to pattern #{UUIDV4_PATTERN.inspect}" unless UUIDV4_PATTERN.match?(prefix_trimmed)
+      normalized = prefix_trimmed.gsub(/[^0-9A-Fa-f]/, '')
+      from_integer(normalized.to_i(16))
+    rescue => err
+      raise ParserError, "parsing failure as #{err.inspect} for given #{uuid}"
+    end
+  end
+
+  # @param [Integer, #to_int] integer
+  # @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
+    raise ArgumentError, "integer should not be negative: given: #{integer}" if integer.negative?
+
+    octets = octets_from_integer(integer, length: OCTETS_LENGTH).freeze
+    time_octets = octets.slice(0, TIMESTAMP_OCTETS_LENGTH).freeze
+    randomness_octets = octets.slice(TIMESTAMP_OCTETS_LENGTH, RANDOMNESS_OCTETS_LENGTH).freeze
+    milliseconds = inverse_of_digits(time_octets)
+    entropy = inverse_of_digits(randomness_octets)
+
+    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)
@@ -126,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
@@ -146,8 +216,34 @@ class ULID
     true
   end
 
+  # @api private
+  # @param [Integer] integer
+  # @param [Integer] length
+  # @return [Array<Integer>]
+  def self.octets_from_integer(integer, length:)
+    digits = integer.digits(256)
+    (length - digits.size).times do
+      digits.push 0
+    end
+    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]
+  def self.inverse_of_digits(reversed_digits)
+    base = 256
+    num = 0
+    reversed_digits.each do |digit|
+      num = (num * base) + digit
+    end
+    num
+  end
+
   attr_reader :milliseconds, :entropy
 
+  # @api private
   # @param [Integer] milliseconds
   # @param [Integer] entropy
   # @return [void]
@@ -172,7 +268,7 @@ class ULID
 
   # @return [Integer]
   def to_i
-    @integer ||= inverse_of_digits(octets)
+    @integer ||= self.class.inverse_of_digits(octets)
   end
   alias_method :hash, :to_i
 
@@ -210,63 +306,90 @@ class ULID
 
   # @return [Time]
   def to_time
-    @time ||= Time.at(0, @milliseconds, :millisecond).utc
+    @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)]
   def octets
-    @octets ||= (time_octets + randomness_octets).freeze
+    @octets ||= (timestamp_octets + randomness_octets).freeze
   end
 
   # @return [Array(Integer, Integer, Integer, Integer, Integer, Integer)]
-  def time_octets
-    @time_octets ||= octets_from_integer(@milliseconds, length: TIME_OCTETS_LENGTH).freeze
+  def timestamp_octets
+    @timestamp_octets ||= self.class.octets_from_integer(@milliseconds, length: TIMESTAMP_OCTETS_LENGTH).freeze
   end
 
   # @return [Array(Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer)]
   def randomness_octets
-    @randomness_octets ||= octets_from_integer(@entropy, length: RANDOMNESS_OCTETS_LENGTH).freeze
+    @randomness_octets ||= self.class.octets_from_integer(@entropy, length: RANDOMNESS_OCTETS_LENGTH).freeze
   end
 
-  # @raise [OverflowError] if the next entropy part is larger than the ULID limit
-  # @return [ULID]
+  # @return [String]
+  def timestamp
+    @timestamp ||= matchdata[:timestamp].freeze
+  end
+
+  # @return [String]
+  def randomness
+    @randomness ||= matchdata[:randomness].freeze
+  end
+
+  # @return [Regexp]
+  def pattern
+    @pattern ||= /(?<timestamp>#{timestamp})(?<randomness>#{randomness})/i.freeze
+  end
+
+  # @return [Regexp]
+  def strict_pattern
+    @strict_pattern ||= /\A#{pattern.source}\z/i.freeze
+  end
+
+  # @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
 
   private
 
-  # @param [Integer] integer
-  # @param [Integer] length
-  # @return [Array<Integer>]
-  def octets_from_integer(integer, length:)
-    digits = integer.digits(256)
-    (length - digits.size).times do
-      digits.push 0
-    end
-    digits.reverse!
+  # @return [MatchData]
+  def matchdata
+    @matchdata ||= STRICT_PATTERN.match(to_str).freeze
   end
+end
 
-  # @see The logics taken from https://bugs.ruby-lang.org/issues/14401, thanks!
-  # @param [Array<Integer>] reversed_digits
-  # @return [Integer]
-  def inverse_of_digits(reversed_digits)
-    base = 256
-    num = 0
-    reversed_digits.each do |digit|
-      num = (num * base) + digit
-    end
-    num
-  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.8'
+  VERSION = '0.0.13'
 end

data/sig/ulid.rbs

@@ -2,18 +2,24 @@
 class ULID
   VERSION: String
   ENCODING_CHARS: Array[String]
-  TIME_PART_LENGTH: 10
+  TIMESTAMP_PART_LENGTH: 10
   RANDOMNESS_PART_LENGTH: 16
   ENCODED_ID_LENGTH: 26
-  TIME_OCTETS_LENGTH: 6
+  TIMESTAMP_OCTETS_LENGTH: 6
   RANDOMNESS_OCTETS_LENGTH: 10
   OCTETS_LENGTH: 16
   MAX_MILLISECONDS: 281474976710655
   MAX_ENTROPY: 1208925819614629174706175
+  MAX_INTEGER: 340282366920938463463374607431768211455
   TIME_FORMAT_IN_INSPECT: '%Y-%m-%d %H:%M:%S.%3N %Z'
+  PATTERN: Regexp
+  STRICT_PATTERN: Regexp
+  UUIDV4_PATTERN: Regexp
   MONOTONIC_GENERATOR: MonotonicGenerator
   include Comparable
 
+  type moment = Time | Integer
+
   class Error < StandardError
   end
 
@@ -24,34 +30,52 @@ 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 octets = [Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer]
-  type time_octets = [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]
 
-  @string: String
-  @integer: Integer
-  @octets: octets
-  @time_octets: time_octets
-  @randomness_octets: randomness_octets
-  @inspect: String
-  @time: Time
-  @next: ULID
+  @milliseconds: Integer
+  @entropy: Integer
+  @string: String?
+  @integer: Integer?
+  @octets: octets?
+  @timestamp_octets: timestamp_octets?
+  @randomness_octets: randomness_octets?
+  @timestamp: String?
+  @randomness: String?
+  @inspect: String?
+  @time: Time?
+  @next: ULID?
+  @pattern: Regexp?
+  @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)
+  def self.octets_from_integer: (Integer integer, length: Integer) -> Array[Integer]
+  def self.inverse_of_digits: (Array[Integer] reversed_digits) -> Integer
   attr_reader milliseconds: Integer
   attr_reader entropy: Integer
   def initialize: (milliseconds: Integer, entropy: Integer) -> void
@@ -66,14 +90,18 @@ class ULID
   alias == eql?
   def ===: (untyped other) -> bool
   def to_time: -> Time
+  def timestamp: -> String
+  def randomness: -> String
+  def pattern: -> Regexp
+  def strict_pattern: -> Regexp
   def octets: -> octets
-  def time_octets: -> time_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
-  def octets_from_integer: (Integer integer, length: Integer) -> Array[Integer]
-  def inverse_of_digits: (Array[Integer] reversed_digits) -> Integer
+  def matchdata: -> MatchData
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-ulid
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 0.0.13
 platform: ruby
 authors:
 - Kenichi Kamiya
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-04-29 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