attr-gather 1.0.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 Ian Ker-Seymer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,63 @@
+# attr-gather
+
+[![Actions Status](https://github.com/ianks/attr-gather/workflows/.github/workflows/ruby.yml/badge.svg)](https://github.com/ianks/attr-gather/actions)
+
+A gem for creating simple workflows to enhance entities with extra attributes.
+At a high level, `attr-gather` provides a process to sync attributes from many
+sources (third party APIs, legacy databases, etc).
+
+## Links
+
+- [API Documentation](https://www.rubydoc.info/gems/attr-gather)
+
+## Examples
+
+| [![SVG of Workflow](./examples/post_enhancer.svg)](./examples/post_enhancer.rb) |
+| :-----------------------------------------------------------------------------: |
+|  [Example of workflow that enhances a blog post](./examples/post_enhancer.rb)   |
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'attr-gather'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install attr-gather
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`rake spec` to run the tests. You can also run `bin/console` for an interactive
+prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To
+release a new version, update the version number in `version.rb`, and then 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).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/ianks/attr-gather. This project is intended to be a safe,
+welcoming space for collaboration, and contributors are expected to adhere to
+the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the [MIT
+License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Attr::Gather project’s codebases, issue trackers,
+chat rooms and mailing lists is expected to follow the [code of
+conduct](https://github.com/ianks/attr-gather/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+require 'yard'
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new(:lint)
+YARD::Rake::YardocTask.new(:doc)
+
+task default: %i[spec lint]
+
+namespace :examples do
+  desc 'Run all examples'
+  task :run do
+    Dir['examples/*.rb'].each do |filename|
+      system "ruby #{filename}"
+    end
+  end
+end

data/attr-gather.gemspec

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'attr/gather/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'attr-gather'
+  spec.version = Attr::Gather::VERSION
+  spec.authors = ['Ian Ker-Seymer']
+  spec.email = ['i.kerseymer@gmail.com']
+
+  spec.summary = 'Write a short summary, because RubyGems requires one.'
+  spec.description = 'Write a longer description or delete this line.'
+  spec.homepage = 'https://github.com/ianks/attr-gather'
+  spec.license = 'MIT'
+
+  # spec.metadata["allowed_push_host"] = "TODO: Set to 'http://mygemserver.com'"
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/ianks/attr-gather'
+  # spec.metadata["changelog_uri"] = "Put your gem's CHANGELOG.md URL here."
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 2.0'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+
+  spec.add_dependency 'dry-container', '~> 0.7'
+end

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'attr/gather'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/bin/solargraph

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'solargraph' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile',
+                                           Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path('bundle', __dir__)
+
+if File.file?(bundle_binstub)
+  if /This file was generated by Bundler/.match?(File.read(bundle_binstub, 300))
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('solargraph', 'solargraph')

data/examples/post_enhancer.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require 'dry-container'
+require 'dry-validation'
+require 'attr-gather'
+require 'http'
+
+# create the container
+class MyContainer
+  extend Dry::Container::Mixin
+
+  register :fetch_post do |id:, **_attrs|
+    res = HTTP.get("https://jsonplaceholder.typicode.com/posts/#{id}")
+    post = JSON.parse(res.to_s, symbolize_names: true)
+
+    { title: post[:title], user_id: post[:userId], body: post[:body] }
+  end
+
+  register :fetch_user_from_buggy_api do |*|
+    { user: { email: 'invalidemail' } }
+  end
+
+  register :fetch_user do |user_id:, **_attrs|
+    res = HTTP.get("https://jsonplaceholder.typicode.com/users/#{user_id}")
+    user = JSON.parse(res.to_s, symbolize_names: true)
+
+    { user: { name: user[:name], email: user[:email] } }
+  end
+
+  register :email_info do |user:, **_attrs|
+    res = HTTP.timeout(3).get("https://api.trumail.io/v2/lookups/json?email=#{user[:email]}")
+    info = JSON.parse(res.to_s, symbolize_names: true)
+
+    { user: { email_info: { deliverable: info[:deliverable], free: info[:free] } } }
+  end
+
+  register :gravatar_image do |user:, **_attrs|
+    require 'digest/md5'
+    email_address = user[:email].downcase
+    hash = Digest::MD5.hexdigest(email_address)
+    image_url = "https://www.gravatar.com/avatar/#{hash}"
+
+    { user: { gravatar: image_url } }
+  end
+end
+
+# define a workflow
+class EnhanceUserProfile
+  include Attr::Gather::Workflow
+
+  # contains all the task implementations
+  container MyContainer
+
+  # perform a deep merge of the task outputs for the result
+  aggregator :deep_merge
+
+  # filter out invalid values using a Dry::Validation::Contract
+  filter_with_contract do
+    params do
+      required(:user_id).filled(:integer)
+
+      optional(:user).hash do
+        optional(:name).filled(:string)
+        optional(:email).filled(:string)
+        optional(:gravatar).filled(:string)
+        optional(:email_info).hash do
+          optional(:deliverable).filled(:bool?)
+          optional(:free).filled(:bool?)
+        end
+      end
+    end
+  end
+
+  task :fetch_post do |t|
+    t.depends_on = []
+  end
+
+  task :fetch_user_from_buggy_api do |t|
+    t.depends_on = [:fetch_post]
+  end
+
+  task :fetch_user do |t|
+    t.depends_on = [:fetch_post]
+  end
+
+  # will run in parallel
+  task :email_info do |t|
+    t.depends_on = [:fetch_user]
+  end
+
+  # will run in parallel
+  task :gravatar_image do |t|
+    t.depends_on = [:fetch_user]
+  end
+end
+
+# run the workflow
+enhancer = EnhanceUserProfile.new
+
+puts
+puts 'Runing workflow...'
+puts
+puts 'Result'
+puts '======'
+pp enhancer.call(id: 12).value!
+
+# fun fact: you can preview as svg!
+puts
+print 'Would you like to preview the workflow as SVG? (y/n): '
+exit 0 unless gets.strip == 'y'
+
+begin
+  enhancer.to_dot(preview: true)
+rescue SignalException
+  puts 'Done!'
+rescue StandardError
+  abort 'Could not render SVG, please make sure you have ' \
+        'graphviz installed (brew install graphviz), then retry'
+end

data/examples/post_enhancer.svg

@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 2.43.20190912.0211 (20190912.0211)
+ -->
+<!-- Title: TaskGraph Pages: 1 -->
+<svg width="308pt" height="188pt"
+ viewBox="0.00 0.00 308.04 188.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 184)">
+<title>TaskGraph</title>
+<polygon fill="white" stroke="transparent" points="-4,4 -4,-184 304.04,-184 304.04,4 -4,4"/>
+<!-- fetch_post -->
+<g id="node1" class="node">
+<title>fetch_post</title>
+<ellipse fill="none" stroke="black" cx="136.84" cy="-162" rx="58.49" ry="18"/>
+<text text-anchor="middle" x="136.84" y="-158.3" font-family="Times,serif" font-size="14.00">fetch_post</text>
+</g>
+<!-- fetch_user -->
+<g id="node2" class="node">
+<title>fetch_user</title>
+<ellipse fill="none" stroke="black" cx="136.84" cy="-90" rx="59.29" ry="18"/>
+<text text-anchor="middle" x="136.84" y="-86.3" font-family="Times,serif" font-size="14.00">fetch_user</text>
+</g>
+<!-- fetch_post&#45;&gt;fetch_user -->
+<g id="edge1" class="edge">
+<title>fetch_post&#45;&gt;fetch_user</title>
+<path fill="none" stroke="black" d="M136.84,-143.7C136.84,-135.98 136.84,-126.71 136.84,-118.11"/>
+<polygon fill="black" stroke="black" points="140.34,-118.1 136.84,-108.1 133.34,-118.1 140.34,-118.1"/>
+</g>
+<!-- email_info -->
+<g id="node3" class="node">
+<title>email_info</title>
+<ellipse fill="none" stroke="black" cx="57.84" cy="-18" rx="57.69" ry="18"/>
+<text text-anchor="middle" x="57.84" y="-14.3" font-family="Times,serif" font-size="14.00">email_info</text>
+</g>
+<!-- fetch_user&#45;&gt;email_info -->
+<g id="edge2" class="edge">
+<title>fetch_user&#45;&gt;email_info</title>
+<path fill="none" stroke="black" d="M118.52,-72.76C108.15,-63.58 95.02,-51.94 83.62,-41.84"/>
+<polygon fill="black" stroke="black" points="85.87,-39.16 76.07,-35.15 81.23,-44.4 85.87,-39.16"/>
+</g>
+<!-- gravatar_image -->
+<g id="node4" class="node">
+<title>gravatar_image</title>
+<ellipse fill="none" stroke="black" cx="216.84" cy="-18" rx="83.39" ry="18"/>
+<text text-anchor="middle" x="216.84" y="-14.3" font-family="Times,serif" font-size="14.00">gravatar_image</text>
+</g>
+<!-- fetch_user&#45;&gt;gravatar_image -->
+<g id="edge3" class="edge">
+<title>fetch_user&#45;&gt;gravatar_image</title>
+<path fill="none" stroke="black" d="M155.4,-72.76C165.75,-63.71 178.82,-52.27 190.24,-42.28"/>
+<polygon fill="black" stroke="black" points="192.61,-44.85 197.84,-35.63 188,-39.58 192.61,-44.85"/>
+</g>
+</g>
+</svg>

data/lib/attr-gather.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'attr/gather'

data/lib/attr/gather.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'attr/gather/version'
+
+module Attr
+  module Gather
+    class Error < StandardError; end
+    # Your code goes here...
+
+    EMPTY_HASH = {}.freeze
+  end
+end
+
+require 'attr/gather/workflow'
+require 'attr/gather/aggregators'
+require 'attr/gather/filters'

data/lib/attr/gather/aggregators.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'attr/gather/concerns/registrable'
+
+module Attr
+  module Gather
+    # Namespace for aggregators
+    module Aggregators
+      extend Registrable
+
+      # The default aggregator if none is specified
+      #
+      # @return [Attr::Gather::Aggregators::DeepMerge]
+      def self.default
+        @default = resolve(:deep_merge)
+      end
+
+      register(:deep_merge) do |*args|
+        require 'attr/gather/aggregators/deep_merge'
+
+        DeepMerge.new(*args)
+      end
+
+      register(:shallow_merge) do |*args|
+        require 'attr/gather/aggregators/shallow_merge'
+
+        ShallowMerge.new(*args)
+      end
+    end
+  end
+end

data/lib/attr/gather/aggregators/base.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Attr
+  module Gather
+    module Aggregators
+      # @abstract Subclass and override {#call} to implement
+      #   a custom Aggregator class.
+      #
+      # @!attribute [r] filter
+      #   @return [Attr::Gather::Filters::Base] filter for the output data
+      class Base
+        attr_accessor :filter
+
+        def initialize(**opts)
+          @filter = opts.delete(:filter)
+        end
+
+        def call(_original_input, _results_array)
+          raise NotImplementedError
+        end
+
+        private
+
+        def wrap_result(result)
+          Concurrent::Promise.fulfill(result)
+        end
+
+        def unwrap_result(res)
+          unvalidated = res.result.value!
+
+          return unvalidated if filter.nil?
+
+          filter.call(unvalidated).value
+        end
+      end
+    end
+  end
+end