hanami-model 0.0.0 → 0.6.0

data/hanami-model.gemspec

@@ -4,20 +4,25 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'hanami/model/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "hanami-model"
+  spec.name          = 'hanami-model'
   spec.version       = Hanami::Model::VERSION
-  spec.authors       = ["Luca Guidi"]
-  spec.email         = ["me@lucaguidi.com"]
+  spec.authors       = ['Luca Guidi', 'Trung Lê', 'Alfonso Uceda']
+  spec.email         = ['me@lucaguidi.com', 'trung.le@ruby-journal.com', 'uceda73@gmail.com']
+  spec.summary       = %q{A persistence layer for Hanami}
+  spec.description   = %q{A persistence framework with entities, repositories, data mapper and query objects}
+  spec.homepage      = 'http://hanamirb.org'
+  spec.license       = 'MIT'
 
-  spec.summary       = %q{The web, with simplicity}
-  spec.description   = %q{Hanami is a web framework for Ruby}
-  spec.homepage      = "http://hanamirb.org"
+  spec.files         = `git ls-files -z -- lib/* CHANGELOG.md EXAMPLE.md LICENSE.md README.md hanami-model.gemspec`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+  spec.required_ruby_version = '>= 2.0.0'
 
-  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
-  spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
+  spec.add_runtime_dependency 'hanami-utils', '~> 0.7'
+  spec.add_runtime_dependency 'sequel',       '~> 4.9'
 
-  spec.add_development_dependency "bundler", "~> 1.11"
-  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency 'bundler',  '~> 1.6'
+  spec.add_development_dependency 'minitest', '~> 5'
+  spec.add_development_dependency 'rake',     '~> 10'
 end

data/lib/hanami-model.rb

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

data/lib/hanami/entity.rb

