time_zone_scheduler 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2fb3de5fe652050bd39dd7d0c9f701d03192bcaa
-  data.tar.gz: 82b688ff61898698f7c02fc003884df2233e8680
+  metadata.gz: 8893fdc4ca33c5f42c0491fbe22a5b1f7622b761
+  data.tar.gz: 622570aac4c0b1bd5a2bcd893d94cfb0a7b2ee4c
 SHA512:
-  metadata.gz: b2b4553f90d2ad11373a4ae9aaee1edc9f4c8bea5f922bcf92346a6fb1b8e19d0e9332b12ac4929677c786fae4d2457d974d2f11292d49c252561c63a8a47dd4
-  data.tar.gz: 3a3cd0847f7561c700f86f1a1286f1fc877bfbe17740d2ee0b424acdbd4301261696f1e3455d717945fd8f8facdcf63e899a8319059d1ed94d3d3e9b94596762
+  metadata.gz: 55b0629af3ff87ed95329d7baabcc25d6eb349c0d4e359596287cee288cba5cec6efdcc69f04569f5a09dab3a24e6a1ee0e5467b1fc92ec29dc31ab573c76cfa
+  data.tar.gz: 5da1e804698e831fe6ed453c99a91eb09dae87c2b84f1521cdbd1c4413f59e013bbd6e0e19f47bfbd8080c90f248af29728cabd85c3a1010125b8082f0bfe4ee

data/README.md

@@ -5,6 +5,9 @@
 A Ruby library that assists in scheduling events whilst taking time zones into account. E.g. when to best deliver
 notifications such as push notifications or emails.
 
+It includes a ORM ‘view’ that is able to partition a collection by time zone and extends the partitions with the
+TimeZoneScheduler API.
+
 NOTE: _It is not yet battle-tested. This will all follow over the next few weeks._
 
 ## Installation
@@ -25,7 +28,47 @@ Or install it yourself as:
 
 ## Usage
 
-See [the documentation](http://www.rubydoc.info/gems/time_zone_scheduler).
+For full details, see [the documentation](http://www.rubydoc.info/gems/time_zone_scheduler).
+
+Here’s an example that uses the ‘view’ ORM helper. This example uses Mongoid, but its usage is pretty much the same with
+ActiveRecord.
+
+```ruby
+require 'time_zone_scheduler/view'
+
+class User
+  include Mongoid::Document
+
+  field :time_zone, type: String
+
+  extend TimeZoneScheduler::View
+  view_field_as_time_zone :time_zone
+end
+
+User.create(time_zone: 'Europe/Amsterdam') # => #<User ID=1>
+User.create(time_zone: 'Europe/Paris')     # => #<User ID=2>
+User.create(time_zone: 'America/New_York') # => #<User ID=3>
+
+time_zone_views = User.in_time_zones
+p time_zone_views.map { |view| view.map(&:id) }    # => [[1], [2], [3]]
+p time_zone_views.map { |view| view.map(&:class) } # => [Mongoid::Criteria, Mongoid::Criteria, Mongoid::Criteria]
+p time_zone_views.map { |view| view.time_zone }    # => ['Europe/Amsterdam', 'Europe/Paris', 'America/New_York']
+```
+
+Now consider, for instance, that you want to schedule the delivery of Apple Push Notifications, but do want to respect
+the user and so, regardless of the user’s time zone, always deliver on Friday, January the 15th of 2016, at 10AM:
+
+```ruby
+date_and_time = Time.parse('2016-01-15 10:00')
+
+User.in_time_zones.each do |users|
+  # Calculate the system time that corresponds to the date and time in the user’s time zone.
+  run_at = users.schedule_on_date(date_and_time)
+  # Perform the delivery of the push notifications on the calculated time.
+  # (This example uses the DelayedJob API to delay delivery.)
+  PushNotification.delay(run_at: run_at).deliver(users)
+end
+```
 
 ## Contributing
 

data/lib/time_zone_scheduler/version.rb

@@ -1,3 +1,3 @@
 class TimeZoneScheduler
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/lib/time_zone_scheduler/view.rb

@@ -0,0 +1,95 @@
+require 'time_zone_scheduler'
+require 'forwardable'
+
+class TimeZoneScheduler
+  module View
+    # Defines a singleton method called `in_time_zones` which returns a list of
+    # views on the model partitioned by the time zones available in the specified
+    # time zone model field.
+    #
+    # It is able to extend ActiveRecord and Mongoid models.
+    #
+    # @see View#in_time_zones
+    #
+    # @param  [Symbol] time_zone_field
+    #         the model field that holds the time zone names.
+    #
+    # @param  [String] default_time_zone
+    #         the time zone to use if the value of the field can be `nil`.
+    #
+    # @return [void]
+    #
+    def view_field_as_time_zone(time_zone_field, default_time_zone = nil)
+      time_zone_scopes = lambda do |scope, time_zones|
+        time_zones.map do |time_zone|
+          scope.where(time_zone_field => time_zone).tap do |scope|
+            scope.extend Mixin
+            scope.time_zone_scheduler = TimeZoneScheduler.new(time_zone || default_time_zone)
+          end
+        end
+      end
+
+      if respond_to?(:scope)
+        # ActiveRecord
+        define_singleton_method :in_time_zones do
+          time_zone_scopes.call(scope, scope.select(time_zone_field).distinct)
+        end
+      elsif respond_to?(:scoped)
+        # Mongoid
+        define_singleton_method :in_time_zones do
+          time_zone_scopes.call(scoped, scoped.distinct(time_zone_field))
+        end
+      else
+        raise 'Unknown ORM.'
+      end
+    end
+
+    # Defines a singleton method called `in_time_zones` which returns a list of
+    # views on the model partitioned by the time zones available in the specified
+    # time zone model field.
+    #
+    # Returns views that are regular `Mongoid::Criteria` or `ActiveRecord::Relation` instances created from the current
+    # scope (and narrowed down by time zone), but are extended with the `TimeZoneScheduler` API.
+    #
+    # @see https://github.com/alloy/time_zone_scheduler
+    # @see http://www.rubydoc.info/gems/time_zone_scheduler/TimeZoneScheduler
+    #
+    # @example
+    #
+    #   class User
+    #     field :time_zone, type: String
+    #
+    #     extend TimeZoneScheduler::View
+    #     view_field_as_time_zone :time_zone
+    #   end
+    #
+    #   User.create(time_zone: 'Europe/Amsterdam')
+    #   time_zone_view = User.in_time_zones.first
+    #
+    #   p time_zone_view # => #<User where: { time_zone: 'Europe/Amsterdam' }>
+    #   p time_zone_view.time_zone # => 'Europe/Amsterdam'
+    #   p time_zone_view.time_zone_scheduler # => #<TimeZoneScheduler>
+    #
+    #   # See TimeZoneScheduler for documentation on these available methods.
+    #   time_zone_view.schedule_on_date(time)
+    #   time_zone_view.schedule_in_timeframe(time, timeframe)
+    #   time_zone_view.in_timeframe?(time, timeframe)
+    #
+    # @return [Array<Mongoid::Criteria, ActiveRecord::Relation, TimeZoneScheduler::View::Mixin>]
+    #         a list of criteria partitioned by time zone and extended with the {Mixin} module.
+    #
+    def in_time_zones
+      raise 'Need to call view_field_as_time_zone first.'
+    end
+
+    module Mixin
+      extend Forwardable
+
+      attr_accessor :time_zone_scheduler
+      def_delegator :time_zone_scheduler, :destination_time_zone, :time_zone
+      def_delegator :time_zone_scheduler, :schedule_on_date
+      def_delegator :time_zone_scheduler, :schedule_in_timeframe
+      def_delegator :time_zone_scheduler, :in_timeframe?
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: time_zone_scheduler
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Eloy Durán
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-01-14 00:00:00.000000000 Z
+date: 2016-01-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -96,6 +96,7 @@ files:
 - Rakefile
 - lib/time_zone_scheduler.rb
 - lib/time_zone_scheduler/version.rb
+- lib/time_zone_scheduler/view.rb
 - time_zone_scheduler.gemspec
 homepage: https://github.com/alloy/time_zone_scheduler
 licenses: