lotus-model 0.0.0 → 0.1.0

data/Rakefile

@@ -1 +1,17 @@
-require "bundler/gem_tasks"
+require 'rake'
+require 'rake/testtask'
+require 'bundler/gem_tasks'
+
+Rake::TestTask.new do |t|
+  t.pattern = 'test/**/*_test.rb'
+  t.libs.push 'test'
+end
+
+namespace :test do
+  task :coverage do
+    ENV['COVERAGE'] = 'true'
+    Rake::Task['test'].invoke
+  end
+end
+
+task default: :test

data/lib/lotus-model.rb

@@ -0,0 +1 @@
+require 'lotus/model'

data/lib/lotus/entity.rb

@@ -0,0 +1,157 @@
+require 'lotus/utils/kernel'
+
+module Lotus
+  # An object that is defined by its identity.
+  # See Domain Driven Design by Eric Evans.
+  #
+  # An entity is the core of an application, where the part of the domain
+  # logic is implemented. It's a small, cohesive object that express coherent
+  # and meagniful behaviors.
+  #
+  # It deals with one and only one responsibility that is pertinent to the
+  # domain of the application, without caring about details such as persistence
+  # or validations.
+  #
+  # This simplicity of design allows developers to focus on behaviors, or
+  # message passing if you will, which is the quintessence of Object Oriented
+  # Programming.
+  #
+  # @example With Lotus::Entity
+  #   require 'lotus/model'
+  #
+  #   class Person
+  #     include Lotus::Entity
+  #     self.attributes = :name, :age
+  #   end
+  #
+  # When a class includes `Lotus::Entity` it will receive the following interface:
+  #
+  #   * #id
+  #   * #id=
+  #   * #initialize(attributes = {})
+  #
+  # Also, the usage of `.attributes=` defines accessors for the given attribute
+  # names.
+  #
+  # If we expand the code above in pure Ruby, it would be:
+  #
+  # @example Pure Ruby
+  #   class Person
+  #     attr_accessor :id, :name, :age
+  #
+  #     def initialize(attributes = {})
+  #       @id, @name, @age = attributes.values_at(:id, :name, :age)
+  #     end
+  #   end
+  #
+  # Indeed, **Lotus::Model** ships `Entity` only for developers's convenience, but the
+  # rest of the framework is able to accept any object that implements the interface above.
+  #
+  # However, we suggest to implement this interface by including `Lotus::Entity`,
+  # in case that future versions of the framework will expand it.
+  #
+  # @since 0.1.0
+  #
+  # @see Lotus::Repository
+  module Entity
+    # Inject the public API into the hosting class.
+    #
+    # @since 0.1.0
+    #
+    # @example With Object
+    #   require 'lotus/model'
+    #
+    #   class User
+    #     include Lotus::Entity
+    #   end
+    #
+    # @example With Struct
+    #   require 'lotus/model'
+    #
+    #   User = Struct.new(:id, :name) do
+    #     include Lotus::Entity
+    #   end
+    def self.included(base)
+      base.class_eval do
+        extend ClassMethods
+      end
+    end
+
+    module ClassMethods
+      # (Re)defines getters, setters and initialization for the given attributes.
+      #
+      # These attributes can match the database columns, but this isn't a
+      # requirement. The mapper used by the relative repository will translate
+      # these names automatically.
+      #
+      # An entity can work with attributes not configured in the mapper, but
+      # of course they will be ignored when the entity will be persisted.
+      #
+      # Please notice that the required `id` attribute is automatically defined
+      # and can be omitted in the arguments.
+      #
+      # @param attributes [Array<Symbol>] a set of arbitrary attribute names
+      #
+      # @since 0.1.0
+      #
+      # @see Lotus::Repository
+      # @see Lotus::Model::Mapper
+      #
+      # @example
+      #   require 'lotus/model'
+      #
+      #   class User
+      #     include Lotus::Entity
+      #     self.attributes = :name
+      #   end
+      def attributes=(*attributes)
+        @attributes = Lotus::Utils::Kernel.Array(attributes.unshift(:id))
+
+        class_eval %{
+          def initialize(attributes = {})
+        #{ @attributes.map {|a| "@#{a}" }.join(', ') }, = *attributes.values_at(#{ @attributes.map {|a| ":#{a}"}.join(', ') })
+          end
+        }
+
+        @attributes.each do |attr|
+          class_eval do
+            attr_accessor attr
+          end
+        end
+      end
+
+      def attributes
+        @attributes
+      end
+    end
+
+    # Defines a generic, inefficient initializer, in case that the attributes
+    # weren't explicitly defined with `.attributes=`.
+    #
+    # @param attributes [Hash] a set of attribute names and values
+    #
+    # @raise NoMethodError in case the given attributes are trying to set unknown
+    #   or private methods.
+    #
+    # @since 0.1.0
+    #
+    # @see .attributes
+    def initialize(attributes = {})
+      attributes.each do |k, v|
+        public_send("#{ k }=", v)
+      end
+    end
+
+    # Overrides the equality Ruby operator
+    #
+    # Two entities are considered equal if they are instances of the same class
+    # and if they have the same #id.
+    #
+    # @since 0.1.0
+    def ==(other)
+      self.class == other.class &&
+         self.id == other.id
+    end
+  end
+end
+

data/lib/lotus/model.rb

@@ -1,7 +1,28 @@
-require "lotus/model/version"
+require 'lotus/model/version'
+require 'lotus/entity'
+require 'lotus/repository'
+require 'lotus/model/mapper'
 
 module Lotus
+  # Model
+  #
+  # @since 0.1.0
   module Model
-    # Your code goes here...
+    # Error for not found entity
+    #
+    # @since 0.1.0
+    #
+    # @see Lotus::Repository.find
+    class EntityNotFound < ::StandardError
+    end
+
+    # Error for non persisted entity
+    # It's raised when we try to update or delete a non persisted entity.
+    #
+    # @since 0.1.0
+    #
+    # @see Lotus::Repository.update
+    class NonPersistedEntityError < ::StandardError
+    end
   end
 end

data/lib/lotus/model/adapters/abstract.rb

@@ -0,0 +1,167 @@
+module Lotus
+  module Model
+    module Adapters
+      # It's raised when an adapter can't find the underlying database adapter.
+      #
+      # Example: When we try to use the SqlAdapter with a Postgres database
+      # but we didn't loaded the pg gem before.
+      #
+      # @see Lotus::Model::Adapters::SqlAdapter#initialize
+      #
+      # @since 0.1.0
+      class DatabaseAdapterNotFound < ::StandardError
+      end
+
+      # Abstract adapter.
+      #
+      # An adapter is a concrete implementation that allows a repository to
+      # communicate with a single database.
+      #
+      # Lotus::Model is shipped with Memory and SQL adapters.
+      # Third part adapters MUST implement the interface defined here.
+      # For convenience they may inherit from this class.
+      #
+      # These are low level details, and shouldn't be used directly.
+      # Please use a repository for entities persistence.
+      #
+      # @since 0.1.0
+      class Abstract
+        # Initialize the adapter
+        #
+        # @param mapper [Lotus::Model::Mapper] the object that defines the
+        #   database to entities mapping
+        #
+        # @param uri [String] the optional connection string to the database
+        #
+        # @since 0.1.0
+        def initialize(mapper, uri = nil)
+          @mapper, @uri = mapper, uri
+        end
+
+        # Creates or updates a record in the database for the given entity.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        # @param entity [Object] the entity to persist
+        #
+        # @return [Object] the entity
+        #
+        # @since 0.1.0
+        def persist(collection, entity)
+          raise NotImplementedError
+        end
+
+        # Creates a record in the database for the given entity.
+        # It should assign an id (identity) to the entity in case of success.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        # @param entity [Object] the entity to create
+        #
+        # @return [Object] the entity
+        #
+        # @since 0.1.0
+        def create(collection, entity)
+          raise NotImplementedError
+        end
+
+        # Updates a record in the database corresponding to the given entity.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        # @param entity [Object] the entity to update
+        #
+        # @return [Object] the entity
+        #
+        # @since 0.1.0
+        def update(collection, entity)
+          raise NotImplementedError
+        end
+
+        # Deletes a record in the database corresponding to the given entity.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        # @param entity [Object] the entity to delete
+        #
+        # @since 0.1.0
+        def delete(collection, entity)
+          raise NotImplementedError
+        end
+
+        # Returns all the records for the given collection
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        #
+        # @return [Array] all the records
+        #
+        # @since 0.1.0
+        def all(collection)
+          raise NotImplementedError
+        end
+
+        # Returns an unique record from the given collection, with the given
+        # identity.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        # @param id [Object] the identity of the object.
+        #
+        # @return [Object] the entity
+        #
+        # @since 0.1.0
+        def find(collection, id)
+          raise NotImplementedError
+        end
+
+        # Returns the first record in the given collection.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        #
+        # @return [Object] the first entity
+        #
+        # @since 0.1.0
+        def first(collection)
+          raise NotImplementedError
+        end
+
+        # Returns the last record in the given collection.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        #
+        # @return [Object] the last entity
+        #
+        # @since 0.1.0
+        def last(collection)
+          raise NotImplementedError
+        end
+
+        # Empties the given collection.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        #
+        # @since 0.1.0
+        def clear(collection)
+          raise NotImplementedError
+        end
+
+        # Executes a command for the given query.
+        #
+        # @param query [Object] the query object to act on.
+        #
+        # @since 0.1.0
+        def command(query)
+          raise NotImplementedError
+        end
+
+        # Returns a query
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        # @param blk [Proc] a block of code to be executed in the context of
+        #   the query.
+        #
+        # @return [Object]
+        #
+        # @since 0.1.0
+        def query(collection, &blk)
+          raise NotImplementedError
+        end
+      end
+    end
+  end
+end

data/lib/lotus/model/adapters/implementation.rb

@@ -0,0 +1,111 @@
+module Lotus
+  module Model
+    module Adapters
+      # Shared implementation for SqlAdapter and MemoryAdapter
+      #
+      # @api private
+      # @since 0.1.0
+      module Implementation
+        # Creates or updates a record in the database for the given entity.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        # @param entity [#id, #id=] the entity to persist
+        #
+        # @return [Object] the entity
+        #
+        # @api private
+        # @since 0.1.0
+        def persist(collection, entity)
+          if entity.id
+            update(collection, entity)
+          else
+            create(collection, entity)
+          end
+        end
+
+        # Returns all the records for the given collection
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        #
+        # @return [Array] all the records
+        #
+        # @api private
+        # @since 0.1.0
+        def all(collection)
+          # TODO consider to make this lazy (aka remove #all)
+          query(collection).all
+        end
+
+        # Returns an unique record from the given collection, with the given
+        # id.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        # @param id [Object] the identity of the object.
+        #
+        # @return [Object] the entity
+        #
+        # @api private
+        # @since 0.1.0
+        def find(collection, id)
+          _first(
+            _find(collection, id)
+          )
+        end
+
+        # Returns the first record in the given collection.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        #
+        # @return [Object] the first entity
+        #
+        # @api private
+        # @since 0.1.0
+        def first(collection)
+          _first(
+            query(collection).asc(_identity(collection))
+          )
+        end
+
+        # Returns the last record in the given collection.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        #
+        # @return [Object] the last entity
+        #
+        # @api private
+        # @since 0.1.0
+        def last(collection)
+          _first(
+            query(collection).desc(_identity(collection))
+          )
+        end
+
+        private
+        def _collection(name)
+          raise NotImplementedError
+        end
+
+        def _mapped_collection(name)
+          @mapper.collection(name)
+        end
+
+        def _find(collection, id)
+          identity = _identity(collection)
+          query(collection).where(identity => _id(collection, identity, id))
+        end
+
+        def _first(query)
+          query.limit(1).first
+        end
+
+        def _identity(collection)
+          _mapped_collection(collection).identity
+        end
+
+        def _id(collection, column, value)
+          _mapped_collection(collection).deserialize_attribute(column, value)
+        end
+      end
+    end
+  end
+end