dm-is-temporal 0.0.1 → 0.2.0

data/README.md

@@ -6,12 +6,13 @@ DataMapper plugin implementing temporal patterns on DataMapper models.
 These patterns are based on research by Martin Fowler, Richard Snodgrass and others.  For more information follow these links:
 
 +  [Temporal Patterns](http://martinfowler.com/eaaDev/timeNarrative.html)
-
 +  [Developing Time-Oriented Database Applications in SQL](http://www.cs.arizona.edu/people/rts/publications.html)
 
 Examples
 ---------
 
+So lets assume you have a simple class. The plugin will automatically create some auxillary tables when you auto_migrate.
+
     require 'rubygems'
     require 'dm-core'
     require 'dm-migrations'
@@ -32,38 +33,114 @@ Examples
     end
         
     DataMapper.auto_migrate!
-    
-    m = MyModel.create(:name => 'start', :foo => 1)
-        
-    m.foo
-    #= 1
-    m.name  
-    #=> 'start'
-    
-    m.foo = 2
-    
-    m.name = 'hello'
-    m.name  
-    #=> 'hello'
-    
-    m.foo
-    #= 2
-    
-    m.foo = 42
-        
+
+You can create, modify and access it as normal:
+
+    m = MyModel.create(:name => 'start', :foo => 42)
+
+    m.bar = 'hello'
+    m.foo              #= 42
+    m.name             #=> 'start'
+
+Or you can access it at different times (future or past):
+
     old = DateTime.parse('-4712-01-01T00:00:00+00:00')
-    m.at(old).foo
-    #=> nil
-    m.foo
-    #=> 42
-    
-    m.update(:foo => 100, :name => 'goodbye')
-    
-    m.foo
-    #=> 100
-    m.name
-    #=> 'goodbye'
-    
+    now = DateTime.now
+
+    m.at(old).foo         #=> nil
+    m.at(now).foo         #=> 42
+
+But it really gets interesting when you modify it `at` different `DateTime`s
+
+    oldish = DateTime.parse('-4712-01-01T00:00:00+00:00')
+    nowish = DateTime.parse('2011-03-01T00:00:00+00:00')
+    future = DateTime.parse('4712-01-01T00:00:00+00:00')
+
+    m.at(oldish).foo = 1
+
+    m.at(oldish).foo       #=> 1
+    m.at(nowish).foo       #=> 42
+    m.at(future).foo       #=> 42
+
+    m.at(nowish).foo = 1024
+
+    m.at(oldish).foo        #=> 1
+    m.at(nowish).foo        #=> 1024
+    m.at(future).foo        #=> 1024
+
+    m.at(future).foo = 3
+
+    m.at(oldish).foo        #=> 1
+    m.at(nowish).foo        #=> 1024
+    m.at(future).foo        #=> 3
+
+Remember that properties outside of the `is_temporal` block are not versioned.  But you can read and write them though the `at(time)` method if you want:
+
+    m.at(now).name = "finished"
+
+    m.at(old).name        #=> 'finished'
+    m.at(now).name        #=> 'finished'
+
+If you try to set a value at the same time as one you already set, it will overwrite the previous value (like non-temporal models).  In future versions of dm-is-temporal you will be able to configure if this works or causes an error.
+
+    m.at(nowish).foo = 11
+    m.at(nowish).foo         #=> 11
+
+    m.at(nowish).foo = 22
+    m.at(nowish).foo         #=> 22
+
+You can also update several properties with the same time in a block (I use `v` for "version" here)
+
+
+    m.at(nowish) do |v|
+      v.foo = 42
+      v.bar = "cat"
+    end
+
+    m.at(nowish).foo           #=> 42
+    m.at(nowish).bar           #=> 'cat'
+
+
+How it works
+-------------
+Temporal patterns differ from versioning patterns (such as [dm-is-versioned](https://github.com/datamapper/dm-is-versioned))
+in that every version of the temporal properties is a peer (even the most recent).  Accessing temporal properties without the `at(time)` method
+is just a convinience for `at(DateTime.now)`.
+
+In addition, you have the ability inject versions at previous time-states (modifying history).
+
+When you use the `is_temporal` form, the plugin will dynamically create a temporal version table.  In the example above,
+these two tables would be created:
+
+    # db.my_models table
+    ---------------------------------------------
+    | id | name                                 |
+    ---------------------------------------------
+    | 1  | 'start'                              |
+
+
+    # db.my_model_temporal_versions table
+    -----------------------------------------------------------------------
+    | id | foo          | bar            | updated_at     | my_model_id   |
+    -----------------------------------------------------------------------
+    | 1  | '42'         | null           | DateTime       | 1             |
+    | 2  | '1024'       | null           | DateTime       | 1             |
+    | 3  | '1024'       | 'hello'        | DateTime       | 1             |
+
+Thanks
+------
+Thanks to the [dm-is-versioned](https://github.com/datamapper/dm-is-versioned) folks!  I based a lot of my infrastructure
+on that project.
+
+TODO
+------
+
++  MyClass.update (update all records for a model) doesn't work
++  Temporal Associations
++  Temporal Property pattern (i.e. multiple independent temporal properties per class)
++  Bi-temporality
++  Add a config flag that enables an error to be raised when attempting to rewrite existing versions
+
 
 Copyright
 ----------

data/Rakefile

@@ -4,7 +4,7 @@ begin
 
   Jeweler::Tasks.new do |gem|
     gem.name        = 'dm-is-temporal'
-    gem.version     = '0.0.1'
+    gem.version     = '0.2.0'
     gem.summary     = 'DataMapper plugin implementing temporal patterns'
     gem.description = gem.summary
     gem.email       = 'jpkutner [a] gmail [d] com'

data/VERSION

@@ -1 +1 @@
-0.0.1
+0.2.0

data/lib/dm-is-temporal/is/temporal.rb

@@ -41,7 +41,7 @@ module DataMapper
 
           version_model.property(:id, DataMapper::Property::Serial)
           version_model.property(:updated_at, DataMapper::Property::DateTime)
-          version_model.before(:save) { self.updated_at = DateTime.now }
+          version_model.before(:save) { self.updated_at ||= DateTime.now }
           version_model.instance_eval(&block)
 
           const_set(:TemporalVersion, version_model)
@@ -70,11 +70,16 @@ module DataMapper
         class_eval <<-RUBY
 
           def self.update(options={})
-            raise 'TODO'
+            raise "Updating all doesn't work yet"
+#            t_opts = __select_temporal_options__(options)
+#            raise "Can't update at temporal properties from class level yet." if !t_opts.empty?
+#            super.update(options)
           end
 
-          def self.all(*args)
-            raise 'TODO'
+          def self.all(options={})
+            t_opts = __select_temporal_options__(options)
+            raise "Can't select all by temporal properties from class level yet." if !t_opts.empty?             
+            super.all(options)
           end
 
           def self.create(options={})
@@ -87,8 +92,13 @@ module DataMapper
             base
           end
 
-          def at(context)
-            @__at__ = context
+          def at(context=DateTime.now, &block)
+            if block_given?
+              yield TemporalProxy.new(self, context)
+            else
+              # this is hokie.  need to do better
+              @__at__ = context
+            end
             self
           end
 
@@ -141,10 +151,15 @@ module DataMapper
       def create_temporal_writer(name)
         class_eval <<-RUBY
           def #{name}=(x)
+            at = @__at__
             t = __version_for_context__
-            attrs = t.nil? ? {} : t.attributes
-            t = TemporalVersion.create(attrs.merge(:id => nil, :updated_at => nil))
-            temporal_versions << t
+            if t.nil?
+              t = TemporalVersion.create(:updated_at => at)
+              temporal_versions << t
+            elsif t.updated_at != at
+              t = TemporalVersion.create(t.attributes.merge(:id => nil, :updated_at => at))
+              temporal_versions << t
+            end
             t.#{name} = x
             self.save
             #{name}
@@ -152,6 +167,20 @@ module DataMapper
         RUBY
       end
 
+      class TemporalProxy
+        # make this a blank slate
+        instance_methods.each { |m| undef_method m unless m =~ /^__/ }
+
+        def initialize(proxied_object, context)
+          @proxied_object = proxied_object
+          @context = context
+        end
+
+        def method_missing(sym, *args, &block)
+          @proxied_object.at(@context).__send__(sym, *args, &block)
+        end
+      end
+
       module Migration
 
         def auto_migrate!(repository_name = self.repository_name)

data/spec/temporal_spec.rb

@@ -4,10 +4,6 @@ require 'spec_helper'
 class MyModel
   include DataMapper::Resource
 
-#  def self.default_repository_name
-#    :test
-#  end
-
   property :id, Serial
   property :name, String
 
@@ -47,6 +43,98 @@ describe DataMapper::Is::Temporal do
       MyModel.create
     end
 
+    it "version has the right parent" do
+      subject.foo = 42
+      subject.instance_eval { puts self.temporal_versions[0].my_model_id.should == self.id}
+    end
+
+    it "update all still works for non-temporal properties" do
+      pending
+      MyModel.update(:name => 'all the same')
+
+      subject.name.should == 'all the same'
+    end
+
+    it "select all still works for non-temporal properties" do
+      subject.name = 'looking for me!'
+      subject.save
+      all = MyModel.all(:name => 'looking for me!')
+      all.size.should == 1
+      all[0].name.should == 'looking for me!'
+    end
+
+    context "non-temporal properties" do
+      it "should work as normal" do
+        subject.name = 'foo'
+        subject.name.should == 'foo'
+
+        subject.name = 'bar'
+        subject.name.should == 'bar'
+      end
+
+      it "should work when accessed via at(time)" do
+        oldish = DateTime.parse('-4712-01-01T00:00:00+00:00')
+        nowish = DateTime.parse('2011-03-01T00:00:00+00:00')
+        future = DateTime.parse('4712-01-01T00:00:00+00:00')
+
+        subject.at(oldish).name = 'foo'
+
+        subject.at(oldish).name.should == 'foo'
+        subject.at(nowish).name.should == 'foo'
+        subject.at(future).name.should == 'foo'
+
+        subject.at(nowish).name = 'bar'
+
+        subject.at(oldish).name.should == 'bar'
+        subject.at(nowish).name.should == 'bar'
+        subject.at(future).name.should == 'bar'
+
+        subject.name = 'rat'
+
+        subject.at(oldish).name.should == 'rat'
+        subject.at(nowish).name.should == 'rat'
+        subject.at(future).name.should == 'rat'    
+      end
+    end
+
+    context "setting temporal properties" do
+      it "works" do
+        oldish = DateTime.parse('-4712-01-01T00:00:00+00:00')
+        nowish = DateTime.parse('2011-03-01T00:00:00+00:00')
+        future = DateTime.parse('4712-01-01T00:00:00+00:00')
+
+        subject.at(oldish).foo = 42
+
+        subject.at(oldish).foo.should == 42
+        subject.at(nowish).foo.should == 42
+        subject.at(future).foo.should == 42
+
+        subject.at(nowish).foo = 1024
+
+        subject.at(oldish).foo.should == 42
+        subject.at(nowish).foo.should == 1024
+        subject.at(future).foo.should == 1024
+
+        subject.at(future).foo = 3
+
+        subject.at(oldish).foo.should == 42
+        subject.at(nowish).foo.should == 1024
+        subject.at(future).foo.should == 3
+
+        subject.instance_eval { puts self.temporal_versions.size.should == 3}
+      end
+
+      it "and rewriting works" do
+        now = DateTime.parse('2011-03-01T00:00:00+00:00')
+
+        subject.at(now).foo = 42
+        subject.at(now).foo.should == 42
+
+        subject.at(now).foo = 1
+        subject.at(now).foo.should == 1
+      end
+    end
+
     context "when at context" do
       it "returns old values" do
         subject.foo.should == nil
@@ -58,6 +146,12 @@ describe DataMapper::Is::Temporal do
 
         subject.at(old).foo.should == nil
         subject.at(now).foo.should == 42
+
+        subject.foo = 1024
+        subject.foo.should == 1024
+
+        subject.at(old).foo.should == nil
+        subject.at(now).foo.should == 42
       end
     end
 
@@ -67,6 +161,15 @@ describe DataMapper::Is::Temporal do
         subject.foo = 42
         subject.foo.should == 42
       end
+
+      it "returns 'same' for bar" do
+        subject.bar = 'same'
+        subject.bar.should == 'same'
+        subject.foo.should == nil
+        subject.foo = 42
+        subject.foo.should == 42
+        subject.bar.should == 'same'
+      end
     end
 
     context "when bar is 'hello'" do
@@ -166,5 +269,142 @@ describe DataMapper::Is::Temporal do
         end
       end
     end
+
+    context "when multi setting" do
+      it "works with different times" do
+        oldish = DateTime.parse('-4712-01-01T00:00:00+00:00')
+        nowish = DateTime.parse('2011-03-01T00:00:00+00:00')
+        future = DateTime.parse('4712-01-01T00:00:00+00:00')
+
+        subject.at(oldish) do |s|
+          s.foo = 42
+          s.bar = "cat"
+        end
+
+        subject.at(oldish).foo.should == 42
+        subject.at(nowish).foo.should == 42
+        subject.at(future).foo.should == 42
+
+        subject.at(oldish).bar.should == "cat"
+        subject.at(nowish).bar.should == "cat"
+        subject.at(future).bar.should == "cat"
+
+        subject.at(nowish) do |s|
+          s.foo = 1024
+          s.bar = "dog"
+        end
+
+        subject.at(oldish).foo.should == 42
+        subject.at(nowish).foo.should == 1024
+        subject.at(future).foo.should == 1024
+
+        subject.at(oldish).bar.should == "cat"
+        subject.at(nowish).bar.should == "dog"
+        subject.at(future).bar.should == "dog"
+
+        subject.at(future) do |s|
+          s.foo = 3
+          s.bar = "rat"
+        end
+
+        subject.at(oldish).foo.should == 42
+        subject.at(nowish).foo.should == 1024
+        subject.at(future).foo.should == 3
+
+        subject.at(oldish).bar.should == "cat"
+        subject.at(nowish).bar.should == "dog"
+        subject.at(future).bar.should == "rat"
+
+        subject.instance_eval { puts self.temporal_versions.size.should == 3}
+      end
+
+      it "works with different times and non-temporal properties" do
+        oldish = DateTime.parse('-4712-01-01T00:00:00+00:00')
+        nowish = DateTime.parse('2011-03-01T00:00:00+00:00')
+        future = DateTime.parse('4712-01-01T00:00:00+00:00')
+
+        subject.at(oldish) do |s|
+          s.name = "same"
+          s.foo = 42
+          s.bar = "cat"
+        end
+
+        subject.at(oldish).foo.should == 42
+        subject.at(nowish).foo.should == 42
+        subject.at(future).foo.should == 42
+
+        subject.at(oldish).bar.should == "cat"
+        subject.at(nowish).bar.should == "cat"
+        subject.at(future).bar.should == "cat"
+
+        subject.at(oldish).name.should == "same"
+        subject.at(nowish).name.should == "same"
+        subject.at(future).name.should == "same"
+
+        subject.at(nowish) do |s|
+          s.name = "every"
+          s.foo = 1024
+          s.bar = "dog"
+        end
+
+        subject.at(oldish).foo.should == 42
+        subject.at(nowish).foo.should == 1024
+        subject.at(future).foo.should == 1024
+
+        subject.at(oldish).bar.should == "cat"
+        subject.at(nowish).bar.should == "dog"
+        subject.at(future).bar.should == "dog"
+
+        subject.at(oldish).name.should == "every"
+        subject.at(nowish).name.should == "every"
+        subject.at(future).name.should == "every"
+
+        subject.at(future) do |s|
+          s.name = "time"
+          s.foo = 3
+          s.bar = "rat"
+        end
+
+        subject.at(oldish).foo.should == 42
+        subject.at(nowish).foo.should == 1024
+        subject.at(future).foo.should == 3
+
+        subject.at(oldish).bar.should == "cat"
+        subject.at(nowish).bar.should == "dog"
+        subject.at(future).bar.should == "rat"
+
+        subject.at(oldish).name.should == "time"
+        subject.at(nowish).name.should == "time"
+        subject.at(future).name.should == "time"
+
+        subject.instance_eval { puts self.temporal_versions.size.should == 3}
+      end
+
+      it "works with no time (i.e. now)" do
+        subject.at do |s|
+          s.foo = 42
+          s.bar = "cat"
+        end
+
+        subject.foo.should == 42
+        subject.bar.should == "cat"
+
+        subject.instance_eval { puts self.temporal_versions.size.should == 1}
+      end
+
+      it "works with no time (i.e. now)" do
+        subject.at do |s|
+          s.name = "foobar"
+          s.foo = 42
+          s.bar = "cat"
+        end
+
+        subject.foo.should == 42
+        subject.bar.should == "cat"
+        subject.name.should == "foobar"
+
+        subject.instance_eval { puts self.temporal_versions.size.should == 1}
+      end
+    end
   end
 end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
     - 0
+    - 2
     - 0
-    - 1
-  version: 0.0.1
+  version: 0.2.0
 platform: ruby
 authors: 
   - Joe Kutner
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-03-08 00:00:00 -06:00
+date: 2011-03-22 00:00:00 -05:00
 default_executable: 
 dependencies: []
 
@@ -28,7 +28,6 @@ extra_rdoc_files:
   - LICENSE.txt
   - README.md
 files: 
-  - Gemfile
   - LICENSE.txt
   - README.md
   - Rakefile