make_id 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30fbadcaf247ed032060da86a3634f1124cc550b6061fd8599dd63f8f07ce473
-  data.tar.gz: 1fed2e5cd4c0ace07c5457a7b0f3839ea0756d737a842f2876390121cf88374e
+  metadata.gz: 7f93b4ee4fa18932ab4bc7769214bee5a4297555d776ab4b38a31a56e3c98fe6
+  data.tar.gz: ea62bc4fa6bab34e649d9c3983146b55c81dbe469d16142c9847c00c8c291f49
 SHA512:
-  metadata.gz: 234e0c71427fd3ec7f522862c42698afb475702baf6e70bf9e524d98ded74c26f9652b404e4afea82bbb0b0e2cd8daf181c505bb2a44c25ac12d5611418feb43
-  data.tar.gz: 2f682f097b4d791c956b381c9007c14a4748dc2e3e97c21f5e8a5942f54e1369c5cc361033a41aa88e65f2ce9f1fada51fac98b4f22c1684e36d3fbf6a46bc05
+  metadata.gz: 183ea9a2f7e14c6a70d5f0addec62718ce467face83be99128163df22eae71cb5a6cdb813fe413cac2bb0daa80e1bda17267400995455fa11b916ba37bb20662
+  data.tar.gz: c2001d8acbc1427e88007146a05a32bbf47e725cce418ac42fd6242d94a23757819afefbaca268558943881012ba3ddcf5b133bc580b2fea44b6f4af092041bd

data/README.md

@@ -61,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
 
@@ -76,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
@@ -96,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:
 
@@ -137,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.1"
+  VERSION = "0.1.3"
 end

data/lib/make_id.rb

@@ -3,6 +3,7 @@
 require_relative "make_id/version"
 require "securerandom"
 require "zlib"
+require "digest"
 
 # MakeID generates record Identifiers other than sequential integers.
 # MakeId  - From the "make_id" gem found at https://github.com/afair/make_id
@@ -73,24 +74,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, chars: nil)
-    _, chars = base_characters(base, chars)
-    SecureRandom.alphanumeric(size, chars: chars.chars)
-  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
@@ -98,17 +86,41 @@ module MakeId
     id
   end
 
-  def self.random_id_password(bytes: 8, base: 10, absolute: true, alpha: nil)
-    id = random_id(bytes: bytes)
-    pass = random_id(bytes: 16)
+  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
+
+  # Takes a string and returns an 8-byte integer for the string.
+  # This implementation uses the SHA256 hash of the string to generate the ID.
+  # You can also have random bits added to the ID to make it unique.
+  # This is not a unique ID, but a repeatable ID for the same string
+  # (unless random_bits is used), and can be used like a hashing value.
+  def self.string_id(string, random_bits: 0, base: 10, bytes: 8)
+    id = Digest::SHA256.hexdigest(string)[0, bytes * 2].to_i(16)
+    if random_bits > 0
+      id >> random_bits
+      id << random_bits
+      id |= SecureRandom.random_number(2**random_bits - 1)
+    end
+    (base == 10) ? id : int_to_base(id, base)
+  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
@@ -121,49 +133,40 @@ 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) ? BASE32 : BASE62
-    size -= 1 if check_digit
-    id = random(size, base: base)
-    check_digit ? append_check_digit(id, base) : id
+  # 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
+
+  # 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
 
   # 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)
-  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
-  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
+  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
 
   ##############################################################################
-  # TEMPORAL ID's
+  # TEMPORAL Identifiers
   ##############################################################################
 
   # Event Id - A nano_id, but timestamped event identifier: YMDHMSUUrrrrc
@@ -180,7 +183,7 @@ module MakeId
       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
@@ -206,10 +209,40 @@ module MakeId
       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
 
+  # Returns an id using the current epoch time with floating precision and random bits.
+  # Be default, this returns an 8-byte integer in ascending order within precision.
+  # Format is approximately "SSSSSSSSSMMMRRR" (seconds, milliseconds, random).
+  # * precision (1..5) The number of milliseconds decimeal places to use. Default is 4.
+  # * random_bits (1..) The number of bits to use for the random number. Default is 18.
+  # * time - Time object to use for the token. Default is Time.now
+  # * base - The base to use for the id. Default is 10
+  # * chars - The character set to use for the base conversion. Default is BASE62
+  def self.time_id(base: 10, precision: 4, random_bits: 18, time: nil, chars: nil)
+    seconds = ((time || Time.now).to_f * (10**precision)).to_i
+    id = (seconds * (2**random_bits)) | SecureRandom.random_number(2**random_bits - 1)
+    (base == 10) ? id : int_to_base(id, base, chars: chars)
+  end
+
+  # Returns a string from the time with floating precision, and a random number appended.
+  # This calls time_id() and returns a token of the given size.
+  # If size is zero, the full token is returned. If size is greater than the token,
+  # the token is right-justified with zeros. If the token is larger than size, the
+  # right-most characters are returned.
+  def self.time_token(size: 0, base: 62, chars: nil, time: nil, precision: 3, random_bits: 8)
+    token = time_id(base: base, precision: precision, random_bits: random_bits, time: time, chars: chars)
+    if size == 0
+      token
+    elsif token.size < size
+      token.rjust(size, "0")
+    else
+      token[-size, size]
+    end
+  end
+
   ##############################################################################
   # Snowflake Id - Epoch + millisecond + worker_id id + sequence number
   # Snowflakes are a form of unique identifier used in distributed computing.
@@ -323,7 +356,7 @@ 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
+    # TODO: check_digit
     _, chars = base_characters(base, chars)
     decode_alphabet(string, chars)
   end
@@ -367,9 +400,7 @@ module MakeId
     else
       chars = BASE62[0..(base - 1)]
     end
-    if shuffle_seed
-      chars = chars.chars.shuffle(random: Random.new(shuffle_seed)).join
-    end
+    chars = chars.chars.shuffle(random: Random.new(shuffle_seed)).join if shuffle_seed
     base = chars.size
 
     [base, chars]
@@ -385,10 +416,17 @@ module MakeId
     id.to_s + compute_check_digit(id, base)
   end
 
+  # Removes and validates the check digit. Retuns nil if the check digit is invalid.
+  def self.remove_check_digit(id, base = 10)
+    id, cd = id.to_s[0..-2], id.to_s[-1]
+    valid_check_digit?(id + cd, base) ? id : nil
+  end
+
   # Returns a character computed using the CRC32 algorithm
   # 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,13 @@
 --- !ruby/object:Gem::Specification
 name: make_id
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - Allen Fair
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-11-11 00:00:00.000000000 Z
+date: 2025-03-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -24,6 +23,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: irb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: MakeId is a collection of record Identifier generators
 email:
 - allen.fair@gmail.com
@@ -49,7 +62,6 @@ licenses:
 metadata:
   homepage_uri: https://github.com/afair/make_id
   source_code_uri: https://github.com/afair/make_id
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -64,8 +76,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.20
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: MakeId provides a collection of record Identifier generators
 test_files: []