ruby-ulid 0.0.15 → 0.0.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a620e80f82e91c778329ccf7da8cca96bda4b12e047610b9543768c5ec85d22
-  data.tar.gz: ea28469d63348758f52e1460b5330ce177ad2281e63060800a0669054758f3ee
+  metadata.gz: 15a83604732cdc37f8015ee9382884e950852f8c9c82aba107ea4b3c065c5a4d
+  data.tar.gz: 06e7b69a5838786f4d23da19f5e1f00fb3173014e7438459165b66703637851a
 SHA512:
-  metadata.gz: acb07ae797c3a06a6626d34e15dc1056a30586e8bc151a3773770259d2f4047d0708593e702fbd67a7609758165f20a15f208fede068717a5555733535ed4bde
-  data.tar.gz: 57c9819d86f2a0f002cf3b9a7b76b3a36bc412fa874d50136ec296f1217fb905fa19feb52de2c9d5250547da384580cf882121f0e331054cd665bd113d1f10e3
+  metadata.gz: 6ca46525e80b1d832a703b8cb867466327de333853ee236654f722dc6abc30f46fd149ca9633c42ececcea08db2a01a6d82ab60f8eeb61ebb947f0441436dd96
+  data.tar.gz: ccd08e78dfb047f82af02eeaf14ccd12fcb05fe882edeb2bf48c2e7ec5b9fd698feccf0b9f9e187aaff97c2e793f671a3f9d32c11e3741656c3df94f944bc808

data/README.md

@@ -1,6 +1,6 @@
 # ruby-ulid
 
-A handy `ULID` library
+## Overview
 
 The `ULID` spec is defined on [ulid/spec](https://github.com/ulid/spec). It has useful specs for applications (e.g. `Database key`), especially possess all `uniqueness`, `randomness`, `extractable timestamps` and `sortable` features.
 This gem aims to provide the generator, monotonic generator, parser and handy manipulation features around the ULID.
@@ -33,16 +33,26 @@ Instead, herein is proposed ULID:
 - No special characters (URL safe)
 - Monotonic sort order (correctly detects and handles the same millisecond)
 
-## Install
+## Usage
+
+### Install
 
 Require Ruby 2.6 or later
 
+This command will install the latest version into your environment
+
 ```console
 $ gem install ruby-ulid
-#=> Installed
+Should be installed!
 ```
 
-## Usage
+Add this line to your application/library's `Gemfile` is needed in basic use-case
+
+```ruby
+gem 'ruby-ulid', '0.0.16'
+```
+
+### Generator and Parser
 
 The generated `ULID` is an object not just a string.
 It means easily get the timestamps and binary formats.
@@ -54,7 +64,6 @@ ulid = ULID.generate #=> ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GR
 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
 ```
 
 You can get the objects from exists encoded ULIDs
@@ -64,6 +73,8 @@ ulid = ULID.parse('01ARZ3NDEKTSV4RRFFQ69G5FAV') #=> ULID(2016-07-30 23:54:10.259
 ulid.to_time #=> 2016-07-30 23:54:10.259 UTC
 ```
 
+### Sortable with the timestamp
+
 ULIDs are sortable when they are generated in different timestamp with milliseconds precision
 
 ```ruby
@@ -71,14 +82,14 @@ ulids = 1000.times.map do
   sleep(0.001)
   ULID.generate
 end
-ulids.sort == ulids #=> true
 ulids.uniq(&:to_time).size #=> 1000
+ulids.sort == ulids #=> true
 ```
 
 `ULID.generate` can take fixed `Time` instance
 
 ```ruby
-time = Time.at(946684800, in: 'UTC') #=> 2000-01-01 00:00:00 UTC
+time = Time.at(946684800).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)
 
@@ -98,7 +109,9 @@ ulids.uniq(&:to_time).size #=> 35 (the size is not fixed, might be changed in en
 ulids.sort == ulids #=> false
 ```
 
-If you want to ensure `sortable`, Use `MonotonicGenerator` instead. It is called as [Monotonicity](https://github.com/ulid/spec/tree/d0c7170df4517939e70129b4d6462cc162f2d5bf#monotonicity) on the spec.
+### 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)
 
 ```ruby
@@ -128,20 +141,40 @@ sample_ulids_by_the_time.take(5) #=>
 ulids.sort == ulids #=> true
 ```
 
-When filtering ULIDs by `Time`, we should consider to handle the precision.
-So this gem provides `ULID.range` to generate `Range[ULID]` from given `Range[Time]`
+### Filtering IDs with `Time`
+
+`ULID` can be element of the `Range`. If you generated the IDs in monotonic generator, ID based filtering is easy and reliable
+
+```ruby
+include_end = ulid1..ulid2
+exclude_end = ulid1...ulid2
+
+ulids.grep(one_of_the_above)
+ulids.grep_v(one_of_the_above)
+```
+
+When want to filter ULIDs with `Time`, we should consider to handle the precision.
+So this gem provides `ULID.range` to generate reasonable `Range[ULID]` from `Range[Time]`
 
 ```ruby
 # Both of below, The begin of `Range[ULID]` will be the minimum in the floored milliseconds of the time1
 include_end = ULID.range(time1..time2) #=> The end of `Range[ULID]` will be the maximum in the floored milliseconds of the time2
 exclude_end = ULID.range(time1...time2) #=> The end of `Range[ULID]` will be the minimum in the floored milliseconds of the time2
 
+# Below patterns are acceptable
+pinpointing = ULID.range(time1..time1) #=> This will match only for all IDs in `time1`
+until_the_end = ULID.range(..time1) #=> This will match only for all IDs upto `time1` (The `nil` starting `Range` can be used since Ruby 2.7)
+until_the_end = ULID.range(ULID.min.to_time..time1) #=> This is same as above for Ruby 2.6
+until_the_ulid_limit = ULID.range(time1..) # This will match only for all IDs from `time1` to max value of the ULID limit
+
 # So you can use the generated range objects as below
-ulids.grep(include_end)
-ulids.grep(exclude_end)
+ulids.grep(one_of_the_above)
+ulids.grep_v(one_of_the_above)
 #=> I hope the results should be actually you want!
 ```
 
+### Scanner for string (e.g. `JSON`)
+
 For rough operations, `ULID.scan` might be useful.
 
 ```ruby
@@ -182,6 +215,8 @@ ULID.scan(json).to_a
  ULID(2021-04-30 05:53:12.478 UTC: 01F4GND4RYYSKNAADHQ9BNXAWJ)]
 ```
 
+### Some methods to help manipulations
+
 `ULID.min` and `ULID.max` return termination values for ULID spec.
 
 ```ruby
@@ -193,7 +228,10 @@ ULID.min(moment: time) #=> ULID(2000-01-01 00:00:00.123 UTC: 00VHNCZB3V000000000
 ULID.max(moment: time) #=> ULID(2000-01-01 00:00:00.123 UTC: 00VHNCZB3VZZZZZZZZZZZZZZZZ)
 ```
 
-`ULID#next` and `ULID#succ` returns next(successor) ULID
+`ULID#next` and `ULID#succ` returns next(successor) ULID.
+Especially `ULID#succ` makes it possible `Range[ULID]#each`.
+
+NOTE: But basically `Range[ULID]#each` should not be used, incrementing 128 bits IDs are not reasonable operation in most case
 
 ```ruby
 ULID.parse('01BX5ZZKBKZZZZZZZZZZZZZZZY').next.to_s #=> "01BX5ZZKBKZZZZZZZZZZZZZZZZ"
@@ -239,6 +277,50 @@ ULID.min == reversed_min #=> false
 ULID.max == reversed_max #=> false
 ```
 
+## How to migrate from other gems
+
+As far as I know, major prior arts are below
+
+### [ulid gem](https://rubygems.org/gems/ulid) - [rafaelsales/ulid](https://github.com/rafaelsales/ulid)
+
+It is just providing basic `String` generator only.
+So you can replace the code as below
+
+```diff
+-ULID.generate
++ULID.generate.to_s
+```
+
+NOTE: It had crucial issue for handling precision, in version before `1.3.0`, when you extract timestamps from old generated ULIDs, it might be not accurate value.
+
+1. [Sort order does not respect millisecond ordering](https://github.com/rafaelsales/ulid/issues/22)
+1. [Fixed in this PR](https://github.com/rafaelsales/ulid/pull/23)
+1. [Released in 1.3.0](https://github.com/rafaelsales/ulid/compare/1.2.0...v1.3.0)
+
+### [ulid-ruby gem](https://rubygems.org/gems/ulid-ruby) - [abachman/ulid-ruby](https://github.com/abachman/ulid-ruby)
+
+It is providing basic generator(except monotonic generator) and parser.
+Major methods can be replaced as below.
+
+```diff
+-ULID.generate
++ULID.generate.to_s
+-ULID.at(time)
++ULID.generate(moment: time).to_s
+-ULID.time(string)
++ULID.parse(string).to_time
+-ULID.min_ulid_at(time)
++ULID.min(moment: time).to_s
+-ULID.max_ulid_at(time)
++ULID.max(moment: time).to_s
+```
+
+NOTE: It is still having precision issue similar as `ulid gem` in the both generator and parser. I sent PRs.
+
+1. [Parsed time object has more than milliseconds](https://github.com/abachman/ulid-ruby/issues/3)
+1. [Fix to handle timestamp precision in parser](https://github.com/abachman/ulid-ruby/pull/5)
+1. [Fix to handle timestamp precision in generator](https://github.com/abachman/ulid-ruby/pull/4)
+
 ## References
 
 - [Repository](https://github.com/kachick/ruby-ulid)

data/lib/ulid.rb

@@ -16,6 +16,7 @@ class ULID
   class Error < StandardError; end
   class OverflowError < Error; end
   class ParserError < Error; end
+  class SetupError < ScriptError; end
 
   encoding_string = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'
   # Crockford's Base32. Excluded I, L, O, U.
@@ -190,11 +191,13 @@ class ULID
     SecureRandom.random_number(MAX_ENTROPY)
   end
 
+  # @api private
+  # @deprecated Just exists to compare performance with old implementation. ref: https://github.com/kachick/ruby-ulid/issues/7
   # @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)
+  def self.parse_with_integer_base(string)
     begin
       string = string.to_str
       unless string.size == ENCODED_ID_LENGTH
@@ -211,6 +214,67 @@ class ULID
     new milliseconds: milliseconds, entropy: entropy
   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
+
+  # Currently supporting only for `subset for actual use-case`
+  # 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
+  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
+
+  REPLACING_MAP = ENCODING_CHARS.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 REPLACING_MAP.keys == crockford_base32_mappings.keys
+  REPLACING_PATTERN = /[#{REPLACING_MAP.keys.join}]/.freeze
+
+  def self.parse(string)
+    begin
+      string = string.to_str
+      raise "given argument does not match to `#{STRICT_PATTERN.inspect}`" unless STRICT_PATTERN.match?(string)
+      n32encoded = convert_crockford_base32_to_n32(string.upcase)
+      timestamp = n32encoded.slice(0, TIMESTAMP_PART_LENGTH)
+      randomness = n32encoded.slice(TIMESTAMP_PART_LENGTH, RANDOMNESS_PART_LENGTH)
+      milliseconds = timestamp.to_i(32)
+      entropy = randomness.to_i(32)
+    rescue => err
+      raise ParserError, "parsing failure as #{err.inspect} for given #{string.inspect}"
+    end
+
+    new milliseconds: milliseconds, entropy: entropy
+  end
+
+  # @api private
+  private_class_method def self.convert_crockford_base32_to_n32(string)
+    string.gsub(REPLACING_PATTERN, REPLACING_MAP)
+  end
+
   # @return [Boolean]
   def self.valid?(string)
     parse(string)
@@ -348,11 +412,13 @@ class ULID
     @randomness ||= matchdata[:randomness].freeze
   end
 
+  # @deprecated This method might be changed in https://github.com/kachick/ruby-ulid/issues/84
   # @return [Regexp]
   def pattern
     @pattern ||= /(?<timestamp>#{timestamp})(?<randomness>#{randomness})/i.freeze
   end
 
+  # @deprecated This method might be changed in https://github.com/kachick/ruby-ulid/issues/84
   # @return [Regexp]
   def strict_pattern
     @strict_pattern ||= /\A#{pattern.source}\z/i.freeze
@@ -418,5 +484,5 @@ class ULID
   MAX = parse('7ZZZZZZZZZZZZZZZZZZZZZZZZZ').freeze
   MONOTONIC_GENERATOR = MonotonicGenerator.new
 
-  private_constant :ENCODING_CHARS, :TIME_FORMAT_IN_INSPECT, :UUIDV4_PATTERN, :MIN, :MAX
+  private_constant :ENCODING_CHARS, :TIME_FORMAT_IN_INSPECT, :UUIDV4_PATTERN, :MIN, :MAX, :REPLACING_PATTERN, :REPLACING_MAP
 end

data/lib/ulid/version.rb

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

data/sig/ulid.rbs

@@ -15,6 +15,8 @@ class ULID
   PATTERN: Regexp
   STRICT_PATTERN: Regexp
   UUIDV4_PATTERN: Regexp
+  REPLACING_MAP: Hash[String, String]
+  REPLACING_PATTERN: Regexp
   MONOTONIC_GENERATOR: MonotonicGenerator
   MIN: ULID
   MAX: ULID
@@ -32,6 +34,9 @@ class ULID
   class ParserError < Error
   end
 
+  class SetupError < ScriptError
+  end
+
   class MonotonicGenerator
     attr_accessor latest_milliseconds: Integer
     attr_accessor latest_entropy: Integer
@@ -80,6 +85,7 @@ class 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
   attr_reader milliseconds: Integer
   attr_reader entropy: Integer
   def initialize: (milliseconds: Integer, entropy: Integer) -> void

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-ulid
 version: !ruby/object:Gem::Version
-  version: 0.0.15
+  version: 0.0.16
 platform: ruby
 authors:
 - Kenichi Kamiya
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-05-04 00:00:00.000000000 Z
+date: 2021-05-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: integer-base
@@ -84,10 +84,10 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '2'
-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"
+description: |2
+      The ULID(Universally Unique Lexicographically Sortable Identifier) has useful specs for applications (e.g. `Database key`), especially possess all `uniqueness`, `randomness`, `extractable timestamps` and `sortable` features.
+      This gem aims to provide the generator, monotonic generator, parser and handy manipulation features around the ULID.
+      Also providing `ruby/rbs` signature files.
 email:
 - kachick1+ruby@gmail.com
 executables: []