halitosis 0.1.0 → 0.3.0

data/lib/halitosis/identifiers.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Halitosis
+  module Identifiers
+    def self.included(base)
+      base.extend ClassMethods
+
+      base.send :include, InstanceMethods
+    end
+
+    module ClassMethods
+      # Rails-style identifier definition
+      #
+      # @param name [Symbol, String]
+      # @param options [nil, Hash]
+      #
+      # @return [Halitosis::Identifiers::Field]
+      #
+      def identifier(name, options = {}, &procedure)
+        if fields.for_type(Field).any?
+          raise InvalidField, "You can only define one identifier per serializer"
+        end
+
+        fields.add(Field.new(name, options, procedure))
+      end
+    end
+
+    module InstanceMethods
+      # @return [Hash] the rendered hash with identifiers, if any
+      #
+      def render_with_context(context)
+        super.merge(identifiers(context))
+      end
+
+      # @return [Hash] identifiers from fields
+      #
+      def identifiers(context = build_context)
+        render_fields(Field, context) do |field, result|
+          result[field.name] = field.value(context)
+        end
+      end
+    end
+  end
+end
+
+require "halitosis/identifiers/field"

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

@@ -3,8 +3,13 @@ module Halitosis
   #
   class Railtie < ::Rails::Railtie
     module Renderable
+      def render_with_params(params)
+        render(include: params[:include])
+      end
+
       def render_in(view_context)
-        view_context.render json: self
+        rendered = render_with_params(view_context.params)
+        view_context.render plain: rendered.to_json
       end
 
       def format
@@ -16,6 +21,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,34 +24,35 @@ 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)
 
-          result[field.name] = child if child
+          result[field.name] = relationships_child(field.name.to_s, context, value)
         end
       end
 
       # @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 +60,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 +69,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,33 @@ 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 identifier 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 identifier
+      # @param options [nil, Hash] identifier 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 identifier(name, options = {}, &procedure)
+        unless procedure || options.key?(:value)
+          procedure = proc { resource.public_send(name) }
         end
+        super(name, options, &procedure)
+      end
+
+      # Override standard attribute field for resource-based serializers
+      #
+      # @param name [Symbol, String] name of the attribute
+      # @param options [nil, Hash] attribute options for field
+      #
+      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 +62,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/root_links/field.rb

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

data/lib/halitosis/root_links.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Halitosis
+  module RootLinks
+    def self.included(base)
+      base.extend ClassMethods
+
+      base.send :include, InstanceMethods
+    end
+
+    module ClassMethods
+      # @return [Halitosis::RootLinks::Field]
+      #
+      def root_link(name, **options, &procedure)
+        fields.add(Field.new(name, options, procedure))
+      end
+    end
+
+    module InstanceMethods
+      # @return [Hash] the rendered hash with link, if any
+      #
+      def render(**)
+        super.tap do |result|
+          next unless options.fetch(:include_root) { true }
+
+          value = root_links
+          result[:_links] = result.fetch(:_links, {}).merge(value) if value.any?
+        end
+      end
+
+      # @return [Hash] link from fields
+      #
+      # @return [Hash] root_links from fields
+      #
+      def root_links(context = build_context)
+        render_fields(Field, context) do |field, result|
+          value = field.value(context)
+
+          result[field.name] = value if value
+        end
+      end
+    end
+  end
+end
+
+require "halitosis/root_links/field"

data/lib/halitosis/root_meta/field.rb

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

data/lib/halitosis/root_meta.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Halitosis
+  module RootMeta
+    def self.included(base)
+      base.extend ClassMethods
+
+      base.send :include, InstanceMethods
+    end
+
+    module ClassMethods
+      # @return [Halitosis::RootMeta::Field]
+      #
+      def root_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(**)
+        super.tap do |result|
+          next unless options.fetch(:include_root) { true }
+
+          value = root_meta
+          result[:_meta] = result.fetch(:_meta, {}).merge(value) if value.any?
+        end
+      end
+
+      # @return [Hash] meta from fields
+      #
+      def root_meta(context = build_context)
+        render_fields(Field, context) do |field, result|
+          value = field.value(context)
+
+          result[field.name] = value
+        end
+      end
+    end
+  end
+end
+
+require "halitosis/root_meta/field"

data/lib/halitosis/root_permissions/field.rb

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

data/lib/halitosis/root_permissions.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Halitosis
+  module RootPermissions
+    def self.included(base)
+      base.extend ClassMethods
+
+      base.send :include, InstanceMethods
+    end
+
+    module ClassMethods
+      # @return [Halitosis::RootPermission::Field]
+      #
+      def root_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(**)
+        super.tap do |result|
+          value = root_permissions
+          result[:_permissions] = result.fetch(:_permissions, {}).merge(value) if value.any?
+        end
+      end
+
+      # @return [Hash] permissions from fields
+      #
+      def root_permissions(context = build_context)
+        render_fields(Field, context) do |field, result|
+          next unless options.fetch(:include_root) { true }
+
+          value = field.value(context)
+          result[field.name] = value || false
+        end
+      end
+    end
+  end
+end
+
+require "halitosis/root_permissions/field"

data/lib/halitosis/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Halitosis
-  VERSION = "0.1.0"
+  VERSION = "0.3.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,19 +33,31 @@ module Halitosis
     base.extend ClassMethods
 
     base.include Base
+    base.include Attributes
 
     config.extensions.each { |extension| base.send :include, extension }
   end
 
   module ClassMethods
     def resource(name)
+      include Identifiers
+      include Links
+      include Meta
+      include Permissions
+      include Relationships
       include Halitosis::Resource
+      include RootLinks
+      include RootMeta
+      include RootPermissions
 
       define_resource(name)
     end
 
     def collection(name, ...)
       include Halitosis::Collection
+      include RootLinks
+      include RootMeta
+      include RootPermissions
 
       define_collection(name, ...)
     end
@@ -68,15 +80,20 @@ 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/identifiers"
 require_relative "halitosis/links"
 require_relative "halitosis/meta"
 require_relative "halitosis/permissions"
 require_relative "halitosis/relationships"
+require_relative "halitosis/root_links"
+require_relative "halitosis/root_meta"
+require_relative "halitosis/root_permissions"
 require_relative "halitosis/resource"
 require_relative "halitosis/collection"
 require_relative "halitosis/hash_util"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: halitosis
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Ben Morrall
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-09-30 00:00:00.000000000 Z
+date: 2024-12-17 00:00:00.000000000 Z
 dependencies: []
 description: Provides an interface for serializing resources as JSON with HAL-like
   links and relationships.
@@ -26,26 +26,35 @@ 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
 - lib/halitosis/hash_util.rb
+- lib/halitosis/identifiers.rb
+- lib/halitosis/identifiers/field.rb
 - lib/halitosis/links.rb
 - lib/halitosis/links/field.rb
 - lib/halitosis/meta.rb
 - 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
 - lib/halitosis/resource.rb
+- lib/halitosis/root_links.rb
+- lib/halitosis/root_links/field.rb
+- lib/halitosis/root_meta.rb
+- lib/halitosis/root_meta/field.rb
+- lib/halitosis/root_permissions.rb
+- lib/halitosis/root_permissions/field.rb
 - lib/halitosis/version.rb
 - sig/halitosis.rbs
 homepage: https://github.com/bmorrall/halitosis

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"