acts_as_scd 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: cd88d8b2f1369a9cfb0e892bbc2fe3dd9e2d68ad
+  data.tar.gz: a27d5a9ee397392427b499c54793e4626ce43e1b
+SHA512:
+  metadata.gz: f290ece490f8f573b3ec3695de9e523e559cc35b733dd135be492bc7da5d613e2dd9ae4ccec11a1290d97aba0c12f4f2557c768728b4285993179642c8ebc579
+  data.tar.gz: 45795c69e470ca3d6340b444518310b5264496c5084d329d1a6f1f1395146016a99dc71a1aab2a2d0fc28148cbdd0fd11e7c5665c0ce078310a840cef9cb2f18

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2014 YOURNAME
+
+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.rdoc

@@ -0,0 +1,43 @@
+= Acts as SCD (Slowly Changing Dimension)
+
+This gem provides SCD behaviour for ActiveRecord models.
+The kind of SCD implemented is "Type 2" acording to http://en.wikipedia.org/wiki/Slowly_changing_dimension
+
+Models that use this plugin must provide an +identity+ column that establishes the identity
+of an entity that may be representented by multiple records (iterations), each one of them
+representing the entity for a specific 'effective' period of time.
+
+The effective period of an iteration is defined with day-granularity by two integer columns,
++effective_from+ and +effective_to+ using YYYYMMDD format.
+By default effective_from has value 0 and effective_to 99999999; these special values meaning
+unlimited periods of time (0 represents the 'start of time' and 99999999 the 'end of time').
+
+SCD models must provide a +compute_identity+ method to compute the identity attribute.
+
+Here we use this terms:
+
+* *Identity*: key that identifies an entity of a SCD through time. The tables will have
+  additional surrogate primary keys (id by default) that identify each iteration of
+  the entity. Here we'll use identity often in a loose sense to refer to the entity which
+  it identifies.
+* *Iteration*: the different revisions or variations over time that an Identity may go through.
+  Each iteration of an identity has an effective period in which the iteration is the valid
+  representation of the identity. Here this period is specified by start and end dates (so that
+  variations which have any frequency higher than daily cannot be handled by this method)
+
+Note that the +current+ term, when applied to identities, is used to mean the last iteration
+if it extends indefinitely to the future (effective_to == 99999999). The last iteration may
+have a effective end date, meaning that it has disappeared at that date, and in that case it
+would not be current. Also, if iterations exist with effective dates in the future, the
+current iterations may not be active at the current date. To get the iteration which is active
+at the current or any other date, the +at+ methods should be used.
+
+= TODO
+
+* Write Tests
+* Write Documentation
+* Require modal_fields or make it optional?
+* Create generator to add identity to a model and generate migration
+* Release gem 1.0.0
+* Test with Rails 3 & 4
+

data/Rakefile

@@ -0,0 +1,32 @@
+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    = 'ActsAsScd'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task default: :test

data/lib/acts_as_scd/base_class_methods.rb

@@ -0,0 +1,101 @@
+module ActsAsScd
+
+
+  module BaseClassMethods
+
+    def acts_as_scd(*args)
+      @slowly_changing_columns ||= []
+      @slowly_changing_indices ||= []
+      @slowly_changing_columns += [[IDENTITY_COLUMN, args], [START_COLUMN, [:integer, :default=>START_OF_TIME]], [END_COLUMN, [:integer, :default=>END_OF_TIME]]]
+      @slowly_changing_indices += [IDENTITY_COLUMN, START_COLUMN, END_COLUMN, [START_COLUMN, END_COLUMN]]
+      include ActsAsScd
+    end
+
+    def has_identity(*args)
+      acts_as_scd *args
+      if defined?(ModalFields) && respond_to?(:fields)
+        fields do
+          identity *args
+          effective_from :integer, :default=>START_OF_TIME
+          effective_to :integer, :default=>END_OF_TIME
+        end
+      end
+    end
+
+    # Association to be used in a child which belongs to a parent which has identity
+    # (the identity is used for the association rather than the id).
+    # The inverse assocation should be has_many_through_identity.
+    def belongs_to_identity(assoc, options={})
+      other_model = assoc.to_s.camelize.constantize
+      fk = :"#{other_model.model_name.to_s.underscore}_identity"
+      if defined?(@slowly_changing_columns)
+        @slowly_changing_columns << [fk, other_model.identity_column_definition.last]
+        @slowly_changing_indices << fk
+      end
+      belongs_to assoc, ->{ where "#{other_model.effective_to_column_sql()}=#{END_OF_TIME}" },
+                 options.reverse_merge(foreign_key: fk, primary_key: IDENTITY_COLUMN)
+      # For Rails 3 is this necessary?:
+      # belongs_to assoc, {:foreign_key=>fk, :primary_key=>IDENTITY_COLUMN, :conditions=>"#{other_model.effective_to_column_sql()}=#{END_OF_TIME}"}.merge(options)
+      define_method :"#{assoc}_at" do |date=nil|
+        other_model.at(date).where(IDENTITY_COLUMN=>send(fk)).first
+      end
+    end
+
+    # Association to be used in a parent class which has children which have identities
+    # (the parent class is referenced by id and may not have identity)
+    # The inverse association should be belongs_to
+    def has_many_identities(assoc, options)
+      fk =  options[:foreign_key] || :"#{model_name.to_s.underscore}_id"
+      pk = primary_key
+      other_model_name = options[:class_name] || assoc.to_s.singularize.camelize
+      other_model = other_model_name.to_s.constantize
+
+      # all children iterations
+      has_many :"#{assoc}_iterations", class_name: other_model_name, foreign_key: fk
+
+      # current children:
+      # has_many assoc, options.merge(conditions: ["#{model.effective_to_column_sql} = :date", :date=>END_OF_TIME)]
+      define_method assoc do
+        send(:"#{assoc}_iterations").current
+      end
+      # children at some date
+      define_method :"#{assoc}_at" do |date=nil|
+        # has_many assoc, options.merge(conditions: [%{#{model.effective_from_column_sql}<=:date AND #{model.effective_to_column_sql}>:date}, :date=>model.effective_date(date)]
+        send(:"#{assoc}_iterations").scoped.at(date) # scoped necessary here to avoid delegation to Array
+      end
+
+      # all children identities
+      define_method :"#{assoc}_identities" do
+        # send(:"#{assoc}_iterations").select("DISTINCT #{other_model.identity_column_sql}").order(other_model.identity_column_sql).pluck(:identity)
+        # other_model.unscoped.where(fk=>send(pk)).identities
+        send(:"#{assoc}_iterations").identities
+      end
+
+      # children identities at a date
+      define_method :"#{assoc}_identities_at" do |date=nil|
+        # send(:"#{assoc}_iterations_at", date).select("DISTINCT #{other_model.identity_column_sql}").order(other_model.identity_column_sql).pluck(:identity)
+        # other_model.unscoped.where(fk=>send(pk)).identities_at(date)
+        send(:"#{assoc}_iterations").identities_at(date)
+      end
+
+      # current children identities
+      define_method :"#{assoc}_current_identities" do
+        # send(assoc).select("DISTINCT #{other_model.identity_column_sql}").order(other_model.identity_column_sql).pluck(:identity)
+        # other_model.unscoped.where(fk=>send(pk)).current_identities
+        send(:"#{assoc}_iterations").current_identities
+      end
+
+    end
+
+    # Since this code has been extracted from a Rails 3 project, we need to adapt to Rails 4
+    # For a gradual transition and to allow compatibility with Rails 3 we'll provide this
+    # for the time being:
+    if ActiveRecord::VERSION::MAJOR > 3
+      def scoped
+        all
+      end
+    end
+
+  end
+
+end

data/lib/acts_as_scd/block_updater.rb

