ruby-ulid 0.1.1 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d9517a4c0fe5e9feec91b2d8e19366baed6b8f1c1ccb42640389c1ad11066854
-  data.tar.gz: 24344ffd2549f7eae76f6f344169eb74baf3168e05499a9d7577a18fea63fc4d
+  metadata.gz: 6e67f6449c010a7c85ff8050a081b21e824ed876d7695a4fa22beb25f2a62534
+  data.tar.gz: f0b0607131f8b04dd57c587746cd992a9a01070cacb53857fca6efb7dd11fe45
 SHA512:
-  metadata.gz: 5420da3cddc622a02a9d84ba398c17f59c733eea62d122aef0e5fb39dfade8e76cb3e4608814a0afb5c2e0251c6ebbbb2a10c6b27ea68b4ff8e32ad9f2e31ee3
-  data.tar.gz: 7bb4f8f941ed3f3ec2d5ebef03b4559b1ba2b07eaf5a9970ee3936ba6157bf5ff818eabc63847ba973536910bd6e8b8c65ae3382b74a368af85e228fec6524dd
+  metadata.gz: 5c1e3540e8e4f75c92fbc8347d2898fe8f8f233830a878c67462f8f9c9f065c969a9df8dd93e11bd27baa7a5cb7c1cb1eaf2fdf1e7dba5f5833e6295cd9d083f
+  data.tar.gz: cd70d28d9cba7270ddf61dcf46bba1c4a04328d828ba7ed32a39c68c01f460b36f9f85da74fdb1d1b742309fdffb29d118cc8bc238c1744b61dbdc3a32255475

data/README.md

@@ -10,7 +10,7 @@ Also providing [ruby/rbs](https://github.com/ruby/rbs) signature files.
 
 ![ULIDlogo](https://raw.githubusercontent.com/kachick/ruby-ulid/main/logo.png)
 
-![Build Status](https://github.com/kachick/ruby-ulid/actions/workflows/test.yml/badge.svg?branch=main)
+![Build Status](https://github.com/kachick/ruby-ulid/actions/workflows/test_behaviors.yml/badge.svg?branch=main)
 [![Gem Version](https://badge.fury.io/rb/ruby-ulid.png)](http://badge.fury.io/rb/ruby-ulid)
 
 ## Universally Unique Lexicographically Sortable Identifier
@@ -28,7 +28,7 @@ Instead, herein is proposed ULID:
 - 1.21e+24 unique ULIDs per millisecond
 - Lexicographically sortable!
 - Canonically encoded as a 26 character string, as opposed to the 36 character UUID
-- Uses [Crockford's base32](https://www.crockford.com/base32.html) for better efficiency and readability (5 bits per character) # See also exists issues in [Note](#note)
+- Uses [Crockford's base32](https://www.crockford.com/base32.html) for better efficiency and readability (5 bits per character)
 - Case insensitive
 - No special characters (URL safe)
 - Monotonic sort order (correctly detects and handles the same millisecond)
@@ -49,7 +49,7 @@ Should be installed!
 Add this line to your application/library's `Gemfile` is needed in basic use-case
 
 ```ruby
-gem 'ruby-ulid', '>= 0.1.1', '< 0.2.0'
+gem 'ruby-ulid', '>= 0.1.6', '< 0.2.0'
 ```
 
 ### Generator and Parser
@@ -146,7 +146,7 @@ sample_ulids_by_the_time.take(5) #=>
 ulids.sort == ulids #=> true
 ```
 
-Same generator does not generate duplicated ULIDs even in multi threads environment. It is implemented with [Thread::Mutex](https://github.com/ruby/ruby/blob/5f8bca32571fa9c651f6903d36f66082363f8879/thread_sync.c#L1572-L1582)
+Same generator does not generate duplicated ULIDs even in multi threads environment. It is implemented with [Monitor](https://bugs.ruby-lang.org/issues/16255)
 
 ### Filtering IDs with `Time`
 
@@ -170,7 +170,7 @@ exclude_end = ULID.range(time1...time2) #=> The end of `Range[ULID]` will be the
 
 # Below patterns are acceptable
 pinpointing = ULID.range(time1..time1) #=> This will match only for all IDs in `time1`
-until_the_end = ULID.range(..time1) #=> This will match only for all IDs upto `time1` (The `nil` starting `Range` can be used since Ruby 2.7)
+# until_the_end = ULID.range(..time1) #=> This will match only for all IDs upto `time1` (The `nil` starting `Range` can be used since Ruby 2.7)
 until_the_end = ULID.range(ULID.min.to_time..time1) #=> This is same as above for Ruby 2.6
 until_the_ulid_limit = ULID.range(time1..) # This will match only for all IDs from `time1` to max value of the ULID limit
 
@@ -192,7 +192,7 @@ ULID.floor(time) #=> 2000-01-01 00:00:00.123 UTC
 For rough operations, `ULID.scan` might be useful.
 
 ```ruby
-json =<<'EOD'
+json = <<'JSON'
 {
   "id": "01F4GNAV5ZR6FJQ5SFQC7WDSY3",
   "author": {
@@ -217,7 +217,7 @@ json =<<'EOD'
     }
   ]
 }
-EOD
+JSON
 
 ULID.scan(json).to_a
 #=>
@@ -313,7 +313,7 @@ ulids.take(10)
 # ULID(2021-04-29 03:18:24.152 UTC: 01F4DT4Z4RA0QV8WFQGRAG63EH),
 # ULID(2021-05-02 13:27:16.394 UTC: 01F4PM605ABF5SDVMEHBH8JJ9R)]
 ULID.sample(10, period: ulid1.to_time..ulid2.to_time)
-#=> 
+#=>
 # [ULID(2021-04-29 06:44:41.513 UTC: 01F4E5YPD9XQ3MYXWK8ZJKY8SW),
 #  ULID(2021-05-01 00:35:06.629 UTC: 01F4JNKD85SVK1EAEYSJGF53A2),
 #  ULID(2021-05-02 12:45:28.408 UTC: 01F4PHSEYRG9BWBEWMRW1XE6WW),
@@ -326,6 +326,34 @@ ULID.sample(10, period: ulid1.to_time..ulid2.to_time)
 #  ULID(2021-04-28 15:05:06.808 UTC: 01F4CG68ZRST94T056KRZ5K9S4)]
 ```
 
+### ULID specification ambiguity around orthographical variants of the format
+
+I'm afraid so, we should consider [Current ULID spec](https://github.com/ulid/spec/tree/d0c7170df4517939e70129b4d6462cc162f2d5bf#universally-unique-lexicographically-sortable-identifier) has `orthographical variants of the format` possibilities.
+
+>Uses Crockford's base32 for better efficiency and readability (5 bits per character)
+
+The original `Crockford's base32` maps `I`, `L` to `1`, `O` to `0`.
+And accepts freestyle inserting `Hyphens (-)`.
+To consider this patterns or not is different in each implementations.
+
+Current parser/validator/matcher aims to cover `subset of Crockford's base32`.
+I have suggested it would be clarified in [ulid/spec#57](https://github.com/ulid/spec/pull/57).
+
+>Case insensitive
+
+I can understand it might be considered in actual use-case.
+But it is a controversial point, discussing in [ulid/spec#3](https://github.com/ulid/spec/issues/3).
+
+Be that as it may, this gem provides API for handling the nasty possibilities.
+
+`ULID.normalize` and `ULID.normalized?`
+
+```ruby
+ULID.normalize('-olarz3-noekisv4rrff-q6ig5fav--') #=> "01ARZ3N0EK1SV4RRFFQ61G5FAV"
+ULID.normalized?('-olarz3-noekisv4rrff-q6ig5fav--') #=> false
+ULID.normalized?('01ARZ3N0EK1SV4RRFFQ61G5FAV') #=> true
+```
+
 ### UUIDv4 converter for migration use-cases
 
 `ULID.from_uuidv4` and `ULID#to_uuidv4` is the converter.
@@ -335,7 +363,7 @@ The imported timestamp is meaningless. So ULID's benefit will lost.
 # Currently experimental feature, so needed to load the extension.
 require 'ulid/uuid'
 
-# Basically reversible 
+# Basically reversible
 ulid = ULID.from_uuidv4('0983d0a2-ff15-4d83-8f37-7dd945b5aa39') #=> ULID(2301-07-10 00:28:28.821 UTC: 09GF8A5ZRN9P1RYDVXV52VBAHS)
 ulid.to_uuidv4 #=> "0983d0a2-ff15-4d83-8f37-7dd945b5aa39"
 
@@ -403,81 +431,11 @@ NOTE: It is still having precision issue similar as `ulid gem` in the both gener
 1. [Fix to handle timestamp precision in parser](https://github.com/abachman/ulid-ruby/pull/5)
 1. [Fix to handle timestamp precision in generator](https://github.com/abachman/ulid-ruby/pull/4)
 
-### Generating benchmarks
-
-This runs rough benchmarks
-
-```console
-$ rake benchmark_with_other_gems
-(Do not use `bundle exec`!)
-```
+### Compare performance with them
 
-<details>
-<summary>One of the result at 2021/05/10 on my machine</summary>
-
-```plaintext
-#### rafaelsales - ulid
-cd ./benchmark/compare_with_othergems/rafaelsales && bundle install --quiet && bundle exec ruby -v ./generate.rb
-ruby 3.0.1p64 (2021-04-05 revision 0fb782ee38) [x86_64-darwin20]
-Warming up --------------------------------------
-       ULID.generate     5.560k i/100ms
-Calculating -------------------------------------
-       ULID.generate     52.655k (±11.0%) i/s -    261.320k in   5.029719s
-"`ulid gem - 1.3.0` generated products: 371927 - sample: [\"01F59Y97807D2S67KE6X7ATK7Z\", \"01F59Y9AVRQJFAT5M2N7Z72BVF\", \"01F59Y95Z1042X4Z1K9729BSE3\", \"01F59Y95ZMVDFKD63Y8TT145GQ\", \"01F59Y94YQEZ3PH5STZ8PS1JPG\"]"
-------------------------------------------------------------------------
-#### abachman - ulid-ruby
-cd ./benchmark/compare_with_othergems/abachman && bundle install --quiet && bundle exec ruby -v ./generate.rb
-ruby 3.0.1p64 (2021-04-05 revision 0fb782ee38) [x86_64-darwin20]
-Warming up --------------------------------------
-       ULID.generate     3.862k i/100ms
-Calculating -------------------------------------
-       ULID.generate     38.415k (±13.1%) i/s -    189.238k in   5.025788s
-"`ulid-ruby gem - 1.0.0` generated products: 260625 - sample: [\"01F59Y9H9V17EPXTYNZDCXB9EZ\", \"01F59Y9J4S4XZ68MF5DJDWHTAC\", \"01F59Y9J8887VC8E850QSBDCDX\", \"01F59Y9JEJPD088EYXVHB86W3N\", \"01F59Y9GGAZFXGCB92EQD695CZ\"]"
-------------------------------------------------------------------------
-#### kachick - ruby-ulid(This one)
-cd ./benchmark/compare_with_othergems/kachick && bundle install --quiet && bundle exec ruby -v ./generate.rb
-ruby 3.0.1p64 (2021-04-05 revision 0fb782ee38) [x86_64-darwin20]
-Warming up --------------------------------------
-  ULID.generate.to_s     3.185k i/100ms
-Calculating -------------------------------------
-  ULID.generate.to_s     31.934k (± 9.1%) i/s -    159.250k in   5.030707s
-"`ruby-ulid gem (this one) - 0.1.0` generated products: 223867 - sample: [\"01F59Y9SPZHM6JCTYP50CHGVAX\", \"01F59Y9VB7X0SX32MMKF78KJR3\", \"01F59Y9W0C83RYCNYVH84R4JG3\", \"01F59Y9V218Q3D4YP3W74ET3EW\", \"01F59Y9X6DD8NX99WBGCR7RNXF\"]"
-```
-
-In another execution, Changed as below. So there doesn't seem to be a big difference.
-
-```plaintext
-#### rafaelsales - ulid
-cd ./benchmark/compare_with_othergems/rafaelsales && bundle install --quiet && bundle exec ruby -v ./generate.rb
-ruby 3.0.1p64 (2021-04-05 revision 0fb782ee38) [x86_64-darwin20]
-Warming up --------------------------------------
-       ULID.generate     2.473k i/100ms
-Calculating -------------------------------------
-       ULID.generate     24.101k (±15.9%) i/s -    118.704k in   5.066190s
-"`ulid gem - 1.3.0` generated products: 164763 - sample: [\"01F59YEGPFMXXZWC1YQ49TSK8Y\", \"01F59YEFF7VX5WAW91VTCSE2N9\", \"01F59YEEZ5P9428SDYEDYW8D27\", \"01F59YEHVK56DZBJSNSQK6V1W6\", \"01F59YEHE07M98PVV97ABBAKHM\"]"
-------------------------------------------------------------------------
-#### abachman - ulid-ruby
-cd ./benchmark/compare_with_othergems/abachman && bundle install --quiet && bundle exec ruby -v ./generate.rb
-ruby 3.0.1p64 (2021-04-05 revision 0fb782ee38) [x86_64-darwin20]
-Warming up --------------------------------------
-       ULID.generate     2.620k i/100ms
-Calculating -------------------------------------
-       ULID.generate     27.571k (±14.2%) i/s -    136.240k in   5.056272s
-"`ulid-ruby gem - 1.0.0` generated products: 186683 - sample: [\"01F59YEVX6GC9TC0RCZ74RC6Z3\", \"01F59YESJXWYGZ61TXHKRVKS97\", \"01F59YEVQ4QQKBED5T49RTV1MA\", \"01F59YEPJ6MMZY1N63DNW7C4SN\", \"01F59YEQK52K8TKTP1ESC6VC5X\"]"
-------------------------------------------------------------------------
-#### kachick - ruby-ulid(This one)
-cd ./benchmark/compare_with_othergems/kachick && bundle install --quiet && bundle exec ruby -v ./generate.rb
-ruby 3.0.1p64 (2021-04-05 revision 0fb782ee38) [x86_64-darwin20]
-Warming up --------------------------------------
-  ULID.generate.to_s     3.014k i/100ms
-Calculating -------------------------------------
-  ULID.generate.to_s     31.612k (±10.1%) i/s -    156.728k in   5.013432s
-"`ruby-ulid gem (this one) - 0.1.0` generated products: 212293 - sample: [\"01F59YF1WP49TT4GQPDN3E9JTJ\", \"01F59YF1MW1ZDQW93NX4J6RG4G\", \"01F59YF0KRX2CZKHDQQSN5HXHW\", \"01F59YEZVNH8YHP4ZHDK2ZRWSR\", \"01F59YF1J0FV3CVV099SHA2Q9A\"]"
-```
+See [Benchmark](https://github.com/kachick/ruby-ulid/wiki/Benchmark).
 
-I have an excuse, This gem does not aim `faster than other`.
-So I think the results are acceptable.
-</details>
+The results are not something to be proud of.
 
 ## References
 
@@ -488,4 +446,3 @@ So I think the results are acceptable.
 ## Note
 
 - Another choices for sortable and randomness IDs, [UUIDv6, UUIDv7, UUIDv8 might be the one. (But they are still in draft state)](https://www.ietf.org/archive/id/draft-peabody-dispatch-new-uuid-format-01.html), I will track them in [ruby-ulid#37](https://github.com/kachick/ruby-ulid/issues/37)
-- Current parser/validator/matcher aims to cover `subset of Crockford's base32`. Suggesting it in [ulid/spec#57](https://github.com/ulid/spec/pull/57). Be that as it may, I might provide special handler or converter for the exception in [ruby-ulid#57](https://github.com/kachick/ruby-ulid/issues/57) and/or [ruby-ulid#78](https://github.com/kachick/ruby-ulid/issues/78)

data/lib/ruby-ulid.rb

@@ -0,0 +1,6 @@
+# coding: us-ascii
+# frozen_string_literal: true
+
+# Copyright (C) 2021 Kenichi Kamiya
+
+require_relative 'ulid'

data/lib/ulid.rb

@@ -1,5 +1,6 @@
 # coding: us-ascii
 # frozen_string_literal: true
+
 # Copyright (C) 2021 Kenichi Kamiya
 
 require 'securerandom'
@@ -60,6 +61,7 @@ class ULID
   # @return [ULID]
   def self.at(time)
     raise ArgumentError, 'ULID.at takes only `Time` instance' unless Time === time
+
     from_milliseconds_and_entropy(milliseconds: milliseconds_from_time(time), entropy: reasonable_entropy)
   end
 
@@ -91,19 +93,21 @@ class ULID
   #   * Do not take random generator for the arguments
   #   * Raising error instead of truncating elements for the given number
   def self.sample(*args, period: nil)
-    int_generator = if period
-      ulid_range = range(period)
-      min, max, exclude_end = ulid_range.begin.to_i, ulid_range.end.to_i, ulid_range.exclude_end?
+    int_generator = (
+      if period
+        ulid_range = range(period)
+        min, max, exclude_end = ulid_range.begin.to_i, ulid_range.end.to_i, ulid_range.exclude_end?
 
-      possibilities = (max - min) + (exclude_end ? 0 : 1)
-      raise ArgumentError, "given range `#{ulid_range.inspect}` does not have possibilities" unless possibilities.positive?
+        possibilities = (max - min) + (exclude_end ? 0 : 1)
+        raise ArgumentError, "given range `#{ulid_range.inspect}` does not have possibilities" unless possibilities.positive?
 
-      -> {
-        SecureRandom.random_number(possibilities) + min
-      }
-    else
-      RANDOM_INTEGER_GENERATOR
-    end
+        -> {
+          SecureRandom.random_number(possibilities) + min
+        }
+      else
+        RANDOM_INTEGER_GENERATOR
+      end
+    )
 
     case args.size
     when 0
@@ -134,6 +138,7 @@ class ULID
     string = String.try_convert(string)
     raise ArgumentError, 'ULID.scan takes only strings' unless string
     return to_enum(__callee__, string) unless block_given?
+
     string.scan(SCANNING_PATTERN) do |matched|
       yield parse(matched)
     end
@@ -156,7 +161,7 @@ class ULID
     milliseconds = n32encoded_timestamp.to_i(32)
     entropy = n32encoded_randomness.to_i(32)
 
-    new milliseconds: milliseconds, entropy: entropy, integer: integer
+    new(milliseconds: milliseconds, entropy: entropy, integer: integer)
   end
 
   # @param [Range<Time>, Range<nil>, Range[ULID]] period
@@ -164,6 +169,7 @@ class ULID
   # @raise [ArgumentError] if the given period is not a `Range[Time]`, `Range[nil]` or `Range[ULID]`
   def self.range(period)
     raise ArgumentError, 'ULID.range takes only `Range[Time]`, `Range[nil]` or `Range[ULID]`' unless Range === period
+
     begin_element, end_element, exclude_end = period.begin, period.end, period.exclude_end?
     return period if self === begin_element && self === end_element
 
@@ -180,11 +186,7 @@ class ULID
 
     case end_element
     when Time
-      if exclude_end
-        end_ulid = min(end_element)
-      else
-        end_ulid = max(end_element)
-      end
+      end_ulid = exclude_end ? min(end_element) : max(end_element)
     when nil
       # The end should be max and include end, because nil end means to cover endless ULIDs until the limit
       end_ulid = MAX
@@ -260,9 +262,29 @@ class ULID
   end
 
   # @param [String, #to_str] string
-  # @return [Boolean]
-  def self.valid?(string)
+  # @return [String]
+  # @raise [ParserError] if the given format is not correct for ULID specs, even if ignored `orthographical variants of the format`
+  def self.normalize(string)
     string = String.try_convert(string)
+    raise ArgumentError, 'ULID.normalize takes only strings' unless string
+
+    normalized_in_crockford = CrockfordBase32.normalize(string)
+    # Ensure the ULID correctness, because CrockfordBase32 does not always mean to satisfy ULID format
+    parse(normalized_in_crockford).to_s
+  end
+
+  # @return [Boolean]
+  def self.normalized?(object)
+    normalized = normalize(object)
+  rescue Exception
+    false
+  else
+    normalized == object
+  end
+
+  # @return [Boolean]
+  def self.valid?(object)
+    string = String.try_convert(object)
     string ? STRICT_PATTERN_WITH_CROCKFORD_BASE32_SUBSET.match?(string) : false
   end
 
@@ -290,8 +312,19 @@ class ULID
   private_class_method def self.safe_get_class_name(object)
     fallback = 'UnknownObject'
 
+    # This class getter implementation used https://github.com/rspec/rspec-support/blob/4ad8392d0787a66f9c351d9cf6c7618e18b3d0f2/lib/rspec/support.rb#L83-L89 as a reference, thank you!
+    # ref: https://twitter.com/_kachick/status/1400064896759304196
+    klass = (
+      begin
+        object.class
+      rescue NoMethodError
+        singleton_class = class << object; self; end
+        singleton_class.ancestors.detect { |ancestor| !ancestor.equal?(singleton_class) }
+      end
+    )
+
     begin
-      name = String.try_convert(object.class.name)
+      name = String.try_convert(klass.name)
     rescue Exception
       fallback
     else
@@ -315,7 +348,7 @@ class ULID
     n32encoded_randomness = entropy.to_s(32).rjust(RANDOMNESS_ENCODED_LENGTH, '0')
     integer = (n32encoded_timestamp + n32encoded_randomness).to_i(32)
 
-    new milliseconds: milliseconds, entropy: entropy, integer: integer
+    new(milliseconds: milliseconds, entropy: entropy, integer: integer)
   end
 
   attr_reader :milliseconds, :entropy
@@ -386,7 +419,7 @@ class ULID
   def octets
     digits = @integer.digits(256)
     (OCTETS_LENGTH - digits.size).times do
-      digits.push 0
+      digits.push(0)
     end
     digits.reverse!
   end
@@ -457,6 +490,20 @@ class ULID
     super
   end
 
+  # @api private
+  # @return [Integer]
+  def marshal_dump
+    @integer
+  end
+
+  # @api private
+  # @param [Integer] integer
+  # @return [void]
+  def marshal_load(integer)
+    unmarshaled = ULID.from_integer(integer)
+    initialize(integer: unmarshaled.to_i, milliseconds: unmarshaled.milliseconds, entropy: unmarshaled.entropy)
+  end
+
   # @return [self]
   def to_ulid
     self

data/lib/ulid/crockford_base32.rb

@@ -1,9 +1,12 @@
 # coding: us-ascii
 # frozen_string_literal: true
+
 # Copyright (C) 2021 Kenichi Kamiya
 
 class ULID
-  # Currently supporting only for `subset` for actual use-case`
+  # @see https://www.crockford.com/base32.html
+  #
+  # This module supporting only `subset of original crockford for actual use-case` in ULID context.
   # Original decoding spec allows other characters.
   # But I think ULID should allow `subset` of Crockford's Base32.
   # See below
@@ -46,11 +49,24 @@ class ULID
       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
 
+    STANDARD_BY_VARIANT = {
+      'L' => '1',
+      'l' => '1',
+      'I' => '1',
+      'i' => '1',
+      'O' => '0',
+      'o' => '0',
+      '-' => ''
+    }.freeze
+    VARIANT_PATTERN = /[#{STANDARD_BY_VARIANT.keys.join}]/.freeze
+
+    # @api private
     # @param [String] string
     # @return [Integer]
     def self.decode(string)
@@ -58,11 +74,19 @@ class ULID
       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
+
+    # @api private
+    # @param [String] string
+    # @return [String]
+    def self.normalize(string)
+      string.gsub(VARIANT_PATTERN, STANDARD_BY_VARIANT)
+    end
   end
 end

data/lib/ulid/monotonic_generator.rb

@@ -1,16 +1,19 @@
 # coding: us-ascii
 # frozen_string_literal: true
+
 # Copyright (C) 2021 Kenichi Kamiya
 
 class ULID
   class MonotonicGenerator
+    include MonitorMixin
+
     # @return [ULID, nil]
     attr_reader :prev
 
     undef_method :instance_variable_set
 
     def initialize
-      @mutex = Thread::Mutex.new
+      super()
       @prev = nil
     end
 
@@ -26,7 +29,7 @@ class ULID
     # @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)
-      @mutex.synchronize do
+      synchronize do
         unless @prev
           @prev = ULID.generate(moment: moment)
           return @prev
@@ -34,19 +37,23 @@ class ULID
 
         milliseconds = ULID.milliseconds_from_moment(moment)
 
-        ulid = if @prev.milliseconds < milliseconds
-          ULID.generate(moment: milliseconds)
-        else
-          ULID.from_milliseconds_and_entropy(milliseconds: @prev.milliseconds, entropy: @prev.entropy.succ)
-        end
+        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
+          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

data/lib/ulid/uuid.rb

@@ -1,5 +1,6 @@
 # coding: us-ascii
 # frozen_string_literal: true
+
 # Copyright (C) 2021 Kenichi Kamiya
 
 # Extracted features around UUID from some reasons
@@ -8,7 +9,7 @@
 #  * 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
+  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
@@ -18,7 +19,7 @@ class ULID
     uuid = String.try_convert(uuid)
     raise ArgumentError, 'ULID.from_uuidv4 takes only strings' unless uuid
 
-    prefix_trimmed = uuid.sub(/\Aurn: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

data/lib/ulid/version.rb

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

data/sig/ulid.rbs

@@ -1,5 +1,4 @@
-# Classes
-class ULID
+class ULID < Object
   VERSION: String
   CROCKFORD_BASE32_ENCODING_STRING: String
   TIMESTAMP_ENCODED_LENGTH: 10
@@ -44,22 +43,57 @@ class ULID
     CROCKFORD_BASE32_CHAR_PATTERN: Regexp
     CROCKFORD_BASE32_CHAR_BY_N32_CHAR: Hash[String, String]
     N32_CHAR_PATTERN: Regexp
+    STANDARD_BY_VARIANT: Hash[String, String]
+    VARIANT_PATTERN: Regexp
 
+    # A private API. Should not be used in your code.
     def self.encode: (Integer integer) -> String
+
+    # A private API. Should not be used in your code.
     def self.decode: (String string) -> Integer
+
+    # A private API. Should not be used in your code.
+    def self.normalize: (String string) -> String
   end
 
   class MonotonicGenerator
-    @mutex: Thread::Mutex
+    include MonitorMixin
+
+    # Returned value is `basically not` Thread-safety
+    # If you want to keep Thread-safety, keep to call {#generate} only in same {#synchronize} block
+    #
+    # ```ruby
+    # generator.synchronize do
+    #   generator.prev
+    #   generator.inspect
+    #   generator.generate
+    # end
+    # ```
     attr_reader prev: ULID | nil
+
+    # A private 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)
+    # The `Thread-safety` is implemented with [Monitor](https://bugs.ruby-lang.org/issues/16255)
     def generate: (?moment: moment) -> ULID
+
+    # Returned value is `basically not` Thread-safety
+    # If you want to keep Thread-safety, keep to call {#generate} only in same {#synchronize} block
+    #
+    # ```ruby
+    # generator.synchronize do
+    #   generator.prev
+    #   generator.inspect
+    #   generator.generate
+    # end
+    # ```
     def inspect: -> String
     alias to_s inspect
     def freeze: -> void
   end
 
-  interface _ULID
+  interface _ToULID
     def to_ulid: () -> ULID
   end
 
@@ -75,57 +109,437 @@ class ULID
   @inspect: String?
   @time: Time?
 
-  def self.generate: (?moment: moment, ?entropy: Integer) -> self
-  def self.at: (Time time) -> self
+  # 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) -> ULID
+
+  # 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) -> ULID
+
+  # A private API. Should not be used in your code.
   def self.current_milliseconds: -> Integer
+
+  # A private API. Should not be used in your code.
   def self.milliseconds_from_moment: (moment moment) -> Integer
+
+  # `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.parse: (String string) -> self
+
+  # 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) -> ULID
+
+  # ```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) -> self
+  def self.from_integer: (Integer integer) -> ULID
+
+  # 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
-  def self.sample: (?period: period) -> self
-                 | (Integer number, ?period: period) -> Array[self]
-  def self.valid?: (untyped string) -> bool
-  def self.scan:  (String string) -> Enumerator[self, singleton(ULID)]
-                | (String string) { (self ulid) -> void } -> singleton(ULID)
-  def self.from_milliseconds_and_entropy: (milliseconds: Integer, entropy: Integer) -> self
-  def self.try_convert: (_ULID) -> self
+
+  # 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) -> ULID
+                 | (Integer number, ?period: period) -> Array[ULID]
+  def self.valid?: (untyped) -> bool
+
+  # Returns normalized string
+  #
+  # ```ruby
+  # ULID.normalize('-olarz3-noekisv4rrff-q6ig5fav--') #=> "01ARZ3N0EK1SV4RRFFQ61G5FAV"
+  # ULID.normalized?('-olarz3-noekisv4rrff-q6ig5fav--') #=> false
+  # ULID.normalized?('01ARZ3N0EK1SV4RRFFQ61G5FAV') #=> true
+  # ```
+  #
+  # See also [ulid/spec#57](https://github.com/ulid/spec/pull/57) and [ulid/spec#3](https://github.com/ulid/spec/issues/3)
+  def self.normalize: (_ToStr string) -> String
+
+  # Returns `true` if it is normalized string
+  #
+  # ```ruby
+  # ULID.normalize('-olarz3-noekisv4rrff-q6ig5fav--') #=> "01ARZ3N0EK1SV4RRFFQ61G5FAV"
+  # ULID.normalized?('-olarz3-noekisv4rrff-q6ig5fav--') #=> false
+  # ULID.normalized?('01ARZ3N0EK1SV4RRFFQ61G5FAV') #=> true
+  # ```
+  #
+  # See also [ulid/spec#57](https://github.com/ulid/spec/pull/57) and [ulid/spec#3](https://github.com/ulid/spec/issues/3)
+  def self.normalized?: (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) { (ULID ulid) -> void } -> singleton(ULID)
+  def self.from_milliseconds_and_entropy: (milliseconds: Integer, entropy: Integer) -> ULID
+  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, integer: 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) -> 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
+
+  # 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
+
+  # A private API. Should not be used in your code.
+  def marshal_dump: -> Integer
+
+  # A private API. Should not be used in your code.
+  def marshal_load: (Integer integer) -> void
+
+  # Returns `self`
   def to_ulid: -> self
+
+  # Returns `self`. Not a new instance.
   def dup: -> self
-  # Same as https://github.com/ruby/rbs/blob/4fb4c33b2325d1a73d79ff7aaeb49f21cec1e0e5/core/object.rbs#L79
+
+  # 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
+
+  # A private API. Should not be used in your code.
+  def self.new: (milliseconds: Integer, entropy: Integer, integer: Integer) -> self
+
+  # A private API. Should not be used in your code.
   def self.reasonable_entropy: -> Integer
+
+  # A private API. Should not be used in your code.
   def self.milliseconds_from_time: (Time time) -> Integer
+
+  # A private API. Should not be used in your code.
   def self.safe_get_class_name: (untyped object) -> String
+
+  # A private API. Should not be used in your code.
+  def initialize: (milliseconds: Integer, entropy: Integer, integer: Integer) -> void
+
+  # A private API. Should not be used in your code.
   def cache_all_instance_variables: -> void
 end

metadata

@@ -1,69 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: ruby-ulid
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.6
 platform: ruby
 authors:
 - Kenichi Kamiya
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-05-15 00:00:00.000000000 Z
-dependencies:
-- !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
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 2.8.4
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '3'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 2.8.4
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '3'
-- !ruby/object:Gem::Dependency
-  name: yard
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.9.26
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '2'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.9.26
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '2'
+date: 2021-07-05 00:00:00.000000000 Z
+dependencies: []
 description: |2
       The ULID(Universally Unique Lexicographically Sortable Identifier) 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.
@@ -74,8 +20,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- LICENSE
+- LICENSE.txt
 - README.md
+- lib/ruby-ulid.rb
 - lib/ulid.rb
 - lib/ulid/crockford_base32.rb
 - lib/ulid/monotonic_generator.rb
@@ -89,6 +36,7 @@ metadata:
   documentation_uri: https://kachick.github.io/ruby-ulid/
   homepage_uri: https://github.com/kachick/ruby-ulid
   source_code_uri: https://github.com/kachick/ruby-ulid
+  bug_tracker_uri: https://github.com/kachick/ruby-ulid/issues
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -107,5 +55,5 @@ requirements: []
 rubygems_version: 3.2.15
 signing_key:
 specification_version: 4
-summary: A handy ULID library
+summary: ULID manipulation library
 test_files: []