ruby-ulid 0.8.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 323b750a4e11157bd492b31d74833df2042192775c8627917880ef386dee4c1c
-  data.tar.gz: 2dc8a91cbed7b473d6f9e28480dd227ab3469828ab0833f48a754111bd6e926c
+  metadata.gz: 3b0c26b06cd815f96d9ffc78836ceb69ed4677a4f5acfac6e15c016e093e0d18
+  data.tar.gz: '09acd9841d6ee33b87687dd12a7912ef262c9cad3d85b37db6215912048b36e1'
 SHA512:
-  metadata.gz: e78a5289863c1300a3f4c186b72a0f1d97cd709ce6043b69729d851f5e6ffcedac001e3bb691397d761ee497d609b5292c300db7f2ec3f8cf5be0ee5c095af80
-  data.tar.gz: e19197709d7a896a79c6ebdc40fa919c2e7876284fa1dbf8895498ad7b80e989634cdd3e651362db5cf9f7c627fe17439ccc21e75c8e6598b002da6b19858aa0
+  metadata.gz: bd7f5fe5b75a1d8f91d5a016a81a6a132debaf4247f075918ad4a52dfc96a6bef937ef433663d71610a008621eac3e5c997f35f15249c8030bbc095357882a78
+  data.tar.gz: d444cfac8c9b66ce72850236a7cd7367873a3ea8c51a6c67bc5d34bb0a549fb4192c120cbaa13ba92b4e4c49ccc45fe2cf7a3a6a01882daee287428ca29dd597

data/README.md

@@ -3,6 +3,9 @@
 [![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)
 
+This gem is in maintenance mode, I have no plan to add new features.\
+The reason is UUID v7 has been accepted in [IETF](https://www.rfc-editor.org/rfc/rfc9562.html) and [ruby's securerandom](https://github.com/ruby/securerandom/pull/19). See [UUID section](#uuid) for detail.
+
 ## Overview
 
 [ulid/spec](https://github.com/ulid/spec) defines some useful features.\
@@ -38,12 +41,12 @@ Instead, herein is proposed ULID:
 
 ### Install
 
-Tested only in the last 2 Rubies. So you need Ruby 3.1 or higher.
+Tested only in the Ruby 4.
 
 Add this line to your `Gemfile`.
 
 ```ruby
-gem('ruby-ulid', '~> 0.8.0')
+gem('ruby-ulid', '~> 1.0.0')
 ```
 
 And load it.
@@ -53,7 +56,18 @@ require 'ulid'
 ```
 
 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).
+If you would like to see released version's one. [Look at the ref](https://github.com/kachick/ruby-ulid/tree/v1.0.0).
+
+In [Nix](https://nixos.org/), you can skip the installation steps for both ruby and ruby-ulid to try.
+
+```console
+> nix run github:kachick/ruby-ulid#ruby -- -e 'p ULID.generate'
+ULID(2024-03-03 18:37:06.152 UTC: 01HR2SNY789ZZ027EDJEHAGQ62)
+
+> 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
 
@@ -269,7 +283,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`.
@@ -290,6 +304,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.
@@ -356,38 +381,47 @@ ULID.parse_variant_format('01G70Y0Y7G-ZLXWDIREXERGSDoD') #=> ULID(2022-07-03 02:
 
 #### UUID
 
-Both ULID and UUID are 128-bit IDs. But with different specs. Especially UUID has some versions probably UUIDv4.
+Both ULID and UUID are 128-bit IDs. But with different specs. Especially, UUID has some versions, for example, UUIDv4 and UUIDv7.
 
-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.
+All UUIDs can be converted to ULID, but only [new versions](https://datatracker.ietf.org/doc/rfc9562/) have a correct "timestamp".\
+Most ULIDs cannot be converted to UUID while maintaining reversibility, because UUID requires version and variants in the fields.
 
 See also [ulid/spec#64](https://github.com/ulid/spec/issues/64) for further detail.
 
-For now, this gem provides 4 methods for UUIDs.
+For now, this gem provides some methods for UUIDs.
 
 - Reversibility is preferred: `ULID.from_uuidish`, `ULID.to_uuidish`
-- Prefer UUIDv4 specification: `ULID.from_uuidv4`, `ULID.to_uuidv4`
+- Prefer variants specification: `ULID.from_uuid_v4`, `ULID.from_uuid_v7`, `ULID.to_uuid_v4`, `ULID.to_uuid_v7`
 
 ```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
+# All UUIDv4 and UUIDv7 IDs can be reversible even if converted to ULID
+uuid_v4 = SecureRandom.uuid_v4
+ULID.from_uuidish(uuid_v4) == ULID.from_uuid_v4(uuid_v4) #=> true
+ULID.from_uuidish(uuid_v4).to_uuidish == ULID.from_uuid_v4(uuid_v4).to_uuid_v4 #=> true
+
+# v4 does not have timestamp, v7 has it.
+
+ULID.from_uuid_v4(SecureRandom.uuid_v4).to_time
+# 'f80b3f53-043a-4298-a674-cd83a7fd5d22' => 10612-05-19 16:58:53.882 UTC
 
-# But most ULIDs cannot be converted to UUIDv4 
+ULID.from_uuid_v7(SecureRandom.uuid_v7).to_time
+# '01946f9e-bf58-7be3-8fd4-4606606b05aa' => 2025-01-16 14:57:42.232 UTC
+# ULID is officially defined milliseconds precision for the spec. So omit the nanoseconds precisions even if the UUID v7 ID was generated with extra_timestamp_bits >= 1.
+
+# However most ULIDs cannot be converted to versioned UUID
 ulid = ULID.parse('01F4A5Y1YAQCYAYCTC7GRMJ9AA')
-ulid.to_uuidv4 #=> ULID::IrreversibleUUIDError
+ulid.to_uuid_v4 #=> 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_uuid_v4(force: true) #=> "0179145f-07ca-4b3c-af33-4c3c3149254a" this cannot be reverse to source ULID
+ulid == ULID.from_uuid_v4(ulid.to_uuid_v4(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.min.to_uuid_v4(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"
+ULID.max.to_uuid_v4(force: true) #=> "ffffffff-ffff-4fff-bfff-ffffffffffff"
 ```
 
 ## Migration from other gems
@@ -404,9 +438,3 @@ See [wiki page for gem migration](https://github.com/kachick/ruby-ulid/wiki/Gem-
 - [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-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/monotonic_generator.rb

@@ -10,7 +10,7 @@ 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]

data/lib/ulid/utils.rb

@@ -7,20 +7,16 @@
 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
+      # There are different recommendations for this featrure with the accuracy and other context
+      # At here, I prefer to adjust with Ruby UUID v7 imeplementation and respect monotonicity use-case
+      # https://github.com/ruby/securerandom/pull/19/files#diff-cad52e37612706fe31d85599bb8bc789e90fd382f091ed31fdd036119af3e5cdR252
+      # Other resources
+      #   - https://blog.dnsimple.com/2018/03/elapsed-time-with-ruby-the-right-way/
+      #   - https://github.com/ruby/ruby/blob/5df20ab0b49b55c9cf858879f3e6e30cc3dcd803/process.c#L8131
+      Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)
     end
 
     # @param [Time, Integer] moment
@@ -30,7 +26,7 @@ class ULID
       when Integer
         moment
       when Time
-        milliseconds_from_time(moment)
+        (moment.to_r * 1000).to_i
       else
         raise(ArgumentError, '`moment` should be a `Time` or `Integer as milliseconds`')
       end

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_version_from_octets(octets, mask:)
+        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) | mask,
+            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

data/lib/ulid/uuid.rb

@@ -6,12 +6,14 @@
 
 require_relative('errors')
 require_relative('utils')
+require_relative('uuid/fields')
 
 class ULID
   module UUID
     BASE_PATTERN = /\A[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}\z/i
     # Imported from https://stackoverflow.com/a/38191104/1212807, thank you!
     V4_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
+    V7_PATTERN = /\A[0-9A-F]{8}-[0-9A-F]{4}-7[0-9A-F]{3}-[89AB][0-9A-F]{3}-[0-9A-F]{12}\z/i
 
     def self.parse_any_to_int(uuidish)
       encoded = String.try_convert(uuidish)
@@ -38,34 +40,16 @@ class ULID
       parse_any_to_int(encoded)
     end
 
-    # @see https://www.rfc-editor.org/rfc/rfc4122#section-4.1.2
-    # @todo Replace to Data class after dropped Ruby 3.1
-    # @note Using `Fields = Struct.new` syntax made https://github.com/kachick/ruby-ulid/issues/233 again. So use class syntax instead
-    class Fields < Struct.new(:time_low, :time_mid, :time_hi_and_version, :clock_seq_hi_and_res, :clk_seq_low, :node, keyword_init: true)
-      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.parse_v7_to_int(uuid)
+      encoded = String.try_convert(uuid)
+      raise(ArgumentError, 'should pass a string for UUID parser') unless encoded
 
-      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
+      prefix_trimmed = encoded.delete_prefix('urn:uuid:')
+      unless V7_PATTERN.match?(prefix_trimmed)
+        raise(ParserError, "given `#{encoded}` does not match to `#{V7_PATTERN.inspect}`")
       end
 
-      def to_s
-        '%08x-%04x-%04x-%04x-%04x%08x' % values
-      end
+      parse_any_to_int(encoded)
     end
   end
 

data/lib/ulid/version.rb

@@ -3,5 +3,5 @@
 # shareable_constant_value: literal
 
 class ULID
-  VERSION = '0.8.0'
+  VERSION = '1.0.0'
 end

data/lib/ulid.rb

@@ -40,7 +40,7 @@ class ULID
   SCANNING_PATTERN = /\b[0-7][#{CrockfordBase32::ENCODING_STRING}]{#{TIMESTAMP_ENCODED_LENGTH - 1}}[#{CrockfordBase32::ENCODING_STRING}]{#{RANDOMNESS_ENCODED_LENGTH}}\b/i
 
   # 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.
+  # Time#inspect truncates 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'
@@ -351,10 +351,17 @@ class ULID
   # @param [String, #to_str] uuid
   # @return [ULID]
   # @raise [ParserError] if the given format is not correct for UUIDv4 specs
-  def self.from_uuidv4(uuid)
+  def self.from_uuid_v4(uuid)
     from_integer(UUID.parse_v4_to_int(uuid))
   end
 
+  # @param [String, #to_str] uuid
+  # @return [ULID]
+  # @raise [ParserError] if the given format is not correct for UUIDv4 specs
+  def self.from_uuid_v7(uuid)
+    from_integer(UUID.parse_v7_to_int(uuid))
+  end
+
   attr_reader(:milliseconds, :entropy, :encoded)
   protected(:encoded)
 
@@ -449,33 +456,43 @@ class ULID
     @encoded.slice(TIMESTAMP_ENCODED_LENGTH, RANDOMNESS_ENCODED_LENGTH) || raise(UnexpectedError)
   end
 
-  # @return [ULID, nil] when called on ULID as `7ZZZZZZZZZZZZZZZZZZZZZZZZZ`, returns `nil` instead of ULID
-  def succ
-    succ_int = @integer.succ
-    if succ_int >= MAX_INTEGER
-      if succ_int == MAX_INTEGER
-        MAX
-      else
+  # @param [Integer] other
+  # @return [ULID, nil] when returning URID might be greater than `7ZZZZZZZZZZZZZZZZZZZZZZZZZ`, returns `nil` instead of ULID
+  def +(other)
+    raise(ArgumentError, 'ULID#+ takes only integers') unless Integer === other
+
+    new_int = @integer + other
+    case new_int
+    when MAX_INTEGER
+      MAX
+    when 0
+      MIN
+    else
+      if new_int > MAX_INTEGER || new_int < 0
         nil
+      else
+        ULID.from_integer(new_int)
       end
-    else
-      ULID.from_integer(succ_int)
     end
   end
+
+  # @param [Integer] other
+  # @return [ULID, nil] when returning URID might be less than `00000000000000000000000000`, returns `nil` instead of ULID
+  def -(other)
+    raise(ArgumentError, 'ULID#- takes only integers') unless Integer === other
+
+    self + -other
+  end
+
+  # @return [ULID, nil] when called on ULID as `7ZZZZZZZZZZZZZZZZZZZZZZZZZ`, returns `nil` instead of ULID
+  def succ
+    self + 1
+  end
   alias_method(:next, :succ)
 
   # @return [ULID, nil] when called on ULID as `00000000000000000000000000`, returns `nil` instead of ULID
   def pred
-    pred_int = @integer.pred
-    if pred_int <= 0
-      if pred_int == 0
-        MIN
-      else
-        nil
-      end
-    else
-      ULID.from_integer(pred_int)
-    end
+    self - 1
   end
 
   # @return [Integer]
@@ -500,8 +517,8 @@ class ULID
     self
   end
 
-  # Generate a UUID-like string that does not set the version and variants field.
-  # It means wrong in UUIDv4 spec, but reversible
+  # Generate a UUID-like string that does not touch the version and variants field.
+  # It means basically wrong in UUID specs, but reversible
   #
   # @return [String]
   def to_uuidish
@@ -516,8 +533,8 @@ class ULID
   # @see https://github.com/kachick/ruby-ulid/issues/76
   # @param [bool] force
   # @return [String]
-  def to_uuidv4(force: false)
-    v4 = UUID::Fields.forced_v4_from_octets(octets)
+  def to_uuid_v4(force: false)
+    v4 = UUID::Fields.forced_version_from_octets(octets, mask: 0x4000)
     unless force
       uuidish = UUID::Fields.raw_from_octets(octets)
       raise(IrreversibleUUIDError) unless uuidish == v4
@@ -526,6 +543,19 @@ class ULID
     v4.to_s.freeze
   end
 
+  # @see [#to_uuid_v4] and https://datatracker.ietf.org/doc/rfc9562/
+  # @param [bool] force
+  # @return [String]
+  def to_uuid_v7(force: false)
+    v7 = UUID::Fields.forced_version_from_octets(octets, mask: 0x7000)
+    unless force
+      uuidish = UUID::Fields.raw_from_octets(octets)
+      raise(IrreversibleUUIDError) unless uuidish == v7
+    end
+
+    v7.to_s.freeze
+  end
+
   # @return [ULID]
   def dup
     super.freeze

data/sig/ulid.rbs

@@ -37,21 +37,23 @@ class ULID < Object
   module UUID
     BASE_PATTERN: Regexp
     V4_PATTERN: Regexp
+    V7_PATTERN: Regexp
 
     def self.parse_any_to_int: (String) -> Integer
     def self.parse_v4_to_int: (String) -> Integer
-
-    class Fields < Struct[Integer]
-      attr_accessor time_low: Integer
-      attr_accessor time_mid: Integer
-      attr_accessor time_hi_and_version: Integer
-      attr_accessor clock_seq_hi_and_res: Integer
-      attr_accessor clk_seq_low: Integer
-      attr_accessor node: Integer
+    def self.parse_v7_to_int: (String) -> Integer
+
+    class Fields
+      attr_reader time_low: Integer
+      attr_reader time_mid: Integer
+      attr_reader time_hi_and_version: Integer
+      attr_reader clock_seq_hi_and_res: Integer
+      attr_reader clk_seq_low: Integer
+      attr_reader node: Integer
       def self.raw_from_octets: (octets) -> Fields
-      def self.forced_v4_from_octets: (octets) -> Fields
+      def self.forced_version_from_octets: (octets, mask: Integer) -> Fields
 
-      def values: -> Array[Integer]
+      def deconstruct: -> Array[Integer]
 
       private
 
@@ -69,8 +71,6 @@ class ULID < Object
 
     def self.reasonable_entropy: -> Integer
 
-    def self.milliseconds_from_time: (Time time) -> milliseconds
-
     def self.safe_get_class_name: (untyped object) -> String
 
     def self.make_sharable_constants: (Module) -> void
@@ -147,7 +147,7 @@ class ULID < Object
   @integer: Integer
   @encoded: String
 
-  # Retuns a ULID
+  # Returns a ULID
   #
   # They are sortable when generated in different timestamp with milliseconds precision
   #
@@ -183,7 +183,7 @@ class ULID < Object
   #
   def self.generate: (?moment: moment, ?entropy: Integer) -> ULID
 
-  # Retuns encoded and normalzied String.\
+  # Returns encoded and normalzied String.\
   # It has same arguments signatures as `.generate`\
   # So can be used for just ID creation usecases without needless object creation.
   #
@@ -287,20 +287,23 @@ class ULID < Object
   # #=> ULID(2605-08-20 10:28:29.979 UTC: 0J7S2PFT4V2B9T8NJ2CRA1EG00)
   # ```
   #
-  # See also [ULID.from_uuidv4]
+  # See also [ULID.from_uuid_v4]
   def self.from_uuidish: (String uuidish) -> ULID
 
   # Load a UUIDv4 string with checking version and variants.
   #
   # ```ruby
-  # ULID.from_uuidv4('0983d0a2-ff15-4d83-8f37-7dd945b5aa39')
+  # ULID.from_uuid_v4('0983d0a2-ff15-4d83-8f37-7dd945b5aa39')
   # #=> ULID(2301-07-10 00:28:28.821 UTC: 09GF8A5ZRN9P1RYDVXV52VBAHS)
-  # ULID.from_uuidv4('123e4567-e89b-12d3-a456-426614174000')
+  # ULID.from_uuid_v4('123e4567-e89b-12d3-a456-426614174000')
   # #=> ULID::ParserError
   # ```
   #
   # See also [ULID.from_uuidish]
-  def self.from_uuidv4: (String uuid) -> ULID
+  def self.from_uuid_v4: (String uuid) -> ULID
+
+  # See also [ULID.from_uuid_v4]
+  def self.from_uuid_v7: (String uuid) -> ULID
 
   # Load integer as ULID
   #
@@ -594,6 +597,18 @@ class ULID < Object
   # ```
   def octets: -> octets
 
+  # Returns incremented ULID.\
+  # Especially providing for Range#step since ruby-3.4.0 spec changes
+  #
+  # See also [ruby-lang#18368](https://bugs.ruby-lang.org/issues/18368)
+  # ```
+  def +: (Integer other) -> ULID?
+
+  # Returns decremented ULID.\
+  # Providing for realizing natural API convention with the `ULID#+`
+  # ```
+  def -: (Integer other) -> ULID?
+
   # Returns next(successor) ULID.\
   # Especially `ULID#succ` makes it possible `Range[ULID]#each`.
   #
@@ -636,7 +651,7 @@ class ULID < Object
   # ULID.from_uuidish(ulid.to_uuidish) #=> ULID(2023-03-07 11:48:07.469 UTC: 01GTXYCWNDKRYH14DBZ77TRSD7)
   # ```
   #
-  # See also [ULID.from_uuidish], [ULID#to_uuidv4], [ulid/spec#64](https://github.com/ulid/spec/issues/64)
+  # See also [ULID.from_uuidish], [ULID#to_uuid_v4], [ulid/spec#64](https://github.com/ulid/spec/issues/64)
   def to_uuidish: -> String
 
   # Generate a UUIDv4-like string that sets the version and variants field.\
@@ -645,18 +660,21 @@ class ULID < Object
   #
   # ```ruby
   # uuid = '0983d0a2-ff15-4d83-8f37-7dd945b5aa39'
-  # ulid = ULID.from_uuidv4(uuid)
-  # ulid.to_uuidv4 #=> 0983d0a2-ff15-4d83-8f37-7dd945b5aa39
+  # ulid = ULID.from_uuid_v4(uuid)
+  # ulid.to_uuid_v4 #=> 0983d0a2-ff15-4d83-8f37-7dd945b5aa39
   # ```
   #
   # ```ruby
   # ulid = ULID.from_uuidish('0186bbe6-72ad-9e3d-1091-abf9cfac65a7')
-  # ulid.to_uuidv4 #=> ULID::IrreversibleUUIDError
-  # ulid.to_uuidv4(force: true) #=> '0186bbe6-72ad-4e3d-9091-abf9cfac65a7'
+  # ulid.to_uuid_v4 #=> ULID::IrreversibleUUIDError
+  # ulid.to_uuid_v4(force: true) #=> '0186bbe6-72ad-4e3d-9091-abf9cfac65a7'
   # ```
   #
-  # See also [ULID.from_uuidv4], [ULID#to_uuidish], [ulid/spec#64](https://github.com/ulid/spec/issues/64)
-  def to_uuidv4: (?force: boolish) -> String
+  # See also [ULID.from_uuid_v4], [ULID#to_uuidish], [ulid/spec#64](https://github.com/ulid/spec/issues/64)
+  def to_uuid_v4: (?force: boolish) -> String
+
+  # See also [ULID.from_uuid_v7], [ULID#to_uuidish]
+  def to_uuid_v7: (?force: boolish) -> String
 
   # Returns same ID with different Ruby object.
   def dup: -> ULID

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ruby-ulid
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Kenichi Kamiya
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-08 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: "    generator, optional monotonicity, parser and tools for ULID (RBS
   included)\n"
@@ -27,6 +26,7 @@ files:
 - lib/ulid/monotonic_generator.rb
 - lib/ulid/utils.rb
 - lib/ulid/uuid.rb
+- lib/ulid/uuid/fields.rb
 - lib/ulid/version.rb
 - sig/ulid.rbs
 homepage: https://github.com/kachick/ruby-ulid
@@ -34,11 +34,9 @@ licenses:
 - MIT
 metadata:
   documentation_uri: https://kachick.github.io/ruby-ulid/
-  homepage_uri: https://github.com/kachick/ruby-ulid
   source_code_uri: https://github.com/kachick/ruby-ulid
   bug_tracker_uri: https://github.com/kachick/ruby-ulid/issues
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -46,15 +44,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '4.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.6
-signing_key:
+rubygems_version: 4.0.3
 specification_version: 4
 summary: ULID manipulation library
 test_files: []