mongoid-multi-db 3.0.0

data/lib/mongoid/paranoia.rb

@@ -0,0 +1,158 @@
+# encoding: utf-8
+module Mongoid #:nodoc:
+
+  # Include this module to get soft deletion of root level documents.
+  # This will add a deleted_at field to the +Document+, managed automatically.
+  # Potentially incompatible with unique indices. (if collisions with deleted items)
+  #
+  # @example Make a document paranoid.
+  #   class Person
+  #     include Mongoid::Document
+  #     include Mongoid::Paranoia
+  #   end
+  module Paranoia
+    extend ActiveSupport::Concern
+
+    included do
+      field :deleted_at, :type => Time
+    end
+
+    # Delete the paranoid +Document+ from the database completely. This will
+    # run the destroy callbacks.
+    #
+    # @example Hard destroy the document.
+    #   document.destroy!
+    #
+    # @return [ true, false ] If the operation succeeded.
+    #
+    # @since 1.0.0
+    def destroy!
+      run_callbacks(:destroy) { delete! }
+    end
+
+    # Delete the paranoid +Document+ from the database completely.
+    #
+    # @example Hard delete the document.
+    #   document.delete!
+    #
+    # @return [ true, false ] If the operation succeeded.
+    #
+    # @since 1.0.0
+    def delete!
+      Persistence::Operations.remove(self).persist
+    end
+
+    # Delete the +Document+, will set the deleted_at timestamp and not actually
+    # delete it.
+    #
+    # @example Soft remove the document.
+    #   document.remove
+    #
+    # @param [ Hash ] options The database options.
+    #
+    # @return [ true ] True.
+    #
+    # @since 1.0.0
+    def remove(options = {})
+      time = self.deleted_at = Time.now
+      paranoid_collection.update(
+        atomic_selector,
+        { "$set" => { paranoid_field => time }},
+        Safety.merge_safety_options(options)
+      )
+      cascade!
+      @destroyed = true
+      IdentityMap.remove(self)
+      Threaded.clear_options!
+      true
+    end
+    alias :delete :remove
+
+    # Determines if this document is destroyed.
+    #
+    # @example Is the document destroyed?
+    #   person.destroyed?
+    #
+    # @return [ true, false ] If the document is destroyed.
+    #
+    # @since 1.0.0
+    def destroyed?
+      @destroyed || !!deleted_at
+    end
+
+    # Restores a previously soft-deleted document. Handles this by removing the
+    # deleted_at flag.
+    #
+    # @example Restore the document from deleted state.
+    #   document.restore
+    #
+    # @return [ Time ] The time the document had been deleted.
+    #
+    # @since 1.0.0
+    def restore
+      paranoid_collection.update(
+        atomic_selector,
+        { "$unset" => { paranoid_field => true }}
+      )
+      attributes.delete("deleted_at")
+    end
+
+    private
+
+    # Get the collection to be used for paranoid operations.
+    #
+    # @example Get the paranoid collection.
+    #   document.paranoid_collection
+    #
+    # @return [ Collection ] The root collection.
+    #
+    # @since 2.3.1
+    def paranoid_collection
+      embedded? ? _root.collection : self.collection
+    end
+
+    # Get the field to be used for paranoid operations.
+    #
+    # @example Get the paranoid field.
+    #   document.paranoid_field
+    #
+    # @return [ String ] The deleted at field.
+    #
+    # @since 2.3.1
+    def paranoid_field
+      embedded? ? "#{atomic_position}.deleted_at" : "deleted_at"
+    end
+
+    module ClassMethods #:nodoc:
+
+      # Override the default +Criteria+ accessor to only get existing
+      # documents. Passes all arguments up to +NamedScope.criteria+
+      #
+      # @example Override the criteria.
+      #   Person.criteria
+      #
+      # @param [ Array ] args The arguments.
+      #
+      # @return [ Criteria ] The paranoid compliant criteria.
+      #
+      # @since 1.0.0
+      def criteria(embedded = false, scoped = true)
+        scoped ? super.where(:deleted_at => nil) : super
+      end
+
+      # Find deleted documents
+      #
+      # @example Find deleted documents.
+      #   Person.deleted
+      #   Company.first.employees.deleted
+      #   Person.deleted.find("4c188dea7b17235a2a000001").first
+      #
+      # @return [ Criteria ] The deleted criteria.
+      #
+      # @since 1.0.0
+      def deleted
+        where(:deleted_at.ne => nil)
+      end
+    end
+  end
+end

data/lib/mongoid/persistence.rb

@@ -0,0 +1,264 @@
+# encoding: utf-8
+require "mongoid/persistence/atomic"
+require "mongoid/persistence/deletion"
+require "mongoid/persistence/insertion"
+require "mongoid/persistence/modification"
+require "mongoid/persistence/operations"
+
+module Mongoid #:nodoc:
+
+  # The persistence module is a mixin to provide database accessor methods for
+  # the document. These correspond to the appropriate accessors on a
+  # mongo collection and retain the same DSL.
+  #
+  # @example Sample persistence operations.
+  #   document.insert
+  #   document.update
+  #   document.upsert
+  module Persistence
+    extend ActiveSupport::Concern
+    include Atomic
+
+    # Remove the document from the datbase with callbacks.
+    #
+    # @example Destroy a document.
+    #   document.destroy
+    #
+    # @param [ Hash ] options Options to pass to destroy.
+    #
+    # @return [ true, false ] True if successful, false if not.
+    def destroy(options = {})
+      run_callbacks(:destroy) { remove(options) }
+    end
+
+    # Insert a new document into the database. Will return the document
+    # itself whether or not the save was successful.
+    #
+    # @example Insert a document.
+    #   document.insert
+    #
+    # @param [ Hash ] options Options to pass to insert.
+    #
+    # @return [ Document ] The persisted document.
+    def insert(options = {})
+      Operations.insert(self, options).persist
+    end
+
+    # Remove the document from the datbase.
+    #
+    # @example Remove the document.
+    #   document.remove
+    #
+    # @param [ Hash ] options Options to pass to remove.
+    #
+    # @return [ TrueClass ] True.
+    def remove(options = {})
+      Operations.remove(self, options).persist
+    end
+    alias :delete :remove
+
+    # Save the document - will perform an insert if the document is new, and
+    # update if not. If a validation error occurs an error will get raised.
+    #
+    # @example Save the document.
+    #   document.save!
+    #
+    # @param [ Hash ] options Options to pass to the save.
+    #
+    # @return [ true, false ] True if validation passed.
+    def save!(options = {})
+      unless upsert(options)
+        self.class.fail_validate!(self) if errors.any?
+        self.class.fail_callback!(self, :save!)
+      end
+      return true
+    end
+
+    # Update the document in the datbase.
+    #
+    # @example Update an existing document.
+    #   document.update
+    #
+    # @param [ Hash ] options Options to pass to update.
+    #
+    # @return [ true, false ] True if succeeded, false if not.
+    def update(options = {})
+      Operations.update(self, options).persist
+    end
+
+    # Update a single attribute and persist the entire document.
+    # This skips validation but fires the callbacks.
+    #
+    # @example Update the attribute.
+    #   person.update_attribute(:title, "Sir")
+    #
+    # @param [ Symbol, String ] name The name of the attribute.
+    # @param [ Object ] value The new value of the attribute.a
+    #
+    # @return [ true, false ] True if save was successfull, false if not.
+    #
+    # @since 2.0.0.rc.6
+    def update_attribute(name, value)
+      write_attribute(name, value)
+      save(:validate => false)
+    end
+
+    # Update the document attributes in the datbase.
+    #
+    # @example Update the document's attributes
+    #   document.update_attributes(:title => "Sir")
+    #
+    # @param [ Hash ] attributes The attributes to update.
+    #
+    # @return [ true, false ] True if validation passed, false if not.
+    def update_attributes(attributes = {})
+      write_attributes(attributes); save
+    end
+
+    # Update the document attributes in the database and raise an error if
+    # validation failed.
+    #
+    # @example Update the document's attributes.
+    #   document.update_attributes(:title => "Sir")
+    #
+    # @param [ Hash ] attributes The attributes to update.
+    #
+    # @raise [ Errors::Validations ] If validation failed.
+    #
+    # @return [ true, false ] True if validation passed.
+    def update_attributes!(attributes = {})
+      update_attributes(attributes).tap do |result|
+        unless result
+          self.class.fail_validate!(self) if errors.any?
+          self.class.fail_callback!(self, :update_attributes!)
+        end
+      end
+    end
+
+    # Upsert the document - will perform an insert if the document is new, and
+    # update if not.
+    #
+    # @example Upsert the document.
+    #   document.upsert
+    #
+    # @param [ Hash ] options Options to pass to the upsert.
+    #
+    # @return [ true, false ] True is success, false if not.
+    def upsert(options = {})
+      if new_record?
+        insert(options).persisted?
+      else
+        update(options)
+      end
+    end
+    alias :save :upsert
+
+    module ClassMethods #:nodoc:
+
+      # Create a new document. This will instantiate a new document and
+      # insert it in a single call. Will always return the document
+      # whether save passed or not.
+      #
+      # @example Create a new document.
+      #   Person.create(:title => "Mr")
+      #
+      # @param [ Hash ] attributes The attributes to create with.
+      # @param [ Hash ] options A mass-assignment protection options. Supports
+      #   :as and :without_protection
+      #
+      # @return [ Document ] The newly created document.
+      def create(attributes = {}, options = {}, &block)
+        _creating do
+          new(attributes, options, &block).tap { |doc| doc.save }
+        end
+      end
+
+      # Create a new document. This will instantiate a new document and
+      # insert it in a single call. Will always return the document
+      # whether save passed or not, and if validation fails an error will be
+      # raise.
+      #
+      # @example Create a new document.
+      #   Person.create!(:title => "Mr")
+      #
+      # @param [ Hash ] attributes The attributes to create with.
+      # @param [ Hash ] options A mass-assignment protection options. Supports
+      #   :as and :without_protection
+      #
+      # @return [ Document ] The newly created document.
+      def create!(attributes = {}, options = {}, &block)
+        _creating do
+          new(attributes, options, &block).tap do |doc|
+            fail_validate!(doc) if doc.insert.errors.any?
+            fail_callback!(doc, :create!) if doc.new?
+          end
+        end
+      end
+
+      # Delete all documents given the supplied conditions. If no conditions
+      # are passed, the entire collection will be dropped for performance
+      # benefits. Does not fire any callbacks.
+      #
+      # @example Delete matching documents from the collection.
+      #   Person.delete_all(:conditions => { :title => "Sir" })
+      #
+      # @example Delete all documents from the collection.
+      #   Person.delete_all
+      #
+      # @param [ Hash ] conditions Optional conditions to delete by.
+      #
+      # @return [ Integer ] The number of documents deleted.
+      def delete_all(conditions = nil)
+        selector = (conditions || {})[:conditions] || {}
+        selector.merge!(:_type => name) if hereditary?
+        collection.find(selector).count.tap do
+          collection.remove(selector, Safety.merge_safety_options)
+          Threaded.clear_options!
+        end
+      end
+
+      # Delete all documents given the supplied conditions. If no conditions
+      # are passed, the entire collection will be dropped for performance
+      # benefits. Fires the destroy callbacks if conditions were passed.
+      #
+      # @example Destroy matching documents from the collection.
+      #   Person.destroy_all(:conditions => { :title => "Sir" })
+      #
+      # @example Destroy all documents from the collection.
+      #   Person.destroy_all
+      #
+      # @param [ Hash ] conditions Optional conditions to destroy by.
+      #
+      # @return [ Integer ] The number of documents destroyed.
+      def destroy_all(conditions = {})
+        documents = all(conditions)
+        documents.count.tap do
+          documents.each { |doc| doc.destroy }
+        end
+      end
+
+      # Raise an error if validation failed.
+      #
+      # @example Raise the validation error.
+      #   Person.fail_validate!(person)
+      #
+      # @param [ Document ] document The document to fail.
+      def fail_validate!(document)
+        raise Errors::Validations.new(document)
+      end
+
+      # Raise an error if a callback failed.
+      #
+      # @example Raise the callback error.
+      #   Person.fail_callback!(person, :create!)
+      #
+      # @param [ Document ] document The document to fail.
+      # @param [ Symbol ] method The method being called.
+      #
+      # @since 2.2.0
+      def fail_callback!(document, method)
+        raise Errors::Callback.new(document.class, method)
+      end
+    end
+  end
+end

data/lib/mongoid/persistence/atomic.rb

@@ -0,0 +1,223 @@
+# encoding: utf-8
+require "mongoid/persistence/atomic/operation"
+require "mongoid/persistence/atomic/add_to_set"
+require "mongoid/persistence/atomic/bit"
+require "mongoid/persistence/atomic/inc"
+require "mongoid/persistence/atomic/pop"
+require "mongoid/persistence/atomic/pull"
+require "mongoid/persistence/atomic/pull_all"
+require "mongoid/persistence/atomic/push"
+require "mongoid/persistence/atomic/push_all"
+require "mongoid/persistence/atomic/rename"
+require "mongoid/persistence/atomic/sets"
+require "mongoid/persistence/atomic/unset"
+
+module Mongoid #:nodoc:
+  module Persistence #:nodoc:
+
+    # This module provides the explicit atomic operations helpers on the
+    # document itself.
+    module Atomic
+
+      # Performs an atomic $addToSet of the provided value on the supplied field.
+      # If the field does not exist it will be initialized as an empty array.
+      #
+      # If the value already exists on the array it will not be added.
+      #
+      # @example Add only a unique value on the field.
+      #   person.add_to_set(:aliases, "Bond")
+      #
+      # @param [ Symbol ] field The name of the field.
+      # @param [ Object ] value The value to add.
+      # @param [ Hash ] options The mongo persistence options.
+      #
+      # @return [ Array<Object> ] The new value of the field.
+      #
+      # @since 2.0.0
+      def add_to_set(field, value, options = {})
+        AddToSet.new(self, field, value, options).persist
+      end
+
+      # Performs an atomic $bit operation on the field with the provided hash
+      # of bitwise ops to execute in order.
+      #
+      # @example Execute a bitwise and on the field.
+      #   person.bit(:age, { :and => 12 })
+      #
+      # @example Execute a bitwise or on the field.
+      #   person.bit(:age, { :or => 12 })
+      #
+      # @example Execute a chain of bitwise operations.
+      #   person.bit(:age, { :and => 10, :or => 12 })
+      #
+      # @param [ Symbol ] field The name of the field.
+      # @param [ Hash ] value The bitwise operations to perform.
+      # @param [ Hash ] options The mongo persistence options.
+      #
+      # @return [ Integer ] The new value of the field.
+      #
+      # @since 2.1.0
+      def bit(field, value, options = {})
+        Bit.new(self, field, value, options).persist
+      end
+
+      # Performs an atomic $inc of the provided value on the supplied
+      # field. If the field does not exist it will be initialized as
+      # the provided value.
+      #
+      # @example Increment a field.
+      #   person.inc(:score, 2)
+      #
+      # @param [ Symbol ] field The name of the field.
+      # @param [ Integer ] value The value to increment.
+      # @param [ Hash ] options The mongo persistence options.
+      #
+      # @return [ Array<Object> ] The new value of the field.
+      #
+      # @since 2.0.0
+      def inc(field, value, options = {})
+        Inc.new(self, field, value, options).persist
+      end
+
+      # Performs an atomic $pop of the provided value on the supplied
+      # field.
+      #
+      # @example Pop the last value from the array.
+      #   person.pop(:aliases, 1)
+      #
+      # @example Pop the first value from the array.
+      #   person.pop(:aliases, -1)
+      #
+      # @param [ Symbol ] field The name of the field.
+      # @param [ Integer ] value Whether to pop the first or last.
+      # @param [ Hash ] options The mongo persistence options.
+      #
+      # @return [ Array<Object> ] The new value of the field.
+      #
+      # @since 2.1.0
+      def pop(field, value, options = {})
+        Pop.new(self, field, value, options).persist
+      end
+
+      # Performs an atomic $pull of the provided value on the supplied
+      # field.
+      #
+      # @note Support for a $pull with an expression is not yet supported.
+      #
+      # @example Pull the value from the field.
+      #   person.pull(:aliases, "Bond")
+      #
+      # @param [ Symbol ] field The name of the field.
+      # @param [ Object ] value The value to pull.
+      # @param [ Hash ] options The mongo persistence options.
+      #
+      # @return [ Array<Object> ] The new value of the field.
+      #
+      # @since 2.1.0
+      def pull(field, value, options = {})
+        Pull.new(self, field, value, options).persist
+      end
+
+      # Performs an atomic $pullAll of the provided value on the supplied
+      # field. If the field does not exist it will be initialized as an
+      # empty array.
+      #
+      # @example Pull the values from the field.
+      #   person.pull_all(:aliases, [ "Bond", "James" ])
+      #
+      # @param [ Symbol ] field The name of the field.
+      # @param [ Array<Object> ] value The values to pull.
+      # @param [ Hash ] options The mongo persistence options.
+      #
+      # @return [ Array<Object> ] The new value of the field.
+      #
+      # @since 2.0.0
+      def pull_all(field, value, options = {})
+        PullAll.new(self, field, value, options).persist
+      end
+
+      # Performs an atomic $push of the provided value on the supplied field. If
+      # the field does not exist it will be initialized as an empty array.
+      #
+      # @example Push a value on the field.
+      #   person.push(:aliases, "Bond")
+      #
+      # @param [ Symbol ] field The name of the field.
+      # @param [ Object ] value The value to push.
+      # @param [ Hash ] options The mongo persistence options.
+      #
+      # @return [ Array<Object> ] The new value of the field.
+      #
+      # @since 2.0.0
+      def push(field, value, options = {})
+        Push.new(self, field, value, options).persist
+      end
+
+      # Performs an atomic $pushAll of the provided value on the supplied field. If
+      # the field does not exist it will be initialized as an empty array.
+      #
+      # @example Push the values onto the field.
+      #   person.push_all(:aliases, [ "Bond", "James" ])
+      #
+      # @param [ Symbol ] field The name of the field.
+      # @param [ Array<Object> ] value The values to push.
+      # @param [ Hash ] options The mongo persistence options.
+      #
+      # @return [ Array<Object> ] The new value of the field.
+      #
+      # @since 2.1.0
+      def push_all(field, value, options = {})
+        PushAll.new(self, field, value, options).persist
+      end
+
+      # Performs the atomic $rename from the old field to the new field name.
+      #
+      # @example Rename the field.
+      #   person.rename(:age, :years)
+      #
+      # @param [ Symbol ] field The old field name.
+      # @param [ Symbol ] value The new field name.
+      # @param [ Hash ] options The mongo persistence options.
+      #
+      # @return [ Object ] The value of the new field.
+      #
+      # @since 2.1.0
+      def rename(field, value, options = {})
+        Rename.new(self, field, value, options).persist
+      end
+
+      # Performs an atomic $set of the provided value on the supplied
+      # field. If the field does not exist it will be initialized as
+      # the provided value.
+      #
+      # @example Set a field.
+      #   person.set(:score, 2)
+      #
+      # @param [ Symbol ] field The name of the field.
+      # @param [ Integer ] value The value to set.
+      # @param [ Hash ] options The mongo persistence options.
+      #
+      # @return [ Array<Object> ] The new value of the field.
+      #
+      # @since 2.1.0
+      def set(field, value = nil, options = {})
+        Sets.new(self, field, value, options).persist
+      end
+
+      # Performs the atomic $unset on the supplied field.
+      #
+      # @example Remove the field.
+      #   person.unset(:age)
+      #
+      # @param [ Symbol ] field The field name.
+      # @param [ Hash ] options The mongo persistence options.
+      #
+      # @return [ nil ] Always nil.
+      #
+      # @since 2.1.0
+      def unset(field, options = {})
+        Unset.new(self, field, 1, options).persist
+      end
+    end
+  end
+end