mongoscript 0.0.8 → 0.0.9

data/.travis.yml

@@ -0,0 +1,10 @@
+language: ruby
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - jruby-18mode # JRuby in 1.8 mode
+  - jruby-19mode # JRuby in 1.9 mode
+  - rbx-18mode
+  - rbx-19mode
+script: bundle exec rake spec

data/Gemfile

@@ -9,10 +9,17 @@ end
 
 group :development, :test do
   # ORM
-  gem "mongoid", "~> 2.2"
-  gem "bson_ext"
+  gem "mongoid", "~> 2.3.0"
+  # mongo & bson 1.6 generate invalid gemspecs in rbx
+  gem "mongo", "~> 1.5.0"
+  if defined? JRUBY_VERSION
+    gem "bson"
+  else
+    gem "bson_ext", "~> 1.5.0"
+  end
 
   # Testing infrastructure
+  gem 'rake'
   gem 'rspec'
   gem 'mocha'
   gem 'guard'

data/Rakefile

@@ -9,3 +9,8 @@ rescue LoadError
     abort "Jasmine is not available. In order to run jasmine, you must: (sudo) gem install jasmine"
   end
 end
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new do |t|
+  t.rspec_opts = ["--color", '--format doc']
+end

data/lib/mongoscript/execution.rb

@@ -1,44 +1,47 @@
 require 'digest/md5'
 
 module MongoScript
-  # Execute raw code on the Mongo server
-  # code_for can
-  # longer term, we could store functions on the server
-  # and have deploy tasks that delete all and reinstall stored method on deploys
-  # see http://neovintage.blogspot.com/2010/07/mongodb-stored-javascript-functions.html
-  # 10gen recommends not using stored functions, but that's mainly b/c
-  # they should be stored and versioned with other code
-  # but a cool 6W gem for automatically clearing and installing such code would meet that objection
-  # see http://www.mongodb.org/display/DOCS/Server-side+Code+Execution#Server-sideCodeExecution-Storingfunctionsserverside
+  # Execute code on the Mongo server.
 
   module Execution
+    extend ActiveSupport::Concern
 
     LOADED_SCRIPTS = {}
 
-    class ScriptNotFound < Errno::ENOENT; end
+    class ScriptNotFound < StandardError; end
     class NoScriptDirectory < ArgumentError; end
     class ExecutionFailure < RuntimeError; end
 
-    def self.included(base)
-      base.class_eval do
-        class << self
-          attr_accessor :script_dirs
-        end
-
-        def self.gem_path
-          mongoscript = Bundler.load.specs.find {|s| s.name == "mongoscript"}
-          File.join(mongoscript.full_gem_path, "lib", "mongoscript", "javascripts")
-        end
-
-        # start out with the scripts provided by the gem
-        @script_dirs = [gem_path]
-
-        extend MongoScript::Execution::ClassMethods
+    included do
+      class << self
+        attr_accessor :script_dirs
       end
+
+      # start out with the scripts provided by the gem
+      @script_dirs = [gem_path]
     end
 
     module ClassMethods
-      # code from stored files
+      # Get code from stored files.
+      # This looks through each of the script directories, returning the first match it finds.
+      #
+      # Longer term, we could store functions on the server
+      # keyed by both name and a hash of the contents (to ensure uniqueness).
+      #
+      # @see http://neovintage.blogspot.com/2010/07/mongodb-stored-javascript-functions.html.
+      # @see http://www.mongodb.org/display/DOCS/Server-side+Code+Execution#Server-sideCodeExecution-Storingfunctionsserverside
+      #
+      # @note 10gen recommends not using stored functions, but that's mainly because
+      #       they should be stored and versioned with other code.
+      #       However, automatic installation and versioning via MD5 hashes should meet that objection.
+      #
+      # @param script_name the name of the script file (without .js)
+      #
+      # @note this is currently cached in LOADED_SCRIPTS without hashing. (To do!)
+      #
+      # @raises ScriptNotFound if a file with the provided basename doesn't exist in any provided directory.
+      #
+      # @returns the script contents
       def code_for(script_name)
         script_name = script_name.to_s
         dir = @script_dirs.find {|d| File.exists?(File.join(d, "#{script_name}.js"))}
@@ -56,10 +59,30 @@ module MongoScript
         # code
       end
 
+      # Execute read-only code stored in a file.
+      # The code will be run non-blockingly;
+      # it should not contain any statements that write to the database.
+      #
+      # @note The name of this function may change before 1.0.
+      #
+      # @param script_name the name of the script file (see #code_for)
+      # @param args any arguments to the function
+      #
+      # @returns the result of the Mongo call
       def execute_readonly_routine(script_name, *args)
         execute_readonly_code(code_for(script_name), *args)
       end
 
+      # Execute code stored in a file that can write to the database.
+      #
+      # @note This call will block MongoDB, so use this method sparingly.
+      #
+      # @note (see #execute_readonly_routine)
+      #
+      # @param script_name the name of the script file (see #code_for)
+      # @param args any arguments to the function
+      #
+      # @returns (see #execute_readonly_routine)
       def execute_readwrite_routine(script_name, *args)
         execute_readwrite_code(code_for(script_name), *args)
       end
@@ -79,12 +102,19 @@ module MongoScript
 
       def execute(code, args = [], options = {})
         # see http://mrdanadams.com/2011/mongodb-eval-ruby-driver/
-        result = MongoScript.database.command({:$eval => code, args: resolve_arguments(args)}.merge(options))
+        result = MongoScript.database.command({:$eval => code, :args => resolve_arguments(args)}.merge(options))
         unless result["ok"] == 1.0
           raise ExecutionFailure, "MongoScript.execute JS didn't return {ok: 1.0}!  Result: #{result.inspect}"
         end
         result["retval"]
       end
+
+      protected
+
+      def gem_path
+        mongoscript = Bundler.load.specs.find {|s| s.name == "mongoscript"}
+        File.join(mongoscript.full_gem_path, "lib", "mongoscript", "javascripts")
+      end
     end
   end
 end

data/lib/mongoscript/multiquery.rb

@@ -1,6 +1,9 @@
 module MongoScript
   module Multiquery
+    extend ActiveSupport::Concern
 
+    # An error class representing Mongo queries that for some reason failed in the Javascript.
+    # This error will never be raised; instead it will be returned as an object in the results array.
     class QueryFailedError < RuntimeError
       # The original query whose execution failed.
       attr_accessor :query_parameters
@@ -9,6 +12,7 @@ module MongoScript
       # The response from the multiquery Javascript.
       attr_accessor :db_response
 
+      # Initialize the error, and set its backtrace.
       def initialize(name, query, response)
         @query_name = name
         @query_parameters = query
@@ -19,15 +23,7 @@ module MongoScript
       end
     end
 
-    # @private
-    def self.included(base)
-      base.class_eval do
-        extend MongoScript::Multiquery::ClassMethods
-      end
-    end
-
     module ClassMethods
-
       # Runs multiple find queries at once,
       # returning the results keyed to the original query names.
       # If a query produces an error, its result will be a QueryFailedError object

data/lib/mongoscript/orm/mongoid_adapter.rb

@@ -1,18 +1,21 @@
 module MongoScript
   module ORM
     module MongoidAdapter
-
-      def self.included(base)
-        base.class_eval do
-          extend MongoScript::ORM::MongoidAdapter::ClassMethods
-        end
-      end
+      extend ActiveSupport::Concern
 
       module ClassMethods
+        # The MongoDB database.
         def database
           Mongoid::Config.database
         end
 
+        # Turn a raw hash returned by the MongoDB driver into a regular Ruby object.
+        # For this adapter, it a Mongoid document.
+        #
+        # @param klass an ORM class that can instantiate objects from data
+        # @param data raw data returned from the database
+        #
+        # @returns a Ruby object
         def rehydrate(klass, data)
           Mongoid::Factory.from_db(klass, data)
         end
@@ -73,6 +76,11 @@ module MongoScript
           end
         end
 
+        # Answers whether a given non-hash object can be turned into a hash
+        # suitable for database queries.
+        # Currently, it checks if the object is a Mongoid::Criteria.
+        #
+        # @param object the object to test
         def processable_into_parameters?(object)
           object.is_a?(Mongoid::Criteria)
         end

data/lib/mongoscript/orm/mongoid_document_methods.rb

@@ -1,3 +1,4 @@
+# @private
 # TBD: do we need this?
 module MongoidDocumentMethods
   module ClassMethods

data/lib/mongoscript/version.rb

@@ -1,3 +1,3 @@
 module Mongoscript
-  VERSION = "0.0.8"
+  VERSION = "0.0.9"
 end

data/lib/mongoscript.rb

@@ -15,7 +15,7 @@ module MongoScript
   #
   # @returns MongoScript::ORM::Mongoid if Mongoid is detected
   def self.orm_adapter
-    if const_defined? "Mongoid"
+    if Object.const_defined? "Mongoid"
       MongoScript::ORM::MongoidAdapter
     else
       raise NoORMError, "Unable to locate Mongoid!"

data/mongoscript.gemspec

@@ -6,7 +6,7 @@ Gem::Specification.new do |gem|
   gem.email         = ["alex+git@alexkoppel.com"]
   gem.description   = %q{An experimental Ruby library for running serverside Javascript in MongoDB.}
   gem.summary       = %q{An experimental Ruby library for running serverside Javascript in MongoDB.}
-  gem.homepage      = ""
+  gem.homepage      = "http://github.com/arsduo/mongoscript"
 
   gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   gem.files         = `git ls-files`.split("\n")

data/readme.md

@@ -1,3 +1,5 @@
+[![Build Status](https://secure.travis-ci.org/arsduo/mongoscript.png)](http://travis-ci.org/arsduo/mongoscript)
+
 #MongoScript#
 
 An experimental library designed to make server-side Javascript execution in MongoDB easy, fun, and profitable.
@@ -10,13 +12,48 @@ This library isn't "experimental" only in the sense that I'm trying out new code
 
 If you're building a small-to-medium-sized system that you know will never grow huge, you may be able to use MongoScript to very cool effect.  I wouldn't recommend it for any kind of "we're gonna scale it  to the moon!" kind of product, though.  Disentangling Javascript functions and reimplementing them in Ruby so you can shard your growing database doesn't sound like my kind of fun.
 
+###The cool stuff###
+
+You understand all that, you just want to hack some server-side code for the fun of it?  Let's get to it!
+
+First, what are a few things you could do with Mongo server-side Javascript?
+
+* Multiquery: execute multiple find queries in one call.  (See Performance below.)
+* Join: Mongo's (in)famous for not offering native joins, but a Javascript method to fetch from collection A and then get any referenced records from collection B won't be hard.
+* Easy maintenance: why transfer records and updates back forth between your web server and your database, when you can do everything at localhost speed?
+
+You'll notice a theme: making one connection to the database and executing multiple operations.  That's where server-side Javascript shines: it's a language you already know that can do whatever you need it to, all within the context of your server.
+
+(more ideas/explanation coming soon)
+
 ###Performance###
 
-There's also no guarantee that using Javascript to perform semi-complex queries is actually worth it -- Javascript can be significantly slower.  I'll post some performance statistics soon.
+Just to show what a Javascript-based approach to Mongo can do, let's take a look at multiquery, one of the first tools built into MongoScript.  This lets you execute multiple find queries easily using a single database connection.
 
-###The cool stuff###
+When run locally, it doesn't make a significant difference:
 
-You understand all that, you just want to hack some server-side code for the fun of it?  Let's get to it!
+```
+# Macbook Pro running Ruby and MongoDB locally
+# 100 run average
+Traditional execution took 0.38300072999999996
+Multiquery execution took  0.37415497999999997
+```
+
+But check out what happens if the web server and the database aren't on the same machine:
+
+```
+# Test web and MongoDB servers in the same EC2 location
+# 100 run average
+Traditional execution took 0.02256884963
+Multiquery execution took  0.01187204267
+```
+
+The results hold up over multiple runs, and I suspect would be even stronger with writes.
+
+###Coming Soon###
+
+A more detailed readme, with usage instructions and so on.
 
+###Note on Dependencies###
 
-####More readme coming soon!####
+Since this is currently experimental/for fun, I'm relying on ActiveSupport for HashWithIndifferentAccess and Concern.  I acknowledge this restricts the gem to projects where ActiveSupport is an option, but should be easy enough to rip out if someone wants to use this seriously.

data/spec/cases/execution_spec.rb

@@ -18,8 +18,8 @@ describe MongoScript::Execution do
     MongoScript::Execution::LOADED_SCRIPTS.should be_a(Hash)
   end
 
-  it "defines ScriptNotFound error < Errno::ENOENT" do
-    MongoScript::Execution::ScriptNotFound.superclass.should == Errno::ENOENT
+  it "defines ScriptNotFound error" do
+    MongoScript::Execution::ScriptNotFound.superclass.should == StandardError
   end
 
   it "defines ExecutionFailure error < RuntimeError" do
@@ -62,7 +62,7 @@ describe MongoScript::Execution do
     end
 
     it "raises a ScriptNotFound error if the file doesn't exist" do
-      File.stubs(:exist?).returns(false)
+      File.stubs(:exists?).returns(false)
       expect { ObjectWithExecution.code_for("i don't exist") }.to raise_exception(ObjectWithExecution::ScriptNotFound)
     end
 

data/spec/cases/mongoid_adapter_spec.rb

@@ -105,7 +105,7 @@ describe MongoScript::ORM::MongoidAdapter do
     end
 
     it "returns the fields to get as :fields" do
-      ObjectWithMongoidAdapter.build_multiquery_parameters(criteria)[:fields].should == {_id: 1, _type: 1}
+      ObjectWithMongoidAdapter.build_multiquery_parameters(criteria)[:fields].should == {:_id => 1, :_type => 1}
     end
 
     it "returns all other options as :modifiers" do

data/spec/cases/mongoscript_spec.rb

@@ -18,7 +18,7 @@ describe MongoScript do
     end
 
     it "raises a NoORMError if no Mongo ORM is available" do
-      MongoScript.stubs(:const_defined?).with("Mongoid").returns(false)
+      Object.stubs(:const_defined?).with("Mongoid").returns(false)
       expect { MongoScript.orm_adapter }.to raise_exception(MongoScript::NoORMError)
     end
   end

data/spec/fixtures/mongoid.yml

@@ -1,5 +1,5 @@
 mongoscript_settings: &mongoscript_settings
-  host: localhost
+  host: 127.0.0.1
   database: mongoscript_dev
 
 development:

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mongoscript
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 0.0.9
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-02-27 00:00:00.000000000 Z
+date: 2012-03-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
-  requirement: &70212414216240 !ruby/object:Gem::Requirement
+  requirement: &70280991269600 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,7 +21,7 @@ dependencies:
         version: '3.0'
   type: :runtime
   prerelease: false
-  version_requirements: *70212414216240
+  version_requirements: *70280991269600
 description: An experimental Ruby library for running serverside Javascript in MongoDB.
 email:
 - alex+git@alexkoppel.com
@@ -30,6 +30,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .travis.yml
 - Gemfile
 - Guardfile
 - Rakefile
@@ -56,7 +57,7 @@ files:
 - spec/spec_helper.rb
 - spec/support/mongoid.yml
 - spec/support/mongoid_classes.rb
-homepage: ''
+homepage: http://github.com/arsduo/mongoscript
 licenses: []
 post_install_message: 
 rdoc_options: []