reforge 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b3954966aa5b1027a05381e015a54986920c1e08af4f92ea4cbbee550ec9547e
+  data.tar.gz: e9fd17106ca7608a4e1ee47a0b19e9d22e8fe300b098e5edac9b6f4a47451ae8
+SHA512:
+  metadata.gz: 5c287390d5e5016dae3b0f30d0251c3b91ee8690b2f067674d550a156e8725b9c3c0b5b902794cda7d170fd6ce2e929c20dd2a273103b15af5dbd0d87637c119
+  data.tar.gz: 438364630d684abe90326e6aadd263687b504ccbd9b09f741849b5fd3462a0af6a77033902a1d4321b20c4b70c1196f85da3ff7ad61f1762365afad5cb3579eb

data/.github/workflows/ci.yml

@@ -0,0 +1,76 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+    - main
+
+env:
+  BUNDLE_PATH: vendor/bundle
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: 2.6.6
+    - name: Cache dependencies
+      id: cache-dependencies
+      uses: actions/cache@v2
+      with:
+        path: ${{ env.BUNDLE_PATH }}
+        key: ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile.lock') }}
+        restore-keys:  ${{ runner.os }}-gems-
+    - name: Install dependencies
+      if: steps.cache-dependencies.outputs.cache-hit != 'true'
+      run: bundle install --jobs 20 --retry 5
+    - name: Lint files
+      run: bundle exec rake rubocop
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 2
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: 2.6.6
+    - name: Cache dependencies
+      id: cache-dependencies
+      uses: actions/cache@v2
+      with:
+        path: ${{ env.BUNDLE_PATH }}
+        key: ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile.lock') }}
+        restore-keys:  ${{ runner.os }}-gems-
+    - name: Download test reporter
+      run: |
+        curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
+        chmod +x ./cc-test-reporter
+    - name: Notify of pending report
+      run: ./cc-test-reporter before-build
+    - name: Install dependencies
+      if: steps.cache-dependencies.outputs.cache-hit != 'true'
+      run: bundle install --jobs 20 --retry 5
+    - name: Run tests
+      run: bundle exec rake rspec
+    - name: Publish code coverage
+      # TRICKY: We need to manually set the env vars required by Code Climate. GIT_BRANCH is simple to determine, but
+      # GIT_COMMIT_SHA is context dependent:
+      # - When running actions on main when it is pushed we can simply use GITHUB_SHA
+      # - When running actions on a pull request actions/checkout@v2 creates a merge commit, so GITHUB_SHA is one
+      #   commit ahead. We use the log to determine GIT_COMMIT_SHA by looking at the second parent of the merge commit,
+      #   and set actions/checkout@v2's fetch-depth to 2 above to ensure that the commit is available
+      # (ref: https://docs.codeclimate.com/docs/github-actions-test-coverage)
+      run: |
+        export GIT_BRANCH="${GITHUB_HEAD_REF}"
+        if [ $GITHUB_EVENT_NAME == "pull_request" ]
+        then
+          export GIT_COMMIT_SHA="$(git log --pretty=%P -n 1 "${GITHUB_SHA}" | cut -d' ' -f2)"
+        else
+          export GIT_COMMIT_SHA="${GITHUB_SHA}"
+        fi
+        ./cc-test-reporter after-build -r ${{secrets.CC_TEST_REPORTER_ID}}

data/.gitignore

@@ -0,0 +1,13 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+
+reforge-*.gem

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,13 @@
+require: rubocop-performance
+
+# overrides
+Style/Documentation:
+  Enabled: false
+Style/MutableConstant:
+  EnforcedStyle: strict
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+# opt-in new cops
+AllCops:
+  NewCops: enable

data/.ruby-version

@@ -0,0 +1 @@
+2.6.6

data/.tool-versions

@@ -0,0 +1 @@
+ruby 2.6.6

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at eizengan@gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in reforge.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,89 @@
+PATH
+  remote: .
+  specs:
+    reforge (0.1.0)
+      zeitwerk (~> 2.4)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.1)
+    attr_extras (6.2.4)
+    byebug (11.1.3)
+    coderay (1.1.3)
+    diff-lcs (1.3)
+    docile (1.3.2)
+    json (2.3.1)
+    method_source (1.0.0)
+    parallel (1.19.2)
+    parser (2.7.2.0)
+      ast (~> 2.4.1)
+    patience_diff (1.1.0)
+      trollop (~> 1.16)
+    pry (0.13.1)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    pry-byebug (3.9.0)
+      byebug (~> 11.0)
+      pry (~> 0.13.0)
+    rainbow (3.0.0)
+    rake (12.3.3)
+    regexp_parser (1.8.2)
+    rexml (3.2.4)
+    rspec (3.9.0)
+      rspec-core (~> 3.9.0)
+      rspec-expectations (~> 3.9.0)
+      rspec-mocks (~> 3.9.0)
+    rspec-core (3.9.2)
+      rspec-support (~> 3.9.3)
+    rspec-expectations (3.9.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.9.0)
+    rspec-mocks (3.9.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.9.0)
+    rspec-support (3.9.3)
+    rubocop (1.1.0)
+      parallel (~> 1.10)
+      parser (>= 2.7.1.5)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8)
+      rexml
+      rubocop-ast (>= 1.0.1)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 2.0)
+    rubocop-ast (1.1.0)
+      parser (>= 2.7.1.5)
+    rubocop-performance (1.8.1)
+      rubocop (>= 0.87.0)
+      rubocop-ast (>= 0.4.0)
+    ruby-progressbar (1.10.1)
+    simplecov (0.17.1)
+      docile (~> 1.1)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.2)
+    super_diff (0.5.2)
+      attr_extras (>= 6.2.4)
+      diff-lcs
+      patience_diff
+    trollop (1.16.2)
+    unicode-display_width (1.7.0)
+    zeitwerk (2.4.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 2.0)
+  pry-byebug (~> 3.9)
+  rake (~> 12.0)
+  reforge!
+  rspec (~> 3.0)
+  rubocop (~> 1.0)
+  rubocop-performance (~> 1.8)
+  simplecov (~> 0.17.1)
+  super_diff (~> 0.5)
+
+BUNDLED WITH
+   2.1.4

data/INTRODUCTION.md

@@ -0,0 +1,274 @@
+# Introduction
+
+This guide outlines the basic knowledge required to use Reforge in a project. Navigation links for the guide are provided below for your convenience.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Getting Started](#getting-started)
+- [Terminology](#terminology)
+- [The Transformation DSL](#the-transformation-dsl)
+- [Defining Paths](#defining-paths)
+- [Defining Transforms](#defining-transforms)
+  - [Attribute Configuration Hashes](#attribute-configuration-hashes)
+  - [Key Configuration Hashes](#key-configuration-hashes)
+  - [Nil Propogation](#nil-propogation)
+  - [Value Configuration Hashes](#value-configuration-hashes)
+- [Memoizing Transform Results](#memoizing-transform-results)
+  - [Memo Lifetime](#memo-lifetime)
+  - [Simple Memoization](#simple-memoization)
+  - [Calculating A Transform Only Once](#calculating-a-transform-only-once)
+  - [Custom Memoization](#custom-memoization)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'reforge'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install reforge
+
+## Terminology
+
+**Transformation** : The most crucial class provided by Reforge. Provides a simple DSL to define one or more *Pathed Transforms*, and uses them to convert a *Source* into a *Result*.
+
+**Pathed Transform** : A pairing of a *Transform* and a *Path*. Describes both how to obtain a value from a *Source* and a location to place it within the *Result*.
+
+**Transform** : A description of how to obtain a single, transformed value from a *Source*.
+
+**Path** : A description of a location within a *Result*. Typically a Symbol/String key when the *Result* is a Hash, or an Integer index when the *Result* is an Array.
+
+**Source** : An object which a *Transformation* can convert into a *Result*. Can be any object, but all the *Transformation's* constituent *Transforms* must succeed when processing it.
+
+**Result** : The object created by a *Transformation* from a *Source* by aggregating the output of all its *Pathed Transforms*.
+
+## Getting Started
+
+The following example illustrates how to create a Transformation and transform your data:
+
+```ruby
+require "reforge"
+require "date"
+
+def expensive_method
+  puts "expensive_method was called, but only once!"
+  sleep(10)
+  "hello world"
+end
+
+class ExampleTransformation < Reforge::Transformation
+  extract :date, from: ->(source) { Date.parse(source[:timestamp]) }
+  extract :amount, from: { key: :usd }
+  extract :expensive_result, from: -> { expensive_method }, memoize: :first
+end
+
+sources = [
+  { timestamp: "2019-01-01", usd: 1.23 },
+  { timestamp: "2019-01-10", usd: 2.46 },
+  { timestamp: "2019-10-01", usd: 3.69 }
+]
+results = ExampleTransformation.call(*sources)
+# expensive_method was called, but only once!
+# => [{:date=>#<Date: 2019-01-01 ...>, :amount=>1.23, :expensive_result=>"hello world"},
+#     {:date=>#<Date: 2019-01-10 ...>, :amount=>2.46, :expensive_result=>"hello world"},
+#     {:date=>#<Date: 2019-10-01 ...>, :amount=>3.69, :expensive_result=>"hello world"}]
+```
+
+You can glean the following from the above example:
+
+- Transformations are created by inheriting the `Reforge::Transformation` class
+- The Result of a Transformation is described in parts by using the `.extract` DSL method
+- The `.extract` DSL method takes a Path to determine where in the Result to place transformed Source data
+- The `.extract` DSL method takes a `from:` keyword argument to determine a Transform to perform on the Source data
+- Transforms of Source data can be defined by a proc or derived from a special configuration hash
+- The `.extract` DSL method takes an optional `memoize:` keyword argument which can sometimes be used to avoid repeating expensive Transforms
+
+These are all described in greater detail below, and are linked in the [Table of Contents](#table-of-contents).
+
+## The Transformation DSL
+
+Inheriting from the `Reforge::Transformation` class grants access to the DSL methods outlined in the example below:
+
+```ruby
+class DSLExamples < Reforge::Transformation
+  extract path_definition, from: transform_definition, memoize: memoize_options
+  transform transform_definition, into: path_definition, memoize: memoize_options
+end
+```
+
+The `.extract` and `.transform` methods are used to define Pathed Transforms, and cause identical results when given the same arguments (as above). You may use whichever method better suits your use case, although this documentation prefers `.extract`. The path_definition must [define a valid Path](#defining-paths). The transform_definition must [define a valid Transform](#defining-transforms). The memoize parameter is optional, and when included is used to [avoid repeating expensive Transforms](#memoizing-transform-results).
+
+Errors resulting from improper usage of the DSL are not raised immediately. Instead they are deferred until the Transformation containing the improper DSL calls is instantiated or otherwise used. This ensures an application using Reforge will not break outside contexts where improper DSL usage could adversely affect its behavior.
+
+## Defining Paths
+
+Paths are used by Reforge to determine where in the Result to place transformed Source data. They are also used to determine what type the Result will take - a path of `:key` or `"key"` will result in a Hash, and `0` in an Array. A Path with Array type can be used when values should be nested within a series of Hashes and Arrays; the regular type deduction rules will be applied in order. The following examples illustrate what happens when the string `"data"` is placed using the path definitions shown:
+
+```ruby
+path = :foo        # result = { foo: "data" }
+path = "foo"       # result = { "foo" => "data" }
+path = 0           # result = ["data"]
+path = [:foo, 0]   # result = { foo: ["data"] }
+path = %i[foo bar] # result = { foo: { bar: "data" } }
+```
+
+## Defining Transforms
+
+Transforms are used by Reforge to determine how to obtain a single, transformed value from a Source. A Transform can be a Proc which takes the Source as an argument or a Proc which takes no arguments. For some simple Transforms a Configuration Hash can be used instead.
+
+### Transform Configuration Hashes
+
+#### Key Configuration Hashes
+
+If the data you need from a Source exists inside nested Hash- or Array-like objects, then you can use a Transform defined by a key configuration hash to obtain it. The pairs of Transforms below will produce the same results:
+```ruby
+transform = ->(source) { source[:foo] }
+transform = { key: :foo }
+
+nested_transform = ->(source) { source[:foo][1] }
+nested_transform = { key: [:foo, 1] }
+```
+
+#### Attribute Configuration Hashes
+
+Similarly if the data you need lies at the end of a series of attribute calls, then you can use an attribute configuration hash to obtain it. The pairs of Transforms below will produce the same results:
+```ruby
+transform = ->(source) { source.size }
+transform = { attribute: :size }
+
+nested_transform = ->(source) { source.size.digits }
+nested_transform = { attribute: %i[size digits] }
+
+```
+
+#### Nil Propogation
+
+The Transforms made by key and attribute configuration hashes will raise an error if they hit a nil value partway through the array of keys or attributes they have been instructed to traverse. To avoid this, you may pass the option `propogate_nil: true`. These Transforms will produce the same results:
+```ruby
+transform = ->(source) { source&.size&.digits }
+transform = { attribute: %i[size digits], propogate_nil: true }
+```
+
+#### Value Configuration Hashes
+
+Sometimes the data you need to add to a Result is independent of the Source and will not change. In such cases you can use a value configuration hash. These Transforms will produce the same results:
+```ruby
+transform = -> { 1_234_567 }
+transform = { value: 1_234_567 }
+```
+
+## Memoizing Transform Results
+
+There may be occasions where your Transforms are expensive either in the time required to precess them or their resource use. The initial cost of these Transforms may be unavoidable, but by memoizing the Transform results you can avoid incurring it when the Transform is repeated. By specifying what criteria qualify as "repitition", you can tailor memoization perfectly to your use case.
+
+### Memo Lifetime
+
+Memoized results will last as long as the Transformation that uses them. For calls directly against the class this duration is equal the duration of the call, and for calls against a Transformation instance it is equal the lifetime of that instance:
+
+```ruby
+class ExampleTransformation < Reforge::Transformation
+  extract :expensive_result, from: -> { expensive_method }, memoize: :true
+end
+
+# The memo used in this call lasts only for the duration of that call - future calls are unaffected
+ExampleTransformation.call(*sources)
+
+
+# A Transformation instance keeps its memo between calls...
+transformation = ExampleTransformation.new
+transform.call(*sources)
+# ...so since all the sources have already been memoized by the call above, the call below only ever uses the
+# memoized results
+transform.call(*sources)
+```
+
+### Simple Memoization
+
+Basic memoization is performed by providing the `memoize: true` option to the DSL's Transform creation methods. This style of memoization stores the Transform result by its source, and future calls will use this result instead of recalculating it:
+
+```ruby
+def expensive_method(i)
+  puts "expensive_method was called!"
+  sleep(10)
+  "result for #{i}"
+end
+
+class ExampleTransformation < Reforge::Transformation
+  extract :expensive_result, from: ->(i) { expensive_method(i) }, memoize: :true
+end
+
+sources = [1, 1]
+results = ExampleTransformation.call(*sources)
+# expensive_method was called!
+# => [{:expensive_result=>"result for 1"},
+#     {:expensive_result=>"result for 1"}]
+
+sources = [1, 2, 2]
+results = ExampleTransformation.call(*sources)
+# expensive_method was called!
+# expensive_method was called!
+# => [{:expensive_result=>"result for 1"},
+#     {:expensive_result=>"result for 2"},
+#     {:expensive_result=>"result for 2"}]
+```
+
+### Calculating A Transform Only Once
+
+You may find cases where you only need to calculate the results of a Transform once. As an example, you may want to add a timestamp depicting when the Transformation was called to the Result. This can be done by supplying the DSL's Transform creation methods with the `memoize: :first` option. This stores the first value for the first Transform call, and will continue using it for all future calls regardless of the Source:
+
+```ruby
+def current_time
+  puts "calculating current time"
+  Time.now
+end
+
+class ExampleTransformation < Reforge::Transformation
+  extract :timestamp, from: -> { current_time }, memoize: :first
+end
+
+sources = [*1..5]
+results = ExampleTransformation.call(*sources)
+# calculating current time
+# => [{:timestamp=>2020-12-10 18:29:52 -0500},
+#     {:timestamp=>2020-12-10 18:29:52 -0500},
+#     {:timestamp=>2020-12-10 18:29:52 -0500},
+#     {:timestamp=>2020-12-10 18:29:52 -0500},
+#     {:timestamp=>2020-12-10 18:29:52 -0500}]
+```
+
+### Custom Memoization
+
+You may create your own memoization schemes in cases where memoization is required but none of the built-in schemes will work. As an example, perhaps an attribute of the source contains a substring which corresponds to an ID in your database; in other words: the transform result should be memoized by that substring, not by the source itself. This can be accomplished by providing a configuration hash to the memoize option, such as `memoize: { by: ->(s) { s.id_attr[0..10] } }`. This configuration hash must contain the `:by` key, which must contain a [valid transform definition](#defining-transforms) - either a Proc or a configuration hash. When the transform specified at the `:by` key results in a value which was already calculated, then the memoized transform will return the stored result:
+
+```ruby
+def find_customer(customer_id)
+  puts "finding customer with id='#{id}'"
+  Customer.find(customer_id)
+end
+
+class ExampleTransformation < Reforge::Transformation
+  extract :customer,
+          from: ->(source) { find_customer(source[:purchase_order].split("-").first) },
+          memoize: { by: ->(source) { source[:purchase_order].split("-").first } }
+end
+
+sources = [
+  { purchase_order: "123-2020-12-01" },
+  { purchase_order: "123-2020-12-02" },
+  { purchase_order: "456-2020-12-01" }
+]
+results = ExampleTransformation.call(*sources)
+# finding customer with id='123'
+# finding customer with id='456'
+# => [{:customer=>#<Retailer id: 123, ...>,
+#     {:customer=>#<Retailer id: 123, ...>,
+#     {:customer=>#<Retailer id: 456, ...>]
+```