lite-uxid 2.0.1 → 2.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9078e4e13dc6877ed30a6a0028ad4327ff95d3056a5303f789137272e2bb0f12
-  data.tar.gz: c25e8acbb22ad4e4381bf9b07018eaf12daaf8e1d0123cee24f5fa9c8af8e87a
+  metadata.gz: 7a5ffc2eb4b3088dfba64e17944b8da4e50b6daf1340e45dafb6ad9c98917bad
+  data.tar.gz: da4d9ac855493ca6556782375e775192e07ef4ecd8a8a90b7ed13a76160d6cd9
 SHA512:
-  metadata.gz: bd5d7ef2cd4c425fb798dea874a7f395e20e5514ca07fb807d673feb75187e8a236236bd7f833084983a820d71a05a7a27c80d72138a13f888fb5b088a4c869f
-  data.tar.gz: 24462c53958076c1435e1012f3608002d23fdb01b3d59d00ac9d7d78c81f8f1d91b3a80fcac78d9a6a9ce358d9db728af6dd6df3d6815037a1c7dfa25515ba3f
+  metadata.gz: 94dd97afca7b4eaebb652c6f916211b605a002645eae9500e0cc2fac1f85b1b213447e3f67278e768150acaf82dde5a7a1360cf86fe5142cb365e5d480404422
+  data.tar.gz: b15bb1df870cf94356098e8c87542f44e034a64dced29ddc0d7ebe292d9ceeaeb457a956bab23b8f8fee40e1d3c4c40e605805386f78e4807bd15af809b9f1da

data/CHANGELOG.md

@@ -6,6 +6,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.0.2] - 2024-09-23
+### Added
+- Prefixes to uuid and ulid
+### Changed
+- Improve configuration template
+- Improve hashid generation
+- Improve specs
+- Improve docs
+### Removed
+- Hashid size option
+
 ## [2.0.1] - 2024-09-23
 ### Changed
 - Renamed `Scatterid` to `Obfuscateid`

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    lite-uxid (2.0.1)
+    lite-uxid (2.0.2)
 
 GEM
   remote: https://rubygems.org/
@@ -162,7 +162,7 @@ GEM
       concurrent-ruby (~> 1.0)
     unicode-display_width (2.6.0)
     useragent (0.16.10)
-    webrick (1.8.1)
+    webrick (1.8.2)
     zeitwerk (2.6.18)
 
 PLATFORMS

data/README.md

@@ -27,12 +27,14 @@ Or install it yourself as:
 
 * [Configuration](#configuration)
 * [Usage](#usage)
-* [HashID](#hashid)
-* [NanoID](#nanoid)
-* [ObfuscateID](#obfuscateid)
-* [ULID](#ulid)
-* [UUID](#uuid)
 * [Options](#options)
+* [Reversible](#reversible)
+    * [HashID](#hashid)
+    * [ObfuscateID](#obfuscateid)
+* [Irreversible](#Irreversible)
+    * [NanoID](#nanoid)
+    * [ULID](#ulid)
+    * [UUID](#uuid)
 * [ActiveRecord](#active_record)
 * [Benchmarks](#benchmarks)
 
@@ -42,101 +44,112 @@ Or install it yourself as:
 `config/initalizers/lite_uxid.rb`
 
 ```ruby
-Lite::Uxid::ALPHANUMERIC = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
-Lite::Uxid::COCKFORDS_32 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"
-Lite::Uxid::WEB_SAFE     = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ-_"
-
 Lite::Uxid.configure do |config|
-  config.hashid_charset = ALPHANUMERIC
+  # HashID
+  config.hashid_charset = Lite::Uxid::ALPHANUMERIC
   config.hashid_salt = 1_369_136
-  config.hashid_size = 16
-  config.nanoid_charset = WEB_SAFE
+
+  # NanoID
+  config.nanoid_charset = Lite::Uxid::WEB_SAFE
   config.nanoid_size = 21
-  config.ulid_charset = COCKFORDS_32
+
+  # ObfuscatedID
+  config.obfuscateid_spin = 0
+
+  # ULID
+  config.ulid_charset = Lite::Uxid::COCKFORDS_32
   config.ulid_size = 26
+
+  # UUID
   config.uuid_version = 4
 end
 ```
 
 ## Usage
 
-#### Instance
+### Instance call
+
 ```ruby
 coder = Lite::Uxid::Reversible::Hashid.new(10, size: 12)
 coder.encode #=> '67wGI0'
 ```
 
-#### Class
+### Class call
 ```ruby
 Lite::Uxid::Reversible::Hashid.decode('67wGI0', size: 12) #=> 10
 ```
 
-## HashID
+## Options
 
-[More information](https://hashids.org)
+Local options can be passed to override global options.
 
 ```ruby
-Lite::Uxid::Reversible::Hashid.encode(10)        #=> '1zWr1m0'
-Lite::Uxid::Reversible::Hashid.decode('1zWr1m0') #=> 10
+Lite::Uxid::Irreversible::Ulid.encode(charset: 'abc123', size: 12) #=> 'a3b12c12c3ca'
 ```
 
-## NanoID
-
-[More information](https://github.com/ai/nanoid)
+Passable options are:
 
 ```ruby
-Lite::Uxid::Irreversible::Nanoid.encode #=> 'sMuNUa3Cegn6r5GRQ4Ij2'
+{
+  charset: 'string',  # Available for: hashid, nanoid, ulid
+  salt:    'string',  # Available for: hashid
+  size:    'integer', # Available for: nanoid, ulid
+  spin:    'integer', # Available for: obfuscateid
+  version: 'integer', # Available for: uuid
+  prefix:  'string'   # Available for: hashid, nanoid, ulid, uuid
+}
 ```
 
-## ObfuscateID
+## Reversible
 
-[More information](https://github.com/namick/scatter_swap)
+### HashID
+
+- [More information](https://hashids.org)
 
 ```ruby
-Lite::Uxid::Reversible::Obfuscateid.encode(10)         #=> '2056964183'
-Lite::Uxid::Reversible::Obfuscateid.decode(2056964183) #=> 10
+Lite::Uxid::Reversible::Hashid.encode(10)             #=> '7pau2oXSklq0'
+Lite::Uxid::Reversible::Hashid.decode('7pau2oXSklq0') #=> 10
 ```
 
-## ULID
+### NanoID
 
-[More information](https://github.com/ulid/spec)
+- [More information](https://github.com/ai/nanoid)
 
 ```ruby
-Lite::Uxid::Irreversible::Ulid.encode #=> '01GJAY9KGR539EZF4QWYEJGSN7'
+Lite::Uxid::Irreversible::Nanoid.encode #=> 'sMuNUa3Cegn6r5GRQ4Ij2'
 ```
 
-## UUID
+## Irreversible
+
+### ObfuscateID
 
-Implements `v4` and `v7` of the specification. [More information](https://en.wikipedia.org/wiki/Universally_unique_identifier)
+- [More information](https://github.com/namick/scatter_swap)
 
 ```ruby
-Lite::Uxid::Irreversible::Uuid.encode #=> '4376a67e-1189-44b3-a599-7f7566bf105b'
+Lite::Uxid::Reversible::Obfuscateid.encode(10)         #=> 2056964183
+Lite::Uxid::Reversible::Obfuscateid.decode(2056964183) #=> 10
 ```
 
-## Options
+### ULID
 
-Local options can be passed to override global options.
+- [More information](https://github.com/ulid/spec)
 
 ```ruby
-Lite::Uxid::Irreversible::Ulid.encode(charset: 'abc123', size: 12) #=> 'a3b12c12c3ca'
+Lite::Uxid::Irreversible::Ulid.encode #=> '01GJAY9KGR539EZF4QWYEJGSN7'
 ```
 
-Passable options are:
+### UUID
+
+Implements `v4` and `v7` of the specification.
+- [More information](https://en.wikipedia.org/wiki/Universally_unique_identifier)
 
 ```ruby
-{
-  charset: 'string',  # Available for: hashid, nanoid, ulid
-  salt:    'string',  # Available for: hashid
-  size:    'integer', # Available for: hashid, nanoid, ulid
-  spin:    'integer', # Available for: obfuscateid
-  version: 'integer', # Available for: uuid
-  prefix:  'string'   # Available for: hashid, nanoid
-}
+Lite::Uxid::Irreversible::Uuid.encode #=> '4376a67e-1189-44b3-a599-7f7566bf105b'
 ```
 
 ## ActiveRecord
 
-**Table**
+### Table
 
 Add the following attribute to all corresponding tables.
 
@@ -146,7 +159,7 @@ Add the following attribute to all corresponding tables.
 t.string :uxid, null: false, index: { unique: true }
 ```
 
-If using UUID and your database supports it:
+If using UUID or ULID and your database supports it:
 
 ```ruby
 t.uuid :uxid, null: false, index: { unique: true }
@@ -156,7 +169,7 @@ t.uuid :uxid, null: false, index: { unique: true }
 
 `uxid` attribute will be automatically generated and applied when the record is created.
 
-#### HashID
+### Mixin
 ```ruby
 class User < ActiveRecord::Base
   # Pick one:
@@ -168,7 +181,7 @@ class User < ActiveRecord::Base
 end
 ```
 
-Add a prefix to `hashid` and `nanoid` record types by adding a `uxid_prefix` method.
+HashID, NanoID, ULID, and UUID modules allow prefixing via the `uxid_prefix` method.
 
 ```ruby
 class User < ActiveRecord::Base
@@ -180,26 +193,38 @@ class User < ActiveRecord::Base
 end
 ```
 
-**Usage**
-
 Using the `hashid` and `nanoid` above provide handy methods to find records by uxid.
 
-#### Hashing methods
 ```ruby
 user = User.new
 user.id_to_uxid #=> Encodes the records id to uxid
 user.uxid_to_id #=> Decodes the records uxid to id
-```
 
-#### Finder methods
-```ruby
 User.find_by_uxid('x123')  #=> Find record by uxid
 User.find_by_uxid!('x123') #=> Raises an ActiveRecord::RecordNotFound error if not found
 ```
 
 ## Benchmarks
 
-The classes ranked from fastest to slowest are `UUID`, `HashID`, `NanoID`, `ULID`, and `ObfuscateID`.
+The classes ranked from fastest to slowest are `UUID`, `HashID`, `NanoID`, `ULID`, and `ObfuscateID`. Here are the latest results:
+
+```
+Calculating -------------------------------------
+              Hashid    135.993k (± 2.9%) i/s    (7.35 μs/i) -    681.588k in   5.016413s
+         Obfuscateid     30.702k (± 2.2%) i/s   (32.57 μs/i) -    155.907k in   5.080592s
+              NanoID     99.327k (± 1.5%) i/s   (10.07 μs/i) -    504.135k in   5.076630s
+                ULID     82.211k (± 2.3%) i/s   (12.16 μs/i) -    418.455k in   5.092823s
+             UUID v4    237.629k (± 6.8%) i/s    (4.21 μs/i) -      1.190M in   5.040477s
+             UUID v7    234.956k (±13.8%) i/s    (4.26 μs/i) -      1.153M in   5.051057s
+
+Comparison:
+             UUID v4:   237629.0 i/s
+             UUID v7:   234955.9 i/s - same-ish: difference falls within error
+              Hashid:   135993.5 i/s - 1.75x  slower
+              NanoID:    99327.3 i/s - 2.39x  slower
+                ULID:    82210.7 i/s - 2.89x  slower
+         Obfuscateid:    30702.0 i/s - 7.74x  slower
+```
 
 View how each compares by running the [benchmarks](https://github.com/drexed/lite-uxid/tree/master/benchmarks).
 

data/benchmarks/compare.rb

@@ -6,12 +6,12 @@ require "benchmark/ips"
 require "lite/uxid"
 
 Benchmark.ips do |x|
-  x.report("Hashid") do
+  x.report("HashID") do
     id = rand(1..1_000_000)
     Lite::Uxid::Reversible::Hashid.encode(id)
   end
 
-  x.report("Obfuscateid") do
+  x.report("ObfuscateID") do
     id = rand(1..1_000_000)
     Lite::Uxid::Reversible::Obfuscateid.encode(id)
   end
@@ -29,10 +29,15 @@ Benchmark.ips do |x|
     Lite::Uxid::Irreversible::Ulid.encode
   end
 
-  x.report("UUID") do
+  x.report("UUID v4") do
     _id = rand(1..1_000_000)
     Lite::Uxid::Irreversible::Uuid.encode
   end
 
+  x.report("UUID v7") do
+    _id = rand(1..1_000_000)
+    Lite::Uxid::Irreversible::Uuid.encode(version: 7)
+  end
+
   x.compare!
 end

data/lib/generators/lite/uxid/templates/install.rb

@@ -1,13 +1,21 @@
 # frozen_string_literal: true
 
 Lite::Uxid.configure do |config|
-  config.hashid_charset = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
-  config.hashid_salt = 1_369_136
-  config.hashid_size = 16
-  config.nanoid_charset = "_-0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
-  config.nanoid_size = 21
-  config.obfuscateid_spin = 0
-  config.ulid_charset = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"
-  config.ulid_size = 26
-  config.uuid_version = 4
+  # HashID
+  # config.hashid_charset = Lite::Uxid::ALPHANUMERIC
+  # config.hashid_salt = 1_369_136
+
+  # NanoID
+  # config.nanoid_charset = Lite::Uxid::WEB_SAFE
+  # config.nanoid_size = 21
+
+  # ObfuscatedID
+  # config.obfuscateid_spin = 0
+
+  # ULID
+  # config.ulid_charset = Lite::Uxid::COCKFORDS_32
+  # config.ulid_size = 26
+
+  # UUID
+  # config.uuid_version = 4
 end

data/lib/lite/uxid/base.rb

@@ -30,7 +30,7 @@ module Lite
       end
 
       def coder_length
-        @coder_length ||= coder_charset.size
+        @coder_length ||= coder_charset.length
       end
 
       def coder_prefix

data/lib/lite/uxid/configuration.rb

@@ -9,7 +9,7 @@ module Lite
 
     class Configuration
 
-      attr_accessor :hashid_charset, :hashid_size, :hashid_salt,
+      attr_accessor :hashid_charset, :hashid_salt,
                     :nanoid_charset, :nanoid_size,
                     :obfuscateid_spin,
                     :ulid_charset, :ulid_size,
@@ -18,7 +18,6 @@ module Lite
       def initialize
         @hashid_charset = ALPHANUMERIC
         @hashid_salt = 1_369_136
-        @hashid_size = 16
         @nanoid_charset = WEB_SAFE
         @nanoid_size = 21
         @obfuscateid_spin = 0

data/lib/lite/uxid/irreversible/ulid.rb

@@ -18,7 +18,7 @@ module Lite
             pos -= 1
           end
 
-          encoded_id
+          "#{coder_prefix}#{encoded_id}"
         end
 
         private

data/lib/lite/uxid/irreversible/uuid.rb

@@ -6,12 +6,15 @@ module Lite
       class Uuid < Base
 
         def encode
-          case coder_version
-          when 7
-            SecureRandom.uuid_v7
-          else
-            SecureRandom.uuid
-          end
+          encoded_id =
+            case coder_version
+            when 7
+              SecureRandom.uuid_v7
+            else
+              SecureRandom.uuid
+            end
+
+          "#{coder_prefix}#{encoded_id}"
         end
 
       end

data/lib/lite/uxid/record/hashid.rb

@@ -43,7 +43,8 @@ module Lite
         end
 
         def uxid_prefix
-          nil
+          # Define in your class to enable prefixing uxid.
+          # eg: "sub_" or "user_"
         end
 
         private

data/lib/lite/uxid/record/nanoid.rb

@@ -13,7 +13,8 @@ module Lite
         end
 
         def uxid_prefix
-          nil
+          # Define in your class to enable prefixing uxid.
+          # eg: "sub_" or "user_"
         end
 
         private

data/lib/lite/uxid/record/ulid.rb

@@ -12,10 +12,15 @@ module Lite
           end
         end
 
+        def uxid_prefix
+          # Define in your class to enable prefixing uxid.
+          # eg: "sub_" or "user_"
+        end
+
         private
 
         def callback_generate_uxid!
-          self.uxid = Lite::Uxid::Irreversible::Ulid.encode
+          self.uxid = Lite::Uxid::Irreversible::Ulid.encode(prefix: uxid_prefix)
         end
 
       end

data/lib/lite/uxid/record/uuid.rb

@@ -12,10 +12,15 @@ module Lite
           end
         end
 
+        def uxid_prefix
+          # Define in your class to enable prefixing uxid.
+          # eg: "sub_" or "user_"
+        end
+
         private
 
         def callback_generate_uxid!
-          self.uxid = Lite::Uxid::Irreversible::Uuid.encode
+          self.uxid = Lite::Uxid::Irreversible::Uuid.encode(prefix: uxid_prefix)
         end
 
       end

data/lib/lite/uxid/reversible/hashid.rb

@@ -5,14 +5,16 @@ module Lite
     module Reversible
       class Hashid < Base
 
+        MASK = 48
+
         def encode
-          encoded_id = encode_chars((id + coder_salt) << coder_size)
+          encoded_id = encode_chars((id + coder_salt) << MASK)
           "#{coder_prefix}#{encoded_id}"
         end
 
         def decode
           encoded_id = id.delete_prefix(coder_prefix.to_s)
-          (decode_chars(encoded_id) >> coder_size) - coder_salt
+          (decode_chars(encoded_id) >> MASK) - coder_salt
         end
 
         private
@@ -34,7 +36,7 @@ module Lite
         def decode_chars(encoded_id)
           pos = 0
           num = 0
-          len = encoded_id.size
+          len = encoded_id.length
           max = len - 1
 
           while pos < len

data/lib/lite/uxid/version.rb

@@ -3,7 +3,7 @@
 module Lite
   module Uxid
 
-    VERSION = "2.0.1"
+    VERSION = "2.0.2"
 
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lite-uxid
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.0.2
 platform: ruby
 authors:
 - Juan Gomez
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-09-23 00:00:00.000000000 Z
+date: 2024-09-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord