typeid_rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 545fbb367919209222c4334d6ae3ae560a6f338d1d76cd59bf964b74009d0df4
+  data.tar.gz: 8d5edbc4b5096f8c418047e71b6400c5895c2f431b0cf1358315b136f91478f9
+SHA512:
+  metadata.gz: 8eee45396ef77293c114761afbe6a21f3655af65bc157934eee501b64b59e4a22e9dacc70181f7b45a8369dfcbcf7279b3ebe01cf6250ba26db6bd854a1b436e
+  data.tar.gz: 820f7eeb45365192d2f66d4651f2e93abf17b1c5dff9c6486a5bad989fbbe49271dc67e2517194c22d3ee6193cd84041412790bd95906e1920d25739be92fc8c

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.1.0 - 2026-10-19
+
+Initial release.
+
+- `TypeidRails.encode`, `parse`, `to_uuid` and `generate` convert between UUIDs and
+  [TypeID](https://github.com/jetify-com/typeid) strings, conforming to spec version 0.3.0.
+  `TypeidRails::Value` is the parsed, immutable form.
+- `TypeidRails.configure` sets process-wide defaults: `fuzzy` accepts Crockford's lenient
+  spellings when decoding, `equality` picks prefix-sensitive (`:typeid`) or UUID-only (`:uuid`)
+  comparison, and `uuid_version` picks UUIDv4 or UUIDv7 for `generate`.
+- `TypeidRails::Identifiable` exposes a model's UUID primary key as a TypeID, and registers its
+  prefix in `TypeidRails::Registry`. `TypeidRails::AssociationSupport` does the same for foreign
+  keys pointing at such models.
+- `typeid_options` sets `fuzzy` and `strict` on a model class, inherited by its subclasses.
+- `TypeidRails::PolymorphicType` types a uuid column whose rows point at different models.
+- `TypeidRails.derive_uuid` derives a stable UUID from input parts with SHAKE128, when the
+  `sha3` gem is available.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Sorah Fukumori
+
+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,224 @@
+# typeid_rails: TypeID identifiers for UUID primary keys in Rails
+
+typeid_rails renders a 128-bit UUID as a [TypeID](https://github.com/jetify-com/typeid), a short string that carries its own type tag, and parses it back. Its ActiveRecord attribute type keeps a plain `uuid` column in the database and exposes the TypeID to application code.
+
+```
+user_0wp9c9wd1d90msb3z67p5eb0v5
+│    └─ the UUID, 26 Base32 characters
+└────── a prefix naming the kind of resource
+```
+
+A UUID is a fine primary key and a poor thing to put in a URL. It is long, it looks like every other UUID, and pasting a user's ID where an order's ID belongs silently finds nothing. A TypeID is shorter, says what it identifies, and is obviously wrong in the wrong place.
+
+The implementation passes the TypeID specification's test vectors (spec version 0.3.0). Optional settings relax decoding and equality for applications that already hand out Crockford Base32 identifiers decoded leniently.
+
+## Installation
+
+```bash
+bundle add typeid_rails
+```
+
+Requires Ruby 3.3 or later. The optional ActiveRecord integration is tested against ActiveRecord 7.1 and later.
+
+## Usage
+
+```ruby
+require "typeid_rails"
+
+TypeidRails.encode("1cb2589e-342d-4829-958f-e63d8ae58365", prefix: "user")
+# => "user_0wp9c9wd1d90msb3z67p5eb0v5"
+
+TypeidRails.to_uuid("user_0wp9c9wd1d90msb3z67p5eb0v5")
+# => "1cb2589e-342d-4829-958f-e63d8ae58365"
+```
+
+`to_uuid` returns `nil` for anything malformed. When a bad identifier should be an error instead, parse it:
+
+```ruby
+id = TypeidRails.parse("user_0wp9c9wd1d90msb3z67p5eb0v5")
+id.uuid    # => "1cb2589e-342d-4829-958f-e63d8ae58365"
+id.prefix  # => "user"
+id.to_s    # => "user_0wp9c9wd1d90msb3z67p5eb0v5"
+
+TypeidRails.parse("user_0WP9C9WD1D90MSB3Z67P5EB0V5")  # raises TypeidRails::InvalidFormatError
+```
+
+Pass `expected_prefix:` to reject identifiers that belong to another kind of resource. The result is `nil` rather than an exception, since a wrong prefix is usually a lookup that should miss:
+
+```ruby
+TypeidRails.parse("user_0wp9c9wd1d90msb3z67p5eb0v5", expected_prefix: "org")  # => nil
+```
+
+Prefixes follow the TypeID grammar: lowercase ASCII letters and underscores, at most 63 characters, with no underscore at either end. An empty prefix is allowed and renders as the bare suffix. `TypeidRails::Value` is immutable. Decoding is strict by default. See [Configuration](#configuration) to relax it.
+
+To mint a new identifier without a database round-trip:
+
+```ruby
+TypeidRails.generate(prefix: "user")              # => "user_..." from a UUIDv4
+TypeidRails.generate(prefix: "user", version: 7)  # => "user_01m5a5kxrqeea9n21at57rtheq"
+```
+
+### ActiveRecord
+
+Under Rails the integration loads itself. Elsewhere, `require "typeid_rails/active_record"`.
+
+Declare a prefix on any model whose primary key is a UUID:
+
+```ruby
+class User < ApplicationRecord
+  include TypeidRails::Identifiable
+  id_prefix "user"
+end
+
+User.first.id                                     # => "user_0wp9c9wd1d90msb3z67p5eb0v5"
+User.find_by(id: "user_0wp9c9wd1d90msb3z67p5eb0v5")
+```
+
+The column still holds a plain UUID. Only the attribute is encoded. Raw UUIDs are accepted on assignment too, so seeds, migrations and hand-written queries do not have to encode first.
+
+This gem never generates primary keys. That stays with the database (`gen_random_uuid()` or similar) or with your own code.
+
+Foreign keys are handled by a second concern, included once in your base class. It is separate because a model with no public identifier of its own, such as a join table or an audit row, can still point at models that have one:
+
+```ruby
+class ApplicationRecord < ActiveRecord::Base
+  primary_abstract_class
+  include TypeidRails::AssociationSupport
+end
+
+class Membership < ApplicationRecord
+  belongs_to :user  # user_id now reads and writes "user_..." identifiers
+end
+```
+
+By default an identifier with the wrong prefix, or one that is malformed, collapses to the null UUID. It matches no row, and the lookup simply finds nothing. Pass `strict: true` to raise `TypeidRails::PrefixMismatchError` or `TypeidRails::InvalidFormatError` instead:
+
+```ruby
+id_prefix "user", strict: true
+```
+
+A uuid column whose rows point at different models, with a sibling column naming which, has no single prefix. Type it with `TypeidRails::PolymorphicType`. It accepts an identifier under any prefix, or a raw UUID, and reads back the bare UUID, so the owning record supplies the prefix:
+
+```ruby
+class Preference < ApplicationRecord
+  OWNER_MODELS = {"user" => User, "org" => Organization}.freeze
+
+  attribute :owner_id, TypeidRails::PolymorphicType.new
+
+  def owner_id
+    model = OWNER_MODELS[owner_type]
+    model ? model.type_for_attribute("id").cast(super) : super
+  end
+end
+```
+
+### Prefix registry
+
+Declaring a prefix registers the model under it, so an identifier can be routed back to whatever owns it. This is useful when a token or an API path carries an identifier whose kind is not known ahead of time.
+
+```ruby
+TypeidRails::Registry.model_for("user") # => User
+TypeidRails::Registry.prefix_for(User)  # => "user"
+```
+
+### Deterministic identifiers
+
+`derive_uuid` turns any set of input parts into a stable UUID, so two systems that agree on the inputs arrive at the same identifier without talking to each other. Useful when records are mirrored across a boundary and both sides need to name them identically.
+
+```ruby
+TypeidRails.derive_uuid("production", "users", "42")
+# => "82b28cf0-404a-d9b3-1a45-70f9e81ea106"
+```
+
+Parts are joined with a NUL byte before hashing, so `("ab", "c")` and `("a", "bc")` derive different identifiers.
+
+This requires the [`sha3`](https://rubygems.org/gems/sha3) gem, which is not a dependency of this gem. Add it yourself if you use this feature:
+
+```ruby
+gem "sha3"
+```
+
+The result is 128 raw bits of SHAKE128 output rendered in UUID shape. It is deliberately not an RFC 9562 UUID: no version or variant bits are set. This keeps derived identifiers stable forever, at the cost of them not being valid v4 or v7 UUIDs.
+
+## Configuration
+
+```ruby
+# config/initializers/typeid_rails.rb
+TypeidRails.configure do |config|
+  config.fuzzy = false          # accept Crockford's lenient spellings when decoding
+  config.equality = :typeid     # :typeid or :uuid, see below
+  config.uuid_version = 4       # 4 or 7, used by generate
+end
+```
+
+Each setting can be overridden where it applies: `parse(..., fuzzy:)`, `generate(..., version:)`, and `id_prefix "user", fuzzy:` or `Type.new(prefix:, fuzzy:)` for an attribute.
+
+- `fuzzy`: TypeID accepts only the lowercase alphabet. With `fuzzy = true`, the suffix also decodes in uppercase, and `i`/`l` read as `1`, `o` as `0` and `u` as `v`, as in [Crockford's Base32](https://www.crockford.com/base32.html). The prefix is never relaxed, and the result always renders canonically.
+- `equality`: with `:typeid`, two values are equal when both the prefix and the UUID match, and a value equals a String only when it is the exact rendering. With `:uuid`, the prefix is ignored and a value also equals its raw UUID text.
+- `uuid_version`: TypeID recommends v7 so identifiers sort by creation time. A v7 UUID also reveals that time to anyone who holds the identifier, so the default is v4.
+
+### Per model
+
+The attribute types can take `fuzzy` and `strict` from a model class instead, so they can be set on an abstract class rather than for the whole process:
+
+```ruby
+class ApplicationRecord < ActiveRecord::Base
+  primary_abstract_class
+  include TypeidRails::AssociationSupport
+  typeid_options fuzzy: true, strict: true
+end
+
+class LegacyRecord < ApplicationRecord
+  self.abstract_class = true
+  typeid_options strict: false  # merged over the inherited options
+end
+```
+
+An attribute takes the first setting found: the `id_prefix` argument, then the model's `typeid_options`, then the global configuration (`fuzzy`) or `false` (`strict`). A foreign key follows the options of the model that declares the `belongs_to`. `typeid_options` applies to attributes declared after it, so call it before `id_prefix` and `belongs_to` in the same class. `equality` and `uuid_version` act on values outside any model, and stay global.
+
+To keep accepting identifiers an application already issued under the lenient Crockford rules, while migrating it towards TypeID:
+
+```ruby
+TypeidRails.configure do |config|
+  config.fuzzy = true
+  config.equality = :uuid
+end
+```
+
+## Difference with the typeid gem
+
+The [typeid](https://github.com/broothie/typeid-ruby) gem is a general Ruby implementation of TypeID that mints UUIDv7 identifiers. Use it when you need TypeIDs outside ActiveRecord and want no integration with models.
+
+typeid_rails is built around existing UUID primary keys. It adds an attribute type so columns stay `uuid` while models read and write TypeIDs, a prefix registry, a type for polymorphic columns, and compatibility settings for identifiers already issued under lenient Crockford rules. The namespaces are different (`TypeidRails` and `TypeID`), so both gems can be loaded together.
+
+## Caveats
+
+- With `fuzzy = true`, the gem accepts strings that the TypeID spec requires to be rejected. Encoding is unaffected, and every identifier it renders is a valid TypeID.
+- `generate` mints UUIDv4 by default, while the spec recommends UUIDv7. Set `uuid_version = 7` to follow it.
+- `Value#==` and `#hash` read the `equality` setting on every call. Changing it while values are held as hash keys leaves those hashes inconsistent.
+
+## Development
+
+```bash
+bin/setup                        # install dependencies
+bundle exec rake                 # run the specs, including the TypeID test vectors
+bundle exec rbs collection install
+bundle exec steep check          # typecheck lib/ against sig/
+hk check --all                   # run every linter, as CI does
+```
+
+## Third-party code
+
+The bit-buffer technique in `TypeidRails::Base32` is adapted from the [rotp](https://github.com/mdp/rotp) gem, Copyright (c) 2011 Mark Percival, used under the MIT License. The notice is reproduced in `lib/typeid_rails/base32.rb`.
+
+The test vectors in `spec/fixtures/typeid/` are taken from the [TypeID specification](https://github.com/jetify-com/typeid) and used under the Apache License 2.0. They are not part of the published gem.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/sorah/typeid_rails.
+
+## License
+
+Copyright (c) 2026 Sorah Fukumori
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+desc "Typecheck lib/ against sig/ with steep"
+task :steep do
+  sh "bundle exec steep check"
+end
+
+task default: :spec

data/lib/typeid_rails/active_record.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "../typeid_rails"
+
+require_relative "type"
+require_relative "polymorphic_type"
+require_relative "identifiable"
+require_relative "association_support"

data/lib/typeid_rails/association_support.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+require_relative "model_options"
+require_relative "type"
+
+module TypeidRails
+  # Applies TypeidRails::Type to foreign keys pointing at Identifiable models, so an
+  # association can be assigned a prefixed identifier directly. The type takes this
+  # model's typeid_options, not the referenced model's.
+  #
+  # This lives apart from Identifiable because a model that has no public identifier
+  # of its own — a join table, an audit row — can still hold foreign keys to models
+  # that do. Include it once, in the application's base record class:
+  #
+  #   class ApplicationRecord < ActiveRecord::Base
+  #     primary_abstract_class
+  #     include TypeidRails::AssociationSupport
+  #   end
+  module AssociationSupport
+    extend ActiveSupport::Concern
+    include ModelOptions
+
+    class_methods do
+      def belongs_to(name, scope = nil, **options, &block)
+        result = super
+        association = reflect_on_association(name)
+        configure_foreign_key_for_association(association) if association
+        result
+      end
+
+      # Configures every already-declared belongs_to. Needed only when an association
+      # was defined before this module was included.
+      def configure_foreign_keys!
+        reflect_on_all_associations(:belongs_to).each do |association|
+          configure_foreign_key_for_association(association)
+        end
+      end
+
+      private def configure_foreign_key_for_association(association)
+        return if association.polymorphic?
+
+        fk_name = association.foreign_key.to_s
+        return if attribute_types[fk_name].is_a?(Type)
+
+        referenced_model = resolve_association_class(association)
+        return unless referenced_model.respond_to?(:id_prefix) && referenced_model.id_prefix
+
+        attribute fk_name, build_typeid_type(referenced_model.id_prefix)
+      end
+
+      # An association may name a class that does not exist yet (or at all); that is
+      # not our problem to report. Any other NameError comes from loading the class
+      # itself and must not be swallowed.
+      private def resolve_association_class(association)
+        association.klass
+      rescue NameError => e
+        raise unless e.name.to_s == association.class_name.to_s.split("::").last
+
+        nil
+      end
+    end
+  end
+end

data/lib/typeid_rails/base32.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require_relative "configuration"
+
+module TypeidRails
+  # TypeID's Base32 encoding/decoding for raw bytes: Crockford's alphabet over a
+  # 130-bit big-endian value whose top 2 bits are zero.
+  # Uses a streaming bit-buffer approach to avoid bigint arithmetic.
+  #
+  # Reference: https://github.com/jetify-com/typeid/tree/main/spec#base32-encoding
+  #
+  # Bit-buffer technique adapted from rotp gem (https://github.com/mdp/rotp).
+  # Copyright (C) 2011 by Mark Percival <m@mdp.im>
+  #
+  # 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.
+  module Base32
+    # Crockford's Base32 alphabet (lowercase, excludes I, L, O, U to avoid ambiguity)
+    ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz"
+
+    # Indexable form of ALPHABET, so encoding does not allocate a String per lookup.
+    ALPHABET_CHARS = ALPHABET.chars.freeze
+
+    # Number of bytes a single encoded value carries.
+    BYTE_SIZE = 16
+
+    # Number of characters produced for BYTE_SIZE bytes.
+    LENGTH = 26
+
+    STRICT_DECODE_MAP = ALPHABET.each_char.with_index.to_h.freeze
+
+    # Looked up after downcasing.
+    FUZZY_DECODE_MAP = STRICT_DECODE_MAP.merge(
+      "i" => 1,
+      "l" => 1,
+      "o" => 0,
+      "u" => 27, # Crockford reserves U as a check symbol; read it as V.
+    ).freeze
+
+    SHIFT = 5
+    MASK = 0x1f
+
+    class << self
+      # Encodes a 16-byte string to 26 Base32 characters.
+      # 16 bytes = 128 bits; with 2 leading zero bits = 130 bits = 26 × 5.
+      # @param bytes [String] 16-byte binary string
+      # @return [String] 26-character base32 string
+      def encode_bytes(bytes)
+        raise ArgumentError, "Expected #{BYTE_SIZE} bytes, got #{bytes.bytesize}" unless bytes.bytesize == BYTE_SIZE
+
+        data = bytes.unpack("C*") #: Array[Integer]
+        out = String.new
+        buffer = 0
+        bits_left = 2 # 2 leading zero bits: 2 + 128 = 130 = 26 * 5
+        idx = 0
+
+        while bits_left > 0 || idx < data.length
+          if bits_left < SHIFT
+            buffer = (buffer << 8) | data.fetch(idx)
+            bits_left += 8
+            idx += 1
+          end
+          bits_left -= SHIFT
+          out << ALPHABET_CHARS.fetch((buffer >> bits_left) & MASK)
+          buffer &= (1 << bits_left) - 1
+        end
+
+        out
+      end
+
+      # Decodes a 26-character Base32 string to a 16-byte string.
+      # 26 chars × 5 bits = 130 bits. The first char carries 2 padding zeros + 3 data bits.
+      # Remaining 25 chars carry 125 bits. Total data: 3 + 125 = 128 bits = 16 bytes.
+      # @param base32 [String] 26-character base32 string
+      # @param fuzzy [Boolean] see Configuration#fuzzy
+      # @return [String] 16-byte binary string
+      def decode_bytes(base32, fuzzy: TypeidRails.config.fuzzy)
+        values = to_values(base32, fuzzy:) if valid128?(base32, fuzzy:)
+        raise ArgumentError, "Invalid base32 format" unless values
+
+        # First character: discard top 2 padding bits, keep bottom 3 data bits
+        buffer = values.fetch(0) & 0x07
+        bits_left = 3
+        result = [] #: Array[Integer]
+
+        values.drop(1).each do |value|
+          buffer = (buffer << SHIFT) | value
+          bits_left += SHIFT
+
+          if bits_left >= 8
+            bits_left -= 8
+            result << ((buffer >> bits_left) & 0xff)
+            buffer &= (1 << bits_left) - 1
+          end
+        end
+
+        result.pack("C*")
+      end
+
+      # Checks if a string is a valid 26-character base32 encoding of 128 bits.
+      # @param string [String] string to validate
+      # @param fuzzy [Boolean] see Configuration#fuzzy
+      # @return [Boolean]
+      def valid128?(string, fuzzy: TypeidRails.config.fuzzy)
+        return false unless string.is_a?(String)
+        return false unless string.length == LENGTH
+
+        values = to_values(string, fuzzy:)
+        return false unless values
+
+        # A 128-bit encoding carries 2 leading zero bits, so the first character
+        # must decode to a value in 0-7. Without this check, decode_bytes silently
+        # masks the top 2 bits and multiple base32 strings collapse to the same UUID.
+        values.fetch(0) <= 7
+      end
+
+      # @return [Array<Integer>, nil] nil when a character is outside the alphabet
+      private def to_values(string, fuzzy:)
+        map = fuzzy ? FUZZY_DECODE_MAP : STRICT_DECODE_MAP
+        normalized = fuzzy ? string.downcase : string
+        values = [] #: Array[Integer]
+        normalized.each_char do |char|
+          value = map[char]
+          return nil unless value
+
+          values << value
+        end
+        values
+      end
+    end
+  end
+end

data/lib/typeid_rails/configuration.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module TypeidRails
+  # Process-wide defaults. Each setting can also be overridden where it is consumed.
+  class Configuration
+    UUID_VERSIONS = [4, 7].freeze
+    EQUALITY_MODES = [:typeid, :uuid].freeze
+
+    # When true, suffixes are decoded with Crockford's leniency: uppercase is accepted,
+    # and I/L read as 1, O as 0 and U as V. TypeID itself rejects all of these.
+    attr_accessor :fuzzy
+
+    # UUID version minted by Value.generate. 7 sorts by creation time, and also
+    # reveals it.
+    attr_reader :uuid_version
+
+    # How Value#== compares. :typeid compares the prefix and the UUID, and matches a
+    # String only when it is the exact rendering. :uuid ignores the prefix and also
+    # matches the raw UUID text.
+    attr_reader :equality
+
+    def initialize
+      @fuzzy = false
+      @uuid_version = 4
+      @equality = :typeid
+    end
+
+    def equality=(mode)
+      unless EQUALITY_MODES.include?(mode)
+        raise ArgumentError, "Unsupported equality mode #{mode.inspect}; expected one of #{EQUALITY_MODES.join(", ")}"
+      end
+
+      @equality = mode
+    end
+
+    def uuid_version=(version)
+      self.class.validate_uuid_version!(version)
+      @uuid_version = version
+    end
+
+    def self.validate_uuid_version!(version)
+      return if UUID_VERSIONS.include?(version)
+
+      raise ArgumentError, "Unsupported UUID version #{version.inspect}; expected one of #{UUID_VERSIONS.join(", ")}"
+    end
+  end
+
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+
+    def reset_config!
+      @config = Configuration.new
+    end
+  end
+end

data/lib/typeid_rails/derivation.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+begin
+  require "sha3"
+rescue LoadError => e
+  raise LoadError, "TypeidRails.derive_uuid requires the `sha3` gem; add `gem \"sha3\"` to your Gemfile", cause: e
+end
+
+require_relative "encoder"
+
+module TypeidRails
+  # Deterministic identifier derivation.
+  #
+  # Two systems that agree on the same input parts derive the same identifier without
+  # coordinating, which is what makes it useful for mirroring records across a boundary.
+  #
+  # The result is 128 raw bits of SHAKE128 output rendered in UUID shape. It is
+  # deliberately *not* an RFC 4122 UUID: no version or variant bits are set, so it
+  # cannot be confused with a randomly generated one and stays stable forever.
+  module Derivation
+    class << self
+      # @param parts [Array<String>] input components, joined with a NUL separator
+      # @return [String] canonical UUID text
+      def uuid(*parts)
+        digest = SHA3::Digest::SHAKE_128.new.tap { |shake| shake.update(parts.join("\0")) }.hex_squeeze(16)
+        Encoder.format_uuid(digest)
+      end
+    end
+  end
+end

data/lib/typeid_rails/encoder.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "base32"
+
+module TypeidRails
+  # Converts between canonical UUID text and its Base32 rendering.
+  # This is the unprefixed half of the format; see Value for the prefixed form.
+  module Encoder
+    # Sentinel UUID substituted for invalid or mismatched input by lenient consumers.
+    NULL_UUID = "00000000-0000-0000-0000-000000000000"
+
+    UUID_REGEX = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i
+
+    class << self
+      # @param uuid [String] canonical UUID text
+      # @return [String] 26-character Base32 string
+      def encode(uuid)
+        raise ArgumentError, "Invalid UUID format" unless uuid.is_a?(String) && uuid.match?(UUID_REGEX)
+
+        bytes = [uuid.delete("-")].pack("H*")
+        Base32.encode_bytes(bytes)
+      end
+
+      # @param base32 [String] 26-character Base32 string
+      # @param fuzzy [Boolean] see Configuration#fuzzy
+      # @return [String] canonical lowercase UUID text
+      def decode(base32, fuzzy: TypeidRails.config.fuzzy)
+        hex = Base32.decode_bytes(base32, fuzzy:).unpack1("H*") #: String
+        format_uuid(hex)
+      end
+
+      def valid?(string, fuzzy: TypeidRails.config.fuzzy)
+        Base32.valid128?(string, fuzzy:)
+      end
+
+      # Formats 32 hex characters as canonical UUID text.
+      # @param hex [String] 32-character hex string
+      # @return [String]
+      def format_uuid(hex)
+        "#{hex[0, 8]}-#{hex[8, 4]}-#{hex[12, 4]}-#{hex[16, 4]}-#{hex[20, 12]}"
+      end
+    end
+  end
+end