ruby-ulid 0.0.16 → 0.1.1

data/lib/ulid/crockford_base32.rb

@@ -0,0 +1,68 @@
+# coding: us-ascii
+# frozen_string_literal: true
+# Copyright (C) 2021 Kenichi Kamiya
+
+class ULID
+  # Currently supporting only for `subset` for actual use-case`
+  # Original decoding spec allows other characters.
+  # But I think ULID should allow `subset` of Crockford's Base32.
+  # See below
+  #   * https://github.com/ulid/spec/pull/57
+  #   * https://github.com/kachick/ruby-ulid/issues/57
+  #   * https://github.com/kachick/ruby-ulid/issues/78
+  module CrockfordBase32
+    class SetupError < ScriptError; end
+
+    n32_chars = [*'0'..'9', *'A'..'V'].map(&:freeze).freeze
+    raise SetupError, 'obvious bug exists in the mapping algorithm' unless n32_chars.size == 32
+
+    n32_char_by_number = {}
+    n32_chars.each_with_index do |char, index|
+      n32_char_by_number[index] = char
+    end
+    n32_char_by_number.freeze
+
+    crockford_base32_mappings = {
+      'J' => 18,
+      'K' => 19,
+      'M' => 20,
+      'N' => 21,
+      'P' => 22,
+      'Q' => 23,
+      'R' => 24,
+      'S' => 25,
+      'T' => 26,
+      'V' => 27,
+      'W' => 28,
+      'X' => 29,
+      'Y' => 30,
+      'Z' => 31
+    }.freeze
+
+    N32_CHAR_BY_CROCKFORD_BASE32_CHAR = CROCKFORD_BASE32_ENCODING_STRING.chars.map(&:freeze).each_with_object({}) do |encoding_char, map|
+      if n = crockford_base32_mappings[encoding_char]
+        char_32 = n32_char_by_number.fetch(n)
+        map[encoding_char] = char_32
+      end
+    end.freeze
+    raise SetupError, 'obvious bug exists in the mapping algorithm' unless N32_CHAR_BY_CROCKFORD_BASE32_CHAR.keys == crockford_base32_mappings.keys
+    CROCKFORD_BASE32_CHAR_PATTERN = /[#{N32_CHAR_BY_CROCKFORD_BASE32_CHAR.keys.join}]/.freeze
+
+    CROCKFORD_BASE32_CHAR_BY_N32_CHAR = N32_CHAR_BY_CROCKFORD_BASE32_CHAR.invert.freeze
+    N32_CHAR_PATTERN = /[#{CROCKFORD_BASE32_CHAR_BY_N32_CHAR.keys.join}]/.freeze
+
+    # @param [String] string
+    # @return [Integer]
+    def self.decode(string)
+      n32encoded = string.upcase.gsub(CROCKFORD_BASE32_CHAR_PATTERN, N32_CHAR_BY_CROCKFORD_BASE32_CHAR)
+      n32encoded.to_i(32)
+    end
+
+    # @param [Integer] integer
+    # @return [String]
+    def self.encode(integer)
+      n32encoded = integer.to_s(32)
+      n32encoded.upcase.gsub(N32_CHAR_PATTERN, CROCKFORD_BASE32_CHAR_BY_N32_CHAR).rjust(ENCODED_LENGTH, '0')
+    end
+  end
+end

data/lib/ulid/monotonic_generator.rb

@@ -4,39 +4,60 @@
 
 class ULID
   class MonotonicGenerator
-    # @api private
-    attr_accessor :latest_milliseconds, :latest_entropy
+    # @return [ULID, nil]
+    attr_reader :prev
+
+    undef_method :instance_variable_set
 
     def initialize
-      reset
+      @mutex = Thread::Mutex.new
+      @prev = nil
+    end
+
+    # @return [String]
+    def inspect
+      "ULID::MonotonicGenerator(prev: #{@prev.inspect})"
     end
+    alias_method :to_s, :inspect
 
     # @param [Time, Integer] moment
     # @return [ULID]
     # @raise [OverflowError] if the entropy part is larger than the ULID limit in same milliseconds
-    # @raise [ArgumentError] if the given moment(milliseconds) is negative number
+    # @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)
-      milliseconds = ULID.milliseconds_from_moment(moment)
-      raise ArgumentError, "milliseconds should not be negative: given: #{milliseconds}" if milliseconds.negative?
-
-      if @latest_milliseconds < milliseconds
-        @latest_milliseconds = milliseconds
-        @latest_entropy = ULID.reasonable_entropy
-      else
-        @latest_entropy += 1
-      end
+      @mutex.synchronize do
+        unless @prev
+          @prev = ULID.generate(moment: moment)
+          return @prev
+        end
 
-      ULID.new milliseconds: @latest_milliseconds, entropy: @latest_entropy
-    end
+        milliseconds = ULID.milliseconds_from_moment(moment)
 
-    # @api private
-    # @return [void]
-    def reset
-      @latest_milliseconds = 0
-      @latest_entropy = ULID.reasonable_entropy
-      nil
+        ulid = if @prev.milliseconds < milliseconds
+          ULID.generate(moment: milliseconds)
+        else
+          ULID.from_milliseconds_and_entropy(milliseconds: @prev.milliseconds, entropy: @prev.entropy.succ)
+        end
+
+        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'
+          else
+            '# NOTE: ran on multi threads, so this might from concurrency issue'
+          end
+
+          raise UnexpectedError, base_message + additional_information
+        end
+
+        @prev = ulid
+        ulid
+      end
     end
 
+    undef_method :freeze
+
     # @raise [TypeError] always raises exception and does not freeze self
     # @return [void]
     def freeze

data/lib/ulid/uuid.rb

@@ -0,0 +1,38 @@
+# coding: us-ascii
+# frozen_string_literal: true
+# Copyright (C) 2021 Kenichi Kamiya
+
+# Extracted features around UUID from some reasons
+# ref:
+#  * https://github.com/kachick/ruby-ulid/issues/105
+#  * https://github.com/kachick/ruby-ulid/issues/76
+class ULID
+  # Imported from https://stackoverflow.com/a/38191104/1212807, thank you!
+  UUIDV4_PATTERN = /\A[0-9A-F]{8}-[0-9A-F]{4}-[4][0-9A-F]{3}-[89AB][0-9A-F]{3}-[0-9A-F]{12}\z/i.freeze
+  private_constant :UUIDV4_PATTERN
+
+  # @param [String, #to_str] uuid
+  # @return [ULID]
+  # @raise [ParserError] if the given format is not correct for UUIDv4 specs
+  def self.from_uuidv4(uuid)
+    uuid = String.try_convert(uuid)
+    raise ArgumentError, 'ULID.from_uuidv4 takes only strings' unless uuid
+
+    prefix_trimmed = uuid.sub(/\Aurn:uuid:/, '')
+    unless UUIDV4_PATTERN.match?(prefix_trimmed)
+      raise ParserError, "given `#{uuid}` does not match to `#{UUIDV4_PATTERN.inspect}`"
+    end
+
+    normalized = prefix_trimmed.gsub(/[^0-9A-Fa-f]/, '')
+    from_integer(normalized.to_i(16))
+  end
+
+  # @return [String]
+  def to_uuidv4
+    # This code referenced https://github.com/ruby/ruby/blob/121fa24a3451b45c41ac0a661b64e9fc8600e589/lib/securerandom.rb#L221-L241
+    array = octets.pack('C*').unpack('NnnnnN')
+    array[2] = (array[2] & 0x0fff) | 0x4000
+    array[3] = (array[3] & 0x3fff) | 0x8000
+    ('%08x-%04x-%04x-%04x-%04x%08x' % array).freeze
+  end
+end

data/lib/ulid/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 class ULID
-  VERSION = '0.0.16'
+  VERSION = '0.1.1'
 end

data/sig/ulid.rbs

@@ -1,10 +1,10 @@
 # Classes
 class ULID
   VERSION: String
-  ENCODING_CHARS: Array[String]
-  TIMESTAMP_PART_LENGTH: 10
-  RANDOMNESS_PART_LENGTH: 16
-  ENCODED_ID_LENGTH: 26
+  CROCKFORD_BASE32_ENCODING_STRING: String
+  TIMESTAMP_ENCODED_LENGTH: 10
+  RANDOMNESS_ENCODED_LENGTH: 16
+  ENCODED_LENGTH: 26
   TIMESTAMP_OCTETS_LENGTH: 6
   RANDOMNESS_OCTETS_LENGTH: 10
   OCTETS_LENGTH: 16
@@ -12,12 +12,11 @@ class ULID
   MAX_ENTROPY: 1208925819614629174706175
   MAX_INTEGER: 340282366920938463463374607431768211455
   TIME_FORMAT_IN_INSPECT: '%Y-%m-%d %H:%M:%S.%3N %Z'
-  PATTERN: Regexp
-  STRICT_PATTERN: Regexp
+  RANDOM_INTEGER_GENERATOR: ^() -> Integer
+  PATTERN_WITH_CROCKFORD_BASE32_SUBSET: Regexp
+  STRICT_PATTERN_WITH_CROCKFORD_BASE32_SUBSET: Regexp
+  SCANNING_PATTERN: Regexp
   UUIDV4_PATTERN: Regexp
-  REPLACING_MAP: Hash[String, String]
-  REPLACING_PATTERN: Regexp
-  MONOTONIC_GENERATOR: MonotonicGenerator
   MIN: ULID
   MAX: ULID
   include Comparable
@@ -34,66 +33,75 @@ class ULID
   class ParserError < Error
   end
 
-  class SetupError < ScriptError
+  class UnexpectedError < Error
+  end
+
+  module CrockfordBase32
+    class SetupError < ScriptError
+    end
+
+    N32_CHAR_BY_CROCKFORD_BASE32_CHAR: Hash[String, String]
+    CROCKFORD_BASE32_CHAR_PATTERN: Regexp
+    CROCKFORD_BASE32_CHAR_BY_N32_CHAR: Hash[String, String]
+    N32_CHAR_PATTERN: Regexp
+
+    def self.encode: (Integer integer) -> String
+    def self.decode: (String string) -> Integer
   end
 
   class MonotonicGenerator
-    attr_accessor latest_milliseconds: Integer
-    attr_accessor latest_entropy: Integer
+    @mutex: Thread::Mutex
+    attr_reader prev: ULID | nil
     def initialize: -> void
     def generate: (?moment: moment) -> ULID
-    def reset: -> void
+    def inspect: -> String
+    alias to_s inspect
     def freeze: -> void
   end
 
+  interface _ULID
+    def to_ulid: () -> ULID
+  end
+
   type octets = [Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer]
   type timestamp_octets = [Integer, Integer, Integer, Integer, Integer, Integer]
   type randomness_octets = [Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer]
+  type period = Range[Time] | Range[nil] | Range[ULID]
 
-  @milliseconds: Integer
-  @entropy: Integer
   @string: String?
-  @integer: Integer?
-  @octets: octets?
-  @timestamp_octets: timestamp_octets?
-  @randomness_octets: randomness_octets?
+  @integer: Integer
   @timestamp: String?
   @randomness: String?
   @inspect: String?
   @time: Time?
-  @next: ULID?
-  @pattern: Regexp?
-  @strict_pattern: Regexp?
-  @uuidv4: String?
-  @matchdata: MatchData?
 
-  def self.generate: (?moment: moment, ?entropy: Integer) -> ULID
-  def self.monotonic_generate: -> ULID
+  def self.generate: (?moment: moment, ?entropy: Integer) -> self
+  def self.at: (Time time) -> self
   def self.current_milliseconds: -> Integer
-  def self.milliseconds_from_time: (Time time) -> Integer
   def self.milliseconds_from_moment: (moment moment) -> Integer
-  def self.range: (Range[Time] | Range[nil] time_range) -> Range[ULID]
+  def self.range: (period period) -> Range[ULID]
   def self.floor: (Time time) -> Time
-  def self.reasonable_entropy: -> Integer
-  def self.parse: (String string) -> ULID
+  def self.parse: (String string) -> self
   def self.from_uuidv4: (String uuid) -> ULID
-  def self.from_integer: (Integer integer) -> ULID
-  def self.min: (?moment: moment) -> ULID
-  def self.max: (?moment: moment) -> ULID
+  def self.from_integer: (Integer integer) -> self
+  def self.min: (?moment moment) -> ULID
+  def self.max: (?moment moment) -> ULID
+  def self.sample: (?period: period) -> self
+                 | (Integer number, ?period: period) -> Array[self]
   def self.valid?: (untyped string) -> bool
-  def self.scan:  (String string) -> Enumerator[ULID, singleton(ULID)]
-                | (String string) { (ULID ulid) -> void } -> singleton(ULID)
-  def self.octets_from_integer: (Integer integer, length: Integer) -> Array[Integer]
-  def self.inverse_of_digits: (Array[Integer] reversed_digits) -> Integer
-  def self.convert_crockford_base32_to_n32: (String) -> String
+  def self.scan:  (String string) -> Enumerator[self, singleton(ULID)]
+                | (String string) { (self ulid) -> void } -> singleton(ULID)
+  def self.from_milliseconds_and_entropy: (milliseconds: Integer, entropy: Integer) -> self
+  def self.try_convert: (_ULID) -> self
+                      | (untyped) -> nil
   attr_reader milliseconds: Integer
   attr_reader entropy: Integer
-  def initialize: (milliseconds: Integer, entropy: Integer) -> void
+  def initialize: (milliseconds: Integer, entropy: Integer, integer: Integer) -> void
   def to_s: -> String
   def to_i: -> Integer
   alias hash to_i
   def <=>: (ULID other) -> Integer
-         | (untyped other) -> Integer?
+         | (untyped other) -> nil
   def inspect: -> String
   def eql?: (untyped other) -> bool
   alias == eql?
@@ -101,8 +109,7 @@ class ULID
   def to_time: -> Time
   def timestamp: -> String
   def randomness: -> String
-  def pattern: -> Regexp
-  def strict_pattern: -> Regexp
+  def patterns: -> Hash[Symbol, Regexp | String]
   def octets: -> octets
   def timestamp_octets: -> timestamp_octets
   def randomness_octets: -> randomness_octets
@@ -111,9 +118,14 @@ class ULID
   alias succ next
   def pred: -> ULID?
   def freeze: -> self
+  def to_ulid: -> self
+  def dup: -> self
+  # Same as https://github.com/ruby/rbs/blob/4fb4c33b2325d1a73d79ff7aaeb49f21cec1e0e5/core/object.rbs#L79
+  def clone: (?freeze: bool) -> self
 
   private
-  def self.argument_error_for_range_building: (untyped argument) -> ArgumentError
-  def matchdata: -> MatchData
+  def self.reasonable_entropy: -> Integer
+  def self.milliseconds_from_time: (Time time) -> Integer
+  def self.safe_get_class_name: (untyped object) -> String
   def cache_all_instance_variables: -> void
 end

metadata

@@ -1,35 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: ruby-ulid
 version: !ruby/object:Gem::Version
-  version: 0.0.16
+  version: 0.1.1
 platform: ruby
 authors:
 - Kenichi Kamiya
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-05-05 00:00:00.000000000 Z
+date: 2021-05-15 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: integer-base
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.1.2
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: 0.2.0
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.1.2
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: 0.2.0
 - !ruby/object:Gem::Dependency
   name: rbs
   requirement: !ruby/object:Gem::Requirement
@@ -97,7 +77,9 @@ files:
 - LICENSE
 - README.md
 - lib/ulid.rb
+- lib/ulid/crockford_base32.rb
 - lib/ulid/monotonic_generator.rb
+- lib/ulid/uuid.rb
 - lib/ulid/version.rb
 - sig/ulid.rbs
 homepage: https://github.com/kachick/ruby-ulid