make_id 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30fbadcaf247ed032060da86a3634f1124cc550b6061fd8599dd63f8f07ce473
-  data.tar.gz: 1fed2e5cd4c0ace07c5457a7b0f3839ea0756d737a842f2876390121cf88374e
+  metadata.gz: 2448e655a9a006abb23272b2b54c6b4fc537f702407c931afcf106b82c468b04
+  data.tar.gz: 9852758f34e12c2be8aa90149cdded09e011f2ab879320089fc1bfb3f577d849
 SHA512:
-  metadata.gz: 234e0c71427fd3ec7f522862c42698afb475702baf6e70bf9e524d98ded74c26f9652b404e4afea82bbb0b0e2cd8daf181c505bb2a44c25ac12d5611418feb43
-  data.tar.gz: 2f682f097b4d791c956b381c9007c14a4748dc2e3e97c21f5e8a5942f54e1369c5cc361033a41aa88e65f2ce9f1fada51fac98b4f22c1684e36d3fbf6a46bc05
+  metadata.gz: 108e40b61bfdcc00ac5e550b4afb14fb8f7298df617d10b7179975b2be8f6f04c6b4693fc6909de26f42e6a9977333d12f7ecc5c5846b1317b3ab728b6e6d04d
+  data.tar.gz: 25c7229af03bc353707c2ee832f00c2ad63243318156ffa51bcd197f328a2cae865eaf37fa0949d7c8d98bcf9e583b4ec8f2fb2563317d7584b906b9f3c8cf08

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.2"
 end

data/lib/make_id.rb

@@ -73,24 +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, 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 +85,26 @@ 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
+
   ##############################################################################
   # 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 +117,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
-  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
 
   ##############################################################################
-  # TEMPORAL ID's
+  # TEMPORAL Identifiers
   ##############################################################################
 
   # Event Id - A nano_id, but timestamped event identifier: YMDHMSUUrrrrc
@@ -180,7 +167,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,7 +193,7 @@ 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
 
@@ -323,7 +310,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 +354,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]
@@ -389,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.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Allen Fair
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-11-11 00:00:00.000000000 Z
+date: 2024-11-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64