mongoid-historicals 0.1.0

data/README.md

@@ -0,0 +1,5 @@
+Mongoid Historicals
+===================
+
+Record a snapshot of current values to reference later as historical values.  Useful for showing changes in values over time.
+

data/Rakefile

@@ -0,0 +1,8 @@
+require 'rake/testtask'
+
+task :default => :test
+
+Rake::TestTask.new do |t|
+  t.libs.push "lib"
+  t.pattern = "test/*_test.rb"
+end

data/lib/mongoid/historicals/record.rb

@@ -0,0 +1,10 @@
+module Mongoid
+  module Historicals
+    class Record
+      include Mongoid::Document
+      include Mongoid::Timestamps::Created
+
+      field :'_label', type: String
+    end
+  end
+end

data/lib/mongoid/historicals/version.rb

@@ -0,0 +1,7 @@
+module Mongoid
+  module Historicals
+
+    VERSION = "0.1.0"
+
+  end
+end

data/lib/mongoid/historicals.rb

@@ -0,0 +1,103 @@
+require 'mongoid'
+require_relative 'historicals/version'
+require_relative 'historicals/record'
+
+module Mongoid
+  module Historicals
+    extend ActiveSupport::Concern
+
+    included do
+      embeds_many :historicals,
+        class_name: "Mongoid::Historicals::Record"
+
+      class_attribute :historical_attributes
+      class_attribute :historical_options
+    end
+
+    # Save the current values for historicals by label
+    #
+    def record!(label = nil)
+      label ||= Time.now
+      record = historical(label) || self.historicals.build(:'_label' => labelize(label))
+
+      self.class.historical_attributes.each do |attr|
+        record[attr] = self.send(attr)
+      end
+
+      record.save!
+      destroy_old_historicals!
+      record
+    end
+
+    def historical(label)
+      self.historicals.where(:'_label' => labelize(label)).first
+    end
+
+    def historical_difference(attr, label, options = {})
+      opts = {
+        default: 0
+      }.merge(options)
+
+      record = historical(labelize(label))
+
+      begin
+        self[attr] - record[attr]
+      rescue # Pokemon exception handling, but actually seems appropriate here
+        opts[:default]
+      end
+    end
+
+    private
+
+      def labelize(label)
+        if label.is_a?(String) || label.is_a?(Symbol)
+          label.to_s
+        elsif label.respond_to?(:to_datetime)
+          dt = label.to_datetime
+
+          case self.class.historical_options[:frequency]
+          when :monthly
+            dt.strftime("%Y/%m")
+          when :weekly
+            dt.strftime("%G-%V")
+          else # default to `:daily`
+            dt.strftime("%Y/%m/%d")
+          end
+        else
+          raise("`label` must be a String, Symbol or respond to :to_datetime")
+        end
+      end
+
+      def destroy_old_historicals!
+        if self.class.historical_options[:max]
+          records = self.historicals.asc(:created_at)
+          
+          if (num_to_delete = records.size - self.class.historical_options[:max]) > 0
+            records[0, num_to_delete].each do |r|
+              self.historicals.delete(r)
+            end
+          end
+        end
+      end
+
+    module ClassMethods
+
+      # This model should record historical values for the specified
+      # attributes.
+      #
+      # Options:
+      # 
+      #   <tt>max</tt>: The maximum number of entries to store (default: none)
+      #   <tt>frequency</tt>: :monthly, :weekly, or :daily (default: :daily)
+      #
+      def historicals(*attrs)
+        options = attrs.extract_options!
+        options[:max] ||= nil
+        options[:frequency] ||= :daily
+
+        self.historical_options = options
+        self.historical_attributes = attrs
+      end
+    end
+  end
+end

data/test/example/mongoid.yml

@@ -0,0 +1,6 @@
+test:
+  sessions:
+    default:
+      database: mongoid_historicals_test
+      hosts:
+        - localhost:27017

data/test/example/player.rb

@@ -0,0 +1,9 @@
+class Player
+  include Mongoid::Document
+  include Mongoid::Historicals
+
+  field :name,  type: String
+  field :score, type: Float
+
+  historicals :score
+end

data/test/historicals_test.rb

