ruby-ulid 0.2.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cea320f797b834d5a0f246db9920a9453a6d229728b428590e2f99dd275c8fe9
-  data.tar.gz: e703ca1896a7ee4155b1362cffdfaf9499e4ae32073cd440c50750d4e9cc9c1a
+  metadata.gz: 4d7356366d0184815a725d1947f4f685b3abba0320ae60800b5a015dc7c649e9
+  data.tar.gz: 04b55b6d92dbf02865a7803be352f5cd385f3417c061269f2ad197474202154d
 SHA512:
-  metadata.gz: b9d0436d98095dd0084675d87a6605848f6c7ee14d65724ce5bd9229945ffc17a3b7e1efaf9a295baeaeac11782c9fc63bc901149cfa58d96046e334d5d19067
-  data.tar.gz: f7e016a4ca3d859f8469b5281d9f5581ffe6c0fdde737c554c627f7862461701844e46e4513ce09748e1cdf3fa4b8da2607a8d3267f74c64ae4a257ae54d6e78
+  metadata.gz: aa826d204cbdc1e6850fbeab278dc72e5b683926db9af7ed477ec2e74837d32829dbfb468c1156d6dcf5be604f9fdeb8fd0a282999b47a627884152b2a2cd5d4
+  data.tar.gz: 0b1208e76af50f9952c8c4835d1410c7e1fd114313cc71d39a143c9bc04ac4f1a35ba49be88a49406606c441e4f4fa7cad5fc938d74fcecde0d612319a6890b3

data/README.md

@@ -1,18 +1,17 @@
 # ruby-ulid
 
