mongoid_archival 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 07ba0abce107f9b1480d234623377106c955e53f34666b2958ffdd2b76c829f0
+  data.tar.gz: 06f63e64420baa03f3bddeca4f971c0a506edfb98c6447140e2db82e4d48bf8f
+SHA512:
+  metadata.gz: 0e1727027aea380a8654b8f566acdb8dfec1e8c71bba2bdafb59251b47d2d412eda3eb15cd2de235430a95b6e7f9db76e20d383b49c924642cf06826c9fe2f8e
+  data.tar.gz: ea9db2aae467c6a0169e40869702fa5fff7fe62660c7d6f9f016037482d458b945d7fc89553c23b02752ff8f9ebdf4801e658da0b45f89ff77b0365c3511cdb3

data/LICENSE

@@ -0,0 +1,24 @@
+Copyright (c) 2009 Durran Jordan
+Copyright (c) 2013 Josef Šimánek
+Copyright (c) 2021 TableCheck Inc.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,245 @@
+# Mongoid::Archivable (mongoid_archival)
+
+[![Build Status](https://github.com/tablecheck/mongoid_archival/actions/workflows/test.yml/badge.svg?query=branch%3Amaster)](https://github.com/tablecheck/mongoid_archival/actions/workflows/test.yml?query=branch%3Amaster)
+[![Gem Version](https://img.shields.io/gem/v/mongoid_archival.svg)](https://rubygems.org/gems/mongoid_archival)
+
+`Mongoid::Archivable` enables archiving (soft delete) of Mongoid documents.
+Instead of being removed from the database, archived docs are flagged with an `archived_at` timestamp.
+This allows you to maintain references to archived documents, and restore if necessary.
+
+#### Instability Warning
+
+Versions prior to 1.0.0 are in **alpha** state. Behaviors, APIs, method names, etc.
+may change anytime without warning. Please lock your gem version, be careful when upgrading,
+and write tests in your own project.
+
+#### Disambiguation
+
+* This gem is different than [mongoid-archivable](https://github.com/Sign2Pay/mongoid-archivable),
+which moves documents to a separate "archive" database/collection. Cannot be used concurrently with
+this gem as both use the `Mongoid::Archivable` namespace.
+* This gem is forked from [mongoid_paranoia](https://github.com/simi/mongoid_paranoia).
+Can be used concurrently with this gem. See section below for key differences.
+
+#### TODO
+
+* [ ] Support embedded documents.
+* [ ] Support model-level configuration.
+* [ ] Allow rename archive field alias.
+* [ ] Consider adding #archive(callbacks: false)
+* [ ] Consider adding .archive_all query action
+
+## Usage
+
+#### Installation
+
+In your application's Gemfile:
+
+```ruby
+gem 'mongoid_archival'
+```
+
+#### Adding to Model Class
+
+```ruby
+class Person
+  include Mongoid::Document
+  include Mongoid::Archivable
+
+  # TODO: archivable macro
+end
+```
+
+#### Archiving with Documents
+
+```ruby
+# Set the archived_at field to the current time, firing callbacks
+# and archiving any dependent documents. Analogous to Mongoid #destroy method.
+person.archive
+
+# Sets the archived_at field to the current time, ignoring callbacks
+# and dependency rules. Analogous to Mongoid #delete method.
+person.archive_without_callbacks
+# TODO person.archive(callbacks: false)
+
+# Un-archive an archive document back.
+person.restore
+
+# Un-archive an archive document back, including any dependent documents.
+person.restore(recursive: true)
+```
+
+#### Querying
+
+```ruby
+# Return all documents, both archived and non-archived.
+Person.all
+
+# Return only documents that are not flagged as archived.
+Person.current
+
+# Return only documents that are flagged as archived.
+Person.archived
+```
+
+#### Global Configuration
+
+You may globally configure field and method names in an initializer.
+
+```ruby
+# config/initializers/mongoid_archivable.rb
+
+Mongoid::Archivable.configure do |c|
+  c.archived_field = :archived_at
+  c.archived_scope = :archived
+  c.nonarchived_scope = :current
+end
+```
+
+#### Callbacks
+
+Archivable documents have the following new callbacks.
+Note that these callbacks are **not** fired on `#destroy`.
+
+* `before_archive`
+* `after_archive`
+* `around_archive`
+* `before_restore`
+* `after_restore`
+* `around_restore`
+
+```ruby
+class User
+  include Mongoid::Document
+  include Mongoid::Archivable
+
+  before_archive :before_archive_action
+  after_archive :after_archive_action
+  around_archive :around_archive_action
+
+  before_restore :before_restore_action
+  after_restore :after_restore_action
+  around_restore :around_restore_action
+
+  # You may `throw(:abort)` within a callback to prevent
+  # the action from proceeding.
+  def before_archive_action
+    throw(:abort) if name == 'Pete'
+  end
+end
+```
+
+#### Relation Dependencies
+
+This gem adds two new relation dependency handling strategies:
+
+* `:archive` - Invokes `#archive` and callbacks on each dependency, recursively
+including dependencies of dependencies. Analogous to `:destroy`.
+* `:archive_all` - Calls `.set(archived_at: Time.now)` on the
+dependency scope in a single query. Much faster but does not support callbacks
+or dependency recursion. Analogous to `:delete_all`.
+
+If the dependent model is not archivable, these strategies will be ignored without any effect.
+
+```ruby
+class User
+  include Mongoid::Document
+  include Mongoid::Archivable
+
+  has_many :pokemons, dependent: :archive
+  belongs_to :gym, dependent: :archive_all
+end
+```
+
+In addition, dependency strategies `:nullify`, `:restrict_with_exception`,
+and `:restrict_with_error` will be applied when archiving documents.
+`:destroy` and `:delete_all` are intentionally ignored.
+
+#### Protecting Against Deletion
+
+Add the `Mongoid::Archivable::Protected` mixin to cause 
+`#delete` and `#destroy` methods to raise an error.
+The bang methods `#delete!` and `#destroy!` can be used instead.
+This is useful when migrating a legacy codebase.
+
+```ruby
+class Pokemon
+  include Mongoid::Document
+  include Mongoid::Archivable
+  include Mongoid::Archivable::Protected
+end
+
+venusaur = Pokemon.create
+venusaur.delete    # raises RuntimeError
+venusaur.destroy   # raises RuntimeError
+venusaur.delete!   # deletes the document without callbacks
+venusaur.destroy!  # deletes the document with callbacks
+```
+
+## Gotchas
+
+The following require additional manual changes when using this gem.
+
+#### Uniqueness Validation
+
+You must set `scope: :archived_at` in your uniqueness validations to prevent
+validating against archived documents.
+
+```ruby
+validates_uniqueness_of :title, scope: :archived_at
+```
+
+#### Indexes
+
+You should add `archived_at` to your query indexes. As a rule-of-thumb, we recommend
+to add `archived_at` as the final key; this will create a compound index that will be
+selected with or without `archived_at` in the query.
+
+```ruby
+index category: 1, title: 1, archived_at: 1
+```
+
+Note that this may not give the best performance in all cases, for example
+when performing a time-range query on the value of `archived_at`. Please refer to the
+[MongoDB Indexes documentation](https://docs.mongodb.com/manual/indexes/)
+to learn more about index design.
+
+## Comparison with Mongoid::Paranoia
+
+We used [Mongoid::Paranoia](https://github.com/simi/mongoid_paranoia) at [TableCheck](https://www.tablecheck.com/en/join/)
+for many years. While many of design assumptions of Mongoid::Paranoia
+lead to initial productivity, we found them ultimately limiting and unintuitive
+as we grew both our team and our codebase.
+
+#### Key Differences 
+
+* The flag named is `archived_at` rather than `deleted_at`.
+The name `deleted_at` was confusing with respect to hard deletion.
+* Mongoid::Paranoia overrides the `#delete` and `#destroy` methods; this gem does not.
+Monkey patches and hackery are removed; behavior is less surprising.
+* This gem does **not** set a default scope on root (non-embedded) docs.
+Use the `.current` (non-archived) and `.archived` query scopes as needed.
+Mongoid::Paranoia relies on `.unscoped` 
+
+#### Migration Checklist
+
+* [ ] Add `mongoid_archival` to your gemspec **after** `mongoid_paranoia`.
+You may use the two gems together in your project,
+but should include only one of `Mongoid::Archivable` or `Mongoid::Paranoia` into each model class.
+In this manner, you can migrate each model one-by-one.
+* [ ] To avoid accidentally calling `#delete` and `#destroy`, add the
+`Mongoid::Archivable::Protected` mixin to cause those methods to raise an error.
+* [ ] Configure your `archived_field_name = :deleted_at` for backwards compatibility.
+* [ ] Add `.current` to your queries as necessary. You can remove usages of `.unscoped`.
+* [ ] In your relations, replace `dependent: :destroy` with `dependent: :archive` as necessary.
+
+## About Us
+
+Mongoid::Archivable is made with ❤ by [TableCheck](https://www.tablecheck.com/en/join/),
+the leading restaurant reservation and guest management app maker.
+If **you** are a ninja-level 🥷 coder (Javascript/Ruby/Elixir/Python/Go),
+designer, product manager, data scientist, QA, etc. and are ready to join us in Tokyo, Japan
+or work remotely, please get in touch at [careers@tablecheck.com](mailto:careers@tablecheck.com).
+
+Shout out to Durran Jordan and Josef Šimánek for their original work on
+[Mongoid::Paranoia](https://github.com/simi/mongoid_paranoia).

data/lib/mongoid/archivable.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'mongoid/archivable/version'
+require 'mongoid/archivable/configuration'
+require 'mongoid/archivable/depending'
+require 'mongoid/archivable/protected'
+
+module Mongoid
+
+  # Include this module to get archivable root level documents.
+  # This will add a archived_at field to the +Document+, managed automatically.
+  # Potentially incompatible with unique indices. (if collisions with archived items)
+  #
+  # @example Make a document archivable.
+  #   class Person
+  #     include Mongoid::Document
+  #     include Mongoid::Archivable
+  #   end
+  module Archivable
+    extend ActiveSupport::Concern
+
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def reset
+        @configuration = Configuration.new
+      end
+
+      # Set an alternate field name for archived_at.
+      #
+      # @example
+      #   Mongoid::Archivable.configure do |c|
+      #     c.archived_field = :my_field_name
+      #   end
+      def configure
+        yield(configuration)
+      end
+    end
+
+    # class_methods do
+    #   def archivable(options = {})
+    #     Mongoid::Archivable::Installer.new(self, options).setup
+    #   end
+    # end
+
+    included do
+      class_attribute :archivable
+      self.archivable = true
+
+      config = Archivable.configuration
+
+      field config.archived_field, as: :archived_at, type: Time
+
+      scope config.nonarchived_scope, -> { where(archived_at: nil) }
+      scope config.archived_scope, -> { ne(archived_at: nil) }
+
+      define_model_callbacks :archive
+      define_model_callbacks :restore
+
+      def archive(options = {})
+        return if archived?
+        raise Errors::ReadonlyDocument.new(self.class) if readonly?
+        run_callbacks(:archive) do
+          if catch(:abort) { apply_archive_dependencies! }
+            archive_without_callbacks(options || {})
+          else
+            false
+          end
+        end
+      end
+
+      def archive_without_callbacks(_options = {})
+        return if archived?
+        raise Errors::ReadonlyDocument.new(self.class) if readonly?
+        now = Time.now
+        self.archived_at = now
+        _archivable_update('$set' => { archived_field => now })
+        true
+      end
+
+      # Determines if this document is archived.
+      #
+      # @example Is the document destroyed?
+      #   person.destroyed?
+      #
+      # @return [ true, false ] If the document is destroyed.
+      def archived?
+        !!archived_at
+      end
+
+      # Restores a previously archived document. Handles this by removing the
+      # archived_at flag.
+      #
+      # @example Restore the document from archived state.
+      #   document.restore
+      #
+      # For restoring associated documents use :recursive => true
+      # @example Restore the associated documents from archived state.
+      #   document.restore(recursive: true)
+      def restore(options = {})
+        return unless archived?
+        run_callbacks(:restore) { restore_without_callbacks(options) }
+      end
+
+      def restore_without_callbacks(options = {})
+        return unless archived?
+        _archivable_update('$unset' => { archived_field => true })
+        attributes.delete('archived_at') # TODO: does this need database field name
+        restore_relations if options[:recursive]
+        true
+      end
+
+      def restore_relations
+        relations.each_pair do |name, association|
+          next unless association.dependent.in?(%i[archive archive_all])
+          next unless _association_archivable?(association)
+          relation = send(name)
+          next unless relation
+          Array.wrap(relation).each do |doc|
+            doc.restore(recursive: true)
+          end
+        end
+      end
+
+      private
+
+      # Get the collection to be used for archivable operations.
+      #
+      # @example Get the archivable collection.
+      #   document.archivable_collection
+      #
+      # @return [ Collection ] The root collection.
+      def archivable_collection
+        embedded? ? _root.collection : collection
+      end
+
+      # Get the field to be used for archivable operations.
+      #
+      # @example Get the archivable field.
+      #   document.archived_field
+      #
+      # @return [ String ] The archived at field.
+      def archived_field
+        field = Archivable.configuration.archived_field
+        embedded? ? "#{atomic_position}.#{field}" : field
+      end
+
+      # @return [ Object ] Update result.
+      #
+      def _archivable_update(value)
+        archivable_collection.find(atomic_selector).update_one(value)
+      end
+    end
+  end
+end

data/lib/mongoid/archivable/configuration.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Archivable
+    class Configuration
+      attr_accessor :archived_field,
+                    :archived_scope,
+                    :nonarchived_scope
+
+      def initialize
+        @archived_field = :archived_at
+        @archived_scope = :archived
+        @nonarchived_scope = :current
+      end
+    end
+  end
+end