burner 1.11.0 → 1.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f687d9818e7a090c0999f144096eef52c5ba7093a069a8d2ef784f5abdb859d7
-  data.tar.gz: cae3bb23c2671ab69263fe7359c93a47777c72fc387ab93a03006c38a2bc83cd
+  metadata.gz: ce126372d1a0fa7d4873cb58c354372a13a013a56f89f4814950eb497e9fb095
+  data.tar.gz: 0efcd55a83ef5b1c0cc716cafeae2204f4207c894419a3e40450d46e505b8ca7
 SHA512:
-  metadata.gz: 3d1740b55ec51e3459092d99165f75197dcad75d2dcce28ae285ed9dc1e1fcbb2a85002f8abeb868e0bc388424e8e85056bab1b41a54046023d06fbd836f0598
-  data.tar.gz: bffbcf8567d03252bc04fb8e207674595b271635da2ef4cec963cd6ac329e4e58194167f0b474dc522785cbaef10a239b504e12825c56fb9d55042f4733b1840
+  metadata.gz: 5ebf524b5794577e5d287a917a52207962241ad98aa68c75069aee65d0bfeb06ae4a20af84b4ce2568449f72c2611922f69cbc130fb91b859c60f3fd28e34465
+  data.tar.gz: 18db46b8876228fec2357672b6abe6cf07a86434ab1595667d18c230122d2dfac3ae03cf0794a097be7fc75c42444a368a7ede5ff8207eca5defec57c6022775

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+# 1.12.0 (August 12th, 2021)
+
+Enhanced Job:
+
+* b/collection/flat_file_parse now supports key mappings.
+
+Added Jobs:
+
+* b/collection/prepend (alias for unshift)
+* b/collection/unshift
+
 # 1.11.0 (May 17th, 2021)
 
 Added Jobs:

data/README.md

@@ -266,7 +266,7 @@ This library only ships with very basic, rudimentary jobs that are meant to just
 * **b/collection/arrays_to_objects** [mappings, register]: Convert an array of arrays to an array of objects.
 * **b/collection/coalesce** [grouped_register, insensitive, key_mappings, keys, register, separator]: Merge two datasets together based on the key values of one dataset (array) with a grouped dataset (hash).  If insensitive (false by default) is true then each key's value will be converted/coerced to a lowercase string.
 * **b/collection/concatenate** [from_registers, to_register]: Concatenate each from_register's value and place the newly concatenated array into the to_register.  Note: this does not do any deep copying and should be assumed it is shallow copying all objects.
-* **b/collection/flat_file_parse** [keys_register, register, separator]: Map an array of arrays to an array of hashes.  These keys can be realized at run-time as they are pulled from the first entry in the array.  The `keys_register` will also be set to the keys used for mapping.
+* **b/collection/flat_file_parse** [keys_register, register, separator, key_mappings]: Map an array of arrays to an array of hashes.  These keys can be realized at run-time as they are pulled from the first entry in the array.  The `keys_register` will also be set to the keys used for mapping. Only keys that are mapped will be included in the `keys_register` array if `key_mappings` are defined. Otherwise all keys that are pulled from the first entry in the `register` will be included in the `keys_register`.
 * **b/collection/graph** [config, key, register]: Use [Hashematics](https://github.com/bluemarblepayroll/hashematics) to turn a flat array of objects into a deeply nested object tree.
 * **b/collection/group** [insensitive, keys, register, separator]: Take a register's value (an array of objects) and group the objects by the specified keys.  If insensitive (false by default) is true then each key's value will be converted/coerced to a lowercase string.
 * **b/collection/nested_aggregate** [register, key_mappings, key, separator]: Traverse a set of objects, resolving key's value for each object, optionally copying down key_mappings to the child records, then merging all the inner records together.
@@ -275,9 +275,11 @@ This library only ships with very basic, rudimentary jobs that are meant to just
 * **b/collection/only_keys** [keys_register, register, separator]: Limit an array of objects' keys to a specified set of keys.  These keys can be realized at run-time as they are pulled from another register (`keys_register`) thus making it dynamic.
 * **b/collection/pivot** [unique_keys, insensitive, other_keys, pivot_key, pivot_value_key, register, separator]:
 Take an array of objects and pivot a key into multiple keys.  It essentially takes all the values for a key and creates N number of keys (one per value.) Under the hood it uses HashMath's [Record](https://github.com/bluemarblepayroll/hash_math#record-the-hash-prototype) and [Table](https://github.com/bluemarblepayroll/hash_math#table-the-double-hash-hash-of-hashes) classes.
+* **b/collection/prepend** [from_registers, to_register]: Alias for b\collection\unshift.
 * **b/collection/shift** [amount, register]: Remove the first N number of elements from an array.
 * **b/collection/transform** [attributes, exclusive, separator, register]: Iterate over all objects and transform each key per the attribute transformers specifications.  If exclusive is set to false then the current object will be overridden/merged.  Separator can also be set for key path support.  This job uses [Realize](https://github.com/bluemarblepayroll/realize), which provides its own extendable value-transformation pipeline.  If an attribute is not set with `explicit: true` then it will automatically start from the key's value from the record.  If `explicit: true` is started, then it will start from the record itself.
 * **b/collection/unpivot** [pivot_set, register]: Take an array of objects and unpivot specific sets of keys into rows.  Under the hood it uses [HashMath's Unpivot class](https://github.com/bluemarblepayroll/hash_math#unpivot-hash-key-coalescence-and-row-extrapolation).
+* **b/collection/unshift** [from_registers, register]: Adds the values of the `from_registers` to the `register` array. All existing elements in the `register` array will be shifted upwards.
 * **b/collection/validate** [invalid_register, join_char, message_key, register, separator, validations]: Take an array of objects, run it through each declared validator, and split the objects into two registers.  The valid objects will be split into the current register while the invalid ones will go into the invalid_register as declared.  Optional arguments, join_char and message_key, help determine the compiled error messages.  The separator option can be utilized to use dot-notation for validating keys.  See each validation's options by viewing their classes within the `lib/modeling/validations` directory.
 * **b/collection/values** [include_keys, register]: 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.
 * **b/collection/zip** [base_register, register, with_register]: Combines `base_register` and `with_register`s' data to form one single array in `register`.  It will combine each element, positionally in each array to form the final array.  For example:  ['hello', 'bugs'] + ['world', 'bunny'] => [['hello', 'world'], ['bugs', 'bunny']]

data/lib/burner/job_with_dynamic_keys.rb

@@ -13,17 +13,20 @@ module Burner
   # Add on a register attribute to the configuration for a job.  This indicates that a job
   # either accesses and/or mutates the payload's registers.
   class JobWithDynamicKeys < JobWithRegister
-    attr_reader :keys_register,
+    attr_reader :key_mappings,
+                :keys_register,
                 :resolver
 
     def initialize(
       keys_register:,
       name: '',
       register: DEFAULT_REGISTER,
-      separator: BLANK
+      separator: BLANK,
+      key_mappings: []
     )
       super(name: name, register: register)
 
+      @key_mappings  = Modeling::KeyMapping.array(key_mappings)
       @keys_register = keys_register.to_s
       @resolver      = Objectable.resolver(separator: separator)
 

data/lib/burner/jobs.rb

@@ -33,9 +33,11 @@ module Burner
     register 'b/collection/objects_to_arrays', Library::Collection::ObjectsToArrays
     register 'b/collection/only_keys',         Library::Collection::OnlyKeys
     register 'b/collection/pivot',             Library::Collection::Pivot
+    register 'b/collection/prepend',           Library::Collection::Unshift
     register 'b/collection/shift',             Library::Collection::Shift
     register 'b/collection/transform',         Library::Collection::Transform
     register 'b/collection/unpivot',           Library::Collection::Unpivot
+    register 'b/collection/unshift',           Library::Collection::Unshift
     register 'b/collection/values',            Library::Collection::Values
     register 'b/collection/validate',          Library::Collection::Validate
     register 'b/collection/zip',               Library::Collection::Zip

data/lib/burner/library.rb

@@ -27,6 +27,7 @@ require_relative 'library/collection/pivot'
 require_relative 'library/collection/shift'
 require_relative 'library/collection/transform'
 require_relative 'library/collection/unpivot'
+require_relative 'library/collection/unshift'
 require_relative 'library/collection/validate'
 require_relative 'library/collection/values'
 require_relative 'library/collection/zip'

data/lib/burner/library/collection/flat_file_parse.rb

@@ -11,8 +11,10 @@ module Burner
   module Library
     module Collection
       # Convert an array of arrays to an array of objects.  The difference between this
-      # job and ArraysToObjects is that this one does not take in mappings and instead
+      # job and ArraysToObjects is that this one does not require mappings and instead
       # will use the first entry as the array of keys to positionally map to.
+      # If key mappings are specified then the keys register will only contain
+      # the keys that are mapped. The register will still contain mapped and unmapped keys.
       #
       # For example, if a register had this:
       #
@@ -22,35 +24,123 @@ module Burner
       #
       #   [{ 'id' => 1, 'first' => frank, 'last' => rizzo }]
       #
-      # As a side-effect, the keys_register would result in this:
+      # As a side-effect, the keys_register would result in this, if no key mappings were specified:
       #
       #   ['id', 'first', 'last']
       #
+      # If key mappings are specified:
+      # [
+      #
+      #  {
+      #     from: 'first',
+      #     to: 'first_name'
+      #  }
+      #  {
+      #     from: 'iban',
+      #     to: 'iban_number'
+      #  }
+      # ]
+      # Then the register will now be:
+      #   [{ 'id' => 1, 'first_name' => frank, 'last' => rizzo }]
+      #
+      # And the keys_register will now contain:
+      #   ['first_name']
+      #
+      # Since 'last' did not have a key mapping entry it does not exist in the keys register.
+      # In addition, even though 'iban' does have a key mapping it does not exist in the
+      # register's payload, so it also does not exist in the keys register.
+      #
       # Expected Payload[register] input: array of arrays.
       # Payload[register] output: An array of hashes.
+      # Payload[keys_register] output; An array of key names.
       class FlatFileParse < JobWithDynamicKeys
         def perform(output, payload)
-          objects = array(payload[register])
-          keys    = array(objects.shift)
-          count   = objects.length
+          objects     = array(payload[register])
+          keys        = array(objects.shift)
+          count       = objects.length
+          mapped_keys = update_keys_using_mappings(keys, output)
+
+          payload[register]      = objects.map { |object| transform(object, mapped_keys, output) }
+          payload[keys_register] = get_mapped_keys(mapped_keys)
 
-          output.detail("Mapping #{count} array(s) to key(s): #{keys.join(', ')}")
+          output.detail("Mapping #{count} array(s)")
 
-          payload[register]      = objects.map { |object| transform(object, keys) }
-          payload[keys_register] = keys
+          output.detail("Mapping keys register array to: #{payload[keys_register].join(', ')}")
         end
 
         private
 
-        def transform(object, keys)
+        def transform(object, keys, output)
           object.each_with_object({}).with_index do |(value, memo), index|
             next if index >= keys.length
 
-            key = keys[index]
+            key_hash = keys[index]
+
+            key = key_hash[:unmapped_key_name]
+
+            mapped_key = key_hash[:mapped_key_name]
+
+            key = mapped_key if mapped_key
 
             resolver.set(memo, key, value)
+
+            output.detail("Using key #{key}")
+          end
+        end
+
+        def get_mapped_keys(mapped_keys)
+          mapped_keys.each_with_object([]) do |mapped_key_hash, memo|
+            mapped_key = mapped_key_hash[:mapped_key_name]
+
+            memo << mapped_key if mapped_key
+          end
+        end
+
+        def update_keys_using_mappings(keys, output)
+          if key_mappings.count.positive?
+            populate_key_hashes_from_mappings(keys, output)
+          else
+            populate_key_hashes_without_mappings(keys)
+          end
+        end
+
+        def populate_key_hashes_from_mappings(keys, output)
+          keys.each_with_object([]) do |key, memo|
+            mapped_key_name = find_key_name_to_use_from_mappings(key, output)
+
+            mapped_key_name = nil if key == mapped_key_name
+
+            memo << create_key_hash(key, mapped_key_name)
           end
         end
+
+        def populate_key_hashes_without_mappings(keys)
+          keys.each_with_object([]) do |key, memo|
+            memo << create_key_hash(key, key)
+          end
+        end
+
+        def create_key_hash(unmapped_key_name, mapped_key_name)
+          { unmapped_key_name: unmapped_key_name, mapped_key_name: mapped_key_name }
+        end
+
+        def find_key_name_to_use_from_mappings(key, output)
+          key_to_use = key
+
+          key_mappings.each do |key_mapping|
+            next unless key_mapping.from.downcase == key.downcase
+
+            key_to_use = populate_key_to_use(key_mapping)
+            output.detail("Using key_mapping from key #{key} to #{key_to_use}")
+            break
+          end
+
+          key_to_use
+        end
+
+        def populate_key_to_use(key_mapping)
+          key_mapping.to unless key_mapping.to.empty?
+        end
       end
     end
   end

data/lib/burner/library/collection/unshift.rb

@@ -0,0 +1,45 @@
+# 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 Library
+    module Collection
+      # Adds the values of the from_registers to the to_register array.
+      # All existing elements in the register array will be shifted upwards.
+      #
+      # Expected Payload[from_registers] input: Array containing names of registers
+      # whose values to prepend.
+      # Payload[register] output: An array with the from_registers'
+      # payload added to the beginning.
+      class Unshift < JobWithRegister
+        attr_reader :from_registers
+
+        def initialize(from_registers: [], name: '', register: DEFAULT_REGISTER)
+          super(name: name, register: register)
+
+          @from_registers = Array(from_registers)
+
+          freeze
+        end
+
+        def perform(output, payload)
+          output.detail("Prepending registers: '#{from_registers}' to: '#{register}'")
+
+          payload_register = array(payload[register])
+
+          from_registers.each do |from_register|
+            from_register_value = payload[from_register]
+
+            payload_register.unshift(from_register_value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/burner/version.rb

@@ -8,5 +8,5 @@
 #
 
 module Burner
-  VERSION = '1.11.0'
+  VERSION = '1.12.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: burner
 version: !ruby/object:Gem::Version
-  version: 1.11.0
+  version: 1.12.0
 platform: ruby
 authors:
 - Matthew Ruggio
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-05-18 00:00:00.000000000 Z
+date: 2021-08-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: acts_as_hashable
@@ -258,6 +258,7 @@ files:
 - lib/burner/library/collection/shift.rb
 - lib/burner/library/collection/transform.rb
 - lib/burner/library/collection/unpivot.rb
+- lib/burner/library/collection/unshift.rb
 - lib/burner/library/collection/validate.rb
 - lib/burner/library/collection/values.rb
 - lib/burner/library/collection/zip.rb