active_record-undo 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30415ed66666364750a948cbbb06c6edffb88bff916bc5b7fc42d78ae027038d
-  data.tar.gz: 83f4abe357af730e23bf89f85e93e009cd6f6207a8bb313bb5972b67c1b6488e
+  metadata.gz: aedb1b7356b0530c7316c1c94a4f2681cf4c103cb50986e24dfaa1f5d1eec553
+  data.tar.gz: 33f779d1c31b5c80126fa4838b8f080f512e25dca9dd372d88e3ff1d9a1b4eaa
 SHA512:
-  metadata.gz: 4fc93992835bec03fff811b669ea856230b8498bb53e81b62be8e85e6d7d047d0f644f9568de5bf337d77bd4b2ed20f2a36b00155f8b8021c3a358e6bbb0b710
-  data.tar.gz: a1afbb6efc8ce17b31b8f2a8b863e94c0c5d1f04ad4eb475d21a5599f525845002ced413793b8139d1241e936aaac2d3754b89ff11a3a4b2e139c42aa7756bec
+  metadata.gz: 982b77e10592f7e0599d080b74d5c9daa4658c9df14e8a068b95dd00d51cacd33e813e5250e88b3fedc134fbfbe66fde57a6ad62c089b0dd2ce32a56c2597332
+  data.tar.gz: 177f71075ba0e65a2e372fbfc9afb4783248c29eb164955cf7449706257e82759d38e86b0eefad18b89a4b4a17ee335c8d589be65b6d288ff0126ccf9fafd7ab

data/DOCUMENTATION.md

@@ -12,6 +12,7 @@ graph TD
     
     subgraph GemCore[ActiveRecord::Undo Core Engine]
         ModelExt -->|Calls soft_delete!| TxBoundary[ActiveRecord::Base.transaction]
+        ModelExt -->|Calls undoable?| CheckQuery[SQL EXISTS Query across UndoLogItem & UndoLog]
         
         subgraph TxBoundary
             CreateLog[Create UndoLog Parent]
@@ -28,6 +29,7 @@ graph TD
     subgraph DatabaseStorage[Persistence Layer]
         AppendItem --> UndoLogTable[(undo_logs)]
         AppendItem --> UndoItemTable[(undo_log_items)]
+        CheckQuery --> UndoItemTable
     end
 ```
 
@@ -40,13 +42,17 @@ graph TD
 | Component | File Path | Class / Module | Core Responsibility |
 | :--- | :--- | :--- | :--- |
 | **Main Hook** | `lib/active_record/undo.rb` | `ActiveRecord::Undo` | Hooks into `ActiveSupport.on_load(:active_record)` |
-| **Model Extension** | `lib/active_record/undo/model_extension.rb` | `ModelExtension` | Injects DSL (`acts_as_undoable`), scopes (`kept`, `soft_deleted`), and methods (`soft_delete!`) |
+| **Model Extension** | `lib/active_record/undo/model_extension.rb` | `ModelExtension` | Injects DSL (`acts_as_undoable`), scopes (`kept`, `soft_deleted`), and methods (`soft_delete!`, `undoable?`, `restore!`) |
 | **Cascade Engine** | `lib/active_record/undo/cascade_handler.rb` | `CascadeHandler` | Inspects ActiveRecord reflections (`reflections`) and executes DFS traversal |
 | **Cascade Association Finder** | `lib/active_record/undo/cascade_handler/association_finder.rb` | `AssociationFinder` | Resolves which records should cascade based on dependency configuration |
 | **Cascade Record Updater** | `lib/active_record/undo/cascade_handler/record_updater.rb` | `RecordUpdater` | Updates the database timestamps directly bypassing callbacks |
 | **Audit Log Parent** | `lib/active_record/undo/undo_log.rb` | `UndoLog` | Represents the top-level deletion event and manages atomic batch restoration |
 | **Audit Log Child** | `lib/active_record/undo/undo_log_item.rb` | `UndoLogItem` | Maps polymorphic targets (`item_type`, `item_id`) to original deleted entities |
 | **Engine Link** | `lib/active_record/undo/engine.rb` | `Engine` | Appends `db/migrate/` directly to host app migration paths |
+| **Configuration** | `lib/active_record/undo/configuration.rb` | `Configuration` | Houses retention_period settings |
+| **Purger Service** | `lib/active_record/undo/purger.rb` | `Purger` | Deletes expired UndoLog/Items and soft-deleted model records in batches |
+| **Purge Job** | `lib/active_record/undo/purge_job.rb` | `PurgeJob` | ActiveJob background runner invoking Purger |
+| **Rake Task** | `lib/active_record/undo/tasks/purge.rake` | Rake Task | Exposes `active_record_undo:purge_expired` command |
 
 ---
 
@@ -117,6 +123,28 @@ sequenceDiagram
     Model-->>User: Returns UndoLog Instance
 ```
 
