in_time_scope 0.1.4 → 0.1.6

data/lib/in_time_scope.rb

@@ -2,227 +2,129 @@
 
 require "active_record"
 require_relative "in_time_scope/version"
-
+require_relative "in_time_scope/class_methods"
+
+# InTimeScope 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.
+#
+# InTimeScope 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 InTimeScope
+  # Base error class for InTimeScope 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
-
-  module ClassMethods
-    def in_time_scope(scope_name = :in_time, start_at: {}, end_at: {}, prefix: false)
-      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)
-
-      scope_method_name = method_name(scope_name, prefix)
-
-      define_scope_methods(scope_method_name, start_at_column:, start_at_null:, end_at_column:, end_at_null:)
-    end
-
-    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
-
-    def method_name(scope_name, prefix)
-      return :in_time if scope_name == :in_time
-
-      prefix ? "#{scope_name}_in_time" : "in_time_#{scope_name}"
-    end
-
-    def define_scope_methods(scope_method_name, start_at_column:, start_at_null:, end_at_column:, end_at_null:)
-      # Define class-level scope
-      if start_at_column.nil? && end_at_column.nil?
-        # Both disabled - return all
-        raise ConfigurationError, "At least one of start_at or end_at must be specified"
-      elsif end_at_column.nil?
-        # Start-only pattern (history tracking)
-        define_start_only_scope(scope_method_name, start_at_column, start_at_null)
-      elsif start_at_column.nil?
-        # End-only pattern (expiration)
-        define_end_only_scope(scope_method_name, end_at_column, end_at_null)
-      else
-        # Both start and end
-        define_full_scope(scope_method_name, start_at_column, start_at_null, end_at_column, end_at_null)
-      end
-
-      # Define instance method
-      define_instance_method(scope_method_name, start_at_column, start_at_null, end_at_column, end_at_null)
-    end
-
-    def define_start_only_scope(scope_method_name, start_column, start_null)
-      # Simple scope - WHERE only, no ORDER BY
-      # Users can add .order(start_at: :desc) externally if needed
-      if start_null
-        scope scope_method_name, ->(time = Time.current) {
-          where(arel_table[start_column].eq(nil).or(arel_table[start_column].lteq(time)))
-        }
-      else
-        scope scope_method_name, ->(time = Time.current) {
-          where(arel_table[start_column].lteq(time))
-        }
-      end
-
-      # Efficient scope for has_one + includes using NOT EXISTS subquery
-      # Usage: has_one :current_price, -> { latest_in_time(:user_id) }, class_name: 'Price'
-      define_latest_one_scope(scope_method_name, start_column, start_null)
-      define_earliest_one_scope(scope_method_name, start_column, start_null)
-    end
-
-    def define_latest_one_scope(scope_method_name, start_column, start_null)
-      latest_method_name = scope_method_name == :in_time ? :latest_in_time : :"latest_#{scope_method_name}"
-      tbl = table_name
-      col = start_column
-
-      # NOT EXISTS approach: select records where no later record exists for the same foreign key
-      # SELECT * FROM prices p1 WHERE start_at <= ? AND NOT EXISTS (
-      #   SELECT 1 FROM prices p2 WHERE p2.user_id = p1.user_id
-      #   AND p2.start_at <= ? AND p2.start_at > p1.start_at
-      # )
-      scope latest_method_name, ->(foreign_key, time = Time.current) {
-        fk = foreign_key
-
-        not_exists_sql = if start_null
-                           <<~SQL.squish
-                             NOT EXISTS (
-                               SELECT 1 FROM #{tbl} p2
-                               WHERE p2.#{fk} = #{tbl}.#{fk}
-                               AND (p2.#{col} IS NULL OR p2.#{col} <= ?)
-                               AND (p2.#{col} IS NULL OR p2.#{col} > #{tbl}.#{col} OR #{tbl}.#{col} IS NULL)
-                               AND p2.id != #{tbl}.id
-                             )
-                           SQL
-                         else
-                           <<~SQL.squish
-                             NOT EXISTS (
-                               SELECT 1 FROM #{tbl} p2
-                               WHERE p2.#{fk} = #{tbl}.#{fk}
-                               AND p2.#{col} <= ?
-                               AND p2.#{col} > #{tbl}.#{col}
-                             )
-                           SQL
-                         end
-
-        base_condition = if start_null
-                           where(arel_table[col].eq(nil).or(arel_table[col].lteq(time)))
-                         else
-                           where(arel_table[col].lteq(time))
-                         end
-
-        base_condition.where(not_exists_sql, time)
-      }
-    end
-
-    def define_earliest_one_scope(scope_method_name, start_column, start_null)
-      earliest_method_name = scope_method_name == :in_time ? :earliest_in_time : :"earliest_#{scope_method_name}"
-      tbl = table_name
-      col = start_column
-      scope earliest_method_name, ->(foreign_key, time = Time.current) {
-        fk = foreign_key
-        not_exists_sql = if start_null
-                           <<~SQL.squish
-                             NOT EXISTS (
-                               SELECT 1 FROM #{tbl} p2
-                               WHERE p2.#{fk} = #{tbl}.#{fk}
-                               AND (p2.#{col} IS NULL OR p2.#{col} <= ?)
-                               AND (p2.#{col} IS NULL OR p2.#{col} < #{tbl}.#{col} OR #{tbl}.#{col} IS NULL)
-                               AND p2.id != #{tbl}.id
-                             )
-                           SQL
-                         else
-                           <<~SQL.squish
-                             NOT EXISTS (
-                               SELECT 1 FROM #{tbl} p2
-                               WHERE p2.#{fk} = #{tbl}.#{fk}
-                               AND p2.#{col} <= ?
-                               AND p2.#{col} < #{tbl}.#{col}
-                             )
-                           SQL
-                         end
-        base_condition = if start_null
-                           where(arel_table[col].eq(nil).or(arel_table[col].lteq(time)))
-                         else
-                           where(arel_table[col].lteq(time))
-                         end
-
-        base_condition.where(not_exists_sql, time)
-      }
-    end
-
-    def define_end_only_scope(scope_method_name, end_column, end_null)
-      if end_null
-        scope scope_method_name, ->(time = Time.current) {
-          where(arel_table[end_column].eq(nil).or(arel_table[end_column].gt(time)))
-        }
-      else
-        scope scope_method_name, ->(time = Time.current) {
-          where(arel_table[end_column].gt(time))
-        }
-      end
-
-      define_latest_one_scope(scope_method_name, end_column, end_null)
-      define_earliest_one_scope(scope_method_name, end_column, end_null)
-    end
-
-    def define_full_scope(scope_method_name, start_column, start_null, end_column, end_null)
-      scope scope_method_name, ->(time = Time.current) {
-        start_condition = if start_null
-                            arel_table[start_column].eq(nil).or(arel_table[start_column].lteq(time))
-                          else
-                            arel_table[start_column].lteq(time)
-                          end
-
-        end_condition = if end_null
-                          arel_table[end_column].eq(nil).or(arel_table[end_column].gt(time))
-                        else
-                          arel_table[end_column].gt(time)
-                        end
-
-        where(start_condition).where(end_condition)
-      }
-
-      define_latest_one_scope(scope_method_name, start_column, start_null)
-      define_earliest_one_scope(scope_method_name, start_column, start_null)
-    end
-
-    def define_instance_method(scope_method_name, start_column, start_null, end_column, end_null)
-      define_method("#{scope_method_name}?") 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
-  end
 end
 
 ActiveSupport.on_load(:active_record) do

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": ["."]
+}

data/sig/in_time_scope.rbs

@@ -1,4 +1,93 @@
+# Type definitions for InTimeScope gem
+
 module InTimeScope
   VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+
+  # Base error class for InTimeScope errors
+  class Error < StandardError
+  end
+
+  # Raised when a specified column does not exist on the table
+  class ColumnNotFoundError < Error
+  end
+
+  # Raised when the scope configuration is invalid
+  class ConfigurationError < Error
+  end
+
+  def self.included: (Class model) -> void
+
+  # Configuration options for start_at column
+  type start_at_config = {
+    ?column: Symbol?,
+    ?null: bool
+  }
+
+  # Configuration options for end_at column
+  type end_at_config = {
+    ?column: Symbol?,
+    ?null: bool
+  }
+
+  # Class methods added to ActiveRecord models when InTimeScope is included
+  module ClassMethods
+    # Defines time-window scopes for the model
+    #
+    # @param scope_name [Symbol] The name of the scope (default: :in_time)
+    # @param start_at [Hash] Configuration for the start column
+    # @param end_at [Hash] Configuration for the end column
+    # @return [void]
+    # @raise [ColumnNotFoundError] When a specified column doesn't exist
+    # @raise [ConfigurationError] When the configuration is invalid (at scope call time)
+    def in_time_scope: (
+      ?Symbol scope_name,
+      ?start_at: start_at_config,
+      ?end_at: end_at_config
+    ) -> void
+
+    private
+
+    # Private implementation methods
+    # These use ActiveRecord internals and are typed as untyped for flexibility
+    def fetch_null_option: (untyped config, untyped column, untyped table_column_hash) -> untyped
+    def define_scope_methods: (String suffix, start_at_column: untyped, start_at_null: untyped, end_at_column: untyped, end_at_null: untyped) -> void
+    def define_error_scope_and_method: (String suffix, String message) -> void
+    def define_start_only_scope: (String suffix, Symbol column) -> void
+    def define_latest_one_scope: (String suffix, Symbol column) -> void
+    def define_earliest_one_scope: (String suffix, Symbol column) -> void
+    def define_end_only_scope: (String suffix, Symbol column) -> void
+    def define_full_scope: (String suffix, Symbol start_column, untyped start_null, Symbol end_column, untyped end_null) -> void
+    def define_instance_method: (String suffix, Symbol? start_column, untyped start_null, Symbol? end_column, untyped end_null) -> void
+    def define_before_scope: (String suffix, Symbol? start_column, untyped start_null) -> void
+    def define_after_scope: (String suffix, Symbol? end_column, untyped end_null) -> void
+    def define_out_of_time_scope: (String suffix) -> void
+  end
+end
+
+# Generated scope methods (dynamically defined)
+# When you call `in_time_scope` on a model, it creates these methods:
+#
+# Class methods (primary - records in time window):
+#   Model.in_time(time = Time.current) -> ActiveRecord::Relation
+#   Model.in_time_<name>(time = Time.current) -> ActiveRecord::Relation  (for named scopes)
+#   Model.latest_in_time(foreign_key, time = Time.current) -> ActiveRecord::Relation  (start-only/end-only)
+#   Model.earliest_in_time(foreign_key, time = Time.current) -> ActiveRecord::Relation (start-only/end-only)
+#
+# Class methods (inverse - records outside time window):
+#   Model.before_in_time(time = Time.current) -> ActiveRecord::Relation  (not yet started)
+#   Model.after_in_time(time = Time.current) -> ActiveRecord::Relation   (already ended)
+#   Model.out_of_time(time = Time.current) -> ActiveRecord::Relation     (before OR after)
+#
+# Instance methods (primary):
+#   model.in_time?(time = Time.current) -> bool
+#   model.in_time_<name>?(time = Time.current) -> bool  (for named scopes)
+#
+# Instance methods (inverse):
+#   model.before_in_time?(time = Time.current) -> bool
+#   model.after_in_time?(time = Time.current) -> bool
+#   model.out_of_time?(time = Time.current) -> bool
+
+# Extend ActiveRecord::Base to include InTimeScope
+class ActiveRecord::Base
+  extend InTimeScope::ClassMethods
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: in_time_scope
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.6
 platform: ruby
 authors:
 - kyohah
 bindir: exe
 cert_chain: []
-date: 2026-01-29 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: irb
   requirement: !ruby/object:Gem::Requirement
@@ -51,6 +51,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rbs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -93,6 +107,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: steep
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: InTimeScope provides time-window scopes for ActiveRecord models.
 email:
 - 3257272+kyohah@users.noreply.github.com
@@ -101,14 +143,40 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".rubocop.yml"
+- ".rulesync/commands/translate-readme.md"
+- ".rulesync/rules/project.md"
 - CHANGELOG.md
-- CLAUDE.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
 - Rakefile
+- Steepfile
+- docs/book.toml
+- docs/de/SUMMARY.md
+- docs/de/index.md
+- docs/de/point-system.md
+- docs/de/user-name-history.md
+- docs/fr/SUMMARY.md
+- docs/fr/index.md
+- docs/fr/point-system.md
+- docs/fr/user-name-history.md
+- docs/ja/SUMMARY.md
+- docs/ja/index.md
+- docs/ja/point-system.md
+- docs/ja/user-name-history.md
+- docs/src/SUMMARY.md
+- docs/src/index.md
+- docs/src/point-system.md
+- docs/src/user-name-history.md
+- docs/zh/SUMMARY.md
+- docs/zh/index.md
+- docs/zh/point-system.md
+- docs/zh/user-name-history.md
 - lib/in_time_scope.rb
+- lib/in_time_scope/class_methods.rb
 - lib/in_time_scope/version.rb
+- rbs_collection.yaml
+- rulesync.jsonc
 - sig/in_time_scope.rbs
 homepage: https://github.com/kyohah/in_time_scope
 licenses:
@@ -126,14 +194,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Add time-window scopes to ActiveRecord models
 test_files: []