attributes_history 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c5ab51f8fcbd9cad95f6e3724546f8f5d57fb848
+  data.tar.gz: ecdc7309e290238fc6b21bf46c259b76f9dff6bc
+SHA512:
+  metadata.gz: 7c05774dccf3d142db49d91e8a949aa4cb4d80159c9839b36a31f62c5c7b2cc7cc82487d473e9c1ae432d651718fa21a5e38a136c12a1b886041a6ea58f2fd43
+  data.tar.gz: d054f8a660744d412454a4c086bb881accbeb0cbc39db75115218ffa3a7b64abbb4efb50e5a67d603f8885547d0243fdce8a025450d4433f0fe15f863bc90967

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2015
+
+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,138 @@
+# AttributesHistory
+
+Date-granular history for specified model fields. Compact & easy to query.
+
+[![Build Status](https://travis-ci.org/CruGlobal/attributes_history.svg)](https://travis-ci.org/CruGlobal/attributes_history)
+
+## Usage
+
+Include the gem: 
+
+`gem 'attributes_history'`
+
+Call `has_attributes_history for: [attributes], with_model: AttributesLog` where
+`attributes` are the ones you want to track and `AttributesLog` will contain the
+history entries. Your `AttributesLog` model should have a field `recorded_on`
+which tracks the date when those attributes changed to the values in the next
+recorded entry (or to the current attribute values).
+
+## Example
+
+Here's an example of how you could track the `status` and `pledge` fields
+for a ministry donor contact in a `PartnerStatusLog` table. This would then allow
+you to easily query the ministry partner's status and commitment information
+over time.
+
+```
+class Contact < ActiveRecord::Base
+  has_attributes_history for: [:status, :pledge], with_model: PartnerStatusLog
+end
+```
+
+Here would be the `ParterStatusLog` model and relevant migrations:
+
+```
+class PartnerStatusLog < ActiveRecord::Base
+end
+
+class CreateContacts < ActiveRecord::Migration
+  def change
+    create_table :contacts do |t|
+      t.string :name
+      t.string :status
+      t.decimal :pledge
+    end
+  end
+end
+
+class CreatePartnerStatusLogs < ActiveRecord::Migration
+  def change
+    create_table :partner_status_logs do |t|
+      t.integer :contact_id, null: false
+      t.date :recorded_on, null: false
+      t.string :status
+      t.decimal :pledge
+    end
+
+    add_index :partner_status_logs, :contact_id
+    add_index :partner_status_logs, :recorded_on
+  end
+end
+```
+
+## Retrieving past values with  `attribute_on_date` methods
+
+To make retrieving previous values easy, `attributes_history` defines an
+`attribute_on_date(attribute, date)` method, as well as specific 
+`#{attribute}_on_date` method for each of your histroy-tracked attributes
+which returns that value on the specified date based on the log.
+
+For instance, in the ministry partner history example, there would
+be methods `status_on_date` and `pledge_on_date` that would return the
+`status` or `pledge` for a contact for that given date. You could also call
+`attribute_on_date(:pledge, date)` to get the pledge value for a given date.
+
+The log is granular by date and so it makes the assumption that a change
+any time during a date is effective for the whole of that date. The
+`attribute_on_date` methods will use caching so if you look up multiple fields on
+the same date only one query will be performed.
+
+## Querying the log table directly
+
+You can also query the history log table directly. The `recorded_on` field in the
+table represents the date that set of attributes was replaced by a new
+set, either in a subsequent history record, or in the object itself.
+
+So to look up the version for a particular date, do a query like this:
+```
+current_version = contact.partner_status_logs
+  .where('recorded_on > ?', date).order(:recorded_on).first || contact
+```
+That will give either a `PartnerStatusLog` instance for the past, or the current
+`Contact` instance for the present record, both of which will respond to the
+history-tracked attributes of `status` and `pledge`.
+
+This is similar to how [paper_trail](https://github.com/airblade/paper_trail)
+works in that the versions represent past data, and only the current regular
+model record (contact in this case) has the current state.
+
+## Enabling and disabling
+
+By default the history logging is enabled once you set it up, but you can
+disable it by setting `AttributesHistory.enabled = false` (and reset it back to
+`true` also).
+
+## Testing with RSpec
+
+For testing with RSpec, you can `require 'attributes_history/rspec'` which will
+disable attribute history by default in your specs unless you specify
+`versioning: true` in the spec metadata, or you explicitly set
+`AttributesHistory.enabled = true`.
+
+## Designed to complement (not replace) a full audit trail
+
+This is intended to augment a full audit trail solution like
+[paper_trail](https://github.com/airblade/paper_trail). The advantage of a full
+audit trail is that you track every change in a consistent way across models.
+
+But it's possible for the full audit trail to become large and it's often stored in
+a less easily queryable way (object data stored in a generic `object` field as
+YAML/JSON).
+
+If you use auto-saving or make single attribute changes easy, then you may get a
+lot of updates in the same day which semantically represent a single update.
+
+This `attributes_history` gem allows you to choose a subset of fields for a
+particular model that will be tracked with at most one new version per day to
+limit growth and make time-series displaying of the versions easier. And is
+designed to store the versions in specialized table(s) per model with fields that
+parallel those in the model itself so you can more easily query the historical
+fields.
+
+## Acknowledgement and License
+
+Credit to [Spencer Oberstadt](https://github.com/soberstadt) for coming up with
+the idea of versioning our partner status log with date level granularity to
+keep it compact and easy to query.
+
+AttributesHistory is [MIT Licensed](https://github.com/CruGlobal/attributes_history/blob/master/MIT-LICENSE).

data/Rakefile

@@ -0,0 +1,17 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'VersionableByDate'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+Bundler::GemHelper.install_tasks

data/lib/attributes_history/gem_version.rb

@@ -0,0 +1,3 @@
+module AttributesHistory
+  VERSION = '0.0.2'
+end

data/lib/attributes_history/has_attributes_history.rb

@@ -0,0 +1,38 @@
+require 'active_support'
+require_relative 'history_saver'
+require_relative 'history_retriever'
+
+module AttributesHistory
+  module HasAttributesHistory
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      # The options should include the keys :attributes and :version_class
+      def has_attributes_history(options)
+        class_attribute :history_model, :history_attributes, :history_association
+        self.history_model = options[:with_model]
+        self.history_attributes = options[:for].map(&:to_s)
+        self.history_association = history_model.name.underscore.pluralize.to_sym
+
+        has_many history_association
+        after_update { HistorySaver.new(self).save_if_needed }
+        define_verisons_by_date_lookups
+      end
+
+      private
+
+      def define_verisons_by_date_lookups
+        define_method :attribute_on_date do |attribute, date|
+          @history_retriever ||= HistoryRetriever.new(self)
+          @history_retriever.attribute_on_date(attribute, date)
+        end
+
+        history_attributes.each do |attribute|
+          define_method "#{attribute}_on_date" do |date|
+            attribute_on_date(attribute, date)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/attributes_history/history_retriever.rb

@@ -0,0 +1,20 @@
+module AttributesHistory
+  class HistoryRetriever
+    def initialize(object)
+      @object = object
+      @cached_history = {}
+    end
+
+    def attribute_on_date(attribute, date)
+      history_entry = @cached_history[date] ||= find_entry_on(date)
+      history_entry.public_send(attribute)
+    end
+
+    private
+
+    def find_entry_on(date)
+      @object.public_send(@object.history_association)
+        .where('recorded_on > ?', date).order(:recorded_on).first || @object
+    end
+  end
+end

data/lib/attributes_history/history_saver.rb

@@ -0,0 +1,40 @@
+module AttributesHistory
+  class HistorySaver
+    def initialize(changed_object)
+      @object = changed_object
+    end
+
+    def save_if_needed
+      save_history_entry if ::AttributesHistory.enabled? &&
+                            history_attributes_changed?
+    end
+
+    private
+
+    def history_attributes_changed?
+      (@object.changed & @object.history_attributes).present?
+    end
+
+    def save_history_entry
+      history_entry = @object.public_send(@object.history_association)
+                      .find_or_initialize_by(recorded_on: Date.current)
+
+      # If there is an existing history record for today, just leave it as is,
+      # otherwise, save the newly initialized one.
+      history_entry.update!(history_params) if history_entry.new_record?
+    end
+
+    def history_params
+      Hash[@object.history_attributes.map { |f| [f, history_value_for(f)] }]
+    end
+
+    def history_value_for(attribute)
+      # Use the previous value if it was changed, otherwise the current value
+      if attribute.in?(@object.changed)
+        @object.changes[attribute].first
+      else
+        @object.public_send(attribute)
+      end
+    end
+  end
+end

data/lib/attributes_history/rspec.rb

@@ -0,0 +1,11 @@
+require 'rspec/core'
+
+RSpec.configure do |config|
+  config.before(:each) do
+    ::AttributesHistory.enabled = false
+  end
+
+  config.before(:each, versioning: true) do
+    ::AttributesHistory.enabled = true
+  end
+end

data/lib/attributes_history.rb

@@ -0,0 +1,17 @@
+require 'attributes_history/gem_version.rb'
+require 'attributes_history/has_attributes_history.rb'
+
+module AttributesHistory
+  class << self
+    attr_writer :enabled
+
+    def enabled?
+      # Enabled by default
+      @enabled.nil? ? true : @enabled
+    end
+  end
+end
+
+ActiveSupport.on_load(:active_record) do
+  include AttributesHistory::HasAttributesHistory
+end

metadata

@@ -0,0 +1,178 @@
+--- !ruby/object:Gem::Specification
+name: attributes_history
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+platform: ruby
+authors:
+- draffensperger
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-12-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 4.2.5
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 4.2.5
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.4.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.4.0
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.35.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.35.1
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  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: pry
+  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: pry-byebug
+  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'
+description: Date-granular history for specified model fields. Compact & easy to query.
+email:
+- d.raffensperger@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/attributes_history.rb
+- lib/attributes_history/gem_version.rb
+- lib/attributes_history/has_attributes_history.rb
+- lib/attributes_history/history_retriever.rb
+- lib/attributes_history/history_saver.rb
+- lib/attributes_history/rspec.rb
+homepage: https://github.com/CruGlobal/attributes_history
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.8
+signing_key: 
+specification_version: 4
+summary: Date-granular history for specified model fields. Compact & easy to query.
+test_files: []
+has_rdoc: