clockwork 1.3.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 66489a780e645c6b88fe4fe8548faaa80615d85c
-  data.tar.gz: ad94d2f1a2f376d7f5931d177267b91ec6b69841
+  metadata.gz: 6614568ab73c78b0be1866b355ba1cd288cce5a6
+  data.tar.gz: a083d36f8fc30fb7b55f86278b1fd1e3577d4915
 SHA512:
-  metadata.gz: 9b1409ea965916002991e9fd1a38d2453350994d027aa9b114a7f4feee4edb1a902ac07076c691d84e462fc9b697fe13989858f524184311d44d3717c7887aba
-  data.tar.gz: 085f2739c059e90b8ea5875c0fb9b2eb161a7e09114cdd5db9a116a171fb5615db066278e65bfd641b78b1bac4cd77255438e8c27d94679d26bda66d4e2aa518
+  metadata.gz: dffa0ee3bcd26a2febaafebac063f71a46857001654b3748b292601f4134a9f64c0186b626bb72bc4c4d39eaec1a41e3c162d6ca5b64d53de248176854cd7915
+  data.tar.gz: 169d1db6499306e74dd86c89767e92818ffcc3d55873ac9dd04ddec9fe8b2d5648cb685e1dfbac4d3ad7bff4e467fcd2046e9c4cb0c680aef079906b354fd76a

data/README.md

@@ -142,9 +142,9 @@ module Clockwork
 end
 ```
 
-This tells clockwork to fetch all `ClockworkDatabaseEvent` instances from the database, creating an internal clockwork event for each one, configured based on the instance's `frequency`, `at` and optionally `name` and `tz` methods. It also says to reload the events from the database every `1.minute`; we need pick up any changes in the database frequently (choose a sensible reload frequency by changing the `every:` option).
+This tells clockwork to fetch all `ClockworkDatabaseEvent` instances from the database, and create an internal clockwork event for each one. Each clockwork event will be configured based on the instance's `frequency` and, optionally, its `at`, `name`, `if?` and `tz` methods. The code above also says to reload the events from the database every `1.minute`; we need pick up any changes in the database frequently (choose a sensible reload frequency by changing the `every:` option).
 
-When one of the events is ready to be run (based on it's `frequency`, `at` and possible `tz` methods), clockwork arranges for the block passed to `sync_database_events` to be run. The above example shows how you could use either DelayedJob or Sidekiq to simply kick off a worker job. This approach is good because the ideal is to use clockwork as a simple scheduler, and avoid making it carry out any long-running tasks.
+When one of the events is ready to be run (based on it's `frequency`, and possible `at`, `if?` and `tz` methods), clockwork arranges for the block passed to `sync_database_events` to be run. The above example shows how you could use either DelayedJob or Sidekiq to kick off a worker job. This approach is good because the ideal is to use clockwork as a simple scheduler, and avoid making it carry out any long-running tasks.
 
 ### Your Model Classes
 
@@ -158,10 +158,14 @@ When one of the events is ready to be run (based on it's `frequency`, `at` and p
 
     - `frequency` returning the how frequently (in seconds) the database event should be run
 
-    - `at` return nil or `''` if not using `:at`, or otherwise any acceptable clockwork `:at` string
+    - `attributes` returning a hash of [attribute name] => [attribute value] values (or really anything that we can use store on registering the event, and then compare again to see if the state has changed later)
+
+    - (optionally) `at` return any acceptable clockwork `:at` string
 
     - (optionally) `name` returning the name for the event (used to identify it in the Clcockwork output)
 
+    - (optionally) `if?` returning either true or false, depending on whether the database event should run at the given time (this method will be passed the time as a parameter, much like the standard clockwork `:if`)
+
     - (optionally) `tz` returning the timezone to use (default is the local timezone)
 
 #### Example Setup
@@ -220,6 +224,28 @@ end
 ...
 ```
 
+#### Example use of `if?`
+
+Database events support the ability to run events if certain conditions are met. This can be used to only run events on a given day, week, or month, or really any criteria you could conceive. Best of all, these criteria e.g. which day to
+run it on can be attributes on your Model, and therefore change dynamically as you change the Model in the database.
+
+So for example, if you had a Model that had a `day` and `month` integer attribute, you could specify that the Database event should only run on a particular day of a particular month as follows:
+
+```ruby
+# app/models/clockwork_database_event.rb
+class ClockworkDatabaseEvent < ActiveRecord::Base
+
+  ...
+
+  def if?(time)
+    time.day == day && time.month == month
+  end
+
+  ...
+end
+```
+
+
 Event Parameters
 ----------
 

data/clockwork.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = "clockwork"
-  s.version = "1.3.1"
+  s.version = "2.0.0"
 
   s.authors = ["Adam Wiggins", "tomykaira"]
   s.license = 'MIT'

data/lib/clockwork/database_events/event.rb

@@ -4,12 +4,13 @@ module Clockwork
 
     class Event < Clockwork::Event
 
-      attr_accessor :event_store, :at
+      attr_accessor :event_store, :model_attributes
 
-      def initialize(manager, period, job, block, event_store, options={})
+      def initialize(manager, period, job, block, event_store, model_attributes, options={})
         super(manager, period, job, block, options)
         @event_store = event_store
         @event_store.register(self, job)
+        @model_attributes = model_attributes
       end
 
       def name

data/lib/clockwork/database_events/event_collection.rb

@@ -14,9 +14,7 @@ module Clockwork
       def has_changed?(model)
         return true if event.nil?
 
-        (has_name? && name != model.name) ||
-          frequency != model.frequency ||
-            ats != model_ats(model)
+        event.model_attributes != model.attributes
       end
 
       def unregister
@@ -27,33 +25,12 @@ module Clockwork
 
       attr_reader :events, :manager
 
+      # All events in the same collection (for a model instance) are equivalent
+      # so we can use any of them. Only their @at variable will be different,
+      # but we don't care about that here.
       def event
         events.first
       end
-
-      def has_name?
-        event.job_has_name?
-      end
-
-      def name
-        event.name
-      end
-
-      def frequency
-        event.frequency
-      end
-
-      def ats
-        events.collect(&:at).compact
-      end
-
-      def model_ats(model)
-        at_strings_for(model).collect{|at| At.parse(at) }
-      end
-
-      def at_strings_for(model)
-        model.at.to_s.split(',').map(&:strip)
-      end
     end
   end
 end

data/lib/clockwork/database_events/event_store.rb

@@ -112,11 +112,16 @@ module Clockwork
         options = {
           :from_database => true,
           :synchronizer => self,
-          :at => at_strings_for(model)
         }
 
+        options[:at] = at_strings_for(model) if model.respond_to?(:at)
+        options[:if] = ->(time){ model.if?(time) } if model.respond_to?(:if?)
         options[:tz] = model.tz if model.respond_to?(:tz)
 
+        # store the state of the model at time of registering so we can
+        # easily compare and determine if state has changed later
+        options[:model_attributes] = model.attributes
+
         options
       end
 

data/lib/clockwork/database_events/manager.rb

@@ -10,7 +10,11 @@ module Clockwork
 
       def register(period, job, block, options)
         @events << if options[:from_database]
-          Clockwork::DatabaseEvents::Event.new(self, period, job, (block || handler), options.fetch(:synchronizer), options)
+          synchronizer = options.fetch(:synchronizer)
+          model_attributes = options.fetch(:model_attributes)
+
+          Clockwork::DatabaseEvents::Event.
+            new(self, period, job, (block || handler), synchronizer, model_attributes, options)
         else
           Clockwork::Event.new(self, period, job, block || handler, options)
         end

data/test/database_events/support/active_record_fake.rb

@@ -23,6 +23,10 @@ module ActiveRecordFake
     set_attribute_values_from_options options
   end
 
+  def attributes
+    Hash[instance_variables.map { |name| [name, instance_variable_get(name)] } ]
+  end
+
   module ClassMethods
     def create *args
       new *args

data/test/database_events/synchronizer_test.rb

@@ -10,8 +10,6 @@ require_relative 'test_helpers'
 describe Clockwork::DatabaseEvents::Synchronizer do
   before do
     @now = Time.now
-    DatabaseEventModel.delete_all
-    DatabaseEventModel2.delete_all
 
     Clockwork.manager = @manager = Clockwork::DatabaseEvents::Manager.new
     class << @manager
@@ -21,6 +19,9 @@ describe Clockwork::DatabaseEvents::Synchronizer do
 
   after do
     Clockwork.clear!
+    DatabaseEventModel.delete_all
+    DatabaseEventModel2.delete_all
+    DatabaseEventModelWithIf.delete_all
   end
 
   describe "setup" do
@@ -254,6 +255,37 @@ describe Clockwork::DatabaseEvents::Synchronizer do
       end
     end
 
+    describe "with model that responds to `if?`" do
+
+      before do
+        @events_run = []
+      end
+
+      describe "when model.if? is true" do
+        it 'runs' do
+          DatabaseEventModelWithIf.create(:if_state => true, :frequency => 10)
+          setup_sync(model: DatabaseEventModelWithIf, :every => 1.minute, :events_run => @events_run)
+
+          tick_at(@now, :and_every_second_for => 9.seconds)
+
+          assert_equal 1, @events_run.length
+        end
+      end
+
+      describe "when model.if? is false" do
+        it 'does not run' do
+          DatabaseEventModelWithIf.create(:if_state => false, :frequency => 10, :name => 'model with if?')
+          setup_sync(model: DatabaseEventModelWithIf, :every => 1.minute, :events_run => @events_run)
+
+          tick_at(@now, :and_every_second_for => 1.minute)
+
+          # require 'byebug'
+          # byebug if events_run.length > 0
+          assert_equal 0, @events_run.length
+        end
+      end
+    end
+
     describe "with task that responds to `tz`" do
       before do
         @events_run = []

data/test/database_events/test_helpers.rb

@@ -55,4 +55,17 @@ end
 class DatabaseEventModelWithoutName
   include ActiveRecordFake
   attr_accessor :frequency, :at
+end
+
+class DatabaseEventModelWithIf
+  include ActiveRecordFake
+  attr_accessor :name, :frequency, :at, :tz, :if_state
+
+  def name
+    @name || "#{self.class}:#{id}"
+  end
+
+  def if?(time)
+    @if_state
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clockwork
 version: !ruby/object:Gem::Version
-  version: 1.3.1
+  version: 2.0.0
 platform: ruby
 authors:
 - Adam Wiggins