+### Restoration Verification Flow (`#undoable?`)
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User
+    participant Model as Post Model
+    participant Ext as ModelExtension
+    participant DB as SQL Engine
+
+    User->>Model: post.undoable?
+    Model->>Ext: Check soft_deleted?
+    
+    alt Not Soft Deleted
+        Ext-->>User: returns false
+    else Is Soft Deleted
+        Ext->>DB: SELECT 1 FROM undo_log_items INNER JOIN undo_logs ... LIMIT 1
+        DB-->>Ext: Record Exists (true / false)
+        Ext-->>User: returns boolean
+    end
+```
+
 ### Restoration Flow (`#restore!`)
 
 ```mermaid
@@ -147,9 +175,10 @@ sequenceDiagram
 
 1. **Depth-First Traversal Order:** Cascading deletes traverse downward to child records before updating the parent node. Child item associations are appended to `undo_log_items` first, and the parent record is appended last.
 2. **Reverse Restoration Order:** `#restore!` calls `undo_log_items.reverse_each`. This ensures the parent node is restored first before restoring its dependent records, maintaining database relational integrity.
-3. **Bypassing Callbacks:** Soft-deletion updates use `update_columns`. This executes a direct SQL `UPDATE` query without firing standard ActiveRecord persistence callbacks (`save`, `validate`), preventing unintended side effects during soft deletes.
-4. **Unscoped Model Resolution:** `#restore_item!` uses `klass.unscoped.find_by(id: item_id)` to locate records. This guarantees records are retrieved even when models define default scopes that filter out soft-deleted records.
-5. **Class Inheritance Security Check:** When constantizing stored class strings, the gem validates that target models inherit from `ActiveRecord::Base` to prevent arbitrary non-model constant manipulation.
+3. **Optimized `#undoable?` Query Execution:** Calling `#undoable?` executes a single optimized `EXISTS` query (`joins(:undo_log).exists?(item_type: self.class.name, item_id: id)`). This checks for the presence of both the audit item and the valid parent log without loading records into Ruby memory.
+4. **Bypassing Callbacks:** Soft-deletion updates use `update_columns`. This executes a direct SQL `UPDATE` query without firing standard ActiveRecord persistence callbacks (`save`, `validate`), preventing unintended side effects during soft deletes.
+5. **Unscoped Model Resolution:** `#restore_item!` uses `klass.unscoped.find_by(id: item_id)` to locate records. This guarantees records are retrieved even when models define default scopes that filter out soft-deleted records.
+6. **Class Inheritance Security Check:** When constantizing stored class strings, the gem validates that target models inherit from `ActiveRecord::Base` to prevent arbitrary non-model constant manipulation.
 
 ---
 
@@ -177,8 +206,15 @@ sequenceDiagram
     - `undoable_column`: Caches the name of the column (defaults to `:deleted_at`).
     - `kept` scope: Returns records that are not soft-deleted (`where(column => nil)`).
     - `soft_deleted` scope: Returns records that are soft-deleted (`where.not(column => nil)`).
