active_record_date_range_scopes

ActiveRecord Date Range Scopes

Simply add a line like this within your ActiveRecord model:

  date_range_scopes :created

… and it will defines 3 date range scopes named after the given scope name:

• {name}_between
• {name}_after
• {name}_before

Usage

date_range_scopes

Simple example:

class Book < ActiveRecord::Base
  # This defines created_between, created_after, created_before scopes
  date_range_scopes :created

  # This defines updated_between, updated_after, updated_before scopes
  date_range_scopes :updated
end

Book.created_between(3.years.ago, 1.year.ago)
Book.created_between('2020-01-01', '2020-01-31')
Book.created_after(1.week.ago)
Book.created_before(1.day.ago)

By default, uses {name}_at as the column name. Column should be a :datetime (timestamp) column.

But if the defaults aren't what you need, it is fully customizable:

• You can give the scopes any name prefix you want
• You can specify a different column name to use for the scopes
• You can optionally add any joins or other clauses you need to add to the relation.

class Book < ActiveRecord::Base
  # This creates is_between, is_after, is_before scopes
  date_range_scopes :is, ->{ arel_table[:created_at] },
end

class Author < ActiveRecord::Base
  date_range_scopes :with_any_books_created,
    ->{ Book.arel_table[:created_at] },
    ->(_) { joins(:books) }
end

This would be the same as writing it out long-hand:

class Author < ActiveRecord::Base
  scope :with_any_books_created_between, ->(after, before) {
    with_any_books_created_after(after).
    with_any_books_created_before(before)
  }
  scope :with_any_books_created_after, ->(date_or_time) {
    next unless date_or_time

    joins(:books).
    where(
      Book.arel_table[:created_at].gteq( time_or_beginning_of_day(date_or_time) )
    )
  }
  scope :with_any_books_created_before, ->(date_or_time) {
    next unless date_or_time

    joins(:books).
    where(
      Book.arel_table[:created_at].lteq( time_or_end_of_day(date_or_time) )
    )
  }
end

delegate_date_range_scopes

Delegates the date filter scopes to an association (requires the scopes to already be defined there in the to model using date_range_scopes).

This uses Relation.merge to merge the scope on the associated model, allowing you to reuse existing scopes on other models. But since these scopes are local (to the model in which you call delegate_date_range_scopes), the query returns instances of the local model rather than instances of the associated model.

Unlike date_range_scopes, where you specify which column to operate on, this lets you specify which scope to delegate to in the target (to) model. If scope not specified, uses the same scope name as in the source model, removing {target}s_ prefix if there is one.

Example:

class Book < ActiveRecord::Base
  date_range_scopes :created
end

class Author < ActiveRecord::Base
  # Delegates to Book.created* scopes by default
  delegate_date_range_scopes :books_created,          ->(_) { joins(:books) }, to: Book
  # Explicitly tells it to delegate Author.with_any_books_written_* to Book.created_
  delegate_date_range_scopes :with_any_books_written, ->(_) { joins(:books) }, to: Book, scope: :created
end

Author.with_any_books_written_before('1970-01-01')

Features

• Makes it very easy to define date range scopes
• Lets you add scopes that are based on associated (join) records
• If nil is passed to any of these scopes, the scope simply has no effect, rather than raising an error. This is useful if you have lots of filters that your users may or may not provide any value for.
• Handles time zones correctly: calls in_time_zone on strings/dates that are passed in
• If a date is passed in, it is converted to beginning_of_day/end_of_day depending on whether it is used in an _after/_before scope, respectively
• It even lets you mix dates and times in an intuitive way: Model.created_between(1.week.ago, Date.today)

Comparison with other date range gems

date_supercharger (meat)

• It automatically adds scopes for every datetime/date column (PR welcome for an optional module that you can include to get this behavior); active_record_date_range_scopes requires explicitly adding scopes, provides a macro that makes it easy to add scopes for the columns you care about, give them meaningful/custom names, and even add scopes that are based on associated (join) records
• =: It defines separate between and between_inclusive scopes; active_record_date_range_scopes provides an inclusive: option that can be passed to any scope

date_range_scopes (meat)

• +: It supports date (_on) fields; active_record_date_range_scopes currently only supports datetime (_at) fields (PR welcome!)
• +: It provides _on, _in_week, _in_month, _in_year scopes (PR welcome!)
• -: It doesn't provides _between/_after/_before scopes
• -: It uses strings ("column >=") for where clause; active_record_date_range_scopes uses Arel (arel_table[:column].gteq())

https://github.com/kevinkaske/readable_date_ranges (meat)

• Its main focus appears to be adding readable range scopes like created_this_week, which is nice to have as presets but means it is pretty inflexible (can't specify custom ranges like you can in active_record_date_range_scopes and the other similar gems)
• +: It provides _this_week, _this_month, _this_year; _last_week, etc. scopes (PR welcome!)

Installation

Add this line to your application's Gemfile:

gem 'active_record_date_range_scopes'

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/TylerRick/active_record_date_range_scopes.