Nostalgic

A Rails engine gem that adds effective-dated attribute versioning to ActiveRecord models. Declare an attribute as "nostalgic" and the gem transparently stores its full history — you can query any attribute's value as of any past or future date without changing your application's existing interface.

• Ruby >= 3.0, < 3.5
• Rails >= 7.0

Add to your application's Gemfile:

gem "nostalgic"

Then run:

bundle install

Install the migration:

bin/rails nostalgic:install:migrations
bin/rails db:migrate

Include the JavaScript and stylesheet in your asset pipeline. In app/assets/javascripts/application.js:

//= require nostalgic

In app/assets/stylesheets/application.css:

/*
 *= require nostalgic
 */

Nostalgic's JavaScript requires jQuery and jQuery UI (datepicker). These must be provided by your application.

Call nostalgic_attr in your model with the attribute names you want to version:

class User < ApplicationRecord
  nostalgic_attr :tel, :salary
end

This is all you need. The gem hooks into after_find and after_save — no other changes required to your model or controller.

Pass nostalgic: true to belongs_to to version the foreign key:

class User < ApplicationRecord
  belongs_to :company, nostalgic: true
end

This records the effective-dated history of which company the user belongs to.

Load a record normally — the attribute reflects the most recent value effective on or before today:

user = User.find(1)
user.tel         # => "222-123-4567"  (current value)
user.company     # => <Company id=1>  (current association)

Use #<attr>_on(date) or #<attr>_at(date) (alias) to retrieve the value effective on a specific date:

user.tel_on(Date.today - 1.day)   # => "111-123-4567"
user.tel_on(Date.today)           # => "222-123-4567"
user.tel_on(Date.today + 1.day)   # => "333-123-4567"

user.company_on(Date.today - 1.day)  # => <Company id=1>
user.company_on(Date.today + 1.day)  # => <Company id=2>

Passing nil returns the current value.

Each versioned attribute gets a has_many association for its full history, ordered most-recent first:

user.tels          # => [<Nostalgic::Attr value="222-123-4567" effective_at=...>, ...]
user.tels.size     # => 3

Set the attribute value and the effective date, then save:

user.tel = "444-123-4567"
user.tel_effective_at = Date.today
user.save

If a record already exists for that (model, attribute, effective_at) combination, it is updated in place. Otherwise a new history entry is created.

Nostalgic provides two FormBuilder helpers that render a table showing the current value with a date picker and an expandable history list.

<%= form_with model: @user do |f| %>
  <%= f.nostalgic_text_field :tel %>
<% end %>

Renders a text input for the current value alongside a hidden datepicker for tel_effective_at. Clicking the list icon expands the version history with delete buttons.

<%= form_with model: @user do |f| %>
  <%= f.nostalgic_collection_select :company_id, Company.all, :id, :name %>
<% end %>

Same layout as nostalgic_text_field but renders a <select> for the current value.

Accept nested attributes in your controller's strong parameters:

def user_params
  params.require(:user).permit(
    :name,
    tels_attributes: [:id, :value, :effective_at, :_destroy]
  )
end

For each declared attribute <attr>:

For each belongs_to declared with nostalgic: true:

The gem creates a single shared table for all versioned attributes across all models:

nostalgic_attrs
  id          integer
  model_type  string   (e.g. "User")
  model_id    integer
  name        string   (e.g. "tel")
  value       string
  effective_at date
  created_at  datetime
  updated_at  datetime

All values are stored as strings. Type coercion is the responsibility of the calling code.

Bug reports and pull requests are welcome at https://github.com/ichylinux/nostalgic.

The gem is available as open source under the terms of the MIT License.