ruby-ulid 0.0.10 → 0.0.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce2bb6c517e9fee4f758577e57d2c5eddfd16db9ee3c0d17ad41db8d9f1de383
-  data.tar.gz: 1cfb027a652e2035445483bdff2511c2837441e2e664286d60682fec6769cd17
+  metadata.gz: 91f6d4c9dad8e12663686099c487dbbf3ec5b7995e0e4b2b210ac8a16fbcd91c
+  data.tar.gz: 1ca6e29d83771636b2a20aa71d90f15699d07d6a7a75f22c306094507bb51d89
 SHA512:
-  metadata.gz: ea00703256bc218a1e022dd732da22b37b9caeec30bdbdb4df945f9f185d408f0b746c36b36377dba2d4acaae5d2cf0b4db8b574ecc9da0e6e4b9b0af5c2404f
-  data.tar.gz: 6cd088ae1d539d8cb1d2690eb4248be413e527a87db7eb67b3c1adfc167c285cf2b90bb5701e82208586996649d56d1ef6c7c30396d1fbf0fc68220487711a54
+  metadata.gz: 22dcc2541f7e4fa1a1d4014f996aef3d3bfcb69b002c1cc6ca4864e17bce50a327e1ec98453b4dab0773400b678055dc024a7287342a08916ce30772aadb418d
+  data.tar.gz: 27c69c7319858a4c732f04f6944ff180f3dfc9a5df12bd67cd1e4cac91421a2bc00d1a79c8ff91190b425731f831fdaef1a2f5bc0c3ef4fdaff73a6ce6749e35

data/README.md

@@ -3,10 +3,8 @@
 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.
+This gem aims to provide the generator, monotonic generator, parser and handy manipulation features around the ULID.
+Also providing rbs signature files.
 
 ---
 
@@ -57,13 +55,34 @@ ulid.octets #=> [1, 121, 20, 95, 7, 202, 187, 60, 175, 51, 76, 60, 49, 73, 37, 7
 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
 ```
 
-ULID is sortable when they are generated different timestamp in milliseconds precision
+ULIDs are sortable when they are generated in different timestamp with milliseconds precision
 
 ```ruby
 ulids = 1000.times.map do
@@ -74,29 +93,40 @@ 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.
+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 number will be changed by every creation)
+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
-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.)
+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"]
 
-```ruby
-ULID.from_uuidv4('0983d0a2-ff15-4d83-8f37-7dd945b5aa39')
-#=> ULID(2301-07-10 00:28:28.821 UTC: 09GF8A5ZRN9P1RYDVXV52VBAHS)
+monotonic_ulids.sort == monotonic_ulids #=> true
 ```
 
 For rough operations, `ULID.scan` might be useful.
@@ -150,50 +180,31 @@ 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)
 ```
 
-## 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>
-```
+`ULID#next` and `ULID#succ` returns next(successor) ULID
 
 ```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
+ULID.parse('01BX5ZZKBKZZZZZZZZZZZZZZZY').next.to_s #=> "01BX5ZZKBKZZZZZZZZZZZZZZZZ"
+ULID.parse('01BX5ZZKBKZZZZZZZZZZZZZZZZ').next.to_s #=> "01BX5ZZKBM0000000000000000"
+ULID.parse('7ZZZZZZZZZZZZZZZZZZZZZZZZZ').next #=> nil
 ```
 
-If you try to add/change/fix features, please update tests and ensure they are not broken.
+`ULID#pred` returns predecessor ULID
 
-```console
-$ bundle exec rake test
-$ echo $?
-0
+```ruby
+ULID.parse('01BX5ZZKBK0000000000000001').pred.to_s #=> "01BX5ZZKBK0000000000000000"
+ULID.parse('01BX5ZZKBK0000000000000000').pred.to_s #=> "01BX5ZZKBJZZZZZZZZZZZZZZZZ"
+ULID.parse('00000000000000000000000000').pred #=> nil
 ```
 
-If you try to improve any performance issue, please add benchmarking and check the result of before and after.
+UUIDv4 converter for migration use-cases. (Of course the timestamp will be useless one. Sortable benefit is lost.)
 
-```console
-$ bundle exec ruby benchmark/the_added_file.rb
-# Showing the results
+```ruby
+ULID.from_uuidv4('0983d0a2-ff15-4d83-8f37-7dd945b5aa39')
+#=> ULID(2301-07-10 00:28:28.821 UTC: 09GF8A5ZRN9P1RYDVXV52VBAHS)
 ```
 
-## Documents
-
-- [API documents generated by YARD](https://kachick.github.io/ruby-ulid/)
-
-## Author
+## References
 
-Kenichi Kamiya - [@kachick](https://github.com/kachick)
+- [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/lib/ulid.rb

@@ -107,6 +107,7 @@ class ULID
   # @return [ULID]
   # @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
@@ -292,20 +293,29 @@ class ULID
     @strict_pattern ||= /\A#{pattern.source}\z/i.freeze
   end
 
-  # @raise [OverflowError] if the next entropy part is larger than the ULID limit
-  # @return [ULID]
+  # @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

data/lib/ulid/version.rb

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

data/sig/ulid.rbs

@@ -93,8 +93,9 @@ class ULID
   def octets: -> octets
   def timestamp_octets: -> timestamp_octets
   def randomness_octets: -> randomness_octets
-  def next: -> ULID
+  def next: -> ULID?
   alias succ next
+  def pred: -> ULID?
   def freeze: -> self
 
   private

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-ulid
 version: !ruby/object:Gem::Version
-  version: 0.0.10
+  version: 0.0.11
 platform: ruby
 authors:
 - Kenichi Kamiya
@@ -70,11 +70,10 @@ 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: []