ruby-ulid 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 637c2b95fc9d18a59e1bc6d23a3791bc80362b146c52ff962c407894c29c782e
-  data.tar.gz: 74a9e3ea4be5d9a541d4cb6dd012997406ef3cb68a08f7a1a42959f40f7ab4e5
+  metadata.gz: 6c0ca476ab05b4b53ce593e893ffdfd6aa72b3c08563116b95f5a22f43a7926b
+  data.tar.gz: 7454acd393c8df299696d2907a71f994643dacc45103e2874561d186e1fa85c5
 SHA512:
-  metadata.gz: c39c42f8da0aac22356cb26fefb7d23855d118f68148be90c1e253577847b91135f8a04ef1fdca1af59075bd673e61cf2f492f046f30616f7c6b493e28332174
-  data.tar.gz: 623f7f9b4d46e46c2a47a143330b3d1c2cf83a033e83c8e68ab3af13e56f1ff5a082b3a15f57efcf4a3180fcc5786e18e94a0221fd03c44343322d641b69e31a
+  metadata.gz: bfe19e20452a12edd7472ddaf3b9583d2eaa5640e03a081621c35bcfdf218f9ccf5d7c7625b0850312447f61c0592796d333aa4578a6c2f0281e6ff4e8392efd
+  data.tar.gz: cdd8dba77214852ea70d07a137f75098558097db686a4409dd14e611d533de33f4c510b9a38ee232e918dd0aae6b028f19a4dd7312ac42172890d726091f282b

data/README.md

@@ -5,9 +5,10 @@
 
 ## Overview
 
-[ulid/spec](https://github.com/ulid/spec) has some useful features.\
-Especially possess all `uniqueness`, `randomness`, `extractable timestamps` and `sortability`.\
-This gem aims to provide the generator, optional monotonicity, parser and other manipulation ways 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,33 @@ Instead, herein is proposed ULID:
 
 ### Install
 
-Require Ruby 2.7 or later
+Tested only in the last 2 Rubies. So you need Ruby 3.2 or higher.
 
-This command will install the latest version into your environment
+Add this line to your `Gemfile`.
 
-```console
-$ gem install ruby-ulid
-Should be installed!
+```ruby
+gem('ruby-ulid', '~> 0.9.0')
 ```
 
-Add this line in your Gemfile.
+And load it.
 
 ```ruby
-gem('ruby-ulid', '~> 0.7.0')
+require 'ulid'
 ```
 
-### How to use
+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.9.0).
 
-```ruby
-require 'ulid'
+In [Nix](https://nixos.org/), you can skip the installation steps for both ruby and ruby-ulid to try.
 
-ULID::VERSION
-# => "0.7.0"
-```
+```console
+> nix run github:kachick/ruby-ulid#ruby -- -e 'p ULID.generate'
+ULID(2024-03-03 18:37:06.152 UTC: 01HR2SNY789ZZ027EDJEHAGQ62)
 
-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.7.0).
+> nix run github:kachick/ruby-ulid#irb
+irb(main):001:0> ULID.parse('01H66XG2A9WWYRCYGPA62T4AZA')
+=> ULID(2023-07-25 16:18:12.937 UTC: 01H66XG2A9WWYRCYGPA62T4AZA)
+```
 
 ### Generator and Parser
 
@@ -77,7 +80,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
@@ -118,15 +121,15 @@ ULID.decode_time('00VHNCZB00SYG7RCEXZC9DA4E1', in: '+09:00') #=> 2000-01-01 09:0
 
 This project does not prioritize on the speed. However it actually works faster than others! :zap:
 
-Snapshot on 0.7.0 is below
+Snapshot on v0.8.0 with Ruby 3.2.1 is below
 
-- Generator is 1.6x 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.6x 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 +142,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 +154,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 +167,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
 ```
@@ -265,18 +265,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.
@@ -292,7 +280,7 @@ 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
+#### As an element in Enumerable and Range
 
 `ULID#next` and `ULID#succ` returns next(successor) ULID.\
 Especially `ULID#succ` makes it possible `Range[ULID]#each`.
@@ -313,6 +301,17 @@ ULID.parse('01BX5ZZKBK0000000000000000').pred.to_s #=> "01BX5ZZKBJZZZZZZZZZZZZZZ
 ULID.parse('00000000000000000000000000').pred #=> nil
 ```
 
+`ULID#+` is also provided to realize `Range#step` since [ruby-3.4.0 spec changes](https://bugs.ruby-lang.org/issues/18368).
+
+```ruby
+# This code works only in ruby-3.4.0dev or later
+(ULID.min...).step(42).take(3)
+# =>
+[ULID(1970-01-01 00:00:00.000 UTC: 00000000000000000000000000),
+ ULID(1970-01-01 00:00:00.000 UTC: 0000000000000000000000001A),
+ ULID(1970-01-01 00:00:00.000 UTC: 0000000000000000000000002M)]
+```
+
 #### Test helpers
 
 `ULID.sample` returns random ULIDs.
@@ -324,13 +323,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,22 +335,16 @@ 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
@@ -385,60 +376,57 @@ 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"
 ```
 
+[UUIDv6, UUIDv7, UUIDv8](https://www.ietf.org/archive/id/draft-ietf-uuidrev-rfc4122bis-02.html) are other candidates for sortable and randomness ID.\
+Latest [ruby/securerandom merged the UUIDv7 generator](https://github.com/ruby/securerandom/pull/19).\
+See [tracker](https://bugs.ruby-lang.org/issues/19735) for further detail.
+
 ## Migration from other gems
 
 See [wiki page for gem migration](https://github.com/kachick/ruby-ulid/wiki/Gem-migration).
 
 ## 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
 
 - [Repository](https://github.com/kachick/ruby-ulid)
 - [API documents](https://kachick.github.io/ruby-ulid/)
 - [ulid/spec](https://github.com/ulid/spec)
-
-## 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)

data/lib/ulid/crockford_base32.rb

@@ -6,7 +6,7 @@
 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.
@@ -38,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',
@@ -54,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 = {
@@ -69,22 +69,22 @@ class ULID
     VARIANT_TR_PATTERN = variant_to_normarized.keys.join.freeze
     NORMALIZED_TR_PATTERN = variant_to_normarized.values.join.freeze
 
-    Utils.make_sharable_constantans(self)
+    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
 
     # @param [String] string
     # @return [Integer]
     def self.decode(string)
-      base32encoded = string.upcase.tr(CROCKFORD_TR_PATTERN, BASE32_TR_PATTERN)
-      Integer(base32encoded, 32, exception: true)
+      base32hex = string.upcase.tr(CROCKFORD_TR_PATTERN, BASE32HEX_TR_PATTERN)
+      Integer(base32hex, 32, exception: true)
     end
 
     # @param [Integer] integer
     # @return [String]
     def self.encode(integer)
-      base32encoded = integer.to_s(32)
-      from_base32(base32encoded).rjust(ENCODED_LENGTH, '0')
+      base32hex = integer.to_s(32)
+      from_base32hex(base32hex).rjust(ENCODED_LENGTH, '0')
     end
 
     # @param [String] string
@@ -93,10 +93,10 @@ class ULID
       string.delete('-').tr(VARIANT_TR_PATTERN, NORMALIZED_TR_PATTERN)
     end
 
-    # @param [String] base32encoded
+    # @param [String] base32hex
     # @return [String]
-    def self.from_base32(base32encoded)
-      base32encoded.upcase.tr(BASE32_TR_PATTERN, CROCKFORD_TR_PATTERN)
+    def self.from_base32hex(base32hex)
+      base32hex.upcase.tr(BASE32HEX_TR_PATTERN, CROCKFORD_TR_PATTERN)
     end
   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

@@ -10,23 +10,23 @@ require_relative('utils')
 class ULID
   class MonotonicGenerator
     # @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.
+    #       However it is a C extension, I'm pending to use it for now.
     include(MonitorMixin)
 
     # @return [ULID, nil]
-    attr_accessor(:prev)
-    private(: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)
 
@@ -37,25 +37,25 @@ class ULID
     #   Basically will not happen. Just means this feature prefers error rather than invalid value.
     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 = Utils.milliseconds_from_moment(moment)
 
         ulid = (
-          if prev_ulid.milliseconds < milliseconds
+          if prev.milliseconds < milliseconds
             ULID.generate(moment: milliseconds)
           else
-            ULID.generate(moment: 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'
@@ -67,7 +67,7 @@ class ULID
           raise(UnexpectedError, base_message + additional_information)
         end
 
-        @prev = ulid
+        @last = ulid
         ulid
       end
     end
@@ -78,7 +78,7 @@ class ULID
     # @param [Time, Integer] moment
     # @return [String]
     def encode(moment: Utils.current_milliseconds)
-      generate(moment: moment).encode
+      generate(moment:).encode
     end
 
     undef_method(:freeze)

data/lib/ulid/utils.rb

@@ -46,15 +46,15 @@ class ULID
     # @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_base32(milliseconds:, entropy:)
+    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?
 
-      base32encoded_timestamp = milliseconds.to_s(32).rjust(TIMESTAMP_ENCODED_LENGTH, '0')
-      base32encoded_randomness = entropy.to_s(32).rjust(RANDOMNESS_ENCODED_LENGTH, '0')
-      "#{base32encoded_timestamp}#{base32encoded_randomness}"
+      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
@@ -86,31 +86,13 @@ class ULID
       end
     end
 
-    def self.make_sharable_value(value)
-      value.freeze
-      if defined?(Ractor)
-        case value
-        when ULID, Time
-          if ractor_can_make_shareable_time?
-            Ractor.make_shareable(value)
-          end
-        else
-          Ractor.make_shareable(value)
-        end
-      end
-    end
-
     # @note Call before Module#private_constant
-    def self.make_sharable_constantans(mod)
+    def self.make_sharable_constants(mod)
       mod.constants.each do |const_name|
         value = mod.const_get(const_name)
-        make_sharable_value(value)
+        Ractor.make_shareable(value)
       end
     end
-
-    def self.ractor_can_make_shareable_time?
-      RUBY_VERSION >= '3.1'
-    end
   end
 
   private_constant(:Utils)

data/lib/ulid/uuid/fields.rb

@@ -0,0 +1,41 @@
+# coding: us-ascii
+# frozen_string_literal: true
+# shareable_constant_value: literal
+
+# Copyright (C) 2021 Kenichi Kamiya
+
+class ULID
+  module UUID
+    # @see https://www.rfc-editor.org/rfc/rfc4122#section-4.1.2
+    # @note
+    #   - Using `Fields = Data.define do; end` syntax made https://github.com/kachick/ruby-ulid/issues/233 again. So use class syntax instead
+    #   - This file is extracted to avoid YARD warnings "Ruby::ClassHandler: Undocumentable superclass" https://github.com/lsegal/yard/issues/737
+    #     Partially avoiding is hard in YARD, so extracting the code and using exclude filter in yardopts...
+    class Fields < Data.define(:time_low, :time_mid, :time_hi_and_version, :clock_seq_hi_and_res, :clk_seq_low, :node)
+      def self.raw_from_octets(octets)
+        case octets.pack('C*').unpack('NnnnnN')
+        in [Integer => time_low, Integer => time_mid, Integer => time_hi_and_version, Integer => clock_seq_hi_and_res, Integer => clk_seq_low, Integer => node]
+          new(time_low:, time_mid:, time_hi_and_version:, clock_seq_hi_and_res:, clk_seq_low:, node:).freeze
+        end
+      end
+
+      def self.forced_v4_from_octets(octets)
+        case octets.pack('C*').unpack('NnnnnN')
+        in [Integer => time_low, Integer => time_mid, Integer => time_hi_and_version, Integer => clock_seq_hi_and_res, Integer => clk_seq_low, Integer => node]
+          new(
+            time_low:,
+            time_mid:,
+            time_hi_and_version: (time_hi_and_version & 0x0fff) | 0x4000,
+            clock_seq_hi_and_res: (clock_seq_hi_and_res & 0x3fff) | 0x8000,
+            clk_seq_low:,
+            node:
+          ).freeze
+        end
+      end
+
+      def to_s
+        '%08x-%04x-%04x-%04x-%04x%08x' % deconstruct
+      end
+    end
+  end
+end