ruby-ulid 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b50cb3fee0b304a62ebd460e7d08b932d3c58c1f7810a1dc24b5166df10ceaf
-  data.tar.gz: b84a2ad766640fa7c87e4bbb5b0fdd637bf831407f235989cdd043ea5b1189aa
+  metadata.gz: 4d7356366d0184815a725d1947f4f685b3abba0320ae60800b5a015dc7c649e9
+  data.tar.gz: 04b55b6d92dbf02865a7803be352f5cd385f3417c061269f2ad197474202154d
 SHA512:
-  metadata.gz: e44eadac5ad4c83f1c8da74fbfa502a3b3b7293dda8eb44855bb477070687afd815d46237a9cc15266223f7cd0981b69670165767b366156d23728cdb76c878e
-  data.tar.gz: 349b2e8c2b16d5c9ae58270fdb5e87a3c364eef4b3ae2972680cb5de119ba737ed035db36bb7283fc96ff7c7a54663be5de8c0725e0de1975d8f66de34dd052c
+  metadata.gz: aa826d204cbdc1e6850fbeab278dc72e5b683926db9af7ed477ec2e74837d32829dbfb468c1156d6dcf5be604f9fdeb8fd0a282999b47a627884152b2a2cd5d4
+  data.tar.gz: 0b1208e76af50f9952c8c4835d1410c7e1fd114313cc71d39a143c9bc04ac4f1a35ba49be88a49406606c441e4f4fa7cad5fc938d74fcecde0d612319a6890b3

data/README.md

