apiwork 0.0.0.pre → 0.1.1

data/lib/apiwork/export/zod_mapper.rb

@@ -0,0 +1,421 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Export
+    class ZodMapper
+      TYPE_MAP = {
+        binary: 'z.string()',
+        boolean: 'z.boolean()',
+        date: 'z.iso.date()',
+        datetime: 'z.iso.datetime()',
+        decimal: 'z.number()',
+        integer: 'z.number().int()',
+        number: 'z.number()',
+        string: 'z.string()',
+        time: 'z.iso.time()',
+        unknown: 'z.unknown()',
+        uuid: 'z.uuid()',
+      }.freeze
+
+      class << self
+        def map(export, surface)
+          new(export).map(surface)
+        end
+      end
+
+      def initialize(export)
+        @export = export
+      end
+
+      def map(surface)
+        @surface = surface
+        parts = []
+
+        enum_schemas = build_enum_schemas
+        parts << enum_schemas if enum_schemas.present?
+
+        type_schemas = build_type_schemas
+        parts << type_schemas if type_schemas.present?
+
+        action_schemas = build_action_schemas
+        parts << action_schemas if action_schemas.present?
+
+        parts.join("\n\n")
+      end
+
+      def build_object_schema(type_name, type, recursive: false)
+        schema_name = pascal_case(type_name)
+
+        properties = type.shape.sort_by { |name, _param| name.to_s }.map do |name, param|
+          key = @export.transform_key(name)
+          zod_type = map_field(param)
+          "  #{key}: #{zod_type}"
+        end.join(",\n")
+
+        type_annotation = recursive ? ": z.ZodType<#{schema_name}>" : ''
+
+        if recursive
+          "export const #{schema_name}Schema#{type_annotation} = z.lazy(() => z.object({\n#{properties}\n}));"
+        elsif type.extends?
+          build_object_schema_code(schema_name, properties, type.extends, type_annotation:)
+        else
+          "export const #{schema_name}Schema#{type_annotation} = z.object({\n#{properties}\n});"
+        end
+      end
+
+      def build_object_schema_code(schema_name, properties, extends, type_annotation: '')
+        base_schemas = extends.map { |type| "#{pascal_case(type)}Schema" }
+
+        base_chain = if base_schemas.size == 1
+                       base_schemas.first
+                     else
+                       first, *rest = base_schemas
+                       rest.reduce(first) { |acc, schema| "#{acc}.merge(#{schema})" }
+                     end
+
+        if properties.empty?
+          "export const #{schema_name}Schema#{type_annotation} = #{base_chain};"
+        else
+          "export const #{schema_name}Schema#{type_annotation} = #{base_chain}.extend({\n#{properties}\n});"
+        end
+      end
+
+      def build_union_schema(type_name, type, recursive: false)
+        schema_name = pascal_case(type_name)
+
+        variant_schemas = type.variants.map do |variant|
+          base_schema = map_param(variant)
+
+          if type.discriminator && variant.tag && !reference_contains_discriminator?(variant, type.discriminator)
+            "#{base_schema}.extend({ #{@export.transform_key(type.discriminator)}: z.literal('#{variant.tag}') })"
+          else
+            base_schema
+          end
+        end
+
+        union_body = variant_schemas.map { |schema| "  #{schema}" }.join(",\n")
+
+        type_annotation = recursive ? ": z.ZodType<#{schema_name}>" : ''
+
+        union_code = if type.discriminator
+                       "z.discriminatedUnion('#{@export.transform_key(type.discriminator)}', [\n#{union_body}\n])"
+                     else
+                       "z.union([\n#{union_body}\n])"
+                     end
+
+        if recursive
+          "export const #{schema_name}Schema#{type_annotation} = z.lazy(() => #{union_code});"
+        else
+          "export const #{schema_name}Schema#{type_annotation} = #{union_code};"
+        end
+      end
+
+      def build_action_request_query_schema(resource_name, action_name, query_params, parent_identifiers: [])
+        properties = query_params.sort_by { |name, _param| name.to_s }.map do |param_name, param|
+          key = @export.transform_key(param_name)
+          zod_type = map_field(param)
+          "  #{key}: #{zod_type}"
+        end.join(",\n")
+
+        "export const #{action_type_name(resource_name, action_name, 'RequestQuery', parent_identifiers:)}Schema = z.object({\n#{properties}\n});"
+      end
+
+      def build_action_request_body_schema(resource_name, action_name, body_params, parent_identifiers: [])
+        properties = body_params.sort_by { |name, _param| name.to_s }.map do |param_name, param|
+          key = @export.transform_key(param_name)
+          zod_type = map_field(param)
+          "  #{key}: #{zod_type}"
+        end.join(",\n")
+
+        "export const #{action_type_name(resource_name, action_name, 'RequestBody', parent_identifiers:)}Schema = z.object({\n#{properties}\n});"
+      end
+
+      def build_action_request_schema(resource_name, action_name, request, parent_identifiers: [])
+        nested_properties = []
+
+        if request[:query].any?
+          nested_properties << "  query: #{action_type_name(resource_name, action_name, 'RequestQuery', parent_identifiers:)}Schema"
+        end
+
+        if request[:body].any?
+          nested_properties << "  body: #{action_type_name(resource_name, action_name, 'RequestBody', parent_identifiers:)}Schema"
+        end
+
+        "export const #{action_type_name(
+          resource_name,
+          action_name,
+          'Request',
+          parent_identifiers:,
+        )}Schema = z.object({\n#{nested_properties.join(",\n")}\n});"
+      end
+
+      def build_action_response_body_schema(resource_name, action_name, response_body, parent_identifiers: [])
+        "export const #{action_type_name(resource_name, action_name, 'ResponseBody', parent_identifiers:)}Schema = #{map_param(response_body)};"
+      end
+
+      def build_action_response_schema(resource_name, action_name, response, parent_identifiers: [])
+        "export const #{action_type_name(
+          resource_name,
+          action_name,
+          'Response',
+          parent_identifiers:,
+        )}Schema = z.object({\n  body: #{action_type_name(
+          resource_name,
+          action_name,
+          'ResponseBody',
+          parent_identifiers:,
+        )}Schema\n});"
+      end
+
+      def action_type_name(resource_name, action_name, suffix, parent_identifiers: [])
+        "#{pascal_case((parent_identifiers + [resource_name.to_s, action_name.to_s]).join('_'))}#{suffix.split(/(?=[A-Z])/).map(&:capitalize).join}"
+      end
+
+      def map_field(param, force_optional: nil)
+        if param.reference? && type_or_enum_reference?(param.reference)
+          schema_name = pascal_case(param.reference)
+          type = "#{schema_name}Schema"
+          return apply_modifiers(type, param, force_optional:)
+        end
+
+        type = map_param(param)
+        type = resolve_enum_schema(param) || type
+
+        apply_modifiers(type, param, force_optional:)
+      end
+
+      def map_param(param)
+        if param.object?
+          map_object_type(param)
+        elsif param.array?
+          map_array_type(param)
+        elsif param.union?
+          map_union_type(param)
+        elsif param.literal?
+          map_literal_type(param)
+        elsif param.reference? && type_or_enum_reference?(param.reference)
+          resolve_enum_schema(param) || schema_reference(param.reference)
+        else
+          resolve_enum_schema(param) || map_primitive(param)
+        end
+      end
+
+      def map_object_type(param)
+        return 'z.record(z.string(), z.unknown())' if param.shape.empty?
+
+        partial = param.partial?
+
+        properties = param.shape.sort_by { |name, _field| name.to_s }.map do |name, field|
+          key = @export.transform_key(name)
+          zod_type = if partial
+                       map_field(field, force_optional: false)
+                     else
+                       map_field(field)
+                     end
+          "#{key}: #{zod_type}"
+        end.join(', ')
+
+        base_object = "z.object({ #{properties} })"
+        partial ? "#{base_object}.partial()" : base_object
+      end
+
+      def map_array_type(param)
+        items_type = param.of
+
+        if items_type.nil? && param.shape.any?
+          items_schema = map_object_type(param)
+          base = "z.array(#{items_schema})"
+        elsif items_type
+          items_schema = map_param(items_type)
+          base = "z.array(#{items_schema})"
+        else
+          base = 'z.array(z.unknown())'
+        end
+
+        base += ".min(#{param.min})" unless param.min.nil?
+        base += ".max(#{param.max})" unless param.max.nil?
+        base
+      end
+
+      def map_union_type(param)
+        if param.discriminator
+          map_discriminated_union(param)
+        else
+          variants = param.variants.map { |variant| map_param(variant) }
+          "z.union([#{variants.join(', ')}])"
+        end
+      end
+
+      def map_discriminated_union(param)
+        discriminator_field = @export.transform_key(param.discriminator)
+
+        variant_schemas = param.variants.map { |variant| map_param(variant) }
+
+        "z.discriminatedUnion('#{discriminator_field}', [#{variant_schemas.join(', ')}])"
+      end
+
+      def map_literal_type(param)
+        case param.value
+        when nil then 'z.null()'
+        when String then "z.literal('#{param.value}')"
+        when Numeric, TrueClass, FalseClass then "z.literal(#{param.value})"
+        else "z.literal('#{param.value}')"
+        end
+      end
+
+      def map_primitive(param)
+        return 'z.unknown()' if param.unknown?
+
+        format = param.format&.to_sym if param.formattable?
+
+        base_type = if format
+                      map_format_to_zod(format)
+                    else
+                      TYPE_MAP[param.type.to_sym] || 'z.unknown()'
+                    end
+
+        if param.boundable?
+          base_type += ".min(#{param.min})" unless param.min.nil?
+          base_type += ".max(#{param.max})" unless param.max.nil?
+        end
+
+        base_type
+      end
+
+      def map_format_to_zod(format)
+        case format
+        when :email then 'z.email()'
+        when :uuid then 'z.uuid()'
+        when :url then 'z.url()'
+        when :ipv4 then 'z.ipv4()'
+        when :ipv6 then 'z.ipv6()'
+        when :date then 'z.iso.date()'
+        when :datetime then 'z.iso.datetime()'
+        when :password, :hostname then 'z.string()'
+        when :int32, :int64 then 'z.number().int()'
+        when :float, :double then 'z.number()'
+        else 'z.string()'
+        end
+      end
+
+      def schema_reference(symbol)
+        "#{pascal_case(symbol)}Schema"
+      end
+
+      def pascal_case(name)
+        name.to_s.camelize(:upper)
+      end
+
+      private
+
+      def build_enum_schemas
+        return '' if @surface.enums.empty?
+
+        @surface.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
+        types_hash = @surface.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]
+          recursive = lazy_types.include?(type_name)
+
+          if type.union?
+            build_union_schema(type_name, type, recursive:)
+          else
+            build_object_schema(type_name, type, recursive:)
+          end
+        end.join("\n\n")
+      end
+
+      def build_action_schemas
+        schemas = []
+
+        traverse_resources do |resource|
+          resource_name = resource.identifier.to_sym
+          parent_identifiers = resource.parent_identifiers
+
+          resource.actions.each do |action_name, action|
+            request = action.request
+            if request && (request.query? || request.body?)
+              if request.query?
+                schemas << build_action_request_query_schema(
+                  resource_name,
+                  action_name,
+                  request.query,
+                  parent_identifiers:,
+                )
+              end
+              if request.body?
+                schemas << build_action_request_body_schema(
+                  resource_name,
+                  action_name,
+                  request.body,
+                  parent_identifiers:,
+                )
+              end
+              schemas << build_action_request_schema(
+                resource_name,
+                action_name,
+                { body: request.body, query: request.query },
+                parent_identifiers:,
+              )
+            end
+
+            response = action.response
+            if response.no_content?
+              schemas << "export const #{action_type_name(resource_name, action_name, 'Response', parent_identifiers:)}Schema = z.never();"
+            elsif response.body?
+              schemas << build_action_response_body_schema(resource_name, action_name, response.body, parent_identifiers:)
+              schemas << build_action_response_schema(resource_name, action_name, { body: response.body }, parent_identifiers:)
+            end
+          end
+        end
+
+        schemas.join("\n\n")
+      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 type_or_enum_reference?(symbol)
+        @export.api.types.key?(symbol) || @export.api.enums.key?(symbol)
+      end
+
+      def reference_contains_discriminator?(variant, discriminator)
+        return false unless variant.reference?
+
+        referenced_type = @export.api.types[variant.reference]
+        return false unless referenced_type
+
+        referenced_type.shape.key?(discriminator)
+      end
+
+      def resolve_enum_schema(param)
+        return nil unless param.scalar? && param.enum?
+
+        if param.enum_reference? && @export.api.enums.key?(param.enum)
+          "#{pascal_case(param.enum)}Schema"
+        else
+          enum_literal = param.enum.map { |value| "'#{value}'" }.join(', ')
+          "z.enum([#{enum_literal}])"
+        end
+      end
+
+      def apply_modifiers(type, param, force_optional: nil)
+        type += '.nullable()' if param.nullable?
+        optional = force_optional.nil? ? param.optional? : force_optional
+        type += '.optional()' if optional
+        type
+      end
+    end
+  end
+end

