atacama 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3c084ce1e412bcdd0fd5b4496b95bf06541e5fce
+  data.tar.gz: 3a01181b47c0e4531492e135a69fb5279993ae4e
+SHA512:
+  metadata.gz: 93fa86a443b71fa0a428855f317cb1debb6789b18fa22776592650a54689fd124b056748d088992e9c2aa2533af7f387b049b8cdf6e32191d2d2b34d87119e0e
+  data.tar.gz: fb995c152f720d6737091ae89b0bce3e190e959857b02b2fde32dc4f48d14fdc6aa4dc1feeec448c265ada2824946207ed327aa57f426056155f378b50f5bb3b

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.gem

data/.travis.yml

@@ -0,0 +1,7 @@
+---
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+  - 2.2.4
+before_install: gem install bundler -v 1.16.3

data/Gemfile

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

data/Gemfile.lock

@@ -0,0 +1,44 @@
+PATH
+  remote: .
+  specs:
+    atacama (0.1.0)
+      dry-types
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    concurrent-ruby (1.0.5)
+    dry-configurable (0.7.0)
+      concurrent-ruby (~> 1.0)
+    dry-container (0.6.0)
+      concurrent-ruby (~> 1.0)
+      dry-configurable (~> 0.1, >= 0.1.3)
+    dry-core (0.4.7)
+      concurrent-ruby (~> 1.0)
+    dry-equalizer (0.2.1)
+    dry-inflector (0.1.2)
+    dry-logic (0.4.2)
+      dry-container (~> 0.2, >= 0.2.6)
+      dry-core (~> 0.2)
+      dry-equalizer (~> 0.2)
+    dry-types (0.13.2)
+      concurrent-ruby (~> 1.0)
+      dry-container (~> 0.3)
+      dry-core (~> 0.4, >= 0.4.4)
+      dry-equalizer (~> 0.2)
+      dry-inflector (~> 0.1, >= 0.1.2)
+      dry-logic (~> 0.4, >= 0.4.2)
+    minitest (5.11.3)
+    rake (10.5.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  atacama!
+  bundler (~> 1.16)
+  minitest (~> 5.0)
+  rake (~> 10.0)
+
+BUNDLED WITH
+   1.16.2

data/README.md

@@ -0,0 +1,102 @@
+
+
+# Atacama
+
+[![Build Status](https://travis-ci.org/fulcrumapp/atacama.svg?branch=master)](https://travis-ci.org/fulcrumapp/atacama)
+
+Atacama aims to attack the issue of Service Object patterns in a way that focuses on reusing logic
+and ease of testability.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'atacama'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install atacama
+
+## Usage
+
+The basic object is `Contract`. It enforces type contracts by utilizing `dry-types`.
+
+```
+class UserFetcher < Atacama::Contract
+  option :id, Types::Strict::Number.gt(0)
+
+  def call
+    User.find(id)
+  end
+end
+
+UserFetcher.call(id: 1)
+```
+
+With the use of two classes, we can compose together multiple Contracts to yield a pipeline
+of changes to execute.
+
+```
+class UserFetcher < Atacama::Step
+  option :id, type: Types::Strict::Number.gt(0)
+
+  def call
+    Option(model: User.find(id))
+  end
+end
+
+class Duration < Atacama::Step
+  def call
+    start = Time.now
+    yield
+    $redis.avg('duration', Time.now - start)
+  end
+end
+
+class UpdateUser < Atacama::Transformer
+  option :model, type: Types::Instance(User)
+  option :attributes, type: Types::Strict::Hash
+
+  step :duration, with: Duration do
+    step :find, with: UserFetcher
+    step :save
+  end
+
+  private
+
+  def save
+    context.model.update_attributes(attributes)
+  end
+end
+
+UpdateUser.call(id: 1, attributes: {
+  email: 'hello@world.com'
+})
+```
+
+Any step can be mocked out without the need for a third party library. Just pass any object that
+responds to `#call` in the class initializer.
+
+```
+UpdateUser.new(steps: {
+  save: lambda do |**|
+    puts "skipping save"
+  end
+})
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` 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/fulcrumapp/atacama.

data/Rakefile

@@ -0,0 +1,14 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task default: :test
+
+task :bash do
+  exec 'docker run -v `pwd`:/app:cached -it spatialnetworks/alpine bash -l -c "gem install rerun && bundle && bash"'
+end

data/atacama.gemspec

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'atacama/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'atacama'
+  spec.version       = Atacama::VERSION
+  spec.authors       = ['Tyler Johnston']
+  spec.email         = ['tyler@spatialnetworks.com']
+  spec.license       = 'MIT'
+  spec.summary       = 'DRY Service Objects'
+  spec.description   = 'Service objects using composable contracts'
+  spec.homepage      = 'https://github.com/fulcrumapp/atacama'
+
+  # 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_dependency 'dry-types', '~> 0.13.2'
+
+  spec.add_development_dependency 'bundler', '~> 1.16'
+  spec.add_development_dependency 'minitest', '~> 5.0'
+  spec.add_development_dependency 'rake', '~> 10.0'
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'atacama'
+
+# 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/atacama/contract/context.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'ostruct'
+
+module Atacama
+  # Generic object store for passing values between contracts
+  class Context < OpenStruct
+    alias key? respond_to?
+
+    def merge!(hash)
+      hash.each do |(key, value)|
+        self[key] = value
+      end
+    end
+  end
+end

data/lib/atacama/contract/parameter.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Atacama
+  # A description of the signature of the parameter being validated
+  class Parameter
+    attr_reader :name, :type
+
+    def initialize(name:, type: nil)
+      @name = name
+      @type = type
+    end
+
+    # Determine the validity of a value for an optionally given type. Raises a
+    # type error on failure.
+    # @raise [Atacama::TypeError]
+    # @returns Boolean
+    def valid?(value)
+      return true if type.nil?
+      type[value]
+      true
+    rescue Dry::Types::ConstraintError => error
+      raise TypeError, error.message
+    end
+  end
+end

data/lib/atacama/contract/validator.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Atacama
+  # Validation execution class for a given set of parameters and options.
+  class Validator
+    def self.call(**context)
+      new(**context).call
+    end
+
+    # @param options [Hash] options schema
+    # @param context [Atacama::Context] keyword arguments to validate
+    def initialize(options:, context:)
+      @options = options
+      @context = context
+    end
+
+    def call
+      detect_invalid_types!
+    end
+
+    private
+
+    attr_reader :options, :context
+
+    def detect_invalid_types!
+      options.each do |(key, parameter)|
+        raise ArgumentError, "option not found: #{key}" unless context.key?(key)
+        parameter.valid? context[key]
+      end
+    end
+  end
+end

data/lib/atacama/contract.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'dry-types'
+
+require 'atacama/contract/parameter'
+require 'atacama/contract/validator'
+require 'atacama/contract/context'
+
+module Atacama
+  # The type namespace to interact with DRY::Types
+  module Types
+    include Dry::Types.module
+    Boolean = Types::True | Types::False
+    ContextOrHash = Strict::Hash | Instance(Context)
+  end
+
+  # This class enables a DSL for creating a contract for the initializer
+  class Contract
+    RESERVED_KEYS = %i[call initialize context].freeze
+
+    NameInterface = Types::Strict::Symbol.constrained(excluded_from: RESERVED_KEYS)
+
+    class << self
+      def options
+        @options ||= {}
+      end
+
+      # Define an initializer value.
+      # @param [Symbol] name of the argument
+      def option(name, **kwargs)
+        # Validate it's a symbol and not reserved
+        name = NameInterface[name]
+
+        options[name] = Parameter.new(name: name, **kwargs)
+
+        define_method(name) { @context[name] }
+        define_method("#{name}?") { !!@context[name] }
+      end
+
+      def call(context = {})
+        new(context: context).call
+      end
+    end
+
+    attr_reader :context
+
+    def initialize(context: {}, **)
+      # Validate the type
+      Types::ContextOrHash[context]
+      @context = context.is_a?(Context) ? context : Context.new(context)
+      Validator.call(options: self.class.options, context: @context)
+    end
+
+    def call
+      self
+    end
+  end
+end

data/lib/atacama/step.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'atacama/contract'
+require 'atacama/values'
+
+module Atacama
+  class Step < Contract
+    include Values::Methods
+  end
+end

data/lib/atacama/transaction/definition.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Atacama
+  # Struct object holding the step definition
+  class Definition < Contract
+    option :name, type: Types::Strict::Symbol
+    option :with, type: Types::Any.optional
+    option :yielding, type: Types::Any.optional
+
+    def yielding?
+      !!yielding
+    end
+
+    def proc_invocation?
+      with.is_a? Proc
+    end
+
+    def method_invocation?
+      with.nil?
+    end
+  end
+end

data/lib/atacama/transaction/halt_execution.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Atacama
+  class HaltExecution < StandardError
+    attr_reader :value
+
+    def initialize(value)
+      super('Execution was halted and yielding a value with #value')
+      @value = value
+    end
+  end
+end

data/lib/atacama/transaction.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'atacama/contract'
+require 'atacama/transaction/halt_execution'
+require 'atacama/transaction/definition'
+
+module Atacama
+  class Transaction < Contract
+    include Values::Methods
+
+    class Result < Contract
+      option :value, type: Types::Any
+      option :transaction, type: Types.Instance(Context)
+    end
+
+    class << self
+      # @returns [Array<Atacama::Transaction::Definition>]
+      def steps
+        @steps ||= []
+      end
+
+      # Add a step to the processing queue.
+      # @param name [Symbol] a unique name for a step
+      def step(name, **kwargs, &block)
+        kwargs[:yielding] = block_given? ? Class.new(self, &block) : nil
+        kwargs[:with] ||= nil
+        steps.push Definition.call(name: name, **kwargs)
+      end
+    end
+
+    def initialize(context: {}, steps: {})
+      super(context: context)
+      @overrides = steps
+    end
+
+    def call
+      value = begin
+        execute(self.class.steps)
+      rescue HaltExecution => exception
+        exception.value
+      end
+
+      raise MissingReturn, "Return value from #{self.class} missing, received: #{value.inspect}" unless value.is_a? Values::Return
+
+      Result.call(value: value.value, transaction: context)
+    end
+
+    private
+
+    def execute(steps)
+      steps.each do |step|
+        evaluate(step).tap do |result|
+          context.merge!(result.value) if result.is_a? Values::Option
+        end
+      end
+    end
+
+    def evaluate(step)
+      if overridden?(step)
+        evaluate_override(step)
+      elsif step.method_invocation?
+        evaluate_method(step)
+      elsif step.proc_invocation?
+        evaluate_proc(step)
+      else
+        evaluate_instance(step)
+      end
+    end
+
+    def overridden?(step)
+      @overrides.key?(step.name)
+    end
+
+    def evaluate_override(step)
+      callable = @overrides[step.name]
+      instance_exec(&callable)
+    end
+
+    def evaluate_method(step)
+      send(step.name) do
+        execute(step.yielding.steps)
+      end
+    end
+
+    def evaluate_proc(step)
+      callable = step.with
+      instance_exec(&callable)
+    end
+
+    def evaluate_instance(step)
+      step.with.new(context: context).call do
+        execute(step.yielding.steps)
+      end
+    end
+  end
+end

data/lib/atacama/values.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'atacama/contract'
+
+module Atacama
+  module Values
+    # Helper methods for emitting value objects inside of a Contract.
+    module Methods
+      # rubocop:disable Naming/MethodName
+
+      # This value tells the orchestrator to merge in these parameters on the
+      # next call.
+      # @param [Hash] the hash object to merge
+      def Option(value)
+        Values::Option.call(value: value)
+      end
+
+      def Return(value)
+        raise HaltExecution.new(Values::Return.call(value: value))
+      end
+      # rubocop:enable Naming/MethodName
+    end
+
+    # This object notifies the Transaction that a new variable needs to be
+    # merged in to the current context.
+    class Option < Contract
+      option :value, type: Types::Strict::Hash
+    end
+
+    # This object notifies the Transaction that a new
+    class Return < Contract
+      option :value
+    end
+  end
+end

data/lib/atacama/version.rb

@@ -0,0 +1,3 @@
+module Atacama
+  VERSION = '0.1.0'.freeze
+end

data/lib/atacama.rb

@@ -0,0 +1,10 @@
+require 'atacama/version'
+require 'atacama/contract'
+require 'atacama/transaction'
+require 'atacama/step'
+
+module Atacama
+  ArgumentError = Class.new(StandardError)
+  TypeError = Class.new(StandardError)
+  MissingReturn = Class.new(StandardError)
+end

metadata

@@ -0,0 +1,120 @@
+--- !ruby/object:Gem::Specification
+name: atacama
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tyler Johnston
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2018-10-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dry-types
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.13.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.13.2
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+description: Service objects using composable contracts
+email:
+- tyler@spatialnetworks.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
+- atacama.gemspec
+- bin/console
+- bin/setup
+- lib/atacama.rb
+- lib/atacama/contract.rb
+- lib/atacama/contract/context.rb
+- lib/atacama/contract/parameter.rb
+- lib/atacama/contract/validator.rb
+- lib/atacama/step.rb
+- lib/atacama/transaction.rb
+- lib/atacama/transaction/definition.rb
+- lib/atacama/transaction/halt_execution.rb
+- lib/atacama/values.rb
+- lib/atacama/version.rb
+homepage: https://github.com/fulcrumapp/atacama
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.11
+signing_key: 
+specification_version: 4
+summary: DRY Service Objects
+test_files: []