ruby-ulid 0.0.17 → 0.1.2

data/lib/ulid/crockford_base32.rb

@@ -0,0 +1,70 @@
+# coding: us-ascii
+# frozen_string_literal: true
+# Copyright (C) 2021 Kenichi Kamiya
+
+class ULID
+  # Currently supporting only for `subset` for actual use-case`
+  # Original decoding spec allows other characters.
+  # But I think ULID should allow `subset` of Crockford's Base32.
+  # See below
+  #   * https://github.com/ulid/spec/pull/57
+  #   * https://github.com/kachick/ruby-ulid/issues/57
+  #   * https://github.com/kachick/ruby-ulid/issues/78
+  module CrockfordBase32
+    class SetupError < ScriptError; end
+
+    n32_chars = [*'0'..'9', *'A'..'V'].map(&:freeze).freeze
+    raise SetupError, 'obvious bug exists in the mapping algorithm' unless n32_chars.size == 32
+
+    n32_char_by_number = {}
+    n32_chars.each_with_index do |char, index|
+      n32_char_by_number[index] = char
+    end
+    n32_char_by_number.freeze
+
+    crockford_base32_mappings = {
+      'J' => 18,
+      'K' => 19,
+      'M' => 20,
+      'N' => 21,
+      'P' => 22,
+      'Q' => 23,
+      'R' => 24,
+      'S' => 25,
+      'T' => 26,
+      'V' => 27,
+      'W' => 28,
+      'X' => 29,
+      'Y' => 30,
+      'Z' => 31
+    }.freeze
+
+    N32_CHAR_BY_CROCKFORD_BASE32_CHAR = CROCKFORD_BASE32_ENCODING_STRING.chars.map(&:freeze).each_with_object({}) do |encoding_char, map|
+      if n = crockford_base32_mappings[encoding_char]
+        char_32 = n32_char_by_number.fetch(n)
+        map[encoding_char] = char_32
+      end
+    end.freeze
+    raise SetupError, 'obvious bug exists in the mapping algorithm' unless N32_CHAR_BY_CROCKFORD_BASE32_CHAR.keys == crockford_base32_mappings.keys
+    CROCKFORD_BASE32_CHAR_PATTERN = /[#{N32_CHAR_BY_CROCKFORD_BASE32_CHAR.keys.join}]/.freeze
+
+    CROCKFORD_BASE32_CHAR_BY_N32_CHAR = N32_CHAR_BY_CROCKFORD_BASE32_CHAR.invert.freeze
+    N32_CHAR_PATTERN = /[#{CROCKFORD_BASE32_CHAR_BY_N32_CHAR.keys.join}]/.freeze
+
+    # @api private
+    # @param [String] string
+    # @return [Integer]
+    def self.decode(string)
+      n32encoded = string.upcase.gsub(CROCKFORD_BASE32_CHAR_PATTERN, N32_CHAR_BY_CROCKFORD_BASE32_CHAR)
+      n32encoded.to_i(32)
+    end
+
+    # @api private
+    # @param [Integer] integer
+    # @return [String]
+    def self.encode(integer)
+      n32encoded = integer.to_s(32)
+      n32encoded.upcase.gsub(N32_CHAR_PATTERN, CROCKFORD_BASE32_CHAR_BY_N32_CHAR).rjust(ENCODED_LENGTH, '0')
+    end
+  end
+end

data/lib/ulid/monotonic_generator.rb

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

data/lib/ulid/uuid.rb

@@ -0,0 +1,38 @@
+# coding: us-ascii
+# frozen_string_literal: true
+# Copyright (C) 2021 Kenichi Kamiya
+
+# Extracted features around UUID from some reasons
+# ref:
+#  * https://github.com/kachick/ruby-ulid/issues/105
+#  * https://github.com/kachick/ruby-ulid/issues/76
+class ULID
+  # 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.freeze
+  private_constant :UUIDV4_PATTERN
+
+  # @param [String, #to_str] uuid
+  # @return [ULID]
+  # @raise [ParserError] if the given format is not correct for UUIDv4 specs
+  def self.from_uuidv4(uuid)
+    uuid = String.try_convert(uuid)
+    raise ArgumentError, 'ULID.from_uuidv4 takes only strings' unless uuid
+
+    prefix_trimmed = uuid.delete_prefix('urn:uuid:')
+    unless UUIDV4_PATTERN.match?(prefix_trimmed)
+      raise ParserError, "given `#{uuid}` does not match to `#{UUIDV4_PATTERN.inspect}`"
+    end
+
+    normalized = prefix_trimmed.gsub(/[^0-9A-Fa-f]/, '')
+    from_integer(normalized.to_i(16))
+  end
+
+  # @return [String]
+  def to_uuidv4
+    # 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

data/lib/ulid/version.rb

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

data/sig/ulid.rbs

@@ -1,10 +1,9 @@
-# Classes
-class ULID
+class ULID < Object
   VERSION: String
-  ENCODING_CHARS: Array[String]
-  TIMESTAMP_PART_LENGTH: 10
-  RANDOMNESS_PART_LENGTH: 16
-  ENCODED_ID_LENGTH: 26
+  CROCKFORD_BASE32_ENCODING_STRING: String
+  TIMESTAMP_ENCODED_LENGTH: 10
+  RANDOMNESS_ENCODED_LENGTH: 16
+  ENCODED_LENGTH: 26
   TIMESTAMP_OCTETS_LENGTH: 6
   RANDOMNESS_OCTETS_LENGTH: 10
   OCTETS_LENGTH: 16
@@ -12,16 +11,13 @@ class ULID
   MAX_ENTROPY: 1208925819614629174706175
   MAX_INTEGER: 340282366920938463463374607431768211455
   TIME_FORMAT_IN_INSPECT: '%Y-%m-%d %H:%M:%S.%3N %Z'
-  PATTERN: Regexp
-  STRICT_PATTERN: Regexp
+  RANDOM_INTEGER_GENERATOR: ^() -> Integer
+  PATTERN_WITH_CROCKFORD_BASE32_SUBSET: Regexp
+  STRICT_PATTERN_WITH_CROCKFORD_BASE32_SUBSET: Regexp
+  SCANNING_PATTERN: Regexp
   UUIDV4_PATTERN: Regexp
-  N32_CHAR_BY_CROCKFORD_BASE32_CHAR: Hash[String, String]
-  CROCKFORD_BASE32_CHAR_PATTERN: Regexp
-  CROCKFORD_BASE32_CHAR_BY_N32_CHAR: Hash[String, String]
-  N32_CHAR_PATTERN: Regexp
   MIN: ULID
   MAX: ULID
-  UNDEFINED: BasicObject
   include Comparable
 
   # The `moment` is a `Time` or `Intger of the milliseconds`
@@ -36,88 +32,458 @@ class ULID
   class ParserError < Error
   end
 
-  class SetupError < ScriptError
+  class UnexpectedError < Error
+  end
+
+  module CrockfordBase32
+    class SetupError < ScriptError
+    end
+
+    N32_CHAR_BY_CROCKFORD_BASE32_CHAR: Hash[String, String]
+    CROCKFORD_BASE32_CHAR_PATTERN: Regexp
+    CROCKFORD_BASE32_CHAR_BY_N32_CHAR: Hash[String, String]
+    N32_CHAR_PATTERN: Regexp
+
+    # A pribate API. Should not be used in your code.
+    def self.encode: (Integer integer) -> String
+
+    # A pribate API. Should not be used in your code.
+    def self.decode: (String string) -> Integer
   end
 
   class MonotonicGenerator
-    attr_accessor latest_milliseconds: Integer
-    attr_accessor latest_entropy: Integer
+    @mutex: Thread::Mutex
+    attr_reader prev: ULID | nil
+
+    # A pribate API. Should not be used in your code.
     def initialize: -> void
+
+    # See [How to keep `Sortable` even if in same timestamp](https://github.com/kachick/ruby-ulid#how-to-keep-sortable-even-if-in-same-timestamp)
     def generate: (?moment: moment) -> ULID
-    def reset: -> void
+    def inspect: -> String
+    alias to_s inspect
     def freeze: -> void
   end
 
+  interface _ToULID
+    def to_ulid: () -> ULID
+  end
+
   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]
+  type period = Range[Time] | Range[nil] | Range[ULID]
 
-  @milliseconds: Integer
-  @entropy: Integer
   @string: String?
-  @integer: Integer?
-  @octets: octets?
-  @timestamp_octets: timestamp_octets?
-  @randomness_octets: randomness_octets?
+  @integer: Integer
   @timestamp: String?
   @randomness: String?
   @inspect: String?
   @time: Time?
-  @next: ULID?
-  @pattern: Regexp?
-  @strict_pattern: Regexp?
-  @uuidv4: String?
-  @matchdata: MatchData?
 
-  def self.generate: (?moment: moment, ?entropy: Integer) -> ULID
+  # Retuns a ULID
+  #
+  # They are sortable when generated in different timestamp with milliseconds precision
+  #
+  # ```ruby
+  # ulids = 1000.times.map do
+  #   sleep(0.001)
+  #   ULID.generate
+  # end
+  # ulids.uniq(&:to_time).size #=> 1000
+  # ulids.sort == ulids #=> true
+  # ```
+  #
+  # `ULID.generate` can take fixed `Time` instance.
+  #  See also the short hand [ULID.at](https://kachick.github.io/ruby-ulid/ULID.html#at-class_method)
+  #
+  # ```ruby
+  # time = Time.at(946684800).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)
+  # ```
+  #
+  # 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 keep sortable even if in same timestamp, See also [ULID::MonotonicGenerator](https://github.com/kachick/ruby-ulid#how-to-keep-sortable-even-if-in-same-timestamp)
+  #
+  def self.generate: (?moment: moment, ?entropy: Integer) -> self
+
+  # Shorthand of `ULID.generate(moment: Time)`
+  # See also [ULID.generate](https://kachick.github.io/ruby-ulid/ULID.html#generate-class_method)
+  #
+  # ```ruby
+  # time = Time.at(946684800).utc #=> 2000-01-01 00:00:00 UTC
+  # ULID.at(time) #=> ULID(2000-01-01 00:00:00.000 UTC: 00VHNCZB002W5BGWWKN76N22H6)
+  #
+  # ulids = 1000.times.map do |n|
+  #   ULID.at(time + n)
+  # end
+  # ulids.sort == ulids #=> true
+  # ```
+  def self.at: (Time time) -> self
+
+  # A pribate API. Should not be used in your code.
   def self.current_milliseconds: -> Integer
-  def self.milliseconds_from_time: (Time time) -> Integer
+
+  # A pribate API. Should not be used in your code.
   def self.milliseconds_from_moment: (moment moment) -> Integer
-  def self.range: (Range[Time] | Range[nil] time_range) -> Range[ULID]
+
+  # `ULID` can be element of the `Range`. If you generated the IDs in monotonic generator, ID based filtering is easy and reliable
+  #
+  # ```ruby
+  # include_end = ulid1..ulid2
+  # exclude_end = ulid1...ulid2
+  #
+  # ulids.grep(one_of_the_above)
+  # ulids.grep_v(one_of_the_above)
+  # ```
+  #
+  # When want to filter ULIDs with `Time`, we should consider to handle the precision.
+  # So this gem provides `ULID.range` to generate reasonable `Range[ULID]` from `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
+  #
+  # # 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(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
+  #
+  # # So you can use the generated range objects as below
+  # ulids.grep(one_of_the_above)
+  # ulids.grep_v(one_of_the_above)
+  # #=> I hope the results should be actually you want!
+  # ```
+  #
+  def self.range: (period period) -> Range[ULID]
+
+  # Returns new `Time` with truncating excess precisions in ULID spec.
+  #
+  # ```ruby
+  # time = Time.at(946684800, Rational('123456.789')).utc
+  # #=> 2000-01-01 00:00:00.123456789 UTC
+  # ULID.floor(time) #=> 2000-01-01 00:00:00.123 UTC
+  # ```
   def self.floor: (Time time) -> Time
-  def self.reasonable_entropy: -> Integer
-  def self.parse: (String string) -> ULID
+
+  # Get ULID instance from encoded String.
+  #
+  # ```ruby
+  # ulid = ULID.parse('01ARZ3NDEKTSV4RRFFQ69G5FAV')
+  # #=> ULID(2016-07-30 23:54:10.259 UTC: 01ARZ3NDEKTSV4RRFFQ69G5FAV)
+  # ```
+  def self.parse: (_ToStr string) -> self
+
+  # ```ruby
+  # # Currently experimental feature, so needed to load the extension.
+  # require 'ulid/uuid'
+  #
+  # # 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"
+  # ```
+  #
+  # See also [Why this is experimental?](https://github.com/kachick/ruby-ulid/issues/76)
   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.sample: -> ULID
-                 | (Integer number) -> Array[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
+  def self.from_integer: (Integer integer) -> self
+
+  # Returns termination values for ULID spec.
+  #
+  # ```ruby
+  # ULID.min
+  # #=> ULID(1970-01-01 00:00:00.000 UTC: 00000000000000000000000000)
+  # ```
+  #
+  # It can take `Time` instance as an optional argument.
+  # Then returns ULID that has minimum value of randomness part in the timestamp.
+  #
+  # ```ruby
+  # time = Time.at(946684800, Rational('123456.789')).utc
+  # #=> 2000-01-01 00:00:00.123456789 UTC
+  # ULID.min(time)
+  # #=> ULID(2000-01-01 00:00:00.123 UTC: 00VHNCZB3V0000000000000000)
+  # ```
+  #
+  # See also [ULID.max](https://kachick.github.io/ruby-ulid/ULID.html#max-class_method)
+  def self.min: (?moment moment) -> ULID
+
+  # Returns termination values for ULID spec.
+  #
+  # ```ruby
+  # ULID.max
+  # #=> ULID(10889-08-02 05:31:50.655 UTC: 7ZZZZZZZZZZZZZZZZZZZZZZZZZ)
+  # ```
+  #
+  # It can take `Time` instance as an optional argument.
+  # Then returns ULID that has maximum value of randomness part in the timestamp.
+  #
+  # ```ruby
+  # time = Time.at(946684800, Rational('123456.789')).utc
+  # #=> 2000-01-01 00:00:00.123456789 UTC
+  # ULID.max(time)
+  # #=> ULID(2000-01-01 00:00:00.123 UTC: 00VHNCZB3VZZZZZZZZZZZZZZZZ)
+  # ```
+  #
+  # See also [ULID.min](https://kachick.github.io/ruby-ulid/ULID.html#min-class_method)
+  def self.max: (?moment moment) -> ULID
+
+  # Returns random ULIDs.
+  #
+  # Basically ignores generating time.
+  #
+  # ```ruby
+  # ULID.sample #=> ULID(2545-07-26 06:51:20.085 UTC: 0GGKQ45GMNMZR6N8A8GFG0ZXST)
+  # ULID.sample #=> ULID(5098-07-26 21:31:06.946 UTC: 2SSBNGGYA272J7BMDCG4Z6EEM5)
+  # ULID.sample(0) #=> []
+  # ULID.sample(1) #=> [ULID(2241-04-16 03:31:18.440 UTC: 07S52YWZ98AZ8T565MD9VRYMQH)]
+  # ULID.sample(5)
+  # #=>
+  # #[ULID(5701-04-29 12:41:19.647 UTC: 3B2YH2DV0ZYDDATGTYSKMM1CMT),
+  # # ULID(2816-08-01 01:21:46.612 UTC: 0R9GT6RZKMK3RG02Q2HAFVKEY2),
+  # # ULID(10408-10-05 17:06:27.848 UTC: 7J6CPTEEC86Y24EQ4F1Y93YYN0),
+  # # ULID(2741-09-02 16:24:18.803 UTC: 0P4Q4V34KKAJW46QW47WQB5463),
+  # # ULID(2665-03-16 14:50:22.724 UTC: 0KYFW9DWM4CEGFNTAC6YFAVVJ6)]
+  # ```
+  #
+  # You can specify a range object for the timestamp restriction, See also [ULID.range](https://kachick.github.io/ruby-ulid/ULID.html#range-class_method).
+  #
+  # ```ruby
+  # ulid1 = ULID.parse('01F4A5Y1YAQCYAYCTC7GRMJ9AA') #=> ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GRMJ9AA)
+  # ulid2 = ULID.parse('01F4PTVCSN9ZPFKYTY2DDJVRK4') #=> ULID(2021-05-02 15:23:48.917 UTC: 01F4PTVCSN9ZPFKYTY2DDJVRK4)
+  # ulids = ULID.sample(1000, period: ulid1..ulid2)
+  # ulids.uniq.size #=> 1000
+  # ulids.take(10)
+  # #=>
+  # #[ULID(2021-05-02 06:57:19.954 UTC: 01F4NXW02JNB8H0J0TK48JD39X),
+  # # ULID(2021-05-02 07:06:07.458 UTC: 01F4NYC372GVP7NS0YAYQGT4VZ),
+  # # ULID(2021-05-01 06:16:35.791 UTC: 01F4K94P6F6P68K0H64WRDSFKW),
+  # # ULID(2021-04-27 22:17:37.844 UTC: 01F4APHGSMFJZQTGXKZBFFBPJP),
+  # # ULID(2021-04-28 20:17:55.357 UTC: 01F4D231MXQJXAR8G2JZHEJNH3),
+  # # ULID(2021-04-30 07:18:54.307 UTC: 01F4GTA2332AS2VPHC4FMKC7R5),
+  # # ULID(2021-05-02 12:26:03.480 UTC: 01F4PGNXARG554Y3HYVBDW4T9S),
+  # # ULID(2021-04-29 09:52:15.107 UTC: 01F4EGP483ZX2747FQPWQNPPMW),
+  # # 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),
+  # #  ULID(2021-05-01 03:06:09.130 UTC: 01F4JY7ZBABCBMX16XH2Q4JW4W),
+  # #  ULID(2021-04-29 21:38:58.109 UTC: 01F4FS45DX4049JEQK4W6TER6G),
+  # #  ULID(2021-04-29 17:14:14.116 UTC: 01F4F9ZDQ449BE8BBZFEHYQWG2),
+  # #  ULID(2021-04-30 16:18:08.205 UTC: 01F4HS5DPD1HWDVJNJ6YKJXKSK),
+  # #  ULID(2021-04-30 10:31:33.602 UTC: 01F4H5ATF2A1CSQF0XV5NKZ288),
+  # #  ULID(2021-04-28 16:49:06.484 UTC: 01F4CP4PDM214Q6H3KJP7DYJRR),
+  # #  ULID(2021-04-28 15:05:06.808 UTC: 01F4CG68ZRST94T056KRZ5K9S4)]
+  # ```
+  def self.sample: (?period: period) -> self
+                 | (Integer number, ?period: period) -> Array[self]
+  def self.valid?: (untyped) -> bool
+
+  # Returns parsed ULIDs from given String for rough operations.
+  #
+  # ```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)]
+  # ```
+  def self.scan:  (_ToStr string) -> Enumerator[self, singleton(ULID)]
+                | (_ToStr string) { (self ulid) -> void } -> singleton(ULID)
+  def self.from_milliseconds_and_entropy: (milliseconds: Integer, entropy: Integer) -> self
+  def self.try_convert: (_ToULID) -> ULID
+                      | (untyped) -> nil
+
+  # ```ruby
+  # ulid = ULID.generate
+  # #=> ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GRMJ9AA)
+  # ulid.milliseconds #=> 1619544442826
+  # ```
   attr_reader milliseconds: Integer
   attr_reader entropy: Integer
-  def initialize: (milliseconds: Integer, entropy: Integer) -> void
+
+  # ```ruby
+  # ulid = ULID.generate
+  # #=> ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GRMJ9AA)
+  # ulid.to_s #=> "01F4A5Y1YAQCYAYCTC7GRMJ9AA"
+  # ```
   def to_s: -> String
+
+  # ```ruby
+  # ulid = ULID.generate
+  # #=> ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GRMJ9AA)
+  # ulid.to_i #=> 1957909092946624190749577070267409738
+  # ```
   def to_i: -> Integer
   alias hash to_i
+
+  # Basically same as String based sort.
+  #
+  # ```ruby
+  # ulids = ULID.sample(10000); nil
+  # ulids.map(&:to_s).sort == ulids.sort.map(&:to_s)
+  # #=> true
+  # ```
+  #
+  # To be precise, this sorting unaffected with `case sensitive or not` and might handle [ulid/spec#57](https://github.com/ulid/spec/pull/57) in future. So preferable than `lexicographically sortable` in actual case.
+  #
   def <=>: (ULID other) -> Integer
-         | (untyped other) -> Integer?
+         | (untyped other) -> nil
+
+  # ```ruby
+  # ulid = ULID.generate
+  # ulid.inspect #=> "ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GRMJ9AA)"
+  # ```
   def inspect: -> String
+
+  # ```ruby
+  # ULID.parse('4NNB20D9C1ME2NGMTX51ERZJX0') == ULID.parse('4nnb20d9c1me2ngmtx51erzjx0')
+  # #=> true
+  # ```
   def eql?: (untyped other) -> bool
   alias == eql?
   def ===: (untyped other) -> bool
+
+  # ```ruby
+  # ulid = ULID.generate
+  # #=> ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GRMJ9AA)
+  # ulid.to_time #=> 2021-04-27 17:27:22.826 UTC
+  # ```
   def to_time: -> Time
+
+  # ```ruby
+  # ulid = ULID.generate
+  # #=> ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GRMJ9AA)
+  # ulid.timestamp #=> "01F4A5Y1YA"
+  # ```
   def timestamp: -> String
+
+  # ```ruby
+  # ulid = ULID.generate
+  # #=> ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GRMJ9AA)
+  # ulid.randomness #=> "QCYAYCTC7GRMJ9AA"
+  # ```
   def randomness: -> String
-  def pattern: -> Regexp
-  def strict_pattern: -> Regexp
+
+  # Intentionally avoiding to use `Record type` ref: https://github.com/ruby/rbs/blob/4fb4c33b2325d1a73d79ff7aaeb49f21cec1e0e5/docs/syntax.md#record-type
+  # Because the returning values are not fixed.
+  def patterns: -> Hash[Symbol, Regexp | String]
   def octets: -> octets
   def timestamp_octets: -> timestamp_octets
   def randomness_octets: -> randomness_octets
+
+  # ```ruby
+  # # Currently experimental feature, so needed to load the extension.
+  # require 'ulid/uuid'
+  #
+  # # 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"
+  # ```
+  #
+  # See also [Why this is experimental?](https://github.com/kachick/ruby-ulid/issues/76)
   def to_uuidv4: -> String
-  def next: -> ULID?
-  alias succ next
+
+  # Returns next(successor) ULID.
+  # Especially `ULID#succ` makes it possible `Range[ULID]#each`.
+  #
+  # NOTE: But basically `Range[ULID]#each` should not be used, incrementing 128 bits IDs are not reasonable operation in most case
+  #
+  # ```ruby
+  # ULID.parse('01BX5ZZKBKZZZZZZZZZZZZZZZY').next.to_s #=> "01BX5ZZKBKZZZZZZZZZZZZZZZZ"
+  # ULID.parse('01BX5ZZKBKZZZZZZZZZZZZZZZZ').next.to_s #=> "01BX5ZZKBM0000000000000000"
+  # ULID.parse('7ZZZZZZZZZZZZZZZZZZZZZZZZZ').next #=> nil
+  # ```
+  #
+  # See also [ULID#pred](https://kachick.github.io/ruby-ulid/ULID.html#pred-instance_method)
+  def succ: -> ULID?
+  alias next succ
+
+  # Returns predecessor ULID.
+  #
+  # ```ruby
+  # ULID.parse('01BX5ZZKBK0000000000000001').pred.to_s #=> "01BX5ZZKBK0000000000000000"
+  # ULID.parse('01BX5ZZKBK0000000000000000').pred.to_s #=> "01BX5ZZKBJZZZZZZZZZZZZZZZZ"
+  # ULID.parse('00000000000000000000000000').pred #=> nil
+  # ```
+  #
+  # See also [ULID#succ](https://kachick.github.io/ruby-ulid/ULID.html#succ-instance_method)
   def pred: -> ULID?
   def freeze: -> self
 
+  # Returns `self`
+  def to_ulid: -> self
+
+  # Returns `self`. Not a new instance.
+  def dup: -> self
+
+  # Same API as [Object#clone](https://github.com/ruby/rbs/blob/4fb4c33b2325d1a73d79ff7aaeb49f21cec1e0e5/core/object.rbs#L79)
+  # But actually returns `self`. Not a new instance.
+  def clone: (?freeze: bool) -> self
+
   private
-  def self.convert_crockford_base32_to_n32: (String) -> String
-  def self.argument_error_for_range_building: (untyped argument) -> ArgumentError
-  def convert_n32_to_crockford_base32: (String) -> String
-  def matchdata: -> MatchData
+
+  # A pribate API. Should not be used in your code.
+  def self.new: (milliseconds: Integer, entropy: Integer, integer: Integer) -> self
+
+  # A pribate API. Should not be used in your code.
+  def self.reasonable_entropy: -> Integer
+
+  # A pribate API. Should not be used in your code.
+  def self.milliseconds_from_time: (Time time) -> Integer
+
+  # A pribate API. Should not be used in your code.
+  def self.safe_get_class_name: (untyped object) -> String
+
+  # A pribate API. Should not be used in your code.
+  def initialize: (milliseconds: Integer, entropy: Integer, integer: Integer) -> void
+
+  # A pribate API. Should not be used in your code.
   def cache_all_instance_variables: -> void
 end