active_record-undo 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c421e5d58b60163d2abd5d6acc9033b9a96dbcdc0cd628b49d30bc0e0631d88c
+  data.tar.gz: f283ee35d356473309b5fbbcff68793765a4e307e31cbdcc82b5bd0c91b312d5
+SHA512:
+  metadata.gz: 0dfc203a6c9a27028cdddcdbec738a680ea177c3ada73c8e46f3ad836aa2c95402b985f78003ce74f1b421bf3ee84ee7e821ee2350d6eeb5fa5f03b15998fa13
+  data.tar.gz: d2d46f0384fbe4a0fe0ff8fd654732ca52405c90cd511eff2b9148a7b9aad83be94462927bfa46152ed3b07ecb1cb9015a8dc4804f96add8468d394ca8a03ff7

data/.rubocop.yml

@@ -0,0 +1,44 @@
+AllCops:
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - 'bin/**/*'
+    - 'db/schema.rb'
+    - 'spec/internal/**/*'
+    - 'vendor/**/*'
+
+Style/Documentation:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+
+Layout/LineLength:
+  Max: 120
+
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - 'active_record-undo.gemspec'
+
+Naming/VariableNumber:
+  Enabled: false
+
+Metrics/MethodLength:
+  Max: 10
+
+Metrics/AbcSize:
+  Max: 15
+
+Metrics/CyclomaticComplexity:
+  Max: 7
+  Exclude:
+    - 'db/migrate/**/*'
+
+Metrics/PerceivedComplexity:
+  Max: 7
+  Exclude:
+    - 'db/migrate/**/*'

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-08-08
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/DOCUMENTATION.md

