thalamus 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 822ad009daebff4c13eac447e6724b0f2206641e
+  data.tar.gz: bd1d9d475aff1910b645372f2c88d9e900ec9d06
+SHA512:
+  metadata.gz: f1bcd0fc04e006f5116ed0348ed3fc5789e57d432562725eafb479b94325140edc250f5f460472c58fe4f2a422285478550614681f51770da511bab8d334b3c3
+  data.tar.gz: 3bbd55cca05ce32b5112dc5bd573c5c54bd50a38d497b8c00da3133310f7dc33f83250412c1bd00cf394e4c2e7db79cf9981e8769cbad03f8dacedb2d0e0a84a

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/log/*.log
+.DS_Store
+/.env*

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.4.0
+before_install: gem install bundler -v 1.15.1

data/Gemfile

@@ -0,0 +1,2 @@
+source "https://rubygems.org"
+gemspec

data/Guardfile

@@ -0,0 +1,7 @@
+guard :minitest do
+  watch(%r{^test/(.*)\/?(.*)_test\.rb$})
+  watch(%r{^lib/(.*/)?([^/]+)\.rb$}) { |m| "test/#{m[1]}#{m[2]}_test.rb" }
+  watch(%r{^lib((/\w+)+)/\w+.rb$})   { |m| "test#{m[1]}_test.rb" }
+  watch(%r{^lib/\w+\.rb$})           { 'test' }
+  watch(%r{^test/test_helper\.rb$})  { 'test' }
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Josh Greenberg
+
+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,123 @@
+# Thalamus
+
+**Thalamus** is a simple implementation of the interactor pattern. It encourages SOLID(ish) design, in particular the separation of business logic from implementation logic. Thin files, fat directories!
+
+Thalamus is heavily inspired by [Hanami::Interactor](https://github.com/hanami/utils) and, in many ways, is just a more opinionated version.
+
+## Installation
+
+Come on now.
+
+```ruby
+gem 'thalamus'#, github: 'joshgreenberg/thalamus'
+```
+```bash
+bundle install
+```
+
+## Usage
+
+```ruby
+class DoSomething < Thalamus::Interactor
+  def call
+    perform_side_effects
+  end
+
+  private
+  def perform_side_effects
+    # ...
+  end
+end
+```
+
+Call `DoSomething.call(payload)` from anywhere - a controller, an API endpoint, a task or job, the command line, another interactor, etc. This is the _only_ entry point from your app's implementation details to the business logic.
+
+Note that you invoke with `Interactor.call` but define behaviour with `Interactor#call`.
+
+### Input
+
+The input payload must be a hash and is immutable. Symbolized keys are preferred. The hash content may take two forms:
+
+- `{params: {foo: 'bar'}, current_user: User.new}` is recommended. `:params` must be structured like a JSON object. Often, implementation in the controller will look like `Interactor.call(params: http_request_body, current_user: authenticated_user)`.
+- `{foo: 'bar', current_user: User.new}` is also accepted. Special fields will be extracted and will _not_ be passed to `:params`. Special fields include:
+    + `:current_user` (see Authorization)
+
+### Authorization
+
+```ruby
+class EatCheese < Thalamus::Interactor
+  policy PunditStylePolicy, :eat?
+  def call
+    # ...
+  end
+end
+```
+
+If a policy is defined, `.call` will extract `payload[:current_user]` (which should be an entity) and run it through the policy. If the policy fails, the interactor will fail immediately.
+
+### Validation
+
+Thalamus depends on [dry-rb](http://dry-rb.org/gems/dry-validation) and [Hanami::Validations](https://github.com/hanami/validations):
+
+```ruby
+class Blah < Thalamus::Interactor
+  validations do
+    # ...
+  end
+  def call
+    # ...
+  end
+end
+```
+
+Validations will be run on `payload[:params]` after authorization and before execution. Running validations first ensures that your business logic will never be working with invalid input.
+
+You can override the default validation logic. Overriding `#valid?` will ignore the `validations` block.
+
+```ruby
+class Foo < Thalamus::Interactor
+  def call
+    # ...
+  end
+  private
+  def valid?
+    # boolean expression
+  end
+end
+```
+
+### Execution
+
+This is where you work with domain entities - and as a best practice, this should be the outermost layer _in your entire application_ where you work with them. (User authentication in the router or controller is the only exception, and even then you should only be exposing credentials outside of the business domain.) `#call` will only be run if the interactor is both authorized and valid, enforcing permitted access and changes.
+
+`#error!(message)` triggers a failure and aborts the interactor.
+
+`#params` provides a copy of the sanitized input after it has been processed by the validator. It cannot be modified - see below to mutate return data.
+
+### Output
+
+An interactor returns an instance of Thalamus::Result. It responds to the following instance methods:
+
+- `status` => Symbol in `[:success, :unauthorized, :invalid, :failure]`
+    + `success?` => Boolean, results are successful if no errors are raised
+    + `unauthorized?` => Boolean
+    + `invalid?` => Boolean
+    + `failure?` => Boolean, equivalent of `!success?`
+- `errors` => Array of `Interactor#error!(message)`
+- `validation_errors` => Hash of error messages from dry-validation, organized by key
+
+Any other name starting with a lowercase letter can be exposed to the result object:
+
+```ruby
+class CreateBook < Thalamus::Interactor
+  expose :book
+
+  def call
+    @book = Book.create({})
+  end
+end
+```
+
+Whatever is at `@book` is now available at `Result#book`.
+
+It is up to the developer to enforce boundaries appropriately. You must decide which data to expose outside of the interactor, and which layer is responsible for converting it. For example, you may wish to convert an entity to JSON for an API response, but when calling an interactor from somewhere else you may find it more useful to return a richer object. You may decide to handle JSON conversions in the controller - the interactor is the layer that modifies data, but there is no conversion mechanism because it is agnostic to how it is stored.

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "rake/notes/rake_task"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task :default => :test

data/bin/console

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "thalamus"
+
+require "pry"
+Pry.start

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/thalamus/interactor/result.rb

@@ -0,0 +1,64 @@
+module Thalamus
+  class Interactor
+    class Result
+
+      def expose!(exposures)
+        @exposures = exposures
+        self
+      end
+
+      def finish!(status, errors = [], validation_errors = {})
+        @status = status
+        @errors = errors
+        @validation_errors = validation_errors
+        self
+      end
+      attr_reader :status, :errors, :validation_errors
+
+      def success? # 200 or 201
+        @status == :success && errors.empty?
+      end
+
+      def unauthorized? # 403
+        @status == :unauthorized
+      end
+
+      def invalid? # 422
+        @status == :invalid
+      end
+
+      def failure? # catch-all
+        !success?
+      end
+
+      def response
+        if success?
+          @exposures
+        elsif unauthorized?
+          {errors: ["UNAUTHORIZED"]}
+        elsif invalid?
+          validation_errors
+        elsif failure?
+          {errors: errors}
+        else
+          raise "[Thalamus] Invalid result status: #{status}"
+        end
+      end
+
+      protected
+
+      def method_missing(m, *args, &block)
+        if m.to_s =~ /^[a-z]/
+          (@exposures || {}).fetch(m) { super }
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(m, include_private = false)
+        m.to_s =~ /^[a-z]/ && @exposures.key?(m)
+      end
+      
+    end
+  end
+end

data/lib/thalamus/interactor.rb

@@ -0,0 +1,101 @@
+require 'hanami/validations/form'
+require 'thalamus/interactor/result'
+
+module Thalamus
+  class Interactor
+    include Hanami::Validations::Form
+
+    def initialize(payload = {})
+      @current_user = payload.delete(:current_user)
+      @_params = payload.delete(:params) || payload
+      @_errors = []
+    end
+    attr_reader :current_user, :model
+
+    def params
+      @_params.dup
+    end
+
+    def _call
+     status = catch :status do
+        # Authorization
+        if tuple = self.class._policy
+          klass, policy = tuple
+          fail!(:unauthorized) unless klass.new(current_user, model).send(policy)
+        end
+
+        # Validation
+        fail!(:invalid) unless valid?
+
+        # Execution
+        call
+        :success
+      end
+      result = Result.new.expose!(_exposures)
+                         .finish!(status, @_errors, @_validation_errors)
+      yield result if block_given? && result.success?
+      result
+    end
+
+    private
+
+    def error!(msg = '')
+      @_errors << msg
+      fail!
+    end
+
+    def fail!(status = :failure)
+      throw :status, status
+    end
+
+    def valid?
+      if schema = self.class.schema
+        r = schema.call(@_params)
+        @_params = r.output
+        @_validation_errors = r.errors
+        r.success?
+      else
+        true
+      end
+    end
+
+    def _exposures
+      exposures = self.class.exposures || {}
+      exposures.map do |ivar|
+        [ivar, instance_variable_get("@#{ivar}")]
+      end.to_h
+    end
+
+    class << self
+      private :new
+
+      def call(payload = {}, &block) # Public entry point
+        new(payload)._call(&block)
+      end
+
+      attr_reader :_policy, :exposures
+
+      private # Class-level DSL
+
+      def policy(klass, policy)
+        @_policy = [klass, policy]
+      end
+
+      def schema_type(type)
+        @_schema_type = type
+      end
+
+      def _schema_type
+        @_schema_type || super
+      end
+
+      def expose(*ivars)
+        ivars.each do |ivar|
+          @exposures ||= []
+          @exposures << ivar.to_sym
+        end
+      end
+    end
+
+  end
+end

data/lib/thalamus/policy.rb

@@ -0,0 +1,17 @@
+module Thalamus
+  class Policy
+    attr_reader :user, :model
+    
+    def initialize(user, model)
+      @user, @model = user, model
+    end
+
+    def method_missing(m, *args, &block)
+      m.to_s[-1] == '?' ? false : super
+    end
+
+    def respond_to_missing?(m, include_private = false)
+      m.to_s[-1] == '?' || super
+    end
+  end
+end

data/lib/thalamus/version.rb

@@ -0,0 +1,3 @@
+module Thalamus
+  VERSION = "0.0.2"
+end

data/lib/thalamus.rb

@@ -0,0 +1,6 @@
+require 'thalamus/version'
+require 'thalamus/interactor'
+require 'thalamus/policy'
+
+module Thalamus
+end

data/thalamus.gemspec

@@ -0,0 +1,33 @@
+# coding: utf-8
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "thalamus/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "thalamus"
+  spec.version       = Thalamus::VERSION
+  spec.authors       = ["Josh Greenberg"]
+  spec.email         = ["joshgreenberg91@gmail.com"]
+
+  spec.summary       = "Interactors"
+  spec.description   = "Interactors"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |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", "~> 1.15"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "minitest-reporters"
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "guard"
+  spec.add_development_dependency "guard-minitest"
+  spec.add_development_dependency "rake-notes"
+
+  spec.add_dependency "hanami-validations", "~> 1.0"
+end

metadata

@@ -0,0 +1,185 @@
+--- !ruby/object:Gem::Specification
+name: thalamus
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+platform: ruby
+authors:
+- Josh Greenberg
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2017-07-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !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'
+- !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: minitest-reporters
+  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: pry
+  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: guard
+  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: guard-minitest
+  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: rake-notes
+  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: hanami-validations
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Interactors
+email:
+- joshgreenberg91@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- Gemfile
+- Guardfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/thalamus.rb
+- lib/thalamus/interactor.rb
+- lib/thalamus/interactor/result.rb
+- lib/thalamus/policy.rb
+- lib/thalamus/version.rb
+- thalamus.gemspec
+homepage: 
+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.8
+signing_key: 
+specification_version: 4
+summary: Interactors
+test_files: []