sober_swag 0.21.0 → 0.22.0

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

@@ -0,0 +1,69 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # Defer loading of an output for mutual recursion and/or loading time speed.
+      # Probably just do this for mutual recursion though.
+      #
+      # Note: this *does not* save you from infinite schema generation.
+      # This type *must* return some sort of {Referenced} type in order to do that!
+      #
+      # The common use case for this is mutual recursion.
+      # Something like...
+      #
+      # ```ruby
+      # class PersonOutput < SoberSwag::Reporting::Output::Struct
+      #   field :first_name, SoberSwag::Reporting::Output.text
+      #   view :detail do
+      #     field :classes, SoberSwag::Reporting::Output::Defer.new { ClassroomOutput.view(:base).array }
+      #   end
+      # end
+      #
+      # class ClassroomOutut < SoberSwag::Reporting::Output::Struct
+      #   field :class_name, SoberSwag::Reporting::Output.text
+      #
+      #   view :detail do
+      #     field :students, SoberSwag::Reporting::Output::Defer.new { PersonOutput.view(:base).array }
+      #   end
+      # end
+      # ```
+      class Defer < Base
+        ##
+        # Nicer initialization: uses a block.
+        #
+        # @yieldreturn [Interface] serializer to use.
+        def self.defer(&block)
+          new(block)
+        end
+
+        def initialize(other_lazy)
+          @other_lazy = other_lazy
+        end
+
+        attr_reader :other_lazy
+
+        ##
+        # @return [Interface]
+        def other
+          @other ||= other_lazy.call
+        end
+
+        def call(input)
+          other.call(input)
+        end
+
+        def serialize_report(input)
+          other.serialize_report(input)
+        end
+
+        def view(view)
+          other.view(view)
+        end
+
+        def swagger_schema
+          other.swagger_schema
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # Add a description onto an object.
+      class Described < Base
+        def initialize(output, description)
+          @output = output
+          @description = description
+        end
+
+        ##
+        # @return [Interface] output to describe
+        attr_reader :output
+
+        ##
+        # @return [String] description of output
+        attr_reader :description
+
+        def call(value)
+          output.call(value)
+        end
+
+        def serialize_report(value)
+          output.serialize_report(value)
+        end
+
+        def swagger_schema
+          schema, found = output.swagger_schema
+
+          merged =
+            if schema.key?(:$ref)
+              { allOf: [schema] }
+            else
+              schema
+            end.merge(description: description)
+          [merged, found]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # Output a dictionary of key-value pairs.
+      class Dictionary < Base
+        def self.of(valout)
+          new(valout)
+        end
+
+        def initialize(value_output)
+          @value_output = value_output
+        end
+
+        attr_reader :value_output
+
+        def call(item)
+          item.transform_values { |v| value_output.call(v) }
+        end
+
+        def serialize_report(item)
+          return Report::Base.new(['was not a dict']) unless item.is_a?(Hash)
+
+          bad, good = item.map { |k, v|
+            [k, value_output.serialize_report(v)]
+          }.compact.partition { |(_, v)| v.is_a?(Report::Base) }
+
+          return Report::Object.new(bad.to_h) if bad.any?
+
+          good.to_h
+        end
+
+        def swagger_schema
+          schema, found = value_output.swagger_schema
+          [
+            {
+              type: :object,
+              additionalProperties: schema
+            },
+            found
+          ]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,83 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # Interface methods for all outputs.
+      module Interface
+        def call!(item)
+          res = serialize_report(item)
+
+          raise Report::Error.new(res) if res.is_a?(Report::Base) # rubocop:disable Style/RaiseArgs
+
+          res
+        end
+
+        ##
+        # Show off that this is a reporting output.
+        def reporting?
+          true
+        end
+
+        ##
+        # Delegates to {#call}
+        def serialize(item)
+          call(item)
+        end
+
+        def via_map(&block)
+          raise ArgumentError, 'block argument required' unless block
+
+          ViaMap.new(self, block)
+        end
+
+        def referenced(name)
+          Referenced.new(self, name)
+        end
+
+        def list
+          List.new(self)
+        end
+
+        ##
+        # Partition this serializer into two potentials.
+        # If the block given returns *false*, we will use `other` as the serializer.
+        # Otherwise, we will use `self`.
+        #
+        # This might be useful to serialize a sum type:
+        #
+        # ```ruby
+        # ResolutionOutput = TransferOutput.partitioned(RefundOutput) { |to_serialize| to_serialize.is_a?(Transfer)
+        # ```
+        #
+        # @param other [Interface] serializer to use if the block returns false
+        # @yieldreturn [true,false] false if we should use the other serializer
+        # @return [Interface]
+        def partitioned(other, &block)
+          raise ArgumentError, 'need a block' if block.nil?
+
+          Partitioned.new(
+            block,
+            self,
+            other
+          )
+        end
+
+        def nilable
+          Partitioned.new(
+            :nil?.to_proc,
+            Null.new,
+            self
+          )
+        end
+
+        def array
+          List.new(self)
+        end
+
+        def described(description)
+          Described.new(self, description)
+        end
+      end
+    end
+  end
+end

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