cinnamon_serial 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 82d270da4eb17b6f19b8bc07991f497001b624ff
+  data.tar.gz: e6066491403152ead4a08d7523c9a867cfb5de82
+SHA512:
+  metadata.gz: 9f23a5d532c75e3dc676a947fb27abd1497601f269376a5c65a775cb9128edecad6ae803f28e2bb617a39e33fedb51da8ae7d6366674c9e359a465661d37639c
+  data.tar.gz: 1cf6043f141a31c2021ee2168bcb032f57990ce44e05a5bd9be9935afc34a1e72eb548bee619c8c344cd87c4062579e0c68243dfe277bf84ddaaa19b4525672e

data/.editorconfig

@@ -0,0 +1,8 @@
+# See http://editorconfig.org/
+
+[*]
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+end_of_line = lf

data/.gitignore

@@ -0,0 +1,2 @@
+.DS_Store
+*.gem

data/.rubocop.yml

@@ -0,0 +1,7 @@
+inherit_from: .rubocop_todo.yml
+
+Metrics/LineLength:
+  Max: 100
+
+Metrics/MethodLength:
+  Max: 20

data/.rubocop_todo.yml

@@ -0,0 +1,56 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2018-10-03 13:08:39 -0500 using RuboCop version 0.59.2.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 2
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: empty_lines, empty_lines_except_namespace, empty_lines_special, no_empty_lines, beginning_only, ending_only
+Layout/EmptyLinesAroundClassBody:
+  Exclude:
+    - 'spec/examples.rb'
+
+# Offense count: 4
+Lint/BooleanSymbol:
+  Exclude:
+    - 'lib/cinnamon_serial/resolver.rb'
+    - 'spec/examples.rb'
+
+# Offense count: 4
+Metrics/AbcSize:
+  Max: 26
+
+# Offense count: 2
+# Configuration parameters: CountComments, ExcludedMethods.
+# ExcludedMethods: refine
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/base_spec.rb'
+    - 'spec/dsl_spec.rb'
+
+# Offense count: 1
+# Configuration parameters: CountComments.
+Metrics/ClassLength:
+  Max: 111
+
+# Offense count: 2
+Metrics/CyclomaticComplexity:
+  Max: 15
+
+# Offense count: 1
+# Configuration parameters: CountKeywordArgs.
+Metrics/ParameterLists:
+  Max: 8
+
+# Offense count: 1
+Metrics/PerceivedComplexity:
+  Max: 16
+
+# Offense count: 1
+Style/DoubleNegation:
+  Exclude:
+    - 'lib/cinnamon_serial/formatting.rb'

data/.ruby-version

@@ -0,0 +1 @@
+2.3.7

data/.travis.yml

