legatus 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd9586b50f1209e599a2c6da395c11a0be0926bee165f0d0a1046330cf844ed1
-  data.tar.gz: ad18c8452d8f52170fc04880f6d0370e6af3f956faa49bb1ba6021d13f502d83
+  metadata.gz: 54c62e8d695d9c99e975d2170a5355fbe6f4ba9da844375ca7d485456db900db
+  data.tar.gz: b9656081c257e65998f8eff41592fea7a13c56293b62c1f4f2089f468926e71e
 SHA512:
-  metadata.gz: 226fa1d9f2d5f3168bbe4cdd3420513ceeeac36434490166555990eac2a44bed98dab8e81075fbdb85bb10f31cf90743abe9761432665261d4f0c6f57c590aa4
-  data.tar.gz: 89eef7866335b9ef6dcaea661f85643087f430e81cb8fd2a28b3bd73897080cfd34bbbe50210581696a05b922df15e4f45f145d81e3ec997d18222e4cca2aa26
+  metadata.gz: f675a9c344bd4908d683ee8a07bcaaa1dbaa9c238b704677ed5c21b6f1ad4c6fcb71047941ded5090971966bc050efd7253c0cc98c58f9720e519ee9b464b0ab
+  data.tar.gz: b46a115930c206c238147ce8309f46dc330343db1ed6ffd5aa9ea2c88de9b090f2822d80d39b288a6723181ab58087f71d986feec30887f760e678fd21b72148

data/README.md

@@ -1,8 +1,272 @@
 # Legatus
-Short description and motivation.
+Build business directives in Rails. A `Legatus::Directive` has the following properties:
+
+1. `params` - The raw parameters from a controller.
+2. `props` - The filtered out from params. In traditional Rails apps, these are usually declared in the controller (e.g. for a scaffolded `BookController`, there will be a `book_params` method which filters the raw parameters).
+2. `errors` - Errors encountered during the directive's execution.
+
+A `Legatus::Directive` also has the following default lifecycles called in sequence in the directive's `execute` (apart from initialize which is called on creation of the directive) method:
+
+1. `initialize` - Accepts raw parameters and prepares `props`.
+2. `clean` - Validate the extracted `props` for any missing or wrongly formatted input.
+3. `load` - Load models from the cleaned `props`.
+4. `validate` - Validate the loaded models (e.g. by default, done by calling `valid?` on them)
+5. `persist` - Persist the changes onto the database.
+
+When calling `execute`, each of the lifecyle methods is expected to return a value that is truthy or falsy. If the return value is falsy, the execution stops (e.g., if `clean` returns false, `load`, `validate`, and `persist` will no longer be called). A directive can also have before and after callbacks for each of the lifecycle methods.
+
+A directive can be defined in two ways:
+1. Overriding the lifecycle methods.
+2. Specifying meta information which will be used by the superclass' default methods.
 
 ## Usage
-How to use my plugin.
+
+To create a directive, the class `Legatus::Directive` should be extended and the models handled by the directive should be declared using `attr_accessor`:
+```ruby
+class Product::Item::Save < Legatus::Directive
+  attr_accessor :item
+end
+```
+
+For this example, we will be creating a directive for saving a Product which is an ActiveRecord object, wherein a Product can have many UnitPrices. 
+
+### Initialize
+
+The first step when dealing with directives is converting params from controllers into properties. In traditional Rails controllers, we would usually find:
+
+```ruby
+protected
+  def order_params
+    params[:item].permit(:id, :name, :description, :merchant_id, :status)
+  end
+
+  def line_item_params
+    params[:item].permit(unit_prices: [:price, :effective_date, :_destroy])
+  end
+```
+
+In our directive, the above would look like:
+
+```ruby
+class Product::Item::Save < Legatus::Directive
+  attr_accessor :item
+
+  def initialize(params)
+    @props = {
+      order:       params[:item].permit(:id, :name, :description, :merchant_id, :status),
+      unit_prices: params[:item].permit(unit_prices: [:price, :effective_date, :_destroy])[:unit_prices]
+    }
+  end
+end
+```
+
+Alternatively, if you don't want to override the constructor:
+
+```ruby
+class Product::Item::Save < Legatus::Directive
+  attr_accessor :item
+
+  props do
+    {
+      item:        { dig: [:item], permit: [:id, :name, :description, :partner_id, :status] },
+      unit_prices: { dig: [:item, :unit_prices], map: permit([:price, :effective_date, :_destroy]) }
+    }
+  end
+end
+```
+
+Wherein the value describes a series of method calls to be performed in sequence, that is:
+
+```ruby
+# item: { dig: [:item], permit: [:id, :name, :description, :partner_id, :status] }
+# is equivalent to:
+
+@props[:item] = params[:item].dig(:item).permit(:id, :name, :description, :partner_id, :status)
+
+# The method `permit` for `unit_prices` in the above example actually returns a lambda function which will be pased to map. 
+# unit_prices: { dig: [:item, :unit_prices], map: permit([:price, :effective_date, :_destroy]) }
+# is equivalent to:
+
+@props[:unit_prices] = params.dig(:item, :unit_prices).map &permit([:price, :effective_date, :_destroy])
+
+```
+
+The method `permit` can also handle permitting nested values, for example:
+
+```ruby
+props do
+  {
+    line_items: { 
+      dig: [:order, :line_items], 
+      map: permit(
+        [:id, :item_id, :price, :quantity, :payments, :added_at, :start_date, :end_date], 
+        payments: [:id, :amount, :paid_at, :status]
+      )
+    }
+  }
+end
+
+# The above is equivalent to:
+@props[:line_items] = params.dig(:order, :line_items).map do |li|
+  li.permit(:id, :item_id, :price, :quantity, :payments, :added_at, :start_date, :end_date).tap do |whitelisted|
+    whitelisted[:payments_attributes] = li.permit(payments: [:id, :amount, :paid_at, :status])[:payments]
+  end
+end if params[:order][:line_items].present?
+```
+
+The main advantage of using the class-level ``props`` declaration is that it will stop the chain of method invocations once the return value of one of the invocations returns nil (which is the case when the user leaves certain parameters blank). It uses ``Legatus::Chain`` to perform the method invocations.
+
+### Clean
+
+The second step is "cleaning" the extracted properties of the directive. This may include setting default or derived values as well as validations before attempting to retrieve or create `ActiveRecord` models. In `Legatus::Directive` the clean method is defined as:
+
+```ruby
+def clean
+  self.reqs(self.props, self.props.keys)
+end
+```
+
+Which simply means all properties declared in the previous step is required (i.e., the values must not return true when `.blank?` is called on them). To add a custom error, simply set a value using `@errors`:
+
+```ruby
+def clean
+  @errors[:message] = 'Not authorized' if @user.is_guest?
+end
+```
+
+Take note that adding a value to `@error` will cause `valid?` of the directive to return false. Which will halt the execution chain if `execute` is used in the directive because `execute` will call `valid?` before proceeding to the next step.
+
+### Load
+
+The third step is loading or initializing models or services that will be used to persist the changes for the directive. We can override it like so:
+
+```ruby
+def load
+  @item = Product::Item.find_and_init(
+    @props[:item].slice(:id),
+    @props[:item].merge(unit_prices_attributes: @props[:unit_prices])
+  )
+end
+```
+
+In the above example, the method `find_and_init` is defined in `Legatus::Repository`. It simply uses find_by on the first parameter, instantiates a new one if none is found, and then sets the attributes of that model using the second attribute.
+
+Alternatively, models can be declared using:
+
+```ruby
+class Product::Item::Save < Legatus::Directive
+  attr_accessor :item
+
+  model(:item) do |props|
+    Product::Item.find_and_init(
+      props[:item].slice(:id),
+      props[:item].merge(unit_prices_attributes: props[:unit_prices])
+    )
+  end
+end
+```
+
+Attributes declared using `attr_accessor` can be injected onto the lambda function passed to `model` so long as the parameter name in the lambda function is the same as the attribute. For example, using a more complex directive:
+
+```ruby
+class School::Student::Registration < Legatus::Directive
+
+  attr_accessor :user, :university, 
+                :graduate, :student, :enrollment
+
+  props do |params|
+    #...
+  end
+  
+  model(:user) do |props|
+    #...
+  end
+
+  model(:university) do |props|
+    #...
+  end
+
+  # The attributes user and university is passed onto the lambda
+  model(:graduate) do |props, user, university|
+    Credential::Graduate.find_and_init(
+      props[:graduate].merge(
+        user:       user,
+        university: university
+      )
+    )
+  end
+end
+```
+
+This is achived using the flexcon gem.
+
+### Validate
+
+The fourth step is the validation of the models. If you defined the models at the class level (e.g. `model(:item) { ... }`), by default, all models registered that way will be validated because the metadata on which attributes of the directive are models is available. On the other hand, if a custom load model was defined, you can also define a custom validate model:
+
+```ruby
+def validate
+  if @item.invalid?
+    @errors[key] ||= {}
+    @errors[key].merge!(@item.errors)
+  end
+end
+```
+
+### Persist
+
+The fifth and final step is persisting the changes to the database. You can define a custom `persist` method:
+
+```ruby
+def persist
+  @item.save
+end
+```
+
+Or define it at the class level:
+
+```ruby
+class Product::Item::Save < Legatus::Directive
+
+  attr_accessor :item
+
+  transaction do |uow, operation|
+    uow.save operation.item
+  end
+end
+```
+
+The uow above is a ```Legatus::UnitOfWork``` which is useful for directives that persist multiple models. A unit of work will store all save operations as lambda functions and will only start persisting them when `commit` is called. This is useful for when there are additional logic that needs to be performed  in between saving models. Such that when `commit` is called, only persistence operations are performed. When a transaction is defined at the class level, the `commit` automatically after calling the block.
+
+### All Together Now
+
+The save order directive, using class-level definitions, would then look like:
+
+```ruby
+class Product::Item::Save < Legatus::Directive
+
+  attr_accessor :item
+
+  props do |params|
+    {
+      item:        { dig: [:item], permit: [:id, :name, :description, :partner_id, :status] },
+      unit_prices: { dig: [:item, :unit_prices], map: permit([:price, :effective_date, :_destroy]) }
+    }
+  end
+
+  model(:item) do |props|
+    Product::Item.find_and_init(
+      props[:item].slice(:id),
+      props[:item].merge(unit_prices_attributes: props[:unit_prices])
+    )
+  end
+
+  transaction do |uow, operation|
+    uow.save operation.item
+  end
+end
+```
+
 
 ## Installation
 Add this line to your application's Gemfile:

data/lib/legatus/directive.rb

@@ -21,17 +21,25 @@ module Legatus
         end
       end
 
-      def permit(parent, attributes, subschema=nil)
-        result = parent.permit(attributes)
-        result.tap do |whitelisted|
-          subschema.each do |key, allowed|
-            child = parent[key]
-            next if child.nil?
-            
-            if child.is_a?(Array)
-              whitelisted[key] = child.map { |c| c.permit(allowed) }
-            else
-              whitelisted[key] = child.permit(allowed)
+      def chain(obj, invocations)
+        return Chain.new(invocations).apply(obj)
+      end
+
+      def permit(attributes, subschema=nil)
+        lambda do |parent|
+          result = parent.permit(attributes)
+          return result if subschema.nil?
+
+          result.tap do |whitelisted|
+            subschema.each do |key, allowed|
+              child = parent[key]
+              next if child.nil?
+              
+              if child.is_a?(Array)
+                whitelisted[:"#{key}_attributes"] = child.map { |c| c.permit(allowed) }
+              else
+                whitelisted[:"#{key}_attributes"] = child.permit(allowed)
+              end
             end
           end
         end
@@ -93,38 +101,39 @@ module Legatus
     end
 
     def validate
-      self.valid? and self.class.validations.each do |mname|
-        self.check(mname => self.send(mname))
-      end if self.class.validations.present?
+      return (
+        self.valid? and self.class.validations.each do |mname|
+          self.check(mname => self.send(mname))
+        end
+      ) if self.class.validations.present?
 
-      self.valid? and self.class.models.each do |mname, loader|
-        self.check(mname => self.send(mname))
-      end if self.class.models.present?
+      return (
+        self.valid? and self.class.models.each do |mname, loader|
+          self.check(mname => self.send(mname))
+        end
+      ) if self.class.models.present?
     end
 
     def persist
-      self.valid? and UnitOfWork.transaction do |uow|
-        self.class.transactions.each do |handler|
-          handler.call(uow, self)
-        end
-      end
+      return nil if self.invalid?
+
+      self.class.transactions.each do |handler|
+        uow = UnitOfWork.new
+        handler.call(uow, self)
+        uow.commit
+      end if self.class.transactions.present?
     end
     
     def execute
       return (
-        self.valid? and
-        self.executed?(:clean) and
-        self.executed?(:load) and 
-        self.executed?(:validate) and
-        self.executed?(:persist)
+        self.valid? and self.executed?(:clean) and
+        self.valid? and self.executed?(:load) and 
+        self.valid? and self.executed?(:validate) and
+        self.valid? and self.executed?(:persist)
       )
     end
 
     protected
-      def chain(obj, invocations)
-        return Chain.new(invocations).apply(obj)
-      end
-
       def reqs(source, attributes)
         attributes.each do |attribute|
           next if not source[attribute].blank?

data/lib/legatus/extensions/hash.rb

@@ -1,5 +1,5 @@
 class Hash
   def permit(*keys)
-    self.slice(keys)
+    self.slice(*keys)
   end
 end

data/lib/legatus/repository.rb

@@ -1,25 +1,30 @@
 module Legatus
   module Repository
     extend ActiveSupport::Concern
-
     class_methods do
       def find_and_init(filters, attributes=nil)
-        instance = self.find_by(filters)
+        instance = self.find_one(filters)
         instance ||= self.new
 
-        attributes ||= filters
+        attributes = filters if attributes.blank?
         instance.assign_attributes(attributes) 
 
         return instance
       end
 
       def find_or_init(filters, attributes)
-        instance = self.find_by(filters)
-        return if instance.present?
+        instance = self.find_one(filters)
+        return instance if instance.present?
 
         instance = self.new
         instance.assign_attributes(attributes) 
       end
+
+      def find_one(filters)
+        instance = filters.find { |f| self.find_by(f) } if filters.is_a?(Array)
+        instance ||= self.find_by(filters)
+        return instance
+      end
     end
   end
 end

data/lib/legatus/unit_of_work.rb

@@ -1,36 +1,74 @@
 module Legatus
   class UnitOfWork
 
-    def self.transaction
-      ActiveRecord::Base.connection.transaction do 
-        yield(UnitOfWork.new)
-      end
+    def initialize
+      @steps = []
     end
 
     def save(*models)
-      models.all? { |model| model.save }
+      @steps << lambda do 
+        models.all? { |model| self.execute(:save, model) }
+      end
     end
 
     def update(*models)
-      models.all? { |model| model.update }
+      @steps << lambda do 
+        models.all? { |model| self.execute(:update, model) }
+      end
     end
 
     def create(*models)
-      models.all? { |model| model.create }
+      @steps << lambda do 
+        models.all? { |model| self.execute(:create, model) }
+      end
     end
 
     def destroy(*models)
-      models.all? { |model| model.destroy }
+      @steps << lambda do 
+        models.all? { |model| self.execute(:destroy, model) }
+      end
     end
 
     def persist(*models)
-      models.all? do |model| 
-        if model.marked_for_destruction?
-          model.destroy
-        else
-          model.save
+      @steps << lambda do 
+        models.all? do |model| 
+          if model.is_a?(Array)
+            model.all? { |elem| self.save_or_destroy(elem) }
+          else
+            self.save_or_destroy(model)
+          end
         end
       end
     end
+
+    def denormalize(model, schema)
+      @steps << lambda do 
+        schema.each do |field, subschema|
+          assoc    = subschema.keys[0]
+          aggre    = subschema.values[0].keys[0]
+          subfield = subschema.values[0].values[0]
+
+          model[field] = model.send(subschema.keys[0]).send(aggre, subfield)
+        end
+        model.save
+      end
+    end
+
+    def commit
+      ActiveRecord::Base.connection.transaction do 
+        @steps.all? { |step| step.call }
+      end
+    end
+
+    protected
+      def execute(methodname, model)
+        return model.all? { |elem| elem.send(methodname) } if model.is_a?(Array)
+        return model.send(methodname)
+      end
+
+      def save_or_destroy(model)
+        return model.destroy if model.marked_for_destruction?
+        return model.save
+      end
   end
 end

data/lib/legatus/version.rb

@@ -1,3 +1,3 @@
 module Legatus
-  VERSION = '0.1.0'
+  VERSION = '0.1.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: legatus
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - rcpedro
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-09-21 00:00:00.000000000 Z
+date: 2018-10-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails