simple_jsonapi 1.0.0

data/lib/simple_jsonapi/definition/relationship.rb

@@ -0,0 +1,60 @@
+# Represents a single relationship on a resource
+#
+# @!attribute [r] name
+#   @return [Symbol]
+# @!attribute [r] cardinality
+#   @return [:singular,:collection]
+# @!attribute [r] serializer_inferrer
+#   @return [SerializerInferrer]
+# @!attribute [r] description
+#   @return [String]
+# @!attribute [r] data_definition
+#   @return [Proc]
+class SimpleJsonapi::Definition::Relationship < SimpleJsonapi::Definition::Base
+  include SimpleJsonapi::Definition::Concerns::HasLinksObject
+  include SimpleJsonapi::Definition::Concerns::HasMetaObject
+
+  attr_reader :name, :cardinality, :serializer_inferrer, :description, :data_definition
+
+  # @param name [Symbol]
+  # @param cardinality [Symbol] +:singular+, +:collection+
+  # @param description [String]
+  # @yieldparam resource [Object]
+  # @yieldreturn [Object,Array<Object>] The related resource or resources
+  # @option (see Definition::Base#initialize)
+  def initialize(name, cardinality:, description: nil, **options, &block)
+    super
+
+    unless %i[singular collection].include?(cardinality)
+      raise ArgumentError, "Cardinality must be :singular or :collection"
+    end
+
+    @name = name.to_sym
+    @cardinality = cardinality.to_sym
+    @description = description.to_s.presence
+    @serializer_inferrer = SimpleJsonapi::SerializerInferrer.wrap(options[:serializer])
+
+    instance_eval(&block) if block_given?
+
+    data { |resource| resource.public_send(name) } unless data_definition
+  end
+
+  private def initialize_dup(new_def)
+    super
+    # name and cardinality are symbols, can't be duped
+    # serializer_inferrer doesn't need to be duped?
+  end
+
+  # @return [void]
+  def data(&block)
+    @data_definition = block
+  end
+
+  def singular?
+    cardinality == :singular
+  end
+
+  def collection?
+    cardinality == :collection
+  end
+end

data/lib/simple_jsonapi/definition/resource.rb

@@ -0,0 +1,104 @@
+# Represents a single resource object.
+#
+# @!attribute [r] id_definition
+#   @return [Proc]
+# @!attribute [r] type_definition
+#   @return [Proc]
+# @!attribute [r] attribute_definitions
+#   @return [Hash{Symbol => Attribute}]
+# @!attribute [r] relationship_definitions
+#   @return [Hash{Symbol => Relationship}]
+class SimpleJsonapi::Definition::Resource < SimpleJsonapi::Definition::Base
+  include SimpleJsonapi::Definition::Concerns::HasLinksObject
+  include SimpleJsonapi::Definition::Concerns::HasMetaObject
+
+  attr_reader :id_definition, :type_definition, :attribute_definitions, :relationship_definitions
+
+  def initialize
+    super
+    @id_definition = wrap_in_proc(&:id)
+    @type_definition = wrap_in_proc do |resource|
+      resource.class.name.demodulize.underscore.pluralize
+    end
+
+    @attribute_definitions = {}
+    @relationship_definitions = {}
+  end
+
+  private def initialize_dup(new_def)
+    super
+    new_def.instance_variable_set(:@id_definition, @id_definition.dup) unless @id_definition.nil?
+    new_def.instance_variable_set(:@type_definition, @type_definition.dup) unless @type_definition.nil?
+
+    unless @attribute_definitions.nil?
+      new_def.instance_variable_set(:@attribute_definitions, @attribute_definitions.dup)
+    end
+
+    unless @relationship_definitions.nil?
+      new_def.instance_variable_set(:@relationship_definitions, @relationship_definitions.dup)
+    end
+  end
+
+  # @overload id(&block)
+  # @overload id(value)
+  # @yieldparam resource [Object]
+  # @yieldreturn [String]
+  # @return [void]
+  def id(*args, &block)
+    @id_definition = wrap_in_proc(*args, &block)
+  end
+
+  # @overload type(&block)
+  # @overload type(value)
+  # @yieldparam resource [Object]
+  # @yieldreturn [String]
+  # @return [void]
+  def type(*args, &block)
+    @type_definition = wrap_in_proc(*args, &block)
+  end
+
+  # @overload attribute(name, type: nil, description: nil, **options)
+  # @overload attribute(name, type: nil, description: nil, **options, &block)
+  # @option (see Definition::Base#initialize)
+  # @option options [Symbol] type data type
+  # @option options [String] description
+  # @yieldparam resource [Object]
+  # @yieldreturn [#to_json] the value
+  # @return [void]
+  def attribute(name, **options, &block)
+    # Allow type attribute to be defined before throwing error to support non-compliant data_comleteness/v1
+    attribute_definitions[name.to_sym] = SimpleJsonapi::Definition::Attribute.new(name, **options, &block)
+
+    if %w[id type].include?(name.to_s)
+      raise ArgumentError, "`#{name}` is not allowed as an attribute name"
+    end
+  end
+
+  # @overload has_one(name, description: nil, **options, &block)
+  # @param name [Symbol]
+  # @option (see Definition::Relationship#initialize)
+  # @option options [String] description
+  # @yieldparam (see Definition::Relationship#initialize)
+  # @yieldreturn (see Definition::Relationship#initialize)
+  # @return [void]
+  def has_one(name, **options, &block)
+    relationship(name, cardinality: :singular, **options, &block)
+  end
+
+  # @overload has_many(name, description: nil, **options, &block)
+  # @param name [Symbol]
+  # @option (see Definition::Relationship#initialize)
+  # @option options [String] description
+  # @yieldparam (see Definition::Relationship#initialize)
+  # @yieldreturn (see Definition::Relationship#initialize)
+  # @return [void]
+  def has_many(name, **options, &block)
+    relationship(name, cardinality: :collection, **options, &block)
+  end
+
+  private
+
+  def relationship(name, **options, &block)
+    relationship_definitions[name.to_sym] = SimpleJsonapi::Definition::Relationship.new(name, options, &block)
+  end
+end

data/lib/simple_jsonapi/error_serializer.rb

@@ -0,0 +1,76 @@
+# Subclass {ErrorSerializer} to create serializers for specific types of errors.
+class SimpleJsonapi::ErrorSerializer
+  include SimpleJsonapi::SerializerMethods
+
+  class << self
+    # @overload (see Definition::Error#id)
+    # @return (see Definition::Error#id)
+    def id(*args, **options, &block)
+      definition.id(*args, **options, &block)
+    end
+
+    # @overload (see Definition::Error#status)
+    # @return (see Definition::Error#status)
+    def status(*args, **options, &block)
+      definition.status(*args, **options, &block)
+    end
+
+    # @overload (see Definition::Error#code)
+    # @return (see Definition::Error#code)
+    def code(*args, **options, &block)
+      definition.code(*args, **options, &block)
+    end
+
+    # @overload (see Definition::Error#title)
+    # @return (see Definition::Error#title)
+    def title(*args, **options, &block)
+      definition.title(*args, **options, &block)
+    end
+
+    # @overload (see Definition::Error#detail)
+    # @return (see Definition::Error#detail)
+    def detail(*args, **options, &block)
+      definition.detail(*args, **options, &block)
+    end
+
+    # @overload (see Definition::Error#source)
+    # @return (see Definition::Error#source)
+    def source(*args, &block)
+      definition.source(*args, &block)
+    end
+
+    # @overload (see Definition::Error#about_link)
+    # @return (see Definition::Error#about_link)
+    def about_link(*args, **options, &block)
+      definition.about_link(*args, **options, &block)
+    end
+
+    # @overload (see Definition::Concerns::HasMetaObject#meta)
+    # @return (see Definition::Concerns::HasMetaObject#meta)
+    def meta(name, *args, **options, &block)
+      definition.meta(name, *args, **options, &block)
+    end
+  end
+
+  self.definition = SimpleJsonapi::Definition::Error.new
+
+  # @return (see Definition::Error#member_definitions)
+  def member_definitions
+    definition.member_definitions
+  end
+
+  # @return (see Definition::Error#source_definitions)
+  def source_definition
+    definition.source_definition
+  end
+
+  # @return (see Definition::Concerns::HasLinksObject#link_definitions)
+  def link_definitions
+    definition.link_definitions
+  end
+
+  # @return (see Definition::Concerns::HasMetaObject#meta_definitions)
+  def meta_definitions
+    definition.meta_definitions
+  end
+end

data/lib/simple_jsonapi/errors/bad_request.rb

@@ -0,0 +1,11 @@
+require_relative 'wrapped_error'
+
+class SimpleJsonapi::Errors::BadRequest < SimpleJsonapi::Errors::WrappedError
+  def initialize(_cause = nil, **attributes)
+    super attributes.merge(
+      status: "400",
+      code: "bad_request",
+      title: "Bad request",
+    )
+  end
+end

data/lib/simple_jsonapi/errors/exception_serializer.rb

@@ -0,0 +1,6 @@
+# A generic serializer for Ruby +Exception+ objects.
+class SimpleJsonapi::Errors::ExceptionSerializer < SimpleJsonapi::ErrorSerializer
+  code { |err| err.class.name.underscore.tr('/', '_') }
+  title { |err| err.class.name }
+  detail(&:message)
+end

data/lib/simple_jsonapi/errors/wrapped_error.rb

@@ -0,0 +1,35 @@
+module SimpleJsonapi::Errors
+  # A generic serializable error class.
+  class WrappedError
+    # @!attribute [rw] cause
+    #   The original error.
+    #   @return [Object]
+    # @!attribute [rw] id
+    #   @return [String]
+    # @!attribute [rw] status
+    #   @return [String]
+    # @!attribute [rw] code
+    #   @return [String]
+    # @!attribute [rw] title
+    #   @return [String]
+    # @!attribute [rw] detail
+    #   @return [String]
+    # @!attribute [rw] source_pointer
+    #   @return [String]
+    # @!attribute [rw] source_parameter
+    #   @return [String]
+    # @!attribute [rw] about_link
+    #   @return [String]
+    attr_accessor :cause, :id, :status, :code, :title, :detail, :source_pointer, :source_parameter, :about_link
+
+    # @param cause [Object] The underlying error
+    # @param attributes [Hash{Symbol => String}]
+    def initialize(cause = nil, **attributes)
+      self.cause = cause
+
+      attributes.each do |name, value|
+        send("#{name}=", value) if respond_to?("#{name}=")
+      end
+    end
+  end
+end

data/lib/simple_jsonapi/errors/wrapped_error_serializer.rb

@@ -0,0 +1,35 @@
+# A serializer for {WrappedError} objects.
+class SimpleJsonapi::Errors::WrappedErrorSerializer < SimpleJsonapi::ErrorSerializer
+  id(if: ->(err) { err.id.to_s.present? }) do |err|
+    err.id.to_s.presence
+  end
+
+  status(if: ->(err) { err.status.to_s.present? }) do |err|
+    err.status.to_s.presence
+  end
+
+  code(if: ->(err) { err.code.to_s.present? }) do |err|
+    err.code.to_s.presence
+  end
+
+  title(if: ->(err) { err.title.to_s.present? }) do |err|
+    err.title.to_s.presence
+  end
+
+  detail(if: ->(err) { err.detail.to_s.present? }) do |err|
+    err.detail.to_s.presence
+  end
+
+  source do
+    pointer(if: ->(err) { err.source_pointer.to_s.present? }) do |err|
+      err.source_pointer.to_s.presence
+    end
+    parameter(if: ->(err) { err.source_parameter.to_s.present? }) do |err|
+      err.source_parameter.to_s.presence
+    end
+  end
+
+  about_link(if: ->(err) { err.about_link.to_s.present? }) do |err|
+    err.about_link.to_s.presence
+  end
+end

data/lib/simple_jsonapi/helpers/exceptions.rb

@@ -0,0 +1,39 @@
+module SimpleJsonapi
+  # The error raised when a document does not have a valid JSONAPI structure.
+  class InvalidJsonStructureError < StandardError
+  end
+
+  # The error raised when the same resource is added to the +included+ member twice.
+  class DuplicateResourceError < StandardError
+    attr_reader :type, :id
+
+    # @param type [String]
+    # @param id [String]
+    # @param msg [String]
+    def initialize(type, id, msg = nil)
+      @type = type
+      @id = id
+      @msg = msg
+    end
+
+    def to_s
+      @msg.present? ? @msg : "Resource with type #{type} and id #{id} is already included"
+    end
+  end
+
+  # The error raised when a {SerializerInferrer} cannot find the serializer for a resource or error.
+  class SerializerInferenceError < StandardError
+    attr_reader :object
+
+    # @param object [Object] the resource or error
+    # @param msg [String]
+    def initialize(object, msg = nil)
+      @object = object
+      @msg = msg
+    end
+
+    def to_s
+      @msg.present? ? @msg : "Unable to infer serializer for #{object.class}"
+    end
+  end
+end

data/lib/simple_jsonapi/helpers/serializer_inferrer.rb

@@ -0,0 +1,136 @@
+module SimpleJsonapi
+  # Identifies the serializer class that should be used for a resource or error object.
+  class SerializerInferrer
+    # @!attribute [r] namespace
+    #   @return [String]
+    attr_reader :namespace
+
+    # # A {SerializerInferrer} that always returns the serializer class provided in the constructor.
+    # class Constant
+    #   # @param serializer_class [Serializer,ErrorSerializer]
+    #   def initialize(serializer_class)
+    #     @serializer_class = case serializer_class
+    #     when Class then serializer_class
+    #     else serializer_class.to_s.constantize
+    #     end
+
+    #     super { |resource| @serializer_class }
+    #   end
+    # end
+
+    # @param serializer [SerializerInferrer,Serializer,ErrorSerializer,nil]
+    # @return [SerializerInferrer]
+    def self.wrap(serializer)
+      if serializer.is_a?(SerializerInferrer)
+        serializer
+      elsif serializer.present?
+        klass = serializer_class(serializer)
+        SerializerInferrer.new { |_resource| klass }
+      else
+        SimpleJsonapi.serializer_inferrer
+      end
+    end
+
+    # @param explicit_mappings [Hash{Class => Class}] A mapping of resource classes to serializer classes
+    # @param namespace [String] A namespace in which to search for serializer classes
+    # @yieldparam object [Object] The resource or error
+    # @yieldreturn [Class] A serializer class
+    def initialize(explicit_mappings: nil, namespace: nil, &block)
+      @explicit_mappings = {}
+      @explicit_mappings.merge!(explicit_mappings) if explicit_mappings
+
+      @namespace = namespace
+      @infer_proc = block
+    end
+
+    delegate :each, to: :@explicit_mappings
+
+    # @param explicit_mappings [Hash{Class => Class}]
+    # @return [self]
+    def merge(explicit_mappings)
+      explicit_mappings.each do |resource_class, serializer_class|
+        add(resource_class, serializer_class)
+      end
+      self
+    end
+
+    # @param resource_class [Class]
+    # @param serializer_class [Class]
+    # @return [void]
+    def add(resource_class, serializer_class)
+      @explicit_mappings[resource_class.name] = serializer_class
+    end
+
+    # @param resource [Object]
+    # @return [Class] A serializer class
+    # @raise [SerializerInferenceError] if a serializer isn't found
+    def infer(resource)
+      serializer = (@infer_proc || default_infer_proc).call(resource)
+      raise SerializerInferenceError.new(resource) unless serializer
+      serializer
+    end
+
+    # @return [Class,nil]
+    def default_serializer
+      unless defined?(@default_serializer)
+        begin
+          @default_serializer = infer(nil)
+        rescue SerializerInferenceError
+          @default_serializer = nil
+        end
+      end
+      @default_serializer
+    end
+
+    def default_serializer?
+      default_serializer != nil
+    end
+
+    private
+
+    def default_infer_proc
+      @default_infer_proc ||= proc do |resource|
+        serializer = nil
+
+        resource.class.ancestors.find do |ancestor|
+          serializer = find_serializer_by_name(ancestor.name)
+        end
+
+        serializer
+      end
+    end
+
+    def find_serializer_by_name(name)
+      if @explicit_mappings.key?(name)
+        @explicit_mappings[name]
+      else
+        serializer_name_for_class_name(name).safe_constantize
+      end
+    end
+
+    def serializer_name_for_class_name(resource_class_name)
+      "#{prefix(resource_class_name)}#{resource_class_name}Serializer"
+    end
+
+    def prefix(resource_class_name)
+      if namespace.blank?
+        ""
+      elsif resource_class_name.starts_with?("#{namespace}::")
+        ""
+      else
+        "#{namespace}::"
+      end
+    end
+
+    def self.serializer_class(serializer)
+      case serializer
+      when Class
+        serializer
+      else
+        serializer.to_s.constantize
+      end
+    end
+
+    private_class_method :serializer_class
+  end
+end