+[![Build Status](https://github.com/kachick/ruby-ulid/actions/workflows/test_behaviors.yml/badge.svg?branch=main)](https://github.com/kachick/ruby-ulid/actions/workflows/test_behaviors.yml/?branch=main)
+[![Gem Version](https://badge.fury.io/rb/ruby-ulid.svg)](http://badge.fury.io/rb/ruby-ulid)
+
 ## Overview
 
-The `ULID` spec is defined on [ulid/spec](https://github.com/ulid/spec). It has useful specs for applications (e.g. `Database key`), especially possess all `uniqueness`, `randomness`, `extractable timestamps` and `sortable` features.
-This gem aims to provide the generator, monotonic generator, parser and handy manipulation features around the ULID.
-Also providing [ruby/rbs](https://github.com/ruby/rbs) signature files.
+[ulid/spec](https://github.com/ulid/spec) is useful.
+Especially possess all `uniqueness`, `randomness`, `extractable timestamps` and `sortable` features.  
+This gem aims to provide the generator, optional monotonicity, parser and other manipulation features around ULID with included [RBS](https://github.com/ruby/rbs).
 
 ---
 
-![ULIDlogo](https://raw.githubusercontent.com/kachick/ruby-ulid/main/logo.png)
-
-[![Build Status](https://github.com/kachick/ruby-ulid/actions/workflows/test_behaviors.yml/badge.svg?branch=main)](https://github.com/kachick/ruby-ulid/actions/workflows/test_behaviors.yml/?branch=main)
-[![Gem Version](https://badge.fury.io/rb/ruby-ulid.svg)](http://badge.fury.io/rb/ruby-ulid)
-[![Visual Studio Code](https://img.shields.io/badge/Visual%20Studio%20Code-0078d7.svg?style=for-the-badge&logo=visual-studio-code&logoColor=white)](https://github.dev/kachick/ruby-ulid)
+![ULIDlogo](./assets/logo.png)
 
 ## Universally Unique Lexicographically Sortable Identifier
 
@@ -47,21 +46,43 @@ $ gem install ruby-ulid
 Should be installed!
 ```
 
-Add this line to your application/library's `Gemfile` is needed in basic use-case
+Add this line in your Gemfile.
 
 ```ruby
-gem 'ruby-ulid', '~> 0.2.2'
+gem('ruby-ulid', '~> 0.5.0')
 ```
 
-### Generator and Parser
-
-The generated `ULID` is an object not just a string.
-It means easily get the timestamps and binary formats.
+### How to use
 
 ```ruby
 require 'ulid'
 
+ULID::VERSION
+# => "0.5.0"
+```
+
+### Basic Generator
+
+The generated `ULID` is an object not just a string.
+
+```ruby
 ulid = ULID.generate #=> ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GRMJ9AA)
+```
+
+### Parser
+
+Get the objects from exists encoded ULIDs.
+
+```ruby
+ulid = ULID.parse('01ARZ3NDEKTSV4RRFFQ69G5FAV') #=> ULID(2016-07-30 23:54:10.259 UTC: 01ARZ3NDEKTSV4RRFFQ69G5FAV)
+```
+
+### ULID object
+
+Extract timestamps and binary formats.
+
+```ruby
+ulid = ULID.parse('01F4A5Y1YAQCYAYCTC7GRMJ9AA') #=> ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GRMJ9AA)
 ulid.to_time #=> 2021-04-27 17:27:22.826 UTC
 ulid.milliseconds #=> 1619544442826
 ulid.to_s #=> "01F4A5Y1YAQCYAYCTC7GRMJ9AA"
@@ -71,16 +92,9 @@ ulid.to_i #=> 1957909092946624190749577070267409738
 ulid.octets #=> [1, 121, 20, 95, 7, 202, 187, 60, 175, 51, 76, 60, 49, 73, 37, 74]
 ```
 
-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
-```
-
 ### Sortable with the timestamp
 
-ULIDs are sortable when they are generated in different timestamp with milliseconds precision
+ULIDs are sortable when they are generated in different timestamp with milliseconds precision.
 
 ```ruby
 ulids = 1000.times.map do
@@ -91,7 +105,7 @@ ulids.uniq(&:to_time).size #=> 1000
 ulids.sort == ulids #=> true
 ```
 
-`ULID.generate` can take fixed `Time` instance. The shorthand is `ULID.at`
+`ULID.generate` can take fixed `Time` instance. The shorthand is `ULID.at`.
 
 ```ruby
 time = Time.at(946684800).utc #=> 2000-01-01 00:00:00 UTC
@@ -105,7 +119,7 @@ end
 ulids.sort == ulids #=> true
 ```
 
-The basic generator prefers `randomness`, it does not guarantee `sortable` for same milliseconds ULIDs.
+Basic generator prefers `randomness`, it does not guarantee `sortable` for same milliseconds ULIDs.
 
 ```ruby
 ulids = 10000.times.map do
@@ -147,11 +161,11 @@ 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 [Monitor](https://bugs.ruby-lang.org/issues/16255)
+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`
 
-`ULID` can be element of the `Range`. If you generated the IDs in monotonic generator, ID based filtering is easy and reliable
+`ULID` can be element of the `Range`. If they were generated with monotonic generator, ID based filtering is easy and reliable.
 
 ```ruby
 include_end = ulid1..ulid2
@@ -187,7 +201,9 @@ time = Time.at(946684800, Rational('123456.789')).utc #=> 2000-01-01 00:00:00.12
 ULID.floor(time) #=> 2000-01-01 00:00:00.123 UTC
 ```
 
-### Scanner for string (e.g. `JSON`)
+### Tools
+
+#### Scanner for string (e.g. `JSON`)
 
 For rough operations, `ULID.scan` might be useful.
 
@@ -230,7 +246,7 @@ ULID.scan(json).to_a
 ```
 
 `ULID#patterns` is a util for text based operations.
-The results and spec are not fixed. Should not be used except snippets/console operation
+The results and spec are not fixed. Should not be used except snippets/console operation.
 
 ```ruby
 ULID.parse('01F4GNBXW1AM2KWW52PVT3ZY9X').patterns
@@ -241,7 +257,7 @@ ULID.parse('01F4GNBXW1AM2KWW52PVT3ZY9X').patterns
 }
 ```
 
-### Some methods to help manipulations
+#### Get boundary ULIDs
 
 `ULID.min` and `ULID.max` return termination values for ULID spec.
 
@@ -256,10 +272,12 @@ ULID.min(time) #=> ULID(2000-01-01 00:00:00.123 UTC: 00VHNCZB3V0000000000000000)
 ULID.max(time) #=> ULID(2000-01-01 00:00:00.123 UTC: 00VHNCZB3VZZZZZZZZZZZZZZZZ)
 ```
 
+#### As element in Enumerable
+
 `ULID#next` and `ULID#succ` 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
+NOTE: However basically `Range[ULID]#each` should not be used. Iincrementing 128 bits IDs are not reasonable operation in most cases.
 
 ```ruby
 ULID.parse('01BX5ZZKBKZZZZZZZZZZZZZZZY').next.to_s #=> "01BX5ZZKBKZZZZZZZZZZZZZZZZ"
@@ -267,7 +285,7 @@ ULID.parse('01BX5ZZKBKZZZZZZZZZZZZZZZZ').next.to_s #=> "01BX5ZZKBM00000000000000
 ULID.parse('7ZZZZZZZZZZZZZZZZZZZZZZZZZ').next #=> nil
 ```
 
-`ULID#pred` returns predecessor ULID
+`ULID#pred` returns predecessor ULID.
 
 ```ruby
 ULID.parse('01BX5ZZKBK0000000000000001').pred.to_s #=> "01BX5ZZKBK0000000000000000"
@@ -275,6 +293,8 @@ ULID.parse('01BX5ZZKBK0000000000000000').pred.to_s #=> "01BX5ZZKBJZZZZZZZZZZZZZZ
 ULID.parse('00000000000000000000000000').pred #=> nil
 ```
 
+#### Test helpers
+
 `ULID.sample` returns random ULIDs.
 
 Basically ignores generating time.
@@ -300,61 +320,52 @@ ulid1 = ULID.parse('01F4A5Y1YAQCYAYCTC7GRMJ9AA') #=> ULID(2021-04-27 17:27:22.82
 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)
+ulids.take(5)
 #=>
 #[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-28 20:17:55.357 UTC: 01F4D231MXQJXAR8G2JZHEJNH3)]
+ULID.sample(5, 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)]
+#  ULID(2021-04-29 21:38:58.109 UTC: 01F4FS45DX4049JEQK4W6TER6G)]
 ```
 
-### ULID specification ambiguity around orthographical variants of the format
+#### Variants of 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.
 
+>Case insensitive
+
+I can understand it might be considered in actual use-case. So `ULID.parse` accepts upcase and downcase.
+However it is a controversial point, discussing in [ulid/spec#3](https://github.com/ulid/spec/issues/3).
+
 >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 have suggested to clarify `subset of Crockford's base32` in [ulid/spec#57](https://github.com/ulid/spec/pull/57).
 
-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).
+This gem provides some methods to handle the nasty possibilities.
 
-Be that as it may, this gem provides API for handling the nasty possibilities.
-
-`ULID.normalize` and `ULID.normalized?`
+`ULID.normalize`, `ULID.normalized?`, `ULID.valid_as_variant_format?` and `ULID.parse_variant_format`
 
 ```ruby
-ULID.normalize('-olarz3-noekisv4rrff-q6ig5fav--') #=> "01ARZ3N0EK1SV4RRFFQ61G5FAV"
-ULID.normalized?('-olarz3-noekisv4rrff-q6ig5fav--') #=> false
-ULID.normalized?('01ARZ3N0EK1SV4RRFFQ61G5FAV') #=> true
+ULID.normalize('01g70y0y7g-z1xwdarexergsddd') #=> "01G70Y0Y7GZ1XWDAREXERGSDDD"
+ULID.normalized?('01g70y0y7g-z1xwdarexergsddd') #=> false
+ULID.normalized?('01G70Y0Y7GZ1XWDAREXERGSDDD') #=> true
+ULID.valid_as_variant_format?('01g70y0y7g-z1xwdarexergsddd') #=> true
+ULID.parse_variant_format('01G70Y0Y7G-ZLXWDIREXERGSDoD') #=> ULID(2022-07-03 02:25:22.672 UTC: 01G70Y0Y7GZ1XWD1REXERGSD0D)
 ```
 
-### UUIDv4 converter for migration use-cases
+#### UUIDv4 converter (experimental)
 
 `ULID.from_uuidv4` and `ULID#to_uuidv4` is the converter.
 The imported timestamp is meaningless. So ULID's benefit will lost.
@@ -387,56 +398,19 @@ ULID.min == reversed_min #=> false
 ULID.max == reversed_max #=> false
 ```
 
-## How to migrate from other gems
-
-As far as I know, major prior arts are below
-
-### [ulid gem](https://rubygems.org/gems/ulid) - [rafaelsales/ulid](https://github.com/rafaelsales/ulid)
-
-It is just providing basic `String` generator only.
-So you can replace the code as below
-
-```diff
--ULID.generate
-+ULID.generate.to_s
-```
-
-NOTE: In version before `1.3.0`, timestamps might not be correct value.
-
-1. [Sort order does not respect millisecond ordering](https://github.com/rafaelsales/ulid/issues/22)
-1. [Fixed in this PR](https://github.com/rafaelsales/ulid/pull/23)
-1. [Released in 1.3.0](https://github.com/rafaelsales/ulid/compare/1.2.0...v1.3.0)
-
-### [ulid-ruby gem](https://rubygems.org/gems/ulid-ruby) - [abachman/ulid-ruby](https://github.com/abachman/ulid-ruby)
-
-It is providing basic generator(except monotonic generator) and parser.
-Major methods can be replaced as below.
-
-```diff
--ULID.generate
-+ULID.generate.to_s
--ULID.at(time)
-+ULID.at(time).to_s
--ULID.time(string)
-+ULID.parse(string).to_time
--ULID.min_ulid_at(time)
-+ULID.min(time).to_s
--ULID.max_ulid_at(time)
-+ULID.max(time).to_s
-```
+## Migration from other gems
 
-NOTE: In version before `1.0.2`, timestamps might not be correct value.
+See [wiki page for gem migration](https://github.com/kachick/ruby-ulid/wiki/Gem-migration).
 
-1. [Parsed time object has more than milliseconds](https://github.com/abachman/ulid-ruby/issues/3)
-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)
-1. [Released in 1.0.2](https://github.com/abachman/ulid-ruby/compare/v1.0.0...v1.0.2)
+## RBS
 
-### Compare performance with them
+Try at [examples/rbs_sandbox](https://github.com/kachick/ruby-ulid/tree/main/examples/rbs_sandbox).
 
-See [Benchmark](https://github.com/kachick/ruby-ulid/wiki/Benchmark).
+I have checked the behavior with [ruby/rbs@2.6.0](https://github.com/ruby/rbs) + [soutaro/steep@1.0.1](https://github.com/soutaro/steep) +  [soutaro/steep-vscode](https://github.com/soutaro/steep-vscode).
 
-The results are not something to be proud of.
+* ![rbs overview](./assets/ulid-rbs-overview.png?raw=true.png)
+* ![rbs mix](./assets/ulid-rbs-mix.png?raw=true.png)
+* ![rbs ng-to_str](./assets/ulid-rbs-ng-to_str.png?raw=true.png)
 
 ## References
 
@@ -446,4 +420,5 @@ The results are not something to be proud of.
 
 ## 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)
+- [UUIDv6, UUIDv7, UUIDv8](https://www.ietf.org/archive/id/draft-peabody-dispatch-new-uuid-format-01.html) is another choice for sortable and randomness ID.  
+  However they are stayed in draft state. ref: [ruby-ulid#37](https://github.com/kachick/ruby-ulid/issues/37)

data/lib/ruby-ulid.rb

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

data/lib/ulid/crockford_base32.rb

@@ -1,5 +1,6 @@
 # coding: us-ascii
 # frozen_string_literal: true
+# shareable_constant_value: literal
 
 # Copyright (C) 2021 Kenichi Kamiya
 
@@ -14,10 +15,10 @@ class ULID
   #   * https://github.com/kachick/ruby-ulid/issues/57
   #   * https://github.com/kachick/ruby-ulid/issues/78
   module CrockfordBase32
-    class SetupError < ScriptError; end
+    class SetupError < UnexpectedError; end
 
     n32_chars = [*'0'..'9', *'A'..'V'].map(&:freeze).freeze
-    raise SetupError, 'obvious bug exists in the mapping algorithm' unless n32_chars.size == 32
+    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|
@@ -48,7 +49,7 @@ class ULID
         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
+    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
 

data/lib/ulid/monotonic_generator.rb

@@ -1,19 +1,23 @@
 # coding: us-ascii
 # frozen_string_literal: true
+# shareable_constant_value: literal
 
 # Copyright (C) 2021 Kenichi Kamiya
 
 class ULID
   class MonotonicGenerator
-    include MonitorMixin
+    # @note When use https://github.com/ko1/ractor-tvar might realize Ractor based thread safe monotonic generator.
+    #       However it is a C extention, I'm pending to use it for now.
+    include(MonitorMixin)
 
+    # @dynamic prev
     # @return [ULID, nil]
-    attr_reader :prev
+    attr_reader(:prev)
 
-    undef_method :instance_variable_set
+    undef_method(:instance_variable_set)
 
     def initialize
-      super()
+      super
       @prev = nil
     end
 
@@ -21,7 +25,8 @@ class ULID
     def inspect
       "ULID::MonotonicGenerator(prev: #{@prev.inspect})"
     end
-    alias_method :to_s, :inspect
+    # @dynamic to_s
+    alias_method(:to_s, :inspect)
 
     # @param [Time, Integer] moment
     # @return [ULID]
@@ -30,23 +35,25 @@ class ULID
     #   Basically will not happen. Just means this feature prefers error rather than invalid value.
     def generate(moment: ULID.current_milliseconds)
       synchronize do
-        unless @prev
-          @prev = ULID.generate(moment: moment)
-          return @prev
+        prev_ulid = @prev
+        unless prev_ulid
+          ret = ULID.generate(moment: moment)
+          @prev = ret
+          return ret
         end
 
         milliseconds = ULID.milliseconds_from_moment(moment)
 
         ulid = (
-          if @prev.milliseconds < milliseconds
+          if prev_ulid.milliseconds < milliseconds
             ULID.generate(moment: milliseconds)
           else
-            ULID.from_milliseconds_and_entropy(milliseconds: @prev.milliseconds, entropy: @prev.entropy.succ)
+            ULID.from_milliseconds_and_entropy(milliseconds: prev_ulid.milliseconds, entropy: prev_ulid.entropy.succ)
           end
         )
 
-        unless ulid > @prev
-          base_message = "monotonicity broken from unexpected reasons # generated: #{ulid.inspect}, prev: #{@prev.inspect}"
+        unless ulid > prev_ulid
+          base_message = "monotonicity broken from unexpected reasons # generated: #{ulid.inspect}, prev: #{prev_ulid.inspect}"
           additional_information = (
             if Thread.list == [Thread.main]
               '# NOTE: looks single thread only exist'
@@ -55,7 +62,7 @@ class ULID
             end
           )
 
-          raise UnexpectedError, base_message + additional_information
+          raise(UnexpectedError, base_message + additional_information)
         end
 
         @prev = ulid
@@ -63,12 +70,12 @@ class ULID
       end
     end
 
-    undef_method :freeze
+    undef_method(:freeze)
 
     # @raise [TypeError] always raises exception and does not freeze self
     # @return [void]
     def freeze
-      raise TypeError, "cannot freeze #{self.class}"
+      raise(TypeError, "cannot freeze #{self.class}")
     end
   end
 end

data/lib/ulid/ractor_unshareable_constants.rb

@@ -0,0 +1,12 @@
+# coding: us-ascii
+# frozen_string_literal: true
+
+class ULID
+  min = parse('00000000000000000000000000').freeze
+  max = parse('7ZZZZZZZZZZZZZZZZZZZZZZZZZ').freeze
+
+  ractor_can_make_shareable_time = RUBY_VERSION >= '3.1'
+
+  MIN = ractor_can_make_shareable_time ? Ractor.make_shareable(min) : min
+  MAX = ractor_can_make_shareable_time ? Ractor.make_shareable(max) : max
+end

data/lib/ulid/uuid.rb

@@ -1,5 +1,6 @@
 # coding: us-ascii
 # frozen_string_literal: true
+# shareable_constant_value: literal
 
 # Copyright (C) 2021 Kenichi Kamiya
 
@@ -10,18 +11,18 @@
 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
+  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
+    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}`"
+      raise(ParserError, "given `#{uuid}` does not match to `#{UUIDV4_PATTERN.inspect}`")
     end
 
     normalized = prefix_trimmed.gsub(/[^0-9A-Fa-f]/, '')
@@ -32,8 +33,11 @@ class ULID
   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
+    ref2, ref3 = array[2], array[3]
+    raise unless Integer === ref2 && Integer === ref3
+
+    array[2] = (ref2 & 0x0fff) | 0x4000
+    array[3] = (ref3 & 0x3fff) | 0x8000
     ('%08x-%04x-%04x-%04x-%04x%08x' % array).freeze
   end
 end

data/lib/ulid/version.rb

@@ -1,6 +1,7 @@
 # coding: us-ascii
 # frozen_string_literal: true
+# shareable_constant_value: literal
 
 class ULID
-  VERSION = '0.2.2'
+  VERSION = '0.5.0'
 end

data/lib/ulid.rb

@@ -1,9 +1,10 @@
 # coding: us-ascii
 # frozen_string_literal: true
+# shareable_constant_value: experimental_everything
 
 # Copyright (C) 2021 Kenichi Kamiya
 
-require 'securerandom'
+require('securerandom')
 
 # @see https://github.com/ulid/spec
 # @!attribute [r] milliseconds
@@ -11,7 +12,7 @@ require 'securerandom'
 # @!attribute [r] entropy
 #   @return [Integer]
 class ULID
-  include Comparable
+  include(Comparable)
 
   class Error < StandardError; end
   class OverflowError < Error; end
@@ -25,10 +26,12 @@ class ULID
 
   TIMESTAMP_ENCODED_LENGTH = 10
   RANDOMNESS_ENCODED_LENGTH = 16
-  ENCODED_LENGTH = TIMESTAMP_ENCODED_LENGTH + RANDOMNESS_ENCODED_LENGTH
+  ENCODED_LENGTH = 26
+
   TIMESTAMP_OCTETS_LENGTH = 6
   RANDOMNESS_OCTETS_LENGTH = 10
-  OCTETS_LENGTH = TIMESTAMP_OCTETS_LENGTH + RANDOMNESS_OCTETS_LENGTH
+  OCTETS_LENGTH = 16
+
   MAX_MILLISECONDS = 281474976710655
   MAX_ENTROPY = 1208925819614629174706175
   MAX_INTEGER = 340282366920938463463374607431768211455
@@ -40,14 +43,15 @@ class ULID
   STRICT_PATTERN_WITH_CROCKFORD_BASE32_SUBSET = /\A#{PATTERN_WITH_CROCKFORD_BASE32_SUBSET.source}\z/i.freeze
 
   # Optimized for `ULID.scan`, might be changed the definition with gathered `ULID.scan` spec changed.
-  # This can't contain `\b` for considering UTF-8 (e.g. Japanese), so intentional `false negative` definition.
-  SCANNING_PATTERN = /[0-7][#{CROCKFORD_BASE32_ENCODING_STRING}]{#{TIMESTAMP_ENCODED_LENGTH - 1}}[#{CROCKFORD_BASE32_ENCODING_STRING}]{#{RANDOMNESS_ENCODED_LENGTH}}/i.freeze
+  SCANNING_PATTERN = /\b[0-7][#{CROCKFORD_BASE32_ENCODING_STRING}]{#{TIMESTAMP_ENCODED_LENGTH - 1}}[#{CROCKFORD_BASE32_ENCODING_STRING}]{#{RANDOMNESS_ENCODED_LENGTH}}\b/i.freeze
 
-  # Same as Time#inspect since Ruby 2.7, just to keep backward compatibility
+  # Similar as Time#inspect since Ruby 2.7, however it is NOT same.
+  # Time#inspect trancates needless digits. Keeping full milliseconds with "%3N" will fit for ULID.
   # @see https://bugs.ruby-lang.org/issues/15958
+  # @see https://github.com/ruby/ruby/blob/744d17ff6c33b09334508e8110007ea2a82252f5/time.c#L4026-L4078
   TIME_FORMAT_IN_INSPECT = '%Y-%m-%d %H:%M:%S.%3N %Z'
 
-  private_class_method :new
+  private_class_method(:new)
 
   # @param [Integer, Time] moment
   # @param [Integer] entropy
@@ -60,7 +64,7 @@ class ULID
   # @param [Time] time
   # @return [ULID]
   def self.at(time)
-    raise ArgumentError, 'ULID.at takes only `Time` instance' unless Time === 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
@@ -79,7 +83,7 @@ class ULID
 
   RANDOM_INTEGER_GENERATOR = -> {
     SecureRandom.random_number(MAX_INTEGER)
-  }
+  }.freeze
 
   # @param [Range<Time>, Range<nil>, Range[ULID], nil] period
   # @overload sample(number, period: nil)
@@ -92,14 +96,14 @@ class ULID
   #   * Do not ensure the uniqueness
   #   * Do not take random generator for the arguments
   #   * Raising error instead of truncating elements for the given number
-  def self.sample(*args, period: nil)
+  def self.sample(number=nil, 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?
 
         possibilities = (max - min) + (exclude_end ? 0 : 1)
-        raise ArgumentError, "given range `#{ulid_range.inspect}` does not have possibilities" unless possibilities.positive?
+        raise(ArgumentError, "given range `#{ulid_range.inspect}` does not have possibilities") unless possibilities.positive?
 
         -> {
           SecureRandom.random_number(possibilities) + min
@@ -109,24 +113,21 @@ class ULID
       end
     )
 
-    case args.size
-    when 0
+    case number
+    when nil
       from_integer(int_generator.call)
-    when 1
-      number = args.first
-      raise ArgumentError, 'accepts no argument or integer only' unless Integer === number
-
+    when Integer
       if number > MAX_INTEGER || number.negative?
-        raise ArgumentError, "given number `#{number}` is larger than ULID limit `#{MAX_INTEGER}` or negative"
+        raise(ArgumentError, "given number `#{number}` is larger than ULID limit `#{MAX_INTEGER}` or negative")
       end
 
-      if period && (number > possibilities)
-        raise ArgumentError, "given number `#{number}` is larger than given possibilities `#{possibilities}`"
+      if period && possibilities && (number > possibilities)
+        raise(ArgumentError, "given number `#{number}` is larger than given possibilities `#{possibilities}`")
       end
 
       Array.new(number) { from_integer(int_generator.call) }
     else
-      raise ArgumentError, "wrong number of arguments (given #{args.size}, expected 0..1)"
+      raise(ArgumentError, 'accepts no argument or integer only')
     end
   end
 
@@ -136,11 +137,13 @@ class ULID
   # @yieldreturn [self]
   def self.scan(string)
     string = String.try_convert(string)
-    raise ArgumentError, 'ULID.scan takes only strings' unless string
-    return to_enum(__callee__, string) unless block_given?
+    raise(ArgumentError, 'ULID.scan takes only strings') unless string
+    return to_enum(:scan, string) unless block_given?
 
     string.scan(SCANNING_PATTERN) do |matched|
-      yield parse(matched)
+      if String === matched
+        yield(parse(matched))
+      end
     end
     self
   end
@@ -150,14 +153,16 @@ class ULID
   # @raise [OverflowError] if the given integer is larger than the ULID limit
   # @raise [ArgumentError] if the given integer is negative number
   def self.from_integer(integer)
-    raise ArgumentError, 'ULID.from_integer takes only `Integer`' unless Integer === integer
-    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?
+    raise(ArgumentError, 'ULID.from_integer takes only `Integer`') unless Integer === integer
+    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?
 
     n32encoded = integer.to_s(32).rjust(ENCODED_LENGTH, '0')
     n32encoded_timestamp = n32encoded.slice(0, TIMESTAMP_ENCODED_LENGTH)
     n32encoded_randomness = n32encoded.slice(TIMESTAMP_ENCODED_LENGTH, RANDOMNESS_ENCODED_LENGTH)
 
+    raise(UnexpectedError) unless n32encoded_timestamp && n32encoded_randomness
+
     milliseconds = n32encoded_timestamp.to_i(32)
     entropy = n32encoded_randomness.to_i(32)
 
@@ -168,37 +173,43 @@ class ULID
   # @return [Range<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
+    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
-
-    case begin_element
-    when Time
-      begin_ulid = min(begin_element)
-    when nil
-      begin_ulid = MIN
-    when self
-      begin_ulid = begin_element
-    else
-      raise ArgumentError, "ULID.range takes only `Range[Time]`, `Range[nil]` or `Range[ULID]`, given: #{period.inspect}"
-    end
+    new_begin, new_end = false, false
+
+    begin_ulid = (
+      case begin_element
+      when Time
+        new_begin = true
+        min(begin_element)
+      when nil
+        MIN
+      when self
+        begin_element
+      else
+        raise(ArgumentError, "ULID.range takes only `Range[Time]`, `Range[nil]` or `Range[ULID]`, given: #{period.inspect}")
+      end
+    )
 
-    case end_element
-    when Time
-      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
-      exclude_end = false
-    when self
-      end_ulid = end_element
-    else
-      raise ArgumentError, "ULID.range takes only `Range[Time]`, `Range[nil]` or `Range[ULID]`, given: #{period.inspect}"
-    end
+    end_ulid = (
+      case end_element
+      when Time
+        new_end = true
+        exclude_end ? min(end_element) : max(end_element)
+      when nil
+        exclude_end = false
+        # The end should be max and include end, because nil end means to cover endless ULIDs until the limit
+        MAX
+      when self
+        end_element
+      else
+        raise(ArgumentError, "ULID.range takes only `Range[Time]`, `Range[nil]` or `Range[ULID]`, given: #{period.inspect}")
+      end
+    )
 
-    begin_ulid.freeze
-    end_ulid.freeze
+    begin_ulid.freeze if new_begin
+    end_ulid.freeze if new_end
 
     Range.new(begin_ulid, end_ulid, exclude_end)
   end
@@ -206,7 +217,7 @@ class ULID
   # @param [Time] time
   # @return [Time]
   def self.floor(time)
-    raise ArgumentError, 'ULID.floor takes only `Time` instance' unless Time === time
+    raise(ArgumentError, 'ULID.floor takes only `Time` instance') unless Time === time
 
     time.floor(3)
   end
@@ -234,7 +245,7 @@ class ULID
     when Time
       milliseconds_from_time(moment)
     else
-      raise ArgumentError, '`moment` should be a `Time` or `Integer as milliseconds`'
+      raise(ArgumentError, '`moment` should be a `Time` or `Integer as milliseconds`')
     end
   end
 
@@ -248,39 +259,67 @@ class ULID
   # @raise [ParserError] if the given format is not correct for ULID specs
   def self.parse(string)
     string = String.try_convert(string)
-    raise ArgumentError, 'ULID.parse takes only strings' unless string
+    raise(ArgumentError, 'ULID.parse takes only strings') unless string
 
     unless STRICT_PATTERN_WITH_CROCKFORD_BASE32_SUBSET.match?(string)
-      raise ParserError, "given `#{string}` does not match to `#{STRICT_PATTERN_WITH_CROCKFORD_BASE32_SUBSET.inspect}`"
+      raise(ParserError, "given `#{string}` does not match to `#{STRICT_PATTERN_WITH_CROCKFORD_BASE32_SUBSET.inspect}`")
     end
 
     from_integer(CrockfordBase32.decode(string))
   end
 
+  # @param [String, #to_str] string
+  # @return [ULID]
+  # @raise [ParserError] if the given format is not correct for ULID specs
+  def self.parse_variant_format(string)
+    string = String.try_convert(string)
+    raise(ArgumentError, 'ULID.parse_variant_format takes only strings') unless string
+
+    normalized_in_crockford = CrockfordBase32.normalize(string)
+    parse(normalized_in_crockford)
+  end
+
   # @param [String, #to_str] 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
+    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
+    parse_variant_format(string).to_s
   end
 
+  # @param [String, #to_str] string
   # @return [Boolean]
-  def self.normalized?(object)
-    normalized = normalize(object)
+  def self.normalized?(string)
+    normalized = normalize(string)
   rescue Exception
     false
   else
-    normalized == object
+    normalized == string
   end
 
+  # @param [String, #to_str] string
   # @return [Boolean]
-  def self.valid?(object)
-    string = String.try_convert(object)
+  def self.valid_as_variant_format?(string)
+    normalize(string)
+  rescue Exception
+    false
+  else
+    true
+  end
+
+  # @deprecated Use [.valid_as_variant_format?] or [.normalized?] instead
+  #
+  # Returns `true` if it is normalized string.
+  # Basically the difference of normalized? is to accept downcase or not. This returns true for downcased ULIDs.
+  #
+  # @return [Boolean]
+  def self.valid?(string)
+    warn_kwargs = (RUBY_VERSION >= '3.0') ? { category: :deprecated } : {}
+    Warning.warn('ULID.valid? is deprecated. Use ULID.valid_as_variant_format? or ULID.normalized? instead.', **warn_kwargs)
+    string = String.try_convert(string)
     string ? STRICT_PATTERN_WITH_CROCKFORD_BASE32_SUBSET.match?(string) : false
   end
 
@@ -298,7 +337,7 @@ class ULID
       else
         object_class_name = safe_get_class_name(object)
         converted_class_name = safe_get_class_name(converted)
-        raise TypeError, "can't convert #{object_class_name} to ULID (#{object_class_name}#to_ulid gives #{converted_class_name})"
+        raise(TypeError, "can't convert #{object_class_name} to ULID (#{object_class_name}#to_ulid gives #{converted_class_name})")
       end
     end
   end
@@ -314,8 +353,12 @@ class ULID
       begin
         object.class
       rescue NoMethodError
+        # steep can't correctly handle singleton class assign. See https://github.com/soutaro/steep/pull/586 for further detail
+        # So this annotation is hack for the type infer.
+        # @type var object: BasicObject
+        # @type var singleton_class: untyped
         singleton_class = class << object; self; end
-        singleton_class.ancestors.detect { |ancestor| !ancestor.equal?(singleton_class) }
+        (Class === singleton_class) ? singleton_class.ancestors.detect { |ancestor| !ancestor.equal?(singleton_class) } : fallback
       end
     )
 
@@ -335,10 +378,10 @@ class ULID
   # @raise [OverflowError] if the given value is larger than the ULID limit
   # @raise [ArgumentError] if the given milliseconds and/or entropy is negative number
   def self.from_milliseconds_and_entropy(milliseconds:, entropy:)
-    raise ArgumentError, 'milliseconds and entropy should be an `Integer`' unless Integer === milliseconds && Integer === entropy
-    raise OverflowError, "timestamp overflow: given #{milliseconds}, max: #{MAX_MILLISECONDS}" unless milliseconds <= MAX_MILLISECONDS
-    raise OverflowError, "entropy overflow: given #{entropy}, max: #{MAX_ENTROPY}" unless entropy <= MAX_ENTROPY
-    raise ArgumentError, 'milliseconds and entropy should not be negative' if milliseconds.negative? || entropy.negative?
+    raise(ArgumentError, 'milliseconds and entropy should be an `Integer`') unless Integer === milliseconds && Integer === entropy
+    raise(OverflowError, "timestamp overflow: given #{milliseconds}, max: #{MAX_MILLISECONDS}") unless milliseconds <= MAX_MILLISECONDS
+    raise(OverflowError, "entropy overflow: given #{entropy}, max: #{MAX_ENTROPY}") unless entropy <= MAX_ENTROPY
+    raise(ArgumentError, 'milliseconds and entropy should not be negative') if milliseconds.negative? || entropy.negative?
 
     n32encoded_timestamp = milliseconds.to_s(32).rjust(TIMESTAMP_ENCODED_LENGTH, '0')
     n32encoded_randomness = entropy.to_s(32).rjust(RANDOMNESS_ENCODED_LENGTH, '0')
@@ -347,7 +390,8 @@ class ULID
     new(milliseconds: milliseconds, entropy: entropy, integer: integer)
   end
 
-  attr_reader :milliseconds, :entropy
+  # @dynamic milliseconds, entropy
+  attr_reader(:milliseconds, :entropy)
 
   # @api private
   # @param [Integer] milliseconds
@@ -376,7 +420,7 @@ class ULID
     [ULID, @integer].hash
   end
 
-  # @return [Integer, nil]
+  # @return [-1, 0, 1, nil]
   def <=>(other)
     (ULID === other) ? (@integer <=> other.to_i) : nil
   end
@@ -390,15 +434,29 @@ class ULID
   def eql?(other)
     equal?(other) || (ULID === other && @integer == other.to_i)
   end
-  alias_method :==, :eql?
+  # @dynamic ==
+  alias_method(:==, :eql?)
 
+  # Return `true` for same value of ULID, variant formats of strings, same Time in ULID precision(msec).
+  # Do not consider integer, octets and partial strings, then returns `false`.
+  #
   # @return [Boolean]
+  # @see .normalize
+  # @see .floor
   def ===(other)
     case other
     when ULID
       @integer == other.to_i
     when String
-      to_s == other.upcase
+      begin
+        normalized = ULID.normalize(other)
+      rescue Exception
+        false
+      else
+        to_s == normalized
+      end
+    when Time
+      to_time == ULID.floor(other)
     else
       false
     end
@@ -420,22 +478,22 @@ class ULID
 
   # @return [Array(Integer, Integer, Integer, Integer, Integer, Integer)]
   def timestamp_octets
-    octets.slice(0, TIMESTAMP_OCTETS_LENGTH)
+    octets.slice(0, TIMESTAMP_OCTETS_LENGTH) || raise(UnexpectedError)
   end
 
   # @return [Array(Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer)]
   def randomness_octets
-    octets.slice(TIMESTAMP_OCTETS_LENGTH, RANDOMNESS_OCTETS_LENGTH)
+    octets.slice(TIMESTAMP_OCTETS_LENGTH, RANDOMNESS_OCTETS_LENGTH) || raise(UnexpectedError)
   end
 
   # @return [String]
   def timestamp
-    @timestamp ||= to_s.slice(0, TIMESTAMP_ENCODED_LENGTH).freeze
+    @timestamp ||= (to_s.slice(0, TIMESTAMP_ENCODED_LENGTH).freeze || raise(UnexpectedError))
   end
 
   # @return [String]
   def randomness
-    @randomness ||= to_s.slice(TIMESTAMP_ENCODED_LENGTH, RANDOMNESS_ENCODED_LENGTH).freeze
+    @randomness ||= (to_s.slice(TIMESTAMP_ENCODED_LENGTH, RANDOMNESS_ENCODED_LENGTH).freeze || raise(UnexpectedError))
   end
 
   # @note Providing for rough operations. The keys and values is not fixed.
@@ -461,7 +519,8 @@ class ULID
       ULID.from_integer(succ_int)
     end
   end
-  alias_method :next, :succ
+  # @dynamic next
+  alias_method(:next, :succ)
 
   # @return [ULID, nil] when called on ULID as `00000000000000000000000000`, returns `nil` instead of ULID
   def pred
@@ -513,7 +572,7 @@ class ULID
     self
   end
 
-  undef_method :instance_variable_set
+  undef_method(:instance_variable_set)
 
   private
 
@@ -525,13 +584,12 @@ class ULID
   end
 end
 
-require_relative 'ulid/version'
-require_relative 'ulid/crockford_base32'
-require_relative 'ulid/monotonic_generator'
+require_relative('ulid/version')
+require_relative('ulid/crockford_base32')
+require_relative('ulid/monotonic_generator')
+require_relative('ulid/ractor_unshareable_constants')
 
 class ULID
-  MIN = parse('00000000000000000000000000').freeze
-  MAX = parse('7ZZZZZZZZZZZZZZZZZZZZZZZZZ').freeze
-
-  private_constant :TIME_FORMAT_IN_INSPECT, :MIN, :MAX, :RANDOM_INTEGER_GENERATOR
+  # Do not write as `ULID.private_constant` for avoiding YARD warnings `[warn]: in YARD::Handlers::Ruby::PrivateConstantHandler: Undocumentable private constants:`
+  private_constant(:TIME_FORMAT_IN_INSPECT, :MIN, :MAX, :RANDOM_INTEGER_GENERATOR, :CROCKFORD_BASE32_ENCODING_STRING)
 end

data/sig/ulid.rbs

@@ -36,7 +36,7 @@ class ULID < Object
   end
 
   module CrockfordBase32
-    class SetupError < ScriptError
+    class SetupError < UnexpectedError
     end
 
     N32_CHAR_BY_CROCKFORD_BASE32_CHAR: Hash[String, String]
@@ -97,9 +97,9 @@ class ULID < Object
     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 full_octets = [Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer] | Array[Integer]
+  type timestamp_octets = [Integer, Integer, Integer, Integer, Integer, Integer] | Array[Integer]
+  type randomness_octets = [Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer] | Array[Integer]
   type period = Range[Time] | Range[nil] | Range[ULID]
 
   @string: String?
@@ -213,6 +213,21 @@ class ULID < Object
   # ```
   def self.parse: (_ToStr string) -> ULID
 
+  # Get ULID instance from unnormalized String that encoded in Crockford's base32.
+  #
+  # http://www.crockford.com/base32.html
+  #
+  # * Ignore Hyphens (-)
+  # * Mapping 0 O o => 0, 1 I i L l => 1
+  #
+  # ```ruby
+  # ulid = ULID.parse_variant_format('01G70Y0Y7G-ZLXWDIREXERGSDoD')
+  # #=> ULID(2022-07-03 02:25:22.672 UTC: 01G70Y0Y7GZ1XWD1REXERGSD0D)
+  # ```
+  #
+  # 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.parse_variant_format: (_ToStr string) -> ULID
+
   # ```ruby
   # # Currently experimental feature, so needed to load the extension.
   # require 'ulid/uuid'
@@ -292,41 +307,30 @@ class ULID < Object
   # 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)
+  # ulids.take(5)
   # #=>
   # #[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(2021-04-28 20:17:55.357 UTC: 01F4D231MXQJXAR8G2JZHEJNH3)]
   # 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)]
+  # #  ULID(2021-04-29 21:38:58.109 UTC: 01F4FS45DX4049JEQK4W6TER6G)]
   # ```
   def self.sample: (?period: period) -> ULID
-                 | (Integer number, ?period: period) -> Array[ULID]
-  def self.valid?: (untyped) -> bool
+                 | (Integer number, ?period: period?) -> Array[ULID]
 
   # Returns normalized string
   #
   # ```ruby
+  # ULID.normalize('01G70Y0Y7G-Z1XWDAREXERGSDDD') #=> "01G70Y0Y7GZ1XWDAREXERGSDDD"
   # ULID.normalize('-olarz3-noekisv4rrff-q6ig5fav--') #=> "01ARZ3N0EK1SV4RRFFQ61G5FAV"
-  # ULID.normalized?('-olarz3-noekisv4rrff-q6ig5fav--') #=> false
-  # ULID.normalized?('01ARZ3N0EK1SV4RRFFQ61G5FAV') #=> true
+  # ULID.normalize('01G70Y0Y7G_Z1XWDAREXERGSDDD') #=> ULID::ParserError
   # ```
   #
   # See also [ulid/spec#57](https://github.com/ulid/spec/pull/57) and [ulid/spec#3](https://github.com/ulid/spec/issues/3)
@@ -335,13 +339,40 @@ class ULID < Object
   # Returns `true` if it is normalized string
   #
   # ```ruby
-  # ULID.normalize('-olarz3-noekisv4rrff-q6ig5fav--') #=> "01ARZ3N0EK1SV4RRFFQ61G5FAV"
-  # ULID.normalized?('-olarz3-noekisv4rrff-q6ig5fav--') #=> false
-  # ULID.normalized?('01ARZ3N0EK1SV4RRFFQ61G5FAV') #=> true
+  # ULID.normalized?('01G70Y0Y7GZ1XWDAREXERGSDDD') #=> true
+  # ULID.normalized?('01G70Y0Y7G-Z1XWDAREXERGSDDD') #=> false
+  # ULID.normalized?(ULID.generate.to_s.downcase) #=> false
+  # ULID.normalized?('01G70Y0Y7G_Z1XWDAREXERGSDDD') #=> false (Not raising ULID::ParserError)
+  # ```
+  #
+  # 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?: (_ToStr string) -> bool
+                      | (untyped) -> false
+
+  # Returns `true` if it is valid in ULID format variants
+  #
+  # ```ruby
+  # ULID.valid_as_variant_format?(ULID.generate.to_s.downcase) #=> true
+  # ULID.valid_as_variant_format?('01G70Y0Y7G-Z1XWDAREXERGSDDD') #=> true
+  # ULID.valid_as_variant_format?('01G70Y0Y7G_Z1XWDAREXERGSDDD') #=> false
   # ```
   #
   # 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
+  def self.valid_as_variant_format?: (_ToStr string) -> bool
+                             | (untyped) -> false
+
+  # DEPRECATED Use valid_as_variant_format? instead
+  #
+  # Returns `true` if it is normalized string.
+  # Basically the difference of normalized? is to accept downcase or not. This returns true for downcased ULIDs.
+  #
+  # ```ruby
+  # ULID.valid?(ULID.generate.to_s.downcase) #=> 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.valid?: (_ToStr string) -> bool
+                 | (untyped) -> false
 
   # Returns parsed ULIDs from given String for rough operations.
   #
@@ -409,7 +440,9 @@ class ULID < Object
   # ulid.to_i #=> 1957909092946624190749577070267409738
   # ```
   def to_i: -> Integer
-  alias hash to_i
+
+  # Returns integer for making as a hash key use-case
+  def hash: -> Integer
 
   # Basically same as String based sort.
   #
@@ -419,7 +452,12 @@ class ULID < Object
   # #=> 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.
+  # 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.
+  #
+  # This returns -1 | 0 | 1 for ULIDs. However defined as returning Integer. It is caused on ruby/rbs current definition.
+  #   https://github.com/ruby/ruby/blob/cd34f56d450f2310cceaf4c5f34d23eddfda58e8/numeric.c#L4646-L4660
+  #   https://github.com/ruby/rbs/blob/14abbbae8885a09a2ed82de2ef31d67a9c0a108d/core/integer.rbs#L461-L462
   #
   def <=>: (ULID other) -> Integer
          | (untyped other) -> nil
@@ -434,9 +472,28 @@ class ULID < Object
   # ULID.parse('4NNB20D9C1ME2NGMTX51ERZJX0') == ULID.parse('4nnb20d9c1me2ngmtx51erzjx0')
   # #=> true
   # ```
-  def eql?: (untyped other) -> bool
+  def eql?: (ULID other) -> bool
+          | (untyped other) -> false
   alias == eql?
-  def ===: (untyped other) -> bool
+
+  # Return `true` for same value of ULID, variant formats of strings, same Time in ULID precision(msec).
+  # Do not consider integer, octets and partial strings, then returns `false`.
+  #
+  # ```ruby
+  # ulid = ULID.parse('01G6Z7Q4RSH97E6QHAC7VK19G2')
+  # ulid === ULID.parse(ulid.to_s)
+  # #=> true
+  # ulid === ulid.to_s.downcase
+  # #=> true
+  # ulid === ulid.to_time
+  # #=> true
+  # ulid === ulid.to_i
+  # #=> false
+  # ulid === ulid.next
+  # #=> false
+  # ```
+  def ===: (ULID | String | Time other) -> bool
+         | (untyped other) -> false
 
   # ```ruby
   # ulid = ULID.generate
@@ -462,7 +519,7 @@ class ULID < Object
   # 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 octets: -> full_octets
   def timestamp_octets: -> timestamp_octets
   def randomness_octets: -> randomness_octets
 
@@ -525,7 +582,7 @@ class ULID < Object
   private
 
   # A private API. Should not be used in your code.
-  def self.new: (milliseconds: Integer, entropy: Integer, integer: Integer) -> self
+  def self.new: (milliseconds: Integer, entropy: Integer, integer: Integer) -> ULID
 
   # A private API. Should not be used in your code.
   def self.reasonable_entropy: -> Integer

metadata

@@ -1,19 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: ruby-ulid
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.5.0
 platform: ruby
 authors:
 - Kenichi Kamiya
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-05-26 00:00:00.000000000 Z
+date: 2022-07-03 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.
-      Also providing `ruby/rbs` signature files.
+description: "    generator, optional monotonicity, parser and tools for ULID (RBS
+  included)\n"
 email:
 - kachick1+ruby@gmail.com
 executables: []
@@ -26,6 +24,7 @@ files:
 - lib/ulid.rb
 - lib/ulid/crockford_base32.rb
 - lib/ulid/monotonic_generator.rb
+- lib/ulid/ractor_unshareable_constants.rb
 - lib/ulid/uuid.rb
 - lib/ulid/version.rb
 - sig/ulid.rbs
@@ -46,7 +45,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 2.7.2
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="