rmodel 0.4.0.dev → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bfd28def37943474200080f54ed361a5a7ff742c
-  data.tar.gz: 09936b026f1c1d5b232cafe8ccce68665726a0eb
+  metadata.gz: f1cabda8d90f129c91be844839240e35c667e866
+  data.tar.gz: 63d948217cbee488f8e93be4ef575ff838d9cabf
 SHA512:
-  metadata.gz: d7857a21445b42cab34bb02205949cbb3204cd245fd59508204cfca4cfa6c74753f698d1d5ce56596559dc03dbbe5abd58ab6092ca486332b426c9e887d6fa94
-  data.tar.gz: fd441d8e206b3d21eb0cc636c6c178e319f7fe05114b5924e44d0440ff1f6b572735642e4080a255729580a21a6353b960ef7f2520664f62def8d8632ba0273f
+  metadata.gz: 1eb0276bbb918397139567f1a3c081fa3de431eff3cbffb406f2aa0e524c4d862082d5d5155bad31ce2188d5cb66ea300272a3657edc4d8f1e3debbc54f03628
+  data.tar.gz: 85fa52294b5ee0e0cbed4fb23a443f995ef442114e9ec67738aabbf21b8d437506af32834b26de7fa64f9ff217096577ca4dea48972fb8afd9f61a9bbf691dcb

data/.gitignore

@@ -21,3 +21,4 @@ tmp
 *.a
 mkmf.log
 rmodel_test.sqlite3
+run.rb

data/.rubocop.yml

@@ -0,0 +1,4 @@
+Style/Documentation:
+  Enabled: false
+Style/AndOr:
+  Enabled: false

data/.travis.yml

@@ -1,8 +1,9 @@
 language: ruby
-script: rspec
+script: bundle exec rubocop -D && bundle exec rspec
 rvm:
   - 2.0.0
-  - 2.1.7
-  - 2.2.3
+  - 2.1.8
+  - 2.2.4
+  - 2.3.0
 services:
   - mongodb

data/README.md

@@ -20,6 +20,7 @@ The main thoughts of it are:
 
 * let you models be simple and independent of the persistent layer,
 * be able to switch the persistent layer at any moment,
+* be able to use different databases for different entities,
 * keep the simplicity of the Active Record pattern by default,
 * be able to implement any type of persistence: SQL, NoSQL, files, HTTP etc.
 
@@ -27,13 +28,13 @@ It consists of 3 major components:
 
 1. **Entities**; ex.: User, Order etc.
 2. **Repositories**, which are used to fetch, save and delete entities; ex.: UserRepository, OrderRepository
-3. **Factories**, which play the role of mappers.
+3. **Mappers**, which are used to serialize/deserialize entities to/from database tuples.
 
 Basic implemented features:
 
-1. CRUD operations: `find`, `insert`, `update`, `remove`;
-2. Scopes: `userRepository.query.recent.sorted`
-3. Query-based operations: `userRepository.query.recent.remove`
+1. CRUD operations: `find`, `insert`, `update`, `destroy`;
+2. Scopes: `repo.fetch.recent.sorted`;
+3. Query-based operations: `repo.fetch.recent.delete_all`.
 
 ## Installation
 
@@ -54,80 +55,78 @@ Or install it yourself as:
 Let's define an entity
 
 ```ruby
-class User
-  attr_accessor :id, :name, :email
-end
+User = Struct.new(:id, :name, :email)
 ```
 
-As you see it's a plain ruby class with attributes. It must have either the zero-argument `#initialize` method or no `#initialize` at all.
+As you see it's a PORO (Plain Old Ruby Objects), a class which inherits from nothing.
+It must have either the zero-argument `#initialize` method or no `#initialize` at all.
 
 Of course we need a repository to save users.
 
 ```ruby
 require 'rmodel' # dont forget to require the gem
 
-class User
-  attr_accessor :id, :name, :email
-end
-
-class UserRepository < Rmodel::Mongo::Repository
-end
+User = Struct.new(:id, :name, :email)
 
-userRepository = UserRepository.new
-```
-The code above raises the exception *Client driver is not setup (ArgumentError)*. UserRepository derives from Rmodel::Mongo::Repository, which uses the ruby mongo driver to access the database. We must provide the appropriate connection options. To do this we use the following code:
+DB = Mongo::Client.new(['localhost'], database: 'test')
+source = Rmodel::Mongo::Source.new(DB, :users)
 
