apiwork 0.3.1 → 0.5.0

data/lib/apiwork/contract/object/coercer.rb

@@ -85,6 +85,7 @@ module Apiwork
 
           return coerce_union(value, param_options[:union]) if type == :union
           return coerce_array(value, param_options) if type == :array && value.is_a?(Array)
+          return coerce_record(value, param_options) if type == :record && value.is_a?(Hash)
           return Coercer.coerce(param_options[:shape], value) if param_options[:shape] && value.is_a?(Hash)
 
           if value.is_a?(Hash) && type && !PRIMITIVES.key?(type)
@@ -105,7 +106,9 @@ module Apiwork
           custom_shape = resolve_custom_shape(of_type) if of_type && !PRIMITIVES.key?(of_type)
 
           array.map do |item|
-            if of_shape && item.is_a?(Hash)
+            if of_type == :union && item.is_a?(Hash)
+              coerce_union(item, of_shape)
+            elsif of_shape && item.is_a?(Hash)
               Coercer.coerce(of_shape, item)
             elsif of_type && PRIMITIVES.key?(of_type)
               coerced = coerce_primitive(item, of_type)
@@ -120,6 +123,23 @@ module Apiwork
           end
         end
 
+        def coerce_record(hash, param_options)
+          of = param_options[:of]
+          of_type = of&.type
+          of_shape = of&.shape
+
+          hash.transform_values do |item|
+            if of_shape && item.is_a?(Hash)
+              Coercer.coerce(of_shape, item)
+            elsif of_type && PRIMITIVES.key?(of_type)
+              coerced = coerce_primitive(item, of_type)
+              coerced.nil? ? item : coerced
+            else
+              item
+            end
+          end
+        end
+
         def coerce_union(value, union)
           if union.variants.any? { |variant| variant[:type] == :boolean }
             coerced = coerce_primitive(value, :boolean)
@@ -156,6 +176,13 @@ module Apiwork
 
             next if discriminator
 
+            if PRIMITIVES.key?(variant_type) && !value.is_a?(Hash) && !value.is_a?(Array)
+              coerced = coerce_primitive(value, variant_type)
+              return coerced unless coerced.nil?
+
+              next
+            end
+
             custom_shape = resolve_custom_shape(variant_type)
             next unless custom_shape
 
@@ -184,7 +211,9 @@ module Apiwork
           type_definition = @shape.contract_class.resolve_custom_type(type_name)
           return @type_cache[type_name] = nil unless type_definition
 
-          @type_cache[type_name] = Object.new(@shape.contract_class).tap do |type_shape|
+          scope = type_definition.scope || @shape.contract_class
+
+          @type_cache[type_name] = Object.new(scope).tap do |type_shape|
             type_shape.copy_type_definition_params(type_definition, type_shape)
           end
         end

data/lib/apiwork/contract/object/deserializer.rb

@@ -85,10 +85,14 @@ module Apiwork
         end
 
         def deserialize_array(array, param_options)
+          of = param_options[:of]
+
           array.map do |item|
             next item unless item.is_a?(Hash)
 
-            if param_options[:shape]
+            if of&.type == :union && of.shape.is_a?(Apiwork::Union)
+              deserialize_union(item, of.shape)
+            elsif param_options[:shape]
               Deserializer.deserialize(param_options[:shape], item)
             else
               item

data/lib/apiwork/contract/object/transformer.rb

@@ -32,11 +32,22 @@ module Apiwork
 
             if param_options[:shape] && value.is_a?(Hash)
               transformed[name] = Transformer.transform(param_options[:shape], value)
-            elsif param_options[:type] == :array && value.is_a?(Array)
+            elsif param_options[:type] == :record && value.is_a?(Hash)
               of = param_options[:of]
               of_shape = of&.shape
 
               if of_shape
+                transformed[name] = value.transform_values do |item|
+                  item.is_a?(Hash) ? Transformer.transform(of_shape, item) : item
+                end
+              end
+            elsif param_options[:type] == :array && value.is_a?(Array)
+              of = param_options[:of]
+              of_shape = of&.shape
+
+              if of&.type == :union
+                transformed[name] = value
+              elsif of_shape
                 transformed[name] = value.map do |item|
                   item.is_a?(Hash) ? Transformer.transform(of_shape, item) : item
                 end
@@ -85,7 +96,9 @@ module Apiwork
         end
 
         def build_type_shape(type_definition, contract_class)
-          type_shape = Object.new(contract_class, action_name: @shape.action_name)
+          scope = type_definition.scope || contract_class
+
+          type_shape = Object.new(scope, action_name: @shape.action_name)
           type_shape.copy_type_definition_params(type_definition, type_shape)
           type_shape
         end

data/lib/apiwork/contract/object/validator.rb

@@ -129,14 +129,7 @@ module Apiwork
           return nil if param_options[:optional]
           return nil if param_options[:nullable] && data.key?(name) && value.nil?
 
-          missing = case param_options[:type]
-                    when :boolean, :string
-                      value.nil?
-                    else
-                      value.blank?
-                    end
-
-          return nil unless missing
+          return nil unless value.nil?
 
           if param_options[:enum].present?
             Issue.new(
@@ -208,6 +201,8 @@ module Apiwork
             validate_shape_object(value, param_options[:shape], field_path, max_depth, current_depth)
           elsif param_options[:type] == :array && value.is_a?(Array)
             validate_array_param(value, param_options, field_path, max_depth, current_depth)
+          elsif param_options[:type] == :record && value.is_a?(Hash)
+            validate_record_param(value, param_options, field_path, max_depth, current_depth)
           else
             [[], value]
           end
@@ -237,6 +232,41 @@ module Apiwork
           array_issues.empty? ? [[], array_values] : [array_issues, NOT_SET]
         end
 
+        def validate_record_param(value, param_options, field_path, max_depth, current_depth)
+          issues = []
+          validated = {}
+
+          of = param_options[:of]
+          of_type = of&.type
+          of_shape = of&.shape
+
+          value.each do |key, item|
+            item_path = field_path + [key]
+
+            if of_shape
+              validator = Validator.new(normalize_shape(of_shape))
+              shape_result = validator.validate(
+                item,
+                max_depth:,
+                current_depth: current_depth + 1,
+                path: item_path,
+              )
+              if shape_result.invalid?
+                issues.concat(shape_result.issues)
+              else
+                validated[key] = shape_result.params
+              end
+            elsif of_type
+              type_error = validate_type(key, item, of_type, item_path)
+              type_error ? issues << type_error : validated[key] = item
+            else
+              validated[key] = item
+            end
+          end
+
+          issues.empty? ? [[], validated] : [issues, NOT_SET]
+        end
+
         def check_unknown_params(data, path)
           extra_keys = data.keys - @shape.params.keys
           extra_keys.map do |key|
@@ -287,7 +317,10 @@ module Apiwork
           array.each_with_index do |item, index|
             item_path = field_path + [index]
 
-            if of_shape
+            if of&.type == :union && of_shape.is_a?(Apiwork::Union)
+              error, validated = validate_union(nil, item, of_shape, item_path, current_depth:, max_depth:)
+              error ? issues << error : values << validated
+            elsif of_shape
               validator = Validator.new(normalize_shape(of_shape))
               shape_result = validator.validate(
                 item,
@@ -376,6 +409,7 @@ module Apiwork
                   when :uuid then value.is_a?(String) && value.match?(/\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i)
                   when :object then value.is_a?(Hash)
                   when :array then value.is_a?(Array)
+                  when :record then value.is_a?(Hash)
                   when :decimal, :number then value.is_a?(Numeric)
                   else true
                   end
@@ -437,6 +471,8 @@ module Apiwork
               most_specific_error = error
             elsif error.code == :value_invalid && (most_specific_error.nil? || most_specific_error.code != :field_unknown)
               most_specific_error = error
+            elsif error.path.length > path.length && most_specific_error.nil?
+              most_specific_error = error
             end
           end
 
@@ -448,7 +484,7 @@ module Apiwork
             translate_detail(:type_invalid),
             path:,
             meta: {
-              actual: value.is_a?(Hash) ? :hash : value.class.name.underscore.to_sym,
+              actual: value.is_a?(Hash) ? :object : value.class.name.underscore.to_sym,
               expected: expected_types.join(' | '),
               field: name,
             },
@@ -605,7 +641,9 @@ module Apiwork
         end
 
         def validate_with_type_definition(type_definition, value, path, current_depth:, exclude_param: nil, max_depth:)
-          type_shape = Object.new(@shape.contract_class, action_name: @shape.action_name)
+          scope = type_definition.scope || @shape.contract_class
+
+          type_shape = Object.new(scope, action_name: @shape.action_name)
           type_shape.copy_type_definition_params(type_definition, type_shape)
           type_shape.params.delete(exclude_param) if exclude_param
 

data/lib/apiwork/contract/object.rb

@@ -56,7 +56,7 @@ module Apiwork
       #
       # @param name [Symbol]
       #   The param name.
-      # @param type [Symbol, nil] (nil) [:array, :binary, :boolean, :date, :datetime, :decimal, :integer, :literal, :number, :object, :string, :time, :union, :uuid]
+      # @param type [Symbol, nil] (nil) [:array, :binary, :boolean, :date, :datetime, :decimal, :integer, :literal, :number, :object, :record, :string, :time, :union, :unknown, :uuid]
       #   The param type.
       # @param as [Symbol, nil] (nil)
       #   The target attribute name.
@@ -72,10 +72,10 @@ module Apiwork
       #   The allowed values or enum reference.
       # @param example [Object, nil] (nil)
       #   The example value. Metadata included in exports.
-      # @param format [Symbol, nil] (nil) [:date, :datetime, :double, :email, :float, :hostname, :int32, :int64, :ipv4, :ipv6, :password, :url, :uuid]
+      # @param format [Symbol, nil] (nil) [:date, :datetime, :double, :email, :float, :hostname, :int32, :int64, :ipv4, :ipv6, :password, :text, :url, :uuid]
       #   Format hint for exports. Does not change the type, but exports may add validation or documentation based on it.
       #   Valid formats by type: `:decimal`/`:number` (`:double`, `:float`), `:integer` (`:int32`, `:int64`),
-      #   `:string` (`:date`, `:datetime`, `:email`, `:hostname`, `:ipv4`, `:ipv6`, `:password`, `:url`, `:uuid`).
+      #   `:string` (`:date`, `:datetime`, `:email`, `:hostname`, `:ipv4`, `:ipv6`, `:password`, `:text`, `:url`, `:uuid`).
       # @param max [Integer, nil] (nil)
       #   The maximum. For `:array`: size. For `:decimal`, `:integer`, `:number`: value. For `:string`: length.
       # @param min [Integer, nil] (nil)
@@ -83,7 +83,7 @@ module Apiwork
       # @param nullable [Boolean] (false)
       #   Whether the value can be `null`.
       # @param of [Symbol, Hash, nil] (nil)
-      #   The element type. Arrays only.
+      #   The element or value type. Arrays and records only.
       # @param optional [Boolean] (false)
       #   Whether the param is optional.
       # @param required [Boolean] (false)
@@ -109,6 +109,7 @@ module Apiwork
         name,
         type: nil,
         as: nil,
+        custom_type: nil,
         default: nil,
         deprecated: false,
         description: nil,
@@ -238,6 +239,69 @@ module Apiwork
         )
       end
 
+      # @api public
+      # Defines a record param with value type.
+      #
+      # @param name [Symbol]
+      #   The param name.
+      # @param as [Symbol, nil] (nil)
+      #   The target attribute name.
+      # @param default [Object, nil] (nil)
+      #   The default value.
+      # @param deprecated [Boolean] (false)
+      #   Whether deprecated. Metadata included in exports.
+      # @param description [String, nil] (nil)
+      #   The description. Metadata included in exports.
+      # @param nullable [Boolean] (false)
+      #   Whether the value can be `null`.
+      # @param optional [Boolean] (false)
+      #   Whether the param is optional.
+      # @param required [Boolean] (false)
+      #   Whether the param is required.
+      # @yield block for defining value type
+      # @yieldparam element [Contract::Element]
+      # @return [void]
+      #
+      # @example instance_eval style
+      #   record :scores do
+      #     integer
+      #   end
+      #
+      # @example yield style
+      #   record :scores do |element|
+      #     element.integer
+      #   end
+      def record(
+        name,
+        as: nil,
+        default: nil,
+        deprecated: false,
+        description: nil,
+        nullable: false,
+        optional: false,
+        required: false,
+        &block
+      )
+        raise ConfigurationError, 'record requires a block' unless block
+
+        element = Element.new(@contract_class)
+        block.arity.positive? ? yield(element) : element.instance_eval(&block)
+        element.validate!
+
+        param(
+          name,
+          as:,
+          default:,
+          deprecated:,
+          description:,
+          nullable:,
+          optional:,
+          required:,
+          of: element,
+          type: :record,
+        )
+      end
+
       def wrapped?
         @wrapped
       end
@@ -264,8 +328,10 @@ module Apiwork
         type_definition.params.each do |param_name, param_options|
           nested_shape = param_options[:shape]
 
-          if param_options[:type] == :array && nested_shape.is_a?(Apiwork::API::Object)
+          if param_options[:type] == :array && nested_shape.is_a?(API::Object)
             target_param.param(param_name, **param_options.except(:name))
+          elsif param_options[:type] == :array
+            target_param.param(param_name, **param_options.except(:name, :shape, :discriminator))
           elsif nested_shape.is_a?(API::Object)
             copy_nested_object_param(target_param, param_name, param_options, nested_shape)
           elsif nested_shape.is_a?(API::Union)
@@ -416,7 +482,9 @@ module Apiwork
         as:,
         options:
       )
-        union = Union.new(@contract_class, discriminator: type_definition.discriminator)
+        scope = type_definition.scope || @contract_class
+
+        union = Union.new(scope, discriminator: type_definition.discriminator)
 
         type_definition.variants.each do |variant|
           if variant[:shape].is_a?(API::Object)
@@ -467,8 +535,10 @@ module Apiwork
         options:,
         &block
       )
+        scope = type_definition.scope || @contract_class
+
         shape = Object.new(
-          @contract_class,
+          scope,
           action_name: @action_name,
           visited_types: visited_types.dup.add([@contract_class.object_id, type]),
         )
@@ -516,7 +586,7 @@ module Apiwork
       end
 
       def resolve_of(of, type, &block)
-        return nil unless type == :array
+        return nil unless [:array, :record].include?(type)
 
         if block_given?
           element = Element.new(@contract_class)
@@ -531,7 +601,7 @@ module Apiwork
       end
 
       def resolve_shape(shape, type, &block)
-        return nil if type == :array
+        return nil if [:array, :record].include?(type)
 
         if shape
           shape

data/lib/apiwork/element.rb

@@ -82,7 +82,7 @@ module Apiwork
     #
     # @param enum [Array, Symbol, nil] (nil)
     #   The allowed values.
-    # @param format [Symbol, nil] (nil) [:date, :datetime, :email, :hostname, :ipv4, :ipv6, :password, :url, :uuid]
+    # @param format [Symbol, nil] (nil) [:date, :datetime, :email, :hostname, :ipv4, :ipv6, :password, :text, :url, :uuid]
     #   Format hint for exports. Does not change the type, but exports may add validation or documentation based on it.
     #   Valid formats by type: `:string`.
     # @param max [Integer, nil] (nil)
@@ -250,6 +250,19 @@ module Apiwork
       of(:binary)
     end
 
+    # @api public
+    # Defines an unknown.
+    #
+    # @return [void]
+    #
+    # @example
+    #   array :values do
+    #     unknown
+    #   end
+    def unknown
+      of(:unknown)
+    end
+
     # @api public
     # Defines an object.
     #
@@ -300,6 +313,26 @@ module Apiwork
       of(:array, &block)
     end
 
+    # @api public
+    # Defines a record.
+    #
+    # @yield block defining value type
+    # @yieldparam element [Element]
+    # @return [void]
+    #
+    # @example instance_eval style
+    #   record :scores do
+    #     integer
+    #   end
+    #
+    # @example yield style
+    #   record :scores do |element|
+    #     element.integer
+    #   end
+    def record(&block)
+      of(:record, &block)
+    end
+
     # @api public
     # Defines a union.
     #

data/lib/apiwork/export/base.rb

@@ -263,10 +263,7 @@ module Apiwork
       end
 
       def extract_options_from_config(config)
-        self.class.options.keys.each_with_object({}) do |key, hash|
-          value = config.public_send(key)
-          hash[key] = value unless value.nil?
-        end
+        config.to_h.slice(*self.class.options.keys).compact
       end
 
       def validate_options!

data/lib/apiwork/export/builder_mapper.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Export
+    class BuilderMapper
+      class << self
+        def map(export, surface)
+          new(export).map(surface)
+        end
+      end
+
+      def initialize(export)
+        @export = export
+      end
+
+      def map(surface)
+        build_builders(surface.types)
+      end
+
+      def build_builders(types)
+        builders = types.sort_by { |name, _type| name.to_s }.flat_map do |name, type|
+          if type.union?
+            build_union_builders(name, type, types)
+          elsif type.object?
+            [build_object_builder(name, type)]
+          end
+        end.compact
+
+        builders.join("\n\n")
+      end
+
+      private
+
+      def build_object_builder(name, type)
+        type_name = pascal_case(name)
+        defaulted, required = classify_fields(type.shape)
+
+        if defaulted.empty?
+          build_passthrough_builder(type_name)
+        elsif required.empty?
+          build_all_defaulted_builder(type_name, defaulted)
+        else
+          build_mixed_builder(type_name, defaulted, required)
+        end
+      end
+
+      def build_passthrough_builder(type_name)
+        "export function build#{type_name}(fields: #{type_name}): #{type_name} {\n" \
+          "  return fields;\n" \
+          '}'
+      end
+
+      def build_all_defaulted_builder(type_name, defaulted)
+        defaults = build_defaults_body(defaulted)
+
+        "export function build#{type_name}(fields?: Partial<#{type_name}>): #{type_name} {\n" \
+          "  return {\n" \
+          "#{defaults}\n" \
+          "    ...fields,\n" \
+          "  };\n" \
+          '}'
+      end
+
+      def build_mixed_builder(type_name, defaulted, required)
+        required_keys = required.keys.map { |name| "'#{@export.transform_key(name)}'" }.sort.join(' | ')
+        fields_type = "Pick<#{type_name}, #{required_keys}> & Partial<#{type_name}>"
+        defaults = build_defaults_body(defaulted)
+
+        "export function build#{type_name}(fields: #{fields_type}): #{type_name} {\n" \
+          "  return {\n" \
+          "#{defaults}\n" \
+          "    ...fields,\n" \
+          "  };\n" \
+          '}'
+      end
+
+      def build_defaults_body(defaulted)
+        defaulted.sort_by { |name, _param| name.to_s }.map do |name, param|
+          "    #{@export.transform_key(name)}: #{serialize_default(param)},"
+        end.join("\n")
+      end
+
+      def build_union_builders(name, type, types)
+        type_name = pascal_case(name)
+        builders = [build_passthrough_builder(type_name)]
+
+        if type.discriminator
+          type.variants.each do |variant|
+            next unless variant.tag
+            next if variant.reference? && types.key?(variant.reference)
+
+            builders << build_variant_builder(type_name, type.discriminator, variant)
+          end
+        end
+
+        builders
+      end
+
+      def build_variant_builder(type_name, discriminator, variant)
+        discriminator_key = @export.transform_key(discriminator)
+        builder_name = variant.reference? ? "build#{pascal_case(variant.reference)}" : "build#{type_name}#{pascal_case(variant.tag)}"
+        extract_type = "Extract<#{type_name}, { #{discriminator_key}: '#{variant.tag}' }>"
+
+        variant_defaults = {}
+        variant_required = {}
+
+        variant_defaults, variant_required = classify_fields(variant.shape) if variant.object? && variant.shape.any?
+
+        fields_type = build_variant_fields_type(extract_type, discriminator_key, variant_defaults, variant_required)
+
+        body_lines = ["    #{discriminator_key}: '#{variant.tag}',"]
+        variant_defaults.sort_by { |name, _param| name.to_s }.each do |name, param|
+          body_lines << "    #{@export.transform_key(name)}: #{serialize_default(param)},"
+        end
+        body_lines << '    ...fields,'
+
+        "export function #{builder_name}(fields: #{fields_type}): #{type_name} {\n" \
+          "  return {\n" \
+          "#{body_lines.join("\n")}\n" \
+          "  };\n" \
+          '}'
+      end
+
+      def build_variant_fields_type(extract_type, discriminator_key, defaulted, required)
+        omitted_type = "Omit<#{extract_type}, '#{discriminator_key}'>"
+
+        if required.empty? && defaulted.empty?
+          omitted_type
+        elsif required.empty?
+          "Partial<#{omitted_type}>"
+        else
+          required_keys = required.keys.map { |name| "'#{@export.transform_key(name)}'" }.sort.join(' | ')
+          "Pick<#{omitted_type}, #{required_keys}> & Partial<#{omitted_type}>"
+        end
+      end
+
+      def classify_fields(shape)
+        defaulted = {}
+        required = {}
+
+        shape.sort_by { |name, _param| name.to_s }.each do |name, param|
+          if defaulted_field?(param)
+            defaulted[name] = param
+          else
+            required[name] = param
+          end
+        end
+
+        [defaulted, required]
+      end
+
+      def defaulted_field?(param)
+        return true if param.nullable?
+        return true if param.respond_to?(:default) && !param.default.nil?
+
+        false
+      end
+
+      def serialize_default(param)
+        if param.respond_to?(:default) && !param.default.nil?
+          serialize_value(param.default)
+        elsif param.nullable?
+          'null'
+        end
+      end
+
+      def serialize_value(value)
+        case value
+        when String then "'#{value.gsub("'", "\\\\'")}'"
+        when Integer, Float then value.to_s
+        when BigDecimal then value.to_s('F')
+        when TrueClass, FalseClass then value.to_s
+        when Array then '[]'
+        when Hash then '{}'
+        else value.to_s
+        end
+      end
+
+      def pascal_case(name)
+        name.to_s.camelize(:upper)
+      end
+    end
+  end
+end

data/lib/apiwork/export/open_api.rb

@@ -319,7 +319,7 @@ module Apiwork
         schema = map_param(param)
 
         schema[:description] = param.description if param.description
-        schema[:example] = param.example if param.example
+        schema[:example] = param.example if param.concrete? && param.example
         schema[:deprecated] = true if param.deprecated?
 
         schema[:format] = param.format.to_s if param.formattable? && param.format
@@ -332,6 +332,8 @@ module Apiwork
           map_object(param)
         elsif param.array?
           map_array(param)
+        elsif param.record?
+          map_record(param)
         elsif param.union?
           map_union(param)
         elsif param.literal?
@@ -353,7 +355,7 @@ module Apiwork
         }
 
         result[:description] = param.description if param.description
-        result[:example] = param.example if param.example
+        result[:example] = param.example if param.respond_to?(:example) && param.example
 
         param.shape.each do |name, field|
           result[:properties][transform_key(name)] = map_field(field)
@@ -383,6 +385,11 @@ module Apiwork
         }
       end
 
+      def map_record(param)
+        value_schema = param.of ? map_param(param.of) : {}
+        { additionalProperties: value_schema, type: 'object' }
+      end
+
       def map_inline_object(shape)
         result = { properties: {}, type: 'object' }