base58_id 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 350af1c45ca377d67a9d8223e069a2fe4d7578ba2a1428f54fa0ed9dfc3935e0
-  data.tar.gz: bb0a090804ba8890d5d3c1a851932dd137ff64985b806c01736c1b3c9b63fe0a
+  metadata.gz: 65f4480fda9f96d178cef620945be28ff9dbf552d7d52076af7f5bd240e7e430
+  data.tar.gz: 685d5c2bd0c49d6acbd961939efafcaea0a2e327cf9ee0fb377605b026a0e27e
 SHA512:
-  metadata.gz: 39220e72e36409269d9d6d6dc74bf54a6aef3c40a45096f049190e3e89a0b68df150e6ab843deadb951b99c6e630981a29b05db18a757293845caeaea938a2b6
-  data.tar.gz: 5450dc9d8a03b82716ba14c8bb9000654b80918200586b10c1ba1211626962d73fbb9a0f698ec8098e6c6951608373537cdb746790130034e7a816e87be4cca6
+  metadata.gz: fb7ab1847d946c426915cd79879f88928f68b9b9e509a3e9852b821feac65f1c7937bc58931bb469eb798cbdb887a4b6a9109693d449a1d38a65589e02435d06
+  data.tar.gz: e39086f6f0850df707f8075029326f71566190767a090316d22f3adcb94d5a6d8cfc7710c9f1a2ed7501b13c00b7577796067b745a4d3ab0e4843a9fb3e644bc

data/.rubocop.yml

@@ -39,6 +39,9 @@ Style/TrailingCommaInArrayLiteral:
 Style/TrailingCommaInHashLiteral:
   Enabled: false
 
+Naming/MethodParameterName:
+  Enabled: false
+
 RSpec/ExampleLength:
   Enabled: false
 RSpec/MultipleExpectations:

data/README.md

@@ -1,6 +1,6 @@
 # Base58Id
 
-Convert an Integer ID or a UUID String to/from Base58 String
+Convert Integer ID or UUID String to/from Base58 String; Generate random Base58 String
 
 ## Install
 
@@ -15,14 +15,14 @@ Or via `Gemfile` in your project:
 ```sh
 source 'https://rubygems.org'
 
-gem 'base58_id', '~> 1.0'
+gem 'base58_id', '~> 1.1'
 ```
 
 Or build and install the gem locally:
 
 ```sh
 gem build base58_id.gemspec
-gem install base58_id-1.0.0.gem
+gem install base58_id-1.1.0.gem
 ```
 
 Require it in your Ruby code and the `Base58Id` class will be available:
@@ -41,7 +41,9 @@ a b c d e f g h i j k   m n o p q r s t u v w x y z
   1 2 3 4 5 6 7 8 9
 ```
 
-## Example
+## Examples
+
+### Converting
 
 ```rb
 require 'base58_id'
@@ -82,12 +84,14 @@ Base58Id::UUID_PATTERN
 # => /\A(0x)?[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}\z/i
 ```
 
-### Note
+### Notes about zero
 
 As it performs an integer conversion, Base58 leading zeros (represented by `A`)
 are ignored/lost:
 
 ```rb
+require 'base58_id'
+
 Base58Id.base58_to_integer('A') == Base58Id.base58_to_integer('AAAAAA')
 # => true
 
@@ -102,6 +106,8 @@ Base58Id.integer_to_base58(Base58Id.base58_to_integer('AAAAAAqocqGYw9LEfu4WVujMz
 And an empty Base58 String also represents zero:
 
 ```rb
+require 'base58_id'
+
 Base58Id.base58_to_integer('')
 # => 0
 
@@ -112,6 +118,66 @@ Base58Id.base58_to_integer('') == Base58Id.base58_to_integer('A')
 # => true
 ```
 
+### Generating random Base58 number strings from Integers
+
+```rb
+require 'base58_id'
+
+# Using the default range [0, 2^63 - 1]
+Base58Id.random_number
+# => "RvHTkxcYYJ4"
+
+# With a custom max, i.e. [0, max)
+Base58Id.random_number(100) # [0, 100)
+# => "BW"
+
+# With custom ranges
+Base58Id.random_number(100..1_000) # [100, 1000]
+# => "L2"
+Base58Id.random_number(100...1_000) # [100, 1000)
+# => "Qv"
+```
+
+Under the hood, the implementation just passes the `max_or_range` argument to
+`SecureRandom.random_number` and then the result to `Base58Id.integer_to_base58`:
+
+```rb
+require 'securerandom'
+require 'base58_id'
+
+class Base58Id
+  # ...
+
+  DEFAULT_RANDOM_RANGE = 0..(2**63 - 1)
+
+  # ...
+
+  def self.random_number(max_or_range = nil)
+    max_or_range = DEFAULT_RANDOM_RANGE if max_or_range.nil?
+
+    integer_to_base58(SecureRandom.random_number(max_or_range))
+  end
+
+  def self.rand(*args)
+    random_number(*args)
+  end
+end
+```
+
+### Generating random Base58 string digits
+
+```rb
+require 'base58_id'
+
+# Using the default number of random digits, 10
+Base58Id.random_digits
+# => "EWcSDcga66"
+
+# With a custom number of random digits
+Base58Id.random_digits(42)
+# => "YJn8u1UhkS9vt3YrWFPTXzMjzqFze7v2nWUbcdmnrU"
+```
+
 ## Tests
 
 Run tests with:

data/base58_id.gemspec

@@ -6,7 +6,7 @@ Gem::Specification.new do |s|
   s.name     = 'base58_id'
   s.version  = Base58Id::VERSION
   s.license  = 'MIT'
-  s.summary  = 'Convert an Integer ID or a UUID String to/from Base58 String'
+  s.summary  = 'Convert Integer ID or UUID String to/from Base58 String; Generate random Base58 String'
   s.homepage = 'https://github.com/elias19r/base58_id'
   s.author   = 'Elias Rodrigues'
 

data/lib/base58_id/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Base58Id
-  VERSION = '1.0.0'
+  VERSION = '1.1.0'
 end

data/lib/base58_id.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'securerandom'
+
 class Base58Id
   # Based on Base64 URL-safe alphabet but with I, O, l, 0, -, _ removed.
   ALPHABET_58 = %w[
@@ -15,6 +17,9 @@ class Base58Id
   UUID_PATTERN = /\A(0x)?[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}\z/i.freeze
   UUID_BYTES_FORMAT = '%02x%02x%02x%02x-%02x%02x-%02x%02x-%02x%02x-%02x%02x%02x%02x%02x%02x'
 
+  DEFAULT_RANDOM_RANGE = (0..((2**63) - 1)).freeze
+  DEFAULT_RANDOM_DIGITS = 10
+
   def self.integer_to_base58(integer)
     raise ArgumentError, 'argument must be an Integer' unless integer.is_a?(Integer)
     raise ArgumentError, 'argument must be greater than or equal to zero' if integer.negative?
@@ -70,4 +75,22 @@ class Base58Id
 
     value.match?(UUID_PATTERN)
   end
+
+  def self.random_number(max_or_range = nil)
+    max_or_range = DEFAULT_RANDOM_RANGE if max_or_range.nil?
+
+    integer_to_base58(SecureRandom.random_number(max_or_range))
+  end
+
+  def self.rand(*args)
+    random_number(*args)
+  end
+
+  def self.random_digits(n = nil)
+    n = DEFAULT_RANDOM_DIGITS if n.nil?
+
+    raise ArgumentError, 'argument must be an Integer' unless n.is_a?(Integer)
+
+    n.times.reduce('') { |str, _| str + ALPHABET_58[SecureRandom.random_number(58)] }
+  end
 end

data/spec/base58_id_spec.rb

@@ -4,7 +4,7 @@ require 'spec_helper'
 require 'base58_id'
 
 RSpec.describe Base58Id do
-  it 'converts an Integer ID or a UUID String to/from Base58 String' do
+  it 'converts Integer ID or UUID String to/from Base58 String' do
     base58 = generate_base58
 
     expect(
@@ -366,6 +366,108 @@ RSpec.describe Base58Id do
     end
   end
 
+  describe '.random_number' do
+    context 'when max_or_range is not set or nil' do
+      it 'generates a random Base58 String using the default range' do
+        expected_default_random_range = 0..((2**63) - 1)
+
+        allow(SecureRandom).to receive(:random_number).with(expected_default_random_range).and_return(1000)
+
+        expect(described_class.random_number).to eq('TQ')
+        expect(described_class.random_number(nil)).to eq('TQ')
+
+        expect(SecureRandom).to have_received(:random_number).with(expected_default_random_range).twice
+      end
+    end
+
+    context 'when max_or_range is set and not nil' do
+      it 'generates a random Base58 String using the given range' do
+        max_or_range = 100
+
+        allow(SecureRandom).to receive(:random_number).and_return(99)
+
+        expect(described_class.random_number(max_or_range)).to eq('Bs')
+
+        expect(SecureRandom).to have_received(:random_number).with(max_or_range).once
+      end
+    end
+  end
+
+  describe '.rand as an alias to random_number' do
+    context 'when max_or_range is not set or nil' do
+      it 'generates a random Base58 String using the default range' do
+        expected_default_random_range = 0..((2**63) - 1)
+
+        allow(SecureRandom).to receive(:random_number).with(expected_default_random_range).and_return(1000)
+
+        expect(described_class.rand).to eq('TQ')
+        expect(described_class.rand(nil)).to eq('TQ')
+
+        expect(SecureRandom).to have_received(:random_number).with(expected_default_random_range).twice
+      end
+    end
+
+    context 'when max_or_range is set and not nil' do
+      it 'generates a random Base58 String using the given range' do
+        max_or_range = 100
+
+        allow(SecureRandom).to receive(:random_number).and_return(99)
+
+        expect(described_class.rand(max_or_range)).to eq('Bs')
+
+        expect(SecureRandom).to have_received(:random_number).with(max_or_range).once
+      end
+    end
+  end
+
+  describe '.random_digits' do
+    context 'when n is set to non-nil but not an Integer' do
+      it 'raises an ArgumentError' do
+        non_integer = Object.new
+
+        expect do
+          described_class.random_digits(non_integer)
+        end.to raise_error(ArgumentError, 'argument must be an Integer')
+      end
+    end
+
+    context 'when n is not set or nil' do
+      it 'generates a random string of 10 Base58 digits' do
+        string = described_class.random_digits
+
+        expect(string.size).to eq(10)
+        expect(string.count("^#{base58_chars.join}")).to eq(0)
+
+        string = described_class.random_digits(nil)
+
+        expect(string.size).to eq(10)
+        expect(string.count("^#{base58_chars.join}")).to eq(0)
+      end
+    end
+
+    context 'when n is zero or a negative Integer' do
+      it 'returns an empty string' do
+        string = described_class.random_digits(0)
+
+        expect(string).to eq('')
+
+        string = described_class.random_digits(generate_negative_integer)
+
+        expect(string).to eq('')
+      end
+    end
+
+    context 'when n is a positive Integer' do
+      it 'generates a random string of n Base58 digits' do
+        n = SecureRandom.random_number(1..256)
+        string = described_class.random_digits(n)
+
+        expect(string.size).to eq(n)
+        expect(string.count("^#{base58_chars.join}")).to eq(0)
+      end
+    end
+  end
+
   def generate_uuid
     SecureRandom.uuid
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: base58_id
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Elias Rodrigues
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-06-30 00:00:00.000000000 Z
+date: 2022-10-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -128,7 +128,7 @@ homepage: https://github.com/elias19r/base58_id
 licenses:
 - MIT
 metadata:
-  source_code_uri: https://github.com/elias19r/base58_id/tree/v1.0.0
+  source_code_uri: https://github.com/elias19r/base58_id/tree/v1.1.0
   rubygems_mfa_required: 'true'
 post_install_message: 
 rdoc_options: []
@@ -145,8 +145,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.1.4
 signing_key: 
 specification_version: 4
-summary: Convert an Integer ID or a UUID String to/from Base58 String
+summary: Convert Integer ID or UUID String to/from Base58 String; Generate random
+  Base58 String
 test_files: []