burner 1.0.0.pre.alpha.5 → 1.0.0.pre.alpha.6

data/lib/burner/{jobs → library}/collection/transform.rb

@@ -7,14 +7,17 @@
 # LICENSE file in the root directory of this source tree.
 #
 
-require_relative 'transform/attribute'
-require_relative 'transform/attribute_renderer'
-
 module Burner
-  class Jobs
+  module Library
     module Collection
-      # Iterate over all objects and return a new set of transformed objects.  Under the hood
-      # this uses the Realize library: https://github.com/bluemarblepayroll/realize
+      # Iterate over all objects and return a new set of transformed objects.  The object is
+      # transformed per the "transformers" attribute for its attributes.  An attribute defines
+      # the ultimate key to place the value in and then the transformer pipeline to use to
+      # derive the value.  Under the hood this uses the Realize library:
+      #   https://github.com/bluemarblepayroll/realize
+      # For more information on the specific contract for attributes, see the
+      # Burner::Modeling::Attribute class.
+      #
       # Expected Payload#value input: array of objects.
       # Payload#value output: An array of objects.
       class Transform < Job
@@ -30,14 +33,15 @@ module Burner
           @resolver  = Objectable.resolver(separator: separator)
           @exclusive = exclusive || false
 
-          @attribute_renderers = Attribute.array(attributes)
-                                          .map { |a| AttributeRenderer.new(a, resolver) }
+          @attribute_renderers =
+            Modeling::Attribute.array(attributes)
+                               .map { |a| Modeling::AttributeRenderer.new(a, resolver) }
 
           freeze
         end
 
         def perform(output, payload)
-          payload.value = (payload.value || []).map { |row| transform(row, payload.time) }
+          payload.value = array(payload.value).map { |row| transform(row, payload.time) }
 
           attr_count = attribute_renderers.length
           row_count  = payload.value.length

data/lib/burner/{jobs → library}/collection/unpivot.rb

@@ -8,11 +8,12 @@
 #
 
 module Burner
-  class Jobs
+  module Library
     module Collection
       # Take an array of objects and un-pivot groups of keys into rows.
       # Under the hood it uses HashMath's Unpivot class:
       # https://github.com/bluemarblepayroll/hash_math
+      #
       # Expected Payload#value input: array of objects.
       # Payload#value output: An array of objects.
       class Unpivot < Job
@@ -27,15 +28,16 @@ module Burner
         end
 
         def perform(output, payload)
-          pivot_count  = unpivot.pivot_set.pivots.length
-          key_count    = unpivot.pivot_set.pivots.map { |p| p.keys.length }.sum
-          object_count = payload.value&.length || 0
+          pivot_count   = unpivot.pivot_set.pivots.length
+          key_count     = unpivot.pivot_set.pivots.map { |p| p.keys.length }.sum
+          payload.value = array(payload.value)
+          object_count  = payload.value.length || 0
 
           message = "#{pivot_count} Pivots, Key(s): #{key_count} key(s), #{object_count} objects(s)"
 
           output.detail(message)
 
-          payload.value = (payload.value || []).flat_map { |object| unpivot.expand(object) }
+          payload.value = payload.value.flat_map { |object| unpivot.expand(object) }
 
           nil
         end

data/lib/burner/{jobs → library}/collection/values.rb

@@ -8,11 +8,12 @@
 #
 
 module Burner
-  class Jobs
+  module Library
     module Collection
       # Take an array of objects and call #values on each object.
       # If include_keys is true (it is false by default), then call #keys on the first
       # object and inject that as a "header" object.
+      #
       # Expected Payload#value input: array of objects.
       # Payload#value output: An array of arrays.
       class Values < Job
@@ -27,9 +28,9 @@ module Burner
         end
 
         def perform(_output, payload)
-          keys   = include_keys ? [keys(payload.value&.first)] : []
-          values = (payload.value || []).map { |object| values(object) }
-
+          payload.value = array(payload.value)
+          keys          = include_keys ? [keys(payload.value.first)] : []
+          values        = payload.value.map { |object| values(object) }
           payload.value = keys + values
 
           nil

data/lib/burner/{jobs → library}/deserialize/csv.rb

@@ -8,9 +8,10 @@
 #
 
 module Burner
-  class Jobs
+  module Library
     module Deserialize
       # Take a CSV string and de-serialize into object(s).
+      #
       # Expected Payload#value input: nothing.
       # Payload#value output: an array of arrays.  Each inner array represents one data row.
       class Csv < Job

