terminal-shop 1.7.0 → 2.0.0

data/lib/terminal-shop/base_model.rb

@@ -1,41 +1,35 @@
 # frozen_string_literal: true
 
 module TerminalShop
-  # @private
-  #
-  # @abstract
-  #
+  # @api private
   module Converter
     # rubocop:disable Lint/UnusedMethodArgument
 
-    # @private
+    # @api private
     #
     # @param value [Object]
     #
     # @return [Object]
-    #
     def coerce(value) = value
 
-    # @private
+    # @api private
     #
     # @param value [Object]
     #
     # @return [Object]
-    #
     def dump(value) = value
 
-    # @private
+    # @api private
     #
     # @param value [Object]
     #
     # @return [Array(true, Object, nil), Array(false, Boolean, Integer)]
-    #
     def try_strict_coerce(value) = (raise NotImplementedError)
 
     # rubocop:enable Lint/UnusedMethodArgument
 
     class << self
-      # @private
+      # @api private
       #
       # @param spec [Hash{Symbol=>Object}, Proc, TerminalShop::Converter, Class] .
       #
@@ -48,14 +42,13 @@ module TerminalShop
       #   @option spec [Boolean] :"nil?"
       #
       # @return [Proc]
-      #
       def type_info(spec)
         case spec
         in Hash
           type_info(spec.slice(:const, :enum, :union).first&.last)
         in Proc
           spec
-        in TerminalShop::Converter | Class | Symbol
+        in TerminalShop::Converter | Module | Symbol
           -> { spec }
         in true | false
           -> { TerminalShop::BooleanModel }
@@ -64,7 +57,7 @@ module TerminalShop
         end
       end
 
-      # @private
+      # @api private
       #
       # Based on `target`, transform `value` into `target`, to the extent possible:
       #
@@ -77,7 +70,6 @@ module TerminalShop
       # @param value [Object]
       #
       # @return [Object]
-      #
       def coerce(target, value)
         case target
         in TerminalShop::Converter
@@ -89,7 +81,7 @@ module TerminalShop
           else
             value
           end
-        in Class
+        in Module
           case target
           in -> { _1 <= NilClass }
             nil
@@ -111,13 +103,12 @@ module TerminalShop
         end
       end
 
-      # @private
+      # @api private
       #
       # @param target [TerminalShop::Converter, Class]
       # @param value [Object]
       #
       # @return [Object]
-      #
       def dump(target, value)
         case target
         in TerminalShop::Converter
@@ -127,7 +118,7 @@ module TerminalShop
         end
       end
 
-      # @private
+      # @api private
       #
       # The underlying algorithm for computing maximal compatibility is subject to
       #   future improvements.
@@ -142,7 +133,6 @@ module TerminalShop
       # @param value [Object]
       #
       # @return [Object]
-      #
       def try_strict_coerce(target, value)
         case target
         in TerminalShop::Converter
@@ -154,7 +144,7 @@ module TerminalShop
           else
             [false, false, 0]
           end
-        in Class
+        in Module
           case [target, value]
           in [-> { _1 <= NilClass }, _]
             [true, nil, value.nil? ? 1 : 0]
@@ -182,7 +172,7 @@ module TerminalShop
     end
   end
 
-  # @private
+  # @api private
   #
   # @abstract
   #
@@ -192,45 +182,38 @@ module TerminalShop
 
     # rubocop:disable Lint/UnusedMethodArgument
 
-    private_class_method :new
-
     # @param other [Object]
     #
     # @return [Boolean]
-    #
     def self.===(other) = true
 
     # @param other [Object]
     #
     # @return [Boolean]
-    #
     def self.==(other) = other.is_a?(Class) && other <= TerminalShop::Unknown
 
     class << self
       # @!parse
-      #   # @private
+      #   # @api private
       #   #
       #   # @param value [Object]
       #   #
       #   # @return [Object]
-      #   #
       #   def coerce(value) = super
 
       # @!parse
-      #   # @private
+      #   # @api private
       #   #
       #   # @param value [Object]
       #   #
       #   # @return [Object]
-      #   #
       #   def dump(value) = super
 
-      # @private
+      # @api private
       #
       # @param value [Object]
       #
       # @return [Array(true, Object, nil), Array(false, Boolean, Integer)]
-      #
       def try_strict_coerce(value)
         # prevent unknown variant from being chosen during the first coercion pass
         [false, true, 0]
@@ -240,7 +223,7 @@ module TerminalShop
     # rubocop:enable Lint/UnusedMethodArgument
   end
 
-  # @private
+  # @api private
   #
   # @abstract
   #
@@ -248,45 +231,38 @@ module TerminalShop
   class BooleanModel
     extend TerminalShop::Converter
 
-    private_class_method :new
-
     # @param other [Object]
     #
     # @return [Boolean]
-    #
     def self.===(other) = other == true || other == false
 
     # @param other [Object]
     #
     # @return [Boolean]
-    #
     def self.==(other) = other.is_a?(Class) && other <= TerminalShop::BooleanModel
 
     class << self
       # @!parse
-      #   # @private
+      #   # @api private
       #   #
       #   # @param value [Boolean, Object]
       #   #
       #   # @return [Boolean, Object]
-      #   #
       #   def coerce(value) = super
 
       # @!parse
-      #   # @private
+      #   # @api private
       #   #
       #   # @param value [Boolean, Object]
       #   #
       #   # @return [Boolean, Object]
-      #   #
       #   def dump(value) = super
 
-      # @private
+      # @api private
       #
       # @param value [Object]
       #
       # @return [Array(true, Object, nil), Array(false, Boolean, Integer)]
-      #
       def try_strict_coerce(value)
         case value
         in true | false
@@ -298,9 +274,7 @@ module TerminalShop
     end
   end
 
-  # @private
-  #
-  # @abstract
+  # @api private
   #
   # A value from among a specified list of options. OpenAPI enum values map to Ruby
   #   values in the SDK as follows:
@@ -314,211 +288,186 @@ module TerminalShop
   #   values safely.
   #
   # @example
-  # ```ruby
-  # # `region` is a `TerminalShop::Models::Region`
-  # case region
-  # when TerminalShop::Models::Region::EU
-  #   # ...
-  # when TerminalShop::Models::Region::NA
-  #   # ...
-  # else
-  #   # ...
-  # end
-  # ```
+  #   # `region` is a `TerminalShop::Models::Region`
+  #   case region
+  #   when TerminalShop::Models::Region::EU
+  #     # ...
+  #   when TerminalShop::Models::Region::NA
+  #     # ...
+  #   else
+  #     puts(region)
+  #   end
   #
   # @example
-  # ```ruby
-  # case region
-  # in :eu
-  #   # ...
-  # in :na
-  #   # ...
-  # else
-  #   # ...
-  # end
-  # ```
-  class Enum
-    extend TerminalShop::Converter
-
-    class << self
-      # All of the valid Symbol values for this enum.
-      #
-      # @return [Array<NilClass, Boolean, Integer, Float, Symbol>]
-      #
-      def values = (@values ||= constants.map { const_get(_1) })
+  #   case region
+  #   in :eu
+  #     # ...
+  #   in :na
+  #     # ...
+  #   else
+  #     puts(region)
+  #   end
+  module Enum
+    include TerminalShop::Converter
 
-      # @private
-      #
-      # Guard against thread safety issues by instantiating `@values`.
-      #
-      private def finalize! = values
-    end
+    # All of the valid Symbol values for this enum.
+    #
+    # @return [Array<NilClass, Boolean, Integer, Float, Symbol>]
+    def values = (@values ||= constants.map { const_get(_1) })
 
-    private_class_method :new
+    # @api private
+    #
+    # Guard against thread safety issues by instantiating `@values`.
+    private def finalize! = values
 
     # @param other [Object]
     #
     # @return [Boolean]
-    #
-    def self.===(other) = values.include?(other)
+    def ===(other) = values.include?(other)
 
     # @param other [Object]
     #
     # @return [Boolean]
-    #
-    def self.==(other)
-      other.is_a?(Class) && other <= TerminalShop::Enum && other.values.to_set == values.to_set
+    def ==(other)
+      other.is_a?(Module) && other.singleton_class.ancestors.include?(TerminalShop::Enum) && other.values.to_set == values.to_set
     end
 
