sober_swag 0.21.0 → 0.24.0

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

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

@@ -0,0 +1,287 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # A DSL for building "output object structs."
+      class Struct # rubocop:disable Metrics/ClassLength
+        class << self
+          include Interface
+
+          ##
+          # Define a new field to be serialized.
+          #
+          # @param name [Symbol] name of this field.
+          # @param output [Interface] reporting output to use to serialize.
+          # @param description [String,nil] description for this field.
+          # @param block [Proc, nil]
+          #   If a block is given, it will be defined as a method on the output object struct.
+          #   If the block takes an argument, the object being serialized will be passed to it.
+          #   Otherwise, it will be accessible as `#object_to_serialize` from within the body.
+          #
+          #   You can access other methods from this method.
+          def field(name, output, description: nil, &extract)
+            raise ArgumentError, "output of field #{name} is not a SoberSwag::Reporting::Output::Interface" unless output.is_a?(Interface)
+
+            define_field(name, extract)
+
+            object_fields[name] = Object::Property.new(
+              output.view(:base).via_map(&name.to_proc),
+              description: description
+            )
+          end
+
+          def object_output
+            base = Object.new(object_fields).via_map { |o| new(o) }
+            if description
+              base.described(description)
+            else
+              base
+            end
+          end
+
+          ##
+          # Set a description for the *type* of this output.
+          # It will show up as a description in the component key for this output.
+          # Right now that unfortunately will not render with ReDoc, but it should eventually.
+          #
+          # @param val [String, nil] pass if you want to set, otherwise you will get the current value
+          # @return [String] the description assigned to this object, if any.
+          def description(val = nil)
+            return @description unless val
+
+            @description = val
+          end
+
+          ##
+          # An output for this specific schema type.
+          # If this schema has any views, it will be defined as a map of possible views to the actual views used.
+          # Otherwise, it will directly be the base definition.
+          def single_output
+            single =
+              if view_map.any?
+                Viewed.new(identified_view_map)
+              else
+                inherited_output
+              end
+            identifier ? single.referenced(identifier) : single
+          end
+
+          ##
+          # Used to generate 'allOf' subtyping relationships.
+          # Probably do not call this yourself.
+          #
+          # @return [Interface]
+          def identified_with_base
+            object_output.referenced([identifier, 'Base'].join('.'))
+          end
+
+          ##
+          # Used to generate 'allOf' subtyping relationships.
+          # Probably do not call this yourself.
+          def identified_without_base
+            if parent_struct
+              MergeObjects
+                .new(parent_struct.inherited_output, object_output)
+            else
+              object_output
+            end.referenced(identifier)
+          end
+
+          ##
+          # Used to generate 'allOf' subtyping relationships.
+          # Probably do not call this yourself!
+          # Use {#single_output} instead.
+          #
+          # This allows us to implement *inheritance*.
+          # So, if you inherit from another output object struct, you get its methods and attributes.
+          # Views behave as if they have inherited the base object.
+          #
+          # This means that any views added to any parent output objects *will* be visible in children.
+          # @return [Interface]
+          def inherited_output
+            inherited =
+              if parent_struct
+                MergeObjects
+                  .new(parent_struct.inherited_output, object_output)
+              else
+                object_output
+              end
+
+            identifier ? inherited.referenced([identifier, 'Base'].join('.')) : inherited
+          end
+
+          ##
+          # Schema for this output.
+          # Will include views, if applicable.
+          def swagger_schema
+            single_output.swagger_schema
+          end
+
+          ##
+          # Serialize an object to a hash.
+          #
+          # @param value [Object] value to serialize
+          # @param view [Symbol] which view to use to serialize this output.
+          # @return [Hash] the serialized ruby hash, suitable for passing to JSON.generate
+          def call(value, view: :base)
+            view(view).output.call(value)
+          end
+
+          ##
+          # Serialize an object to a hash, with type-checking.
+          #
+          # @param value [Object] value to serialize
+          # @param view [Symbol] which view to use
+          # @return [Hash] the serialized ruby hash, suitable for passsing to JSON.generate
+          def serialize_report(value, view: :base)
+            view(view).output.serialize_report(value)
+          end
+
+          ##
+          # @return [Hash<Symbol, Object::Property>] the properties defined *directly* on this object.
+          #   Does not include inherited fields!
+          def object_fields
+            @object_fields ||= {}
+          end
+
+          ##
+          # Define a view for this object.
+          #
+          # Views behave like their own output structs, which inherit the parent (or 'base' view).
+          # This means that fields *after* the definition of a view *will be present in the view*.
+          # This enables views to maintain a subtyping relationship.
+          #
+          # Your base view should thus serialize *as little as possible*.
+          #
+          # View classes get defined as child constants.
+          # So, if I write `define_view(:foo)` on a struct called `Person`,
+          # I will get `Person::Foo` as a class I can use if I want!
+          #
+          # @param name [Symbol] name of this view.
+          # @yieldself [self] a block in which you can add more fields to the view.
+          # @return [Class]
+          def define_view(name, &block)
+            define_view_with_parent(name, self, block)
+          end
+
+          ##
+          # Defines a view for this object, which "inherits" another view.
+          # @see #define_view for how views behave.
+          #
+          # @param name [Symbol] name of this view
+          # @param inherits [Symbol] name of the view this view inherits
+          # @yieldself [self] a block in which you can add more fields to this view
+          # @return [Class]
+          def define_inherited_view(name, inherits:, &block)
+            define_view_with_parent(name, view_class(inherits), block)
+          end
+
+          ##
+          # @return Hash<Symbol,Class> map of potential views.
+          #   Does not include the 'base' view.
+          def view_map
+            @view_map ||= {}
+          end
+
+          ##
+          # @return [Set<Symbol>] all applicable views.
+          #   Will always include `:base`.
+          def views
+            [:base, *view_map.keys].to_set
+          end
+
+          ##
+          # @param name [Symbol] which view to use.
+          # @return [Interface] a serializer suitable for this interface.
+          def view(name)
+            return inherited_output if name == :base
+
+            view_map.fetch(name).view(:base)
+          end
+
+          ##
+          # Equivalent to .view, but returns the raw view class.
+          #
+          # @return [Class]
+          def view_class(name)
+            return self if name == :base
+
+            view_map.fetch(name)
+          end
+
+          attr_accessor :parent_struct
+
+          ##
+          # When this class is inherited, it sets up a future subtyping relationship.
+          # This gets expressed with 'allOf' in the generated swagger.
+          def inherited(other)
+            other.parent_struct = self unless self == ::SoberSwag::Reporting::Output::Struct
+          end
+
+          ##
+          # Set a new identifier for this output object.
+          #
+          # @param value [String, nil] provide a new identifier to use.
+          #   Stateful operation.
+          # @return [String] identifier key to use in the components hash.
+          #   In rare cases (a class with no name and no set identifier) it can return nil.
+          #   We consider this case "unsupported", IE, please do not do that.
+          def identifier(value = nil)
+            if value
+              @identifier = value
+            else
+              @identifier || name&.gsub('::', '.')
+            end
+          end
+
+          private
+
+          def define_view_with_parent(name, parent, block)
+            raise ArgumentError, "duplicate view #{name}" if name == :base || views.include?(name)
+
+            classy_name = name.to_s.classify
+            us = self # grab this so its identifier doesn't get nested under whatever parent it inherits from, since its our view
+
+            Class.new(parent).tap do |c|
+              c.instance_eval(&block)
+              c.define_singleton_method(:define_view) { |*| raise ArgumentError, 'no nesting views' }
+              c.define_singleton_method(:identifier) { [us.identifier, classy_name.gsub('::', '.')].join('.') }
+              const_set(classy_name, c)
+              view_map[name] = c
+            end
+          end
+
+          def identified_view_map
+            view_map.transform_values(&:identified_without_base).merge(base: inherited_output)
+          end
+
+          def define_field(method, extractor)
+            e =
+              if extractor.nil?
+                proc { _struct_serialized.public_send(method) }
+              elsif extractor.arity == 1
+                proc { extractor.call(_struct_serialized) }
+              else
+                extractor
+              end
+
+            define_method(method, &e)
+          end
+        end
+
+        def initialize(struct_serialized)
+          @_struct_serialized = struct_serialized
+        end
+
+        attr_reader :_struct_serialized
+
+        ##
+        # The object to serialize.
+        # Use this if you're defining your own methods.
+        def object_to_serialize
+          @_struct_serialized
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # Output raw text.
+      class Text < Base
+        def call(input)
+          input
+        end
+
+        def serialize_report(input)
+          result = call(input)
+
+          return Report::Value.new(['was not a string']) unless result.is_a?(String)
+
+          result
+        end
+
+        def swagger_schema
+          [{ type: 'string' }, {}]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # Apply a mapping function before calling
+      # a base output.
+      #
+      # Note that this is applied *before* the base output.
+      # This is different than {SoberSwag::Reporting::Input::Mapped}, which does the reverse.
+      # IE, this class does `call block -> pass result to base output`,
+      # while the other does `call serializer -> pass result to block`.
+      #
+      # If you want to get *really* nerdy, this is *contravariant* to `Mapped`.
+      #
+      # This lets you do things like making an output that serializes to strings via `to_s`:
+      #
+      # ```ruby
+      # ToSTextOutput = SoberSwag::Reporting::Output::ViaMap.new(
+      #   SoberSwag::Reporting::Output.text,
+      #   proc { |arg| arg.to_s }
+      # )
+      #
+      # class Person
+      #   def to_s
+      #     'Person'
+      #   end
+      # end
+      #
+      # ToSTextOutput.call(Person.new) # => 'Person'
+      # ```
+      class ViaMap < Base
+        def initialize(output, mapper)
+          @output = output
+          @mapper = mapper
+        end
+
+        ##
+        # @return [Interface] base output
+        attr_reader :output
+
+        ##
+        # @return [#call] mapping function
+        attr_reader :mapper
+
+        def call(input)
+          output.call(mapper.call(input))
+        end
+
+        def serialize_report(input)
+          output.serialize_report(mapper.call(input))
+        end
+
+        def view(view)
+          ViaMap.new(output.view(view), mapper)
+        end
+
+        def views
+          output.views
+        end
+
+        def swagger_schema
+          output.swagger_schema
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # Augment outputs with the ability to select views.
+      # This models a 'oneOf' relationship, where the choice picked is controlled by the 'view' parameter.
+      #
+      # This is "optional choice," in the sense that you *must* provide a default `:base` key.
+      # This key will be used in almost all cases.
+      class Viewed < Base
+        ##
+        # @param views [Hash<Symbol,Interface>] a map of view key to view.
+        #   Note: this map *must* include the base view.
+        def initialize(views)
+          @view_map = views
+
+          raise ArgumentError, 'views must have a base key' unless views.key?(:base)
+        end
+
+        attr_reader :view_map
+
+        ##
+        # Serialize out an object.
+        # If the view key is not provided, use the base view.
+        #
+        # @param input [Object] object to serialize
+        # @param view [Symbol] which view to use.
+        #   If view is not valid, an exception will be thrown
+        # @raise [KeyError] if view is not valid
+        # @return [Object,String,Array,Numeric] JSON-serializable object.
+        #   Suitable for use with #to_json.
+        def call(input, view: :base)
+          view(view).call(input)
+        end
+
+        def serialize_report(input)
+          view(:base).call(input)
+        end
+
+        ##
+        # Get a view with a particular key.
+        def view(view)
+          view_map.fetch(view)
+        end
+
+        ##
+        # @return [Set<Symbol>] all of the views applicable.
+        def views
+          view_map.keys.to_set
+        end
+
+        ##
+        # Add (or override) the possible views.
+        #
+        # @return [Viewed] a new view map, with one more view.
+        def with_view(name, val)
+          Viewed.new(views.merge(name => val))
+        end
+
+        def swagger_schema
+          found = {}
+          possibles = view_map.values.flat_map do |v|
+            view_item, view_found = v.swagger_schema
+            found.merge!(view_found)
+            view_item[:oneOf] || [view_item]
+          end
+          [{ oneOf: possibles }, found]
+        end
+      end
+    end
+  end
+end