sweet_actions 0.1.5 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1d876fa0a38c4362063893f5f103368cb66a0ef1
-  data.tar.gz: 76d1bcd450c832d38e708c34892ed17615efb569
+  metadata.gz: a2460958332f8a5291485d228c95da9b3c6f38a9
+  data.tar.gz: 977ce5b64b0d74e726ebc212ab259bc3db1d26e5
 SHA512:
-  metadata.gz: 549ae05b48cc2d281525898bfeaaa557a57399b41be1b42f6b944d29e948a2fdff43a1c1f32360740abbc112cc0ba05e0522433e52140cdba9c543b1b48fab59
-  data.tar.gz: 70ef12a7a56ea0b1a9651cfa9e67f54984cfe35a12f86c6d9a7de1768f51b31ee7900c69f512f4ad8d1a1b3ce6a85643cf95fcc500be79becc18c644ed27f47a
+  metadata.gz: 2994cd3afa31f96da8f23a90af9399ff029da96c9c813fab812c34f2c07492a78b891e7b75ff02d4b36895ba6ae6c157ee2223e99817470a8c4e2d002a7006de
+  data.tar.gz: 568fc472e0f7ba8476ad86e359650f730a128f279fb01aca0e562fb5926e65cafe468f7f812a81894938b041bf63cf489f84cafb4f0bc072fc35b7155b007936

data/README.md

@@ -1,6 +1,174 @@
 # Sweet Actions
 
-## The Idea
+## Introduction
+Controller actions (`events#create`) tend to have more in common with their cousins (`articles#create`) than their siblings (`events#show`). Because of this, we think actions should be classes instead of methods. This makes it possible for actions to take advantage of common Object Oriented principles like Inheritance and Composition.
+
+The end result of this approach is that resource-specific controllers and actions often don't even need to exist - their logic is abstracted to parent actions.
+
+Work smart not hard right?
+
+Let's take a look at how that's possible.
+
+## Installation
+
+### 1. Install Gem
+
+Gemfile:
+
+```ruby
+gem 'sweet_actions'
+gem 'active_model_serializers'
+gem 'decanter'
+```
+
+Terminal:
+
+```
+bundle
+bundle exec rails g sweet_actions:install
+```
+
+This command generates a folder at `app/actions` with the following structure:
+
+```
+- base_action.rb
+- collect_action.rb
+- create_action.rb
+- destroy_action.rb
+- show_action.rb
+- update_action.rb
+```
+
+### 2. Generate Resource
+
+```
+rails g model Event title:string start_date:date
+bundle exec rake db:migrate
+rails g decanter Event title:string start_date:date
+rails g serializer Event title:string start_date:date
+rails g actions Events
+```
+
+This last command (`rails g actions events`) generates a folder at `app/actions/events` with the following structure:
+
+```
+- events/
+    - collect.rb
+    - create.rb
+    - destroy.rb
+    - show.rb
+    - update.rb
+```
+
+### 3. Add Routes
+
+```ruby
+Rails.application.routes.draw do
+  scope :api do
+    scope :v1 do
+      create_sweet_actions(:events)
+    end
+  end
+end
+```
+
+### 4. Profit
+
+```
+rails s
+```
+
+Using Postman, submit the following request:
+
+POST to localhost:3000/api/v1/events
+
+```json
+{
+  "event": {
+    "title": "My sweet event",
+    "start_date": "01/18/2018"
+  }
+}
+```
+
+You should get a response like so:
+
+```json
+{
+  "type": "event",
+  "attributes": {
+    "id": 1,
+    "title": "My sweet event",
+    "start_date": "2018-01-18"
+  }
+}
+```
+
+## Default REST Actions
+
+For a given resource, we provide five RESTful actions:
+
+```
+Collect: GET '/events'
+Create: POST '/events'
+Show: GET '/events/:id'
+Update: PUT '/events/:id'
+Destroy: DELETE '/events/:id'
+```
+
+Many of these actions have shared behavior, which we abstract for you:
+- Authorization of resource (cancancan for example)
+- Create and Update need to be able to properly respond with error information when save does not succeed
+- Create and Update rely on decanted params
+- Serialization of resource
+
+## Creating One-Off Actions
+
+For actions that are not RESTful (i.e. not one of the five listed above), you can still use `sweet_actions`. For example, let's say you want to create the action `events#export`.
+
+1. Create a new file at app/actions/events/export.rb:
+2. Implement `action` method that responds with a response hash
+3. Create the route
+
+```ruby
+# app/actions/events/export.rb:
+module Events
+  class Export < SweetActions::JSON::BaseAction
+    def action
+      {
+        success: true
+      }
+    end
+  end
+end
+```
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  scope :api
+    scope :v1
+      get '/events/export' => 'sweet_actions#export', resource_class: 'Event'
+    end
+  end
+end
+```
+
+Using a tool like Postman, submit the following request:
+
+```
+GET to localhost:3000/api/v1/events/export
+```
+
+You should get a response like so:
+
+```json
+{
+  success: true
+}
+```
+
+## The Idea Explained in Detail
 
 In a RESTful context, controller actions tend to have more in common with the same actions belonging to other resources than other actions belonging to the same resource. For example, let's say we have two resources in our app: Events and Articles.
 
@@ -16,7 +184,7 @@ We would argue that #2 has more in common than #1. Both events#create and articl
 3. Persist the new record
 4. Respond with new record (if successful) or error information (if unsuccessful) in the JSON
 
-By organizing our actions as methods inside a resource based controller like below, we don't have the opportunity to take advantage of basic Object Oriented programming concepts like Inheritance and Modules.
+Rails pushes us to organize our actions as methods inside a resource based controller like below. With this approach we cannot take advantage of basic Object Oriented programming concepts like Inheritance and Modules as it relates to specific actions.
 
 ```ruby
 class EventsController < ApplicationController
@@ -61,33 +229,22 @@ class ArticlesController < ApplicationController
 end
 ```
 
-Instead, we propose a strategy that looks more like the following:
+Instead, we propose a strategy where the actions themselves are classes. This would allow us have multiple layers of abstraction like so:
 
-```ruby
-# generic logic for create (sweet_actions gem)
-module SweetActions
-  class CreateAction < ApiAction
-    def action
-      @resource = set_resource
-      authorize
-      validate_and_save ? success : failure
-    end
+1. **Generic Logic** (logic that applies to all apps that use SweetActions):
+- `class SweetActions::JSON::CreateAction`
 
-    # ...
-  end
-end
+2. **Application Logic**: logic that applies to all create actions in your app:
+- `class CreateAction < SweetActions::JSON::CreateAction`
 
-# app logic for create (app/actions/create_action.rb)
-class CreateAction < SweetActions::CreateAction
-  def set_resource
-    resource_class.new(resource_params)
-  end
+3. **Resource Logic**: logic that applies to a specific resource (e.g. Events) in your app
+- `class Events::Create < CreateAction`
 
-  def authorized?
-    can?(:create, resource)
-  end
-end
+With this approach, we often won't even need to implement resource specific actions. This is because by default our `Events::Create` action will inherit all the functionality it needs. Only when there are deviances from the norm do we implement resource specific classes and in those cases, we need only override the methods that correspond with the deviance.
+
+For example, let's say we want to send an email when an event is created. It's as easy as overriding the `after_save` hook:
 
+```ruby
 # resource logic for create (app/actions/events/create.rb)
 module Events
   class Create < CreateAction
@@ -98,182 +255,66 @@ module Events
 end
 ```
 
-With this structure, we essentially have three levels of abstraction:
-
-- Generic create logic: SweetActions::CreateActions
-- App create logic: CreateAction
-- Resource create logic: Events::Create
-
-
-As you can see, we can abstract most of the `create` logic to be shared across resources, which means you **only need to write the code that is unique about this create action vs. other create actions**.
-
-## Default REST Actions
-
-For a given resource...
-- Collect: list items
-- Create: create new item
-- Show: show item
-- Update: update item
-- Destroy: delete item
-
-Many of these actions have shared behavior, which we abstract for you:
-- All require serialization of the resource
-- Create and Update need to be able to properly respond with error information when save does not succeed
-- Create and Update rely on decanted params
-- All require authorization (cancancan)
-
-## Automatic REST API
-
-Given an Event model, one can do the following and get a basic RESTful API (assuming we have [decanter](https://github.com/launchpadlab/decanter) and [AMS](https://github.com/rails-api/active_model_serializers):
-
-- rails g model Event name:string start_date:date
-- rails g decanter Event name:string start_date:date
-- rails g serializer Event name:string start_date:date
-- add the new resource in routes
-
-With that, you have the following at your disposal:
-
-Collect: get '/events'
-Create: post '/events'
-Show: get '/events/:id'
-Update: put '/events/:id'
-Destroy: delete '/events/:id'
-
-Each of these will respond with a consistent JSON format, including when saves don't succeed.
-
-## Overriding Default Actions
-
-Should you choose to override the default behavior (defined in app/sweet_actions/defaults/, ), you need only create your own action like so:
-
-app/sweet_actions/events/collect.rb
-
-```
-module Events
-  class Collect < SweetActions::CollectAction
-    def set_resource
-      Event.all.limit(10)
-    end
+If we wanted to override all action behavior, we could just implement the `action` method itself:
 
-    def authorized?
-      can?(:read, resource)
-    end
-  end
-end
-```
-
-app/sweet_actions/events/create.rb
-
-```
+```ruby
 module Events
   class Create < CreateAction
-    def set_resource
-      Event.new(resource_params)
-    end
-
-    def authorized?
-      can?(:create, resource)
-    end
-
-    def save
-      resource.save
+    def action
+      event = Event.new(resource_params)
+      event.save ? success(event) : failure
     end
 
-    def after_save
-      SiteMailer.notify_user
+    def success(event)
+      UserMailer.new_event_confirmation(resource).deliver_later
+      { success: true, data: { event: event } }
     end
   end
 end
 ```
 
-app/sweet_actions/events/show.rb
+Under the hood, this is made possible by a structure that looks like the following:
 
-```
-module Events
-  class Show < ShowAction
-    def set_resource
-      Event.find(params[:id])
-    end
-
-    def authorized?
-      can?(:read, resource)
+```ruby
+# generic logic for create (sweet_actions gem)
+module SweetActions
+  module JSON
+    class CreateAction < BaseAction
+      def action
+        @resource = set_resource
+        authorize
+        validate_and_save ? success : failure
+      end
+
+      # ...
     end
   end
 end
 ```
 
-app/sweet_actions/events/update.rb
-
-```
-module Events
-  class Update < UpdateAction
-    def set_resource
-      Event.find(params[:id])
-    end
-
-    def authorized?
-      can?(:update, resource)
-    end
+```ruby
+# app logic for create (app/actions/create_action.rb)
+class CreateAction < SweetActions::JSON::CreateAction
+  def set_resource
+    resource_class.new(resource_params)
+  end
 
-    def save
-      resource.update(resource_params)
-    end
+  def authorized?
+    can?(:create, resource)
   end
 end
 ```
 
-app/sweet_actions/events/destroy.rb
-
-```
+```ruby
+# resource logic for create (app/actions/events/create.rb)
 module Events
-  class Destroy < DestroyAction
-    def set_resource
-      Event.find(params[:id])
-    end
-
-    def authorized?
-      can?(:destroy, resource)
-    end
-
-    def destroy
-      resource.destroy
+  class Create < CreateAction
+    def after_save
+      UserMailer.new_event_confirmation(resource).deliver_later
     end
   end
 end
 ```
 
-## Installation
-
-### 1. Install Gem
-
-Gemfile:
-
-```ruby
-gem 'sweet_actions'
-gem 'active_model_serializers'
-gem 'decanter'
-```
-
-Terminal:
-
-```
-bundle
-bundle exec rails g sweet_actions:install
-```
-
-### 2. Generate Resource
-
-```
-rails g model Event title:name start_date:date
-bundle exec rake db:migrate
-rails g decanter Event title:name start_date:date
-rails g serializer Event title:name start_date:date
-rails g actions Events
-```
-
-### 3. Add Routes
+As you can see, we can abstract most of the `create` logic to be shared across resources, which means you **only need to write the code that is unique about this create action vs. other create actions**.
 
-```ruby
-Rails.application.routes.draw do
-  create_sweet_actions(:events)
-end
-```

data/lib/generators/sweet_actions/templates/base_action.rb

@@ -0,0 +1,4 @@
+class CreateAction < SweetActions::JSON::BaseAction
+  include SweetActions::REST::Base
+  include SweetActions::REST::Serialize
+end

data/lib/generators/sweet_actions/templates/collect_action.rb

@@ -1,10 +1,9 @@
-class CollectAction < SweetActions::CollectAction
-  def set_resource
-    resource_class.all
-  end
+class CollectAction < SweetActions::JSON::CollectAction
+  # def set_resource
+  #   resource_class.all
+  # end
 
-  def authorized?
-    # can?(:read, resource)
-    false
-  end
+  # def authorized?
+  #   false
+  # end
 end

data/lib/generators/sweet_actions/templates/create_action.rb

@@ -1,14 +1,13 @@
-class CreateAction < SweetActions::CreateAction
-  def set_resource
-    resource_class.new(resource_params)
-  end
+class CreateAction < SweetActions::JSON::CreateAction
+  # def set_resource
+  #   resource_class.new(resource_params)
+  # end
 
-  def authorized?
-    # can?(:create, resource)
-    false
-  end
+  # def authorized?
+  #   can?(:create, resource)
+  # end
 
-  def save
-    resource.save
-  end
+  # def save
+  #   resource.save
+  # end
 end

data/lib/generators/sweet_actions/templates/destroy_action.rb

@@ -1,14 +1,13 @@
-class DestroyAction < SweetActions::DestroyAction
-  def set_resource
-    resource_class.find(params[:id])
-  end
+class DestroyAction < SweetActions::JSON::DestroyAction
+  # def set_resource
+  #   resource_class.find(params[:id])
+  # end
 
-  def authorized?
-    # can?(:destroy, resource)
-    false
-  end
+  # def authorized?
+  #   can?(:destroy, resource)
+  # end
 
-  def destroy
-    resource.destroy
-  end
+  # def destroy
+  #   resource.destroy
+  # end
 end

data/lib/generators/sweet_actions/templates/show_action.rb

@@ -1,10 +1,9 @@
-class ShowAction < SweetActions::ShowAction
-  def set_resource
-    resource_class.find(params[:id])
-  end
+class ShowAction < SweetActions::JSON::ShowAction
+  # def set_resource
+  #   resource_class.find(params[:id])
+  # end
 
-  def authorized?
-    # can?(:read, resource)
-    false
-  end
+  # def authorized?
+  #   can?(:read, resource)
+  # end
 end

data/lib/generators/sweet_actions/templates/update_action.rb

@@ -1,15 +1,14 @@
-class UpdateAction < SweetActions::UpdateAction
-  def set_resource
-    resource_class.find(params[:id])
-  end
+class UpdateAction < SweetActions::JSON::UpdateAction
+  # def set_resource
+  #   resource_class.find(params[:id])
+  # end
 
-  def authorized?
-    # can?(:update, resource)
-    false
-  end
+  # def authorized?
+  #   can?(:update, resource)
+  # end
 
-  def save
-    resource.attributes = resource_params
-    resource.save
-  end
+  # def save
+  #   resource.attributes = resource_params
+  #   resource.save
+  # end
 end

data/lib/sweet_actions/action.rb

@@ -0,0 +1,32 @@
+module SweetActions
+  class Action
+    attr_reader :controller
+
+    def initialize(controller, options = {})
+      @controller = controller
+      after_init(options)
+    end
+
+    def perform_action
+      action
+    end
+
+    private
+
+    delegate :request, :params, to: :controller
+
+    def after_init(options); end
+
+    def action
+      raise "action method is required for #{self.class.name} because it inherits from SweetActions::Action"
+    end
+
+    def env
+      request.env
+    end
+
+    def path_parameters
+      @path_parameters ||= env['action_dispatch.request.path_parameters']
+    end
+  end
+end

data/lib/sweet_actions/action_factory.rb

@@ -21,9 +21,11 @@ module SweetActions
     end
 
     def action_class
-      klass_name = [namespace, resource_module, action_class_name].compact.join('::')
+      parts = [namespace, resource_module, action_class_name].compact
+      klass_name = parts.join('::')
       return klass_name.constantize if klass_defined?(klass_name)
-      default_action
+      path = parts.map(&:downcase).join('/')
+      raise SweetActions::Exceptions::ActionNotFound, path: path, class_name: klass_name
     end
 
     def resource_module

data/lib/sweet_actions/{authorization_concerns.rb → authorization.rb}

@@ -1,5 +1,5 @@
 module SweetActions
-  module AuthorizationConcerns
+  module Authorization
     private
 
     def authorize?
@@ -13,7 +13,7 @@ module SweetActions
     end
 
     def authorized?
-      raise "authorized? method is required for the #{self.class.name} action"
+      false # lock it down by default
     end
 
     def unauthorized

data/lib/sweet_actions/controller_concerns.rb

@@ -4,7 +4,6 @@ module SweetActions
       factory = ActionFactory.new(self, action_name)
       action = factory.build_action
       action.perform_action
-      render status: action.response_code, json: action.response_data
     end
   end
 end

data/lib/sweet_actions/exceptions.rb

@@ -1,5 +1,18 @@
 module SweetActions
   module Exceptions
     class NotAuthorized < StandardError; end
+
+    class ActionNotFound < StandardError
+      attr_reader :path, :class_name
+
+      def initialize(args = {})
+        @path = args.fetch(:path, '')
+        @class_name = args.fetch(:class_name, '')
+      end
+
+      def message
+        "Action class not found. Please make sure #{class_name} exists at app/actions/#{path}."
+      end
+    end
   end
 end