-```ruby
-require 'rmodel'
+mapper = Rmodel::Mongo::Mapper.new(User).define_attributes(:name, :email)
 
-Rmodel.setup do
-  client :default, { hosts: [ 'localhost' ], database: 'test' }
-end
+user_repository = Rmodel::Repository.new(source, mapper)
 ```
 
-The `:default` client is used by every repository that doesn't specify it's client explicitly.
+Here 3 main components of Rmodel are described:
 
-Run the code again and get another error *Factory can not be guessed (ArgumentError)*. The factory is used to convert the array of database tuples (hashes) to the array of User objects.
-
-```ruby
-class UserRepository < Rmodel::Mongo::Repository
-  simple_factory User, :name, :email
-end
-```
-
-The `simple_factory` class macro says that every database tuple will be straightforwardly converted to an instance of User with  attributes :id, :name and :email. There is no need to specify :id, because it's required.
+1. `source` points to the `users` collection withing MongoDB.
+2. `mapper` is an example of a mapper class instance. It's methods
+`#initialize` and `define_attributes` are used to declare the mapping rules
+(User -> Hash and Hash -> User). It's a rather easy mapper. Every database
+tuple is straightforwardly converted to an instance of User with  attributes
+:id, :name and :email. There is no need to specify :id.
+3. Finally, `user_repository` takes `source` and `mapper` and makes all magic
+about fetching and saving users from/to the database.
 
 ### CRUD
 
 Let's create and insert several users.
 
 ```ruby
-john = User.new('John', 'john@example.com')
-bill = User.new('Bill', 'bill@example.com')
-bob = User.new('Bob', 'bob@example.com')
+john = User.new(nil, 'John', 'john@example.com')
+bill = User.new(nil, 'Bill', 'bill@example.com')
+bob = User.new(nil, 'Bob', 'bob@example.com')
 
-userRepository.insert(john)
-userRepository.insert(bill)
-userRepository.insert(bob)
+user_repository.insert(john)
+user_repository.insert(bill)
+user_repository.insert(bob)
 ```
 
-Now you can check you `test` database. There are 3 new users there. Print the `john`. As you can see it's got the `@id`.
+Now you can check you `test` database. There must be 3 new users there. Print
+the `john`. As you can see it's got the `@id`.
 
 ```ruby
 p john
-#<User:0x00... @name="John", @email="john@example.com", @id=BSON::ObjectId('562a...')>
+#<struct User id=BSON::ObjectId('...'), name="John", email="john@example.com">
 ```
 
-Let's update John and remove Bob.
+Let's update John and destroy Bob.
 
 ```ruby
 john.name = 'John Smith'
-userRepository.update(john)
+user_repository.update(john)
+
+user_repository.destroy(bob)
+
+p user_repository.find(john.id) # <struct User id=BSON::ObjectId('...'), ...>
+p user_repository.find(bob.id) # nil
+```
 
-userRepository.remove(bob)
+The `insert` method is polysemantic. All options below are valid.
 
-p userRepository.find(john.id) # #<User:0x000000037237d0 @name="John Smith" ... >
-p userRepository.find(bob.id) # nil
+```ruby
+repo.insert(object)
+repo.insert([ object1, object2, object3 ])
+repo.insert(object1, object2, object3)
 ```
 
 ### Scopes
@@ -135,9 +134,7 @@ p userRepository.find(bob.id) # nil
 Scopes are defined inside the repository.
 
 ```ruby
-class UserRepository < Rmodel::Mongo::Repository
-  simple_factory User, :name, :email
-
+class UserRepository < Rmodel::Repository
   scope :have_email do
     where(email: { '$exists' => true })
   end
@@ -147,24 +144,38 @@ class UserRepository < Rmodel::Mongo::Repository
   end
 end
 
-userRepository.query.start_with('b').to_a
+repo = UserRepository.new(source, mapper)
+
+p repo.fetch.start_with('b').to_a
 ```
 
 Of course you can chain scopes.
 
 ```ruby
-userRepository.query.start_with('b').have_email
+p repo.fetch.start_with('b').have_email.to_a
 ```
 
-The result of the scope is Enumerable, so you can apply the #each method and others (map, select etc).
+The result of the scope is Enumerable, so you can apply the #each method and
+others (map, select etc).
 
-Inside the scopes you can use any methods supported by the driver (database client). In our case we use Origin (https://github.com/mongoid/origin) as a query builder for mongo.
+Inside the scopes you can use any methods supported by the driver (database
+connection). In our case we use Origin (https://github.com/mongoid/origin) as
+a query builder for mongo.
 
 Also it's possible to use scopes to run the multi-row operations.
 
 ```ruby
-userRepository.query.have_email.remove
-p userRepository.query.count # 0
+repo.fetch.have_email.delete_all # simply run the operation against the database
+repo.fetch.have_email.destroy_all # extract users and run repo.destroy for the each one
+p repo.fetch.count # 0
+```
+
+If you have no scopes then just call
+
+```ruby
+repo.all
+repo.delete_all
+repo.destroy_all
 ```
 
 ### Timestamps
@@ -172,14 +183,20 @@ p userRepository.query.count # 0
 Here is an example how to track the time, when the entity was created and updated.
 
 ```ruby
+require 'rmodel'
+
+DB = Mongo::Client.new(['localhost'], database: 'test')
+source = Rmodel::Mongo::Source.new(DB, :things)
+
 class Thing
   attr_accessor :id, :name, :created_at, :updated_at
 end
 
-class ThingRepository < Rmodel::Mongo::Repository
-  simple_factory Thing, :name, :created_at, :updated_at
-end
-repo = ThingRepository.new
+mapper = Rmodel::Mongo::Mapper.new(Thing)
+                              .define_attribute(:name)
+                              .define_timestamps
+
+repo = Rmodel::Repository.new(source, mapper)
 
 thing = Thing.new
 thing.name = 'chair'
@@ -208,28 +225,6 @@ If the object has no not-nil id then it gets inserted. Otherwise it gets updated
 The `find!` method works like the simple `find`
 , but instead of nil it raises the Rmodel::NotFound error.
 
-### Advanced creation of repository
-
-```ruby
-require 'rmodel'
-
-class Thing
-  attr_accessor :id, :name
-end
-
-class ThingRepository < Rmodel::Mongo::Repository
-end
-
-client = Mongo::Client.new([ 'localhost:27017' ], database: 'test')
-collection = :things
-factory = Rmodel::Mongo::SimpleFactory.new(Thing, :name)
-
-repo = ThingRepository.new(client, collection, factory)
-repo.find(1)
-```
-
-The `factory` is an object, which has 2 methods: `#fromHash(hash)` and `#toHash(object)`.
-
 ### SQL repository
 
 SQL amenities is based on the Sequel gem (http://sequel.jeremyevans.net/).
@@ -242,50 +237,38 @@ Below you can the the example how to setup Rmodel for any supported SQL database
 ```ruby
 require 'rmodel'
 
-Rmodel.setup do
-  client :default, { adapter: 'sqlite', database: 'rmodel_test.sqlite3' }
-end
+DB = Sequel.connect(adapter: 'sqlite', database: 'rmodel_test.sqlite3')
+source = Rmodel::Sequel::Source.new(DB, :things)
 
-client = Rmodel.setup.establish_sequel_client(:default)
-client.drop_table? :things
-client.create_table :things do
+DB.drop_table? :things
+DB.create_table :things do
   primary_key :id
   String :name
   Float :price
 end
 
-class Thing
-  attr_accessor :id, :name, :price
-
-  def initialize(name = nil, price = nil)
-    self.name = name
-    self.price = price
-  end
-end
-
-class ThingRepository < Rmodel::Sequel::Repository
-  simple_factory Thing, :name, :price
+Thing = Struct.new :id, :name, :price
+mapper = Rmodel::Sequel::Mapper.new(Thing).define_attributes(:name, :price)
 
+class ThingRepository < Rmodel::Repository
   scope :worth_more_than do |amount|
     # use Sequel dataset filtering http://sequel.jeremyevans.net/rdoc/files/doc/dataset_filtering_rdoc.html
     where { price >= amount }
   end
 end
 
-repo = ThingRepository.new
-repo.insert Thing.new('iPod', 200)
-repo.insert Thing.new('iPhone', 300)
-repo.insert Thing.new('iPad', 500)
+repo = ThingRepository.new(source, mapper)
+repo.insert Thing.new(nil, 'iPod', 200)
+repo.insert Thing.new(nil, 'iPhone', 300)
+repo.insert Thing.new(nil, 'iPad', 500)
 
-p repo.query.count # 3
-p repo.query.worth_more_than(400).count # 1
-p repo.query.worth_more_than(400).to_sql
+p repo.fetch.count # 3
+p repo.fetch.worth_more_than(400).count # 1
 ```
 
 ### Embedded documents in MongoDB
 
-Let's assume that we have the `flats` collection and every documents reveals
-the following structure.
+Let's assume that we have the `flats` collection and every documents reveals the following structure.
 
 ```js
 > db.flats.findOne()
@@ -325,66 +308,49 @@ the following structure.
 }
 ```
 
-We need a rather complicated factory to build such object. Here is the example how we can map nested embedded documents with SimpleFactory.
+We need a rather complicated mapper to build such object. Here is the example how we can map nested embedded documents with Rmodel::Mongo::Mapper.
+
+The idea is easy:
+* define primitive mappers,
+* use them in declaration of composite mappers.
 
 ```ruby
-Owner = Struct.new(:id, :first_name, :last_name)
-Room = Struct.new(:id, :name, :square, :bed)
+require 'rmodel'
+
+DB = Mongo::Client.new(['localhost'], database: 'test')
+source = Rmodel::Mongo::Source.new(DB, :flats)
+
+Owner = Struct.new(:first_name, :last_name)
+Bed = Struct.new(:type)
+Room = Struct.new(:name, :square, :bed)
 Flat = Struct.new(:id, :address, :rooms, :owner)
-Bed = Struct.new(:id, :type)
-
-class FlatRepository < Rmodel::Mongo::Repository
-  simple_factory Flat, :address do
-    embeds_many :rooms, simple_factory(Room, :name, :square) do
-      embeds_one :bed, simple_factory(Bed, :type)
-    end
-    embeds_one :owner, simple_factory(Owner, :first_name, :last_name)
-  end
-end
-```
 
-1. The row `simple_factory Flat, :address` create a factory for Flat.
-  * It takes a block, where the detailed declaration goes.
-  * `embeds_many` and `embeds_one` are methods of the created factory.
-2. The row `embeds_many :rooms, simple_factory(Room, :name, :square)` describes  the embedded array of rooms within the flat.
-  * The first argument `:room` is the name of the flat attribute (`flat.rooms`).
-  * The second argument is another simple factory for the Room class.
-  * The row `embeds_many :rooms` takes the block, that described nested embedded documents for the Room factory.
-3. etc.
+owner_mapper = Rmodel::Mongo::Mapper.new(Owner)
+                                    .define_attributes(:first_name, :last_name)
 
-The full example.
+bed_mapper = Rmodel::Mongo::Mapper.new(Bed).define_attribute(:type)
 
-```ruby
-require 'rmodel'
+room_mapper = Rmodel::Mongo::Mapper.new(Room)
+                                   .define_attributes(:name, :square)
+                                   .define_attribute(:bed, bed_mapper)
 
-Rmodel.setup do
-  client :default, { hosts: [ 'localhost'], database: 'test' }
-end
+rooms_mapper = Rmodel::ArrayMapper.new(room_mapper)
+flat_mapper =  Rmodel::Mongo::Mapper.new(Flat)
+                                    .define_attribute(:address)
+                                    .define_attribute(:rooms, rooms_mapper)
+                                    .define_attribute(:owner, owner_mapper)
 
-Owner = Struct.new(:id, :first_name, :last_name)
-Room = Struct.new(:id, :name, :square, :bed)
-Flat = Struct.new(:id, :address, :rooms, :owner)
-Bed = Struct.new(:id, :type)
-
-class FlatRepository < Rmodel::Mongo::Repository
-  simple_factory Flat, :address do
-    embeds_many :rooms, simple_factory(Room, :name, :square) do
-      embeds_one :bed, simple_factory(Bed, :type)
-    end
-    embeds_one :owner, simple_factory(Owner, :first_name, :last_name)
-  end
-end
-repo = FlatRepository.new
-repo.query.remove
+repo = Rmodel::Repository.new(source, flat_mapper)
+repo.delete_all
 
 flat = Flat.new
 flat.address = 'Googleplex, Mountain View, California, U.S'
 flat.rooms = [
-  Room.new(nil, 'dining room', 150),
-  Room.new(nil, 'sleeping room #1', 50, Bed.new(nil, 'single')),
-  Room.new(nil, 'sleeping room #2', 20, Bed.new(nil, 'king-size'))
+  Room.new('dining room', 150),
+  Room.new('sleeping room #1', 50, Bed.new('single')),
+  Room.new('sleeping room #2', 20, Bed.new('king-size'))
 ]
-flat.owner = Owner.new(nil, 'John', 'Doe')
+flat.owner = Owner.new('John', 'Doe')
 
 repo.insert(flat)
 p repo.find(flat.id)