-    class << self
-      # @private
-      #
-      # @param value [String, Symbol, Object]
-      #
-      # @return [Symbol, Object]
-      #
-      def coerce(value)
-        case value
-        in Symbol | String if values.include?(val = value.to_sym)
-          val
-        else
-          value
-        end
+    # @api private
+    #
+    # @param value [String, Symbol, Object]
+    #
+    # @return [Symbol, Object]
+    def coerce(value)
+      case value
+      in Symbol | String if values.include?(val = value.to_sym)
+        val
+      else
+        value
       end
+    end
 
-      # @!parse
-      #   # @private
-      #   #
-      #   # @param value [Symbol, Object]
-      #   #
-      #   # @return [Symbol, Object]
-      #   #
-      #   def dump(value) = super
+    # @!parse
+    #   # @api private
+    #   #
+    #   # @param value [Symbol, Object]
+    #   #
+    #   # @return [Symbol, Object]
+    #   def dump(value) = super
 
-      # @private
-      #
-      # @param value [Object]
-      #
-      # @return [Array(true, Object, nil), Array(false, Boolean, Integer)]
-      #
-      def try_strict_coerce(value)
-        return [true, value, 1] if values.include?(value)
+    # @api private
+    #
+    # @param value [Object]
+    #
+    # @return [Array(true, Object, nil), Array(false, Boolean, Integer)]
+    def try_strict_coerce(value)
+      return [true, value, 1] if values.include?(value)
 
-        case value
-        in Symbol | String if values.include?(val = value.to_sym)
-          [true, val, 1]
+      case value
+      in Symbol | String if values.include?(val = value.to_sym)
+        [true, val, 1]
+      else
+        case [value, values.first]
+        in [true | false, true | false] | [Integer, Integer] | [Symbol | String, Symbol]
+          [false, true, 0]
         else
-          case [value, values.first]
-          in [true | false, true | false] | [Integer, Integer] | [Symbol | String, Symbol]
-            [false, true, 0]
-          else
-            [false, false, 0]
-          end
+          [false, false, 0]
         end
       end
     end
   end
 
-  # @private
-  #
-  # @abstract
-  #
-  class Union
-    extend TerminalShop::Converter
+  # @api private
+  module Union
+    include TerminalShop::Converter
 
-    class << self
-      # @private
-      #
-      # All of the specified variant info for this union.
-      #
-      # @return [Array<Array(Symbol, Proc)>]
-      #
-      private def known_variants = (@known_variants ||= [])
+    # @api private
+    #
+    # All of the specified variant info for this union.
+    #
+    # @return [Array<Array(Symbol, Proc)>]
+    private def known_variants = (@known_variants ||= [])
 
-      # @private
-      #
-      # All of the specified variants for this union.
-      #
-      # @return [Array<Array(Symbol, Object)>]
-      #
-      protected def variants
-        @known_variants.map { |key, variant_fn| [key, variant_fn.call] }
+    # @api private
+    #
+    # @return [Array<Array(Symbol, Object)>]
+    protected def derefed_variants
+      @known_variants.map { |key, variant_fn| [key, variant_fn.call] }
+    end
+
+    # All of the specified variants for this union.
+    #
+    # @return [Array<Object>]
+    def variants
+      derefed_variants.map(&:last)
+    end
+
+    # @api private
+    #
+    # @param property [Symbol]
+    private def discriminator(property)
+      case property
+      in Symbol
+        @discriminator = property
       end
+    end
 
-      # @private
-      #
-      # @param property [Symbol]
-      #
-      private def discriminator(property)
-        case property
+    # @api private
+    #
+    # @param key [Symbol, Hash{Symbol=>Object}, Proc, TerminalShop::Converter, Class]
+    #
+    # @param spec [Hash{Symbol=>Object}, Proc, TerminalShop::Converter, Class] .
+    #
+    #   @option spec [NilClass, TrueClass, FalseClass, Integer, Float, Symbol] :const
+    #
+    #   @option spec [Proc] :enum
+    #
+    #   @option spec [Proc] :union
+    #
+    #   @option spec [Boolean] :"nil?"
+    private def variant(key, spec = nil)
+      variant_info =
+        case key
         in Symbol
-          @discriminator = property
+          [key, TerminalShop::Converter.type_info(spec)]
+        in Proc | TerminalShop::Converter | Module | Hash
+          [nil, TerminalShop::Converter.type_info(key)]
         end
-      end
 
-      # @private
-      #
-      # @param key [Symbol, Hash{Symbol=>Object}, Proc, TerminalShop::Converter, Class]
-      #
-      # @param spec [Hash{Symbol=>Object}, Proc, TerminalShop::Converter, Class] .
-      #
-      #   @option spec [NilClass, TrueClass, FalseClass, Integer, Float, Symbol] :const
-      #
-      #   @option spec [Proc] :enum
-      #
-      #   @option spec [Proc] :union
-      #
-      #   @option spec [Boolean] :"nil?"
-      #
-      private def variant(key, spec = nil)
-        variant_info =
-          case key
-          in Symbol
-            [key, TerminalShop::Converter.type_info(spec)]
-          in Proc | TerminalShop::Converter | Class | Hash
-            [nil, TerminalShop::Converter.type_info(key)]
-          end
-
-        known_variants << variant_info
-      end
+      known_variants << variant_info
+    end
 
-      # @private
-      #
-      # @param value [Object]
-      #
-      # @return [TerminalShop::Converter, Class, nil]
-      #
-      private def resolve_variant(value)
-        case [@discriminator, value]
-        in [_, TerminalShop::BaseModel]
-          value.class
-        in [Symbol, Hash]
-          key =
-            if value.key?(@discriminator)
-              value.fetch(@discriminator)
-            elsif value.key?((discriminator = @discriminator.to_s))
-              value.fetch(discriminator)
-            end
+    # @api private
+    #
+    # @param value [Object]
+    #
+    # @return [TerminalShop::Converter, Class, nil]
+    private def resolve_variant(value)
+      case [@discriminator, value]
+      in [_, TerminalShop::BaseModel]
+        value.class
+      in [Symbol, Hash]
+        key =
+          if value.key?(@discriminator)
+            value.fetch(@discriminator)
+          elsif value.key?((discriminator = @discriminator.to_s))
+            value.fetch(discriminator)
+          end
 
-          key = key.to_sym if key.is_a?(String)
-          _, resolved = known_variants.find { |k,| k == key }
-          resolved.nil? ? TerminalShop::Unknown : resolved.call
-        else
-          nil
-        end
+        key = key.to_sym if key.is_a?(String)
+        _, resolved = known_variants.find { |k,| k == key }
+        resolved.nil? ? TerminalShop::Unknown : resolved.call
+      else
+        nil
       end
     end
 
     # rubocop:disable Style/HashEachMethods
     # rubocop:disable Style/CaseEquality
 
-    private_class_method :new
-
     # @param other [Object]
     #
     # @return [Boolean]
-    #
-    def self.===(other)
+    def ===(other)
       known_variants.any? do |_, variant_fn|
         variant_fn.call === other
       end
@@ -527,101 +476,95 @@ module TerminalShop
     # @param other [Object]
     #
     # @return [Boolean]
-    #
-    def self.==(other)
-      other.is_a?(Class) && other <= TerminalShop::Union && other.variants == variants
+    def ==(other)
+      other.is_a?(Module) && other.singleton_class.ancestors.include?(TerminalShop::Union) && other.derefed_variants == derefed_variants
     end
 
-    class << self
-      # @private
-      #
-      # @param value [Object]
-      #
-      # @return [Object]
-      #
-      def coerce(value)
-        if (variant = resolve_variant(value))
-          return TerminalShop::Converter.coerce(variant, value)
-        end
+    # @api private
+    #
+    # @param value [Object]
+    #
+    # @return [Object]
+    def coerce(value)
+      if (variant = resolve_variant(value))
+        return TerminalShop::Converter.coerce(variant, value)
+      end
 
-        matches = []
+      matches = []
 
