ruby-ulid 0.9.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c0ca476ab05b4b53ce593e893ffdfd6aa72b3c08563116b95f5a22f43a7926b
-  data.tar.gz: 7454acd393c8df299696d2907a71f994643dacc45103e2874561d186e1fa85c5
+  metadata.gz: 3b0c26b06cd815f96d9ffc78836ceb69ed4677a4f5acfac6e15c016e093e0d18
+  data.tar.gz: '09acd9841d6ee33b87687dd12a7912ef262c9cad3d85b37db6215912048b36e1'
 SHA512:
-  metadata.gz: bfe19e20452a12edd7472ddaf3b9583d2eaa5640e03a081621c35bcfdf218f9ccf5d7c7625b0850312447f61c0592796d333aa4578a6c2f0281e6ff4e8392efd
-  data.tar.gz: cdd8dba77214852ea70d07a137f75098558097db686a4409dd14e611d533de33f4c510b9a38ee232e918dd0aae6b028f19a4dd7312ac42172890d726091f282b
+  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.2 or higher.
+Tested only in the Ruby 4.
 
 Add this line to your `Gemfile`.
 
 ```ruby
-gem('ruby-ulid', '~> 0.9.0')
+gem('ruby-ulid', '~> 1.0.0')
 ```
 
 And load it.
@@ -53,7 +56,7 @@ 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.9.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.
 
@@ -378,44 +381,49 @@ 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"
 ```
 
-[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).

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

@@ -19,13 +19,13 @@ class ULID
         end
       end
 
-      def self.forced_v4_from_octets(octets)
+      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) | 0x4000,
+            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:

data/lib/ulid/uuid.rb

@@ -13,6 +13,7 @@ class ULID
     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,6 +39,18 @@ class ULID
 
       parse_any_to_int(encoded)
     end
+
+    def self.parse_v7_to_int(uuid)
+      encoded = String.try_convert(uuid)
+      raise(ArgumentError, 'should pass a string for UUID parser') unless encoded
+
+      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
+
+      parse_any_to_int(encoded)
+    end
   end
 
   Ractor.make_shareable(UUID)

data/lib/ulid/version.rb

@@ -3,5 +3,5 @@
 # shareable_constant_value: literal
 
 class ULID
-  VERSION = '0.9.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)
 
@@ -510,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
@@ -526,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
@@ -536,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,9 +37,11 @@ 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
+    def self.parse_v7_to_int: (String) -> Integer
 
     class Fields
       attr_reader time_low: Integer
@@ -49,7 +51,7 @@ class ULID < Object
       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 deconstruct: -> Array[Integer]
 
@@ -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
@@ -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
   #
@@ -648,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.\
@@ -657,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.9.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Kenichi Kamiya
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-08-28 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"
@@ -38,7 +37,6 @@ metadata:
   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.2'
+      version: '4.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
-signing_key:
+rubygems_version: 4.0.3
 specification_version: 4
 summary: ULID manipulation library
 test_files: []