apiwork 0.3.1 → 0.5.0

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/api.rb

@@ -33,6 +33,14 @@ module Apiwork
         @dump[:base_path]
       end
 
+      # @api public
+      # The fingerprint for this API.
+      #
+      # @return [String]
+      def fingerprint
+        @dump[:fingerprint]
+      end
+
       # @api public
       # The info for this API.
       #
@@ -65,6 +73,14 @@ module Apiwork
         @enums ||= @dump[:enums].transform_values { |dump| Enum.new(dump) }
       end
 
+      # @api public
+      # The supported locales for this API.
+      #
+      # @return [Array<Symbol>]
+      def locales
+        @dump[:locales]
+      end
+
       # @api public
       # The error codes for this API.
       #
@@ -80,6 +96,8 @@ module Apiwork
       def to_h
         {
           base_path:,
+          fingerprint:,
+          locales:,
           enums: enums.transform_values(&:to_h),
           error_codes: error_codes.transform_values(&:to_h),
           info: info&.to_h,

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

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

@@ -18,7 +18,9 @@ module Apiwork
             base_path: @api_class.transform_path(@api_class.base_path),
             enums: type_dump_hash[:enums],
             error_codes: build_error_codes(collect_all_error_code_keys(resources)),
+            fingerprint: @api_class.fingerprint,
             info: build_info,
+            locales: @api_class.locales,
             types: type_dump_hash[:types],
           }
         end

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

@@ -162,15 +162,28 @@ module Apiwork
 
           result = {
             reference:,
+            as: nil,
+            default: nil,
+            deprecated: false,
+            description: nil,
+            discriminator: nil,
             enum: element.enum,
+            example: nil,
             format: element.format,
             max: element.max,
             min: element.min,
+            nullable: false,
+            of: nil,
+            optional: false,
+            partial: false,
             shape: resolved_shape,
+            tag: nil,
             type: reference ? :reference : type_value,
+            value: nil,
+            variants: [],
           }
 
-          result[:of] = build_of_from_element(element.inner) if element.type == :array && element.inner
+          result[:of] = build_of_from_element(element.inner) if [:array, :record].include?(element.type) && element.inner
 
           result
         end
@@ -294,19 +307,39 @@ module Apiwork
           of = options[:of]
           return nil unless of
 
+          union = of.type == :union
+          union_shape = union && of.shape.is_a?(Apiwork::API::Union) ? of.shape : nil
+
           result = {
+            as: nil,
+            default: nil,
+            deprecated: false,
+            description: nil,
+            discriminator: union ? of.discriminator : nil,
             enum: of.enum,
+            example: nil,
             format: of.format,
             max: of.max,
             min: of.min,
+            nullable: false,
+            of: nil,
+            optional: false,
+            partial: false,
             reference: nil,
-            shape: of.shape ? build_nested_shape(of.shape) : {},
+            shape: union ? {} : build_of_shape(of),
+            tag: nil,
             type: of.type,
+            value: nil,
+            variants: union_shape ? union_shape.variants.map { |variant| build_api_variant(variant) } : [],
           }
           result[:of] = build_api_of({ of: of.inner }) if of.type == :array && of.inner
           result
         end
 
+        def build_of_shape(of)
+          of.shape ? build_nested_shape(of.shape) : {}
+        end
+
         def build_api_variant(variant)
           {
             as: nil,
@@ -320,7 +353,7 @@ module Apiwork
             max: nil,
             min: nil,
             nullable: false,
-            of: build_api_variant_of(variant),
+            of: build_api_of(variant),
             optional: false,
             partial: variant[:partial] == true,
             reference: nil,
@@ -332,23 +365,6 @@ module Apiwork
           }
         end
 
-        def build_api_variant_of(variant)
-          of = variant[:of]
-          return nil unless of
-
-          result = {
-            enum: of.enum,
-            format: of.format,
-            max: of.max,
-            min: of.min,
-            reference: nil,
-            shape: of.shape ? build_nested_shape(of.shape) : {},
-            type: of.type,
-          }
-          result[:of] = build_api_variant_of({ of: of.inner }) if of.type == :array && of.inner
-          result
-        end
-
         def build_shape(options)
           dumped = options[:shape] ? build_nested_shape(options[:shape]) : nil
 

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

@@ -4,11 +4,12 @@ module Apiwork
   module Introspection
     module Dump
       class Resource
-        def initialize(resource, api_class, parent_identifiers: [], parent_param: nil, parent_singular: false)
+        def initialize(resource, api_class, parent_identifiers: [], parent_param: nil, parent_path: nil, parent_singular: false)
           @resource = resource
           @api_class = api_class
           @parent_identifiers = parent_identifiers
           @parent_param = parent_param
+          @parent_path = parent_path
           @parent_singular = parent_singular
         end
 
@@ -57,10 +58,11 @@ module Apiwork
         end
 
         def build_resource_path(formatted_segment)
-          return formatted_segment if @parent_identifiers.empty?
-          return formatted_segment if @parent_singular
+          return formatted_segment if @parent_path.nil?
+          return "#{@parent_path}/#{formatted_segment}" if @parent_singular
 
-          ":#{@parent_param || "#{@parent_identifiers.last.singularize}_id"}/#{formatted_segment}"
+          param = @parent_param || "#{@parent_identifiers.last.singularize}_id"
+          "#{@parent_path}/:#{param}/#{formatted_segment}"
         end
 
         def build_nested_resources(resource_path)
@@ -70,6 +72,7 @@ module Apiwork
 
           nested_options = {
             parent_identifiers: child_parent_identifiers,
+            parent_path: resource_path,
             parent_singular: @resource.singular,
           }
           nested_options[:parent_param] = @resource.param&.to_s || "#{@resource.name.to_s.singularize}_id" unless @resource.singular

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

@@ -4,6 +4,11 @@ module Apiwork
   module Introspection
     module Dump
       class Type
+        PRIMITIVE_TYPES = %i[
+          array binary boolean date datetime decimal enum float integer json
+          literal number object record string text time union unknown uuid
+        ].to_set.freeze
+
         def initialize(api_class)
           @api_class = api_class
         end
@@ -99,7 +104,11 @@ module Apiwork
         end
 
         def build_param(name, options, scope)
-          reference = resolve_type_reference(options[:type], scope)
+          reference = if options[:custom_type]
+                        resolve_type_reference(options[:custom_type], scope)
+                      elsif options[:type] && !PRIMITIVE_TYPES.include?(options[:type])
+                        resolve_type_reference(options[:type], scope)
+                      end
 
           {
             reference:,
@@ -142,7 +151,7 @@ module Apiwork
             max: nil,
             min: nil,
             nullable: false,
-            of: resolve_variant_of(variant, scope),
+            of: resolve_of(variant, scope),
             optional: false,
             partial: variant[:partial] == true,
             shape: build_nested_shape(variant[:shape]),
@@ -201,23 +210,41 @@ module Apiwork
           of = options[:of]
           return nil unless of
 
+          union = of.type == :union
+          union_shape = union && of.shape.is_a?(Apiwork::API::Union) ? of.shape : nil
           type_value = of.type
           scoped_name = resolve_scoped_type_name(type_value, scope)
-          resolved_shape = of.shape ? build_nested_shape(of.shape) : {}
 
           result = {
+            as: nil,
+            default: nil,
+            deprecated: false,
+            description: nil,
+            discriminator: union ? of.discriminator : nil,
             enum: of.enum,
+            example: nil,
             format: of.format,
             max: of.max,
             min: of.min,
+            nullable: false,
+            of: nil,
+            optional: false,
+            partial: false,
             reference: scoped_name,
-            shape: resolved_shape,
+            shape: union ? {} : resolve_of_shape(of),
+            tag: nil,
             type: scoped_name ? :reference : type_value,
+            value: nil,
+            variants: union_shape ? union_shape.variants.map { |variant| build_variant(variant, scope) } : [],
           }
           result[:of] = resolve_of({ of: of.inner }, scope) if of.type == :array && of.inner
           result
         end
 
+        def resolve_of_shape(of)
+          of.shape ? build_nested_shape(of.shape) : {}
+        end
+
         def resolve_variant_enum(variant, scope)
           return nil unless variant[:enum]
 
@@ -228,27 +255,6 @@ module Apiwork
           end
         end
 
-        def resolve_variant_of(variant, scope)
-          of = variant[:of]
-          return nil unless of
-
-          type_value = of.type
-          scoped_name = resolve_scoped_type_name(type_value, scope)
-          resolved_shape = of.shape ? build_nested_shape(of.shape) : {}
-
-          result = {
-            enum: of.enum,
-            format: of.format,
-            max: of.max,
-            min: of.min,
-            reference: scoped_name,
-            shape: resolved_shape,
-            type: scoped_name ? :reference : type_value,
-          }
-          result[:of] = resolve_variant_of({ of: of.inner }, scope) if of.type == :array && of.inner
-          result
-        end
-
         def build_enum(qualified_name, enum_definition)
           {
             deprecated: enum_definition.deprecated?,

data/lib/apiwork/introspection/param/array.rb

@@ -20,6 +20,22 @@ module Apiwork
       #   param.max # => 10 or nil
       #   param.boundable? # => true
       class Array < Base
+        # @api public
+        # The default for this param.
+        #
+        # @return [Object, nil]
+        def default
+          @dump[:default]
+        end
+
+        # @api public
+        # The example for this param.
+        #
+        # @return [Object, nil]
+        def example
+          @dump[:example]
+        end
+
         # @api public
         # The of for this param.
         #
@@ -62,6 +78,14 @@ module Apiwork
           true
         end
 
+        # @api public
+        # Whether this param is concrete.
+        #
+        # @return [Boolean]
+        def concrete?
+          true
+        end
+
         # @api public
         # Whether this param is boundable.
         #
@@ -76,6 +100,8 @@ module Apiwork
         # @return [Hash]
         def to_h
           result = super
+          result[:default] = default
+          result[:example] = example
           result[:max] = max
           result[:min] = min
           result[:of] = of&.to_h

data/lib/apiwork/introspection/param/base.rb

@@ -49,35 +49,19 @@ module Apiwork
         end
 
         # @api public
-        # The example for this param.
-        #
-        # @return [Object, nil]
-        def example
-          @dump[:example]
-        end
-
-        # @api public
-        # The default for this param.
+        # The tag for this param.
         #
-        # @return [Object, nil]
-        def default
-          @dump[:default]
+        # @return [String, nil]
+        def tag
+          @dump[:tag]
         end
 
         # @api public
-        # Whether this param has a default.
+        # Whether this param is concrete.
         #
         # @return [Boolean]
-        def default?
-          @dump.key?(:default)
-        end
-
-        # @api public
-        # The tag for this param.
-        #
-        # @return [String, nil]
-        def tag
-          @dump[:tag]
+        def concrete?
+          false
         end
 
         # @api public
@@ -104,6 +88,14 @@ module Apiwork
           false
         end
 
+        # @api public
+        # Whether this param is a record.
+        #
+        # @return [Boolean]
+        def record?
+          false
+        end
+
         # @api public
         # Whether this param is a union.
         #
@@ -270,10 +262,8 @@ module Apiwork
         # @return [Hash]
         def to_h
           {
-            default: default,
             deprecated: deprecated?,
             description: description,
-            example: example,
             nullable: nullable?,
             optional: optional?,
             type: type,

data/lib/apiwork/introspection/param/binary.rb

@@ -20,6 +20,30 @@ module Apiwork
       #     param.enum_reference? # => false
       #   end
       class Binary < Base
+        # @api public
+        # The default for this param.
+        #
+        # @return [Object, nil]
+        def default
+          @dump[:default]
+        end
+
+        # @api public
+        # The example for this param.
+        #
+        # @return [Object, nil]
+        def example
+          @dump[:example]
+        end
+
+        # @api public
+        # Whether this param is concrete.
+        #
+        # @return [Boolean]
+        def concrete?
+          true
+        end
+
         # @api public
         # Whether this param is scalar.
         #
@@ -67,6 +91,18 @@ module Apiwork
         def formattable?
           false
         end
+
+        # @api public
+        # Converts this param to a hash.
+        #
+        # @return [Hash]
+        def to_h
+          result = super
+          result[:default] = default
+          result[:enum] = enum if enum?
+          result[:example] = example
+          result
+        end
       end
     end
   end