pragma-operation 0.1.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a0e4b70a6dbf00fc017919c4a20a4fcab1314caf
-  data.tar.gz: 10bd799eabb43d6f76a9d29f80a737df2c2902e0
+  metadata.gz: d1a35deac8b18a13c8f5e7cd9b4ee1372afb6321
+  data.tar.gz: 6f2abba3db47e143d06c407fe33a1416f44cffac
 SHA512:
-  metadata.gz: ff8e629a189aa67af574569fbf2fa2db77e65e753d553f4d6ae2fc3d8b892693060a223a0f69a6112f8e9ba6ba0479fc44b77550616a9a97e7567f0565ca36a1
-  data.tar.gz: 5db34e59a55d5251eb05d0f33283bb83f26027afe491c8150094076eee53af092f0d20fd0f345381f1dfa7c879643f2e9868611b4f6b0b6cbe0f827a94bd1418
+  metadata.gz: 1af71177cbec88e40273ebc84fd5118d2bf2d894df7823791850e50d12dcd5ca0e2ba649b6c4509ff71708bfdafb3bd13ba78064cdc78709f9a3e59267c1626d
+  data.tar.gz: fd674718c93267c02e48e6ce035ff0595a1cb6db79ed047938a762ae4e555ed35e9be6348ec02d5b0aed038fe428f64c738fc10edd7c62498b9c24bec37976bb

data/doc/03-policies.md

@@ -1,8 +1,7 @@
 # Policies
 
 Operations integrate with [Pragma::Policy](https://github.com/pragmarb/pragma-policy). All you have
-to do is specify the policy class with `#policy`. This will give you access to `#authorize` and
-`#authorize!`:
+to do is specify the policy class with `#policy`:
 
 ```ruby
 module API
@@ -92,3 +91,28 @@ module API
   end
 end
 ```
+
+## Authorizing collections
+
+To authorize a collection, use `#authorize_collection`. This will call `.accessible_by` on the
+policy class with the current user and the provided collection and return an authorized collection
+containing only records accessible by the user.
+
+```ruby
+module API
+  module V1
+    module Post
+      module Operation
+        class Index < Pragma::Operation::Base
+          policy API::V1::Post::Policy
+
+          def call
+            posts = authorize_collection Post.all
+            respond_with status: :ok, resource: posts
+          end
+        end
+      end
+    end
+  end
+end
+```

data/doc/04-decorators.md

@@ -0,0 +1,26 @@
+# Decorators
+
+Operations integrate with [Pragma::Decorator](https://github.com/pragmarb/pragma-decorator). All you
+have to do is specify the policy class with `#decorator`. This will give you access to `#decorate`:
+
+```ruby
+module API
+  module V1
+    module Post
+      module Operation
+        class Show < Pragma::Operation::Base
+          policy API::V1::Post::Policy
+
+          def call
+            post = Post.find(params[:id])
+            respond_with status: :ok, resource: decorate(post)
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+Note that `#decorate` works with both singular resources and collections, as it uses the decorator's
+[`.represent`](http://trailblazer.to/gems/representable/3.0/api.html) method.

data/lib/pragma/operation/authorization.rb

@@ -18,6 +18,13 @@ module Pragma
           @policy = klass
         end
 
+        # Returns the policy class.
+        #
+        # @return [Class]
+        def policy_klass
+          @policy
+        end
+
         # Builds the policy for the given user and resource, using the previous defined policy
         # class.
         #
@@ -28,7 +35,7 @@ module Pragma
         #
         # @see #policy
         def build_policy(user:, resource:)
-          @policy.new(user: user, resource: resource)
+          policy_klass.new(user: user, resource: resource)
         end
       end
 
@@ -48,11 +55,15 @@ module Pragma
 
         # Authorizes this operation on the provided resource or policy.
         #
+        # If no policy was defined, simply returns true.
+        #
         # @param authorizable [Pragma::Policy::Base|Object] resource or policy
         #
         # @return [Boolean] whether the operation is authorized
         def authorize(authorizable)
-          policy = if defined?(Pragma::Policy::Base) && authorizable.is_a?(Pragma::Policy::Base)
+          return true unless self.class.policy_klass
+
+          policy = if authorizable.is_a?(self.class.policy_klass)
             authorizable
           else
             build_policy(authorizable)
@@ -77,6 +88,22 @@ module Pragma
             }
           )
         end
+
+        # Scopes the provided collection.
+        #
+        # If no policy class is defined, simply returns the collection.
+        #
+        # @param collection [Enumerable]
+        #
+        # @return [Pragma::Decorator::Base|Enumerable]
+        def authorize_collection(collection)
+          return collection unless self.class.policy_klass
+
+          self.class.policy_klass.accessible_by(
+            user: current_user,
+            scope: collection
+          )
+        end
       end
     end
   end

data/lib/pragma/operation/base.rb

@@ -9,6 +9,10 @@ module Pragma
     class Base
       include Interactor
 
+      include Authorization
+      include Validation
+      include Decoration
+
       STATUSES = {
         200 => :ok,
         201 => :created,
@@ -70,9 +74,6 @@ module Pragma
       class << self
         def inherited(child)
           child.class_eval do
-            include Authorization
-            include Validation
-
             before :setup_context
             around :handle_halt
             after :mark_result, :consolidate_status, :validate_status, :set_default_status

data/lib/pragma/operation/decoration.rb

@@ -0,0 +1,70 @@
+module Pragma
+  module Operation
+    # Provides integration with {https://github.com/pragmarb/pragma-decorator Pragma::Decorator}.
+    #
+    # @author Alessandro Desantis
+    module Decoration
+      def self.included(base)
+        base.extend ClassMethods
+        base.include InstanceMethods
+      end
+
+      module ClassMethods # :nodoc:
+        # Sets the decorator to use for validating this operation.
+        #
+        # @param klass [Class] a subclass of +Pragma::Decorator::Base+
+        def decorator(klass)
+          @decorator = klass
+        end
+
+        # Returns the decorator class.
+        #
+        # @return [Class]
+        def decorator_klass
+          @decorator
+        end
+
+        # Builds the decorator for the given resource, using the previously defined decorator class.
+        #
+        # Works with both singular resources and collections.
+        #
+        # @param resource [Object]
+        #
+        # @return [Pragma::Decorator::Base]
+        #
+        # @see #decorator
+        def build_decorator(resource)
+          decorator_klass.represent(resource)
+        end
+      end
+
+      module InstanceMethods # :nodoc:
+        # Builds the decorator for the given resource, using the previously defined decorator class.
+        #
+        # This is just an instance-level alias of {.build_decorator}. You should use this from
+        # inside the operation.
+        #
+        # @param resource [Object]
+        #
+        # @return [Pragma::Decorator::Base]
+        #
+        # @see #decorate
+        def build_decorator(resource)
+          self.class.build_decorator(resource)
+        end
+
+        # If a decorator is defined, acts as an alias for {#build_decorator}. If not, simply returns
+        # the provided resource.
+        # @param decoratable [Object]
+        #
+        # @return [Pragma::Decorator::Base|Object]
+        #
+        # @see #build_decorator
+        def decorate(decoratable)
+          return decoratable unless self.class.decorator_klass
+          build_decorator(decoratable)
+        end
+      end
+    end
+  end
+end

data/lib/pragma/operation/validation.rb

@@ -18,6 +18,13 @@ module Pragma
           @contract = klass
         end
 
+        # Returns the contract class.
+        #
+        # @return [Class]
+        def contract_klass
+          @contract
+        end
+
         # Builds the contract for the given resource, using the previous defined contract class.
         #
         # @param resource [Object]
@@ -26,7 +33,7 @@ module Pragma
         #
         # @see #contract
         def build_contract(resource)
-          @contract.new(resource)
+          contract_klass.new(resource)
         end
       end
 
@@ -53,7 +60,7 @@ module Pragma
         # @return [Boolean] whether the operation is valid
         def validate(validatable)
           # rubocop:disable Metrics/LineLength
-          contract = if defined?(Pragma::Contract::Base) && validatable.is_a?(Pragma::Contract::Base)
+          contract = if validatable.is_a?(self.class.contract_klass)
             validatable
           else
             build_contract(validatable)

data/lib/pragma/operation/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 module Pragma
   module Operation
-    VERSION = '0.1.2'
+    VERSION = '1.0.0'
   end
 end

data/lib/pragma/operation.rb

@@ -2,9 +2,10 @@
 require 'interactor'
 
 require 'pragma/operation/version'
-require 'pragma/operation/base'
 require 'pragma/operation/authorization'
 require 'pragma/operation/validation'
+require 'pragma/operation/decoration'
+require 'pragma/operation/base'
 
 module Pragma
   # Operations provide business logic encapsulation for your JSON API.

data/pragma-operation.gemspec

@@ -24,6 +24,7 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency 'pragma-policy', '~> 0.1.0'
   spec.add_development_dependency 'pragma-contract', '~> 0.1.0'
+  spec.add_development_dependency 'pragma-decorator', '~> 0.1.0'
 
   spec.add_development_dependency "bundler"
   spec.add_development_dependency "rake"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pragma-operation
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 1.0.0
 platform: ruby
 authors:
 - Alessandro Desantis
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-12-26 00:00:00.000000000 Z
+date: 2016-12-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: interactor
@@ -52,6 +52,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: pragma-decorator
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -156,9 +170,11 @@ files:
 - doc/01-basic-usage.md
 - doc/02-contracts.md
 - doc/03-policies.md
+- doc/04-decorators.md
 - lib/pragma/operation.rb
 - lib/pragma/operation/authorization.rb
 - lib/pragma/operation/base.rb
+- lib/pragma/operation/decoration.rb
 - lib/pragma/operation/validation.rb
 - lib/pragma/operation/version.rb
 - pragma-operation.gemspec