thalamus 0.0.2 → 0.1.0

checksums.yaml

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

data/Gemfile

@@ -1,2 +1,14 @@
 source "https://rubygems.org"
 gemspec
+
+group :development do
+  gem 'pry'
+  gem 'guard'
+  gem 'guard-minitest'
+  gem 'rake-notes'
+end
+
+group :test do
+  gem 'minitest', '~> 5.0'
+  gem 'minitest-reporters'
+end

data/README.md

@@ -1,20 +1,26 @@
 # 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!
+[![Gem Version](https://badge.fury.io/rb/thalamus.svg)](https://badge.fury.io/rb/thalamus)
 
-Thalamus is heavily inspired by [Hanami::Interactor](https://github.com/hanami/utils) and, in many ways, is just a more opinionated version.
+**Thalamus** is a simple implementation of the interactor pattern. It encourages separating business logic from implementation concerns. Thalamus provides the glue between your endpoints and your problem domain, and is especially useful for keeping logic consistent in apps with multiple interfaces.
 
 ## Installation
 
-Come on now.
+Come on now:
 
 ```ruby
-gem 'thalamus'#, github: 'joshgreenberg/thalamus'
+gem 'thalamus'
 ```
 ```bash
 bundle install
 ```
 
+Or:
+
+```bash
+gem install thalamus
+```
+
 ## Usage
 
 ```ruby
@@ -30,7 +36,7 @@ class DoSomething < Thalamus::Interactor
 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.
+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 into the business logic.
 
 Note that you invoke with `Interactor.call` but define behaviour with `Interactor#call`.
 
@@ -38,26 +44,44 @@ Note that you invoke with `Interactor.call` but define behaviour with `Interacto
 
 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)`.
+- `{params: {foo: 'bar'}, current_user: User.new}` is recommended. Often, implementation in the controller will look like `Interactor.call(params: http_request_params_hash, 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 MyPolicy < Thalamus::Policy
+  def eat?
+    # boolean expression
+  end
+end
+
 class EatCheese < Thalamus::Interactor
-  policy PunditStylePolicy, :eat?
+  policy MyPolicy, :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.
+If a policy is defined on the interactor, `Interactor.call` provides its payload to the policy. If the policy fails, the interactor will fail immediately.
+
+Policies have access to `#current_user` and `#params` getters.
+
+In your policy, you may need to define a way to transform your data from raw inputs to rich domain objects:
+
+```ruby
+class ApplicationPolicy < Thalamus::Policy
+  def model
+    params[:type].constantize.find(params[:id])
+  end
+end
+```
 
 ### Validation
 
-Thalamus depends on [dry-rb](http://dry-rb.org/gems/dry-validation) and [Hanami::Validations](https://github.com/hanami/validations):
+Thalamus depends on [dry-rb](http://dry-rb.org/gems/dry-validation) via [Hanami::Validations](https://github.com/hanami/validations):
 
 ```ruby
 class Blah < Thalamus::Interactor
@@ -88,23 +112,26 @@ 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.
+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.
+`#current_user` and `#params` access the payload. `#params` provides a copy of the sanitized input after it has been processed by the validator. It cannot be modified - see Output to mutate return data.
 
 ### Output
 
-An interactor returns an instance of Thalamus::Result. It responds to the following instance methods:
+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
+  + `success?` => Boolean, results are successful if no errors are raised
+  + `unauthorized?` => Boolean
+  + `invalid?` => Boolean
+  + `failure?` => Boolean, equivalent of `!success?`
+- `errors` => Enumerable of error messages, depending on status
+  + success: Empty array: `[]`
+  + unauthorized: `['Unauthorized']`
+  + invalid: Hash of arrays from dry-validation: `{param: [errors]}`
+  + failure: `[error!(message)]`
 
 Any other name starting with a lowercase letter can be exposed to the result object:
 
@@ -120,4 +147,11 @@ 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.
+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 used.
+
+For your convenience, `Result#response` provides a JSON-friendly hash of appropriate information:
+
+- success: all exposures
+- unauthorized: `{messages: ['Unauthorized']}`
+- invalid: errors hash
+- failure: `{messages: [error_message]}`

data/TODO.md

@@ -0,0 +1,3 @@
+# TODO
+
+- Allow custom validation library

data/lib/thalamus.rb

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

data/lib/thalamus/interactor.rb

@@ -1,27 +1,28 @@
 require 'hanami/validations/form'
-require 'thalamus/interactor/result'
+require 'thalamus/result'
 
 module Thalamus
   class Interactor
     include Hanami::Validations::Form
 
+    attr_reader :current_user
+
     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
+      status = catch :status do
         # Authorization
         if tuple = self.class._policy
           klass, policy = tuple
-          fail!(:unauthorized) unless klass.new(current_user, model).send(policy)
+          fail!(:unauthorized) unless klass.new(current_user, params).send(policy)
         end
 
         # Validation
@@ -31,29 +32,30 @@ module Thalamus
         call
         :success
       end
-      result = Result.new.expose!(_exposures)
-                         .finish!(status, @_errors, @_validation_errors)
+      result = Result.new(status, @_errors, _exposures)
       yield result if block_given? && result.success?
       result
     end
 
     private
 
+    # Throw an error from the business logic, and abort
     def error!(msg = '')
-      @_errors << msg
+      @_errors = [msg]
       fail!
     end
 
+    # Internal methods
     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?
+        validation = schema.call(@_params)
+        @_params = validation.output
+        @_errors = validation.errors
+        validation.success?
       else
         true
       end
@@ -66,36 +68,42 @@ module Thalamus
       end.to_h
     end
 
+    # Class methods
     class << self
       private :new
 
-      def call(payload = {}, &block) # Public entry point
+      attr_reader :_policy, :exposures
+
+      # Public entry point
+      def call(payload = {}, &block)
         new(payload)._call(&block)
       end
 
-      attr_reader :_policy, :exposures
-
       private # Class-level DSL
 
+      # Example:
+      # policy UserPolicy, :edit?
       def policy(klass, policy)
         @_policy = [klass, policy]
       end
 
-      def schema_type(type)
-        @_schema_type = type
-      end
-
-      def _schema_type
-        @_schema_type || super
-      end
-
+      # Example:
+      # expose :foo, :bar
       def expose(*ivars)
         ivars.each do |ivar|
           @exposures ||= []
           @exposures << ivar.to_sym
         end
       end
-    end
 
-  end
+      # TODO: Document this
+      # def schema_type(type)
+      #   @_schema_type = type
+      # end
+
+      # def _schema_type
+      #   @_schema_type || super
+      # end
+    end # class << self
+  end # class Interactor
 end

data/lib/thalamus/policy.rb

@@ -1,9 +1,9 @@
 module Thalamus
   class Policy
-    attr_reader :user, :model
+    attr_reader :current_user, :params
     
-    def initialize(user, model)
-      @user, @model = user, model
+    def initialize(current_user, params)
+      @current_user, @params = current_user, params
     end
 
     def method_missing(m, *args, &block)

data/lib/thalamus/result.rb

@@ -0,0 +1,55 @@
+module Thalamus
+  class Result
+    def initialize(status, errors, exposures)
+      @status = status
+      @errors = errors || []
+      @exposures = exposures || {}
+    end
+
+    attr_reader :status, :errors
+
+    def success?
+      status == :success && errors.empty?
+    end
+
+    def unauthorized?
+      status == :unauthorized
+    end
+
+    def invalid?
+      status == :invalid
+    end
+
+    def failure?
+      !success?
+    end
+
+    def response
+      if success?
+        @exposures
+      elsif unauthorized?
+        {messages: ['Unauthorized']}
+      elsif invalid?
+        errors
+      elsif failure?
+        {messages: 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 # class Result
+end

data/lib/thalamus/version.rb

@@ -1,3 +1,14 @@
 module Thalamus
-  VERSION = "0.0.2"
+  def self.version
+    Gem::Version.new VERSION::STRING
+  end
+
+  module VERSION
+    MAJOR = 0
+    MINOR = 1
+    TINY  = 0
+    PRE   = nil
+
+    STRING = [MAJOR, MINOR, TINY, PRE].compact.join('.')
+  end
 end

data/thalamus.gemspec

@@ -1,11 +1,11 @@
 # coding: utf-8
 lib = File.expand_path("../lib", __FILE__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+$:.unshift(lib) unless $:.include?(lib)
 require "thalamus/version"
 
 Gem::Specification.new do |spec|
   spec.name          = "thalamus"
-  spec.version       = Thalamus::VERSION
+  spec.version       = Thalamus.version
   spec.authors       = ["Josh Greenberg"]
   spec.email         = ["joshgreenberg91@gmail.com"]
 
@@ -22,12 +22,6 @@ Gem::Specification.new do |spec|
 
   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

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: thalamus
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors:
 - Josh Greenberg
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-07-05 00:00:00.000000000 Z
+date: 2017-09-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -38,90 +38,6 @@ dependencies:
     - - "~>"
       - !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
@@ -150,12 +66,12 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- TODO.md
 - bin/console
-- bin/setup
 - lib/thalamus.rb
 - lib/thalamus/interactor.rb
-- lib/thalamus/interactor/result.rb
 - lib/thalamus/policy.rb
+- lib/thalamus/result.rb
 - lib/thalamus/version.rb
 - thalamus.gemspec
 homepage: 

data/bin/setup

@@ -1,8 +0,0 @@
-#!/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

@@ -1,64 +0,0 @@
-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