make_id 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 90cbe0cbac923318d4badd6c848042404633a27c6fbecdd7e2509aee6c31ab5c
-  data.tar.gz: 41f946d9367bb73257ac31ffce792bd309f2e707c44b39003d66dcc3d1890a49
+  metadata.gz: 2448e655a9a006abb23272b2b54c6b4fc537f702407c931afcf106b82c468b04
+  data.tar.gz: 9852758f34e12c2be8aa90149cdded09e011f2ab879320089fc1bfb3f577d849
 SHA512:
-  metadata.gz: da8822e1194eb4ed1e51f1090f120db17cdd421fc330f84dbe4b4556c1dd71eac4dc33dff678768999cee03ad21749a9f3bbb5a2949ced4f83c7f7afd802128a
-  data.tar.gz: '038ae0b3bc50252cd75eec5fb7283feb27381e3362bd2681fbba6ff225865727ef4fa560f84d24e8c4703f5ba96ce168c9278462b9469b97323ab981869e387d'
+  metadata.gz: 108e40b61bfdcc00ac5e550b4afb14fb8f7298df617d10b7179975b2be8f6f04c6b4693fc6909de26f42e6a9977333d12f7ecc5c5846b1317b3ab728b6e6d04d
+  data.tar.gz: 25c7229af03bc353707c2ee832f00c2ad63243318156ffa51bcd197f328a2cae865eaf37fa0949d7c8d98bcf9e583b4ec8f2fb2563317d7584b906b9f3c8cf08

data/README.md

@@ -40,18 +40,19 @@ numeric codes.
 
 Bases supported are:
 
-- Base62: digits, upper, and lower-case letters. No special characters
+- Base94: Base64 (Upper, Lower, Digits) with 30 extra special characters
+- Base64: Url-Safe version. Base64 but swaps the plus and slash by dash and underscore respectively.
+- Base62: digits, upper, and lower-case letters. No special characters. The default.
 - Base32: digits and upper case without ambiguous characters "1lI" or "oO0"
 - Base 2 through 36 (except 32): Ruby's `Integer#to_s(base)` is used
-- Base64: Uses the `Base64.urlsafe_encode64` such has 2 special characters.
-- Base63: It is not implemented.
 
-The Base32 may seem out of place, but is useful for alpha-numeric codes the users are required to type, such as redemption codes.
-All letter are folded to upper-case, and ambiguous characters are converted to the canonical ones.
+The Base32 may seem out of place, but is useful for alpha-numeric codes the users are required to type or speak,
+such as serial numbers or license codes.
+All letters are upper-case, and ambiguous characters are converted to the canonical ones.
 
-    MakeId.int_to_base(123456789, 32) #=> "3nqk8n"
-    MakeId.from_base("3nqk8n", 10)    #=> 123456789
-    MakeId.int_to_base(123456789, 32) #=> "3nqk8n"
+    MakeId.int_to_base(123456789, 32) #=> "3NQK8N"
+    MakeId.from_base("3NQK8N", 10)    #=> 123456789
+    MakeId.int_to_base(123456789, 32) #=> "3NQK8N"
     MakeId.verify_base32_id("...")    #=> corrected_id or nil if error
 
 ### Random Integer
@@ -60,8 +61,14 @@ MakeId can return a random (8-byte by default) integer. You can request it retur
 and with an optional check_digit.
 Usually, you would use the integer returned, and call `int_to_base` to format for a URL or code.
 
-    MakeId.random_id() #=> 15379918763975837985ZZ
-    MakeId.random_id(base: 62, check_digit: true) #=> "2984biEwRT1"
+    MakeId.id() #=> 15379918763975837985ZZ
+    MakeId.id(base: 62, check_digit: true) #=> "2984biEwRT1"
+
+Nano Id's are shorter unique strings generated from random characters, usually as a friendlier alternative
+to UUID's. These are 8-byte numeric identifiers in extended bases, such as 36 or 62.
+
+    MakeId.nano_id()         #=> "iZnLn96FVcjivEJA" (Base-62 be default)
+    MakeId.nano_id(base: 36) #=> "sf8kqb8ekn7k98rq"
 
 ### UUID
 
@@ -75,16 +82,28 @@ can be used to transform a long UUID into a possibly more palettable base repres
     MakeId.uuid_to_base(u, 62) #=> "fWJtuXEQJnkjxroWjkmei" (21 characters)
 
 Note that some databases support a UUID type which makes storing UUID's easier, and since they are stored as a binary
-field, consume less space.ZZ
+field, consume less space.
 
-### Nano Id
+### Tokens
 
-Nano Id's are shorter unique strings generated from random characters, usually as a friendlier alternative
-to UUID's. They also can be of any size, depending on the key range you require. Pay attention to the keyspace,
-ensuring you have enough characters to avoid predictable collisions in the future.
+Tokens are randomly-generated strings of the character set of the requested base.
+The default size is 16 characters of the Base-62 character set.
+
+    MakeId.token() #=> "Na4VX61PBFVZWL6Y"
+    MakeId.token(8, base:36) #=> "BK0ZTL9H"
+
+### Codes
 
-    MakeId.nano_id(size: 16) #=> "iZnLn96FVcjivEJA"
-    MakeId.nano_id(size: 16, base: 32) #=> "sf8kqb8ekn7k98rq"
+Codes are string tokens to send to users for input. They have no ambiguous characters to avoid confusion.
+This is useful for verifications such as two-factor authentication codes, or license numbers.
+This returns an 8-character string by default. Specify a group (size) and delimiter (default is a hyphen)
+to make long codes readable.
+
+    MakeId.code #=> "22E0D18F"
+    MakeId.code(20) #=> "Y41Q24AG7DYZYTAZWQZX"
+    MakeId.code(20, group: 4, delimiter: "-") #=> "9975-V5VM-KKSR-4PQ6-7F4G"
+
+### Temporal Identifiers
 
 A `request_id` is a nano_id that can be used to track requests and jobs. It is a 16-byte string, the same
 storage as a UUID, but with columnar values. The substring of 3 for 8 is a short (8 character) version that
@@ -95,9 +114,7 @@ can be used as well, is easier to read, sortable within a day, and unique enough
     id[3,8]                #=> "f1272t01"
     #-------------------------->Hsssuuqq
 
-### Snowflake Id
-
-Snowflakes were invented at Twitter to stamp an identifier for a tweet or direct message.
+Snowflake Id's were invented at Twitter to stamp an identifier for a tweet or direct message.
 It is an 8-byte integer intended to be time-sorted and unique across the fleet of servers saving messages.
 It is a bit-mapped integer consisting of these parts:
 
@@ -120,7 +137,7 @@ You can also pass in options to return it as a different base, and with a check
 
     MakeId.app_worker_id = 234
     MakeId.snowflake_id => 618905333721374720
-    MakeId.snowflake_id(worker_id: 12, base: 32, sequence_method: :random) #=> "2tmxk6ne81jd5"
+    MakeId.snowflake_id(worker_id: 12, base: 32, sequence_method: :random) #=> "2TMXK6NE81JD5"
 
 The `snowflake_uuid` method provides a time-based identifier, great for sorting just as sequential numbers, but unique enough to fit the bill.
 
@@ -136,18 +153,6 @@ records or when you need a slowflake ID but have a UUID column to fill.
     MakeID.snowflake_datetime_uuid #=> "20240904-1418-5332-2000-3a38e61d5582"
     #------------------------>YYYYMMDD-hhmm-ssuu-uwww-rrrrrrrrrrrr
 
-## Experimental Id's
-
-The `event_id` is a string, sortable by creation time, with visible time seperator columns.
-It is of the format "YMDhmsuurrrr", using Base62, with an optional check_sum characer.
-It also used the application epoch described under `snowflake_id`. "uu" represents the fractional
-seconds that can be represented in Base62, and a 4-character random Base64 "nano_id".
-
-    MakeId.epoch = 2020
-    MakeId.event_id #=> "493KgpQGErTB"
-    #------------------->YMDhmsuurrrr ()
-    MakeId.event_id(check_digit: true) #=> "493Kkha6HZa2" (3 random chars + check digit)
-
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/make_id/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MakeId
-  VERSION = "0.1.0"
+  VERSION = "0.1.2"
 end

data/lib/make_id.rb

@@ -2,7 +2,6 @@
 
 require_relative "make_id/version"
 require "securerandom"
-require "base64"
 require "zlib"
 
 # MakeID generates record Identifiers other than sequential integers.
@@ -11,10 +10,27 @@ require "zlib"
 # Adopt   - Copy this file to your application with the above attribution to
 #           allow others to find fixes, documentation, and new features.
 module MakeId
-  # class Error < StandardError; end
+  class Error < StandardError; end
 
-  CHARS32 = "0123456789abcdefghjkmnpqrstvwxyz" # Avoiding ambiguous 0/o i/l/I
-  CHARS62 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+  # Base32 avoids ambiguous letters for 0/o/O and i/I/l/1. This is useful
+  # for human-interpreted codes for serial numbers, license keys, etc.
+  BASE32 = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+
+  # Ruby's Integer.to_s(2..36) uses extended Hexadecimal: 0-9,a-z.
+  # Base62 includes upper-case letters as well, maintaining ASCII cardinality.
+  BASE62 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+
+  # Base64 Does not use ASCII-collating (sort) character set
+  BASE64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
+
+  # Base94 extends Base64 with all printable ASCII special characters.
+  # Using Base of 90 won't use quotes, backslash
+  BASE94 = BASE64 + %q(!$%&()*,-.:;<=>?@[]^_{|}~#`'"\\)
+
+  # URL-Encoded Base64 swaps the + and / for - and _ respectively to avoid URL Encoding
+  URL_BASE64 = BASE64.tr("+/", "-_")
+
+  # TWitter Snowflake starts its epoch at this time.
   EPOCH_TWITTER = Time.utc(2006, 3, 21, 20, 50, 14)
 
   @@app_worker_id = ENV.fetch("APP_WORKER_ID", 0)
@@ -57,31 +73,11 @@ module MakeId
   end
 
   ##############################################################################
-  # Random Strings
-  ##############################################################################
-
-  # Returns a random alphanumeric string of the given base, default of 62.
-  # Base 64 uses URL-safe characters. Bases 19-32 and below use a special
-  # character set that avoids visually ambiguous characters. Other bases
-  # utilize the full alphanumeric characer set (digits, lower/upper letters).
-  def self.random(size = 16, base: 62)
-    raise "Base must be between 2 and 62, or 64, not #{base}" unless base < 63 || base == 64
-    if base == 62
-      SecureRandom.alphanumeric(size)
-    elsif base == 64
-      SecureRandom.urlsafe_base64(size)
-    else
-      alpha = (base <= 32) ? CHARS32 : CHARS62
-      (1..size).map { alpha[SecureRandom.rand(base - 1)] }.join
-    end
-  end
-
-  ##############################################################################
-  # Integers
+  # Numeric Identifiers (of any suported base)
   ##############################################################################
 
   # Random Integer ID
-  def self.random_id(bytes: 8, base: 10, absolute: true, check_digit: false)
+  def self.id(bytes: 8, base: 10, absolute: true, check_digit: false)
     id = SecureRandom.random_number(2**(bytes * 8) - 2) + 1 # +1 to avoid zero
     id = id.abs if absolute
     id = int_to_base(id, base) unless base == 10
@@ -89,11 +85,26 @@ module MakeId
     id
   end
 
+  def self.id_password(bytes: 8, base: 10, absolute: true, alpha: nil)
+    id = id(bytes: bytes)
+    pass = id(bytes: 16)
+    [int_to_base(id, base), encode_alphabet(pass, alpha || BASE94, seed: id)]
+  end
+
+  # Generates a 8-byte "nano id", a string of random characters of the given alphabet,
+  # suitable for URL's or where you don't want to show a sequential number.
+  # A check digit can be added to the end to help prevent typos.
+  def self.nano_id(bytes: 8, base: 62, check_digit: true)
+    bytes -= 1 if check_digit
+    id = id(bytes: bytes, base: base)
+    check_digit ? append_check_digit(id, base) : id
+  end
+
   ##############################################################################
   # UUID - Universally Unique Identifier
   ##############################################################################
 
-  # Returns a (securely) random generated UUID v4
+  # Returns a 16-byte securely-random generated UUID v4
   def self.uuid
     SecureRandom.uuid
   end
@@ -106,66 +117,57 @@ module MakeId
   end
 
   ##############################################################################
-  # Nano Id - Simple, secure URL-friendly unique string ID generator
+  # Strings Identifiers
   ##############################################################################
 
-  # Generates a "nano id", a string of random characters of the given alphabet,
-  # suitable for URL's or where you don't want to show a sequential number.
-  # A check digit is added to the end to help prevent typos.
-  def self.nano_id(size: 20, base: 62, check_digit: true)
-    # alpha = (base <= 32) ? CHARS32 : CHARS62
-    size -= 1 if check_digit
-    id = random(size, base: base)
-    check_digit ? append_check_digit(id, base) : id
-  end
-
-  # Given a nano_id, replaces visually ambiguous characters and verifies the
-  # check digit. Returns the corrected id or nil if the check digit is invalid.
-  def self.verify_base32_id(nanoid)
-    nanoid.gsub!(/[oO]/, "0")
-    nanoid.gsub!(/[lLiI]/, "1")
-    nanoid.downcase
-    valid_check_digit?(nanoid, base: 32)
+  # Returns a random alphanumeric string of the given base, default of 62.
+  # Base 64 uses URL-safe characters. Bases 19-32 and below use a special
+  # character set that avoids visually ambiguous characters. Other bases
+  # utilize the full alphanumeric characer set (digits, lower/upper letters).
+  def self.token(size = 16, base: 62, chars: nil)
+    _, chars = base_characters(base, chars)
+    SecureRandom.alphanumeric(size, chars: chars.chars)
   end
 
-  # Manual Id is a code and/or identifier that is manually entered by a user.
-  # Examples of this would be a Two-Factor Authentication challenge, a code
-  # used for confirmation, redemption, or a short-term record lookup code
-  # (like an airline ticket/itenerary code)
-  # It uses a base-32 (non-ambiguous character set) by default,
-  def self.manual_id(size: 6, base: 32, check_digit: false)
-    base = 32 if base > 36 # For upcasing
-    nano_id(size: size, base: base, check_digit: check_digit).upcase
+  # Returns a new, ramdonly-generated Base-32 code (no ambiguous characters).
+  # Use this for Two-Factor Authorization, and serial number codes to be
+  # input by users. Use verify_code() to "fix" user-input of codes.
+  def self.code(size = 8, group: 0, delimiter: "-")
+    id = token(size, base: 32)
+    id = id.chars.each_slice(group).map(&:join).join(delimiter) if group > 0
+    id
   end
 
-  def self.fix_manual_id(id, base: 32, check_digit: false)
-    if base == 32
-      id = id.gsub(/[oO]/, "0")
-      id = id.gsub(/[lLiI]/, "1")
-    end
-    id = valid_check_digit?(id.downcase, base: 32) if check_digit
-    id.upcase
+  # Given a nano_id, replaces visually ambiguous characters and verifies the
+  # check digit. Returns the corrected id or nil if the check digit is invalid.
+  def self.verify_code(nanoid, check_digit: false)
+    nanoid = nanoid.gsub(/\W/, "")
+    nanoid = nanoid.gsub(/[oO]/, "0")
+    nanoid = nanoid.gsub(/[lLiI]/, "1")
+    nanoid = nanoid.upcase
+    return valid_check_digit?(nanoid, base: 32) if check_digit
+    nanoid
   end
 
   ##############################################################################
-  # Event Id - A nano_id, but timestamped event identifier: YMDHMSUUrrrrc
+  # TEMPORAL Identifiers
   ##############################################################################
 
-  # Returns an event timestamp of the form YMDHMSUUrrrrc
+  # Event Id - A nano_id, but timestamped event identifier: YMDHMSUUrrrrc
   def self.event_id(size: 12, check_digit: false, time: nil)
     time ||= Time.new.utc
     usec = int_to_base((time.subsec.to_f * 62 * 62).to_i, 62)
     parts = [
-      CHARS62[time.year % @@epoch.year],
-      CHARS62[time.month],
-      CHARS62[time.day],
-      CHARS62[time.hour],
-      CHARS62[time.min],
-      CHARS62[time.sec],
+      BASE62[time.year % @@epoch.year],
+      BASE62[time.month],
+      BASE62[time.day],
+      BASE62[time.hour],
+      BASE62[time.min],
+      BASE62[time.sec],
       usec.rjust(2, "0") # 2-chars, 0..3843
     ]
     nano_size = size - 8 - (check_digit ? 1 : 0)
-    parts << nano_id(size: nano_size, base: 62) if nano_size > 0
+    parts << token(nano_size, base: 62) if nano_size > 0
     id = check_digit ? append_check_digit(parts.join, 62) : parts.join
     id[0, size]
   end
@@ -183,15 +185,15 @@ module MakeId
     end
 
     [
-      CHARS62[time.year % @@epoch.year],
-      CHARS62[time.month],
-      CHARS62[time.day], # "-",
-      CHARS62[time.hour].downcase,
+      BASE62[time.year % @@epoch.year],
+      BASE62[time.month],
+      BASE62[time.day], # "-",
+      BASE62[time.hour].downcase,
       int_to_base(seconds, 32).rjust(3, "0"), # 3 chars
       int_to_base((time.subsec.to_f * 32 * 32).to_i, 32), # 2 chars
       sequence.to_s(32).rjust(2, "0"), # 2 chars "-",
       (app_worker_id % 1024).to_s(32).rjust(2, "0"), # 2 chars
-      random(3, base: 32)
+      token(3, base: 32)
     ].join
   end
 
@@ -298,23 +300,9 @@ module MakeId
   # Ruby's int.to_s(base) only goes to 36. Base 32 is special as it does not
   # contain visually ambiguous characters (1, not i, I, l, L) and (0, not o or O)
   # Which is useful for serial numbers or codes the user has to read or type
-  def self.int_to_base(int, base = 62, check_digit: false)
-    int = int.to_i
-    if base == 10
-      id = int.to_s
-    elsif base == 64
-      id = Base64.urlsafe_encode64(int.to_s).delete("=")
-    elsif base == 32 || base > 36
-      alpha = (base <= 32) ? CHARS32 : CHARS62
-      id = ""
-      while int > (base - 1)
-        id = alpha[int % base] + id
-        int /= base
-      end
-      id = alpha[int] + id
-    else
-      id = int.to_s(base)
-    end
+  def self.int_to_base(int, base = 62, check_digit: false, chars: nil)
+    base, chars = base_characters(base, chars)
+    id = encode_alphabet(int, chars)
     check_digit ? append_check_digit(id, base) : id
   end
 
@@ -322,21 +310,55 @@ module MakeId
 
   # Parses a string as a base n number and returns its decimal integer value
   def self.base_to_int(string, base = 62, check_digit: false)
-    # TODO check_digit
-    if base == 64
-      int = Base64.urlsafe_decode64(string.to_s + "==")
-    elsif base == 32 || base > 36
-      alpha = (base <= 32) ? CHARS32 : CHARS62
-      string = string.to_s
-      int = 0
-      string.each_char { |c| int = int * base + alpha.index(c) }
-    else
-      int = string.to_i(base)
+    # TODO: check_digit
+    _, chars = base_characters(base, chars)
+    decode_alphabet(string, chars)
+  end
+
+  singleton_class.alias_method :from_base, :base_to_int
+
+  def self.encode_alphabet(int, alpha = BASE62, seed: nil)
+    base = alpha.size
+    alpha = alpha.chars.shuffle(random: Random.new(seed)).join if seed
+    id = ""
+    while int > (base - 1)
+      id = alpha[int % base] + id
+      int /= base
     end
+    alpha[int] + id
+  end
+
+  def self.decode_alphabet(string, alpha = BASE32, seed: nil, base: nil)
+    base ||= alpha.size
+    alpha = alpha.chars.shuffle(random: Random.new(seed)).join if seed
+    int = 0
+    string.each_char { |c| int = int * base + alpha.index(c) }
     int
+  rescue
+    nil
   end
 
-  singleton_class.alias_method :from_base, :base_to_int
+  # Returns the refined base and characters used for the base conversions
+  def self.base_characters(base, chars = nil, shuffle_seed: nil)
+    if chars
+      base ||= chars.size
+      chars = chars[0..(base - 1)]
+    elsif base > 94 || base < 2
+      raise Error.new("Base#{base} is not supported")
+    elsif base > 64
+      chars = BASE94[0..(base - 1)]
+    elsif base > 62
+      chars = URL_BASE64[0..(base - 1)]
+    elsif base == 32
+      chars = BASE32
+    else
+      chars = BASE62[0..(base - 1)]
+    end
+    chars = chars.chars.shuffle(random: Random.new(shuffle_seed)).join if shuffle_seed
+    base = chars.size
+
+    [base, chars]
+  end
 
   ##############################################################################
   # Check Digit
@@ -352,6 +374,7 @@ module MakeId
   # Uses a pre-defined check_proc if configured. See check_proc=().
   def self.compute_check_digit(id, base = 10)
     return @@check_proc.call(id, base) if @@check_proc.is_a?(Proc)
+
     int_to_base(Zlib.crc32(id.to_s) % base, base)
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: make_id
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Allen Fair
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-13 00:00:00.000000000 Z
+date: 2024-11-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64