pragma 1.2.6 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a231e9c37711edada72361aff42676d8713903b1
-  data.tar.gz: a43091b07a58d402f346abe79abbc9fb88b086a5
+  metadata.gz: 27c896a2d1034183edbcae9079c7f435057e62da
+  data.tar.gz: bc5a709485d117f346b7d23880ab155e8d66392b
 SHA512:
-  metadata.gz: 97a24156d5da33359875dfdd96f96d04e8c3243e727915036a9b72ddb4a964340ee5d648260a8718f63f75078e0da1849ed7a7c2100f6de9bc20a09897bbbd0c
-  data.tar.gz: dab8c7acf8751282f8f8fa2a89c5e01afbe8e44a1bc45262fb7c3d8813e41b7080a8938f2311b792e9f643539f511e5066f6acad0705e2214c8d9824ee978eab
+  metadata.gz: b754320e5db9566992162c53ab8f1db93f5f073021745a5975ac7ea3ddd4c2334ebcaf39fb69447191c8dc2e2efd7574b685fa0703b222655303f2b00d4ebe79
+  data.tar.gz: 6067ff68d0fbaa81cc5de835109650bb4b7d4811a0795f0a76fc7b5dc6cbca8b042cbd54ebb9ea489dcec737e7b0df755d02b7609b2e3ab610e77312df537d66

data/.rubocop.yml

@@ -24,26 +24,26 @@ Style/BlockDelimiters:
   Exclude:
     - 'spec/**/*'
 
-Style/AlignParameters:
+Layout/AlignParameters:
   EnforcedStyle: with_fixed_indentation
 
-Style/ClosingParenthesisIndentation:
+Layout/ClosingParenthesisIndentation:
   Enabled: false
 
 Metrics/LineLength:
   Max: 100
   AllowURI: true
 
-Style/FirstParameterIndentation:
+Layout/FirstParameterIndentation:
   Enabled: false
 
-Style/MultilineMethodCallIndentation:
+Layout/MultilineMethodCallIndentation:
   EnforcedStyle: indented
 
-Style/IndentArray:
+Layout/IndentArray:
   EnforcedStyle: consistent
 
-Style/IndentHash:
+Layout/IndentHash:
   EnforcedStyle: consistent
 
 Style/SignalException:
@@ -53,7 +53,7 @@ Style/BracesAroundHashParameters:
   EnforcedStyle: context_dependent
 
 Lint/EndAlignment:
-  AlignWith: variable
+  EnforcedStyleAlignWith: variable
   AutoCorrect: true
 
 Style/AndOr:
@@ -68,7 +68,7 @@ RSpec/NamedSubject:
 RSpec/ExampleLength:
   Enabled: false
 
-Style/MultilineMethodCallBraceLayout:
+Layout/MultilineMethodCallBraceLayout:
   Enabled: false
 
 Metrics/MethodLength:
@@ -85,3 +85,6 @@ Metrics/CyclomaticComplexity:
 
 Metrics/ClassLength:
   Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false

data/Gemfile

@@ -4,3 +4,8 @@ source 'https://rubygems.org'
 gemspec
 
 gem 'pry'
+
+gem 'pragma-policy', github: 'pragmarb/pragma-policy'
+gem 'pragma-operation', github: 'pragmarb/pragma-operation'
+gem 'pragma-contract', github: 'pragmarb/pragma-contract'
+gem 'pragma-decorator', github: 'pragmarb/pragma-decorator'

data/README.md

@@ -24,25 +24,25 @@ Looking for a Rails integration? Check out [pragma-rails](https://github.com/pra
 Pragma was created with a very specific goal in mind: to make the development of JSON APIs a matter
 of hours, not days. In other words, Pragma is for JSON APIs what Rails is for web applications.
 
-In order to achieve that goal, some ground rules were needed. Here they are.
+Here are the ground rules:
 
 1. **Pragma is opinionated.** With Pragma, you don't get to make a lot of choices and that's
    _exactly_ why people are using it: they want to focus on the business logic of their API rather
    than the useless details. We understand this approach will not work in some cases and that's
    alright. If you need more personalization, only use a subset of Pragma (see item 2) or something
    else.
-2. **Pragma is modular.** Pragma is built as a set of gems (currently 4), plus some standalone
+2. **Pragma is modular.** Pragma is built as a set of gems (currently 6), plus some standalone
    tools. You can pick one or more modules and use them in your application as you see fit. Even
    though they are completely independent from each other, they nicely integrate and work best when
    used together, creating an ecosystem that will dramatically speed up your design and development
    process.
-3. **Pragma is not designed to be Rails-free.** This does not mean that Pragma _is not_ Rails free.
-   Our Rails integration is decoupled from the rest of the ecosystem and all of the gems, in their
-   current state, _can_ be used without Rails. However, this is just a byproduct of the project's
-   design: independence from Rails is not a goal of the Pragma ecosystem, so don't count on it too
-   much.
+3. **Pragma is designed to be Rails-free.** Just as what happens with Trailblazer, our Rails 
+   integration is decoupled from the rest of the ecosystem and all of the gems can be used without 
+   Rails. This is just a byproduct of the project's design: Pragma is built with pure Ruby.
+   [pragma-rails](https://github.com/pragmarb/pragma-rails) is the only available framework 
+   integration at the moment, but more will come! 
 
-## Why not Trailblazer?
+### Why not Trailblazer?
 
 [Trailblazer](https://github.com/trailblazer/trailblazer) and all of its companion projects are
 awesome. They are so awesome that Pragma is built on top of them: even though we're not using
@@ -50,7 +50,8 @@ the Trailblazer gem itself yet, many of the Pragma gems are simply extensions of
 counterparts:
 
 - decorators are [ROAR representers](https://github.com/apotonick/roar);
-- contracts are [Reform forms](https://github.com/apotonick/reform).
+- contracts are [Reform forms](https://github.com/apotonick/reform);
+- operations are [Trailblazer operations](https://github.com/trailblazer/trailblazer-operation).
 
 Trailblazer and Pragma have different (but similar) places in the Ruby world: Trailblazer is an
 architecture for building all kinds of web applications in an intelligent, rational way, while
@@ -82,7 +83,61 @@ $ gem install pragma
 
 ## Usage
 
-All documentation is in the [doc](https://github.com/pragmarb/pragma/tree/master/doc) folder.
+### Project Structure
+
+This gem works best if you follow the recommended structure for organizing resources:
+
+```
+└── api
+    └── v1
+        └── article
+            ├── contract
+            │   ├── create.rb
+            │   └── update.rb
+            ├── operation
+            │   ├── create.rb
+            │   ├── destroy.rb
+            │   ├── index.rb
+            │   └── update.rb
+            └── policy.rb
+            └── decorator.rb
+```
+
+Your modules and classes would, of course, follow the same structure: `API::V1::Article::Policy` and 
+so on and so forth.
+
+If you adhere to this structure, the gem will be able to locate all of your classes without any
+explicit configuration. This will save you a lot of time and is highly recommended.
+
+### Fantastic Five
+
+Pragma comes with five built-in operations, often referred to as Fantastic Five (or "FF" for 
+brevity). They are, of course, Index, Show, Create, Update and Destroy. 
+
+These operations leverage the full power of the integrated Pragma ecosystem and require all four 
+components to be properly installed and configured in your application. You may reconfigure them
+to skip some of the steps, but it is highly recommended to use them as they come.
+
+You can find these operations under [lib/pragma/operation](https://github.com/pragmarb/pragma/tree/master/lib/pragma/operation).
+To use them, simply create your own operations and inherit from ours. For instance:
+
+```ruby
+module API
+  module V1
+    module Article
+      module Operation
+        class Create < Pragma::Operation::Create
+          # This assumes that you have the following:
+          #   - a policy that responds to #create?
+          #   - a Create contract
+          #   - a decorator
+          #   - an Article model
+        end
+      end
+    end
+  end
+end
+```
 
 ## Contributing
 

data/lib/pragma.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 require 'pragma/operation'
 require 'pragma/policy'
 require 'pragma/contract'
@@ -9,7 +10,17 @@ require 'will_paginate/array'
 
 require 'pragma/version'
 
-require 'pragma/operation/defaults'
+require 'pragma/decorator/error'
+
+require 'pragma/operation/macro/classes'
+require 'pragma/operation/macro/decorator'
+require 'pragma/operation/macro/pagination'
+require 'pragma/operation/macro/policy'
+require 'pragma/operation/macro/model'
+require 'pragma/operation/macro/contract/build'
+require 'pragma/operation/macro/contract/validate'
+require 'pragma/operation/macro/contract/persist'
+
 require 'pragma/operation/index'
 require 'pragma/operation/show'
 require 'pragma/operation/create'

data/lib/pragma/decorator/error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Pragma
+  module Decorator
+    class Error < Pragma::Decorator::Base
+      property :error_type
+      property :error_message
+      property :meta
+    end
+  end
+end

data/lib/pragma/operation/create.rb

@@ -1,33 +1,24 @@
 # frozen_string_literal: true
+
 module Pragma
   module Operation
-    # Finds the requested record, authorizes it, updates it accordingly to the parameters and
-    # responds with the decorated record.
+    # Creates a new record and responds with the decorated record.
     #
     # @author Alessandro Desantis
     class Create < Pragma::Operation::Base
-      include Pragma::Operation::Defaults
-
-      def call
-        context.record = build_record
-        context.contract = build_contract(context.record)
-
-        validate! context.contract
-        authorize! context.contract
-
-        context.contract.save
-        context.record.save!
-
-        respond_with status: :created, resource: decorate(context.record)
-      end
-
-      protected
+      step Macro::Classes()
+      step Macro::Model()
+      step Macro::Policy(), fail_fast: true
+      step Macro::Contract::Build()
+      step Macro::Contract::Validate(), fail_fast: true
+      step Macro::Contract::Persist(), fail_fast: true
+      step Macro::Decorator()
+      step :respond!
 
-      # Builds the requested record.
-      #
-      # @return [Object]
-      def build_record
-        self.class.model_klass.new
+      def respond!(options)
+        options['result.response'] = Response::Created.new(
+          entity: options['result.decorator.instance']
+        )
       end
     end
   end

data/lib/pragma/operation/destroy.rb

@@ -1,28 +1,30 @@
 # frozen_string_literal: true
+
 module Pragma
   module Operation
-    # Finds the requested record, authorizes it and decorates it.
+    # Finds an existing record, destroys it and responds 204 No Content.
     #
     # @author Alessandro Desantis
     class Destroy < Pragma::Operation::Base
-      include Pragma::Operation::Defaults
-
-      def call
-        context.record = find_record
-        authorize! context.record
+      step Macro::Classes()
+      step Macro::Model(:find_by), fail_fast: true
+      step Macro::Policy(), fail_fast: true
+      step :destroy!
+      failure :handle_invalid_model!, fail_fast: true
+      step :respond!
 
-        context.record.destroy!
-
-        head :no_content
+      def destroy!(_options, model:, **)
+        model.destroy
       end
 
-      protected
+      def handle_invalid_model!(options, model:, **)
+        options['result.response'] = Response::UnprocessableEntity.new(
+          errors: model.errors
+        ).decorate_with(Decorator::Error)
+      end
 
-      # Finds the requested record.
-      #
-      # @return [Object]
-      def find_record
-        self.class.model_klass.find(params[:id])
+      def respond!(options)
+        options['result.response'] = Response::NoContent.new
       end
     end
   end

data/lib/pragma/operation/index.rb

@@ -1,115 +1,33 @@
 # frozen_string_literal: true
+
+require 'trailblazer/dsl'
+
 module Pragma
   module Operation
-    # Finds all records of the requested resource, authorizes them, paginates them and returns
-    # the decorated collection.
+    # Finds all records of the requested resource, authorizes them, paginates them and decorates
+    # them.
     #
     # @author Alessandro Desantis
     class Index < Pragma::Operation::Base
-      include Pragma::Operation::Defaults
-
-      def call
-        context.records = authorize_collection(find_records)
-
-        begin
-          context.records = context.records.paginate(page: page, per_page: per_page)
-        rescue RangeError => e
-          respond_with!(
-            status: :bad_request,
-            resource: {
-              error_type: :invalid_page,
-              error_message: e.message
-            }
-          )
-        end
-
-        respond_with(
-          resource: decorate(context.records),
-          status: :ok,
-          headers: {
-            'Page' => context.records.current_page.to_i,
-            'Per-Page' => context.records.per_page,
-            'Total' => context.records.total_entries
-          },
-          links: {
-            first: build_page_url(1),
-            last: build_page_url(context.records.total_pages),
-            next: (build_page_url(context.records.next_page) if context.records.next_page),
-            prev: (build_page_url(context.records.previous_page) if context.records.previous_page)
-          }
-        )
-      end
-
-      protected
-
-      # Finds all the records. By default, calls +.all+ on the model class, which is inferred from
-      # the operation's namespace (e.g. +API::V1::Post::Operation::Index+ will retrieve all records
-      # of the +Post+ model).
-      #
-      # @return [Enumerable]
-      def find_records
-        self.class.model_klass.all
-      end
+      step Macro::Classes()
+      step :retrieve!
+      step :scope!
+      step Macro::Pagination(), fail_fast: true
+      step Macro::Decorator(name: :collection), fail_fast: true
+      step :respond!
 
-      # Returns the name of the page parameter.
-      #
-      # @return [Symbol]
-      def page_param
-        :page
+      def retrieve!(options)
+        options['model'] = options['model.class'].all
       end
 
-      # Returns the page number. By default, this is the page parameter or 1 if it is empty.
-      #
-      # @return [Fixnum]
-      #
-      # @see #page_param
-      def page
-        return 1 if !params[page_param] || params[page_param].empty?
-        params[page_param].to_i
+      def scope!(options, current_user:, model:, **)
+        options['model'] = options['policy.default.scope.class'].new(current_user, model).resolve
       end
 
-      # Returns the name of the per_page param.
-      #
-      # @return [Symbol]
-      def per_page_param
-        :per_page
-      end
-
-      # Returns the default number of records per page.
-      #
-      # @return [Fixnum]
-      def default_per_page
-        30
-      end
-
-      # Returns the maximum number of records per page.
-      #
-      # @return [Fixnum]
-      def max_per_page
-        100
-      end
-
-      # Returns the number of records to include per page. By default, this is the +per_page+
-      # parameter, up to a maximum of {#max_per_page} records, or {#default_per_page} if the
-      # parameter is not present.
-      #
-      # @return [Fixnum]
-      #
-      # @see #default_per_page
-      # @see #max_per_page
-      # @see #per_page_param
-      def per_page
-        return default_per_page if !params[per_page_param] || params[per_page_param].empty?
-        params[per_page_param].to_i > max_per_page ? max_per_page : params[per_page_param].to_i
-      end
-
-      # Builds the URL to a specific page in the collection.
-      #
-      # @param page [Fixnum] a page number
-      #
-      # @return [String]
-      def build_page_url(_page)
-        nil
+      def respond!(options, model:, **)
+        options['result.response'] = Response::Ok.new(
+          entity: options['result.decorator.collection']
+        )
       end
     end
   end