ByStar
A Ruby gem for querying ActiveRecord and Mongoid objects by time ranges like year, month, week, and day.
What is ByStar?
ByStar is a Ruby gem that adds time-based querying capabilities to ActiveRecord and Mongoid models. It provides a rich set of scopes and methods to find database records by year, month, week, day, and other time ranges, simplifying common tasks like retrieving posts from a specific month or events happening today.
Ruby on Rails and Mongoid developers who need to frequently query models based on dates and times, such as those building blogs, event calendars, analytics dashboards, or any time-sensitive application.
Developers choose ByStar for its clean, expressive API that reduces boilerplate code for time queries, its support for both ActiveRecord and Mongoid, and its robust handling of edge cases like timezones, offsets, and timespan objects.
Overview
Lets you find ActiveRecord + Mongoid objects by year, month, fortnight, week and more!
Use Cases
Best For
- Querying blog posts or articles by publication month or year
- Building event calendars with date-based filtering
- Generating reports for specific time periods (e.g., last quarter)
- Finding records relative to the current date (e.g., recent activity)
- Handling timespan-based objects like multi-day events
- Implementing pagination or navigation by time (next/previous post)
Not Ideal For
- Projects using ORMs other than ActiveRecord or Mongoid, such as Sequel or ROM
- Applications where time-based queries are simple enough for raw SQL or basic ActiveRecord scopes
- Systems requiring sub-second precision or nanosecond-level time filtering
Pros & Cons
Pros
Provides intuitive methods like `by_year` and `past_week` that eliminate complex SQL, as shown in examples for querying posts by date without manual condition building.
Covers everything from days to years, including relative scopes and timespan handling, with options for offsets and timezones detailed in the README's usage sections.
Works seamlessly with both ActiveRecord and Mongoid, requiring only a simple `include Mongoid::ByStar` for Mongoid models, as per installation instructions.
Supports objects with start and end times, offering permissive or strict matching and configurable :index_scope for database performance, though setup is manual.
Cons
For timespan objects, proper database indexing requires understanding and setting the :index_scope option, which the README admits is not automated and can be error-prone.
Natural language date parsing depends on the Chronic gem, which must be explicitly added to the Gemfile since version 2.2.0, adding maintenance overhead.
The README warns of issues with between_times for dates (see Issue #49), potentially leading to unexpected behavior in edge cases without clear resolutions.
Frequently Asked Questions
Related Projects
groupdateThe simplest way to group temporal data
chronicChronic is a pure Ruby natural language date parser.
ice_cubeRuby Date Recurrence Library - Allows easy creation of recurrence rules and fast querying
local_timeRails engine for cache-friendly, client-side local time
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.