lite-uxid 2.0.0 → 2.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 767645737040b210cc058a0a781f89751f447e991aa03c527f5d12b039d1980a
-  data.tar.gz: 1c777db2675144f26b24ed2ec75d175c83f55d5ede9e83ab5d0d75ca2b76e692
+  metadata.gz: 7a5ffc2eb4b3088dfba64e17944b8da4e50b6daf1340e45dafb6ad9c98917bad
+  data.tar.gz: da4d9ac855493ca6556782375e775192e07ef4ecd8a8a90b7ed13a76160d6cd9
 SHA512:
-  metadata.gz: 313da972f69d52e8951d552c3269500767e7fb80255de25c44d1bbe0d6497aaa3b0c398736b2e451d393ad0642446e298ebbad36a225528f010a96a8684f221e
-  data.tar.gz: 61ce05436d5e2793164007f1b28edd28ea138c9efbf02f0a6ac6ef021708d3171b61c77e2811dfe9c65ef764b46d55713e6121eefd57d87a22cb10e80a9c0eef
+  metadata.gz: 94dd97afca7b4eaebb652c6f916211b605a002645eae9500e0cc2fac1f85b1b213447e3f67278e768150acaf82dde5a7a1360cf86fe5142cb365e5d480404422
+  data.tar.gz: b15bb1df870cf94356098e8c87542f44e034a64dced29ddc0d7ebe292d9ceeaeb457a956bab23b8f8fee40e1d3c4c40e605805386f78e4807bd15af809b9f1da

data/CHANGELOG.md

@@ -6,6 +6,23 @@ 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`
+### Removed
+- Removed prefix option from obfuscateid
+
 ## [2.0.0] - 2024-09-23
 ### Added
 - Scatterid reversible lib

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    lite-uxid (2.0.0)
+    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)
-* [Scatterid](#scatterid)
-* [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
+}
 ```
 
-## ScatterID
+## Reversible
+
+### HashID
 
-[More information](https://github.com/namick/scatter_swap)
+- [More information](https://hashids.org)
 
 ```ruby
-Lite::Uxid::Reversible::Scatterid.encode(10)           #=> '2056964183'
-Lite::Uxid::Reversible::Scatterid.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
 
-Implements `v4` and `v7` of the specification. [More information](https://en.wikipedia.org/wiki/Universally_unique_identifier)
+### ObfuscateID
+
+- [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: scatterid
-  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,80 +169,64 @@ 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:
   include Lite::Uxid::Record::Hashid
-end
-```
-
-#### NanoID
-```ruby
-class User < ActiveRecord::Base
   include Lite::Uxid::Record::Nanoid
-end
-```
-
-#### ScatterID
-```ruby
-class User < ActiveRecord::Base
-  include Lite::Uxid::Record::Scatterid
-end
-```
-
-#### ULID
-```ruby
-class User < ActiveRecord::Base
+  include Lite::Uxid::Record::Obfuscateid
   include Lite::Uxid::Record::Ulid
-end
-```
-
-#### UUID
-```ruby
-class User < ActiveRecord::Base
   include Lite::Uxid::Record::Uuid
 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
   include Lite::Uxid::Record::Hashid
 
   def uxid_prefix
-    "sub_"
+    "usr_"
   end
 end
 ```
 
-**Usage**
+Using the `hashid` and `nanoid` above provide handy methods to find records by uxid.
 
-Using one of the mixins above provides a handy method to find records by uxid.
-
-#### HashID 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`, and `Ulid`.
+The classes ranked from fastest to slowest are `UUID`, `HashID`, `NanoID`, `ULID`, and `ObfuscateID`. Here are the latest results:
 
-View how each compares by running the [benchmarks](https://github.com/drexed/lite-uxid/tree/master/benchmarks).
+```
+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
 
-#### Alternatives
+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
+```
 
-Learn more about alternative functions and more advance hashing setups:
-[hashids.org](https://hashids.org)
+View how each compares by running the [benchmarks](https://github.com/drexed/lite-uxid/tree/master/benchmarks).
 
 ## Development
 

data/benchmarks/compare.rb

@@ -6,24 +6,37 @@ 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::Hashid.encode(id)
+    Lite::Uxid::Reversible::Hashid.encode(id)
   end
 
+  x.report("ObfuscateID") do
+    id = rand(1..1_000_000)
+    Lite::Uxid::Reversible::Obfuscateid.encode(id)
+  end
+
+  # The irreversible examples include `rand` simulate
+  # the extra work just like reversible examples.
+
   x.report("NanoID") do
-    _id = rand(1..1_000_000) # To simulate the extra work from `rand`
-    Lite::Uxid::Nanoid.encode
+    _id = rand(1..1_000_000)
+    Lite::Uxid::Irreversible::Nanoid.encode
   end
 
   x.report("ULID") do
-    _id = rand(1..1_000_000) # To simulate the extra work from `rand`
-    Lite::Uxid::Ulid.encode
+    _id = rand(1..1_000_000)
+    Lite::Uxid::Irreversible::Ulid.encode
+  end
+
+  x.report("UUID v4") do
+    _id = rand(1..1_000_000)
+    Lite::Uxid::Irreversible::Uuid.encode
   end
 
-  x.report("UUID") do
-    _id = rand(1..1_000_000) # To simulate the extra work from `rand`
-    Lite::Uxid::Uuid.encode
+  x.report("UUID v7") do
+    _id = rand(1..1_000_000)
+    Lite::Uxid::Irreversible::Uuid.encode(version: 7)
   end
 
   x.compare!

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.scatterid_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,19 +9,18 @@ module Lite
 
     class Configuration
 
-      attr_accessor :hashid_charset, :hashid_size, :hashid_salt,
+      attr_accessor :hashid_charset, :hashid_salt,
                     :nanoid_charset, :nanoid_size,
-                    :scatterid_spin,
+                    :obfuscateid_spin,
                     :ulid_charset, :ulid_size,
                     :uuid_version
 
       def initialize
         @hashid_charset = ALPHANUMERIC
         @hashid_salt = 1_369_136
-        @hashid_size = 16
         @nanoid_charset = WEB_SAFE
         @nanoid_size = 21
-        @scatterid_spin = 0
+        @obfuscateid_spin = 0
         @ulid_charset = COCKFORDS_32
         @ulid_size = 26
         @uuid_version = 4

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/{scatterid.rb → obfuscateid.rb}

@@ -3,7 +3,7 @@
 module Lite
   module Uxid
     module Record
-      module Scatterid
+      module Obfuscateid
 
         def self.included(base)
           base.extend ClassMethods
@@ -17,7 +17,7 @@ module Lite
         module ClassMethods
 
           def find_by_uxid(uxid)
-            decoded_id = Lite::Uxid::Reversible::Scatterid.decode(uxid, prefix: new.uxid_prefix)
+            decoded_id = Lite::Uxid::Reversible::Obfuscateid.decode(uxid)
             find_by(id: decoded_id)
           end
 
@@ -33,17 +33,13 @@ module Lite
         def id_to_uxid
           return unless respond_to?(:uxid)
 
-          Lite::Uxid::Reversible::Scatterid.encode(id, prefix: uxid_prefix)
+          Lite::Uxid::Reversible::Obfuscateid.encode(id)
         end
 
         def uxid_to_id
           return unless respond_to?(:uxid)
 
-          Lite::Uxid::Reversible::Scatterid.decode(uxid, prefix: uxid_prefix)
-        end
-
-        def uxid_prefix
-          nil
+          Lite::Uxid::Reversible::Obfuscateid.decode(uxid)
         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/reversible/{scatterid.rb → obfuscateid.rb}

@@ -3,21 +3,18 @@
 module Lite
   module Uxid
     module Reversible
-      class Scatterid < Base
+      class Obfuscateid < Base
 
         def encode
           swap
           scatter
-
-          "#{coder_prefix}#{joined_array}"
+          result
         end
 
         def decode
-          @id = id.delete_prefix(coder_prefix.to_s)
-
           unscatter
           unswap
-          joined_array.to_i
+          result
         end
 
         private
@@ -30,8 +27,8 @@ module Lite
           @coder_array ||= zero_padded_id.chars.collect(&:to_i)
         end
 
-        def joined_array
-          coder_array.join
+        def result
+          coder_array.join.to_i
         end
 
         def swapper_map(index)

data/lib/lite/uxid/version.rb

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

data/lib/lite/uxid.rb

@@ -12,9 +12,9 @@ require "lite/uxid/irreversible/ulid"
 require "lite/uxid/irreversible/uuid"
 require "lite/uxid/reversible/base"
 require "lite/uxid/reversible/hashid"
-require "lite/uxid/reversible/scatterid"
+require "lite/uxid/reversible/obfuscateid"
 require "lite/uxid/record/hashid"
 require "lite/uxid/record/nanoid"
-require "lite/uxid/record/scatterid"
+require "lite/uxid/record/obfuscateid"
 require "lite/uxid/record/ulid"
 require "lite/uxid/record/uuid"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lite-uxid
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  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
@@ -225,12 +225,12 @@ files:
 - lib/lite/uxid/irreversible/uuid.rb
 - lib/lite/uxid/record/hashid.rb
 - lib/lite/uxid/record/nanoid.rb
-- lib/lite/uxid/record/scatterid.rb
+- lib/lite/uxid/record/obfuscateid.rb
 - lib/lite/uxid/record/ulid.rb
 - lib/lite/uxid/record/uuid.rb
 - lib/lite/uxid/reversible/base.rb
 - lib/lite/uxid/reversible/hashid.rb
-- lib/lite/uxid/reversible/scatterid.rb
+- lib/lite/uxid/reversible/obfuscateid.rb
 - lib/lite/uxid/version.rb
 - lite-uxid.gemspec
 homepage: http://drexed.github.io/lite-uxid