Periodoxical

"Up, and down, and in the end, it's only round and round and round..." - Pink Floyd, "Us and Them"

Generate periodic datetime blocks based on provided rules/conditions. Great for (but not limited to) calendar and scheduling applications. See Usage for detailed examples.

Installation

Add this line to your application's Gemfile:

gem 'periodoxical'

And then execute:

$ bundle

Or install it yourself as:

$ gem install periodoxical

Usage

Basic Example

As a Ruby dev, I want to generate all the datetime blocks of 9:00AM - 10:30AM for all days from May 23, 2024 to May 26, 2024 inclusive.

Periodoxical.generate(
  time_zone: 'America/Los_Angeles',
  time_blocks: [
    {
      start_time: '9:00AM',
      end_time: '10:30AM'
    },
  ],
  starting_from: '2024-05-23',
  ending_at: '2024-05-26',
)
#=> 
[
    {
     start: #<DateTime: 2024-05-23T09:00:00-0700>,
     end: #<DateTime: 2024-05-23T10:30:00-0700>,
    },
    {
     start: #<DateTime: 2024-05-24T09:00:00-0700>,
     end: #<DateTime: 2024-05-24T10:30:00-0700>,
    },
    {
     start: #<DateTime: 2024-05-25T09:00:00-0700>,
     end: #<DateTime: 2024-05-25T10:30:00-0700>,
    },
    {
     start: #<DateTime: 2024-05-26T09:00:00-0700>,
     end: #<DateTime: 2024-05-26T10:30:00-0700>,
    }
]

The starting_from and ending_at params can also accept datetimes in ISO 8601 format. This example generate all the datetime blocks of 9:00AM - 10:30AM but starting from May 23, 2024 at 9:30AM.

Periodoxical.generate(
  time_zone: 'America/Los_Angeles',
  time_blocks: [
    {
      start_time: '9:00AM',
      end_time: '10:30AM'
    },
  ],
  starting_from: '2024-05-23T09:30:00-07:00', # can be string in iso8601 format
  ending_at: DateTime.parse('2024-05-26T17:00:00-07:00'), # or an instance of DateTime
)
#=> [
    # 2024-05-23 was skipped because the 9AM time block was before
    # the `starting_from` of '2024-05-23T09:30:00-07:00'
    {
     start_time: #<DateTime: 2024-05-24T09:00:00-0700>,
     end_time: #<DateTime: 2024-05-24T10:30:00-0700>,
    },
    ...
]

Specify days of the week

As a Ruby dev, I want to generate all the datetime blocks of 9:00AM - 10:30AM and 2:00PM - 2:30PM, on Mondays, Wednesdays, and Thursdays, between the dates of May 23, 2024 and June 12, 2024, inclusive. I can do this using the days_of_week parameter. This can be represented visually as:

(image courtesy of Cal.com)

Periodoxical.generate(
  time_zone: 'America/Los_Angeles',
  days_of_week: %w[mon wed thu],
  time_blocks: [
    {
      start_time: '9:00AM',
      end_time: '10:30AM'
    },
    {
      start_time: '2:00PM',
      end_time: '2:30PM'
    }
  ],
  starting_from: '2024-05-23',
  ending_at: '2024-06-12',
)
# returns an array of hashes, each with :start and :end keys
#=> 
[
  {
    start: #<DateTime: 2024-05-23T09:00:00-0700">,
    end:   #<DateTime: 2024-05-23T22:30:00-0700">,
  },
  {
    start: #<DateTime: 2024-05-23T14:00:00-0700>,
    end:   #<DateTime: 2024-05-23T14:30:00-0700>,
  },
 {
    start: #<DateTime: 2024-05-27T09:00:00-0700>,
    end:   #<DateTime: 2024-05-27T22:30:00-0700>
 },
 ...
 {
    start: #<DateTime: 2024-06-12T14:00:00-0700>,
    end:   #<DateTime: 2024-06-12T14:30:00-0700>
 }
]

Example using the `limit` parameter.

As a ruby dev, I want to generate the next 3 datetime blocks of 9:00AM - 10:30AM and 2:00PM - 2:30PM on Sundays, after May 23, 2024. I can do this using the limit parameter, instead of ending_at.

Periodoxical.generate(
  time_zone: 'America/Los_Angeles',
  days_of_week: %w[sun],
  time_blocks: [
    {
      start_time: '9:00AM',
      end_time: '10:30PM'
    },
    {
      start_time: '2:00PM',
      end_time: '2:30PM'
    }
  ],
  starting_from: Date.parse('2024-05-23'), # Can also pass in `Date` object.
  limit: 3
)
# =>
[
  {
    start: #<DateTime: 2024-05-26T09:00:00-0700>,
    end:   #<DateTime: 2024-05-26T22:30:00-0700>,
  },
  {
    start: #<DateTime: 2024-05-26T14:00:00-0700>,
    end:   #<DateTime: 2024-05-26T14:30:00-0700>,
  },
  {
    start: #<DateTime: 2024-06-02T09:00:00-0700>,
    end:   #<DateTime: 2024-06-02T22:30:00-0700>,
  },
]

Time blocks that vary between days-of-the-week

As a ruby dev, I want to generate all the timeblocks between May 23, 2024 and June 12, 2024 where the time should be 8AM-9AM on Mondays, but 10:45AM-12:00PM and 2:00PM-4:00PM on Wednesdays, and 2:30PM-4:15PM on Thursdays. I can do this using the day_of_week_time_blocks parameter.

(image courtesy of Cal.com)

Periodoxical.generate(
  time_zone: 'America/Los_Angeles',
  starting_from: Date.parse('2024-05-23'), # can also pass in Date objects
  ending_at: Date.parse('2024-06-12'), # can also pass in Date objects,
  day_of_week_time_blocks: {
    mon: [
      { start_time: '8:00AM', end_time: '9:00AM' },
    ],
    wed: [
      { start_time: '10:45AM', end_time: '12:00PM' },
      { start_time: '2:00PM', end_time: '4:00PM' },
    ],
    thu: [
      { start_time: '2:30PM', end_time: '4:15PM' }
    ],
  }
)

Specifying time blocks using rules for month(s) and/or day-of-month.

As a Ruby dev, I want to generate the next 3 timeblocks for 8AM - 9AM for the 5th and 10th day of every month starting from June. I can do this using the days_of_month parameter.

Periodoxical.generate(
  time_zone: 'America/Los_Angeles',
  starting_from: '2024-06-01',
  limit: 3,
  days_of_month: [5, 10],
  time_blocks: [
    { start_time: '8:00AM', end_time: '9:00AM' },
  ],
)
#=>
[
    {
      start: #<DateTime: 2024-06-05T08:00:00-0700>,
      end: #<DateTime: 2024-06-05T09:00:00-0700>,
    },
    {
      start: #<DateTime: 2024-06-10T08:00:00-0700>,
      end: #<DateTime: 2024-06-10T09:00:00-0700>,
    },
    {
      start: #<DateTime: 2024-07-05T08:00:00-0700>,
      end: #<DateTime: 2024-07-05T09:00:00-0700>,
    },
]

Specify nth day-of-week in month (ie. first Monday of the Month, second Tuesday of the Month, last Friday of Month)

As a Ruby dev, I want to generate timeblocks for 8AM - 9AM on the first and second Mondays and last Fridays of every month starting in June 2024. I can do this with the nth_day_of_week_in_month param.

Periodoxical.generate(
  time_zone: 'America/Los_Angeles',
  starting_from: '2024-06-01',
  limit: 5,
  nth_day_of_week_in_month: {
    mon: [1, 2], # valid values: -1,1,2,3,4,5
    fri: [-1], # Use -1 to specify the last Friday of the month.
  },
  time_blocks: [
    { start_time: '8:00AM', end_time: '9:00AM' },
  ],
)
# =>
[
  {
    start: #<DateTime: 2024-06-03T08:00:00-0700>, # First Monday of June 2024
    end: #<DateTime: 2024-06-03T09:00:00-0700>,
  },
  {
    start: #<DateTime: 2024-06-10T08:00:00-0700>, # second Monday of June 2024
    end: #<DateTime: 2024-06-10T09:00:00-0700>,
  },
  {
    start: #<DateTime: 2024-06-28 08:00:00 -0700>, # last Friday of June 2024
    end: #<DateTime: 2024-06-28 09:00:00 -0700>,
  },
  {
    start: #<DateTime: 2024-07-01 08:00:00 -0700>, # First Monday of July 2024
    end: #<DateTime: 2024-07-01 09:00:00 -0700>,
  },
  {
    start: #<DateTime: 2024-07-08 08:00:00 -0700>, # Second Monday of July 2024
    end: #<DateTime: 2024-07-08 09:00:00 -0700>,
  },
]

Exclude time blocks using the `exclusion_dates` and `exclusion_times` parameters

As a Ruby dev, I want to generate timeblocks for 8AM - 9AM on Mondays, except for the Monday of June 10, 2024. I can do this using the exlcusion_dates parameter.

Periodoxical.generate(
  time_zone: 'America/Los_Angeles',
  starting_from: '2024-06-03',
  limit: 4,
  exclusion_dates: %w(2024-06-10),
  day_of_week_time_blocks: {
    mon: [
      { start_time: '8:00AM', end_time: '9:00AM' },
    ],
  }
)
# Returns all Monday 8AM - 9AM blocks except for the Monday on June 10, 2024
# => 
[
    {
      start: #<DateTime: 2024-06-03T08:00:00-0700>,
      end: #<DateTime: 2024-06-03T09:00:00-0700>,
    }
    {
      start: #<DateTime: 2024-06-17T08:00:00-0700>,
      end: #<DateTime: 2024-06-17T09:00:00-0700>,
    }
    {
      start: #<DateTime: 2024-06-24T08:00:00-0700>,
      end: #<DateTime: 2024-06-24T09:00:00-0700>,
    }
    {
      start: #<DateTime: 2024-07-01T08:00:00-0700>,
      end: #<DateTime: 2024-07-01T09:00:00-0700>,
    }
]

As a Ruby dev, I want to generate timeblocks for 8AM - 9AM, and 10AM - 11AM on Mondays, except for those that conflict (meaning overlap) with the time block of 10:30AM - 11:30AM on the Monday of June 10, 2024. I can skip the conflicting time blocks by using the exclusion_times parameter.

Periodoxical.generate(
  time_zone: 'America/Los_Angeles',
  starting_from: '2024-06-03',
  limit: 4,
  days_of_week: %(mon),
  time_blocks: [
      { start_time: '8:00AM', end_time: '9:00AM' },
      { start_time: '10:00AM', end_time: '11:00AM' },
  ],
  exclusion_times: [
    {
        start: '2024-06-10T10:30:00-07:00',
        end: '2024-06-10T11:30:00-07:00',
    }
  ],
)
# =>
[
    {
      start: #<DateTime 2024-06-03T08:00:00-0700>,
      end: #<DateTime 2024-06-03T09:00:00-0700>,
    },
    {
      start: #<DateTime 2024-06-03T10:00:00-0700>,
      end: #<DateTime 2024-06-03T11:00:00-0700>,
    },
    {
      start: #<DateTime 2024-06-10T08:00:00-0700>,
      end: #<DateTime 2024-06-10T09:00:00-0700>,
    },
    # The June 10 10AM - 11AM was skipped because it overlapped with the June 10 10:30AM - 11:30AM exclusion time.
    {
      start: #<DateTime 2024-06-17T08:00:00-0700>,
      end: #<DateTime 2024-06-17T09:00:00-0700>,
    },
    {
      start: #<DateTime 2024-06-17T10:00:00-0700>,
      end: #<DateTime 2024-06-17T11:00:00-0700>,
    },
    {
      start: #<DateTime 2024-06-24T08:00:00-0700>,
      end: #<DateTime 2024-06-24T09:00:00-0700>,
    },
]

Every-other-nth day-of-week rules (ie. every other Tuesday, every 3rd Wednesday, every 10th Friday)

As a Ruby dev, I want to generate timeblocks for 9AM- 10AM on every Monday, but every other Tuesday, and every other 3rd Wednesday. I can do this using the days_of_week parameter with the every and every_other_nth keys to specify the every-other-nth-rules.

This can be visualized as:

(image courtesy of calendar.google.com)

Periodoxical.generate(
  time_zone: 'America/Los_Angeles',
  starting_from: '2024-12-30',
  days_of_week: {
    mon: { every: true }, # every Monday (no skipping)
    tue: { every_other_nth: 2 }, # every other Tuesday starting at first Tuesday from `starting_from` date
    wed: { every_other_nth: 3 }, # every 3rd Wednesday starting at first Wednesday from `starting_from` date
  },
  limit: 10,
  time_blocks: [
    { start_time: '9:00AM', end_time: '10:00AM' },
  ],
)
#=> 
[
    {
       start: #<DateTime: 2024-12-30T09:00:00-0800>,
       end: #<DateTime: 2024-12-30T10:00:00-0800>,
    },
    {
       start: #<DateTime: 2024-12-31T09:00:00-0800>,
       end: #<DateTime: 2024-12-31T10:00:00-0800>,
    },
    {
       start: #<DateTime: 2025-01-01T09:00:00-0800>,
       end: #<DateTime: 2025-01-01T10:00:00-0800>,
    },
    {
       start: #<DateTime: 2025-01-06T09:00:00-0800>,
       end: #<DateTime: 2025-01-06T10:00:00-0800>,
    },
    {
       start: #<DateTime: 2025-01-13T09:00:00-0800>,
       end: #<DateTime: 2025-01-13T10:00:00-0800>,
    },
    {
       start: #<DateTime: 2025-01-14T09:00:00-0800>,
       end: #<DateTime: 2025-01-14T10:00:00-0800>,
    },
    {
       start: #<DateTime: 2025-01-20T09:00:00-0800>,
       end: #<DateTime: 2025-01-20T10:00:00-0800>,
    },
    {
       start: #<DateTime: 2025-01-22T09:00:00-0800>,
       end: #<DateTime: 2025-01-22T10:00:00-0800>,
    },
    {
       start: #<DateTime: 2025-01-27T09:00:00-0800>,
       end: #<DateTime: 2025-01-27T10:00:00-0800>,
    },
    {
       start: #<DateTime: 2025-01-28T09:00:00-0800>,
       end: #<DateTime: 2025-01-28T10:00:00-0800>,
    }
]

Use the `duration` key, to automatically partition the provided `time_blocks` into smaller chunks to the given duration.

As a Ruby dev, I want to generate 30 minute time blocks between 9:00AM - 1:00PM, and 2:00PM - 5:00PM. Because it is too tedious to generate all 14 of these time blocks, I prefer to pass in the duration key and have periodoxical generate them for me.

N.B. If you provide a duration that conflicts with your time blocks, periodoxical will not return any time blocks. For example, if you specify 9:00AM - 10:00AM but set your duration as 90 minutes, no time blocks are generated since we can't fit 90 minutes into an hour!

Periodoxical.generate(
  time_zone: 'America/Los_Angeles',
  time_blocks: [
    {
      start_time: '9:00AM',
      end_time: '1:00PM'
    },
    {
      start_time: '2:00PM',
      end_time: '5:00PM'
    },
  ],
  duration: 30, #(minutes)
  starting_from: '2024-05-23',
  ending_at: '2024-05-26',
)
# => [
    {
      start: #<DateTime: 2024-05-23T09:00:00--0700>
      end: #<DateTime: 2024-05-23T09:30:00--0700>
    },
    {
      start: #<DateTime: 2024-05-23T09:30:00--0700>
      end: #<DateTime: 2024-05-23T10:00:00--0700>
    },
    {
      start: #<DateTime: 2024-05-23T10:00:00--0700>
      end: #<DateTime: 2024-05-23T10:30:00--0700>
    },
    {
      start: #<DateTime: 2024-05-23T10:30:00--0700>
      end: #<DateTime: 2024-05-23T11:00:00--0700>
    }
]

Having Some Fun

Generate all the Friday the 13ths ever since May 1980 (when the first Friday the 13th film was released).

Periodoxical.generate(
  time_zone: 'America/Los_Angeles',
  starting_from: '1980-05-01',
  days_of_week: %w(fri),
  days_of_month: [13],
  limit: 100,
  time_blocks: [
    { start_time: '11:00PM', end_time: '12:00AM' },
  ],
)
# =>
[
    {
      start: #<DateTime: 1980-06-13T23:00:00-0700>,
      end: #<DateTime: 1980-06-13T00:00:00-0700>,
    },
    {
      start: #<DateTime: 1981-02-13T23:00:00-0800>,
      end: #<DateTime: 1981-02-13T00:00:00-0800>,
    },
    {
      start: #<DateTime: 1981-03-13T23:00:00-0800>,
      end: #<DateTime: 1981-03-13T00:00:00-0800>,
    },
    {
      start: #<DateTime: 1981-11-13T23:00:00-0800>,
      end: #<DateTime: 1981-11-13T00:00:00-0800>,
    }
    ...
]

Generate the next 10 Thanksgivings from now on (Thanksgivings is defined as the 4th Thursday in November).

Periodoxical.generate(
  time_zone: 'America/Los_Angeles',
  starting_from: '2024-05-01',
  months: [11],
  nth_day_of_week_in_month: {
    thu: [4],
  },
  limit: 10,
  time_blocks: [
    { start_time: '5:00PM', end_time: '6:00PM' },
  ],
)
#=>
[
    {
      start: #<DateTime: 2024-11-28T17:00:00-0800>,
      end: #<DateTime: 2024-11-28T18:00:00-0800>,
    },
    {
      start: #<DateTime: 2025-11-27T17:00:00-0800>,
      end: #<DateTime: 2025-11-27T18:00:00-0800>,
    },
    {
      start: #<DateTime: 2026-11-26T17:00:00-0800>,
      end: #<DateTime: 2026-11-26T18:00:00-0800>,
    },
    {
      start: #<DateTime: 2027-11-25T17:00:00-0800>,
      end: #<DateTime: 2027-11-25T18:00:00-0800>,
    },
    {
      start: #<DateTime: 2028-11-23T17:00:00-0800>,
      end: #<DateTime: 2028-11-23T18:00:00-0800>,
    },
    ...
]

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/periodoxical. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Periodoxical project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

periodoxical

Development

Runtime

Periodoxical

Installation

Usage

Basic Example

Specify days of the week

Example using the limit parameter.

Time blocks that vary between days-of-the-week

Specifying time blocks using rules for month(s) and/or day-of-month.

Specify nth day-of-week in month (ie. first Monday of the Month, second Tuesday of the Month, last Friday of Month)

Exclude time blocks using the exclusion_dates and exclusion_times parameters

Every-other-nth day-of-week rules (ie. every other Tuesday, every 3rd Wednesday, every 10th Friday)

Use the duration key, to automatically partition the provided time_blocks into smaller chunks to the given duration.

Having Some Fun

Development

Contributing

License

Code of Conduct

Example using the `limit` parameter.

Exclude time blocks using the `exclusion_dates` and `exclusion_times` parameters

Use the `duration` key, to automatically partition the provided `time_blocks` into smaller chunks to the given duration.