lotus-model 0.0.0 → 0.1.0

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

@@ -0,0 +1,154 @@
+require 'lotus/model/adapters/abstract'
+require 'lotus/model/adapters/implementation'
+require 'lotus/model/adapters/sql/collection'
+require 'lotus/model/adapters/sql/command'
+require 'lotus/model/adapters/sql/query'
+require 'sequel'
+
+module Lotus
+  module Model
+    module Adapters
+      # Adapter for SQL databases
+      #
+      # In order to use it with a specific database, you must require the Ruby
+      # gem before of loading Lotus::Model.
+      #
+      # @see Lotus::Model::Adapters::Implementation
+      #
+      # @api private
+      # @since 0.1.0
+      class SqlAdapter < Abstract
+        include Implementation
+
+        # Initialize the adapter.
+        #
+        # Lotus::Model uses Sequel. For a complete reference of the connection
+        # URI, please see: http://sequel.jeremyevans.net/rdoc/files/doc/opening_databases_rdoc.html
+        #
+        # @param mapper [Object] the database mapper
+        # @param uri [String] the connection uri for the database
+        #
+        # @return [Lotus::Model::Adapters::SqlAdapter]
+        #
+        # @raise [Lotus::Model::Adapters::DatabaseAdapterNotFound] if the given
+        #   URI refers to an unknown or not registered adapter.
+        #
+        # @raise [URI::InvalidURIError] if the given URI is malformed
+        #
+        # @see Lotus::Model::Mapper
+        # @see http://sequel.jeremyevans.net/rdoc/files/doc/opening_databases_rdoc.html
+        #
+        # @api private
+        # @since 0.1.0
+        def initialize(mapper, uri)
+          super
+          @connection = Sequel.connect(@uri)
+        rescue Sequel::AdapterNotFound => e
+          raise DatabaseAdapterNotFound.new(e.message)
+        end
+
+        # Creates a record in the database for the given entity.
+        # It assigns the `id` attribute, in case of success.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        # @param entity [#id=] the entity to create
+        #
+        # @return [Object] the entity
+        #
+        # @api private
+        # @since 0.1.0
+        def create(collection, entity)
+          entity.id = command(
+                        query(collection)
+                      ).create(entity)
+          entity
+        end
+
+        # Updates a record in the database corresponding to the given entity.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        # @param entity [#id] the entity to update
+        #
+        # @return [Object] the entity
+        #
+        # @api private
+        # @since 0.1.0
+        def update(collection, entity)
+          command(
+            _find(collection, entity.id)
+          ).update(entity)
+        end
+
+        # Deletes a record in the database corresponding to the given entity.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        # @param entity [#id] the entity to delete
+        #
+        # @api private
+        # @since 0.1.0
+        def delete(collection, entity)
+          command(
+            _find(collection, entity.id)
+          ).delete
+        end
+
+        # Deletes all the records from the given collection.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        #
+        # @api private
+        # @since 0.1.0
+        def clear(collection)
+          command(query(collection)).clear
+        end
+
+        # Fabricates a command for the given query.
+        #
+        # @param query [Lotus::Model::Adapters::Sql::Query] the query object to
+        #   act on.
+        #
+        # @return [Lotus::Model::Adapters::Sql::Command]
+        #
+        # @see Lotus::Model::Adapters::Sql::Command
+        #
+        # @api private
+        # @since 0.1.0
+        def command(query)
+          Sql::Command.new(query)
+        end
+
+        # Fabricates 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 [Lotus::Model::Adapters::Sql::Query]
+        #
+        # @see Lotus::Model::Adapters::Sql::Query
+        #
+        # @api private
+        # @since 0.1.0
+        def query(collection, context = nil, &blk)
+          Sql::Query.new(_collection(collection), context, &blk)
+        end
+
+        private
+
+        # Returns a collection from the given name.
+        #
+        # @param name [Symbol] a name of the collection (it must be mapped).
+        #
+        # @return [Lotus::Model::Adapters::Sql::Collection]
+        #
+        # @see Lotus::Model::Adapters::Sql::Collection
+        #
+        # @api private
+        # @since 0.1.0
+        def _collection(name)
+          Sql::Collection.new(@connection[name], _mapped_collection(name))
+        end
+      end
+    end
+  end
+end

