apiwork 0.4.0 → 0.5.0

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,
@@ -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

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

data/lib/apiwork/export/type_script_mapper.rb

@@ -30,7 +30,7 @@ module Apiwork
           ts_type = map_field(param)
           optional_marker = param.optional? ? '?' : ''
 
-          prop_jsdoc = jsdoc(description: param.description, example: param.example)
+          prop_jsdoc = jsdoc(description: param.description, example: param.concrete? ? param.example : nil)
           if prop_jsdoc
             indented_jsdoc = prop_jsdoc.lines.map { |line| "  #{line.chomp}" }.join("\n")
             "#{indented_jsdoc}\n  #{key}#{optional_marker}: #{ts_type};"
@@ -165,6 +165,8 @@ module Apiwork
           map_object_type(param)
         elsif param.array?
           map_array_type(param)
+        elsif param.record?
+          map_record_type(param)
         elsif param.union?
           map_union_type(param)
         elsif param.literal?
@@ -207,8 +209,29 @@ module Apiwork
         end
       end
 
+      def map_record_type(param)
+        value_type = param.of ? map_param(param.of) : 'unknown'
+        "Record<string, #{value_type}>"
+      end
+
       def map_union_type(param)
-        param.variants.map { |variant| map_param(variant) }.sort.join(' | ')
+        variant_types = param.variants.map do |variant|
+          if param.discriminator && variant.tag && variant.object?
+            discriminator_prop = "#{@export.transform_key(param.discriminator)}: '#{variant.tag}'"
+            properties = variant.shape.sort_by { |name, _| name.to_s }.map do |name, field|
+              "#{@export.transform_key(name)}: #{map_field(field)}"
+            end
+            all_properties = [discriminator_prop, *properties].join('; ')
+            "{ #{all_properties} }"
+          elsif param.discriminator && variant.tag
+            base_type = map_param(variant)
+            "{ #{@export.transform_key(param.discriminator)}: '#{variant.tag}' } & #{base_type}"
+          else
+            map_param(variant)
+          end
+        end
+
+        variant_types.sort.join(' | ')
       end
 
       def map_literal_type(param)

data/lib/apiwork/export/zod.rb

@@ -7,6 +7,7 @@ module Apiwork
       output :string
       file_extension '.ts'
 
+      option :builders, default: false, type: :boolean
       option :version, default: '4', enum: %w[4], type: :string
 
       def generate
@@ -26,6 +27,14 @@ module Apiwork
           parts << ''
         end
 
+        if options[:builders]
+          builder_output = BuilderMapper.map(self, surface)
+          if builder_output.present?
+            parts << builder_output
+            parts << ''
+          end
+        end
+
         parts.join("\n")
       end
 

data/lib/apiwork/export/zod_mapper.rb

@@ -200,6 +200,8 @@ module Apiwork
           map_object_type(param)
         elsif param.array?
           map_array_type(param)
+        elsif param.record?
+          map_record_type(param)
         elsif param.union?
           map_union_type(param)
         elsif param.literal?
@@ -248,6 +250,11 @@ module Apiwork
         base
       end
 
+      def map_record_type(param)
+        value_schema = param.of ? map_param(param.of) : 'z.unknown()'
+        "z.record(z.string(), #{value_schema})"
+      end
+
       def map_union_type(param)
         if param.discriminator
           map_discriminated_union(param)
@@ -260,7 +267,21 @@ module Apiwork
       def map_discriminated_union(param)
         discriminator_field = @export.transform_key(param.discriminator)
 
-        variant_schemas = param.variants.map { |variant| map_param(variant) }
+        variant_schemas = param.variants.map do |variant|
+          if variant.tag && variant.object?
+            discriminator_prop = "#{discriminator_field}: z.literal('#{variant.tag}')"
+            properties = variant.shape.sort_by { |name, _| name.to_s }.map do |name, field|
+              "#{@export.transform_key(name)}: #{map_field(field)}"
+            end
+            all_properties = [discriminator_prop, *properties].join(', ')
+            "z.object({ #{all_properties} })"
+          elsif variant.tag
+            base_schema = map_param(variant)
+            "#{base_schema}.extend({ #{discriminator_field}: z.literal('#{variant.tag}') })"
+          else
+            map_param(variant)
+          end
+        end
 
         "z.discriminatedUnion('#{discriminator_field}', [#{variant_schemas.join(', ')}])"
       end

data/lib/apiwork/introspection/dump/action.rb

@@ -52,7 +52,7 @@ module Apiwork
 
         def build_response(response)
           return { body: {}, description: i18n_lookup(:response, :description), no_content: false } unless response
-          return { body: {}, description: response.description || i18n_lookup(:response, :description), no_content: true } if response.no_content?
+          return { body: nil, description: response.description || i18n_lookup(:response, :description), no_content: true } if response.no_content?
 
           description = response.description || i18n_lookup(:response, :description)
           body_shape = response.body