typeid_rails 0.1.0

data/lib/typeid_rails/errors.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module TypeidRails
+  class Error < StandardError; end
+
+  # Raised when parsing a string that is not a well-formed resource identifier.
+  class InvalidFormatError < Error
+    attr_reader :input
+
+    def initialize(input:, message:)
+      @input = input
+      super(message)
+    end
+  end
+
+  # Raised for a prefix outside TypeID's grammar, whether parsed or declared.
+  class InvalidPrefixError < InvalidFormatError; end
+
+  # Raised when a resource identifier carries a prefix other than the expected one.
+  # Only raised by strict consumers; lenient ones substitute the null UUID instead.
+  class PrefixMismatchError < Error
+    attr_reader :expected, :actual, :input
+
+    def initialize(expected:, actual:, input:)
+      @expected = expected
+      @actual = actual
+      @input = input
+      super("Expected prefix '#{expected}', got '#{actual}' in '#{input}'")
+    end
+  end
+
+  # Raised when two different models claim the same prefix.
+  class DuplicatePrefixError < Error
+    attr_reader :prefix, :existing_model, :conflicting_model
+
+    def initialize(prefix:, existing_model:, conflicting_model:)
+      @prefix = prefix
+      @existing_model = existing_model
+      @conflicting_model = conflicting_model
+      super("Duplicate prefix '#{prefix}' used by #{existing_model} and #{conflicting_model}")
+    end
+  end
+end

data/lib/typeid_rails/identifiable.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+require_relative "model_options"
+require_relative "registry"
+
+module TypeidRails
+  # Gives a model a public identifier: its UUID primary key is read and written as a
+  # prefixed string, and the prefix is registered so the model can be found from one.
+  #
+  #   class User < ApplicationRecord
+  #     include TypeidRails::Identifiable
+  #     id_prefix "u"
+  #   end
+  #
+  #   User.first.id # => "u_2n1t201rmv87aae5j4csam8000"
+  module Identifiable
+    extend ActiveSupport::Concern
+    include ModelOptions
+
+    class_methods do
+      # Declares (with an argument) or reads (without) this model's prefix.
+      # @param prefix [String, nil]
+      # @param strict [Boolean, nil] see Type#initialize; nil follows typeid_options
+      # @param fuzzy [Boolean, nil] see Type#initialize; nil follows typeid_options
+      # @return [String, nil]
+      def id_prefix(prefix = nil, strict: nil, fuzzy: nil)
+        if prefix
+          attribute :id, build_typeid_type(prefix, strict:, fuzzy:)
+          @id_prefix = prefix
+          Registry.register(prefix, self)
+        end
+        @id_prefix
+      end
+    end
+  end
+end

data/lib/typeid_rails/model_options.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "active_support/core_ext/class/attribute"
+
+require_relative "type"
+
+module TypeidRails
+  # Per-model defaults for the attribute types this gem installs. Declared on an
+  # abstract base class, they are inherited by every model below it:
+  #
+  #   class ApplicationRecord < ActiveRecord::Base
+  #     primary_abstract_class
+  #     include TypeidRails::AssociationSupport
+  #     typeid_options fuzzy: true, strict: true
+  #   end
+  #
+  # Identifiable and AssociationSupport include this, so it rarely needs including directly.
+  module ModelOptions
+    extend ActiveSupport::Concern
+
+    KEYS = [:fuzzy, :strict].freeze
+
+    included do
+      # @type self: singleton(ActiveRecord::Base)
+      defaults = {} #: Hash[Symbol, bool]
+      class_attribute :typeid_rails_options, instance_accessor: false, default: defaults.freeze
+    end
+
+    class_methods do
+      # Merges into the options inherited from the superclass, and returns the result.
+      # Applies to attributes declared afterwards.
+      # @param fuzzy [Boolean] see Type#initialize; unset follows TypeidRails.config
+      # @param strict [Boolean] see Type#initialize; unset means false
+      def typeid_options(**options)
+        unknown = options.keys - KEYS
+        raise ArgumentError, "Unknown typeid_options: #{unknown.join(", ")}" unless unknown.empty?
+
+        self.typeid_rails_options = typeid_rails_options.merge(options).freeze unless options.empty?
+        typeid_rails_options
+      end
+
+      # Builds a Type, filling options the caller left nil from this model's.
+      private def build_typeid_type(prefix, strict: nil, fuzzy: nil)
+        options = typeid_rails_options
+        Type.new(
+          prefix:,
+          strict: strict.nil? ? options.fetch(:strict, false) : strict,
+          fuzzy: fuzzy.nil? ? options[:fuzzy] : fuzzy,
+        )
+      end
+    end
+  end
+end

data/lib/typeid_rails/polymorphic_type.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "type"
+
+module TypeidRails
+  # An attribute type for a uuid column whose rows point at different models, with a
+  # sibling column naming which. Accepts an identifier under any prefix, or a raw
+  # UUID, and reads back the bare UUID, since only the owning record knows which
+  # prefix applies:
+  #
+  #   class Preference < ApplicationRecord
+  #     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
+  class PolymorphicType < Type
+    # @param strict [Boolean] when true, malformed input raises instead of becoming
+    #   the null UUID
+    # @param fuzzy [Boolean, nil] see Type#initialize
+    def initialize(strict: false, fuzzy: nil)
+      super(prefix: "", strict:, fuzzy:)
+    end
+
+    def deserialize(value)
+      value&.downcase
+    end
+
+    def cast(value)
+      serialize(value)
+    end
+
+    def serialize(value)
+      return if value.nil?
+
+      value.is_a?(Value) ? value.to_uuid : string_to_uuid(value.to_s)
+    end
+
+    private def parse_or_null(string)
+      Value.parse(string, fuzzy: fuzzy?)
+    rescue InvalidFormatError
+      raise if strict?
+
+      nil
+    end
+  end
+end

data/lib/typeid_rails/railtie.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Reaching this file means Rails is present, so the ActiveRecord integration is
+# wanted and can simply be loaded. The railtie itself carries no behaviour.
+require_relative "active_record"
+
+module TypeidRails
+  class Railtie < ::Rails::Railtie
+  end
+end

data/lib/typeid_rails/registry.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module TypeidRails
+  # Process-wide prefix -> model mapping, letting a bare identifier string be routed
+  # back to the class that owns it.
+  module Registry
+    @prefixes = {}
+    @models = {}
+
+    class << self
+      # @raise [DuplicatePrefixError] when another model already claims this prefix
+      def register(prefix, model)
+        existing = @prefixes[prefix]
+        # Compared by name, not identity: a code reloader hands us a fresh class object
+        # for the same constant, which is a re-registration rather than a conflict.
+        if existing && name_of(existing) != name_of(model)
+          raise DuplicatePrefixError.new(
+            prefix:,
+            existing_model: name_of(existing),
+            conflicting_model: name_of(model),
+          )
+        end
+
+        @models.delete(existing) if existing
+        @prefixes[prefix] = model
+        @models[model] = prefix
+        model
+      end
+
+      def all_prefixes
+        @prefixes.dup
+      end
+
+      def model_for(prefix)
+        @prefixes[prefix]
+      end
+
+      def prefix_for(model)
+        @models[model]
+      end
+
+      def reset!
+        @prefixes = {}
+        @models = {}
+      end
+
+      private def name_of(model) = model.name || model.to_s
+    end
+  end
+end

data/lib/typeid_rails/type.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "active_record"
+
+require_relative "encoder"
+require_relative "errors"
+require_relative "value"
+
+module TypeidRails
+  # An ActiveRecord attribute type that stores a UUID but exposes the prefixed
+  # identifier string, so a record's public identifier never has to be built by hand.
+  #
+  # Reading gives back a plain String rather than a Value, so the attribute stays
+  # comparable and serializable in the ways application code already expects.
+  class Type < ActiveRecord::Type::Value
+    attr_reader :prefix
+
+    # @param prefix [String] the type tag this attribute is presented under
+    # @param strict [Boolean] when true, malformed input and prefix mismatches raise.
+    #   When false (the default), they collapse to the null UUID, which matches no row.
+    # @param fuzzy [Boolean, nil] see Configuration#fuzzy; nil follows the configuration
+    #   at the time of each cast
+    # @raise [InvalidPrefixError]
+    def initialize(prefix:, strict: false, fuzzy: nil)
+      Value.validate_prefix!(prefix)
+      @prefix = prefix
+      @strict = strict
+      @fuzzy = fuzzy
+      super()
+    end
+
+    def strict? = @strict
+
+    def fuzzy?
+      fuzzy = @fuzzy
+      fuzzy.nil? ? TypeidRails.config.fuzzy : fuzzy
+    end
+
+    def type = :uuid
+
+    def deserialize(value)
+      return if value.nil?
+
+      Value.from_uuid(value, prefix:).to_s
+    end
+
+    def cast(value)
+      return if value.nil?
+
+      case value
+      when Value then value.to_s
+      when String then cast_string(value)
+      else cast_string(value.to_s)
+      end
+    end
+
+    def serialize(value)
+      return if value.nil?
+
+      case value
+      when Value then value.to_uuid
+      when String then string_to_uuid(value)
+      else value
+      end
+    end
+
+    # The exposed value is a frozen String rebuilt on every read, so in-place mutation
+    # is not a thing that can happen.
+    def changed_in_place?(_raw_old_value, _new_value)
+      false
+    end
+
+    private def cast_string(string)
+      uuid = string_to_uuid(string)
+      Value.from_uuid(uuid, prefix:).to_s
+    end
+
+    private def string_to_uuid(string)
+      # Raw UUIDs are accepted so that seeds, migrations and hand-written queries
+      # do not have to encode first.
+      return string.downcase if string.match?(Encoder::UUID_REGEX)
+
+      parsed = parse_or_null(string)
+      parsed ? parsed.to_uuid : Encoder::NULL_UUID
+    end
+
+    private def parse_or_null(string)
+      parsed = Value.parse(string, expected_prefix: prefix, fuzzy: fuzzy?)
+      raise PrefixMismatchError.new(expected: prefix, actual: string.rpartition("_").first, input: string) if parsed.nil? && strict?
+
+      parsed
+    rescue InvalidFormatError
+      raise if strict?
+
+      nil
+    end
+  end
+end

data/lib/typeid_rails/value.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+require_relative "configuration"
+require_relative "encoder"
+require_relative "errors"
+
+module TypeidRails
+  # An immutable TypeID: a 128-bit UUID plus the type prefix it is presented under.
+  # Renders as "<prefix>_<base32>", e.g. "u_2n1t201rmv87aae5j4csam8000", or as the
+  # bare suffix when the prefix is empty.
+  class Value
+    # Lowercase ASCII letters and underscores, at most 63 characters, neither starting
+    # nor ending with an underscore. Empty is allowed.
+    PREFIX_FORMAT = /\A(?:[a-z](?:[a-z_]{0,61}[a-z])?)?\z/
+
+    attr_reader :uuid, :prefix, :encoded
+
+    def initialize(uuid:, prefix:, encoded:)
+      @uuid = uuid.downcase.freeze
+      @prefix = prefix.freeze
+      @encoded = encoded.downcase.freeze
+      freeze
+    end
+
+    class << self
+      def valid_prefix?(prefix)
+        prefix.is_a?(String) && prefix.match?(PREFIX_FORMAT)
+      end
+
+      # @raise [InvalidPrefixError]
+      def validate_prefix!(prefix)
+        return if valid_prefix?(prefix)
+
+        raise InvalidPrefixError.new(input: prefix.to_s, message: "Invalid prefix: #{prefix.inspect}")
+      end
+
+      # @raise [InvalidPrefixError]
+      def from_uuid(uuid, prefix:)
+        validate_prefix!(prefix)
+        normalized_uuid = uuid.downcase
+        new(uuid: normalized_uuid, prefix:, encoded: Encoder.encode(normalized_uuid))
+      end
+
+      # Mints a new identifier from a random UUID.
+      # @param version [Integer] 4 or 7; see Configuration#uuid_version
+      def generate(prefix:, version: TypeidRails.config.uuid_version)
+        Configuration.validate_uuid_version!(version)
+        from_uuid(version == 7 ? SecureRandom.uuid_v7 : SecureRandom.uuid, prefix:)
+      end
+
+      # @param string [String, nil] a "<prefix>_<base32>" identifier, or a bare suffix
+      # @param expected_prefix [String, nil] when given, returns nil on a prefix mismatch
+      # @param fuzzy [Boolean] see Configuration#fuzzy; affects the suffix only
+      # @raise [InvalidFormatError] when the string is not a well-formed identifier
+      # @return [Value, nil]
+      def parse(string, expected_prefix: nil, fuzzy: TypeidRails.config.fuzzy)
+        return if string.nil?
+
+        string = string.to_s
+        # Prefixes may contain underscores, so the separator is the last one.
+        prefix, separator, encoded_part = string.rpartition("_")
+        if !separator.empty? && prefix.empty?
+          raise InvalidFormatError.new(input: string, message: "Invalid format: separator without a prefix")
+        end
+        unless valid_prefix?(prefix)
+          raise InvalidPrefixError.new(input: string, message: "Invalid format: invalid prefix")
+        end
+        unless Encoder.valid?(encoded_part, fuzzy:)
+          raise InvalidFormatError.new(input: string, message: "Invalid format: invalid suffix")
+        end
+
+        return if expected_prefix && prefix != expected_prefix
+
+        from_uuid(Encoder.decode(encoded_part, fuzzy:), prefix:)
+      end
+    end
+
+    def to_s
+      prefix.empty? ? encoded : "#{prefix}_#{encoded}"
+    end
+
+    def to_uuid
+      uuid
+    end
+
+    # @see Configuration#equality
+    def ==(other)
+      uuid_only = TypeidRails.config.equality == :uuid
+      case other
+      when Value
+        uuid == other.uuid && (uuid_only || prefix == other.prefix)
+      when String
+        to_s == other || (uuid_only && uuid == other.downcase)
+      else
+        false
+      end
+    end
+    alias_method :eql?, :==
+
+    def hash
+      TypeidRails.config.equality == :uuid ? uuid.hash : [uuid, prefix].hash
+    end
+
+    def inspect
+      "#<#{self.class.name} #{self}>"
+    end
+  end
+end

