sorbet-runtime 0.5.5841

data/lib/types/props/private/parser.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+# typed: false
+
+module T::Props
+  module Private
+    module Parse
+      def parse(source)
+        @current_ruby ||= require_parser(:CurrentRuby)
+        @current_ruby.parse(source)
+      end
+
+      def s(type, *children)
+        @node ||= require_parser(:AST, :Node)
+        @node.new(type, children)
+      end
+
+      private def require_parser(*constants)
+        # This is an optional dependency for sorbet-runtime in general,
+        # but is required here
+        require 'parser/current'
+
+        # Hack to work around the static checker thinking the constant is
+        # undefined
+        cls = Kernel.const_get(:Parser, true)
+        while (const = constants.shift)
+          cls = cls.const_get(const, false)
+        end
+        cls
+      end
+    end
+  end
+end

data/lib/types/props/private/serde_transform.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+# typed: strict
+
+module T::Props
+  module Private
+    module SerdeTransform
+      extend T::Sig
+
+      class Serialize; end
+      private_constant :Serialize
+      class Deserialize; end
+      private_constant :Deserialize
+      ModeType = T.type_alias {T.any(Serialize, Deserialize)}
+      private_constant :ModeType
+
+      module Mode
+        SERIALIZE = T.let(Serialize.new.freeze, Serialize)
+        DESERIALIZE = T.let(Deserialize.new.freeze, Deserialize)
+      end
+
+      NO_TRANSFORM_TYPES = T.let(
+        [TrueClass, FalseClass, NilClass, Symbol, String].freeze,
+        T::Array[Module],
+      )
+      private_constant :NO_TRANSFORM_TYPES
+
+      sig do
+        params(
+          type: T::Types::Base,
+          mode: ModeType,
+          varname: String,
+        )
+        .returns(T.nilable(String))
+        .checked(:never)
+      end
+      def self.generate(type, mode, varname)
+        case type
+        when T::Types::TypedArray
+          inner = generate(type.type, mode, 'v')
+          if inner.nil?
+            "#{varname}.dup"
+          else
+            "#{varname}.map {|v| #{inner}}"
+          end
+        when T::Types::TypedSet
+          inner = generate(type.type, mode, 'v')
+          if inner.nil?
+            "#{varname}.dup"
+          else
+            "Set.new(#{varname}) {|v| #{inner}}"
+          end
+        when T::Types::TypedHash
+          keys = generate(type.keys, mode, 'k')
+          values = generate(type.values, mode, 'v')
+          if keys && values
+            "#{varname}.each_with_object({}) {|(k,v),h| h[#{keys}] = #{values}}"
+          elsif keys
+            "#{varname}.transform_keys {|k| #{keys}}"
+          elsif values
+            "#{varname}.transform_values {|v| #{values}}"
+          else
+            "#{varname}.dup"
+          end
+        when T::Types::Simple
+          raw = type.raw_type
+          if NO_TRANSFORM_TYPES.any? {|cls| raw <= cls}
+            nil
+          elsif raw <= Float
+            case mode
+            when Deserialize then "#{varname}.to_f"
+            when Serialize then nil
+            else T.absurd(mode)
+            end
+          elsif raw <= Numeric
+            nil
+          elsif raw < T::Props::Serializable
+            handle_serializable_subtype(varname, raw, mode)
+          elsif raw.singleton_class < T::Props::CustomType
+            handle_custom_type(varname, T.unsafe(raw), mode)
+          elsif T::Configuration.scalar_types.include?(raw.name)
+            # It's a bit of a hack that this is separate from NO_TRANSFORM_TYPES
+            # and doesn't check inheritance (like `T::Props::CustomType.scalar_type?`
+            # does), but it covers the main use case (pay-server's custom `Boolean`
+            # module) without either requiring `T::Configuration.scalar_types` to
+            # accept modules instead of strings (which produces load-order issues
+            # and subtle behavior changes) or eating the performance cost of doing
+            # an inheritance check by manually crawling a class hierarchy and doing
+            # string comparisons.
+            nil
+          else
+            "T::Props::Utils.deep_clone_object(#{varname})"
+          end
+        when T::Types::Union
+          non_nil_type = T::Utils.unwrap_nilable(type)
+          if non_nil_type
+            inner = generate(non_nil_type, mode, varname)
+            if inner.nil?
+              nil
+            else
+              "#{varname}.nil? ? nil : #{inner}"
+            end
+          else
+            # Handle, e.g., T::Boolean
+            if type.types.all? {|t| generate(t, mode, varname).nil?}
+              nil
+            else
+              # We currently deep_clone_object if the type was T.any(Integer, Float).
+              # When we get better support for union types (maybe this specific
+              # union type, because it would be a replacement for
+              # Chalk::ODM::DeprecatedNumemric), we could opt to special case
+              # this union to have no specific serde transform (the only reason
+              # why Float has a special case is because round tripping through
+              # JSON might normalize Floats to Integers)
+              "T::Props::Utils.deep_clone_object(#{varname})"
+            end
+          end
+        when T::Types::Intersection
+          dynamic_fallback = "T::Props::Utils.deep_clone_object(#{varname})"
+
+          # Transformations for any members of the intersection type where we
+          # know what we need to do and did not have to fall back to the
+          # dynamic deep clone method.
+          #
+          # NB: This deliberately does include `nil`, which means we know we
+          # don't need to do any transforming.
+          inner_known = type.types
+            .map {|t| generate(t, mode, varname)}
+            .reject {|t| t == dynamic_fallback}
+            .uniq
+
+          if inner_known.size != 1
+            # If there were no cases where we could tell what we need to do,
+            # e.g. if this is `T.all(SomethingWeird, WhoKnows)`, just use the
+            # dynamic fallback.
+            #
+            # If there were multiple cases and they weren't consistent, e.g.
+            # if this is `T.all(String, T::Array[Integer])`, the type is probably
+            # bogus/uninhabited, but use the dynamic fallback because we still
+            # don't have a better option, and this isn't the place to raise that
+            # error.
+            dynamic_fallback
+          else
+            # This is probably something like `T.all(String, SomeMarker)` or
+            # `T.all(SomeEnum, T.enum(SomeEnum::FOO))` and we should treat it
+            # like String or SomeEnum even if we don't know what to do with
+            # the rest of the type.
+            inner_known.first
+          end
+        when T::Types::Enum
+          generate(T::Utils.lift_enum(type), mode, varname)
+        else
+          "T::Props::Utils.deep_clone_object(#{varname})"
+        end
+      end
+
+      sig {params(varname: String, type: Module, mode: ModeType).returns(String).checked(:never)}
+      private_class_method def self.handle_serializable_subtype(varname, type, mode)
+        case mode
+        when Serialize
+          "#{varname}.serialize(strict)"
+        when Deserialize
+          type_name = T.must(module_name(type))
+          "#{type_name}.from_hash(#{varname})"
+        else
+          T.absurd(mode)
+        end
+      end
+
+      sig {params(varname: String, type: Module, mode: ModeType).returns(String).checked(:never)}
+      private_class_method def self.handle_custom_type(varname, type, mode)
+        case mode
+        when Serialize
+          "T::Props::CustomType.checked_serialize(#{varname})"
+        when Deserialize
+          type_name = T.must(module_name(type))
+          "#{type_name}.deserialize(#{varname})"
+        else
+          T.absurd(mode)
+        end
+      end
+
+      # Guard against overrides of `name` or `to_s`
+      MODULE_NAME = T.let(Module.instance_method(:name), UnboundMethod)
+      private_constant :MODULE_NAME
+
+      sig {params(type: Module).returns(T.nilable(String)).checked(:never)}
+      private_class_method def self.module_name(type)
+        MODULE_NAME.bind(type).call
+      end
+    end
+  end
+end

data/lib/types/props/private/serializer_generator.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+# typed: strict
+
+module T::Props
+  module Private
+
+    # Generates a specialized `serialize` implementation for a subclass of
+    # T::Props::Serializable.
+    #
+    # The basic idea is that we analyze the props and for each prop, generate
+    # the simplest possible logic as a block of Ruby source, so that we don't
+    # pay the cost of supporting types like T:::Hash[CustomType, SubstructType]
+    # when serializing a simple Integer. Then we join those together,
+    # with a little shared logic to be able to detect when we get input keys
+    # that don't match any prop.
+    module SerializerGenerator
+      extend T::Sig
+
+      sig do
+        params(
+          props: T::Hash[Symbol, T::Hash[Symbol, T.untyped]],
+        )
+        .returns(String)
+        .checked(:never)
+      end
+      def self.generate(props)
+        stored_props = props.reject {|_, rules| rules[:dont_store]}
+        parts = stored_props.map do |prop, rules|
+          # All of these strings should already be validated (directly or
+          # indirectly) in `validate_prop_name`, so we don't bother with a nice
+          # error message, but we double check here to prevent a refactoring
+          # from introducing a security vulnerability.
+          raise unless T::Props::Decorator::SAFE_NAME.match?(prop.to_s)
+
+          hash_key = rules.fetch(:serialized_form)
+          raise unless T::Props::Decorator::SAFE_NAME.match?(hash_key)
+
+          ivar_name = rules.fetch(:accessor_key).to_s
+          raise unless ivar_name.start_with?('@') && T::Props::Decorator::SAFE_NAME.match?(ivar_name[1..-1])
+
+          transformed_val = SerdeTransform.generate(
+            T::Utils::Nilable.get_underlying_type_object(rules.fetch(:type_object)),
+            SerdeTransform::Mode::SERIALIZE,
+            ivar_name
+          ) || ivar_name
+
+          nil_asserter =
+            if rules[:fully_optional]
+              ''
+            else
+              "required_prop_missing_from_serialize(#{prop.inspect}) if strict"
+            end
+
+          # Don't serialize values that are nil to save space (both the
+          # nil value itself and the field name in the serialized BSON
+          # document)
+          <<~RUBY
+            if #{ivar_name}.nil?
+              #{nil_asserter}
+            else
+              h[#{hash_key.inspect}] = #{transformed_val}
+            end
+          RUBY
+        end
+
+        <<~RUBY
+          def __t_props_generated_serialize(strict)
+            h = {}
+            #{parts.join("\n\n")}
+            h
+          end
+        RUBY
+      end
+    end
+  end
+end
+

data/lib/types/props/private/setter_factory.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+# typed: strict
+
+module T::Props
+  module Private
+    module SetterFactory
+      extend T::Sig
+
+      SetterProc = T.type_alias {T.proc.params(val: T.untyped).void}
+      ValidateProc = T.type_alias {T.proc.params(prop: Symbol, value: T.untyped).void}
+
+      sig do
+        params(
+          klass: T.all(Module, T::Props::ClassMethods),
+          prop: Symbol,
+          rules: T::Hash[Symbol, T.untyped]
+        )
+        .returns(SetterProc)
+        .checked(:never)
+      end
+      def self.build_setter_proc(klass, prop, rules)
+        # Our nil check works differently than a simple T.nilable for various
+        # reasons (including the `raise_on_nil_write` setting and the existence
+        # of defaults & factories), so unwrap any T.nilable and do a check
+        # manually.
+        non_nil_type = T::Utils::Nilable.get_underlying_type_object(rules.fetch(:type_object))
+        accessor_key = rules.fetch(:accessor_key)
+        validate = rules[:setter_validate]
+
+        # It seems like a bug that this affects the behavior of setters, but
+        # some existing code relies on this behavior
+        has_explicit_nil_default = rules.key?(:default) && rules.fetch(:default).nil?
+
+        # Use separate methods in order to ensure that we only close over necessary
+        # variables
+        if !T::Props::Utils.need_nil_write_check?(rules) || has_explicit_nil_default
+          nilable_proc(prop, accessor_key, non_nil_type, klass, validate)
+        else
+          non_nil_proc(prop, accessor_key, non_nil_type, klass, validate)
+        end
+      end
+
+      sig do
+        params(
+          prop: Symbol,
+          accessor_key: Symbol,
+          non_nil_type: T::Types::Base,
+          klass: T.all(Module, T::Props::ClassMethods),
+          validate: T.nilable(ValidateProc)
+        )
+        .returns(SetterProc)
+      end
+      private_class_method def self.non_nil_proc(prop, accessor_key, non_nil_type, klass, validate)
+        proc do |val|
+          if non_nil_type.valid?(val)
+            if validate
+              validate.call(prop, val)
+            end
+            instance_variable_set(accessor_key, val)
+          else
+            T::Props::Private::SetterFactory.raise_pretty_error(
+              klass,
+              prop,
+              non_nil_type,
+              val,
+            )
+            instance_variable_set(accessor_key, val)
+          end
+        end
+      end
+
+      sig do
+        params(
+          prop: Symbol,
+          accessor_key: Symbol,
+          non_nil_type: T::Types::Base,
+          klass: T.all(Module, T::Props::ClassMethods),
+          validate: T.nilable(ValidateProc),
+        )
+        .returns(SetterProc)
+      end
+      private_class_method def self.nilable_proc(prop, accessor_key, non_nil_type, klass, validate)
+        proc do |val|
+          if val.nil?
+            instance_variable_set(accessor_key, nil)
+          elsif non_nil_type.valid?(val)
+            if validate
+              validate.call(prop, val)
+            end
+            instance_variable_set(accessor_key, val)
+          else
+            T::Props::Private::SetterFactory.raise_pretty_error(
+              klass,
+              prop,
+              non_nil_type,
+              val,
+            )
+            instance_variable_set(accessor_key, val)
+          end
+        end
+      end
+
+      sig do
+        params(
+          klass: T.all(Module, T::Props::ClassMethods),
+          prop: Symbol,
+          type: T.any(T::Types::Base, Module),
+          val: T.untyped,
+        )
+        .void
+      end
+      def self.raise_pretty_error(klass, prop, type, val)
+        base_message = "Can't set #{klass.name}.#{prop} to #{val.inspect} (instance of #{val.class}) - need a #{type}"
+
+        pretty_message = "Parameter '#{prop}': #{base_message}\n"
+        caller_loc = caller_locations&.find {|l| !l.to_s.include?('sorbet-runtime/lib/types/props')}
+        if caller_loc
+          pretty_message += "Caller: #{caller_loc.path}:#{caller_loc.lineno}\n"
+        end
+
+        T::Configuration.call_validation_error_handler(
+          nil,
+          message: base_message,
+          pretty_message: pretty_message,
+          kind: 'Parameter',
+          name: prop,
+          type: type,
+          value: val,
+          location: caller_loc,
+        )
+      end
+    end
+  end
+end

data/lib/types/props/serializable.rb

@@ -0,0 +1,330 @@
+# frozen_string_literal: true
+# typed: false
+
+module T::Props::Serializable
+  include T::Props::Plugin
+  # Required because we have special handling for `optional: false`
+  include T::Props::Optional
+  # Required because we have special handling for extra_props
+  include T::Props::PrettyPrintable
+
+  # Serializes this object to a hash, suitable for conversion to
+  # JSON/BSON.
+  #
+  # @param strict [T::Boolean] (true) If false, do not raise an
+  #   exception if this object has mandatory props with missing
+  #   values.
+  # @return [Hash] A serialization of this object.
+  def serialize(strict=true)
+    begin
+      h = __t_props_generated_serialize(strict)
+    rescue => e
+      msg = self.class.decorator.message_with_generated_source_context(
+        e,
+        :__t_props_generated_serialize,
+        :generate_serialize_source
+      )
+      if msg
+        begin
+          raise e.class.new(msg)
+        rescue ArgumentError
+          raise TypeError.new(msg)
+        end
+      else
+        raise
+      end
+    end
+
+    h.merge!(@_extra_props) if @_extra_props
+    h
+  end
+
+  private def __t_props_generated_serialize(strict)
+    # No-op; will be overridden if there are any props.
+    #
+    # To see the definition for class `Foo`, run `Foo.decorator.send(:generate_serialize_source)`
+    {}
+  end
+
+  # Populates the property values on this object with the values
+  # from a hash. In general, prefer to use {.from_hash} to construct
+  # a new instance, instead of loading into an existing instance.
+  #
+  # @param hash [Hash<String, Object>] The hash to take property
+  #  values from.
+  # @param strict [T::Boolean] (false) If true, raise an exception if
+  #  the hash contains keys that do not correspond to any known
+  #  props on this instance.
+  # @return [void]
+  def deserialize(hash, strict=false)
+    begin
+      hash_keys_matching_props = __t_props_generated_deserialize(hash)
+    rescue => e
+      msg = self.class.decorator.message_with_generated_source_context(
+        e,
+        :__t_props_generated_deserialize,
+        :generate_deserialize_source
+      )
+      if msg
+        begin
+          raise e.class.new(msg)
+        rescue ArgumentError
+          raise TypeError.new(msg)
+        end
+      else
+        raise
+      end
+    end
+
+    if hash.size > hash_keys_matching_props
+      serialized_forms = self.class.decorator.prop_by_serialized_forms
+      extra = hash.reject {|k, _| serialized_forms.key?(k)}
+
+      # `extra` could still be empty here if the input matches a `dont_store` prop;
+      # historically, we just ignore those
+      if !extra.empty?
+        if strict
+          raise "Unknown properties for #{self.class.name}: #{extra.keys.inspect}"
+        else
+          @_extra_props = extra
+        end
+      end
+    end
+  end
+
+  private def __t_props_generated_deserialize(hash)
+    # No-op; will be overridden if there are any props.
+    #
+    # To see the definition for class `Foo`, run `Foo.decorator.send(:generate_deserialize_source)`
+    0
+  end
+
+  # with() will clone the old object to the new object and merge the specified props to the new object.
+  def with(changed_props)
+    with_existing_hash(changed_props, existing_hash: self.serialize)
+  end
+
+  private def recursive_stringify_keys(obj)
+    if obj.is_a?(Hash)
+      new_obj = obj.class.new
+      obj.each do |k, v|
+        new_obj[k.to_s] = recursive_stringify_keys(v)
+      end
+    elsif obj.is_a?(Array)
+      new_obj = obj.map {|v| recursive_stringify_keys(v)}
+    else
+      new_obj = obj
+    end
+    new_obj
+  end
+
+  private def with_existing_hash(changed_props, existing_hash:)
+    serialized = existing_hash
+    new_val = self.class.from_hash(serialized.merge(recursive_stringify_keys(changed_props)))
+    old_extra = self.instance_variable_get(:@_extra_props) # rubocop:disable PrisonGuard/NoLurkyInstanceVariableAccess
+    new_extra = new_val.instance_variable_get(:@_extra_props) # rubocop:disable PrisonGuard/NoLurkyInstanceVariableAccess
+    if old_extra != new_extra
+      difference =
+        if old_extra
+          new_extra.reject {|k, v| old_extra[k] == v}
+        else
+          new_extra
+        end
+      raise ArgumentError.new("Unexpected arguments: input(#{changed_props}), unexpected(#{difference})")
+    end
+    new_val
+  end
+
+  # Asserts if this property is missing during strict serialize
+  private def required_prop_missing_from_serialize(prop)
+    if @_required_props_missing_from_deserialize&.include?(prop)
+      # If the prop was already missing during deserialization, that means the application
+      # code already had to deal with a nil value, which means we wouldn't be accomplishing
+      # much by raising here (other than causing an unnecessary breakage).
+      T::Configuration.log_info_handler(
+        "chalk-odm: missing required property in serialize",
+        prop: prop, class: self.class.name, id: self.class.decorator.get_id(self)
+      )
+    else
+      raise TypeError.new("#{self.class.name}.#{prop} not set for non-optional prop")
+    end
+  end
+
+  # Marks this property as missing during deserialize
+  private def required_prop_missing_from_deserialize(prop)
+    @_required_props_missing_from_deserialize ||= Set[]
+    @_required_props_missing_from_deserialize << prop
+    nil
+  end
+end
+
+
+##############################################
+
+# NB: This must stay in the same file where T::Props::Serializable is defined due to
+# T::Props::Decorator#apply_plugin; see https://git.corp.stripe.com/stripe-internal/pay-server/blob/fc7f15593b49875f2d0499ffecfd19798bac05b3/chalk/odm/lib/chalk-odm/document_decorator.rb#L716-L717
+module T::Props::Serializable::DecoratorMethods
+  include T::Props::HasLazilySpecializedMethods::DecoratorMethods
+
+  VALID_RULE_KEYS = {dont_store: true, name: true, raise_on_nil_write: true}.freeze
+  private_constant :VALID_RULE_KEYS
+
+  def valid_rule_key?(key)
+    super || VALID_RULE_KEYS[key]
+  end
+
+  def required_props
+    @class.props.select {|_, v| T::Props::Utils.required_prop?(v)}.keys
+  end
+
+  def prop_dont_store?(prop); prop_rules(prop)[:dont_store]; end
+  def prop_by_serialized_forms; @class.prop_by_serialized_forms; end
+
+  def from_hash(hash, strict=false)
+    raise ArgumentError.new("#{hash.inspect} provided to from_hash") if !(hash && hash.is_a?(Hash))
+
+    i = @class.allocate
+    i.deserialize(hash, strict)
+
+    i
+  end
+
+  def prop_serialized_form(prop)
+    prop_rules(prop)[:serialized_form]
+  end
+
+  def serialized_form_prop(serialized_form)
+    prop_by_serialized_forms[serialized_form.to_s] || raise("No such serialized form: #{serialized_form.inspect}")
+  end
+
+  def add_prop_definition(prop, rules)
+    rules[:serialized_form] = rules.fetch(:name, prop.to_s)
+    res = super
+    prop_by_serialized_forms[rules[:serialized_form]] = prop
+    enqueue_lazy_method_definition!(:__t_props_generated_serialize) {generate_serialize_source}
+    enqueue_lazy_method_definition!(:__t_props_generated_deserialize) {generate_deserialize_source}
+    res
+  end
+
+  private def generate_serialize_source
+    T::Props::Private::SerializerGenerator.generate(props)
+  end
+
+  private def generate_deserialize_source
+    T::Props::Private::DeserializerGenerator.generate(
+      props,
+      props_with_defaults || {},
+    )
+  end
+
+  def message_with_generated_source_context(error, generated_method, generate_source_method)
+    line_label = error.backtrace.find {|l| l.end_with?("in `#{generated_method}'")}
+    return unless line_label
+
+    line_num = line_label.split(':')[1]&.to_i
+    return unless line_num
+
+    source_lines = self.send(generate_source_method).split("\n")
+    previous_blank = source_lines[0...line_num].rindex(&:empty?) || 0
+    next_blank = line_num + (source_lines[line_num..-1]&.find_index(&:empty?) || 0)
+    context = "  " + source_lines[(previous_blank + 1)...(next_blank)].join("\n  ")
+    <<~MSG
+      Error in #{decorated_class.name}##{generated_method}: #{error.message}
+      at line #{line_num-previous_blank-1} in:
+      #{context}
+    MSG
+  end
+
+  def raise_nil_deserialize_error(hkey)
+    msg = "Tried to deserialize a required prop from a nil value. It's "\
+      "possible that a nil value exists in the database, so you should "\
+      "provide a `default: or factory:` for this prop (see go/optional "\
+      "for more details). If this is already the case, you probably "\
+      "omitted a required prop from the `fields:` option when doing a "\
+      "partial load."
+    storytime = {prop: hkey, klass: decorated_class.name}
+
+    # Notify the model owner if it exists, and always notify the API owner.
+    begin
+      if defined?(Opus) && defined?(Opus::Ownership) && decorated_class < Opus::Ownership
+        T::Configuration.hard_assert_handler(
+          msg,
+          storytime: storytime,
+          project: decorated_class.get_owner
+        )
+      end
+    ensure
+      T::Configuration.hard_assert_handler(msg, storytime: storytime)
+    end
+  end
+
+  def prop_validate_definition!(name, cls, rules, type)
+    result = super
+
+    if (rules_name = rules[:name])
+      unless rules_name.is_a?(String)
+        raise ArgumentError.new("Invalid name in prop #{@class.name}.#{name}: #{rules_name.inspect}")
+      end
+
+      validate_prop_name(rules_name)
+    end
+
+    if !rules[:raise_on_nil_write].nil? && rules[:raise_on_nil_write] != true
+        raise ArgumentError.new("The value of `raise_on_nil_write` if specified must be `true` (given: #{rules[:raise_on_nil_write]}).")
+    end
+
+    result
+  end
+
+  def get_id(instance)
+    prop = prop_by_serialized_forms['_id']
+    if prop
+      get(instance, prop)
+    else
+      nil
+    end
+  end
+
+  EMPTY_EXTRA_PROPS = {}.freeze
+  private_constant :EMPTY_EXTRA_PROPS
+
+  def extra_props(instance)
+    instance.instance_variable_get(:@_extra_props) || EMPTY_EXTRA_PROPS
+  end
+
+  # @override T::Props::PrettyPrintable
+  private def inspect_instance_components(instance, multiline:, indent:)
+    if (extra_props = extra_props(instance)) && !extra_props.empty?
+      pretty_kvs = extra_props.map {|k, v| [k.to_sym, v.inspect]}
+      extra = join_props_with_pretty_values(pretty_kvs, multiline: false)
+      super + ["@_extra_props=<#{extra}>"]
+    else
+      super
+    end
+  end
+end
+
+
+##############################################
+
+
+# NB: This must stay in the same file where T::Props::Serializable is defined due to
+# T::Props::Decorator#apply_plugin; see https://git.corp.stripe.com/stripe-internal/pay-server/blob/fc7f15593b49875f2d0499ffecfd19798bac05b3/chalk/odm/lib/chalk-odm/document_decorator.rb#L716-L717
+module T::Props::Serializable::ClassMethods
+  def prop_by_serialized_forms; @prop_by_serialized_forms ||= {}; end
+
+  # @!method self.from_hash(hash, strict)
+  #
+  # Allocate a new instance and call {#deserialize} to load a new
+  # object from a hash.
+  # @return [Serializable]
+  def from_hash(hash, strict=false)
+    self.decorator.from_hash(hash, strict)
+  end
+
+  # Equivalent to {.from_hash} with `strict` set to true.
+  # @return [Serializable]
+  def from_hash!(hash)
+    self.decorator.from_hash(hash, true)
+  end
+end