@@ -7,8 +7,7 @@
 
 [ulid/spec](https://github.com/ulid/spec) is useful.
 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 ULID.  
-Also providing [RBS](https://github.com/ruby/rbs) signatures.
+This gem aims to provide the generator, optional monotonicity, parser and other manipulation features around ULID with included [RBS](https://github.com/ruby/rbs).
 
 ---
 
@@ -50,7 +49,7 @@ Should be installed!
 Add this line in your Gemfile.
 
 ```ruby
-gem('ruby-ulid', '~> 0.4.0')
+gem('ruby-ulid', '~> 0.5.0')
 ```
 
 ### How to use
@@ -58,8 +57,8 @@ gem('ruby-ulid', '~> 0.4.0')
 ```ruby
 require 'ulid'
 
-defined? ULID
-# => "constant"
+ULID::VERSION
+# => "0.5.0"
 ```
 
 ### Basic Generator
@@ -72,7 +71,7 @@ ulid = ULID.generate #=> ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GR
 
 ### Parser
 
-You can get the objects from exists encoded ULIDs.
+Get the objects from exists encoded ULIDs.
 
 ```ruby
 ulid = ULID.parse('01ARZ3NDEKTSV4RRFFQ69G5FAV') #=> ULID(2016-07-30 23:54:10.259 UTC: 01ARZ3NDEKTSV4RRFFQ69G5FAV)
@@ -80,7 +79,7 @@ ulid = ULID.parse('01ARZ3NDEKTSV4RRFFQ69G5FAV') #=> ULID(2016-07-30 23:54:10.259
 
 ### ULID object
 
-You can extract timestamps and binary formats.
+Extract timestamps and binary formats.
 
 ```ruby
 ulid = ULID.parse('01F4A5Y1YAQCYAYCTC7GRMJ9AA') #=> ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GRMJ9AA)
@@ -120,7 +119,7 @@ end
 ulids.sort == ulids #=> true
 ```
 
-The basic generator prefers `randomness`, it does not guarantee `sortable` for same milliseconds ULIDs.
+Basic generator prefers `randomness`, it does not guarantee `sortable` for same milliseconds ULIDs.
 
 ```ruby
 ulids = 10000.times.map do
@@ -202,7 +201,7 @@ time = Time.at(946684800, Rational('123456.789')).utc #=> 2000-01-01 00:00:00.12
 ULID.floor(time) #=> 2000-01-01 00:00:00.123 UTC
 ```
 
-### Some methods to help manipulations
+### Tools
 
 #### Scanner for string (e.g. `JSON`)
 
@@ -341,31 +340,32 @@ ULID.sample(5, period: ulid1.to_time..ulid2.to_time)
 
 I'm afraid so, we should consider [Current ULID spec](https://github.com/ulid/spec/tree/d0c7170df4517939e70129b4d6462cc162f2d5bf#universally-unique-lexicographically-sortable-identifier) has `orthographical variants of the format` possibilities.
 
+>Case insensitive
+
+I can understand it might be considered in actual use-case. So `ULID.parse` accepts upcase and downcase.
+However it is a controversial point, discussing in [ulid/spec#3](https://github.com/ulid/spec/issues/3).
+
 >Uses Crockford's base32 for better efficiency and readability (5 bits per character)
 
 The original `Crockford's base32` maps `I`, `L` to `1`, `O` to `0`.
 And accepts freestyle inserting `Hyphens (-)`.
 To consider this patterns or not is different in each implementations.
 
-Current parser/validator/matcher aims to cover `subset of Crockford's base32`.
-I have suggested it would be clarified in [ulid/spec#57](https://github.com/ulid/spec/pull/57).
-
->Case insensitive
-
-I can understand it might be considered in actual use-case.
-But it is a controversial point, discussing in [ulid/spec#3](https://github.com/ulid/spec/issues/3).
+I have suggested to clarify `subset of Crockford's base32` in [ulid/spec#57](https://github.com/ulid/spec/pull/57).
 
-Be that as it may, this gem provides API for handling the nasty possibilities.
+This gem provides some methods to handle the nasty possibilities.
 
-`ULID.normalize` and `ULID.normalized?`
+`ULID.normalize`, `ULID.normalized?`, `ULID.valid_as_variant_format?` and `ULID.parse_variant_format`
 
 ```ruby
-ULID.normalize('-olarz3-noekisv4rrff-q6ig5fav--') #=> "01ARZ3N0EK1SV4RRFFQ61G5FAV"
-ULID.normalized?('-olarz3-noekisv4rrff-q6ig5fav--') #=> false
-ULID.normalized?('01ARZ3N0EK1SV4RRFFQ61G5FAV') #=> true
+ULID.normalize('01g70y0y7g-z1xwdarexergsddd') #=> "01G70Y0Y7GZ1XWDAREXERGSDDD"
+ULID.normalized?('01g70y0y7g-z1xwdarexergsddd') #=> false
+ULID.normalized?('01G70Y0Y7GZ1XWDAREXERGSDDD') #=> true
+ULID.valid_as_variant_format?('01g70y0y7g-z1xwdarexergsddd') #=> true
+ULID.parse_variant_format('01G70Y0Y7G-ZLXWDIREXERGSDoD') #=> ULID(2022-07-03 02:25:22.672 UTC: 01G70Y0Y7GZ1XWD1REXERGSD0D)
 ```
 
-#### UUIDv4 converter for migration use-cases
+#### UUIDv4 converter (experimental)
 
 `ULID.from_uuidv4` and `ULID#to_uuidv4` is the converter.
 The imported timestamp is meaningless. So ULID's benefit will lost.
@@ -398,68 +398,19 @@ 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: In version before `1.3.0`, timestamps might not be correct 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.at(time).to_s
--ULID.time(string)
-+ULID.parse(string).to_time
--ULID.min_ulid_at(time)
-+ULID.min(time).to_s
--ULID.max_ulid_at(time)
-+ULID.max(time).to_s
-```
-
-NOTE: In version before `1.0.2`, timestamps might not be correct value.
-
-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)
-1. [Released in 1.0.2](https://github.com/abachman/ulid-ruby/compare/v1.0.0...v1.0.2)
-
-### Compare performance with them
-
-See [Benchmark](https://github.com/kachick/ruby-ulid/wiki/Benchmark).
+## Migration from other gems
 
-The results are not something to be proud of.
+See [wiki page for gem migration](https://github.com/kachick/ruby-ulid/wiki/Gem-migration).
 
-## How to use rbs
+## RBS
 
-See structure at [examples/rbs_sandbox](https://github.com/kachick/ruby-ulid/tree/main/examples/rbs_sandbox)
+Try at [examples/rbs_sandbox](https://github.com/kachick/ruby-ulid/tree/main/examples/rbs_sandbox).
 
 I have checked the behavior with [ruby/rbs@2.6.0](https://github.com/ruby/rbs) + [soutaro/steep@1.0.1](https://github.com/soutaro/steep) +  [soutaro/steep-vscode](https://github.com/soutaro/steep-vscode).
 
 * ![rbs overview](./assets/ulid-rbs-overview.png?raw=true.png)
 * ![rbs mix](./assets/ulid-rbs-mix.png?raw=true.png)
 * ![rbs ng-to_str](./assets/ulid-rbs-ng-to_str.png?raw=true.png)
-* ![rbs ok-at-time](./assets/ulid-rbs-ok-at-time.png?raw=true.png)
-* ![rbs ng-at-int](./assets/ulid-rbs-ng-at-int.png?raw=true.png)
 
 ## References
 

data/lib/ulid/version.rb

@@ -3,5 +3,5 @@
 # shareable_constant_value: literal
 
 class ULID
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end

data/lib/ulid.rb

@@ -268,6 +268,17 @@ class ULID
     from_integer(CrockfordBase32.decode(string))
   end
 
+  # @param [String, #to_str] string
+  # @return [ULID]
+  # @raise [ParserError] if the given format is not correct for ULID specs
+  def self.parse_variant_format(string)
+    string = String.try_convert(string)
+    raise(ArgumentError, 'ULID.parse_variant_format takes only strings') unless string
+
+    normalized_in_crockford = CrockfordBase32.normalize(string)
+    parse(normalized_in_crockford)
+  end
+
   # @param [String, #to_str] string
   # @return [String]
   # @raise [ParserError] if the given format is not correct for ULID specs, even if ignored `orthographical variants of the format`
@@ -275,23 +286,40 @@ class ULID
     string = String.try_convert(string)
     raise(ArgumentError, 'ULID.normalize takes only strings') unless string
 
-    normalized_in_crockford = CrockfordBase32.normalize(string)
     # Ensure the ULID correctness, because CrockfordBase32 does not always mean to satisfy ULID format
-    parse(normalized_in_crockford).to_s
+    parse_variant_format(string).to_s
+  end
+
+  # @param [String, #to_str] string
+  # @return [Boolean]
+  def self.normalized?(string)
+    normalized = normalize(string)
+  rescue Exception
+    false
+  else
+    normalized == string
   end
 
+  # @param [String, #to_str] string
   # @return [Boolean]
-  def self.normalized?(object)
-    normalized = normalize(object)
+  def self.valid_as_variant_format?(string)
+    normalize(string)
   rescue Exception
     false
   else
-    normalized == object
+    true
   end
 
+  # @deprecated Use [.valid_as_variant_format?] or [.normalized?] instead
+  #
+  # Returns `true` if it is normalized string.
+  # Basically the difference of normalized? is to accept downcase or not. This returns true for downcased ULIDs.
+  #
   # @return [Boolean]
-  def self.valid?(object)
-    string = String.try_convert(object)
+  def self.valid?(string)
+    warn_kwargs = (RUBY_VERSION >= '3.0') ? { category: :deprecated } : {}
+    Warning.warn('ULID.valid? is deprecated. Use ULID.valid_as_variant_format? or ULID.normalized? instead.', **warn_kwargs)
+    string = String.try_convert(string)
     string ? STRICT_PATTERN_WITH_CROCKFORD_BASE32_SUBSET.match?(string) : false
   end
 
@@ -392,7 +420,7 @@ class ULID
     [ULID, @integer].hash
   end
 
-  # @return [Integer, nil]
+  # @return [-1, 0, 1, nil]
   def <=>(other)
     (ULID === other) ? (@integer <=> other.to_i) : nil
   end

data/sig/ulid.rbs

@@ -213,6 +213,21 @@ class ULID < Object
   # ```
   def self.parse: (_ToStr string) -> ULID
 
+  # Get ULID instance from unnormalized String that encoded in Crockford's base32.
+  #
+  # http://www.crockford.com/base32.html
+  #
+  # * Ignore Hyphens (-)
+  # * Mapping 0 O o => 0, 1 I i L l => 1
+  #
+  # ```ruby
+  # ulid = ULID.parse_variant_format('01G70Y0Y7G-ZLXWDIREXERGSDoD')
+  # #=> ULID(2022-07-03 02:25:22.672 UTC: 01G70Y0Y7GZ1XWD1REXERGSD0D)
+  # ```
+  #
+  # See also [ulid/spec#57](https://github.com/ulid/spec/pull/57) and [ulid/spec#3](https://github.com/ulid/spec/issues/3)
+  def self.parse_variant_format: (_ToStr string) -> ULID
+
   # ```ruby
   # # Currently experimental feature, so needed to load the extension.
   # require 'ulid/uuid'
@@ -309,14 +324,13 @@ class ULID < Object
   # ```
   def self.sample: (?period: period) -> ULID
                  | (Integer number, ?period: period?) -> Array[ULID]
-  def self.valid?: (untyped) -> bool
 
   # Returns normalized string
   #
   # ```ruby
+  # ULID.normalize('01G70Y0Y7G-Z1XWDAREXERGSDDD') #=> "01G70Y0Y7GZ1XWDAREXERGSDDD"
   # ULID.normalize('-olarz3-noekisv4rrff-q6ig5fav--') #=> "01ARZ3N0EK1SV4RRFFQ61G5FAV"
-  # ULID.normalized?('-olarz3-noekisv4rrff-q6ig5fav--') #=> false
-  # ULID.normalized?('01ARZ3N0EK1SV4RRFFQ61G5FAV') #=> true
+  # ULID.normalize('01G70Y0Y7G_Z1XWDAREXERGSDDD') #=> ULID::ParserError
   # ```
   #
   # See also [ulid/spec#57](https://github.com/ulid/spec/pull/57) and [ulid/spec#3](https://github.com/ulid/spec/issues/3)
@@ -325,13 +339,40 @@ class ULID < Object
   # Returns `true` if it is normalized string
   #
   # ```ruby
-  # ULID.normalize('-olarz3-noekisv4rrff-q6ig5fav--') #=> "01ARZ3N0EK1SV4RRFFQ61G5FAV"
-  # ULID.normalized?('-olarz3-noekisv4rrff-q6ig5fav--') #=> false
-  # ULID.normalized?('01ARZ3N0EK1SV4RRFFQ61G5FAV') #=> true
+  # ULID.normalized?('01G70Y0Y7GZ1XWDAREXERGSDDD') #=> true
+  # ULID.normalized?('01G70Y0Y7G-Z1XWDAREXERGSDDD') #=> false
+  # ULID.normalized?(ULID.generate.to_s.downcase) #=> false
+  # ULID.normalized?('01G70Y0Y7G_Z1XWDAREXERGSDDD') #=> false (Not raising ULID::ParserError)
   # ```
   #
   # See also [ulid/spec#57](https://github.com/ulid/spec/pull/57) and [ulid/spec#3](https://github.com/ulid/spec/issues/3)
-  def self.normalized?: (untyped) -> bool
+  def self.normalized?: (_ToStr string) -> bool
+                      | (untyped) -> false
+
+  # Returns `true` if it is valid in ULID format variants
+  #
+  # ```ruby
+  # ULID.valid_as_variant_format?(ULID.generate.to_s.downcase) #=> true
+  # ULID.valid_as_variant_format?('01G70Y0Y7G-Z1XWDAREXERGSDDD') #=> true
+  # ULID.valid_as_variant_format?('01G70Y0Y7G_Z1XWDAREXERGSDDD') #=> false
+  # ```
+  #
+  # See also [ulid/spec#57](https://github.com/ulid/spec/pull/57) and [ulid/spec#3](https://github.com/ulid/spec/issues/3)
+  def self.valid_as_variant_format?: (_ToStr string) -> bool
+                             | (untyped) -> false
+
+  # DEPRECATED Use valid_as_variant_format? instead
+  #
+  # Returns `true` if it is normalized string.
+  # Basically the difference of normalized? is to accept downcase or not. This returns true for downcased ULIDs.
+  #
+  # ```ruby
+  # ULID.valid?(ULID.generate.to_s.downcase) #=> true
+  # ```
+  #
+  # See also [ulid/spec#57](https://github.com/ulid/spec/pull/57) and [ulid/spec#3](https://github.com/ulid/spec/issues/3)
+  def self.valid?: (_ToStr string) -> bool
+                 | (untyped) -> false
 
   # Returns parsed ULIDs from given String for rough operations.
   #
@@ -411,7 +452,12 @@ class ULID < Object
   # #=> true
   # ```
   #
-  # To be precise, this sorting unaffected with `case sensitive or not` and might handle [ulid/spec#57](https://github.com/ulid/spec/pull/57) in future. So preferable than `lexicographically sortable` in actual case.
+  # To be precise, this sorting unaffected with `case sensitive or not` and might handle [ulid/spec#57](https://github.com/ulid/spec/pull/57) in future.
+  # So preferable than `lexicographically sortable` in actual case.
+  #
+  # This returns -1 | 0 | 1 for ULIDs. However defined as returning Integer. It is caused on ruby/rbs current definition.
+  #   https://github.com/ruby/ruby/blob/cd34f56d450f2310cceaf4c5f34d23eddfda58e8/numeric.c#L4646-L4660
+  #   https://github.com/ruby/rbs/blob/14abbbae8885a09a2ed82de2ef31d67a9c0a108d/core/integer.rbs#L461-L462
   #
   def <=>: (ULID other) -> Integer
          | (untyped other) -> nil

metadata

@@ -1,17 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: ruby-ulid
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Kenichi Kamiya
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-07-02 00:00:00.000000000 Z
+date: 2022-07-03 00:00:00.000000000 Z
 dependencies: []
-description: "    generator, monotonic generator, parser and manipulations for ULID
-  (RBS included)\n"
+description: "    generator, optional monotonicity, parser and tools for ULID (RBS
+  included)\n"
 email:
 - kachick1+ruby@gmail.com
 executables: []