active_record_date_range_scopes 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1909e880a4c222561ba32c51bfc9c7d9ef2b1569d2406753288b3ee1620e0987
+  data.tar.gz: 7b7c06039f49a79f3ec2b64ee10a6f1771ac23095406f11398429b48ef4f70e7
+SHA512:
+  metadata.gz: 619b3fc50ed3cdb62f060b9b8a562d103ca4f0f5084af741d8391e8f9db67d575c436727aec700b41a3518f8236ab500b8dbfc5b20713e17fe857e3a6871b746
+  data.tar.gz: 0d9835c95dc6ff11fea13203d33e9980479282f8c8ed5eac90570f26b3db612876b1b0388b5213d70ca236d8b66dc1b8ba8af4c8a1978d01c406e7b9e39e916e

data/.gitignore

@@ -0,0 +1,10 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+.rspec_status
+Gemfile.lock

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,7 @@
+---
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+  - 2.6.3
+before_install: gem install bundler -v 1.17.3

data/Changelog.md

@@ -0,0 +1,10 @@
+# Changelog
+
+This project follows [semver 2.0.0](http://semver.org/spec/v2.0.0.html) and the
+recommendations of [keepachangelog.com](http://keepachangelog.com/).
+
+## (Unreleased)
+
+## 0.1.2 (2020-01-31)
+
+Initial release

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in active_record_date_range_scopes.gemspec
+gemspec

data/License

@@ -0,0 +1,18 @@
+Copyright (c) 2020 Tyler Rick
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/Readme.md

@@ -0,0 +1,152 @@
+# ActiveRecord Date Range Scopes
+
+Simply add a line like this within your ActiveRecord model:
+```ruby
+  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:
+
+```ruby
+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.
+
+```ruby
+class Book < ActiveRecord::Base
+  # This creates is_between, is_after, is_before scopes
+  date_range_scopes :is, ->{ arel_table[:created_at] },
+end
+```
+
+```ruby
+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:
+```ruby
+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) {
+    …
+  }
+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:
+
+```ruby
+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](https://github.com/simon0191/date_supercharger) ([meat](https://github.com/simon0191/date_supercharger/blob/master/lib/date_supercharger/method_definer.rb))
+- It [_automatically_ adds scopes](https://github.com/simon0191/date_supercharger/blob/master/lib/date_supercharger/matcher.rb#L25) 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](https://github.com/nragaz/date_range_scopes) ([meat](https://github.com/nragaz/date_range_scopes/blob/master/lib/date_range_scopes.rb))
+- +: It [supports](https://github.com/nragaz/date_range_scopes/blob/master/lib/date_range_scopes.rb#L28) `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](https://github.com/kevinkaske/readable_date_ranges) ([meat](https://github.com/kevinkaske/readable_date_ranges/blob/master/lib/readable_date_ranges.rb))
+- 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`:
+
+```ruby
+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](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/TylerRick/active_record_date_range_scopes.

data/active_record_date_range_scopes.gemspec

@@ -0,0 +1,34 @@
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "active_record/date_range_scopes/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "active_record_date_range_scopes"
+  spec.version       = ActiveRecord::DateRangeScopes.version
+  spec.authors       = ["Tyler Rick"]
+  spec.email         = ["tyler@tylerrick.com"]
+
+  spec.summary       = %q{Easily create ActiveRecord date range scopes}
+  spec.description   = spec.summary
+  spec.homepage      = "http://github.com/TylerRick/active_record_date_range_scopes"
+
+  spec.metadata["homepage_uri"]    = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.metadata["source_code_uri"]}/blob/master/Changelog.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activesupport", [">= 4.2"]
+  spec.add_dependency "activerecord", [">= 4.2"]
+
+  spec.add_development_dependency "bundler", "~> 1.17"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "active_record_date_range_scopes"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/active_record/date_range_scopes.rb