@@ -0,0 +1,298 @@
+require 'hanami/utils/kernel'
+require 'hanami/utils/attributes'
+
+module Hanami
+  # 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 expresses coherent
+  # and meaningful 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 Hanami::Entity
+  #   require 'hanami/model'
+  #
+  #   class Person
+  #     include Hanami::Entity
+  #     attributes :name, :age
+  #   end
+  #
+  # When a class includes `Hanami::Entity` it receives the following interface:
+  #
+  #   * #id
+  #   * #id=
+  #   * #initialize(attributes = {})
+  #
+  # `Hanami::Entity` also provides the `.attributes=` for defining attribute accessors for the given 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
+  #
+  # **Hanami::Model** ships `Hanami::Entity` for developers's convenience.
+  #
+  # **Hanami::Model** depends on a narrow and well-defined interface for an
+  # Entity - `#id`, `#id=`, `#initialize(attributes={})`.If your object
+  # implements that interface then that object can be used as an Entity in the
+  # **Hanami::Model** framework.
+  #
+  # However, we suggest to implement this interface by including
+  # `Hanami::Entity`, in case that future versions of the framework will expand
+  # it.
+  #
+  # See Dependency Inversion Principle for more on interfaces.
+  #
+  # @since 0.1.0
+  #
+  # @see Hanami::Repository
+  module Entity
+    # Inject the public API into the hosting class.
+    #
+    # @since 0.1.0
+    #
+    # @example With Object
+    #   require 'hanami/model'
+    #
+    #   class User
+    #     include Hanami::Entity
+    #   end
+    #
+    # @example With Struct
+    #   require 'hanami/model'
+    #
+    #   User = Struct.new(:id, :name) do
+    #     include Hanami::Entity
+    #   end
+    def self.included(base)
+      base.class_eval do
+        extend ClassMethods
+        attributes :id
+      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 attrs [Array<Symbol>] a set of arbitrary attribute names
+      #
+      # @since 0.2.0
+      #
+      # @see Hanami::Repository
+      # @see Hanami::Model::Mapper
+      #
+      # @example
+      #   require 'hanami/model'
+      #
+      #   class User
+      #     include Hanami::Entity
+      #     attributes :name, :age
+      #   end
+      #   User.attributes => #<Set: {:id, :name, :age}>
+      #
+      # @example Given params is array of attributes
+      #   require 'hanami/model'
+      #
+      #   class User
+      #     include Hanami::Entity
+      #     attributes [:name, :age]
+      #   end
+      #   User.attributes => #<Set: {:id, :name, :age}>
+      #
+      # @example Extend entity
+      #   require 'hanami/model'
+      #
+      #   class User
+      #     include Hanami::Entity
+      #     attributes :name
+      #   end
+      #
+      #   class DeletedUser < User
+      #     include Hanami::Entity
+      #     attributes :deleted_at
+      #   end
+      #
+      #   User.attributes => #<Set: {:id, :name}>
+      #   DeletedUser.attributes => #<Set: {:id, :name, :deleted_at}>
+      #
+      def attributes(*attrs)
+        return @attributes ||= Set.new unless attrs.any?
+
+        Hanami::Utils::Kernel.Array(attrs).each do |attr|
+          if allowed_attribute_name?(attr)
+            define_attr_accessor(attr)
+            self.attributes << attr
+          end
+        end
+      end
+
+      # Define setter/getter methods for attributes.
+      #
+      # @param attr [Symbol] an attribute name
+      #
+      # @since 0.3.1
+      # @api private
+      def define_attr_accessor(attr)
+        attr_accessor(attr)
+      end
+
+      # Check if attr_reader define the given attribute
+      #
+      # @since 0.5.1
+      # @api private
+      def allowed_attribute_name?(name)
+        !instance_methods.include?(name)
+      end
+
+      protected
+
+      # @see Class#inherited
+      def inherited(subclass)
+        subclass.attributes(*attributes)
+        super
+      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|
+        setter = "#{ k }="
+        public_send(setter, v) if respond_to?(setter)
+      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
+
+    # Return the hash of attributes
+    #
+    # @since 0.2.0
+    #
+    # @example
+    #   require 'hanami/model'
+    #   class User
+    #     include Hanami::Entity
+    #     attributes :name
+    #   end
+    #
+    #   user = User.new(id: 23, name: 'Luca')
+    #   user.to_h # => { :id => 23, :name => "Luca" }
+    def to_h
+      Hash[attribute_names.map { |a| [a, read_attribute(a)] }]
+    end
+
+    # Return the set of attribute names
+    #
+    # @since 0.5.1
+    #
+    # @example
+    #   require 'hanami/model'
+    #   class User
+    #     include Hanami::Entity
+    #     attributes :name
+    #   end
+    #
+    #   user = User.new(id: 23, name: 'Luca')
+    #   user.attribute_names # #<Set: {:id, :name}>
+    def attribute_names
+      self.class.attributes
+    end
+
+    # Return the contents of the entity as a nicely formatted string.
+    #
+    # Display all attributes of the entity for inspection (even if they are nil)
+    #
+    # @since 0.5.1
+    #
+    # @example
+    #   require 'hanami/model'
+    #   class User
+    #     include Hanami::Entity
+    #     attributes :name, :email
+    #   end
+    #
+    #   user = User.new(id: 23, name: 'Luca')
+    #   user.inspect # #<User:0x007fa7eefe0b58 @id=nil @name="Luca" @email=nil>
+    def inspect
+      attr_list = attribute_names.inject([]) do |res, name|
+        res << "@#{name}=#{read_attribute(name).inspect}"
+      end.join(' ')
+
+      "#<#{self.class.name}:0x00#{(__id__ << 1).to_s(16)} #{attr_list}>"
+    end
+
+    alias_method :to_s, :inspect
+
+    # Set attributes for entity
+    #
+    # @since 0.2.0
+    #
+    # @example
+    #   require 'hanami/model'
+    #   class User
+    #     include Hanami::Entity
+    #     attributes :name
+    #   end
+    #
+    #   user = User.new(name: 'Lucca')
+    #   user.update(name: 'Luca')
+    #   user.name # => 'Luca'
+    def update(attributes={})
+      attributes.each do |attribute, value|
+        public_send("#{attribute}=", value)
+      end
+    end
+
+    private
+
+    # Return the value by attribute name
+    #
+    # @since 0.5.1
+    # @api private
+    def read_attribute(attr_name)
+      public_send(attr_name)
+    end
+  end
+end

data/lib/hanami/entity/dirty_tracking.rb

@@ -0,0 +1,74 @@
+module Hanami
+  module Entity
+    # Dirty tracking for entities
+    #
+    # @since 0.3.1
+    #
+    # @example Dirty tracking
+    #   require 'hanami/model'
+    #
+    #   class User
+    #     include Hanami::Entity
+    #     include Hanami::Entity::DirtyTracking
+    #
+    #     attributes :name
+    #   end
+    #
+    #   article = Article.new(title: 'Generation P')
+    #   article.changed? # => false
+    #
+    #   article.title = 'Master and Margarita'
+    #   article.changed? # => true
+    #
+    #   article.changed_attributes # => {:title => "Generation P"}
+    module DirtyTracking
+      # Override initialize process.
+      #
+      # @param attributes [Hash] a set of attribute names and values
+      #
+      # @since 0.3.1
+      #
+      # @see Hanami::Entity#initialize
+      def initialize(attributes = {})
+        super
+        @_initial_state = Utils::Hash.new(to_h).deep_dup
+      end
+
+      # Getter for hash of changed attributes.
+      # Return empty hash, if there is no changes
+      # Getter for hash of changed attributes. Value in it is the previous one.
+      #
+      # @return [::Hash] the changed attributes
+      #
+      # @since 0.3.1
+      #
+      # @example
+      #   require 'hanami/model'
+      #
+      #   class Article
+      #     include Hanami::Entity
+      #     include Hanami::Entity::DirtyTracking
+      #
+      #     attributes :title
+      #   end
+      #
+      #   article = Article.new(title: 'The crime and punishment')
+      #   article.changed_attributes # => {}
+      #
+      #   article.title = 'Master and Margarita'
+      #   article.changed_attributes # => {:title => "The crime and punishment"}
+      def changed_attributes
+        Hash[@_initial_state.to_a - to_h.to_a]
+      end
+
+      # Checks if the attributes were changed
+      #
+      # @return [TrueClass, FalseClass] the result of the check
+      #
+      # @since 0.3.1
+      def changed?
+        changed_attributes.any?
+      end
+    end
+  end
+end

data/lib/hanami/model.rb

@@ -1,7 +1,209 @@
-require "hanami/model/version"
+require 'hanami/model/version'
+require 'hanami/entity'
+require 'hanami/entity/dirty_tracking'
+require 'hanami/repository'
+require 'hanami/model/mapper'
+require 'hanami/model/configuration'
+require 'hanami/model/error'
 
 module Hanami
+  # Model
+  #
+  # @since 0.1.0
   module Model
-    # Your code goes here...
+    # Error for non persisted entity
+    # It's raised when we try to update or delete a non persisted entity.
+    #
+    # @since 0.1.0
+    #
+    # @see Hanami::Repository.update
+    class NonPersistedEntityError < Hanami::Model::Error
+    end
+
+    # Error for invalid mapper configuration
+    # It's raised when mapping is not configured correctly
+    #
+    # @since 0.2.0
+    #
+    # @see Hanami::Configuration#mapping
+    class InvalidMappingError < Hanami::Model::Error
+    end
+
+    # Error for invalid raw command syntax
+    #
+    # @since 0.5.0
+    class InvalidCommandError < Hanami::Model::Error
+      def initialize(message = "Invalid command")
+        super
+      end
+    end
+
+    # Error for invalid raw query syntax
+    #
+    # @since 0.3.1
+    class InvalidQueryError < Hanami::Model::Error
+      def initialize(message = "Invalid query")
+        super
+      end
+    end
+
+    include Utils::ClassAttribute
+
+    # Framework configuration
+    #
+    # @since 0.2.0
+    # @api private
+    class_attribute :configuration
+    self.configuration = Configuration.new
+
+    # Configure the framework.
+    # It yields the given block in the context of the configuration
+    #
+    # @param blk [Proc] the configuration block
+    #
+    # @since 0.2.0
+    #
+    # @see Hanami::Model
+    #
+    # @example
+    #   require 'hanami/model'
+    #
+    #   Hanami::Model.configure do
+    #     adapter type: :sql, uri: 'postgres://localhost/database'
+    #
+    #     mapping do
+    #       collection :users do
+    #         entity User
+    #
+    #         attribute :id,   Integer
+    #         attribute :name, String
+    #       end
+    #     end
+    #   end
+    #
+    # Adapter MUST follow the convention in which adapter class is inflection of adapter name
+    # The above example has name :sql, thus derived class will be `Hanami::Model::Adapters::SqlAdapter`
+    def self.configure(&blk)
+      configuration.instance_eval(&blk)
+      self
+    end
+
+    # Load the framework
+    #
+    # @since 0.2.0
+    # @api private
+    def self.load!
+      configuration.load!
+    end
+
+    # Unload the framework
+    #
+    # @since 0.2.0
+    # @api private
+    def self.unload!
+      configuration.unload!
+    end
+
+    # Duplicate Hanami::Model in order to create a new separated instance
+    # of the framework.
+    #
+    # The new instance of the framework will be completely decoupled from the
+    # original. It will inherit the configuration, but all the changes that
+    # happen after the duplication, won't be reflected on the other copies.
+    #
+    # @return [Module] a copy of Hanami::Model
+    #
+    # @since 0.2.0
+    # @api private
+    #
+    # @example Basic usage
+    #   require 'hanami/model'
+    #
+    #   module MyApp
+    #     Model = Hanami::Model.dupe
+    #   end
+    #
+    #   MyApp::Model == Hanami::Model # => false
+    #
+    #   MyApp::Model.configuration ==
+    #     Hanami::Model.configuration # => false
+    #
+    # @example Inheriting configuration
+    #   require 'hanami/model'
+    #
+    #   Hanami::Model.configure do
+    #     adapter type: :sql, uri: 'sqlite3://uri'
+    #   end
+    #
+    #   module MyApp
+    #     Model = Hanami::Model.dupe
+    #   end
+    #
+    #   module MyApi
+    #     Model = Hanami::Model.dupe
+    #     Model.configure do
+    #       adapter type: :sql, uri: 'postgresql://uri'
+    #     end
+    #   end
+    #
+    #   Hanami::Model.configuration.adapter_config.uri # => 'sqlite3://uri'
+    #   MyApp::Model.configuration.adapter_config.uri # => 'sqlite3://uri'
+    #   MyApi::Model.configuration.adapter_config.uri # => 'postgresql://uri'
+    def self.dupe
+      dup.tap do |duplicated|
+        duplicated.configuration = Configuration.new
+      end
+    end
+
+    # Duplicate the framework and generate modules for the target application
+    #
+    # @param mod [Module] the Ruby namespace of the application
+    # @param blk [Proc] an optional block to configure the framework
+    #
+    # @return [Module] a copy of Hanami::Model
+    #
+    # @since 0.2.0
+    #
+    # @see Hanami::Model#dupe
+    # @see Hanami::Model::Configuration
+    #
+    # @example Basic usage
+    #   require 'hanami/model'
+    #
+    #   module MyApp
+    #     Model = Hanami::Model.dupe
+    #   end
+    #
+    #   # It will:
+    #   #
+    #   # 1. Generate MyApp::Model
+    #   # 2. Generate MyApp::Entity
+    #   # 3. Generate MyApp::Repository
+    #
+    #   MyApp::Model      == Hanami::Model # => false
+    #   MyApp::Repository == Hanami::Repository # => false
+    #
+    # @example Block usage
+    #   require 'hanami/model'
+    #
+    #   module MyApp
+    #     Model = Hanami::Model.duplicate(self) do
+    #       adapter type: :memory, uri: 'memory://localhost'
+    #     end
+    #   end
+    #
+    #   Hanami::Model.configuration.adapter_config # => nil
+    #   MyApp::Model.configuration.adapter_config # => #<Hanami::Model::Config::Adapter:0x007ff0ff0244f8 @type=:memory, @uri="memory://localhost", @class_name="MemoryAdapter">
+    def self.duplicate(mod, &blk)
+      dupe.tap do |duplicated|
+        mod.module_eval %{
+          Entity = Hanami::Entity.dup
+          Repository = Hanami::Repository.dup
+        }
+
+        duplicated.configure(&blk) if block_given?
+      end
+    end
+
   end
 end