Discard Documentation

Unlike paranoia, Discard does not automatically destroy dependent associations. This prevents accidental data loss. Instead, you should manage associations using one of two patterns:

1. Independent Discarding

Keep records independent. For example, a Comment can remain 'kept' even if its parent Post is discarded. You simply query for kept records using the kept scope.

2. Dependent Scoping

If a child record should only be considered 'kept' if its parent is also 'kept', override the child's kept scope using a join and a merge.

class Comment < ActiveRecord::Base
  belongs_to :post
  include Discard::Model

  # Only returns comments where both the comment and the post are kept
  scope :kept, -> { undiscarded.joins(:post).merge(Post.kept) }

  def kept?
    undiscarded? && post.kept?
  end
end

To enable soft-deletion on an ActiveRecord model, include Discard::Model in the class. You must also ensure the model has a discarded_at datetime column with an index.

Migration Example

You can generate the migration using Rails:

rails generate migration add_discarded_at_to_posts discarded_at:datetime:index

Or create a manual migration:

class AddDiscardToPosts < ActiveRecord::Migration[5.0]
  def change
    add_column :posts, :discarded_at, :datetime
    add_index :posts, :discarded_at
  end
end

class Post < ActiveRecord::Base
  include Discard::Model
end

To use Discard in your ActiveRecord application, add the following line to your Gemfile:

gem 'discard', '~> 2.0'

Then, run the bundle command in your terminal:

$ bundle

If you are migrating from another gem like paranoia and want to reuse an existing column (e.g., deleted_at), set the discard_column attribute in your model.

class Post < ActiveRecord::Base
  include Discard::Model
  self.discard_column = :deleted_at
end

If you apply Discard to a User model, discarded users can still log in by default. To prevent discarded users from authenticating, override active_for_authentication? in your User model:

class User < ActiveRecord::Base
  def active_for_authentication?
    super && !discarded?
  end
end

You can hook into the discard/undiscard lifecycle using before_, after_, or around_ callbacks. This is useful for manually managing associated records.

Important Callback Behaviors:

• Validations: #discard and #undiscard use update_attribute, which skips validations.
• State Transition: The discard column is flipped between before_ and after_ callbacks.
  • before_discard sees discarded? as false.
  • after_discard sees discarded? as true.

class Post < ActiveRecord::Base
  include Discard::Model
  has_many :comments

  after_discard do
    comments.discard_all
  end

  after_undiscard do
    comments.undiscard_all
  end
end

You can soft-delete or restore individual records using the following methods:

Soft-deleting a record

• discard: Attempts to soft-delete the record. Returns true if successful, false if the record is already discarded.
• discard!: Attempts to soft-delete the record. Raises Discard::RecordNotDiscarded if the action fails or is aborted by a before_discard callback.

Restoring a record

• undiscard: Attempts to restore a discarded record. Returns true if successful, false if the record is already undiscarded.
• undiscard!: Attempts to restore a discarded record. Raises Discard::RecordNotUndiscarded if the action fails or is aborted by a before_undiscard callback.

Checking status

• discarded?: Returns true if the record has been discarded.
• undiscarded? (or kept?): Returns true if the record has not been discarded.

Once Discard::Model is included in your model, you can use the following scopes to query records based on their discard status:

• kept: Returns records that have not been discarded (alias for undiscarded).
• undiscarded: Returns records where the discard_column is nil.
• discarded: Returns records where the discard_column is present.
• with_discarded: Returns all records, unreserving the discard_column filter.