apiwork 0.4.0 → 0.6.0

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

@@ -163,7 +163,7 @@ module Apiwork
         def validate_enum_value(name, value, enum, field_path)
           enum_values = resolve_enum(enum)
           return nil unless enum_values
-          return nil if enum_values.include?(value.to_s) || enum_values.include?(value)
+          return nil if enum_values.any? { |enum_value| enum_value.to_s == value.to_s }
 
           Issue.new(
             :value_invalid,
@@ -201,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
@@ -230,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|
@@ -280,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,
@@ -369,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
@@ -600,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.
@@ -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,
@@ -188,6 +189,10 @@ module Apiwork
       #   Whether deprecated. Metadata included in exports.
       # @param description [String, nil] (nil)
       #   The description. Metadata included in exports.
+      # @param max [Integer, nil] (nil)
+      #   The maximum number of elements.
+      # @param min [Integer, nil] (nil)
+      #   The minimum number of elements.
       # @param nullable [Boolean] (false)
       #   Whether the value can be `null`.
       # @param optional [Boolean] (false)
@@ -213,6 +218,8 @@ module Apiwork
         default: nil,
         deprecated: false,
         description: nil,
+        max: nil,
+        min: nil,
         nullable: false,
         optional: false,
         required: false,
@@ -230,6 +237,8 @@ module Apiwork
           default:,
           deprecated:,
           description:,
+          max:,
+          min:,
           nullable:,
           optional:,
           required:,
@@ -238,6 +247,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 +336,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 +490,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 +543,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 +594,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 +609,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/controller.rb

@@ -138,10 +138,10 @@ module Apiwork
                end
              else
                data[:meta] = meta if meta.present?
-               data
+               data.deep_symbolize_keys
              end
 
-      response = Response.new(body:)
+      response = Response.new(body: deep_as_json(body))
 
       if Rails.env.development?
         result = contract_class.parse_response(response, action_name)
@@ -223,6 +223,19 @@ module Apiwork
 
     private
 
+    def deep_as_json(value)
+      case value
+      when Hash
+        value.transform_values { |nested_value| deep_as_json(nested_value) }
+      when Array
+        value.map { |element| deep_as_json(element) }
+      when String, Integer, Float, TrueClass, FalseClass, NilClass, Symbol, Time, Date, BigDecimal
+        value
+      else
+        value.as_json
+      end
+    end
+
     def validate_contract
       return unless resource
       return if contract.valid?

data/lib/apiwork/element.rb

@@ -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' }
 

data/lib/apiwork/export/sorbus.rb

@@ -7,8 +7,12 @@ module Apiwork
       output :string
       file_extension '.ts'
 
+      option :builders, default: false, type: :boolean
+
       def generate
-        SorbusMapper.map(self, surface)
+        output = SorbusMapper.map(self, surface)
+        output += "\n\n#{BuilderMapper.map(self, surface)}" if options[:builders]
+        output
       end
 
       private

data/lib/apiwork/export/sorbus_mapper.rb

@@ -37,10 +37,8 @@ module Apiwork
       end
 
       def build_contract
-        contract = {
-          endpoints: build_endpoint_tree(@export.api.resources),
-          error: build_error_schema,
-        }
+        contract = { endpoints: build_endpoint_tree(@export.api.resources) }
+        contract[:error] = build_error_schema if @surface.types.key?(:error)
         "export const contract = #{format_object(contract, indent: 0)} as const;"
       end
 
@@ -80,9 +78,7 @@ module Apiwork
       end
 
       def transform_path(path)
-        path.gsub(%r{(/:?)(\w+)}) do
-          "#{::Regexp.last_match(1)}#{@export.transform_key(::Regexp.last_match(2))}"
-        end
+        path.to_s.gsub(/:(\w+)/) { ":#{@export.transform_key(::Regexp.last_match(1))}" }
       end
 
       def extract_path_params(path)

data/lib/apiwork/export/type_analysis.rb

@@ -4,9 +4,8 @@ module Apiwork
   module Export
     class TypeAnalysis
       PRIMITIVE_TYPES = %i[
-        string integer boolean datetime date uuid object array
-        decimal float literal union enum text binary json number time
-        unknown
+        array binary boolean date datetime decimal enum float integer json
+        literal number object record string text time union unknown uuid
       ].to_set.freeze
 
       class << self
@@ -39,11 +38,22 @@ module Apiwork
 
         def find_cycle_breaking_types(graph)
           lazy_types = Set.new
+          reduced_graph = graph
 
-          find_strongly_connected_components(graph).each do |component|
-            next if component.size == 1 && !graph[component.first].include?(component.first)
+          loop do
+            previous_size = lazy_types.size
+
+            find_strongly_connected_components(reduced_graph).each do |component|
+              next if component.size == 1 && !reduced_graph[component.first].include?(component.first)
+
+              lazy_types.add(select_cycle_breaker(component, reduced_graph))
+            end
 
-            lazy_types.add(component.min_by(&:to_s))
+            break if lazy_types.size == previous_size
+
+            reduced_graph = reduced_graph
+              .reject { |node, _| lazy_types.include?(node) }
+              .transform_values { |deps| deps - lazy_types.to_a }
           end
 
           lazy_types
@@ -114,6 +124,10 @@ module Apiwork
           state[:components] << component
         end
 
+        def select_cycle_breaker(component, graph)
+          component.min_by { |node| [-(graph[node] & component).size, node.to_s] }
+        end
+
         def collect_references(node, references, filter)
           return unless node.is_a?(Hash)
 

data/lib/apiwork/export/type_script.rb

@@ -7,10 +7,13 @@ module Apiwork
       output :string
       file_extension '.ts'
 
+      option :builders, default: false, type: :boolean
       option :version, default: '5', enum: %w[4 5], type: :string
 
       def generate
-        TypeScriptMapper.map(self, surface)
+        output = TypeScriptMapper.map(self, surface)
+        output += "\n\n#{BuilderMapper.map(self, surface)}" if options[:builders]
+        output
       end
 
       private