@@ -0,0 +1,173 @@
+require_relative 'test_helper'
+
+describe Mongoid::Historicals do
+  describe ".historical_attributes" do
+    it "should include specified attributes" do
+      Player.historical_attributes.must_include :score
+    end
+
+    it "should not include other attributes" do
+      Player.historical_attributes.wont_include :name
+    end
+  end
+
+  describe ".historical_options" do
+    it "should have default `max` of nil" do
+      Player.historical_options[:max].must_equal nil
+    end
+
+    it "should have a default `frequency` of :daily" do
+      Player.historical_options[:frequency].must_equal :daily
+    end
+  end
+
+  describe "#record!" do
+    before do
+      @player = Player.create!(name: "Lytol", score: 95.0)
+      @record = @player.record!('test')
+    end
+
+    it "should add a record to historicals" do
+      @player.historicals.wont_equal []
+    end
+
+    it "should label with specified label" do
+      @record._label.must_equal 'test'
+    end
+
+    it "should timestamp the record" do
+      @record.created_at.wont_equal nil
+    end
+
+    it "should have existing values for specified attrbutes in record" do
+      @record.score.must_equal 95.0
+    end
+
+    it "should not have values for unspecified attributes in record" do
+      @record.wont_respond_to :name
+    end
+
+    describe "when labelled record already exists" do
+      it "should overwrite existing record" do
+        @player.update_attribute(:score, 90.0)
+        record = @player.record!('test')
+        @player.historicals.size.must_equal 1
+        @player.historicals.must_include record
+      end
+    end
+
+    describe "when `max` records is exceeded" do
+      before do
+        @player.class.historical_options[:max] = 5
+        5.times do |i|
+          @player.record!(i.to_s)
+        end
+      end
+
+      after do
+        @player.class.historical_options[:max] = nil
+      end
+
+      it "should delete the oldest records" do
+        oldest_record = @player.historicals.desc(:created_at).last
+        @player.record!('test')
+        @player.historicals.wont_include oldest_record
+      end
+    end
+
+    describe "when labelled with DateTime" do
+      before do
+        @player.update_attribute(:score, 54.0)
+        @player.record!(5.days.ago)
+        @player.update_attribute(:score, 65.0)
+      end
+
+      it "should be retrievable with DateTime" do
+        record = @player.historical(5.days.ago)
+        record.score.must_equal 54.0
+      end
+    end
+  end
+
+  describe "#historical" do
+    before do
+      @player = Player.create!(name: "Lytol", score: 95.0)
+      @player.record!('test')
+    end
+
+    describe "when record exists" do
+      it "should return record" do
+        @record = @player.historical('test')
+        @record.must_be_instance_of(Mongoid::Historicals::Record)
+        @record._label.must_equal 'test'
+      end
+    end
+
+    describe "when record does not exist" do
+      it "should return nil" do
+        @record = @player.historical('unknown-label')
+        @record.must_equal nil
+      end
+    end
+  end
+
+  describe "#historicals" do
+    before do
+      @player = Player.create!(name: "Lytol", score: 95.0)
+    end
+
+    describe "before any recording" do
+      it "should be empty" do
+        @player.historicals.must_equal []
+      end
+    end
+  end
+
+  describe "#historical_difference" do
+    before do
+      @player = Player.create!(name: "Lytol", score: 90.5)
+      @player.record!('test')
+      @player.update_attribute(:score, 92.0)
+    end
+
+    it "should return difference from specified label" do
+      @player.historical_difference(:score, 'test').must_equal 1.5
+    end
+
+    describe "when there is no historical value" do
+      before do
+        @player = Player.create!(name: "Lytol", score: nil)
+        @player.record!('test')
+        @player.update_attribute(:score, 92.0)
+      end
+
+      it "should return 0" do
+        @player.historical_difference(:score, 'test').must_equal 0
+      end
+
+      describe "and a default is provided" do
+        it "should return specified `default`" do
+          @player.historical_difference(:score, 'test', default: 'none').must_equal 'none'
+        end
+      end
+    end
+
+    describe "when there is no labeled record" do
+      before do
+        @player = Player.create!(name: "Lytol", score: 90.0)
+        @player.record!('test')
+        @player.update_attribute(:score, 92.0)
+      end
+
+      it "should return 0" do
+          @player.historical_difference(:score, 'invalid').must_equal 0
+      end
+
+      describe "and a default is provided" do
+        it "should return specified `default`" do
+          @player.historical_difference(:score, 'invalid', default: 'none').must_equal 'none'
+        end
+      end
+    end
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,7 @@
+require 'mongoid'
+require 'minitest/autorun'
+
+require_relative '../lib/mongoid/historicals'
+require_relative 'example/player'
+
+Mongoid.load!(File.join(File.dirname(__FILE__), "example/mongoid.yml"), :test)

metadata

@@ -0,0 +1,101 @@
+--- !ruby/object:Gem::Specification
+name: mongoid-historicals
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Brian Smith
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-10-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mongoid
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 2.6.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 2.6.2
+description: ''
+email: bsmith@swig505.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Rakefile
+- lib/mongoid/historicals/record.rb
+- lib/mongoid/historicals/version.rb
+- lib/mongoid/historicals.rb
+- test/example/mongoid.yml
+- test/example/player.rb
+- test/historicals_test.rb
+- test/test_helper.rb
+- README.md
+homepage: http://github.com/Lytol/mongoid-historicals
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: ''
+test_files: []