dry-transformer 0.1.0

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+task default: :spec
+
+RSpec::Core::RakeTask.new(:spec)

data/docsite/source/built-in-transformations.html.md

@@ -0,0 +1,47 @@
+---
+title: Built-in transformation
+layout: gem-single
+name: dry-transformer
+---
+
+`dry-transformer` comes with a lot of built-in functions. They come in the form of modules with class methods, which you can import into a registry:
+
+* [Coercions](https://www.rubydoc.info/gems/dry-transformer/Dry/Transformer/Coercions)
+* [Array transformations](https://www.rubydoc.info/gems/dry-transformer/Dry/Transformer/ArrayTransformations)
+* [Hash transformations](https://www.rubydoc.info/gems/dry-transformer/Dry/Transformer/HashTransformations)
+* [Class transformations](https://www.rubydoc.info/gems/dry-transformer/Dry/Transformer/ClassTransformations)
+* [Proc transformations](https://www.rubydoc.info/gems/dry-transformer/Dry/Transformer/ProcTransformations)
+* [Conditional](https://www.rubydoc.info/gems/dry-transformer/Dry/Transformer/Conditional)
+* [Recursion](https://www.rubydoc.info/gems/dry-transformer/Dry/Transformer/Recursion)
+
+You can import everything with:
+
+```ruby
+module T
+  extend Dry::Transformer::Registry
+
+  import Dry::Transformer::Coercions
+  import Dry::Transformer::ArrayTransformations
+  import Dry::Transformer::HashTransformations
+  import Dry::Transformer::ClassTransformations
+  import Dry::Transformer::ProcTransformations
+  import Dry::Transformer::Conditional
+  import Dry::Transformer::Recursion
+end
+
+T[:to_string].(:abc) # => 'abc'
+```
+
+Or import selectively with:
+
+```ruby
+module T
+  extend Dry::Transformer::Registry
+
+  import :to_string, from: Dry::Transformer::Coercions, as: :stringify
+end
+
+T[:stringify].(:abc) # => 'abc'
+T[:to_string].(:abc)
+# => Dry::Transformer::FunctionNotFoundError: No registered function T[:to_string]
+```

data/docsite/source/index.html.md

@@ -0,0 +1,15 @@
+---
+title: Introduction
+description: Data transformation toolkit
+layout: gem-single
+type: gem
+name: dry-transformer
+sections:
+  - transformation-objects
+  - built-in-transformations
+  - using-standalone-functions
+---
+
+dry-transformer is a library that allows you to compose procs into a functional pipeline using left-to-right function composition.
+
+The approach came from Functional Programming, where simple functions are composed into more complex functions in order to transform some data. It works like `|>` in Elixir or `>>` in F#. dry-transformer provides a mechanism to define and compose transformations, along with a number of built-in transformations.

data/docsite/source/transformation-objects.html.md

@@ -0,0 +1,32 @@
+---
+title: Transformation objects
+name: dry-transformer
+layout: gem-single
+---
+
+You can define transformation classes using the DSL which converts every method call to its corresponding transformation, and composes these transformations into a transformation pipeline. Here's a simple example where the default registry is used:
+
+```ruby
+class MyMapper < Dry::Transformer[Dry::Transformer::Registry]
+  define! do
+    map_array do
+      symbolize_keys
+      rename_keys user_name: :name
+      nest :address, [:city, :street, :zipcode]
+    end
+  end
+end
+
+mapper = MyMapper.new
+
+mapper.(
+  [
+    { 'user_name' => 'Jane',
+      'city' => 'NYC',
+      'street' => 'Street 1',
+      'zipcode' => '123'
+    }
+  ]
+)
+# => [{:name=>"Jane", :address=>{:city=>"NYC", :street=>"Street 1", :zipcode=>"123"}}]
+```

data/docsite/source/using-standalone-functions.html.md

@@ -0,0 +1,82 @@
+---
+title: Using standalone functions
+name: dry-transformer
+layout: gem-single
+---
+
+You can use `dry-transformer` and its function registry feature stand-alone, without the need to define transformation classes. To do so, simply define a module and extend it with the registry API:
+
+``` ruby
+require 'json'
+require 'dry/transformer/all'
+
+# create your own local registry for transformation functions
+module Functions
+  extend Dry::Transformer::Registry
+end
+
+# import necessary functions from other transprocs...
+module Functions
+  # import all singleton methods from a module/class
+  import Dry::Transformer::HashTransformations
+  import Dry::Transformer::ArrayTransformations
+end
+
+# ...or from any external library
+require 'dry-inflector'
+
+Inflector = Dry::Inflector.new
+
+module Functions
+  # import only necessary singleton methods from a module/class
+  # and rename them locally
+  import :camelize, from: Inflector, as: :camel_case
+end
+
+def t(*args)
+  Functions[*args]
+end
+
+# use imported transformation
+transformation = t(:camel_case)
+
+transformation.call 'i_am_a_camel'
+# => "IAmACamel"
+
+transformation = t(:map_array, (
+  t(:symbolize_keys).>> t(:rename_keys, user_name: :user)
+  )).>> t(:wrap, :address, [:city, :street, :zipcode])
+
+transformation.call(
+  [
+    { 'user_name' => 'Jane',
+      'city' => 'NYC',
+      'street' => 'Street 1',
+      'zipcode' => '123' }
+  ]
+)
+# => [{:user=>"Jane", :address=>{:city=>"NYC", :street=>"Street 1", :zipcode=>"123"}}]
+
+# define your own composable transformation easily
+transformation = t(-> v { JSON.dump(v) })
+
+transformation.call(name: 'Jane')
+# => "{\"name\":\"Jane\"}"
+
+# ...or add it to registered functions via singleton method of the registry
+module Functions
+  # ...
+
+  def self.load_json(v)
+    JSON.load(v)
+  end
+end
+
+# ...or add it to registered functions via .register method
+Functions.register(:load_json) { |v| JSON.load(v) }
+
+transformation = t(:load_json) >> t(:map_array, t(:symbolize_keys))
+
+transformation.call('[{"name":"Jane"}]')
+# => [{ :name => "Jane" }]
+```

data/dry-transformer.gemspec

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'dry/transformer/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'dry-transformer'
+  spec.version       = Dry::Transformer::VERSION.dup
+  spec.authors       = ['Piotr Solnica']
+  spec.email         = ['piotr.solnica@gmail.com']
+  spec.summary       = 'Data transformation toolkit'
+  spec.description   = spec.summary
+  spec.homepage      = 'https://dry-rb.org/gems/dry-transformer/'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+  spec.required_ruby_version = '>= 2.3.0'
+end

data/lib/dry-transformer.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'dry/transformer'

data/lib/dry/transformer.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'dry/transformer/version'
+require 'dry/transformer/constants'
+require 'dry/transformer/function'
+require 'dry/transformer/error'
+require 'dry/transformer/store'
+require 'dry/transformer/registry'
+
+require 'dry/transformer/array'
+require 'dry/transformer/hash'
+
+require 'dry/transformer/pipe'
+
+module Dry
+  module Transformer
+    # @api public
+    # @see Pipe.[]
+    def self.[](registry)
+      Pipe[registry]
+    end
+  end
+end

data/lib/dry/transformer/all.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'dry/transformer'
+
+require 'dry/transformer/class'
+require 'dry/transformer/coercions'
+require 'dry/transformer/conditional'
+require 'dry/transformer/array'
+require 'dry/transformer/hash'
+require 'dry/transformer/proc'
+require 'dry/transformer/recursion'

data/lib/dry/transformer/array.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require 'dry/transformer/coercions'
+require 'dry/transformer/hash'
+require 'dry/transformer/array/combine'
+
+module Dry
+  module Transformer
+    # Transformation functions for Array objects
+    #
+    # @example
+    #   require 'dry/transformer/array'
+    #
+    #   include Dry::Transformer::Helper
+    #
+    #   fn = t(:map_array, t(:symbolize_keys)) >> t(:wrap, :address, [:city, :zipcode])
+    #
+    #   fn.call(
+    #     [
+    #       { 'city' => 'Boston', 'zipcode' => '123' },
+    #       { 'city' => 'NYC', 'zipcode' => '312' }
+    #     ]
+    #   )
+    #   # => [{:address=>{:city=>"Boston", :zipcode=>"123"}}, {:address=>{:city=>"NYC", :zipcode=>"312"}}]
+    #
+    # @api public
+    module ArrayTransformations
+      extend Registry
+
+      # Map array values using transformation function
+      #
+      # @example
+      #
+      #   fn = Dry::Transformer(:map_array, -> v { v.upcase })
+      #
+      #   fn.call ['foo', 'bar'] # => ["FOO", "BAR"]
+      #
+      # @param [Array] array The input array
+      # @param [Proc] fn The transformation function
+      #
+      # @return [Array]
+      #
+      # @api public
+      def self.map_array(array, fn)
+        Array(array).map { |value| fn[value] }
+      end
+
+      # Wrap array values using HashTransformations.nest function
+      #
+      # @example
+      #   fn = Dry::Transformer(:wrap, :address, [:city, :zipcode])
+      #
+      #   fn.call [{ city: 'NYC', zipcode: '123' }]
+      #   # => [{ address: { city: 'NYC', zipcode: '123' } }]
+      #
+      # @param [Array] array The input array
+      # @param [Object] key The nesting root key
+      # @param [Object] keys The nesting value keys
+      #
+      # @return [Array]
+      #
+      # @api public
+      def self.wrap(array, key, keys)
+        nest = HashTransformations[:nest, key, keys]
+        array.map { |element| nest.call(element) }
+      end
+
+      # Group array values using provided root key and value keys
+      #
+      # @example
+      #   fn = Dry::Transformer(:group, :tags, [:tag])
+      #
+      #   fn.call [
+      #     { task: 'Group it', tag: 'task' },
+      #     { task: 'Group it', tag: 'important' }
+      #   ]
+      #   # => [{ task: 'Group it', tags: [{ tag: 'task' }, { tag: 'important' }]]
+      #
+      # @param [Array] array The input array
+      # @param [Object] key The nesting root key
+      # @param [Object] keys The nesting value keys
+      #
+      # @return [Array]
+      #
+      # @api public
+      def self.group(array, key, keys)
+        grouped = Hash.new { |h, k| h[k] = [] }
+        array.each do |hash|
+          hash = Hash[hash]
+
+          old_group = Coercions.to_tuples(hash.delete(key))
+          new_group = keys.inject({}) { |a, e| a.merge(e => hash.delete(e)) }
+
+          grouped[hash] << old_group.map { |item| item.merge(new_group) }
+        end
+        grouped.map do |root, children|
+          root.merge(key => children.flatten)
+        end
+      end
+
+      # Ungroup array values using provided root key and value keys
+      #
+      # @example
+      #   fn = Dry::Transformer(:ungroup, :tags, [:tag])
+      #
+      #   fn.call [
+      #     { task: 'Group it', tags: [{ tag: 'task' }, { tag: 'important' }] }
+      #   ]
+      #   # => [
+      #     { task: 'Group it', tag: 'task' },
+      #     { task: 'Group it', tag: 'important' }
+      #   ]
+      #
+      # @param [Array] array The input array
+      # @param [Object] key The nesting root key
+      # @param [Object] keys The nesting value keys
+      #
+      # @return [Array]
+      #
+      # @api public
+      def self.ungroup(array, key, keys)
+        array.flat_map { |item| HashTransformations.split(item, key, keys) }
+      end
+
+      def self.combine(array, mappings)
+        Combine.combine(array, mappings)
+      end
+
+      # Converts the array of hashes to array of values, extracted by given key
+      #
+      # @example
+      #   fn = t(:extract_key, :name)
+      #   fn.call [
+      #     { name: 'Alice', role: 'sender' },
+      #     { name: 'Bob', role: 'receiver' },
+      #     { role: 'listener' }
+      #   ]
+      #   # => ['Alice', 'Bob', nil]
+      #
+      # @param [Array<Hash>] array The input array of hashes
+      # @param [Object] key The key to extract values by
+      #
+      # @return [Array]
+      #
+      # @api public
+      def self.extract_key(array, key)
+        map_array(array, ->(v) { v[key] })
+      end
+
+      # Wraps every value of the array to tuple with given key
+      #
+      # The transformation partially inverses the `extract_key`.
+      #
+      # @example
+      #   fn = t(:insert_key, 'name')
+      #   fn.call ['Alice', 'Bob', nil]
+      #   # => [{ 'name' => 'Alice' }, { 'name' => 'Bob' }, { 'name' => nil }]
+      #
+      # @param [Array<Hash>] array The input array of hashes
+      # @param [Object] key The key to extract values by
+      #
+      # @return [Array]
+      #
+      # @api public
+      def self.insert_key(array, key)
+        map_array(array, ->(v) { { key => v } })
+      end
+
+      # Adds missing keys with nil value to all tuples in array
+      #
+      # @param [Array] keys
+      #
+      # @return [Array]
+      #
+      # @api public
+      #
+      def self.add_keys(array, keys)
+        base = keys.inject({}) { |a, e| a.merge(e => nil) }
+        map_array(array, ->(v) { base.merge(v) })
+      end
+    end
+  end
+end

data/lib/dry/transformer/array/combine.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Dry
+  module Transformer
+    module ArrayTransformations
+      class Combine
+        EMPTY_ARRAY = [].freeze
+
+        class << self
+          def combine(array, mappings)
+            root, nodes = array
+            return EMPTY_ARRAY if root.nil?
+            return root if nodes.nil?
+
+            groups = group_nodes(nodes, mappings)
+
+            root.map do |element|
+              element.dup.tap { |copy| add_groups_to_element(copy, groups, mappings) }
+            end
+          end
+
+          private
+
+          def add_groups_to_element(element, groups, mappings)
+            groups.each_with_index do |candidates, index|
+              mapping = mappings[index]
+              resource_key = mapping[0]
+              element[resource_key] = element_candidates(element, candidates, mapping[1].keys)
+            end
+          end
+
+          def element_candidates(element, candidates, keys)
+            candidates[element_candidates_key(element, keys)] || EMPTY_ARRAY
+          end
+
+          def group_nodes(nodes, mappings)
+            nodes.each_with_index.map do |candidates, index|
+              mapping = mappings[index]
+              group_candidates(candidates, mapping)
+            end
+          end
+
+          def group_candidates(candidates, mapping)
+            nested_mapping = mapping[2]
+            candidates = combine(candidates, nested_mapping) unless nested_mapping.nil?
+            group_candidates_by_keys(candidates, mapping[1].values)
+          end
+
+          def group_candidates_by_keys(candidates, keys)
+            return candidates.group_by { |a| a.values_at(*keys) } if keys.size > 1
+
+            key = keys.first
+            candidates.group_by { |a| a[key] }
+          end
+
+          def element_candidates_key(element, keys)
+            return element.values_at(*keys) if keys.size > 1
+
+            element[keys.first]
+          end
+        end
+      end
+    end
+  end
+end