Datamappify

Overview

Compose and manage domain logic and data persistence separately and intelligently, Datamappify is loosely based on the Repository Pattern and Entity Aggregation.

Datamappify is built using Virtus and existing ORMs (ActiveRecord and Sequel, etc). The design goal is to utilise the powerfulness of existing ORMs as well as to separate domain logic (model behaviour) from data persistence.

My motivation for creating Datamappify is to hide the complexity of dealing with data in different data sources including the ones from external web services. Features like lazy loading and dirty tracking are designed to enhance the usability of dealing with web services.

Datamappify consists of three components:

• Entity contains models behaviour, think an ActiveRecord model with the persistence specifics removed.
• Repository is responsible for data retrieval and persistence, e.g. find, save and destroy, etc.
• Data as the name suggests, holds your model data. It contains ORM objects (ActiveRecord and Sequel, etc).

Note: Datamappify is NOT affiliated with the Datamapper project.

Built-in ORMs for Persistence

You may implement your own data provider and criterias, but Datamappify comes with build-in support for the following ORMS:

• ActiveRecord
• Sequel

Installation

Add this line to your application's Gemfile:

gem 'datamappify'

Usage

Entity

Entity uses Virtus DSL for defining attributes and ActiveModel::Validations DSL for validations.

class User
  include Datamappify::Entity

  attribute :first_name,     String
  attribute :last_name,      String
  attribute :age,            Integer
  attribute :passport,       String
  attribute :driver_license, String
  attribute :health_care,    String

  validates :first_name, :presence => true,
                         :length   => { :minimum => 2 }
  validates :passport,   :presence => true,
                         :length   => { :minimum => 8 }

  def full_name
    "#{first_name} #{last_name}"
  end
end

Lazy loading

Datamappify supports attribute lazy loading via the Lazy module.

class User
  include Datamappify::Entity
  include Datamappify::Lazy
end

When an entity is lazy loaded, only attributes from the default source will be loaded. Other attributes will only be loaded once they are called. This is especially useful if some of your data sources are external services.

Repository

Map entity attributes to DB columns - better yet, you can even map attributes to different ORMs!

class UserRepository
  include Datamappify::Repository

  # specify the entity class
  for_entity User

  # specify the default data provider for unmapped attributes
  default_provider :ActiveRecord

  # specify any attributes that need to be mapped
  #
  # for example:
  #   - 'last_name' is mapped to the 'User' ActiveRecord class and its 'surname' attribute
  #   - 'driver_license' is mapped to the 'UserDriverLicense' ActiveRecord class and its 'number' attribute
  #   - 'passport' is mapped to the 'UserPassport' Sequel class and its 'number' attribute
  #   - attributes not specified here are mapped automatically to 'ActiveRecord::User'
  map_attribute :last_name,      'ActiveRecord::User#surname'
  map_attribute :driver_license, 'ActiveRecord::UserDriverLicense#number'
  map_attribute :passport,       'Sequel::UserPassport#number'
  map_attribute :health_care,    'Sequel::UserHealthCare#number'
end

Retrieving entities

Pass in an id.

user  = UserRepository.find(1)

Checking if an entity exists in the repository

Pass in an entity.

UserRepository.exists?(user)

Saving/updating entities

Pass in an entity.

There is also save! that raises Datamappify::Data::EntityNotSaved.

UserRepository.save(user)

Datamappify supports attribute dirty tracking - only dirty attributes will be saved.

Destroying an entity

Pass in an entity.

There is also destroy! that raises Datamappify::Data::EntityNotDestroyed.

Note that due to the attributes mapping, any data found in mapped ActiveRecord objects are not touched.

UserRepository.destroy(user)

Callbacks

Datamappify supports the following callbacks via Hooks:

• before_create
• before_update
• before_save
• before_destroy
• after_create
• after_update
• after_save
• after_destroy

Callbacks are defined in repositories, and they have access to the entity. Example:

class UserRepository
  include Datamappify::Repository

  before_create :make_me_admin
  before_create :make_me_awesome
  after_save    :make_me_smile

  private

  def make_me_admin(entity)
    # ...
  end

  def make_me_awesome(entity)
    # ...
  end

  def make_me_smile(entity)
    # ...
  end

  # ...
end

Note: Returning either nil or false from the callback will cancel all subsequent callbacks (and the action itself, it it's a before_ callback).

Changelog

Refer to CHANGELOG.

Todo

• Authoritative source.
• Enforce attribute type casting.
• Support for configurable primary keys and foreign keys.

Similar Projects

• Curator
• Edr
• Minimapper

Credits

• Fred Wu - author.
• James Ladd for reviewing the code and giving advice on architectural decisions.
• Locomote - where Datamappify is built and being tested in product development.

License

Licensed under MIT