perpetuity 0.2 → 0.3

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+## Version 0.3
+
+- Add `Mapper#save` to update an object's current state in the DB
+- Fix `select` calls using `id` as criteria
+- Switch from `Mongo::Connection` to `Mongo::MongoClient`
+  - This makes MongoDB reads and writes fail fast
+- Add indexing interface
+- Silence warnings
+- Raise when calling Mapper[] with unmapped class
+- Add unions and intersections to select queries for MongoDB adapter
+  - This allows for queries like `Perpetuity[Article].select { (created_at < Time.now) & (published == true) }`
+- Update object in memory when calling `Mapper#update`
+- Allow subclassing of `Perpetuity::Mapper` with map macro
+- Use `Perpetuity[]` instead of `Perpetuity::Mapper[]` to get mapper instances
+
+*Version 0.2 and 0.1 have no changelog because I am a terrible developer*

data/LICENSE

@@ -0,0 +1,7 @@
+Copyright (C) Jamie Gaskins
+
+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.md

@@ -49,8 +49,8 @@ class Article
 end
 
 Perpetuity.generate_mapper_for Article do
-  attribute :title, String
-  attribute :body, String
+  attribute :title
+  attribute :body
 end
 
 article = Article.new
@@ -94,7 +94,9 @@ 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:
+The database can natively serialize some objects. For example, MongoDB can serialize `String`, `Numeric`, `Array`, `Hash`, `Time`, `nil`, `true`, `false`, and a few others. If an object references another type of object (such as an article referencing its author, a `User` object), the association is declared just as any other attribute. No special treatment is required.
+
+If the associated object's class has a mapper defined, it will be used by the parent object's mapper for serialization. Otherwise, the object will be `Marshal.dump`ed. If the object cannot be marshaled, the object cannot be serialized and an exception will be raised.
 
 ```ruby
 class User
@@ -102,17 +104,13 @@ 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
+  attribute :author
 end
 ```
 
@@ -125,6 +123,8 @@ article_mapper.load_association! article, :author
 user = article.author
 ```
 
+All loading of associated objects is explicit so that we don't load an entire object graph unnecessarily.
+
 ## Customizing persistence
 
 Setting the ID of a record to a custom value rather than using the DB default.
@@ -135,6 +135,48 @@ Perpetuity.generate_mapper_for Article do
 end
 ```
 
+## Indexing
+
+Indexes are declared with the `index` method. The simplest way to create an index is just to pass the attribute to be indexed as a parameter:
+
+```ruby
+Perpetuity.generate_mapper_for Article do
+  index :title
+end
+```
+
+The following will generate a unique index on an `Article` class so that two articles cannot be added to the database with the same title. This eliminates the need for uniqueness validations (like ActiveRecord has) that check for existence of that value. Uniqueness validations have race conditions and don't protect you at the database level. Using unique indexes is a superior way to do this.
+
+```ruby
+Perpetuity.generate_mapper_for Article do
+  index :title, unique: true
+end
+```
+
+Also, MongoDB, as well as some other databases, provide the ability to specify an order for the index. For example, if you want to query your blog with articles in descending order, you can specify a descending-order index on the timestamp for increased query performance.
+
+```ruby
+Perpetuity.generate_mapper_for Article do
+  index :timestamp, order: :descending
+end
+```
+
+### Applying indexes
+
+It's very important to keep in mind that specifying an index does not create it on the database immediately. If you did this, you could potentially introduce downtime every time you specify a new index and deploy your application.
+
+In order to apply indexes to the database, you must send `reindex!` to the mapper. For example:
+
+```ruby
+class ArticleMapper < Perpetuity::Mapper
+  map Article
+  attribute :title
+  index :title, unique: true
+end
+
+Perpetuity[Article].reindex!
+```
+
 ## 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/lib/perpetuity/attribute.rb

@@ -11,7 +11,11 @@ module Perpetuity
     end
 
     def embedded?
-      @embedded
+      @embedded ||= false
+    end
+
+    def to_s
+      name
     end
   end
 end

data/lib/perpetuity/attribute_set.rb

@@ -17,7 +17,7 @@ module Perpetuity
     end
 
     def each &block
-      @attributes.each &block
+      @attributes.each(&block)
     end
   end
 end

data/lib/perpetuity/mapper.rb

@@ -2,37 +2,50 @@ require 'perpetuity/attribute_set'
 require 'perpetuity/attribute'
 require 'perpetuity/validations'
 require 'perpetuity/data_injectable'
-require 'perpetuity/mongodb/query'
+require 'perpetuity/mapper_registry'
+require 'perpetuity/serializer'
 
 module Perpetuity
   class Mapper
     include DataInjectable
-    attr_accessor :object, :original_object
 
-    def initialize(klass=Object, &block)
+    def self.generate_for(klass, &block)
+      mapper = Class.new(base_class, &block)
+      mapper.map klass
+    end
+
+    def self.map klass
+      MapperRegistry[klass] = self
       @mapped_class = klass
-      instance_exec &block if block_given?
     end
 
-    def self.generate_for(klass=Object, &block)
-      mapper = new(klass, &block)
-      mappers[klass] = mapper
+    def self.attribute_set
+      @attribute_set ||= AttributeSet.new
     end
 
-    def self.mappers
-      @mappers ||= {}
+    def self.attribute name, options = {}
+      type = options.fetch(:type) { nil }
+      attribute_set << Attribute.new(name, type, options)
     end
 
-    def attribute_set
-      @attribute_set ||= AttributeSet.new
+    def self.attributes
+      attribute_set.map(&:name)
     end
 
-    def attribute name, type, options = {}
-      attribute_set << Attribute.new(name, type, options)
+    def self.index attribute
+      data_source.index mapped_class, attribute_set[attribute]
+    end
+
+    def indexes
+      data_source.indexes(mapped_class)
+    end
+
+    def reindex!
+      indexes.each { |index| data_source.activate_index! index }
     end
 
     def attributes
-      attribute_set.map(&:name)
+      self.class.attributes
     end
 
     def delete_all
@@ -40,9 +53,9 @@ module Perpetuity
     end
 
     def insert object
-      raise "#{object} is invalid and cannot be persisted." unless validations.valid?(object)
+      raise "#{object} is invalid and cannot be persisted." unless self.class.validations.valid?(object)
       serializable_attributes = serialize(object)
-      if o_id = object.instance_exec(&id)
+      if o_id = object.instance_exec(&self.class.id)
         serializable_attributes[:id] = o_id
       end
 
@@ -52,70 +65,29 @@ module Perpetuity
     end
 
     def serialize object
-      attrs = {}
-      attribute_set.each do |attrib|
-        value = object.send(attrib.name)
-        attrib_name = attrib.name.to_s
-
-        if value.respond_to? :each
-          attrs[attrib_name] = serialize_enumerable(value)
-        elsif data_source.can_serialize? value
-          attrs[attrib_name] = value
-        elsif Mapper[value.class]
-          if attrib.embedded?
-            attrs[attrib_name] = Mapper[value.class].serialize(value).merge '__metadata__' =>  { 'class' => value.class }
-          else
-            attrs[attrib_name] = {
-              '__metadata__' =>  {
-                'class' => value.class.to_s,
-                'id' => value.id
-              }
-            }
-          end
-        else
-          if attrib.embedded?
-            attrs[attrib_name] = Marshal.dump(value)
-          end
-        end
-      end
-
-      attrs
-    end
-
-    def serialize_enumerable enum
-      enum.map do |value|
-        if value.respond_to? :each
-          serialize_enumerable(value)
-        elsif data_source.can_serialize? value
-          value
-        elsif Mapper[value.class]
-          {
-            '__metadata__' => {
-              'class' => value.class.to_s
-            }
-          }.merge Mapper[value.class].serialize(value)
-        else
-          Marshal.dump(value)
-        end
-      end
+      Serializer.new(self).serialize(object)
     end
 
-    def self.[] klass
-      mappers[klass]
+    def self.data_source
+      Perpetuity.configuration.data_source
     end
 
     def data_source
-      Perpetuity.configuration.data_source
+      self.class.data_source
     end
 
     def count
       data_source.count mapped_class
     end
 
-    def mapped_class
+    def self.mapped_class
       @mapped_class
     end
 
+    def mapped_class
+      self.class.mapped_class
+    end
+
     def first
       data = data_source.first mapped_class
       object = mapped_class.new
@@ -159,10 +131,10 @@ module Perpetuity
       klass = reference.klass
       id = reference.id
 
-      inject_attribute object, attribute, Mapper[klass].find(id)
+      inject_attribute object, attribute, MapperRegistry[klass].find(id)
     end
 
-    def id &block
+    def self.id &block
       if block_given?
         @id = block
       else
@@ -170,21 +142,31 @@ module Perpetuity
       end
     end
 
-    def update object, new_data
+    def update object, new_data, update_in_memory = true
       id = object.is_a?(mapped_class) ? object.id : object
 
+      inject_data object, new_data if update_in_memory
       data_source.update mapped_class, id, new_data
     end
 
-    def validate &block
+    def save object
+      update object, serialize(object), false
+    end
+
+    def self.validate &block
       @validations ||= ValidationSet.new
 
       validations.instance_exec(&block)
     end
 
-    def validations
+    def self.validations
       @validations ||= ValidationSet.new
     end
+
+    private
+    def self.base_class
+      Mapper
+    end
   end
 end
 

data/lib/perpetuity/mapper_registry.rb

@@ -0,0 +1,17 @@
+module Perpetuity
+  class MapperRegistry
+    @mappers = Hash.new { |_, klass| raise KeyError, "No mapper for #{klass}" }
+
+    def self.has_mapper? klass
+      @mappers.has_key? klass
+    end
+
+    def self.[] klass
+      @mappers[klass].new
+    end
+
+    def self.[]= klass, mapper
+      @mappers[klass] = mapper
+    end
+  end
+end

data/lib/perpetuity/mongodb/index.rb

@@ -0,0 +1,48 @@
+module Perpetuity
+  class MongoDB
+    class Index
+      KEY_ORDERS = { 1 => :ascending, -1 => :descending }
+      attr_reader :collection, :attribute
+
+      def initialize klass, attribute, options={}
+        @collection = klass
+        @attribute = attribute
+        @unique = options.fetch(:unique) { false }
+        @order = options.fetch(:order) { :ascending }
+        @activated = false
+      end
+
+      def active?
+        @activated
+      end
+
+      def inactive?
+        !active?
+      end
+
+      def activate!
+        @activated = true
+      end
+
+      def unique?
+        @unique
+      end
+
+      def order
+        @order
+      end
+
+      def == other
+        hash == other.hash
+      end
+
+      def eql? other
+        self == other
+      end
+
+      def hash
+        "#{collection}/#{attribute}:#{unique?}:#{order}".hash
+      end
+    end
+  end
+end

data/lib/perpetuity/mongodb/query_expression.rb

@@ -1,3 +1,6 @@
+require 'perpetuity/mongodb/query_union'
+require 'perpetuity/mongodb/query_intersection'
+
 module Perpetuity
   class MongoDB
     class QueryExpression
@@ -50,6 +53,14 @@ module Perpetuity
       def matches
         { @attribute => @value }
       end
+
+      def | other
+        QueryUnion.new(self, other)
+      end
+
+      def & other
+        QueryIntersection.new(self, other)
+      end
     end
   end
 end

data/lib/perpetuity/mongodb/query_intersection.rb

@@ -0,0 +1,16 @@
+module Perpetuity
+  class MongoDB
+    class QueryIntersection
+      attr_reader :lhs, :rhs
+
+      def initialize lhs, rhs
+        @lhs = lhs
+        @rhs = rhs
+      end
+
+      def to_db
+        { '$and' => [lhs.to_db, rhs.to_db] }
+      end
+    end
+  end
+end

data/lib/perpetuity/mongodb/query_union.rb

@@ -0,0 +1,16 @@
+module Perpetuity
+  class MongoDB
+    class QueryUnion
+      attr_reader :lhs, :rhs
+
+      def initialize lhs, rhs
+        @lhs = lhs
+        @rhs = rhs
+      end
+
+      def to_db
+        { '$or' => [lhs.to_db, rhs.to_db] }
+      end
+    end
+  end
+end

data/lib/perpetuity/mongodb.rb

@@ -1,4 +1,6 @@
 require 'mongo'
+require 'perpetuity/mongodb/query'
+require 'perpetuity/mongodb/index'
 
 module Perpetuity
   class MongoDB
@@ -12,11 +14,12 @@ module Perpetuity
       @username   = options[:username]
       @password   = options[:password]
       @connection = nil
+      @indexes    = Hash.new { |hash, key| hash[key] = active_indexes(key) }
     end
 
     def connect
       database.authenticate(@username, @password) if @username and @password
-      @connection ||= Mongo::Connection.new @host, @port, pool_size: @pool_size
+      @connection ||= Mongo::MongoClient.new @host, @port, pool_size: @pool_size
     end
 
     def connected?
@@ -61,12 +64,11 @@ module Perpetuity
 
       # 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 }
-          ]
-        }
+        if criteria[:id].is_a? String
+          criteria = { _id: BSON::ObjectId.from_string(criteria[:id].to_s) }
+        else
+          criteria[:_id] = criteria.delete(:id)
+        end
       end
 
       sort_field = options[:attribute]
@@ -103,6 +105,41 @@ module Perpetuity
       serializable_types.include? value.class
     end
 
+    def drop_collection to_be_dropped
+      collection(to_be_dropped).drop
+    end
+
+    def index klass, attribute, options={}
+      @indexes[klass] ||= Set.new
+
+      index = Index.new(klass, attribute, options)
+      @indexes[klass] << index 
+      index
+    end
+
+    def indexes klass
+      @indexes[klass]
+    end
+
+    def active_indexes klass
+      indexes = collection(klass).index_information
+      indexes.map do |name, index|
+        key = index['key'].keys.first
+        direction = index['key'][key]
+        unique = index['unique']
+        Index.new(klass, key, order: Index::KEY_ORDERS[direction], unique: unique)
+      end.to_set
+    end
+
+    def activate_index! index
+      attribute = index.attribute.to_s
+      order = index.order == :ascending ? 1 : -1
+      unique = index.unique?
+
+      collection(index.collection).create_index [[attribute, order]], unique: unique
+      index.activate!
+    end
+
     private
     def serializable_types
       @serializable_types ||= [NilClass, TrueClass, FalseClass, Fixnum, Float, String, Array, Hash, Time]

data/lib/perpetuity/serializer.rb

@@ -0,0 +1,75 @@
+require 'perpetuity/mapper_registry'
+
+module Perpetuity
+  class Serializer
+    attr_reader :mapper
+
+    def initialize(mapper)
+      @mapper = mapper
+    end
+
+    def attribute_for object, attribute_name
+      if object.respond_to? attribute_name
+        object.send(attribute_name)
+      else
+        object.instance_variable_get("@#{attribute_name}")
+      end
+    end
+
+    def serialize object
+      attrs = mapper.class.attribute_set.map do |attrib|
+        value = attribute_for object, attrib.name
+
+        serialized_value = if value.is_a? Array
+          serialize_array(value)
+        elsif mapper.data_source.can_serialize? value
+          value
+        elsif MapperRegistry.has_mapper?(value.class)
+          serialize_with_foreign_mapper(value, attrib.embedded?)
+        else
+          if attrib.embedded?
+            Marshal.dump(value)
+          end
+        end
+
+        [attrib.name.to_s, serialized_value]
+      end
+
+      Hash[attrs]
+    end
+
+    def serialize_with_foreign_mapper value, embedded = false
+      if embedded
+        value_mapper = MapperRegistry[value.class]
+        value_serializer = Serializer.new(value_mapper)
+        attr = value_serializer.serialize(value)
+        attr.merge '__metadata__' =>  { 'class' => value.class }
+      else
+        {
+          '__metadata__' =>  {
+            'class' => value.class.to_s,
+            'id' => value.id
+          }
+        }
+      end
+    end
+
+    def serialize_array enum
+      enum.map do |value|
+        if value.is_a? Array
+          serialize_array(value)
+        elsif mapper.data_source.can_serialize? value
+          value
+        elsif MapperRegistry.has_mapper?(value.class)
+          {
+            '__metadata__' => {
+              'class' => value.class.to_s
+            }
+          }.merge MapperRegistry[value.class].serialize(value)
+        else
+          Marshal.dump(value)
+        end
+      end
+    end
+  end
+end

data/lib/perpetuity/version.rb

@@ -1,3 +1,3 @@
 module Perpetuity
-  VERSION = "0.2"
+  VERSION = "0.3"
 end

data/lib/perpetuity.rb

@@ -10,7 +10,7 @@ module Perpetuity
   end
   
   def self.configuration
-    @@configuration ||= Configuration.new
+    @configuration ||= Configuration.new
   end
 
   def self.generate_mapper_for klass, &block
@@ -18,6 +18,6 @@ module Perpetuity
   end
 
   def self.[] klass
-    Mapper[klass]
+    MapperRegistry[klass]
   end
 end

data/perpetuity.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |s|
   s.email       = ["jgaskins@gmail.com"]
   s.homepage    = "https://github.com/jgaskins/perpetuity.git"
   s.summary     = %q{Persistence library allowing serialization of Ruby objects}
-  s.description = %q{Persistence layer Ruby objects}
+  s.description = %q{Persistence layer for Ruby objects}
 
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
@@ -19,7 +19,6 @@ Gem::Specification.new do |s|
   # specify any dependencies here; for example:
   s.add_development_dependency "rake"
   s.add_development_dependency "rspec", "~> 2.8.0"
-  s.add_development_dependency "guard-rspec"
-  s.add_runtime_dependency "mongo"
+  s.add_runtime_dependency "mongo", ">= 1.8.0"
   s.add_runtime_dependency "bson_ext"
 end

data/spec/perpetuity/mapper_registry_spec.rb

@@ -0,0 +1,15 @@
+require 'perpetuity/mapper_registry'
+
+module Perpetuity
+  describe MapperRegistry do
+    subject { described_class }
+    let(:mapper) { Class.new }
+
+    before { MapperRegistry[Object] = mapper }
+
+    it { should have_mapper Object }
+    it 'maps classes to instances of their mappers' do
+      MapperRegistry[Object].should be_a mapper
+    end
+  end
+end