perpetuity 0.1

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/.rspec

@@ -0,0 +1 @@
+--colour

data/.rvmrc

@@ -0,0 +1 @@
+rvm use @perpetuity --create

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+rvm:
+  - 1.9.2
+  - 1.9.3
+  - rbx-19mode
+services:
+  - mongodb

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+
+gemspec

data/Guardfile

@@ -0,0 +1,24 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard 'rspec', :version => 2 do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+
+  # Rails example
+  watch(%r{^app/(.+)\.rb$})                           { |m| "spec/#{m[1]}_spec.rb" }
+  watch(%r{^app/(.*)(\.erb|\.haml)$})                 { |m| "spec/#{m[1]}#{m[2]}_spec.rb" }
+  watch(%r{^app/controllers/(.+)_(controller)\.rb$})  { |m| ["spec/routing/#{m[1]}_routing_spec.rb", "spec/#{m[2]}s/#{m[1]}_#{m[2]}_spec.rb", "spec/acceptance/#{m[1]}_spec.rb"] }
+  watch(%r{^spec/support/(.+)\.rb$})                  { "spec" }
+  watch('config/routes.rb')                           { "spec/routing" }
+  watch('app/controllers/application_controller.rb')  { "spec/controllers" }
+
+  # Capybara request specs
+  watch(%r{^app/views/(.+)/.*\.(erb|haml)$})          { |m| "spec/requests/#{m[1]}_spec.rb" }
+
+  # Turnip features and steps
+  watch(%r{^spec/acceptance/(.+)\.feature$})
+  watch(%r{^spec/acceptance/steps/(.+)_steps\.rb$})   { |m| Dir[File.join("**/#{m[1]}.feature")][0] || 'spec/acceptance' }
+end
+

data/README.md

@@ -0,0 +1,142 @@
+# Perpetuity [![Build Status](https://secure.travis-ci.org/jgaskins/perpetuity.png)](http://travis-ci.org/jgaskins/perpetuity)
+
+Perpetuity is a simple Ruby object persistence layer that attempts to follow Martin Fowler's Data Mapper pattern, allowing you to use plain-old Ruby objects in your Ruby apps in order to decouple your domain logic from the database as well as speed up your tests. There is no need for your model classes to inherit from another class or even include a mix-in.
+
+Your objects will hopefully eventually be able to be persisted into whichever database you like. Right now, only MongoDB is supported. Other persistence solutions will come later.
+
+This gem was inspired by [a blog post by Steve Klabnik](http://blog.steveklabnik.com/posts/2011-12-30-active-record-considered-harmful).
+
+## How it works
+
+In the Data Mapper pattern, the objects you work with don't understand how to persist themselves. They interact with other objects just as in any other object-oriented application, leaving all persistence logic to mapper objects. This decouples them from the database and allows you to write your code without it in mind.
+
+## Installation
+
+Add the following to your Gemfile and run `bundle` to install it.
+
+```ruby
+gem 'perpetuity', github: 'jgaskins/perpetuity'
+```
+
+Once it's got enough functionality to release, you'll be able to remove the `github` parameter.
+
+## Configuration
+
+The only currently supported persistence method is MongoDB. Other schemaless solutions can probably be implemented easily.
+
+```ruby
+mongodb = Perpetuity::MongoDB.new host: 'mongodb.example.com', db: 'example_db'
+Perpetuity.configure do 
+  data_source mongodb
+end
+```
+
+## Setting up object mappers
+
+Object mappers are generated by the following:
+
+```ruby
+Perpetuity.generate_mapper_for MyClass do
+  # individual mapper configuration goes here
+end
+```
+
+The primary mapper configuration will be configuring attributes to be persisted. This is done using the `attribute` method. Calling `attribute` will add the specified attribute and its class to the mapper's attribute set. This is how the mapper knows what to store and how to store it. Here is an example of an `Article` class, its mapper and how it can be saved to the database.
+
+Accessing mappers after they've been generated is done through the use of the subscript operator on the `Perpetuity` module. For example, if you generate a mapper for an `Article` class, you can access it by calling `Perpetuity[Article]`.
+
+```ruby
+class Article
+  attr_accessor :title, :body
+end
+
+Perpetuity.generate_mapper_for Article do
+  attribute :title, String
+  attribute :body, String
+end
+
+article = Article.new
+article.title = 'New Article'
+article.body = 'This is an article.'
+
+Perpetuity[Article].insert article
+```
+
+## Loading Objects
+
+You can load all persisted objects of a particular class by sending `all` to the mapper object. Example:
+
+```ruby
+Perpetuity[Article].all
+```
+
+You can load specific objects by calling the `find` method with an ID param on that class's mapper class and passing in the criteria. You may also specify more general criteria using the `select` method with a block similar to `Enumerable#select`.
+
+```ruby
+article  = Perpetuity[Article].find params[:id]
+users    = Perpetuity[User].select { email == 'me@example.com' }
+articles = Perpetuity[Article].select { published_at < Time.now }
+comments = Perpetuity[Comment].select { article_id.in articles.map(&:id) }
+```
+
+Unfortunately, due to limitations in the Ruby language itself, this is as close as I could get to a true `Enumerable`-style select method. Once I can override `&&` and `||`, we can put more Rubyesque code in here.
+
+These methods will return a Perpetuity::Retrieval object, which will lazily retrieve the objects from the database. They will wait to hit the DB when you begin iterating over the objects so you can continue chaining methods.
+
+```ruby
+article_mapper = Perpetuity[Article]
+articles = article_mapper.select { published_at < Time.now }
+articles = articles.sort(:published_at).reverse
+articles = articles.page(2).per_page(10) # built-in pagination
+
+articles.each do |article| # This is when the DB gets hit
+  # Display the pretty articles
+end
+```
+
+## Associations with Other Objects
+
+If an object references another object (such as an article referencing its author), it must have a relationship identifier in its mapper class. For example:
+
+```ruby
+class User
+end
+
+class Article
+  attr_accessor :author
+
+  def initialize(author)
+    self.author = author
+  end
+end
+
+Perpetuity.generate_mapper_for User do
+end
+
+Perpetuity.generate_mapper_for Article do
+  attribute :author, User # Notice the author's class
+end
+```
+
+This allows you to write the following:
+
+```ruby
+article_mapper = Perpetuity[Article]
+article = article_mapper.first
+article_mapper.load_association! article, :author
+user = article.author
+```
+
+## Customizing persistence
+
+Setting the ID of a record to a custom value rather than using the DB default.
+
+```ruby
+Perpetuity.generate_mapper_for Article do
+  id { title.gsub(/\W+/, '-') } # use the article's parameterized title attribute as its ID
+end
+```
+
+## Contributing
+
+Right now, this code is pretty bare and there are possibly some design decisions that need some more refinement. You can help. If you have ideas to build on this, send some love in the form of pull requests or issues or tweets or e-mails and I'll do what I can for them.

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/lib/perpetuity/attribute.rb

@@ -0,0 +1,17 @@
+module Perpetuity
+  class Attribute
+    attr_reader :name, :type
+    def initialize(name, type, options = {})
+      @name = name
+      @type = type
+
+      options.each do |option, value|
+        instance_variable_set "@#{option}", value
+      end
+    end
+
+    def embedded?
+      @embedded
+    end
+  end
+end

data/lib/perpetuity/attribute_set.rb

@@ -0,0 +1,23 @@
+require 'set'
+
+module Perpetuity
+  class AttributeSet
+    include Enumerable
+
+    def initialize
+      @attributes = Set.new
+    end
+
+    def << attribute
+      @attributes << attribute
+    end
+
+    def [] name
+      @attributes.find { |attr| attr.name == name }
+    end
+
+    def each &block
+      @attributes.each &block
+    end
+  end
+end

data/lib/perpetuity/config.rb

@@ -0,0 +1,11 @@
+module Perpetuity
+  class Configuration
+    def data_source *args
+      if args.any?
+        @db = args.pop
+      end
+
+      @db
+    end
+  end
+end

data/lib/perpetuity/data_injectable.rb

@@ -0,0 +1,21 @@
+module Perpetuity
+  module DataInjectable
+    def inject_data object, data
+      data.each_pair do |attribute,value|
+        if object.respond_to?("#{attribute}=")
+          object.send("#{attribute}=", value)
+        else
+          attribute = "@#{attribute}" unless attribute[0] == '@'
+          object.instance_variable_set(attribute, value)
+        end
+      end
+      give_id_to object if object.instance_variables.include?(:@id)
+    end
+
+    def give_id_to object, *args
+      object.define_singleton_method :id do
+        args.first || object.instance_variable_get(:@id)
+      end
+    end
+  end
+end

data/lib/perpetuity/mapper.rb

@@ -0,0 +1,195 @@
+require 'perpetuity/attribute_set'
+require 'perpetuity/attribute'
+require 'perpetuity/validations'
+require 'perpetuity/data_injectable'
+require 'perpetuity/mongodb/query'
+
+module Perpetuity
+  class Mapper
+    include DataInjectable
+    attr_accessor :object, :original_object
+
+    def initialize(klass=Object, &block)
+      @mapped_class = klass
+      instance_exec &block if block_given?
+    end
+
+    def self.generate_for(klass=Object, &block)
+      mapper = new(klass, &block)
+      mappers[klass] = mapper
+    end
+
+    def self.mappers
+      @mappers ||= {}
+    end
+
+    def attribute_set
+      @attribute_set ||= AttributeSet.new
+    end
+
+    def attribute name, type, options = {}
+      attribute_set << Attribute.new(name, type, options)
+    end
+
+    def attributes
+      attribute_set.map(&:name)
+    end
+
+    def delete_all
+      data_source.delete_all mapped_class
+    end
+
+    def serializable_types
+      @serializable_types ||= [NilClass, TrueClass, FalseClass, Fixnum, Bignum, Float, String, Array, Hash, Time, Date]
+    end
+
+    def insert object
+      raise "#{object} is invalid and cannot be persisted." unless validations.valid?(object)
+      serializable_attributes = {}
+      if o_id = object.instance_exec(&id)
+        serializable_attributes[:id] = o_id
+      end
+
+      attributes_for(object).each_pair do |attribute, value|
+        if serializable_types.include? value.class
+          serializable_attributes[attribute] = value
+        elsif value.respond_to?(:id)
+          serializable_attributes[attribute] = value.id
+        else
+          raise "Must persist #{attribute} (#{value.inspect}) before persisting this #{object.inspect}."
+        end
+      end
+
+      new_id = data_source.insert mapped_class, serializable_attributes
+      give_id_to object, new_id
+      new_id
+    end
+
+    def attributes_for object
+      attrs = {}
+      attribute_set.each do |attrib|
+        value = object.send(attrib.name)
+
+        if attrib.type == Array
+          new_array = []
+          value.each do |i|
+            if serializable_types.include? i.class
+              new_array << i
+            else
+              if attrib.embedded?
+                new_array << Marshal.dump(i)
+              else
+                new_array << i.id
+              end
+            end
+          end
+
+          attrs[attrib.name] = new_array
+        else
+          attrs[attrib.name] = value
+        end
+      end
+      attrs
+    end
+
+    def unserialize(data)
+      if data.is_a?(String) && data.start_with?("\u0004")
+        Marshal.load(data)
+      elsif data.is_a? Array
+        data.map { |i| unserialize i }
+      elsif data.is_a? Hash
+        Hash[data.map{|k,v| [k, unserialize(v)]}]
+      else
+        data
+      end
+    end
+
+    def self.[] klass
+      mappers[klass]
+    end
+
+    def data_source
+      Perpetuity.configuration.data_source
+    end
+
+    def count
+      data_source.count mapped_class
+    end
+
+    def mapped_class
+      @mapped_class
+    end
+
+    def first
+      data = data_source.first mapped_class
+      object = mapped_class.new
+      inject_data object, data
+
+      object
+    end
+
+    def all
+      results = data_source.all mapped_class
+      objects = []
+      results.each do |result|
+        object = mapped_class.new
+        inject_data object, result
+
+        objects << object
+      end
+
+      objects
+    end
+
+    def retrieve criteria={}
+      Perpetuity::Retrieval.new mapped_class, criteria
+    end
+
+    def select &block
+      query = data_source.class::Query.new(&block).to_db
+      retrieve query
+    end
+
+    def find id
+      retrieve(id: id).first
+    end
+
+    def delete object
+      data_source.delete object, mapped_class
+    end
+
+    def load_association! object, attribute
+      class_name = attribute_set[attribute].type
+      id = object.send(attribute)
+
+      mapper = Mapper[class_name]
+      associated_object = mapper.find(id)
+      object.send("#{attribute}=", associated_object)
+    end
+
+    def id &block
+      if block_given?
+        @id = block
+      else
+        @id ||= -> { nil }
+      end
+    end
+
+    def update object, new_data
+      id = object.is_a?(mapped_class) ? object.id : object
+
+      data_source.update mapped_class, id, new_data
+    end
+
+    def validate &block
+      @validations ||= ValidationSet.new
+
+      validations.instance_exec(&block)
+    end
+
+    def validations
+      @validations ||= ValidationSet.new
+    end
+  end
+end
+

data/lib/perpetuity/mongodb/query.rb

@@ -0,0 +1,19 @@
+require 'perpetuity/mongodb/query_attribute'
+
+module Perpetuity
+  class MongoDB
+    class Query
+      def initialize &block
+        @query = instance_exec(&block)
+      end
+
+      def to_db
+        @query.to_db
+      end
+
+      def method_missing missing_method
+        QueryAttribute.new missing_method
+      end
+    end
+  end
+end

data/lib/perpetuity/mongodb/query_attribute.rb

@@ -0,0 +1,49 @@
+require 'perpetuity/mongodb/query_expression'
+
+module Perpetuity
+  class MongoDB
+    class QueryAttribute
+      attr_reader :name
+
+      def initialize name
+        @name = name
+      end
+
+      def == value
+        QueryExpression.new self, :equals, value
+      end
+
+      def < value
+        QueryExpression.new self, :less_than, value
+      end
+
+      def >= value
+        QueryExpression.new self, :gte, value
+      end
+
+      def > value
+        QueryExpression.new self, :greater_than, value
+      end
+
+      def <= value
+        QueryExpression.new self, :lte, value
+      end
+
+      def not_equal? value
+        QueryExpression.new self, :not_equal, value
+      end
+
+      def =~ regexp
+        QueryExpression.new self, :matches, regexp
+      end
+
+      def in collection
+        QueryExpression.new self, :in, collection
+      end
+
+      def to_sym
+        name
+      end
+    end
+  end
+end

data/lib/perpetuity/mongodb/query_expression.rb

@@ -0,0 +1,55 @@
+module Perpetuity
+  class MongoDB
+    class QueryExpression
+      attr_accessor :comparator
+
+      def initialize attribute, comparator, value
+        @attribute = attribute
+        @comparator = comparator
+        @value = value
+
+        @attribute = @attribute.to_sym if @attribute.respond_to? :to_sym
+      end
+
+      def to_db
+        send @comparator
+      end
+
+      def equals
+        { @attribute => @value }
+      end
+
+      def function func
+        { @attribute => { func => @value } }
+      end
+
+      def less_than
+        function '$lt'
+      end
+
+      def lte
+        function '$lte'
+      end
+
+      def greater_than
+        function '$gt'
+      end
+
+      def gte
+        function '$gte'
+      end
+
+      def not_equal
+        function '$ne'
+      end
+
+      def in
+        function '$in'
+      end
+
+      def matches
+        { @attribute => @value }
+      end
+    end
+  end
+end

data/lib/perpetuity/mongodb.rb

@@ -0,0 +1,102 @@
+require 'mongo'
+
+module Perpetuity
+  class MongoDB
+    attr_accessor :connection, :host, :port, :db, :pool_size, :username, :password
+
+    def initialize options
+      @host       = options.fetch(:host, 'localhost')
+      @port       = options.fetch(:port, 27017)
+      @db         = options.fetch(:db)
+      @pool_size  = options.fetch(:pool_size, 5)
+      @username   = options[:username]
+      @password   = options[:password]
+      @connection = nil
+    end
+
+    def connect
+      database.authenticate(@username, @password) if @username and @password
+      @connection ||= Mongo::Connection.new @host, @port, pool_size: @pool_size
+    end
+
+    def connected?
+      !!@connection
+    end
+
+    def database
+      connect unless connected?
+      @connection.db(@db)
+    end
+
+    def collection klass
+      database.collection(klass.to_s)
+    end
+
+    def insert klass, attributes
+      if attributes.has_key? :id
+        attributes[:_id] = attributes[:id]
+        attributes.delete :id
+      end
+
+      collection(klass).insert attributes
+    end
+
+    def count klass
+      collection(klass).count
+    end
+
+    def delete_all klass
+      database.collection(klass.to_s).remove
+    end
+
+    def first klass
+      document = database.collection(klass.to_s).find_one
+      document[:id] = document.delete("_id")
+
+      document
+    end
+
+    def retrieve klass, criteria, options = {}
+      objects = []
+
+      # MongoDB uses '_id' as its ID field.
+      if criteria.has_key?(:id)
+        criteria = {
+          '$or' => [
+            { _id: BSON::ObjectId.from_string(criteria[:id].to_s) },
+            { _id: criteria[:id].to_s }
+          ]
+        }
+      end
+
+      sort_field = options[:attribute]
+      sort_direction = options[:direction]
+      sort_criteria = [[sort_field, sort_direction]]
+      other_options = { limit: options[:limit] }
+      if options[:page]
+        other_options = other_options.merge skip: (options[:page] - 1) * options[:limit]
+      end
+
+      database.collection(klass.to_s).find(criteria, other_options).sort(sort_criteria).each do |document|
+        document[:id] = document.delete("_id")
+        objects << document
+      end
+
+      objects
+    end
+
+    def all klass
+      retrieve klass, {}, {}
+    end
+    
+    def delete object, klass=nil
+      id = object.respond_to?(:id) ? object.id : object
+      klass ||= object.class
+      collection(klass.to_s).remove "_id" => id
+    end
+
+    def update klass, id, new_data
+      collection(klass).update({ _id: id }, new_data)
+    end
+  end
+end