@@ -0,0 +1,261 @@
+# ActiveRecord::Undo Architecture & Technical Documentation
+
+`ActiveRecord::Undo` is a Rails Engine gem providing transactional, cascade-aware soft deletion and restoration capabilities for ActiveRecord models. It records state transitions into a dedicated polymorphic audit structure within single database transactions.
+
+---
+
+## 1. System Architecture Overview
+
+```mermaid
+graph TD
+    SubGraphHostApp[Host Rails Application Models] -->|acts_as_undoable| ModelExt[ActiveRecord::Undo::ModelExtension]
+    
+    subgraph GemCore[ActiveRecord::Undo Core Engine]
+        ModelExt -->|Calls soft_delete!| TxBoundary[ActiveRecord::Base.transaction]
+        
+        subgraph TxBoundary
+            CreateLog[Create UndoLog Parent]
+            CreateLog --> Cascade[CascadeHandler Engine]
+            Cascade -->|Reflects Associations| AssociationLoop{Has Dependent Relations?}
+            AssociationLoop -->|Yes| RecursiveCall[Recurse soft_delete_cascade_internal!]
+            AssociationLoop -->|No / Completed| UpdateCol[update_columns timestamp]
+            UpdateCol --> AppendItem[Build UndoLogItem Record]
+        end
+        
+        TxBoundary --> LogResult[Return UndoLog Instance]
+    end
+
+    subgraph DatabaseStorage[Persistence Layer]
+        AppendItem --> UndoLogTable[(undo_logs)]
+        AppendItem --> UndoItemTable[(undo_log_items)]
+    end
+```
+
+---
+
+## 2. Core Components & Responsibilities
+
+### Component Summary
+
+| 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!`) |
+| **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 |
+
+---
+
+## 3. Data Model & Database Design
+
+```mermaid
+erDiagram
+    UNDO_LOGS ||--|{ UNDO_LOG_ITEMS : "has_many"
+    UNDO_LOG_ITEMS }|--|| TARGET_MODEL : "belongs_to (polymorphic)"
+
+    UNDO_LOGS {
+        bigint id PK
+        datetime created_at
+        datetime updated_at
+      }
+
+    UNDO_LOG_ITEMS {
+        bigint id PK
+        bigint undo_log_id FK
+        string item_type
+        bigint item_id
+        datetime created_at
+        datetime updated_at
+      }
+
+    TARGET_MODEL {
+        bigint id PK
+        datetime deleted_at "or custom column"
+      }
+```
+
+---
+
+## 4. Sequence Diagrams
+
+### Soft Deletion Flow (`#soft_delete!`)
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User
+    participant Model as Post Model
+    participant Ext as ModelExtension
+    participant Tx as DB Transaction
+    participant Log as UndoLog
+    participant Cascade as CascadeHandler
+    participant Child as Comment Model
+
+    User->>Model: post.soft_delete!
+    Model->>Ext: Check soft_deleted?
+    Ext-->>Model: false
+    Model->>Tx: Open ActiveRecord::Base.transaction
+    Tx->>Log: UndoLog.create!
+    Tx->>Cascade: CascadeHandler.new(post).soft_delete_with_cascade!
+    
+    rect rgb(240, 240, 240)
+        note over Cascade, Child: Dynamic Association Reflection
+        Cascade->>Cascade: Inspect Post.reflections (:comments)
+        Cascade->>Child: Recurse soft_delete_cascade_internal!
+        Child->>Child: update_columns(deleted_at: timestamp)
+        Child->>Log: undo_log_items.build(item: comment_101)
+    end
+
+    Cascade->>Model: update_columns(deleted_at: timestamp)
+    Cascade->>Log: undo_log_items.build(item: post)
+    Log->>Tx: undo_log.save!
+    Tx-->>Model: Commit Transaction
+    Model-->>User: Returns UndoLog Instance
+```
+
+### Restoration Flow (`#restore!`)
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User
+    participant Log as UndoLog
+    participant Item as UndoLogItem
+    participant Model as Target Models
+
+    User->>Log: undo_log.restore!
+    Log->>Log: Open ActiveRecord::Base.transaction
+    
+    rect rgb(240, 240, 240)
+        note over Log, Model: Reverse Order Processing (Bottom-Up)
+        Log->>Item: undo_log_items.reverse_each
+        Item->>Model: TargetClass.unscoped.find_by(id)
+        Item->>Model: target.update_columns(column_name => nil)
+    end
+
+    Log->>Log: destroy! (Deletes UndoLog & UndoLogItems)
+    Log-->>User: Restoration Complete
+```
+
+---
+
+## 5. Key Technical Considerations
+
+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.
+
+---
+
+## 6. Method-by-Method Implementation Reference
+
+### 6.1 `lib/active_record/undo.rb` (Entrypoint)
+
+* **`require 'active_record'` Loader Check**
+  - *Function*: Safely imports ActiveRecord. If ActiveRecord is not in the load path, it catches the `LoadError` and throws a detailed error instructing the developer to add `activerecord` to their `Gemfile`.
+* **Loader Hook Block**
+  - *Function*: Detects if `ActiveSupport` is loaded:
+    - If present, registers `ActiveSupport.on_load(:active_record)` to inject the extension module when ActiveRecord boots.
+    - If absent (e.g. running in simple Ruby scripts), directly includes `ModelExtension` into `ActiveRecord::Base` as a fallback.
+
+### 6.2 `lib/active_record/undo/engine.rb` (Rails Integration)
+
+* **`initializer 'active_record_undo.migrations'`**
+  - *Function*: Automatically runs on Rails boot to append the gem's engine migrations directory to the host application's migrations search paths. This allows host applications to detect and run gem database migrations without needing to manually copy them into the application's workspace.
+
+### 6.3 `lib/active_record/undo/model_extension.rb` (Model Extension Module)
+
+* **`acts_as_undoable(column: :deleted_at)`**
+  - *Function*: Class-level DSL macro injected into models to enable soft-deletion.
+  - *Details*: Defines class-level configurations:
+    - `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)`).
+* **`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.
+* **`soft_delete!`**
+  - *Function*: Starts the cascade soft-deletion sequence for the record.
+  - *Steps*:
+    1. Calls `ensure_undoable_column_exists!` to verify the database column is present.
+    2. Aborts and returns `false` if the record is already soft-deleted.
+    3. Opens an ActiveRecord database transaction block.
+    4. Creates a new parent `UndoLog` object.
+    5. Recursively invokes cascading soft-deletes on associations and marks the record itself as soft-deleted via `CascadeHandler`.
+    6. Saves the transaction and returns the constructed `UndoLog`.
+* **`restore!`**
+  - *Function*: Restores the record from its soft-deleted state.
+  - *Steps*:
+    1. Verifies column presence via `ensure_undoable_column_exists!`.
+    2. Aborts and returns `false` if the record is not soft-deleted.
+    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`.
+* **`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)**
+  - *Function*: Queries `UndoLogItem` records pointing to this record, ordering by `created_at DESC` to find the most recent deletion event.
+* **`soft_delete_cascade_internal!(timestamp, undo_log)` (Private)**
+  - *Function*: Wraps instantiation and invocation of `CascadeHandler` to encapsulate cascade traversal.
+
+### 6.4 `lib/active_record/undo/cascade_handler.rb` (Cascade Execution)
+
+* **`initialize(record)`**
+  - *Function*: Caches the record instance to be cascade deleted.
+* **`soft_delete_with_cascade!(timestamp, undo_log)`**
+  - *Function*: Coordinates the cascade deletion of the current record.
+  - *Steps*:
+    1. Invokes `#cascade_to_associations!` to recurse into child tables.
+    2. Invokes `#update_record_timestamps!` to mark the current record as soft-deleted.
+    3. Appends an `UndoLogItem` pointing to this record to the `UndoLog` transaction.
+* **`cascade_to_associations!(timestamp, undo_log)` (Private)**
+  - *Function*: Iterates over reflections retrieved by `AssociationFinder`, fetches their records, and calls `#cascade_to_record!` on each associated record.
+* **`cascade_to_record!(associated, reflection, timestamp, undo_log)` (Private)**
+  - *Function*: Handles deletion of a single associated child record:
+    - Excludes it if it is already soft-deleted.
+    - If the child model is also configured with `acts_as_undoable`, calls its private `#soft_delete_cascade_internal!` recursively.
+    - If it is not undoable, but configured with `dependent: :destroy`, it invokes `#destroy!` to perform a hard-deletion.
+
+### 6.5 `lib/active_record/undo/cascade_handler/association_finder.rb` (Reflections Finder)
+
+* **`associations_to_cascade` (Private)**
+  - *Function*: Reflects on the model's association metadata and filters list of associations to select only those configured with `dependent: :destroy`, `dependent: :soft_delete`, or `dependent: :delete_all`.
+* **`associated_records_for(reflection)` (Private)**
+  - *Function*: Fetches associated target records. Normalizes single relations and collection associations (like `has_many`) into a flat array structure.
+
+### 6.6 `lib/active_record/undo/cascade_handler/record_updater.rb` (Timestamps Updater)
+
+* **`update_record_timestamps!(timestamp)` (Private)**
+  - *Function*: Bypasses ActiveRecord validations, callbacks, and dirty checking to directly write updates for the soft-delete column and `updated_at` timestamps using database-level `update_columns`.
+
+### 6.7 `lib/active_record/undo/undo_log.rb` (Batch Restoration)
+
+* **`restore!`**
+  - *Function*: Triggers database restoration of the entire tree recorded under this log.
+  - *Steps*:
+    1. Opens a database transaction block.
+    2. Iterates over associated `undo_log_items` in *reverse order* (`reverse_each`), guaranteeing parent records are restored before child records.
+    3. Invokes `#restore_item!` on each item.
+    4. Automatically calls `#destroy!` on completion to purge the audit records (`UndoLog` and nested `UndoLogItem` rows) from the database.
+
+### 6.8 `lib/active_record/undo/undo_log_item.rb` (Item Restoration)
+
+* **`restore_item!`**
+  - *Function*: Performs restoration of the individual record referenced by the audit log item.
+  - *Steps*:
+    1. Resolves model class via `#resolve_model_class`.
+    2. Resolves target record using `unscoped.find_by(id: item_id)` (unscoping ignores default scopes filtering soft-deleted records).
+    3. Ensures the soft-delete column exists on the model table.
+    4. Resets the soft-delete column to `nil` using `#reset_soft_delete_column!`.
+* **`resolve_model_class` (Private)**
+  - *Function*: Constantizes the stored `item_type` string.
+  - *Security*: Asserts that the constant is a valid class that inherits from `ActiveRecord::Base`. Raises `ActiveRecord::Undo::Error` if constantization fails or targets non-model classes.
+* **`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.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Saurabh Sharma
+
+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,217 @@
+# ActiveRecord::Undo
+
+[![Gem Version](https://badge.fury.io/rb/active_record-undo.svg)](https://badge.fury.io/rb/active_record-undo)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**ActiveRecord::Undo** brings transactional, cascade-aware soft deletes and automatic restores to Rails applications.
+
+Unlike conventional soft-deletion gems, `active_record-undo` automatically captures an audit snapshot of all records affected across associations (e.g., dependent `has_many` or `has_one` relations) and tracks them in a dedicated polymorphic undo log. Restoring a deleted record cleanly restores its entire deleted child tree in a single atomic database transaction.
+
+---
+
+## 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.
+- ⚙️ **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.
+
+---
+
+## Installation
+
+Add this line to your application's `Gemfile`:
+
+```ruby
+gem "active_record-undo"
+```
+
+Then execute:
+
+```bash
+$ bundle install
+```
+
+Run database migrations. The gem automatically appends its tables (`undo_logs` and `undo_log_items`) to your app's migration path:
+
+```bash
+$ rails db:migrate
+```
+
+*(Optional)* If you need to customize the migration, copy it to your host application's `db/migrate` folder:
+
+```bash
+$ rails active_record_undo:install:migrations
+```
+
+---
+
+## Usage
+
+### 1. Database Setup
+
+Ensure models using soft deletion have a timestamp column in their underlying database table:
+
+```ruby
+class AddSoftDeleteColumnsToModels < ActiveRecord::Migration[7.0]
+  def change
+    add_column :posts, :deleted_at, :datetime
+    add_column :comments, :deleted_at, :datetime
+    add_column :archive_items, :archived_at, :datetime
+
+    add_index :posts, :deleted_at
+    add_index :comments, :deleted_at
+    add_index :archive_items, :archived_at
+  end
+end
+```
+
+### 2. Configure Models
+
+Add `acts_as_undoable` to models where you want soft deletion enabled. By default, it uses `:deleted_at`, but you can pass a custom column name:
+
+```ruby
+class Post < ApplicationRecord
+  # Uses default :deleted_at column
+  acts_as_undoable
+
+  has_many :comments, dependent: :destroy
+end
+
+class Comment < ApplicationRecord
+  # Uses default :deleted_at column
+  acts_as_undoable
+
+  belongs_to :post
+end
+
+class ArchiveItem < ApplicationRecord
+  # Configured with a custom column
+  acts_as_undoable column: :archived_at
+end
+```
+
+---
+
+## Quick Start Guide
+
+### Soft Delete & Cascade
+
+Call `soft_delete!` on a record. It sets the configured soft-delete column across the record and its dependent relations inside a single transaction, returning an `ActiveRecord::Undo::UndoLog` instance:
+
+```ruby
+post = Post.find(1)
+
+# Soft deletes post and all associated comments
+undo_log = post.soft_delete!
+
+post.soft_deleted? # => true
+post.comments.kept.count # => 0
+```
+
+### Custom Column Usage
+
+```ruby
+item = ArchiveItem.find(5)
+item.soft_delete!
+
+item.soft_deleted? # => true
+item.archived_at   # => 2026-08-08 22:20:16 UTC
+```
+
+### Inspect Deletion Logs
+
+Inspect affected records through standard Rails associations on the returned `UndoLog`:
+
+```ruby
+# List all items affected by this deletion event
+undo_log.undo_log_items.map(&:item)
+# => [#<Comment 101... id:>, #<Comment 102... id:>, #<Post 1... id:>]
+```
+
+### Restoring Records
+
+To restore a deleted object tree, you can invoke `restore!` either on the corresponding `UndoLog` or directly on the model instance itself:
+
+#### Option A: Restore from the model instance (Recommended)
+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
+post.restore!
+
+post.reload.soft_deleted? # => false
+post.comments.count       # => 2
+```
+
+#### Option B: Restore from the `UndoLog`
+```ruby
+# Reverses soft deletes for the post and comments
+undo_log.restore!
+
+post.reload.soft_deleted? # => false
+post.comments.count       # => 2
+```
+
+---
+
+## Scopes & Querying
+
+`ActiveRecord::Undo` provides scopes for filtering records based on the configured column:
+
+```ruby
+# Fetch only active (non-deleted) records
+Post.kept
+
+# Fetch soft-deleted records
+Post.soft_deleted
+
+# Retrieve records including soft-deleted ones via unscoped
+Post.unscoped.where(id: 1)
+```
+
+---
+
+## 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`.
+
+---
+
+## Error Handling
+
+To ensure database integrity and provide clear debugging context, the gem raises an `ActiveRecord::Undo::Error` in the following scenarios:
+* **Missing Column at Runtime:** If the configured soft-delete column is missing from the database table when calling `soft_delete!` or `restore!`.
+* **Missing Model Class:** If a model class has been renamed or deleted, preventing the polymorphic log items from finding the target class during restore.
+* **Missing Column on Target Class:** If a model class exists but no longer has the target soft-delete column during restore.
+
+---
+
+## Development
+
+After cloning the repository, install dependencies:
+
+```bash
+$ bundle install
+```
+
+Run test suite via RSpec:
+
+```bash
+$ bundle exec rspec
+```
+
+---
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/saurabh-activecode/active_record-undo.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/db/migrate/20260808000000_create_active_record_undo_tables.rb

@@ -0,0 +1,16 @@
+# db/migrate/20260808000000_create_active_record_undo_tables.rb
+# frozen_string_literal: true
+
+class CreateActiveRecordUndoTables < ActiveRecord::Migration[7.0]
+  def change
+    create_table :undo_logs, &:timestamps
+
+    create_table :undo_log_items do |t|
+      t.references :undo_log, null: false, foreign_key: { to_table: :undo_logs }
+      t.references :item, polymorphic: true, null: false
+      t.timestamps
+    end
+
+    add_index :undo_log_items, %i[item_type item_id]
+  end
+end

data/lib/active_record/undo/cascade_handler/association_finder.rb

@@ -0,0 +1,25 @@
+# lib/active_record/undo/cascade_handler/association_finder.rb
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Undo
+    class CascadeHandler
+      module AssociationFinder
+        private
+
+        def associations_to_cascade
+          @record.class.reflections.values.select do |reflection|
+            %i[destroy soft_delete delete_all].include?(reflection.options[:dependent])
+          end
+        end
+
+        def associated_records_for(reflection)
+          target = @record.public_send(reflection.name)
+          return [] if target.nil?
+
+          target.is_a?(Enumerable) ? target : [target]
+        end
+      end
+    end
+  end
+end

data/lib/active_record/undo/cascade_handler/record_updater.rb

@@ -0,0 +1,21 @@
+# lib/active_record/undo/cascade_handler/record_updater.rb
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Undo
+    class CascadeHandler
+      module RecordUpdater
+        private
+
+        def update_record_timestamps!(timestamp)
+          column_name = @record.class.respond_to?(:undoable_column) ? @record.class.undoable_column : :deleted_at
+
+          @record.update_columns(
+            column_name => timestamp,
+            updated_at: timestamp
+          )
+        end
+      end
+    end
+  end
+end

data/lib/active_record/undo/cascade_handler.rb

@@ -0,0 +1,44 @@
+# lib/active_record/undo/cascade_handler.rb
+# frozen_string_literal: true
+
+require_relative 'cascade_handler/association_finder'
+require_relative 'cascade_handler/record_updater'
+
+module ActiveRecord
+  module Undo
+    class CascadeHandler
+      include AssociationFinder
+      include RecordUpdater
+
+      def initialize(record)
+        @record = record
+      end
+
+      def soft_delete_with_cascade!(timestamp, undo_log)
+        cascade_to_associations!(timestamp, undo_log)
+        update_record_timestamps!(timestamp)
+        undo_log.undo_log_items.build(item: @record)
+      end
+
+      private
+
+      def cascade_to_associations!(timestamp, undo_log)
+        associations_to_cascade.each do |reflection|
+          associated_records_for(reflection).each do |associated|
+            cascade_to_record!(associated, reflection, timestamp, undo_log)
+          end
+        end
+      end
+
+      def cascade_to_record!(associated, reflection, timestamp, undo_log)
+        return if associated.respond_to?(:soft_deleted?) && associated.soft_deleted?
+
+        if associated.respond_to?(:soft_delete_cascade_internal!, true)
+          associated.send(:soft_delete_cascade_internal!, timestamp, undo_log)
+        elsif reflection.options[:dependent] == :destroy
+          associated.destroy!
+        end
+      end
+    end
+  end
+end

data/lib/active_record/undo/engine.rb

@@ -0,0 +1,19 @@
+# lib/active_record/undo/engine.rb
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Undo
+    class Engine < ::Rails::Engine
+      isolate_namespace ActiveRecord::Undo
+
+      # Automatically appends gem migrations to the host application's migration path
+      initializer 'active_record_undo.migrations' do |app|
+        unless app.root.to_s.match?(root.to_s)
+          config.paths['db/migrate'].expanded.each do |expanded_path|
+            app.config.paths['db/migrate'] << expanded_path
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_record/undo/model_extension.rb

@@ -0,0 +1,85 @@
+# lib/active_record/undo/model_extension.rb
+# frozen_string_literal: true
+
+require_relative 'cascade_handler'
+
+module ActiveRecord
+  module Undo
+    module ModelExtension
+      extend ActiveSupport::Concern
+
+      class_methods do
+        # Accept a custom column parameter, defaulting to :deleted_at
+        def acts_as_undoable(column: :deleted_at)
+          include InstanceMethods
+
+          class_attribute :undoable_column
+          self.undoable_column = column.to_sym
+
+          # Dynamic scopes using the configured column
+          scope :kept, -> { where(undoable_column => nil) }
+          scope :soft_deleted, -> { where.not(undoable_column => nil) }
+        end
+      end
+
+      module InstanceMethods
+        def soft_deleted?
+          public_send(self.class.undoable_column).present?
+        end
+
+        def soft_delete!
+          ensure_undoable_column_exists!
+          return false if soft_deleted?
+
+          undo_log = nil
+          timestamp = Time.current
+
+          transaction do
+            undo_log = ActiveRecord::Undo::UndoLog.create!
+            soft_delete_cascade_internal!(timestamp, undo_log)
+            undo_log.save!
+          end
+
+          undo_log
+        end
+
+        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
+        end
+
+        private
+
+        def ensure_undoable_column_exists!
+          column_name = self.class.undoable_column
+          return if self.class.column_names.include?(column_name.to_s)
+
+          raise ActiveRecord::Undo::Error,
+                "The configured soft-delete column '#{column_name}' " \
+                "does not exist on table '#{self.class.table_name}'."
+        end
+
+        def find_latest_undo_log_item
+          ActiveRecord::Undo::UndoLogItem
+            .where(item: self)
+            .order(created_at: :desc)
+            .first
+        end
+
+        def soft_delete_cascade_internal!(timestamp, undo_log)
+          CascadeHandler.new(self).soft_delete_with_cascade!(timestamp, undo_log)
+        end
+      end
+    end
+  end
+end

