mongodoc 0.1.2 → 0.2.0

data/README.textile

@@ -0,0 +1,143 @@
+h1. MongoDoc
+
+Version: 0.2 1/18/10
+
+h2. Introduction
+
+MongoDoc is simple and easy to use ActiveRecord-like object mapper for "mongoDB":http://www.mongodb.org in Ruby.
+
+MongoDoc is _also_ an extension of the "Mongo Ruby Driver":http://github.com/mongodb/mongo-ruby-driver making it a snap to get Ruby in and out of mongoDB.
+
+MongoDoc is *not* ActiveRecord for mongoDB.  We do not have callbacks, nor do we have dynamic finders.  We do have associations, named scopes, and other features.
+
+MongoDoc *is* simple, easy-to-use, and fast. And it works with Rails (2.3.x at the moment, 3 soonish?).
+
+MongoDoc is designed to work with document data, if you are looking to map relational data in mongoDB, you will have to look elsewhere.
+
+h2. Ruby objects in mongoDB
+
+Lets just get right into it and save some Ruby objects in mongoDB!
+
+bc.. class Contact
+  attr_accessor :name, :addresses, :interests
+end
+
+class Address
+  attr_accessor :street, :city, :state, :zip, :phone_number
+end
+
+p. With MongoDoc, instead of saving JSON[1], we can save an object directly:
+
+bc.. contact = Contact.new
+contact.name = 'Hashrocket'
+contact.interests = ['ruby', 'rails', 'agile']
+
+address = Address.new
+address.street = '320 First Street North, #712'
+address.city = 'Jacksonville Beach'
+address.state = 'FL'
+address.zip = '32250'
+address.phone_number = '877 885 8846'
+contact.addresses = [address]
+
+collection.save(contact)
+
+p. We can query using the powerful mongoDB query syntax, and have it return Ruby objects:
+
+bc.. results = collection.find('addresses.state' => 'FL')
+hashrocket = results.to_a.find {|contact| contact.name == 'Hashrocket'}
+puts hashrocket.addresses.first.phone_number
+
+p. Take a look in the examples directory for more code.
+
+h2. Mapping Documents
+
+MongoDoc provides ActiveRecord-like persistence, associations, named scopes, and validations (from "Validatable":http://github.com/durran/validatable) as well as a mongoDB query language (from "Mongoid":http://mongoid.org/home). MongoDoc also plays nicely with Rails.
+
+@MongoDoc::Document@ provides all these features as a mixin.  A @MongoDoc::Document@ can either be a top-level mongoDB document, or an embedded document contained within a top-level document. Top-level documents are stored in collections named after their class: @Contact@ objects are stored in the 'contacts' collection (much like ActiveRecord).
+
+Lets define a @Contact@ document with an @Address@ embedded document:
+
+bc.. class Address
+  include MongoDoc::Document
+
+  key :street
+  key :city
+  key :state
+  key :zip_code
+  key :phone_number
+end
+
+class Contact
+  include MongoDoc::Document
+
+  key :name
+  key :interests
+  has_many :addresses
+
+  named_scope :in_state, lambda {|state| {:where => {'addresses.state' => state}}}
+end
+
+p. Since a mongoDB document has no fixed schema, we define the composition of a document directly in our classes. Please note we do not specify types! We can also specify @has_one@ or @has_many@ associations.
+
+Building and saving a document is easy:
+
+bc.. contact = Contact.new(:name => 'Hashrocket', :interests => ['ruby', 'rails', 'agile'])
+contact.addresses << Address.new(:street => '320 1st Street North, #712',
+  :city => 'Jacksonville Beach',
+  :state => 'FL',
+  :zip_code => '32250',
+  :phone_number => '877 885 8846')
+contact.save
+
+p. Now that we have some data, we can query using our named scope:
+
+bc. hashrocket = Contact.in_state('FL').find {|contact| contact.name == 'Hashrocket'}
+
+p. And we can even perform partial updates:
+
+bc. hashrocket.addresses.first.update_attributes(:street => '320 First Street North, #712')
+
+h2. Installation
+
+bc. sudo gem install mongodoc
+
+h2. Configuration
+
+Configure your database connection in ./mongodb.yml, you do not need one if you are running on localhost with the default port
+
+bc. name: test
+host: localhost
+port: 27017
+options:
+  auto_reconnect: true
+
+You can change the location of the configuration file:
+
+bc. MongoDoc.config_path = './config/mongodb.yml'
+
+h2. Credits
+
+Les Hill, leshill on github
+
+h3. Thanks
+
+Thanks to Sandro and Durran for some great conversations and some lovely code.
+
+h2. Note on Patches/Pull Requests
+
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but
+  bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+h2. Copyright
+
+Copyright (c) 2009 Les Hill. See LICENSE for details.
+
+fn1. The Ruby driver exposes an API that understands JSON.
+

data/Rakefile

@@ -10,9 +10,9 @@ begin
     gem.email = "leshill@gmail.com"
     gem.homepage = "http://github.com/leshill/mongodoc"
     gem.authors = ["Les Hill"]
-    gem.add_dependency "mongo", "= 0.18.1"
-    gem.add_dependency "mongo_ext", "= 0.18.1"
-    gem.add_dependency "durran-validatable", "= 1.8.3"
+    gem.add_dependency "mongo", "= 0.18.2"
+    gem.add_dependency "mongo_ext", "= 0.18.2"
+    gem.add_dependency "durran-validatable", "= 1.8.4"
     gem.add_dependency "leshill-will_paginate", "= 2.3.11"
     gem.add_development_dependency "rspec", "= 1.2.9"
     gem.add_development_dependency "cucumber", "= 0.4.4"
@@ -80,3 +80,35 @@ namespace :mongo do
     puts "\n"
   end
 end
+
+namespace :bench do
+  desc 'Run benchmark for MongoDoc'
+  task 'mongodoc' do
+    $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), 'lib'))
+    require 'perf/mongodoc_runner'
+    MongoDocRunner.benchmark
+  end
+
+  desc 'Run profiler for driver'
+  task 'driver' do
+    $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), 'lib'))
+    require 'perf/ruby_driver_runner'
+    RubyDriverRunner.benchmark
+  end
+end
+
+namespace :prof do
+  desc 'Run profiler for MongoDoc'
+  task 'mongodoc' do
+    $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), 'lib'))
+    require 'perf/mongodoc_runner'
+    MongoDocRunner.profile
+  end
+
+  desc 'Run profiler for driver'
+  task 'driver' do
+    $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), 'lib'))
+    require 'perf/ruby_driver_runner'
+    RubyDriverRunner.profile
+  end
+end

data/VERSION

@@ -1 +1 @@
-0.1.2
+0.2.0

data/examples/simple_document.rb

@@ -0,0 +1,35 @@
+require 'mongodoc'
+
+class Address
+  include MongoDoc::Document
+
+  key :street
+  key :city
+  key :state
+  key :zip_code
+  key :phone_number
+end
+
+class Contact
+  include MongoDoc::Document
+
+  key :name
+  key :interests
+  has_many :addresses
+
+  named_scope :in_state, lambda {|state| {:where => {'addresses.state' => state}}}
+end
+
+MongoDoc.connect_to_database 'test'
+Contact.collection.drop
+
+contact = Contact.new(:name => 'Hashrocket', :interests => ['ruby', 'rails', 'agile'])
+contact.addresses << Address.new(:street => '320 1st Street North, #712', :city => 'Jacksonville Beach', :state => 'FL', :zip_code => '32250', :phone_number => '877 885 8846')
+contact.save
+
+hashrocket = Contact.in_state('FL').find {|contact| contact.name == 'Hashrocket'}
+
+hashrocket_address = hashrocket.addresses.first
+hashrocket_address.update_attributes(:street => '320 First Street North, #712')
+
+puts Contact.find_one(:where => {:name => 'Hashrocket'}).addresses.first.street

data/examples/simple_object.rb

@@ -0,0 +1,32 @@
+require 'mongodoc'
+
+class Contact
+  attr_accessor :name, :addresses, :interests
+end
+
+class Address
+  attr_accessor :street, :city, :state, :zip, :phone_number
+end
+
+MongoDoc.connect_to_database 'test'
+
+collection = MongoDoc::Collection.new('contacts')
+collection.drop
+
+contact = Contact.new
+contact.name = 'Hashrocket'
+contact.interests = ['ruby', 'rails', 'agile']
+
+address = Address.new
+address.street = '320 First Street North, #712'
+address.city = 'Jacksonville Beach'
+address.state = 'FL'
+address.zip = '32250'
+address.phone_number = '877 885 8846'
+contact.addresses = [address]
+
+collection.save(contact)
+
+results = collection.find('addresses.state' => 'FL')
+hashrocket = results.to_a.find {|contact| contact.name == 'Hashrocket'}
+puts hashrocket.addresses.first.phone_number

data/features/finders.feature

@@ -0,0 +1,72 @@
+Feature: Finders
+
+  Background:
+    Given an empty Contact document collection
+    And a Contact document named 'hashrocket' :
+      | Name       | Type    |
+      | Hashrocket | company |
+    And 'hashrocket' has interests, an array of:
+      | Interest      |
+      | ruby          |
+      | rails         |
+      | employment    |
+      | contract work |
+      | restaurants   |
+      | hotels        |
+      | flights       |
+      | car rentals   |
+    And 'hashrocket' has many addresses :
+      | Street                 | City               | State | Zip Code |
+      | 320 First Street North | Jacksonville Beach | FL    | 32250    |
+      | 1 Lake Michigan Street | Chicago            | IL    | 60611    |
+      | 1 Main Street          | Santiago           | Chile |          |
+    And I save the document 'hashrocket'
+    And a Contact document named 'rocketeer' :
+      | Name           |
+      | Rocketeer Mike |
+    And 'rocketeer' has interests, an array of:
+      | Interest    |
+      | ruby        |
+      | rails       |
+      | restaurants |
+      | employment  |
+    And 'rocketeer' has many addresses :
+      | Street                 | City               | State | Zip Code |
+      | 1 Main Street          | Atlantic Beach     | FL    | 32233    |
+    And I save the document 'rocketeer'
+    And a Contact document named 'contractor' :
+      | Name          |
+      | Contractor Joe |
+    And 'contractor' has interests, an array of:
+      | Interest      |
+      | ruby          |
+      | rails         |
+      | contract work |
+      | flights       |
+      | car rentals   |
+      | hotels        |
+      | restaurants   |
+    And 'contractor' has many addresses :
+      | Street                 | City               | State | Zip Code |
+      | 1 Main St.             | Jacksonville       | FL    | 32218    |
+    And I save the document 'contractor'
+
+  Scenario: All
+    When I query contacts with all
+    Then the query result has 3 documents
+
+  Scenario: Count
+    When I query contacts with count
+    Then the query result was 3 documents
+
+  Scenario: First
+    When I query contacts with first
+    Then the query result is the document 'hashrocket'
+
+  Scenario: Last
+    When I query contacts with last
+    Then the query result is the document 'contractor'
+
+  Scenario: Find One
+    When I query contacts to find_one with the id of the 'contractor' document
+    Then the query result is the document 'contractor'

data/features/mongodoc_base.feature

@@ -74,7 +74,7 @@ Feature: MongoDoc::Base
     And the Contact collection should have 1 document
     And the document 'hashrocket' roundtrips
 
-  Scenario: failing to update attributes from a has_many child document
+  Scenario: Update attributes from a has_many child document
     Given an empty Contact document collection
     And a Contact document named 'hashrocket' :
       | Name       |
@@ -89,7 +89,8 @@ Feature: MongoDoc::Base
       | Street         |
       | 1a Calle       |
     When I update the document 'chile' with the hash named 'street'
-    Then the last return value is false
+    Then the last return value is true
+    And the document 'hashrocket' roundtrips
 
   Scenario: update attributes from a has_one child document
     Given an empty Place document collection
@@ -107,3 +108,12 @@ Feature: MongoDoc::Base
     When I update the document 'address' with the hash named 'street'
     Then the Place collection should have 1 document
     And the document 'hashrocket' roundtrips
+
+  Scenario: Finder
+    Given an empty Contact document collection
+    And a Contact document named 'hashrocket' :
+      | Name       | Type    |
+      | Hashrocket | company |
+    And I save the last document
+    When I query contacts with find {:where => {'type' => 'company'}}
+    Then the size of the last return value is 1

data/features/named_scopes.feature

@@ -0,0 +1,66 @@
+Feature: Named Scopes
+
+  Background:
+    Given an empty Contact document collection
+    And a Contact document named 'hashrocket' :
+      | Name       | Type    |
+      | Hashrocket | company |
+    And 'hashrocket' has interests, an array of:
+      | Interest      |
+      | ruby          |
+      | rails         |
+      | employment    |
+      | contract work |
+      | restaurants   |
+      | hotels        |
+      | flights       |
+      | car rentals   |
+    And 'hashrocket' has many addresses :
+      | Street                 | City               | State | Zip Code |
+      | 320 First Street North | Jacksonville Beach | FL    | 32250    |
+      | 1 Lake Michigan Street | Chicago            | IL    | 60611    |
+      | 1 Main Street          | Santiago           | Chile |          |
+    And I save the document 'hashrocket'
+    And a Contact document named 'rocketeer' :
+      | Name           |
+      | Rocketeer Mike |
+    And 'rocketeer' has interests, an array of:
+      | Interest    |
+      | ruby        |
+      | rails       |
+      | restaurants |
+      | employment  |
+    And 'rocketeer' has many addresses :
+      | Street                 | City               | State | Zip Code |
+      | 1 Main Street          | Atlantic Beach     | FL    | 32233    |
+    And I save the document 'rocketeer'
+    And a Contact document named 'contractor' :
+      | Name          |
+      | Contractor Joe |
+    And 'contractor' has interests, an array of:
+      | Interest      |
+      | ruby          |
+      | rails         |
+      | contract work |
+      | flights       |
+      | car rentals   |
+      | hotels        |
+      | restaurants   |
+    And 'contractor' has many addresses :
+      | Street                 | City               | State | Zip Code |
+      | 1 Main St.             | Jacksonville       | FL    | 32218    |
+    And I save the document 'contractor'
+
+  Scenario: Simple named scope
+    When I query contacts with scope 'rubyists'
+    Then the query result has 3 documents
+
+  Scenario: Simple chained scope
+    When I query contacts with scopes 'rubyists, contract_work'
+    Then the query result has 2 documents
+    And one of the query results is the document 'contractor'
+
+  Scenario: Named scope with lambda
+    When I query contacts with lambda scope 'in_state' with parameters 'IL'
+    Then the query result has 1 documents
+    And one of the query results is the document 'hashrocket'

data/features/new_record.feature

@@ -0,0 +1,36 @@
+Feature: New record
+
+  Scenario: saving a has_many children document
+    Given an empty Contact document collection
+    And a Contact document named 'hashrocket' :
+      | Name       |
+      | Hashrocket |
+    And 'hashrocket' has many addresses :
+      | Street                 | City               | State | Zip Code |
+      | 320 First Street North | Jacksonville Beach | FL    | 32250    |
+      | 1 Main Street          | Santiago           | Chile |          |
+    When I save the document 'hashrocket'
+    Then the first address of 'hashrocket' is not a new record
+
+  Scenario: saving a has_one child document
+    Given an empty Place document collection
+    And a Place document named 'hashrocket' :
+      | Name       |
+      | Hashrocket |
+    And 'hashrocket' has one Address as address :
+      | Street                 | City               | State | Zip Code |
+      | 320 First Street North | Jacksonville Beach | FL    | 32250    |
+    When I save the document 'hashrocket'
+    Then the address of 'hashrocket' is not a new record
+
+  Scenario: id is roundtripped when saving a has_one child document
+    Given an empty Place document collection
+    And a Place document named 'hashrocket' :
+      | Name       |
+      | Hashrocket |
+    And 'hashrocket' has one Address as address :
+      | Street                 | City               | State | Zip Code |
+      | 320 First Street North | Jacksonville Beach | FL    | 32250    |
+    When I save the document 'hashrocket'
+    Then the address of 'hashrocket' roundtrips
+

data/features/partial_updates.feature

@@ -0,0 +1,105 @@
+Feature: Partial Updates
+
+  Background:
+    Given an empty Contact document collection
+    And a Contact document named 'hashrocket' :
+      | Name       | Type    | Note                            |
+      | Hashrocket | company | Premier Rails development shop! |
+    And 'hashrocket' has interests, an array of:
+      | Interest      |
+      | ruby          |
+      | rails         |
+      | employment    |
+      | contract work |
+      | restaurants   |
+      | hotels        |
+      | flights       |
+      | car rentals   |
+    And 'hashrocket' has many addresses :
+      | Street                 | City               | State | Zip Code |
+      | 320 First Street North | Jacksonville Beach | FL    | 32250    |
+      | 1 Lake Michigan Street | Chicago            | IL    | 60611    |
+      | 1 Main Street          | Santiago           | Chile |          |
+    And I save the document 'hashrocket'
+    And a Contact document named 'rocketeer' :
+      | Name           | Note                |
+      | Rocketeer Mike | Fantastic developer |
+    And 'rocketeer' has interests, an array of:
+      | Interest    |
+      | ruby        |
+      | rails       |
+      | restaurants |
+      | employment  |
+    And 'rocketeer' has many addresses :
+      | Street                 | City               | State | Zip Code |
+      | 1 Main Street          | Atlantic Beach     | FL    | 32233    |
+    And I save the document 'rocketeer'
+    And a Contact document named 'contractor' :
+      | Name           | Note          |
+      | Contractor Joe | Knows MongoDB |
+    And 'contractor' has interests, an array of:
+      | Interest      |
+      | ruby          |
+      | rails         |
+      | contract work |
+      | flights       |
+      | car rentals   |
+      | hotels        |
+      | restaurants   |
+    And 'contractor' has many addresses :
+      | Street                 | City               | State | Zip Code |
+      | 1 Main St.             | Jacksonville       | FL    | 32218    |
+    And I save the document 'contractor'
+    And an empty Place document collection
+    And a Place document named 'hashrocket_hq' :
+      | Name       | Type    |
+      | Hashrocket | company |
+    And 'hashrocket_hq' has one Address as address (identified by 'hq_address'):
+      | Street                 | City               | State | Zip Code |
+      | 1 Main St.             | Jacksonville       | FL    | 32218    |
+    And I save the document 'hashrocket_hq'
+
+  Scenario: Naive Update
+    When I update the 'note' for 'contractor' to 'Knows MongoDB and MongoDoc'
+    Then the document 'contractor' roundtrips
+
+  Scenario: Naive Update on a has one
+    When I update the 'street' for 'hq_address' to '320 1st Street North'
+    Then the document 'hashrocket_hq' roundtrips
+
+  Scenario: Naive Update on a has many
+    When 'hq_address' is the first address of 'hashrocket'
+    And I update the 'street' for 'hq_address' to '320 1st Street North'
+    Then the document 'hashrocket' roundtrips
+
+  Scenario: Strict Update
+    When I strict update the 'note' for 'contractor' to 'Knows MongoDB and MongoDoc'
+    Then the document 'contractor' roundtrips
+
+  Scenario: Strict Update on a has one
+    When I strict update the 'street' for 'hq_address' to '320 1st Street North'
+    Then the document 'hashrocket_hq' roundtrips
+
+  Scenario: Strict Update on a has many
+    When 'hq_address' is the first address of 'hashrocket'
+    And I strict update the 'street' for 'hq_address' to '320 1st Street North'
+    Then the document 'hashrocket' roundtrips
+
+  Scenario: Failing Strict Update on a has one
+    When someone else changes the Address 'address' of 'hashrocket_hq' to 
+      | Street                 | City               | State | Zip Code |
+      | 1 Ocean Blvd.          | Jacksonville       | FL    | 32218    |
+    And I strict update the 'street' for 'hq_address' to '320 1st Street North'
+    Then the last return value is false
+    And the document 'hashrocket_hq' does not roundtrip
+
+  Scenario: Failing Strict Update on a has many
+    When 'hq_address' is the first address of 'hashrocket'
+    And someone else changes the addresses of 'hashrocket':
+      | Street                 | City               | State | Zip Code |
+      | 320 1st N, #712        | Jacksonville Beach | FL    | 32250    |
+      | 1001 Mulligan Street   | Chicago            | IL    | 60611    |
+      | 345 Avenida Grande     | Santiago           | Chile |          |
+    And I strict update the 'street' for 'hq_address' to '320 1st Street North'
+    Then the last return value is false
+    And the document 'hashrocket' does not roundtrip

data/features/step_definitions/criteria_steps.rb

@@ -1,17 +1,10 @@
-def query(klass_name = nil)
-  return @query if @query or klass_name.nil?
-  klass = klass_name.singularize.camelize.constantize
-  @query = klass.criteria
+When /^I query (.*) with 'all'$/ do |doc|
+  query(doc).all
 end
 
-# When /^I query (.*) with all "([^\"]*)"$/ do |doc, selections_text|
-  # selections = eval(selections_text)
-  # query(doc).all(selections)
-# end
-
 When /^I query (.*) to select fields? "([^\"]*)"$/ do |doc, fields|
   fields = fields.split
-  query(doc).select(*fields)
+  query(doc).only(*fields)
 end
 
 When /^I query (.*) where "([^\"]*)"$/ do |doc, where_text|
@@ -34,7 +27,7 @@ When /^I query (.*) with (every|not in|in) "([^\"]*)"$/ do |doc, op, hash_text|
   query(doc).send(op.gsub(' ', '_'), hash)
 end
 
-When /^I query (.*) with '(.*)' id$/ do |doc, name|
+When /^I query (.*) with the '(.*)' id$/ do |doc, name|
   object = instance_variable_get("@#{name}")
   query(doc).id(object.id)
 end
@@ -47,33 +40,3 @@ When /^I order the (.*) query by "([^\"]*)"$/ do |doc, order_text|
   order = eval(order_text)
   query(doc).order_by(order)
 end
-
-Then /^the (first|last) query result is equal to the document '(.*)'$/ do |position, name|
-  object = instance_variable_get("@#{name}")
-  query.send(position).should == object
-end
-
-Then /^one of the query results is the document '(.*)'$/ do |name|
-  object = instance_variable_get("@#{name}")
-  query.any? {|doc| doc == object}
-end
-
-Then /^the aggregate query result with "(.*)" == "(.*)" has a count of (.*)$/ do |key, value, count|
-  result = query.aggregate
-  result.find {|r| r.has_key?(key) and r[key] == value }['count'].should == count.to_i
-end
-
-Then /^the query result has (.*) documents*$/ do |count|
-  query.count.should == count.to_i
-end
-
-Then /^the size of the query result is (.*)$/ do |count|
-  query.to_a.size.should == count.to_i
-end
-
-Then /^the group query result with "([^\"]*)" == "([^\"]*)" has the document '(.*)'$/ do |key, value, name|
-  object = instance_variable_get("@#{name}")
-  result = query.group
-  result.find {|r| r.has_key?(key) and r[key] == value }['group'].should include(object)
-end
-