by_star

ByStar

ByStar (by_*) allows you easily and reliably query ActiveRecord and Mongoid objects based on time.

Examples

Post.by_year(2013)                           # all posts in 2013
Post.before(Date.today)                      # all posts for before today
Post.yesterday                               # all posts for yesterday
Post.between_times(Time.zone.now - 3.hours,  # all posts in last 3 hours
                   Time.zone.now)
@post.next                                   # next post after a given post

Installation

Install this gem by adding this to your Gemfile:

gem 'by_star', git: 'https://github.com/radar/by_star'

Then run bundle install

If you are using ActiveRecord, you're done!

Mongoid users, please include the Mongoid::ByStar module for each model you wish to use the functionality. This is the convention among Mongoid plugins.

class MyModel
  include Mongoid::Document
  include Mongoid::ByStar

Finder Methods

Base Scopes

ByStar adds the following finder scopes (class methods) to your model to query time ranges. These accept a Date, Time, or DateTime object as an argument, which defaults to Time.zone.now if not specified:

between_times and between_dates supports alternate argument forms:

• between_times(Range)
• between_times(Array)
• between_times(start_time, nil) - same as after(start_time)
• between_times(nil, end_time) - same as before(end_time)

Time Range Scopes

ByStar adds additional shortcut scopes based on commonly used time ranges. See sections below for detailed argument usage of each:

Relative Scopes

ByStar also adds scopes which are relative to the current time. Note the past_* and next_* methods represent a time distance from current time (Time.zone.now), and do not strictly end/begin evenly on a calendar week/month/year (unlike by_* methods which do.)

Superlative Finders

Find the oldest or newest records. Returns an object instance (not a relation):

• newest
• oldest

Instance Methods

In addition, ByStar adds instance methods to return the next / previous record in the timewise sequence. Returns an object instance (not a relation):

• object.next
• object.previous

Kernel Extensions

ByStar extends the kernel Date, Time, and DateTime objects with the following instance methods, which mirror the ActiveSupport methods beginning_of_day, end_of_week, etc:

• beginning_of_weekend
• end_of_weekend
• beginning_of_fortnight
• end_of_fortnight
• beginning_of_calendar_month
• end_of_calendar_month

Lastly, ByStar aliases Rails 3 Date#to_time_in_current_zone to the Rails 4 syntax #in_time_zone, if it has not already been defined.

Usage

Setting the Query Field

By default, ByStar assumes you will use the created_at field to query objects by time. You may specify an alternate field on all query methods as follows:

Post.by_month("January", field: :updated_at)

Alternatively, you may set a default in your model using the by_star_field macro:

class Post  "ruby")

Want to count records? Simple:

Post.by_month.count

Timezone Handling

ByStar date-range finders will use value of Time.zone to evaluate the args. This may cause unexpected behavior when use Time values in timezones other than Time.zone.

Time.zone = 'Australia/Sydney'
Post.by_day('2020-04-05 18:00:00 EST')
#=> Returns Apr 6th, 0:00 until Apr 6th, 23:59 in Sydney timezone.

:offset Option

All ByStar finders support an :offset option which is applied to time period of the query condition. This is useful in cases where the daily cycle occurs at a time other than midnight.

For example, if you'd like to find all Posts from 9:00 on 2014-03-05 until 8:59:59.999 on 2014-03-06, you can do:

Post.by_day('2014-03-05', offset: 9.hours)

Note: When passing offset in date finders, it will set the hour, minute, and second on the queried date in order to properly handle DST transitions. Example:

Time.zone = 'Australia/Sydney'
Post.by_day('2020-04-05', offset: 9.hours)
#=> Returns Apr 5th, 09:00 until Apr 6th, 08:59

Timespan Objects

If your object has both a start and end time, you may pass both params to by_star_field:

by_star_field :start_time, :end_time

By default, ByStar queries will return all objects whose range has any overlap within the desired period (permissive):

MultiDayEvent.by_month("January")
#=> returns MultiDayEvents that overlap in January,
#   even if they start in December and/or end in February

Timespan Objects: #at_time

To find all instances of a timespan object which contain a specific time:

Post.at_time(time)

This can be useful to find all currently active instances. Note that object instances which start exactly at the given time will be included in the result, but instances that end exactly at the given time will not be.

Timespan Objects: :strict Option

If you'd like to confine results to only those both starting and ending within the given range, use the :strict option:

MultiDayEvent.by_month("January", :strict => true)
#=> returns MultiDayEvents that both start AND end in January

Timespan Objects: Database Indexing and :index_scope Option

In order to ensure query performance on large dataset, you must add an index to the query field (e.g. "created_at") be indexed. ByStar does not define indexes automatically.

Database indexes require querying a range query on a single field, i.e. start_time >= X and start_time = X and end_time = end_time, we add the converse constraint start_time = X to ensure both fields are double-sided, i.e. an index can be used on either field.

1. Timespan without :strict option, e.g. "start_time X".

Here we need to add a condition start_time >= X to ensure start_time is bounded on both sides. To achieve this, we allow an :index_scope option which is the minimum "strict" bound on the querying range, in other words, it is an assumption about the maximum timespan of objects.

:index_scope supports multiple value types:

An example settings of :index_scope:

# The maximum possible object length is 5 hours.
by_star index_scope: 5.hours

# Objects are guaranteed to start within the same month, with some offset.
by_star index_scope: ->(start_time, end_time, options){ start_time.beginning_of_month + (options[:offset] || 0) }

# The maximum possible object length half the range being queried.
by_star index_scope: ->(start_time, end_time, options){ ((start_time - end_time)*0.5).seconds }

Chronic Support

If Chronic gem is present, it will be used to parse natural-language date/time strings in all ByStar finder methods. Otherwise, the Ruby Time.parse kernel method will be used as a fallback.

As of ByStar 2.2.0, you must explicitly include gem 'chronic' into your Gemfile in order to use Chronic.

Advanced Usage

between_times

To find records between two times:

Post.between_times(time1, time2)

You use a Range like so:

Post.between_times(time1..time2)

Also works with dates - WARNING: there are currently some caveats see Issue #49:

Post.between_times(date1, date2)

It will query records from date1 (00:00:00 Hrs) until date2 (23:59:59 Hrs).

before and after

To find all posts before / after the current time:

Post.before
Post.after

To find all posts before certain time or date:

Post.before(Date.today + 2)
Post.after(Time.now + 5.days)

You can also pass a string:

Post.before("next tuesday")

For Time-Range type objects, only the start time is considered for before and after.

previous and next

To find the prior/subsequent record to a model instance, previous/next on it:

Post.last.previous
Post.first.next

You can specify a field also:

Post.last.previous(field: "published_at")
Post.first.next(field: "published_at")

For Time-Range type objects, only the start time is considered for previous and next.

by_year

To find records from the current year, simply call the method without any arguments:

Post.by_year

To find records based on a year you can pass it a two or four digit number:

Post.by_year(09)

This will return all posts in 2009, whereas:

Post.by_year(99)

will return all the posts in the year 1999.

You can also specify the full year:

Post.by_year(2009)
Post.by_year(1999)

by_month

If you know the number of the month you want:

Post.by_month(1)

This will return all posts in the first month (January) of the current year.

If you like being verbose:

Post.by_month("January")

This will return all posts created in January of the current year.

If you want to find all posts in January of last year just do

Post.by_month(1, year: 2007)

or

Post.by_month("January", year: 2007)

This will perform a find using the column you've speci