shamu 0.0.1 → 0.0.2

data/lib/shamu/entities/active_record_soft_destroy.rb

@@ -0,0 +1,91 @@
+module Shamu
+  module Entities
+
+    # Add the ability to "soft-delete" a record. Marking it as deleted so it is
+    # no longer present in the default scope but without actually removing the
+    # record from the database.
+    #
+    # > **Note** You must add a column `destroyed_at` to the model.
+    module ActiveRecordSoftDestroy
+      extend ActiveSupport::Concern
+
+      included do
+
+        # ============================================================================
+        # @!group Attributes
+        #
+
+        # @!attribute destroyed_at
+        # @return [DateTime] when the record was destroyed.
+
+        #
+        # @!endgroup Attributes
+
+        # ============================================================================
+        # @!group Scopes
+        #
+
+        # Limit the records to those that have been soft destroyed.
+        # @return [ActiveRecord::Relation]
+        scope :destroyed, ->() { unscope( where: :destroyed_at ).where( arel_table[ :destroyed_at ].not_eq( nil ) ) }
+
+        # Include live and soft destroyed records.
+        # @return [ActiveRecord::Relation]
+        scope :including_destroyed, ->() { unscope( where: :destroyed_at ) }
+
+        # Exclude destroyed records by dfault.
+        default_scope { where( destroyed_at: nil ) }
+
+        #
+        # @!endgroup Scopes
+
+      end
+
+      # Mark the record as deleted.
+      # @overload destroy
+      # @return [Boolean] true if the record was destroyed.
+      def destroy( options = nil )
+        if destroyed_at || ( options && options[:obliterate] )
+          super()
+        else
+          update_attribute :destroyed_at, Time.now.utc
+        end
+      end
+
+      # Really destroy the record.
+      # @return [Boolean] true if the record was destroyed.
+      def obliterate
+        destroy( obliterate: true )
+      end
+
+      # Really destroy! the record.
+      # @overload destroy!
+      # @return [Boolean] true if the record was destroyed.
+      def destroy!( options = nil )
+        if destroyed_at || ( options && options[:obliterate] )
+          super()
+        else
+          update_attribute :destroyed_at, Time.now.utc
+        end
+      end
+
+      # Really destroy! the record.
+      # @return [Boolean] true if the record was destroyed.
+      def obliterate!
+        destroy!( obliterate: true )
+      end
+
+      # Mark the record as no longer destroyed.
+      # @return [Boolean] true if the record was restored.
+      def undestroy
+        update_attribute :destroyed_at, nil
+      end
+
+      # @return [Boolean] true if the record has been soft destroyed.
+      def soft_destroyed?
+        !!destroyed_at
+      end
+
+    end
+  end
+end

data/lib/shamu/entities/entity.rb

@@ -0,0 +1,196 @@
+require "shamu/attributes"
+require "shamu/to_model_id_extension"
+require "active_model"
+
+module Shamu
+  module Entities
+
+    # An entity is an abstract set of data returned from a {Services::Service}
+    # describing the current state of an object.
+    #
+    # Entities are **immutable**. They will not change for the duration of the
+    # request. Instead use a {Services::Service} to mutate the underlying data
+    # and request an updated copy of the Entity.
+    #
+    # See {Shamu::Entities} for more on using entities.
+    #
+    # ## Helper Methods
+    #
+    # Entities can define helper methods to perform simple calculations or
+    # projections of it's data. They only rely on state available by other
+    # attribute projections. This makes the entity cacheable and serializable.
+    #
+    # ### Why class instead of module?
+    #
+    # The Entity class is ridiculously simple. It just mixes in a few modules
+    # and adds a few helper methods. It could just as easily been implemented
+    # as a module to mixin with POROs.
+    #
+    # While modules are generally preferred for non-domain specific behaviors,
+    # in this case the purpose is to intentionally make it harder to mix the
+    # responsibilities of an Entity class with another object in your project.
+    # This tends to lead to better separation in your design.
+    #
+    # @example
+    #
+    #   class LiveAccount < Shamu::Entities::Entity
+    #
+    #     # Use an ActiveRecord User model for the actual data. Not accessible
+    #     # to callers.
+    #     model :user
+    #
+    #     # Simple projections
+    #     attribute :name, on: :user
+    #     attribute :email, on: :user
+    #
+    #     # Computed projections. Only calculated once, then cached in the
+    #     # entity instance.
+    #     attribute :signed_up_on do
+    #       I18n.localize( user.created_at )
+    #     end
+    #
+    #     attribute :last_login_at do
+    #       user.login_reccords.last
+    #     end
+    #
+    #     # Project another model
+    #     model :contact
+    #
+    #     # Project a JSON object using another entity class
+    #     attribute :address, AddressEntity, on: :contact
+    #
+    #     # Helper method
+    #     def new_user?
+    #       signed_up_on > 3.days.ago
+    #     end
+    #   end
+    #
+    class Entity
+      include Shamu::Attributes
+      include Shamu::Attributes::Equality
+      include Shamu::ToModelIdExtension::Models
+
+      # @!attribute
+      # @return [Object] id of the entity.
+      #
+      # Shamu makes the assumption that all entities will have a single unique
+      # identifier that can be used to distinguish the entity from other
+      # instances of the same class.
+      #
+      # While not strictly necessary in an purely abstract service, this
+      # invariant significantly reduces the complexity of caching, lookups and
+      # other helpful conventions and is almost always true in most modern
+      # architectures.
+      #
+      # If an Entity does not have a natural primary key id, an id may be
+      # generated by joining the values of the composite key that is used to
+      # identify the resource.
+      def id
+        fail "No id attribute defined. Add `attribute :id, on: :record` to #{ self.class.name }"
+      end
+
+      # @return [false] real entities are not empty. See {NullEntity}.
+      def empty?
+        false
+      end
+      alias_method :blank?, :empty?
+
+      # @return [true] the entity is present. See {NullEntity}.
+      def present?
+        !empty?
+      end
+
+      # Entities are always immutable - so they are considered persisted. Use a
+      # {Services::ChangeRequest} to back a form instead.
+      def persisted?
+        true
+      end
+
+      # @return [self]
+      def to_entity
+        self
+      end
+
+      private
+
+        def serialize_attribute?( name, options )
+          super && !options[:model]
+        end
+
+      class << self
+
+        # @return [ActiveModel::Name] used by url_helpers etc when generating
+        #   model specific names for this entity.
+        def model_name
+          @model_name ||= begin
+            base_name = name.sub /(::)?Entity$/, ""
+            parts     = base_name.split "::"
+            parts[-1] = parts[-1].singularize
+            base_name = parts.join "::"
+
+            ::ActiveModel::Name.new( self, nil, base_name )
+          end
+        end
+
+        # Define custom default attributes for a {NullEntity} for this class.
+        # @return [Class] the {NullEntity} class for the entity.
+        #
+        # @example
+        #
+        #   class Users::UserEntity < Shamu::Entities::Entity
+        #     attribute :id
+        #     attribute :name
+        #     attribute :level
+        #
+        #     null_entity do
+        #       attribute :level do
+        #         "Guest"
+        #       end
+        #     end
+        #   end
+        def null_entity( &block )
+          null_class = ::Shamu::Entities::NullEntity.for( self )
+          null_class.class_eval( &block ) if block_given?
+          null_class
+        end
+
+        private
+
+          # @!visibility public
+          # Define a model attribute that the entity will project. Use additional
+          # {.attribute} calls to define the actual projections.
+          #
+          # Model attributes are _private_ and should never be exposed to any
+          # client from another domain. Instead project only the properties needed
+          # for the Entity's clients.
+          #
+          # @param (see Shamu::Attributes::DSL#attribute)
+          # @return [self]
+          #
+          # @example
+          #
+          #   class Account < Shamu::Entities::Entity
+          #     model :user
+          #
+          #     attribute :username, on: :user
+          #     attribute :email, on: :user
+          #   end
+          def model( name, **args, &block )
+            attribute( name, **args, &block )
+            attributes[name][:model] = true
+            private name
+          end
+
+          # Redefined to prevent creating mutable attributes.
+          def attr_accessor( * )
+            fail "Remember, an Entity is immutable. Use a Services::Service to mutate the underlying data."
+          end
+
+          # Redefined to prevent creating mutable attributes.
+          def attr_writer( * )
+            fail "Remember, an Entity is immutable. Use a Services::Service to mutate the underlying data."
+          end
+      end
+    end
+  end
+end

