minimapper 0.0.3 → 0.0.4

data/.gitignore

@@ -9,10 +9,7 @@ _yardoc
 coverage
 doc/
 lib/bundler/man
-pkg
 rdoc
 spec/reports
-test/tmp
-test/version_tmp
 tmp
 *.txt

data/README.md

@@ -2,26 +2,36 @@
 
 # Minimapper
 
-A minimalistic way of separating your models from ORMs like ActiveRecord that allows you to swap out your persistance layer for an in-memory implementation in tests or use different persistance for different models.
+## About
+
+### Introduction
+
+A minimalistic way of separating your models from ORMs like ActiveRecord that allows you to swap out your persistence layer for an in-memory implementation in tests or use different persistence for different models.
 
 If you're following good style you're probably already pushing all knowledge of your ORM down into your models or model-layer classes. This takes it a step further and let's you work with your models without depending on heavy frameworks like rails or needing a database.
 
-Minimapper is a partial [repository-pattern](http://martinfowler.com/eaaCatalog/repository.html) implementation (it implements repositories and data mappers but not critera builders).
+Minimapper is a partial [repository-pattern](http://martinfowler.com/eaaCatalog/repository.html) implementation (it implements repositories and data mappers but not criteria builders).
 
-## Only the most basic API
+### Only the most basic API
 
-This library only implements the most basic persistance API (mostly just CRUD). Any significant additions will be made into separate gems (with names like "minimapper-FOO").
+This library only implements the most basic persistence API (mostly just CRUD). Any significant additions will be made into separate gems (with names like "minimapper-FOO").
 
 The reasons for this are:
+
 * You should be able to depend on the API
 * It should be possible to learn all it does in a short time
 * It should be simple to add an adapter for a new database
 * It should be simple to maintain minimapper
 
-## Compatibility
+### Compatibility
 
 This gem is tested against all major rubies in both 1.8 and 1.9, see [.travis.yml](https://github.com/joakimk/minimapper/blob/master/.travis.yml). For each ruby version, the SQL mappers are tested against SQLite3, PostgreSQL and MySQL.
 
+### Early days
+
+This is not quite intended for production use yet. It's a very small API that is well tested so you could use it in production apps, but there are still some problem areas that hasn't been well explored (for example, how to handle associations). It is probably better to use this than to roll your own project specific solution though.
+
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -40,9 +50,12 @@ Please avoid installing directly from the github repository. Code will be pushed
 
 ## Usage
 
-You can use the mappers directly like this:
+### Basics
+
+You can use the mappers like this (**it's runnable, try copy and pasting it into a ruby file** or [use this gist](https://gist.github.com/3904952)):
 
 ``` ruby
+# minimapper_test.rb
 require "rubygems"
 require "minimapper"
 require "minimapper/entity"
@@ -56,35 +69,31 @@ end
 class UserMapper < Minimapper::Memory
 end
 
-# Creating
+## Creating
 user = User.new(:name => "Joe")
-mapper = UserMapper.new
-mapper.create(user)
+user_mapper = UserMapper.new
+user_mapper.create(user)
 
-# Finding
-user = mapper.find(user.id)
-puts user.name             # -> Joe
-puts mapper.first.name     # -> Joe
+## Finding
+user = user_mapper.find(user.id)
+puts user.name             # => Joe
+puts user_mapper.first.name     # => Joe
 
-# Updating
+## Updating
 user.name = "Joey"
-mapper.update(user)
-puts mapper.first.name    # -> Joey
+user_mapper.update(user)
+puts user_mapper.first.name    # => Joey
 
-# Deleting
+## Deleting
 old_id = user.id
-mapper.delete(user)
-user.id                   # -> nil
-# mapper.find(old_id)     # raises Minimapper::Common::CanNotFindEntity
-mapper.find_by_id(old_id) # -> nil
-
-# Deleting all
-mapper.delete_all
-```
-
-Or though a repository:
-
-``` ruby
+user_mapper.delete(user)
+puts user.id                   # => nil
+puts user_mapper.find_by_id(old_id) # => nil
+# user_mapper.find(old_id)          # raises Minimapper::Common::CanNotFindEntity
+# user_mapper.delete_all
+# user_mapper.delete_by_id(1)
+
+## Using a repository
 require "minimapper/repository"
 
 repository = Minimapper::Repository.build({
@@ -94,10 +103,20 @@ repository = Minimapper::Repository.build({
 
 user = User.new(:name => "Joe")
 repository.users.create(user)
-puts repository.users.find(user.id).name # -> Joe
+puts repository.users.find(user.id).name # => Joe
+
+## Using ActiveModel validations
+user = User.new
+repository.users.create(user)
+puts repository.users.count    # => 0
+puts user.errors.full_messages # Name can't be blank
 ```
 
-## Using the ActiveRecord mapper
+### ActiveRecord
+
+This is not directly runnable like the previous example, it requires ActiveRecord, a database and a users table. Isn't it interesting how much you could do without those things in the previous example? :)
+
+When you do need to use an ORM like ActiveRecord however, it now has the same API as your in-memory persistence (thanks to the [shared tests](https://github.com/joakimk/minimapper/blob/master/spec/support/shared_examples/mapper.rb) which define how a mapper is supposed to behave).
 
 ``` ruby
 require "minimapper/ar"
@@ -116,56 +135,124 @@ mapper = AR::UserMapper.new
 mapper.create(user)
 ```
 
-## Using ActiveModel validation
+### Custom queries
+
+You can write custom queries like this:
 
 ``` ruby
-user = User.new
+# Memory implementation
+module Memory
+  class ProjectMapper < Minimapper::Memory
+    def waiting_for_review
+      all.find_all { |p| p.waiting_for_review }.sort_by(&:id).reverse
+    end
+  end
+end
 
-mapper = UserMapper.new
-mapper.create(user)
+# ActiveRecord implementation
+module AR
+  class ProjectMapper < Minimapper::AR
+    def waiting_for_review
+      record_klass.where(waiting_for_review: true).order("id DESC").map do |record|
+        entity_for(record)
+      end
+    end
+  end
+end
+```
 
-mapper.count              # -> 0
-user.errors.full_messages # Name can't be blank
+And then use it like this:
+
+``` ruby
+# repository = Minimapper::Repository.build(...)
+repository.projects.waiting_for_review.each do |project|
+  puts project.name
+end
 ```
 
-## Implementing custom queries
+It gets simpler to maintain if you use shared tests to test both implementations. For inspiration, see the [shared tests](https://github.com/joakimk/minimapper/blob/master/spec/support/shared_examples/mapper.rb) used to test minimapper.
+
+### Typed attributes
+
+``` ruby
+# Supported types: Integer, DateTime
+# TODO: Will probably not support more types, but instead provide a way to add custom conversions.
+
+class User < Minimapper::Entity
+  attributes [ :profile_id, Integer ]
+end
+
+User.new(:profile_id => "10").profile_id      # => 10
+User.new(:profile_id => " 10 ").profile_id    # => 10
+User.new(:profile_id => " ").profile_id       # => nil
+User.new(:profile_id => "foobar").profile_id  # => nil
+```
 
-*todo* show how, talk about shared examples.
+### Adding a new mapper
 
-## Implementing another mapper
+If you where to add a [Mongoid](http://mongoid.org/en/mongoid/index.html) mapper:
 
-*todo*: how to use the shared examples
+1. Start by copying *spec/ar_spec.rb* to *spec/mongoid_spec.rb* and adapt it for Mongoid.
+2. Add any setup code needed in *spec/support/database_setup.rb*.
+3. Get the [shared tests](https://github.com/joakimk/minimapper/blob/master/spec/support/shared_examples/mapper.rb) to pass for *spec/mongoid_spec.rb*.
+4. Ensure all other tests pass.
+5. Send a pull request.
+6. As soon as it can be made to work in travis in all ruby versions that apply (in Mongoid's case that is only the 1.9 rubies), I'll merge it in.
 
 ## Inspiration
 
+### People
+
 Jason Roelofs:
+
 * [Designing a Rails App](http://jasonroelofs.com/2012/05/29/designing-a-rails-app-part-1/) (find the whole series of posts)
 
 Robert "Uncle Bob" Martin:
+
 * [Architecture: The Lost Years](http://www.confreaks.com/videos/759-rubymidwest2011-keynote-architecture-the-lost-years)
 * [The Clean Architecture](http://blog.8thlight.com/uncle-bob/2012/08/13/the-clean-architecture.html)
 
-## Apps using minimapper
+### Apps
 
 * The deploy status app that minimapper was extracted from: [https://github.com/joakimk/deployer](https://github.com/joakimk/deployer)
 
-## Running the tests
+## Contributing
+
+### Running the tests
 
 You need mysql and postgres installed (but they do not have to be running) to be able to run bundle. The sql-mapper tests use sqlite3 by default.
 
     bundle
     rake
 
-## Contributing
+### Steps
 
 0. Read "Only the most basic API" above
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Don't forget to write test
+4. Don't forget to write tests
 5. Push to the branch (`git push origin my-new-feature`)
 6. Create new Pull Request
 
+## Todo
+
+### Next
+
+* Add some way to extend type conversions to keep that part of minimapper small.
+* Extract entity and model class lookup code from the ar-mapper and reuse it in the memory mapper.
+* Change the memory mapper to store entity attributes, not entity instances.
+  - Unless this makes it difficult to handle associated data.
+* Make Minimapper::Entity a module so you won't have to inherit from it.
+* Make using Minimapper::Entity optional by providing shared examples of the behavior required by the mappers. Test the mappers with an object implementing only this behavior.
+
+### Ideas
+
+I won't implement anything that isn't actually used. But here are some ideas for things that might make it into minimapper someday if there is a need for it.
+
+* Provide a hook to convert attributes between entities and the backing models (when your entity attributes and db-schema isn't a one-to-one match).
+* Copy validation errors back from the mapper to the entity (for example if you do uniqueness validation in a backing ActiveRecord-model).
+
 ## Credits and license
 
 By [Joakim Kolsjö](https://twitter.com/joakimk) under the MIT license:

data/lib/minimapper/entity/convert.rb

@@ -0,0 +1,41 @@
+require 'active_support/core_ext'
+
+module Minimapper
+  class Entity
+    class Convert
+      def initialize(value)
+        @value = value
+      end
+
+      def to(type)
+        return if value.blank?
+        return value unless value.is_a?(String)
+
+        case type.to_s
+        when "Integer"
+          to_integer
+        when "DateTime"
+          to_date_time
+        else
+          value
+        end
+      end
+
+      private
+
+      def to_integer
+        if value =~ /[0-9]/
+          value.to_i
+        else
+          nil
+        end
+      end
+
+      def to_date_time
+        DateTime.parse(value) rescue nil
+      end
+
+      attr_reader :value
+    end
+  end
+end

data/lib/minimapper/entity.rb

@@ -6,6 +6,7 @@
 #
 # This class also does some things needed for it to work well with rails.
 require 'informal'
+require 'minimapper/entity/convert'
 
 module Minimapper
   class Entity
@@ -13,11 +14,18 @@ module Minimapper
 
     def self.attributes(*list)
       list.each do |attribute|
+        type = nil
+
+        if attribute.is_a?(Array)
+          attribute, type = attribute
+        end
+
         define_method(attribute) do
           instance_variable_get("@#{attribute}")
         end
 
         define_method("#{attribute}=") do |value|
+          value = Convert.new(value).to(type)
           instance_variable_set("@#{attribute}", value)
           @attributes[attribute] = value
         end
@@ -37,7 +45,7 @@ module Minimapper
       id
     end
 
-    attributes :id, :created_at, :updated_at
+    attributes [ :id, Integer ], [ :created_at, DateTime ], [ :updated_at, DateTime ]
 
     attr_reader :attributes
   end

data/lib/minimapper/version.rb

@@ -1,3 +1,3 @@
 module Minimapper
-  VERSION = "0.0.3"
+  VERSION = "0.0.4"
 end

data/spec/support/shared_examples/mapper.rb

@@ -1,7 +1,7 @@
 shared_examples :mapper do
   # expects repository and entity_klass to be defined
 
-  describe "create" do
+  describe "#create" do
     it "sets an id on the entity" do
       entity1 = build_valid_entity
       entity1.id.should be_nil
@@ -32,7 +32,7 @@ shared_examples :mapper do
     end
   end
 
-  describe "find" do
+  describe "#find" do
     it "returns an entity matching the id" do
       entity = build_valid_entity
       repository.create(entity)
@@ -55,12 +55,12 @@ shared_examples :mapper do
       repository.find(entity.id).object_id.should_not == repository.find(entity.id).object_id
     end
 
-    it "fails when the an entity can not be found" do
+    it "fails when an entity can not be found" do
       lambda { repository.find(-1) }.should raise_error(Minimapper::Common::CanNotFindEntity)
     end
   end
 
-  describe "find_by_id" do
+  describe "#find_by_id" do
     it "returns an entity matching the id" do
       entity = build_valid_entity
       repository.create(entity)
@@ -83,12 +83,12 @@ shared_examples :mapper do
       repository.find_by_id(entity.id).object_id.should_not == repository.find_by_id(entity.id).object_id
     end
 
-    it "returns nil when the an entity can not be found" do
+    it "returns nil when an entity can not be found" do
       repository.find_by_id(-1).should be_nil
     end
   end
 
-  describe "all" do
+  describe "#all" do
     it "returns all entities in undefined order" do
       first_created_entity = build_valid_entity
       second_created_entity = build_valid_entity
@@ -108,7 +108,7 @@ shared_examples :mapper do
     end
   end
 
-  describe "first" do
+  describe "#first" do
     it "returns the first entity" do
       first_created_entity = build_valid_entity
       repository.create(first_created_entity)
@@ -129,7 +129,7 @@ shared_examples :mapper do
     end
   end
 
-  describe "last" do
+  describe "#last" do
     it "returns the last entity" do
       last_created_entity = build_valid_entity
       repository.create(build_valid_entity)
@@ -150,7 +150,7 @@ shared_examples :mapper do
     end
   end
 
-  describe "count" do
+  describe "#count" do
     it "returns the number of entities" do
       repository.create(build_valid_entity)
       repository.create(build_valid_entity)
@@ -158,7 +158,7 @@ shared_examples :mapper do
     end
   end
 
-  describe "update" do
+  describe "#update" do
     it "updates" do
       entity = build_valid_entity
       repository.create(entity)
@@ -199,7 +199,7 @@ shared_examples :mapper do
     end
   end
 
-  describe "delete" do
+  describe "#delete" do
     it "removes the entity" do
       entity = build_valid_entity
       removed_entity_id = entity.id
@@ -229,7 +229,7 @@ shared_examples :mapper do
     end
   end
 
-  describe "delete_by_id" do
+  describe "#delete_by_id" do
     it "removes the entity" do
       entity = build_valid_entity
       repository.create(entity)
@@ -239,12 +239,12 @@ shared_examples :mapper do
       repository.first.id.should_not == entity.id
     end
 
-    it "fails when the an entity can not be found" do
+    it "fails when an entity can not be found" do
       lambda { repository.delete_by_id(-1) }.should raise_error(Minimapper::Common::CanNotFindEntity)
     end
   end
 
-  describe "delete_all" do
+  describe "#delete_all" do
     it "empties the repository" do
       repository.create(build_valid_entity)
       repository.delete_all

data/unit/entity/convert_spec.rb

@@ -0,0 +1,23 @@
+require 'minimapper/entity/convert'
+
+describe Minimapper::Entity::Convert do
+  it "converts strings into integers" do
+    described_class.new('10').to(Integer).should == 10
+    described_class.new(' 10 ').to(Integer).should == 10
+  end
+
+  it "converts datetime strings into datetimes" do
+    described_class.new('2012-01-01 20:57').to(DateTime).should == DateTime.new(2012, 01, 01, 20, 57)
+  end
+
+  it "make it nil when it can't convert" do
+    described_class.new(' ').to(Integer).should be_nil
+    described_class.new(' ').to(DateTime).should be_nil
+    described_class.new('garbage').to(Integer).should be_nil
+    described_class.new('garbage').to(DateTime).should be_nil
+  end
+
+  it "returns the value as-is when it does not know how to convert it" do
+    described_class.new('foobar').to(Kernel).should == 'foobar'
+  end
+end

data/unit/entity_spec.rb

@@ -13,6 +13,26 @@ describe Minimapper::Entity do
     base.updated_at = time
     base.updated_at.should == time
   end
+
+  it "converts typed attributes" do
+    base = described_class.new
+    base.id = "10"
+    base.id.should == 10
+  end
+end
+
+class TestUser < Minimapper::Entity
+  attributes :name
+end
+
+describe Minimapper::Entity, "attributes without type" do
+  it "can be set and get with anything" do
+    user = TestUser.new
+    user.name = "Hello"
+    user.name.should == "Hello"
+    user.name = 5
+    user.name.should == 5
+  end
 end
 
 describe Minimapper::Entity, "attributes" do

metadata

@@ -1,61 +1,46 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: minimapper
-version: !ruby/object:Gem::Version 
-  hash: 25
+version: !ruby/object:Gem::Version
+  version: 0.0.4
   prerelease: 
-  segments: 
-  - 0
-  - 0
-  - 3
-  version: 0.0.3
 platform: ruby
-authors: 
-- "Joakim Kolsj\xC3\xB6"
+authors:
+- Joakim Kolsjö
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2012-10-14 00:00:00 +02:00
-default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2012-11-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: informal
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: &70301509547800 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: rake
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  version_requirements: *70301509547800
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &70301509545740 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
-  version_requirements: *id002
-description: A minimalistic way of separating your models from ORMs like ActiveRecord (by implementing the repository pattern)
-email: 
+  prerelease: false
+  version_requirements: *70301509545740
+description: A minimalistic way of separating your models from ORMs like ActiveRecord
+  (by implementing the repository pattern)
+email:
 - joakim.kolsjo@gmail.com
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - .gitignore
 - .rspec
 - .rvmrc
@@ -67,6 +52,7 @@ files:
 - lib/minimapper/ar.rb
 - lib/minimapper/common.rb
 - lib/minimapper/entity.rb
+- lib/minimapper/entity/convert.rb
 - lib/minimapper/memory.rb
 - lib/minimapper/repository.rb
 - lib/minimapper/version.rb
@@ -77,46 +63,39 @@ files:
 - spec/spec_helper.rb
 - spec/support/database_setup.rb
 - spec/support/shared_examples/mapper.rb
+- unit/entity/convert_spec.rb
 - unit/entity_spec.rb
 - unit/memory_spec.rb
 - unit/repository_spec.rb
 - unit/spec_helper.rb
-has_rdoc: true
-homepage: ""
+homepage: ''
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.5.3
+rubygems_version: 1.8.5
 signing_key: 
 specification_version: 3
-summary: A minimalistic way of separating your models from ORMs like ActiveRecord (by implementing the repository pattern)
-test_files: 
+summary: A minimalistic way of separating your models from ORMs like ActiveRecord
+  (by implementing the repository pattern)
+test_files:
 - spec/ar_spec.rb
 - spec/spec_helper.rb
 - spec/support/database_setup.rb
 - spec/support/shared_examples/mapper.rb
+has_rdoc: