burner 1.0.0.pre.alpha.2 → 1.0.0.pre.alpha.7

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/modeling/key_index_mapping.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
+    # Generic relationship between a numeric index and a key.
+    class KeyIndexMapping
+      acts_as_hashable
+
+      attr_reader :index, :key
+
+      def initialize(index:, key:)
+        raise ArgumentError, 'index is required' if index.to_s.empty?
+        raise ArgumentError, 'key is required'   if key.to_s.empty?
+
+        @index = index.to_i
+        @key   = key.to_s
+
+        freeze
+      end
+    end
+  end
+end

data/lib/burner/modeling/validations.rb

@@ -0,0 +1,23 @@
+# 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.
+#
+
+require_relative 'validations/blank'
+require_relative 'validations/present'
+
+module Burner
+  module Modeling
+    # Factory for building sub-classes that can validate an individual object and field value.
+    class Validations
+      acts_as_hashable_factory
+
+      register 'blank',   Validations::Blank
+      register 'present', Validations::Present
+    end
+  end
+end

data/lib/burner/modeling/validations/base.rb

@@ -0,0 +1,35 @@
+# 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
+    class Validations
+      # Common logic shared among all Validation subclasses.
+      # This class is an abstract class, make sure to implement:
+      # - #valid?(object, resolver)
+      # - #default_message
+      class Base
+        acts_as_hashable
+
+        attr_reader :key
+
+        def initialize(key:, message: '')
+          raise ArgumentError, 'key is required' if key.to_s.empty?
+
+          @key     = key.to_s
+          @message = message.to_s
+        end
+
+        def message
+          @message.to_s.empty? ? "#{key}#{default_message}" : @message.to_s
+        end
+      end
+    end
+  end
+end

data/lib/burner/modeling/validations/blank.rb

@@ -0,0 +1,31 @@
+# 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.
+#
+
+require_relative 'base'
+
+module Burner
+  module Modeling
+    class Validations
+      # Check if a value is blank, if it is not blank then it is not valid.
+      class Blank < Base
+        acts_as_hashable
+
+        def valid?(object, resolver)
+          resolver.get(object, key).to_s.empty?
+        end
+
+        private
+
+        def default_message
+          ' must be blank'
+        end
+      end
+    end
+  end
+end

data/lib/burner/modeling/validations/present.rb

@@ -0,0 +1,31 @@
+# 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.
+#
+
+require_relative 'base'
+
+module Burner
+  module Modeling
+    class Validations
+      # Check if a value is present.  If it is blank (null or empty) then it is invalid.
+      class Present < Base
+        acts_as_hashable
+
+        def valid?(object_value, resolver)
+          !resolver.get(object_value, key).to_s.empty?
+        end
+
+        private
+
+        def default_message
+          ' is required'
+        end
+      end
+    end
+  end
+end

data/lib/burner/payload.rb

@@ -7,27 +7,72 @@
 # 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,
+                :registers,
+                :side_effects,
+                :time
+
+    def initialize(
+      params: {},
+      registers: {},
+      side_effects: [],
+      time: Time.now.utc
+    )
+      @params       = params || {}
+      @registers    = {}
+      @side_effects = side_effects || []
+      @time         = time || Time.now.utc
+
+      add_registers(registers)
+    end
+
+    # Add a side effect of a job.  This helps to keep track of things jobs do outside of its
+    # register mutations.
+    def add_side_effect(side_effect)
+      tap { side_effects << side_effect }
+    end
+
+    # Set a register's value.
+    def []=(key, value)
+      set(key, value)
+    end
+
+    # Retrieve a register's value.
+    def [](key)
+      registers[key.to_s]
+    end
+
+    # Set halt_pipeline to true.  This will indicate to the pipeline to stop all
+    # subsequent processing.
+    def halt_pipeline
+      @halt_pipeline = true
+    end
+
+    # Check and see if halt_pipeline was called.
+    def halt_pipeline?
+      @halt_pipeline || false
+    end
 
-    attr_reader :context, :written_files
+    private
 
-    def initialize(context: {}, value: nil, written_files: [])
-      @context       = context || {}
-      @value         = value
-      @written_files = written_files || []
+    def set(key, value)
+      registers[key.to_s] = value
     end
 
-    def add_written_file(written_file)
-      tap { written_files << WrittenFile.make(written_file) }
+    def add_registers(registers)
+      (registers || {}).each { |k, v| set(k, v) }
     end
   end
 end

data/lib/burner/pipeline.rb

@@ -19,11 +19,16 @@ module Burner
     acts_as_hashable
 
     class JobNotFoundError < StandardError; end
+    class DuplicateJobNameError < StandardError; end
 
     attr_reader :steps
 
     def initialize(jobs: [], steps: [])
-      jobs_by_name = Jobs.array(jobs).map { |job| [job.name, job] }.to_h
+      jobs = Jobs.array(jobs)
+
+      assert_unique_job_names(jobs)
+
+      jobs_by_name = jobs.map { |job| [job.name, job] }.to_h
 
       @steps = Array(steps).map do |step_name|
         job = jobs_by_name[step_name.to_s]
@@ -35,18 +40,18 @@ module Burner
     end
 
     # The main entry-point for kicking off a pipeline.
-    def execute(output: Output.new, params: {}, payload: Payload.new)
+    def execute(output: Output.new, payload: Payload.new)
       output.write("Pipeline started with #{steps.length} step(s)")
 
-      output_params(params, output)
+      output_params(payload.params, output)
       output.ruler
 
       time_in_seconds = Benchmark.measure do
         steps.each do |step|
-          return_value = step.perform(output, payload, params)
+          step.perform(output, payload)
 
-          if return_value.is_a?(FalseClass)
-            output.detail('Job returned false, ending pipeline.')
+          if payload.halt_pipeline?
+            output.detail('Payload was halted, ending pipeline.')
             break
           end
         end
@@ -60,6 +65,20 @@ module Burner
 
     private
 
+    def assert_unique_job_names(jobs)
+      unique_job_names = Set.new
+
+      jobs.each do |job|
+        if unique_job_names.include?(job.name)
+          raise DuplicateJobNameError, "job with name: #{job.name} already declared"
+        end
+
+        unique_job_names << job.name
+      end
+
+      nil
+    end
+
     def output_params(params, output)
       if params.keys.any?
         output.write('Parameters:')

data/lib/burner/side_effects.rb

@@ -0,0 +1,10 @@
+# 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.
+#
+
+require_relative 'side_effects/written_file'

data/lib/burner/side_effects/written_file.rb

@@ -0,0 +1,28 @@
+# 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 SideEffects
+    # Describes a file that was generated by a Job.  If a Job emits a file, it should also add the
+    # file details to the Payload#side_effects array using the Payload#add_side_effect method.
+    class WrittenFile
+      attr_reader :logical_filename,
+                  :physical_filename,
+                  :time_in_seconds
+
+      def initialize(logical_filename:, physical_filename:, time_in_seconds:)
+        @logical_filename  = logical_filename.to_s
+        @physical_filename = physical_filename.to_s
+        @time_in_seconds   = time_in_seconds.to_f
+
+        freeze
+      end
+    end
+  end
+end

data/lib/burner/step.rb

@@ -28,20 +28,14 @@ module Burner
       freeze
     end
 
-    def perform(output, payload, params)
-      return_value = nil
-
+    def perform(output, payload)
       output.title("#{job.class.name}#{SEPARATOR}#{job.name}")
 
       time_in_seconds = Benchmark.measure do
-        job_params = (params || {}).merge(__id: output.id, __value: payload.value)
-
-        return_value = job.perform(output, payload, job_params)
+        job.perform(output, payload)
       end.real.round(3)
 
       output.complete(time_in_seconds)
-
-      return_value
     end
   end
 end

data/lib/burner/util.rb

@@ -0,0 +1,11 @@
+# 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.
+#
+
+require_relative 'util/arrayable'
+require_relative 'util/string_template'

data/lib/burner/util/arrayable.rb

@@ -0,0 +1,30 @@
+# 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 Util
+    # Provide helper methods for dealing with Arrays.
+    module Arrayable
+      # Since Ruby's Kernel#Array will properly call #to_a for scalar Hash objects, this could
+      # return something funky in the context of this library.  In this library, Hash instances
+      # are typically viewed as an atomic key-value-based "object".  This library likes to deal
+      # with object-like things, treating Hash, OpenStruct, Struct, or Object subclasses as
+      # basically the same thing.  In this vein, this library leverages Objectable to help
+      # unify access data from objects.  See the Objectable library for more information:
+      # https://github.com/bluemarblepayroll/objectable
+      def array(value)
+        if value.is_a?(Hash)
+          [value]
+        else
+          Array(value)
+        end
+      end
+    end
+  end
+end

data/lib/burner/util/string_template.rb

@@ -0,0 +1,42 @@
+# 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 Util
+    # Can take in a string and an object and use the object for formatting string interpolations
+    # using tokens of form: {attribute_name}.  This templating class does not understand nested
+    # structures, so input should be a flat object/hash in the form of key-value pairs.
+    # A benefit of using Objectable for resolution is that it can understand almost any type of
+    # object: Hash, Struct, OpenStruct, custom objects, etc.
+    # For more information see underlying libraries:
+    #   * Stringento: https://github.com/bluemarblepayroll/stringento
+    #   * Objectable: https://github.com/bluemarblepayroll/objectable
+    class StringTemplate
+      include Singleton
+
+      attr_reader :resolver
+
+      def initialize
+        @resolver = Objectable.resolver(separator: '')
+
+        freeze
+      end
+
+      # For general consumption
+      def evaluate(expression, input)
+        Stringento.evaluate(expression, input, resolver: self)
+      end
+
+      # For Stringento consumption
+      def resolve(value, input)
+        resolver.get(input, value)
+      end
+    end
+  end
+end