halitosis 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 759e2f5eada1444024bd208f82706b0a30b40dbfe24f6c1d829bea49067d1b3d
-  data.tar.gz: 72b52a2ccba027e2745fbcc245b7311b8aca6097afc77395c92f4274036c8d00
+  metadata.gz: 0576b2d1e7ce15303f1bdc4a845bc7e81d1f2e497d3e49b220f1dd68920938cb
+  data.tar.gz: 79a5d29e8ec21cf3f035719dab8ef719216424a8514c2ff045d8f0f0d1cbe552
 SHA512:
-  metadata.gz: b4384527d214837272668d24c9e0f4c7ad9578189d0c31bbadb8490b00a88f2cd92b236c7c36f3584f98abebf216980c626c6b617c72e4e217d11bac3df175ed
-  data.tar.gz: 1f4d4c859877996961a9187397ab9913f0214542893d718f5fe8c9dc226ceaff5eb2d298f4b18d62f0a65ad5e1a32330268ff7c1eb57c25db25d0e032fecbad6
+  metadata.gz: '02779ecf3fd87d66cab25c245c1ca82a2eee370241088d1af6fcc72bde1f3e7917687119260e4d5d04f22dfb363c1d8d9b54730caece6a82825d2ca65f6d9ef5'
+  data.tar.gz: 2e77dae400e7f5ece72aa1604898444b90c43cca04694b495f23dda4aaf38e4b62b05bc1cdd67b1f32d1e5c1014924756e2b242bd4c5a648df944bee18d61520

data/README.md

@@ -21,7 +21,7 @@ Need something more standardized ([JSON:API](https://jsonapi.org/), or [HAL](htt
 Add this line to your application's Gemfile:
 
 ```ruby
-gem "`UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG`"
+gem "halitosis"
 ```
 
 And then execute:
@@ -33,7 +33,7 @@ $ bundle install
 Or install it yourself as:
 
 ```bash
-$ gem install `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG`
+$ gem install halitosis
 ```
 
 ### Basic usage
@@ -51,7 +51,7 @@ class DuckSerializer
 
   resource :duck
 
-  property :name
+  attribute :name
 
   link :self do
     "/ducks/#{duck.code}"
@@ -68,11 +68,13 @@ serializer = DuckSerializer.new(duck)
 
 Then call `serializer.render`:
 
-```json
+```ruby
 {
-  name: 'Ferdi',
-  _links: {
-    self: { href: '/ducks/ferdi' }
+  duck: {
+    name: 'Ferdi',
+    _links: {
+      self: { href: '/ducks/ferdi' }
+    }
   }
 }
 ```
@@ -80,7 +82,7 @@ Then call `serializer.render`:
 Or `serializer.to_json`:
 
 ```ruby
-'{"name": "Ferdi", "_links": {"self": {"href": "/ducks/ferdi"}}}'
+'{"duck": {"name": "Ferdi", "_links": {"self": {"href": "/ducks/ferdi"}}}}'
 ```
 
 
@@ -117,10 +119,10 @@ When a resource is declared, `#initialize` expects the resource as the first arg
 serializer = DuckSerializer.new(Duck.new, ...)
 ```
 
-This makes property definitions cleaner:
+This makes attribute definitions cleaner:
 
 ```ruby
-property :name # now calls Duck#name by default
+attribute :name # now calls Duck#name by default
 ```
 
 #### 3. Collection
@@ -139,39 +141,51 @@ end
 
 The block should return an array of Halitosis instances in order to be rendered.
 
-### Defining properties, links, relationships, meta, and permissions
+### Defining attributes, links, relationships, meta, and permissions
 
-Properties can be defined in several ways:
+Attributes can be defined in several ways:
 
 ```ruby
-property(:quacks) { "#{duck.quacks} per minute" }
+attribute(:quacks) { "#{duck.quacks} per minute" }
+```
+
+```ruby
+attribute :quacks # => Duck#quacks, if resource is declared
 ```
 
 ```ruby
-property :quacks # => Duck#quacks, if resource is declared
+attribute :quacks, value: "many"
 ```
 
 ```ruby
-property :quacks do
+attribute :quacks do
   duck.quacks.round
 end
 ```
 
 ```ruby
-property(:quacks) { calculate_quacks }
+attribute(:quacks) { calculate_quacks }
 
 def calculate_quacks
   ...
 end
 ```
 
+Attributes can also be implemented using the legacy `property` alias:
+
+```ruby
+property(:quacks) { "#{duck.quacks} per minute" }
+property :quacks # Duck#quacks
+property :quacks, value: "many"
+```
+
 #### Conditionals
 
-The inclusion of properties can be determined by conditionals using `if` and
+The inclusion of attributes can be determined by conditionals using `if` and
 `unless` options. For example, with a method name:
 
 ```ruby
-property :quacks, if: :include_quacks?
+attribute :quacks, if: :include_quacks?
 
 def include_quacks?
   duck.quacks < 10
@@ -180,7 +194,7 @@ end
 
 With a proc:
 ```ruby
-property :quacks, unless: proc { duck.quacks.nil? }, value: ...
+attribute :quacks, unless: proc { duck.quacks.nil? }, value: ...
 ```
 
 For links and relationships:

data/lib/halitosis/attributes/field.rb

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

data/lib/halitosis/attributes.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Halitosis
+  module Attributes
+    def self.included(base)
+      base.extend ClassMethods
+
+      base.send :include, InstanceMethods
+    end
+
+    module ClassMethods
+      # Legacy alias for attribute
+      #
+      # @param name [Symbol, String]
+      # @param options [nil, Hash]
+      #
+      # @return [Halitosis::Attributes::Field]
+      def property(...)
+        attribute(...)
+      end
+
+      # Rails-style attribute definition
+      #
+      # @param name [Symbol, String]
+      # @param options [nil, Hash]
+      #
+      # @return [Halitosis::Attributes::Field]
+      #
+      def attribute(name, options = {}, &procedure)
+        fields.add(Field.new(name, options, procedure))
+      end
+    end
+
+    module InstanceMethods
+      # @return [Hash] the rendered hash with attributes, if any
+      #
+      def render_with_context(context)
+        super.merge(attributes(context))
+      end
+
+      # @return [Hash] attributes from fields
+      #
+      def attributes(context = build_context)
+        render_fields(Field, context) do |field, result|
+          result[field.name] = field.value(context)
+        end
+      end
+    end
+  end
+end
+
+require "halitosis/attributes/field"

data/lib/halitosis/base.rb

@@ -1,18 +1,18 @@
 # frozen_string_literal: true
 
 module Halitosis
+  # Base module for all serializer classes.
+  #
+  # Include this module in your serializer class, and include any additional field-type modules
   module Base
     def self.included(base)
       base.extend ClassMethods
 
       base.send :include, InstanceMethods
-      base.send :include, Links
-      base.send :include, Meta
-      base.send :include, Permissions
-      base.send :include, Properties
-      base.send :include, Relationships
 
       base.send :attr_reader, :options
+
+      base.class.send :attr_accessor, :resource_type
     end
 
     module ClassMethods
@@ -32,7 +32,7 @@ module Halitosis
       # @return [Object] the serializer instance
       #
       def initialize(**options)
-        @options = Halitosis::HashUtil.symbolize_params(options)
+        @options = Halitosis::HashUtil.symbolize_hash(options).freeze
       end
 
       # @return [Hash, Array] rendered JSON
@@ -48,21 +48,15 @@ module Halitosis
 
       # @return [Hash] rendered representation
       #
-      def render
-        {}
-      end
-
-      # @return [nil, Object] the parent serializer, if this instance is an
-      #   embedded child
-      #
-      def parent
-        @parent ||= options.fetch(:parent, nil)
+      def render(**options)
+        render_with_context(build_context(options))
       end
 
-      # @return [Integer] the depth at which this serializer is embedded
+      # @param context [Halitosis::Context] the context instance
+      # @return [Hash] the rendered hash
       #
-      def depth
-        @depth ||= parent ? parent.depth + 1 : 0
+      def render_with_context(_context)
+        {}
       end
 
       def collection?
@@ -71,6 +65,13 @@ module Halitosis
 
       protected
 
+      # Build a new context instance using this serializer instance
+      #
+      # @return [Halitosis::Context] the context instance
+      def build_context(options = {})
+        Context.new(self, HashUtil.deep_merge(@options, options))
+      end
+
       # Allow included modules to decorate rendered hash
       #
       # @param key [Symbol] the key (e.g. `embedded`, `links`)
@@ -78,9 +79,9 @@ module Halitosis
       #
       # @return [Hash] the decorated hash
       #
-      def decorate_render(key, result)
+      def decorate_render(key, context, result)
         result.tap do
-          value = send(key)
+          value = send(key, context)
 
           result[:"_#{key}"] = value if value.any?
         end
@@ -93,11 +94,11 @@ module Halitosis
       #
       # @return [Hash] the result
       #
-      def render_fields(type)
-        fields = self.class.fields.fetch(type, [])
+      def render_fields(type, context)
+        fields = self.class.fields.for_type(type)
 
         fields.each_with_object({}) do |field, result|
-          next unless field.enabled?(self)
+          next unless field.enabled?(context)
 
           yield field, result
         end
@@ -108,15 +109,10 @@ module Halitosis
       #
       # @return [nil, Hash] the rendered child
       #
-      def render_child(child, opts)
-        return unless child.class.included_modules.include?(Halitosis)
-
-        child.options[:include] ||= {}
-        child.options[:include] = child.options[:include].merge(opts)
-
-        child.options[:parent] = self
+      def render_child(child, context, opts)
+        return unless child.class.included_modules.include?(Halitosis::Base)
 
-        child.render
+        child.render_with_context child.build_context(parent: context, include: opts)
       end
     end
   end

data/lib/halitosis/collection/field.rb

@@ -3,6 +3,17 @@
 module Halitosis
   module Collection
     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, "Collection #{name} must be defined with a proc"
+      end
     end
   end
 end

data/lib/halitosis/collection.rb

@@ -15,8 +15,6 @@ module Halitosis
       base.send :include, InstanceMethods
 
       base.send :attr_reader, :collection
-
-      base.class.send :attr_accessor, :collection_name
     end
 
     module ClassMethods
@@ -25,9 +23,9 @@ module Halitosis
       # @return [Module] self
       #
       def define_collection(name, options = {}, &procedure)
-        raise InvalidCollection, "#{self.name} collection is already defined" if fields.key?(Field.name)
+        raise InvalidCollection, "#{self.name || Collection.name} collection is already defined" if fields.for_type(Field).any?
 
-        self.collection_name = name.to_s
+        self.resource_type = name.to_s
 
         alias_method name, :collection
 
@@ -39,7 +37,22 @@ module Halitosis
       end
 
       def collection_field
-        fields[Field.name].last || raise(InvalidCollection, "#{name} collection is not defined")
+        fields.for_type(Field).last || raise(InvalidCollection, "#{name || Collection.name} collection is not defined")
+      end
+
+      # Provide an alias for root_link
+      def link(*, **, &)
+        root_link(*, **, &)
+      end
+
+      # Provide an alias for root_meta
+      def meta(*, **, &)
+        root_meta(*, **, &)
+      end
+
+      # Provide an alias for root_permission
+      def permission(*, **, &)
+        root_permission(*, **, &)
       end
     end
 
@@ -50,47 +63,47 @@ module Halitosis
       #
       def initialize(collection, **)
         @collection = collection
+        @collection_field = self.class.collection_field
 
         super(**)
       end
 
-      # @return [Hash] the rendered hash with collection, if any
+      # @return [Hash, Array] the rendered hash with collection, as an array or a hash under a key
       #
-      def render
-        field = self.class.collection_field
-        if depth.zero?
-          super.merge(field.name => render_collection_field(field))
+      def render_with_context(context)
+        if (include_root = context.fetch(:include_root) { context.depth.zero? })
+          {
+            root_name(include_root) => render_collection_field(context)
+          }.merge(super)
         else
-          render_collection_field(field)
+          render_collection_field(context)
         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]
+      attr_reader :collection_field
+
+      # @return [Hash] collection from fields
       #
-      def collection_opts
-        return include_options if depth.positive?
+      def render_collection_field(context)
+        value = collection_field.value(context)
 
-        opts = include_options.fetch(self.class.collection_field.name.to_s, {})
+        return render_child(value, context, context.include_options) if value.is_a?(Halitosis::Collection)
+
+        value.reject { |child| child.is_a?(Halitosis::Collection) } # Skip nested collections in array
+          .map { |child| render_child(child, context, context.include_options) }
+          .compact
+      end
 
-        # Turn { :report => 1 } into { :report => {} } for child
-        opts = {} unless opts.is_a?(Hash)
+      def root_name(include_root)
+        return include_root.to_sym if include_root.is_a?(String) || include_root.is_a?(Symbol)
 
-        opts
+        self.class.resource_type.to_sym
       end
     end
   end

data/lib/halitosis/context.rb

@@ -0,0 +1,54 @@
+module Halitosis
+  class Context
+    # @param instance [Halitosis::Base] the serializer instance
+    # @param options [Hash] hash of options
+    def initialize(instance, options = {})
+      @instance = instance
+      @options = HashUtil.symbolize_hash(options).freeze
+    end
+
+    ### Instance ###
+
+    # Evaluate guard procedure or method on the serializer instance
+    #
+    def call_instance(guard)
+      case guard
+      when Proc
+        instance.instance_exec(self, &guard)
+      when Symbol, String
+        instance.send(guard)
+      else
+        guard
+      end
+    end
+
+    ### Options ###
+
+    def fetch(...)
+      options.fetch(...)
+    end
+
+    # @return [Hash] hash of options with top level string keys
+    #
+    def include_options
+      @include_options ||= HashUtil.hasherize_include_option(options[:include] || {})
+    end
+
+    # @return [nil, Halitosis::Context] the parent context, if this instance is an
+    #   embedded child
+    #
+    def parent
+      options.fetch(:parent, nil)
+    end
+
+    # @return [Integer] the depth at which this serializer is embedded
+    #
+    def depth
+      @depth ||= parent ? parent.depth + 1 : 0
+    end
+
+    private
+
+    attr_reader :instance, :options
+  end
+end

data/lib/halitosis/errors.rb

@@ -3,9 +3,22 @@
 module Halitosis
   class Error < StandardError; end
 
+  ### Configuration Errors ###
+
   class InvalidCollection < StandardError; end
 
   class InvalidField < StandardError; end
 
   class InvalidResource < StandardError; end
+
+  ### Rendering Errors ###
+
+  class InvalidQueryParameter < Error
+    def initialize(message, parameter)
+      @parameter = parameter
+      super(message)
+    end
+
+    attr_reader :parameter
+  end
 end

data/lib/halitosis/field.rb

@@ -7,8 +7,6 @@ module Halitosis
   class Field
     attr_reader :name, :options
 
-    attr_accessor :procedure
-
     # Construct a new Field instance
     #
     # @param name [Symbol, String] Field name
@@ -18,27 +16,25 @@ module Halitosis
     #
     def initialize(name, options, procedure)
       @name = name.to_sym
-      @options = Halitosis::HashUtil.symbolize_params(options)
+      @options = Halitosis::HashUtil.symbolize_hash(options)
       @procedure = procedure
     end
 
-    # @param instance [Object] the serializer instance with which to evaluate
+    # @param context [Halitosis::Context] 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
+    def value(context)
+      options.fetch(:value) { context.call_instance(procedure || name) }
     end
 
     # @return [true, false] whether this Field should be included based on
     #   its conditional guard, if any
     #
-    def enabled?(instance)
+    def enabled?(context)
       if options.key?(:if)
-        !!eval_guard(instance, options.fetch(:if))
+        !!context.call_instance(options.fetch(:if))
       elsif options.key?(:unless)
-        !eval_guard(instance, options.fetch(:unless))
+        !context.call_instance(options.fetch(:unless))
       else
         true
       end
@@ -57,17 +53,6 @@ module Halitosis
 
     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
+    attr_reader :procedure
   end
 end

data/lib/halitosis/fields.rb

@@ -9,10 +9,16 @@ module Halitosis
 
       field.validate
 
+      field.freeze
+
       self[type] ||= []
       self[type] << field
 
       field
     end
+
+    def for_type(type)
+      fetch(type.name, [])
+    end
   end
 end

data/lib/halitosis/hash_util.rb

@@ -4,23 +4,42 @@ module Halitosis
   module HashUtil
     module_function
 
-    # Transform hash keys into strings if necessary
+    # Transform include params into a hash
     #
-    # @param hash [Hash, Array, String]
+    # @param object [Hash, Array, String]
     #
     # @return [Hash]
-    #
-    def stringify_params(hash)
-      case hash
-      when String
-        hash.split(",").inject({}) do |output, key|
+    def hasherize_include_option(object)
+      case object
+      when Hash
+        object.transform_keys(&:to_s)
+      when String, Symbol
+        object.to_s.split(",").inject({}) do |output, key|
           f, value = key.split(".", 2)
-          output.merge(f => value ? stringify_params(value) : true)
+          deep_merge(output, f => value ? hasherize_include_option(value) : {})
         end
       when Array
-        hash.map { |item| stringify_params(item) }.inject({}, &:merge)
+        object.inject({}) do |output, value|
+          deep_merge(output, hasherize_include_option(value))
+        end
       else
-        hash.transform_keys(&:to_s)
+        object
+      end
+    end
+
+    # Deep merge two hashes
+    #
+    # @param hash [Hash]
+    # @param other_hash [Hash]
+    #
+    # @return [Hash]
+    def deep_merge(hash, other_hash)
+      hash.merge(other_hash) do |key, this_val, other_val|
+        if this_val.is_a?(Hash) && other_val.is_a?(Hash)
+          deep_merge(this_val, other_val)
+        else
+          other_val
+        end
       end
     end
 
@@ -30,9 +49,9 @@ module Halitosis
     #
     # @return [Hash]
     #
-    def symbolize_params(hash)
+    def symbolize_hash(hash)
       if hash.respond_to?(:transform_keys)
-        hash.transform_keys(&:to_sym).transform_values(&method(:symbolize_params))
+        hash.transform_keys(&:to_sym).transform_values(&method(:symbolize_hash))
       else
         hash
       end

data/lib/halitosis/{properties → identifiers}/field.rb

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