halitosis 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 759e2f5eada1444024bd208f82706b0a30b40dbfe24f6c1d829bea49067d1b3d
-  data.tar.gz: 72b52a2ccba027e2745fbcc245b7311b8aca6097afc77395c92f4274036c8d00
+  metadata.gz: 6dc2b6951bb551687107ecbf28dd84ef5d616b86a01f405bfd0578592e2ae572
+  data.tar.gz: a98c1b99cc9973958db53bd3ea5d6acd11de9b6f79fb9a5c9fcf07f97514de01
 SHA512:
-  metadata.gz: b4384527d214837272668d24c9e0f4c7ad9578189d0c31bbadb8490b00a88f2cd92b236c7c36f3584f98abebf216980c626c6b617c72e4e217d11bac3df175ed
-  data.tar.gz: 1f4d4c859877996961a9187397ab9913f0214542893d718f5fe8c9dc226ceaff5eb2d298f4b18d62f0a65ad5e1a32330268ff7c1eb57c25db25d0e032fecbad6
+  metadata.gz: dfed5ec625a1764322fa5ddc3df08b3fe0ee2dca6bcbe21da0c92daa00a168518f2f31e69ac0c7834ef4dded8ba3c62e93ba9349f9e68d63e7403ce98131d96b
+  data.tar.gz: bb36dc686ccecdefc51500b9cf5d8142a72d4e460ad562ea020de9b93b57f00f9a2ff4ddac12351afe3060c2494408dbefa3735002672bb80e39d97bb88e2f34

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/{properties → attributes}/field.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Halitosis
-  module Properties
+  module Attributes
     class Field < Halitosis::Field
     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
@@ -49,20 +49,14 @@ 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)
+        render_with_context(build_context)
       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,7 @@ 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
     end
 
@@ -50,47 +48,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/links/field.rb

@@ -25,7 +25,7 @@ module Halitosis
 
       # @return [nil, Hash]
       #
-      def value(_instance)
+      def value(_context)
         hrefs = super
 
         attrs = options.fetch(:attrs, {})

data/lib/halitosis/links.rb

@@ -19,9 +19,9 @@ module Halitosis
     module InstanceMethods
       # @return [Hash] the rendered hash with links, if any
       #
-      def render
-        if options.fetch(:include_links, true)
-          decorate_render :links, super
+      def render_with_context(context)
+        if context.fetch(:include_links, true)
+          decorate_render :links, context, super
         else
           super
         end
@@ -29,9 +29,9 @@ module Halitosis
 
       # @return [Hash] links from fields
       #
-      def links
-        render_fields(Field.name) do |field, result|
-          value = field.value(self)
+      def links(context = build_context)
+        render_fields(Field, context) do |field, result|
+          value = field.value(context)
 
           result[field.name] = value if value
         end

data/lib/halitosis/meta.rb

@@ -19,9 +19,9 @@ module Halitosis
     module InstanceMethods
       # @return [Hash] the rendered hash with meta, if any
       #
-      def render
-        if options.fetch(:include_meta, true)
-          decorate_render :meta, super
+      def render_with_context(context)
+        if context.fetch(:include_meta, true)
+          decorate_render :meta, context, super
         else
           super
         end
@@ -29,11 +29,11 @@ module Halitosis
 
       # @return [Hash] meta from fields
       #
-      def meta
-        render_fields(Field.name) do |field, result|
-          value = field.value(self)
+      def meta(context = build_context)
+        render_fields(Field, context) do |field, result|
+          value = field.value(context)
 
-          result[field.name] = value if value
+          result[field.name] = value
         end
       end
     end

data/lib/halitosis/permissions.rb

@@ -19,9 +19,9 @@ module Halitosis
     module InstanceMethods
       # @return [Hash] the rendered hash with permissions, if any
       #
-      def render
-        if options.fetch(:include_permissions, true)
-          decorate_render :permissions, super
+      def render_with_context(context)
+        if context.fetch(:include_permissions, true)
+          decorate_render :permissions, context, super
         else
           super
         end
@@ -29,11 +29,11 @@ module Halitosis
 
       # @return [Hash] permissions from fields
       #
-      def permissions
-        render_fields(Field.name) do |field, result|
-          value = field.value(self)
+      def permissions(context = build_context)
+        render_fields(Field, context) do |field, result|
+          value = field.value(context)
 
-          result[field.name] = value if value
+          result[field.name] = value || false
         end
       end
     end

data/lib/halitosis/railtie.rb

@@ -16,6 +16,10 @@ module Halitosis
       Halitosis.config.extensions << ::Rails.application.routes.url_helpers
     end
 
+    initializer "halitosis.error_response" do |app|
+      app.config.action_dispatch.rescue_responses[InvalidQueryParameter.name] ||= :bad_request
+    end
+
     initializer "halitosis.renderable" do |_app|
       Halitosis.config.extensions << Renderable
     end

data/lib/halitosis/relationships/field.rb

@@ -21,10 +21,10 @@ module Halitosis
       #
       # @return [true, false]
       #
-      def enabled?(instance)
+      def enabled?(context)
         return false unless super
 
-        opts = instance.include_options
+        opts = context.include_options
 
         # Field name must appear in instance included option keys
         return false unless opts.include?(name.to_s)

data/lib/halitosis/relationships.rb

@@ -24,17 +24,20 @@ module Halitosis
     module InstanceMethods
       # @return [Hash] the rendered hash with relationships resources, if any
       #
-      def render
-        decorate_render :relationships, super
+      def render_with_context(context)
+        decorate_render :relationships, context, super
       end
 
       # @return [Hash] hash of rendered resources to include
       #
-      def relationships
-        render_fields(Field.name) do |field, result|
-          value = instance_eval(&field.procedure)
+      def relationships(context = build_context)
+        # Do not validation non-root collections (as they pass values directly to children)
+        validate_relationships!(context) unless collection?
 
-          child = relationships_child(field.name.to_s, value)
+        render_fields(Field, context) do |field, result|
+          value = field.value(context)
+
+          child = relationships_child(field.name.to_s, context, value)
 
           result[field.name] = child if child
         end
@@ -43,15 +46,15 @@ module Halitosis
       # @return [nil, Hash, Array<Hash>] either a single rendered child
       #   serializer or an array of them
       #
-      def relationships_child(key, value)
+      def relationships_child(key, context, value)
         return unless value
 
-        opts = child_relationship_opts(key)
+        opts = child_relationship_opts(key, context)
 
         if value.is_a?(Array)
-          value.map { |item| render_child(item, opts) }.compact
+          value.map { |item| render_child(item, context, opts) }.compact
         else
-          render_child(value, opts)
+          render_child(value, context, opts)
         end
       end
 
@@ -59,8 +62,8 @@ module Halitosis
       #
       # @return [Hash]
       #
-      def child_relationship_opts(key)
-        opts = include_options.fetch(key, {})
+      def child_relationship_opts(key, context)
+        opts = context.include_options.fetch(key, {})
 
         # Turn { :report => 1 } into { :report => {} } for child
         opts = {} unless opts.is_a?(Hash)
@@ -68,10 +71,17 @@ module Halitosis
         opts
       end
 
-      # @return [Hash] hash of options with top level string keys
-      #
-      def include_options
-        @include_options ||= Halitosis::HashUtil.stringify_params(options.fetch(:include, {}))
+      private
+
+      def validate_relationships!(context)
+        opts = context.include_options.keys.map(&:to_s)
+
+        opts -= self.class.fields.for_type(Field).map { |field| field.name.to_s }
+
+        return if opts.none?
+
+        resource_label = [self.class.resource_type, "resource"].compact.join(" ")
+        raise Halitosis::InvalidQueryParameter.new("The #{resource_label} does not have a `#{opts.first}` relationship path.", "include")
       end
     end
   end

data/lib/halitosis/resource.rb

@@ -14,8 +14,6 @@ module Halitosis
       base.send :include, InstanceMethods
 
       base.send :attr_reader, :resource
-
-      base.class.send :attr_accessor, :resource_name
     end
 
     module ClassMethods
@@ -24,22 +22,21 @@ module Halitosis
       # @return [Module] self
       #
       def define_resource(name)
-        self.resource_name = name.to_s
+        self.resource_type = name.to_s
 
         alias_method name, :resource
       end
 
-      # Override standard property field for resource-based serializers
+      # Override standard attribute field for resource-based serializers
       #
-      # @param name [Symbol, String] name of the property
-      # @param options [nil, Hash] property options for field
+      # @param name [Symbol, String] name of the attribute
+      # @param options [nil, Hash] attribute options for field
       #
-      def property(name, options = {}, &procedure)
-        super.tap do |field|
-          unless field.procedure || field.options.key?(:value)
-            field.procedure = proc { resource.send(name) }
-          end
+      def attribute(name, options = {}, &procedure)
+        unless procedure || options.key?(:value)
+          procedure = proc { resource.public_send(name) }
         end
+        super(name, options, &procedure)
       end
     end
 
@@ -53,6 +50,23 @@ module Halitosis
 
         super(**)
       end
+
+      # @return [Hash] the rendered hash with resource, as a hash
+      #
+      def render_with_context(context)
+        if (include_root = context.fetch(:include_root) { context.depth.zero? })
+          {root_name(include_root, self.class.resource_type) => super}
+        else
+          super
+        end
+      end
+
+      private
+
+      def root_name(include_root, default)
+        return include_root.to_sym if include_root.is_a?(String) || include_root.is_a?(Symbol)
+        default.to_sym
+      end
     end
   end
 end

data/lib/halitosis/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Halitosis
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/halitosis.rb

@@ -15,9 +15,9 @@ require "json"
 #
 #     resource :article
 #
-#     property :id, required: true
+#     attribute :id, required: true
 #
-#     property :title
+#     attribute :title
 #
 #     link :self, -> { article_path(article) }
 #
@@ -33,6 +33,11 @@ module Halitosis
     base.extend ClassMethods
 
     base.include Base
+    base.include Links
+    base.include Meta
+    base.include Permissions
+    base.include Attributes
+    base.include Relationships
 
     config.extensions.each { |extension| base.send :include, extension }
   end
@@ -68,11 +73,12 @@ module Halitosis
   end
 end
 
+require_relative "halitosis/context"
 require_relative "halitosis/base"
 require_relative "halitosis/errors"
 require_relative "halitosis/field"
 require_relative "halitosis/fields"
-require_relative "halitosis/properties"
+require_relative "halitosis/attributes"
 require_relative "halitosis/links"
 require_relative "halitosis/meta"
 require_relative "halitosis/permissions"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: halitosis
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Ben Morrall
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-09-30 00:00:00.000000000 Z
+date: 2024-10-07 00:00:00.000000000 Z
 dependencies: []
 description: Provides an interface for serializing resources as JSON with HAL-like
   links and relationships.
@@ -26,10 +26,13 @@ files:
 - README.md
 - Rakefile
 - lib/halitosis.rb
+- lib/halitosis/attributes.rb
+- lib/halitosis/attributes/field.rb
 - lib/halitosis/base.rb
 - lib/halitosis/collection.rb
 - lib/halitosis/collection/field.rb
 - lib/halitosis/configuration.rb
+- lib/halitosis/context.rb
 - lib/halitosis/errors.rb
 - lib/halitosis/field.rb
 - lib/halitosis/fields.rb
@@ -40,8 +43,6 @@ files:
 - lib/halitosis/meta/field.rb
 - lib/halitosis/permissions.rb
 - lib/halitosis/permissions/field.rb
-- lib/halitosis/properties.rb
-- lib/halitosis/properties/field.rb
 - lib/halitosis/railtie.rb
 - lib/halitosis/relationships.rb
 - lib/halitosis/relationships/field.rb

data/lib/halitosis/properties.rb

@@ -1,40 +0,0 @@
-# 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"