data/lib/apiwork/export.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Apiwork
+  # @api public
+  module Export
+    class << self
+      # @!method find(name)
+      #   @api public
+      #   Finds an export by name.
+      #   @param name [Symbol]
+      #     The export name.
+      #   @return [Class<Export::Base>, nil]
+      #   @see .find!
+      #   @example
+      #     Apiwork::Export.find(:openapi)
+      #
+      # @!method find!(name)
+      #   @api public
+      #   Finds an export by name.
+      #   @param name [Symbol]
+      #     The export name.
+      #   @return [Class<Export::Base>]
+      #   @raise [KeyError] if the export is not found
+      #   @see .find
+      #   @example
+      #     Apiwork::Export.find!(:openapi)
+      #
+      # @!method register(klass)
+      #   @api public
+      #   Registers an export.
+      #   @param klass [Class<Export::Base>]
+      #     The export class with export_name set.
+      #   @see Export::Base
+      #   @example
+      #     Apiwork::Export.register(JSONSchemaExport)
+      delegate :clear!,
+               :exists?,
+               :find,
+               :find!,
+               :keys,
+               :register,
+               :values,
+               to: Registry
+
+      # @api public
+      # Generates an export for an API.
+      #
+      # @param export_name [Symbol]
+      #   The registered export name. Built-in: `:openapi`, `:typescript`, `:zod`.
+      # @param api_base_path [String]
+      #   The API base path.
+      # @param format [Symbol, nil] (nil) [:json, :yaml]
+      #   The output format. Hash exports only.
+      # @param key_format [Symbol, nil] (nil) [:camel, :kebab, :keep, :pascal, :underscore]
+      #   The key format.
+      # @param locale [Symbol, nil] (nil)
+      #   The locale for translations.
+      # @param options
+      #   Export-specific keyword arguments.
+      # @return [String]
+      # @raise [ConfigurationError] if export is not declared for the API
+      # @see Export::Base
+      #
+      # @example
+      #   Apiwork::Export.generate(:openapi, '/api/v1')
+      #   Apiwork::Export.generate(:openapi, '/api/v1', format: :yaml)
+      #   Apiwork::Export.generate(:typescript, '/api/v1', key_format: :camel)
+      def generate(export_name, api_base_path, format: nil, key_format: nil, locale: nil, **options)
+        export_class = find!(export_name)
+        export_class.generate(api_base_path, format:, key_format:, locale:, **options)
+      end
+
+      def register_defaults!
+        register(OpenAPI)
+        register(TypeScript)
+        register(Zod)
+      end
+    end
+  end
+end

data/lib/apiwork/http_error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Apiwork
+  class HttpError < ConstraintError
+    attr_reader :error_code
+
+    def initialize(issues, error_code)
+      @error_code = error_code
+      super(issues)
+    end
+
+    def layer
+      :http
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Introspection
+    class Action
+      # @api public
+      # Wraps action request definitions.
+      #
+      # Contains query parameters and/or body parameters.
+      #
+      # @example
+      #   request = action.request
+      #   request.query? # => true
+      #   request.body? # => false
+      #   request.query[:page] # => Param for page param
+      class Request
+        def initialize(dump)
+          @dump = dump
+        end
+
+        # @api public
+        # The query for this request.
+        #
+        # @return [Hash{Symbol => Param}]
+        def query
+          @query ||= @dump[:query].transform_values { |dump| Param.build(dump) }
+        end
+
+        # @api public
+        # The body for this request.
+        #
+        # @return [Hash{Symbol => Param}]
+        def body
+          @body ||= @dump[:body].transform_values { |dump| Param.build(dump) }
+        end
+
+        # @api public
+        # Whether this request has query parameters.
+        #
+        # @return [Boolean]
+        def query?
+          query.any?
+        end
+
+        # @api public
+        # Whether this request has a body.
+        #
+        # @return [Boolean]
+        def body?
+          body.any?
+        end
+
+        # @api public
+        # Converts this request to a hash.
+        #
+        # @return [Hash]
+        def to_h
+          {
+            body: body.transform_values(&:to_h),
+            query: query.transform_values(&:to_h),
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Introspection
+    class Action
+      # @api public
+      # Wraps action response definitions.
+      #
+      # @example Response with body
+      #   response = action.response
+      #   response.body? # => true
+      #   response.no_content? # => false
+      #   response.body # => Param for response body
+      #
+      # @example No content response
+      #   response.no_content? # => true
+      #   response.body? # => false
+      class Response
+        def initialize(dump)
+          @dump = dump
+        end
+
+        # @api public
+        # The body for this response.
+        #
+        # @return [Param, nil]
+        def body
+          @body ||= @dump[:body] ? Param.build(@dump[:body]) : nil
+        end
+
+        # @api public
+        # Whether this response has no content.
+        #
+        # @return [Boolean]
+        def no_content?
+          @dump[:no_content]
+        end
+
+        # @api public
+        # Whether this response has a body.
+        #
+        # @return [Boolean]
+        def body?
+          body.present?
+        end
+
+        # @api public
+        # Converts this response to a hash.
+        #
+        # @return [Hash]
+        def to_h
+          { body: body&.to_h, no_content: no_content? }
+        end
+      end
+    end
+  end
+end