@@ -0,0 +1,142 @@
+module ActsAsScd
+
+  # BlockUpdater is a utilty to batch-update a SCD table, in a way
+  # in which at a given date all the identities of the table are updated.
+  # No iteration will span the update date. Current iterations at the
+  # update date will end at that date and new iterations will start at it.
+  #
+  # This update style simplifies managing tables with identities;
+  # effective periods ara shared by all the identities.
+  #
+  class BlockUpdater
+
+    # Block-Update a table with identities:
+    #
+    # ActsAsScd::BlockUpdater.update Model, date do |updater|
+    #   new_records.each do |record_attributes|
+    #     updater.add(record_attributes) do |record|
+    #       raise "Error" if record.errors.present?
+    #     end
+    #   end
+    # end
+    #
+    def self.update(model, fecha, options={})
+      updater = new(model, fecha, options={})
+      model.transaction do
+        updater.start
+        yield updater
+        updater.finish
+      end
+      updater
+    end
+
+    # Delete a block-update.
+    def self.delete(model, fecha, options={})
+      updater = new(model, fecha, options={})
+      updater.delete_all
+    end
+
+    # Check if a block-update has been performed at the given date
+    def self.exists?(model, fecha, options={})
+      updater = new(model, fecha, options={})
+      updater.exists?
+    end
+
+    def self.count(model, fecha, options={})
+      updater = new(model, fecha, options={})
+      updater.count
+    end
+
+    def initialize(model, fecha, options={})
+      @model = model
+      @fecha = fecha
+      @preterminate = false
+      @raise_on_error = options.delete :raise_on_error
+      @scope = options.delete :scope
+      # @extend_from = options[:extend_from]
+      # @unterminate = options[:unterminate]
+      @iteration_options = options.dup
+    end
+
+    attr_reader :model, :fecha, :counters, :new_items, :old_items, :missing_items
+
+    def scoped_model
+      if @scope.present?
+        if Symbol === @scope
+          @model.send(@scope)
+        else
+          @model.where(scope)
+        end
+      else
+        @model
+      end
+    end
+
+    def start
+      @new_items = 0
+      @old_items = 0
+      @missing_items = 0
+      if @preterminate
+        @pre_items = scoped_model.current.count
+        scoped_model.current.update_all(:effective_to=>model.effective_date(fecha))
+        # @unterminate = true
+        @iteration_options[:unterminate] = true
+      end
+      self
+    end
+
+    def add(identity, attributes={})
+      record = model.create_iteration(identity, attributes, fecha, @iteration_options)
+      yield record if block_given?
+      raise "Errors: #{record.errors.full_messages}" if @raise_on_error && record.errors.present?
+      if record.antecessor
+        @old_items += 1
+      else
+        @new_items += 1
+      end
+      record
+    end
+
+    def finish
+      if @preterminate
+        @missing_items = @pre_items - @old_items
+      else
+        scoped_model.current.where('effective_from < :fecha', fecha: model.effective_date(fecha)).each do |record|
+          record.terminate_identity fecha
+          @missing_items += 1
+        end
+      end
+      self
+    end
+
+    def delete_all
+      date = ActsAsScd::Period.date(fecha)
+      query = scoped_model.where(effective_from: date)
+      @missing_items = query.count
+      query.destroy_all
+      self
+    end
+
+    def identity_exists?(identity)
+      date = ActsAsScd::Period.date(fecha)
+      scoped_model.where(effective_from: date, identity: identity).exists?
+    end
+
+    def find_identity(identity)
+      date = ActsAsScd::Period.date(fecha)
+      scoped_model.where(effective_from: date, identity: identity).first
+    end
+
+    def exists?
+      date = ActsAsScd::Period.date(fecha)
+      scoped_model.where(effective_from: date).exists?
+    end
+
+    def count
+      date = ActsAsScd::Period.date(fecha)
+      scoped_model.where(effective_from: date).count
+    end
+
+  end
+
+end

data/lib/acts_as_scd/class_methods.rb

@@ -0,0 +1,240 @@
+module ActsAsScd
+
+
+  module ClassMethods
+
+    # Return objects representing identities; (with a single attribute, :identity)
+    # Warning: do not chain this method after other queries;
+    # any query should be applied after this method.
+    # If identities are required for an association, either latest, earliest or initial can be used
+    # (which one is appropriate depends on desired result, data contents, etc.; initial/current are faster)
+    def distinct_identities
+      # Note that since Rails 2.3.13, when pluck(col) is applied to distinct_identities
+      # the "DISTINCT" is lost from the SELECT if added explicitly  as in .select('DISTINCT #{col}'),
+      # so we have avoid explicit use of DISTINCT in distinct_identities.
+      # This can be used on association queries
+      if ActiveRecord::VERSION::MAJOR > 3
+        unscope(:select).reorder(identity_column_sql).select(identity_column_sql).uniq
+      else
+        query = scoped.with_default_scope
+        query.select_values.clear
+        query.reorder(identity_column_sql).select(identity_column_sql).uniq
+      end
+    end
+
+    def ordered_identities
+      distinct_identities.pluck(identity_column_sql)
+    end
+
+    # This can be applied to an ordered query (but returns an Array, not a query)
+    def identities
+      # pluck(identity_column_sql).uniq # does not work if select has been applied
+      scoped.map(&IDENTITY_COLUMN).uniq
+    end
+
+    def identities_at(date=nil)
+      at(date).identities
+    end
+
+    def current_identities
+      current.identities
+    end
+
+    def identity_column_sql(table_alias=nil)
+      %{"#{table_alias || table_name}"."#{IDENTITY_COLUMN}"}
+    end
+
+    def effective_from_column_sql(table_alias=nil)
+      %{"#{table_alias || table_name}"."#{START_COLUMN}"}
+    end
+
+    def effective_to_column_sql(table_alias=nil)
+      %{"#{table_alias || table_name}"."#{END_COLUMN}"}
+    end
+
+    def effective_date(d)
+      Period.date(d)
+    end
+
+    # Note that find_by_identity will return nil if there's not a current iteration of the identity
+    def find_by_identity(identity, at_date=nil)
+      # (at_date.nil? ? current : at(at_date)).where(IDENTITY_COLUMN=>identity).first
+      if at_date.nil?
+        q = current
+      else
+        q = at(at_date)
+      end
+      q = q.where(IDENTITY_COLUMN=>identity)
+      q.first
+    end
+
+    def identity_exists?(identity, at_date=nil)
+      (at_date.nil? ? self : at(at_date)).where(IDENTITY_COLUMN=>identity).exists?
+    end
+
+    # The first iteration can be defined with a specific start date, but
+    # that is in general a bad idea, since it complicates obtaining
+    # the first iteration
+    def create_identity(attributes, start=nil)
+      start ||= START_OF_TIME
+      create(attributes.merge(START_COLUMN=>start || START_OF_TIME))
+    end
+
+    # Create a new iteration
+    # options
+    # :unterminate - if the identity exists and is terminated, unterminate it (extending the last iteration to the new date)
+    # :extend_from - if no prior iteration exists, extend effective_from to the start-of-time
+    # (TODO: consider making :extend_from the default, adding an option for the opposite...)
+    def create_iteration(identity, attribute_changes, start=nil, options={})
+      start = effective_date(start || Date.today)
+      transaction do
+        current_record = find_by_identity(identity)
+        if !current_record && options[:unterminate]
+          current_record = latest_of(identity) # terminated.where(IDENTITY_COLUMN=>identity).first
+          #   where(IDENTITY_COLUMN=>identity).where("#{effective_to_column_sql} < #{END_OF_TIME}").reorder("#{effective_to_column_sql} desc").limit(1).first
+        end
+        attributes = {IDENTITY_COLUMN=>identity}.with_indifferent_access
+        if current_record
+          non_replicated_attrs = %w[id effective_from effective_to updated_at created_at]
+          attributes = attributes.merge current_record.attributes.with_indifferent_access.except(*non_replicated_attrs)
+        end
+        start = START_OF_TIME if options[:extend_from] && !identity_exists?(identity)
+        attributes = attributes.merge(START_COLUMN=>start).merge(attribute_changes.with_indifferent_access.except(START_COLUMN, END_COLUMN))
+        new_record = create(attributes)
+        if new_record.errors.blank? && current_record
+          # current_record.update_attributes END_COLUMN=>start
+          current_record.send :"#{END_COLUMN}=", start
+          current_record.save validate: false
+        end
+        new_record
+      end
+    end
+
+    def terminate_identity(identity, finish=Date.today)
+       finish = effective_date(finish)
+       transaction do
+         current_record = find_by_identity(identity)
+         current_record.update_attributes END_COLUMN=>finish
+       end
+    end
+
+    # Association yo be used in a parent class which has identity and has children
+    # which have identities too;
+    # the association is implemented through the identity, not the PK.
+    # The inverse association should be belongs_to_identity
+    def has_many_iterations_through_identity(assoc, options={})
+      fk =  options[:foreign_key] || :"#{model_name.to_s.underscore}_identity"
+      assoc_singular = assoc.to_s.singularize
+      other_model_name = options[:class_name] || assoc_singular.camelize
+      other_model = other_model_name.constantize
+      pk = IDENTITY_COLUMN
+
+      # all children iterations
+      has_many :"#{assoc_singular}_iterations", class_name: other_model_name, foreign_key: fk, primary_key: pk
+
+      # current_children
+      has_many assoc, ->{ where "#{other_model.effective_to_column_sql}=#{END_OF_TIME}" },
+               options.reverse_merge(foreign_key: fk, primary_key: pk)
+      # has_many assoc, {:foreign_key=>fk, :primary_key=>pk, :conditions=>"#{other_model.effective_to_column_sql}=#{END_OF_TIME}"}.merge(options)
+
+      # children at some date
+      define_method :"#{assoc}_at" do |date|
+        # other_model.unscoped.at(date).where(fk=>send(pk))
+        send(:"#{assoc_singular}_iterations").scoped.at(date)
+      end
+
+      # all children identities
+      define_method :"#{assoc_singular}_identities" do
+        # send(:"#{assoc}_iterations").select("DISTINCT #{other_model.identity_column_sql}").reorder(other_model.identity_column_sql).pluck(:identity)
+        # other_model.unscoped.where(fk=>send(pk)).identities
+        send(:"#{assoc_singular}_iterations").identities
+      end
+
+      # children identities at a date
+      define_method :"#{assoc_singular}_identities_at" do |date=nil|
+        # send(:"#{assoc}_iterations_at", date).select("DISTINCT #{other_model.identity_column_sql}").reorder(other_model.identity_column_sql).pluck(:identity)
+        # other_model.unscoped.where(fk=>send(pk)).identities_at(date)
+        send(:"#{assoc_singular}_iterations").identities_at(date)
+      end
+
+      # current children identities
+      define_method :"#{assoc_singular}_current_identities" do
+        # send(assoc).select("DISTINCT #{other_model.identity_column_sql}").reorder(other_model.identity_column_sql).pluck(:identity)
+        # other_mode.unscoped.where(fk=>send(pk)).current_identities
+        send(:"#{assoc_singular}_iterations").current_identities
+      end
+
+    end
+
+    # Association to be used in a parent class which has identity and has children
+    # which don't have identities;
+    # the association is implemented through the identity, not the PK.
+    # The inverse association should be belongs_to_identity
+    def has_many_through_identity(assoc, options={})
+      fk = :"#{model_name.to_s.underscore}_identity"
+      pk = IDENTITY_COLUMN
+
+      has_many assoc, {:foreign_key=>fk, :primary_key=>pk}.merge(options)
+    end
+
+    def identity_column_definition
+      @slowly_changing_columns.first
+    end
+
+    def slow_changing_migration
+      migration = ""
+
+      migration << "def up\n"
+      @slowly_changing_columns.each do |col, args|
+        migration << "  add_column :#{table_name}, :#{col}, #{args.inspect.unwrap('[]')}\n"
+      end
+      @slowly_changing_indices.each do |index|
+        migration << "  add_index :#{table_name}, #{index.inspect}\n"
+      end
+      migration << "end\n"
+
+      migration << "def down\n"
+      @slowly_changing_columns.each do |col, args|
+        migration << "  remove_column :#{table_name}, :#{col}\n"
+      end
+      migration << "end\n"
+
+    end
+
+    def effective_periods(*args)
+      # periods = unscoped.select("DISTINCT effective_from, effective_to").order('effective_from, effective_to')
+      if ActiveRecord::VERSION::MAJOR > 3
+        # periods = unscope(where: [:effective_from, :effective_to]).select("DISTINCT effective_from, effective_to").reorder('effective_from, effective_to')
+        periods = unscope(where: [:effective_from, :effective_to]).select([:effective_from, :effective_to]).uniq.reorder('effective_from, effective_to')
+      else
+        query = scoped.with_default_scope
+        query.select_values.clear
+        periods = query.reorder('effective_from, effective_to').select([:effective_from, :effective_to]).uniq
+      end
+
+      # formerly unscoped was used, so any desired condition had to be defined here
+      periods = periods.where(*args) if args.present?
+
+      periods.map{|p| Period[p.effective_from, p.effective_to]}
+    end
+
+    # def effective_spans
+    #   # select all distinct effective_from, and effective_to, order, return in pairs
+    # end
+
+    # Most recent iteration (terminated or not)
+    def latest_of(identity)
+      where(identity:identity).reorder('effective_to desc').limit(1).first
+    end
+
+    def earliest_of(identity)
+      where(identity:identity).reorder('effective_to asc').limit(1).first
+    end
+
+    def all_of(identity)
+      where(identity:identity).reorder('effective_from asc')
+    end
+
+  end
+
+end