discard 0.2.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: e3d4174c8881bc3bf1fa453aafb3d966d8361292
-  data.tar.gz: 858b1edbe5d9c09144239a13cc3ca662f1485547
+SHA256:
+  metadata.gz: 99f47416f1c4bdc6ed76c7814e6f1b88baea019acf8d38abbbbf709d42db0efa
+  data.tar.gz: c6699d73d311300e8cdeecd1cb2498c3b25197a10292f28993abc237ad1abd5f
 SHA512:
-  metadata.gz: 1246d6187b35af15ceb8d5e8a1b914e09a45ba0380d833ca638305336d3075e67f60edc67fad55c49e994b0ab9e9f60b3d9a916acc837d3416b3b89ec56e2bcd
-  data.tar.gz: 1d098bf07dcefdd3d338b0a4a73b206dfd96e5c39b8abbabb17cd749970ff9c54efd3d35fe7f6f363f8c35b076b7e54f278f1f3cbb43de7330da0a363671f2f5
+  metadata.gz: ebd11402b212e931423a98484b598675eac16ef4eb878a701fd1479da488bd503058d0679053be16b43bab4e651b50cd512c6d14f19d131dae02fbcbc3396c78
+  data.tar.gz: f5baab64f5a951f1c55c73615490587d44291296645c4e4317c6918dcdc52675c3fa1856f86db03de2341518d9836ab2ad7e011d914599ebbc27d425406f5ccf

data/.travis.yml

@@ -1,12 +1,14 @@
 sudo: false
 language: ruby
 rvm:
-  - 2.2.7
-  - 2.3.4
-  - 2.4.1
+  - 2.2.9
+  - 2.3.6
+  - 2.4.3
+  - 2.5.0
 env:
   matrix:
     - RAILS_VERSION='~> 4.2.0'
     - RAILS_VERSION='~> 5.0.0'
-    - RAILS_VERSION='~> 5.1.x'
+    - RAILS_VERSION='~> 5.1.0'
+    - RAILS_VERSION='~> 5.2.x'
 before_install: gem install bundler -v 1.14.6

data/README.md

@@ -8,42 +8,12 @@ Soft deletes for ActiveRecord done right.
 
 A simple ActiveRecord mixin to add conventions for flagging records as discarded.
 
-## Why should I use this?
-
-I've worked with and have helped maintain
-[paranoia](https://github.com/rubysherpas/paranoia) for a while. I'm convinced
-it does the wrong thing for most cases.
-
-Paranoia and
-[acts_as_paranoid](https://github.com/ActsAsParanoid/acts_as_paranoid) both
-attempt to emulate deletes by setting a column and adding a default scope on the
-model. This requires some ActiveRecord hackery, and leads to some surprising
-and awkward behaviour.
-
-* A default scope is added to hide soft-deleted records, which necessitates
-  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.
-* `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:
-  * requiring any dependent records to also be `acts_as_paranoid` to avoid losing data. :grimacing:
-
-There are some use cases where these behaviours make sense: if you really did
-want to _almost_ delete the record. More often developers are just looking to
-hide some records, or mark them as inactive.
-
-Discard takes a different approach. It doesn't override any ActiveRecord
-methods and instead simply provides convenience methods and scopes for
-discarding (hiding), restoring, and querying records.
-
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'discard'
+gem 'discard', '~> 1.0'
 ```
 
 And then execute:
@@ -67,21 +37,23 @@ end
 class AddDiscardToPosts < ActiveRecord::Migration[5.0]
   def up
     add_column :posts, :discarded_at, :datetime
+    add_index :posts, :discarded_at
   end
 end
 ```
 
 
 **Discard a record**
+
 ```
 Post.all             # => [#<Post id: 1, ...>]
 Post.kept            # => [#<Post id: 1, ...>]
 Post.discarded       # => []
 
-@post = Post.first   # => #<Post id: 1, ...>
-@post.discard!
-@post.discarded?     # => true
-@post.discarded_at   # => 2017-04-18 18:49:49 -0700
+post = Post.first   # => #<Post id: 1, ...>
+post.discard        # => true
+post.discarded?     # => true
+post.discarded_at   # => 2017-04-18 18:49:49 -0700
 
 Post.all             # => [#<Post id: 1, ...>]
 Post.kept            # => []
@@ -99,6 +71,23 @@ def destroy
 end
 ```
 
+
+**Undiscard a record**
+
+```
+post = Post.first   # => #<Post id: 1, ...>
+post.undiscard      # => true
+```
+
+***From a controller***
+
+```
+def update
+  @post.undiscard
+  redirect_to users_url, notice: "Post undiscarded"
+end
+```
+
 **Working with associations**
 
 Under paranoia, soft deleting a record will destroy any `dependent: :destroy`
@@ -172,12 +161,75 @@ class Post < ActiveRecord::Base
 end
 ```
 
+**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 Post < ActiveRecord::Base
+  include Discard::Model
+
+  has_many :comments
+
+  after_discard do
+    comments.discard_all
+  end
+
+  after_undiscard do
+    comments.undiscard_all
+  end
+end
+```
+
+**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.
+
+```
+class User < ActiveRecord::Base
+  def active_for_authentication?
+    super && !discarded_at
+  end
+end
+```
+
 ## Non-features
 
-* Restoring records (this will probably be added)
-* Discarding dependent records (this will likely be added)
-* Callbacks (this will probably be added)
 * Special handling of AR counter cache columns - The counter cache counts the total number of records, both kept and discarded.
+* Recursive discards (like AR's dependent: destroy) - This can be avoided using queries (See "Working with associations") or emulated using callbacks.
+* Recursive restores - This concept is fundamentally broken, but not necessary if the recursive discards are avoided.
+
+## Why not paranoia or acts_as_paranoid?
+
+I've worked with and have helped maintain
+[paranoia](https://github.com/rubysherpas/paranoia) for a while. I'm convinced
+it does the wrong thing for most cases.
+
+Paranoia and
+[acts_as_paranoid](https://github.com/ActsAsParanoid/acts_as_paranoid) both
+attempt to emulate deletes by setting a column and adding a default scope on the
+model. This requires some ActiveRecord hackery, and leads to some surprising
+and awkward behaviour.
+
+* A default scope is added to hide soft-deleted records, which necessitates
+  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.
+* `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:
+  * requiring any dependent records to also be `acts_as_paranoid` to avoid losing data. :grimacing:
+
+There are some use cases where these behaviours make sense: if you really did
+want to _almost_ delete the record. More often developers are just looking to
+hide some records, or mark them as inactive.
+
+Discard takes a different approach. It doesn't override any ActiveRecord
+methods and instead simply provides convenience methods and scopes for
+discarding (hiding), restoring, and querying records.
 
 ## Development
 

data/lib/discard/model.rb

@@ -12,18 +12,24 @@ module Discard
       scope :with_discarded, ->{ unscope(where: discard_column) }
 
       define_model_callbacks :discard
+      define_model_callbacks :undiscard
     end
 
-    class_methods do
+    module ClassMethods
       def discard_all
         all.each(&:discard)
       end
+      def undiscard_all
+        all.each(&:undiscard)
+      end
     end
 
+    # @return [true,false] true if this record has been discarded, otherwise false
     def discarded?
       !!self[self.class.discard_column]
     end
 
+    # @return [true,false] true if successful, otherwise false
     def discard
       unless discarded?
         with_transaction_returning_status do
@@ -35,9 +41,16 @@ module Discard
       end
     end
 
+    # @return [true,false] true if successful, otherwise false
     def undiscard
-      self[self.class.discard_column] = nil
-      save
+      if discarded?
+        with_transaction_returning_status do
+          run_callbacks(:undiscard) do
+            self[self.class.discard_column] = nil
+            save
+          end
+        end
+      end
     end
   end
 end

data/lib/discard/version.rb

@@ -1,3 +1,3 @@
 module Discard
-  VERSION = "0.2.0"
+  VERSION = "1.0.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: discard
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.0.0
 platform: ruby
 authors:
 - John Hawthorn
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-11-22 00:00:00.000000000 Z
+date: 2018-03-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -156,7 +156,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.11
+rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
 summary: ActiveRecord soft-deletes done right