mongodb 0.0.1 → 0.0.2

data/readme.md

@@ -1,9 +1,264 @@
-# Ruby ODM for MongoDB
+Object Model & Ruby driver enhancements for MongoDB.
 
-Not finished, in development.
+1. Driver enchancements & Migrations.
+2. Persistence for any Ruby object.
+3. Object Model (callbacks, validations, mass-assignment, finders, ...).
 
-- Very small.
-- Schema-less, dynamic.
+Lower layers are independent from upper, use only what You need.
+
+# MongoDB driver enhancements
+
+MongoDB itself is very powerful, flexible and simple tool, but the API of the Ruby driver is a little complicated.
+These enhancements alter the driver's API and made it more simple and intuitive.
+
+- Makes API of mongo-ruby-driver friendly & handy.
+- No extra abstraction or complexities introduced, all things are exactly the same as in MongoDB.
+- 100% backward compatibility with original driver API (if not - it's a bug, report it please)
+
+``` ruby
+require 'mongodb/driver'
+
+# Changing some defaults.
+Mongo.defaults.merge! symbolize: true, multi: true, safe: true
+
+# Connection & db.
+connection = Mongo::Connection.new
+db = connection.db 'default_test'
+db.units.drop
+
+# Collection shortcuts.
+db.some_collection
+
+# Create.
+zeratul =  {name: 'Zeratul',  stats: {attack: 85, life: 300, shield: 100}}
+tassadar = {name: 'Tassadar', stats: {attack: 0,  life: 80,  shield: 300}}
+
+db.units.save zeratul
+db.units.save tassadar
+
+# Udate (we made error - mistakenly set Tassadar's attack as zero, let's fix it).
+tassadar[:stats][:attack] = 20
+db.units.save tassadar
+
+# Querying first & all, there's also :each, the same as :all.
+db.units.first name: 'Zeratul'                     # => zeratul
+db.units.all name: 'Zeratul'                       # => [zeratul]
+db.units.all name: 'Zeratul' do |unit|
+  unit                                             # => zeratul
+end
+
+# Dynamic Finders (bang versions also availiable).
+db.units.by_name 'Zeratul'                         # => zeratul
+db.units.first_by_name 'Zeratul'                   # => zeratul
+db.units.all_by_name 'Zeratul'                     # => [zeratul]
+
+# Query sugar, use {name: {_gt: 'Z'}} instead of {name: {:$gt => 'Z'}}.
+Mongo.defaults.merge! convert_underscore_to_dollar: true
+db.units.all name: {_gt: 'Z'}                      # => [zeratul]
+```
+
+Source: examples/driver.rb
+
+More docs - there's no need for more docs, the whole point of this extension is to be small, intuitive, 100% compatible with the official driver, and require no extra knowledge.
+So, please use standard Ruby driver documentation.
+
+# Persistence for any Ruby object
+
+Save any Ruby object to MongoDB, as if it's a document. Objects can be any type, simple or composite with other objects / arrays / hashes inside.
+
+Note: the :initialize method should allow to create object without arguments.
+
+``` ruby
+# Let's define the game unit.
+class Unit
+  attr_reader :name, :stats
+
+  # don't forget to allow creating object with no arguments
+  def initialize name = nil, stats = nil
+    @name, @stats = name, stats
+  end
+
+  class Stats
+    attr_accessor :attack, :life, :shield
+
+    def initialize attack = nil, life = nil, shield = nil
+      @attack, @life, @shield = attack, life, shield
+    end
+  end
+end
+
+# Connecting to MongoDB.
+require 'mongodb/object'
+Mongo.defaults.merge! symbolize: true, multi: true, safe: true
+connection = Mongo::Connection.new
+db = connection.db 'default_test'
+db.units.drop
+
+# Create.
+zeratul  = Unit.new('Zeratul',  Unit::Stats.new(85, 300, 100))
+tassadar = Unit.new('Tassadar', Unit::Stats.new(0,  80,  300))
+
+db.units.save zeratul
+db.units.save tassadar
+
+# Udate (we made error - mistakenly set Tassadar's attack as zero, let's fix it).
+tassadar.stats.attack = 20
+db.units.save tassadar
+
+# Querying first & all, there's also :each, the same as :all.
+db.units.first name: 'Zeratul'                     # => zeratul
+db.units.all name: 'Zeratul'                       # => [zeratul]
+db.units.all name: 'Zeratul' do |unit|
+  unit                                             # => zeratul
+end
+
+# Simple finders (bang versions also availiable).
+db.units.by_name 'Zeratul'                         # => zeratul
+db.units.first_by_name 'Zeratul'                   # => zeratul
+db.units.all_by_name 'Zeratul'                     # => [zeratul]
+
+# Query sugar, use {name: {_gt: 'Z'}} instead of {name: {:$gt => 'Z'}}.
+Mongo.defaults.merge! convert_underscore_to_dollar: true
+db.units.all name: {_gt: 'Z'}                      # => [zeratul]
+```
+
+Source: examples/object.rb
+
+# Object Model
+
+- The same API for pure driver and Models.
+- Minimum extra abstractions, trying to keep things as close to the MongoDB semantic as possible.
+- Schema-less, dynamic (with ability to specify types for mass-assignment).
 - Models can be saved to any collection.
-- Full support for embedded objects (and MDD composite pattern).
-- Doesn't try to mimic ActiveRecord, it's differrent and designed to get most of MongoDB.
+- Full support for embedded objects (validations, callbacks, ...).
+- Scope, default_scope
+- Doesn't try to mimic ActiveRecord, MongoDB is differrent and this tool designed to get most of it.
+- Very small, see [code stats][code_stats].
+
+Other ODM usually try to cover simple but non-standard API of MongoDB behind complex ORM-like abstractions. This tool **exposes simplicity and power of MongoDB and leverages it's differences**.
+
+``` ruby
+# Connecting to MongoDB.
+require 'mongodb/model'
+Mongo.defaults.merge! symbolize: true, multi: true, safe: true
+connection = Mongo::Connection.new
+db = connection.db 'default_test'
+db.units.drop
+Mongo::Model.db = db
+
+# Let's define the game unit.
+class Unit
+  inherit Mongo::Model
+  collection :units
+
+  attr_accessor :name, :status, :stats
+
+  scope :alive, status: 'alive'
+
+  class Stats
+    inherit Mongo::Model
+    attr_accessor :attack, :life, :shield
+  end
+end
+
+# Create.
+zeratul  = Unit.build(name: 'Zeratul',  status: 'alive', stats: Unit::Stats.build(attack: 85, life: 300, shield: 100))
+tassadar = Unit.build(name: 'Tassadar', status: 'dead',  stats: Unit::Stats.build(attack: 0,  life: 80,  shield: 300))
+
+zeratul.save
+tassadar.save
+
+# Udate (we made error - mistakenly set Tassadar's attack as zero, let's fix it).
+tassadar.stats.attack = 20
+tassadar.save
+
+# Querying first & all, there's also :each, the same as :all.
+Unit.first name: 'Zeratul'                         # => zeratul
+Unit.all name: 'Zeratul'                           # => [zeratul]
+Unit.all name: 'Zeratul' do |unit|
+  unit                                             # => zeratul
+end
+
+# Simple finders (bang versions also availiable).
+Unit.by_name 'Zeratul'                             # => zeratul
+Unit.first_by_name 'Zeratul'                       # => zeratul
+Unit.all_by_name 'Zeratul'                         # => [zeratul]
+
+# Scopes.
+Unit.alive.count                                   # => 1
+Unit.alive.first                                   # => zeratul
+
+# Callbacks & callbacks on embedded models.
+
+# Validations.
+
+# Save model to any collection.
+```
+
+Source: examples/model.rb
+
+# Migrations
+
+Define migration steps, specify desired version and apply it (usually all this should be done via Rake task).
+
+``` ruby
+require 'mongodb/migration'
+
+# Connection & db.
+connection = Mongo::Connection.new
+db = connection.db 'default_test'
+db.units.drop
+
+# Initialize migration (usually all this should be done inside of :migrate
+# rake task).
+migration = Mongo::Migration.new db
+
+# Define migrations.
+# Usually they are defined as files in some folder and You loading it by
+# using something like this:
+#   Dir['<runtime_dir>/db/migrations/*.rb'].each{|fname| load fname}
+migration.add 1 do |m|
+  m.up{|db|   db.units.save   name: 'Zeratul'}
+  m.down{|db| db.units.remove name: 'Zeratul'}
+end
+
+# Let's add another one.
+migration.add 2 do |m|
+  m.up{|db|   db.units.save   name: 'Tassadar'}
+  m.down{|db| db.units.remove name: 'Tassadar'}
+end
+
+# Specify what version of database You need and apply migration.
+migration.update 2
+
+migration.current_version                        # => 2
+db.units.count                                   # => 2
+
+# You can rollback it the same way.
+migration.update 0
+
+migration.current_version                        # => 0
+db.units.count                                   # => 0
+
+# To update to the highest version just call it without the version specified
+migration.update
+
+migration.current_version                        # => 2
+db.units.count                                   # => 2
+```
+
+Source: examples/migration.rb
+
+# Installation
+
+``` bash
+gem install mongodb
+```
+
+# License
+
+Copyright (c) Alexey Petrushin, http://petrush.in, released under the MIT license.
+
+[mongo_mapper_ext]: https://github.com/alexeypetrushin/mongo_mapper_ext
+[mongoid_misc]: https://github.com/alexeypetrushin/mongoid_misc
+[code_stats]: https://github.com/alexeypetrushin/mongodb/raw/master/docs/code_stats.png

data/spec/driver/collection_spec.rb

@@ -0,0 +1,83 @@
+require 'driver/spec_helper'
+
+describe "Collection" do
+  with_mongo
+
+  it 'by default save must update all matched by criteria (not first as defautl in mongo)' do
+    db.units.save name: 'Probe', race: 'Protoss', status: 'alive'
+    db.units.save name: 'Zealot', race: 'Protoss', status: 'alive'
+
+    # update
+    db.units.update({race: 'Protoss'}, :$set => {status: 'dead'})
+    db.units.all.collect{|u| u[:status]}.should == %w(dead dead)
+
+    # destroy
+    db.units.destroy race: 'Protoss'
+    db.units.count.should == 0
+  end
+
+  describe "symbolize" do
+    it 'should always return symbolized hashes' do
+      zeratul = {name: 'Zeratul'}
+      db.units.save(zeratul).should be_mongo_id
+      r = db.units.first(name: 'Zeratul')
+      r[:_id].should be_mongo_id
+      r['_id'].should be_nil
+      r[:name].should == 'Zeratul'
+      r['name'].should be_nil
+    end
+
+    it "should be able to disable symbolization" do
+      old = Mongo.defaults[:symbolize]
+      begin
+        Mongo.defaults[:symbolize] = false
+
+        zeratul = {name: 'Zeratul'}
+        db.units.save(zeratul).should be_mongo_id
+        r = db.units.first(name: 'Zeratul')
+        r[:_id].should be_nil
+        r['_id'].should be_mongo_id
+        r[:name].should be_nil
+        r['name'].should == 'Zeratul'
+      ensure
+        Mongo.defaults[:symbolize] = old
+      end
+    end
+  end
+
+  it "first" do
+    db.units.first.should be_nil
+    zeratul = {name: 'Zeratul'}
+    db.units.save(zeratul).should be_mongo_id
+    db.units.first(name: 'Zeratul')[:name].should == 'Zeratul'
+  end
+
+  it 'all' do
+    db.units.all.should == []
+
+    zeratul = {name: 'Zeratul'}
+    db.units.save(zeratul).should be_mongo_id
+
+    list = db.units.all(name: 'Zeratul')
+    list.size.should == 1
+    list.first[:name].should == 'Zeratul'
+
+    # with block
+    list = []; db.units.all{|o| list << o}
+    list.size.should == 1
+    list.first[:name].should == 'Zeratul'
+  end
+
+  it 'count' do
+    db.units.count(name: 'Zeratul').should == 0
+    db.units.save name: 'Zeratul'
+    db.units.save name: 'Tassadar'
+    db.units.count(name: 'Zeratul').should == 1
+  end
+
+  it "underscore to dollar" do
+    db.units.save name: 'Jim',     age: 34
+    db.units.save name: 'Zeratul', age: 600
+    db.units.all(age: {_lt: 100}).count.should == 1
+  end
+end

data/spec/{mongo_model/hash → driver}/crud_spec.rb

@@ -1,53 +1,54 @@
-require 'spec_helper'
+require 'driver/spec_helper'
 
 describe "Hash CRUD" do
-  with_mongo_model
-  
+  with_mongo
+
   describe 'simple' do
     before do
       @zeratul = {name: 'Zeratul', info: 'Dark Templar'}
     end
-  
+
     it 'crud' do
       # read
-      db.heroes.count.should == 0
-      db.heroes.all.should == []
-      db.heroes.first.should == nil
-  
+      db.units.count.should == 0
+      db.units.all.should == []
+      db.units.first.should == nil
+
       # create
-      db.heroes.save(@zeratul)
-    
+      db.units.save(@zeratul).should be_mongo_id
+      @zeratul[:_id].should be_mongo_id
+
       # read
-      db.heroes.all.should == [@zeratul]
-      db.heroes.count.should == 1
-      db.heroes.first.should == @zeratul
-    
+      db.units.all.should == [@zeratul]
+      db.units.count.should == 1
+      db.units.first.should == @zeratul
+
       # update
       @zeratul[:info] = 'Killer of Cerebrates'
-      db.heroes.save({name: 'Zeratul'}, @zeratul)
-      db.heroes.count.should == 1
-      db.heroes.first(name: 'Zeratul').info.should == 'Killer of Cerebrates'
-    
+      db.units.save @zeratul
+      db.units.count.should == 1
+      db.units.first(name: 'Zeratul')[:info].should == 'Killer of Cerebrates'
+
       # destroy
-      db.heroes.destroy name: 'Zeratul'
-      db.heroes.count.should == 0
+      db.units.destroy @zeratul
+      db.units.count.should == 0
     end
   end
-  
+
   describe 'embedded' do
-    before do 
+    before do
       @player = {
         name: 'Alex',
         missions: [
           {name: 'Wasteland',         stats: {buildings: 5, units: 10}},
           {name: 'Backwater Station', stats: {buildings: 8, units: 25}}
         ]
-      }      
+      }
     end
-    
+
     it 'crud' do
       # create
-      db.players.save(@player)
+      db.players.save(@player).should be_mongo_id
 
       # read
       db.players.count.should == 1
@@ -55,15 +56,15 @@ describe "Hash CRUD" do
 
       # update
       @player[:missions].first[:stats][:units] = 9
-      @player.missions << {name: 'Desperate Alliance', stats: {buildings: 11, units: 40}},
-      db.players.save({name: 'Alex'}, @player)
+      @player[:missions].push name: 'Desperate Alliance', stats: {buildings: 11, units: 40}
+      db.players.save(@player).should_not be_nil
       db.players.count.should == 1
       db.players.first.should == @player
       db.players.first.object_id.should_not == @player.object_id
 
       # destroy
-      db.players.destroy name: 'Alex'
+      db.players.destroy @player
       db.players.count.should == 0
     end
-  end  
+  end
 end