sober_swag 0.18.0 → 0.22.0

data/lib/sober_swag/reporting/output/list.rb

@@ -0,0 +1,54 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # Serialize a list of some other output type.
+      # Passes views down.
+      class List < Base
+        def initialize(element_output)
+          @element_output = element_output
+        end
+
+        attr_reader :element_output
+
+        def view(view)
+          List.new(element_output.view(view))
+        end
+
+        def views
+          element_output.views
+        end
+
+        def call(input)
+          input.map { |i| element_output.call(i) }
+        end
+
+        def swagger_schema
+          schema, found = element_output.swagger_schema
+          [
+            {
+              type: 'array',
+              items: schema
+            },
+            found
+          ]
+        end
+
+        def serialize_report(input)
+          return Report::Value.new(['could not be made an array']) unless input.respond_to?(:map)
+
+          errs = {}
+          mapped = input.map.with_index do |item, idx|
+            element_output.serialize_report(item).tap { |e| errs[idx] = e if e.is_a?(Report::Base) }
+          end
+
+          if errs.any?
+            Report::List.new(errs)
+          else
+            mapped
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/output/merge_objects.rb

@@ -0,0 +1,97 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # Represents object that are marged with `allOf` in swagger.
+      #
+      # These *have* to be objects, due to how `allOf` works.
+      # This expresses a subtyping relationship.
+      #
+      # Note: non-careful use of this can generate impossible objects,
+      # IE, objects where a certain field has to be *both* a string and an integer or something.
+      # Subtyping is dangerous and should be used with care!
+      #
+      # This class is used in the implementation of {SoberSwag::Reporting::Output::Struct},
+      # in order to model the inheritence relationship structs have.
+      class MergeObjects < Base
+        ##
+        # @param parent [Interface] parent interface to use.
+        #   Should certainly be some sort of object, or a reference to it.
+        # @param child [Interface] child interface to use.
+        #   Should certainly be some sort of object, or a reference to it.
+        def initialize(parent, child)
+          @parent = parent
+          @child = child
+        end
+
+        ##
+        # @return [Interface] first object to merge
+        attr_reader :parent
+        ##
+        # @return [Interface] second object to merge
+        attr_reader :child
+
+        ##
+        # Serialize with the parent first, then merge in the child.
+        # This *does* mean that parent keys override child keys.
+        #
+        # If `parent` or `child` does not serialize some sort of object, this will result in an error.
+        def call(input)
+          parent.call(input).merge(child.call(input))
+        end
+
+        ##
+        # Child views.
+        def views
+          child.views
+        end
+
+        ##
+        # Passes on view to the *child object*.
+        def view(view)
+          MergeObjects.new(parent, child.view(view))
+        end
+
+        def serialize_report(value)
+          parent_attrs = parent.serialize_report(value)
+
+          return parent_attrs if parent_attrs.is_a?(Report::Value)
+
+          child_attrs = child.serialize_report(value)
+
+          return child_attrs if child_attrs.is_a?(Report::Value)
+
+          merge_results(parent_attrs, child_attrs)
+        end
+
+        ##
+        # Swagger schema.
+        #
+        # This will collapse 'allOf' keys, so a chain of parent methods will be
+        def swagger_schema # rubocop:disable Metrics/MethodLength
+          found = {}
+          mapped = [parent, child].flat_map do |i|
+            schema, item_found = i.swagger_schema
+            found.merge!(item_found)
+            if schema.key?(:allOf)
+              schema[:allOf]
+            else
+              [schema]
+            end
+          end
+          [{ allOf: mapped }, found]
+        end
+
+        private
+
+        def merge_results(par, chi)
+          return Report::MergedObject.new(par, chi) if [par, chi].all? { |c| c.is_a?(Report::Base) }
+          return par if par.is_a?(Report::Base)
+          return chi if chi.is_a?(Report::Base)
+
+          par.to_h.merge(chi.to_h)
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/output/null.rb

@@ -0,0 +1,25 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # Output JSON nulls.
+      class Null < Base
+        def call(input)
+          input
+        end
+
+        def serialize_report(input)
+          result = call(input)
+
+          return Report::Value.new(['was not null']) unless result.nil?
+
+          result
+        end
+
+        def swagger_schema
+          [{ type: 'null' }, {}]
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/output/number.rb

@@ -0,0 +1,25 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # Output numbers of some variety.
+      class Number < Base
+        def call(input)
+          input
+        end
+
+        def serialize_report(input)
+          result = call(input)
+
+          return Report::Value.new(['was not a number']) unless result.is_a?(Numeric)
+
+          result
+        end
+
+        def swagger_schema
+          [{ type: 'number' }, {}]
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/output/object/property.rb

@@ -0,0 +1,45 @@
+module SoberSwag
+  module Reporting
+    module Output
+      class Object
+        ##
+        # Definitions for a specific property of an object.
+        class Property
+          def initialize(output, description: nil)
+            @output = output
+            @description = description
+          end
+          ##
+          # @return [Interface]
+          attr_reader :output
+
+          ##
+          # @return [String,nil]
+          attr_reader :description
+
+          def call(item, view: :base)
+            output.call(item, view: view)
+          end
+
+          def property_schema
+            direct, refined = output.swagger_schema
+
+            if description
+              [add_description(direct), refined]
+            else
+              [direct, refined]
+            end
+          end
+
+          def add_description(dir)
+            if dir.key?(:$ref)
+              { allOf: [dir] }
+            else
+              dir
+            end.merge(description: description)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/output/object.rb

@@ -0,0 +1,54 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # Serialize out a JSON object.
+      class Object < Base
+        autoload(:Property, 'sober_swag/reporting/output/object/property')
+
+        ##
+        # @param properties [Hash<Symbol,Property>] the properties to serialize
+        def initialize(properties)
+          @properties = properties
+        end
+
+        ##
+        # @param properties [Hash<Symbol,Property>]
+        attr_reader :properties
+
+        def call(item)
+          properties.each.with_object({}) do |(k, v), hash|
+            hash[k] = v.output.call(item)
+          end
+        end
+
+        def serialize_report(item)
+          bad, good = properties.map { |k, prop|
+            [k, prop.output.serialize_report(item)]
+          }.partition { |(_, v)| v.is_a?(Report::Base) }
+
+          return Report::Object.new(bad.to_h) if bad.any?
+
+          good.to_h
+        end
+
+        def swagger_schema # rubocop:disable Metrics/MethodLength
+          props, found = properties.each.with_object([{}, {}]) do |(k, v), (field, f)|
+            prop_type, prop_found = v.property_schema
+            field[k] = prop_type
+            f.merge!(prop_found)
+          end
+
+          [
+            {
+              type: 'object',
+              properties: props,
+              required: properties.keys
+            },
+            found
+          ]
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/output/partitioned.rb

@@ -0,0 +1,77 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # Partition output into one of two possible cases.
+      # We use a block to decide if we should use the first or the second.
+      # If the block returns a truthy value, we use the first output.
+      # If it returns a falsy value, we use the second.
+      #
+      # This is useful to serialize sum types, or types where it can be EITHER one thing OR another.
+      # IE, if I can resolve a dispute by EITHER transfering money OR refunding a customer, I can do this:
+      #
+      # ```ruby
+      # ResolutionOutput = SoberSwag::Reporting::Output.new(
+      #   proc { |x| x.is_a?(Transfer) },
+      #   TransferOutput,
+      #   RefundOutput
+      # )
+      # ```
+      class Partitioned < Base
+        ##
+        # @param partition [#call] block that returns true or false for the input type
+        # @param true_output [Interface] serializer to use if block is true
+        # @param false_output [Interface] serializer to use if block is false
+        def initialize(partition, true_output, false_output)
+          @partition = partition
+          @true_output = true_output
+          @false_output = false_output
+        end
+
+        ##
+        # @return [#call] partitioning block
+        attr_reader :partition
+
+        ##
+        # @return [Interface]
+        attr_reader :true_output
+
+        ##
+        # @return [Interface]
+        attr_reader :false_output
+
+        def call(item)
+          serializer_for(item).call(item)
+        end
+
+        def serialize_report(item)
+          serializer_for(item).serialize_report(item)
+        end
+
+        def swagger_schema
+          true_schema, true_found = true_output.swagger_schema
+          false_schema, false_found = false_output.swagger_schema
+
+          [
+            {
+              oneOf: (true_schema[:oneOf] || [true_schema]) + (false_schema[:oneOf] || [false_schema])
+            },
+            true_found.merge(false_found)
+          ]
+        end
+
+        private
+
+        ##
+        # @return [Interface]
+        def serializer_for(item)
+          if partition.call(item)
+            true_output
+          else
+            false_output
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/output/pattern.rb

@@ -0,0 +1,50 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # Output with a particular pattern.
+      class Pattern < Base
+        def initialize(output, pattern)
+          @output = output
+          @pattern = pattern
+        end
+
+        ##
+        # @return [Interface]
+        attr_reader :output
+
+        ##
+        # @return [Regexp]
+        attr_reader :pattern
+
+        def call(input)
+          output.call(input)
+        end
+
+        def serialize_report(value)
+          base = output.serialize_report(value)
+
+          return base if base.is_a?(Report::Error)
+
+          if pattern.match?(base)
+            base
+          else
+            Report::Value.new(['did not match pattern'])
+          end
+        end
+
+        def swagger_schema
+          schema, defs = output.swagger_schema
+
+          merged =
+            if schema.key?(:$ref)
+              { oneOf: [schema] }
+            else
+              schema
+            end.merge(pattern: pattern.to_s.gsub('?-mix:', ''))
+          [merged, defs]
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/output/referenced.rb

@@ -0,0 +1,42 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # Referenced: An input that will be referred to via reference in the
+      # final schema.
+      class Referenced < Base
+        def initialize(output, reference)
+          @output = output
+          @reference = reference
+        end
+
+        ##
+        # @return [Interface] the actual output type to use
+        attr_reader :output
+
+        ##
+        # @return [String] key in the components hash
+        attr_reader :reference
+
+        def call(input)
+          output.call(input)
+        end
+
+        def serialize_report(input)
+          output.serialize_report(input)
+        end
+
+        def ref_path
+          "#/components/schemas/#{reference}"
+        end
+
+        def swagger_schema
+          [
+            { "$ref": ref_path },
+            { reference => proc { output.swagger_schema } }
+          ]
+        end
+      end
+    end
+  end
+end