kongo 1.0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in kongo.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,15 @@
+The Azure License
+
+Copyright (c) 2011 Kenneth Ballenegger
+
+Attribute to Kenneth Ballenegger - http://kswizz.com/
+
+You (the licensee) are hereby granted permission, free of charge, to deal in this software or source code (this "Software") without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, and/or sublicense this Software, subject to the following conditions:
+
+You must give attribution to the party mentioned above, by name and by hyperlink, in the about box, credits document and/or documentation of any derivative work using a substantial portion of this Software.
+
+You may not use the name of the copyright holder(s) to endorse or promote products derived from this Software without specific prior written permission.
+
+THIS 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 THIS SOFTWARE OR THE USE OR OTHER DEALINGS IN THIS SOFTWARE.
+
+http://license.azuretalon.com/

data/README.md

@@ -0,0 +1,204 @@
+# Kongo
+
+Kongo is a lightweight and generic library for accessing data from Mongo.
+
+## Rationale
+
+Kongo is not your typical ORM. Traditionally, according to MVC architecture best practices, you would create a model class to represent data from each collection in your application. However, while it is a good abstraction early on, as an application grows and scales, it is not uncommon to see models grow to thousands of lines of code, grouping together many different pieces of unrelated business logic. Not only that, but dependencies and tight coupling arises between the various related models.
+
+Kongo takes a different approach. Kongo does not have models, it simply provides basic data-access functionality and object-oriented wrapping of the Mongo driver. It also provides support for extending collections and models with libraries. Kongo believes logic belongs in libraries, and related code belongs in the same file, not divided amongst multiple models and mixed with other logic.
+
+## Usage
+
+Using Kongo is fairly straight-forward.
+
+First, however, Kongo must know how to connect to Mongo (put this in a init / config type file):
+
+```ruby
+db = Mongo::Connection.new(...)['dbname']
+Kongo::Collection.fetch_collections_using do |collection_name|
+  # In larger applications you would insert logic here to figure out
+  # how to connect to Mongo, when you have multiple replicated or
+  # sharded clusters...
+  db[collection_name]
+end
+```
+
+Then, simply define your collections as you use them. (It's okay to do this in multiple contexts).
+
+```ruby
+Posts = Kongo::Collection.new(:posts)
+Comments = Kongo::Collection.new(:comments)
+```
+
+You can use a collection to read data:
+
+```ruby
+post = Posts.find_by_id(id)
+
+# this returns a cursor
+comments = Comments.find_many(post: post._id)
+
+# get a json of the top ten comments
+top = comments.sort(score: -1)
+json = top.to_enum.take(10).map(:&to_hash).to_json
+```
+
+All Kongo methods yield `Kongo::Model` objects whenever possible. These objects simply wrap around a `Hash` and provide some helper methods for dealing with the object.
+
+Perhaps the most useful of these helpers is `update!`:
+
+```ruby
+# Kongo encourages only performing atomic updates:
+
+# simple setters change the data and record the appropriate delta
+post.title = 'New title!'
+post.date = Time.now.to_i
+# more advanced deltas can be set explicitly. see mongo update syntax for documentation.
+post.delta('$inc', edit_count: 1)
+
+# the update! method commits deltas.
+post.update!
+```
+
+This is just the tip of the iceberg. See the documentation for the Kongo classes to see everything that Kongo can do.
+
+### Writing an extension
+
+Imagine you have three models, `user`, `account`, and `transaction`. You want to make a library that will let you transfer money between users and their accounts. Typically you'd add code to your three existing model classes:
+
+models/user.rb:
+
+```ruby
+require 'models/account'
+
+class User < Model
+
+  # a whole bunch of random crap
+  # ...
+
+  def earnings
+    Account::find_by_id(self['earnings_account'])
+  end
+  def spend
+    Account::find_by_id(sefl['spend_account'])
+  end
+end
+```
+
+models/account.rb:
+
+```ruby
+require 'models/transaction'
+class Account < Model
+  # more random crap
+  def deposit; ...; end
+
+  def transfer_to(other_account, amount)
+    if Transaction.create(self, other_account, amount})
+    self.update!('$inc', amount: (-1 * amount))
+    other_account('$inc', amount: amount)
+  end
+end
+```
+
+models/transaction.rb:
+
+```ruby
+class Transaction < Model
+  def self.create(from, to, amount)
+    if from.balance >= amount
+      insert!({form: from['_id'], to: to['_id'], amount: amount})
+      true
+    else
+      false
+    end
+  end
+end
+```
+
+Now we have code related to the same thing in three different model files, and it's all mixed up with the other functionality of these models (such as analytics for transactions or authentication for the user model).
+
+Instead, if we have the possibility of abstracting this into a library, we might have something much cleaner like a single `lib/finance.rb` file:
+
+```ruby
+module Finance
+
+  # other finance functionality that does not belong directly to a
+  # model, eg something like inance::convert_currency
+  # our finance extensions to the models:
+
+  module Extensions
+    module User
+      def earnings
+        Account::find_by_id(self['earnings_account'])
+      end
+      def spend
+        Account::find_by_id(sefl['spend_account'])
+      end
+    end
+    Kongo::Model.add_extension(:users, User)
+
+    module Transactions
+      def create(from, to, amount)
+        if from.balance >= amount
+          insert!({form: from['_id'], to: to['_id'], amount: amount})
+          true
+        else
+          false
+        end
+      end
+    end
+    Kongo::Collection.add_extension(:transactions, Transactions)
+
+    TransactionsCollection = Kongo::Collection.new(:transactions)
+    module Account
+      def deposit; ...; end
+      def transfer_to(other_account, amount)
+        if TransactionsCollection.create(self, other_account, amount})
+        self.update!('$inc', amount: (-1 * amount))
+        other_account('$inc', amount: amount)
+      end
+    end
+    Kongo::Model.add_extension(:accounts, Account)
+
+  end
+
+  # The Account and Transaction "models" belong to the finance library,
+  # in that it is their primary function. So we provide constants for them:
+  Acounts = Kongo::Collection.new(:accounts)
+  Transactions = Kongo::Collection.new(:transactions)
+end
+```
+
+Using this extension is now straight-forward:
+
+```ruby
+require 'lib/authentication' # imagine this lib provides user-related functionality
+require 'lib/finance'
+user = Authentication.current_user
+kenneth = Authentication::Users.find_one(email: 'kenneth@ballenegger.com')
+user.transfer_to(kenneth, 100)
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'kongo'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install kongo
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (```git checkout -b my-new-feature```)
+3. Commit your changes (```git commit -am 'Add some feature'```)
+4. Push to the branch (```git push origin my-new-feature```)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/kongo.gemspec

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'kongo/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = 'kongo'
+  gem.version       = Kongo::VERSION
+  gem.authors       = ['Kenneth Ballenegger']
+  gem.email         = ['kenneth@ballenegger.com']
+  gem.description   = %q{Kongo is a lightweight and generic library for accessing data from Mongo.}
+  gem.summary       = %q{Kongo is a lightweight and generic library for accessing data from Mongo.}
+  gem.homepage      = 'https://github.com/kballenegger/Kongo'
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ['lib']
+  
+  gem.add_dependency('mongo', '>= 1.7.0')
+end

data/lib/kongo.rb

@@ -0,0 +1,348 @@
+
+require 'mongo'
+
+
+module Kongo
+
+  class Collection
+
+    # Initialize with a collection name (as symbol), will use that collection
+    # name to generate the connection lazily when it is first used, thru the
+    # collection callback (*must* be defined).
+    #
+    def initialize(name)
+      @coll_name = name
+      @visible_ivars = []
+      @@extensions ||= {}
+
+      if @@extensions[name.to_sym]
+        @@extensions[name.to_sym].each do |const|
+          extend(const)
+        end
+      end
+    end
+
+    # `find_one` and `find_by_id` are the same method. When passed a native
+    # BSON::ObjectId, it will act as a find_by_id, otherwise, expects a regular
+    # query hash. Will return a Kongo::Model.
+    #
+    def find_one(*args)
+      (r = coll.find_one(*args)) ?
+        Model.new(r, coll) : r
+    end
+    alias :find_by_id :find_one
+
+    # `find`, aka. `find_many` returns a Kongo::Cursor wrapping the Mongo
+    # cursor.
+    #
+    def find(*args)
+      (c = coll.find(*args)).is_a?(::Mongo::Cursor) ?
+        Cursor.new(c, coll) : c
+    end
+    alias :find_many :find
+
+    # Count, just forwards to driver.
+    #
+    def count(*args)
+      coll.count(*args)
+    end
+
+    # Verify existence of record by id.
+    #
+    def has?(id)
+      count(:query => {_id: id}) == 1
+    end
+
+    # Insert a record, returns a Model object.
+    #
+    def insert!(hash)
+      coll.insert(hash)
+      Model.new(hash, coll)
+    end
+
+    # Collection#extend adds the option of extending with a symbol, which
+    # will automatically use that constant from Extensions::Collections,
+    # calls super in every other case.
+    #
+    def extend(arg)
+      super(arg.is_a?(Symbol) ? Extensions::Collections.const_get(arg) : arg)
+    end
+
+
+    # This method must be called statically on the ORM once before being used,
+    # so that the ORM knows how to connect to mongo and fetch collections.
+    #
+    # A simple usage example might look like this:
+    #
+    #   class MongoCollectionFetcher
+    #     def self.fetch(name)
+    #       unless @mongo
+    #         @mongo = Mongo::Connection.new
+    #       end
+    #       return @mongo['database'][name.to_s]
+    #     end
+    #   end
+    #
+    #   Kongo::Collection.fetch_collections_using do |n|
+    #     MongoCollectionFetcher.fetch(n)
+    #   end
+    #
+    def self.fetch_collections_using(&block)
+      @@collection_fetcher = block
+    end
+
+
+    # This method returns the Mongo::Collection object for this collection.
+    #
+    def coll
+      return @coll if @coll
+
+      raise 'Kongo has not been initialized with a collection fetcher.' unless @@collection_fetcher
+      @coll = @@collection_fetcher.call(@coll_name)
+      @coll
+    end
+
+
+
+    # Inspecting a Mongo Model attempts to only show *useful* information,
+    # such as what its extensions are as well as certain ivars.
+    # 
+    def inspect
+      proxy = Object.new
+      @visible_ivars.each do |ivar|
+        val = instance_variable_get(ivar)
+        proxy.instance_variable_set(ivar, val) unless val.nil?
+      end
+      string = proxy.inspect
+      ext_info = @extensions ? '(+ '+@extensions.join(', ')+')' : ''
+      string.gsub(/Object:0x[0-9a-f]+/, "Kongo::Collection#{ext_info}:0x#{object_id}")
+    end
+
+
+    # Declare extensions using this method:
+    #
+    #   Kongo::Collection.add_extension(:collection_name, module)
+    #
+    def self.add_extension(collection_name, mod)
+      ((@@extensions ||= {})[collection_name.to_sym] ||= []) << mod
+    end
+
+    # This method just adds the extension to the list of extension, for the
+    # sake of inspect, and call super:
+    #
+    def extend(const)
+      (@extensions ||= []) << const.to_s
+      super
+    end
+
+  end
+
+
+  # Cursor is an object that wraps around a Mongo::Cursor, wrapping objects it
+  # returns in Kongo::Model objects.
+  #
+  class Cursor
+
+    # `initialize` is typically only used internally by Kongo::Collection when
+    # it returns cursors.
+    #
+    def initialize(cursor, coll)
+      @coll = coll
+      @cursor = cursor
+    end
+
+    # Any method is forwarded to its wrapped cursor.
+    #
+    def method_missing(*args, &block)
+      @cursor.send(*args, &block)
+    end
+
+    # `next` wraps responses in Kongo::Model.
+    #
+    def next
+      (e = @cursor.next).is_a?(Hash) ?
+        Model.new(e, @coll) : e
+    end
+
+    # `each` yields Kongo::Model objects.
+    #
+    def each
+      @cursor.each { |e| yield Model.new(e, @coll) }
+    end
+    
+    # `to_enum` returns an Enumerator which yields the results of the cursor.
+    # 
+    def to_enum
+      Enumerator.new do |yielder|
+        while @cursor.has_next?
+          yielder.yield(self.next)
+        end
+      end
+    end
+
+    # `to_a` returns an array of Kongo::Model.
+    #
+    def to_a
+      arr = []
+      each { |e| arr << e }
+      arr
+    end
+  end
+
+
+  # Kongo::Model is the most important class of Kongo, it wraps around hashes
+  # representing Mongo records, provides a collection of useful methods, and
+  # allows itself to be extended by third party libraries.
+  #
+  class Model
+
+    # Typically, you would not call Model#new directly, but rather get
+    # a model from a method on Collections, such as a finder or #insert.
+    #
+    def initialize(hash, coll)
+      @coll = coll
+      @hash = hash
+      @deltas = {}
+      @visible_ivars = [:@hash, :@deltas]
+      @@extensions ||= {}
+
+      if @@extensions[coll.name.to_sym]
+        @@extensions[coll.name.to_sym].each do |const|
+          extend(const)
+        end
+      end
+    end
+
+    attr_reader :hash
+    attr_reader :deltas
+
+    # Record fields can be accessed using [] syntax.
+    #
+    def [](k); @hash[k]; end
+
+    # This adds to the list of deltas, so that we may update with no
+    # arguments below
+    #
+    def []=(k,v)
+      @hash[k.to_s]=v
+
+      delta('$set', k => v)
+    end
+
+    # Add a delta
+    #
+    #   delta '$inc',
+    #     total: 3,
+    #     unique: 1
+    #
+    def delta(type, fields = {})
+      fields.each do |k,v|
+        @deltas[type.to_s] ||= {}
+        @deltas[type.to_s][k.to_s] = v
+      end
+      self
+    end
+
+    # `unset` lets you remove a key from the hash, as well as adding it to
+    # the deltas so that the next update will unset that key in Mongo.
+    #
+    def unset(key)
+      @hash.delete(key.to_s)
+      delta('$unset', key => 1)
+    end
+
+    # This method_missing provides accessors for keys as proprieties of the
+    # model object, so you may do:
+    #
+    #   object.key = :value
+    #   object.key #=> :value
+    #
+    def method_missing(key, *args, &block)
+      key = key.to_s
+      if matches = /^(.+)=$/.match(key)
+        raise ArgumentError.new 'Unexpected argument count.' if args.count != 1
+        self[matches[1]] = args.first
+      else
+        raise ArgumentError.new 'Unexpected argument count.' if args.count != 0
+        return self[key]
+      end
+    end
+
+    # @deprecated
+    # Do not use saves, they're dirty.
+    #
+    def save!(options = {})
+      warn("#{Kernel.caller.first}: `save` is deprecated, use `update` instead.")
+      raise if @stale unless options[:ignore_stale] # TODO: custom exception
+      @coll.save(@hash, :safe => true)
+    end
+
+    # Issues an update on the database, for this record, with the provided
+    # deltas. WARNING: the record will become stale, and should no longer be
+    # saved after an update has been issued.
+    #
+    def update!(deltas = {})
+      return if @deltas.empty?
+
+      id = @hash['_id']
+      raise unless id # TODO: custom exception
+
+      if @deltas
+        deltas = @deltas.merge(deltas)
+        @deltas = {}
+      end
+
+      @stale = true
+
+      @coll.update({_id: id}, deltas, :safe => true)
+    end
+
+    # Deletes this record from the database.
+    #
+    def delete!
+      id = @hash['_id']
+      raise unless id # TODO: custom exception
+      @coll.remove({_id: id})
+    end
+
+    # Returns the hash of the record itself.
+    #
+    def to_hash
+      @hash
+    end
+
+    # Inspecting a Mongo Model attempts to only show *useful* information,
+    # such as what its extensions are as well as certain ivars.
+    # 
+    def inspect
+      proxy = Object.new
+      @visible_ivars.each do |ivar|
+        val = instance_variable_get(ivar)
+        proxy.instance_variable_set(ivar, val) unless val.nil?
+      end
+      string = proxy.inspect
+      ext_info = @extensions ? '(+ '+@extensions.join(', ')+')' : ''
+      string.gsub(/Object:0x[0-9a-f]+/, "Kongo::Model#{ext_info}:0x#{object_id}")
+    end
+
+
+
+    # Declare extensions using this method:
+    #
+    #   Kongo::Model.add_extension(:collection_name, module)
+    #
+    def self.add_extension(collection_name, mod)
+      ((@@extensions ||= {})[collection_name.to_sym] ||= []) << mod
+    end
+
+    # This method just adds the extension to the list of extension, for the
+    # sake of inspect, and call super:
+    #
+    def extend(const)
+      (@extensions ||= []) << const.to_s
+      super
+    end
+
+  end
+
+end

data/lib/kongo/version.rb

@@ -0,0 +1,3 @@
+module Kongo
+  VERSION = '1.0'
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: kongo
+version: !ruby/object:Gem::Version
+  version: '1.0'
+  prerelease: 
+platform: ruby
+authors:
+- Kenneth Ballenegger
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-02-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mongo
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.7.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.7.0
+description: Kongo is a lightweight and generic library for accessing data from Mongo.
+email:
+- kenneth@ballenegger.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- kongo.gemspec
+- lib/kongo.rb
+- lib/kongo/version.rb
+homepage: https://github.com/kballenegger/Kongo
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Kongo is a lightweight and generic library for accessing data from Mongo.
+test_files: []
+has_rdoc: