exid 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 064c2fa33e682ce0cc265bfc7504b5880468084b27d0a494b00de81fd49d24d2
-  data.tar.gz: 4f1d3c6f0a3dec4cdfab9a944b8914893cecb4440f4c6402d10adc56066a4c94
+  metadata.gz: e84938938a68a64371ab17add16229d3cd21a2f225d9205dd34c68a496ec54c7
+  data.tar.gz: d0e45c03c17b898eb30b0406075bf239091883a996a7285c138c9ff764ce2a49
 SHA512:
-  metadata.gz: 93cf7e89ba36affd92b44427d3c502a24ec746551a393e4ec20854810db697cbf5856a6aa7c372df9dee6bc4fda6650eb22f1e70849b2dd450b788483860b6b1
-  data.tar.gz: d70ea9392154d335c8e1cb241e07ea1d71162141264fcd5e99c0063a7a404fb70a849d512c0576d965325f9aff58732b01ac6f20ca2de626bdf25a9fa16be0c5
+  metadata.gz: 6af718bfd3c92b368bd0ff6ae85ff58b20436d449dd9db007e0a62e151f190facd21bdf4e8331b62d09f8301a76a7f36b31e22c0c017553bc16506549cd097ab
+  data.tar.gz: 97daf7c43e837b8c0f78ee5106c3f26f67a0eca0c8e35d6f1fe745069e84a9dcd16d65f195954a8cbc77b9808709e3150e906abe88f68a0eecc9c278562d016c

data/.ruby-version

@@ -0,0 +1 @@
+3.4.4

data/.standard.yml

@@ -0,0 +1,2 @@
+---
+ruby_version: 3.2

data/Dockerfile

@@ -0,0 +1,3 @@
+FROM node:20-bookworm AS node-base
+WORKDIR /app
+RUN npm install -g @anthropic-ai/claude-code

data/README.md

@@ -1,84 +1,129 @@
-# Exid
+# Exid ![CI](https://github.com/marzdrel/exid/actions/workflows/ci.yml/badge.svg)
 
-**!! Warning: Documentation is not complete yet. Work in progress**
+A Ruby gem for implementing human-friendly, prefixed identifiers for records using Base62-encoded UUIDs.
 
-This gem implements helper methods for implementing External, Prefixed
-identifiers for records.
+## Overview
 
-Core `Exid::Coder.encode` accepts a string prefix with an UUID and
-returns an "external ID", composed of this prefix and zero-padded
-Base62-encoded UUID.
+Exid provides helper methods to create external, prefixed identifiers for your records, following the pattern popularized by Stripe's API.
 
-For example: `prg, 018977bb-02f0-729c-8c00-2f384eccb763` => `prg_02TOxMzOS0VaLzYiS3NPd9`
+Similar to Stripe's IDs (like `cus_12345` for customers or `prod_67890` for products), Exid generates readable, prefixed identifiers that:
 
