shamu 0.0.1 → 0.0.2

data/lib/shamu/services/request.rb

@@ -0,0 +1,122 @@
+module Shamu
+  module Services
+
+    # Define the attributes and validations required to request a change by a
+    # {Service}. You can use the Request in place of an ActiveRecord model in
+    # rails forms_helpers.
+    #
+    # ```
+    # module Document
+    #   module Request
+    #     class Change < Shamu::Services::Request
+    #       attribute :title, presence: true
+    #       attribute :author_id, presence: true
+    #     end
+    #
+    #     class Create < Change
+    #     end
+    #
+    #     class Update < Change
+    #       attribute :id, presence: true
+    #     end
+    #   end
+    # end
+    # ```
+    class Request
+      include Shamu::Attributes
+      include Shamu::Attributes::Assignment
+      include Shamu::Attributes::FluidAssignment
+      include Shamu::Attributes::Validation
+
+      # Applies the attributes of the request to the given model. Only handles
+      # scalar attributes. For more complex associations, override in a custom
+      # {Request} class.
+      #
+      # @param [Object] model or object to apply the attributes to.
+      # @return [model]
+      def apply_to( model )
+        self.class.attributes.each do |name, _|
+          method = :"#{ name }="
+          model.send method, send( name ) if model.respond_to?( method ) && set?( name )
+        end
+
+        model
+      end
+
+      # Entities are always immutable - so they are considered persisted. Use a
+      # {Services::ChangeRequest} to back a form instead.
+      def persisted?
+        if respond_to?( :id )
+          !!id
+        else
+          fail NotImplementedError, "override persisted? in #{ self.class.name }"
+        end
+      end
+
+      class << self
+        # Coerces a hash or params object to a proper {Request} object.
+        # @param [Object] params to be coerced.
+        # @return [Request] the coerced request.
+        def coerce( params )
+          if params.is_a?( self )
+            params
+          elsif params.respond_to?( :to_h ) || params.respond_to?( :to_attributes )
+            new( params )
+          elsif params.nil?
+            new
+          else
+            raise ArgumentError
+          end
+        end
+
+        # Coerces the given params object and raises an ArgumentError if any of
+        # the parameters are invalid.
+        # @param (see .coerce)
+        # @return (see .coerce)
+        def coerce!( params )
+          coerced = coerce( params )
+          raise ArgumentError unless coerced.valid?
+          coerced
+        end
+
+        REQUEST_ACTION_PATTERN = /(Create|Update|New|Change|Delete)?(Request)?$/
+
+        # @return [ActiveModel::Name] used by url_helpers or form_helpers etc.
+        #   when generating model specific names for this request.
+        def model_name
+          @model_name ||= begin
+            base_name = name || ""
+            parts     = reduce_model_name_parts( base_name.split( "::" ) )
+            parts     = ["Request"] if parts.empty?
+            base_name = parts.join "::"
+
+            ::ActiveModel::Name.new( self, nil, base_name )
+          end
+        end
+
+        private
+
+          def reduce_model_name_parts( parts )
+            while last = parts.last
+              if last == "Request"
+                parts[-1] = parts[-2].singularize
+                break
+              end
+
+              last.sub! REQUEST_ACTION_PATTERN, ""
+              if last.empty?
+                parts.pop
+                next
+              end
+
+              last = last.singularize
+              parts[-1] = last
+              break
+            end
+
+            parts
+          end
+      end
+    end
+  end
+end

data/lib/shamu/services/request_support.rb

@@ -0,0 +1,124 @@
+module Shamu
+  module Services
+
+    # Include into services that support mutating resources to add basic
+    # {#with_request} and {Request} conventions.
+    module RequestSupport
+      extend ActiveSupport::Concern
+
+      # Used to interrogate the service for the {Request} class to use for a
+      # given method.
+      #
+      # Combine with {Request#init_from} to prepare a request for use in a rails
+      # form ready to modify an existing entity.
+      #
+      # @param [Symbol] method on the service that will be called.
+      # @return [Class] a class that inherits from Request.
+      def request_class( method )
+        self.class.request_class( method )
+      end
+
+      # Build a {Request} object, prepopulated with the current state of the
+      # resource to submit changes to the given `method`.
+      #
+      # @param [Symbol] method that will be called with the generated request.
+      # @param [Entities::Entity] entity optional entity that will modified.
+      # @return [Request]
+      def request_for( method, entity = nil )
+        request    = request_class( method ).new( entity )
+        request.id = entity.id if entity && request.attribute?( :id )
+
+        request
+      end
+
+      private
+
+        # @!visibility public
+        #
+        # Respond to a {Request} returning a {Result} touple of the subject
+        # {Entities::Entity} and {Request}.
+        #
+        # Before processing the `params` will be coerced and validated. If the
+        # request is invalid, the method will immediately return without
+        # yielding to the block.
+        #
+        # If the block yields an {Entities::Entity} it will be assigned as the
+        # {Result#entity} in the returned {Result} object.
+        #
+        # @param [Request,Hash] params of the request.
+        # @param [Class] request_class to coerce `params` to.
+        # @yield (request)
+        # @yieldparam [Request] request coerced and validated from `params`.
+        # @yieldreturn [Entities::Entity,#errors] the entity manipulated during
+        #   the request or an object that responds to #errors.
+        # @return [Result]
+        # @example
+        #   def process_order( params )
+        #     with_request params, ProcesOrderRequest do |request|
+        #       order = Models::Order.find( request.id )
+        #
+        #       # Custom validation
+        #       next error( :base, "can't do that" ) if order.state == 'processed'
+        #
+        #       request.apply_to( order )
+        #
+        #       # If DB only validations fail, return errors
+        #       next order unless order.save
+        #
+        #       # All good, return an entity for the order
+        #       scorpion.fetch OrderEntity, { order: order }, {}
+        #     end
+        #   end
+        def with_request( params, request_class, &block )
+          request = request_class.coerce( params )
+          sources = yield( request ) if request.valid?
+
+          result request, *sources
+        end
+
+      # Static methods added to {RequestSupport}
+      class_methods do
+
+        # (see #request_class)
+        def request_class( method )
+          result = request_class_by_name( method ) \
+                   || request_class_by_alias( method ) \
+                   || request_class_default
+
+          result ||= superclass.request_class( method ) if superclass.respond_to?( :request_class )
+
+          result || fail( IncompleteSetupError, "No Shamu::Services::Request classes defined for '#{ name }'." )
+        end
+
+        private
+
+          def request_class_namespace
+            @request_class_namespace ||= ( name || "" ).sub( /(Service)?$/, "Request" ).constantize
+          rescue NameError
+            self
+          end
+
+          def request_class_by_name( method )
+            camelized = method.to_s.camelize
+            request_class_namespace.const_get( camelized ) if request_class_namespace.const_defined?( camelized )
+          end
+
+          def request_class_by_alias( method )
+            candidate =
+              case method
+              when :new  then "Create"
+              when :edit then "Update"
+              end
+
+            if candidate && request_class_namespace.const_defined?( candidate )
+              request_class_namespace.const_get( candidate )
+            end
+          end
+
+          def request_class_default
+            request_class_namespace.const_get( "Change" ) if request_class_namespace.const_defined?( "Change" )
+          end
+      end
+    end
+  end
+end

data/lib/shamu/services/result.rb

@@ -0,0 +1,75 @@
+module Shamu
+  module Services
+
+    # The result of a {Service} {Request} capturing the validation errors
+    # recorded while processing the request and the resulting
+    # {Services::Entities::Entity} and {Request} used.
+    class Result
+      extend ActiveModel::Translation
+
+      # ============================================================================
+      # @!group Attributes
+      #
+
+      # @return [Request] the request submitted to the {Service}.
+      attr_reader :request
+
+      # @return [Entities::Entity] the entity created or changed by the request.
+      attr_reader :entity
+
+      #
+      # @!endgroup Attributes
+
+      # @param [Array<#errors>] validation_sources an array of objects that respond to `#errors`
+      #   returning a {ActiveModel::Errors} object.
+      # @param [Request] request submitted to the service. If :not_set, uses
+      #   the first {Request} object found in the `validation_sources`.
+      # @param [Entities::Entity] entity submitted to the service. If :not_set,
+      #   uses the first {Request} object found in the `validation_sources`.
+      def initialize( *validation_sources, request: :not_set, entity: :not_set )
+        validation_sources.each do |source|
+          request = source if request == :not_set && source.is_a?( Services::Request )
+          entity  = source if entity == :not_set && source.is_a?( Entities::Entity )
+
+          append_error_source source
+        end
+
+        unless request == :not_set
+          @request = request
+          append_error_source request
+        end
+
+        unless entity == :not_set
+          @entity = entity
+          append_error_source entity
+        end
+      end
+
+      # @return [Boolean] true if there were not recorded errors.
+      def valid?
+        errors.empty?
+      end
+
+      # @return [ActiveModel::Errors] errors gathered from all the validation sources.
+      #     Typically the {#request} and {#entity}.
+      def errors
+        @errors ||= ActiveModel::Errors.new( self )
+      end
+
+      # Delegate model_name to request/entity
+      def model_name
+        ( request && request.model_name ) || ( entity && entity.model_name ) || ActiveModel::Name.new( self, nil, "Request" ) # rubocop:disable Metrics/LineLength
+      end
+
+      private
+
+        def append_error_source( source )
+          return unless source.respond_to?( :errors )
+
+          source.errors.each do |attr, message|
+            errors.add attr, message unless errors[attr].include? message
+          end
+        end
+    end
+  end
+end

data/lib/shamu/services/service.rb

@@ -0,0 +1,355 @@
+require "scorpion"
+require "shamu/logger"
+
+module Shamu
+  module Services
+
+    # ...
+    #
+    # ## Well Known Methos
+    #
+    # - __list( list_scope )__ - lists all of the entities matching the
+    #   requested {Entities::ListScope list scope}. Often apply
+    #   {Entities::ListScope::Paging} or other filters.
+    #
+    #     ```
+    #     def list( list_scope )
+    #       list_scope = UserListScope.coerce! list_scope
+    #       entity_list Models::User.by_list_scope( list_scope ) do |record|
+    #         scorpion.fetch UserEntity, record: record
+    #       end
+    #     end
+    #     ```
+    #
+    # - __lookup( *ids )__ - matches a given list of ids to their entities or a
+    #   {Entities::NullEntity} for ids that can't be found. The `lookup` method
+    #   is typically used to resolve related resources between services -
+    #   similar to associations in an ActiveRecord model. Use
+    #   {#entity_lookup_list} to transform a list of records or external
+    #   resources to a lookup list of entities.
+    #
+    #     ```
+    #     def lookup( *ids )
+    #       entity_lookup_list Models::User.where( id: ids ), ids, NullEntity.for( UserEntity ) do |record|
+    #         scorpion.fetch UserEntity, record: record
+    #       end
+    #     end
+    #     ```
+    #
+    # - __find( id )__ - finds a single entity with the given id, raising
+    #   {Shamu::NotFoundError} if the resource cannot be found. If the service
+    #   also implements `lookup` then this can be implemented by simply aliasing
+    #   `find` to {#find_by_lookup}.
+    #
+    #     ```
+    #     def find( id )
+    #       find_by_lookup( id )
+    #     end
+    #     ```
+    #
+    # - __report( report_scope )__ - Compile a report including metrics, and
+    #   master/detail data that make take longer to gather than a standard
+    #   `list` request.
+    #
+    #     ```
+    #     def report( report_scope = nil )
+    #       report_scope = UserReportScope.coerce! report_scope
+    #       scorpion.fetch UserReport, report_scope, {}
+    #     end
+    #     ```
+    class Service
+
+      # Support dependency injection for related services.
+      include Scorpion::Object
+
+      # ============================================================================
+      # @!group Dependencies
+      #
+
+      # @!attribute
+      # @return [Shamu::Logger] the IO to dump logging info to.
+      attr_dependency :logger, Shamu::Logger
+
+      #
+      # @!endgroup Dependencies
+
+      initialize do
+      end
+
+      private
+
+        # @!visibility public
+        # Takes a raw enumerable list of records and transforms them to a proper
+        # {Entities::List}.
+        #
+        # As simple as the method is, it also serves as a hook for mixins to add
+        # additional behavior when processing lists.
+        #
+        # If a block is not provided, looks for a method `build_entity(record,
+        # records=nil)` where `record` is the individual record to be
+        # transformed and `records` is the original collection or database query
+        # being transformed.
+        #
+        # @param [Enumerable] records the raw list of records.
+        # @yield (record)
+        # @yieldparam [Object] record the raw value from the `list` to to
+        #     transform to an {Entities::Entity}.
+        # @yieldreturn [Entities::Entity]
+        # @return [Entities::List]
+        def entity_list( records, &transformer )
+          return Entities::List.new [] unless records
+          unless transformer
+            fail "Either provide a block or add a private method `def build_entity( record, records = nil )` to #{ self.class.name }." unless respond_to?( :build_entity, true ) # rubocop:disable Metrics/LineLength
+            transformer ||= ->( record ) { build_entity( record, records ) }
+          end
+
+          Entities::List.new LazyTransform.new( records, &transformer )
+        end
+
+        # @!visibility public
+        # Match a list of records with the ids used to look up those records.
+        # Uses a {Entities::NullEntity} if the id doesn't have a matching record.
+        #
+        # @param [Enumerable] records matching the requested `ids`.
+        # @param [Array<Integer>] ids of records found.
+        # @param [Class] null_class to use when an id doesn't have a matching
+        #     record.
+        # @param [Symbol,#call(record)] match the attribute or a Proc used to
+        #  extract the id used to compare records.
+        # @param [Symbol,#call] coerce a method that can be used to coerce id values
+        #     to the same type (eg :to_i). If not set, automatically uses :to_i
+        #     if match is an 'id' attribute.
+        # @yield (see #entity_list)
+        # @yieldparam (see #entity_list)
+        # @yieldreturn (see #entity_list)
+        # @return [Entities::List]
+        #
+        # @example
+        #   def lookup( *ids )
+        #     records = Models::Favorite.all.where( id: ids )
+        #     entity_lookup_list records, ids, NullEntity.for( FavoriteEntity ) do |record|
+        #       scorpion.fetch FavoriteEntity, { record: record }, {}
+        #     end
+        #   end
+        #
+        #   def lookup_by_name( *names )
+        #     records = Models::Favorite.all.where( :name.in( names ) )
+        #
+        #     entity_lookup_list records, names, NullEntity.for( FavoriteEntity ), match: :name do |record|
+        #       scorpion.fetch FavoriteEntity, { record: record }, {}
+        #     end
+        #   end
+        #
+        #   def lookup_by_lowercase( *names )
+        #     records = Models::Favorite.all.where( :name.in( names.map( &:downcase ) ) )
+        #     matcher = ->( record ) { record.name.downcase }
+        #
+        #     entity_lookup_list records, names, NullEntity.for( FavoriteEntity ), match: matcher do |record|
+        #       scorpion.fetch FavoriteEntity, { record: record }, {}
+        #     end
+        #   end
+        #
+        #
+        def entity_lookup_list( records, ids, null_class, match: :id, coerce: :not_set, &transformer )
+          matcher = entity_lookup_list_matcher( match )
+          coerce  = coerce_method( coerce, match )
+          ids = ids.map( &coerce ) if coerce
+
+          list = entity_list records, &transformer
+          matched = ids.map do |id|
+            list.find { |e| matcher.call( e ) == id } || scorpion.fetch( null_class, { id: id }, {} )
+          end
+
+          Entities::List.new( matched )
+        end
+
+          def entity_lookup_list_matcher( match )
+            if !match.is_a?( Symbol ) && match.respond_to?( :call )
+              match
+            elsif match == :id
+              ->( record ) { record && record.id }
+            else
+              ->( record ) { record && record.send( match ) }
+            end
+          end
+
+          def coerce_method( coerce, match )
+            return coerce unless coerce == :not_set
+            :to_i if match.is_a?( Symbol ) && match =~ /(^|_)id$/
+          end
+
+        # @!visibility public
+        #
+        # For services that expose a standard `lookup` method, find_by_lookup
+        # looks up a single entity and raises {Shamu::NotFoundError} if the
+        # entity is nil or a {Entities::NullEntity}.
+        #
+        # A `find` method can then be implemented in terms of the `lookup`
+        # method.
+        #
+        # @param [Integer] id of the entity.
+        # @return [Entities::Entity]
+        #
+        # @example
+        #
+        #   class Example < Services::Service
+        #     def lookup( *ids )
+        #       # do something to find the entity
+        #     end
+        #
+        #     def find( id )
+        #       find_by_lookup( id )
+        #     end
+        #   end
+        def find_by_lookup( id )
+          entity = lookup( id ).first
+          raise Shamu::NotFoundError unless entity.present?
+          entity
+        end
+
+        # @!visibility public
+        #
+        # Find an associated entity from a dependent service. Attempts to
+        # effeciently handle multiple requests to lookup associations by caching
+        # all the associated entities when {#lookup_association} is used
+        # repeatedly when building an entity.
+        #
+        # @param [Object] id of the associated {Entities::Entity} to find.
+        # @param [Service] service used to locate the associated resource.
+        # @return [Entity] the found entity or a {Entities::NullEntity} if the
+        #     association doesn't exist.
+        #
+        # @example
+        #
+        #   def build_entity( record, records = nil )
+        #     owner = lookup_association record.owner_id, users_service do
+        #               records.pluck( :owner_id ) if records
+        #             end
+        #
+        #     scorpion.fetch UserEntity, { record: record, owner: owner }, {}
+        #   end
+        def lookup_association( id, service, &block )
+          return unless id
+
+          cache = cache_for( entity: service )
+          cache.fetch( id ) || begin
+            if block_given? && ( ids = yield )
+              service.lookup( *ids ).map do |entity|
+                cache.add( entity.id, entity )
+              end
+
+              cache.fetch( id )
+            else
+              association = service.lookup( id ).first
+              cache.add( association.id, association )
+            end
+          end
+        end
+
+        # @!visibility public
+        #
+        # Perform a lazy {#lookup_association} and only load the entity if its
+        # actually dereferenced by the caller.
+        #
+        # @param (see #lookup_association)
+        # @return [LazyAssociation<Entity>]
+        def lazy_association( id, service, &block )
+          LazyAssociation.new( id ) do
+            lookup_association id, service, &block
+          end
+        end
+
+        # @!visibility public
+        #
+        # Get the {Entities::IdentityCache} for the given {Entities::Entity} class.
+        # @param [Class] entity the type of entity that will be cached. Only
+        #     required if the service manages multiple entities.
+        # @param [Symbol,#call] key the attribute on the entity, or a custom
+        #     block used to obtain the cache key from an entity.
+        # @param [Symbol,#call] coerce a method that can be used to coerce key values
+        #     to the same type (eg :to_i). If not set, automatically uses :to_i
+        #     if key is an 'id' attribute.
+        # @return [Entities::IdentityCache]
+        def cache_for( key: :id, entity: nil, coerce: :not_set )
+          coerce = coerce_method( coerce, key )
+
+          cache_key        = [ entity, key, coerce ]
+          @entity_caches ||= {}
+          @entity_caches[ cache_key ] ||= scorpion.fetch( Entities::IdentityCache, coerce )
+        end
+
+        # @!visibility public
+        #
+        # Caches the results of looking up the given ids in an {Entities::IdentityCache}
+        # and only fetches the records that have not yet been cached.
+        #
+        # @param (see #cache_for)
+        # @param [Array] ids to fetch.
+        # @yield (missing_ids)
+        # @yieldparam [Array] missing_ids that have not been cached yet.
+        # @yieldreturn [Entities::List] the list of entities for the missing ids.
+        #
+        # @example
+        #
+        #   def lookup( *ids )
+        #     cached_lookup( ids ) do |missing_ids|
+        #       entity_lookup_list( Models::User.where( id: missing_ids ), missing_ids, UserEntity::Missing )
+        #     end
+        #   end
+        def cached_lookup( ids, match: :id, coerce: :not_set, entity: nil, &lookup )
+          cache       = cache_for( key: match, coerce: coerce, entity: entity )
+          missing_ids = cache.uncached_keys( ids )
+
+          cache_entities( cache, match, missing_ids, &lookup ) if missing_ids.any?
+
+          entities = ids.map { |id| cache.fetch( id ) || fail( Shamu::NotFoundError ) }
+          Entities::List.new( entities )
+        end
+
+          def cache_entities( cache, match, missing_ids, &lookup )
+            matcher = entity_lookup_list_matcher( match )
+            if list = yield( missing_ids )
+              list.each do |e|
+                if e.empty?
+                  # For NullEntitty, the id for a custom field or matcher will
+                  # still always be assigned to the entity id.
+                  cache.add( e.id, e )
+                else
+                  cache.add( matcher.call( e ), e )
+                end
+              end
+            end
+          end
+
+        # @!visibility public
+        #
+        # @overload result( *validation_sources, request: nil, entity: nil )
+        # @param (see Result#initialize)
+        # @return [Result]
+        def result( *args )
+          Result.new( *args )
+        end
+
+        # @!visibility public
+        #
+        # Return an error {#result} from a service request.
+        # @overload error( attribute, message )
+        # @param (see ErrorResult#initialize)
+        # @return [ErrorResult]
+        def error( *args )
+          Result.new.tap do |r|
+            r.errors.add( *args )
+          end
+        end
+
+        # @param [String,Integer,#to_model_id] value
+        # @return [Boolean] true if the value looks like an ID.
+        def model_id?( value )
+          case Array( value ).first
+          when Integer then true
+          when String  then ToModelIdExtension::Strings::NUMERIC_PATTERN =~ value
+          end
+        end
+    end
+  end
+end

data/lib/shamu/services.rb

@@ -0,0 +1,12 @@
+module Shamu
+  # {include:file:lib/shamu/services/README.md}
+  module Services
+    require "shamu/services/error"
+    require "shamu/services/service"
+    require "shamu/services/request"
+    require "shamu/services/request_support"
+    require "shamu/services/result"
+    require "shamu/services/lazy_transform"
+    require "shamu/services/lazy_association"
+  end
+end

data/lib/shamu/sessions/README.md

@@ -0,0 +1,2 @@
+
+Sessions are awesome.