trakable 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0dcab04bb1079556fb3f2f036a3e7d6a4ee423dc5d9ab31cb27ea41c4bbd4099
+  data.tar.gz: c7b63e5946469731c3ecacd67d013d44928f635308c70118a91b07adddc82887
+SHA512:
+  metadata.gz: ed12c7a3f09be0d82af29c7d47bc155a70c504c2f46370298e75e65fbad52706a3cf168f6a214d04f52b330f11c39b6404fd4a10de504cb646e33cfe0dbb6ff9
+  data.tar.gz: 654294059fa0e7c7a07531b702797988f0f6bedc491496d2c8ee8c37a3083927e02d60b24dc9e315c5c605796d18ac7d23b33219e08748c324084a307ebdd02c

data/.rubocop.yml

@@ -0,0 +1,81 @@
+plugins: []
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.1
+  SuggestExtensions: false
+  Exclude:
+    - benchmark/**/*
+    - integration/**/*
+    - vendor/**/*
+
+Metrics/BlockLength:
+  Exclude:
+    - test/**/*
+    - rakelib/**/*
+    - "*.gemspec"
+    - lib/trakable/model.rb
+
+Metrics/ClassLength:
+  Max: 200
+
+Metrics/MethodLength:
+  Max: 20
+  Exclude:
+    - test/**/*
+
+Metrics/ParameterLists:
+  Max: 6
+
+Metrics/AbcSize:
+  Exclude:
+    - test/**/*
+    - lib/trakable/revertable.rb
+
+Metrics/CyclomaticComplexity:
+  Exclude:
+    - lib/trakable/revertable.rb
+
+Metrics/PerceivedComplexity:
+  Exclude:
+    - lib/trakable/revertable.rb
+
+Lint/MissingSuper:
+  Exclude:
+    - lib/trakable/trak.rb
+
+Naming/MethodParameterName:
+  Exclude:
+    - test/**/*
+
+Style/OptionalBooleanParameter:
+  Exclude:
+    - test/**/*
+
+Layout/LineLength:
+  Exclude:
+    - "*.gemspec"
+
+Style/Documentation:
+  Exclude:
+    - test/**/*
+    - lib/trakable/version.rb
+    - lib/generators/**/*
+    - lib/trakable/railtie.rb
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Style/OneClassPerFile:
+  Exclude:
+    - test/**/*
+
+Style/WordArray:
+  Exclude:
+    - test/**/*
+
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+Gemspec/RequireMFA:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-03-20
+
+### Added
+
+- **Query scopes** on `Trakable::Trak` (AR-only): `for_item_type`, `for_event`, `for_whodunnit`, `created_before`, `created_after`, `recent`
+- **Batch deletion** in `run_retention` with configurable `batch_size` (default: 1,000) to avoid table locks
+- **CI/CD** via GitHub Actions (Ruby 3.1–3.4 matrix, tests + RuboCop)
+
+### Changed
+
+- **Cleanup is no longer synchronous** — `Cleanup.run` is no longer called after every trak creation. Run it from a background job instead.
+- `run_retention` now returns the total number of deleted rows (Integer) instead of `true`
+
+## [0.1.0] - 2026-03-20
+
+### Added
+
+- Initial release of Trakable gem
+- **Trak model** with JSON serialization for object, changeset, and metadata
+- **Polymorphic whodunnit** tracking (type + id) instead of string
+- **Trakable DSL** for ActiveRecord models with options:
+  - `only:` - track specific attributes
+  - `ignore:` - skip specific attributes
+  - `if:` / `unless:` - conditional tracking
+  - `on:` - selective events (create, update, destroy)
+- **Revertable module**:
+  - `reify` - build non-persisted record from Trak state
+  - `revert!` - restore record to previous state
+  - `trak_at` - get record state at specific timestamp
+- **Controller concern** with automatic whodunnit setting via `around_action`
+- **Cleanup module** with:
+  - `max_traks` - limit number of traks per record
+  - `retention` - automatic pruning of old traks
+- **Railtie** for Rails integration with:
+  - Configuration auto-loading from `config.trakable`
+  - Install generator for migration and initializer
+- **Thread-safe context** for storing whodunnit and metadata
+- **Global configuration** via `Trakable.configure`
+- Comprehensive README with usage examples
+- MIT License
+
+[0.2.0]: https://github.com/hadrienblanc/trakable/releases/tag/v0.2.0
+[0.1.0]: https://github.com/hadrienblanc/trakable/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hadrien Blanc
+
+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,330 @@
+# Trakable
+
+[![CI](https://github.com/hadrienblanc/trakable/actions/workflows/ci.yml/badge.svg)](https://github.com/hadrienblanc/trakable/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/trakable.svg)](https://rubygems.org/gems/trakable)
+[![Ruby](https://img.shields.io/badge/ruby-3.2%E2%80%934.0-red)](https://github.com/hadrienblanc/trakable)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+Audit logging and version tracking for ActiveRecord models.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'trakable'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install trakable
+```
+
+## Quick Start
+
+### 1. Generate the migration
+
+```bash
+$ rails generate trakable:install
+```
+
+This creates:
+- `db/migrate/create_traks.rb` - Migration for the traks table
+- `config/initializers/trakable.rb` - Configuration file
+
+Run the migration:
+
+```bash
+$ rails db:migrate
+```
+
+### 2. Add tracking to your models
+
+```ruby
+class Post < ApplicationRecord
+  include Trakable::Model
+
+  trakable only: %i[title body], ignore: %i[views_count]
+end
+```
+
+### 3. Whodunnit is automatic
+
+Trakable auto-includes its controller concern via Railtie. It calls `current_user` by default — no setup needed.
+
+To use a different method:
+
+```ruby
+Trakable.configure do |config|
+  config.whodunnit_method = :current_admin
+end
+```
+
+## Configuration
+
+### Global configuration
+
+In `config/initializers/trakable.rb`:
+
+```ruby
+Trakable.configure do |config|
+  # Enable/disable tracking globally
+  config.enabled = true
+
+  # Attributes to ignore by default
+  config.ignored_attrs = %w[created_at updated_at id]
+
+  # Controller method that returns the current user (default: :current_user)
+  config.whodunnit_method = :current_user
+end
+```
+
+### Per-model options
+
+```ruby
+class Post < ApplicationRecord
+  include Trakable::Model
+
+  trakable(
+    only: %i[title body],      # Only track these attributes
+    ignore: %i[views_count],   # Ignore these attributes
+    on: %i[create update destroy],  # Only track these events (default: all)
+    if: -> { published? },     # Conditional tracking
+    unless: -> { draft? }      # Skip if true
+  )
+end
+```
+
+## Usage
+
+### Accessing traks
+
+```ruby
+post = Post.first
+
+# Get all traks for a record
+post.traks
+
+# Get the last trak
+post.traks.last
+```
+
+### Trak properties
+
+```ruby
+trak = post.traks.last
+
+trak.event       # => "update"
+trak.create?     # => false
+trak.update?     # => true
+trak.destroy?    # => false
+
+trak.changeset   # => { "title" => ["Old Title", "New Title"] }
+trak.object      # => { "title" => "Old Title", "body" => "..." }
+trak.metadata    # => { "ip" => "192.168.1.1", "user_agent" => "..." }
+trak.created_at  # => 2024-01-15 10:30:00 UTC
+
+# Whodunnit (polymorphic)
+trak.whodunnit_type  # => "User"
+trak.whodunnit_id    # => 42
+trak.whodunnit       # => #<User id: 42, ...>
+```
+
+### Setting metadata
+
+You can add custom metadata to traks using the context:
+
+```ruby
+Trakable::Context.metadata = { ip: request.ip, user_agent: request.user_agent }
+post.update(title: "New Title")
+# The created trak will include the metadata
+```
+
+### Revert changes
+
+```ruby
+# Restore the record to the state before this trak
+post.traks.last.revert!
+
+# Revert and create a trak for the revert action
+post.traks.last.revert!(trak_revert: true)
+```
+
+### Time travel
+
+```ruby
+# Get the state at a specific point in time
+post.trak_at(1.day.ago)  # => Non-persisted record with state from 1 day ago
+
+# Get the state from a specific trak
+post.traks.last.reify  # => Non-persisted record with state at that trak
+```
+
+### Query scopes
+
+```ruby
+# Filter by model type
+Trakable::Trak.for_item_type('Post')
+
+# Filter by event
+Trakable::Trak.for_event(:update)
+
+# Filter by whodunnit
+Trakable::Trak.for_whodunnit(current_user)
+
+# Filter by time range
+Trakable::Trak.created_after(1.week.ago)
+Trakable::Trak.created_before(Date.yesterday)
+
+# Newest first
+Trakable::Trak.recent
+
+# Combine them
+Trakable::Trak.for_item_type('Post').for_event(:update).created_after(1.day.ago).recent
+```
+
+### Temporarily disable tracking
+
+```ruby
+# Disable tracking for a block
+Trakable.without_tracking do
+  post.update(title: "Won't be tracked")
+end
+
+# Force tracking when globally disabled
+Trakable.with_tracking do
+  post.update(title: "Will be tracked")
+end
+
+# Set whodunnit manually
+Trakable.with_user(current_user) do
+  post.update(title: "Tracked with user")
+end
+```
+
+### Cleanup
+
+Configure cleanup options per model:
+
+```ruby
+class Post < ApplicationRecord
+  include Trakable::Model
+
+  trakable max_traks: 100      # Keep only last 100 traks
+  trakable retention: 90.days  # Delete traks older than 90 days
+end
+```
+
+Cleanup is **not** automatic — call it from a background job to keep your traks table lean:
+
+```ruby
+# In a recurring job (e.g. daily cron)
+Trakable::Cleanup.run_retention(Post)
+
+# Per-record cleanup (e.g. after a batch import)
+Trakable::Cleanup.run(post)
+```
+
+### Edge cases
+
+```ruby
+# When no trak exists at the timestamp, returns current state
+post.trak_at(1.year.ago)  # => Returns current state if no older traks exist
+
+# When whodunnit record is deleted, returns nil
+trak.whodunnit  # => nil (if the user was deleted)
+
+# Revert on destroy re-creates the record (with new ID)
+destroy_trak = post.traks.where(event: 'destroy').last
+destroy_trak.revert!  # => Creates new record with same attributes but new ID
+```
+
+## API Reference
+
+### Trakable::Model
+
+| Method | Description |
+|--------|-------------|
+| `trakable(options)` | Configure tracking for this model |
+| `traks` | Association to all traks for this record |
+| `trak_at(timestamp)` | Get record state at a specific time |
+
+### Trakable::Trak
+
+| Method | Description |
+|--------|-------------|
+| `item` | The tracked record (polymorphic) |
+| `whodunnit` | The user who made the change (polymorphic) |
+| `event` | The event type: "create", "update", or "destroy" |
+| `changeset` | Hash of changed attributes with [old, new] values |
+| `object` | Changed attributes before the change (delta for updates, full snapshot for destroys) |
+| `create?` | True if this is a create event |
+| `update?` | True if this is an update event |
+| `destroy?` | True if this is a destroy event |
+| `reify` | Build non-persisted record with state at this trak |
+| `revert!` | Restore record to state before this trak |
+| `for_item_type(type)` | Scope: filter by item type |
+| `for_event(event)` | Scope: filter by event |
+| `for_whodunnit(user)` | Scope: filter by whodunnit (polymorphic) |
+| `created_before(time)` | Scope: traks before a timestamp |
+| `created_after(time)` | Scope: traks after a timestamp |
+| `recent` | Scope: newest first |
+
+### Trakable::Controller (auto-included via Railtie)
+
+| Option | Description |
+|--------|-------------|
+| `config.whodunnit_method` | Controller method that returns the current user (default: `:current_user`) |
+
+## Performance Tips
+
+### Eager loading (N+1 prevention)
+
+When loading multiple records with their traks, use `includes` to avoid N+1 queries:
+
+```ruby
+# Bad — N+1
+posts = Post.all
+posts.each { |p| p.traks.count }
+
+# Good — eager loaded
+posts = Post.includes(:traks).all
+posts.each { |p| p.traks.size }
+```
+
+### Compress serialized columns (Rails 7.1+)
+
+For large `object`/`changeset` payloads, enable column compression by adding a custom initializer:
+
+```ruby
+# config/initializers/trakable_compression.rb
+Rails.application.config.after_initialize do
+  Trakable::Trak.serialize :object, coder: JSON, compress: true
+  Trakable::Trak.serialize :changeset, coder: JSON, compress: true
+end
+```
+
+This uses zlib under the hood and can reduce storage by 60-80% for large payloads.
+
+## Differences from PaperTrail
+
+| Feature | PaperTrail | Trakable |
+|---------|------------|----------|
+| Whodunnit | String | Polymorphic (type + id) |
+| Changeset | Opt-in | Always stored |
+| Metadata | Not native | Built-in column |
+| Retention | Manual | Built-in (max_traks, retention) |
+| Serialization | YAML default | JSON only |
+| Table name | versions | traks |
+| Updated_at | Yes | No (immutable) |
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](./LICENSE).

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+end
+
+task default: :test
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new