data/lib/typeid_rails/version.rb

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

data/lib/typeid_rails.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "typeid_rails/version"
+require_relative "typeid_rails/configuration"
+require_relative "typeid_rails/errors"
+require_relative "typeid_rails/base32"
+require_relative "typeid_rails/encoder"
+require_relative "typeid_rails/value"
+require_relative "typeid_rails/registry"
+
+# TypeID identifiers (https://github.com/jetify-com/typeid) for 128-bit UUIDs.
+#
+#   TypeidRails.encode("1cb2589e-342d-4829-958f-e63d8ae58365", prefix: "u")
+#   # => "u_0wp9c9wd1d90msb3z67p5eb0v5"
+module TypeidRails
+  # Loaded on first use so the `sha3` gem stays an optional dependency.
+  autoload :Derivation, "typeid_rails/derivation"
+
+  class << self
+    # @return [String] the "<prefix>_<base32>" rendering of a UUID, or the bare
+    #   suffix when the prefix is empty
+    def encode(uuid, prefix:)
+      Value.from_uuid(uuid, prefix:).to_s
+    end
+
+    # @return [String] a newly minted identifier
+    # @see Value.generate
+    def generate(prefix:, version: config.uuid_version)
+      Value.generate(prefix:, version:).to_s
+    end
+
+    # @return [Value, nil]
+    # @raise [InvalidFormatError] when the string is not a well-formed identifier
+    def parse(string, expected_prefix: nil, fuzzy: config.fuzzy)
+      Value.parse(string, expected_prefix:, fuzzy:)
+    end
+
+    # Extracts the UUID from an identifier, or nil when it is malformed or carries
+    # an unexpected prefix. Use #parse when a malformed input should raise instead.
+    # @return [String, nil]
+    def to_uuid(prefixed_id, expected_prefix: nil, fuzzy: config.fuzzy)
+      return if prefixed_id.nil?
+
+      Value.parse(prefixed_id, expected_prefix:, fuzzy:)&.to_uuid
+    rescue InvalidFormatError
+      nil
+    end
+
+    # Derives a stable identifier from its input parts. Requires the `sha3` gem.
+    # @see Derivation.uuid
+    def derive_uuid(*parts)
+      Derivation.uuid(*parts)
+    end
+  end
+end
+
+require_relative "typeid_rails/railtie" if defined?(::Rails::Railtie)

data/sig/typeid_rails/association_support.rbs

@@ -0,0 +1,29 @@
+module TypeidRails
+  # See the note on _IdentifiableClass: this is the surface of the including class
+  # that the `class_methods` block body uses.
+  interface _AssociationSupportClass
+    def attribute: (Symbol | String name, untyped type) -> untyped
+    def belongs_to: (untyped name, ?untyped? scope, **untyped options) ?{ () -> void } -> untyped
+    def attribute_types: () -> Hash[String, untyped]
+    def reflect_on_association: (untyped name) -> untyped
+    def reflect_on_all_associations: (?Symbol macro) -> Array[untyped]
+  end
+
+  module AssociationSupport : Module, _AssociationSupportClass, _ModelOptionsClass
+    extend ActiveSupport::Concern
+    include ModelOptions
+
+    def belongs_to: (untyped name, ?untyped? scope, **untyped options) ?{ () -> void } -> untyped
+    def configure_foreign_keys!: () -> void
+
+    private
+
+    def configure_foreign_key_for_association: (untyped association) -> void
+    def resolve_association_class: (untyped association) -> untyped
+
+    # Generated by ActiveSupport::Concern; extended into the including class.
+    module ClassMethods
+      def configure_foreign_keys!: () -> void
+    end
+  end
+end

data/sig/typeid_rails/base32.rbs

@@ -0,0 +1,19 @@
+module TypeidRails
+  module Base32
+    ALPHABET: String
+    ALPHABET_CHARS: Array[String]
+    BYTE_SIZE: Integer
+    LENGTH: Integer
+    STRICT_DECODE_MAP: Hash[String, Integer]
+    FUZZY_DECODE_MAP: Hash[String, Integer]
+    SHIFT: Integer
+    MASK: Integer
+
+    def self.encode_bytes: (String bytes) -> String
+    def self.decode_bytes: (String base32, ?fuzzy: bool) -> String
+    def self.valid128?: (untyped string, ?fuzzy: bool) -> bool
+
+    private
+    def self.to_values: (String string, fuzzy: bool) -> Array[Integer]?
+  end
+end

data/sig/typeid_rails/configuration.rbs

@@ -0,0 +1,21 @@
+module TypeidRails
+  class Configuration
+    UUID_VERSIONS: Array[Integer]
+    EQUALITY_MODES: Array[Symbol]
+
+    attr_accessor fuzzy: bool
+    attr_reader uuid_version: Integer
+    attr_reader equality: Symbol
+
+    def initialize: () -> void
+    def uuid_version=: (Integer version) -> Integer
+    def equality=: (Symbol mode) -> Symbol
+    def self.validate_uuid_version!: (untyped version) -> void
+  end
+
+  self.@config: Configuration?
+
+  def self.config: () -> Configuration
+  def self.configure: () { (Configuration) -> void } -> void
+  def self.reset_config!: () -> Configuration
+end

data/sig/typeid_rails/derivation.rbs

@@ -0,0 +1,5 @@
+module TypeidRails
+  module Derivation
+    def self.uuid: (*String parts) -> String
+  end
+end

data/sig/typeid_rails/encoder.rbs

@@ -0,0 +1,11 @@
+module TypeidRails
+  module Encoder
+    NULL_UUID: String
+    UUID_REGEX: Regexp
+
+    def self.encode: (String uuid) -> String
+    def self.decode: (String base32, ?fuzzy: bool) -> String
+    def self.valid?: (untyped string, ?fuzzy: bool) -> bool
+    def self.format_uuid: (String hex) -> String
+  end
+end

data/sig/typeid_rails/errors.rbs

@@ -0,0 +1,29 @@
+module TypeidRails
+  class Error < StandardError
+  end
+
+  class InvalidFormatError < Error
+    attr_reader input: String
+
+    def initialize: (input: String, message: String) -> void
+  end
+
+  class InvalidPrefixError < InvalidFormatError
+  end
+
+  class PrefixMismatchError < Error
+    attr_reader expected: String
+    attr_reader actual: String?
+    attr_reader input: String
+
+    def initialize: (expected: String, actual: String?, input: String) -> void
+  end
+
+  class DuplicatePrefixError < Error
+    attr_reader prefix: String
+    attr_reader existing_model: String
+    attr_reader conflicting_model: String
+
+    def initialize: (prefix: String, existing_model: String, conflicting_model: String) -> void
+  end
+end

data/sig/typeid_rails/identifiable.rbs

@@ -0,0 +1,23 @@
+module TypeidRails
+  # ActiveSupport::Concern's `class_methods` block body is checked as instance methods
+  # of the concern itself, with `self` being the including class. This describes the
+  # part of that class the block relies on.
+  interface _IdentifiableClass
+    def attribute: (Symbol | String name, untyped type) -> untyped
+  end
+
+  module Identifiable : Module, _IdentifiableClass, _ModelOptionsClass
+    extend ActiveSupport::Concern
+    include ModelOptions
+
+    @id_prefix: String?
+
+    # Declares this model's prefix when given one, and reads it back either way.
+    def id_prefix: (?String? prefix, ?strict: bool?, ?fuzzy: bool?) -> String?
+
+    # Generated by ActiveSupport::Concern; extended into the including class.
+    module ClassMethods
+      def id_prefix: (?String? prefix, ?strict: bool?, ?fuzzy: bool?) -> String?
+    end
+  end
+end