active_record-undo 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30415ed66666364750a948cbbb06c6edffb88bff916bc5b7fc42d78ae027038d
-  data.tar.gz: 83f4abe357af730e23bf89f85e93e009cd6f6207a8bb313bb5972b67c1b6488e
+  metadata.gz: 3463f7d5263618417b5dc0bda22a13f8185b349c24d8b4e1610657afc5509564
+  data.tar.gz: d89197a34b065986d1f0060a83b6d5284af254ec4e9d2710de48549f60078e55
 SHA512:
-  metadata.gz: 4fc93992835bec03fff811b669ea856230b8498bb53e81b62be8e85e6d7d047d0f644f9568de5bf337d77bd4b2ed20f2a36b00155f8b8021c3a358e6bbb0b710
-  data.tar.gz: a1afbb6efc8ce17b31b8f2a8b863e94c0c5d1f04ad4eb475d21a5599f525845002ced413793b8139d1241e936aaac2d3754b89ff11a3a4b2e139c42aa7756bec
+  metadata.gz: 6daed055a8e31d9ce9386c92943b9e07133ca69aa0f782412d032e090491cfcc080054359fa7e9340b78563addf9dc17cf3cc6dabed4baffda12a611bf32e5ff
+  data.tar.gz: 3259b19bec3a4519ad5dda5b3d56dc94ff3ff6c4d4853fb81cdde33556cbbc530689875863a00893ac277bd042f9153261f4413ff0ad6a9dd87fcc26d09d6091

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,7 +42,7 @@ 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 |
@@ -117,6 +119,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 +171,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.
 
 ---
 
@@ -179,6 +204,12 @@ sequenceDiagram
     - `soft_deleted` scope: Returns records that are soft-deleted (`where.not(column => nil)`).
 * **`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*:
@@ -258,4 +289,4 @@ sequenceDiagram
 * **`ensure_column_exists!(klass, column_name)` (Private)**
   - *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.
+  - *Function*: Bypasses standard callbacks and validations to write a `nil` value to the soft-delete column directly in the database.

data/README.md

@@ -12,11 +12,12 @@ 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.
 
 ---
 
@@ -121,6 +122,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`:
@@ -159,7 +178,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,6 +187,12 @@ 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)
 ```
@@ -179,7 +204,8 @@ Post.unscoped.where(id: 1)
 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/model_extension.rb

@@ -27,6 +27,15 @@ module ActiveRecord
           public_send(self.class.undoable_column).present?
         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?

data/lib/active_record/undo/version.rb

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

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.3
 platform: ruby
 authors:
 - Saurabh Sharma