active_record_in_time_scope 0.1.7

data/lib/active_record_in_time_scope/class_methods.rb

@@ -0,0 +1,457 @@
+# frozen_string_literal: true
+
+module ActiveRecordInTimeScope
+  # Class methods added to ActiveRecord models when ActiveRecordInTimeScope is included
+  module ClassMethods
+    # Defines time-window scopes for the model.
+    #
+    # This method creates both a class-level scope and an instance method
+    # to check if records fall within a specified time window.
+    #
+    # @param scope_name [Symbol] The name of the scope (default: :in_time)
+    #   When not :in_time, columns default to +<scope_name>_start_at+ and +<scope_name>_end_at+
+    #
+    # @param start_at [Hash] Configuration for the start column
+    # @option start_at [Symbol, nil] :column Column name (nil to disable start boundary)
+    # @option start_at [Boolean] :null Whether the column allows NULL values
+    #   (auto-detected from schema if not specified)
+    #
+    # @param end_at [Hash] Configuration for the end column
+    # @option end_at [Symbol, nil] :column Column name (nil to disable end boundary)
+    # @option end_at [Boolean] :null Whether the column allows NULL values
+    #   (auto-detected from schema if not specified)
+    #
+    # @raise [ColumnNotFoundError] When a specified column doesn't exist (at class load time)
+    # @raise [ConfigurationError] When both columns are nil, or when using start-only/end-only
+    #   pattern with a nullable column (at scope call time)
+    #
+    # @return [void]
+    #
+    # == Examples
+    #
+    # Default scope with nullable columns:
+    #
+    #   in_time_scope
+    #   # Creates: Model.in_time, model.in_time?
+    #
+    # Named scope:
+    #
+    #   in_time_scope :published
+    #   # Creates: Model.in_time_published, model.in_time_published?
+    #   # Uses: published_start_at, published_end_at columns
+    #
+    # Custom columns:
+    #
+    #   in_time_scope start_at: { column: :available_at }, end_at: { column: :expired_at }
+    #
+    # Start-only pattern (for history tracking):
+    #
+    #   in_time_scope start_at: { null: false }, end_at: { column: nil }
+    #   # Also creates: Model.latest_in_time(:foreign_key), Model.earliest_in_time(:foreign_key)
+    #
+    # End-only pattern (for expiration):
+    #
+    #   in_time_scope start_at: { column: nil }, end_at: { null: false }
+    #   # Also creates: Model.latest_in_time(:foreign_key), Model.earliest_in_time(:foreign_key)
+    #
+    def in_time_scope(scope_name = :in_time, start_at: {}, end_at: {})
+      table_column_hash = columns_hash
+      time_column_prefix = scope_name == :in_time ? "" : "#{scope_name}_"
+
+      start_at_column = start_at.fetch(:column, :"#{time_column_prefix}start_at")
+      end_at_column = end_at.fetch(:column, :"#{time_column_prefix}end_at")
+
+      start_at_null = fetch_null_option(start_at, start_at_column, table_column_hash)
+      end_at_null = fetch_null_option(end_at, end_at_column, table_column_hash)
+
+      define_scope_methods(
+        scope_name == :in_time ? "" : "_#{scope_name}",
+        start_at_column: start_at_column,
+        start_at_null: start_at_null,
+        end_at_column: end_at_column,
+        end_at_null: end_at_null
+      )
+    end
+
+    private
+
+    # Fetches the null option for a column, auto-detecting from schema if not specified
+    #
+    # @param config [Hash] Configuration hash with optional :null key
+    # @param column [Symbol, nil] Column name
+    # @param table_column_hash [Hash] Hash of column metadata from ActiveRecord
+    # @return [Boolean, nil] Whether the column allows NULL values
+    # @raise [ColumnNotFoundError] When the column doesn't exist in the table
+    # @api private
+    def fetch_null_option(config, column, table_column_hash)
+      return nil if column.nil?
+      return config[:null] if config.key?(:null)
+
+      column_info = table_column_hash[column.to_s]
+      raise ColumnNotFoundError, "Column '#{column}' does not exist on table '#{table_name}'" if column_info.nil?
+
+      column_info.null
+    end
+
+    # Returns true when only the start column is configured (history tracking pattern)
+    #
+    # @param start_at_column [Symbol, nil] Start column name
+    # @param end_at_column [Symbol, nil] End column name
+    # @return [Boolean]
+    # @api private
+    def start_only_pattern?(start_at_column, end_at_column)
+      !start_at_column.nil? && end_at_column.nil?
+    end
+
+    # Returns true when only the end column is configured (expiration pattern)
+    #
+    # @param start_at_column [Symbol, nil] Start column name
+    # @param end_at_column [Symbol, nil] End column name
+    # @return [Boolean]
+    # @api private
+    def end_only_pattern?(start_at_column, end_at_column)
+      start_at_column.nil? && !end_at_column.nil?
+    end
+
+    # Defines the appropriate scope methods based on configuration
+    #
+    # @param suffix [String] The suffix for method names ("" or "_#{scope_name}")
+    # @param start_at_column [Symbol, nil] Start column name
+    # @param start_at_null [Boolean, nil] Whether start column allows NULL
+    # @param end_at_column [Symbol, nil] End column name
+    # @param end_at_null [Boolean, nil] Whether end column allows NULL
+    # @return [void]
+    # @api private
+    def define_scope_methods(suffix, start_at_column:, start_at_null:, end_at_column:, end_at_null:)
+      # Define class-level scope and instance method
+      if start_at_column.nil? && end_at_column.nil?
+        define_error_scope_and_method(suffix,
+                                      "At least one of start_at or end_at must be specified")
+      elsif start_only_pattern?(start_at_column, end_at_column)
+        # Start-only pattern (history tracking) - requires non-nullable column
+        if start_at_null
+          define_error_scope_and_method(suffix,
+                                        "Start-only pattern requires non-nullable column. " \
+                                        "Set `start_at: { null: false }` or add an end_at column")
+        else
+          define_start_only_scope(suffix, start_at_column)
+          define_instance_method(suffix, start_at_column, start_at_null, end_at_column, end_at_null)
+          define_latest_one_scope(suffix, start_at_column)
+          define_earliest_one_scope(suffix, start_at_column)
+          define_before_scope(suffix, start_at_column, start_at_null)
+          define_after_scope(suffix, end_at_column, end_at_null)
+          define_out_of_time_scope(suffix)
+        end
+      elsif end_only_pattern?(start_at_column, end_at_column)
+        # End-only pattern (expiration) - requires non-nullable column
+        if end_at_null
+          define_error_scope_and_method(suffix,
+                                        "End-only pattern requires non-nullable column. " \
+                                        "Set `end_at: { null: false }` or add a start_at column")
+        else
+          define_end_only_scope(suffix, end_at_column)
+          define_instance_method(suffix, start_at_column, start_at_null, end_at_column, end_at_null)
+          define_latest_one_scope(suffix, end_at_column)
+          define_earliest_one_scope(suffix, end_at_column)
+          define_before_scope(suffix, start_at_column, start_at_null)
+          define_after_scope(suffix, end_at_column, end_at_null)
+          define_out_of_time_scope(suffix)
+        end
+      else
+        # Both start and end
+        define_full_scope(suffix, start_at_column, start_at_null, end_at_column, end_at_null)
+        define_instance_method(suffix, start_at_column, start_at_null, end_at_column, end_at_null)
+        define_before_scope(suffix, start_at_column, start_at_null)
+        define_after_scope(suffix, end_at_column, end_at_null)
+        define_out_of_time_scope(suffix)
+      end
+    end
+
+    # Defines a scope and instance method that raise ConfigurationError
+    #
+    # @param suffix [String] The suffix for method names
+    # @param message [String] The error message
+    # @return [void]
+    # @api private
+    def define_error_scope_and_method(suffix, message)
+      method_names = [
+        :"in_time#{suffix}",
+        :"before_in_time#{suffix}",
+        :"after_in_time#{suffix}",
+        :"out_of_time#{suffix}"
+      ]
+
+      method_names.each do |method_name|
+        scope method_name, ->(_time = Time.current) {
+          raise ActiveRecordInTimeScope::ConfigurationError, message
+        }
+
+        define_method("#{method_name}?") do |_time = Time.current|
+          raise ActiveRecordInTimeScope::ConfigurationError, message
+        end
+      end
+    end
+
+    # Defines a start-only scope (for history tracking pattern)
+    #
+    # @param suffix [String] The suffix for method names
+    # @param column [Symbol] The start column name
+    # @return [void]
+    # @api private
+    def define_start_only_scope(suffix, column)
+      # Simple scope - WHERE only, no ORDER BY
+      # Users can add .order(start_at: :desc) externally if needed
+      scope :"in_time#{suffix}", ->(time = Time.current) {
+        where(column => ..time)
+      }
+    end
+
+    # Defines the latest_in_time scope using NOT EXISTS subquery
+    #
+    # This scope efficiently finds the latest record per foreign key,
+    # suitable for use with has_one associations and includes.
+    #
+    # @note When multiple records share the same timestamp for a given foreign key,
+    #   all of them will be returned. This is safe for +has_one+ associations
+    #   (ActiveRecord picks one), but callers using this as a standalone scope
+    #   should be aware that the result may contain multiple records per foreign key
+    #   in the case of timestamp ties.
+    #
+    # @param suffix [String] The suffix for method names
+    # @param column [Symbol] The timestamp column name
+    # @return [void]
+    #
+    # @example Usage with has_one
+    #   has_one :current_price, -> { latest_in_time(:user_id) }, class_name: 'Price'
+    #
+    # @api private
+    def define_latest_one_scope(suffix, column)
+      # NOT EXISTS approach: select records where no later record exists for the same foreign key
+      scope :"latest_in_time#{suffix}", ->(foreign_key, time = Time.current) {
+        p2 = arel_table.alias("p2")
+
+        subquery = Arel::SelectManager.new(arel_table)
+                                      .from(p2)
+                                      .project(Arel.sql("1"))
+                                      .where(p2[foreign_key].eq(arel_table[foreign_key]))
+                                      .where(p2[column].lteq(time))
+                                      .where(p2[column].gt(arel_table[column]))
+                                      .where(p2[:id].not_eq(arel_table[:id]))
+
+        # Propagate simple equality conditions from the current scope into the NOT EXISTS
+        # subquery. This ensures that chained scopes like `.approved.latest_in_time(:user_id)`
+        # only consider approved records when searching for "a newer record exists",
+        # preventing a newer rejected record from shadowing the latest approved one.
+        where_values_hash.each do |col, val|
+          next if col.to_s == column.to_s      # time column already handled above
+          next if col.to_s == foreign_key.to_s # foreign key already handled above
+
+          subquery = if val.nil?
+                       subquery.where(p2[col].eq(nil))
+                     elsif val.is_a?(Array)
+                       subquery.where(p2[col].in(val))
+                     else
+                       subquery.where(p2[col].eq(val))
+                     end
+        end
+
+        not_exists = Arel::Nodes::Not.new(Arel::Nodes::Exists.new(subquery.ast))
+
+        where(column => ..time).where(not_exists)
+      }
+    end
+
+    # Defines the earliest_in_time scope using NOT EXISTS subquery
+    #
+    # This scope efficiently finds the earliest record per foreign key,
+    # suitable for use with has_one associations and includes.
+    #
+    # @note When multiple records share the same timestamp for a given foreign key,
+    #   all of them will be returned. This is safe for +has_one+ associations
+    #   (ActiveRecord picks one), but callers using this as a standalone scope
+    #   should be aware that the result may contain multiple records per foreign key
+    #   in the case of timestamp ties.
+    #
+    # @param suffix [String] The suffix for method names
+    # @param column [Symbol] The timestamp column name
+    # @return [void]
+    #
+    # @example Usage with has_one
+    #   has_one :first_price, -> { earliest_in_time(:user_id) }, class_name: 'Price'
+    #
+    # @api private
+    def define_earliest_one_scope(suffix, column)
+      # NOT EXISTS approach: select records where no earlier record exists for the same foreign key
+      scope :"earliest_in_time#{suffix}", ->(foreign_key, time = Time.current) {
+        p2 = arel_table.alias("p2")
+
+        subquery = Arel::SelectManager.new(arel_table)
+                                      .from(p2)
+                                      .project(Arel.sql("1"))
+                                      .where(p2[foreign_key].eq(arel_table[foreign_key]))
+                                      .where(p2[column].lteq(time))
+                                      .where(p2[column].lt(arel_table[column]))
+                                      .where(p2[:id].not_eq(arel_table[:id]))
+
+        # Propagate simple equality conditions from the current scope into the NOT EXISTS
+        # subquery (same reasoning as define_latest_one_scope).
+        where_values_hash.each do |col, val|
+          next if col.to_s == column.to_s
+          next if col.to_s == foreign_key.to_s
+
+          subquery = if val.nil?
+                       subquery.where(p2[col].eq(nil))
+                     elsif val.is_a?(Array)
+                       subquery.where(p2[col].in(val))
+                     else
+                       subquery.where(p2[col].eq(val))
+                     end
+        end
+
+        not_exists = Arel::Nodes::Not.new(Arel::Nodes::Exists.new(subquery.ast))
+
+        where(column => ..time).where(not_exists)
+      }
+    end
+
+    # Defines an end-only scope (for expiration pattern)
+    #
+    # @param suffix [String] The suffix for method names
+    # @param column [Symbol] The end column name
+    # @return [void]
+    # @api private
+    def define_end_only_scope(suffix, column)
+      scope :"in_time#{suffix}", ->(time = Time.current) {
+        where.not(column => ..time)
+      }
+    end
+
+    # Defines a full scope with both start and end columns
+    #
+    # @param suffix [String] The suffix for method names
+    # @param start_column [Symbol] The start column name
+    # @param start_null [Boolean] Whether start column allows NULL
+    # @param end_column [Symbol] The end column name
+    # @param end_null [Boolean] Whether end column allows NULL
+    # @return [void]
+    # @api private
+    def define_full_scope(suffix, start_column, start_null, end_column, end_null)
+      scope :"in_time#{suffix}", ->(time = Time.current) {
+        start_scope = if start_null
+                        where(start_column => nil).or(where(start_column => ..time))
+                      else
+                        where(start_column => ..time)
+                      end
+
+        end_scope = if end_null
+                      where(end_column => nil).or(where.not(end_column => ..time))
+                    else
+                      where.not(end_column => ..time)
+                    end
+
+        start_scope.merge(end_scope)
+      }
+
+      # NOTE: latest_in_time / earliest_in_time are NOT defined for full scope (both start and end)
+      # because the concept of "latest" or "earliest" is ambiguous when there's a time range.
+      # These scopes are only available for start-only or end-only patterns.
+    end
+
+    # Defines the instance method to check if a record is within the time window
+    #
+    # @param suffix [String] The suffix for method names
+    # @param start_column [Symbol, nil] The start column name
+    # @param start_null [Boolean, nil] Whether start column allows NULL
+    # @param end_column [Symbol, nil] The end column name
+    # @param end_null [Boolean, nil] Whether end column allows NULL
+    # @return [void]
+    # @api private
+    def define_instance_method(suffix, start_column, start_null, end_column, end_null)
+      define_method("in_time#{suffix}?") do |time = Time.current|
+        start_ok = if start_column.nil?
+                     true
+                   elsif start_null
+                     send(start_column).nil? || send(start_column) <= time
+                   else
+                     send(start_column) <= time
+                   end
+
+        end_ok = if end_column.nil?
+                   true
+                 elsif end_null
+                   send(end_column).nil? || send(end_column) > time
+                 else
+                   send(end_column) > time
+                 end
+
+        start_ok && end_ok
+      end
+    end
+
+    # Defines before_in_time scope (records not yet started: start_at > time)
+    #
+    # @param suffix [String] The suffix for method names
+    # @param start_column [Symbol, nil] The start column name
+    # @param start_null [Boolean, nil] Whether start column allows NULL
+    # @return [void]
+    # @api private
+    def define_before_scope(suffix, start_column, start_null)
+      # No start column means always started (never before)
+      # start_at > time means not yet started
+      # NULL start_at is treated as "already started" (not before)
+      scope :"before_in_time#{suffix}", ->(time = Time.current) {
+        start_column.nil? ? none : where.not(start_column => ..time)
+      }
+
+      define_method("before_in_time#{suffix}?") do |time = Time.current|
+        return false if start_column.nil?
+
+        val = send(start_column)
+        return false if val.nil? && start_null
+
+        val > time
+      end
+    end
+
+    # Defines after_in_time scope (records already ended: end_at <= time)
+    #
+    # @param suffix [String] The suffix for method names
+    # @param end_column [Symbol, nil] The end column name
+    # @param end_null [Boolean, nil] Whether end column allows NULL
+    # @return [void]
+    # @api private
+    def define_after_scope(suffix, end_column, end_null)
+      # No end column means never ends (never after)
+      # end_at <= time means already ended
+      # NULL end_at is treated as "never ends" (not after)
+      scope :"after_in_time#{suffix}", ->(time = Time.current) {
+        end_column.nil? ? none : where(end_column => ..time)
+      }
+
+      define_method("after_in_time#{suffix}?") do |time = Time.current|
+        return false if end_column.nil?
+
+        val = send(end_column)
+        return false if val.nil? && end_null
+
+        val <= time
+      end
+    end
+
+    # Defines out_of_time scope (records outside time window: before OR after)
+    #
+    # @param suffix [String] The suffix for method names
+    # @return [void]
+    # @api private
+    def define_out_of_time_scope(suffix)
+      # out_of_time = before_in_time OR after_in_time
+      scope :"out_of_time#{suffix}", ->(time = Time.current) {
+        send(:"before_in_time#{suffix}", time).or(send(:"after_in_time#{suffix}", time))
+      }
+
+      define_method("out_of_time#{suffix}?") do |time = Time.current|
+        send("before_in_time#{suffix}?", time) || send("after_in_time#{suffix}?", time)
+      end
+    end
+  end
+end

data/lib/active_record_in_time_scope/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module ActiveRecordInTimeScope
+  # The current version of the ActiveRecordInTimeScope gem
+  VERSION = "0.1.7"
+end

data/lib/active_record_in_time_scope.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "active_record"
+require_relative "active_record_in_time_scope/version"
+require_relative "active_record_in_time_scope/class_methods"
+
+# ActiveRecordInTimeScope provides time-window scopes for ActiveRecord models.
+#
+# It allows you to easily query records that fall within specific time periods,
+# with support for nullable columns, custom column names, and multiple scopes per model.
+#
+# ActiveRecordInTimeScope is automatically included in ActiveRecord::Base, so you can use
+# +in_time_scope+ directly in your models without explicit include.
+#
+# == Basic usage
+#
+#   class Event < ActiveRecord::Base
+#     in_time_scope
+#   end
+#
+#   Event.in_time                    # Records active at current time
+#   Event.in_time(some_time)         # Records active at specific time
+#   event.in_time?                   # Check if record is active now
+#
+# == Patterns
+#
+# === Full pattern (both start and end)
+#
+# Default pattern with both +start_at+ and +end_at+ columns.
+# Supports nullable columns (NULL means "no limit").
+#
+#   class Event < ActiveRecord::Base
+#     in_time_scope  # Uses start_at and end_at columns
+#   end
+#
+# === Start-only pattern (history tracking)
+#
+# For versioned records where each row is valid from +start_at+ until the next row.
+# Requires non-nullable column.
+#
+#   class Price < ActiveRecord::Base
+#     in_time_scope start_at: { null: false }, end_at: { column: nil }
+#   end
+#
+#   # Additional scopes created:
+#   Price.latest_in_time(:user_id)    # Latest record per user
+#   Price.earliest_in_time(:user_id)  # Earliest record per user
+#
+# === End-only pattern (expiration)
+#
+# For records that are always active until they expire.
+# Requires non-nullable column.
+#
+#   class Coupon < ActiveRecord::Base
+#     in_time_scope start_at: { column: nil }, end_at: { null: false }
+#   end
+#
+# == Using with has_one associations
+#
+# The +latest_in_time+ and +earliest_in_time+ scopes are optimized for
+# +has_one+ associations with +includes+, using NOT EXISTS subqueries.
+#
+#   class Price < ActiveRecord::Base
+#     belongs_to :user
+#     in_time_scope start_at: { null: false }, end_at: { column: nil }
+#   end
+#
+#   class User < ActiveRecord::Base
+#     has_many :prices
+#
+#     # Efficient: uses NOT EXISTS subquery
+#     has_one :current_price,
+#             -> { latest_in_time(:user_id) },
+#             class_name: "Price"
+#
+#     has_one :first_price,
+#             -> { earliest_in_time(:user_id) },
+#             class_name: "Price"
+#   end
+#
+#   # Works efficiently with includes
+#   User.includes(:current_price).each do |user|
+#     puts user.current_price&.amount
+#   end
+#
+# == Named scopes
+#
+# Define multiple time windows per model using named scopes.
+#
+#   class Article < ActiveRecord::Base
+#     in_time_scope :published  # Uses published_start_at, published_end_at
+#     in_time_scope :featured   # Uses featured_start_at, featured_end_at
+#   end
+#
+#   Article.in_time_published
+#   Article.in_time_featured
+#   article.in_time_published?
+#
+# == Custom columns
+#
+#   class Event < ActiveRecord::Base
+#     in_time_scope start_at: { column: :available_at },
+#                   end_at: { column: :expired_at }
+#   end
+#
+# == Error handling
+#
+# - ColumnNotFoundError: Raised at class load time if column doesn't exist
+# - ConfigurationError: Raised at scope call time for invalid configurations
+#
+# @see ClassMethods#in_time_scope
+module ActiveRecordInTimeScope
+  # Base error class for ActiveRecordInTimeScope errors
+  class Error < StandardError; end
+
+  # Raised when a specified column does not exist on the table
+  # @note This error is raised at class load time
+  class ColumnNotFoundError < Error; end
+
+  # Raised when the scope configuration is invalid
+  # @note This error is raised when the scope or instance method is called
+  class ConfigurationError < Error; end
+
+  # @api private
+  def self.included(model)
+    model.extend ClassMethods
+  end
+end
+
+ActiveSupport.on_load(:active_record) do
+  include ActiveRecordInTimeScope
+end

data/mise.toml

@@ -0,0 +1,2 @@
+[tools]
+ruby = "4.0.1"

data/rbs_collection.yaml

@@ -0,0 +1,16 @@
+# RBS collection configuration
+# Run `rbs collection install` to download external gem signatures
+
+sources:
+  - type: git
+    name: ruby/gem_rbs_collection
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    revision: main
+    repo_dir: gems
+
+path: .gem_rbs_collection
+
+gems:
+  - name: activerecord
+  - name: activesupport
+  - name: activemodel

data/rulesync.jsonc

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://raw.githubusercontent.com/dyoshikawa/rulesync/refs/heads/main/config-schema.json",
+  "targets": ["claudecode"],
+  "features": ["rules", "commands"],
+  "baseDirs": ["."]
+}