data/lib/shamu/entities/entity_path.rb

@@ -0,0 +1,87 @@
+module Shamu
+  module Entities
+
+    # An entity path descrives one or more levels of parent/child relationships
+    # that can be used to navigate from the root entity to a target entity.
+    #
+    # Entity paths can be used to identify polymorphic relationships between
+    # entities managed by difference services.
+    module EntityPath
+      module_function
+
+
+      # Composes an array of entities describing the path from the root entity
+      # to the leaf into a string.
+      #
+      # @example
+      #   path = compose_entity_path([
+      #             [ "User", "45" ],
+      #             [ "Calendar", "567" ],
+      #             [ "Event", "1" ]
+      #           ])
+      #   path # => "User[45]/Calendar[567]/Event[1]"
+      #
+      #   path = compose_entity_path( user )
+      #   path # => "User[45]"
+      #
+      # @param [Array<Entities::Entity>] entities
+      # @return [String]
+      def compose_entity_path( entities )
+        return unless entities.present?
+
+        entities.each_with_object( "" ) do |entity, path|
+          path << "/" if path.present?
+          path << compose_single_entity( entity )
+        end
+      end
+
+
+      # Decompose an entity path into an array of arrays of entity classes with
+      # their ids.
+      #
+      # @example
+      #   entities = decompose_entity_path( "User[45]/Calendar[567]/Event[1]" )
+      #   entities # => [
+      #            #      [ "User", "45" ],
+      #            #      [ "Calendar", "567" ],
+      #            #      [ "Event", "1" ]
+      #            #    ]
+      #
+      # @param [String] path the composed entity path.
+      # @return [Array<Array<String,String>>] the entities with their ids.
+      def decompose_entity_path( path )
+        return unless path.present?
+
+        path.split( "/" ).map do |node|
+          entity, id = node.split "["
+
+          [ entity, id[ 0..-2 ] ]
+        end
+      end
+
+      private
+
+        def compose_single_entity( entity )
+          case entity
+          when Entities::Entity    then build_composed_entity_path( entity.class.model_name.name, entity.id )
+          when Array               then build_composed_entity_path( entity_path_name( entity.first ), entity.last )
+          when /([A-Z][a-z0-9]*)+/ then entity
+          else                          fail "Don't know how to compose #{ entity }"
+          end
+        end
+
+        def entity_path_name( entity )
+          case entity
+          when String then entity.sub( /Entity$/, "" )
+          when Class  then Class.model_name.name
+          else             fail "Don't know how to compose #{ entity }"
+          end
+        end
+
+        def build_composed_entity_path( name, id )
+          "#{ name }[#{ id }]"
+        end
+
+    end
+  end
+end

data/lib/shamu/entities/identity_cache.rb

@@ -0,0 +1,64 @@
+module Shamu
+  module Entities
+
+    # Keeps a cache of {Entity} instances in memory for quick retrieval. Since
+    # entities are immutable, the cache
+    class IdentityCache
+
+      # Provide a block to automatically coerce keys to a known type. For
+      # example converting numeric strings ("123") to Integer values.
+      #
+      # @param [Symbol] coercion method to call on keys instead of providing a
+      #     block.
+      # @yield (key)
+      # @yieldparam [Object] key to coerce
+      # @yieldreturn [Object] the coerced value of the key.
+      def initialize( coercion = nil, &coercion_block )
+        @cache = {}
+        @coercion = block_given? ? coercion_block : ( coercion && coercion.to_proc )
+      end
+
+      # Fetch an entity with the given key.
+      # @param [Object] key of the entity. Typically the {Entity#id}.
+      # @return [Entity] the entity if found, otherwise `nil`.
+      def fetch( key )
+        cache.fetch( coerce_key( key ), nil )
+      end
+
+      # Filter the list of `keys` to those that haven't been cached yet.
+      # @param [Array] keys of the {Entity entities} that are about to be
+      #     {#fetch fetched}.
+      # @return [Array] the uncached keys.
+      def uncached_keys( keys )
+        uncached = Array( keys ).map { |k| coerce_key( k ) }
+        uncached.reject! { |k| cache.key?( k ) }
+        uncached
+      end
+
+      # Add a new entity to the cache.
+      # @param [Object] key of the entity. Typically the {Entity#id}.
+      # @param [Entity] entity to cache
+      # @return [entity]
+      def add( key, entity )
+        cache[ coerce_key( key ) ] = entity
+      end
+
+      # Invalidate the cached entry for the {Entity} with the given `key`.
+      # @param [Object] key of the entity. Typically the {Entity#id}.
+      # @return [Entity] the entity that was at the given key if present.
+      def invalidate( key )
+        cache.delete( key )
+      end
+
+      private
+
+        attr_reader :cache
+        attr_reader :coercion
+
+        def coerce_key( key )
+          return key unless coercion
+          coercion.call( key )
+        end
+    end
+  end
+end

data/lib/shamu/entities/list.rb

@@ -0,0 +1,54 @@
+module Shamu
+  module Entities
+
+    # A list of {Entities::Entity} records.
+    class List
+      include Enumerable
+
+      # @param [Enumerable] entities the raw list of entities.
+      def initialize( entities )
+        fail ArgumentError, "missing entities" if entities.nil?
+        @raw_entities = entities
+      end
+
+      # Enumerate through each of the entities in the list.
+      def each( &block )
+        entities.each( &block )
+      end
+
+      delegate :first, :count, :empty?, to: :raw_entities
+
+      alias_method :size, :count
+      alias_method :length, :count
+
+      # Get an entity by it's primary key.
+      # @param [Object] key the primary key to look for.
+      # @param [Symbol] field to use as the primary key. Default :id.
+      # @return [Entities::Entity] the found entity.
+      # @raise [Shamu::NotFoundError] if the entity cannot be found.
+      def get( key, field: key_attribute )
+        entity =
+          if field == :id
+            entities.find { |e| e.id == key }
+          else
+            entities.find { |e| e.send( field ) == key }
+          end
+        entity || fail( Shamu::NotFoundError )
+      end
+
+      private
+
+        attr_reader :raw_entities
+
+        def entities
+          # Array and others do not implement #lazy so allow anything that
+          # doesn't support lazy to just enumerate directly.
+          @entities ||= raw_entities.lazy || raw_entities
+        end
+
+        def key_attribute
+          :id
+        end
+    end
+  end
+end

data/lib/shamu/entities/list_scope/dates.rb

@@ -0,0 +1,57 @@
+module Shamu
+  module Entities
+    class ListScope
+
+      # Include paging parsing and attributes. Adds the following attributes
+      # to the list scope:
+      #
+      # ```
+      # class UsersListScope < Shamu::Entities::ListScope
+      #   include Shamu::Entities::ListScope::Paging
+      # end
+      #
+      # scope = UsersListScope.coerce!( params )
+      # scope.page      # => 1
+      # scope.per_page # => 25
+      # ```
+      module Dates
+
+        # ============================================================================
+        # @!group Attributes
+        #
+
+        # @!attribute since
+        # @return [Time] include only records added since the given timestamp.
+
+        # @!attribute until
+        # @return [Time] include only records up until the given timestamp.
+
+        # @!attribute default_since
+        # @return [Time] default {#since} if not specified.
+
+        # @!attribute default_until
+        # @return [Time] default {#until} if not specified.
+
+        #
+        # @!endgroup Attributes
+
+        def self.included( base )
+          super
+
+          coerce = Time.instance_method( :to_time ) ? :to_time : nil
+
+          base.attribute :since, coerce: coerce, default: ->() { default_since }
+          base.attribute :default_since, coerce: coerce, serialize: false
+          base.attribute :until, coerce: coerce, default: ->() { default_until }
+          base.attribute :default_until, coerce: coerce, serialize: false
+        end
+
+        # @return [Boolean] true if the scope is dated.
+        def dated?
+          !!self.since || !!self.until # rubocop:disable Style/RedundantSelf
+        end
+
+      end
+    end
+  end
+end

data/lib/shamu/entities/list_scope/paging.rb

@@ -0,0 +1,51 @@
+module Shamu
+  module Entities
+    class ListScope
+
+      # Include paging parsing and attributes. Adds the following attributes
+      # to the list scope:
+      #
+      # ```
+      # class UsersListScope < Shamu::Entities::ListScope
+      #   include Shamu::Entities::ListScope::Paging
+      # end
+      #
+      # scope = UsersListScope.coerce!( params )
+      # scope.page      # => 1
+      # scope.per_page # => 25
+      # ```
+      module Paging
+
+        # ============================================================================
+        # @!group Attributes
+        #
+
+        # @!attribute page
+        # @return [Integer] the current page number. 1 based.
+
+        # @!attribute per_page
+        # @return [Integer] number of records per page.
+
+        # @!attribute default_per_page
+        # @return [Integer] default number of records per page if not provided.
+
+        #
+        # @!endgroup Attributes
+
+        def self.included( base )
+          super
+
+          base.attribute :page, coerce: :to_i
+          base.attribute :per_page, coerce: :to_i, default: ->() { default_per_page }
+          base.attribute :default_per_page, coerce: :to_i, default: 25, serialize: false
+        end
+
+        # @return [Boolean] true if the scope is paged.
+        def paged?
+          !!page
+        end
+
+      end
+    end
+  end
+end

data/lib/shamu/entities/list_scope/scoped_paging.rb

@@ -0,0 +1,65 @@
+module Shamu
+  module Entities
+    class ListScope
+
+      # Include paging parsing and attributes exposed as a nested page object.
+      # Adds the following attributes to the list scope:
+      #
+      # ```
+      # class UsersListScope < Shamu::Entities::ListScope
+      #   include Shamu::Entities::ListScope::ScopedPaging
+      # end
+      #
+      # scope = UsersListScope.coerce!( page: { number: 5, size: 50 } )
+      # scope.page.number # => 5
+      # scope.page.size   # => 50
+      # ```
+      module ScopedPaging
+
+        # ============================================================================
+        # @!group Attributes
+        #
+
+        # @!attribute page
+        # @return [PageScope] the paging scope.
+
+        #
+        # @!endgroup Attributes
+
+        def self.included( base )
+          super
+
+          base.attribute :page, build: PageScope, default: PageScope.new
+        end
+
+        # @return [Boolean] true if the scope is paged.
+        def scoped_page?
+          !!page.number
+        end
+
+        # The scope of a [ScopedPaging] list scope.
+        class PageScope
+          include Shamu::Attributes
+
+          # @!attribute
+          # @return [Integer] the page number.
+          attribute :number, coerce: :to_i
+
+          # @!attribute
+          # @return [Integer] the size of each page.
+          attribute :size, coerce: :to_i, default: ->() { default_size }
+
+          # @!attribute
+          # @return [Integer] the default page size if not specified.
+          attribute :default_size, coerce: :to_i, default: 25, serialize: false
+
+          # @return [Hash] the scope as a params hash.
+          def params
+            to_attributes
+          end
+        end
+
+      end
+    end
+  end
+end