ruby-ulid 0.0.9 → 0.0.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc7674472c14c213d6fe01c6994520b33bc82ab164b538948a4f1b532d0d88f2
-  data.tar.gz: 85987c59ca6f119d40caaf69cc830a8e1b5cc2f9ea3250c315be2f9d8b7faa09
+  metadata.gz: ce2bb6c517e9fee4f758577e57d2c5eddfd16db9ee3c0d17ad41db8d9f1de383
+  data.tar.gz: 1cfb027a652e2035445483bdff2511c2837441e2e664286d60682fec6769cd17
 SHA512:
-  metadata.gz: f56db0a74a7a6559189039a9f7f13a1f514b4fc956f7993a52ca16a7a978b4b93aa352b9f74b72da73c7b0485ebe1f80052d2e3c7b04a1baba231d06ba594f42
-  data.tar.gz: 597260a0eb43c0fdc187aeb961521fbce22c68fc75b35d445e73d60564b72208aaf1e83a8428daa99423e001572f187872f4077445d6bced8b35d197d7e700ff
+  metadata.gz: ea00703256bc218a1e022dd732da22b37b9caeec30bdbdb4df945f9f185d408f0b746c36b36377dba2d4acaae5d2cf0b4db8b574ecc9da0e6e4b9b0af5c2404f
+  data.tar.gz: 6cd088ae1d539d8cb1d2690eb4248be413e527a87db7eb67b3c1adfc167c285cf2b90bb5701e82208586996649d56d1ef6c7c30396d1fbf0fc68220487711a54

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,199 @@
+# ruby-ulid
+
+A handy `ULID` library
+
+The `ULID` spec is defined on [ulid/spec](https://github.com/ulid/spec).
+Formal name is `Universally Unique Lexicographically Sortable Identifier`.
+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.
+
+---
+
+![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
+```
+
+You can parse from exists IDs
+
+```ruby
+ulid = ULID.parse('01ARZ3NDEKTSV4RRFFQ69G5FAV') #=> ULID(2016-07-30 23:54:10.259 UTC: 01ARZ3NDEKTSV4RRFFQ69G5FAV)
+```
+
+ULID is sortable when they are generated different timestamp in milliseconds precision
+
+```ruby
+ulids = 1000.times.map do
+  sleep(0.001)
+  ULID.generate
+end
+ulids.sort == ulids #=> true
+ulids.uniq(&:to_time).size #=> 1000
+```
+
+Providing monotonic generator for same milliseconds use-cases. It is called as [Monotonicity](https://github.com/ulid/spec/tree/d0c7170df4517939e70129b4d6462cc162f2d5bf#monotonicity) on the spec.
+
+```ruby
+ulids = 10000.times.map do
+  ULID.generate
+end
+ulids.uniq(&:to_time).size #=> 35 (the number will be changed by every creation)
+ulids.sort == ulids #=> false
+
+
+monotonic_generator = ULID::MonotonicGenerator.new
+monotonic_ulids = 10000.times.map do
+  monotonic_generator.generate
+end
+monotonic_ulids.uniq(&:to_time).size #=> 34 (the number will be changed by every creation)
+monotonic_ulids.sort == monotonic_ulids #=> true
+```
+
+Providing converter for UUIDv4. (Of course the timestamp will be useless one.)
+
+```ruby
+ULID.from_uuidv4('0983d0a2-ff15-4d83-8f37-7dd945b5aa39')
+#=> ULID(2301-07-10 00:28:28.821 UTC: 09GF8A5ZRN9P1RYDVXV52VBAHS)
+```
+
+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)
+```
+
+## Development
+
+At first, you should install development dependencies
+
+```console
+$ git clone git@github.com:kachick/ruby-ulid.git
+$ cd ./ruby-ulid
+$ bundle install
+# Executing first time might take longtime, because development mode dependent active_support via steep
+```
+
+Play with the behaviors in REPL.
+
+```console
+$ ./bin/console
+# Starting up IRB with loading developing ULID library
+irb(main):001:0>
+```
+
+```ruby
+# On IRB, you can check behaviors even if it is undocumented
+ulid = ULID.generate #=> ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GRMJ9AA)
+ls ULID
+```
+
+If you try to add/change/fix features, please update tests and ensure they are not broken.
+
+```console
+$ bundle exec rake test
+$ echo $?
+0
+```
+
+If you try to improve any performance issue, please add benchmarking and check the result of before and after.
+
+```console
+$ bundle exec ruby benchmark/the_added_file.rb
+# Showing the results
+```
+
+## Documents
+
+- [API documents generated by YARD](https://kachick.github.io/ruby-ulid/)
+
+## Author
+
+Kenichi Kamiya - [@kachick](https://github.com/kachick)

data/Steepfile

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

data/lib/ulid.rb

@@ -4,7 +4,6 @@
 
 require 'securerandom'
 require 'integer/base'
-require_relative 'ulid/version'
 
 # @see https://github.com/ulid/spec
 # @!attribute [r] milliseconds
@@ -23,16 +22,16 @@ class ULID
   # @see https://www.crockford.com/base32.html
   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
+  ENCODED_ID_LENGTH = TIMESTAMP_PART_LENGTH + RANDOMNESS_PART_LENGTH
   TIMESTAMP_OCTETS_LENGTH = 6
   RANDOMNESS_OCTETS_LENGTH = 10
   OCTETS_LENGTH = TIMESTAMP_OCTETS_LENGTH + RANDOMNESS_OCTETS_LENGTH
   MAX_MILLISECONDS = 281474976710655
   MAX_ENTROPY = 1208925819614629174706175
   MAX_INTEGER = 340282366920938463463374607431768211455
-  PATTERN = /(?<timestamp>[0-7][#{encoding_string}]{#{TIME_PART_LENGTH - 1}})(?<randomness>[#{encoding_string}]{#{RANDOMNESS_PART_LENGTH}})/i.freeze
+  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!
@@ -42,49 +41,6 @@ class ULID
   # @see https://bugs.ruby-lang.org/issues/15958
   TIME_FORMAT_IN_INSPECT = '%Y-%m-%d %H:%M:%S.%3N %Z'
 
-  class MonotonicGenerator
-    attr_accessor :latest_milliseconds, :latest_entropy
-
-    def initialize
-      reset
-    end
-
-    # @raise [OverflowError] if the entropy part is larger than the ULID limit in same milliseconds
-    # @return [ULID]
-    def generate
-      milliseconds = ULID.current_milliseconds
-      reasonable_entropy = ULID.reasonable_entropy
-
-      @latest_milliseconds ||= milliseconds
-      @latest_entropy ||= reasonable_entropy
-      if @latest_milliseconds != milliseconds
-        @latest_milliseconds = milliseconds
-        @latest_entropy = reasonable_entropy
-      else
-        @latest_entropy += 1
-      end
-
-      ULID.new milliseconds: milliseconds, entropy: @latest_entropy
-    end
-
-    # @return [self]
-    def reset
-      @latest_milliseconds = nil
-      @latest_entropy = nil
-      self
-    end
-
-    # @raise [TypeError] always raises exception and does not freeze self
-    # @return [void]
-    def freeze
-      raise TypeError, "cannot freeze #{self.class}"
-    end
-  end
-
-  MONOTONIC_GENERATOR = MonotonicGenerator.new
-
-  private_constant :ENCODING_CHARS, :TIME_FORMAT_IN_INSPECT, :UUIDV4_PATTERN
-
   # @param [Integer, Time] moment
   # @param [Integer] entropy
   # @return [ULID]
@@ -93,6 +49,18 @@ class ULID
     new milliseconds: milliseconds, entropy: entropy
   end
 
+  # @param [Integer, Time] moment
+  # @return [ULID]
+  def self.min(moment: 0)
+    generate(moment: moment, entropy: 0)
+  end
+
+  # @param [Integer, Time] moment
+  # @return [ULID]
+  def self.max(moment: MAX_MILLISECONDS)
+    generate(moment: moment, entropy: MAX_ENTROPY)
+  end
+
   # @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]
@@ -179,8 +147,8 @@ class ULID
       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
@@ -349,3 +317,12 @@ class ULID
     @matchdata ||= STRICT_PATTERN.match(to_str).freeze
   end
 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,44 @@
+# coding: us-ascii
+# frozen_string_literal: true
+# Copyright (C) 2021 Kenichi Kamiya
+
+class ULID
+  class MonotonicGenerator
+    attr_accessor :latest_milliseconds, :latest_entropy
+
+    def initialize
+      reset
+    end
+
+    # @raise [OverflowError] if the entropy part is larger than the ULID limit in same milliseconds
+    # @return [ULID]
+    def generate
+      milliseconds = ULID.current_milliseconds
+      reasonable_entropy = ULID.reasonable_entropy
+
+      @latest_milliseconds ||= milliseconds
+      @latest_entropy ||= reasonable_entropy
+      if @latest_milliseconds != milliseconds
+        @latest_milliseconds = milliseconds
+        @latest_entropy = reasonable_entropy
+      else
+        @latest_entropy += 1
+      end
+
+      ULID.new milliseconds: milliseconds, entropy: @latest_entropy
+    end
+
+    # @return [self]
+    def reset
+      @latest_milliseconds = nil
+      @latest_entropy = nil
+      self
+    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.9'
+  VERSION = '0.0.10'
 end

data/sig/ulid.rbs

@@ -2,7 +2,7 @@
 class ULID
   VERSION: String
   ENCODING_CHARS: Array[String]
-  TIME_PART_LENGTH: 10
+  TIMESTAMP_PART_LENGTH: 10
   RANDOMNESS_PART_LENGTH: 16
   ENCODED_ID_LENGTH: 26
   TIMESTAMP_OCTETS_LENGTH: 6
@@ -36,6 +36,7 @@ class ULID
     def freeze: -> void
   end
 
+  type moment = Time | Integer
   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]
@@ -56,7 +57,7 @@ class ULID
   @strict_pattern: Regexp?
   @matchdata: MatchData?
 
-  def self.generate: (?moment: Time | Integer, ?entropy: Integer) -> ULID
+  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
@@ -64,6 +65,8 @@ class ULID
   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)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-ulid
 version: !ruby/object:Gem::Version
-  version: 0.0.9
+  version: 0.0.10
 platform: ruby
 authors:
 - Kenichi Kamiya
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-04-30 00:00:00.000000000 Z
+date: 2021-05-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: integer-base
@@ -81,7 +81,11 @@ 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