model_orchestration 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: de10668d300579c46514a77f11173ae448475a17
+  data.tar.gz: 14efbe148901ed70aae1e6d1f21acc70c39fa374
+SHA512:
+  metadata.gz: 6073f623db3865ce5cba153d84a6e22ac337e4ff4001b6f335c889e855d33b7c14580002cc0ff26d3b34c8d27f52e9bd30607582495739ee7b2e4c1f3bb2dd33
+  data.tar.gz: 6121df9b444912aa9e3ddb6f27e3cadb06bd161c2f176976cb8ba7e7c8627b327096bd78b26e174ed440b7cfac00ccd1138b0f6fc470db35b7f6be143b6c635b

data/README.md

@@ -0,0 +1,69 @@
+# Model Orchestration - orchestrating actions on related models
+
+`ModelOrchestration` is a toolkit to help with orchestrating handling of multiple models that are related to each other.
+
+The basic idea is to create a new model in which you can nest other models. You can declare relations between the nested models. The new orchestration model then provides interfaces for persistence actions, validations etc. Under the hood, the model orchestrates the save, validate etc. actions on all the nested models.
+
+## Example
+
+Consider you're developing a B2B SaaS application with a signup form. When a new client signs up, you will probably need to create multiple models and save them to the database, for example a user object, representing the person signing up and an organization object which attaches the user to a legal entity which represents your customer, billing data etc.
+
++ModelOrchestration+ allows you to nest the user model and the organization model into a meta model, on which all the actions necessary can be performed (validation, persistence). Let's call this "meta model" simply `Signup`.
+
+```ruby
+class User < ActiveRecord::Base
+  belongs_to :organization
+  validates :name, presence: true
+  validates :email, presence: true
+end
+
+class Organization < ActiveRecord::Base
+  has_many :users
+  validates :name, presence: true
+end
+
+class Signup
+  include ModelOrchestration::Base
+  include ModelOrchestration::Persistence
+  
+  nested_model :organization
+  nested_model :user
+  nested_model_dependency from: :user, to: :organization
+end
+
+signup = Signup.new(user: {name: "Nils", email: "nils@example.org"}, organization: {name: "Nils' Webdesign Agency"})
+
+signup.valid? # => true
+
+signup.user.name # => "Nils"
+signup.user # => #<User:0x007f81f498d078> 
+signup[:user][:email] # => "nils@example.org"
+
+signup.save # => true
+```
+
+`ModelOrchestration::Persistence` only needs to be included if you need
+`save` and `create` method variations. Leaving it you can still use `ModelOrchestration::Base` alone with `ActiveModel` models.
+
+## Download and installation
+
+The latest version of Orchestration Model can be installed with RubyGems:
+
+```bash
+gem install model_orchestration
+```
+
+The source code can be downloaded on GitHub
+
+* https://github.com/nsommer/orchestration_model
+
+## Development & Contributions
+
+Contributions are welcome. Please use GitHub's issue tracker and pull requests to provide patches.
+
+## License
+
+Model Orchestration is released under the MIT license:
+
+* http://www.opensource.org/licenses/MIT
+    

data/lib/model_orchestration.rb

@@ -0,0 +1,43 @@
+require 'active_support/all'
+
+##
+# +ModelOrchestration+ is a toolkit to help with orchestrating handling
+# of multiple models that are related to each other.
+#
+# The basic idea is to create a new model in which you can nest other models.
+# You can declare relations between the nested models. The new orchestration
+# model then provides interfaces for persistence actions, validations etc.
+# Under the hood, the model orchestrates the save, validate etc. actions on
+# all the nested models.
+#
+# Maybe it's easier to explain by using an example. Consider a web application
+# where users can sign up and create an account. But instead of just creating
+# a user account, you also want to attach them to an organization, e.g. to
+# connect billing information which is shared between multiple users. Therefore
+# you might want to create an employee model and a company model at the same
+# time.
+#
+#   class Signup
+#     include ModelOrchestration::Base
+#     include ModelOrchestration::Persistence
+#   
+#     nested_model :company
+#     nested_model :employee
+#   
+#     nested_model_dependency from: :employee, to: :company
+#   end
+#
+# The Signup class prodives you with a lot of automatically generated methods
+# that feel familiar from an ActiveModel/ActiveRecord perspective.
+#
+# For example, you automaticall get a constructor, that accepts an attributes
+# hash which feeds the nested models.
+#
+#   signup = Signup.new(company: {name: "Foo Inc"}, employee: {name: "Bob"})
+#
+module ModelOrchestration
+  extend ActiveSupport::Autoload
+  
+  autoload :Base
+  autoload :Persistence
+end

data/lib/model_orchestration/base.rb

@@ -0,0 +1,201 @@
+module ModelOrchestration
+  class DependencyCycleError < StandardError
+  end
+  
+  ##
+  # The module containing the base functionality. This includes class methods
+  # to specify nested models and dependencies, as well as ActiveModel-like
+  # functionality, such as attribute accessors for the nested models and 
+  # validation methods.
+  module Base
+    extend ActiveSupport::Concern
+    
+    included do
+      class_attribute :nested_models, :dependencies
+      self.nested_models = []
+      self.dependencies  = {}
+    end
+  
+    module ClassMethods
+      ##
+      # Class method to declare a nested model. This invokes instantiation
+      # of the model when the holding model is instantiated. The nested model
+      # can be declared by symbol, type or string.
+      #
+      #   class HoldingClass
+      #     include ModelOrchestration::Base
+      #   
+      #     nested_model :user
+      #   end
+      def nested_model(model)
+        model_key = symbolize(model)
+      
+        self.nested_models << model_key
+      end
+  
+      ##
+      # Class method to declare a dependency from one nested model to another.
+      #
+      #   class Signup
+      #     include ModelOrchestration::Base
+      #   
+      #     nested_model :company
+      #     nested_model :employee
+      #   
+      #     nested_model_dependency from: :employee, to: :company
+      #   end
+      #
+      # The example obove might be used to orchestrate the signup process of
+      # a user who creates an account representative for his company. In the
+      # database schema, company and employee have a 1:n relation, which is
+      # represented by +nested_model_dependency+.
+      def nested_model_dependency(args = {})
+        unless args.include?(:from) && args.include?(:to)
+          raise ArgumentError, ":from and :to hash keys must be included."
+        end
+        
+        from = symbolize(args[:from])
+        to   = symbolize(args[:to])
+        
+        if dependency_introduces_cycle?(from, to)
+          raise ModelOrchestration::DependencyCycleError, "#{from} is already a dependency of #{to}"
+        end
+    
+        self.dependencies[from] = to
+      end
+    
+      private
+    
+        def symbolize(arg)
+          if arg.is_a? Symbol
+            arg
+          elsif arg.is_a? String
+            arg.underscore.to_sym
+          elsif arg.is_a? Class
+            arg.name.underscore.to_sym
+          else
+            arg.to_s.underscore.to_sym
+          end
+        end
+        
+        def dependency_introduces_cycle?(from, to)
+          self.dependencies.include?(to) && (self.dependencies[to] == from)
+        end
+    end
+    
+    ##
+    # Instantiate the model and all nested models. Attributes can be submitted
+    # as a hash and will be handed over to the nested models.
+    def initialize(attrs = {})
+      @nested_model_instances = {}
+    
+      self.nested_models.each do |model|
+        klass = model.to_s.classify.constantize
+      
+        if attrs.include?(model)
+          @nested_model_instances[model] = klass.new(attrs[model])
+        else
+          @nested_model_instances[model] = klass.new
+        end
+      end
+    
+      self.dependencies.each do |from, to|
+        @nested_model_instances[from].public_send("#{to.to_s}=", @nested_model_instances[to])
+      end
+    end
+  
+    ##
+    # Get a nested model by name (symbol).
+    #
+    #   class Signup
+    #     include ModelOrchestration::Base
+    #   
+    #     nested_model :company
+    #     nested_model :employee
+    #   
+    #     nested_model_dependency from: :employee, to: :company
+    #   end
+    #   
+    #   signup  = Signup.new
+    #   company = signup[:company]
+    #
+    # Because ActiveRecord classes also support the +[]+ method, it can
+    # be chained to get attributes of nested models.
+    #
+    #   company_name = signup[:company][:name]
+    #
+    def [](key)
+      send key
+    end
+    
+    ##
+    # Set a nested model by name (symbol).
+    #
+    #   class Signup
+    #     include ModelOrchestration::Base
+    #   
+    #     nested_model :company
+    #     nested_model :employee
+    #   
+    #     nested_model_dependency from: :employee, to: :company
+    #   end
+    #   
+    #   signup  = Signup.new
+    #   signup[:company] = Company.new
+    def []=(key, value)
+      send "#{key}=", value
+    end
+  
+    ##
+    # Implements attribute accessor methods for nested models.
+    def method_missing(message, *args, &block)
+      if @nested_model_instances.include?(message)
+        # Get nested model accessor
+        @nested_model_instances[message]
+      elsif message =~ /^([^=]+)=$/
+        # Set nested model accessor
+        attr = message.to_s.chop.to_sym
+        if @nested_model_instances.include?(attr)
+          @nested_model_instances[attr] = args.first
+        else
+          super
+        end
+      else
+        super
+      end
+    end
+    
+    ##
+    # See: http://api.rubyonrails.org/classes/ActiveModel/Validations.html#method-i-valid-3F
+    def valid?(context = nil)
+      valid = true
+    
+      @nested_model_instances.each do |key, instance|
+        valid = false unless instance.valid?(context)
+      end
+  
+      valid
+    end
+    
+    ##
+    # See: http://api.rubyonrails.org/classes/ActiveModel/Validations.html#method-i-validate
+    alias_method :validate, :valid?
+    
+    # See: http://api.rubyonrails.org/classes/ActiveModel/Validations.html#method-i-invalid-3F
+    def invalid?(context = nil)
+      !valid?(context)
+    end
+    
+    ##
+    # See: http://api.rubyonrails.org/classes/ActiveModel/Validations.html#method-i-validate-21
+    def validate!(context = nil)
+      valid?(context) || raise_validation_error
+    end
+    
+    protected
+    
+      def raise_validation_error
+        raise(ValidationError.new(self))
+      end
+  end
+end

data/lib/model_orchestration/persistence.rb

@@ -0,0 +1,51 @@
+module ModelOrchestration
+  ##
+  # Including this module will give an OrchestrationModel::Base ActiveRecord-like
+  # methods for perstistence. The methods available are restricted to
+  # variations of save and create because updating/deleting/finding are
+  # usually actions performed on a single record, not an orchestrated meta
+  # model. 
+  module Persistence
+    extend ActiveSupport::Concern
+    
+    included do
+      include ModelOrchestration::Base
+    end
+    
+    module ClassMethods
+      ##
+      # See: http://api.rubyonrails.org/classes/ActiveRecord/Persistence/ClassMethods.html#method-i-create
+      def create(attrs = {}, &block)
+        object = new(attrs, &block)
+        object.save
+        object
+      end
+      
+      ##
+      # http://api.rubyonrails.org/classes/ActiveRecord/Persistence/ClassMethods.html#method-i-create-21
+      def create!(attrs = {}, &block)
+        object = new(attrs, &block)
+        object.save!
+        object
+      end
+    end
+    
+    ##
+    # See: http://api.rubyonrails.org/classes/ActiveRecord/Persistence.html#method-i-save
+    def save(*args)
+      @nested_model_instances.each do |key, instance|
+        return false unless instance.save(args)
+      end
+    
+      true
+    end
+    
+    ##
+    # See: http://api.rubyonrails.org/classes/ActiveRecord/Persistence.html#method-i-save-21
+    def save!(*args)
+      @nested_model_instances.each do |key, instance|
+        instance.save(args)
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: model_orchestration
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Nils Sommer
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-02-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5'
+description: In more complex workflows, multiple models that are related to each other
+  need to be created at the same time. This toolkit allows to specifiy models that
+  orchestrate persistence and validation actions of multiple models by nesting them
+  into a so called orchestration model.
+email: mail@nilssommer.de
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- lib/model_orchestration.rb
+- lib/model_orchestration/base.rb
+- lib/model_orchestration/persistence.rb
+homepage: https://github.com/nsommer/model_orchestration
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.2.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: A toolkit for orchestrating actions on related models.
+test_files: []