make_id 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 90cbe0cbac923318d4badd6c848042404633a27c6fbecdd7e2509aee6c31ab5c
+  data.tar.gz: 41f946d9367bb73257ac31ffce792bd309f2e707c44b39003d66dcc3d1890a49
+SHA512:
+  metadata.gz: da8822e1194eb4ed1e51f1090f120db17cdd421fc330f84dbe4b4556c1dd71eac4dc33dff678768999cee03ad21749a9f3bbb5a2949ced4f83c7f7afd802128a
+  data.tar.gz: '038ae0b3bc50252cd75eec5fb7283feb27381e3362bd2681fbba6ff225865727ef4fa560f84d24e8c4703f5ba96ce168c9278462b9469b97323ab981869e387d'

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.standard.yml

@@ -0,0 +1,3 @@
+# For available configuration options, see:
+#   https://github.com/standardrb/standard
+ruby_version: 3.0

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Allen Fair
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Allen Fair
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,167 @@
+# MakeId
+
+MakeID is a ruby library containing data record identifier generators. Perhaps it is a library of _identifier patterns_?
+Let me know (by pull request) if you have any useful standard (or should be) id types.
+
+Most databases use a sequential, auto-incrementing number as the primary key. For example, in PostgreSQL this is implemented using sequences.
+
+Not every data "id" wants to use sequential numbers. These can be easy to guess and allow inpection of random records by altering the URL.
+
+## Installation
+
+This is a gem, and is installed as such:
+
+    gem install make_id
+
+or by placing in your Gemfile, or running this bundler command:
+
+    bundle add make_id
+
+Alternatively, you can skip the dependency and "adopt" the primary file within this repo, `lib/make_id.rb`,
+keeping the attribution comments to find upstream documentation, fixes, and new features.
+
+Another good alternative to using sequential id's is an alternate or external id used for URL's. This external
+id can be generated id of any of these schemes, along with a unique index on the column. This gives you the ease
+of a standard sequential id, with the security of a randomly-generated identifier.
+
+When storing a string key in the database, look at using fixed-size columns instead of "characer varying" strings
+as these have an additional cost of storing the length (PostgreSQL uses 4 bytes). Also, consider index performance
+as these id's will likely require a unique index.
+
+## Usage
+
+Sequential Id's are great, and perform well in most cases. Here are a few alternatives to find here.
+
+### Base conversions and Check Digits
+
+Larger numbers can be represented more compactly with a larger base or radix. MakeId has utilities to
+convert to and from its supported bases. You can leverage these for URL Id's to avoid long or simple
+numeric codes.
+
+Bases supported are:
+
+- Base62: digits, upper, and lower-case letters. No special characters
+- 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.
+
+    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
+
+MakeId can return a random (8-byte by default) integer. You can request it returned in a supported base,
+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"
+
+### UUID
+
+UUID are 16-byte numbers, usually represented in hexadecimal of the format `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`.
+There are different schemes for UUID types, and each has it's use. Most record Id's use a randomly generated UUID,
+which if very unlikely (but possible) to have collitions with existing keys. The `uuid_to_base` helper method
+can be used to transform a long UUID into a possibly more palettable base representation.
+
+    u = MakeId.uuid #=> "1601125f-ee7c-4c0b-b693-dd2265edbcfc"
+    MakeId.uuid_to_base(u, 10) #=> 29248580887982686871727313613986053372 (38 characters)
+    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
+
+### Nano Id
+
+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.
+
+    MakeId.nano_id(size: 16) #=> "iZnLn96FVcjivEJA"
+    MakeId.nano_id(size: 16, base: 32) #=> "sf8kqb8ekn7k98rq"
+
+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
+can be used as well, is easier to read, sortable within a day, and unique enough to work with.
+
+    id = MakeId.request_id #=> "494f1272t01000c4"
+    #-------------------------->YMDHsssuuqqwwrrr
+    id[3,8]                #=> "f1272t01"
+    #-------------------------->Hsssuuqq
+
+### Snowflake Id
+
+Snowflakes 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:
+
+- "Application Epoch" milliseconds (number of seconds since the designated start). positive sign and 41 bits.
+- "Worker Id", a number from 0..1023 (10 bits) used to designate the datacenter, server, and/or process generating the id.
+- "Sequence Id", a number from 0..4095 (12 bits) of messages within the given millisecond, or a random number within.
+
+The application epoch is the start time before data was generated. This is set by passing a year integer or Time object.
+The default is 2020 for the library. Because there are only 41 bits for the `time * 1000` (milliseconds),
+higher order bits are removed. Therefore, limit the size of your epoch to a later date to keep the id's sortable as well as readable.
+
+    MakeId.epoch = 2020 # or Time.utc(2020)
+    MakeId.snowflake_id => 618906575771271168
+    #--------------------->eeeeeeeeeeuuussrrr (Bit breakdown for understanding, not to scale)
+
+The `worker_id` defaults to 0 and can be set with the APP_WORKER_ID environment variable or call
+to a setter at the startup of the application. Set with a number appropriate for your environment.
+
+You can also pass in options to return it as a different base, and with a check digit.
+
+    MakeId.app_worker_id = 234
+    MakeId.snowflake_id => 618905333721374720
+    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.
+
+    MakeId.snowflake_uuid # w> "66d735c6-0be2-6517-da69-57d440987c18"
+    u = MakeId.snowflake_uuid #=> "66d735e6-7ac4-8bfc-5af0-39b4e2c96b05"
+    #------------------------->eeeeeeee-uuuw-wwrr-rrrr-rrrrrrrrrrrr
+
+Want a ISO-like readable timestamp in your UUID? The `snowflake_datetime_uuid` method combines elements of the
+snowflake id (below) and the human-readable ISO timestamp in the UUID. Also includes milliseconds,
+the "worker id" for the snowflake id, and a randomized 12-byte field. This could be useful for time-series
+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.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/afair/make_id. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/afair/make_id/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the MakeId project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/afair/make_id/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "standard/rake"
+
+task default: %i[spec standard]
+
+desc "Open and IRB Console with the gem loaded"
+task :console do
+  sh "bundle exec irb  -Ilib -I . -r make_id"
+end

data/bin/make-id

@@ -0,0 +1,50 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage: make-id
+# Description: Prints a unique id. Useful for batch scripting?
+require 'rubygems'
+require 'make_id'
+# In development mode, do: bundle exec bin/make-id
+
+# For now, print set of Id's
+
+# UUID: Print random UUID, UUID converted to base 10, UUID converted to base 32, UUID converted to base 62
+id = MakeId.uuid
+int = MakeId.uuid_to_base(id)
+puts "UUID:   \t#{id}\t#{int}\t#{MakeId.int_to_base(int,32)}\t#{MakeId.int_to_base(int,62)}"
+
+# DateTimeUUId: Print DateTime UUID, DateTime UUID converted to base 10, DateTime UUID converted to base 32, DateTime UUID converted to base 62
+id = MakeId.datetime_uuid
+int = MakeId.uuid_to_base(id)
+puts "DateTimeUUId:\t#{id}\t#{int}\t#{MakeId.int_to_base(int,32)}\t#{MakeId.int_to_base(int,62)}"
+
+# EpochUUID: Print DateTime UUID, DateTime UUID converted to base 10, DateTime UUID converted to base 32, DateTime UUID converted to base 62
+id = MakeId.epoch_uuid
+int = MakeId.uuid_to_base(id)
+puts "EpochUUID:\t#{id}\t#{int}\t#{MakeId.int_to_base(int,32)}\t#{MakeId.int_to_base(int,62)}"
+id = MakeId.epoch_uuid(application_epoch: true)
+int = MakeId.uuid_to_base(id)
+puts "AppEpochUUID:\t#{id}\t#{int}\t#{MakeId.int_to_base(int,32)}\t#{MakeId.int_to_base(int,62)}"
+
+# RandomId: Print random Id, Random Id converted to base 10, Random Id converted to base 32, Random Id converted to base 62
+id = MakeId.random_id
+puts "RandomId:\t#{id}\t#{MakeId.int_to_base(id,32)}\t#{MakeId.int_to_base(id,62)}"
+
+# SnowflakeId: Print Snowflake Id, Snowflake Id converted to base 10, Snowflake Id converted to base 32, Snowflake Id converted to base 62
+id = MakeId.snowflake_id
+puts "SnowflakeId:\t#{id}\t#{MakeId.int_to_base(id,32)}\t#{MakeId.int_to_base(id,62)}"
+
+# NanoId: Print Nano Id
+id = MakeId.nano_id
+int = MakeId.base_to_int(id, 62)
+puts "NanoId:  \t#{id}\t#{MakeId.int_to_base(int,32)}\t#{int}"
+
+# EventId: Print Event Id
+id = MakeId.event_id
+int = MakeId.base_to_int(id, 62)
+puts "EventId:\t#{id}\t\t#{MakeId.int_to_base(int,32)}\t#{int}"
+
+# RequesetId: Print it
+id = MakeId.request_id
+puts "RequestId:\t#{id}\t\t#{id[3,8]}"

data/lib/make_id/version.rb

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

data/lib/make_id.rb

@@ -0,0 +1,362 @@
+# frozen_string_literal: true
+
+require_relative "make_id/version"
+require "securerandom"
+require "base64"
+require "zlib"
+
+# MakeID generates record Identifiers other than sequential integers.
+# MakeId  - From the "make_id" gem found at https://github.com/afair/make_id
+# License - MIT, see the LICENSE file in the gem's source code.
+# 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
+
+  CHARS32 = "0123456789abcdefghjkmnpqrstvwxyz" # Avoiding ambiguous 0/o i/l/I
+  CHARS62 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+  EPOCH_TWITTER = Time.utc(2006, 3, 21, 20, 50, 14)
+
+  @@app_worker_id = ENV.fetch("APP_WORKER_ID", 0)
+  @@epoch = Time.utc(2020)
+  @@counter_time = 0
+  @@counter = 0
+  @@check_proc = nil
+
+  # Set your default snowflake default id. This is a 10-bit number (0..1023)
+  # that designates your: datacenter, machine, and/or process that generated it.
+  # This can be overridden by setting the environment variable APP_WORKER_ID
+  # or by the caller.
+  # Usage (configuration): MakeId.app_worker_id = 123
+  def self.app_worker_id=(id)
+    @@app_worker_id = id.to_i & 0x3ff
+  end
+
+  # Returns the current worker id
+  def self.app_worker_id
+    @@app_worker_id
+  end
+
+  # Set a custom check digit proc that takes the id string and base as argumentsA
+  # and returns a character to append to the end of the id.
+  def self.check_proc=(proc)
+    @@check_proc = proc
+  end
+
+  # Sets the start year for snowflake epoch
+  def self.epoch=(arg)
+    @@epoch = arg.is_a?(Time) ? arg : Time.utc(arg)
+  end
+
+  def self.epoch
+    @@epoch
+  end
+
+  def self.application_epoch
+    Time.now.to_i - @@epoch.to_i
+  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
+  ##############################################################################
+
+  # Random Integer ID
+  def self.random_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
+    id = append_check_digit(id, base) if check_digit
+    id
+  end
+
+  ##############################################################################
+  # UUID - Universally Unique Identifier
+  ##############################################################################
+
+  # Returns a (securely) random generated UUID v4
+  def self.uuid
+    SecureRandom.uuid
+  end
+
+  # Accepts a hext UUID string and returns the integer value in the given base.
+  # If base is specified, it will convert to that base using MakeId utilities.
+  def self.uuid_to_base(uuid, base = 10)
+    int = uuid.delete("-").to_i(16)
+    (base == 10) ? int : int_to_base(int, base)
+  end
+
+  ##############################################################################
+  # Nano Id - Simple, secure URL-friendly unique string ID generator
+  ##############################################################################
+
+  # 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)
+  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
+  end
+
+  ##############################################################################
+  # Event Id - A nano_id, but timestamped event identifier: YMDHMSUUrrrrc
+  ##############################################################################
+
+  # Returns an event timestamp of the form 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],
+      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
+    id = check_digit ? append_check_digit(parts.join, 62) : parts.join
+    id[0, size]
+  end
+
+  # Returns a 16-character request id string in Base32 of format: YMDHsssuuqqwwrrr
+  # Use substring [3, 8] (Hsssuuqq) for a short 8-character version, easier for human scanning.
+  def self.request_id(time: nil, sequence_method: :counter)
+    time ||= Time.new
+    seconds = time.to_i - Time.new(time.year, time.month, time.day, time.hour).to_i # time.utc.hour??
+
+    sequence = if sequence_method == :counter
+      next_millisecond_sequence(((Time.now.utc.to_f - @@epoch.to_i) * 1000).to_i)
+    elsif sequence_method == :random
+      SecureRandom.random_number(4095)
+    end
+
+    [
+      CHARS62[time.year % @@epoch.year],
+      CHARS62[time.month],
+      CHARS62[time.day], # "-",
+      CHARS62[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)
+    ].join
+  end
+
+  ##############################################################################
+  # Snowflake Id - Epoch + millisecond + worker_id id + sequence number
+  # Snowflakes are a form of unique identifier used in distributed computing.
+  # Uses an epoch time with miliseconds (41 bits), a worker_id id of where it was
+  # created (datacenter, machine, process, 10 bits), and a sequence number (12 bits).
+  ##############################################################################
+
+  # Returns an 8-byte integer snowflake id that can be reverse parsed.
+  # sequence_counter can be :counter for a rotating integer, or :random
+  def self.snowflake_id(worker_id: nil, base: 10, sequence_method: :counter)
+    milliseconds = ((Time.now.utc.to_f - @@epoch.to_i) * 1000).to_i
+    worker_id ||= app_worker_id
+    sequence = 0
+    if sequence_method == :counter
+      sequence = next_millisecond_sequence(milliseconds)
+    elsif sequence_method == :random
+      sequence = SecureRandom.random_number(4095)
+    end
+
+    id = combine_snowflake_parts(milliseconds, worker_id, sequence)
+    (base == 10) ? id : int_to_base(id, base)
+  end
+
+  # Returns uuid with Unix epoch time sort in format: ssssssss-uuuw-wwrr-rrrr-rrrrrrrrrrrr
+  # Specify `application_epoch: true` to use instead of Unix epoch
+  def self.snowflake_uuid(time: nil, format: true, worker_id: nil, application_epoch: false)
+    time ||= Time.new
+    seconds = time.to_i
+    seconds -= @@epoch.to_i if application_epoch
+    worker_id ||= app_worker_id
+    parts = [
+      seconds.to_s(16).rjust(8, "0"),
+      (time.subsec.to_f * 1000).to_i.to_s(16).rjust(3, "0"),
+      (worker_id % 1024).to_s(16).rjust(3, "0"),
+      SecureRandom.hex(9)
+    ]
+    id = append_check_digit(parts.join, 16).downcase
+    format ? "#{id[0..7]}-#{id[8..11]}-#{id[12..15]}-#{id[16..19]}-#{id[20..31]}" : id
+  end
+
+  # Returns UUID with columnar date parts: yyyymmdd-hhmm-ssuu-uwww-rrrrrrrrrrrr
+  def self.snowflake_datetime_uuid(time: nil, format: true, worker_id: nil, utc: true)
+    time ||= Time.new
+    time = time.utc if utc
+    worker_id ||= app_worker_id
+    id = [
+      time.year,
+      time.month.to_s.rjust(2, "0"),
+      time.day.to_s.rjust(2, "0"),
+      time.hour.to_s.rjust(2, "0"),
+      time.min.to_s.rjust(2, "0"),
+      time.sec.to_s.rjust(2, "0"),
+      (time.subsec.to_f * 1000).to_i.to_s(16).rjust(3, "0"),
+      (worker_id % 1024).to_s(16).rjust(3, "0"),
+      SecureRandom.hex(6)
+    ].join
+    format ? "#{id[0..7]}-#{id[8..11]}-#{id[12..15]}-#{id[16..19]}-#{id[20..31]}" : id
+  end
+
+  # Creates the final snowflake by bit-mapping the constituent parts into the whole
+  def self.combine_snowflake_parts(milliseconds, worker_id, sequence)
+    id = milliseconds & 0x1ffffffffff # 0 (sign) + lower 41bits
+    id <<= 10
+    id |= worker_id & 0x3ff # 10bits (0..1023)
+    id <<= 12
+    id |= (sequence & 0xfff) # 12 bits (0..4095)
+
+    id
+  end
+
+  def self.next_millisecond_sequence(milliseconds)
+    sequence = 0
+    semaphore = Mutex.new
+
+    semaphore.synchronize do
+      if @@counter_time != milliseconds
+        @@counter_time = milliseconds
+        @@counter = 0
+      end
+      sequence = @@counter % 4095
+      @@counter += 1
+    end
+
+    sequence
+  end
+
+  # Build an integer value from pairs of [bits, value]
+  def self.pack_int_parts(*pairs)
+    int = 0
+    pairs.each do |bits, value|
+      int = (int << bits) | (value & ((1 << bits) - 1))
+    end
+    int
+  end
+
+  ##############################################################################
+  # Base Conversions
+  ##############################################################################
+
+  # Takes an integer and a base (from 2 to 62) and converts the number.
+  # 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
+    check_digit ? append_check_digit(id, base) : id
+  end
+
+  singleton_class.alias_method :to_base, :int_to_base
+
+  # 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)
+    end
+    int
+  end
+
+  singleton_class.alias_method :from_base, :base_to_int
+
+  ##############################################################################
+  # Check Digit
+  ##############################################################################
+
+  # Adds a check digit to the end of an id string. This check digit is derived
+  # from the CRC-32 (Cyclical Redundancy Check) value of the id string
+  def self.append_check_digit(id, base = 10)
+    id.to_s + compute_check_digit(id, base)
+  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
+
+  # Takes an id with a check digit and return true if the check digit matches
+  def self.valid_check_digit?(id, base = 10)
+    id == append_check_digit(id[0..-2], base)
+  end
+end

data/sig/make_id.rbs

@@ -0,0 +1,4 @@
+module MakeId
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: make_id
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Allen Fair
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-10-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  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
+executables:
+- make-id
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".standard.yml"
+- CODE_OF_CONDUCT.md
+- LICENSE
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/make-id
+- lib/make_id.rb
+- lib/make_id/version.rb
+- sig/make_id.rbs
+homepage: https://github.com/afair/make_id
+licenses:
+- MIT
+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
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.20
+signing_key:
+specification_version: 4
+summary: MakeId provides a collection of record Identifier generators
+test_files: []