sequel_temporal 0.1.0

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/.travis.yml

@@ -0,0 +1,5 @@
+rvm:
+  - 1.9.2
+  - 1.9.3
+notifications:
+  disabled: true

data/Gemfile

@@ -0,0 +1,2 @@
+source "http://rubygems.org"
+gemspec

data/README.md

@@ -0,0 +1,47 @@
+sequel_temporal
+=================
+
+Temporal versioning for sequel.
+
+Dependencies
+------------
+
+* Ruby >= 1.9.2
+* gem "sequel", "~> 3.30.0"
+
+Usage
+-----
+
+* Declare temporality inside your model:
+
+        class HotelPriceVersion < Sequel::Model
+        end
+
+        class HotelPrice < Sequel::Model
+          plugin :temporal, version_class: HotelPriceVersion
+        end
+
+* You can now create a hotel price with versions:
+
+        price = HotelPrice.new
+        price.update_attributes price: 18
+
+* To show all versions:
+
+        price.versions
+
+* To get current version:
+
+        price.current_version
+
+* Look at the specs for more usage patterns.
+
+Build Status
+------------
+
+[![Build Status](http://travis-ci.org/TalentBox/sequel_bitemporal.png)](http://travis-ci.org/TalentBox/sequel_bitemporal)
+
+License
+-------
+
+sequel_temporal is Copyright © 2011 TalentBox SA. It is free software, and may be redistributed under the terms specified in the LICENSE file.

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new("spec").tap do |config|
+  config.rspec_opts = "--color"
+end
+task :default => :spec

data/lib/sequel/plugins/temporal.rb

@@ -0,0 +1,151 @@
+module Sequel
+  module Plugins
+    module Temporal
+      def self.at(time)
+        raise ArgumentError, "requires a block" unless block_given?
+        key = :sequel_plugins_temporal_now
+        previous, Thread.current[key] = Thread.current[key], time.to_time
+        yield
+        Thread.current[key] = previous
+      end
+
+      def self.now
+        Thread.current[:sequel_plugins_temporal_now] || Time.now
+      end
+
+      def self.configure(master, opts = {})
+        version = opts[:version_class]
+        raise Error, "please specify version class to use for temporal plugin" unless version
+        required = [:master_id, :created_at, :expired_at]
+        missing = required - version.columns
+        raise Error, "temporal plugin requires the following missing column#{"s" if missing.size>1} on version class: #{missing.join(", ")}" unless missing.empty?
+        master.instance_eval do
+          @version_class = version
+          base_alias = name ? underscore(demodulize(name)) : table_name
+          @versions_alias = "#{base_alias}_versions".to_sym
+          @current_version_alias = "#{base_alias}_current_version".to_sym
+        end
+        master.one_to_many :versions, class: version, key: :master_id, graph_alias_base: master.versions_alias
+        master.one_to_one :current_version, class: version, key: :master_id, graph_alias_base: master.current_version_alias, :graph_block=>(proc do |j, lj, js|
+          n = ::Sequel::Plugins::Temporal.now
+          e = :expired_at.qualify(j)
+          (:created_at.qualify(j) <= n) & ({e=>nil} | (e > n))
+        end) do |ds|
+          n = ::Sequel::Plugins::Temporal.now
+          ds.where{(created_at <= n) & ({expired_at=>nil} | (expired_at > n))}
+        end
+        master.def_dataset_method :with_current_version do
+          eager_graph(:current_version).where({:id.qualify(model.current_version_alias) => nil}.sql_negate)
+        end
+        version.many_to_one :master, class: master, key: :master_id
+        version.class_eval do
+          def current?
+            n = ::Sequel::Plugins::Temporal.now
+            !new? &&
+            created_at.to_time<=n &&
+            (expired_at.nil? || expired_at.to_time>n)
+          end
+        end
+        unless opts[:delegate]==false
+          (version.columns-required-[:id]).each do |column|
+            master.class_eval <<-EOS
+              def #{column}
+                pending_or_current_version.#{column} if pending_or_current_version
+              end
+            EOS
+          end
+        end
+      end
+      module ClassMethods
+        attr_reader :version_class, :versions_alias, :current_version_alias
+      end
+      module DatasetMethods
+      end
+      module InstanceMethods
+        attr_reader :pending_version
+
+        def before_validation
+          prepare_pending_version
+          super
+        end
+
+        def validate
+          super
+          pending_version.errors.each do |key, key_errors|
+            key_errors.each{|error| errors.add key, error}
+          end if pending_version && !pending_version.valid?
+        end
+
+        def pending_or_current_version
+          pending_version || current_version
+        end
+
+        def attributes
+          if pending_version
+            pending_version.values
+          elsif current_version
+            current_version.values
+          else
+            {}
+          end
+        end
+
+        def attributes=(attributes)
+          if !new? && attributes.delete(:partial_update) && current_version
+            current_attributes = current_version.keys.inject({}) do |hash, key|
+              hash[key] = current_version.send key
+              hash
+            end
+            attributes = current_attributes.merge attributes
+          end
+          attributes.delete :id
+          @pending_version ||= model.version_class.new
+          pending_version.set attributes
+          pending_version.master_id = id unless new?
+        end
+
+        def update_attributes(attributes={})
+          self.attributes = attributes
+          save raise_on_failure: false
+        end
+
+        def after_create
+          super
+          if pending_version
+            return false unless save_pending_version
+          end
+        end
+
+        def before_update
+          if pending_version
+            expire_previous_version
+            return false unless save_pending_version
+          end
+          super
+        end
+
+        def destroy
+          versions_dataset.where(expired_at: nil).update expired_at: Time.now
+        end
+
+      private
+
+        def prepare_pending_version
+          return unless pending_version
+          pending_version.created_at = Time.now
+        end
+
+        def expire_previous_version
+          lock!
+          versions_dataset.where(expired_at: nil).update expired_at: pending_version.created_at
+        end
+
+        def save_pending_version
+          success = add_version pending_version
+          @pending_version = nil if success
+          success
+        end
+      end
+    end
+  end
+end

data/lib/sequel_temporal.rb

@@ -0,0 +1 @@
+require "sequel/plugins/temporal"

data/sequel_temporal.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+
+Gem::Specification.new do |s|
+  s.name        = "sequel_temporal"
+  s.version     = "0.1.0"
+  s.authors     = ["Joseph HALTER", "Jonathan TRON"]
+  s.email       = ["joseph.halter@thetalentbox.com", "jonathan.tron@thetalentbox.com"]
+  s.homepage    = "https://github.com/TalentBox/sequel_temporal"
+  s.summary     = "Temporal versioning for sequel."
+  s.description = "Temporal versioning for sequel, fully tested."
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_runtime_dependency "sequel", "~> 3.30.0"
+
+  s.add_development_dependency "sqlite3"
+  s.add_development_dependency "rspec", "~> 2.8.0.rc1" 
+  s.add_development_dependency "timecop"
+  s.add_development_dependency "rake"
+end

data/spec/spec_helper.rb

@@ -0,0 +1,4 @@
+require "sequel"
+require "timecop"
+DB = Sequel.sqlite
+Dir[File.expand_path("../support/*.rb", __FILE__)].each{|f| require f}

data/spec/support/temporal_matchers.rb

@@ -0,0 +1,40 @@
+RSpec::Matchers.define :have_versions do |versions_str|
+  @table = have_versions_parse_table versions_str
+  @last_index = nil
+  @last_version = nil
+  match do |master|
+    versions = master.versions_dataset.order(:id).all
+    versions.size == @table.size && @table.each.with_index.all? do |version, index|
+      @last_index = index
+      @last_version = version
+      master_version = versions[index]
+      [:name, :price, :created_at, :expired_at, :current].all? do |column|
+        if column==:current
+          found = master_version.current?
+          expected = (version[column.to_s]=="true").to_s
+        else
+          found = master_version.send column
+          expected = version[column.to_s]
+        end
+        equal = found.to_s == expected
+        puts "#{column}: #{found} != #{expected}" unless equal
+        equal
+      end
+    end
+  end
+  failure_message_for_should do |master|
+    versions = master.versions_dataset.order(:id).all
+    if versions.size != @table.size
+      "Expected #{master.class} to have #{@table.size} versions but found #{versions.size}"
+    else
+      "Expected row #{@last_index+1} to match #{@last_version.inspect} but found #{versions[@last_index].inspect}"
+    end
+  end
+end
+
+def have_versions_parse_table(str)
+  rows = str.strip.split("\n")
+  rows.collect!{|row| row[/^\s*\|(.+)\|\s*$/, 1].split("|").collect(&:strip)}
+  headers = rows.shift
+  rows.collect{|row| Hash[headers.zip row]}
+end

data/spec/temporal_spec.rb

@@ -0,0 +1,222 @@
+require "spec_helper"
+
+describe "Sequel::Plugins::Temporal" do
+  before :all do
+    DB.drop_table(:room_versions) if DB.table_exists?(:room_versions)
+    DB.drop_table(:rooms) if DB.table_exists?(:rooms)
+    DB.create_table! :rooms do
+      primary_key :id
+    end
+    DB.create_table! :room_versions do
+      primary_key :id
+      foreign_key :master_id, :rooms
+      String      :name
+      Fixnum      :price
+      Date        :created_at
+      Date        :expired_at
+    end
+    @version_class = Class.new Sequel::Model do
+      set_dataset :room_versions
+      def validate
+        super
+        errors.add(:name, "is required") unless name
+        errors.add(:price, "is required") unless price
+      end
+    end
+    closure = @version_class
+    @master_class = Class.new Sequel::Model do
+      set_dataset :rooms
+      plugin :temporal, version_class: closure
+    end
+  end
+  before do
+    Timecop.freeze 2009, 11, 28
+    @version_class.truncate
+    @master_class.truncate
+  end
+  after do
+    Timecop.return
+  end
+  it "checks version class is given" do
+    lambda{
+      @version_class.plugin :temporal
+    }.should raise_error Sequel::Error, "please specify version class to use for temporal plugin"
+  end
+  it "checks required columns are present" do
+    lambda{
+      @version_class.plugin :temporal, version_class: @master_class
+    }.should raise_error Sequel::Error, "temporal plugin requires the following missing columns on version class: master_id, created_at, expired_at"
+  end
+  it "propagates errors from version to master" do
+    master = @master_class.new
+    master.should be_valid
+    master.attributes = {name: "Single Standard"}
+    master.should_not be_valid
+    master.errors.should == {price: ["is required"]}
+  end
+  it "#update_attributes returns false instead of raising errors" do
+    master = @master_class.new
+    master.update_attributes(name: "Single Standard").should be_false
+    master.should be_new
+    master.errors.should == {price: ["is required"]}
+    master.update_attributes(price: 98).should be_true
+  end
+  it "allows creating a master and its first version in one step" do
+    master = @master_class.new
+    master.update_attributes(name: "Single Standard", price: 98).should be_true
+    master.should_not be_new
+    master.should have_versions %Q{
+      | name            | price | created_at | expired_at | current |
+      | Single Standard | 98    | 2009-11-28 |            | true    |
+    }
+  end
+  it "doesn't loose previous version in same-day update" do
+    master = @master_class.new
+    master.update_attributes name: "Single Standard", price: 98
+    master.update_attributes name: "Single Standard", price: 94
+    master.should have_versions %Q{
+      | name            | price | created_at | expired_at | current |
+      | Single Standard | 98    | 2009-11-28 | 2009-11-28 |         |
+      | Single Standard | 94    | 2009-11-28 |            | true    |
+    }
+  end
+  it "allows partial updating based on current version" do
+    master = @master_class.new
+    master.update_attributes name: "Single Standard", price: 98
+    master.update_attributes price: 94, partial_update: true
+    master.update_attributes name: "King Size", partial_update: true
+    master.should have_versions %Q{
+      | name            | price | created_at | expired_at | current |
+      | Single Standard | 98    | 2009-11-28 | 2009-11-28 |         |
+      | Single Standard | 94    | 2009-11-28 | 2009-11-28 |         |
+      | King Size       | 94    | 2009-11-28 |            | true    |
+    }
+  end
+  it "expires previous version but keep it in history" do
+    master = @master_class.new
+    master.update_attributes name: "Single Standard", price: 98
+    Timecop.freeze Date.today+1
+    master.update_attributes price: 94, partial_update: true
+    master.should have_versions %Q{
+      | name            | price | created_at | expired_at | current |
+      | Single Standard | 98    | 2009-11-28 | 2009-11-29 |         |
+      | Single Standard | 94    | 2009-11-29 |            | true    |
+    }
+  end
+  xit "doesn't do anything if unchanged" do
+  end
+  it "allows deleting current version" do
+    master = @master_class.new
+    master.update_attributes name: "Single Standard", price: 98
+    Timecop.freeze Date.today+1
+    master.destroy.should be_true
+    master.should have_versions %Q{
+      | name            | price | created_at | expired_at | current |
+      | Single Standard | 98    | 2009-11-28 | 2009-11-29 |         |
+    }
+  end
+  it "allows simultaneous updates without information loss" do
+    master = @master_class.new
+    master.update_attributes name: "Single Standard", price: 98
+    Timecop.freeze Date.today+1
+    master2 = @master_class.find id: master.id
+    master.update_attributes name: "Single Standard", price: 94
+    master2.update_attributes name: "Single Standard", price: 95
+    master.should have_versions %Q{
+      | name            | price | created_at | expired_at | current |
+      | Single Standard | 98    | 2009-11-28 | 2009-11-29 |         |
+      | Single Standard | 94    | 2009-11-29 | 2009-11-29 |         |
+      | Single Standard | 95    | 2009-11-29 |            | true    |
+    }
+  end
+  it "allows simultaneous cumulative updates" do
+    master = @master_class.new
+    master.update_attributes name: "Single Standard", price: 98
+    Timecop.freeze Date.today+1
+    master2 = @master_class.find id: master.id
+    master.update_attributes price: 94, partial_update: true
+    master2.update_attributes name: "King Size", partial_update: true
+    master.should have_versions %Q{
+      | name            | price | created_at | expired_at | current |
+      | Single Standard | 98    | 2009-11-28 | 2009-11-29 |         |
+      | Single Standard | 94    | 2009-11-29 | 2009-11-29 |         |
+      | King Size       | 94    | 2009-11-29 |            | true    |
+    }
+  end
+  it "allows eager loading with conditions on current version" do
+    master = @master_class.new
+    master.update_attributes name: "Single Standard", price: 98
+    @master_class.eager_graph(:current_version).where("rooms_current_version.id IS NOT NULL").first.should be
+    Timecop.freeze Date.today+1
+    master.destroy
+    @master_class.eager_graph(:current_version).where("rooms_current_version.id IS NOT NULL").first.should be_nil
+  end
+  it "allows loading masters with a current version" do
+    master_destroyed = @master_class.new
+    master_destroyed.update_attributes name: "Single Standard", price: 98
+    master_destroyed.destroy
+    master_with_current = @master_class.new
+    master_with_current.update_attributes name: "Single Standard", price: 94
+    @master_class.with_current_version.all.should have(1).item
+  end
+  it "gets pending or current version attributes" do
+    master = @master_class.new
+    master.attributes.should == {}
+    master.pending_version.should be_nil
+    master.pending_or_current_version.should be_nil
+    master.update_attributes name: "Single Standard", price: 98
+    master.attributes[:name].should == "Single Standard"
+    master.pending_version.should be_nil
+    master.pending_or_current_version.name.should == "Single Standard"
+    master.attributes = {name: "King Size"}
+    master.attributes[:name].should == "King Size"
+    master.pending_version.should be
+    master.pending_or_current_version.name.should == "King Size"
+  end
+  it "allows to go back in time" do
+    master = @master_class.new
+    master.update_attributes name: "Single Standard", price: 98
+    Timecop.freeze Date.today+1
+    master.update_attributes price: 94, partial_update: true
+    master.should have_versions %Q{
+      | name            | price | created_at | expired_at | current |
+      | Single Standard | 98    | 2009-11-28 | 2009-11-29 |         |
+      | Single Standard | 94    | 2009-11-29 |            | true    |
+    }
+    master.current_version.price.should == 94
+    Sequel::Plugins::Temporal.at(Date.today-1) do
+      master.current_version(true).price.should == 98
+    end
+  end
+  it "delegates attributes from master to pending_or_current_version" do
+    master = @master_class.new
+    master.name.should be_nil
+    master.update_attributes name: "Single Standard", price: 98
+    master.name.should == "Single Standard"
+    master.attributes = {name: "King Size", partial_update: true}
+    master.name.should == "King Size"
+  end
+  it "avoids delegation with option delegate: false" do
+    closure = @version_class
+    without_delegation_class = Class.new Sequel::Model do
+      set_dataset :rooms
+      plugin :temporal, version_class: closure, delegate: false
+    end
+    master = without_delegation_class.new
+    expect{ master.name }.to raise_error NoMethodError
+  end
+  it "get current_version association name from class name" do
+    class MyNameVersion < Sequel::Model
+      set_dataset :room_versions
+    end
+    class MyName < Sequel::Model
+      set_dataset :rooms
+      plugin :temporal, version_class: MyNameVersion
+    end
+    expect do
+      MyName.eager_graph(:current_version).where("my_name_current_version.id IS NOT NULL").first
+    end.not_to raise_error
+    Object.send :remove_const, :MyName
+    Object.send :remove_const, :MyNameVersion
+  end
+end

metadata

@@ -0,0 +1,122 @@
+--- !ruby/object:Gem::Specification
+name: sequel_temporal
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Joseph HALTER
+- Jonathan TRON
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-12-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sequel
+  requirement: &2151890200 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.30.0
+  type: :runtime
+  prerelease: false
+  version_requirements: *2151890200
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: &2151889020 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *2151889020
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &2151887200 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.8.0.rc1
+  type: :development
+  prerelease: false
+  version_requirements: *2151887200
+- !ruby/object:Gem::Dependency
+  name: timecop
+  requirement: &2151902600 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *2151902600
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &2151901800 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *2151901800
+description: Temporal versioning for sequel, fully tested.
+email:
+- joseph.halter@thetalentbox.com
+- jonathan.tron@thetalentbox.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .travis.yml
+- Gemfile
+- README.md
+- Rakefile
+- lib/sequel/plugins/temporal.rb
+- lib/sequel_temporal.rb
+- sequel_temporal.gemspec
+- spec/spec_helper.rb
+- spec/support/temporal_matchers.rb
+- spec/temporal_spec.rb
+homepage: https://github.com/TalentBox/sequel_temporal
+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'
+      segments:
+      - 0
+      hash: -1369786071214787930
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -1369786071214787930
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Temporal versioning for sequel.
+test_files:
+- spec/spec_helper.rb
+- spec/support/temporal_matchers.rb
+- spec/temporal_spec.rb