data/lib/burner/{jobs → library}/deserialize/json.rb

@@ -8,9 +8,12 @@
 #
 
 module Burner
-  class Jobs
+  module Library
     module Deserialize
       # Take a JSON string and deserialize into object(s).
+      #
+      # Expected Payload#value input: string of JSON data.
+      # Payload#value output: anything, as specified by the JSON de-serializer.
       class Json < Job
         def perform(_output, payload)
           payload.value = JSON.parse(payload.value)

data/lib/burner/{jobs → library}/deserialize/yaml.rb

@@ -8,9 +8,15 @@
 #
 
 module Burner
-  class Jobs
+  module Library
     module Deserialize
-      # Take a YAML string and deserialize into object(s).
+      # Take a YAML string and deserialize into object(s).  It uses YAML#safe_load by default,
+      # which ensures only a limited number of Ruby object constants can be hydrated by the
+      # YAML.  If you wish to ease this restriction, for example if you have custom serialization
+      # for custom classes, then you can pass in safe: false.
+      #
+      # Expected Payload#value input: string of YAML data.
+      # Payload#value output: anything as specified by the YAML de-serializer.
       class Yaml < Job
         attr_reader :safe
 

data/lib/burner/{jobs → library}/dummy.rb

@@ -8,8 +8,10 @@
 #
 
 module Burner
-  class Jobs
+  module Library
     # Do nothing.
+    #
+    # Note: this does not use Payload#value.
     class Dummy < Job
       def perform(_output, _payload)
         nil

data/lib/burner/{jobs → library}/echo.rb

@@ -8,8 +8,10 @@
 #
 
 module Burner
-  class Jobs
+  module Library
     # Output a simple message to the output.
+    #
+    # Note: this does not use Payload#value.
     class Echo < Job
       attr_reader :message
 

data/lib/burner/{jobs → library}/io/base.rb

@@ -8,7 +8,7 @@
 #
 
 module Burner
-  class Jobs
+  module Library
     module IO
       # Common configuration/code for all IO Job subclasses.
       class Base < Job

data/lib/burner/{jobs → library}/io/exist.rb

@@ -10,10 +10,12 @@
 require_relative 'base'
 
 module Burner
-  class Jobs
+  module Library
     module IO
       # Check to see if a file exists.  If short_circuit is set to true and the file
       # does not exist then the job will return false and short circuit the pipeline.
+      #
+      # Note: this does not use Payload#value.
       class Exist < Base
         attr_reader :short_circuit
 

data/lib/burner/{jobs → library}/io/read.rb

@@ -10,9 +10,12 @@
 require_relative 'base'
 
 module Burner
-  class Jobs
+  module Library
     module IO
       # Read value from disk.
+      #
+      # Expected Payload#value input: nothing.
+      # Payload#value output: contents of the specified file.
       class Read < Base
         attr_reader :binary
 

data/lib/burner/{jobs → library}/io/write.rb

@@ -10,9 +10,12 @@
 require_relative 'base'
 
 module Burner
-  class Jobs
+  module Library
     module IO
       # Write value to disk.
+      #
+      # Expected Payload#value input: anything.
+      # Payload#value output: whatever was passed in.
       class Write < Base
         attr_reader :binary
 
@@ -35,12 +38,14 @@ module Burner
             File.open(compiled_path, mode) { |io| io.write(payload.value) }
           end.real
 
-          payload.add_written_file(
+          side_effect = SideEffects::WrittenFile.new(
             logical_filename: compiled_path,
             physical_filename: compiled_path,
             time_in_seconds: time_in_seconds
           )
 
+          payload.add_side_effect(side_effect)
+
           nil
         end
 

data/lib/burner/{jobs → library}/serialize/csv.rb

@@ -8,15 +8,16 @@
 #
 
 module Burner
-  class Jobs
+  module Library
     module Serialize
       # Take an array of arrays and create a CSV.
+      #
       # Expected Payload#value input: array of arrays.
       # Payload#value output: a serialized CSV string.
       class Csv < Job
         def perform(_output, payload)
           payload.value = CSV.generate(options) do |csv|
-            (payload.value || []).each do |row|
+            array(payload.value).each do |row|
               csv << row
             end
           end

data/lib/burner/{jobs → library}/serialize/json.rb

@@ -8,9 +8,12 @@
 #
 
 module Burner
-  class Jobs
+  module Library
     module Serialize
       # Treat value like a Ruby object and serialize it using JSON.
+      #
+      # Expected Payload#value input: anything.
+      # Payload#value output: string representing the output of the JSON serializer.
       class Json < Job
         def perform(_output, payload)
           payload.value = payload.value.to_json

data/lib/burner/{jobs → library}/serialize/yaml.rb

@@ -8,9 +8,12 @@
 #
 
 module Burner
-  class Jobs
+  module Library
     module Serialize
       # Treat value like a Ruby object and serialize it using YAML.
+      #
+      # Expected Payload#value input: anything.
+      # Payload#value output: string representing the output of the YAML serializer.
       class Yaml < Job
         def perform(_output, payload)
           payload.value = payload.value.to_yaml

data/lib/burner/{jobs/set.rb → library/set_value.rb}

@@ -8,9 +8,12 @@
 #
 
 module Burner
-  class Jobs
+  module Library
     # Arbitrarily set value
-    class Set < Job
+    #
+    # Expected Payload#value input: anything.
+    # Payload#value output: whatever value was specified in this job.
+    class SetValue < Job
       attr_reader :value
 
       def initialize(name:, value: nil)

data/lib/burner/{jobs → library}/sleep.rb

@@ -8,8 +8,10 @@
 #
 
 module Burner
-  class Jobs
+  module Library
     # Arbitrarily put thread to sleep for X number of seconds
+    #
+    # Payload#value output: whatever value was specified in this job.
     class Sleep < Job
       attr_reader :seconds
 

data/lib/burner/modeling.rb

@@ -7,4 +7,6 @@
 # LICENSE file in the root directory of this source tree.
 #
 
+require_relative 'modeling/attribute'
+require_relative 'modeling/attribute_renderer'
 require_relative 'modeling/key_index_mapping'

data/lib/burner/modeling/attribute.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2020-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 Burner
+  module Modeling
+    # Defines a top-level key and the associated transformers for deriving the final value
+    # to set the key to.
+    class Attribute
+      acts_as_hashable
+
+      attr_reader :key, :transformers
+
+      def initialize(key:, transformers: [])
+        raise ArgumentError, 'key is required' if key.to_s.empty?
+
+        @key          = key.to_s
+        @transformers = Realize::Transformers.array(transformers)
+
+        freeze
+      end
+    end
+  end
+end

data/lib/burner/modeling/attribute_renderer.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2020-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 Burner
+  module Modeling
+    # Composed of an Attribute instance and a Pipeline instance.  It knows how to
+    # render/transform an Attribute.  Since this library is data-first, these intermediary
+    # objects are necessary for non-data-centric modeling.
+    class AttributeRenderer
+      extend Forwardable
+
+      attr_reader :attribute, :pipeline
+
+      def_delegators :attribute, :key
+
+      def_delegators :pipeline, :transform
+
+      def initialize(attribute, resolver)
+        @attribute = attribute
+        @pipeline  = Realize::Pipeline.new(attribute.transformers, resolver: resolver)
+
+        freeze
+      end
+    end
+  end
+end

data/lib/burner/payload.rb

@@ -7,35 +7,38 @@
 # LICENSE file in the root directory of this source tree.
 #
 
-require_relative 'written_file'
-
 module Burner
   # The input for all Job#perform methods.  The main notion of this object is its "value"
   # attribute.  This is dynamic and weak on purpose and is subject to whatever the Job#perform
   # methods decides it is.  This definitely adds an order-of-magnitude complexity to this whole
   # library and lifecycle, but I am not sure there is any other way around it: trying to build
   # a generic, open-ended object pipeline to serve almost any use case.
+  #
+  # The side_effects attribute can also be utilized as a way for jobs to emit any data in a more
+  # structured/additive manner.  The initial use case for this was for Burner's core IO jobs to
+  # report back the files it has written in a more structured data way (as opposed to simply
+  # writing some information to the output.)
   class Payload
     attr_accessor :value
 
     attr_reader :params,
-                :time,
-                :written_files
+                :side_effects,
+                :time
 
     def initialize(
       params: {},
+      side_effects: [],
       time: Time.now.utc,
-      value: nil,
-      written_files: []
+      value: nil
     )
-      @params        = params || {}
-      @time          = time || Time.now.utc
-      @value         = value
-      @written_files = written_files || []
+      @params       = params || {}
+      @side_effects = side_effects || []
+      @time         = time || Time.now.utc
+      @value        = value
     end
 
-    def add_written_file(written_file)
-      tap { written_files << WrittenFile.make(written_file) }
+    def add_side_effect(side_effect)
+      tap { side_effects << side_effect }
     end
   end
 end