@@ -0,0 +1,8 @@
+language: ruby
+rvm:
+  - 2.3.1
+  - 2.3.7
+cache: bundler
+script:
+  - bundle exec rubocop
+  - bundle exec rspec

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,56 @@
+PATH
+  remote: .
+  specs:
+    cinnamon_serial (1.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.0)
+    coderay (1.1.2)
+    diff-lcs (1.3)
+    jaro_winkler (1.5.1)
+    method_source (0.9.0)
+    parallel (1.12.1)
+    parser (2.5.1.2)
+      ast (~> 2.4.0)
+    powerpack (0.1.2)
+    pry (0.11.3)
+      coderay (~> 1.1.0)
+      method_source (~> 0.9.0)
+    rainbow (3.0.0)
+    rspec (3.8.0)
+      rspec-core (~> 3.8.0)
+      rspec-expectations (~> 3.8.0)
+      rspec-mocks (~> 3.8.0)
+    rspec-core (3.8.0)
+      rspec-support (~> 3.8.0)
+    rspec-expectations (3.8.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-mocks (3.8.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-support (3.8.0)
+    rubocop (0.59.2)
+      jaro_winkler (~> 1.5.1)
+      parallel (~> 1.10)
+      parser (>= 2.5, != 2.5.1.1)
+      powerpack (~> 0.1)
+      rainbow (>= 2.2.2, < 4.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (~> 1.0, >= 1.0.1)
+    ruby-progressbar (1.10.0)
+    unicode-display_width (1.4.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  cinnamon_serial!
+  pry
+  rspec
+  rubocop (~> 0.59.2)
+
+BUNDLED WITH
+   1.16.3

data/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2018 Blue Marble Payroll, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,212 @@
+# Cinnamon Serial
+
+[![Build Status](https://travis-ci.org/bluemarblepayroll/cinnamon_serial.svg?branch=master)](https://travis-ci.org/bluemarblepayroll/cinnamon_serial)
+
+A common issue is that we typically want different data going
+outbound than what we have available server-side.  Some example motivations could be:
+
+* I have too much data, I want to slim down the outbound request.
+* I do not have enough data, I need to get more and send that as well.
+* I do not want to expose some data due to security/authorization concerns.
+
+Having a separate layer that specializes in this type of materialization is important no matter
+what the reasons are.  This library provides a simple domain-specific language that makes creating
+serializers or serialization layers declarative and easy.
+
+## Installation
+
+To install through Rubygems:
+
+````
+gem install install cinnamon_serial
+````
+
+You can also add this to your Gemfile:
+
+````
+bundle add cinnamon_serial
+````
+
+## Examples
+
+### Getting Started
+
+Consider the following class:
+
+```
+class Employee
+  attr_accessor :id, :first_name, :last_name, :active, :account, :progress, :start_date
+end
+```
+
+We could create a simple 1:1 serializer like so:
+
+```
+class EmployeeSerializer < CinnamonSerial::Base
+  serialize :id, :first_name, :last_name, :active, :account, :progress, :start_date
+end
+```
+
+To use this serializer:
+
+```
+employee = Employee.new
+# populate employee data...
+serializer = EmployeeSerializer.new(employee)
+data = serializer.as_json
+```
+
+The 'data' variable above is now a hash with only data as specified by the serializer.
+
+### Dynamic Attributes
+
+Serialized keys do not have to match the composed object.  Using our examples above we could
+create another serializer:
+
+```
+class EmployeeListSerializer < CinnamonSerial::Base
+  serialize :id
+  serialize :proper_name, to: :last_name
+end
+```
+
+In this case the serialized data will contain a key 'proper_name' instead of 'last_name'.
+
+### Calling Methods
+
+serialized keys are not limited to just attributes, in fact, it will just test the model to see if the
+composed object responds to the key and if it does it will send to the object.  For example:
+
+```
+class FormalEmployee < Employee
+  def proper_name
+  "#{last_name}, #{first_name}"
+  end
+end
+```
+
+```
+class EmployeeListSerializer < CinnamonSerial::Base
+  serialize :id, :proper_name
+end
+```
+
+### Value Aliasing
+
+Note: Internationalization is an incredibly complex problem that this library will not try to solve but it does provide the ability to override resolved values.  In the future the aliasing and formatting abilities should be extracted and plugged-in as to provide internationalization support.
+
+You are allowed to override the value if a value has been resolved to one of the following:
+
+1. true
+2. false
+3. nil
+4. 'present'
+5. 'blank'
+
+Say you want to show Yes/No/Unknown for a boolean value.  Building on our previous Employee examples we could modify our EmployeeSerializer:
+
+```
+class EmployeeSerializer < CinnamonSerial::Base
+  serialize :id, :first_name, :last_name
+  serialize :active, true_alias: 'Yes', false_alias: 'No', null: 'Unknown'
+end
+```
+
+Now the value of active will be 'Yes', 'No', or 'Unknown' instead of true, false, or null.
+
+### Value Formatting
+
+Two basic formatters that come included with this library are:
+
+1. Masking (defaults to masking all but last 4 characters with character X)
+2. Percent Formatting (two decimal places)
+
+An example of custom formatters would be:
+
+```
+class EmployeeSerializer < CinnamonSerial::Base
+  serialize :id, :first_name, :last_name
+  serialize :account, mask: true
+  serialize :progress, percent: true
+end
+```
+
+Account will be formatted as a masked string and progress will be converted to a percent formatted string.
+
+### Custom Methods
+
+There are two ways to specify to execute a method on the serializer:
+
+1. Method - call an instance method with no arguments.
+2. Transform - Resolve the value first then pass it into an instance method.
+
+For example:
+
+```
+class EmployeeSerializer < CinnamonSerial::Base
+  serialize :id, :first_name, :last_name, :start_date
+  serialize :renewal_date,  for: :start_date, transform: true
+  serialize :user_id, method: true
+
+  private
+
+  def renewal_date(date)
+    # Two years out
+    date + (60 * 60 * 24 * 24)
+  end
+
+  def user_id
+    dig_opt(:user, :id)
+  end
+end
+```
+
+Some notes about the above example:
+
+* You can either pass in true (it will call the method named as the key) or the explicit name of the method.
+* dig_opt is a convenience method that will call dig on the serializer options (second argument in serializer constructor.)
+
+### Custom Code
+
+In you need full control over serialization you can create hydrate blocks of code that will execute (in order of declaration.)  For example:
+
+```
+class EmployeeSerializer < CinnamonSerial::Base
+  serialize :id, :first_name, :last_name, :start_date
+  serialize :active, manual: true
+
+  hydrate do
+    set_active(obj.start_date >= Date.today)
+  end
+end
+```
+
+some notes about the above example:
+
+* setting manual to true declares that no mapping should be automatically performed.  Instead, you must set it within the hydrate block.
+* set_* are magic methods that will set the value to the value passed in.  In this context we will set the 'active' value to true if the start_date is either today or earlier than today.
+* obj is the composed object (in this context it would be the Employee instance.)  You are allowed to access it using the obj getter.  In the same vain, you are also allowed to access the serializer options using 'opts' getter.
+
+## Contributing
+
+### Development Environment Configuration
+
+Basic steps to take to get this repository compiling:
+
+1. Install [Ruby](https://www.ruby-lang.org/en/documentation/installation/) (check cinnamon_serial.gemspec for versions supported)
+2. Install bundler (gem install bundler)
+3. Clone the repository (git clone git@github.com:bluemarblepayroll/cinnamon_serial.git)
+4. Navigate to the root folder (cd cinnamon_serial)
+5. Install dependencies (bundle)
+
+### Running Tests
+
+To execute the test suite run:
+
+````
+rspec
+````
+
+## License
+
+This project is MIT Licensed.

data/cinnamon_serial.gemspec

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require './lib/cinnamon_serial/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'cinnamon_serial'
+  s.version     = CinnamonSerial::VERSION
+  s.summary     = 'Domain-specific language for serialization specification.'
+
+  s.description = <<-DESCRIPTION
+    Domain-specific language for serialization specification.
+  DESCRIPTION
+
+  s.authors     = ['Matthew Ruggio']
+  s.email       = ['mruggio@bluemarblepayroll.com']
+  s.files       = `git ls-files`.split("\n")
+  s.test_files  = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
+  s.homepage    = 'https://github.com/bluemarblepayroll/cinnamon_serial'
+  s.license     = 'MIT'
+
+  s.required_ruby_version = '>= 2.3.1'
+
+  s.add_development_dependency('pry')
+  s.add_development_dependency('rspec')
+  s.add_development_dependency('rubocop', '~> 0.59.2')
+end

data/lib/cinnamon_serial.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2018-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+require_relative 'cinnamon_serial/cinnamon_serial'

data/lib/cinnamon_serial/base.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2018-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module CinnamonSerial
+  # This is the main parent class that all serializers must inherit from.
+  class Base
+    extend Dsl
+
+    class << self
+      def map(enumerable, opts = {})
+        enumerable.map { |e| new(e, opts) }
+      end
+    end
+
+    attr_reader :data,
+                :obj,
+                :opts,
+                :klasses
+
+    def initialize(obj, opts = {}, klasses = Set.new)
+      @obj     = obj
+      @opts    = opts || {}
+      @klasses = klasses
+
+      materialize_data
+      execute_hydrate_blocks
+    end
+
+    def dig_opt(*keys)
+      opts.dig(*keys)
+    end
+
+    def as_json(_options = {})
+      data
+    end
+
+    def respond_to_missing?(method_sym)
+      data.key?(method_sym.to_s) || super
+    end
+
+    def method_missing(method_sym, *arguments, &block)
+      key = method_sym.to_s.sub('set_', '')
+
+      if data.key?(method_sym.to_s)
+        data[method_sym.to_s]
+      elsif data.key?(key)
+        @data[key] = arguments[0]
+      else
+        super
+      end
+    end
+
+    def [](attr)
+      send(attr)
+    end
+
+    private
+
+    def inherited_cinnamon_serial_specification
+      self.class.inherited_cinnamon_serial_specification
+    end
+
+    def materialize_data
+      @data = {}
+
+      inherited_cinnamon_serial_specification.attribute_map.each do |key, options|
+        @data[key.to_s] = options.resolve(self, key)
+      end
+
+      nil
+    end
+
+    def execute_hydrate_blocks
+      inherited_cinnamon_serial_specification.hydrate_blocks.each do |block|
+        if block && block.arity == 1
+          block.call(self)
+        elsif block
+          instance_eval(&block)
+        end
+      end
+
+      nil
+    end
+  end
+end

data/lib/cinnamon_serial/cinnamon_serial.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2018-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+require 'set'
+
+require_relative 'formatting'
+require_relative 'resolver'
+require_relative 'specification'
+require_relative 'dsl'
+require_relative 'base'

data/lib/cinnamon_serial/dsl.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2018-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module CinnamonSerial
+  # This module includes all the class-level methods used to specify serializers.
+  module Dsl
+    def cinnamon_serial_specification
+      @cinnamon_serial_specification ||= Specification.new
+    end
+
+    def serialize(*keys)
+      cinnamon_serial_specification.set(keys)
+
+      nil
+    end
+    # <b>DEPRECATED:</b> Please use <tt>serialize</tt> instead.
+    alias present serialize
+
+    def hydrate(&block)
+      cinnamon_serial_specification.hydrate(block)
+
+      nil
+    end
+
+    def inherited_cinnamon_serial_specification
+      return @inherited_cinnamon_serial_specification if @inherited_cinnamon_serial_specification
+
+      attribute_map  = {}
+      hydrate_blocks = []
+
+      # We need to reverse this so parents go first.
+      ancestors.reverse_each do |ancestor|
+        next unless ancestor.respond_to?(:cinnamon_serial_specification)
+
+        specification = ancestor.cinnamon_serial_specification
+
+        attribute_map.merge!(specification.attribute_map)
+        hydrate_blocks += specification.hydrate_blocks
+      end
+
+      @inherited_cinnamon_serial_specification = Specification.new(
+        attribute_map: attribute_map,
+        hydrate_blocks: hydrate_blocks
+      )
+    end
+  end
+end

data/lib/cinnamon_serial/formatting.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2018-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module CinnamonSerial
+  # Static utility methods for general use.
+  class Formatting
+    class << self
+      # Only show the last N positions in a string, replace the
+      # rest with the mask_with value.
+      # Example:
+      # - 123-45-6789 becomes: XXXXXXX6789
+      # - ABCDEFG     becomes: XXXDEFG
+      def mask(value, keep_last = 4, mask_with = 'X')
+        string_value = value.to_s
+        return string_value if blank?(string_value) || string_value.size <= keep_last
+
+        (mask_with.to_s * (string_value.size - keep_last)) + string_value[-keep_last..-1]
+      end
+
+      def percent(num)
+        present?(num) ? format('%.2f %', num) : ''
+      end
+
+      def present?(value)
+        !blank?(value)
+      end
+
+      def blank?(value)
+        if value.respond_to?(:blank?)
+          value.blank?
+        elsif value.respond_to?(:empty?)
+          !!value.empty?
+        else
+          !value
+        end
+      end
+    end
+  end
+end

data/lib/cinnamon_serial/resolver.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2018-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module CinnamonSerial
+  # Class that allows an engineer to specify what to do about mapping a key for a serializer.
+  class Resolver
+    attr_accessor :as,
+                  :blank,
+                  # <b>DEPRECATED:</b> Please use <tt>false_alias</tt> instead.
+                  :false,
+                  :false_alias,
+                  :for,
+                  :manual,
+                  :mask,
+                  :mask_char,
+                  :mask_len,
+                  :method,
+                  :null,
+                  :percent,
+                  :present,
+                  :through,
+                  :transform,
+                  # <b>DEPRECATED:</b> Please use <tt>true_alias</tt> instead.
+                  :true,
+                  :true_alias
+
+    def initialize(options = {})
+      @option_keys = options.keys.map(&:to_s).to_set
+
+      options.each do |key, value|
+        raise ArgumentError, "Illegal option: #{key}" unless respond_to?(key)
+
+        send("#{key}=", value)
+      end
+    end
+
+    def resolve(presenter, key)
+      raise ArgumentError, 'Presenter is required' unless presenter
+
+      return if manual
+
+      # Get the value
+      value = resolve_value(presenter, key)
+
+      # Transform the value
+      value = resolve_transform(presenter, key, value)
+      value = resolve_alias(value)
+      value = resolve_as(presenter, value)
+
+      # Format the value
+      value = resolve_percent(value)
+      resolve_mask(value)
+    end
+
+    private
+
+    # (method) and (for/through) are mutually exlusive use-cases.
+    # Example: you would never use for and method.
+    def resolve_value(presenter, key)
+      # If you pass in something that is not true boolean value then use that as a method name
+      # to call on the presenter.
+      return presenter.send(key)    if method.is_a?(TrueClass)
+      return presenter.send(method) if method.to_s.length.positive?
+
+      # User for/through
+      model_key = self.for || key
+      model = presenter.obj
+
+      Array(through).each do |association|
+        model = model.respond_to?(association) ? model.send(association) : nil
+
+        break unless model
+      end
+
+      model&.respond_to?(model_key) ? model.send(model_key) : nil
+    end
+
+    def resolve_transform(presenter, key, value)
+      return presenter.send(key, value)       if transform.is_a?(TrueClass)
+      return presenter.send(transform, value) if Formatting.present?(transform)
+
+      value
+    end
+
+    def resolve_alias(value)
+      if @option_keys.include?('true_alias') && value.is_a?(TrueClass)
+        true_alias
+      # <b>DEPRECATED:</b> Please use <tt>true_alias</tt> instead.
+      elsif @option_keys.include?('true') && value.is_a?(TrueClass)
+        self.true
+      elsif @option_keys.include?('false_alias') && value.is_a?(FalseClass)
+        false_alias
+      # <b>DEPRECATED:</b> Please use <tt>false_alias</tt> instead.
+      elsif @option_keys.include?('false') && value.is_a?(FalseClass)
+        self.false
+      elsif @option_keys.include?('null') && value.nil?
+        null
+      elsif @option_keys.include?('blank') && Formatting.blank?(value)
+        blank
+      elsif @option_keys.include?('present') && Formatting.present?(value)
+        present
+      else
+        value
+      end
+    end
+
+    def resolve_mask(value)
+      mask ? Formatting.mask(value, mask_len || 4, mask_char || 'X') : value
+    end
+
+    def resolve_percent(value)
+      percent ? Formatting.percent(value) : value
+    end
+
+    def resolve_as(presenter, value)
+      return value  unless as
+      return nil    unless value
+
+      class_constant = as_class_constant
+
+      # If we already serialized this type, lets not do it again.
+      # This will prevent endless cycles / loops.
+      return nil if presenter.klasses.include?(class_constant.to_s)
+
+      # We do not want to create a hard dependency on ActiveRecord/Rails in this gem,
+      # but we can still create a soft dependency in case it was included as a peer.
+      value = value.to_a if value.class.name == 'ActiveRecord::Relation'
+
+      new_klasses = presenter.klasses + Set[class_constant.to_s]
+
+      if value.is_a?(Array)
+        value.map { |v| class_constant.new(v, presenter.opts, new_klasses) }
+      else
+        class_constant.new(value, presenter.opts, new_klasses)
+      end
+    end
+
+    def as_class_name
+      return nil unless as
+
+      non_constant_types = %w[String Symbol]
+
+      # If we have a peer dependency for ActiveSupport then lets use it.
+      if non_constant_types.include?(as.class.name) && as.to_s.respond_to?(:classify)
+        as.to_s.classify
+      elsif non_constant_types.include?(as.class.name)
+        as.to_s
+      else
+        as
+      end
+    end
+
+    def as_class_constant
+      return nil unless as
+
+      class_name = as_class_name
+
+      # If we have a peer dependency for ActiveSupport then lets use it.
+      if class_name.is_a?(String) && class_name.respond_to?(:constantize)
+        class_name.constantize
+      elsif class_name.is_a?(String)
+        Object.const_get(class_name)
+      else
+        class_name
+      end
+    end
+  end
+end

data/lib/cinnamon_serial/specification.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2018-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module CinnamonSerial
+  # A Specification is a group of attribute mappings and custom code blocks to execute
+  # for a serializer.
+  class Specification
+    attr_reader :attribute_map, :hydrate_blocks
+
+    def initialize(attribute_map: {}, hydrate_blocks: [])
+      @attribute_map  = attribute_map
+      @hydrate_blocks = hydrate_blocks
+    end
+
+    def set(*keys)
+      keys = keys.flatten
+
+      # We have been sent options
+      options = Resolver.new(keys.last.is_a?(Hash) ? keys.pop : {})
+
+      raise ArgumentError, 'keys cannot be empty' if keys.empty?
+
+      keys.each { |key| @attribute_map[key.to_s] = options }
+
+      nil
+    end
+
+    def hydrate(block)
+      @hydrate_blocks << block
+
+      nil
+    end
+  end
+end

data/lib/cinnamon_serial/version.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2018-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module CinnamonSerial
+  VERSION = '1.0.0'
+end

data/spec/base_spec.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2018-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+require 'date'
+require 'pry'
+require './lib/cinnamon_serial'
+require './spec/examples'
+
+describe CinnamonSerial::Base do
+  let(:employee_list_keys) do
+    %w[
+      active
+      id
+      name
+      user_id
+      user_name
+      other_id
+      manager_name
+      renewal_date
+      notify_date
+      true_value
+      true_alias_value
+      false_value
+      false_alias_value
+      null
+      present
+      blank
+      manager
+      employees
+      account
+      progress
+    ]
+  end
+
+  let(:employee_keys) do
+    employee_list_keys + %w[
+      start_date
+      job
+      founder
+      owner
+    ]
+  end
+
+  let(:nick) do
+    Employee.new(
+      id: 2,
+      name: 'nick',
+      start_date: Date.new(1350, 12, 12),
+      job: 'electrician',
+      account: '1234567890',
+      progress: 55.5,
+      employees: [
+        Employee.new(
+          id: 1,
+          name: 'matt',
+          start_date:
+          Date.new(1750, 12, 12),
+          job: 'plumber',
+          account: '98765443322111',
+          progress: 10.98
+        )
+      ]
+    )
+  end
+
+  let(:matt) do
+    Employee.new(
+      id: 1,
+      name: 'matt',
+      start_date:
+      Date.new(1750, 12, 12),
+      job: 'plumber',
+      account: '98765443322111',
+      progress: 10.98,
+      manager: nick
+    )
+  end
+
+  let(:opts)                { { user: { id: 100, name: 'Frank Rizzo' }, active: true } }
+  let(:employee_serializer) { EmployeeSerializer.new(matt, opts) }
+  let(:data)                { employee_serializer.data }
+
+  it 'should materialize_data and execute hydrate blocks for superclass' do
+    expect(data['id']).to           eq(matt.id)
+    expect(data['name']).to         eq(matt.name)
+    expect(data['user_id']).to      eq(opts[:user][:id])
+    expect(data['user_name']).to    eq(opts[:user][:name])
+    expect(data['other_id']).to     eq(matt.id)
+    expect(data['manager_name']).to eq(nick.name)
+    expect(data['renewal_date']).to eq(matt.start_date + (60 * 60 * 24 * 24))
+    expect(data['notify_date']).to  eq(matt.start_date + (60 * 60 * 24 * 23))
+
+    expect(data['true_value']).to         eq('I am true.')
+    expect(data['true_alias_value']).to   eq('I am true alias.')
+    expect(data['false_value']).to        eq('I am false.')
+    expect(data['false_alias_value']).to  eq('I am false alias.')
+    expect(data['null']).to               eq('I am null.')
+    expect(data['present']).to            eq('I am present.')
+    expect(data['blank']).to              eq('I am blank.')
+    expect(data['manager']).to            be_a_kind_of(EmployeeSerializer)
+
+    expect(data['account']).to            eq('XXXXXXXXXX2111')
+    expect(data['progress']).to           eq('10.98 %')
+  end
+
+  it 'should materialize_data and execute hydrate blocks for subclass' do
+    expect(data['active']).to       eq(opts[:active])
+    expect(data['start_date']).to   eq(matt.start_date)
+    expect(data['job']).to          eq(matt.job)
+    expect(data['founder']).to      eq(matt.id < 10)
+    expect(data['owner']).to        eq(matt.id == 1)
+  end
+
+  it 'should not create cycles when flattening out presenters' do
+    expect(data['manager'].employees).to be nil
+  end
+end

data/spec/dsl_spec.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2018-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+require 'date'
+require 'pry'
+require './lib/cinnamon_serial'
+require './spec/examples'
+
+describe CinnamonSerial::Dsl do
+  let(:employee_list_keys) do
+    %w[
+      active
+      id
+      name
+      user_id
+      user_name
+      other_id
+      manager_name
+      renewal_date
+      notify_date
+      true_value
+      true_alias_value
+      false_value
+      false_alias_value
+      null
+      present
+      blank
+      manager
+      employees
+      account
+      progress
+    ]
+  end
+
+  let(:employee_keys) do
+    employee_list_keys + %w[
+      start_date
+      job
+      founder
+      owner
+    ]
+  end
+
+  it 'should include all attribute mappings' do
+    specification = EmployeeListSerializer.cinnamon_serial_specification
+    attribute_map = specification.attribute_map
+    keys = attribute_map.keys
+
+    expect(specification).to  be_a_kind_of(CinnamonSerial::Specification)
+    expect(keys.count).to     eq(employee_list_keys.count)
+    expect(keys).to           eq(employee_list_keys)
+  end
+
+  context 'with inheritance' do
+    it 'should include only its immediate attribute mappings' do
+      specification = EmployeeSerializer.cinnamon_serial_specification
+      attribute_map = specification.attribute_map
+      keys = attribute_map.keys
+
+      expect(specification).to  be_a_kind_of(CinnamonSerial::Specification)
+      expect(keys.count).to     eq(4)
+      expect(keys).to           eq(%w[start_date job founder owner])
+    end
+
+    it 'should include its immediate and ancestor attribute mappings' do
+      specification = EmployeeSerializer.inherited_cinnamon_serial_specification
+      attribute_map = specification.attribute_map
+      keys = attribute_map.keys
+
+      expect(specification).to  be_a_kind_of(CinnamonSerial::Specification)
+      expect(keys.count).to     eq(employee_keys.count)
+      expect(keys).to           eq(employee_keys)
+    end
+  end
+end

data/spec/examples.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2018-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+class Employee
+  attr_accessor :id,
+                :name,
+                :start_date,
+                :job,
+                :account,
+                :progress,
+                :manager,
+                :employees
+
+  def initialize(
+    id:,
+    name:,
+    start_date:,
+    job:,
+    account:,
+    progress:,
+    manager: nil,
+    employees: []
+  )
+    @id         = id
+    @name       = name
+    @start_date = start_date
+    @job        = job
+    @account    = account
+    @progress   = progress
+    @manager    = manager
+    @employees  = employees
+  end
+
+  def true_alias_value
+    true
+  end
+  alias true_value true_alias_value
+
+  def false_alias_value
+    false
+  end
+  alias false_value false_alias_value
+
+  def null
+    nil
+  end
+
+  def blank
+    ''
+  end
+
+  def present
+    'abc123.'
+  end
+end
+
+# ######################################################
+# A Class that exemplifies all possible mapping options.
+# ######################################################
+class EmployeeListSerializer < CinnamonSerial::Base
+  # Test skipping mapping using 'manual'
+  serialize :active, manual: true
+
+  # ################
+  # Value Resolution
+  # ################
+
+  # Test basic 1:1 mapping
+  serialize :id, :name
+
+  # Test presenter 'method'
+  serialize :user_id,   method: true
+  serialize :user_name, method: :formatted_user_name
+
+  # Test 'for'
+  serialize :other_id, for: :id
+
+  # Test 'for' and 'through'
+  serialize :manager_name, for: :name, through: :manager
+
+  # ################
+  # Value Aliasing
+  # ################
+
+  # Test presenter 'transform' method
+  serialize :renewal_date,  for: :start_date, transform: true
+  serialize :notify_date,   for: :start_date, transform: :notification_date
+
+  # Test 'true' alias
+
+  # <b>DEPRECATED:</b> Please use <tt>true_alias</tt> instead.
+  serialize :true_value,        true: 'I am true.'
+  serialize :true_alias_value,  true_alias: 'I am true alias.'
+
+  # Test 'false' alias
+
+  # <b>DEPRECATED:</b> Please use <tt>false_alias</tt> instead.
+  serialize :false_value,       false: 'I am false.'
+  serialize :false_alias_value, false_alias: 'I am false alias.'
+
+  # Test 'null' alias
+  serialize :null,              null: 'I am null.'
+
+  # Test 'present' alias
+  serialize :present,           present: 'I am present.'
+
+  # Test 'blank' alias
+  serialize :blank,             blank: 'I am blank.'
+
+  # Test 'as' conversion
+  serialize :manager,           as: 'EmployeeSerializer'
+  serialize :employees,         as: 'EmployeeSerializer'
+
+  # ################
+  # Value Formatting
+  # ################
+
+  serialize :account,           mask: true
+  serialize :progress,          percent: true
+
+  # #######################
+  # Manual Hydration Blocks
+  # #######################
+  hydrate do
+    set_active(dig_opt(:active))
+  end
+
+  # ##############
+  # Custom Methods
+  # ##############
+
+  private
+
+  def user_id
+    dig_opt(:user, :id)
+  end
+
+  def formatted_user_name
+    dig_opt(:user, :name)
+  end
+
+  def renewal_date(date)
+    # Two years out
+    date + (60 * 60 * 24 * 24)
+  end
+
+  def notification_date(date)
+    # 23 months out
+    date + (60 * 60 * 24 * 23)
+  end
+end
+
+# #############################
+# Subclass to test inheritance.
+# #############################
+class EmployeeSerializer < EmployeeListSerializer
+  present :start_date, :job
+
+  present :founder,
+          :owner, manual: true
+
+  hydrate do
+    set_founder(obj.id < 10)
+  end
+
+  hydrate do
+    set_owner(obj.id == 1)
+  end
+end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: cinnamon_serial
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Matthew Ruggio
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-10-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.59.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.59.2
+description: "    Domain-specific language for serialization specification.\n"
+email:
+- mruggio@bluemarblepayroll.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".editorconfig"
+- ".gitignore"
+- ".rubocop.yml"
+- ".rubocop_todo.yml"
+- ".ruby-version"
+- ".travis.yml"
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- cinnamon_serial.gemspec
+- lib/cinnamon_serial.rb
+- lib/cinnamon_serial/base.rb
+- lib/cinnamon_serial/cinnamon_serial.rb
+- lib/cinnamon_serial/dsl.rb
+- lib/cinnamon_serial/formatting.rb
+- lib/cinnamon_serial/resolver.rb
+- lib/cinnamon_serial/specification.rb
+- lib/cinnamon_serial/version.rb
+- spec/base_spec.rb
+- spec/dsl_spec.rb
+- spec/examples.rb
+homepage: https://github.com/bluemarblepayroll/cinnamon_serial
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.3.1
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.2.3
+signing_key: 
+specification_version: 4
+summary: Domain-specific language for serialization specification.
+test_files:
+- spec/base_spec.rb
+- spec/dsl_spec.rb
+- spec/examples.rb