hash_math 1.1.0 → 1.2.0.pre.alpha

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7df04a330a0de007fb2dba40e7deb6b835ad5aebdf0be39dd596c4af6ee52715
-  data.tar.gz: b0277b0818de7dcb5f59a82e46e761bc6afb16c7f74ed3fc5390b9cd6addd6bc
+  metadata.gz: ac40548aa245ecbca0e7e2cc3dd8d617db1937108aa64f60513a7819b84bf534
+  data.tar.gz: 15b253850e012966eeb4aadbcd5873bd9571abe0fa62bd83a242ed39de8e2395
 SHA512:
-  metadata.gz: 73f27b9a0746d605e7471aa14f4b1203894c72064555ed19303acc2e2c4e18169e8365daf20aeb299afc5b3faef9ec0552af04bab8b73fdc59bf9beb8baa2bd8
-  data.tar.gz: bc0eb13e08c690f7506ad413ad4fe1a3d22698cbe8f313efc1af8d62546ca1c0ab2cea4b0ba55f44758661688d9da6e3ff11931aca88a775226bcfb26758315b
+  metadata.gz: d2289559ffbb080f16eff2655ab83860ca2779120d17ce5795d163dd762f425da9ab27ec16f7f480ffb84b824eaab60068de18548215a770abb4e24847f6e66f
+  data.tar.gz: 5256981292c2f27c706753524f3816b04207a322b179a92028d7e5a902c2d4836fb8b353684beab691c28f0e5c3920715fbff79412a7a8a0e8fa223716e90226

data/CHANGELOG.md

@@ -1,10 +1,16 @@
-# 1.1.0 (August 13t, 2020)
+# 1.2.0 (TBD)
 
-Adding:
+Additions:
 
-* HashMath#Unpivot class and implementation.
+* HashMath::Mapper
 
-Removing:
+# 1.1.0 (August 13th, 2020)
+
+Additions:
+
+* HashMath::Unpivot
+
+Removals:
 
 * Support for Ruby < 2.5
 

data/README.md

@@ -230,6 +230,72 @@ The `rows` variable should now be equivalent to:
 
 Note: `HashMath::Unpivot#add` also exists to update an already instantiated object with new pivot_sets.
 
+### Mapper: Constant-Time Cross-Mapper
+
+The general use-case for `HashMath::Mapper` is to store pre-materialized lookups and then use those lookups efficiently to fill in missing data for a hash.
+
+For example: say we have incoming data representing patients, but this incoming data is value-oriented, not entity/identity-oriented, which may be what we need to ingest it properly:
+
+````ruby
+patient = { patient_id: 2, patient_status: 'active', marital_status: 'married' }
+````
+
+It is not sufficient for us to use patient_status and marital_status, what we need is the entity identifiers for those values.  What we can do is load up a HashMath::Mapper instance with these values and let it do the work for us:
+
+````ruby
+patient_statuses = [
+  { id: 1, name: 'active' },
+  { id: 2, name: 'inactive' },
+  { id: 3, name: 'archived' }
+]
+
+marital_statuses = [
+  { id: 1, code: 'single' },
+  { id: 2, code: 'married' },
+  { id: 3, code: 'divorced' }
+]
+
+mappings = [
+  {
+    lookup: {
+      name: :patient_statuses,
+      by: :name
+    },
+    set: :patient_status_id,
+    value: :patient_status,
+    with: :id
+  },
+  {
+    lookup: {
+      name: :marital_statuses,
+      by: :code
+    },
+    set: :marital_status_id,
+    value: :marital_status,
+    with: :id
+  }
+]
+
+mapper = HashMath::Mapper
+  .new(mappings)
+  .add_each(:patient_statuses, patient_statuses)
+  .add_each(:marital_statuses, marital_statuses)
+
+mapped_patient = mapper.map(patient)
+````
+
+The variable `mapped_patient` should now be equal to:
+
+````ruby
+{
+  patient_id: 2,
+  patient_status: 'active',
+  marital_status: 'single',
+  patient_status_id: 1,
+  marital_status_id: 2
+}
+````
+
 ## Contributing
 
 ### Development Environment Configuration

data/lib/hash_math.rb

@@ -9,6 +9,7 @@
 
 require 'acts_as_hashable'
 
+require_relative 'hash_math/mapper'
 require_relative 'hash_math/matrix'
 require_relative 'hash_math/record'
 require_relative 'hash_math/table'

data/lib/hash_math/mapper.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-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 'mapper/mapping'
+
+module HashMath
+  # A Mapper instance can hold multiple constant-time object lookups and then is able to map
+  # a hash to its corresponding lookup values.  It's main use-case is to fill in missing or
+  # update existing key-value pairs with its corresponding relationships.
+  class Mapper
+    attr_reader :mappings_by_name
+
+    # Accepts an array of Mapping instances of hashes containing the Mapping instance attributes
+    # to initialize.
+    def initialize(mappings = [])
+      mappings          = Mapping.array(mappings)
+      @mappings_by_name = pivot_by_name(mappings)
+
+      freeze
+    end
+
+    # Add an enumerable list of lookup records to this instance's lookup dataset.
+    def add_each(name, objects)
+      tap { objects.each { |o| add(name, o) } }
+    end
+
+    # Add a lookup record to this instance's lookup dataset.
+    def add(name, object)
+      tap { mappings_by_name.fetch(name.to_s).add(object) }
+    end
+
+    # Returns a new hash with the added/updated key-value pairs.  Note that this only does a
+    # shallow copy using Hash#merge.
+    def map(hash)
+      map!({}.merge(hash || {}))
+    end
+
+    # Mutates the inpuuted hash with the added/updated key-value pairs.
+    def map!(hash)
+      mappings_by_name.values.each_with_object(hash) do |mapping, _memo|
+        mapping.map!(hash)
+      end
+    end
+
+    private
+
+    def pivot_by_name(array)
+      array.each_with_object({}) do |object, memo|
+        memo[object.name.to_s] = object
+      end
+    end
+  end
+end

data/lib/hash_math/mapper/lookup.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-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 HashMath
+  class Mapper
+    # A Lookup instance maintains its own list of objects using its own key extraction method,
+    # called 'by' which will be used to extract the key's value for the lookup.
+    # If 'by' is a Proc then it will be called when extracting a new lookup record's lookup value.
+    # If it is anything other than a Proc and it will call #[] on the object.
+    class Lookup
+      acts_as_hashable
+
+      attr_reader :name, :by
+
+      def initialize(name:, by:)
+        @name    = name
+        @by      = by
+        @objects = {}
+
+        freeze
+      end
+
+      def add_each(array) # :nodoc:
+        tap { array.each { |o| add(o) } }
+      end
+
+      def add(object) # :nodoc:
+        id = proc_or_brackets(object, by)
+
+        objects[id] = object
+
+        self
+      end
+
+      def get(value) # :nodoc:
+        objects[value]
+      end
+
+      private
+
+      attr_reader :objects
+
+      def proc_or_brackets(object, thing)
+        return nil unless object
+
+        thing.is_a?(Proc) ? thing.call(object) : object[thing]
+      end
+    end
+  end
+end

data/lib/hash_math/mapper/mapping.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-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 'lookup'
+
+module HashMath
+  class Mapper
+    # Represents one complete configuration for mapping one key-value pair to one lookup.
+    #
+    # Example:
+    # ----------------------------------------------------------------------------------------------
+    # mapping = Mapper.make(
+    #   lookup: { name: :patient_statuses, by: :name },
+    #   value: :status,
+    #   set: :patient_status_id,
+    #   with: :id
+    # ).add(id: 1, name: 'active').add(id: 2, name: 'inactive')
+    #
+    # patient        = { id: 1, code: 'active' }
+    # mapped_patient = mapping.map!(patient)
+    # ----------------------------------------------------------------------------------------------
+    #
+    # mapped_patient now equals: { id: 1, code: 'active', patient_status_id: 1 }
+    class Mapping
+      extend Forwardable
+      acts_as_hashable
+
+      attr_reader :value, :set, :with, :lookup
+
+      def_delegators :lookup, :name, :by, :add, :add_each
+
+      # lookup: can either be a Mapper#Lookup instance or a hash with the attributes to initialize
+      # for a Mapper#Lookup instance.
+      # value: the key to use to get the 'value' from the object to lookup.
+      # set: the key to set once the lookup record is identified.
+      # with: the key use, on the lookup, to get the new value.
+      def initialize(lookup:, value:, set:, with:)
+        @lookup = Lookup.make(lookup)
+        @value  = value
+        @set    = set
+        @with   = with
+
+        freeze
+      end
+
+      def add_each(array) # :nodoc:
+        tap { lookup.add_each(array) }
+      end
+
+      def add(object) # :nodoc:
+        tap { lookup.add(object) }
+      end
+
+      def map!(hash) # :nodoc:
+        lookup_value  = proc_or_brackets(hash, value)
+        lookup_object = lookup.get(lookup_value)
+        hash[set]     = proc_or_brackets(lookup_object, with)
+
+        self
+      end
+
+      private
+
+      def proc_or_brackets(object, thing)
+        return nil unless object
+
+        thing.is_a?(Proc) ? thing.call(object) : object[thing]
+      end
+    end
+  end
+end

data/lib/hash_math/unpivot.rb

@@ -13,7 +13,6 @@ module HashMath
   # This class has the ability to extrapolate one hash (row) into multiple hashes (rows) while
   # unpivoting specific keys into key-value pairs.
   class Unpivot
-    acts_as_hashable
     extend Forwardable
 
     attr_reader :pivot_set

data/lib/hash_math/unpivot/pivot.rb

@@ -34,7 +34,7 @@ module HashMath
       # the first will serve as the prototype for each returned hash
       # the second will be one to use for value extraction.
       # Returns an array of hashes.
-      def expand(base_hash, value_hash)
+      def expand(base_hash, value_hash) # :nodoc:
         keys.map do |key|
           base_hash.merge(
             coalesce_key => key,

data/lib/hash_math/unpivot/pivot_set.rb

@@ -32,7 +32,7 @@ module HashMath
 
       # An aggregation of Pivot#expand.  This method will iterate over all pivots
       # and expand them all out.
-      def expand(hash)
+      def expand(hash) # :nodoc:
         base_hash = make_base_hash(hash)
 
         pivots.map { |pivot| pivot.expand(base_hash, hash) }

data/lib/hash_math/version.rb

@@ -8,5 +8,5 @@
 #
 
 module HashMath
-  VERSION = '1.1.0'
+  VERSION = '1.2.0-alpha'
 end

data/spec/hash_math/mapper/mapping_spec.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-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 'spec_helper'
+
+describe HashMath::Mapper::Mapping do
+  let(:active)           { { id: 1, name: 'active' } }
+  let(:inactive)         { { id: 2, name: 'inactive' } }
+  let(:patient_statuses) { [active, inactive] }
+
+  let(:mapping) do
+    {
+      lookup: {
+        name: :patient_statuses,
+        by: :name
+      },
+      set: :patient_status_id,
+      value: :patient_status,
+      with: :id
+    }
+  end
+
+  subject do
+    described_class.make(mapping).add_each(patient_statuses)
+  end
+
+  let(:omitted) do
+    { patient_id: 1 }
+  end
+
+  let(:filled) do
+    { patient_id: 2, patient_status: 'active' }
+  end
+
+  let(:mismatched) do
+    { patient_id: 2, patient_status: 'doesnt_exist' }
+  end
+
+  context 'when keys are missing' do
+    it 'returns hash with nil values' do
+      expected = omitted.merge(patient_status_id: nil)
+
+      subject.map!(omitted)
+
+      expect(omitted).to eq(expected)
+    end
+  end
+
+  context 'when keys are present' do
+    it 'returns hash with values' do
+      expected = filled.merge(patient_status_id: 1)
+
+      subject.map!(filled)
+
+      expect(filled).to eq(expected)
+    end
+  end
+
+  context 'when keys are present but values are missing' do
+    it 'returns hash with nil values' do
+      expected = mismatched.merge(patient_status_id: nil)
+
+      subject.map!(mismatched)
+
+      expect(mismatched).to eq(expected)
+    end
+  end
+end

data/spec/hash_math/mapper_spec.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-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 'spec_helper'
+
+describe HashMath::Mapper do
+  let(:active)   { { id: 1, name: 'active' } }
+  let(:inactive) { { id: 2, name: 'inactive' } }
+  let(:archived) { { id: 3, name: 'archived' } }
+
+  let(:single)   { { id: 1, code: 'single' } }
+  let(:married)  { { id: 2, code: 'married' } }
+  let(:divorced) { { id: 3, code: 'divorced' } }
+
+  let(:patient_statuses) { [active, inactive, archived] }
+  let(:marital_statuses) { [single, married, divorced] }
+
+  subject do
+    described_class
+      .new(mappings)
+      .add_each(:patient_statuses, patient_statuses)
+      .add_each(:marital_statuses, marital_statuses)
+  end
+
+  let(:mappings) do
+    [
+      {
+        lookup: {
+          name: :patient_statuses,
+          by: :name
+        },
+        set: :patient_status_id,
+        value: :patient_status,
+        with: :id
+      },
+      {
+        lookup: {
+          name: :marital_statuses,
+          by: :code
+        },
+        set: :marital_status_id,
+        value: :marital_status,
+        with: :id
+      }
+    ]
+  end
+
+  let(:omitted) do
+    { patient_id: 1 }
+  end
+
+  let(:filled) do
+    { patient_id: 2, patient_status: 'active', marital_status: 'single' }
+  end
+
+  let(:mismatched) do
+    { patient_id: 2, patient_status: 'doesnt_exist', marital_status: 'no_exist' }
+  end
+
+  context 'when nil' do
+    it 'returns base mapped hash' do
+      expected = {
+        patient_status_id: nil,
+        marital_status_id: nil
+      }
+
+      actual = subject.map(nil)
+
+      expect(actual).to eq(expected)
+    end
+  end
+
+  context 'when keys are missing' do
+    it 'returns hash with nil values' do
+      expected = omitted.merge(
+        patient_status_id: nil,
+        marital_status_id: nil
+      )
+
+      actual = subject.map(omitted)
+
+      expect(actual).to eq(expected)
+    end
+  end
+
+  context 'when keys are present' do
+    it 'returns hash with values' do
+      expected = filled.merge(
+        patient_status_id: 1,
+        marital_status_id: 1
+      )
+
+      actual = subject.map(filled)
+
+      expect(actual).to eq(expected)
+    end
+  end
+
+  context 'when keys are present but values are missing' do
+    it 'returns hash with nil values' do
+      expected = mismatched.merge(
+        patient_status_id: nil,
+        marital_status_id: nil
+      )
+
+      actual = subject.map(mismatched)
+
+      expect(actual).to eq(expected)
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hash_math
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0.pre.alpha
 platform: ruby
 authors:
 - Matthew Ruggio
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-08-13 00:00:00.000000000 Z
+date: 2020-08-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: acts_as_hashable
@@ -160,6 +160,9 @@ files:
 - bin/console
 - hash_math.gemspec
 - lib/hash_math.rb
+- lib/hash_math/mapper.rb
+- lib/hash_math/mapper/lookup.rb
+- lib/hash_math/mapper/mapping.rb
 - lib/hash_math/matrix.rb
 - lib/hash_math/matrix/key_value_pair.rb
 - lib/hash_math/record.rb
@@ -168,6 +171,8 @@ files:
 - lib/hash_math/unpivot/pivot.rb
 - lib/hash_math/unpivot/pivot_set.rb
 - lib/hash_math/version.rb
+- spec/hash_math/mapper/mapping_spec.rb
+- spec/hash_math/mapper_spec.rb
 - spec/hash_math/matrix_spec.rb
 - spec/hash_math/record_spec.rb
 - spec/hash_math/table_spec.rb
@@ -189,15 +194,17 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '2.5'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: Hash-based data structures and algorithms
 test_files:
+- spec/hash_math/mapper/mapping_spec.rb
+- spec/hash_math/mapper_spec.rb
 - spec/hash_math/matrix_spec.rb
 - spec/hash_math/record_spec.rb
 - spec/hash_math/table_spec.rb