appfuel 0.2.3 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7ec8fcf3de5624419dfb3b092481e0b1d5a8c581
-  data.tar.gz: 7816976958c040abda4270e68ecf8ba88cfe744f
+  metadata.gz: 6aa8eb41aca3f2b82a2b9affbb29399c8407a1ed
+  data.tar.gz: 9edc5e0b91bf9acde76210f9e0b1fd84b5d96f78
 SHA512:
-  metadata.gz: 7abff44b24913fe1afd206a23b7e34e885c547fefa2c48ec06869b1fd0ca6b384ea9425ccc08fb601408a2fe584b5214dd26c37b93f57bde3f583455734696d3
-  data.tar.gz: 6ad6e1e1e8004aaff9c2cf07c77eaf4ab82f835d10d6412b17945e7239f0e2a5e58e0c72d6e8687c81c9eb8d6c7726773957bf066f7f70cc02bdf624b1cdd859
+  metadata.gz: 9f779a784215090476418ff5932c6a8b26ad625805494e7851ae469ec4c1b8da5cc452daa7a6815d270fc3a1f82f65e056d50e4139bd23101e738aad8a9f0634
+  data.tar.gz: 57867104cf6bc9650d2c7b17ac45547222893ca43ee8c67add88cc9d878ccfd4283d69a5abdb81d1b606b6f711243305a8965298ed75707bb7ac9e7736e56cae

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Change Log
+All notable changes to this project will be documented in this file. (Pending approval) This project adheres to [Semantic Versioning](http://semver.org/). You can read more on this at [keep a change log](http://keepachangelog.com/)
+
+# [Unreleased]
+
+# Releases
+## [[0.2.5]](https://github.com/rsb/appfuel/releases/tag/0.2.4) 2017-05-23
+### Changed
+- `Appfuel::Domain::BaseCriteria` can now qualify `domain exprs`
+- refactored and tested repo mapper
+- starting to work on db mapper interfaces
+
+
+### Added
+- added exists interface to db mapper, will finalize the repo on next release

data/README.md

@@ -23,7 +23,84 @@ Or install it yourself as:
 
     $ gem install appfuel
 
-## Usage
+## Overview
+Appfuel exists to solve two problems, aligning application boundaries & code scalability.
+
+### Application Boundaries
+We align our application boundaries by isolating our business logic into its own gem and exposing a set of interfaces to interact with that logic. Your ruby app (web, console, daemon) would represent its own boundary that simply interacted with your business gem. It would do this by declaring the business gem as dependency it needs to use and treating it like any other gem. As a result, we establish a standard set of inputs that always deliver a predictable output.
+
+### Code Scalability
+We address the issue of how well code scales by using object oriented design principles, mainly, `single point of responsibility`. This however, creates an illusion, instead of having a small number of very large files, we produce a large number of smaller files. While we have more files, they are simpler to read and mentally reason their intent.
+
+We also tackle complexity using `dependency inversion` where we build all of our dependencies into an application container and rely on the fact that every dependency can be found using a key that will resolve to that particular dependency.
+
+We will cover the basic here, more detailed docs can be found on our [gitbook](https://rsb.gitbooks.io/appfuel/).
+
+## Architecture
+![Basic Flow](docs/images/appfuel_basic_flow.png)
+
+## Directory Structure, Ruby Namespaces & the Application Container
+This is not required but we assume your are moving your business code behind a `rubygem` and as such you should be following [rubygems guidelines](http://guides.rubygems.org/patterns/). From the gem's `lib` we usually declare the root module as the gem module. For example for a gem named `FooBar` we have a lib director that looks like:
+```
+$ ls
+foo_bar/ foo_bar.rb
+```
+
+We loosely follow the guideline that directories match namespaces, however to try and prevent overly long namespaces where we can, we sometimes break with this guideline.
+
+All Appfuel dependencies are registered into a dependency injection (Inversion of Control IoC) container. There are two general types of dependencies:
+
+1. Classes
+    - `Actions`, `Commands`, `Repositories` & `Domains`
+    - Auto register with container using its ruby namespace with a few rules.
+    - Container Key Rules:
+        - the root namespace is never in the key, it is the name of the container
+        - the module directly under the root is either `global` or `the name of a feature module`
+            - ex) `FooBar::Global::Search` => `global.actions.search`
+            - ex) `FooBar::Users::Search` => `features.users.actions.search`
+
+2. Blocks defined from a DSL
+    - `initializers`, `validators`, `domain builders` & `presenters`
+    - register with container via DSL.
+    - DSL handles registration key
+
+## Setting Up Appfuel
+In order to use Appfuel we mixin `Appfuel::Application::Root` into our `application root class` and configure it as follows:
+
+```ruby
+module FooBar
+  extend Appfuel::Application::Root
+
+  setup_appfuel root: self,
+                root_path: File.dirname(__FILE__),
+                config_definition: Configuration.definition,
+                on_after_setup: ->(_container) {
+                  require_relative 'foo_bar/initializers'
+                }
+
+end
+```
+
+1. Mixin the application root to allow us to use `setup_appfuel` and `call`
+    - `call` with run any action with a route of format `feature/action`
+2. `setup_appfuel` allows `appfuel` configure & initialize your system
+    - `root`: is the root module, its name with be the name of the `app_container`
+    - `root_path`: allows appfuel to auto load features
+    - `config_definition`: is a Dsl that setups configuration data
+    - `on_after_setup`: is a hook that will call your lambda once setup is done
+
+After `setup_appfuel` is called the application container named `foo_bar` is initialized and ready. To retrieve the container from `appfuel`:
+
+```ruby
+Appfuel.app_container('foo_bar')
+```
+
+Since there are no other app container this is also the default container so you can simply call:
+```ruby
+Appfuel.app_container
+```
+This is will return the same container as above.
+
 
 
 ## Development

data/appfuel.gemspec

@@ -29,6 +29,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "dry-validation",   "~> 0.10.5"
   spec.add_dependency "dry-monads",       "~> 0.2"
   spec.add_dependency "dry-configurable", "~> 0.6"
+  spec.add_dependency "parslet",          "~> 1.8.0"
 
   spec.add_development_dependency "bundler",            "~> 1.13"
   spec.add_development_dependency "rake",               "~> 10.0"

data/lib/appfuel/application/app_container.rb

@@ -40,6 +40,7 @@ module Appfuel
         def container_path?
           !@container_path.nil?
         end
+
         # @param list [Array] list of container namespace parts including root
         # @return [Array]
         def container_path=(list)
@@ -113,6 +114,28 @@ module Appfuel
           @container_path.last
         end
 
+        # Allow the concrete class that is using this mixing to change the
+        # key which would otherwise be the lowercase, underscored class name
+        #
+        # @return nil
+        def container_class_key(value = nil)
+          return @container_class_key if value.nil?
+          p "[container-class-key] #{self} => #{value}"
+          @container_class_key = value
+        end
+
+        def container_class_id
+          container_class_key || container_key_basename
+        end
+
+        def container_class_type
+          nil
+        end
+
+        def container_class_path
+          "#{top_container_key}.#{container_class_type}.#{container_class_id}"
+        end
+
         # Fully qualified key, meaning you can access the class this was mixed into
         # if you stored it into the container using this key
         #
@@ -135,6 +158,7 @@ module Appfuel
           @container_global_name ||= 'global'
         end
 
+        #
         # Convert the injection key to a fully qualified namespaced key that
         # is used to pull an item out of the app container.
         #
@@ -177,7 +201,6 @@ module Appfuel
         #     convert_to_qualified_container_key('global.baz', 'container')
         #
         #     returns 'baz'
-        #
         # @param key [String] partial key to be built into fully qualified key
         # @param type_ns [String] namespace for key
         # @return [String] fully qualified namespaced key

data/lib/appfuel/application/container_class_registration.rb

@@ -7,16 +7,41 @@ module Appfuel
       # container key, so we simply need to obtain the qualified namespace
       # key for this class extending this, that does not belong to appfuel.
       #
+      # types of classes:
+      #   repositories
+      #   db
+      #   domains
+      #
+      #   features.repositories.key
       # @param klass [Class] the handler class that is inheriting this
       # @return [Boolean]
-      def register_container_class(klass)
+      def stage_class_for_registration(klass)
+        if !klass.respond_to?(:register_class?) || !klass.register_class?
+          return false
+        end
+
+        unless klass.respond_to?(:container_root_name)
+          fail "#{klass} must implement :container_root_name"
+        end
         root = klass.container_root_name
         return false if root == 'appfuel'
 
-        container = Appfuel.app_container(root)
-        container.register(klass.container_qualified_key, klass)
-        true
+        container = Appfuel.app_container(klass.container_root_name)
+        container[:auto_register_classes] << klass
       end
+
+      def disable_class_registration
+        @is_class_registration = false
+      end
+
+      def enable_class_registration
+        @is_class_registration = true
+      end
+
+      def register_class?
+        @is_class_registration ||= true
+      end
+
     end
   end
 end

data/lib/appfuel/application/root.rb

@@ -109,6 +109,7 @@ module Appfuel
         container.register(:root, root)
         container.register(:root_name, root_name)
         container.register(:root_path, root_path)
+        container.register(:auto_register_classes, [])
         container.register(:repository_mappings, {})
         container.register(:repository_initializer, repo_initializer)
         container.register(:features_path, "#{root_name}/features")

data/lib/appfuel/application.rb

@@ -1,4 +1,3 @@
 require_relative 'application/root'
 require_relative 'application/app_container'
-require_relative 'application/container_key'
 require_relative 'application/container_class_registration'

data/lib/appfuel/domain/base_criteria.rb

@@ -0,0 +1,171 @@
+module Appfuel
+  module Domain
+
+    # The Criteria represents the interface between the repositories and actions
+    # or commands. The allow you to find entities in the application storage (
+    # a database) without knowledge of that storage system. The criteria will
+    # always refer to its queries in the domain language for which the repo is
+    # responsible for mapping that query to its persistence layer.
+    #
+    # global.user
+    # memberships.user
+    #
+    # exist: 'foo.bar exists id = 6'
+    # search: 'foo.bar filter id = 6 and bar = "foo" order id asc limit 6'
+    #
+    # search:
+    #   domain: 'foo.bar',
+    #
+    #   filters: 'id = 6 or id = 8 and id = 9'
+    #   filters: [
+    #     'id = 6',
+    #     {or: 'id = 8'}
+    #     {and: id = 9'}
+    #   ]
+    #
+    #   order: 'foo.bar.id asc'
+    #   order: 'foo.bar.id'
+    #   order: [
+    #     'foo.bar.id',
+    #     {desc: 'foo.bar.id'},
+    #     {asc: 'foo.bar.id'}
+    #   ]
+    #   limit: 1
+    #
+    #   settings:
+    #     page: 1
+    #     per_page: 2
+    #     disable_pagination
+    #     first
+    #     all
+    #     last
+    #     error_on_empty
+    #     parser
+    #     transform
+    #
+    # exists:
+    #   domain:
+    #   expr:
+    #
+    #
+    class BaseCriteria
+      include DomainNameParser
+
+
+      attr_reader :domain_basename, :domain_name, :feature, :settings, :filters
+
+      # Parse out the domain into feature, domain, determine the name of the
+      # repo this criteria is for and initailize basic settings.
+      # global.user
+      #
+      # membership.user
+      # foo.id filter name like "foo" order foo.bar.id asc limit 2
+      # foo.id exists foo.id = 5
+      #
+      # @example
+      #   SpCore::Domain::Criteria('foo', single: true)
+      #   Types.Criteria('foo.bar', single: true)
+      #
+      # === Options
+      #   error_on_empty:   will cause the repo to fail when query returns an
+      #                     an empty dataset. The failure will have the message
+      #                     with key as domain and text is "<domain> not found"
+      #
+      #   single:           will cause the repo to return only one, the first,
+      #                     entity in the dataset
+      #
+      # @param domain [String] fully qualified domain name
+      # @param opts   [Hash] options for initializing criteria
+      # @return [Criteria]
+      def initialize(domain_name, data = {})
+        @feature, @domain_basename, @domain_name = parse_domain_name(domain_name)
+        @settings = data[:settings] || CriteriaSettings.new(data)
+        @filters  = nil
+        @params   = {}
+      end
+
+      def clear_filters
+        @filters = nil
+      end
+
+      def filters?
+        !filters.nil?
+      end
+
+      def global?
+        !feature?
+      end
+
+      def feature?
+        @feature != 'global'
+      end
+
+      # @example
+      #   criteria.add_param('foo', 100)
+      #
+      # @param key [Symbol, String] The key name where we want to keep the value
+      # @param value [String, Integer] The value that belongs to the key param
+      # @return [String, Integer] The saved value
+      def add_param(key, value)
+        fail 'key should not be nil' if key.nil?
+
+        @params[key.to_sym] = value
+      end
+
+      # @param key [String, Symbol]
+      # @return [String, Integer, Boolean] the found value
+      def param(key)
+        @params[key.to_sym]
+      end
+
+      # @param key [String, Symbol]
+      # @return [Boolean]
+      def param?(key)
+        @params.key?(key.to_sym)
+      end
+
+      # @return [Boolean] if the @params variable has values
+      def params?
+        !@params.empty?
+      end
+
+      private
+      def parse_expr(str)
+        if !(settings.parser && settings.parser.respond_to?(:parse))
+          fail "expression parser must implement to :parse"
+        end
+
+        if !(settings.transform && settings.transform.respond_to?(:apply))
+          fail "expression transform must implement :apply"
+        end
+
+        begin
+          tree = settings.parser.parse(str)
+        rescue Parslet::ParseFailed => e
+          msg = "The expression (#{str}) failed to parse"
+          err = RuntimeError.new(msg)
+          err.set_backtrace(e.backtrace)
+          raise err
+        end
+
+        result = settings.transform.apply(tree)
+        result = result[:domain_expr] || result[:root]
+        unless result
+          fail "unable to parse (#{str}) correctly"
+        end
+        result
+      end
+
+      def qualify_expr(domain_expr)
+        return domain_expr if domain_expr.qualified?
+        if global?
+          domain_expr.qualify_global(domain_basename)
+          return domain_expr
+        end
+
+        domain_expr.qualify_feature(feature, domain_basename)
+        domain_expr
+      end
+    end
+  end
+end

data/lib/appfuel/domain/criteria_builder.rb

@@ -0,0 +1,248 @@
+module SpCore
+  module Domain
+
+    # CriteriaBuilder is an interface creating new Criteria as well as
+    # building up an existing Criteria instance
+    class CriteriaBuilder
+
+      # For the list of defined inputs and maps, it builds new Criteria object
+      # following build pattern
+      #
+      # @example
+      #
+      #   inputs = {
+      #     search: "projects.offer",
+      #     repo_map: { "projects.offer" => "foo" },
+      #     filters: [
+      #       {foo: 'bar', ep: 1}
+      #     ],
+      #     order: [
+      #       {created_at: :desc}
+      #     ],
+      #     limit: 5,
+      #     all: true,
+      #     page: 1,
+      #     per_page: 10
+      #   }
+      #
+      #   maps = {
+      #     feature: "projects",
+      #     attr_map: {
+      #       foo: "users.user.foo"
+      #     }
+      #   }
+      #
+      #   criteria_builder = SpCore::Domain::CriteriaBuilder.build(inputs, maps)
+      #
+      # @param inputs [Hash] input data
+      # @param maps [Hash] mapping data
+      # @return [Criteria]
+      def self.build(inputs, maps = {})
+        builder = new(inputs, maps)
+        criteria = builder.create
+        builder.build(criteria, inputs)
+        criteria
+      end
+
+      # Builds new Criteria object
+      #
+      # @param inputs [Hash] input data
+      # @option inputs [String] :search entity/domain to search for
+      # @option inputs [Hash] :repo_map repository mapping by entity/domain
+      # @option inputs [Array] :filters list of filter items
+      # @option inputs [Array] :order list of order definitions
+      # @option inputs [Integer] :limit number of records to limit to
+      # @option inputs [Boolean] :all flag for returning all records
+      # @option inputs [Boolean] :first flag for returning only first record
+      # @option inputs [Boolean] :last flag for returning only last record
+      # @option inputs [Integer] :page number of the page in collection
+      # @option inputs [Integer] :per_page num. of items per page in collection
+      # @option inputs [Boolean] :single_page flag for getting single page only
+      # @param maps [Hash] mapping data
+      # @option maps [Hash] :attr_map mapping by attr to domain.attribute_name
+      # @return [Criteria]
+      def initialize(inputs, maps)
+        domain_name   =  inputs.fetch(:search).to_s
+        repo_map =       inputs[:repo_map] || {}
+        fail ":repo_map must be a Hash" unless repo_map.is_a?(Hash)
+
+        @attr_map =      maps[:attr_map] || {}
+        @domain_name   =      "#{domain_name}"
+        @repo_name = repo(repo_map, domain_name)
+      end
+
+      # Creates new Criteria instance.
+      # Actually it's just a delegator to Criteria initializer
+      #
+      # @param domain [String] fully qualified domain name
+      # @param options [Hash] options for initializing Criteria
+      # @return [Criteria]
+      def create
+        Criteria.new(domain_name, repo: repo_name)
+      end
+
+      # Build criteria clauses
+      #
+      # @param inputs [Hash]
+      def build(criteria, inputs)
+        self.filters(criteria, inputs, attr_map)
+            .order(criteria, inputs, attr_map)
+            .limit(criteria, inputs)
+            .scope(criteria, inputs)
+            .pagination(criteria, inputs)
+      end
+
+      # Updates Criteria object filters with the list of given filters
+      # Each filter item must be a Hash.
+      #
+      # @example
+      #   inputs = {
+      #     filters: [
+      #       {first_name: 'Bob'},
+      #       {last_name: 'Doe', op: 'like'},
+      #       {last_name: 'Johnson', op: 'like', or: false}
+      #     ]
+      #   }
+      #
+      # @param criteria [Criteria] criteria object to build
+      # @param inputs [Hash] input data
+      # @option inputs [Array] :filters list of filter items
+      # @param attr_map [Hash] mapping by attr to domain.attribute_name
+      # @return [CriteriaBuilder]
+      def filters(criteria, inputs, attr_map = {})
+        if inputs.key?(:filters)
+          filters = inputs.fetch(:filters)
+          fail ":filters must be an Array" unless filters.is_a?(Array)
+
+          filters.each do |filter_item|
+            attr_name, value = filter_item.first
+            qualified_name = lookup_attribute(attr_name, attr_map)
+            if qualified_name != attr_name
+              filter_item.delete(attr_name)
+              filter_item[qualified_name] = value
+            end
+          end
+
+          criteria.filter(filters)
+        end
+        self
+      end
+
+      # Updates given Criteria ordering clause.
+      # It expects a list of order definitions.
+      # Order definition might be either Hash, String or Symbol.
+      # If item is String or Symbol, ordering direction is ascending(:asc)
+      #
+      # @example
+      #   inputs = {
+      #     order: [
+      #       {created_at: :desc},
+      #       'created_at',
+      #       :created_at
+      #     ]
+      #   }
+      #
+      # @param criteria [Criteria] criteria object to build
+      # @param inputs [Hash] input data
+      # @option inputs [Array] :order list of order definitions
+      # @param attr_map [Hash] mapping by attr to domain.attribute_name
+      # @return [CriteriaBuilder]
+      def order(criteria, inputs, attr_map = {})
+        return self unless inputs.key?(:order)
+        list = inputs.fetch(:order)
+
+        fail ":order must implement :each" unless list.respond_to?(:each)
+        return self if list.empty?
+
+        final_order = {}
+        list.each do |order|
+          domain_attr_name = order
+          order_dir = "asc"
+
+          if order.is_a?(Hash)
+            domain_attr_name, order_dir = order.first
+          end
+
+          qualified_name = lookup_attribute(domain_attr_name, attr_map)
+          final_order[qualified_name.to_s] = order_dir.to_s
+          criteria.order_by(final_order)
+        end
+        self
+      end
+
+      # Updates given Criteria record limit
+      #
+      # @param criteria [Criteria] criteria to build
+      # @param inputs [Hash] input data
+      # @option inputs [Integer] :limit number of records to limit to
+      # @return [CriteriaBuilder]
+      def limit(criteria, inputs)
+        if inputs.key?(:limit)
+          criteria.limit(inputs.fetch(:limit))
+        end
+        self
+      end
+
+      # Updates given Criteria collection limits.
+      # Those are :disable_pagination, :all, :first and :last properties.
+      #
+      # @param criteria [Criteria] criteria to build
+      # @param inputs [Hash] input data
+      # @option inputs [Boolean] :all flag for returning all records
+      # @option inputs [Boolean] :first flag for returning onnly first record
+      # @option inputs [Boolean] :last flag for returning only last record
+      # @return [CriteriaBuilder]
+      def scope(criteria, inputs)
+        if inputs[:first] == true
+          criteria.first
+        elsif inputs[:last] == true
+          criteria.last
+        elsif inputs[:disable_pagination] == true
+          criteria.disable_pagination
+        elsif inputs[:all] == true
+          criteria.all
+        end
+        self
+      end
+
+      # Updates given Criteria pagination params.
+      #
+      # @param criteria [Criteria] criteria to build
+      # @param inputs [Hash] input data
+      # @option inputs [Integer] :page number of the page within collection
+      # @option inputs [Integer] :per_page number of items per page
+      # @option inputs [Boolean] :single_page flag for getting single page only
+      # @param attr_map [Hash] mapping by attr to domain.attribute_name
+      # @return [CriteriaBuilder]
+      def pagination(criteria, inputs)
+        criteria.disable_pagination           if inputs[:single_page]==true || inputs[:disable_pagination] == true
+        criteria.page(inputs[:page])          if inputs[:page]
+        criteria.per_page(inputs[:per_page])  if inputs[:per_page]
+        self
+      end
+
+    private
+
+      attr_reader :attr_map, :domain_name, :repo_name
+
+      def repo(repo_map, domain_name)
+        repo_map.key?(domain_name) ? repo_map[domain_name].to_s : domain_name
+      end
+
+      # It looks for given attribute name in the mapping and returns
+      # domain.attribute_name string if found. Else it returns attribute
+      # name itself.
+      #
+      # @private
+      #
+      # @param name [String] attribute name
+      # @param map [Hash] attribute to domain.attribute_name mapping
+      # @return [String]
+      def lookup_attribute(name, map)
+        return name unless map.is_a?(Hash)
+        return name unless map.key?(name) || map.key?(name.to_sym)
+        map[name] || map[name.to_sym]
+      end
+    end
+  end
+end