mongoid 3.1.6 → 4.0.0

data/lib/mongoid/persistable/pullable.rb

@@ -0,0 +1,55 @@
+# encoding: utf-8
+module Mongoid
+  module Persistable
+
+    # Defines behaviour for $pull and $pullAll operations.
+    #
+    # @since 4.0.0
+    module Pullable
+      extend ActiveSupport::Concern
+
+      # Pull single values from the provided arrays.
+      #
+      # @example Pull a value from the array.
+      #   document.pull(names: "Jeff", levels: 5)
+      #
+      # @note If duplicate values are found they will all be pulled.
+      #
+      # @param [ Hash ] pulls The field/value pull pairs.
+      #
+      # @return [ true, false ] If the operation succeeded.
+      #
+      # @since 4.0.0
+      def pull(pulls)
+        prepare_atomic_operation do |ops|
+          process_atomic_operations(pulls) do |field, value|
+            (send(field) || []).delete(value)
+            ops[atomic_attribute_name(field)] = value
+          end
+          { "$pull" => ops }
+        end
+      end
+
+      # Pull multiple values from the provided array fields.
+      #
+      # @example Pull values from the arrays.
+      #   document.pull_all(names: [ "Jeff", "Bob" ], levels: [ 5, 6 ])
+      #
+      # @param [ Hash ] pulls The pull all operations.
+      #
+      # @return [ true, false ] If the operation succeeded.
+      #
+      # @since 4.0.0
+      def pull_all(pulls)
+        prepare_atomic_operation do |ops|
+          process_atomic_operations(pulls) do |field, value|
+            existing = send(field) || []
+            value.each{ |val| existing.delete(val) }
+            ops[atomic_attribute_name(field)] = value
+          end
+          { "$pullAll" => ops }
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/persistable/pushable.rb

@@ -0,0 +1,62 @@
+# encoding: utf-8
+module Mongoid
+  module Persistable
+
+    # Defines behaviour for $push and $addToSet operations.
+    #
+    # @since 4.0.0
+    module Pushable
+      extend ActiveSupport::Concern
+
+      # Add the single values to the arrays only if the value does not already
+      # exist in the array.
+      #
+      # @example Add the values to the sets.
+      #   document.add_to_set(names: "James", aliases: "Bond")
+      #
+      # @param [ Hash ] adds The field/value pairs to add.
+      #
+      # @return [ true, false ] If the operation succeeded.
+      #
+      # @since 4.0.0
+      def add_to_set(adds)
+        prepare_atomic_operation do |ops|
+          process_atomic_operations(adds) do |field, value|
+            existing = send(field) || (attributes[field] ||= [])
+            values = [ value ].flatten(1)
+            values.each do |val|
+              existing.push(val) unless existing.include?(val)
+            end
+            ops[atomic_attribute_name(field)] = { "$each" => values }
+          end
+          { "$addToSet" => ops }
+        end
+      end
+
+      # Push a single value or multiple values onto arrays.
+      #
+      # @example Push a single value onto arrays.
+      #   document.push(names: "James", aliases: "007")
+      #
+      # @example Push multiple values onto arrays.
+      #   document.push(names: [ "James", "Bond" ])
+      #
+      # @param [ Hash ] pushes The $push operations.
+      #
+      # @return [ true, false ] If the operation succeeded.
+      #
+      # @since 4.0.0
+      def push(pushes)
+        prepare_atomic_operation do |ops|
+          process_atomic_operations(pushes) do |field, value|
+            existing = send(field) || (attributes[field] ||= [])
+            values = [ value ].flatten(1)
+            values.each{ |val| existing.push(val) }
+            ops[atomic_attribute_name(field)] = { "$each" => values }
+          end
+          { "$push" => ops }
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/persistable/renamable.rb

@@ -0,0 +1,35 @@
+# encoding: utf-8
+module Mongoid
+  module Persistable
+
+    # Defines behaviour for $rename operations.
+    #
+    # @since 4.0.0
+    module Renamable
+      extend ActiveSupport::Concern
+
+      # Rename fields from one value to another via $rename.
+      #
+      # @example Rename the fields.
+      #   document.rename(title: "salutation", name: "nombre")
+      #
+      # @note This does not work for fields in embeds many relations.
+      #
+      # @param [ Hash ] renames The rename pairs of old name/new name.
+      #
+      # @return [ true, false ] If the rename suceeded.
+      #
+      # @since 4.0.0
+      def rename(renames)
+        prepare_atomic_operation do |ops|
+          process_atomic_operations(renames) do |old_field, new_field|
+            new_name = new_field.to_s
+            attributes[new_name] = attributes.delete(old_field)
+            ops[atomic_attribute_name(old_field)] = atomic_attribute_name(new_name)
+          end
+          { "$rename" => ops }
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/persistable/savable.rb

@@ -0,0 +1,52 @@
+# encoding: utf-8
+module Mongoid
+  module Persistable
+
+    # Defines behaviour for persistence operations that save documents.
+    #
+    # @since 4.0.0
+    module Savable
+
+      # Save the document - will perform an insert if the document is new, and
+      # update if not.
+      #
+      # @example Save the document.
+      #   document.save
+      #
+      # @param [ Hash ] options Options to pass to the save.
+      #
+      # @return [ true, false ] True is success, false if not.
+      #
+      # @since 1.0.0
+      def save(options = {})
+        if new_record?
+          !insert(options).new_record?
+        else
+          update_document(options)
+        end
+      end
+
+      # 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.
+      #
+      # @raise [ Errors::Validations ] If validation failed.
+      # @raise [ Errors::Callback ] If a callback returns false.
+      #
+      # @return [ true, false ] True if validation passed.
+      #
+      # @since 1.0.0
+      def save!(options = {})
+        unless save(options)
+          fail_due_to_validation! unless errors.empty?
+          fail_due_to_callback!(:save!)
+        end
+        true
+      end
+    end
+  end
+end

data/lib/mongoid/persistable/settable.rb

@@ -0,0 +1,33 @@
+# encoding: utf-8
+module Mongoid
+  module Persistable
+
+    # Defines behaviour for $set operations.
+    #
+    # @since 4.0.0
+    module Settable
+      extend ActiveSupport::Concern
+
+      # Perform a $set operation on the provided field/value pairs and set the
+      # values in the document in memory.
+      #
+      # @example Set the values.
+      #   document.set(title: "sir", dob: Date.new(1970, 1, 1))
+      #
+      # @param [ Hash ] setters The field/value pairs to set.
+      #
+      # @return [ true ] If the operation succeeded.
+      #
+      # @since 4.0.0
+      def set(setters)
+        prepare_atomic_operation do |ops|
+          process_atomic_operations(setters) do |field, value|
+            send("#{field}=", value)
+            ops[atomic_attribute_name(field)] = attributes[field]
+          end
+          { "$set" => ops }
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/persistable/unsettable.rb

@@ -0,0 +1,36 @@
+# encoding: utf-8
+module Mongoid
+  module Persistable
+
+    # Defines behaviour for $unset operations.
+    #
+    # @since 4.0.0
+    module Unsettable
+      extend ActiveSupport::Concern
+
+      # Perform an $unset operation on the provided fields and in the
+      # values in the document in memory.
+      #
+      # @example Unset the values.
+      #   document.unset(:first_name, :last_name, :middle)
+      #
+      # @param [ Array<String, Symbol> ] fields The names of the fields to
+      #   unset.
+      #
+      # @return [ true ] If the operation succeeded.
+      #
+      # @since 4.0.0
+      def unset(*fields)
+        prepare_atomic_operation do |ops|
+          fields.flatten.each do |field|
+            normalized = database_field_name(field)
+            attributes.delete(normalized)
+            ops[atomic_attribute_name(normalized)] = true
+          end
+          { "$unset" => ops }
+        end
+      end
+    end
+  end
+end
+

data/lib/mongoid/persistable/updatable.rb

@@ -0,0 +1,152 @@
+# encoding: utf-8
+module Mongoid
+  module Persistable
+
+    # Defines behaviour for persistence operations that update existing
+    # documents.
+    #
+    # @since 4.0.0
+    module Updatable
+
+      # 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
+      #
+      # @raise [ Errors::ReadonlyAttribute ] If the field cannot be changed due
+      #   to being flagged as reaodnly.
+      #
+      # @return [ true, false ] True if save was successfull, false if not.
+      #
+      # @since 2.0.0
+      def update_attribute(name, value)
+        normalized = name.to_s
+        unless attribute_writable?(normalized)
+          raise Errors::ReadonlyAttribute.new(normalized, value)
+        end
+        setter = "#{normalized}="
+        if respond_to?(setter)
+          send(setter, value)
+        else
+          write_attribute(database_field_name(normalized), value)
+        end
+        save(validate: false)
+      end
+
+      # Update the document attributes in the database.
+      #
+      # @example Update the document's attributes
+      #   document.update(:title => "Sir")
+      #
+      # @param [ Hash ] attributes The attributes to update.
+      #
+      # @return [ true, false ] True if validation passed, false if not.
+      #
+      # @since 1.0.0
+      def update(attributes = {})
+        assign_attributes(attributes)
+        save
+      end
+      alias :update_attributes :update
+
+      # Update the document attributes in the database and raise an error if
+      # validation failed.
+      #
+      # @example Update the document's attributes.
+      #   document.update!(:title => "Sir")
+      #
+      # @param [ Hash ] attributes The attributes to update.
+      #
+      # @raise [ Errors::Validations ] If validation failed.
+      # @raise [ Errors::Callbacks ] If a callback returns false.
+      #
+      # @return [ true, false ] True if validation passed.
+      #
+      # @since 1.0.0
+      def update!(attributes = {})
+        result = update_attributes(attributes)
+        unless result
+          fail_due_to_validation! unless errors.empty?
+          fail_due_to_callback!(:update_attributes!)
+        end
+        result
+      end
+      alias :update_attributes! :update!
+
+      private
+
+      # Initialize the atomic updates.
+      #
+      # @api private
+      #
+      # @example Initialize the atomic updates.
+      #   document.init_atomic_updates
+      #
+      # @return [ Array<Hash> ] The updates and conflicts.
+      #
+      # @since 4.0.0
+      def init_atomic_updates
+        updates = atomic_updates
+        conflicts = updates.delete(:conflicts) || {}
+        [ updates, conflicts ]
+      end
+
+      # Prepare the update for execution. Validates and runs callbacks, etc.
+      #
+      # @api private
+      #
+      # @example Prepare for update.
+      #   document.prepare_update do
+      #     collection.update(atomic_selector)
+      #   end
+      #
+      # @param [ Hash ] options The options.
+      #
+      # @return [ true, false ] The result of the update.
+      #
+      # @since 4.0.0
+      def prepare_update(options = {})
+        return false if performing_validations?(options) && invalid?(:update)
+        process_flagged_destroys
+        result = run_callbacks(:save) do
+          run_callbacks(:update) do
+            yield(self)
+            true
+          end
+        end
+        post_process_persist(result, options) and result
+      end
+
+      # Update the document in the database.
+      #
+      # @example Update an existing document.
+      #   document.update
+      #
+      # @param [ Hash ] options Options to pass to update.
+      #
+      # @option options [ true, false ] :validate Whether or not to validate.
+      #
+      # @return [ true, false ] True if succeeded, false if not.
+      #
+      # @since 1.0.0
+      def update_document(options = {})
+        raise Errors::ReadonlyDocument.new(self.class) if readonly?
+        prepare_update(options) do
+          updates, conflicts = init_atomic_updates
+          unless updates.empty?
+            coll = _root.collection
+            selector = atomic_selector
+            coll.find(selector).update(positionally(selector, updates))
+            conflicts.each_pair do |key, value|
+              coll.find(selector).update(positionally(selector, { key => value }))
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/persistable/upsertable.rb