data/lib/lotus/model/mapper.rb

@@ -0,0 +1,101 @@
+require 'lotus/model/mapping'
+
+module Lotus
+  module Model
+    # A persistence mapper that keep entities independent from database details.
+    #
+    # This is database independent. It can work with SQL, document, and even
+    # with key/value stores.
+    #
+    # @since 0.1.0
+    #
+    # @see http://martinfowler.com/eaaCatalog/dataMapper.html
+    #
+    # @example
+    #   require 'lotus/model'
+    #
+    #   mapper = Lotus::Model::Mapper.new do
+    #     collection :users do
+    #       entity User
+    #
+    #       attribute :id,   Integer
+    #       attribute :name, String
+    #     end
+    #   end
+    #
+    #   # This guarantees thread-safety and should happen as last thing before
+    #   # to start the app code.
+    #   mapper.load!
+    class Mapper
+      # @attr_reader collections [Hash] all the mapped collections
+      #
+      # @since 0.1.0
+      # @api private
+      attr_reader :collections
+
+      # Instantiate a mapper.
+      #
+      # It accepts an optional argument (`coercer`) a class that defines the
+      # policies for entities translations from/to the database.
+      #
+      # If provided, this class must implement the following interface:
+      #
+      #   * #initialize(collection) # Lotus::Model::Mapping::Collection
+      #   * #to_record(entity)      # translates an entity to the database type
+      #   * #from_record(record)    # translates a record into an  entity
+      #   * #deserialize_*(value)   # a set of methods, one for each database column.
+      #
+      # If not given, it uses `Lotus::Model::Mapping::Coercer`, by default.
+      #
+      #
+      #
+      # @param coercer [Class] an optional class that defines the policies for
+      #   entity translations from/to the database.
+      #
+      # @param blk [Proc] an optional block of code that gets evaluated in the
+      #   context of the current instance
+      #
+      # @return [Lotus::Model::Mapper]
+      #
+      # @since 0.1.0
+      def initialize(coercer = nil, &blk)
+        @coercer     = coercer || Mapping::Coercer
+        @collections = {}
+        instance_eval(&blk) if block_given?
+      end
+
+      # Maps a collection.
+      #
+      # A collection is a set of homogeneous records. Think of a table of a SQL
+      # database or about collection of MongoDB.
+      #
+      # @param name [Symbol] the name of the mapped collection. If used with a
+      #   SQL database it's the table name.
+      #
+      # @param blk [Proc] the block that maps the attributes of that collection.
+      #
+      # @since 0.1.0
+      #
+      # @see Lotus::Model::Mapping::Collection
+      def collection(name, &blk)
+        if block_given?
+          @collections[name] = Mapping::Collection.new(name, @coercer, &blk)
+        else
+          # TODO implement a getter with a private API.
+          @collections[name] or raise Mapping::UnmappedCollectionError.new(name)
+        end
+      end
+
+      # Loads the internals of the mapper, in order to guarantee thread safety.
+      #
+      # This method MUST be invoked as the last thing before of start using the
+      # application.
+      #
+      # @since 0.1.0
+      def load!
+        @collections.each {|_, collection| collection.load! }
+        self
+      end
+    end
+  end
+end

data/lib/lotus/model/mapping.rb

@@ -0,0 +1,23 @@
+require 'lotus/model/mapping/collection'
+require 'lotus/model/mapping/coercer'
+
+module Lotus
+  module Model
+    # Mapping internal utilities
+    #
+    # @since 0.1.0
+    module Mapping
+      # Unmapped collection error.
+      #
+      # It gets raised when the application tries to access to a non-mapped
+      # collection.
+      #
+      # @since 0.1.0
+      class UnmappedCollectionError < ::StandardError
+        def initialize(name)
+          super("Cannot find collection: #{ name }")
+        end
+      end
+    end
+  end
+end

data/lib/lotus/model/mapping/coercer.rb

@@ -0,0 +1,80 @@
+require 'lotus/utils/kernel'
+
+module Lotus
+  module Model
+    module Mapping
+      # Translates values from/to the database with the corresponding Ruby type.
+      #
+      # @api private
+      # @since 0.1.0
+      class Coercer
+        # Initialize a coercer for the given collection.
+        #
+        # @param collection [Lotus::Model::Mapping::Collection] the collection
+        #
+        # @api private
+        # @since 0.1.0
+        def initialize(collection)
+          @collection = collection
+          _compile!
+        end
+
+        # Translates the given entity into a format compatible with the database.
+        #
+        # @param entity [Object] the entity
+        #
+        # @return [Hash]
+        #
+        # @api private
+        # @since 0.1.0
+        def to_record(entity)
+        end
+
+        # Translates the given record into a Ruby object.
+        #
+        # @param record [Hash]
+        #
+        # @return [Object]
+        #
+        # @api private
+        # @since 0.1.0
+        def from_record(record)
+        end
+
+        private
+        # Compile itself for perfomance boost.
+        #
+        # @api private
+        # @since 0.1.0
+        def _compile!
+          code = @collection.attributes.map do |_,(klass,mapped)|
+            %{
+            def deserialize_#{ mapped }(value)
+              Lotus::Utils::Kernel.#{klass}(value)
+            end
+            }
+          end.join("\n")
+
+          instance_eval %{
+            def to_record(entity)
+              if entity.id
+                Hash[*[#{ @collection.attributes.map{|name,(_,mapped)| ":#{mapped},entity.#{name}"}.join(',') }]]
+              else
+                Hash[*[#{ @collection.attributes.reject{|name,_| name == @collection.identity }.map{|name,(_,mapped)| ":#{mapped},entity.#{name}"}.join(',') }]]
+              end
+            end
+
+            def from_record(record)
+              #{ @collection.entity }.new(
+                Hash[*[#{ @collection.attributes.map{|name,(klass,mapped)| ":#{name},Lotus::Utils::Kernel.#{klass}(record[:#{mapped}])"}.join(',') }]]
+              )
+            end
+
+            #{ code }
+          }
+        end
+      end
+    end
+  end
+end
+

data/lib/lotus/model/mapping/collection.rb

@@ -0,0 +1,336 @@
+module Lotus
+  module Model
+    module Mapping
+      # Maps a collection and its attributes.
+      #
+      # A collection is a set of homogeneous records. Think of a table of a SQL
+      # database or about collection of MongoDB.
+      #
+      # This is database independent. It can work with SQL, document, and even
+      # with key/value stores.
+      #
+      # @since 0.1.0
+      #
+      # @see Lotus::Model::Mapper
+      #
+      # @example
+      #   require 'lotus/model'
+      #
+      #   mapper = Lotus::Model::Mapper.new do
+      #     collection :users do
+      #       entity User
+      #
+      #       attribute :id,   Integer
+      #       attribute :name, String
+      #     end
+      #   end
+      class Collection
+        # Repository name suffix
+        #
+        # @api private
+        # @since 0.1.0
+        #
+        # @see Lotus::Repository
+        REPOSITORY_SUFFIX = 'Repository'.freeze
+
+        # Defines top level constant for attribute usage.
+        #
+        # @since 0.1.0
+        #
+        # @see Lotus::Model::Mapping::Collection#attribute
+        #
+        # @example
+        #   require 'lotus/model'
+        #
+        #   mapper = Lotus::Model::Mapper.new do
+        #     collection :articles do
+        #       entity Article
+        #
+        #       attribute :published, Boolean
+        #     end
+        #   end
+        class ::Boolean
+        end
+
+        # @attr_reader name [Symbol] the name of the collection
+        #
+        # @since 0.1.0
+        # @api private
+        attr_reader :name
+
+        # @attr_reader coercer_class [Class] the coercer class
+        #
+        # @since 0.1.0
+        # @api private
+        attr_reader :coercer_class
+
+        # @attr_reader attributes [Hash] the set of attributes
+        #
+        # @since 0.1.0
+        # @api private
+        attr_reader :attributes
+
+        # Instantiate a new collection
+        #
+        # @param name [Symbol] the name of the mapped collection. If used with a
+        #   SQL database it's the table name.
+        #
+        # @param blk [Proc] the block that maps the attributes of that collection.
+        #
+        # @since 0.1.0
+        #
+        # @see Lotus::Model::Mapper#collection
+        def initialize(name, coercer_class, &blk)
+          @name, @coercer_class, @attributes = name, coercer_class, {}
+          instance_eval(&blk) if block_given?
+        end
+
+        # Defines the entity that is persisted with this collection.
+        #
+        # The entity can be any kind of object as long it implements the
+        # following interface: `#initialize(attributes = {})`.
+        #
+        # @param klass [Class] the entity persisted with this collection.
+        #
+        # @since 0.1.0
+        #
+        # @see Lotus::Entity
+        def entity(klass = nil)
+          if klass
+            @entity = klass
+          else
+            @entity
+          end
+        end
+
+        # Defines the identity for a collection.
+        #
+        # An identity is an unique value that identifies a record.
+        # If used with an SQL table it corresponds to the primary key.
+        #
+        # This is an optional feature.
+        # By default the system assumes that your identity is `:id`.
+        # If this is the case, you can omit the value, otherwise you have to
+        # specify it.
+        #
+        # @param name [Symbol] the name of the identity
+        #
+        # @since 0.1.0
+        #
+        # @example Default
+        #   require 'lotus/model'
+        #
+        #   # We have an SQL table `users` with a primary key `id`.
+        #   #
+        #   # This this is compliant to the mapper default, we can omit
+        #   # `#identity`.
+        #
+        #   mapper = Lotus::Model::Mapper.new do
+        #     collection :users do
+        #       entity User
+        #
+        #       # attribute definitions..
+        #     end
+        #   end
+        #
+        # @example Custom identity
+        #   require 'lotus/model'
+        #
+        #   # We have an SQL table `articles` with a primary key `i_id`.
+        #   #
+        #   # This schema diverges from the expected default: `id`, that's why
+        #   # we need to use #identity to let the mapper to recognize the
+        #   # primary key.
+        #
+        #   mapper = Lotus::Model::Mapper.new do
+        #     collection :articles do
+        #       entity Article
+        #
+        #       # attribute definitions..
+        #
+        #       identity :i_id
+        #     end
+        #   end
+        def identity(name = nil)
+          if name
+            @identity = name
+          else
+            @identity || :id
+          end
+        end
+
+        # Map an attribute.
+        #
+        # An attribute defines a property of an object.
+        # This is storage independent. For instance, it can map an SQL column,
+        # a MongoDB attribute or everything that makes sense for your database.
+        #
+        # Each attribute defines an Ruby type, to coerce that value from the
+        # database. This fixes a huge problem, because database types don't
+        # match Ruby types.
+        # Think of Redis, where everything is stored as a string or integer,
+        # the mapper translates values from/to the database.
+        #
+        # It supports the following types:
+        #
+        #   * Array
+        #   * Boolean
+        #   * Date
+        #   * DateTime
+        #   * Float
+        #   * Hash
+        #   * Integer
+        #   * Set
+        #   * String
+        #   * Time
+        #
+        # @param name [Symbol] the name of the attribute, as we want it to be
+        #   mapped in the object
+        #
+        # @param klass [Class] the Ruby type that we want to assign as value
+        #
+        # @param options [Hash] a set of options to customize the mapping
+        # @option options [Symbol] :as the name of the original column
+        #
+        # @since 0.1.0
+        #
+        # @example Default schema
+        #   require 'lotus/model'
+        #
+        #   # Given the following schema:
+        #   #
+        #   # CREATE TABLE users (
+        #   #   id     integer NOT NULL,
+        #   #   name   varchar(64),
+        #   # );
+        #   #
+        #   # And the following entity:
+        #   #
+        #   # class User
+        #   #   include Lotus::Entity
+        #   #   self.attributes = :name
+        #   # end
+        #
+        #   mapper = Lotus::Model::Mapper.new do
+        #     collection :users do
+        #       entity User
+        #
+        #       attribute :id,   Integer
+        #       attribute :name, String
+        #     end
+        #   end
+        #
+        #   # The first argument (`:name`) always corresponds to the `User`
+        #   # attribute.
+        #
+        #   # The second one (`:klass`) is the Ruby type that we want for our
+        #   # attribute.
+        #
+        #   # We don't need to use `:as` because the database columns match the
+        #   # `User` attributes.
+        #
+        # @example Customized schema
+        #   require 'lotus/model'
+        #
+        #   # Given the following schema:
+        #   #
+        #   # CREATE TABLE articles (
+        #   #   i_id           integer NOT NULL,
+        #   #   i_user_id      integer NOT NULL,
+        #   #   s_title        varchar(64),
+        #   #   comments_count varchar(8) # Not an error: it's for String => Integer coercion
+        #   # );
+        #   #
+        #   # And the following entity:
+        #   #
+        #   # class Article
+        #   #   include Lotus::Entity
+        #   #   self.attributes = :user_id, :title, :comments_count
+        #   # end
+        #
+        #   mapper = Lotus::Model::Mapper.new do
+        #     collection :articles do
+        #       entity Article
+        #
+        #       attribute :id,             Integer, as: :i_id
+        #       attribute :user_id,        Integer, as: :i_user_id
+        #       attribute :title,          String,  as: :s_title
+        #       attribute :comments_count, Integer
+        #
+        #       identity :i_id
+        #     end
+        #   end
+        #
+        #   # The first argument (`:name`) always corresponds to the `Article`
+        #   # attribute.
+        #
+        #   # The second one (`:klass`) is the Ruby type that we want for our
+        #   # attribute.
+        #
+        #   # The third option (`:as`) is mandatory only when the database
+        #   # column doesn't match the name of the mapped attribute.
+        #   #
+        #   # For instance: we need to use it for translate `:s_title` to
+        #   # `:title`, but not for `:comments_count`.
+        def attribute(name, klass, options = {})
+          @attributes[name] = [klass, (options.fetch(:as) { name }).to_sym]
+        end
+
+        # Serializes an entity to be persisted in the database.
+        #
+        # @param entity [Object] an entity
+        #
+        # @api private
+        # @since 0.1.0
+        def serialize(entity)
+          @coercer.to_record(entity)
+        end
+
+        # Deserialize a set of records fetched from the database.
+        #
+        # @param records [Array] a set of raw records
+        #
+        # @api private
+        # @since 0.1.0
+        def deserialize(records)
+          records.map do |record|
+            @coercer.from_record(record)
+          end
+        end
+
+        # Deserialize only one attribute from a raw value.
+        #
+        # @param attribute [Symbol] the attribute name
+        # @param value [Object,nil] the value to be coerced
+        #
+        # @api private
+        # @since 0.1.0
+        def deserialize_attribute(attribute, value)
+          @coercer.public_send(:"deserialize_#{ attribute }", value)
+        end
+
+        # Loads the internals of the mapper, in order to guarantee thread safety.
+        #
+        # @api private
+        # @since 0.1.0
+        def load!
+          @coercer = coercer_class.new(self)
+          configure_repository!
+        end
+
+        private
+        # Assigns a repository to an entity
+        #
+        # @see Lotus::Repository
+        #
+        # @api private
+        # @since 0.1.0
+        def configure_repository!
+          repository = Object.const_get("#{ entity.name }#{ REPOSITORY_SUFFIX }")
+          repository.collection = name
+        rescue NameError
+        end
+      end
+    end
+  end
+end