halitosis 0.1.0

data/lib/halitosis/collection.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Halitosis
+  # Behavior for serializers with a primary collection resource.
+  #
+  # The main reason to declare a collection is that the resource with that name
+  # will always be included during rendering.
+  #
+  module Collection
+    def self.included(base)
+      raise InvalidCollection, "#{base.name} has already defined a resource" if base.included_modules.include?(Resource)
+
+      base.extend ClassMethods
+
+      base.send :include, InstanceMethods
+
+      base.send :attr_reader, :collection
+
+      base.class.send :attr_accessor, :collection_name
+    end
+
+    module ClassMethods
+      # @param name [Symbol, String] name of the collection
+      #
+      # @return [Module] self
+      #
+      def define_collection(name, options = {}, &procedure)
+        raise InvalidCollection, "#{self.name} collection is already defined" if fields.key?(Field.name)
+
+        self.collection_name = name.to_s
+
+        alias_method name, :collection
+
+        fields.add Field.new(name, options, procedure)
+      end
+
+      def collection?
+        true
+      end
+
+      def collection_field
+        fields[Field.name].last || raise(InvalidCollection, "#{name} collection is not defined")
+      end
+    end
+
+    module InstanceMethods
+      # Override standard initializer to assign primary collection
+      #
+      # @param collection [Object] the primary collection
+      #
+      def initialize(collection, **)
+        @collection = collection
+
+        super(**)
+      end
+
+      # @return [Hash] the rendered hash with collection, if any
+      #
+      def render
+        field = self.class.collection_field
+        if depth.zero?
+          super.merge(field.name => render_collection_field(field))
+        else
+          render_collection_field(field)
+        end
+      end
+
+      # @return [Hash] collection from fields
+      #
+      def render_collection_field(field)
+        value = instance_eval(&field.procedure)
+        value.map { |child| render_child(child, collection_opts) }
+      end
+
+      def collection?
+        true
+      end
+
+      private
+
+      # @param key [String]
+      #
+      # @return [Hash]
+      #
+      def collection_opts
+        return include_options if depth.positive?
+
+        opts = include_options.fetch(self.class.collection_field.name.to_s, {})
+
+        # Turn { :report => 1 } into { :report => {} } for child
+        opts = {} unless opts.is_a?(Hash)
+
+        opts
+      end
+    end
+  end
+end
+
+require "halitosis/collection/field"

data/lib/halitosis/configuration.rb

@@ -0,0 +1,13 @@
+module Halitosis
+  # Simple configuration class
+  #
+  class Configuration
+    # Array of extension modules to be included in all serializers
+    #
+    # @return [Array<Module>]
+    #
+    def extensions
+      @extensions ||= []
+    end
+  end
+end

data/lib/halitosis/errors.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Halitosis
+  class Error < StandardError; end
+
+  class InvalidCollection < StandardError; end
+
+  class InvalidField < StandardError; end
+
+  class InvalidResource < StandardError; end
+end

data/lib/halitosis/field.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Halitosis
+  # Stores instructions for how to render a value for a given serializer
+  # instance
+  #
+  class Field
+    attr_reader :name, :options
+
+    attr_accessor :procedure
+
+    # Construct a new Field instance
+    #
+    # @param name [Symbol, String] Field name
+    # @param options [Hash] hash of options
+    #
+    # @return [Halitosis::Field] the instance
+    #
+    def initialize(name, options, procedure)
+      @name = name.to_sym
+      @options = Halitosis::HashUtil.symbolize_params(options)
+      @procedure = procedure
+    end
+
+    # @param instance [Object] the serializer instance with which to evaluate
+    #   the stored procedure
+    #
+    def value(instance)
+      options.fetch(:value) do
+        procedure ? instance.instance_eval(&procedure) : instance.send(name)
+      end
+    end
+
+    # @return [true, false] whether this Field should be included based on
+    #   its conditional guard, if any
+    #
+    def enabled?(instance)
+      if options.key?(:if)
+        !!eval_guard(instance, options.fetch(:if))
+      elsif options.key?(:unless)
+        !eval_guard(instance, options.fetch(:unless))
+      else
+        true
+      end
+    end
+
+    # @return [true] if nothing is raised
+    #
+    # @raise [Halitosis::InvalidField] if the Field is invalid
+    #
+    def validate
+      return true unless options.key?(:value) && procedure
+
+      raise InvalidField,
+        "Cannot specify both value and procedure for #{name}"
+    end
+
+    private
+
+    # Evaluate guard procedure or method
+    #
+    def eval_guard(instance, guard)
+      case guard
+      when Proc
+        instance.instance_eval(&guard)
+      when Symbol, String
+        instance.send(guard)
+      else
+        guard
+      end
+    end
+  end
+end

data/lib/halitosis/fields.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Halitosis
+  # Each serializer class has a Fields object that stores the fields that have been defined on it.
+  #
+  class Fields < Hash
+    def add(field)
+      type = field.class.name
+
+      field.validate
+
+      self[type] ||= []
+      self[type] << field
+
+      field
+    end
+  end
+end

data/lib/halitosis/hash_util.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Halitosis
+  module HashUtil
+    module_function
+
+    # Transform hash keys into strings if necessary
+    #
+    # @param hash [Hash, Array, String]
+    #
+    # @return [Hash]
+    #
+    def stringify_params(hash)
+      case hash
+      when String
+        hash.split(",").inject({}) do |output, key|
+          f, value = key.split(".", 2)
+          output.merge(f => value ? stringify_params(value) : true)
+        end
+      when Array
+        hash.map { |item| stringify_params(item) }.inject({}, &:merge)
+      else
+        hash.transform_keys(&:to_s)
+      end
+    end
+
+    # Transform hash keys into symbols if necessary
+    #
+    # @param hash [Hash]
+    #
+    # @return [Hash]
+    #
+    def symbolize_params(hash)
+      if hash.respond_to?(:transform_keys)
+        hash.transform_keys(&:to_sym).transform_values(&method(:symbolize_params))
+      else
+        hash
+      end
+    end
+  end
+end

data/lib/halitosis/links/field.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Halitosis
+  module Links
+    class Field < Halitosis::Field
+      # Links have special keywords that other fields don't, so override
+      # the standard initializer to build options from keywords
+      #
+      def initialize(name, *args, procedure)
+        super(name, self.class.build_options(args), procedure)
+      end
+
+      # @return [true] if nothing is raised
+      #
+      # @raise [Halitosis::InvalidField] if the field is invalid
+      #
+      def validate
+        super
+
+        return true if procedure || options.key?(:value)
+
+        raise InvalidField,
+          "Link #{name} requires either procedure or explicit value"
+      end
+
+      # @return [nil, Hash]
+      #
+      def value(_instance)
+        hrefs = super
+
+        attrs = options.fetch(:attrs, {})
+
+        case hrefs
+        when Array
+          hrefs.map { |href| attrs.merge(href:) }
+        when nil
+          # no-op
+        else
+          attrs.merge(href: hrefs)
+        end
+      end
+
+      class << self
+        # Build hash of options from flexible field arguments
+        #
+        # @param args [Array] the raw field arguments
+        #
+        # @return [Hash] standardized hash of options
+        #
+        def build_options(args)
+          {}.tap do |options|
+            options.merge!(args.pop) if args.last.is_a?(Hash)
+
+            options[:attrs] ||= {}
+            options[:attrs].merge!(build_attrs(args))
+          end
+        end
+
+        # @param keywords [Array] array of special keywords
+        #
+        # @raise [Halitosis::InvalidField] if a keyword is unrecognized
+        #
+        def build_attrs(keywords)
+          keywords.each_with_object({}) do |keyword, attrs|
+            case keyword
+            when :templated, "templated"
+              attrs[:templated] = true
+            else
+              raise InvalidField, "Unrecognized link keyword: #{keyword}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/halitosis/links.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Halitosis
+  module Links
+    def self.included(base)
+      base.extend ClassMethods
+
+      base.send :include, InstanceMethods
+    end
+
+    module ClassMethods
+      # @return [Halitosis::Links::Field]
+      #
+      def link(name, *, &procedure)
+        fields.add(Field.new(name, *, procedure))
+      end
+    end
+
+    module InstanceMethods
+      # @return [Hash] the rendered hash with links, if any
+      #
+      def render
+        if options.fetch(:include_links, true)
+          decorate_render :links, super
+        else
+          super
+        end
+      end
+
+      # @return [Hash] links from fields
+      #
+      def links
+        render_fields(Field.name) do |field, result|
+          value = field.value(self)
+
+          result[field.name] = value if value
+        end
+      end
+    end
+  end
+end
+
+require "halitosis/links/field"

data/lib/halitosis/meta/field.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Halitosis
+  module Meta
+    class Field < Halitosis::Field
+    end
+  end
+end

data/lib/halitosis/meta.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Halitosis
+  module Meta
+    def self.included(base)
+      base.extend ClassMethods
+
+      base.send :include, InstanceMethods
+    end
+
+    module ClassMethods
+      # @return [Halitosis::Meta::Field]
+      #
+      def meta(name, **options, &procedure)
+        fields.add(Field.new(name, options, procedure))
+      end
+    end
+
+    module InstanceMethods
+      # @return [Hash] the rendered hash with meta, if any
+      #
+      def render
+        if options.fetch(:include_meta, true)
+          decorate_render :meta, super
+        else
+          super
+        end
+      end
+
+      # @return [Hash] meta from fields
+      #
+      def meta
+        render_fields(Field.name) do |field, result|
+          value = field.value(self)
+
+          result[field.name] = value if value
+        end
+      end
+    end
+  end
+end
+
+require "halitosis/meta/field"

data/lib/halitosis/permissions/field.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Halitosis
+  module Permissions
+    class Field < Halitosis::Field
+    end
+  end
+end

data/lib/halitosis/permissions.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Halitosis
+  module Permissions
+    def self.included(base)
+      base.extend ClassMethods
+
+      base.send :include, InstanceMethods
+    end
+
+    module ClassMethods
+      # @return [Halitosis::Permissions::Field]
+      #
+      def permission(name, **options, &procedure)
+        fields.add(Field.new(name, options, procedure))
+      end
+    end
+
+    module InstanceMethods
+      # @return [Hash] the rendered hash with permissions, if any
+      #
+      def render
+        if options.fetch(:include_permissions, true)
+          decorate_render :permissions, super
+        else
+          super
+        end
+      end
+
+      # @return [Hash] permissions from fields
+      #
+      def permissions
+        render_fields(Field.name) do |field, result|
+          value = field.value(self)
+
+          result[field.name] = value if value
+        end
+      end
+    end
+  end
+end
+
+require "halitosis/permissions/field"

data/lib/halitosis/properties/field.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Halitosis
+  module Properties
+    class Field < Halitosis::Field
+    end
+  end
+end

data/lib/halitosis/properties.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Halitosis
+  module Properties
+    def self.included(base)
+      base.extend ClassMethods
+
+      base.send :include, InstanceMethods
+    end
+
+    module ClassMethods
+      # @param name [Symbol, String]
+      # @param options [nil, Hash]
+      #
+      # @return [Halitosis::Properties::Field]
+      #
+      def property(name, options = {}, &procedure)
+        fields.add(Field.new(name, options, procedure))
+      end
+    end
+
+    module InstanceMethods
+      # @return [Hash] the rendered hash with properties, if any
+      #
+      def render
+        super.merge(properties)
+      end
+
+      # @return [Hash] properties from fields
+      #
+      def properties
+        render_fields(Field.name) do |field, result|
+          result[field.name] = field.value(self)
+        end
+      end
+    end
+  end
+end
+
+require "halitosis/properties/field"

data/lib/halitosis/railtie.rb

@@ -0,0 +1,23 @@
+module Halitosis
+  # Provide Rails-specific extensions if loaded in a Rails application
+  #
+  class Railtie < ::Rails::Railtie
+    module Renderable
+      def render_in(view_context)
+        view_context.render json: self
+      end
+
+      def format
+        :json
+      end
+    end
+
+    initializer "halitosis.url_helpers" do |_app|
+      Halitosis.config.extensions << ::Rails.application.routes.url_helpers
+    end
+
+    initializer "halitosis.renderable" do |_app|
+      Halitosis.config.extensions << Renderable
+    end
+  end
+end

data/lib/halitosis/relationships/field.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Halitosis
+  module Relationships
+    class Field < Halitosis::Field
+      # @return [true] if nothing is raised
+      #
+      # @raise [Halitosis::InvalidField] if the definition is invalid
+      #
+      def validate
+        super
+
+        return true if procedure
+
+        raise InvalidField, "Relationship #{name} must be defined with a proc"
+      end
+
+      # Check whether this definition should be included for the given instance
+      #
+      # @param instance [Object]
+      #
+      # @return [true, false]
+      #
+      def enabled?(instance)
+        return false unless super
+
+        opts = instance.include_options
+
+        # Field name must appear in instance included option keys
+        return false unless opts.include?(name.to_s)
+
+        # Check value of included option for definition name
+        !%w[0 false].include?(opts.fetch(name.to_s).to_s)
+      end
+    end
+  end
+end

data/lib/halitosis/relationships.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Halitosis
+  module Relationships
+    def self.included(base)
+      base.extend ClassMethods
+
+      base.send :include, InstanceMethods
+    end
+
+    module ClassMethods
+      # @param name [Symbol, String]
+      # @param options [nil, Hash]
+      #
+      # @return [Halitosis::Relationships::Field]
+      #
+      def relationship(name, options = {}, &procedure)
+        fields.add(Field.new(name, options, procedure))
+      end
+
+      alias_method :rel, :relationship
+    end
+
+    module InstanceMethods
+      # @return [Hash] the rendered hash with relationships resources, if any
+      #
+      def render
+        decorate_render :relationships, super
+      end
+
+      # @return [Hash] hash of rendered resources to include
+      #
+      def relationships
+        render_fields(Field.name) do |field, result|
+          value = instance_eval(&field.procedure)
+
+          child = relationships_child(field.name.to_s, value)
+
+          result[field.name] = child if child
+        end
+      end
+
+      # @return [nil, Hash, Array<Hash>] either a single rendered child
+      #   serializer or an array of them
+      #
+      def relationships_child(key, value)
+        return unless value
+
+        opts = child_relationship_opts(key)
+
+        if value.is_a?(Array)
+          value.map { |item| render_child(item, opts) }.compact
+        else
+          render_child(value, opts)
+        end
+      end
+
+      # @param key [String]
+      #
+      # @return [Hash]
+      #
+      def child_relationship_opts(key)
+        opts = include_options.fetch(key, {})
+
+        # Turn { :report => 1 } into { :report => {} } for child
+        opts = {} unless opts.is_a?(Hash)
+
+        opts
+      end
+
+      # @return [Hash] hash of options with top level string keys
+      #
+      def include_options
+        @include_options ||= Halitosis::HashUtil.stringify_params(options.fetch(:include, {}))
+      end
+    end
+  end
+end
+
+require "halitosis/relationships/field"