+    - `expired` scope: Returns records soft-deleted before the global retention period threshold.
 * **`soft_deleted?`**
   - *Function*: Checks if the current record instance has been soft-deleted. Returns `true` if the configured deletion column is populated with a timestamp.
+* **`undoable?`**
+  - *Function*: Checks if the soft-deleted record has a valid undo log entry available for restoration.
+  - *Steps*:
+    1. Returns `false` immediately if `soft_deleted?` is `false`.
+    2. Performs a lightweight SQL `EXISTS` query (`ActiveRecord::Undo::UndoLogItem.joins(:undo_log).exists?(item_type: self.class.name, item_id: id)`).
+    3. Returns `true` if both the log item and its parent `UndoLog` exist in the database.
 * **`soft_delete!`**
   - *Function*: Starts the cascade soft-deletion sequence for the record.
   - *Steps*:
@@ -196,6 +232,7 @@ sequenceDiagram
     3. Resolves the latest `UndoLogItem` that records the soft-deletion of this instance.
     4. If a log item is found, it calls `restore!` on the parent `UndoLog` (which restores the entire deleted tree).
     5. If no log item is found, it falls back to a simple, direct restore by setting the deletion column back to `nil`.
+    6. Automatically reloads the instance attributes in-memory (using `reload`) to refresh the model state before returning `true`.
 * **`ensure_undoable_column_exists!` (Private)**
   - *Function*: Asserts that the configured soft-delete column exists in the database schema table. Raises `ActiveRecord::Undo::Error` if missing.
 * **`find_latest_undo_log_item` (Private)**
@@ -259,3 +296,30 @@ sequenceDiagram
   - *Function*: Confirms that the target soft-delete column exists in the class's table schema. Throws `ActiveRecord::Undo::Error` if missing.
 * **`reset_soft_delete_column!(target, column_name)` (Private)**
   - *Function*: Bypasses standard callbacks and validations to write a `nil` value to the soft-delete column directly in the database.
+
+### 6.9 `lib/active_record/undo/configuration.rb` (Global Configuration)
+
+* **`Configuration#initialize`**
+  - *Function*: Instantiates default configurations for the gem.
+  - *Details*: Sets default `@retention_period` to `30.days`.
+
+### 6.10 `lib/active_record/undo/purger.rb` (Hard Purging Engine)
+
+* **`Purger.purge_expired!(batch_size: 1000)`**
+  - *Function*: Cleans up all database records and logs that are past their retention limits.
+  - *Steps*:
+    1. Delegates to `purge_expired_logs!(batch_size)` to find and clean up expired `UndoLog` and `UndoLogItem` entries in batches using direct SQL `delete_all` execution.
+    2. Delegates to `purge_expired_records!(batch_size)` to eager-load the host Rails application models (preventing Zeitwerk lazy-load gaps), identify expired records via the `.expired` scope, and hard-delete them and their cascading dependent associations in batches.
+  - *Relational Integrity & Constraint Protection*: Bottom-up recursive cascading deletes are performed first for associations marked as `:destroy`, `:delete_all`, or `:soft_delete`. For `:nullify` configurations, foreign key values are updated to `nil`, falling back to cascading deletion if the column contains a database-level `NOT NULL` constraint.
+
+### 6.11 `lib/active_record/undo/purge_job.rb` (Background Task Worker)
+
+* **`PurgeJob#perform(batch_size: 1000)`**
+  - *Function*: Runs inside ActiveJob (when available) to execute purging asynchronously.
+  - *Details*: Invokes `ActiveRecord::Undo::Purger.purge_expired!(batch_size: batch_size)`.
+
+### 6.12 `lib/active_record/undo/tasks/purge.rake` (Command Line Utility)
+
+* **`active_record_undo:purge_expired`**
+  - *Function*: Exposes CLI Rake task for the purger engine.
+  - *Details*: Checks `ENV['BATCH_SIZE']` for custom batch sizes, falling back to 1000, and triggers `ActiveRecord::Undo::Purger.purge_expired!`.

data/README.md

@@ -12,11 +12,13 @@ Unlike conventional soft-deletion gems, `active_record-undo` automatically captu
 ## Features
 
 - 🔄 **Cascading Soft Deletes:** Soft deletes parent models along with dependent associations (`dependent: :destroy` / `:delete_all`).
-- ⏪ **Atomic Restores:** Reverses soft deletion for an entire object tree (`undo_log.restore!`) within a single database transaction.
+- ⏪ **Atomic Restores:** Reverses soft deletion for an entire object tree (`undo_log.restore!` or `record.restore!`) within a single database transaction.
+- 🔍 **Restoration Verification:** Provides `#undoable?` to check if a record is soft-deleted and has a valid undo log entry available for restoration.
 - ⚙️ **Configurable Columns:** Supports custom soft-delete columns (e.g., `:archived_at`, `:discarded_at`) per model while defaulting to `:deleted_at`.
 - 📦 **Polymorphic Tracking:** Records deletion events via native `UndoLog` and `UndoLogItem` models—no messy JSON payload parsing required.
 - 🚂 **Zero Generator Setup:** Built on top of `Rails::Engine`. Migrations automatically hook into `rails db:migrate`.
-- 🔍 **Default Scopes & Helpers:** Provides `.kept`, `.soft_deleted`, and `#soft_deleted?` query methods out of the box.
+- 🔍 **Default Scopes & Helpers:** Provides `.kept`, `.soft_deleted`, `#soft_deleted?`, and `#undoable?` query methods out of the box.
+- 🧹 **Automatic Expiration & Purging:** Configurable global retention window with automated background purging (`PurgeJob` and Rake task) to clean up old soft-deleted records and logs.
 
 ---
 
@@ -121,6 +123,24 @@ item.soft_deleted? # => true
 item.archived_at   # => 2026-08-08 22:20:16 UTC
 ```
 
+### Checking Restoration Eligibility (`#undoable?`)
+
+Use `#undoable?` to verify if a record is soft-deleted and has a corresponding `UndoLog` entry available in the database. This is ideal for conditionally rendering UI elements or validating controller actions:
+
+```ruby
+post = Post.unscoped.find(1)
+
+if post.undoable?
+  # Render "Undo Deletion" button or execute restore
+  post.restore!
+end
+```
+
+`#undoable?` returns `false` if:
+* The record is currently active (not soft deleted).
+* The record was soft deleted manually via direct SQL/column updates without generating an undo log.
+* The corresponding `UndoLog` record was purged or already restored.
+
 ### Inspect Deletion Logs
 
 Inspect affected records through standard Rails associations on the returned `UndoLog`:
@@ -139,11 +159,11 @@ To restore a deleted object tree, you can invoke `restore!` either on the corres
 Calling `restore!` directly on the soft-deleted model automatically resolves its latest deletion event log, performs the cascading restore, and cleans up the log database rows:
 
 ```ruby
-# Restores the post and all comments deleted in the same batch
+# Restores the post and all comments deleted in the same batch (automatically reloads in-memory)
 post.restore!
 
-post.reload.soft_deleted? # => false
-post.comments.count       # => 2
+post.soft_deleted?  # => false
+post.comments.count # => 2
 ```
 
 #### Option B: Restore from the `UndoLog`
@@ -159,7 +179,7 @@ post.comments.count       # => 2
 
 ## Scopes & Querying
 
-`ActiveRecord::Undo` provides scopes for filtering records based on the configured column:
+`ActiveRecord::Undo` provides scopes and predicate helpers for filtering and checking records based on the configured column:
 
 ```ruby
 # Fetch only active (non-deleted) records
@@ -168,18 +188,94 @@ Post.kept
 # Fetch soft-deleted records
 Post.soft_deleted
 
+# Check if a record is soft-deleted
+post.soft_deleted?
+
+# Check if a record is soft-deleted AND can be restored via an undo log
+post.undoable?
+
 # Retrieve records including soft-deleted ones via unscoped
 Post.unscoped.where(id: 1)
 ```
 
 ---
 
+## Expiration, Retention & Auto-Purging
+
+To prevent database bloat, `active_record-undo` supports automated retention periods, expiration checks, and background purging for both soft-deleted records and their associated `UndoLog` audit entries.
+
+### 1. Global Configuration
+
+You can configure a global retention period inside a Rails initializer:
+
+```ruby
+# config/initializers/active_record_undo.rb
+ActiveRecord::Undo.configure do |config|
+  # Default retention period for all soft-deleted records and undo logs (defaults to 30.days)
+  config.retention_period = 30.days
+end
+```
+
+If `retention_period` is set to `nil`, records and logs will never expire.
+
+### 2. Expiration Scopes & Helpers
+
+The gem provides query scopes and instance predicate helpers:
+
+- **Model `.expired` Scope**: Returns soft-deleted records older than the configured retention period.
+  ```ruby
+  Post.expired # => ActiveRecord::Relation of posts soft-deleted > 30 days ago
+  ```
+- **Model `#expired?` Predicate**: Checks if a record is soft-deleted and past the retention period.
+  ```ruby
+  post.expired? # => true/false
+  ```
+- **`UndoLog.expired` Scope**: Returns undo log entries older than the retention period.
+  ```ruby
+  ActiveRecord::Undo::UndoLog.expired # => logs created > 30 days ago
+  ```
+
+### 3. Background Purging
+
+#### Purger Service
+The `ActiveRecord::Undo::Purger` class performs hard SQL deletes on expired records and logs using `delete_all` (bypassing callbacks and validations for efficiency):
+
+```ruby
+# Purge all expired soft-deleted records and undo logs in batches
+ActiveRecord::Undo::Purger.purge_expired!(batch_size: 1000)
+```
+
+> [!NOTE]
+> **Relational Integrity & Constraint Protection**: To prevent database-level foreign key constraint failures (e.g. `FOREIGN KEY constraint failed`), `Purger` dynamically resolves dependent associations (such as `dependent: :destroy`, `dependent: :delete_all`, or `dependent: :soft_delete`) and recursively purges associated child records bottom-up before deleting the parent record. For associations configured with `dependent: :nullify`, it nullifies the foreign key (or cascades the deletion if the foreign key column is database-restricted to be `NOT NULL`).
+
+#### ActiveJob Background Job
+The gem provides an ActiveJob class that calls the Purger service:
+
+```ruby
+# Enqueue the purge job to run in the background
+ActiveRecord::Undo::PurgeJob.perform_later(batch_size: 1000)
+```
+
+#### Engine Rake Task
+You can run the purge task via Rake. This task is automatically loaded into host applications:
+
+```bash
+# Run with the default batch size of 1000
+$ rails active_record_undo:purge_expired
+
+# Run with a custom batch size
+$ BATCH_SIZE=500 rails active_record_undo:purge_expired
+```
+
+---
+
 ## How It Works
 
 1. **Cascade Inspection:** When `soft_delete!` is called, `ActiveRecord::Undo::CascadeHandler` reflects on `has_many`, `has_one`, and `belongs_to` associations configured with `dependent: :destroy` or `:delete_all`.
 2. **Dynamic Column Resolution:** The handler checks `record.class.undoable_column` to set the correct timestamp column (`:deleted_at`, `:archived_at`, etc.) across all affected models.
 3. **Polymorphic Logging:** An `ActiveRecord::Undo::UndoLog` record is created alongside multiple `ActiveRecord::Undo::UndoLogItem` entries mapping polymorphic references (`item_type`, `item_id`) to every affected record.
-4. **Atomic Operation:** All updates and log creations take place within an `ActiveRecord::Base.transaction`.
+4. **Restoration Verification:** Calling `#undoable?` executes an efficient SQL query joining `undo_log_items` and `undo_logs` to ensure the entity is soft-deleted and its associated log entry exists before restoration.
+5. **Atomic Operation:** All updates and log creations take place within an `ActiveRecord::Base.transaction`.
 
 ---
 

data/lib/active_record/undo/configuration.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Undo
+    class Configuration
+      attr_accessor :retention_period
+
+      def initialize
+        @retention_period = 30.days
+      end
+    end
+  end
+end

data/lib/active_record/undo/engine.rb

@@ -14,6 +14,11 @@ module ActiveRecord
           end
         end
       end
+
+      rake_tasks do
+        path = root.join('lib', 'tasks', 'active_record_undo_tasks.rake')
+        load path if File.exist?(path)
+      end
     end
   end
 end

data/lib/active_record/undo/model_extension.rb

@@ -8,18 +8,44 @@ module ActiveRecord
     module ModelExtension
       extend ActiveSupport::Concern
 
-      class_methods do
+      module ClassMethods
         # Accept a custom column parameter, defaulting to :deleted_at
         def acts_as_undoable(column: :deleted_at)
           include InstanceMethods
 
+          define_undo_attributes!(column)
+          define_undo_scopes!
+
+          ActiveRecord::Undo.registered_models << self
+        end
+
+        private
+
+        def define_undo_attributes!(column)
           class_attribute :undoable_column
           self.undoable_column = column.to_sym
+        end
+
+        def define_undo_scopes!
+          define_basic_scopes!
+          define_expired_scope!
+        end
 
-          # Dynamic scopes using the configured column
+        def define_basic_scopes!
           scope :kept, -> { where(undoable_column => nil) }
           scope :soft_deleted, -> { where.not(undoable_column => nil) }
         end
+
+        def define_expired_scope!
+          scope :expired, lambda {
+            period = ActiveRecord::Undo.config.retention_period
+            if period
+              where("#{table_name}.#{undoable_column} < ?", Time.current - period)
+            else
+              none
+            end
+          }
+        end
       end
 
       module InstanceMethods
@@ -27,6 +53,25 @@ module ActiveRecord
           public_send(self.class.undoable_column).present?
         end
 
+        def expired?
+          return false unless soft_deleted?
+
+          period = ActiveRecord::Undo.config.retention_period
+          return false unless period
+
+          timestamp = public_send(self.class.undoable_column)
+          timestamp && timestamp < Time.current - period
+        end
+
+        def undoable?
+          return false unless soft_deleted?
+
+          ActiveRecord::Undo::UndoLogItem.joins(:undo_log).exists?(
+            item_type: self.class.name,
+            item_id: id
+          )
+        end
+
         def soft_delete!
           ensure_undoable_column_exists!
           return false if soft_deleted?
@@ -43,20 +88,16 @@ module ActiveRecord
           undo_log
         end
 
+        # rubocop:disable Naming/PredicateMethod
         def restore!
           ensure_undoable_column_exists!
           return false unless soft_deleted?
 
-          log_item = find_latest_undo_log_item
-
-          if log_item
-            log_item.undo_log.restore!
-          else
-            column_name = self.class.undoable_column
-            update_columns(column_name => nil, updated_at: Time.current)
-            true
-          end
+          restore_internally!(find_latest_undo_log_item)
+          reload
+          true
         end
+        # rubocop:enable Naming/PredicateMethod
 
         private
 
@@ -79,6 +120,15 @@ module ActiveRecord
         def soft_delete_cascade_internal!(timestamp, undo_log)
           CascadeHandler.new(self).soft_delete_with_cascade!(timestamp, undo_log)
         end
+
+        def restore_internally!(log_item)
+          if log_item
+            log_item.undo_log.restore!
+          else
+            column_name = self.class.undoable_column
+            update_columns(column_name => nil, updated_at: Time.current)
+          end
+        end
       end
     end
   end

data/lib/active_record/undo/purge_job.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+begin
+  require 'active_job'
+rescue LoadError
+  # ActiveJob is not available
+end
+
+if defined?(ActiveJob::Base)
+  module ActiveRecord
+    module Undo
+      class PurgeJob < ActiveJob::Base
+        queue_as :default
+
+        def perform(batch_size: 1000)
+          ActiveRecord::Undo::Purger.purge_expired!(batch_size: batch_size)
+        end
+      end
+    end
+  end
+end

data/lib/active_record/undo/purger.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Undo
+    class Purger
+      class << self
+        def purge_expired!(batch_size: 1000)
+          purge_expired_logs!(batch_size)
+          purge_expired_records!(batch_size)
+        end
+
+        private
+
+        def purge_expired_logs!(batch_size)
+          loop do
+            log_ids = UndoLog.expired.limit(batch_size).pluck(:id)
+            break if log_ids.empty?
+
+            UndoLogItem.where(undo_log_id: log_ids).delete_all
+            UndoLog.where(id: log_ids).delete_all
+          end
+        end
+
+        def purge_expired_records!(batch_size)
+          period = ActiveRecord::Undo.config.retention_period
+          return unless period
+
+          ActiveRecord::Undo.undoable_models.each do |model|
+            purge_model_expired_records!(model, batch_size)
+          end
+        end
+
+        def purge_model_expired_records!(model, batch_size)
+          primary_key = model.primary_key
+          loop do
+            expired_ids = model.expired.limit(batch_size).pluck(primary_key)
+            break if expired_ids.empty?
+
+            purge_records_with_cascade!(model, expired_ids, batch_size)
+          end
+        end
+
+        def purge_records_with_cascade!(model, record_ids, batch_size)
+          return if record_ids.empty?
+
+          nullify_dependent_associations!(model, record_ids)
+          purge_cascading_associations!(model, record_ids, batch_size)
+          delete_records!(model, record_ids)
+        end
+
+        def nullify_dependent_associations!(model, record_ids)
+          nullify_reflections(model).each do |reflection|
+            child_query_for(model, reflection, record_ids).update_all(reflection.foreign_key => nil)
+          end
+        end
+
+        def purge_cascading_associations!(model, record_ids, batch_size)
+          cascade_reflections(model).each do |reflection|
+            query = child_query_for(model, reflection, record_ids)
+            primary_key = reflection.klass.primary_key
+
+            query.pluck(primary_key).each_slice(batch_size) do |child_ids|
+              purge_records_with_cascade!(reflection.klass, child_ids, batch_size)
+            end
+          end
+        end
+
+        def child_query_for(model, reflection, record_ids)
+          query = reflection.klass.unscoped.where(reflection.foreign_key => record_ids)
+          query = query.where(reflection.type => model.name) if reflection.type
+          query
+        end
+
+        def delete_records!(model, record_ids)
+          model.unscoped.where(model.primary_key => record_ids).delete_all
+        end
+
+        def nullify_reflections(model)
+          model.reflections.values.select do |ref|
+            %i[has_many has_one].include?(ref.macro) &&
+              ref.options[:dependent] == :nullify &&
+              foreign_key_nullable?(ref)
+          end
+        end
+
+        def cascade_reflections(model)
+          model.reflections.values.select do |ref|
+            next false unless %i[has_many has_one].include?(ref.macro)
+
+            dependent = ref.options[:dependent]
+            %i[destroy soft_delete delete_all].include?(dependent) ||
+              non_nullable_nullify?(ref)
+          end
+        end
+
+        def non_nullable_nullify?(ref)
+          ref.options[:dependent] == :nullify && !foreign_key_nullable?(ref)
+        end
+
+        def foreign_key_nullable?(ref)
+          column = ref.klass.columns_hash[ref.foreign_key.to_s]
+          column.nil? || column.null
+        end
+      end
+    end
+  end
+end

data/lib/active_record/undo/tasks/purge.rake

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+namespace :active_record_undo do
+  desc 'Purge expired soft-deleted records and undo logs'
+  task purge_expired: :environment do
+    batch_size = ENV['BATCH_SIZE'] ? ENV['BATCH_SIZE'].to_i : 1000
+    ActiveRecord::Undo::Purger.purge_expired!(batch_size: batch_size)
+  end
+end

data/lib/active_record/undo/undo_log.rb

@@ -8,6 +8,15 @@ module ActiveRecord
 
       has_many :undo_log_items, class_name: 'ActiveRecord::Undo::UndoLogItem', dependent: :destroy
 
+      scope :expired, lambda {
+        period = ActiveRecord::Undo.config.retention_period
+        if period
+          where('created_at < ?', Time.current - period)
+        else
+          none
+        end
+      }
+
       # Restores all records associated with this deletion batch
       def restore!
         transaction do

data/lib/active_record/undo/version.rb

@@ -3,6 +3,6 @@
 
 module ActiveRecord
   module Undo
-    VERSION = '0.1.2'
+    VERSION = '0.1.4'
   end
 end

data/lib/active_record/undo.rb

@@ -9,15 +9,52 @@ rescue LoadError => e
         "Please add 'activerecord' to your Gemfile. (Original error: #{e.message})"
 end
 
+require 'set'
 require_relative 'undo/version'
 require_relative 'undo/engine' if defined?(Rails::Engine)
+require_relative 'undo/configuration'
 require_relative 'undo/model_extension'
 require_relative 'undo/undo_log'
 require_relative 'undo/undo_log_item'
+require_relative 'undo/purger'
+require_relative 'undo/purge_job'
 
 module ActiveRecord
   module Undo
     class Error < StandardError; end
+
+    class << self
+      def config
+        @config ||= Configuration.new
+      end
+
+      def configure
+        yield(config)
+      end
+
+      def registered_models
+        @registered_models ||= Set.new
+      end
+
+      def undoable_models
+        eager_load_rails!
+        models = registered_models.to_a
+        if defined?(ActiveRecord::Base)
+          models += ActiveRecord::Base.descendants.select { |m| m.respond_to?(:undoable_column) }
+        end
+        models.uniq
+      end
+
+      private
+
+      def eager_load_rails!
+        return unless defined?(Rails) && Rails.application
+
+        Rails.application.eager_load!
+      rescue StandardError
+        # Safe fallback if Rails eager loading fails in test environments
+      end
+    end
   end
 end
 

data/lib/tasks/active_record_undo_tasks.rake

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+path = File.expand_path('../active_record/undo/tasks/purge.rake', __dir__)
+load path if File.exist?(path)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_record-undo
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.4
 platform: ruby
 authors:
 - Saurabh Sharma
@@ -141,11 +141,16 @@ files:
 - lib/active_record/undo/cascade_handler.rb
 - lib/active_record/undo/cascade_handler/association_finder.rb
 - lib/active_record/undo/cascade_handler/record_updater.rb
+- lib/active_record/undo/configuration.rb
 - lib/active_record/undo/engine.rb
 - lib/active_record/undo/model_extension.rb
+- lib/active_record/undo/purge_job.rb
+- lib/active_record/undo/purger.rb
+- lib/active_record/undo/tasks/purge.rake
 - lib/active_record/undo/undo_log.rb
 - lib/active_record/undo/undo_log_item.rb
 - lib/active_record/undo/version.rb
+- lib/tasks/active_record_undo_tasks.rake
 - sig/active_record/undo.rbs
 homepage: https://github.com/saurabh-activecode/active_record-undo
 licenses: