discard 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99f47416f1c4bdc6ed76c7814e6f1b88baea019acf8d38abbbbf709d42db0efa
-  data.tar.gz: c6699d73d311300e8cdeecd1cb2498c3b25197a10292f28993abc237ad1abd5f
+  metadata.gz: 2418547a70d311cc7d970ce492f505a0807db23a03eebe2ae1e1f7589a0edb8b
+  data.tar.gz: a45947c018416ee63a873fc0f94f143f20a6a5e34892420893bf3fe50b9a5406
 SHA512:
-  metadata.gz: ebd11402b212e931423a98484b598675eac16ef4eb878a701fd1479da488bd503058d0679053be16b43bab4e651b50cd512c6d14f19d131dae02fbcbc3396c78
-  data.tar.gz: f5baab64f5a951f1c55c73615490587d44291296645c4e4317c6918dcdc52675c3fa1856f86db03de2341518d9836ab2ad7e011d914599ebbc27d425406f5ccf
+  metadata.gz: 4111df84d2628abc622a64bcb730ef1acc1b5d509ed2c226a5f5b5ca96fecaaebf65bf39fa2f54392c9161198e496fd84aa78f72aebf921c21c9c3cdd18ac687
+  data.tar.gz: a881fee07ba21fbf6281f966ff51607a5f2acfb127a43fd35e3a9bfbc2c2dcdfec1962e14ba475e2c33dae81e0dca56f5de8172c4afe3e9536e5f36377d33b82

data/.travis.yml

@@ -1,14 +1,24 @@
 sudo: false
 language: ruby
 rvm:
-  - 2.2.9
-  - 2.3.6
-  - 2.4.3
-  - 2.5.0
+  - 2.2.10
+  - 2.3.8
+  - 2.4.6
+  - 2.5.5
+  - 2.6.3
 env:
   matrix:
-    - RAILS_VERSION='~> 4.2.0'
-    - RAILS_VERSION='~> 5.0.0'
+    - RAILS_VERSION='~> 4.2.0' SQLITE_VERSION='~> 1.3.6'
+    - RAILS_VERSION='~> 5.0.0' SQLITE_VERSION='~> 1.3.6'
     - RAILS_VERSION='~> 5.1.0'
     - RAILS_VERSION='~> 5.2.x'
-before_install: gem install bundler -v 1.14.6
+    - RAILS_VERSION='~> 6.0.0.beta3'
+
+matrix:
+  exclude:
+    - rvm: 2.2.10
+      env: RAILS_VERSION='~> 6.0.0.beta3'
+    - rvm: 2.3.8
+      env: RAILS_VERSION='~> 6.0.0.beta3'
+    - rvm: 2.4.6
+      env: RAILS_VERSION='~> 6.0.0.beta3'

data/.yardopts

@@ -0,0 +1,8 @@
+--protected
+--no-private
+--embed-mixin ClassMethods
+-
+README.md
+CHANGELOG.md
+CODE_OF_CONDUCT.md
+LICENSE.txt

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+### Unreleased
+
+### Version 1.1.0
+Release date: 2019-05-03
+
+* Support for ActiveRecord 6
+* `discard_all` and `undiscard_all` now return affected records
+* Add `discard!` and `undiscard!`
+
+### Version 1.0.0
+Release date: 2018-03-16
+
+* Add undiscard callbacks and `.undiscard_all`
+
+### Version 0.2.0
+Release date: 2017-11-22
+
+* Add `.discard_all`
+* Add `undiscarded` scope
+* Add callbacks
+
+### Version 0.1.0
+Release date: 2017-04-28
+
+* Initial version!

data/Gemfile

@@ -3,5 +3,9 @@ source 'https://rubygems.org'
 rails_version = ENV['RAILS_VERSION']
 gem 'activerecord', rails_version
 
+if sqlite_version = ENV['SQLITE_VERSION']
+  gem 'sqlite3', sqlite_version
+end
+
 # Specify your gem's dependencies in discard.gemspec
 gemspec

data/README.md

@@ -32,10 +32,15 @@ class Post < ActiveRecord::Base
 end
 ```
 
+You can either generate a migration using:
+```
+rails generate migration add_discarded_at_to_posts discarded_at:datetime:index
+```
 
+or create one yourself like the one below:
 ``` ruby
 class AddDiscardToPosts < ActiveRecord::Migration[5.0]
-  def up
+  def change
     add_column :posts, :discarded_at, :datetime
     add_index :posts, :discarded_at
   end
@@ -43,9 +48,9 @@ end
 ```
 
 
-**Discard a record**
+#### Discard a record
 
-```
+```ruby
 Post.all             # => [#<Post id: 1, ...>]
 Post.kept            # => [#<Post id: 1, ...>]
 Post.discarded       # => []
@@ -60,7 +65,7 @@ Post.kept            # => []
 Post.discarded       # => [#<Post id: 1, ...>]
 ```
 
-**From a controller**
+***From a controller***
 
 Controller actions need a small modification to discard records instead of deleting them. Just replace `destroy` with `discard`.
 
@@ -72,23 +77,23 @@ end
 ```
 
 
-**Undiscard a record**
+#### Undiscard a record
 
-```
+```ruby
 post = Post.first   # => #<Post id: 1, ...>
 post.undiscard      # => true
 ```
 
 ***From a controller***
 
-```
+```ruby
 def update
   @post.undiscard
   redirect_to users_url, notice: "Post undiscarded"
 end
 ```
 
-**Working with associations**
+#### Working with associations
 
 Under paranoia, soft deleting a record will destroy any `dependent: :destroy`
 associations. Probably not what you want! This leads to all dependent records
@@ -114,10 +119,10 @@ discarded. Just override the `kept` scope on the Comment model.
 
 ``` ruby
 class Comment < ActiveRecord::Base
-  has_many :posts
+  belongs_to :post
 
   include Discard::Model
-  scope :kept, -> { undiscarded.joins(:posts).merge(Post.kept) }
+  scope :kept, -> { undiscarded.joins(:post).merge(Post.kept) }
 end
 
 Comment.kept
@@ -133,7 +138,7 @@ SQL databases are very good at this, and performance should not be an issue.
 In both of these cases restoring either of these records will do right thing!
 
 
-**Default scope**
+#### Default scope
 
 It's usually undesirable to add a default scope. It will take more effort to
 work around and will cause more headaches. If you know you need a default scope, it's easy to add yourself ❤.
@@ -149,7 +154,7 @@ Post.with_discarded            # All Posts
 Post.with_discarded.discarded  # Only discarded posts
 ```
 
-**Custom column**
+#### Custom column
 
 If you're migrating from paranoia, you might want to continue using the same
 column.
@@ -161,12 +166,16 @@ class Post < ActiveRecord::Base
 end
 ```
 
-**Callbacks**
+#### Callbacks
 
 Callbacks can be run before, after, or around the discard and undiscard operations.
 A likely use is discarding or deleting associated records (but see "Working with associations" for an alternative).
 
 ``` ruby
+class Comment < ActiveRecord::Base
+  include Discard::Model
+end
+
 class Post < ActiveRecord::Base
   include Discard::Model
 
@@ -182,15 +191,25 @@ class Post < ActiveRecord::Base
 end
 ```
 
-**Working with Devise**
+*Warning:* Please note that callbacks for save and update are run when discarding/undiscarding a record
+
+
+#### Performance tuning
+`discard_all` and `undiscard_all` is intended to behave like `destroy_all` which has callbacks, validations, and does one query per record. If performance is a big concern, you may consider replacing it with:
+
+`scope.update_all(discarded_at: Time.current)`
+or
+`scope.update_all(discarded_at: nil)`
+
+#### Working with Devise
 
 A common use case is to apply discard to a User record. Even though a user has been discarded they can still login and continue their session.
 If you are using Devise and wish for discarded users to be unable to login and stop their session you can override Devise's method.
 
-```
+```ruby
 class User < ActiveRecord::Base
   def active_for_authentication?
-    super && !discarded_at
+    super && !discarded?
   end
 end
 ```
@@ -217,7 +236,7 @@ and awkward behaviour.
   adding `.with_deleted` to associations or anywhere soft-deleted records
   should be found. :disappointed:
   * Adding `belongs_to :child, -> { with_deleted }` helps, but doesn't work for
-    joins and eager-loading.
+    joins and eager-loading [before Rails 5.2](https://github.com/rubysherpas/paranoia/issues/355)
 * `delete` is overridden (`really_delete` will actually delete the record) :unamused:
 * `destroy` is overridden (`really_destroy` will actually delete the record) :pensive:
 * `dependent: :destroy` associations are deleted when performing soft-destroys :scream:

data/Rakefile

@@ -1,9 +1,8 @@
-require "bundler/gem_tasks"
+require 'bundler/setup'
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
-begin
-  require 'rspec/core/rake_task'
-  RSpec::Core::RakeTask.new(:spec)
-rescue LoadError
-end
+RSpec::Core::RakeTask.new(:rspec)
 
-task :default => :spec
+desc 'Run the test suite'
+task default: :rspec

data/discard.gemspec

@@ -1,4 +1,5 @@
-# coding: utf-8
+# frozen_string_literal: true
+
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'discard/version'
@@ -21,8 +22,8 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "activerecord", '>= 4.2', '< 6'
-  spec.add_development_dependency "bundler", "~> 1.14"
+  spec.add_dependency "activerecord", ">= 4.2", "< 7"
+  spec.add_development_dependency "bundler"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3.5.0"
   spec.add_development_dependency "database_cleaner", "~> 1.5"

data/lib/discard/errors.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Discard
+  # = Discard Errors
+  #
+  # Generic exception class.
+  class DiscardError < StandardError
+  end
+
+  # Raised by {Discard::Model#discard!}
+  class RecordNotDiscarded < DiscardError
+    attr_reader :record
+
+    def initialize(message = nil, record = nil)
+      @record = record
+      super(message)
+    end
+  end
+
+  # Raised by {Discard::Model#undiscard!}
+  class RecordNotUndiscarded < DiscardError
+    attr_reader :record
+
+    def initialize(message = nil, record = nil)
+      @record = record
+      super(message)
+    end
+  end
+end

data/lib/discard/model.rb

@@ -1,4 +1,11 @@
+# frozen_string_literal: true
+
 module Discard
+  # Handles soft deletes of records.
+  #
+  # Options:
+  #
+  # - :discard_column - The columns used to track soft delete, defaults to `:discarded_at`.
   module Model
     extend ActiveSupport::Concern
 
@@ -15,42 +22,104 @@ module Discard
       define_model_callbacks :undiscard
     end
 
+    # :nodoc:
     module ClassMethods
+      # Discards the records by instantiating each
+      # record and calling its {#discard} method.
+      # Each object's callbacks are executed.
+      # Returns the collection of objects that were discarded.
+      #
+      # Note: Instantiation, callback execution, and update of each
+      # record can be time consuming when you're discarding many records at
+      # once. It generates at least one SQL +UPDATE+ query per record (or
+      # possibly more, to enforce your callbacks). If you want to discard many
+      # rows quickly, without concern for their associations or callbacks, use
+      # #update_all(discarded_at: Time.current) instead.
+      #
+      # ==== Examples
+      #
+      #   Person.where(age: 0..18).discard_all
       def discard_all
-        all.each(&:discard)
+        kept.each(&:discard)
       end
+
+      # Undiscards the records by instantiating each
+      # record and calling its {#undiscard} method.
+      # Each object's callbacks are executed.
+      # Returns the collection of objects that were undiscarded.
+      #
+      # Note: Instantiation, callback execution, and update of each
+      # record can be time consuming when you're undiscarding many records at
+      # once. It generates at least one SQL +UPDATE+ query per record (or
+      # possibly more, to enforce your callbacks). If you want to undiscard many
+      # rows quickly, without concern for their associations or callbacks, use
+      # #update_all(discarded_at: nil) instead.
+      #
+      # ==== Examples
+      #
+      #   Person.where(age: 0..18).undiscard_all
       def undiscard_all
-        all.each(&:undiscard)
+        discarded.each(&:undiscard)
       end
     end
 
-    # @return [true,false] true if this record has been discarded, otherwise false
+    # @return [Boolean] true if this record has been discarded, otherwise false
     def discarded?
-      !!self[self.class.discard_column]
+      self[self.class.discard_column].present?
     end
 
-    # @return [true,false] true if successful, otherwise false
+    # Discard the record in the database
+    #
+    # @return [Boolean] true if successful, otherwise false
     def discard
-      unless discarded?
-        with_transaction_returning_status do
-          run_callbacks(:discard) do
-            self[self.class.discard_column] = Time.current
-            save
-          end
-        end
+      return if discarded?
+      run_callbacks(:discard) do
+        update_attribute(self.class.discard_column, Time.current)
       end
     end
 
-    # @return [true,false] true if successful, otherwise false
+    # Discard the record in the database
+    #
+    # There's a series of callbacks associated with #discard!. If the
+    # <tt>before_discard</tt> callback throws +:abort+ the action is cancelled
+    # and #discard! raises {Discard::RecordNotDiscarded}.
+    #
+    # @return [Boolean] true if successful
+    # @raise {Discard::RecordNotDiscarded}
+    def discard!
+      discard || _raise_record_not_discarded
+    end
+
+    # Undiscard the record in the database
+    #
+    # @return [Boolean] true if successful, otherwise false
     def undiscard
-      if discarded?
-        with_transaction_returning_status do
-          run_callbacks(:undiscard) do
-            self[self.class.discard_column] = nil
-            save
-          end
-        end
+      return unless discarded?
+      run_callbacks(:undiscard) do
+        update_attribute(self.class.discard_column, nil)
       end
     end
+
+    # Discard the record in the database
+    #
+    # There's a series of callbacks associated with #undiscard!. If the
+    # <tt>before_undiscard</tt> callback throws +:abort+ the action is cancelled
+    # and #undiscard! raises {Discard::RecordNotUndiscarded}.
+    #
+    # @return [Boolean] true if successful
+    # @raise {Discard::RecordNotUndiscarded}
+    def undiscard!
+      undiscard || _raise_record_not_undiscarded
+    end
+
+    private
+
+    def _raise_record_not_discarded
+      raise ::Discard::RecordNotDiscarded.new("Failed to discard the record", self)
+    end
+
+    def _raise_record_not_undiscarded
+      raise ::Discard::RecordNotUndiscarded.new("Failed to undiscard the record", self)
+    end
   end
 end

data/lib/discard/version.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
 module Discard
-  VERSION = "1.0.0"
+  # Discard version
+  VERSION = "1.1.0".freeze
 end

data/lib/discard.rb

@@ -1,4 +1,7 @@
+# frozen_string_literal: true
+
 require "active_record"
 
 require "discard/version"
+require "discard/errors"
 require "discard/model"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: discard
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - John Hawthorn
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-03-16 00:00:00.000000000 Z
+date: 2019-05-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -19,7 +19,7 @@ dependencies:
         version: '4.2'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '6'
+        version: '7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -29,21 +29,21 @@ dependencies:
         version: '4.2'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '6'
+        version: '7'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.14'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.14'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -125,6 +125,8 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
+- ".yardopts"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt
@@ -134,6 +136,7 @@ files:
 - bin/setup
 - discard.gemspec
 - lib/discard.rb
+- lib/discard/errors.rb
 - lib/discard/model.rb
 - lib/discard/version.rb
 homepage: https://github.com/jhawthorn/discard
@@ -155,8 +158,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6
+rubygems_version: 3.0.1
 signing_key: 
 specification_version: 4
 summary: ActiveRecord soft-deletes done right