burner 1.0.0.pre.alpha.3 → 1.0.0.pre.alpha.8

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

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

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

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

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

@@ -8,23 +8,24 @@
 #
 
 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 < JobWithRegister
       attr_reader :value
 
-      def initialize(name:, value: nil)
-        super(name: name)
+      def initialize(name:, register: '', value: nil)
+        super(name: name, register: register)
 
         @value = value
 
         freeze
       end
 
-      def perform(_output, payload, _params)
-        payload.value = value
-
-        nil
+      def perform(_output, payload)
+        payload[register] = value
       end
     end
   end

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
 
@@ -21,12 +23,10 @@ module Burner
         freeze
       end
 
-      def perform(output, _payload, _params)
+      def perform(output, _payload)
         output.detail("Going to sleep for #{seconds} second(s)")
 
         Kernel.sleep(seconds)
-
-        nil
       end
     end
   end

data/lib/burner/modeling.rb

@@ -0,0 +1,13 @@
+# 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 'modeling/attribute'
+require_relative 'modeling/attribute_renderer'
+require_relative 'modeling/key_index_mapping'
+require_relative 'modeling/validations'

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/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:')