working_hours Ruby Gem

If you prefer not to modify core Ruby classes, you can use the WorkingHours::Duration class and the WorkingHours module directly. This is safer for libraries or projects that want to avoid side effects.

require 'working_hours/module'

# Use Duration objects
WorkingHours::Duration.new(1, :days).from_now
WorkingHours::Duration.new(8, :days).since(Date.new(2014, 12, 31))
WorkingHours::Duration.new(4, :hours).until(Time.utc(2014, 8, 4, 8, 32))

# Use WorkingHours module methods
WorkingHours.working_days_between(friday, monday)
WorkingHours.working_time_between(from, to)
WorkingHours.working_day?(Date.new(2014, 12, 28))
WorkingHours.in_working_hours?(Time.utc(2014, 8, 4, 7, 16))

To use working_hours in your Ruby project, add it to your Gemfile:

gem 'working_hours'

By default, working_hours extends core Ruby classes like Numeric, Date, and Time to allow for intuitive syntax. This is the easiest way to perform time calculations using natural language-like methods.

require 'working_hours'

# Move forward/backward
1.working.day.from_now
2.working.hours.ago
15.working.minutes.from_now

# Start from custom Date or Time
Date.new(2014, 12, 31) + 8.working.days
Time.utc(2014, 8, 4, 8, 32) - 4.working.hours

# Compute working days between two dates
friday.working_days_until(monday)

# Compute working duration (in seconds) between two times
from.working_time_until(to)

# Check if a day or time is a working one
Date.new(2014, 12, 28).working_day?
Time.utc(2014, 8, 4, 7, 16).in_working_hours?

The configuration defines working periods for each day, the time zone, and holidays. It is thread-safe. You can set it globally (e.g., in a Rails initializer) or temporarily using a block.

# Global configuration
WorkingHours::Config.working_hours = {
  :tue => {'09:00' => '12:00', '13:00' => '17:00'},
  :wed => {'09:00' => '12:00', '13:00' => '17:00'},
  :thu => {'09:00' => '12:00', '13:00' => '17:00'},
  :fri => {'09:00' => '12:00', '13:00' => '17:05:30'},
  :sat => {'19:00' => '24:00'}
}

# Set timezone (defaults to UTC)
WorkingHours::Config.time_zone = 'Paris'

# Set holidays
WorkingHours::Config.holidays = [Date.new(2014, 12, 31)]

# Temporary configuration for a block
WorkingHours::Config.with_config(working_hours: {mon:{'09:00' => '18:00'}}, holidays: [], time_zone: 'Paris') do
  # Intense calculations with this specific config
end

To handle special working hours for specific calendar days (like Christmas Eve), use holiday_hours. If any hours are set for a day in holiday_hours, the standard working_hours for that day are ignored.

# Configure specific hours for a specific date
WorkingHours::Config.holiday_hours = {Date.new(2020, 12, 24) => {'09:00' => '12:00', '13:00' => '15:00'}}

To use the working_hours functionality in your Ruby project, require the main entrypoint. This automatically loads the core module and core extensions for Integer, Date, and Time.

require 'working_hours'

If the configuration is invalid, the gem raises WorkingHours::InvalidConfiguration. You can inspect the error_code to implement custom error handling.

rescue WorkingHours::InvalidConfiguration => e
  if e.error_code == :empty
    raise StandardError.new "Config is required"
  end
  raise e
end

If you want to use the computation methods (without monkey patching core classes) inside your own class, include WorkingHours.

require 'working_hours/module'

class Order
  include WorkingHours

  def shipping_date_estimate
    # Uses Duration and working_days_since/until logic
    Duration.new(2, :days).since(payment_received_at)
  end

  def payment_delay
    # Uses working_days_between logic
    working_days_between(created_at, payment_received_at)
  end
end

The WorkingHours module provides methods to jump to specific points in the working schedule based on a given time.

# Advance to the next available working moment
WorkingHours.next_working_time(sunday)

# Advance to the next closing time of the day
WorkingHours.advance_to_closing_time(time)

# Advance to the next available working moment (alternative syntax)
WorkingHours.advance_to_working_time(time)

# Return to the previous working moment
WorkingHours.return_to_working_time(time)