porridge 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f513e5f2d179544d20b2e0d181066402edd82f03ed491f7ef0c196516a193192
-  data.tar.gz: 864b15e6a5049bc21e4734c184b686604fecef2598597d4287ddc70a7bdeb3de
+  metadata.gz: 1c767e7225acd4284055aa8379a67e9f8f8527d8946ff4df782e3c377d67bec8
+  data.tar.gz: b2bad4d91dc0feb01d990aaa1226345e49ce9baf0900578de6f720d47f86d5c3
 SHA512:
-  metadata.gz: b8104a38ee8512d49eab94d6c5014158f5dac26d30a47410cfed46d92c5830c32817bc22be2c7274802de8464596a5c00e722992c826a6765b58c75eab0a3b1b
-  data.tar.gz: f72647f1966d161194f6e239d2da082481a0a84733a0b8d30b99f893d65ab4475bd4f6c61ecf6a3c522b480a139932f75e0081f6eb6c306e1b53f29c7c1b990e
+  metadata.gz: 835d2f5b110f0de84a242416791b49b28847de02cab5324f87ea6ee6e6209236f9fbc9e288e3caa158056f8e060e9ff254bf48a73c3b925366ea4772fe11be78
+  data.tar.gz: bee59698bf34b8f763c36f39955ffa15ae60976cd151675bbfe2e049f6eb8ba4205d99db74d069b181c64636584d3dbc5816097ceafb9d9f081e7a6ac084d98a

data/.gitignore

@@ -9,3 +9,6 @@
 
 # rspec failure tracking
 .rspec_status
+
+# built gems
+*.gem

data/.idea/fileTemplates/includes/Ruby File Header.rb

@@ -0,0 +1,2 @@
+# frozen_string_literal: true
+

data/.idea/fileTemplates/internal/RSpec.rb

@@ -0,0 +1,5 @@
+#parse("Ruby File Header.rb")
+require 'spec_helper'
+
+describe Porridge::${NAME} do
+end

data/.idea/porridge.iml

@@ -11,12 +11,16 @@
     </content>
     <orderEntry type="inheritedJdk" />
     <orderEntry type="sourceFolder" forTests="false" />
+    <orderEntry type="library" scope="PROVIDED" name="activesupport (v5.2.5, rbenv: 3.0.0) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="ast (v2.4.2, rbenv: 3.0.0) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="bundler (v2.2.25, rbenv: 3.0.0) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="byebug (v11.1.3, rbenv: 3.0.0) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="codecov (v0.6.0, rbenv: 3.0.0) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="concurrent-ruby (v1.1.9, rbenv: 3.0.0) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="diff-lcs (v1.5.0, rbenv: 3.0.0) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="docile (v1.4.0, rbenv: 3.0.0) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="i18n (v1.8.11, rbenv: 3.0.0) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="minitest (v5.15.0, rbenv: 3.0.0) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="parallel (v1.21.0, rbenv: 3.0.0) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="parser (v3.1.0.0, rbenv: 3.0.0) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="rainbow (v3.0.0, rbenv: 3.0.0) [gem]" level="application" />
@@ -36,6 +40,8 @@
     <orderEntry type="library" scope="PROVIDED" name="simplecov (v0.21.2, rbenv: 3.0.0) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="simplecov-html (v0.12.3, rbenv: 3.0.0) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="simplecov_json_formatter (v0.1.3, rbenv: 3.0.0) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="thread_safe (v0.3.6, rbenv: 3.0.0) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="tzinfo (v1.2.9, rbenv: 3.0.0) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="unicode-display_width (v2.1.0, rbenv: 3.0.0) [gem]" level="application" />
   </component>
   <component name="RakeTasksCache">

data/.yardopts

@@ -0,0 +1 @@
+--private --protected lib/**/*.rb - README.md

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
+## [0.2.0] - 2022-01-19
+
+This is the initial functional release of the gem. Extractors, serializers, fields, field policies, and an elegant DSL over top were implemented added.
+
 ## [0.1.0] - 2022-01-16
 
 - Initial release. This version of the gem has no functionality whatsoever and is intended solely as a deployment test.

data/Gemfile.lock

@@ -1,17 +1,27 @@
 PATH
   remote: .
   specs:
-    porridge (0.1.0)
+    porridge (0.2.0)
+      activesupport (~> 5.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    activesupport (5.2.5)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
     ast (2.4.2)
     byebug (11.1.3)
     codecov (0.6.0)
       simplecov (>= 0.15, < 0.22)
+    concurrent-ruby (1.1.9)
     diff-lcs (1.5.0)
     docile (1.4.0)
+    i18n (1.8.11)
+      concurrent-ruby (~> 1.0)
+    minitest (5.15.0)
     parallel (1.21.0)
     parser (3.1.0.0)
       ast (~> 2.4.1)
@@ -54,6 +64,9 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.12.3)
     simplecov_json_formatter (0.1.3)
+    thread_safe (0.3.6)
+    tzinfo (1.2.9)
+      thread_safe (~> 0.1)
     unicode-display_width (2.1.0)
 
 PLATFORMS

data/README.md

@@ -1,5 +1,6 @@
 # Porridge
-
+[![Gem Version](https://badge.fury.io/rb/porridge.svg)](https://badge.fury.io/rb/porridge)
+![Build](https://github.com/jacoblockard99/porridge/actions/workflows/build.yml/badge.svg)
 [![Maintainability](https://api.codeclimate.com/v1/badges/9c3a8a230097bac612e3/maintainability)](https://codeclimate.com/github/jacoblockard99/porridge/maintainability)
 [![codecov](https://codecov.io/gh/jacoblockard99/porridge/branch/master/graph/badge.svg?token=V9GxyepasN)](https://codecov.io/gh/jacoblockard99/porridge)
 

data/lib/porridge/array_serializer.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Porridge
+  # {ArraySerializer} is a serializer that wraps another serializer, calling it for every element of the input array,
+  # if an array was given, or simply passing it the input if not.
+  class ArraySerializer < Serializer
+    # Creates a new instance of {ArraySerializer} with the given base serializer.
+    # @param base [Serializer, #call] the base serializer to call for any input, or all elements of that input if the
+    #   input is an array.
+    # @raise [InvalidSerializerError] if the given base serializer is not a valid serializer.
+    def initialize(base)
+      Serializer.ensure_valid!(base)
+      @base = base
+      super()
+    end
+
+    # Serializes the given object, which may be an array, for the given input with the given options. If the object
+    # is an array (according to {#array?}), the base serializer {#base} will be called for each element, and an array
+    # with each result will be returned. If the object is not an array, will simply delegate to {#base}.
+    #
+    # The given object and options will be given to the base serializer for every element. Note that the options are
+    # *not* cloned or duplicated. Therefore <b>the base serializer must not mutate the options object</b> or else
+    # the other invocations will also receive the mutated version.
+    #
+    # @param object_or_objects [Object, Array<Object>] the object or array of objects for which to transform the input.
+    # @param input the object being transformed, typically either a hash or an array.
+    # @param options [Hash] a hash of "options," which may be application specific.
+    # @return [Object, Array<Object>] the transformed output if the object was not an array, or an array of all
+    #   transformed outputs if the object was an array.
+    def call(object_or_objects, input, options)
+      if array?(object_or_objects)
+        object_or_objects.map { |object| base.call(object, input, options) }
+      else
+        base.call(object_or_objects, input, options)
+      end
+    end
+
+    protected
+
+    # Determines whether the given object is an array for the purposes of this {ArraySerializer} instance. The default
+    # implementation simple checks to see if the object implements the +map+ method. You may override this method to
+    # change the default behavior, if, for example, you have a non-array that implements +map+.
+    # @param object the object to check.
+    # @return [Boolean] +true+ if the given object functions like an array; +false+ if otherwise.
+    def array?(object)
+      object.respond_to? :map
+    end
+
+    private
+
+    # The base serializer, which will be called for the object, or each object, if an array is given.
+    # @return [Serializer, #call]
+    attr_reader :base
+  end
+end

data/lib/porridge/chain_serializer.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Porridge
+  # {ChainSerializer} is a serializer that chains multiple other serializers together by passing the output of the
+  # first one as the input of the second, and the output of the second as the input of the third, and so on.
+  class ChainSerializer < Serializer
+    # Creates a new instance of {ChainSerializer} with the given serializers to chain.
+    # @param serializers [Array<Serializer,#call>] the splatted array of serializers to chain.
+    # @raise [InvalidSerializerError] if any of the given serializers are not valid serializers.
+    def initialize(*serializers)
+      super()
+      Serializer.ensure_valid!(*serializers)
+      @serializers = serializers
+    end
+
+    # Transforms the given input for the given object with the given options by chaining each serializer (contained in
+    # {#serializers}). The provided input will be given to the first serializer, whose output will be given to the next
+    # serializer, and so on for each serializer.
+    #
+    # The given object and options will be given to all the provided serializers. Note that the options are *not*
+    # cloned or duplicated. Therefore <b>none of the serializers should mutate the options object</b> or else
+    # all the other serializers will also receive the mutated version.
+    #
+    # @param object the object for which to transform the input.
+    # @param input the object being transformed, typically either a hash or an array.
+    # @param options [Hash] a hash of "options," which may be application specific.
+    # @return the transformed output, typically either a hash or an array, as returned from the final chained
+    #   serializer.
+    def call(object, input, options)
+      output = input
+      serializers.each { |serializer| output = serializer.call(object, output, options) }
+      output
+    end
+
+    private
+
+    # The array of chained serializers.
+    # @return [Array<Serializer, #call>]
+    attr_reader :serializers
+  end
+end

data/lib/porridge/error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Porridge
+  # {Error} is the base class for all porridge-related errors. You may thus catch {Error} to catch all porridge-specific
+  # errors.
+  class Error < StandardError
+  end
+end

data/lib/porridge/extractor.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Porridge
+  # {Extractor} is the nominal base class for all porridge value extractors.
+  #
+  # A (value) extractor is an object that is capable of retrieving a value from an object, given a set of "options",
+  # which may be application-specific. You are encouraged, but not required, to have your extractors derive from this
+  # class. Currently, any object that implements a +#call+ method is a valid extractor.
+  class Extractor
+    # Determines whether the given object is a valid porridge extractor. Currently, any object that responds to the
+    # +#call+ method is valid.
+    # @param object the object to check.
+    # @return [Boolean] +true+ if the object is a valid extractor; +false+ otherwise.
+    def self.valid?(object)
+      object.respond_to? :call
+    end
+
+    # Ensures that all the provided objects are valid extractors, raising {InvalidExtractorError} if not.
+    # @param objects [Array] the splatted array of objects to validate.
+    # @return [Boolean] +true+ if all the objects were valid; raises an error otherwise.
+    # @raise [InvalidExtractorError] if any of the provided objects are not valid extractors.
+    def self.ensure_valid!(*objects)
+      objects.each { |object| raise InvalidExtractorError unless valid?(object) }
+      true
+    end
+
+    # Should extract a value from the given object with the given options. Subclasses should override this method.
+    # @param object the object from which to retrieve the value.
+    # @param options [Hash] a hash of "options," which may be application-specific.
+    # @return the extracted value.
+    def call(object, options); end
+  end
+end

data/lib/porridge/factory.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Porridge
+  # {Factory} is a class that is capable of instantiating various porridge serializers and extractors. All extractor-
+  # creation methods are suffixed with +_extractor+, all serializer-creation methods are suffixed with +_serializer+,
+  # and all field serializer-creation methods are suffixed with +_field_serializer+.
+  #
+  # You may subclass this class if you wish to change its behavior. For example, if you wished to substitute your
+  # own "from name" extractor, that accesses a hash value rather than sends a method call, for the default one:
+  #
+  #   class CustomPorridgeFactory < Porridge::Factory
+  #     def from_name_extractor(name)
+  #       extractor HashValueExtractor.new(name)
+  #     end
+  #   end
+  #
+  # {#from_name_field_serializer}, {#attribute_extractor}, and {#attribute_field_serializer} would then be automatically
+  # updated in the process, along with any other methods that depend on the aforementioned ones.
+  #
+  # This method is rarely used directly. Typically, it is used in conjunction with a {SerializerDefiner} and/or
+  # {SerializerDefinition} instance.
+  class Factory
+    def extractor(base)
+      return nil if base.nil?
+
+      Extractor.ensure_valid!(base)
+      base
+    end
+
+    def from_name_extractor(name)
+      extractor SendExtractor.new(name)
+    end
+
+    def custom_extractor(callback)
+      extractor callback
+    end
+
+    def association_extractor(serializer:, extractor: nil, extraction_name: nil, callback: nil, &block)
+      extractor SerializingExtractor.new(
+        extractor || custom_extractor(callback) || custom_extractor(block) || from_name_extractor(extraction_name),
+        serializer
+      )
+    end
+    alias belongs_to_extractor association_extractor
+    alias has_many_extractor association_extractor
+
+    def serializer(base)
+      return nil if base.nil?
+
+      Serializer.ensure_valid!(base)
+      base
+    end
+
+    def chain_serializer(*bases)
+      serializer ChainSerializer.new(*bases)
+    end
+    alias serializers chain_serializer
+
+    def for_extracted_serializer(serializer, extractor)
+      serializer SerializerForExtracted.new(serializer, extractor)
+    end
+    alias serializer_for_extracted for_extracted_serializer
+
+    def field_serializer(name, extractor)
+      serializer FieldSerializer.new(name, extractor)
+    end
+
+    def attribute_field_serializer(name, callback = nil, extraction_name: nil, &block)
+      extractor = custom_extractor(callback || block) || from_name_extractor(extraction_name || name)
+      field_serializer(name, extractor)
+    end
+
+    def association_field_serializer(name, options = {}, &block)
+      options[:extraction_name] ||= name
+      field_serializer(name, association_extractor(**options, &block))
+    end
+    alias belongs_to_field_serializer association_field_serializer
+    alias has_many_field_serializer association_field_serializer
+  end
+end

data/lib/porridge/field_policy.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Porridge
+  # {FieldPolicy} is the nominal base class for all field policy classes.
+  #
+  # A field policy is an object that is capable of determining whether a certain "field" is allowed in a given
+  # context. Currently, it is primarily used in {FieldSerializer} as the default method of determining whether a field
+  # is valid. You are encouraged, but not required, to have your own custom field policies derive from this class.
+  # Currently, any object that implements the +#allowed?+ method is a valid field policy.
+  class FieldPolicy
+    # Determines whether the given object is a valid porridge field policy. Currently, any object that responds to the
+    # +#allowed?+ method is valid.
+    # @param object the object to check.
+    # @return [Boolean] +true+ if the object is a valid field policy; +false+ otherwise.
+    def self.valid?(object)
+      object.respond_to? :allowed?
+    end
+
+    # Ensures that all the provided objects are valid field policies, raising {InvalidFieldPolicyError} if not.
+    # @param objects [Array] the splatted array of objects to validate.
+    # @return [Boolean] +true+ if all the objects were valid; raises an error otherwise.
+    # @raise [InvalidFieldPolicyError] if any of the provided objects are not valid field policies.
+    def self.ensure_valid!(*objects)
+      objects.each { |object| raise InvalidFieldPolicyError unless valid?(object) }
+      true
+    end
+
+    # Determiners whether the field with the given name for the given object with the given options is currently
+    # allowed.
+    # @param _name the name of the field being validated.
+    # @param _object the object for which the field being validated is being generated.
+    # @param _options [Hash] the options with which the field being validated is being generated.
+    # @return [Boolean] +true+ if the indicated field is allowed; +false+ otherwise.
+    def allowed?(_name, _object, _options)
+      true
+    end
+  end
+end

data/lib/porridge/field_serializer.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Porridge
+  # {FieldSerializer} is a serializer that adds a "field" to a hash. It does so by using a predefined "field name" as
+  # the key and evaluates an {Extractor} for the object for the value.
+  #
+  # {FieldSerializer} is the most opinionated piece of the porridge framework. In particular, it adds to a
+  # +:field_hierarchy+ array in the options hash to keep track of nested fields. It also requires the use of a
+  # {FieldPolicy} object given in the options to determine whether a given field is allowed. Do not be afraid to
+  # subclass {FieldSerializer} or even create a new "field serializer" class altogether if you want to substantially
+  # change the way fields are implemented.
+  class FieldSerializer < Serializer
+    # Creates a new instance of {FieldSerializer} with the given field name and value extractor.
+    # @param name the name of the field; will be used as the key for the field in the hash.
+    # @param extractor [Extractor, #call] the value extractor to use to retrieve a value from the object, which will be
+    #   used as the value for the field in the hash.
+    # @raise [InvalidExtractorError] if the provided extractor is not a valid extractor.
+    def initialize(name, extractor)
+      @name = name
+      @extractor = extractor
+      Extractor.ensure_valid!(extractor)
+      super()
+    end
+
+    # Serializes the given input hash for the given object with the given options by adding an element to the hash with
+    # a key that is equal to the field name ({#name}) and a value extracted from the object using the field extractor
+    # ({#extractor}).
+    # @param object the object for which to transform the input. The field value will be retrieved from this object
+    #   using the extractor.
+    # @param hash [Hash] the input hash being transformed. A key-value pair will be added for the field.
+    # @param options [Hash] a hash of "options," which may be application specific.
+    # @option options [FieldPolicy, #allowed?] :field_policy the field policy to use to determine whether the field
+    #   is currently allowed. This option *must* be provided.
+    # @return [Hash] the transformed hash.
+    # @raise [InvalidFieldPolicyError] if no field policy was provided or if the field policy was not a valid field
+    #   policy object.
+    def call(object, hash, options)
+      if allowed?(object, options)
+        options = options.dup
+        add_field_to_hierarchy!(options)
+        hash_with_field(object, hash, options)
+      else
+        hash
+      end
+    end
+
+    private
+
+    # Determines whether the given object/options, along with the current {#name} constitutes a valid field. Currently,
+    # this is done by simply delegating to the field policy which should have been provided as an option.
+    # @param object the object for which the field being validated is being implemented.
+    # @param options [Hash] the options for which the field being validated is being implemented.
+    # @return [Boolean] +true+ if the indicated field is valid; +false+ otherwise.
+    # @raise [InvalidFieldPolicyError] if no field policy was provided or if the field policy was not a valid field
+    #   policy object.
+    def allowed?(object, options)
+      FieldPolicy.ensure_valid!(options[:field_policy])
+      options[:field_policy].allowed?(name, object, options.except(:field_policy))
+    end
+
+    # Safely adds the current {#name} to the +:field_hierarchy+ in the given options hash. While the options hash itself
+    # is mutated, the field hierarchy array is first duplicated, meaning the options hash must have first been
+    # duplicated for this to be safe.
+    # @param options_hash [Hash] the options hash to which the field should be added.
+    # @return [void]
+    def add_field_to_hierarchy!(options_hash)
+      options_hash[:field_hierarchy] ||= []
+      options_hash[:field_hierarchy] = options_hash[:field_hierarchy].dup
+      options_hash[:field_hierarchy] << name
+    end
+
+    # Creates a new hash from the given one with a field for the given object injected.
+    # @param object the object for which to inject the field. Will be passed to the extractor.
+    # @param hash [Hash] the hash into which to inject the field.
+    # @param options [Hash] the options for which to inject the field. Will be passed to the extractor.
+    # @return [Hash] the transformed hash.
+    def hash_with_field(object, hash, options)
+      hash.merge(name => extractor.call(object, options))
+    end
+
+    # The name of the field being serialized by this {FieldSerializer}; used as the key for the field in the hash.
+    attr_reader :name
+
+    # The value extractor to use to retrieve a value from the object for which serialization is occurring.
+    # @return [Extractor, #call]
+    attr_reader :extractor
+  end
+end

data/lib/porridge/invalid_extractor_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Porridge
+  # {InvalidExtractorError} is the error that is thrown when a non-extractor object is used like an extractor.
+  class InvalidExtractorError < Error; end
+end

data/lib/porridge/invalid_field_policy_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Porridge
+  # {InvalidFieldPolicyError} is the error that is thrown when a non-field-policy object is used like a field policy.
+  class InvalidFieldPolicyError < Error; end
+end

data/lib/porridge/invalid_serializer_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Porridge
+  # {InvalidSerializerError} is the error that is thrown when a non-serializer object is used like a serializer.
+  class InvalidSerializerError < Error; end
+end

data/lib/porridge/key_normalizing_serializer.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/core_ext/hash/keys'
+
+module Porridge
+  # {KeyNormalizingSerializer} is a serializer that wraps another serializer and recursively normalizes the keys of the
+  # resulting hash to either strings or symbols.
+  class KeyNormalizingSerializer < Serializer
+    # Creates a new instance of {KeyNormalizingSerializer} with the given base serializer and key type.
+    # @param base [Serializer, #call] the base serializer to wrap. Note that the output of the base serializer *must*
+    #   be a hash.
+    # @param key_type [Symbol] the type that the keys should be normalized to. Both +:string+ and +:symbol+ are
+    #   supported.
+    # @raise [InvalidSerializerError] if the given base serializer is not a valid serializer.
+    def initialize(base, key_type: :string)
+      Serializer.ensure_valid!(base)
+      @base = base
+      @key_type = key_type
+      super()
+    end
+
+    # Serializes the given input for the given object with the given options by delegating to the base serializer
+    # ({#base}) and recursively transforming the keys of the resulting hash to the appropriate type ({#key_type}).
+    # Note that the output of the base serializer *must* be a hash.
+    # @param object the object for which to transform the input.
+    # @param input the object being transformed, typically either a hash or an array.
+    # @param options [Hash] a hash of "options," which may be application specific.
+    # @return [Hash] the hash returned from the base serializer, normalized.
+    def call(object, input, options)
+      normalize_keys(base.call(object, input, options))
+    end
+
+    private
+
+    # Normalizes the keys of the given hash according to the {#key_type}. Uses ActiveSupport methods to accomplish this.
+    # @param hash [Hash] the hash to normalize.
+    # @return [Hash] the normalized hash.
+    def normalize_keys(hash)
+      key_type == :symbol ? hash.deep_symbolize_keys : hash.deep_stringify_keys
+    end
+
+    # The base serializer whose output hash will be normalized
+    # @return [Serializer, #call]
+    attr_reader :base
+
+    # The key type that the hash should be normalized to.
+    # @return [Symbol] either +:string+ or +:symbol+.
+    attr_reader :key_type
+  end
+end

data/lib/porridge/send_extractor.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Porridge
+  # {SendExtractor} is an extractor that retrieves a value from an object by simply calling a predefined method on it.
+  class SendExtractor < Extractor
+    # Creates a new instance of {SendExtractor} with the given method name.
+    # @param method_name [String, Symbol] the name of the method to call when extracting the value.
+    def initialize(method_name)
+      @method_name = method_name.to_s
+      super()
+    end
+
+    # Extracts the value from the given object by sending the method name ({#method_name}) to it.
+    # @param object the object from which to retrieve the value.
+    # @param _options [Hash] a hash of "options," which may be application-specific. These options are ignored.
+    # @return the extracted value, as returned from the sent method.
+    def call(object, _options)
+      object.respond_to?(method_name) ? object.send(method_name) : nil
+    end
+
+    private
+
+    # The name of the method to call when extracting the value.
+    # @return [String]
+    attr_reader :method_name
+  end
+end

data/lib/porridge/serializer.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Porridge
+  # {Serializer} is the nominal base class for all porridge serializers.
+  #
+  # A serializer is an object that arbitrarily transforms a given input for a given object with a given set of options.
+  # The input may be anything, but is typically either a hash or an array. In Rails applications, the object is often
+  # an ActiveRecord model. The options may be application-specific.
+  #
+  # Serializers are the heart and soul of the porridge gem and are typically layered with composition into a final
+  # serializer that is used to actually serialize an object into (typically) a hash or array. Thus, a serializer often
+  # simply wraps another serializer, transforming the object or options in some way.
+  #
+  # You are encouraged, but not required, to have all your serializers derive from this class. Currently, any object
+  # that implements the +#call+ method is a valid serializer.
+  class Serializer
+    # Determines whether the given object is a valid porridge serializer. Currently, any object that responds to the
+    # '#call' method is valid.
+    # @param object the object to check.
+    # @return [Boolean] +true+ if the object is a valid serializer; +false+ otherwise.
+    def self.valid?(object)
+      object.respond_to? :call
+    end
+
+    # Ensures that all the provided objects are valid serializers, raising {InvalidSerializerError} if not.
+    # @param objects [Array] the splatted array of objects to validate.
+    # @return [Boolean] +true+ if all the objects were valid; raises an error otherwise.
+    # @raise [InvalidSerializerError] if any of the provided objects are not valid serializers.
+    def self.ensure_valid!(*objects)
+      objects.each { |object| raise InvalidSerializerError unless valid?(object) }
+      true
+    end
+
+    # Should transforms the given input for the given object with the given options and return the desired output.
+    # @param _object the object for which to transform the input.
+    # @param input the object being transformed, typically either a hash or an array.
+    # @param _options [Hash] a hash of "options," which may be application specific.
+    # @return the transformed output, typically either a hash or an array.
+    def call(_object, input, _options)
+      input
+    end
+  end
+end

data/lib/porridge/serializer_definer.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Porridge
+  # {SerializerDefiner} is a class that wraps a {Factory} and allows serializes to be easily defined with an elegant
+  # DSL.
+  class SerializerDefiner
+    FACTORY_PREFIX = 'create_'
+    SERIALIZER_SUFFIX = '_serializer'
+    FIELD_SERIALIZER_SUFFIX = '_field_serializer'
+
+    delegate :call, to: :defined_serializer
+
+    def initialize(factory = Factory.new)
+      @factory = factory
+      @serializers = []
+    end
+
+    def method_missing(method_name, *args, &block)
+      method_name = method_name.to_s
+      return factory.send(method_name.delete_prefix(FACTORY_PREFIX), *args, &block) if create_method? method_name
+
+      if serializer_method? method_name
+        return add_serializer(factory.send(method_name + SERIALIZER_SUFFIX, *args, &block))
+      end
+
+      if field_serializer_method? method_name
+        return add_serializer(factory.send(method_name + FIELD_SERIALIZER_SUFFIX, *args, &block))
+      end
+
+      super(method_name.to_sym, *args, &block)
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      method_name = method_name.to_s
+      super(method_name.to_sym, include_private) ||
+        create_method?(method_name) ||
+        serializer_method?(method_name) ||
+        field_serializer_method?(method_name)
+    end
+
+    def defined_serializer
+      factory.serializers(*added_serializers)
+    end
+
+    def added_serializers
+      @serializers
+    end
+
+    def serializer(...)
+      add_serializer(factory.serializer(...))
+    end
+
+    private
+
+    def create_method?(method_name)
+      method_name.start_with?(FACTORY_PREFIX) && factory.respond_to?(method_name.delete_prefix(FACTORY_PREFIX))
+    end
+
+    def serializer_method?(method_name)
+      factory.respond_to?(method_name + SERIALIZER_SUFFIX)
+    end
+
+    def field_serializer_method?(method_name)
+      factory.respond_to?(method_name + FIELD_SERIALIZER_SUFFIX)
+    end
+
+    def add_serializer(serializer)
+      @serializers << serializer
+    end
+
+    attr_reader :factory
+  end
+end

data/lib/porridge/serializer_definition.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Porridge
+  # {SerializerDefinition} is a class that allows serializers to be defined as with a {SerializerDefiner}, but within
+  # a class. Simply subclass this class and use the same DSL within it.
+  class SerializerDefinition
+    class << self
+      attr_writer :definer
+
+      delegate_missing_to :definer
+
+      def inherited(subclass)
+        super
+        definer.added_serializers.each { |serializer| subclass.definer.serializer(serializer) }
+      end
+
+      def definer
+        @definer ||= create_definer
+      end
+
+      def create_definer
+        SerializerDefiner.new
+      end
+
+      def reset!
+        @definer = nil
+      end
+    end
+  end
+end

data/lib/porridge/serializer_for_extracted.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Porridge
+  # {SerializerForExtracted} is a serializer that wraps another serializer and passes it an object that is extracted
+  # from the initial object using an {Extractor}.
+  class SerializerForExtracted < Serializer
+    # Creates a new instance of {SerializerForExtracted} with the given base serializer and extractor.
+    # @param base [Serializer, #call] the base serializer to wrap.
+    # @param extractor [Extractor, #call] the extractor to use to extract a value from the object before passing it
+    #   to the base serializer.
+    # @raise [InvalidSerializerError] if the provided base serializer is not a valid serializer.
+    # @raise [InvalidExtractorError] if the provided extractor is not a valid extractor.
+    def initialize(base, extractor)
+      Serializer.ensure_valid!(base)
+      Extractor.ensure_valid!(extractor)
+      @base = base
+      @extractor = extractor
+      super()
+    end
+
+    # Serializes the given input for the given object with the given options by first extracted a value from the given
+    # object, then passing that value, along with the given input and options, to the base serializer ({#base}).
+    # @param object the object for which to transform the input. A value will be extracted and that value will be passed
+    #   to the base serializer.
+    # @param input the object being transformed, typically either a hash or an array.
+    # @param options [Hash] a hash of "options," which may be application specific.
+    # @return the transformed output, typically either a hash or an array, as returned from the base serializer.
+    def call(object, input, options)
+      extracted_value = extractor.call(object, options)
+      base.call(extracted_value, input, options)
+    end
+
+    private
+
+    # The base serializer to wrap.
+    # @return [Serializer, #call]
+    attr_reader :base
+
+    # The extractor to use to extract a value from the object before passing it to the base serializer.
+    # @return [Extractor, #call]
+    attr_reader :extractor
+  end
+end

data/lib/porridge/serializer_with_root.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/core_ext/string/inflections'
+
+module Porridge
+  # {SerializerWithRoot} is a serializer that wraps another serializer and adds a "root key" to the resulting hash.
+  class SerializerWithRoot < Serializer
+    # Creates a new instance of {SerializerWithRoot} with the given base serializer and, optionally, root key.
+    # @param base [Serializer, #call] the base serializer to wrap.
+    # @param root_key the "root" key to inject into the resulting hash. If +nil+, which is the default, the root key
+    #   will be inferred from the object.
+    # @raise [InvalidSerializerError] if the provided base serializer is not a valid serializer.
+    def initialize(base, root_key: nil)
+      Serializer.ensure_valid!(base)
+      @base = base
+      @root_key = root_key
+      super()
+    end
+
+    # Serializes the given input for the given object with the given options by delegating to the base serializer
+    # ({#base}) and adding a root key to the resulting hash. Note that the output of the base serializer *must* be a
+    # hash.
+    #
+    # If the root key was not set manually, it will be inferred from the "underscored" class name of the object. If the
+    # object is an array (according to {#array?}), then the class name will be derived from the first object in the
+    # array, and will be pluralized. Be aware that retrieving the first element of the "array" may cause an SQL query to
+    # be performed if the "array" is a Rails relation.
+    #
+    # Note that an inferred root key is always a string. You may wish to use a {KeyNormalizingSerializer} if symbol
+    # keys are desired.
+    #
+    # @param object the object for which to transform the input. If no root key was set manually, it will be inferred
+    #   from the object's class.
+    # @param input the object being transformed, typically either a hash or an array.
+    # @param options [Hash] a hash of "options," which may be application specific.
+    # @return [Hash] the hash returned from the base serializer, injected with a root key.
+    def call(object, input, options)
+      { evaluate_root_key(object) => base.call(object, input, options) }
+    end
+
+    protected
+
+    # Determines whether the given object functions like an array for the purposes of this {SerializerWithRoot}. The
+    # default implementation checks to see whether the object implements both +#map+ and +#first+. You may override the
+    # default behavior by overriding this method. Note that if you override {ArraySerializer#like_array?} you will
+    # likely wish to override this method as well.
+    # @param object the object to check.
+    # @return [Boolean] +true+ if the given object is like an array; +false+ otherwise.
+    def array?(object)
+      object.respond_to?(:map) && object.respond_to?(:first)
+    end
+
+    private
+
+    # Gets a root key for the given object by either returning {#root_key}, or returning a singular/plural version
+    # of the {#base_root_key}, depending on whether the object is an array.
+    # @param object the object for which to get a root key.
+    # @return the resolved string root key.
+    def evaluate_root_key(object)
+      return root_key if root_key
+
+      array?(object) ? base_root_key(object).pluralize : base_root_key(object).singularize
+    end
+
+    # Gets the inferred base root key, without singularization or pluralization for the given object.
+    # @param object the object for which to get the base root key.
+    # @return [String] the resolved base root key.
+    def base_root_key(object)
+      representative_sample(object).class.name.underscore.to_s
+    end
+
+    # Gets a "representative" sample from the given object. In practice, this means either returning the object itself,
+    # or, if the object is an array-like structure, returning the first element.
+    def representative_sample(object)
+      array?(object) ? object.first : object
+    end
+
+    # The base serializer to wrap.
+    # @return [Serializer, #call]
+    attr_reader :base
+
+    # The explicit root key; if +nil+, will be inferred.
+    attr_reader :root_key
+  end
+end

data/lib/porridge/serializing_extractor.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Porridge
+  # {SerializingExtractor} is an extractor that wraps another extractor and serializes for its output using a provided
+  # serializer. Note that {SerializingExtractor} passes the output of the base extractor as the *object* for the
+  # serializer, not the input.
+  class SerializingExtractor < Extractor
+    # Creates a new instance of {SerializingExtractor} with the given base extractor and serializer.
+    # @param base [Extractor, #call] the extractor to wrap, whose output will be serialized for before being returned.
+    # @param serializer [Serializer, #call] the serializer to use to transform the output of the extractor.
+    # @raise [InvalidExtractorError] if the provided base extractor was not a valid extractor.
+    # @raise [InvalidSerializerError] if the provided serializer was not a valid serializer.
+    def initialize(base, serializer)
+      Extractor.ensure_valid!(base)
+      Serializer.ensure_valid!(serializer)
+      @base = base
+      @serializer = serializer
+      super()
+    end
+
+    # Extracts a value from the given object for the given options by:
+    #   1. Using the base extractor ({#extractor}) to extract a value from the object with the given options; and
+    #   2. Passing that value as the object to {#serializer#call}. A blank hash is given as the input, and the
+    #      given options are passed along.
+    # @param object the object from which to retrieve the value.
+    # @param options [Hash] a hash of "options," which may be application-specific.
+    # @return the extracted value.
+    def call(object, options)
+      serializer.call(base.call(object, options), {}, options)
+    end
+
+    private
+
+    # The base extractor.
+    # @return [Extractor, #call]
+    attr_reader :base
+
+    # The serializer to use to serialize for the output of the base extractor.
+    # @return [Serializer, #call]
+    attr_reader :serializer
+  end
+end

data/lib/porridge/version.rb

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

data/lib/porridge/whitelist_field_policy.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Porridge
+  # {WhitelistFieldPolicy} is a field policy that uses a nested whitelist of field names to determine which fields are
+  # valid.
+  class WhitelistFieldPolicy < FieldPolicy
+    # Creates a new instance of {WhitelistFieldPolicy} with the given whitelist.
+    # @param whitelist [Hash] the nested whitelist hash of allowed field names.
+    def initialize(whitelist)
+      @whitelist = whitelist
+      super()
+    end
+
+    # Determiners whether the field with the given name with the given options is currently allowed by checking the
+    # field hierarchy, which must be contained in +options[:field_hierarchy] against the whitelist.
+    # @param name the name of the field being validated.
+    # @param _object the object for which the field being validated is being generated.
+    # @param options [Hash] the options with which the field being validated is being generated.
+    # @return [Boolean] +true+ if the indicated field is allowed; +false+ otherwise.
+    def allowed?(name, _object, options)
+      field_hierarchy = options[:field_hierarchy] || []
+      _allowed?([*field_hierarchy, name], whitelist)
+    end
+
+    protected
+
+    # Determines whether the given object functions as a hash for the purposes of this {WhitelistFieldPolicy} instance.
+    # You may override this method if desired, but hashes must at least respond to +#[]+.
+    # @param input the input object to check.
+    # @return [Boolean] +true+ if the given object is like a hash; +false+ otherwise.
+    def hash?(input)
+      input.is_a? Hash
+    end
+
+    private
+
+    # @overload _allowed?(field_hierarchy, whitelist)
+    #   Recursively traverses the given field hierarchy and determines whether the field indicated by the hierarchy is
+    #   allowed for the given whitelist.
+    #   @param field_hierarchy [Array] the field hierarchy to validate.
+    #   @param whitelist [Hash] the nested whitelist hash of field names.
+    # @overload _allowed?(field_hierarchy, whitelist, level)
+    #   Recursively traverses the given field hierarchy and determines whether the field indicated by the hierarchy is
+    #   allowed for the given whitelist, starting from the specified level.
+    #   @param field_hierarchy [Array] the field hierarchy to validate.
+    #   @param whitelist [Hash] the nested whitelist hash of field names.
+    #   @param level [Integer] the current level of the hierarchy being checked.
+    def _allowed?(field_hierarchy, whitelist, level = 0)
+      # If the level is equal to the field hierarchy length, then we've reached the end. Immediately return the
+      # truthiness of whitelist, which is now equal to the final resolved value referenced by the field hierarchy.
+      return !!whitelist if level >= field_hierarchy.count
+
+      # If the current whitelist is not a hash, then the field hierarchy is deeper than the whitelist.
+      # As an example, take this whitelist:
+      #   { users: true }
+      # And this field hierarchy:
+      #   [:user, :id]
+      # One interpretation of this is that since 'users' is true, all fields should be allowed. We take the opposite
+      # approach and say that no attributes have been explicitly defined.
+      # Therefore immediately return false.
+      return false unless hash?(whitelist)
+
+      _allowed?(field_hierarchy, whitelist[field_hierarchy[level]], level + 1)
+    end
+
+    # The nested whitelist hash of field names.
+    # @return [Hash]
+    attr_reader :whitelist
+  end
+end

data/lib/porridge.rb

@@ -1,8 +1,25 @@
 # frozen_string_literal: true
 
 require_relative 'porridge/version'
+require_relative 'porridge/extractor'
+require_relative 'porridge/send_extractor'
+require_relative 'porridge/serializer'
+require_relative 'porridge/chain_serializer'
+require_relative 'porridge/array_serializer'
+require_relative 'porridge/key_normalizing_serializer'
+require_relative 'porridge/serializer_for_extracted'
+require_relative 'porridge/serializer_with_root'
+require_relative 'porridge/error'
+require_relative 'porridge/invalid_serializer_error'
+require_relative 'porridge/invalid_extractor_error'
+require_relative 'porridge/invalid_field_policy_error'
+require_relative 'porridge/field_policy'
+require_relative 'porridge/field_serializer'
+require_relative 'porridge/serializing_extractor'
+require_relative 'porridge/whitelist_field_policy'
+require_relative 'porridge/factory'
+require_relative 'porridge/serializer_definer'
+require_relative 'porridge/serializer_definition'
 
-module Porridge
-  class Error < StandardError; end
-  # Your code goes here...
-end
+# {Porridge} is the root namespace for all classes in the +porridge+ gem.
+module Porridge; end

data/porridge.gemspec

@@ -42,6 +42,8 @@ Gem::Specification.new do |spec|
   # Uncomment to register a new dependency of your gem
   # spec.add_dependency "example-gem", "~> 1.0"
 
+  spec.add_dependency 'activesupport', '~> 5.0'
+
   # For more information and examples about making a new gem, checkout our
   # guide at: https://bundler.io/guides/creating_gem.html
   spec.metadata['rubygems_mfa_required'] = 'true'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: porridge
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Jacob
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-01-16 00:00:00.000000000 Z
+date: 2022-01-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: byebug
@@ -108,6 +108,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.21'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
 description: |
   `porridge` is a plain Ruby gem that takes a flexible, object-oriented approach to serialization. `porridge`
   transforms objects into ruby hashes and arrays, which can then be serialized with other libraries.
@@ -120,12 +134,15 @@ files:
 - ".github/workflows/build.yml"
 - ".gitignore"
 - ".idea/.gitignore"
+- ".idea/fileTemplates/includes/Ruby File Header.rb"
+- ".idea/fileTemplates/internal/RSpec.rb"
 - ".idea/misc.xml"
 - ".idea/modules.xml"
 - ".idea/porridge.iml"
 - ".idea/vcs.xml"
 - ".rspec"
 - ".rubocop.yml"
+- ".yardopts"
 - CHANGELOG.md
 - Gemfile
 - Gemfile.lock
@@ -135,7 +152,26 @@ files:
 - bin/console
 - bin/setup
 - lib/porridge.rb
+- lib/porridge/array_serializer.rb
+- lib/porridge/chain_serializer.rb
+- lib/porridge/error.rb
+- lib/porridge/extractor.rb
+- lib/porridge/factory.rb
+- lib/porridge/field_policy.rb
+- lib/porridge/field_serializer.rb
+- lib/porridge/invalid_extractor_error.rb
+- lib/porridge/invalid_field_policy_error.rb
+- lib/porridge/invalid_serializer_error.rb
+- lib/porridge/key_normalizing_serializer.rb
+- lib/porridge/send_extractor.rb
+- lib/porridge/serializer.rb
+- lib/porridge/serializer_definer.rb
+- lib/porridge/serializer_definition.rb
+- lib/porridge/serializer_for_extracted.rb
+- lib/porridge/serializer_with_root.rb
+- lib/porridge/serializing_extractor.rb
 - lib/porridge/version.rb
+- lib/porridge/whitelist_field_policy.rb
 - porridge.gemspec
 homepage: https://github.com/jacoblockard99/porridge
 licenses: