mm-embeddable 0.0.1

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,21 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Michael Bleigh
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,66 @@
+= MongoMapper Embeddable
+
+Because MongoDB doesn't have joins but does have the ability to embed documents in other documents, it is often the case that for query minimization purposes it is useful to provide a few key properties of a document when it's embedded in another one. MongoMapper Embeddable is a plugin for MongoMapper to do just that.
+
+== Installation
+
+    gem install mm-embeddable
+    
+== Usage
+
+To declare an embeddable version of a MongoMapper document, simply call <tt>embeds</tt> after all of your <tt>key</tt> declarations and specify the keys that should be embedded in the "compacted" version of the model. This will automatically generate a <tt>YourDocumentClass::Embeddable</tt> class that can be embedded in other documents.
+
+=== Example
+
+    require 'mongo_mapper'
+    require 'mm-embeddable'
+    
+    class User
+      include MongoMapper::Document
+      
+      key :name, String
+      key :profile_photo, String
+      key :bio, String
+      key :interests, Array
+      
+      embeds :name, :profile_photo
+    end
+    
+    class Post
+      include MongoMapper::Document
+      
+      key :author, User::Embeddable
+      key :title, String
+      key :body, String
+    end
+    
+This creates an embeddable version of the <tt>User</tt> model that only contains the name and profile picture. If that's all I access, then no additional queries are called. Example:
+
+    <h1><%= @post.title %></h1>
+    <span class='author'>
+      <img src='<%= @post.author.profile_photo %>'/> <%= @post.author.name %>
+    </span>
+    <div class='body'><%= @post.body %></div>
+    
+But if we need other attributes that haven't been stored in the embeddable model, we can do so seamlessly:
+
+    # no additional query is performed
+    @post.author.name
+    # the full document is seamlessly fetched in the background
+    @post.author.bio
+    
+In this way we take full advantage of Mongo's embedded documents while still being able to easily fall back to the full document when necessary.
+
+== 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.
+
+== Copyright
+
+Copyright (c) 2010 Michael Bleigh. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,51 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "mm-embeddable"
+    gem.summary = %Q{Create compact, embeddable versions of your MongoMapper documents.}
+    gem.description = %Q{For query minimization purposes in MongoDB it is useful to provide a few key properties of a document when it's embedded in another one. MongoMapper Embeddable is a plugin for MongoMapper to do just that.}
+    gem.email = "michael@intridea.com"
+    gem.homepage = "http://github.com/intridea/mm-embeddable"
+    gem.add_dependency 'mongo_mapper', '>= 0.7.0'
+    gem.authors = ["Michael Bleigh"]
+    gem.add_development_dependency "rspec", ">= 1.2.9"
+    gem.add_development_dependency 'mocha'
+    gem.add_development_dependency 'machinist'
+    gem.add_development_dependency 'machinist_mongo'
+    gem.add_development_dependency 'faker'
+    
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "mm_compactable #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/lib/mm-embeddable.rb

@@ -0,0 +1,81 @@
+require 'mongo_mapper'
+
+module MongoMapper
+  module Plugins
+    module Embeddable
+      class EmbeddableDocument #:nodoc:
+        include ::MongoMapper::EmbeddedDocument
+        
+        class << self
+          attr_writer :full_class
+        end
+        
+        def self.from_full(full_document)
+          d = self.new
+          keys.keys.each do |k|
+            d.send("#{k}=".to_sym, full_document.send(k.to_sym))
+          end
+          d
+        end
+        
+        def self.full_class
+          @full_class or raise NotImplementedError, 'This embed has no full class.'
+        end
+        
+        def expand!
+          @expanded = true
+          @expansion = self.class.full_class.find(self.id)
+        end
+        
+        def method_missing(*args)
+          if !@expanded
+            expand!
+            @expansion.send(*args)
+          else
+            super
+          end
+        end
+        
+        def self.to_mongo(instance)
+          case instance
+            when full_class
+              from_full(instance).to_mongo
+            else
+              instance.to_mongo
+          end
+        end
+      end
+      
+      module ClassMethods
+        # Tells MongoMapper that this document can be embedded. Pass
+        # in an array of the keys that should be persisted to the
+        # embedded document (<tt>_id</tt> is automatically persisted
+        # as a reference to the full document).
+        def embeds(*ckeys)
+          @embeddable_keys ||= []
+          @embeddable_keys.push(*ckeys)
+          
+          self.const_set(:Embeddable, Class.new(::MongoMapper::Plugins::Embeddable::EmbeddableDocument))
+          
+          self.const_get(:Embeddable).full_class = self
+          self.const_get(:Embeddable).key :_id, ObjectId
+          
+          ckeys.each do |k|
+            self.const_get(:Embeddable).key k
+            self.const_get(:Embeddable).keys[k.to_s] = self.keys[k.to_s].dup
+          end
+          
+          include MongoMapper::Plugins::Embeddable::EmbeddableMethods
+        end
+      end
+      
+      module EmbeddableMethods
+        def to_embeddable
+          self.class.const_get(:Embeddable).from_full(self)
+        end
+      end
+    end
+  end
+end
+
+MongoMapper::Document.append_extensions(MongoMapper::Plugins::Embeddable::ClassMethods)

data/spec/blueprints.rb

@@ -0,0 +1,22 @@
+require 'machinist/mongo_mapper'
+require 'sham'
+require 'faker'
+
+Sham.name { Faker::Name.name }
+Sham.login { Faker::Internet.user_name }
+Sham.bio { Faker::Lorem.sentence(30) }
+Sham.subject { Faker::Lorem.sentence(10) }
+Sham.body { Faker::Lorem.paragraphs(4).join("\n\n") }
+
+TestUser.blueprint do
+  name
+  login
+  bio
+end
+
+TestMessage.blueprint do
+  sender { TestUser.make }
+  receivers { [TestUser.make, TestUser.make] }
+  subject
+  body
+end

data/spec/mm_embeddable_spec.rb

@@ -0,0 +1,47 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe "MongoMapper::Plugins::Embeddable" do
+  it { TestUser.should be_respond_to(:embeds) }
+  
+  it 'should define the Embedded subclass' do
+    defined?(TestUser::Embeddable).should be_true
+    TestUser::Embeddable.should < MongoMapper::Plugins::Embeddable::EmbeddableDocument
+  end
+  
+  it 'should be able to convert to embedded' do
+    TestUser.new.to_embeddable.should be_kind_of(TestUser::Embeddable)
+  end
+  
+  describe '::EmbeddedDocument' do
+    it 'should set attributes from a document' do
+      mid = Mongo::ObjectID.new
+      c = TestUser::Embeddable.from_full(stub(:_id => mid, :login => 'abc', :name => 'Bob Bobson', :bio => "A great dude."))
+      c.login.should == 'abc'
+      c.name.should == 'Bob Bobson'
+      c._id.should == mid
+      lambda{c.bio}.should raise_error(NoMethodError)
+    end
+    
+    it 'should expand when an attribute is missing' do
+      mid = Mongo::ObjectID.new
+      u = TestUser.new(:_id => mid, :name => "Frank", :bio => 'Once upon a time.')
+      TestUser.expects(:find).with(mid).returns(u)
+      TestUser::Embeddable.from_full(u).bio.should == 'Once upon a time.'
+    end
+  end
+  
+  describe ' in another model' do
+    it 'should coerce as a compact document' do
+      u1 = TestUser.make
+      u2 = TestUser.make
+      u3 = TestUser.make
+      
+      t = TestMessage.make(:sender => u1, :receivers => [u2, u3])
+      
+      t.reload
+      t.sender.should be_kind_of(TestUser::Embeddable)
+      t.sender._id.should == u1._id
+      t.receivers.first.should be_kind_of(TestUser::Embeddable)
+    end
+  end
+end

data/spec/spec.opts

@@ -0,0 +1,2 @@
+--color
+--backtrace

data/spec/spec_helper.rb

@@ -0,0 +1,41 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'rubygems'
+gem 'rspec', '1.3.0'
+
+require 'mm-embeddable'
+require 'spec'
+require 'spec/autorun'
+require 'spec/mocks'
+require 'mocha'
+
+class TestUser
+  include MongoMapper::Document
+  
+  key :login, String
+  key :name, String
+  key :bio, String
+  
+  embeds :login, :name
+end
+
+class TestMessage
+  include MongoMapper::Document
+  
+  key :sender, TestUser::Embeddable
+  many :receivers, :class_name => 'TestUser::Embeddable'
+  
+  key :subject, String
+  key :body, String
+end
+
+require File.expand_path(File.dirname(__FILE__) + "/blueprints")
+
+MongoMapper.database = 'mm_plugin_test'
+
+Spec::Runner.configure do |config|
+  config.mock_with :mocha
+  config.before(:all)    { Sham.reset(:before_all)  }
+  config.before(:each)   { Sham.reset(:before_each); }#MongoMapper.connection.drop_database('mm_plugin_test') }
+end

metadata

@@ -0,0 +1,150 @@
+--- !ruby/object:Gem::Specification 
+name: mm-embeddable
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Michael Bleigh
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-03-29 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: mongo_mapper
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 7
+        - 0
+        version: 0.7.0
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 2
+        - 9
+        version: 1.2.9
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: mocha
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: machinist
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: machinist_mongo
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: faker
+  prerelease: false
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id006
+description: For query minimization purposes in MongoDB it is useful to provide a few key properties of a document when it's embedded in another one. MongoMapper Embeddable is a plugin for MongoMapper to do just that.
+email: michael@intridea.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- .document
+- .gitignore
+- LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- lib/mm-embeddable.rb
+- spec/blueprints.rb
+- spec/mm_embeddable_spec.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/intridea/mm-embeddable
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Create compact, embeddable versions of your MongoMapper documents.
+test_files: 
+- spec/blueprints.rb
+- spec/mm_embeddable_spec.rb
+- spec/spec_helper.rb