ruby-ulid 0.6.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c7cf89034d0f74026278e2a4c113d57f8fc28b861b8bcf1d2210dbb76688e52
-  data.tar.gz: 340bfbea8fb1ff3ec0e49339e2a5a388a81552f8cd73a65ad9ff049448fc0c3f
+  metadata.gz: 323b750a4e11157bd492b31d74833df2042192775c8627917880ef386dee4c1c
+  data.tar.gz: 2dc8a91cbed7b473d6f9e28480dd227ab3469828ab0833f48a754111bd6e926c
 SHA512:
-  metadata.gz: 74d26cb5dc49a8d79a5c933817c1c8913954d675d996a91057f29859fd1fdf0a32c99d8121ef954e1d7d400110fa1737be17a9084bfc03655082de96c9614392
-  data.tar.gz: 96f19838c4c90ee313722857f88693e88f247e5380293291b362eadc834f6adb1613c01034a0cfe430f24576b4fea55f252b79f689b00c3e05b739118db8906e
+  metadata.gz: e78a5289863c1300a3f4c186b72a0f1d97cd709ce6043b69729d851f5e6ffcedac001e3bb691397d761ee497d609b5292c300db7f2ec3f8cf5be0ee5c095af80
+  data.tar.gz: e19197709d7a896a79c6ebdc40fa919c2e7876284fa1dbf8895498ad7b80e989634cdd3e651362db5cf9f7c627fe17439ccc21e75c8e6598b002da6b19858aa0

data/README.md

@@ -1,13 +1,14 @@
 # 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)
+[![Build Status](https://github.com/kachick/ruby-ulid/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/kachick/ruby-ulid/actions/workflows/ci.yml?query=branch%3Amain)
 [![Gem Version](https://badge.fury.io/rb/ruby-ulid.svg)](http://badge.fury.io/rb/ruby-ulid)
 
 ## Overview
 
-[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).
+[ulid/spec](https://github.com/ulid/spec) defines some useful features.\
+In particular, it has uniqueness, randomness, extractable timestamps, and sortability.\
+This gem aims to provide the generator, optional monotonicity, parser, and other manipulations around ULID.\
+[RBS](https://github.com/ruby/rbs) definitions are also included.
 
 ---
 
@@ -37,31 +38,22 @@ Instead, herein is proposed ULID:
 
 ### Install
 
-Require Ruby 2.7 or later
+Tested only in the last 2 Rubies. So you need Ruby 3.1 or higher.
 
-This command will install the latest version into your environment
-
-```console
-$ gem install ruby-ulid
-Should be installed!
-```
-
-Add this line in your Gemfile.
+Add this line to your `Gemfile`.
 
 ```ruby
-gem('ruby-ulid', '~> 0.6.1')
+gem('ruby-ulid', '~> 0.8.0')
 ```
 
-### How to use
+And load it.
 
 ```ruby
 require 'ulid'
-
-ULID::VERSION
-# => "0.6.1"
 ```
 
-NOTE: This README includes info about development version. If you would see released version's one. [Look at the ref](https://github.com/kachick/ruby-ulid/tree/v0.6.1).
+NOTE: This README contains information about the development version.\
+If you would like to see released version's one. [Look at the ref](https://github.com/kachick/ruby-ulid/tree/v0.8.0).
 
 ### Generator and Parser
 
@@ -77,7 +69,7 @@ ulid = ULID.generate #=> ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GR
 ulid = ULID.parse('01F4A5Y1YAQCYAYCTC7GRMJ9AA') #=> ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GRMJ9AA)
 ```
 
-It is helpful to inspect.
+It has inspector methods.
 
 ```ruby
 ulid.to_time #=> 2021-04-27 17:27:22.826 UTC
@@ -99,9 +91,9 @@ ULID.generate(moment: time) #=> ULID(2000-01-01 00:00:00.000 UTC: 00VHNCZB006WQT
 ULID.at(time) #=> ULID(2000-01-01 00:00:00.000 UTC: 00VHNCZB002W5BGWWKN76N22H6)
 ```
 
-Also `ULID.encode` and `ULID.decode_time` can be used to get primitive values for most usecases.  
+Also `ULID.encode` and `ULID.decode_time` can be used to get primitive values for most usecases.
 
-`ULID.encode` returns [normalized](#variants-of-format) String without ULID object creation.  
+`ULID.encode` returns [normalized](#variants-of-format) String without ULID object creation.\
 It can take same arguments as `ULID.generate`.
 
 ```ruby
@@ -116,17 +108,17 @@ ULID.decode_time('00VHNCZB00SYG7RCEXZC9DA4E1') #=> 2000-01-01 00:00:00 UTC
 ULID.decode_time('00VHNCZB00SYG7RCEXZC9DA4E1', in: '+09:00') #=> 2000-01-01 09:00:00 +0900
 ```
 
-This project does not prioritize the speed. However it actually works faster than others! :zap:
+This project does not prioritize on the speed. However it actually works faster than others! :zap:
 
-Snapshot on 0.6.1 is below
+Snapshot on v0.8.0 with Ruby 3.2.1 is below
 
-* Generator is 1.5x faster than - [ulid gem](https://github.com/rafaelsales/ulid)
-* Generator is 1.9x faster than - [ulid-ruby gem](https://github.com/abachman/ulid-ruby)
-* Parser is 2.7x faster than - [ulid-ruby gem](https://github.com/abachman/ulid-ruby)
+- Generator is 1.9x faster than - [ulid gem - v1.4.0](https://github.com/rafaelsales/ulid)
+- Generator is 2.0x faster than - [ulid-ruby gem - v1.0.2](https://github.com/abachman/ulid-ruby)
+- Parser is 3.1x faster than - [ulid-ruby gem - v1.0.2](https://github.com/abachman/ulid-ruby)
 
 You can see further detail at [Benchmark](https://github.com/kachick/ruby-ulid/wiki/Benchmark).
 
-### Sortable with the timestamp
+### Sortable by timestamp
 
 ULIDs are sortable when they are generated in different timestamp with milliseconds precision.
 
@@ -139,7 +131,7 @@ ulids.uniq(&:to_time).size #=> 1000
 ulids.sort == ulids #=> true
 ```
 
-Basic generator prefers `randomness`, it does not guarantee `sortable` for same milliseconds ULIDs.
+The basic generator prefers `randomness`, the results in the same milliseconds are not sortable.
 
 ```ruby
 ulids = 10000.times.map do
@@ -151,8 +143,9 @@ ulids.sort == ulids #=> false
 
 ### How to keep `Sortable` even if in same timestamp
 
-If you want to prefer `sortable`, Use `MonotonicGenerator` instead. It is called as [Monotonicity](https://github.com/ulid/spec/tree/d0c7170df4517939e70129b4d6462cc162f2d5bf#monotonicity) on the spec.
-(Though it starts with new random value when changed the timestamp)
+If you prefer `sortability`, you can use `MonotonicGenerator` instead.\
+It is referred to as [Monotonicity](https://github.com/ulid/spec/tree/d0c7170df4517939e70129b4d6462cc162f2d5bf#monotonicity) in the spec.\
+(Although it starts with a new random value when the timestamp is changed)
 
 ```ruby
 monotonic_generator = ULID::MonotonicGenerator.new
@@ -163,20 +156,16 @@ sample_ulids_by_the_time = ulids.uniq(&:to_time)
 sample_ulids_by_the_time.size #=> 32 (the size is not fixed, might be changed in environment)
 
 # In same milliseconds creation, it just increments the end of randomness part
-ulids.take(5) #=>
+ulids.take(3) #=>
 # [ULID(2021-05-02 15:23:48.917 UTC: 01F4PTVCSN9ZPFKYTY2DDJVRK4),
 #  ULID(2021-05-02 15:23:48.917 UTC: 01F4PTVCSN9ZPFKYTY2DDJVRK5),
-#  ULID(2021-05-02 15:23:48.917 UTC: 01F4PTVCSN9ZPFKYTY2DDJVRK6),
-#  ULID(2021-05-02 15:23:48.917 UTC: 01F4PTVCSN9ZPFKYTY2DDJVRK7),
-#  ULID(2021-05-02 15:23:48.917 UTC: 01F4PTVCSN9ZPFKYTY2DDJVRK8)]
+#  ULID(2021-05-02 15:23:48.917 UTC: 01F4PTVCSN9ZPFKYTY2DDJVRK6)]
 
 # When the milliseconds is updated, it starts with new randomness
-sample_ulids_by_the_time.take(5) #=>
+sample_ulids_by_the_time.take(3) #=>
 # [ULID(2021-05-02 15:23:48.917 UTC: 01F4PTVCSN9ZPFKYTY2DDJVRK4),
 #  ULID(2021-05-02 15:23:48.918 UTC: 01F4PTVCSPF2KXG4ABT7CK3204),
-#  ULID(2021-05-02 15:23:48.919 UTC: 01F4PTVCSQF1GERBPCQV6TCX2K),
-#  ULID(2021-05-02 15:23:48.920 UTC: 01F4PTVCSRBXN2H4P1EYWZ27AK),
-#  ULID(2021-05-02 15:23:48.921 UTC: 01F4PTVCSSK0ASBBZARV7013F8)]
+#  ULID(2021-05-02 15:23:48.919 UTC: 01F4PTVCSQF1GERBPCQV6TCX2K)]
 
 ulids.sort == ulids #=> true
 ```
@@ -195,7 +184,7 @@ 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.
+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
@@ -265,18 +254,6 @@ ULID.scan(json).to_a
 #  ULID(2021-04-30 05:53:12.478 UTC: 01F4GND4RYYSKNAADHQ9BNXAWJ)]
 ```
 
-`ULID#patterns` is a util for text based operations.
-The results and spec are not fixed. Should not be used except snippets/console operation.
-
-```ruby
-ULID.parse('01F4GNBXW1AM2KWW52PVT3ZY9X').patterns
-#=> returns like a fallowing Hash
-{
-  named_captures: /(?<timestamp>01F4GNBXW1)(?<randomness>AM2KWW52PVT3ZY9X)/i,
-  strict_named_captures: /\A(?<timestamp>01F4GNBXW1)(?<randomness>AM2KWW52PVT3ZY9X)\z/i
-}
-```
-
 #### Get boundary ULIDs
 
 `ULID.min` and `ULID.max` return termination values for ULID spec.
@@ -294,7 +271,7 @@ 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.
+`ULID#next` and `ULID#succ` returns next(successor) ULID.\
 Especially `ULID#succ` makes it possible `Range[ULID]#each`.
 
 NOTE: However basically `Range[ULID]#each` should not be used. Incrementing 128 bits IDs are not reasonable operation in most cases.
@@ -324,13 +301,11 @@ 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.sample(3)
 #=>
 #[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)]
+# ULID(10408-10-05 17:06:27.848 UTC: 7J6CPTEEC86Y24EQ4F1Y93YYN0)]
 ```
 
 You can specify a range object for the timestamp restriction, see also `ULID.range`.
@@ -338,37 +313,31 @@ You can specify a range object for the timestamp restriction, see also `ULID.ran
 ```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(5)
+ulids = ULID.sample(3, period: ulid1..ulid2)
 #=>
 #[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.sample(5, period: ulid1.to_time..ulid2.to_time)
+# ULID(2021-05-01 06:16:35.791 UTC: 01F4K94P6F6P68K0H64WRDSFKW)]
+ULID.sample(3, 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-05-02 12:45:28.408 UTC: 01F4PHSEYRG9BWBEWMRW1XE6WW)]
 ```
 
 #### 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
+> Case insensitive
 
-I can understand it might be considered in actual use-case. So `ULID.parse` accepts upcase and downcase.
+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)
+> 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 (-)`.
+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.
 
 I have suggested to clarify `subset of Crockford's base32` in [ulid/spec#57](https://github.com/ulid/spec/pull/57).
@@ -385,37 +354,40 @@ 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 (experimental)
-
-`ULID.from_uuidv4` and `ULID#to_uuidv4` is the converter.
-The imported timestamp is meaningless. So ULID's benefit will lost.
-
-```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"
+#### UUID
 
-uuid_v4s = 10000.times.map { SecureRandom.uuid }
-uuid_v4s.uniq.size == 10000 #=> Probably `true`
+Both ULID and UUID are 128-bit IDs. But with different specs. Especially UUID has some versions probably UUIDv4.
 
-ulids = uuid_v4s.map { |uuid_v4| ULID.from_uuidv4(uuid_v4) }
-ulids.map(&:to_uuidv4) == uuid_v4s #=> **Probably** `true` except below examples.
+All UUIDv4s can be converted to ULID, but this will not have the correct "timestamp".\
+Most ULIDs cannot be converted to UUIDv4 while maintaining reversibility, because UUIDv4 requires version and variants in the fields.
 
-# NOTE: Some boundary values are not reversible. See below.
+See also [ulid/spec#64](https://github.com/ulid/spec/issues/64) for further detail.
 
-ULID.min.to_uuidv4 #=> "00000000-0000-4000-8000-000000000000"
-ULID.max.to_uuidv4 #=> "ffffffff-ffff-4fff-bfff-ffffffffffff"
+For now, this gem provides 4 methods for UUIDs.
 
-# These importing results are same as https://github.com/ahawker/ulid/tree/96bdb1daad7ce96f6db8c91ac0410b66d2e1c4c1 on CPython 3.9.4
-reversed_min = ULID.from_uuidv4('00000000-0000-4000-8000-000000000000') #=> ULID(1970-01-01 00:00:00.000 UTC: 00000000008008000000000000)
-reversed_max = ULID.from_uuidv4('ffffffff-ffff-4fff-bfff-ffffffffffff') #=> ULID(10889-08-02 05:31:50.655 UTC: 7ZZZZZZZZZ9ZZVZZZZZZZZZZZZ)
+- Reversibility is preferred: `ULID.from_uuidish`, `ULID.to_uuidish`
+- Prefer UUIDv4 specification: `ULID.from_uuidv4`, `ULID.to_uuidv4`
 
-# But they are not reversible! Need to consider this issue in https://github.com/kachick/ruby-ulid/issues/76
-ULID.min == reversed_min #=> false
-ULID.max == reversed_max #=> false
+```ruby
+# All UUIDv4 IDs can be reversible even if converted to ULID
+uuid = SecureRandom.uuid
+ULID.from_uuidish(uuid) == ULID.from_uuidv4(uuid) #=> true
+ULID.from_uuidish(uuid).to_uuidish == ULID.from_uuidv4(uuid).to_uuidv4 #=> true
+
+# But most ULIDs cannot be converted to UUIDv4 
+ulid = ULID.parse('01F4A5Y1YAQCYAYCTC7GRMJ9AA')
+ulid.to_uuidv4 #=> ULID::IrreversibleUUIDError
+# So 2 ways to get substitute strings that might satisfy the use case
+ulid.to_uuidv4(force: true) #=> "0179145f-07ca-4b3c-af33-4c3c3149254a" this cannot be reverse to source ULID
+ulid == ULID.from_uuidv4(ulid.to_uuidv4(force: true)) #=> false
+ulid.to_uuidish #=> "0179145f-07ca-bb3c-af33-4c3c3149254a" does not satisfy UUIDv4 spec
+ulid == ULID.from_uuidish(ulid.to_uuidish) #=> true
+
+# Seeing boundary IDs makes it easier to understand
+ULID.min.to_uuidish #=> "00000000-0000-0000-0000-000000000000"
+ULID.min.to_uuidv4(force: true) #=> "00000000-0000-4000-8000-000000000000"
+ULID.max.to_uuidish #=> "ffffffff-ffff-ffff-ffff-ffffffffffff"
+ULID.max.to_uuidv4(force: true) #=> "ffffffff-ffff-4fff-bfff-ffffffffffff"
 ```
 
 ## Migration from other gems
@@ -424,13 +396,8 @@ See [wiki page for gem migration](https://github.com/kachick/ruby-ulid/wiki/Gem-
 
 ## RBS
 
-Try at [examples/rbs_sandbox](https://github.com/kachick/ruby-ulid/tree/main/examples/rbs_sandbox).
-
-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).
-
-* ![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)
+- Try at [examples/rbs_sandbox](https://github.com/kachick/ruby-ulid/tree/main/examples/rbs_sandbox).
+- See the overview in [our wiki page for RBS](https://github.com/kachick/ruby-ulid/wiki/RBS)
 
 ## References
 
@@ -440,5 +407,6 @@ I have checked the behavior with [ruby/rbs@2.6.0](https://github.com/ruby/rbs) +
 
 ## Note
 
-- [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)
+- [UUIDv6, UUIDv7, UUIDv8](https://www.ietf.org/archive/id/draft-ietf-uuidrev-rfc4122bis-02.html) is another choice for sortable and randomness ID.
+  \
+  However they remain in draft state. Our tracker is: [ruby-ulid#37](https://github.com/kachick/ruby-ulid/issues/37)

data/lib/ulid/crockford_base32.rb

@@ -1,11 +1,12 @@
 # coding: us-ascii
 # frozen_string_literal: true
-# shareable_constant_value: literal
 
 # Copyright (C) 2021 Kenichi Kamiya
 
+require_relative('utils')
+
 class ULID
-  # @see https://www.crockford.com/base32.html
+  # @see https://www.crockford.com/base32.html and https://www.rfc-editor.org/rfc/rfc4648
   #
   # This module supporting only `subset of original crockford for actual use-case` in ULID context.
   # Original decoding spec allows other characters.
@@ -37,7 +38,7 @@ class ULID
     }.freeze
 
     # Excluded I, L, O, U, - from Base32
-    base32_to_crockford = {
+    base32hex_to_crockford = {
       'I' => 'J',
       'J' => 'K',
       'K' => 'M',
@@ -53,8 +54,8 @@ class ULID
       'U' => 'Y',
       'V' => 'Z'
     }.freeze
-    BASE32_TR_PATTERN = base32_to_crockford.keys.join.freeze
-    CROCKFORD_TR_PATTERN = base32_to_crockford.values.join.freeze
+    BASE32HEX_TR_PATTERN = base32hex_to_crockford.keys.join.freeze
+    CROCKFORD_TR_PATTERN = base32hex_to_crockford.values.join.freeze
     ENCODING_STRING = "#{same_definitions.values.join}#{CROCKFORD_TR_PATTERN}".freeze
 
     variant_to_normarized = {
@@ -68,36 +69,36 @@ class ULID
     VARIANT_TR_PATTERN = variant_to_normarized.keys.join.freeze
     NORMALIZED_TR_PATTERN = variant_to_normarized.values.join.freeze
 
+    Utils.make_sharable_constants(self)
+
     # @note Avoid to depend regex as possible. `tr(string, string)` is almost 2x Faster than `gsub(regex, hash)` in Ruby 3.1
 
-    # @api private
     # @param [String] string
     # @return [Integer]
     def self.decode(string)
-      n32encoded = string.upcase.tr(CROCKFORD_TR_PATTERN, BASE32_TR_PATTERN)
-      n32encoded.to_i(32)
+      base32hex = string.upcase.tr(CROCKFORD_TR_PATTERN, BASE32HEX_TR_PATTERN)
+      Integer(base32hex, 32, exception: true)
     end
 
-    # @api private
     # @param [Integer] integer
     # @return [String]
     def self.encode(integer)
-      n32encoded = integer.to_s(32)
-      from_n32(n32encoded).rjust(ENCODED_LENGTH, '0')
+      base32hex = integer.to_s(32)
+      from_base32hex(base32hex).rjust(ENCODED_LENGTH, '0')
     end
 
-    # @api private
     # @param [String] string
     # @return [String]
     def self.normalize(string)
       string.delete('-').tr(VARIANT_TR_PATTERN, NORMALIZED_TR_PATTERN)
     end
 
-    # @api private
-    # @param [String] n32encoded
+    # @param [String] base32hex
     # @return [String]
-    def self.from_n32(n32encoded)
-      n32encoded.upcase.tr(BASE32_TR_PATTERN, CROCKFORD_TR_PATTERN)
+    def self.from_base32hex(base32hex)
+      base32hex.upcase.tr(BASE32HEX_TR_PATTERN, CROCKFORD_TR_PATTERN)
     end
   end
+
+  private_constant(:CrockfordBase32)
 end

data/lib/ulid/errors.rb

@@ -7,4 +7,5 @@ class ULID
   class OverflowError < Error; end
   class ParserError < Error; end
   class UnexpectedError < Error; end
+  class IrreversibleUUIDError < Error; end
 end

data/lib/ulid/monotonic_generator.rb

@@ -4,6 +4,9 @@
 
 # Copyright (C) 2021 Kenichi Kamiya
 
+require_relative('errors')
+require_relative('utils')
+
 class ULID
   class MonotonicGenerator
     # @note When use https://github.com/ko1/ractor-tvar might realize Ractor based thread safe monotonic generator.
@@ -11,18 +14,19 @@ class ULID
     include(MonitorMixin)
 
     # @return [ULID, nil]
-    attr_reader(:prev)
+    attr_accessor(:last)
+    private(:last=)
 
     undef_method(:instance_variable_set)
 
     def initialize
       super
-      @prev = nil
+      @last = nil
     end
 
     # @return [String]
     def inspect
-      "ULID::MonotonicGenerator(prev: #{@prev.inspect})"
+      "ULID::MonotonicGenerator(last: #{@last.inspect})"
     end
     alias_method(:to_s, :inspect)
 
@@ -31,27 +35,27 @@ class ULID
     # @raise [OverflowError] if the entropy part is larger than the ULID limit in same milliseconds
     # @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)
+    def generate(moment: Utils.current_milliseconds)
       synchronize do
-        prev_ulid = @prev
-        unless prev_ulid
-          ret = ULID.generate(moment: moment)
-          @prev = ret
+        prev = @last
+        unless prev
+          ret = ULID.generate(moment:)
+          @last = ret
           return ret
         end
 
-        milliseconds = ULID.milliseconds_from_moment(moment)
+        milliseconds = Utils.milliseconds_from_moment(moment)
 
         ulid = (
-          if prev_ulid.milliseconds < milliseconds
+          if prev.milliseconds < milliseconds
             ULID.generate(moment: milliseconds)
           else
-            ULID.from_milliseconds_and_entropy(milliseconds: prev_ulid.milliseconds, entropy: prev_ulid.entropy.succ)
+            ULID.generate(moment: prev.milliseconds, entropy: prev.entropy.succ)
           end
         )
 
-        unless ulid > prev_ulid
-          base_message = "monotonicity broken from unexpected reasons # generated: #{ulid.inspect}, prev: #{prev_ulid.inspect}"
+        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'
@@ -63,15 +67,18 @@ class ULID
           raise(UnexpectedError, base_message + additional_information)
         end
 
-        @prev = ulid
+        @last = ulid
         ulid
       end
     end
 
+    # Just providing similar api as `ULID.generate` and `ULID.encode` relation. No performance benefit exists in monotonic generator's one.
+    #
+    # @see https://github.com/kachick/ruby-ulid/pull/220
     # @param [Time, Integer] moment
     # @return [String]
-    def encode(moment: ULID.current_milliseconds)
-      generate(moment: moment).encode
+    def encode(moment: Utils.current_milliseconds)
+      generate(moment:).encode
     end
 
     undef_method(:freeze)

data/lib/ulid/utils.rb

@@ -0,0 +1,99 @@
+# coding: us-ascii
+# frozen_string_literal: true
+# shareable_constant_value: literal
+
+# Copyright (C) 2021 Kenichi Kamiya
+
+require('securerandom')
+
+class ULID
+  # @note I don't have confidence for the naming of `Utils`. However some standard libraries have same name.
+  #   https://github.com/ruby/webrick/blob/14612a7540fdd7373344461851c4bfff64985b3e/lib/webrick/utils.rb#L17
+  #   https://docs.ruby-lang.org/ja/latest/class/ERB=3a=3aUtil.html
+  #   https://github.com/ruby/rss/blob/af1c3c9c9630ec0a48abec48ed1ef348ba82aa13/lib/rss/utils.rb#L9
+  module Utils
+    # @return [Integer]
+    def self.current_milliseconds
+      milliseconds_from_time(Time.now)
+    end
+
+    # @param [Time] time
+    # @return [Integer]
+    def self.milliseconds_from_time(time)
+      (time.to_r * 1000).to_i
+    end
+
+    # @param [Time, Integer] moment
+    # @return [Integer]
+    def self.milliseconds_from_moment(moment)
+      case moment
+      when Integer
+        moment
+      when Time
+        milliseconds_from_time(moment)
+      else
+        raise(ArgumentError, '`moment` should be a `Time` or `Integer as milliseconds`')
+      end
+    end
+
+    # @return [Integer]
+    def self.reasonable_entropy
+      SecureRandom.random_number(MAX_ENTROPY)
+    end
+
+    # @param [Integer] milliseconds
+    # @param [Integer] entropy
+    # @return [String]
+    # @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.encode_base32hex(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?
+
+      base32hex_timestamp = milliseconds.to_s(32).rjust(TIMESTAMP_ENCODED_LENGTH, '0')
+      base32hex_randomness = entropy.to_s(32).rjust(RANDOMNESS_ENCODED_LENGTH, '0')
+      "#{base32hex_timestamp}#{base32hex_randomness}"
+    end
+
+    # @param [BasicObject] object
+    # @return [String]
+    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
+          # 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
+          (Class === singleton_class) ? singleton_class.ancestors.detect { |ancestor| !ancestor.equal?(singleton_class) } : fallback
+        end
+      )
+
+      begin
+        name = String.try_convert(klass.name)
+      rescue Exception
+        fallback
+      else
+        name || fallback
+      end
+    end
+
+    # @note Call before Module#private_constant
+    def self.make_sharable_constants(mod)
+      mod.constants.each do |const_name|
+        value = mod.const_get(const_name)
+        Ractor.make_shareable(value)
+      end
+    end
+  end
+
+  private_constant(:Utils)
+end