feat!: use plural resource names for per-action types and add request/response wrappers

Per-action type names now use the plural resource identifier instead of the singular contract scope prefix. This aligns type names with endpoint naming (invoices/show, not invoice/show).

Before: invoice_show_response_body, invoice_create_request_body
After: invoices_show_response_body, invoices_create_request_body

New wrapper types register *_request and *_response types in the type registry, referencing their leaf types (request_query, request_body, response_body).

Surface resolver exposes action_types for export consumers. Sorbus now uses types from the type system directly instead of generating its own action schemas.

Author: qwuide

lib/apiwork/adapter/base.rb

@@ -214,14 +214,16 @@ def register_api(api_class)
         build_error_response_body(api_class, error_serializer_class)
       end
 
-      def register_contract(contract_class, representation_class, actions)
+      def register_contract(contract_class, representation_class, resource: nil)
+        resource_actions = resource ? resource.actions : {}
+
         capabilities.each do |capability|
-          capability.contract_types(contract_class, representation_class, actions)
+          capability.contract_types(contract_class, representation_class, resource_actions)
         end
 
         self.class.resource_serializer.new(representation_class).contract_types(contract_class)
 
-        build_action_responses(contract_class, representation_class, actions)
+        build_action_responses(contract_class, representation_class, resource_actions, resource.name) if resource
       end
 
       def apply_request_transformers(request, phase:)
@@ -250,33 +252,35 @@ def apply_capabilities(data, representation_class, request, wrapper_type:)
         )
       end
 
-      def build_action_responses(contract_class, representation_class, actions)
+      def build_action_responses(contract_class, representation_class, actions, resource_name)
         actions.each_value do |action|
-          build_action_response(contract_class, representation_class, action)
+          build_action_response(contract_class, representation_class, action, resource_name)
         end
       end
 
-      def build_action_response(contract_class, representation_class, action)
+      def build_action_response(contract_class, representation_class, action, resource_name)
         contract_action = contract_class.action(action.name)
         return if contract_action.resets_response?
 
         case action.name
         when :index
-          build_collection_action_response(contract_class, representation_class, action, contract_action)
+          build_collection_action_response(contract_class, representation_class, action, contract_action, resource_name)
         when :show, :create, :update
-          build_member_action_response(contract_class, representation_class, action, contract_action)
+          build_member_action_response(contract_class, representation_class, action, contract_action, resource_name)
         when :destroy
           contract_action.response { no_content! }
         else
-          build_custom_action_response(contract_class, representation_class, action, contract_action)
+          build_custom_action_response(contract_class, representation_class, action, contract_action, resource_name)
         end
 
-        build_request_query_type(contract_class, action.name, contract_action)
-        build_request_body_type(contract_class, action.name, contract_action)
+        build_request_query_type(contract_class, action.name, contract_action, resource_name)
+        build_request_body_type(contract_class, action.name, contract_action, resource_name)
+        build_request_type(contract_class, action.name, contract_action, resource_name)
+        build_response_type(contract_class, action.name, contract_action, resource_name)
       end
 
-      def build_member_action_response(contract_class, representation_class, action, contract_action)
-        build_response_body_type(contract_class, representation_class, action.name, :member)
+      def build_member_action_response(contract_class, representation_class, action, contract_action, resource_name)
+        build_response_body_type(contract_class, representation_class, action.name, :member, resource_name)
         member_shape_class = self.class.member_wrapper.shape_class
         data_type = resolve_resource_data_type(representation_class)
 
@@ -287,8 +291,8 @@ def build_member_action_response(contract_class, representation_class, action, c
         end
       end
 
-      def build_collection_action_response(contract_class, representation_class, action, contract_action)
-        build_response_body_type(contract_class, representation_class, action.name, :collection)
+      def build_collection_action_response(contract_class, representation_class, action, contract_action, resource_name)
+        build_response_body_type(contract_class, representation_class, action.name, :collection, resource_name)
         collection_shape_class = self.class.collection_wrapper.shape_class
         data_type = resolve_resource_data_type(representation_class)
 
@@ -299,19 +303,20 @@ def build_collection_action_response(contract_class, representation_class, actio
         end
       end
 
-      def build_custom_action_response(contract_class, representation_class, action, contract_action)
+      def build_custom_action_response(contract_class, representation_class, action, contract_action, resource_name)
         if action.method == :delete
           contract_action.response { no_content! }
         elsif action.collection?
-          build_collection_action_response(contract_class, representation_class, action, contract_action)
+          build_collection_action_response(contract_class, representation_class, action, contract_action, resource_name)
         elsif action.member?
-          build_member_action_response(contract_class, representation_class, action, contract_action)
+          build_member_action_response(contract_class, representation_class, action, contract_action, resource_name)
         end
       end
 
-      def build_response_body_type(contract_class, representation_class, action_name, response_type)
-        type_name = [action_name, 'response_body'].join('_').to_sym
-        return if contract_class.type?(type_name)
+      def build_response_body_type(contract_class, representation_class, action_name, response_type, resource_name)
+        type_name = build_action_type_name(resource_name, action_name, 'response_body')
+        api_class = contract_class.api_class
+        return if api_class.type_registry.key?(type_name)
 
         shape_class = if response_type == :collection
                         self.class.collection_wrapper.shape_class
@@ -320,35 +325,74 @@ def build_response_body_type(contract_class, representation_class, action_name,
                       end
         data_type = resolve_resource_data_type(representation_class)
 
-        contract_class.object(type_name) do |object|
+        api_class.register_object(type_name) do |object|
           shape_class.apply(object, representation_class.root_key, capabilities, representation_class, response_type, data_type:)
         end
       end
 
-      def build_request_query_type(contract_class, action_name, contract_action)
+      def build_request_query_type(contract_class, action_name, contract_action, resource_name)
         request = contract_action.request
         return unless request.query.params.any?
 
-        type_name = [action_name, 'request_query'].join('_').to_sym
-        return if contract_class.type?(type_name)
+        type_name = build_action_type_name(resource_name, action_name, 'request_query')
+        api_class = contract_class.api_class
+        return if api_class.type_registry.key?(type_name)
 
-        contract_class.object(type_name) do |object|
+        api_class.register_object(type_name) do |object|
           request.query.params.each { |name, param| object.param(name, **normalize_request_param(param)) }
         end
       end
 
-      def build_request_body_type(contract_class, action_name, contract_action)
+      def build_request_body_type(contract_class, action_name, contract_action, resource_name)
         request = contract_action.request
         return unless request.body.params.any?
 
-        type_name = [action_name, 'request_body'].join('_').to_sym
-        return if contract_class.type?(type_name)
+        type_name = build_action_type_name(resource_name, action_name, 'request_body')
+        api_class = contract_class.api_class
+        return if api_class.type_registry.key?(type_name)
 
-        contract_class.object(type_name) do |object|
+        api_class.register_object(type_name) do |object|
           request.body.params.each { |name, param| object.param(name, **normalize_request_param(param)) }
         end
       end
 
+      def build_request_type(contract_class, action_name, contract_action, resource_name)
+        request = contract_action.request
+        return unless request.query.params.any? || request.body.params.any?
+
+        type_name = build_action_type_name(resource_name, action_name, 'request')
+        api_class = contract_class.api_class
+        return if api_class.type_registry.key?(type_name)
+
+        query_type_name = build_action_type_name(resource_name, action_name, 'request_query')
+        body_type_name = build_action_type_name(resource_name, action_name, 'request_body')
+
+        api_class.register_object(type_name) do |object|
+          object.param(:query, type: query_type_name) if request.query.params.any?
+          object.param(:body, type: body_type_name) if request.body.params.any?
+        end
+      end
+
+      def build_response_type(contract_class, action_name, contract_action, resource_name)
+        type_name = build_action_type_name(resource_name, action_name, 'response')
+        api_class = contract_class.api_class
+        return if api_class.type_registry.key?(type_name)
+
+        body_type_name = build_action_type_name(resource_name, action_name, 'response_body')
+
+        if contract_action.response.no_content?
+          api_class.register_object(type_name) { |_object| }
+        else
+          api_class.register_object(type_name) do |object|
+            object.param(:body, type: body_type_name)
+          end
+        end
+      end
+
+      def build_action_type_name(resource_name, action_name, suffix)
+        [resource_name, action_name, suffix].join('_').to_sym
+      end
+
       def normalize_request_param(param)
         options = param.except(:name, :custom_type, :union, :partial)
         options[:type] = param[:custom_type] if param[:custom_type]

lib/apiwork/api/base.rb

@@ -727,9 +727,8 @@ def ensure_contract_built!(contract_class)
           @built_contracts.add(contract_class)
 
           resource = @root_resource.find_resource { |resource| resource.resolve_contract_class == contract_class }
-          actions = resource ? resource.actions : {}
 
-          adapter.register_contract(contract_class, representation_class, actions)
+          adapter.register_contract(contract_class, representation_class, resource:)
         end
 
         def ensure_pre_pass_complete!
@@ -788,13 +787,11 @@ def build_contracts_for_resource(resource)
           contract_class = resource.resolve_contract_class
           return unless contract_class
           return if @built_contracts.include?(contract_class)
-
-          representation_class = contract_class.representation_class
-          return unless representation_class
+          return unless contract_class.representation_class
 
           @built_contracts.add(contract_class)
 
-          adapter.register_contract(contract_class, representation_class, resource.actions)
+          adapter.register_contract(contract_class, contract_class.representation_class, resource:)
         end
       end
     end

lib/apiwork/export/surface_resolver.rb

@@ -21,8 +21,36 @@ def enums
         @enums ||= compute_reachable_enums
       end
 
+      def action_types
+        @action_types ||= compute_action_types
+      end
+
       private
 
+      def compute_action_types
+        type_names = Set.new
+        @api.resources.each_value do |resource|
+          collect_action_type_names_from_resource(resource, type_names)
+        end
+        @api.types.select { |name, _| type_names.include?(name) }
+      end
+
+      def collect_action_type_names_from_resource(resource, type_names, parent_identifiers: [])
+        identifier = resource.identifier
+        prefix = (parent_identifiers + [identifier]).join('_')
+
+        resource.actions.each_key do |action_name|
+          %w[request_query request_body request response_body response].each do |suffix|
+            type_name = [prefix, action_name, suffix].join('_').to_sym
+            type_names << type_name if @api.types.key?(type_name)
+          end
+        end
+
+        resource.resources.each_value do |nested|
+          collect_action_type_names_from_resource(nested, type_names, parent_identifiers: parent_identifiers + [identifier])
+        end
+      end
+
       def compute_reachable_types
         type_names = collect_type_names_from_actions
         expand_transitive_dependencies(type_names)

lib/apiwork/export/type_script_mapper.rb

@@ -14,8 +14,8 @@ def initialize(export)
       end
 
       def map(surface)
-        types = build_enum_types(surface) +
-                build_type_definitions(surface) +
+        types = build_enum_types(surface.enums) +
+                build_type_definitions(surface.types) +
                 build_action_types +
                 build_action_response_types
 
@@ -298,47 +298,22 @@ def build_action_response_types
         types
       end
 
-      def build_action_response_envelope_types
-        types = []
-
-        traverse_resources do |resource|
-          resource_name = resource.identifier.to_sym
-          parent_identifiers = resource.parent_identifiers
-
-          resource.actions.each do |action_name, action|
-            type_name = action_type_name(resource_name, action_name, 'Response', parent_identifiers:)
-            response = action.response
-
-            code = if response.no_content?
-                     "export interface #{type_name} {}"
-                   else
-                     body_ref = action_type_name(resource_name, action_name, 'ResponseBody', parent_identifiers:)
-                     "export interface #{type_name} {\n  body: #{body_ref};\n}"
-                   end
-
-            types << { code:, name: type_name }
-          end
-        end
-
-        types
-      end
-
       def traverse_resources(resources: @export.api.resources, &block)
         resources.each_value do |resource|
           yield(resource)
           traverse_resources(resources: resource.resources, &block) if resource.resources.any?
         end
       end
 
-      def build_enum_types(surface)
-        surface.enums.map do |name, enum|
+      def build_enum_types(enums)
+        enums.map do |name, enum|
           { code: build_enum_type(name, enum), name: pascal_case(name) }
         end
       end
 
-      def build_type_definitions(surface)
-        TypeAnalysis.topological_sort_types(surface.types.transform_values(&:to_h)).map(&:first).map do |type_name|
-          type = surface.types[type_name]
+      def build_type_definitions(types)
+        TypeAnalysis.topological_sort_types(types.transform_values(&:to_h)).map(&:first).map do |type_name|
+          type = types[type_name]
           code = type.union? ? build_union_type(type_name, type) : build_interface(type_name, type)
           { code:, name: pascal_case(type_name) }
         end

lib/apiwork/export/zod_mapper.rb

@@ -30,10 +30,10 @@ def initialize(export)
       def map(surface)
         parts = []
 
-        enum_schemas = build_enum_schemas(surface)
+        enum_schemas = build_enum_schemas(surface.enums)
         parts << enum_schemas if enum_schemas.present?
 
-        type_schemas = build_type_schemas(surface)
+        type_schemas = build_type_schemas(surface.types)
         parts << type_schemas if type_schemas.present?
 
         action_schemas = build_action_schemas
@@ -317,20 +317,20 @@ def pascal_case(name)
         name.to_s.camelize(:upper)
       end
 
-      def build_enum_schemas(surface)
-        return '' if surface.enums.empty?
+      def build_enum_schemas(enums)
+        return '' if enums.empty?
 
-        surface.enums.map do |name, enum|
+        enums.map do |name, enum|
           "export const #{pascal_case(name)}Schema = z.enum([#{enum.values.sort.map { |value| "'#{value}'" }.join(', ')}]);"
         end.join("\n\n")
       end
 
-      def build_type_schemas(surface)
-        types_hash = surface.types.transform_values(&:to_h)
+      def build_type_schemas(types)
+        types_hash = types.transform_values(&:to_h)
         lazy_types = TypeAnalysis.cycle_breaking_types(types_hash)
 
         TypeAnalysis.topological_sort_types(types_hash).map(&:first).map do |type_name|
-          type = surface.types[type_name]
+          type = types[type_name]
           recursive = lazy_types.include?(type_name)
 
           if type.union?
@@ -398,29 +398,6 @@ def build_action_response_schemas
         schemas.join("\n\n")
       end
 
-      def build_action_response_envelope_schemas
-        schemas = []
-
-        traverse_resources do |resource|
-          resource_name = resource.identifier.to_sym
-          parent_identifiers = resource.parent_identifiers
-
-          resource.actions.each do |action_name, action|
-            schema_name = "#{action_type_name(resource_name, action_name, 'Response', parent_identifiers:)}Schema"
-            response = action.response
-
-            schemas << if response.no_content?
-                         "export const #{schema_name} = z.object({});"
-                       else
-                         body_ref = "#{action_type_name(resource_name, action_name, 'ResponseBody', parent_identifiers:)}Schema"
-                         "export const #{schema_name} = z.object({ body: #{body_ref} });"
-                       end
-          end
-        end
-
-        schemas.join("\n\n")
-      end
-
       def traverse_resources(resources: @export.api.resources, &block)
         resources.each_value do |resource|
           yield(resource)