opie 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: '045387aa207b16be2233d147879ce84a4aa4f582'
-  data.tar.gz: 721d6f47366e454c71d48d89cb1b52c0c667dee3
+  metadata.gz: 1f3af112187a2390363fe9bcb389ed828eeaea29
+  data.tar.gz: e7f2c4d31314ba73317612f72d1dab3ecd234aa7
 SHA512:
-  metadata.gz: 92a9ea5e58135b1ceb1f652c495b7518de7cc633bf8d83e063e87dad2351aa0bd4c8fb0255882ba52da7ef11bd42e5430c1595d6c194e4d7b6843cfdd7f1a170
-  data.tar.gz: 73a7952a92f88fe0b3434480d7367c03fe99e61809975703f1559da882bbbae51c10f41da3b6d53d77a6e323c4e99274413737e44a2a0de22126eeb452f3de77
+  metadata.gz: 3c7b9d9ce3250ec523633999c61340f3a44529ef1f2af5f5bec7048d68d428f166f242cfc32142fdf22b26c80ad5f64790453eafe67d6ba0240f7e472a72ed7b
+  data.tar.gz: 0bc5a6dbd668167fca6242b4d090214ec9d2dd8be77daae440b2a1dbb44b01abd2077e43df809d9b5c7dc63c7199a5fee6c490b1d9bd900bb9b68e2cb4959e1d

data/.gitignore

@@ -1,4 +1,5 @@
 /.bundle/
+/.byebug*
 /.yardoc
 /Gemfile.lock
 /_yardoc/

data/.rubocop.yml

@@ -1,6 +1,9 @@
 # https://github.com/bbatsov/rubocop/blob/master/config/default.yml
 
 AllCops:
+  Exclude:
+    - 'spec/**/*'
+    - '*.gemspec'
   TargetRubyVersion: 2.3
 
 Metrics/LineLength:
@@ -8,3 +11,6 @@ Metrics/LineLength:
 
 Style/Documentation:
   Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,28 @@
+<a name="1.0.0"></a>
+# [1.0.0](https://github.com/guzart/opie/compare/v0.1.0...v1.0.0) (2017-03-20)
+
+
+### Bug Fixes
+
+* reimplement step and call using new spec ([d765181](https://github.com/guzart/opie/commit/d765181))
+
+
+### Features
+
+* add #success? and #failure? ([29fb177](https://github.com/guzart/opie/commit/29fb177))
+* **operation:** add #output method ([0fa85ae](https://github.com/guzart/opie/commit/0fa85ae))
+* add failure as a value type ([729c429](https://github.com/guzart/opie/commit/729c429))
+* add failure helper method ([6735d2b](https://github.com/guzart/opie/commit/6735d2b))
+
+
+
+<a name="0.1.0"></a>
+# [0.1.0](https://github.com/guzart/opie/compare/6c9db9d...v0.1.0) (2017-03-18)
+
+
+### Features
+
+* add operation with basic support for steps ([6c9db9d](https://github.com/guzart/opie/commit/6c9db9d))
+
+
+

data/README.md

@@ -1,8 +1,204 @@
 # Opie
 
 [![Build Status](https://travis-ci.org/guzart/opie.svg?branch=master)](https://travis-ci.org/guzart/opie)
+[![codecov](https://codecov.io/gh/guzart/opie/branch/master/graph/badge.svg)](https://codecov.io/gh/guzart/opie)
+[![Code Climate](https://codeclimate.com/github/guzart/opie/badges/gpa.svg)](https://codeclimate.com/github/guzart/opie)
+[![Gem Version](https://badge.fury.io/rb/opie.svg)](https://badge.fury.io/rb/opie)
 
-TODO: describe your gem
+**Opie gives you a simple API for creating Operations using the
+[Railsway oriented programming](https://vimeo.com/113707214) paradigm.**
+
+## Usage
+
+**Simple Usage:**
+
+```ruby
+# Create an Operation for completing a Todo
+class Todos::CompleteTodo < Opie::Operation
+  step :find_todo
+  step :mark_as_complete
+
+  def find_todo(todo_id)
+    todo = Todo.find_by(id: todo_id)
+    return fail(:not_found, "Could not find the Todo using id: #{todo_id}") unless todo
+    todo
+  end
+
+  def mark_as_complete(todo)
+    success = todo.update(completed_at: Time.zone.now)
+    return fail(:update) unless success
+    todo
+  end
+end
+
+class TodosController < ApplicationController
+  def complete
+    # invoke the operation
+    result = Todos::CompleteTodo.(params[:id])
+    if result.success? # if #success?
+      render status: :created, json: result.output # use output
+    else
+      render status: :bad_request, json: { error: error_message(result.failure) } # otherwise use #failure
+    end
+  end
+
+  private
+
+  def error_message(failure)
+    case failure[:type]
+      when :not_found then failure[:data]
+      when :update then 'We were unable to make the changes to your todo'
+      else 'There was an unexpected error, sorry for the inconvenience'
+    end
+  end
+end
+```
+
+**Real world example:**
+
+Imagine yourself in the context of a [habit tracker](https://github.com/isoron/uhabits), wanting to 
+add a new habit to track.
+
+```ruby
+# app/controllers/habits_controller.rb
+
+class HabitsController < ApplicationController
+  # POST /habits
+  def create
+    # run the `operation` – since it's a modification we can call it a `command`
+    result = People::AddHabit.(habit_params)
+
+    # render response based on operation result
+    if result.success?
+      render status: :created, json: result.output
+    else
+      render status: error_http_status(result.failure[:type]), json: { errors: [result.failure] }
+    end
+  end
+
+  private
+
+  # the HTTP status depends on the error type, which separating the domain from the infrastructure
+  def error_http_status(error_type)
+    case(error_type) 
+    when :validation then :unprocessable_entity 
+    when :not_found then :not_found
+    else :server_error
+    end
+  end
+
+  # simulate parameters came from a Http request
+  def habit_params
+    {
+      person_id: 2,
+      name: 'Excercise',
+      description: 'Did you excercise for at least 15 minutes today?',
+      frequency: :three_times_per_week,
+      color: 'DeepPink'
+    }
+  end
+end
+```
+
+And now the code that defines the operation
+
+```ruby
+# application-wide dependencies container
+class HabitTrackerContainer
+  extends Dry::Container::Mixin
+
+  register 'repositories.habit', HabitRepository.new
+  register 'repositories.person', PersonRepository.new
+  register 'service_bus', ServiceBus.new
+end
+
+# application-wide dependency injector
+Import = Dry::AutoInject(HabitTrackerContainer.new)
+
+module People
+  # we define a validation schema for our input
+  AddHabitSchema = Dry::Schema.Validation do
+    configure do
+      # custom predicate for frequency
+      def freq?(value)
+        [:weekly, :five_times_per_week, :four_times_per_week, :three_times_per_week].includes?(value)
+      end
+    end
+    
+    required(:person_id).filled(:int?, gt?: 0)
+    required(:name).filled(:str?)
+    required(:description).maybe(:str?)
+    required(:frequency).filled(:freq?)
+    required(:color).filled(:str?)
+  end
+
+  # the operation logic starts
+  class AddHabit < Opie::Operation 
+    # inject dependencies, more flexible than ruby's global namespace
+    include Import[
+      habit_repo: 'repositories.habit',
+      person_repo: 'repositories.person',
+      service_bus: 'service_bus'
+    ]
+
+    # first step receives ::call first argument, then the output of the step is the argument of the next step
+    step :validate
+    step :find_person
+    step :persist_habit
+    step :send_event
+
+    # receives the first input
+    def validate(params)
+      schema = AddHabitSchema.(params)
+      return fail(:validation, schema.errors) if schema.failure?
+      schema.output
+    end
+
+    # if it's valid then find the person (tenant)
+    def find_person(params)
+      person = person_repo.find(params[:person_id])
+      return fail(:repository, 'We could not find your account') unless person
+      params.merge(person: person)
+    end
+
+    # persist the new habit
+    def persist_habit(params)
+      new_habit = Entities::Habit.new(params)
+      habit_repo.create(new_habit)
+    rescue => error
+      fail(:persist_failed, error.message)
+    end
+
+    # notify the world
+    def send_event(habit)
+      event = Habits::CreatedEvent.new(habit.attributes)
+      service_bus.send(event)
+    rescue => error
+      fail(:event_failed, error)
+    end
+  end
+end
+```
+
+## API
+
+The `Opie::Operation` API:
+  * `::step(Symbol) -> void` indicates a method that is executed in the operation sequence
+  * `#success? -> Boolean` indicates  whether the operation was successful
+  * `#failure? -> Boolean` indicates  whether the operation was a failure
+  * `#failure -> Hash | nil` the erorr if the operation is a `failure?`, nil when it's a success
+  * `#failures -> Array<Hash> | nil` an array with all errors
+  * `#output -> *` if succcessful, it returns the operation final output
+  validation error
+
+Internal API:
+  * `#fail(error_type: Symbol, error_data: *) -> Hash` 
+
+_Tentative API_
+
+  * `::step(Array<Symbol>) -> void` a series of methods to be called in parallel
+  * `::step(Opie::Step) -> void` an enforcer of a step signature which helps to compose other steps
+  * `::failure(Symbol) -> void` indicates the method that handles failures
 
 ## Installation
 
@@ -14,21 +210,24 @@ gem 'opie'
 
 And then execute:
 
-    $ bundle
+```bash
+$ bundle
+```
 
 Or install it yourself as:
 
-    $ gem install opie
-
-## Usage
-
-TODO: Write usage instructions here
+```bash
+$ gem install opie
+```
 
 ## 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.
+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).
+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
 

data/lib/opie.rb

@@ -1,4 +1,5 @@
 module Opie
   require 'opie/version'
+  require 'opie/failure'
   require 'opie/operation'
 end

data/lib/opie/failure.rb

@@ -0,0 +1,18 @@
+module Opie
+  class Failure
+    attr_reader :data, :type
+
+    def initialize(type, data = nil)
+      @type = type
+      @data = data
+    end
+
+    def ==(other)
+      type == other.type && data == other.data
+    end
+
+    def hash
+      [type, (data || '').to_sym].hash
+    end
+  end
+end

data/lib/opie/operation.rb

@@ -2,58 +2,64 @@ require 'dry-container'
 
 module Opie
   class Operation
-    attr_reader :container
+    FAIL = '__STEP_FAILED__'.freeze
 
-    def initialize(params = {}, dependencies = {})
-      @container = Dry::Container.new
-      @container.register('params', params)
-      dependencies.each { |k, v| @container.register(k, v) }
+    attr_reader :failure, :output
+
+    def call(input = nil)
+      execute_steps(input)
+      self
+    end
+
+    def failure?
+      !success?
+    end
+
+    def success?
+      failure.nil?
+    end
+
+    def failures
+      [failure].compact
     end
 
     class << self
-      def call(*args)
-        instance = self.new(*args)
-        instance.send(:execute_steps, step_list)
-        instance
+      def call(input = nil)
+        new.call(input)
       end
 
-      def step(step)
-        add_step(step)
+      def step(name)
+        add_step(name)
       end
 
-      private
-
-      def add_step(value)
+      def step_list
         @steps ||= []
-        @steps << value
       end
 
-      def step_list
+      private
+
+      def add_step(name)
         @steps ||= []
+        @steps << name
       end
     end
 
-    def fail
-      'fail'
-    end
+    private
 
-    # def []=(key, value)
-    #   container.register(key, value)
-    # end
-    # result, container
+    def execute_steps(input)
+      step_list = self.class.step_list
 
-    def success?
-      !@failure
-    end
+      next_input = input
+      step_list.find do |name|
+        next_input = public_send(name, next_input)
+        failure?
+      end
 
-    def failure?
-      @failure
+      @output = next_input if success?
     end
 
-    private
-
-    def execute_steps(steps)
-      @failure = steps.find { |m| send(m) == 'fail' }
+    def fail(type, data = nil)
+      @failure = Failure.new(type, data)
     end
   end
 end

data/lib/opie/version.rb

@@ -1,3 +1,3 @@
 module Opie
-  VERSION = '0.1.0'.freeze
+  VERSION = '1.0.0'.freeze
 end

data/opie.gemspec

@@ -27,6 +27,8 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'dry-container', '~> 0.6'
 
   spec.add_development_dependency 'awesome_print', '~> 1.7'
+  spec.add_development_dependency 'byebug', '~> 9.0'
+  spec.add_development_dependency 'codecov', '~> 0'
   spec.add_development_dependency 'bundler', '~> 1.14'
   spec.add_development_dependency 'guard', '~> 2.14'
   spec.add_development_dependency 'guard-rspec', '~> 4.7'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: opie
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Arturo Guzman
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-03-18 00:00:00.000000000 Z
+date: 2017-03-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-container
@@ -38,6 +38,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: codecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -138,6 +166,7 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".travis.yml"
+- CHANGELOG.md
 - Gemfile
 - Guardfile
 - LICENSE.txt
@@ -149,6 +178,7 @@ files:
 - bin/rspec
 - bin/setup
 - lib/opie.rb
+- lib/opie/failure.rb
 - lib/opie/operation.rb
 - lib/opie/version.rb
 - opie.gemspec