appfuel 0.2.5 → 0.2.6

data/lib/appfuel/storage/repository/base.rb

@@ -0,0 +1,246 @@
+module Appfuel
+  module Repository
+    # The generic repository behavior. This represents repo behavior that is
+    # agnostic to any storage system. The following is a definition of this
+    # patter by Martin Fowler:
+    #
+    #   "The repository mediates between the domain and data mapping
+    #    layers using a collection-like interface for accessing domain
+    #    objects."
+    #
+    #    "Conceptually, a Repository encapsulates the set of objects persisted
+    #     in a data store and the operations performed over them, providing a
+    #     more object-oriented view of the persistence layer."
+    #
+    #    https://martinfowler.com/eaaCatalog/repository.html
+    #
+    # While we are not a full repository pattern, we are evolving into it.
+    # All repositories have access to the application container. They register
+    # themselves into the container, as well as handling the cache from the
+    # container.
+    class Base
+      include Appfuel::Application::AppContainer
+
+      class << self
+        attr_writer :mapper
+
+        # Used when the concrete class is being registered, to construct
+        # the container key as a path.
+        #
+        # @example features.membership.repositories.user
+        # @example global.repositories.user
+        # @example <feature|global>.<container_class_type>.<class|container_key>
+        #
+        # @return [String]
+        def container_class_type
+          'repositories'
+        end
+
+        # Stage the concrete class that is inheriting this for registration.
+        # The reason we have to stage the registration is to give the code
+        # enough time to mixin the AppContainer functionality needed for
+        # registration. Therefore registration is defered until feature
+        # initialization.
+        #
+        # @param klass [Class] the class inheriting this
+        # @return nil
+        def inherited(klass)
+          stage_class_for_registration(klass)
+          nil
+        end
+
+        # Mapper holds specific knowledge of storage to domain mappings
+        #
+        # @return [Mapper]
+        def mapper
+          @mapper ||= create_mapper
+        end
+
+        # Factory method to create a mapper. Each concrete Repository will
+        # override this.
+        #
+        # @param maps [Hash] the domain to storage mappings
+        # @return [Mapper]
+        def create_mapper(maps = nil)
+          Mapper.new(container_root_name, maps)
+        end
+
+        # A cache of already resolved domain objects
+        #
+        # @return [Hash]
+        def cache
+          app_container[:repository_cache]
+        end
+      end
+
+
+      # @return [Mapper]
+      def mapper
+        self.class.mapper
+      end
+
+      # Validate the method exists and call it with the criteria and
+      # settings objects
+      #
+      # @params query_method [String] method to call
+      # @params criteria [SearchCriteria]
+      # @params settings [Settings]
+      # @return DomainCollection
+      def execute_query_method(query_method, criteria, settings)
+        unless respond_to?(query_method)
+          fail "Could not execute query method (#{query_method})"
+        end
+
+        public_send(query_method, criteria, settings)
+      end
+
+      # The first method called in the query life cycle. It setups up the
+      # query method used to return a query relation for the next method
+      # in the life cycle. This query method will return a query relation
+      # produced by the concrete repo for that domain. The relation is specific
+      # to the type of repo, a db repo will return an ActiveRecordRelation for
+      # example.
+      #
+      # @param criteria [SearchCriteria]
+      # @param settings [Settings]
+      # @return [Object] A query relation
+      def query_setup(criteria, settings)
+        query_method = "#{criteria.domain_basename}_query"
+        execute_query_method(query_method, criteria, settings)
+      end
+
+      def query(criteria, settings = {})
+        settings = create_settings(settings)
+        criteria = build_criteria(criteria, settings)
+
+        if settings.manual_query?
+          query_method = settings.manual_query
+          return execute_query_method(query_method, criteria, settings)
+        end
+
+        begin
+          result = query_setup(criteria, settings)
+          result = handle_query_conditions(criteria, result, settings)
+          build_domains(criteria, result, settings)
+        rescue => e
+          msg = "query failed for #{criteria.domain_name}: " +
+                "#{e.class} #{e.message}"
+          error = RuntimeError.new(msg)
+          error.set_backtrace(e.backtrace)
+          raise error
+        end
+      end
+
+      # Query conditions can only be applied by a specific type of repo, like
+      # a database or elastic search repo. Because of this we will fail if
+      # this is not implemented
+      #
+      # @param result [Object] some type of query relation
+      # @param criteria [SearchCriteria]
+      # @param settings [Settings]
+      # @return A query relation
+      def apply_query_conditions(_result, _criteria, _settings)
+        method_not_implemented_error
+      end
+
+      # Domain resolution can only be applied by specific repos. Because of
+      # this we fail if is not implmented
+      #
+      # @param result [Object] some type of query relation
+      # @param criteria [SearchCriteria]
+      # @param settings [Settings]
+      # @return A query relation
+      def build_domains(_result, _criteria, _settings)
+        method_not_implemented_error
+      end
+
+      # Factory method to create repo settings. This holds things like
+      # pagination details, parser classes etc..
+      #
+      # @params settings [Hash,Settings]
+      # @return Settings
+      def create_settings(settings = {})
+        return settings if settings.instance_of?(Settings)
+        Settings.new(settings)
+      end
+
+      def build_criteria(criteria, settings = nil)
+        settings ||= create_settings
+
+        return criteria if criteria?(criteria)
+
+        if criteria.is_a?(String)
+          tree = settings.parser.parse(criteria)
+          result = settings.transform.apply(tree)
+          return result[:search]
+        end
+
+        unless criteria.is_a?(Hash)
+          fail "criteria must be a String, Hash, or " +
+               "Appfuel::Domain::SearchCriteria"
+        end
+        Criteria.build(criteria)
+      end
+
+      def criteria?(value)
+        value.instance_of?(Criteria)
+      end
+
+      def exists?(criteria)
+        expr = criteria.fiilters
+        mapper.exists?(expr)
+      end
+
+      def to_storage(entity, exclude = [])
+        mapper.to_storage(entity, exclude)
+      end
+
+      def to_entity(domain_name, storage)
+        key  = qualify_container_key(domain_name, "domains")
+        hash = mapper.to_entity_hash(domain_name, storage)
+        app_container[key].new(hash)
+      end
+
+      def build(type:, name:, storage:, **inputs)
+        builder = find_entity_builder(type: type, domain_name: name)
+        builder.call(storage, inputs)
+      end
+
+      # features.membership.presenters.hash.user
+      # global.presenters.user
+      #
+      # key => db_model
+      # key => db_model
+      def find_entity_builder(domain_name:, type:)
+        key = qualify_container_key(domain_name, "domain_builders.#{type}")
+
+        container = app_container
+        unless container.key?(key)
+          return ->(data, inputs = {}) {
+            build_default_entity(domain_name: domain_name, storage: data)
+          }
+        end
+
+        container[key]
+      end
+
+      def build_default_entity(domain_name:, storage:)
+        storage = [storage] unless storage.is_a?(Array)
+
+        storage_attrs = {}
+        storage.each do |model|
+          storage_attrs.merge!(mapper.model_attributes(model))
+        end
+
+        hash = mapper.to_entity_hash(domain_name, storage_attrs)
+        key  = qualify_container_key(domain_name, "domains")
+        app_container[key].new(hash)
+      end
+
+      private
+      def method_not_implemented_error
+        fail "must be implemented by a storage specific repository"
+      end
+    end
+  end
+end

data/lib/appfuel/storage/repository/criteria.rb

@@ -0,0 +1,317 @@
+module Appfuel
+  module Repository
+
+    # 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', 'eq', '6', 'or']
+    #   ]
+    #   filters: [
+    #     {attr: 'id', op: 'eq', value: 999, or: true},
+    #   ]
+    #
+    #   order: 'foo.bar.id asc'
+    #   order: 'foo.bar.id'
+    #   order: [
+    #     'foo.bar.id',
+    #     {desc: 'foo.bar.id'},
+    #     {asc: 'foo.bar.id'}
+    #   ]
+    #   limit: 1
+    #
+    class Criteria
+      include Appfuel::Domain::DomainNameParser
+      attr_reader :domain_basename, :domain_name, :feature, :filters, :order_by
+
+
+      #
+      # 1) Inputs form the SearchTransform.apply
+      #    search:
+      #       domain:   [String],
+      #       filters:  [Expr|ExprConjunction]
+      #       orders:   [OrderExpr|Array[OrderExpr]]
+      #       limit:    [Integer]
+      #
+      # 2) Inputs manually built from a developer
+      #   search:
+      #     domain:   [String],
+      #     filters:  [String|Array[String|Hash]]
+      #     orders:   [String|Array[String|Hash]]
+      #     limit:    [Integer]
+      #
+      #
+      # 3) Inputs as a full search string
+      #   search: [String]
+      #
+      # domain: String,
+      # filters: String | Expr | ExprConjunction
+      # order: String | Array[OrderExpr|String|Hash]
+      # limit: Integer
+      #
+      #
+      def self.build(inputs)
+        unless inputs.key?(:domain)
+          fail "search criteria :domain is required"
+        end
+        criteria = self.new(inputs[:domain])
+        criteria.filter(inputs[:filters])
+
+        if inputs.key?(:order)
+          criteria.order(inputs[:order])
+        end
+
+        if inputs.key?(:limit)
+          criteria.limit(inputs[:limit])
+        end
+        criteria
+      end
+
+      # 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)
+        @filters   = nil
+        @params    = {}
+        @parser    = data[:expr_parser]    || ExprParser.new
+        @transform = data[:expr_transform] || ExprTransform.new
+        @limit     = nil
+        @order_by  = []
+        filter(data[:filters]) if data[:filters]
+      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
+
+      # [
+      #   'id = 6',
+      #   {'name like "foo"' => 'or'},
+      # ]
+      #
+      #
+      def filter_array(input)
+        unless input.respond_to?(:each)
+          fail "input must implement :each, expecting a list"
+        end
+
+        input.each do |item|
+          filter(item)
+        end
+      end
+
+      def filter_string(expr, op: 'and')
+        expr = parse_expr(expr)
+        fail "Could not parse (#{expr}) unkown failure" unless expr
+        filter_expr(expr, op: op)
+        self
+      end
+
+      #
+      # filters: {
+      #  'id = 6' => :and,
+      #  'id = 8' => :and,
+      # }
+      def filter_hash(input)
+        unless input.respond_to?(:each)
+          fail "input must implement :each, expecting a hash"
+        end
+
+        input.each do |expr, op|
+          filter_string(expr, op: op)
+        end
+
+        self
+      end
+
+      def filter_expr(expr, op: 'and')
+        expr = qualify_expr(expr)
+        if filters?
+          expr = expr_conjunction_class.new(op, filters, expr)
+        end
+        @filters = expr
+        self
+      end
+
+      def filter(item, op: 'and')
+        case
+        when item.is_a?(Array)  then filter_array(item)
+        when item.is_a?(Hash)   then filter_hash(item)
+        when item.is_a?(String) then filter_string(item, op: op)
+        when item.instance_of?(expr_class),
+             item.instance_of?(expr_conjunction_class)
+          filter_expr(item, op: op)
+        else
+          fail "filter could not understand input (#{input})"
+        end
+        self
+      end
+
+      def limit?
+        !@limit.nil?
+      end
+
+      def limit(nbr = nil)
+        return @limit if nbr.nil?
+
+        @limit = Integer(nbr)
+        fail "limit must be an integer greater than 0" unless nbr > 0
+        self
+      end
+
+      def order?
+        !@order_by.empty?
+      end
+
+      # order first_name asc, last_name
+      #   order: 'foo.bar.id asc'
+      #   order: 'foo.bar.id'
+      #   order: [
+      #     'foo.bar.id',
+      #     'foo.bar.id asc',
+      #     {'foo.bar.id => 'desc'},
+      #     {'foo.bar.code => 'asc'},
+      #   ]
+      #
+      # membership.user.id
+      def order(data)
+       order_exprs(OrderExpr.build(data))
+      end
+
+      def order_expr(expr)
+        @order_by << qualify_expr(expr)
+        self
+      end
+
+      def order_exprs(list)
+        list.each do |expr|
+          order_expr(expr)
+        end
+        self
+      end
+
+      private
+      attr_reader :parser, :transform
+
+      def expr_class
+        Expr
+      end
+
+      def expr_conjunction_class
+        ExprConjunction
+      end
+
+      def parse_expr(str)
+        if !(parser && parser.respond_to?(:parse))
+          fail "expression parser must implement :parse"
+        end
+
+        if !(transform && transform.respond_to?(:apply))
+          fail "expression transform must implement :apply"
+        end
+
+        begin
+          tree = 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 = 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 → storage/repository}/expr.rb

@@ -1,5 +1,5 @@
 module Appfuel
-  module Domain
+  module Repository
     # Domain expressions are used mostly by the criteria to describe filter
     # conditions. The class represents a basic expression like "id = 6", the
     # problem with this expression is that "id" is relative to the domain

data/lib/appfuel/storage/repository/expr_conjunction.rb

@@ -0,0 +1,41 @@
+module Appfuel
+  module Repository
+    class ExprConjunction
+      OPERATORS = ['and', 'or'].freeze
+      attr_reader :op, :left, :right
+
+      def initialize(type, left, right)
+        @op    = validate_operator(type)
+        @left  = left
+        @right = right
+      end
+
+      def conjunction?
+        true
+      end
+
+      def qualified?
+        left.qualified? && right.qualified?
+      end
+
+      def qualify_feature(feature, domain)
+        left.qualify_feature(feature, domain) unless left.qualified?
+        right.qualify_feature(feature, domain) unless right.qualified?
+      end
+
+      def qualify_global(domain)
+        left.qualify_global(domain) unless left.qualified?
+        right.qualify_global(domain) unless right.qualified?
+      end
+
+      private
+      def validate_operator(type)
+        type = type.to_s.downcase
+        unless OPERATORS.include?(type)
+          fail "Conjunction operator can only be (and|or)"
+        end
+        type
+      end
+    end
+  end
+end

data/lib/appfuel/{domain → storage/repository}/expr_parser.rb

@@ -1,16 +1,11 @@
-require 'parslet'
-require 'parslet/convenience'
-require_relative 'expr_transform'
-
 module Appfuel
-  module Domain
+  module Repository
     # A PEG (Parser Expression Grammer) parser for our domain language. This
     # gives us the ablity to describe the filtering we would like to do when
     # searching on a given domain entity. The search string is parsed and
     # transformed into an interface that repositories can use to determine how
     # to search a given storage interface. The language always represent the
     # business domain entities and not a storage system.
-    #
     class ExprParser < Parslet::Parser
       rule(:space) { match('\s').repeat(1) }
       rule(:space?) { space.maybe }
@@ -21,10 +16,6 @@ module Appfuel
       rule(:lparen) { str('(') >> space? }
       rule(:rparen) { str(')') >> space? }
 
-      rule(:filter_identifier) { stri('filter') }
-      rule(:order_identifier)  { stri('order') }
-      rule(:limit_identifier)  { stri('limit') }
-
       rule(:integer) do
         (str('-').maybe >> digit >> digit.repeat).as(:integer)
       end
@@ -83,15 +74,13 @@ module Appfuel
         (attr_label >> (str('.') >> attr_label).repeat).maybe.as(:domain_attr)
       end
 
-
-
       rule(:and_op)     { stri('and')  >> space? }
       rule(:or_op)      { stri('or')   >> space? }
-      rule(:in_op)      { stri('in')   >> space? }
-      rule(:like_op)    { stri('like') >> space? }
-      rule(:between_op) { stri('between') >> space? }
+      rule(:in_op)      { (stri('in') | stri('not in'))   >> space? }
+      rule(:like_op)    { (stri('like') | stri('not like'))  >> space? }
+      rule(:between_op) { (stri('between') | stri('not between')) >> space? }
 
-      rule(:eq_op)      { str('=')    >> space? }
+      rule(:eq_op)      { (str('=') | str('!=')) >> space? }
       rule(:gt_op)      { str('>')    >> space? }
       rule(:gteq_op)    { str('>=')   >> space? }
       rule(:lt_op)      { str('<')    >> space? }
@@ -170,22 +159,21 @@ module Appfuel
         lparen >> or_operation >> rparen | domain_expr >> space?
       end
 
+
       rule(:and_operation) do
         (
-          primary.as(:left) >> space? >>
-          and_op >>
-          and_operation.as(:right)
+          primary.as(:left) >> and_op >> and_operation.as(:right) >> space?
         ).as(:and) | primary
       end
 
       rule(:or_operation) do
         (
-          and_operation.as(:left) >> space? >>
-          or_op >>
-          or_operation.as(:right)
+          and_operation.as(:left) >> or_op >> or_operation.as(:right)
         ).as(:or) | and_operation
       end
 
+      # rule for domain
+      #
       root(:or_operation)
 
       def stri(str)