-See more:
-  - https://dev.to/stripe/designing-apis-for-humans-object-ids-3o5a
-  - https://danschultzer.com/posts/prefixed-base62-uuidv7-object-ids-with-ecto
-  - https://dev.to/drnic/friendly-ids-for-ruby-on-rails-1c8p
-  - https://github.com/excid3/prefixed_ids
-  - https://github.com/sprql/uuid7-ruby
-  - https://github.com/steventen/base62-rb
+- Are human-friendly and can be safely exposed in URLs
+- Contain semantic prefixes that indicate resource type
+- Hide internal database IDs
+- Maintain global uniqueness
+- Are collision-resistant
+- Have constant length for a consistent user experience
+
+The core `Exid::Coder.encode` method accepts a string prefix with a UUID and returns an "external ID" composed of the prefix and a zero-padded **Base62-encoded UUID**.
+
+For example:
+```
+prg, 018977bb-02f0-729c-8c00-2f384eccb763 => prg_02TOxMzOS0VaLzYiS3NPd9
+```
+
+### Resources
+
+For more information on this approach:
+- [Designing APIs for Humans: Object IDs](https://dev.to/stripe/designing-apis-for-humans-object-ids-3o5a)
+- [Prefixed Base62 UUIDv7 Object IDs with Ecto](https://danschultzer.com/posts/prefixed-base62-uuidv7-object-ids-with-ecto)
+- [Friendly IDs for Ruby on Rails](https://dev.to/drnic/friendly-ids-for-ruby-on-rails-1c8p)
+- [Prefixed IDs](https://github.com/excid3/prefixed_ids)
+- [UUID7 Ruby](https://github.com/sprql/uuid7-ruby)
+- [Base62 Ruby](https://github.com/steventen/base62-rb)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "exid"
+```
+
+Then execute:
+
+```
+$ bundle install
+```
 
 ## Usage
 
-Add a UUID or (preferably) UUIDv7 to your model include a helper module. Pass a
-prefix (String) and a field name (Symbol) to the `Exid::Record.new` method.
+### Basic Setup
+
+Add a UUID or (preferably) UUIDv7 field to your model and include the helper module. Pass a prefix (String) and a field name (Symbol) to the `Exid::Record.new` method:
 
 ```ruby
 class User < ApplicationRecord
   include Exid::Record.new("user", :uuid)
 
-  # Optional, but recommended. Use the Exid value as the primary object
-  # identier.
-
+  # Optional, but recommended: Use the external ID as the primary object identifier
   def to_param = exid_value
 end
 ```
 
-That's all. This will add certain class and instance methods to your object.
+That's all! This adds several helper methods to your model.
+
+### Example
 
 ```ruby
+# Create a record with a UUID
 user = User.create!(uuid: "018977bb-02f0-729c-8c00-2f384eccb763")
+
+# Access the methods
+user.exid_value        # => "user_02TOxMzOS0VaLzYiS3NPd9"
+user.exid_prefix_name  # => "user"
+user.exid_field        # => :uuid
 ```
 
-Following methods are now available on the instance class.
+The `exid_handle` instance method returns the last 10 characters of the identifier. This is useful for displaying a distinguishing identifier in the UI. When using UUID7, the first few characters derive from timestamps and will be similar for objects created at the same time. You can pass an integer argument to get a specific number of trailing characters.
 
 ```ruby
-user.exid_value # => "user_02TOxMzOS0VaLzYiS3NPd9"
+user.exid_handle # => "OBtqZqRhLm"
+user.exid_handle(6) # => "ZqRhLm"
+```
 
-user.exid_prefix_name # => "user"
+### Configuration
 
-user.exid_field # => :uuid
-```
+You can configure Exid's prefix validation at the application level. Create an initializer (e.g., `config/initializers/exid.rb` in Rails):
 
-The `exid_handle` instanec method simply returns last 10 characters of
-identifier. This might be useful for displaying in the UI as distinguishing
-identifier.  If the UUID7 is used as the identifier, the first few characters
-are not random. They come from the timestamp, so they will be the same for most
-objects created at the same time. Pass integer as the argument to get the last
-N characters.
+By default, prefixes are limited to 4 characters. You can provide a custom validator proc that returns `true` if the prefix is valid, `false` otherwise:
 
 ```ruby
-user.exid_handle # => "OBtqZqRhLm"
-
-user.exid_handle(6) # => "ZqRhLm"
+Exid.configure do |config|
+  config.prefix_validator = proc { it.match?(/\A[a-z]{2,6}\z/) }
+end
 ```
+**Note**: When you set a custom `prefix_validator`, it replaces the default 4-character length validation. Your validator has full control over validation logic.
 
-The `Exid::Record` also offers couple of instance methods designed load
-records. This is another way to mimic Rails `GlobalID`. Warning: Steer
-away from using this as default way to load records using user supplied
-identifiers. User might replace the identifier with other record which might
-lead to unexpected results and security issues.
+### Loading Records by External ID
 
-The `fetch` class method will return the record or nil if not found. The
-`fetch!` variant will use Rails 7.1+ `sole` under the hood and raise an
-exception if the record is not found (or if more than one record is found).
+Use the class method `exid_loader` to load a record using its external ID:
 
 ```ruby
-Exid::Record.fetch!("pref_02WoeojY8dqVYcAhs321rm")
-Exid::Record.fetch("pref_02WoeojY8dqVYcAhs321rm")
+User.exid_loader("user_02TOxMzOS0VaLzYiS3NPd9")
+# Raises ActiveRecord::RecordNotFound if not found
+# Raises NoMatchingPatternError if ID format is invalid
 ```
 
+The `Exid::Record` module also provides global loading methods that mimic Rails `GlobalID` functionality:
+
+```ruby
+Exid::Record.fetch!("pref_02WoeojY8dqVYcAhs321rm") # Raises exception if not found
+Exid::Record.fetch("pref_02WoeojY8dqVYcAhs321rm")  # Returns `nil` if not found
+```
+
+> **⚠️ Security Warning**: Exercise caution when using global loading methods with user-supplied identifiers, as this could lead to unexpected results or security issues if users substitute identifiers.
+
+**Note**: When using this gem in Rails development mode (with `eager_load` set to `false`), ensure the model class is referenced before calling `.fetch` or `.fetch!`. This ensures the prefix is added to the global registry so the loader can identify which class is associated with the prefix.
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/docker-compose.yml

@@ -0,0 +1,14 @@
+---
+name: exid
+
+x-llm: &llm
+  build:
+    context: .
+    dockerfile: Dockerfile
+    target: node-base
+  image: claude
+  tmpfs:
+    - /tmp:mode=1777
+  volumes:
+    - .:/app
+    - ~/.claude.json:/root/.claude.json

data/lib/exid/base62.rb

@@ -2,6 +2,8 @@
 
 module Exid
   class Base62
+    class DecodeError < Error; end
+
     CHARS = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
     BASE = CHARS.length
     CHARS_HASH = CHARS.each_char.zip(0...BASE).to_h
@@ -22,7 +24,13 @@ module Exid
     def self.decode(str)
       max = str.length - 1
       str.each_char.zip(0..max).reduce(0) do |acc, (char, index)|
-        acc + (CHARS_HASH[char] * (BASE**(max - index)))
+        character = CHARS_HASH[char]
+
+        if character.nil?
+          raise DecodeError, "Invalid character '#{char}' in string '#{str}'"
+        end
+
+        acc + (character * (BASE**(max - index)))
       end
     end
   end

data/lib/exid/coder.rb

@@ -33,7 +33,7 @@ module Exid
     def self.encode(prefix, uuid)
       [
         prefix.to_s,
-        Base62.encode(uuid.delete("-").hex),
+        Base62.encode(uuid.delete("-").hex)
       ].join("_")
     end
 
@@ -48,7 +48,7 @@ module Exid
 
       Result.new(
         prefix,
-        [hex[0..7], hex[8..11], hex[12..15], hex[16..19], hex[20..31]].join("-"),
+        [hex[0..7], hex[8..11], hex[12..15], hex[16..19], hex[20..31]].join("-")
       )
     end
   end

data/lib/exid/configuration.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Exid
+  class Configuration
+    attr_accessor :prefix_validator
+
+    def initialize
+      @prefix_validator = default_validator
+    end
+
+    def validate_prefix(prefix)
+      return if prefix_validator.call(prefix)
+
+      raise Error, "Prefix validation failed for: #{prefix}"
+    end
+
+    private
+
+    def default_validator
+      proc { |prefix| prefix.length <= 4 }
+    end
+  end
+
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @_configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/exid/error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Exid
+  class Error < StandardError; end
+end

data/lib/exid/record.rb

@@ -5,6 +5,7 @@ module Exid
     Entry =
       Data.define(:prefix, :field, :klass) do
         def ==(other) = prefix == other.prefix
+
         def hash = prefix.hash
 
         alias_method :eql?, :==
@@ -13,22 +14,22 @@ module Exid
     @registered_modules = Set.new
 
     def included(base)
-      base.send(:include, @module_value)
-      base.send(:include, @module_shared)
-      base.send(:extend, @module_shared)
-      base.send(:extend, @module_static)
+      base.public_send(:include, @module_value)
+      base.public_send(:include, @module_shared)
+      base.public_send(:extend, @module_shared)
+      base.public_send(:extend, @module_static)
 
       self.class.register_module(
         Entry.new(
           prefix: base.exid_prefix_name,
           field: base.exid_field,
-          klass: base,
-        ),
+          klass: base
+        )
       )
     end
 
     def initialize(prefix, field)
-      raise Error, "Prefix cannot be longer than 4 characters" if prefix.length > 4
+      Exid.configuration.validate_prefix(prefix)
 
       @module_static = build_module_static(prefix, field)
       @module_value = build_module_value(prefix, field)
@@ -62,7 +63,7 @@ module Exid
     end
 
     def self.find_module(prefix)
-      registered_modules.detect { it.prefix == prefix } or
+      registered_modules.detect { _1.prefix == prefix } or
         raise Error, "Model for \"#{prefix}\" not found"
     end
 
@@ -74,6 +75,7 @@ module Exid
     end
 
     def self.fetch(eid) = finder(eid).first
+
     def self.fetch!(eid) = finder(eid).sole
 
     private
@@ -90,7 +92,7 @@ module Exid
         # display only, do not use this to fetch records, etc.
 
         define_method :exid_handle do |amount = 10|
-          exid_value.split("_").last[-amount..-1]
+          exid_value.split("_").last[-amount..]
         end
       end
     end

data/lib/exid/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: exid
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - John Doe
@@ -31,12 +31,18 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".rspec"
+- ".ruby-version"
+- ".standard.yml"
+- Dockerfile
 - LICENSE.txt
 - README.md
 - Rakefile
+- docker-compose.yml
 - lib/exid.rb
 - lib/exid/base62.rb
 - lib/exid/coder.rb
+- lib/exid/configuration.rb
+- lib/exid/error.rb
 - lib/exid/record.rb
 - lib/exid/version.rb
 - sig/exid.rbs
@@ -59,7 +65,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.7.2
 specification_version: 4
 summary: Easy External identifier management for models
 test_files: []