availability 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b234c8bd7ec4affc5c2021508d9d7f3875541e94
+  data.tar.gz: 2accd7d37b256be224033646289723257fea91ec
+SHA512:
+  metadata.gz: 2bc9136b9b206d295305bc283bb3624499827017080981c8c3589014292f058b0a637af1a97494e8c7207eb5b1f4ddb5f74aed709bd218e056dda8ad3f033fcd
+  data.tar.gz: f1170cb99e6773867917b83407e55f5d001c38ea453588553633d5f9a82b589e3f39570bcae419d192d9bacffba9f50a57d1bfbbc0f3d329ed732518b4f969a2

data/.gitignore

@@ -0,0 +1,11 @@
+spec/examples.txt
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/WAIVER.asc

data/.rspec

@@ -0,0 +1,5 @@
+--color
+--require spec_helper
+-I examples
+--require scheduler_spec
+--format progress

data/.ruby-gemset

@@ -0,0 +1 @@
+modulo-math-poc

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.3.0

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.3.0
+before_install: gem install bundler -v 1.10.5

data/CREDITS

@@ -0,0 +1 @@
+* Jason Rogers <jacaetevha@gmail.com>

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in availability.gemspec
+gemspec

data/README.md

@@ -0,0 +1,51 @@
+# availability - easily and quickly calculate schedule availability
+
+[![Build Status][travis-availability-png]][travis-availability]
+[![Gem Version](https://badge.fury.io/rb/availability.svg)](http://badge.fury.io/rb/availability)
+
+This library uses modular arithmetic and residue classes to calculate schedule availability for dates. Time ranges within a date are handled differently. The goal is to create an easy-to-use API for schedule availability that is very fast and lightweight that is also easy and lightweight to persist in a database.
+
+Shout out to @dpmccabe for his [original article](http://dmcca.be/2014/01/09/recurring-subscriptions-with-ruby-rspec-and-modular-arithmetic.html) and code.
+
+```
+gem install availability
+```
+
+## TODO
+
+add more documentation
+
+## Authors
+
+* Jason Rogers <jacaetevha@gmail.com>
+
+## Contributors
+
+* Jason Rogers <jacaetevha@gmail.com>
+
+## Contributing
+
+* Do your best to adhere to the existing coding conventions and idioms.
+* Don't use hard tabs, and don't leave trailing whitespace on any line.
+  Before committing, run `git diff --check` to make sure of this.
+* Do document every method you add using [YARD][] annotations. Read the
+  [tutorial][YARD-GS] or just look at the existing code for examples.
+* Don't touch the `availability.gemspec` or `VERSION` files. If you need
+  to change them, do so on your private branch only.
+* Do feel free to add yourself to the `CREDITS` file and the
+  corresponding list in the the `README`. Alphabetical order applies.
+* Don't touch the `AUTHORS` file. If your contributions are significant
+  enough, be assured we will eventually add you in there.
+* Do note that in order for us to merge any non-trivial changes (as a rule
+  of thumb, additions larger than about 15 lines of code), we need an
+  explicit on record from you. You can submit this dedication as a GitHub
+  Issue in this repository. See [public domain dedication][PDD] for an example.
+
+## License
+
+This is free and unencumbered public domain software. For more information,
+see <http://unlicense.org/> or the accompanying [UNLICENSE]{UNLICENSE} file.
+
+[YARD]:             http://yardoc.org/
+[YARD-GS]:          http://rubydoc.info/docs/yard/file/docs/GettingStarted.md
+[PDD]:              http://lists.w3.org/Archives/Public/public-rdf-ruby/2010May/0013.html

data/Rakefile

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

data/UNLICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+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 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.
+
+For more information, please refer to <http://unlicense.org>

data/WAIVER

@@ -0,0 +1,17 @@
+# Copyright waiver for <https://github.com/upper-hand/availability>
+
+I dedicate any and all copyright interest in this software to the
+public domain. I make this dedication for the benefit of the public at
+large and to the detriment of my heirs and successors. I intend this
+dedication to be an overt act of relinquishment in perpetuity of all
+present and future rights to this software under copyright law.
+
+To the best of my knowledge and belief, my contributions are either
+originally authored by me or are derived from prior works which I have
+verified are also in the public domain and are not subject to claims
+of copyright by other parties.
+
+To the best of my knowledge and belief, no individual, business,
+organization, government, or other entity has any copyright interest
+in my contributions, and I affirm that I will not make contributions
+that are otherwise encumbered.

data/availability.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'availability/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "availability"
+  spec.version       = Availability::VERSION
+  spec.authors       = ["Jason Rogers"]
+  spec.email         = ["jacaetevha@gmail.com"]
+
+  spec.summary       = %q{Calculating schedule availability}
+  spec.description   = %q{Use modular arithmetic and residue classes to calculate schedule availability for dates (times handled separately).}
+  spec.homepage      = "https://github.com/upper-hand/availability"
+  spec.license       = "Unlicense"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activesupport"
+
+  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "rspec-its"
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "availability"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/examples/scheduler.rb

@@ -0,0 +1,88 @@
+require_relative '../lib/availability'
+
+#
+# This is just an example of a scheduler that might be used with availabilities. It's a work in
+# progress that's helping to flesh out the design of availabilities.
+#
+class Scheduler
+  attr_reader :availabilities, :scheduled
+
+  #
+  # availabilities: a list of Availability instances defining when the resource is available
+  #
+  def initialize(availabilities)
+    @availabilities = validate_availabilities availabilities
+    @scheduled = Hash.new{|h, k| h[k] = []}
+  end
+
+  #
+  # This method expects either an availability request or a start/end time pair. If the
+  # start/end time pair is offered, this method acts the same as if an Availability::Once
+  # request was offered with the given start_time and a duration going through the given
+  # end_time.
+  #
+  # availability_request: an Availability instance
+  # start_time: Time/DateTime representative of a single request starting at that time
+  # end_time: Time/DateTime representative of a single request ending at that time
+  #
+  # Returns the first availability that corresponds to the availability request. If no
+  # availability is found, returns nil.
+  #
+  def allow?(**args)
+    availability_request = convert **args
+    availability_for availability_request
+  end
+
+  #
+  # This method expects either an availability request or a start/end time pair. If the
+  # start/end time pair is offered, this method acts the same as if an Availability::Once
+  # request was offered with the given start_time and a duration going through the given
+  # end_time.
+  #
+  # availability_request: an Availability instance
+  # start_time: Time/DateTime representative of a single request starting at that time
+  # end_time: Time/DateTime representative of a single request ending at that time
+  #
+  # returns boolean indicating whether the availability request was scheduled.
+  #
+  def schedule(**args)
+    request = convert **args
+    availability = allow? availability_request: request
+    return self unless availability
+    scheduled[availability] << request unless scheduled[availability].size >= availability.capacity
+    self
+  end
+
+  private
+  def availability_for(request)
+    @availabilities.detect do |some_availability|
+      some_availability.corresponds_to? request
+    end
+  end
+
+  def convert(availability_request: nil, start_time: nil, end_time: nil)
+    validate_allow_params! availability_request, start_time, end_time
+    if availability_request.nil?
+      availability_request = Availability::Once.create(
+        start_time: start_time, duration: (end_time.to_time - start_time.to_time).to_i)
+    else
+      availability_request
+    end
+  end
+
+  def validate_availabilities(availabilities)
+    list = Array(availabilities).flatten.compact
+    return list if list.all? { |e| e.respond_to? :corresponds_to? }
+    raise ArgumentError, "expected a list of availabilities"
+  end
+
+  def validate_allow_params!(availability, start_time, end_time)
+    return if Availability.availability?(availability)
+    return if valid_time?(start_time) && valid_time?(end_time)
+    raise ArgumentError, "must specify either availability_request or (start_time and end_time)"
+  end
+
+  def valid_time?(a_time)
+    Time === a_time || DateTime === a_time || Date === a_time
+  end
+end

data/examples/scheduler_spec.rb

@@ -0,0 +1,136 @@
+require_relative 'scheduler'
+
+module SchedulerSpecHelpers
+  def T(*args)
+    Time.new *args
+  end
+
+  def one_hour_slot_per_week(**args)
+    Availability.weekly **args, duration: 1.hour
+  end
+
+  def half_hour_slot_per_week(**args)
+    Availability.weekly **args, duration: 30.minutes
+  end
+end
+
+RSpec.describe Scheduler do
+  include SchedulerSpecHelpers
+
+  context '#allow?' do
+    let(:bob_availabilities) do
+      [
+        one_hour_slot_per_week(start_time: T(2016, 4, 11, 9), stops_by: T(2016, 5,  9, 9)),
+        one_hour_slot_per_week(start_time: T(2016, 4, 12, 9), stops_by: T(2016, 5, 10, 9)),
+        one_hour_slot_per_week(start_time: T(2016, 4, 13, 9), stops_by: T(2016, 5, 11, 9)),
+        one_hour_slot_per_week(start_time: T(2016, 4, 14, 9), stops_by: T(2016, 5, 12, 9)),
+        one_hour_slot_per_week(start_time: T(2016, 4, 15, 9), stops_by: T(2016, 5, 13, 9))
+      ]
+    end
+
+    let(:bobs_schedule) { Scheduler.new bob_availabilities }
+
+    describe '#schedule' do
+      let(:request) { bob_availabilities.first.dup }
+      let(:short_request) do
+        half_hour_slot_per_week start_time: T(2016, 4, 14, 9, 15), stops_by: T(2016, 5, 12, 9, 45)
+      end
+      let(:scheduled_count) { -> { bobs_schedule.scheduled.values.map(&:size).sum } }
+
+      before :each do
+        bob_availabilities.each { |e| e.capacity = 1 }
+      end
+
+      context 'at capacity' do
+        before :each do
+          bob_availabilities.each { |e| bobs_schedule.scheduled[e] = [double('a request')] }
+        end
+
+        context 'with a shorter slot that fits within the availability' do
+          it 'does not accept a request' do
+            expect{ bobs_schedule.schedule availability_request: short_request }.not_to change(&scheduled_count)
+          end
+        end
+
+        it 'does not accept a request' do
+          expect{ bobs_schedule.schedule availability_request: request }.not_to change(&scheduled_count)
+        end
+      end
+
+      context 'not at capacity' do
+        context 'with a shorter slot that fits within the availability' do
+          it 'accepts a request' do
+            expect{ bobs_schedule.schedule availability_request: short_request }.to change(&scheduled_count).from(0).to(1)
+          end
+        end
+
+        it 'accepts a request' do
+          expect{ bobs_schedule.schedule availability_request: request }.to change(&scheduled_count).from(0).to(1)
+        end
+      end
+    end
+
+    describe '#allow?' do
+      context 'enforces parameter values' do
+        it { expect{bobs_schedule.allow?}.to raise_error ArgumentError }
+        it { expect{bobs_schedule.allow? availability_request: nil}.to raise_error ArgumentError }
+        it { expect{bobs_schedule.allow? start_time: nil }.to raise_error ArgumentError }
+        it { expect{bobs_schedule.allow? start_time: Date.today }.to raise_error ArgumentError }
+        it { expect{bobs_schedule.allow? end_time: nil }.to raise_error ArgumentError }
+        it { expect{bobs_schedule.allow? end_time: Date.today }.to raise_error ArgumentError }
+        it { expect{bobs_schedule.allow? availability_request: one_hour_slot_per_week(start_time: T(0))}.not_to raise_error }
+        it { expect{bobs_schedule.allow? start_time: Date.today, end_time: Date.tomorrow}.not_to raise_error }
+      end
+
+      context 'with Availability objects' do
+        it 'allows an event requests that start in the first week and go through the end of the availability' do
+          bob_availabilities.each do |a|
+            expect(bobs_schedule.allow? availability_request: a).to be_truthy, "at #{a.start_time}"
+          end
+        end
+
+        it 'allows an event request in the second week that lasts until the end of the availability' do
+          ar = one_hour_slot_per_week(start_time: T(2016, 4, 18, 9), stops_by: T(2016, 5, 2, 9))
+          expect(bobs_schedule.allow? availability_request: ar).to be_truthy
+        end
+
+        it 'does not allow an event request that is beyond the availability frequency' do
+          expect(bobs_schedule.allow? availability_request: one_hour_slot_per_week(start_time: T(2016, 4, 18, 9), frequency: 4)).to be_falsey
+        end
+
+        it 'does not allow an event request that starts before the availability frequency' do
+          expect(bobs_schedule.allow? availability_request: one_hour_slot_per_week(start_time: T(2016, 4, 4, 9), frequency: 4)).to be_falsey
+        end
+
+        it 'does not allow an event request with a different frequency' do
+          expect(bobs_schedule.allow? availability_request: one_hour_slot_per_week(start_time: T(2016, 4, 4, 9), frequency: 5)).to be_falsey
+        end
+      end
+
+      context 'with start/end times' do
+        it 'allows an event requests that start in the first week and go through the end of the availability' do
+          bob_availabilities.each do |a|
+            expect(bobs_schedule.allow? start_time: a.start_time, end_time: a.end_time).to be_truthy, "at #{a.start_time}"
+          end
+        end
+
+        it 'allows an event request in the second week that lasts until the end of the availability' do
+          a = bob_availabilities[1]
+          expect(bobs_schedule.allow? start_time: a.start_time, end_time: a.end_time).to be_truthy
+        end
+
+        it 'does not allow an event request that is beyond the availability' do
+          start_time = bob_availabilities.last.start_time + 1.day
+          end_time = bob_availabilities.last.start_time + 2.days - 1.hour
+          expect(bobs_schedule.allow? start_time: start_time, end_time: end_time).to be_falsey
+        end
+
+        it 'does not allow an event request that starts before the availability frequency' do
+          start_time = bob_availabilities.first.start_time - 1.hour
+          end_time = bob_availabilities.first.start_time
+          expect(bobs_schedule.allow? start_time: start_time, end_time: end_time).to be_falsey
+        end
+      end
+    end
+  end
+end

data/lib/availability.rb

@@ -0,0 +1,22 @@
+require 'active_support'
+require 'active_support/core_ext'
+require_relative "availability/version"
+require_relative 'availability/createable'
+require_relative 'availability/exclusion'
+require_relative 'availability/abstract_availability'
+require_relative 'availability/daily'
+require_relative 'availability/weekly'
+require_relative 'availability/monthly'
+require_relative 'availability/yearly'
+require_relative 'availability/once'
+require_relative 'availability/class_methods'
+require_relative 'availability/factory_methods'
+
+# shamelessly adapted from the following article
+# http://dmcca.be/2014/01/09/recurring-subscriptions-with-ruby-rspec-and-modular-arithmetic.html
+module Availability
+  class AbstractAvailability
+    extend FactoryMethods
+    extend ClassMethods
+  end
+end

data/lib/availability/abstract_availability.rb

@@ -0,0 +1,173 @@
+module Availability
+  class AbstractAvailability
+    private_class_method :new # :nodoc:
+  
+    attr_accessor :capacity, :duration, :frequency, :stops_by
+    attr_reader :exclusions, :interval, :residue, :start_time
+
+    #
+    # Required arguments:
+    #   interval: an integer that is the interval of occurrences per frequency
+    #   start_time: a Time, Date, or DateTime that indicates when the availability begins
+    #   duration: an integer indicating how long the availability lasts in seconds
+    #
+    # Optional arguements:
+    #   frequency: a symbol, one of [:once, :daily, :monthly, :yearly]; defaults to :daily
+    #   stops_by: specific date by which the availability ends
+    #
+    def initialize(capacity: Float::INFINITY, exclusions: nil, frequency: :daily, stops_by: nil, duration: , interval: , start_time: )
+      raise ArgumentError, "start_time is required" if start_time.nil?
+      raise ArgumentError, "duration is required" if duration.nil?
+      raise ArgumentError, "interval is required" if interval.nil?
+      @capacity = capacity
+      @duration = duration
+      @frequency = frequency
+      @interval = interval
+      @start_time = start_time.to_time
+      @stops_by = stops_by
+      self.exclusions = exclusions
+      compute_residue
+    end
+
+    #
+    # The copy constructor that Ruby calls when cloning or duping an object.
+    #
+    def initialize_copy(orig)
+      super
+      @exclusions = orig.exclusions
+      compute_residue
+    end
+
+    def beginning
+      self.class.beginning
+    end
+
+    def corresponds_to?(availability)
+      return unless occurs_at?(availability.start_time) && occurs_at?(availability.start_time + availability.duration)
+      if !!stops_by
+        that_last = availability.last_occurrence
+        !that_last.nil? &&
+          occurs_at?(that_last) &&
+          occurs_at?(that_last + availability.duration) &&
+          that_last.to_date <= self.last_occurrence.to_date
+      else
+        true
+      end
+    end
+
+    def end_time
+      start_time + duration
+    end
+
+    def exclusions=(exclusions)
+      @exclusions = Array(exclusions).flatten.compact + [
+        Exclusion.before_day(start_time),
+        Exclusion.before_time(start_time)
+      ]
+      if stops_by
+        @exclusions += [
+          Exclusion.after_day(stops_by),
+          Exclusion.after_time(stops_by)
+          # TODO: should previous be: Exclusion.after_time(start_time + duration)
+        ]
+      end
+      self
+    end
+
+    def interval
+      @interval
+    end
+
+    def interval=(interval)
+      @interval = interval
+      compute_residue
+      self
+    end
+
+    def interval_difference(first, second)
+      raise 'subclass responsibility'
+    end
+
+    def last_occurrence
+      return nil unless stops_by
+      unless @last_occurrence
+        next_date = move_by start_time, interval_difference(start_time, stops_by)
+        next_date = move_by next_date, -1 * interval while next_date >= stops_by && residue_for(next_date) != residue
+        @last_occurrence = next_occurrence next_date
+      end
+      @last_occurrence
+    end
+
+    def move_by(time, amount)
+      raise 'subclass responsibility'
+    end
+
+    def next_occurrence(from_date)
+      residue = @residue - residue_for(from_date)
+      date = move_by from_date, residue.modulo(interval)
+      time = Time.new(date.year, date.month, date.day, start_time.hour, start_time.min, start_time.sec)
+      if exclusions.any? {|rule| rule.violated_by? time}
+        if stops_by && time > stops_by
+          nil
+        else
+          next_occurrence(move_by time, 1)
+        end
+      else
+        time
+      end
+    end
+
+    #
+    # Returns an array of occurrences for n <= 1000, otherwise it returns a lazy enumerator
+    #
+    # n: Fixnum, how many occurrences to get
+    # from_date: a Date, Time, or DateTime from which to start calculating
+    #
+    def next_n_occurrences(n, from_date)
+      first_next_occurrence = next_occurrence(from_date)
+      blk = proc { |i| move_by first_next_occurrence, interval * i }
+      range = 0.upto(n - 1)
+      range = range.lazy if n > 1000
+      range.map &blk
+    end
+
+    def occurs_at?(time)
+      residue_for(time) == @residue && time_overlaps?(time, start_time, start_time + duration)
+    end
+
+    def residue_for(time)
+      raise 'subclass responsibility'
+    end
+
+    def start_time=(start_time)
+      @start_time = start_time
+      compute_residue
+      self
+    end
+
+    def time_overlaps?(time, start_time, end_time)
+      that_start = time.seconds_since_midnight.to_i
+      this_start = start_time.seconds_since_midnight.to_i
+      this_end   = end_time.seconds_since_midnight.to_i
+      (this_start..this_end).include?(that_start)
+    end
+
+    private
+
+    def compute_residue
+      @residue = residue_for(@start_time)
+    end
+
+    def hour_offset_from_midnight(time)
+      time.to_time.hour * 60 * 60
+    end
+
+    def minute_offset_from_midnight(time)
+      time.to_time.min * 60
+    end
+
+    def second_offset_from_midnight(time)
+      time.to_time.sec
+    end
+  end
+end

data/lib/availability/class_methods.rb

@@ -0,0 +1,20 @@
+module Availability
+  module ClassMethods
+    def availability?(thing)
+      AbstractAvailability === thing
+    end
+
+    def beginning
+      @@beginning ||= Date.new(1970, 1, 1)
+    end
+
+    def default_args
+      {}
+    end
+
+    def subclass_for(frequency)
+      Availability.const_get frequency.to_s.capitalize rescue nil
+    end
+  end
+  extend ClassMethods
+end

data/lib/availability/createable.rb

@@ -0,0 +1,12 @@
+module Availability
+  module Createable
+    def self.extended(base)
+      base.public_class_method :new
+    end
+
+    def create(**args)
+      frequency = name.split(':').last.downcase.to_sym
+      super **args.merge(frequency: frequency, event_class: self)
+    end
+  end
+end

data/lib/availability/daily.rb

@@ -0,0 +1,20 @@
+require_relative 'abstract_availability'
+
+module Availability
+  class Daily < AbstractAvailability
+    extend Createable
+
+    def interval_difference(this, that)
+      first, second = [this.to_date, that.to_date].sort
+      (second - first).to_i
+    end
+
+    def move_by(time, amount)
+      time + amount.days
+    end
+
+    def residue_for(time)
+      interval_difference(time, beginning).modulo(@interval)
+    end
+  end
+end

data/lib/availability/exclusion.rb

@@ -0,0 +1,91 @@
+module Availability
+  class Exclusion
+    private_class_method :new # :nodoc:
+
+    def self.after_day(date)
+      raise ArgumentError, "invalid date" if date.nil?
+      new Rule::AfterDate.new(date.to_date)
+    end
+
+    def self.after_time(time)
+      raise ArgumentError, "invalid time" if time.nil?
+      new Rule::AfterTime.new(time.to_time)
+    end
+
+    def self.all_day(date)
+      raise ArgumentError, "invalid date" if date.nil?
+      new Rule::OnDate.new(date.to_date)
+    end
+
+    def self.before_day(date)
+      raise ArgumentError, "invalid date" if date.nil?
+      new Rule::BeforeDate.new(date.to_date)
+    end
+
+    def self.before_time(time)
+      raise ArgumentError, "invalid time" if time.nil?
+      new Rule::BeforeTime.new(time.to_time)
+    end
+
+    def initialize(rule)
+      @rule = rule
+    end
+
+    def violated_by?(time)
+      @rule.violated_by? time
+    end
+
+    private
+    module Rule
+      class AfterDate
+        def initialize(date)
+          @date = date
+        end
+
+        def violated_by?(time)
+          time.to_date > @date
+        end
+      end
+
+      class AfterTime
+        def initialize(date_or_time)
+          @compare_to = date_or_time.to_time
+        end
+
+        def violated_by?(time)
+          time.to_time.seconds_since_midnight > @compare_to.to_time.seconds_since_midnight
+        end
+      end
+
+      class BeforeDate
+        def initialize(date)
+          @date = date
+        end
+
+        def violated_by?(time)
+          time.to_date < @date
+        end
+      end
+
+      class BeforeTime
+        def initialize(date_or_time)
+          @compare_to = date_or_time.to_time
+        end
+
+        def violated_by?(time)
+          time.to_time.seconds_since_midnight < @compare_to.to_time.seconds_since_midnight
+        end
+      end
+
+      class OnDate
+        def initialize(date)
+          @date = date
+        end
+
+        def violated_by?(time)
+          time.to_date == @date
+        end
+      end
+    end
+  end
+end

data/lib/availability/factory_methods.rb

@@ -0,0 +1,37 @@
+module Availability
+  module FactoryMethods
+    def create(**args)
+      cls = args.delete(:event_class) || Availability::subclass_for(args[:frequency] ||= :daily)
+      raise ArgumentError, "undefined frequency" if cls.nil?
+      cls.send :new, **args
+    end
+
+    def once(**args)
+      Once.create **args
+    end
+
+    %w{day week month year}.each do |suffix|
+      frequency = suffix == 'day' ? :daily : :"#{suffix}ly"
+      cls = Availability::subclass_for(frequency)
+
+      define_method frequency do |**args|
+        args[:interval] ||= 1 unless args[:interval]
+        cls.create **args
+      end
+
+      {
+        :"every_#{suffix}"        => 1,
+        :"every_other_#{suffix}"  => 2,
+        :"every_two_#{suffix}s"   => 2,
+        :"every_three_#{suffix}s" => 3,
+        :"every_four_#{suffix}s"  => 4,
+        :"every_five_#{suffix}s"  => 5
+      }.each do |method_name, interval|
+        define_method method_name do |**args|
+          cls.send(frequency, **args, interval: interval)
+        end
+      end
+    end
+  end
+  extend FactoryMethods
+end

data/lib/availability/monthly.rb

@@ -0,0 +1,22 @@
+require_relative 'abstract_availability'
+
+module Availability
+  class Monthly < AbstractAvailability
+    extend Createable
+
+    def interval_difference(first, second)
+      first_date, second_date = [first.to_date, second.to_date].sort
+      (second_date.year - first_date.year) * 12 + (second_date.month - first_date.month)
+    end
+
+    def move_by(time, amount)
+      time + amount.months
+    end
+
+    def residue_for(time)
+      # date = time.to_date
+      # ((date.year - beginning.year) * 12 + (date.month - beginning.month)).modulo(@interval)
+      interval_difference(beginning, time).modulo(@interval)
+    end
+  end
+end

data/lib/availability/once.rb

@@ -0,0 +1,29 @@
+require_relative 'abstract_availability'
+
+module Availability
+  class Once < AbstractAvailability
+    extend Createable
+
+    def initialize(**args)
+      raise ArgumentError, "start_time is required" unless args.has_key?(:start_time)
+      raise ArgumentError, "duration is required" unless args.has_key?(:duration)
+      super **args, frequency: :once, interval: 0, stops_by: args[:start_time] + args[:duration]
+    end
+
+    def interval_difference(this, that)
+      raise NotImplementedError.new('not supported')
+    end
+
+    def move_by(time, amount)
+      time + amount.days
+    end
+
+    def last_occurrence
+      start_time
+    end
+
+    def residue_for(time)
+      0
+    end
+  end
+end

data/lib/availability/version.rb

@@ -0,0 +1,3 @@
+module Availability
+  VERSION = "0.0.1"
+end

data/lib/availability/weekly.rb

@@ -0,0 +1,24 @@
+require_relative 'abstract_availability'
+
+module Availability
+  class Weekly < AbstractAvailability
+    extend Createable
+
+    def interval
+      @interval * 7
+    end
+
+    def interval_difference(first, second)
+      first_date, second_date = [first.to_date, second.to_date].sort
+      (second_date - first_date).to_i #/ interval
+    end
+
+    def move_by(time, amount)
+      time + amount.days
+    end
+
+    def residue_for(time)
+      (time.to_date - beginning.to_date).to_i.modulo(interval)
+    end
+  end
+end

data/lib/availability/yearly.rb

@@ -0,0 +1,22 @@
+require_relative 'abstract_availability'
+
+module Availability
+  class Yearly < AbstractAvailability
+    extend Createable
+
+    def interval_difference(first, second)
+      first_date, second_date = [first.to_date, second.to_date].sort
+      second_date.year - first_date.year
+    end
+
+    def move_by(time, amount)
+      time + amount.years
+    end
+
+    def residue_for(time)
+      # date = time.to_date
+      # (date.year - beginning.year).modulo(@interval)
+      interval_difference(beginning, time).modulo(@interval)
+    end
+  end
+end

metadata

@@ -0,0 +1,143 @@
+--- !ruby/object:Gem::Specification
+name: availability
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Jason Rogers
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-05-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-its
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Use modular arithmetic and residue classes to calculate schedule availability
+  for dates (times handled separately).
+email:
+- jacaetevha@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".ruby-gemset"
+- ".ruby-version"
+- ".travis.yml"
+- CREDITS
+- Gemfile
+- README.md
+- Rakefile
+- UNLICENSE
+- WAIVER
+- availability.gemspec
+- bin/console
+- bin/setup
+- examples/scheduler.rb
+- examples/scheduler_spec.rb
+- lib/availability.rb
+- lib/availability/abstract_availability.rb
+- lib/availability/class_methods.rb
+- lib/availability/createable.rb
+- lib/availability/daily.rb
+- lib/availability/exclusion.rb
+- lib/availability/factory_methods.rb
+- lib/availability/monthly.rb
+- lib/availability/once.rb
+- lib/availability/version.rb
+- lib/availability/weekly.rb
+- lib/availability/yearly.rb
+homepage: https://github.com/upper-hand/availability
+licenses:
+- Unlicense
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: Calculating schedule availability
+test_files: []