ruby-ulid 0.0.7 → 0.0.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1f33ff714eef2b217cb557fe4ae46087a77b834aa42c406e940f2f8a6630464c
-  data.tar.gz: ce004faa759110d8494f34a058230a90d7231af4a309c5c7bf66b0f0963bcf81
+  metadata.gz: 0adfc974863e1b2d248eac28305322e20d6b2dc94465b7ca3462fdd2c8676352
+  data.tar.gz: caecb83a030fa1eda5534e748ee3206208ebf25a1d9f76d33ad04030b4ea0f0c
 SHA512:
-  metadata.gz: d60377fcf5cd9523b09eb78be1feef0fb996b9f6ebf0e430db9bf3902899ee6e6e6d62518a9f33ecfb5d6786390e08bbf545d5a9b36f141fd4a95bc7ff8f6612
-  data.tar.gz: 981bafadfcbb63254a276a1ae9b201b2b636555416450ce421ffa0f4482e343072811623ae4856970904227ae0da0fe2f991ffc809556d4bc6a33a910446c7dd
+  metadata.gz: 4a216a8032385e9be00252fb0d9faf1aaa18bdfe75a0ae4b0a2cb1aa438a8786a7e9c477debd87fb6871274c0a50e1579cee41584513199c47b0198c51c6ac6a
+  data.tar.gz: 664d85fe6070a9c0017e831727a33a87799d1b10e7c4992b44b77be288fcc3cab51ecb528ce01fe0ce5d7a6262f61a2786ce30c54dcd90e8ef36c698f3f76f45

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Kenichi Kamiya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,210 @@
+# ruby-ulid
+
+A handy `ULID` library
+
+The `ULID` spec is defined on [ulid/spec](https://github.com/ulid/spec).
+This gem aims to provide the generator, monotonic generator, parser and handy manipulation features around the ULID.
+Also providing rbs signature files.
+
+---
+
+![ULIDlogo](https://raw.githubusercontent.com/kachick/ruby-ulid/main/logo.png)
+
+![Build Status](https://github.com/kachick/ruby-ulid/actions/workflows/test.yml/badge.svg?branch=main)
+[![Gem Version](https://badge.fury.io/rb/ruby-ulid.png)](http://badge.fury.io/rb/ruby-ulid)
+
+## Universally Unique Lexicographically Sortable Identifier
+
+UUID can be suboptimal for many uses-cases because:
+
+- It isn't the most character efficient way of encoding 128 bits of randomness
+- UUID v1/v2 is impractical in many environments, as it requires access to a unique, stable MAC address
+- UUID v3/v5 requires a unique seed and produces randomly distributed IDs, which can cause fragmentation in many data structures
+- UUID v4 provides no other information than randomness which can cause fragmentation in many data structures
+
+Instead, herein is proposed ULID:
+
+- 128-bit compatibility with UUID
+- 1.21e+24 unique ULIDs per millisecond
+- Lexicographically sortable!
+- Canonically encoded as a 26 character string, as opposed to the 36 character UUID
+- Uses Crockford's base32 for better efficiency and readability (5 bits per character)
+- Case insensitive
+- No special characters (URL safe)
+- Monotonic sort order (correctly detects and handles the same millisecond)
+
+## Install
+
+```console
+$ gem install ruby-ulid
+#=> Installed
+```
+
+## Usage
+
+The generated `ULID` is an object not just a string.
+It means easily get the timestamps and binary formats.
+
+```ruby
+require 'ulid'
+
+ulid = ULID.generate #=> ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GRMJ9AA)
+ulid.to_time #=> 2021-04-27 17:27:22.826 UTC
+ulid.to_s #=> "01F4A5Y1YAQCYAYCTC7GRMJ9AA"
+ulid.octets #=> [1, 121, 20, 95, 7, 202, 187, 60, 175, 51, 76, 60, 49, 73, 37, 74]
+ulid.pattern #=> /(?<timestamp>01F4A5Y1YA)(?<randomness>QCYAYCTC7GRMJ9AA)/i
+```
+
+Generator can take `Time` instance
+
+```ruby
+time = Time.at(946684800, in: 'UTC') #=> 2000-01-01 00:00:00 UTC
+ULID.generate(moment: time) #=> ULID(2000-01-01 00:00:00.000 UTC: 00VHNCZB00N018DCPJA4H9379P)
+ULID.generate(moment: time) #=> ULID(2000-01-01 00:00:00.000 UTC: 00VHNCZB006WQT3JTMN0T14EBP)
+
+ulids = 1000.times.map do
+  ULID.generate(moment: time)
+end
+ulids.sort == ulids #=> false
+
+ulids = 1000.times.map do |n|
+  ULID.generate(moment: time + n)
+end
+ulids.sort == ulids #=> true
+```
+
+You can parse from exists IDs
+
+FYI: Current parser/validator/matcher implementation aims `strict`, It might be changed in [ulid/spec#57](https://github.com/ulid/spec/pull/57) and [ruby-ulid#57](https://github.com/kachick/ruby-ulid/issues/57).
+
+```ruby
+ulid = ULID.parse('01ARZ3NDEKTSV4RRFFQ69G5FAV') #=> ULID(2016-07-30 23:54:10.259 UTC: 01ARZ3NDEKTSV4RRFFQ69G5FAV)
+ulid.to_time #=> 2016-07-30 23:54:10.259 UTC
+```
+
+ULIDs are sortable when they are generated in different timestamp with milliseconds precision
+
+```ruby
+ulids = 1000.times.map do
+  sleep(0.001)
+  ULID.generate
+end
+ulids.sort == ulids #=> true
+ulids.uniq(&:to_time).size #=> 1000
+```
+
+The basic generator prefers `randomness`, it does not guarantee `sortable` for same milliseconds ULIDs.
+
+```ruby
+ulids = 10000.times.map do
+  ULID.generate
+end
+ulids.uniq(&:to_time).size #=> 35 (the size is not fixed, might be changed in environment)
+ulids.sort == ulids #=> false
+```
+
+If you want to prefer `sortable` rather than the `strict randomness`, 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)
+
+```ruby
+monotonic_generator = ULID::MonotonicGenerator.new
+monotonic_ulids = 10000.times.map do
+  monotonic_generator.generate
+end
+sample_ulids_by_the_time = monotonic_ulids.uniq(&:to_time)
+sample_ulids_by_the_time.size #=> 34 (the size is not fixed, might be changed in environment)
+sample_ulids_by_the_time.take(10).map(&:randomness)
+#=>
+["JZW56CTA8704D5AQ",
+ "JGEBH2A2B2EA97MW",
+ "0XPE4NS3MZH0NAJ4",
+ "E0S3ZAVADFBPW57Y",
+ "E5CX1T6281443THQ",
+ "3SK8WHSH03CVF7J2",
+ "DDS35BT0R20P3V49",
+ "60KG2W9FVEN1ZX8C",
+ "X59YJVXXVH7AXJJE",
+ "1ZBQ7SNGFKXGH1Y4"]
+
+monotonic_ulids.sort == monotonic_ulids #=> true
+```
+
+For rough operations, `ULID.scan` might be useful.
+
+```ruby
+json =<<'EOD'
+{
+  "id": "01F4GNAV5ZR6FJQ5SFQC7WDSY3",
+  "author": {
+    "id": "01F4GNBXW1AM2KWW52PVT3ZY9X",
+    "name": "kachick"
+  },
+  "title": "My awesome blog post",
+  "comments": [
+    {
+      "id": "01F4GNCNC3CH0BCRZBPPDEKBKS",
+      "commenter": {
+        "id": "01F4GNBXW1AM2KWW52PVT3ZY9X",
+        "name": "kachick"
+      }
+    },
+    {
+      "id": "01F4GNCXAMXQ1SGBH5XCR6ZH0M",
+      "commenter": {
+        "id": "01F4GND4RYYSKNAADHQ9BNXAWJ",
+        "name": "pankona"
+      }
+    }
+  ]
+}
+EOD
+
+ULID.scan(json).to_a
+#=>
+[ULID(2021-04-30 05:51:57.119 UTC: 01F4GNAV5ZR6FJQ5SFQC7WDSY3),
+ ULID(2021-04-30 05:52:32.641 UTC: 01F4GNBXW1AM2KWW52PVT3ZY9X),
+ ULID(2021-04-30 05:52:56.707 UTC: 01F4GNCNC3CH0BCRZBPPDEKBKS),
+ ULID(2021-04-30 05:52:32.641 UTC: 01F4GNBXW1AM2KWW52PVT3ZY9X),
+ ULID(2021-04-30 05:53:04.852 UTC: 01F4GNCXAMXQ1SGBH5XCR6ZH0M),
+ ULID(2021-04-30 05:53:12.478 UTC: 01F4GND4RYYSKNAADHQ9BNXAWJ)]
+```
+
+`ULID.min` and `ULID.max` return termination values for ULID spec.
+
+```ruby
+ULID.min #=> ULID(1970-01-01 00:00:00.000 UTC: 00000000000000000000000000)
+ULID.max #=> ULID(10889-08-02 05:31:50.655 UTC: 7ZZZZZZZZZZZZZZZZZZZZZZZZZ)
+
+time = Time.at(946684800, Rational('123456.789')).utc #=> 2000-01-01 00:00:00.123456789 UTC
+ULID.min(moment: time) #=> ULID(2000-01-01 00:00:00.123 UTC: 00VHNCZB3V0000000000000000)
+ULID.max(moment: time) #=> ULID(2000-01-01 00:00:00.123 UTC: 00VHNCZB3VZZZZZZZZZZZZZZZZ)
+```
+
+`ULID#next` and `ULID#succ` returns next(successor) ULID
+
+```ruby
+ULID.parse('01BX5ZZKBKZZZZZZZZZZZZZZZY').next.to_s #=> "01BX5ZZKBKZZZZZZZZZZZZZZZZ"
+ULID.parse('01BX5ZZKBKZZZZZZZZZZZZZZZZ').next.to_s #=> "01BX5ZZKBM0000000000000000"
+ULID.parse('7ZZZZZZZZZZZZZZZZZZZZZZZZZ').next #=> nil
+```
+
+`ULID#pred` returns predecessor ULID
+
+```ruby
+ULID.parse('01BX5ZZKBK0000000000000001').pred.to_s #=> "01BX5ZZKBK0000000000000000"
+ULID.parse('01BX5ZZKBK0000000000000000').pred.to_s #=> "01BX5ZZKBJZZZZZZZZZZZZZZZZ"
+ULID.parse('00000000000000000000000000').pred #=> nil
+```
+
+UUIDv4 converter for migration use-cases. (Of course the timestamp will be useless one. Sortable benefit is lost.)
+
+```ruby
+ULID.from_uuidv4('0983d0a2-ff15-4d83-8f37-7dd945b5aa39')
+#=> ULID(2301-07-10 00:28:28.821 UTC: 09GF8A5ZRN9P1RYDVXV52VBAHS)
+```
+
+## References
+
+- [API documents](https://kachick.github.io/ruby-ulid/)
+- [ulid/spec](https://github.com/ulid/spec)
+- [Another choices are UUIDv6, UUIDv7, UUIDv8. But they are still in draft state](https://www.ietf.org/archive/id/draft-peabody-dispatch-new-uuid-format-01.html)

data/Steepfile

@@ -0,0 +1,7 @@
+target :lib do
+  signature 'sig'
+
+  check 'lib'
+
+  library 'securerandom'
+end

data/lib/ulid.rb

@@ -3,11 +3,13 @@
 # Copyright (C) 2021 Kenichi Kamiya
 
 require 'securerandom'
-require 'singleton'
 require 'integer/base'
-require_relative 'ulid/version'
 
 # @see https://github.com/ulid/spec
+# @!attribute [r] milliseconds
+#   @return [Integer]
+# @!attribute [r] entropy
+#   @return [Integer]
 class ULID
   include Comparable
 
@@ -15,90 +17,137 @@ class ULID
   class OverflowError < Error; end
   class ParserError < Error; end
 
+  encoding_string = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'
   # Crockford's Base32. Excluded I, L, O, U.
   # @see https://www.crockford.com/base32.html
-  ENCODING_CHARS = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'.chars.map(&:freeze).freeze
+  ENCODING_CHARS = encoding_string.chars.map(&:freeze).freeze
 
-  TIME_PART_LENGTH = 10
+  TIMESTAMP_PART_LENGTH = 10
   RANDOMNESS_PART_LENGTH = 16
-  ENCODED_ID_LENGTH = TIME_PART_LENGTH + RANDOMNESS_PART_LENGTH
-  TIME_OCTETS_LENGTH = 6
+  ENCODED_ID_LENGTH = TIMESTAMP_PART_LENGTH + RANDOMNESS_PART_LENGTH
+  TIMESTAMP_OCTETS_LENGTH = 6
   RANDOMNESS_OCTETS_LENGTH = 10
-  OCTETS_LENGTH = TIME_OCTETS_LENGTH + RANDOMNESS_OCTETS_LENGTH
+  OCTETS_LENGTH = TIMESTAMP_OCTETS_LENGTH + RANDOMNESS_OCTETS_LENGTH
   MAX_MILLISECONDS = 281474976710655
   MAX_ENTROPY = 1208925819614629174706175
+  MAX_INTEGER = 340282366920938463463374607431768211455
+  PATTERN = /(?<timestamp>[0-7][#{encoding_string}]{#{TIMESTAMP_PART_LENGTH - 1}})(?<randomness>[#{encoding_string}]{#{RANDOMNESS_PART_LENGTH}})/i.freeze
+  STRICT_PATTERN = /\A#{PATTERN.source}\z/i.freeze
+
+  # 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
 
   # Same as Time#inspect since Ruby 2.7, just to keep backward compatibility
   # @see https://bugs.ruby-lang.org/issues/15958
   TIME_FORMAT_IN_INSPECT = '%Y-%m-%d %H:%M:%S.%3N %Z'
 
-  class MonotonicGenerator
-    include Singleton
-
-    attr_accessor :latest_milliseconds, :latest_entropy
-
-    def initialize
-      reset
-    end
+  # @param [Integer, Time] moment
+  # @param [Integer] entropy
+  # @return [ULID]
+  def self.generate(moment: current_milliseconds, entropy: reasonable_entropy)
+    new milliseconds: milliseconds_from_moment(moment), entropy: entropy
+  end
 
-    # @return [ULID]
-    def generate
-      milliseconds = ULID.current_milliseconds
-      reasonable_entropy = ULID.reasonable_entropy
+  # @param [Integer, Time] moment
+  # @return [ULID]
+  def self.min(moment: 0)
+    generate(moment: moment, entropy: 0)
+  end
 
-      @latest_milliseconds ||= milliseconds
-      @latest_entropy ||= reasonable_entropy
-      if @latest_milliseconds != milliseconds
-        @latest_milliseconds = milliseconds
-        @latest_entropy = reasonable_entropy
-      else
-        @latest_entropy += 1
-      end
+  # @param [Integer, Time] moment
+  # @return [ULID]
+  def self.max(moment: MAX_MILLISECONDS)
+    generate(moment: moment, entropy: MAX_ENTROPY)
+  end
 
-      ULID.new milliseconds: milliseconds, entropy: @latest_entropy
+  # @deprecated This method actually changes class state. Use {ULID::MonotonicGenerator} instead.
+  # @raise [OverflowError] if the entropy part is larger than the ULID limit in same milliseconds
+  # @return [ULID]
+  def self.monotonic_generate
+    warning = "`ULID.monotonic_generate` actually changes class state. Use `ULID::MonotonicGenerator` instead."
+    if RUBY_VERSION >= '3.0'
+      Warning.warn(warning, category: :deprecated)
+    else
+      Warning.warn(warning)
     end
 
-    # @return [self]
-    def reset
-      @latest_milliseconds = nil
-      @latest_entropy = nil
-      self
-    end
+    MONOTONIC_GENERATOR.generate
+  end
 
-    # @return [void]
-    def freeze
-      raise TypeError, "cannot freeze #{self.class}"
+  # @param [String, #to_str] string
+  # @return [Enumerator]
+  # @yieldparam [ULID] ulid
+  # @yieldreturn [self]
+  def self.scan(string)
+    string = string.to_str
+    return to_enum(__callee__, string) unless block_given?
+    string.scan(PATTERN) do |pair|
+      yield parse(pair.join)
     end
+    self
   end
 
-  MONOTONIC_GENERATOR = MonotonicGenerator.instance
-
-  private_constant :ENCODING_CHARS, :TIME_FORMAT_IN_INSPECT, :MonotonicGenerator
+  # @param [String, #to_str] uuid
+  # @return [ULID]
+  # @raise [ParserError] if the given format is not correct for UUIDv4 specs
+  def self.from_uuidv4(uuid)
+    begin
+      uuid = uuid.to_str
+      prefix_trimmed = uuid.sub(/\Aurn:uuid:/, '')
+      raise "given string is not matched to pattern #{UUIDV4_PATTERN.inspect}" unless UUIDV4_PATTERN.match?(prefix_trimmed)
+      normalized = prefix_trimmed.gsub(/[^0-9A-Fa-f]/, '')
+      from_integer(normalized.to_i(16))
+    rescue => err
+      raise ParserError, "parsing failure as #{err.inspect} for given #{uuid}"
+    end
+  end
 
-  # @param [Integer, Time] moment
-  # @param [Integer] entropy
+  # @param [Integer, #to_int] integer
   # @return [ULID]
-  def self.generate(moment: current_milliseconds, entropy: reasonable_entropy)
-    milliseconds = moment.kind_of?(Time) ? time_to_milliseconds(moment) : moment
+  # @raise [OverflowError] if the given integer is larger than the ULID limit
+  # @raise [ArgumentError] if the given integer is negative number
+  # @todo Need optimized for performance
+  def self.from_integer(integer)
+    integer = integer.to_int
+    raise OverflowError, "integer overflow: given #{integer}, max: #{MAX_INTEGER}" unless integer <= MAX_INTEGER
+    raise ArgumentError, "integer should not be negative: given: #{integer}" if integer.negative?
+
+    octets = octets_from_integer(integer, length: OCTETS_LENGTH).freeze
+    time_octets = octets.slice(0, TIMESTAMP_OCTETS_LENGTH).freeze
+    randomness_octets = octets.slice(TIMESTAMP_OCTETS_LENGTH, RANDOMNESS_OCTETS_LENGTH).freeze
+    milliseconds = inverse_of_digits(time_octets)
+    entropy = inverse_of_digits(randomness_octets)
+
     new milliseconds: milliseconds, entropy: entropy
   end
 
-  # @return [ULID]
-  def self.monotonic_generate
-    MONOTONIC_GENERATOR.generate
+  # @param [Time] time
+  # @return [Time]
+  def self.floor(time)
+    if RUBY_VERSION >= '2.7'
+      time.floor(3)
+    else
+      Time.at(0, milliseconds_from_time(time), :millisecond)
+    end
   end
 
   # @return [Integer]
   def self.current_milliseconds
-    time_to_milliseconds(Time.now)
+    milliseconds_from_time(Time.now)
   end
 
   # @param [Time] time
   # @return [Integer]
-  def self.time_to_milliseconds(time)
+  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)
+    moment.kind_of?(Time) ? milliseconds_from_time(moment) : moment.to_int
+  end
+
   # @return [Integer]
   def self.reasonable_entropy
     SecureRandom.random_number(MAX_ENTROPY)
@@ -106,14 +155,16 @@ class ULID
 
   # @param [String, #to_str] string
   # @return [ULID]
+  # @raise [ParserError] if the given format is not correct for ULID specs
+  # @raise [OverflowError] if the given value is larger than the ULID limit
   def self.parse(string)
     begin
       string = string.to_str
       unless string.size == ENCODED_ID_LENGTH
         raise "parsable string must be #{ENCODED_ID_LENGTH} characters, but actually given #{string.size} characters"
       end
-      timestamp = string.slice(0, TIME_PART_LENGTH)
-      randomness = string.slice(TIME_PART_LENGTH, RANDOMNESS_PART_LENGTH)
+      timestamp = string.slice(0, TIMESTAMP_PART_LENGTH)
+      randomness = string.slice(TIMESTAMP_PART_LENGTH, RANDOMNESS_PART_LENGTH)
       milliseconds = Integer::Base.parse(timestamp, ENCODING_CHARS)
       entropy = Integer::Base.parse(randomness, ENCODING_CHARS)
     rescue => err
@@ -123,7 +174,6 @@ class ULID
     new milliseconds: milliseconds, entropy: entropy
   end
 
-  # @param [String] string
   # @return [Boolean]
   def self.valid?(string)
     parse(string)
@@ -133,8 +183,39 @@ class ULID
     true
   end
 
+  # @api private
+  # @param [Integer] integer
+  # @param [Integer] length
+  # @return [Array<Integer>]
+  def self.octets_from_integer(integer, length:)
+    digits = integer.digits(256)
+    (length - digits.size).times do
+      digits.push 0
+    end
+    digits.reverse!
+  end
+
+  # @api private
+  # @see The logics taken from https://bugs.ruby-lang.org/issues/14401, thanks!
+  # @param [Array<Integer>] reversed_digits
+  # @return [Integer]
+  def self.inverse_of_digits(reversed_digits)
+    base = 256
+    num = 0
+    reversed_digits.each do |digit|
+      num = (num * base) + digit
+    end
+    num
+  end
+
   attr_reader :milliseconds, :entropy
 
+  # @api private
+  # @param [Integer] milliseconds
+  # @param [Integer] entropy
+  # @return [void]
+  # @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 initialize(milliseconds:, entropy:)
     milliseconds = milliseconds.to_int
     entropy = entropy.to_int
@@ -154,13 +235,13 @@ class ULID
 
   # @return [Integer]
   def to_i
-    @integer ||= inverse_of_digits(octets)
+    @integer ||= self.class.inverse_of_digits(octets)
   end
   alias_method :hash, :to_i
 
   # @return [Integer, nil]
   def <=>(other)
-    other.kind_of?(self.class) ? (to_i <=> other.to_i) : nil
+    other.kind_of?(ULID) ? (to_i <=> other.to_i) : nil
   end
 
   # @return [String]
@@ -170,7 +251,7 @@ class ULID
 
   # @return [Boolean]
   def eql?(other)
-    other.equal?(self) || (other.kind_of?(self.class) && other.to_i == to_i)
+    other.equal?(self) || (other.kind_of?(ULID) && other.to_i == to_i)
   end
   alias_method :==, :eql?
 
@@ -192,62 +273,90 @@ class ULID
 
   # @return [Time]
   def to_time
-    @time ||= Time.at(0, @milliseconds, :millisecond).utc
+    @time ||= begin
+      if RUBY_VERSION >= '2.7'
+        Time.at(0, @milliseconds, :millisecond, in: 'UTC').freeze
+      else
+        Time.at(0, @milliseconds, :millisecond).utc.freeze
+      end
+    end
   end
 
-  # @return [Array<Integer>]
+  # @return [Array(Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer)]
   def octets
-    @octets ||= (time_octets + randomness_octets).freeze
+    @octets ||= (timestamp_octets + randomness_octets).freeze
   end
 
-  # @return [Array<Integer>]
-  def time_octets
-    @time_octets ||= octets_from_integer(@milliseconds, length: TIME_OCTETS_LENGTH).freeze
+  # @return [Array(Integer, Integer, Integer, Integer, Integer, Integer)]
+  def timestamp_octets
+    @timestamp_octets ||= self.class.octets_from_integer(@milliseconds, length: TIMESTAMP_OCTETS_LENGTH).freeze
   end
 
-  # @return [Array<Integer>]
+  # @return [Array(Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer)]
   def randomness_octets
-    @randomness_octets ||= octets_from_integer(@entropy, length: RANDOMNESS_OCTETS_LENGTH).freeze
+    @randomness_octets ||= self.class.octets_from_integer(@entropy, length: RANDOMNESS_OCTETS_LENGTH).freeze
   end
 
-  # @return [ULID]
+  # @return [String]
+  def timestamp
+    @timestamp ||= matchdata[:timestamp].freeze
+  end
+
+  # @return [String]
+  def randomness
+    @randomness ||= matchdata[:randomness].freeze
+  end
+
+  # @return [Regexp]
+  def pattern
+    @pattern ||= /(?<timestamp>#{timestamp})(?<randomness>#{randomness})/i.freeze
+  end
+
+  # @return [Regexp]
+  def strict_pattern
+    @strict_pattern ||= /\A#{pattern.source}\z/i.freeze
+  end
+
+  # @return [ULID, nil] when called on ULID as `7ZZZZZZZZZZZZZZZZZZZZZZZZZ`, returns `nil` instead of ULID
   def next
-    @next ||= self.class.new(milliseconds: @milliseconds, entropy: @entropy + 1)
+    next_int = to_i.next
+    return nil if next_int > MAX_INTEGER
+    @next ||= self.class.from_integer(next_int)
   end
   alias_method :succ, :next
 
+  # @return [ULID, nil] when called on ULID as `00000000000000000000000000`, returns `nil` instead of ULID
+  def pred
+    pre_int = to_i.pred
+    return nil if pre_int.negative?
+    @pred ||= self.class.from_integer(pre_int)
+  end
+
   # @return [self]
   def freeze
     # Evaluate all caching
     inspect
     octets
-    succ
     to_i
+    succ
+    pred
+    strict_pattern
     super
   end
 
   private
 
-  # @param [Integer] integer
-  # @param [Integer] length
-  # @return [Array<Integer>]
-  def octets_from_integer(integer, length:)
-    digits = integer.digits(256)
-    (length - digits.size).times do
-      digits.push 0
-    end
-    digits.reverse!
+  # @return [MatchData]
+  def matchdata
+    @matchdata ||= STRICT_PATTERN.match(to_str).freeze
   end
+end
 
-  # @see The logics taken from https://bugs.ruby-lang.org/issues/14401, thanks!
-  # @param [Array<Integer>] reversed_digits
-  # @return [Integer]
-  def inverse_of_digits(reversed_digits)
-    base = 256
-    num = 0
-    reversed_digits.each do |digit|
-      num = (num * base) + digit
-    end
-    num
-  end
+require_relative 'ulid/version'
+require_relative 'ulid/monotonic_generator'
+
+class ULID
+  MONOTONIC_GENERATOR = MonotonicGenerator.new
+
+  private_constant :ENCODING_CHARS, :TIME_FORMAT_IN_INSPECT, :UUIDV4_PATTERN
 end

data/lib/ulid/monotonic_generator.rb

@@ -0,0 +1,46 @@
+# coding: us-ascii
+# frozen_string_literal: true
+# Copyright (C) 2021 Kenichi Kamiya
+
+class ULID
+  class MonotonicGenerator
+    # @api private
+    attr_accessor :latest_milliseconds, :latest_entropy
+
+    def initialize
+      reset
+    end
+
+    # @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
+    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
+
+      ULID.new milliseconds: @latest_milliseconds, entropy: @latest_entropy
+    end
+
+    # @api private
+    # @return [void]
+    def reset
+      @latest_milliseconds = 0
+      @latest_entropy = ULID.reasonable_entropy
+      nil
+    end
+
+    # @raise [TypeError] always raises exception and does not freeze self
+    # @return [void]
+    def freeze
+      raise TypeError, "cannot freeze #{self.class}"
+    end
+  end
+end

data/lib/ulid/version.rb

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

data/sig/ulid.rbs

@@ -2,74 +2,105 @@
 class ULID
   VERSION: String
   ENCODING_CHARS: Array[String]
-  TIME_PART_LENGTH: Integer
-  RANDOMNESS_PART_LENGTH: Integer
-  ENCODED_ID_LENGTH: Integer
-  TIME_OCTETS_LENGTH: Integer
-  RANDOMNESS_OCTETS_LENGTH: Integer
-  OCTETS_LENGTH: Integer
-  MAX_MILLISECONDS: Integer
-  MAX_ENTROPY: Integer
-  TIME_FORMAT_IN_INSPECT: String
+  TIMESTAMP_PART_LENGTH: 10
+  RANDOMNESS_PART_LENGTH: 16
+  ENCODED_ID_LENGTH: 26
+  TIMESTAMP_OCTETS_LENGTH: 6
+  RANDOMNESS_OCTETS_LENGTH: 10
+  OCTETS_LENGTH: 16
+  MAX_MILLISECONDS: 281474976710655
+  MAX_ENTROPY: 1208925819614629174706175
+  MAX_INTEGER: 340282366920938463463374607431768211455
+  TIME_FORMAT_IN_INSPECT: '%Y-%m-%d %H:%M:%S.%3N %Z'
+  PATTERN: Regexp
+  STRICT_PATTERN: Regexp
+  UUIDV4_PATTERN: Regexp
   MONOTONIC_GENERATOR: MonotonicGenerator
   include Comparable
-  @string: String
-  @integer: Integer
-  @octets: Array[Integer]
-  @time_octets: Array[Integer]
-  @randomness_octets: Array[Integer]
-  @inspect: String
-  @time: Time
-  @next: ULID
 
-  def self.generate: (?moment: Time | Integer, ?entropy: Integer) -> ULID
+  type moment = Time | Integer
+
+  class Error < StandardError
+  end
+
+  class OverflowError < Error
+  end
+
+  class ParserError < Error
+  end
+
+  class MonotonicGenerator
+    attr_accessor latest_milliseconds: Integer
+    attr_accessor latest_entropy: Integer
+    def initialize: -> void
+    def generate: (?moment: moment) -> ULID
+    def reset: -> void
+    def freeze: -> void
+  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]
+
+  @milliseconds: Integer
+  @entropy: Integer
+  @string: String?
+  @integer: Integer?
+  @octets: octets?
+  @timestamp_octets: timestamp_octets?
+  @randomness_octets: randomness_octets?
+  @timestamp: String?
+  @randomness: String?
+  @inspect: String?
+  @time: Time?
+  @next: ULID?
+  @pattern: Regexp?
+  @strict_pattern: Regexp?
+  @matchdata: MatchData?
+
+  def self.generate: (?moment: moment, ?entropy: Integer) -> ULID
   def self.monotonic_generate: -> ULID
   def self.current_milliseconds: -> Integer
-  def self.time_to_milliseconds: (Time time) -> Integer
+  def self.milliseconds_from_time: (Time time) -> Integer
+  def self.milliseconds_from_moment: (moment moment) -> Integer
+  def self.floor: (Time time) -> Time
   def self.reasonable_entropy: -> Integer
   def self.parse: (String string) -> ULID
+  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.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
   attr_reader milliseconds: Integer
   attr_reader entropy: Integer
   def initialize: (milliseconds: Integer, entropy: Integer) -> void
   def to_str: -> String
-  def to_s: -> String
+  alias to_s to_str
   def to_i: -> Integer
-  def hash: -> Integer
-  def <=>: (untyped other) -> Integer?
+  alias hash to_i
+  def <=>: (ULID other) -> Integer
+         | (untyped other) -> Integer?
   def inspect: -> String
   def eql?: (untyped other) -> bool
-  def ==: (untyped other) -> bool
+  alias == eql?
   def ===: (untyped other) -> bool
   def to_time: -> Time
-  def octets: -> Array[Integer]
-  def time_octets: -> Array[Integer]
-  def randomness_octets: -> Array[Integer]
-  def next: -> ULID
-  def succ: -> ULID
+  def timestamp: -> String
+  def randomness: -> String
+  def pattern: -> Regexp
+  def strict_pattern: -> Regexp
+  def octets: -> octets
+  def timestamp_octets: -> timestamp_octets
+  def randomness_octets: -> randomness_octets
+  def next: -> ULID?
+  alias succ next
+  def pred: -> ULID?
   def freeze: -> self
 
   private
-  def octets_from_integer: (Integer integer, length: Integer) -> Array[Integer]
-  def inverse_of_digits: (Array[Integer] reversed_digits) -> Integer
-
-  class Error < StandardError
-  end
-
-  class OverflowError < Error
-  end
-
-  class ParserError < Error
-  end
-
-  class MonotonicGenerator
-    include Singleton
-
-    attr_accessor latest_milliseconds: Integer?
-    attr_accessor latest_entropy: Integer?
-    def initialize: -> void
-    def generate: -> ULID
-    def reset: -> void
-    def freeze: -> void
-  end
+  def matchdata: -> MatchData
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-ulid
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 0.0.12
 platform: ruby
 authors:
 - Kenichi Kamiya
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-04-29 00:00:00.000000000 Z
+date: 2021-05-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: integer-base
@@ -70,18 +70,21 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '2'
-description: |2
-      ULID(Universally Unique Lexicographically Sortable Identifier) is defined on https://github.com/ulid/spec.
-      It has useful specs for actual applications.
-      This gem aims to provide the generator, monotonic generator, parser and handy manipulation methods for the ID.
-      Also having rbs signature files.
+description: "    ULID(Universally Unique Lexicographically Sortable Identifier) has
+  useful specs for applications (e.g. `Database key`). \n    This gem aims to provide
+  the generator, monotonic generator, parser and handy manipulation features around
+  the ULID.\n    Also providing `rbs` signature files.\n"
 email:
 - kachick1+ruby@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
+- README.md
+- Steepfile
 - lib/ulid.rb
+- lib/ulid/monotonic_generator.rb
 - lib/ulid/version.rb
 - sig/ulid.rbs
 homepage: https://github.com/kachick/ruby-ulid