The Datetime Helper

A collection of useful utilities for projects that have to deal with dates, times, and time zones, with particular utility for Rails projects that enforce the use of Zulu Time.

1. A base method called is_zulu_time?,
2. rspec matchers be_zulu_time, be_an_iso_formatted_date, and be_an_iso_formatted_time
3. An ActiveModel validator called zulu_time, and
4. ActiveModel::Serializer helper methods called enforce_zulu_time and enforce_iso8601_date that allow formatting and aliasing.

Each feature can be required individually so you can use the rspec matcher, ActiveModel validator, or ActiveModel::Serializer helper in isolation.

1. Ruby, Bundler, etc. The usual suspects. (Tested against Ruby 2.0.0 and up)
2. rspec if you require 'datetime_helper/rspec'
3. active_model if you require 'datetime_helper/active_model'
4. active_model_serializer if you require 'datetime_helper/active_model_serialiser'

Zulu Time is an ISO 8601 formatted string representing a datetime but in the time zone UTC+0. This makes it trivial for client applications to display dates and times correctly in their local, or other nominated time zones.

Enforcing Zulu Time across a range of projects requires a common approach to validating incoming strings, representing the data internally, serialising the data back out into strings, and testing date and time fields.

The Datetime Helper was developed to provide that common approach, and it is available as an open source project because we believe it is generically useful.

Put this in your Gemfile

gem 'datetime_helper'

You can also use this to test that a DateTime, or Time, are at UTC+0, or that a String is formatted in correct Zulu Time format.

DatetimeHelper.is_zulu_time? something

Put this in your spec_helper.rb or equivalent

require 'datetime_helper/rspec'

RSpec.configure do |config|
  config.include DatetimeHelper::Matchers
end

And put this in your rspec tests.

it {expect(subject[:deleted_at]).to be_zulu_time}

This can be used to expect that a DateTime, or Time, are at UTC+0, or that a String is formatted in Zulu Time.

Similarly to the above you can also test Time and Date strings with

• be_an_iso_formatted_time, and
• be_an_iso_formatted_date

First be sure you require 'datetime_helper/active_model'

Then your model class can add:

include DatetimeHelper::Validators

validates :updated_at, zulu_time: true

This will verify that a Time is supplied at UTC+0, or that a DateTime has .zone == "+00:00", or that a String is in Zulu Time format.

First be sure you require 'datetime_helper/active_model_serialiser'

Then you can put this in your serialisers:

extend DatetimeHelper::Serialisers

enforce_zulu_time :updated_at
enforce_iso8601_date :enable_date
enforce_zulu_time :published_at, :published_date

The last case will also alias the api attribute published_at to the table attribute published_date.

or if you have a bunch of 'em

extend DatetimeHelper::Serialisers

%w(updated_at deleted_at).each { |attribute| enforce_zulu_time attribute }
%w(date enable_date).each { |attribute| enforce_iso8601_date attribute }

This will ensure that the serialised output is a proper Zulu time formatted string and iso8601 formatted date string.

bundle install
gem build datetime_helper.gemspec

bundle install
rake

The tests offer insight into how to use these utilities.

Contributions are encouraged. See the contribution instructions for the preferred contribution process.

The Datetime Helper is © 2015 Westfield Labs and is available for use under the Apache 2.0 license.