data/lib/active_record/undo/undo_log.rb

@@ -0,0 +1,21 @@
+# lib/active_record/undo/undo_log.rb
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Undo
+    class UndoLog < ActiveRecord::Base
+      self.table_name = 'undo_logs'
+
+      has_many :undo_log_items, class_name: 'ActiveRecord::Undo::UndoLogItem', dependent: :destroy
+
+      # Restores all records associated with this deletion batch
+      def restore!
+        transaction do
+          # Reverse order ensures child records are restored before or after parents as needed
+          undo_log_items.reverse_each(&:restore_item!)
+          destroy! # Clean up log after successful restoration
+        end
+      end
+    end
+  end
+end

data/lib/active_record/undo/undo_log_item.rb

@@ -0,0 +1,56 @@
+# lib/active_record/undo/undo_log_item.rb
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Undo
+    class UndoLogItem < ActiveRecord::Base
+      self.table_name = 'undo_log_items'
+
+      belongs_to :undo_log, class_name: 'ActiveRecord::Undo::UndoLog'
+      belongs_to :item, polymorphic: true
+
+      def restore_item!
+        klass = resolve_model_class
+        target = klass.unscoped.find_by(id: item_id)
+        return unless target
+
+        column_name = klass.respond_to?(:undoable_column) ? klass.undoable_column : :deleted_at
+        ensure_column_exists!(klass, column_name)
+
+        return unless target.public_send(column_name).present?
+
+        reset_soft_delete_column!(target, column_name)
+      end
+
+      private
+
+      def resolve_model_class
+        klass = item_type.constantize
+        unless klass.is_a?(Class) && klass < ActiveRecord::Base
+          raise ActiveRecord::Undo::Error,
+                "Cannot restore item: '#{item_type}' is not an ActiveRecord model."
+        end
+
+        klass
+      rescue NameError => e
+        raise ActiveRecord::Undo::Error,
+              "Cannot restore item: model class '#{item_type}' could not be loaded. " \
+              "Original error: #{e.message}"
+      end
+
+      def ensure_column_exists!(klass, column_name)
+        return if klass.column_names.include?(column_name.to_s)
+
+        raise ActiveRecord::Undo::Error,
+              "Cannot restore item: column '#{column_name}' does not exist on '#{item_type}' model."
+      end
+
+      def reset_soft_delete_column!(target, column_name)
+        target.update_columns(
+          column_name => nil,
+          updated_at: Time.current
+        )
+      end
+    end
+  end
+end

data/lib/active_record/undo/version.rb

@@ -0,0 +1,8 @@
+# lib/active_record/undo/version.rb
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Undo
+    VERSION = '0.1.1'
+  end
+end

data/lib/active_record/undo.rb

@@ -0,0 +1,31 @@
+# lib/active_record/undo.rb
+# frozen_string_literal: true
+
+begin
+  require 'active_record'
+rescue LoadError => e
+  raise LoadError,
+        'active_record-undo requires ActiveRecord. ' \
+        "Please add 'activerecord' to your Gemfile. (Original error: #{e.message})"
+end
+
+require_relative 'undo/version'
+require_relative 'undo/engine' if defined?(Rails::Engine)
+require_relative 'undo/model_extension'
+require_relative 'undo/undo_log'
+require_relative 'undo/undo_log_item'
+
+module ActiveRecord
+  module Undo
+    class Error < StandardError; end
+  end
+end
+
+if defined?(ActiveSupport)
+  ActiveSupport.on_load(:active_record) do
+    include ActiveRecord::Undo::ModelExtension
+  end
+elsif defined?(ActiveRecord::Base)
+  # Fallback for bare Ruby scripts where ActiveSupport hooks aren't initialized yet
+  ActiveRecord::Base.include(ActiveRecord::Undo::ModelExtension)
+end

data/sig/active_record/undo.rbs

@@ -0,0 +1,6 @@
+module ActiveRecord
+  module Undo
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

metadata

@@ -0,0 +1,173 @@
+--- !ruby/object:Gem::Specification
+name: active_record-undo
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Saurabh Sharma
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.0
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: combustion
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.4'
+description: Provides soft deletion and automatic restoration of records and their
+  dependent associations.
+email:
+- saurabh@activecode.in
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- DOCUMENTATION.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- db/migrate/20260808000000_create_active_record_undo_tables.rb
+- lib/active_record/undo.rb
+- 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/engine.rb
+- lib/active_record/undo/model_extension.rb
+- lib/active_record/undo/undo_log.rb
+- lib/active_record/undo/undo_log_item.rb
+- lib/active_record/undo/version.rb
+- sig/active_record/undo.rbs
+homepage: https://github.com/saurabh-activecode/active_record-undo
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/saurabh-activecode/active_record-undo
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Soft-delete extension for ActiveRecord with transactional cascade undo tracking.
+test_files: []