hash_math 0.0.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 634c0b1692a46994e23fc56cc31346a128182d19da45adaa8913d23898d91b5b
-  data.tar.gz: 7cf7a06c956965072b2dcb0dfe4e8bbccd962a44380c60289d9e9b377d7c8f6a
+  metadata.gz: a13830be433114e0438c34e2e15e136a01ab61c93b57c14e9be2b39a4dc9a7bf
+  data.tar.gz: 14a4d2765184d10f6149dd446be54f1cea68c505e308fbf884a982cecc0ad161
 SHA512:
-  metadata.gz: e5dfeff921d808b1f77d7e303a076ca5a6d3f50760fb7b9296332c443950679858c3498ba6e2629fbe13cdc5fbc5de5cc5c4a74d491299c434d14b529ef46a29
-  data.tar.gz: bc92933f546e34bdb244215e715a690db94cf3d85ff156e05c5383406ab831616162567b6862be89ad6e555d77a64504988f760e2b197825013d21e7e8966351
+  metadata.gz: b5294dee4cb58c9d28cc829b2d18a51edb6036bf110c2ad94bc827e52d80e6b7417cf96e5b699af812b91d6b9ee9be75e2ba2f796a65234e333f68f3fb587033
+  data.tar.gz: '0706231920aa50e791e43820e9544a399d132ff9f5a1ee29cd0fc2c70414ecb181d28350a4aa3f1b5df67bdf904dc93b876246cfdb4e53507e33358e1100de71'

data/.rubocop.yml

@@ -1,4 +1,8 @@
-Metrics/LineLength:
+AllCops:
+  TargetRubyVersion: 2.5
+  NewCops: enable
+
+Layout/LineLength:
   Max: 100
 
 Metrics/BlockLength:
@@ -13,9 +17,6 @@ Metrics/BlockLength:
 Metrics/MethodLength:
   Max: 25
 
-AllCops:
-  TargetRubyVersion: 2.3
-
 Metrics/AbcSize:
   Max: 16
 

data/.ruby-version

@@ -1 +1 @@
-2.6.3
+2.6.6

data/.travis.yml

@@ -4,10 +4,9 @@ env:
 language: ruby
 rvm:
   # Build on the latest stable of all supported Rubies (https://www.ruby-lang.org/en/downloads/):
-  - 2.3.8
-  - 2.4.6
-  - 2.5.5
-  - 2.6.3
+  - 2.5.8
+  - 2.6.6
+  - 2.7.1
 cache: bundler
 before_script:
   - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter

data/CHANGELOG.md

@@ -1,3 +1,31 @@
+# 1.2.0 (August 19th, 2020)
+
+Additions:
+
+* HashMath::Mapper
+
+# 1.1.0 (August 13th, 2020)
+
+Additions:
+
+* HashMath::Unpivot
+
+Removals:
+
+* Support for Ruby < 2.5
+
+# 1.0.0 (September 18th, 2019)
+
+Initial release.
+
+# 1.0.0-alpha (September 16th, 2019)
+
+Added initial implementation of:
+
+* HashMath::Matrix
+* HashMath::Record
+* HashMath::Table
+
 # 0.0.1 (September 16th, 2019)
 
 Published initial shell.  Library has no functionality yet.

data/README.md

@@ -2,4 +2,355 @@
 
 [![Gem Version](https://badge.fury.io/rb/hash_math.svg)](https://badge.fury.io/rb/hash_math) [![Build Status](https://travis-ci.org/bluemarblepayroll/hash_math.svg?branch=master)](https://travis-ci.org/bluemarblepayroll/hash_math) [![Maintainability](https://api.codeclimate.com/v1/badges/9f9a504b3f5df199a253/maintainability)](https://codeclimate.com/github/bluemarblepayroll/hash_math/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/9f9a504b3f5df199a253/test_coverage)](https://codeclimate.com/github/bluemarblepayroll/hash_math/test_coverage) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Under Construction.
+Ruby's Hash data structure is ubiquitous and highly flexible.  This library contains common Hash patterns widely used within our code-base:
+
+* Matrix: build a hash up then expand into hash products
+* Record: define a list of keys and a base value (for each key) to use as a blueprint for hashes
+* Table: key-value pair builder for constructing a two-dimensional array (rows by fields)
+
+See examples for more information on each data structure.
+
+## Installation
+
+To install through Rubygems:
+
+````bash
+gem install install hash_math
+````
+
+You can also add this to your Gemfile:
+
+````bash
+bundle add hash_math
+````
+
+## Examples
+
+### Matrix: The Hash Combination Calculator
+
+HashMath::Matrix is a key-value builder that outputs all the different hash combinations.
+
+Say we have this type of matrix:
+
+````ruby
+{
+  a: [1,2,3],
+  b: [4,5,6],
+  c: [7,8,9]
+}
+````
+
+We could code this as:
+
+````ruby
+matrix = HashMath::Matrix.new
+matrix.add_each(:a, [1,2,3])
+matrix.add_each(:b, [4,5,6])
+matrix.add_each(:c, [7,8,9])
+````
+
+Note: you can also call `Matrix#add` to only add a single value instead of add_each.
+
+and get the combinations by calling to_a:
+
+````ruby
+combinations = matrix.to_a
+````
+
+which would yield the following hashes:
+
+````ruby
+[
+  { a: 1, b: 4, c: 7 },
+  { a: 1, b: 4, c: 8 },
+  { a: 1, b: 4, c: 9 },
+  { a: 1, b: 5, c: 7 },
+  { a: 1, b: 5, c: 8 },
+  { a: 1, b: 5, c: 9 },
+  { a: 1, b: 6, c: 7 },
+  { a: 1, b: 6, c: 8 },
+  { a: 1, b: 6, c: 9 },
+
+  { a: 2, b: 4, c: 7 },
+  { a: 2, b: 4, c: 8 },
+  { a: 2, b: 4, c: 9 },
+  { a: 2, b: 5, c: 7 },
+  { a: 2, b: 5, c: 8 },
+  { a: 2, b: 5, c: 9 },
+  { a: 2, b: 6, c: 7 },
+  { a: 2, b: 6, c: 8 },
+  { a: 2, b: 6, c: 9 },
+
+  { a: 3, b: 4, c: 7 },
+  { a: 3, b: 4, c: 8 },
+  { a: 3, b: 4, c: 9 },
+  { a: 3, b: 5, c: 7 },
+  { a: 3, b: 5, c: 8 },
+  { a: 3, b: 5, c: 9 },
+  { a: 3, b: 6, c: 7 },
+  { a: 3, b: 6, c: 8 },
+  { a: 3, b: 6, c: 9 },
+]
+````
+
+Notes:
+
+* Matrix implements Ruby's Enumerable, which means you have the ability to iterate over each hash combination like you would any other Enumerable object.
+* Values can be arrays and it still works.  For example, `#add` (singular form) will honor the array data type: `matrix.add(:a, [1,2,3])` is **not** the same as: `matrix.add_each(:a, [1,2,3])` but it **is** the same as: `matrix.add(:a, [[1,2,3]])`
+* Keys are type-sensitive and work just like Hash keys work.
+
+### Record: The Hash Prototype
+
+HashMath::Record generates a prototype hash and ensures all derived hashes conform to its shape.
+
+Say we have a person hash, for example:
+
+````ruby
+{
+  id: 1,
+  name: 'Matt',
+  location: 'Chicago'
+}
+````
+
+we could create a record modeling this:
+
+````ruby
+record = HashMath::Record.new(%i[id name location], 'UNKNOWN')
+````
+
+Then, we could shape all other hashes using it to ensure each key is populated.  If a key is not populated, the base value will be used ('UNKNOWN' in our case.)  For example:
+
+````ruby
+records = [
+  record.make(id: 1, name: 'Matt', location: 'Chicago', dob: nil),
+  record.make(id: 2, age: 24),
+  record.make(id: 3, location: 'Los Angeles')
+]
+````
+
+Note: The keys `dob` and `age` appeared in the input but will be ignored as they do not conform to the Record.  You could make this strict and raise an error by calling `#make!` instead of `#make`.
+
+our `records` would now equate to:
+
+````ruby
+[
+  { id: 1, name: 'Matt', location: 'Chicago' },
+  { id: 2, name: 'UNKNOWN', location: 'UNKNOWN' },
+  { id: 3, name: 'UNKNOWN', location: 'Los Angeles' },
+]
+````
+
+Notes:
+
+* keys are type-sensitive and works just like Hash keys work.
+
+### Table: The Double Hash (Hash of Hashes)
+
+HashMath::Table builds on top of HashMath::Record.  It constructs a table data-structure using a key-value pair builder method: `#add(row_id, field_id, value)`.  It ultimately outputs an array of Row objects where each Row object has a row_id and fields (field_id => value) hash.  The value proposition here is you can iterate over a key-value pair and construct each row any way you wish.
+
+Building on our Record example above:
+
+````ruby
+record = HashMath::Record.new(%i[name location], 'UNKNOWN')
+
+table = HashMath::Table.new(record)
+                       .add(1, :name, 'Matt')
+                       .add(1, :location, 'Chicago')
+                       .add(2, :name, 'Nick')
+                       .add(3, :location, 'Los Angeles')
+                       .add(2, :name 'Nicholas') # notice the secondary call to "2, :name"
+
+rows = table.to_a
+````
+
+which would set our variable `rows` to:
+
+````ruby
+[
+  HashMath::Row.new(1, { name: 'Matt', location: 'Chicago' }),
+  HashMath::Row.new(2, { name: 'Nicholas', location: 'UNKNOWN' }),
+  HashMath::Row.new(3, { name: 'UNKNOWN', location: 'Los Angeles' })
+]
+````
+
+Notes:
+
+* `#add` will throw a KeyOutOfBoundsError if the key is not found.
+* key is type-sensitive and works just like Hash keys work.
+
+### Unpivot: Hash Key Coalescence and Row Extrapolation
+
+Sometimes the expected interface is column-based, but the actual data store is row-based.  This causes an impedance between the input set and the persistable data set.  HashMath::Unpivot has the ability to extrapolate one hash (row) into multiple hashes (rows) while unpivoting specific keys into key-value pairs.
+
+For example: say we have a database table persisting key-value pairs of patient attributes:
+
+patient_id | field           | value
+---------- | --------------- | ----------
+2          | first_exam_date | 2020-01-03
+2          | last_exam_date  | 2020-04-05
+2          | consent_date    | 2020-01-02
+
+But our input data looks like this:
+
+````ruby
+patient = {
+  patient_id: 2,
+  first_exam_date: '2020-01-03',
+  last_exam_date: '2020-04-05',
+  consent_date: '2020-01-02'
+}
+````
+
+We could use a HashMath::Unpivot to go from one hash to three hashes:
+
+````ruby
+pivot_set = {
+  pivots: [
+    {
+      keys: %i[first_exam_date last_exam_date consent_date],
+      coalesce_key: :field,
+      coalesce_key_value: :value
+    }
+  ]
+}
+
+rows = HashMath::Unpivot.new(pivot_set).perform(patient)
+````
+
+The `rows` variable should now be equivalent to:
+
+````ruby
+[
+  { patient_id: 2, field: :first_exam_date, value: '2020-01-03' },
+  { patient_id: 2, field: :last_exam_date,  value: '2020-04-05' },
+  { patient_id: 2, field: :consent_date,    value: '2020-01-02' }
+]
+````
+
+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
+
+Basic steps to take to get this repository compiling:
+
+1. Install [Ruby](https://www.ruby-lang.org/en/documentation/installation/) (check hash_math.gemspec for versions supported)
+2. Install bundler (gem install bundler)
+3. Clone the repository (git clone git@github.com:bluemarblepayroll/hash_math.git)
+4. Navigate to the root folder (cd hash_math)
+5. Install dependencies (bundle)
+
+### Running Tests
+
+To execute the test suite and code-coverage tool, run:
+
+````bash
+bundle exec rspec spec --format documentation
+````
+
+Alternatively, you can have Guard watch for changes:
+
+````bash
+bundle exec guard
+````
+
+Also, do not forget to run Rubocop:
+
+````bash
+bundle exec rubocop
+````
+
+or run all three in one command:
+
+````bash
+bundle exec rake
+````
+
+### Publishing
+
+Note: ensure you have proper authorization before trying to publish new versions.
+
+After code changes have successfully gone through the Pull Request review process then the following steps should be followed for publishing new versions:
+
+1. Merge Pull Request into master
+2. Update `lib/hash_math/version.rb` using [semantic versioning](https://semver.org/)
+3. Install dependencies: `bundle`
+4. Update `CHANGELOG.md` with release notes
+5. Commit & push master to remote and ensure CI builds master successfully
+6. Run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Code of Conduct
+
+Everyone interacting in this codebase, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/bluemarblepayroll/hash_math/blob/master/CODE_OF_CONDUCT.md).
+
+## License
+
+This project is MIT Licensed.

data/hash_math.gemspec

@@ -19,13 +19,16 @@ Gem::Specification.new do |s|
   s.homepage    = 'https://github.com/bluemarblepayroll/hash_math'
   s.license     = 'MIT'
 
-  s.required_ruby_version = '>= 2.3.8'
+  s.required_ruby_version = '>= 2.5'
+
+  s.add_dependency('acts_as_hashable', '~>1')
 
   s.add_development_dependency('guard-rspec', '~>4.7')
   s.add_development_dependency('pry', '~>0')
-  s.add_development_dependency('rake', '~> 12')
+  s.add_development_dependency('pry-byebug', '~>3')
+  s.add_development_dependency('rake', '~>13.0')
   s.add_development_dependency('rspec')
-  s.add_development_dependency('rubocop', '~>0.74.0')
-  s.add_development_dependency('simplecov', '~>0.17.0')
-  s.add_development_dependency('simplecov-console', '~>0.5.0')
+  s.add_development_dependency('rubocop', '~>0.88.0')
+  s.add_development_dependency('simplecov', '~>0.18.5')
+  s.add_development_dependency('simplecov-console', '~>0.7.0')
 end