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.

Features

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.

Requirements

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'

TL;DR

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.

To use

Put this in your Gemfile

gem 'datetime_helper'

Basic Zulu Time checking

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

Using the be_zulu_time matcher in your RSpec tests

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.

ISO Times and Dates

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

• be_an_iso_formatted_time, and
• be_an_iso_formatted_date

Validating ActiveModel fields to ensure they hold UTC+0 datetime data

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.

Enforcing ActiveModel::Serializer Zulu Time and iso8601 Date String Formats

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.

To build

bundle install
gem build datetime_helper.gemspec

To test

bundle install
rake

The tests offer insight into how to use these utilities.

To contribute

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

License

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

Version history

Version	Comments
0.0.1	First draft — only the rspec matcher
0.0.2	Added the ActiveModel validator
0.0.3	Added the ActiveModel::Serializer helper
1.0.0	Cleaned up for first official release
1.0.1	Enhanced matchers, and validator
1.0.2	Add iso8601 date format for serializers
1.0.3	Change enforce_iso8601_date to work with
	date-time objects
1.0.4	Anchor strings in RSpec matchers
1.0.5	Add aliasing to serializer formatting