reforge 0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Nate Eizenga
+
+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,44 @@
+# Reforge
+
+[![Gem Version](https://badge.fury.io/rb/reforge.svg)](https://badge.fury.io/rb/reforge)
+[![Actions Status](https://github.com/eizengan/reforge/workflows/CI/badge.svg)](https://github.com/eizengan/reforge/actions)
+[![Maintainability](https://api.codeclimate.com/v1/badges/ca2883109cdb44f8cc9e/maintainability)](https://codeclimate.com/github/eizengan/reforge/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/ca2883109cdb44f8cc9e/test_coverage)](https://codeclimate.com/github/eizengan/reforge/test_coverage)
+
+Reforge provides simple, concise, DSL-driven data transformation for Ruby. Just describe how to obtain data from a source, and then where to place that data in the result - no boilerplate required!
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'reforge'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install reforge
+
+## Usage
+
+See the [introduction](INTRODUCTION.md) for information on how to create transformations.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+
+## Code of Conduct
+
+This project is intended to be a safe, welcoming space for collaboration. Everyone interacting in official project channels is expected to follow the [Code of Conduct](https://github.com/eizengan/reforge/blob/main/CODE_OF_CONDUCT.md) outlined by [Contributor Covenant](http://contributor-covenant.org).
+
+
+## Contributing
+
+Bug reports and pull requests are welcome on the project's [GitHub repository](https://github.com/eizengan/reforge). The current state of development is publicly visible on the project's [Trello board](https://trello.com/b/5hmYBrgt/reforge).
+
+After checking out the repo, run `bin/setup` to install dependencies. Afterward, run `bundle exec rake` to lint the code and run tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment. To install the code as a gem onto your local machine, run `bundle exec rake install`.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+RSpec::Core::RakeTask.new(:rspec)
+RuboCop::RakeTask.new(:rubocop) do |t|
+  t.options = ["--parallel"]
+end
+
+task default: %i[rubocop rspec]

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "reforge"
+
+# 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/lib/reforge.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "reforge/zeitwerk"
+
+module Reforge
+  def self.configure
+    yield configuration if block_given?
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configuration=(configuration)
+    @configuration = configuration
+  end
+end

data/lib/reforge/configuration.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Reforge
+  class Configuration
+  end
+end

data/lib/reforge/transformation.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Reforge
+  class Transformation
+    extend DSL
+
+    def self.call(*sources)
+      new.call(*sources)
+    end
+
+    def call(*sources)
+      return tree.call(sources[0]) if sources.size == 1
+
+      sources.map { |source| tree.call(source) }
+    end
+
+    private
+
+    def tree
+      @tree ||= self.class.create_tree
+    end
+  end
+end

data/lib/reforge/transformation/dsl.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Reforge
+  class Transformation
+    class TreeCreationError < StandardError; end
+
+    module DSL
+      def extract(path = nil, from:, memoize: nil)
+        transform_definitions.push(
+          {
+            path: path,
+            transform: from,
+            memoize: memoize
+          }.compact
+        )
+      end
+
+      # TRICKY: we want to support e.g. the following equivalent calls:
+      # - transform key: 0, into: [:foo, :bar]
+      # - transform ->(source) { source[0] }, into: [:foo, :bar]
+      # but in the former case the arguments are collapsed into a single hash which is used as the transform arg. By
+      # using **transform_hash we can avoid this behavior, but as a result the transform could be in either the
+      # transform argument or the transform_hash
+      def transform(transform = nil, into: nil, memoize: nil, **transform_hash)
+        transform_definitions.push(
+          {
+            path: into,
+            transform: transform || transform_hash,
+            memoize: memoize
+          }.compact
+        )
+      end
+
+      def create_tree
+        transform_definitions.each_with_object(Tree.new) do |transform_definition, tree|
+          transform = Transform.new(
+            transform_definition[:transform],
+            memoize: transform_definition[:memoize]
+          )
+          tree.attach_transform(*transform_definition[:path], transform)
+        rescue StandardError => e
+          raise TreeCreationError, "Failed to attach node at path #{[*transform_definition[:path]]} - #{e.message}"
+        end
+      end
+
+      def transform_definitions
+        @transform_definitions ||= []
+      end
+    end
+  end
+end

data/lib/reforge/transformation/transform.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Reforge
+  class Transformation
+    class Transform
+      include Factories
+
+      attr_reader :transform
+
+      def initialize(transform, memoize: nil)
+        transform = transform_proc_from(transform) if transform.is_a?(Hash)
+        validate_transform!(transform)
+
+        @transform = transform
+        @memo = Memo.from(memoize) if memoize
+      end
+
+      def call(source)
+        if @memo.nil?
+          call_transform(source)
+        else
+          @memo[source] ||= call_transform(source)
+        end
+      end
+
+      private
+
+      def call_transform(source)
+        if @transform.arity.zero?
+          @transform.call
+        else
+          @transform.call(source)
+        end
+      end
+
+      def validate_transform!(transform)
+        return if transform.respond_to?(:call)
+
+        raise ArgumentError, "The transform must be callable"
+      end
+    end
+  end
+end

data/lib/reforge/transformation/transform/factories.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Reforge
+  class Transformation
+    class Transform
+      module Factories
+        # TODO: here we code to the least common denominator: everything is a proc. This likely works slower than
+        # something specialized to each individual case. This could be of concern since these will be called
+        # per-transform, per-source
+        TRANSFORM_PROC_FACTORIES = {
+          attribute: ->(attributes, **config) { attribute_transform_for(attributes, **config) },
+          key: ->(keys, **config) { key_transform_for(keys, **config) },
+          value: ->(value, **_config) { value_transform_for(value) }
+        }.freeze
+        TRANSFORM_TYPES = TRANSFORM_PROC_FACTORIES.keys.freeze
+
+        def transform_proc_from(config)
+          validate_config!(config)
+
+          type = config.keys.detect { |key| TRANSFORM_TYPES.include?(key) }
+          args = config[type]
+          config = config.reject { |k, _v| k == type }
+
+          TRANSFORM_PROC_FACTORIES[type].call(args, **config)
+        end
+
+        private_class_method def self.attribute_transform_for(attributes, propogate_nil: false)
+          recursive_method_call(:send, attributes, propogate_nil: propogate_nil)
+        end
+
+        private_class_method def self.key_transform_for(keys, propogate_nil: false)
+          recursive_method_call(:[], keys, propogate_nil: propogate_nil)
+        end
+
+        private_class_method def self.value_transform_for(value)
+          ->(_source) { value }
+        end
+
+        private_class_method def self.recursive_method_call(method, arguments, propogate_nil: false)
+          # TRICKY: this could be a single argument or an array of many, so we circumvent the destinction by wrapping
+          # single arguments in an array
+          arguments = [arguments] unless arguments.respond_to?(:reduce)
+
+          if propogate_nil
+            ->(source) { arguments.reduce(source) { |object, argument| object&.send(method, argument) } }
+          else
+            ->(source) { arguments.reduce(source) { |object, argument| object.send(method, argument) } }
+          end
+        end
+
+        private
+
+        def validate_config!(config)
+          return if config.is_a?(Hash) && config.keys.count { |key| TRANSFORM_TYPES.include?(key) } == 1
+
+          raise ArgumentError, "The transform configuration hash must define exactly one transform type"
+        end
+      end
+    end
+  end
+end

data/lib/reforge/transformation/transform/memo.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Reforge
+  class Transformation
+    class Transform
+      class Memo
+        CONSTANT_TRANSFORM = ->(_source) { :constant }.freeze
+        IDENTITY_TRANSFORM = ->(source) { source }.freeze
+
+        # TODO: here we code to the least common denominator: everything is a proc. This likely works slower than
+        # something specialized to each individual case This could be of concern since these will be called
+        # per-transform, per-source
+        def self.from(memoize)
+          if memoize.is_a?(Hash) # rubocop:disable Style/CaseLikeIf:
+            Memo.new(memoize[:by])
+          elsif memoize == :first
+            Memo.new(CONSTANT_TRANSFORM)
+          elsif memoize == true
+            Memo.new(IDENTITY_TRANSFORM)
+          else
+            raise ArgumentError, "The memoize option should be true, :first, or a valid configuration hash"
+          end
+        end
+
+        def initialize(key_transform)
+          @memo = {}
+          @key_transform = Transform.new(key_transform)
+        rescue ArgumentError
+          # TRICKY: Transform didn't like key_transform, but we want to raise an error specific to Memo, not the one
+          # directly from Transform
+          raise ArgumentError, "The memoize option should be true, :first, or a valid configuration hash"
+        end
+
+        def [](source)
+          key = @key_transform.call(source)
+          @memo[key]
+        end
+
+        def []=(source, value)
+          key = @key_transform.call(source)
+          @memo[key] = value
+        end
+      end
+    end
+  end
+end

data/lib/reforge/transformation/tree.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Reforge
+  class Transformation
+    class Tree
+      class NodeRedefinitionError < StandardError; end
+      class PathPartError < StandardError; end
+
+      attr_reader :root
+
+      def attach_transform(*path)
+        validate_path!(*path)
+
+        # TRICKY: A single-step path means we are wrapping a single transform. We set the root node accordingly,
+        # allowing it to fail loudly if it is being redefined
+        #
+        # A multi-step path means we are wrapping a branching tree with transforms at its leaf nodes. We only
+        # initialize the root node if we have not done so already, and then begin attaching the nodes necessitated by
+        # the supplied path. The nodes are expected to fail loudly if their attachment rules are violated
+        if path.size == 1
+          initialize_root(path[0])
+        else
+          initialize_root(path[0]) if root.nil?
+          attach_nodes(*path)
+        end
+
+        nil
+      end
+
+      def call(source)
+        root.call(source)
+      end
+
+      private
+
+      def validate_path!(*path, transform)
+        raise ArgumentError, "The path must end with a Transform" unless transform.is_a?(Transform)
+
+        path.each { |path_part| validate_path_part!(path_part) }
+      end
+
+      def validate_path_part!(path_part)
+        return if AggregateNode::IMPLEMENTATION_TYPES.include?(path_part.class)
+
+        raise ArgumentError, "The path includes '#{path_part}' which has unknown key type #{path_part.class}"
+      end
+
+      def initialize_root(path_part)
+        raise NodeRedefinitionError, "The root node has already been defined" unless root.nil?
+
+        @root = create_node(path_part)
+      end
+
+      def attach_nodes(*path, transform)
+        node = root
+
+        # TRICKY: we need two contiguous steps in the path to create and attach a node. The first tells where on the
+        # parent node to attach the new node, and the second allows us to infer which type of node we need to attach.
+        #
+        # As an example, in attach_nodes(:foo, 0, :bar, transform) the pair of steps [:foo, 0] would tell us we need to
+        # attach an ArrayNode (inferred by 0) at root's :foo index. We then move to [0, :bar], which tell us we need to
+        # attach a HashNode (inferred by :bar) at the ArrayNode's 0 index. Finally we move to [:bar, transform], which
+        # tells us to attach an TransformNode (inferred by transform) at the HashNode's :bar index
+        #
+        # To fulfill this requirement we turn the arguments to this method into offset arrays and zip them together. Use
+        # of ||= is inappropriate during TransformNode attachment because it will not attempt to create and attach the
+        # node if a child with the same key already exists, so we just use = below
+        parent_path_parts = path[0..-2]
+        child_path_parts = path[1..]
+        parent_path_parts.zip(child_path_parts).each do |parent_path_part, child_path_part|
+          node = node[parent_path_part] ||= create_node(child_path_part)
+        end
+
+        node[path[-1]] = create_node(transform)
+      end
+
+      def create_node(path_part)
+        if AggregateNode::IMPLEMENTATION_TYPES.include?(path_part.class)
+          AggregateNode.new(path_part.class)
+        elsif path_part.is_a?(Transform)
+          TransformNode.new(path_part)
+        else
+          raise PathPartError, "Cannot create node from path_part type #{step.class}"
+        end
+      end
+    end
+  end
+end