cool_id 0.1.9 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 07011e094fb16385d448b80b4461b0e579d29efc0b4273fff4b41dd1df350a64
-  data.tar.gz: 11d8a83f95a7fce11598df98d1b7175c26b00f8a0d19d6af18ebaa35b8ddfa0b
+  metadata.gz: bc42cbe218faf0128cc6e5c4f35c1b5eb2726dc0f1fcdf28cf5815593b34f5dd
+  data.tar.gz: df7b2bafa9b1981727109d9eed23041c32e010df7e6a578f90594727606d45be
 SHA512:
-  metadata.gz: f98ab9a494119599b383cc41bc9fdb797f68e793f626b07759899fee06ded282b6b8fe4f98d8ab82425127c64f4daac2511b8645f61458625e8356c8a428efe0
-  data.tar.gz: 6002ff50f083a330ad2fcdb582df9e12d9aea31d26e1d7f737dcd20650c0fa7454e2eb43a7f88c84e47bcdb5f9965557433d97acfca13b0afa854032c4de28fa
+  metadata.gz: 3d0fc47f2c3d94877fc3c79480e674b2c57a585623c0ed9d6fecb8d72cb3b3770062304055c794ccb012e34c00aef2a9bd9f7941ff8031198fd73eaaa9949a4c
+  data.tar.gz: 071f5e82664f7915b95f1be643da9dd10b89c81830d71a41d31bc302e4e156482ab38595c69ca9f0d53632987024a91a715423ec54eb2c4bbb3fc407893c98eb

data/.yardopts

@@ -0,0 +1,5 @@
+--no-private
+--markup=markdown
+--readme=README.md
+--title='cool_id api documentation'
+'lib/**/*.rb' - '*.md' LICENSE

data/README.md

@@ -1,6 +1,10 @@
 # cool id
 
-gem for rails apps to generates string ids with a prefix, followed by a [nanoid](https://zelark.github.io/nano-id-cc/). similar to the ids you see in stripe's api. also able to lookup any record by id, similar to rails' globalid.
+gem for rails apps to generate string ids with a prefix, followed by a [nanoid](https://zelark.github.io/nano-id-cc/). similar to the ids you see in stripe's api. also able to lookup any record by id, similar to rails' globalid. there's an [introductory blog post](https://schpet.com/note/cool-id) explaining why i made this.
+
+## usage
+
+### basic id generation
 
 ```ruby
 class User < ActiveRecord::Base
@@ -12,48 +16,33 @@ User.create!(name: "...").id
 # => "usr_vktd1b5v84lr"
 ```
 
-lookup any record by its id
+### locate records
 
 ```ruby
 CoolId.locate("usr_vktd1b5v84lr")
 # => #<User id: "usr_vktd1b5v84lr", name: "John Doe">
 ```
 
-and parse ids
+### generate ids
 
-```ruby
-parsed = CoolId.parse("usr_vktd1b5v84lr")
-# => #<struct CoolId::Id key="vktd1b5v84lr", prefix="usr", id="usr_vktd1b5v84lr", model_class=User>
-
-parsed.model_class
-# => User
-```
-
-and generate ids without creating a record
+e.g. for batch inserts or upserts
 
 ```ruby
-# generate an id, e.g. for batch inserts or upserts
 User.generate_cool_id
 # => "usr_vktd1b5v84lr"
 ```
 
-you can use cool_id with a separate field, keeping the default primary key:
+### parsing ids
 
 ```ruby
-class Product < ActiveRecord::Base
-  include CoolId::Model
-  cool_id prefix: "prd", id_field: :public_id
-end
-
-product = Product.create!(name: "Cool Product")
-product.id  # => 1 (or another integer)
-product.public_id  # => "prd_vktd1b5v84lr"
+parsed = CoolId.parse("usr_vktd1b5v84lr")
+# => #<struct CoolId::Id key="vktd1b5v84lr", prefix="usr", id="usr_vktd1b5v84lr", model_class=User>
 
-# You can still use CoolId.locate with the public_id
-CoolId.locate("prd_vktd1b5v84lr")  # => #<Product id: 1, public_id: "prd_vktd1b5v84lr", name: "Cool Product">
+parsed.model_class
+# => User
 ```
 
-this approach allows you to keep your primary key as an auto-incrementing integer while still benefiting from CoolId's functionality. it's particularly useful when you want to expose a public identifier that's separate from your internal primary key.
+### configuration options
 
 it takes parameters to change the alphabet or length
 
@@ -77,6 +66,27 @@ CoolId.configure do |config|
 end
 ```
 
+#### using a different id field
+
+you can use cool_id with a separate field, keeping the default primary key:
+
+```ruby
+class Product < ActiveRecord::Base
+  include CoolId::Model
+  cool_id prefix: "prd", id_field: :public_id
+end
+
+product = Product.create!(name: "Cool Product")
+product.id  # => 1 (or a uuid or whatever primary key you like)
+product.public_id  # => "prd_vktd1b5v84lr"
+
+# locate will find this
+CoolId.locate("prd_vktd1b5v84lr")  # => #<Product id: 1, public_id: "prd_vktd1b5v84lr", ...>
+```
+
+this approach allows you to avoid exposing your primary keys, read David Bryant Copeland's [Create public-facing unique keys alongside your primary keys](https://naildrivin5.com/blog/2024/08/26/create-public-facing-unique-keys-alongside-your-primary-keys.html) to learn why you might want to do this. it also allows you to adopt cool_id more easily in a project that already has some data.
+
+
 ## installation
 
 add cool_id to your Gemfile:
@@ -89,6 +99,13 @@ bundle add cool_id
 gem "cool_id"
 ```
 
+don't want to deal with a dependency? copy it into your project:
+
+```
+mkdir -p app/lib
+curl https://raw.githubusercontent.com/schpet/cool_id/main/lib/cool_id.rb -o app/lib/cool_id.rb
+```
+
 ### adding cool_id to a single model
 
 use string ids when creating a table
@@ -108,6 +125,8 @@ class User < ActiveRecord::Base
 end
 ```
 
+note: if you prefer more traditional primary keys (like bigints or uuids) you can use the `id_field` on a different column.
+
 ### using cool_id on all models
 
 you have drank the coolaid. setup rails to use string ids on all new generated migrations
@@ -134,7 +153,6 @@ end
 
 if you use the graphql ruby node interface, you can implement [object identification](https://graphql-ruby.org/schema/object_identification)
 
-
 ```ruby
 # app/graphql/app_schema.rb
 class AppSchema < GraphQL::Schema

data/lib/cool_id/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CoolId
-  VERSION = "0.1.9"
+  VERSION = "0.2.0"
 end

data/lib/cool_id.rb

@@ -1,29 +1,59 @@
 # frozen_string_literal: true
 
 require_relative "cool_id/version"
-require "nanoid"
+require "securerandom"
 require "active_support/concern"
 
+# The CoolId module provides functionality for generating and managing unique identifiers.
 module CoolId
+  # Error raised when CoolId is not configured for a model.
   class NotConfiguredError < StandardError; end
 
+  # Error raised when the maximum number of retries is exceeded while generating a unique ID.
   class MaxRetriesExceededError < StandardError; end
 
-  # defaults based on https://planetscale.com/blog/why-we-chose-nanoids-for-planetscales-api
+  # Default separator used in generated IDs.
   DEFAULT_SEPARATOR = "_"
+
+  # Default alphabet used for generating IDs.
   DEFAULT_ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyz"
+
+  # Default length of the generated ID (excluding prefix and separator).
   DEFAULT_LENGTH = 12
+
+  # Default maximum number of retries when generating a unique ID.
   DEFAULT_MAX_RETRIES = 1000
 
+  # Struct representing a parsed CoolId.
+  # @attr [String] key The unique part of the ID (excluding prefix and separator).
+  # @attr [String] prefix The prefix of the ID.
+  # @attr [String] id The full ID (prefix + separator + key).
+  # @attr [Class] model_class The ActiveRecord model class associated with this ID.
+  # @attr [Symbol] id_field The field in the model used to store the ID.
   Id = Struct.new(:key, :prefix, :id, :model_class, :id_field)
 
   class << self
+    # @!attribute [rw] separator
+    #   @return [String] The separator used in generated IDs.
+    # @!attribute [rw] alphabet
+    #   @return [String] The alphabet used for generating IDs.
+    # @!attribute [rw] length
+    #   @return [Integer] The length of the generated ID (excluding prefix and separator).
+    # @!attribute [rw] max_retries
+    #   @return [Integer] The maximum number of retries when generating a unique ID.
+    # @!attribute [rw] id_field
+    #   @return [Symbol, nil] The default field to use for storing the ID in models.
     attr_accessor :separator, :alphabet, :length, :max_retries, :id_field
 
+    # Configures the CoolId module.
+    # @yield [self] Gives itself to the block.
+    # @return [void]
     def configure
       yield self
     end
 
+    # Resets the configuration to default values.
+    # @return [void]
     def reset_configuration
       self.separator = DEFAULT_SEPARATOR
       self.alphabet = DEFAULT_ALPHABET
@@ -32,10 +62,15 @@ module CoolId
       self.id_field = nil
     end
 
+    # @return [Registry] The default registry that keeps track of which prefixes are associated with which model classes.
     def registry
       @prefix_map ||= Registry.new
     end
 
+    # Generates a unique ID based on the given configuration.
+    # @param config [Config] The configuration for ID generation.
+    # @return [String] A unique ID.
+    # @raise [MaxRetriesExceededError] If unable to generate a unique ID within the maximum number of retries.
     def generate_id(config)
       alphabet = config.alphabet || @alphabet
       length = config.length || @length
@@ -43,7 +78,7 @@ module CoolId
 
       retries = 0
       loop do
-        nano_id = Nanoid.generate(size: length, alphabet: alphabet)
+        nano_id = SecureRandom.alphanumeric(length, chars: alphabet.chars)
         full_id = "#{config.prefix}#{separator}#{nano_id}"
         if !config.model_class.exists?(id: full_id)
           return full_id
@@ -56,6 +91,9 @@ module CoolId
       end
     end
 
+    # Resolves the field (column) to use for storing the CoolId in a model.
+    # @param model_class [Class] The ActiveRecord model class.
+    # @return [Symbol] The field to use for storing the CoolId.
     def resolve_cool_id_field(model_class)
       model_class.cool_id_config&.id_field || CoolId.id_field || model_class.primary_key
     end
@@ -66,15 +104,23 @@ module CoolId
   self.length = DEFAULT_LENGTH
   self.max_retries = DEFAULT_MAX_RETRIES
 
+  # Registry for managing prefixes and model classes.
   class Registry
     def initialize
       @prefix_map = {}
     end
 
+    # Registers a prefix with a model class.
+    # @param prefix [String] The prefix to register.
+    # @param model_class [Class] The ActiveRecord model class to associate with the prefix.
+    # @return [void]
     def register(prefix, model_class)
       @prefix_map[prefix] = model_class
     end
 
+    # Locates a record by its CoolId.
+    # @param id [String] The CoolId to look up.
+    # @return [ActiveRecord::Base, nil] The found record, or nil if not found.
     def locate(id)
       parsed = parse(id)
       return nil unless parsed
@@ -83,6 +129,9 @@ module CoolId
       parsed.model_class.find_by(id_field => id)
     end
 
+    # Parses a CoolId into its components.
+    # @param id [String] The CoolId to parse.
+    # @return [Id, nil] The parsed Id object, or nil if parsing fails.
     def parse(id)
       prefix, key = id.split(CoolId.separator, 2)
       model_class = @prefix_map[prefix]
@@ -92,12 +141,36 @@ module CoolId
     end
   end
 
+  # Configuration class for CoolId generation.
   class Config
-    attr_reader :prefix, :length, :alphabet, :max_retries, :model_class, :id_field
+    # @return [String] The prefix for generated IDs.
+    attr_reader :prefix
+
+    # @return [Integer, nil] The length of the generated ID (excluding prefix and separator).
+    attr_reader :length
+
+    # @return [String, nil] The alphabet to use for generating IDs.
+    attr_reader :alphabet
 
+    # @return [Integer, nil] The maximum number of retries when generating a unique ID.
+    attr_reader :max_retries
+
+    # @return [Class] The ActiveRecord model class associated with this configuration.
+    attr_reader :model_class
+
+    # @return [Symbol, nil] The field to use for storing the ID in the model.
+    attr_reader :id_field
+
+    # Initializes a new Config instance.
+    # @param prefix [String] The prefix for generated IDs.
+    # @param model_class [Class] The ActiveRecord model class.
+    # @param length [Integer, nil] The length of the generated ID (excluding prefix and separator).
+    # @param alphabet [String, nil] The alphabet to use for generating IDs.
+    # @param max_retries [Integer, nil] The maximum number of retries when generating a unique ID.
+    # @param id_field [Symbol, nil] The field to use for storing the ID in the model.
     def initialize(prefix:, model_class:, length: nil, alphabet: nil, max_retries: nil, id_field: nil)
-      @length = length
       @prefix = validate_prefix(prefix)
+      @length = length
       @alphabet = validate_alphabet(alphabet)
       @max_retries = max_retries
       @model_class = model_class
@@ -106,12 +179,20 @@ module CoolId
 
     private
 
+    # Validates the prefix.
+    # @param value [String] The prefix to validate.
+    # @return [String] The validated prefix.
+    # @raise [ArgumentError] If the prefix is nil or empty.
     def validate_prefix(value)
       raise ArgumentError, "Prefix cannot be nil" if value.nil?
       raise ArgumentError, "Prefix cannot be empty" if value.empty?
       value
     end
 
+    # Validates the alphabet.
+    # @param value [String, nil] The alphabet to validate.
+    # @return [String, nil] The validated alphabet.
+    # @raise [ArgumentError] If the alphabet includes the separator.
     def validate_alphabet(value)
       return nil if value.nil?
       raise ArgumentError, "Alphabet cannot include the separator '#{CoolId.separator}'" if value.include?(CoolId.separator)
@@ -119,30 +200,52 @@ module CoolId
     end
   end
 
+  # Module to be included in ActiveRecord models for CoolId functionality.
   module Model
     extend ActiveSupport::Concern
 
     class_methods do
+      # @!attribute [rw] cool_id_config
+      #   @return [Config] The CoolId configuration for this model.
+      # @!attribute [rw] cool_id_setup_required
+      #   @return [Boolean] Whether CoolId setup is required for this model.
       attr_accessor :cool_id_config
       attr_accessor :cool_id_setup_required
 
+      # Configures CoolId for this model.
+      # @param options [Hash] Options for configuring CoolId.
+      # @option options [String] :prefix The prefix for generated IDs.
+      # @option options [Integer] :length The length of the generated ID (excluding prefix and separator).
+      # @option options [String] :alphabet The alphabet to use for generating IDs.
+      # @option options [Integer] :max_retries The maximum number of retries when generating a unique ID.
+      # @option options [Symbol] :id_field The field to use for storing the ID in the model.
+      # @return [void]
       def cool_id(options)
         @cool_id_config = Config.new(**options, model_class: self)
         CoolId.registry.register(options[:prefix], self)
       end
 
+      # Generates a new CoolId for this model.
+      # @return [String] A new CoolId.
       def generate_cool_id
         CoolId.generate_id(@cool_id_config)
       end
 
+      # Enforces CoolId setup for all descendants of this model.
+      # @return [void]
       def enforce_cool_id_for_descendants
         @cool_id_setup_required = true
       end
 
+      # Skips enforcing CoolId setup for this model.
+      # @return [void]
       def skip_enforce_cool_id
         @cool_id_setup_required = false
       end
 
+      # Inherits CoolId setup requirements to subclasses.
+      # @param subclass [Class] The subclass inheriting from this model.
+      # @return [void]
       def inherited(subclass)
         super
         if @cool_id_setup_required && !subclass.instance_variable_defined?(:@cool_id_setup_required)
@@ -157,11 +260,16 @@ module CoolId
 
       private
 
+      # Sets the CoolId for the model instance before creation.
+      # @return [void]
       def set_cool_id
         id_field = CoolId.resolve_cool_id_field(self.class)
         self[id_field] = self.class.generate_cool_id if self[id_field].blank?
       end
 
+      # Ensures that CoolId is configured for the model.
+      # @raise [NotConfiguredError] If CoolId is not configured and setup is required.
+      # @return [void]
       def ensure_cool_id_configured
         if self.class.cool_id_setup_required && self.class.cool_id_config.nil?
           suggested_prefix = self.class.name.downcase[0..2]
@@ -171,10 +279,16 @@ module CoolId
     end
   end
 
+  # Locates a record by its CoolId.
+  # @param id [String] The CoolId to look up.
+  # @return [ActiveRecord::Base, nil] The found record, or nil if not found.
   def self.locate(id)
     registry.locate(id)
   end
 
+  # Parses a CoolId into its components.
+  # @param id [String] The CoolId to parse.
+  # @return [Id, nil] The parsed Id object, or nil if parsing fails.
   def self.parse(id)
     registry.parse(id)
   end

metadata

@@ -1,31 +1,31 @@
 --- !ruby/object:Gem::Specification
 name: cool_id
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: 0.2.0
 platform: ruby
 authors:
 - Peter Schilling
 autorequire:
-bindir: exe
+bindir: bin
 cert_chain: []
-date: 2024-08-26 00:00:00.000000000 Z
+date: 2025-01-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: nanoid
+  name: activerecord
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '6.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '6.0'
 - !ruby/object:Gem::Dependency
-  name: activerecord
+  name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -39,19 +39,75 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '6.0'
 - !ruby/object:Gem::Dependency
-  name: activesupport
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.28
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.28
+- !ruby/object:Gem::Dependency
+  name: webrick
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
-  type: :runtime
+        version: '0'
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
@@ -66,30 +122,27 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.4'
-description: generates primary keys using prefixed nanoids for ActiveRecord models
+description: CoolId generates primary keys using prefixed nanoids for ActiveRecord
+  models, providing unique and readable identifiers.
 email:
 - git@schpet.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".aider.conf.yml"
-- ".rspec"
-- ".standard.yml"
+- ".yardopts"
 - CHANGELOG.md
 - LICENSE
 - README.md
-- Rakefile
 - lib/cool_id.rb
 - lib/cool_id/version.rb
-- sig/cool_id.rbs
 homepage: https://github.com/schpet/cool_id
 licenses:
 - ISC
 metadata:
   homepage_uri: https://github.com/schpet/cool_id
   source_code_uri: https://github.com/schpet/cool_id
-  changelog_uri: https://github.com/schpet/cool_id/tree/main/CHANGELOG.md
+  changelog_uri: https://github.com/schpet/cool_id/blob/main/CHANGELOG.md
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -98,15 +151,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: generates cool ids
+summary: Generates cool ids for ActiveRecord models
 test_files: []

data/.aider.conf.yml

@@ -1,9 +0,0 @@
-# https://aider.chat/docs/config/aider_conf.html
-
-lint-cmd: bundle exec standardrb --fix
-auto-lint: true
-
-test-cmd: bundle exec rspec --format progress --no-profile --no-color --fail-fast
-auto-test: true
-
-read: cool_id.gemspec

data/.rspec

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

data/.standard.yml

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

data/Rakefile

@@ -1,10 +0,0 @@
-# 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]

data/sig/cool_id.rbs

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