-        known_variants.each do |_, variant_fn|
-          variant = variant_fn.call
+      known_variants.each do |_, variant_fn|
+        variant = variant_fn.call
 
-          case TerminalShop::Converter.try_strict_coerce(variant, value)
-          in [true, coerced, _]
-            return coerced
-          in [false, true, score]
-            matches << [score, variant]
-          in [false, false, _]
-            nil
-          end
+        case TerminalShop::Converter.try_strict_coerce(variant, value)
+        in [true, coerced, _]
+          return coerced
+        in [false, true, score]
+          matches << [score, variant]
+        in [false, false, _]
+          nil
         end
+      end
+
+      _, variant = matches.sort! { _2.first <=> _1.first }.find { |score,| !score.zero? }
+      variant.nil? ? value : TerminalShop::Converter.coerce(variant, value)
+    end
 
-        _, variant = matches.sort! { _2.first <=> _1.first }.find { |score,| !score.zero? }
-        variant.nil? ? value : TerminalShop::Converter.coerce(variant, value)
+    # @api private
+    #
+    # @param value [Object]
+    #
+    # @return [Object]
+    def dump(value)
+      if (variant = resolve_variant(value))
+        return TerminalShop::Converter.dump(variant, value)
       end
 
-      # @private
-      #
-      # @param value [Object]
-      #
-      # @return [Object]
-      #
-      def dump(value)
-        if (variant = resolve_variant(value))
+      known_variants.each do |_, variant_fn|
+        variant = variant_fn.call
+        if variant === value
           return TerminalShop::Converter.dump(variant, value)
         end
-
-        known_variants.each do |_, variant_fn|
-          variant = variant_fn.call
-          if variant === value
-            return TerminalShop::Converter.dump(variant, value)
-          end
-        end
-        value
       end
+      value
+    end
 
-      # @private
-      #
-      # @param value [Object]
-      #
-      # @return [Array(true, Object, nil), Array(false, Boolean, Integer)]
-      #
-      def try_strict_coerce(value)
-        # TODO(ruby) this will result in super linear decoding behaviour for nested unions
-        # follow up with a decoding context that captures current strictness levels
-        if (variant = resolve_variant(value))
-          return Converter.try_strict_coerce(variant, value)
-        end
+    # @api private
+    #
+    # @param value [Object]
+    #
+    # @return [Array(true, Object, nil), Array(false, Boolean, Integer)]
+    def try_strict_coerce(value)
+      # TODO(ruby) this will result in super linear decoding behaviour for nested unions
+      # follow up with a decoding context that captures current strictness levels
+      if (variant = resolve_variant(value))
+        return Converter.try_strict_coerce(variant, value)
+      end
 
-        coercible = false
-        max_score = 0
+      coercible = false
+      max_score = 0
 
-        known_variants.each do |_, variant_fn|
-          variant = variant_fn.call
+      known_variants.each do |_, variant_fn|
+        variant = variant_fn.call
 
-          case TerminalShop::Converter.try_strict_coerce(variant, value)
-          in [true, coerced, score]
-            return [true, coerced, score]
-          in [false, true, score]
-            coercible = true
-            max_score = [max_score, score].max
-          in [false, false, _]
-            nil
-          end
+        case TerminalShop::Converter.try_strict_coerce(variant, value)
+        in [true, coerced, score]
+          return [true, coerced, score]
+        in [false, true, score]
+          coercible = true
+          max_score = [max_score, score].max
+        in [false, false, _]
+          nil
         end
-
-        [false, coercible, max_score]
       end
+
+      [false, coercible, max_score]
     end
 
     # rubocop:enable Style/CaseEquality
     # rubocop:enable Style/HashEachMethods
   end
 
-  # @private
+  # @api private
   #
   # @abstract
   #
@@ -629,14 +572,22 @@ module TerminalShop
   class ArrayOf
     include TerminalShop::Converter
 
-    private_class_method :new
-
-    def self.[](...) = new(...)
+    # @param type_info [Hash{Symbol=>Object}, Proc, TerminalShop::Converter, Class]
+    #
+    # @param spec [Hash{Symbol=>Object}] .
+    #
+    #   @option spec [NilClass, TrueClass, FalseClass, Integer, Float, Symbol] :const
+    #
+    #   @option spec [Proc] :enum
+    #
+    #   @option spec [Proc] :union
+    #
+    #   @option spec [Boolean] :"nil?"
+    def self.[](type_info, spec = {}) = new(type_info, spec)
 
     # @param other [Object]
     #
     # @return [Boolean]
-    #
     def ===(other)
       type = item_type
       case other
@@ -652,15 +603,13 @@ module TerminalShop
     # @param other [Object]
     #
     # @return [Boolean]
-    #
     def ==(other) = other.is_a?(TerminalShop::ArrayOf) && other.item_type == item_type
 
-    # @private
+    # @api private
     #
     # @param value [Enumerable, Object]
     #
     # @return [Array<Object>, Object]
-    #
     def coerce(value)
       type = item_type
       case value
@@ -671,12 +620,11 @@ module TerminalShop
       end
     end
 
-    # @private
+    # @api private
     #
     # @param value [Enumerable, Object]
     #
     # @return [Array<Object>, Object]
-    #
     def dump(value)
       type = item_type
       case value
@@ -687,12 +635,11 @@ module TerminalShop
       end
     end
 
-    # @private
+    # @api private
     #
     # @param value [Object]
     #
     # @return [Array(true, Object, nil), Array(false, Boolean, Integer)]
-    #
     def try_strict_coerce(value)
       case value
       in Array
@@ -726,13 +673,12 @@ module TerminalShop
       end
     end
 
-    # @private
+    # @api private
     #
     # @return [TerminalShop::Converter, Class]
-    #
     protected def item_type = @item_type_fn.call
 
-    # @private
+    # @api private
     #
     # @param type_info [Hash{Symbol=>Object}, Proc, TerminalShop::Converter, Class]
     #
@@ -745,13 +691,12 @@ module TerminalShop
     #   @option spec [Proc] :union
     #
     #   @option spec [Boolean] :"nil?"
-    #
     def initialize(type_info, spec = {})
       @item_type_fn = TerminalShop::Converter.type_info(type_info || spec)
     end
   end
 
-  # @private
+  # @api private
   #
   # @abstract
   #
@@ -759,14 +704,22 @@ module TerminalShop
   class HashOf
     include TerminalShop::Converter
 
-    private_class_method :new
-
-    def self.[](...) = new(...)
+    # @param type_info [Hash{Symbol=>Object}, Proc, TerminalShop::Converter, Class]
+    #
+    # @param spec [Hash{Symbol=>Object}] .
+    #
+    #   @option spec [NilClass, TrueClass, FalseClass, Integer, Float, Symbol] :const
+    #
+    #   @option spec [Proc] :enum
+    #
+    #   @option spec [Proc] :union
+    #
+    #   @option spec [Boolean] :"nil?"
+    def self.[](type_info, spec = {}) = new(type_info, spec)
 
     # @param other [Object]
     #
     # @return [Boolean]
-    #
     def ===(other)
       type = item_type
       case other
@@ -787,15 +740,13 @@ module TerminalShop
     # @param other [Object]
     #
     # @return [Boolean]
-    #
     def ==(other) = other.is_a?(TerminalShop::HashOf) && other.item_type == item_type
 
-    # @private
+    # @api private
     #
     # @param value [Hash{Object=>Object}, Object]
     #
     # @return [Hash{Symbol=>Object}, Object]
-    #
     def coerce(value)
       type = item_type
       case value
@@ -809,12 +760,11 @@ module TerminalShop
       end
     end
 
-    # @private
+    # @api private
     #
     # @param value [Hash{Object=>Object}, Object]
     #
     # @return [Hash{Symbol=>Object}, Object]
-    #
     def dump(value)
       type = item_type
       case value
@@ -827,12 +777,11 @@ module TerminalShop
       end
     end
 
-    # @private
+    # @api private
     #
     # @param value [Object]
     #
     # @return [Array(true, Object, nil), Array(false, Boolean, Integer)]
-    #
     def try_strict_coerce(value)
       case value
       in Hash
@@ -866,13 +815,12 @@ module TerminalShop
       end
     end
 
-    # @private
+    # @api private
     #
     # @return [TerminalShop::Converter, Class]
-    #
     protected def item_type = @item_type_fn.call
 
-    # @private
+    # @api private
     #
     # @param type_info [Hash{Symbol=>Object}, Proc, TerminalShop::Converter, Class]
     #
@@ -885,55 +833,56 @@ module TerminalShop
     #   @option spec [Proc] :union
     #
     #   @option spec [Boolean] :"nil?"
-    #
     def initialize(type_info, spec = {})
       @item_type_fn = TerminalShop::Converter.type_info(type_info || spec)
     end
   end
 
-  # @private
-  #
   # @abstract
   #
   # @example
-  # ```ruby
-  # # `product_api` is a `TerminalShop::Models::ProductAPI`
-  # product_api => {
-  #   id: id,
-  #   description: description,
-  #   name: name
-  # }
-  # ```
+  #   # `product_api` is a `TerminalShop::Models::ProductAPI`
+  #   product_api => {
+  #     id: id,
+  #     description: description,
+  #     name: name
+  #   }
   class BaseModel
     extend TerminalShop::Converter
 
     class << self
-      # @private
+      # @api private
       #
       # Assumes superclass fields are totally defined before fields are accessed /
       #   defined on subclasses.
       #
       # @return [Hash{Symbol=>Hash{Symbol=>Object}}]
-      #
       def known_fields
         @known_fields ||= (self < TerminalShop::BaseModel ? superclass.known_fields.dup : {})
       end
 
-      # @return [Hash{Symbol=>Hash{Symbol=>Object}}]
+      # @api private
       #
+      # @return [Hash{Symbol=>Symbol}]
+      def reverse_map
+        @reverse_map ||= (self < TerminalShop::BaseModel ? superclass.reverse_map.dup : {})
+      end
+
+      # @api private
+      #
+      # @return [Hash{Symbol=>Hash{Symbol=>Object}}]
       def fields
         known_fields.transform_values do |field|
           {**field.except(:type_fn), type: field.fetch(:type_fn).call}
         end
       end
 
-      # @private
+      # @api private
       #
       # @return [Hash{Symbol=>Proc}]
-      #
       def defaults = (@defaults ||= {})
 
-      # @private
+      # @api private
       #
       # @param name_sym [Symbol]
       #
@@ -950,11 +899,10 @@ module TerminalShop
       #   @option spec [Proc] :union
       #
       #   @option spec [Boolean] :"nil?"
-      #
       private def add_field(name_sym, required:, type_info:, spec:)
         type_fn, info =
           case type_info
-          in Proc | Class | TerminalShop::Converter
+          in Proc | Module | TerminalShop::Converter
             [TerminalShop::Converter.type_info({**spec, union: type_info}), spec]
           in Hash
             [TerminalShop::Converter.type_info(type_info), type_info]
@@ -963,7 +911,7 @@ module TerminalShop
         fallback = info[:const]
         defaults[name_sym] = fallback if required && !info[:nil?] && info.key?(:const)
 
-        key = info.fetch(:api_name, name_sym)
+        key = info[:api_name]&.tap { reverse_map[_1] = name_sym } || name_sym
         setter = "#{name_sym}="
 
         if known_fields.key?(name_sym)
@@ -989,7 +937,7 @@ module TerminalShop
         end
       end
 
-      # @private
+      # @api private
       #
       # @param name_sym [Symbol]
       #
@@ -1004,12 +952,11 @@ module TerminalShop
       #   @option spec [Proc] :union
       #
       #   @option spec [Boolean] :"nil?"
-      #
       def required(name_sym, type_info, spec = {})
         add_field(name_sym, required: true, type_info: type_info, spec: spec)
       end
 
-      # @private
+      # @api private
       #
       # @param name_sym [Symbol]
       #
@@ -1024,18 +971,16 @@ module TerminalShop
       #   @option spec [Proc] :union
       #
       #   @option spec [Boolean] :"nil?"
-      #
       def optional(name_sym, type_info, spec = {})
         add_field(name_sym, required: false, type_info: type_info, spec: spec)
       end
 
-      # @private
+      # @api private
       #
       # `request_only` attributes not excluded from `.#coerce` when receiving responses
       #   even if well behaved servers should not send them
       #
       # @param blk [Proc]
-      #
       private def request_only(&blk)
         @mode = :dump
         blk.call
@@ -1043,12 +988,11 @@ module TerminalShop
         @mode = nil
       end
 
-      # @private
+      # @api private
       #
       # `response_only` attributes are omitted from `.#dump` when making requests
       #
       # @param blk [Proc]
-      #
       private def response_only(&blk)
         @mode = :coerce
         blk.call
@@ -1060,7 +1004,6 @@ module TerminalShop
     # @param other [Object]
     #
     # @return [Boolean]
-    #
     def ==(other)
       case other
       in TerminalShop::BaseModel
@@ -1071,12 +1014,11 @@ module TerminalShop
     end
 
     class << self
-      # @private
+      # @api private
       #
       # @param value [TerminalShop::BaseModel, Hash{Object=>Object}, Object]
       #
       # @return [TerminalShop::BaseModel, Object]
-      #
       def coerce(value)
         case TerminalShop::Util.coerce_hash(value)
         in Hash => coerced
@@ -1086,12 +1028,11 @@ module TerminalShop
         end
       end
 
-      # @private
+      # @api private
       #
       # @param value [TerminalShop::BaseModel, Object]
       #
       # @return [Hash{Object=>Object}, Object]
-      #
       def dump(value)
         unless (coerced = TerminalShop::Util.coerce_hash(value)).is_a?(Hash)
           return value
@@ -1123,12 +1064,11 @@ module TerminalShop
         values
       end
 
-      # @private
+      # @api private
       #
       # @param value [Object]
       #
       # @return [Array(true, Object, nil), Array(false, Boolean, Integer)]
-      #
       def try_strict_coerce(value)
         case value
         in Hash | TerminalShop::BaseModel
@@ -1186,7 +1126,6 @@ module TerminalShop
     # @param key [Symbol]
     #
     # @return [Object, nil]
-    #
     def [](key)
       unless key.instance_of?(Symbol)
         raise ArgumentError.new("Expected symbol key for lookup, got #{key.inspect}")
@@ -1205,7 +1144,6 @@ module TerminalShop
     #   should not be mutated.
     #
     # @return [Hash{Symbol=>Object}]
-    #
     def to_h = @data
 
     alias_method :to_hash, :to_h
@@ -1213,7 +1151,6 @@ module TerminalShop
     # @param keys [Array<Symbol>, nil]
     #
     # @return [Hash{Symbol=>Object}]
-    #
     def deconstruct_keys(keys)
       (keys || self.class.known_fields.keys).filter_map do |k|
         unless self.class.known_fields.key?(k)
@@ -1228,22 +1165,33 @@ module TerminalShop
     # Create a new instance of a model.
     #
     # @param data [Hash{Symbol=>Object}, TerminalShop::BaseModel]
-    #
     def initialize(data = {})
       case TerminalShop::Util.coerce_hash(data)
       in Hash => coerced
-        @data = coerced.transform_keys(&:to_sym)
+        @data = coerced.to_h do |key, value|
+          name = key.to_sym
+          mapped = self.class.reverse_map.fetch(name, name)
+          type = self.class.fields[mapped]&.fetch(:type)
+          stored =
+            case [type, value]
+            in [Module, Hash] if type <= TerminalShop::BaseModel
+              type.new(value)
+            in [TerminalShop::ArrayOf, Array] | [TerminalShop::HashOf, Hash]
+              type.coerce(value)
+            else
+              value
+            end
+          [name, stored]
+        end
       else
         raise ArgumentError.new("Expected a #{Hash} or #{TerminalShop::BaseModel}, got #{data.inspect}")
       end
     end
 
     # @return [String]
-    #
     def to_s = @data.to_s
 
     # @return [String]
-    #
     def inspect
       "#<#{self.class.name}:0x#{object_id.to_s(16)} #{deconstruct_keys(nil).map do |k, v|
         "#{k}=#{v.inspect}"