@@ -0,0 +1,162 @@
+require 'active_record'
+require 'active_support'
+
+module ActiveRecord
+module DateRangeScopes
+  extend ActiveSupport::Concern
+
+  module ClassMethods
+    ##
+    # Defines 3 date range scopes named after the given `name`:
+    # - {name}_between
+    # - {name}_after
+    # - {name}_before
+    #
+    # By default, uses {name}_at as the column name. Column should be a :datetime (timestamp) column.
+    #
+    # Examples:
+    #
+    #   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
+    #
+    #   class Author < ActiveRecord::Base
+    #     # You can specify a different column name to use for the scopes, and optionally, any joins
+    #     # or other clauses you need to add to the relation.
+    #     date_range_scopes :with_any_books_created, ->{ Book.arel_table[:created_at] }, ->(_) { joins(:books) }
+    #   end
+    #
+    #   # This would be the same as:
+    #   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) {
+    #       …
+    #     }
+    #   end
+    #
+    def date_range_scopes(
+      name,
+      arel_attr = -> { arel_table[:"#{name}_at"] },
+      relation = :itself
+    )
+      relation = relation.to_proc
+
+      scope :"#{name}_between", ->(after, before) {
+        public_send(:"#{name}_after", after).
+        public_send(:"#{name}_before", before)
+      }
+      scope :"#{name}_after",   ->(date_or_time) {
+        next unless date_or_time
+
+        instance_eval(&relation).
+        where(
+          arel_attr.().gteq( time_or_beginning_of_day(date_or_time) )
+        )
+      }
+      scope :"#{name}_before",  ->(date_or_time) {
+        next unless date_or_time
+
+        instance_eval(&relation).
+        where(
+          arel_attr.().lteq( time_or_end_of_day(date_or_time) )
+        )
+      }
+    end
+
+    def time_or_end_of_day(date_or_time)
+      if date_or_time.is_a?(Date)
+        date_or_time.in_time_zone.end_of_day
+      else
+        date_or_time.in_time_zone
+      end
+    end
+
+    def time_or_beginning_of_day(date_or_time)
+      if date_or_time.is_a?(Date)
+        date_or_time.in_time_zone.beginning_of_day
+      else
+        date_or_time.in_time_zone
+      end
+    end
+
+    ##
+    # 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')
+    #
+    def delegate_date_range_scopes(
+      local_name,
+      relation = :itself,
+      to:,
+      scope: nil
+    )
+      relation = relation.to_proc
+      target_model = to
+      name_on_target = scope || local_name.to_s.sub(/^#{target_model.model_name.plural}_/, '')
+
+      scope(:"#{local_name}_between", ->(after, before) {
+        public_send(:"#{local_name}_after", after).
+        public_send(:"#{local_name}_before", before)
+      })
+      scope(:"#{local_name}_after",   ->(date_or_time) {
+        next unless date_or_time
+
+        instance_eval(&relation).
+        merge(
+          target_model.public_send(:"#{name_on_target}_after", date_or_time)
+        )
+      })
+      scope(:"#{local_name}_before",  ->(date_or_time) {
+        next unless date_or_time
+
+        instance_eval(&relation).
+        merge(
+          target_model.public_send(:"#{name_on_target}_before", date_or_time)
+        )
+      })
+    end
+  end
+end
+end
+
+ActiveRecord::Base.class_eval do
+  include ActiveRecord::DateRangeScopes
+end

data/lib/active_record/date_range_scopes/version.rb

@@ -0,0 +1,7 @@
+module ActiveRecord
+  module DateRangeScopes
+    def self.version
+      "0.1.2"
+    end
+  end
+end

data/lib/active_record_date_range_scopes.rb

@@ -0,0 +1,2 @@
+require 'active_record/date_range_scopes/version'
+require 'active_record/date_range_scopes'

metadata

@@ -0,0 +1,129 @@
+--- !ruby/object:Gem::Specification
+name: active_record_date_range_scopes
+version: !ruby/object:Gem::Version
+  version: 0.1.2
+platform: ruby
+authors:
+- Tyler Rick
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2020-01-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.2'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.2'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Easily create ActiveRecord date range scopes
+email:
+- tyler@tylerrick.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Changelog.md
+- Gemfile
+- License
+- Rakefile
+- Readme.md
+- active_record_date_range_scopes.gemspec
+- bin/console
+- bin/setup
+- lib/active_record/date_range_scopes.rb
+- lib/active_record/date_range_scopes/version.rb
+- lib/active_record_date_range_scopes.rb
+homepage: http://github.com/TylerRick/active_record_date_range_scopes
+licenses: []
+metadata:
+  homepage_uri: http://github.com/TylerRick/active_record_date_range_scopes
+  source_code_uri: http://github.com/TylerRick/active_record_date_range_scopes
+  changelog_uri: http://github.com/TylerRick/active_record_date_range_scopes/blob/master/Changelog.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Easily create ActiveRecord date range scopes
+test_files: []