@@ -0,0 +1,55 @@
+# encoding: utf-8
+module Mongoid
+  module Persistable
+
+    # Defines behaviour for persistence operations that upsert documents.
+    #
+    # @since 4.0.0
+    module Upsertable
+
+      # Perform an upsert of the document. If the document does not exist in the
+      # database, then Mongo will insert a new one, otherwise the fields will get
+      # overwritten with new values on the existing document.
+      #
+      # @example Upsert the document.
+      #   document.upsert
+      #
+      # @param [ Hash ] options The validation options.
+      #
+      # @return [ true ] True.
+      #
+      # @since 3.0.0
+      def upsert(options = {})
+        prepare_upsert(options) do
+          collection.find(atomic_selector).update(as_document, [ :upsert ])
+        end
+      end
+
+      private
+
+      # Prepare the upsert for execution.
+      #
+      # @api private
+      #
+      # @example Prepare the upsert
+      #   document.prepare_upsert do
+      #     collection.find(selector).update(as_document)
+      #   end
+      #
+      # @param [ Hash ] options The options hash.
+      #
+      # @return [ true, false ] If the operation succeeded.
+      #
+      # @since 4.0.0
+      def prepare_upsert(options = {})
+        return false if performing_validations?(options) && invalid?(:upsert)
+        result = run_callbacks(:upsert) do
+          yield(self)
+          true
+        end
+        self.new_record = false
+        post_process_persist(result, options) and result
+      end
+    end
+  end
+end

data/lib/mongoid/persistable.rb

@@ -0,0 +1,216 @@
+# encoding: utf-8
+require "mongoid/persistable/creatable"
+require "mongoid/persistable/deletable"
+require "mongoid/persistable/destroyable"
+require "mongoid/persistable/incrementable"
+require "mongoid/persistable/logical"
+require "mongoid/persistable/poppable"
+require "mongoid/persistable/pullable"
+require "mongoid/persistable/pushable"
+require "mongoid/persistable/renamable"
+require "mongoid/persistable/savable"
+require "mongoid/persistable/settable"
+require "mongoid/persistable/updatable"
+require "mongoid/persistable/upsertable"
+require "mongoid/persistable/unsettable"
+
+module Mongoid
+
+  # Contains general behaviour for persistence operations.
+  #
+  # @since 2.0.0
+  module Persistable
+    extend ActiveSupport::Concern
+    include Creatable
+    include Deletable
+    include Destroyable
+    include Incrementable
+    include Logical
+    include Poppable
+    include Positional
+    include Pullable
+    include Pushable
+    include Renamable
+    include Savable
+    include Settable
+    include Updatable
+    include Upsertable
+    include Unsettable
+
+    # The atomic operations that deal with arrays or sets in the db.
+    #
+    # @since 4.0.0
+    LIST_OPERATIONS = [ "$addToSet", "$push", "$pull", "$pullAll" ].freeze
+
+    # Execute operations atomically (in a single database call) for everything
+    # that would happen inside the block.
+    #
+    # @example Execute the operations atomically.
+    #   document.atomically do
+    #     document.set(name: "Tool").inc(likes: 10)
+    #   end
+    #
+    # @return [ true, false ] If the operation succeeded.
+    #
+    # @since 4.0.0
+    def atomically
+      begin
+        @atomic_updates_to_execute = {}
+        yield(self) if block_given?
+        persist_atomic_operations(@atomic_updates_to_execute)
+        true
+      ensure
+        @atomic_updates_to_execute = nil
+      end
+    end
+
+    # Raise an error if validation failed.
+    #
+    # @example Raise the validation error.
+    #   Person.fail_due_to_validation!(person)
+    #
+    # @param [ Document ] document The document to fail.
+    #
+    # @raise [ Errors::Validations ] The validation error.
+    #
+    # @since 4.0.0
+    def fail_due_to_validation!
+      raise Errors::Validations.new(self)
+    end
+
+    # Raise an error if a callback failed.
+    #
+    # @example Raise the callback error.
+    #   Person.fail_due_to_callback!(person, :create!)
+    #
+    # @param [ Document ] document The document to fail.
+    # @param [ Symbol ] method The method being called.
+    #
+    # @raise [ Errors::Callback ] The callback error.
+    #
+    # @since 4.0.0
+    def fail_due_to_callback!(method)
+      raise Errors::Callback.new(self.class, method)
+    end
+
+    private
+
+    # Are we executing an atomically block on the current document?
+    #
+    # @api private
+    #
+    # @example Are we executing atomically?
+    #   document.executing_atomically?
+    #
+    # @return [ true, false ] If we are current executing atomically.
+    #
+    # @since 4.0.0
+    def executing_atomically?
+      !@atomic_updates_to_execute.nil?
+    end
+
+    # Post process the persistence operation.
+    #
+    # @api private
+    #
+    # @example Post process the persistence operation.
+    #   document.post_process_persist(true)
+    #
+    # @param [ Object ] result The result of the operation.
+    # @param [ Hash ] options The options.
+    #
+    # @return [ true ] true.
+    #
+    # @since 4.0.0
+    def post_process_persist(result, options = {})
+      post_persist unless result == false
+      errors.clear unless performing_validations?(options)
+      true
+    end
+
+    # Prepare an atomic persistence operation. Yields an empty hash to be sent
+    # to the update.
+    #
+    # @api private
+    #
+    # @example Prepare the atomic operation.
+    #   document.prepare_atomic_operation do |coll, selector, opts|
+    #     ...
+    #   end
+    #
+    # @return [ Object ] The result of the operation.
+    #
+    # @since 4.0.0
+    def prepare_atomic_operation
+      operations = yield({})
+      persist_or_delay_atomic_operation(operations)
+      self
+    end
+
+    # Process the atomic operations - this handles the common behaviour of
+    # iterating through each op, getting the aliased field name, and removing
+    # appropriate dirty changes.
+    #
+    # @api private
+    #
+    # @example Process the atomic operations.
+    #   document.process_atomic_operations(pulls) do |field, value|
+    #     ...
+    #   end
+    #
+    # @param [ Hash ] operations The atomic operations.
+    #
+    # @return [ Hash ] The operations.
+    #
+    # @since 4.0.0
+    def process_atomic_operations(operations)
+      operations.each do |field, value|
+        unless attribute_writable?(field)
+          raise Errors::ReadonlyAttribute.new(field, value)
+        end
+        normalized = database_field_name(field)
+        yield(normalized, value)
+        remove_change(normalized)
+      end
+    end
+
+    # If we are in an atomically block, add the operations to the delayed group,
+    # otherwise persist immediately.
+    #
+    # @api private
+    #
+    # @example Persist immediately or delay the operations.
+    #   document.persist_or_delay_atomic_operation(ops)
+    #
+    # @param [ Hash ] operation The operation.
+    #
+    # @since 4.0.0
+    def persist_or_delay_atomic_operation(operation)
+      if executing_atomically?
+        operation.each do |(name, hash)|
+          @atomic_updates_to_execute[name] ||= {}
+          @atomic_updates_to_execute[name].merge!(hash)
+        end
+      else
+        persist_atomic_operations(operation)
+      end
+    end
+
+    # Persist the atomic operations.
+    #
+    # @api private
+    #
+    # @example Persist the atomic operations.
+    #   persist_atomic_operations(ops)
+    #
+    # @param [ Hash ] operations The atomic operations.
+    #
+    # @since 4.0.0
+    def persist_atomic_operations(operations)
+      if persisted?
+        selector = atomic_selector
+        _root.collection.find(selector).update(positionally(selector, operations))
+      end
+    end
+  end
+end