exid 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e0b51f276cf5b4bac2e662b192b8410ce19c76e04aa93e1b4b6daa58fba00ddb
-  data.tar.gz: 4bf5b946a071e7eec2ce02f7bda93089f514f18daa1a858a58585952eea7c153
+  metadata.gz: ca16f83a2ab050b505cdb0f774c7f147d5ba07bd8ebfa823f7b50791dcb8af5d
+  data.tar.gz: 4bcf07c0a4a1a61305416f13ddf0165292e6f01b2c379a21ca03492ec36a052e
 SHA512:
-  metadata.gz: 472e3a02ace26c1dd4acbf0109a3033f7273312fde90370bcbbe560416293e8bc51178c6c3859d31d4c46ee1c580f41213137091803c3a5f8d82630733f430ec
-  data.tar.gz: e8cec05ea307a1c28479135758b5705b0b5fd993a2aa6ee51f937e1fb6ba79a947c5b810487b6027de9a8639dea5e05da9ad479222bfe2c62c890391f492d0dc
+  metadata.gz: acbe278cae8f90cde6d27a839c9bbf76dfcda618fa5244c6d79765445fc506de7af1171540960a50821637c07b0d979d869ea35e19b49e93b4ee95af0a10e22a
+  data.tar.gz: 1e5878b5c78e5a91494ef8918a5edad2d3c245fed36d50b0298951d06da366c0c7405ca8e24eb01dec3dcf719bf02ae4a5ef5f9096f357ce7d6744dfad71d608

data/.ruby-version

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

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,116 @@
-# 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.
-
-  def to_param = prefix_eid_value
+  # 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.prefix_eid_value # => "user_02TOxMzOS0VaLzYiS3NPd9"
+user.exid_handle # => "OBtqZqRhLm"
+user.exid_handle(6) # => "ZqRhLm"
+```
 
-user.prefix_eid_prefix_name # => "user"
+### Loading Records by External ID
 
-user.prefix_eid_field # => :uuid
+Use the class method `exid_loader` to load a record using its external ID:
+
+```ruby
+User.exid_loader("user_02TOxMzOS0VaLzYiS3NPd9")
+# Raises ActiveRecord::RecordNotFound if not found
+# Raises NoMatchingPatternError if ID format is invalid
 ```
 
-The `prefix_eid_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.
+The `Exid::Record` module also provides global loading methods that mimic Rails `GlobalID` functionality:
 
 ```ruby
-user.prefix_eid_handle # => "OBtqZqRhLm"
-
-user.prefix_eid_handle(6) # => "ZqRhLm"
+Exid::Record.fetch!("pref_02WoeojY8dqVYcAhs321rm") # Raises exception if not found
+Exid::Record.fetch("pref_02WoeojY8dqVYcAhs321rm")   # Returns nil if not found
 ```
 
-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.
+> **⚠️ 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.
 
-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).
+**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.
 
-```ruby
-Exid::Record.fetch!("pref_02WoeojY8dqVYcAhs321rm")
-Exid::Record.fetch("pref_02WoeojY8dqVYcAhs321rm")
-```
+## 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,20 @@
+---
+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
+
+services:
+  ai:
+    <<: *llm
+    stdin_open: true
+    tty: true

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/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,17 +14,17 @@ 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.prefix_eid_prefix_name,
-          field: base.prefix_eid_field,
-          klass: base,
-        ),
+          prefix: base.exid_prefix_name,
+          field: base.exid_field,
+          klass: base
+        )
       )
     end
 
@@ -74,13 +75,14 @@ module Exid
     end
 
     def self.fetch(eid) = finder(eid).first
+
     def self.fetch!(eid) = finder(eid).sole
 
     private
 
     def build_module_value(prefix, field)
       Module.new do
-        define_method :prefix_eid_value do
+        define_method :exid_value do
           Coder.encode(prefix, send(field))
         end
 
@@ -89,19 +91,19 @@ module Exid
         # last bytes of encoded of UUID7 is more likely to be unique. This for
         # display only, do not use this to fetch records, etc.
 
-        define_method :prefix_eid_handle do |amount = 10|
-          prefix_eid_value.split("_").last[-amount..-1]
+        define_method :exid_handle do |amount = 10|
+          exid_value.split("_").last[-amount..]
         end
       end
     end
 
     def build_module_shared(prefix, field)
       Module.new do
-        define_method :prefix_eid_prefix_name do
+        define_method :exid_prefix_name do
           prefix
         end
 
-        define_method :prefix_eid_field do
+        define_method :exid_field do
           field
         end
       end
@@ -109,7 +111,7 @@ module Exid
 
     def build_module_static(prefix, field)
       Module.new do
-        define_method :prefix_eid_loader do |eid|
+        define_method :exid_loader do |eid|
           Coder.decode(eid) => ^prefix, value
           find_sole_by(field => value)
         end

data/lib/exid/version.rb

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

metadata

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