in_time_scope 0.1.0 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eee76cde212cee461aa7b915b048c5479bc1adc82faa1a57fc4d10e136806eb6
-  data.tar.gz: b6de2422411c951e2e1cf3029498755b77c9de73731ed9e24d3d20c0df612d79
+  metadata.gz: 3938b69e9b635a2d488513fbba9a0af9171e163accf5a776357f837f93783830
+  data.tar.gz: eb16bb16cb6681cc8ffa67b10aa32b8e349f5df87734436a6e5d8ff7afebd26a
 SHA512:
-  metadata.gz: 9d9daa7dc0815efde3c0d6a0d6231da6799526fa17be1c96bc22cb76f460ce7e4c84f40ae449760a5e24e86177632b174c94ecf13ec0d3240cae9c4a39ad5721
-  data.tar.gz: 337490e629eca19edec0fe0615ee895f67e475258281a173c61e10cf8014a4f185ae72c48fbc07065d7ae29c0b6e9016b547827b83556a4d8c6be3c79c95ec04
+  metadata.gz: 0cea4dc04116f248f8343902d9aeeb875e6a3cac9dc6c772a9462daea7d99a526862d715af5e94fa45826896ab5cd832a55b7f31fb7b1a94e12649a0ea059984
+  data.tar.gz: e55bc250bd8d38b6cc7fb5a2b1d81d808948244defe93aa4715fb052967f8b3318d62b5dd58e614b03ddaf528a3ddb7ef4ae07786f9dbc67e2eced0c28065d9d

data/.rubocop.yml

@@ -1,5 +1,5 @@
 AllCops:
-  TargetRubyVersion: 3.1
+  TargetRubyVersion: 3.0
   NewCops: enable
   SuggestExtensions: false
 

data/README.md

@@ -1,8 +1,17 @@
 # InTimeScope
 
-TODO: Delete this and the text below, and describe your gem
+A Ruby gem that adds time-window scopes to ActiveRecord models. It provides a convenient way to query records that fall within specific time periods (between `start_at` and `end_at` timestamps), with support for nullable columns, custom column names, and multiple scopes per model.
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/in_time_scope`. To experiment with that code, run `bin/console` for an interactive prompt.
+## Motivation
+
+This gem is inspired by [onk/shibaraku](https://github.com/onk/shibaraku). While shibaraku is a great gem, I wanted to extend it with additional features:
+
+- **Nullable column handling**: shibaraku generates SQL with `OR` conditions when columns allow `NULL`, which can impact query performance. InTimeScope auto-detects column nullability from the schema and generates optimized queries.
+- **Named scopes**: shibaraku only provides `in_time` method. InTimeScope allows multiple named scopes like `in_time_published`, `in_time_featured` per model.
+- **Start-only / End-only patterns**: Support for versioned records (start_at only, no end_at) and expiration patterns (end_at only, no start_at).
+- **has_one association support**: `latest_in_time` and `earliest_in_time` scopes optimized for `has_one` with `includes`, using NOT EXISTS subqueries.
+
+These features required significant architectural changes, so I created a new gem rather than extending shibaraku.
 
 ## Installation
 
@@ -32,18 +41,15 @@ create_table :events do |t|
 end
 
 class Event < ActiveRecord::Base
-  include InTimeScope
-
   # Uses start_at / end_at by default
   in_time_scope
 end
 
 Event.in_time
-# => SELECT "events".* FROM "events" WHERE ("events"."start_at" IS NULL OR "events"."start_at" <= '2026-01-24 19:50:05.738232') AND ("events"."end_at" IS NULL OR "events"."end_at" > '2026-01-24 19:50:05.738232') /* loading for pp */ LIMIT $1  [["LIMIT", 11]]
+# => SELECT "events".* FROM "events" WHERE ("events"."start_at" IS NULL OR "events"."start_at" <= '2026-01-24 19:50:05.738232') AND ("events"."end_at" IS NULL OR "events"."end_at" > '2026-01-24 19:50:05.738232')
 
 # Check at a specific time
 Event.in_time(Time.parse("2024-06-01 12:00:00"))
-# => SELECT "events".* FROM "events" WHERE ("events"."start_at" IS NULL OR "events"."start_at" <= '2024-06-01 12:00:00.000000') AND ("events"."end_at" IS NULL OR "events"."end_at" > '2024-06-01 12:00:00.000000') /* loading for pp */ LIMIT $1  [["LIMIT", 11]]
 
 # Is the current time within the window?
 event = Event.first
@@ -68,15 +74,13 @@ end
 
 # Column metadata is read when Rails boots; SQL is optimized for NOT NULL columns.
 Event.in_time
-# => SELECT "events".* FROM "events" WHERE ("events"."start_at" <= '2026-01-24 19:50:05.738232') AND ("events"."end_at" > '2026-01-24 19:50:05.738232') /* loading for pp */ LIMIT $1  [["LIMIT", 11]]
+# => SELECT "events".* FROM "events" WHERE ("events"."start_at" <= '2026-01-24 19:50:05.738232') AND ("events"."end_at" > '2026-01-24 19:50:05.738232')
 
 # Check at a specific time
 Event.in_time(Time.parse("2024-06-01 12:00:00"))
-# => SELECT "events".* FROM "events" WHERE ("events"."start_at" <= '2024-06-01 12:00:00.000000') AND ("events"."end_at" > '2024-06-01 12:00:00.000000') /* loading for pp */ LIMIT $1  [["LIMIT", 11]]
+# => SELECT "events".* FROM "events" WHERE ("events"."start_at" <= '2024-06-01 12:00:00.000000') AND ("events"."end_at" > '2024-06-01 12:00:00.000000')
 
 class Event < ActiveRecord::Base
-  include InTimeScope
-
   # Explicitly mark columns as NOT NULL (even if the DB allows NULL)
   in_time_scope start_at: { null: false }, end_at: { null: false }
 end
@@ -87,17 +91,18 @@ Use these options in `in_time_scope` to customize column behavior.
 
 | Option | Applies to | Type | Default | Description | Example |
 | --- | --- | --- | --- | --- | --- |
-| `:scope_name` (1st arg) | in_time | `Symbol` | `:in_time` | Creates a named scope like `published_in_time` | `in_time_scope :published` |
+| `:scope_name` (1st arg) | in_time | `Symbol` | `:in_time` | Creates a named scope like `in_time_published` | `in_time_scope :published` |
 | `start_at: { column: ... }` | start_at | `Symbol` / `nil` | `:start_at` (or `:"<scope>_start_at"` when `:scope_name` is set) | Use a custom column name; set `nil` to disable `start_at` | `start_at: { column: :available_at }` |
 | `end_at: { column: ... }` | end_at | `Symbol` / `nil` | `:end_at` (or `:"<scope>_end_at"` when `:scope_name` is set) | Use a custom column name; set `nil` to disable `end_at` | `end_at: { column: nil }` |
 | `start_at: { null: ... }` | start_at | `true/false` | auto (schema) | Force NULL-aware vs NOT NULL behavior | `start_at: { null: false }` |
 | `end_at: { null: ... }` | end_at | `true/false` | auto (schema) | Force NULL-aware vs NOT NULL behavior | `end_at: { null: true }` |
+| `prefix: true` | scope_name | `true/false` | `false` | Use prefix style method name like `published_in_time` instead of `in_time_published` | `in_time_scope :published, prefix: true` |
 
 ### Alternative: Start-Only History (No `end_at`)
 Use this when periods never overlap and you want exactly one "current" row.
 
-Assumptions:
-- `start_at` is always present
+**Requirements:**
+- `start_at` must be NOT NULL (a `ConfigurationError` is raised otherwise)
 - periods never overlap (validated)
 - the latest row is the current one
 
@@ -105,27 +110,21 @@ If your table still has an `end_at` column but you want to ignore it, disable it
 
 ```ruby
 class Event < ActiveRecord::Base
-  include InTimeScope
-
   # Ignore end_at even if the column exists
   in_time_scope start_at: { null: false }, end_at: { column: nil }
 end
 
 Event.in_time(Time.parse("2024-06-01 12:00:00"))
-# => SELECT "events".* FROM "events" WHERE "events"."start_at" <= '2024-06-01 12:00:00.000000' ORDER BY "events"."start_at" DESC
+# => SELECT "events".* FROM "events" WHERE "events"."start_at" <= '2024-06-01 12:00:00.000000'
 
-# Use .first to get the most recent single record
-Event.in_time.first
-# => SELECT "events".* FROM "events" WHERE "events"."start_at" <= '...' ORDER BY "events"."start_at" DESC LIMIT 1
+# Use .first with order to get the most recent single record
+Event.in_time.order(start_at: :desc).first
 ```
 
 With no `end_at`, each row implicitly ends at the next row's `start_at`.
-The scope returns all matching records ordered by `start_at DESC`, so:
-- Use `.first` for a single record
-- Use with `has_one` associations for per-parent record selection
-
-Boundary behavior is stable:
-- `start_at <= NOW()` picks the newest row whose start has passed
+The scope returns all matching records (WHERE only, no ORDER), so:
+- Add `.order(start_at: :desc).first` for a single latest record
+- Use `latest_in_time` for efficient `has_one` associations
 
 Recommended index:
 
@@ -136,30 +135,20 @@ CREATE INDEX index_events_on_start_at ON events (start_at);
 ### Alternative: End-Only Expiration (No `start_at`)
 Use this when a record is active immediately and expires at `end_at`.
 
-Assumptions:
+**Requirements:**
+- `end_at` must be NOT NULL (a `ConfigurationError` is raised otherwise)
 - `start_at` is not used (implicit "always active")
-- `end_at` can be `NULL` for "never expires"
 
 If your table still has a `start_at` column but you want to ignore it, disable it via options:
 
 ```ruby
 class Event < ActiveRecord::Base
-  include InTimeScope
-
   # Ignore start_at and only use end_at
-  in_time_scope start_at: { column: nil }, end_at: { null: true }
+  in_time_scope start_at: { column: nil }, end_at: { null: false }
 end
 
 Event.in_time(Time.parse("2024-06-01 12:00:00"))
-# => SELECT "events".* FROM "events" WHERE ("events"."end_at" IS NULL OR "events"."end_at" > '2024-06-01 12:00:00.000000') /* loading for pp */ LIMIT $1  [["LIMIT", 11]]
-```
-
-To fetch active rows:
-
-```sql
-SELECT *
-FROM events
-WHERE end_at IS NULL OR end_at > NOW();
+# => SELECT "events".* FROM "events" WHERE "events"."end_at" > '2024-06-01 12:00:00.000000'
 ```
 
 Recommended index:
@@ -175,32 +164,45 @@ Customize which columns are used and define more than one time window per model.
 create_table :events do |t|
   t.datetime :available_at, null: true
   t.datetime :expired_at, null: true
-  t.datetime :publish_start_at, null: false
-  t.datetime :publish_end_at, null: false
+  t.datetime :published_start_at, null: false
+  t.datetime :published_end_at, null: false
 
   t.timestamps
 end
 
 class Event < ActiveRecord::Base
-  include InTimeScope
-
   # Use different column names
   in_time_scope start_at: { column: :available_at }, end_at: { column: :expired_at }
 
-  # Define an additional scope
-  in_time_scope :published, start_at: { column: :publish_start_at, null: false }, end_at: { column: :publish_end_at, null: false }
+  # Define an additional scope - uses published_start_at / published_end_at by default
+  in_time_scope :published
 end
 
 Event.in_time
 # => uses available_at / expired_at
 
+Event.in_time_published
+# => uses published_start_at / published_end_at
+```
+
+### Using `prefix: true` Option
+Use the `prefix: true` option if you prefer the scope name as a prefix instead of suffix.
+
+```ruby
+class Event < ActiveRecord::Base
+  # With prefix: true, the method name becomes published_in_time instead of in_time_published
+  in_time_scope :published, prefix: true
+end
+
 Event.published_in_time
-# => uses publish_start_at / publish_end_at
+# => uses published_start_at / published_end_at
 ```
 
 ### Using with `has_one` Associations
 
-The start-only pattern provides two scopes for `has_one` associations:
+The start-only and end-only patterns provide `latest_in_time` and `earliest_in_time` scopes for efficient `has_one` associations.
+
+**Note:** These scopes are NOT available for full time window patterns (both `start_at` and `end_at`), because the concept of "latest" or "earliest" is ambiguous when there's a time range.
 
 #### Simple approach: `in_time` + `order`
 
@@ -208,7 +210,6 @@ The start-only pattern provides two scopes for `has_one` associations:
 
 ```ruby
 class Price < ActiveRecord::Base
-  include InTimeScope
   belongs_to :user
 
   in_time_scope start_at: { null: false }, end_at: { column: nil }
@@ -250,6 +251,44 @@ end
 
 The `latest_in_time(:foreign_key)` scope uses a `NOT EXISTS` subquery to filter at the database level, avoiding loading unnecessary records into memory.
 
+#### Getting the earliest record: `earliest_in_time`
+
+```ruby
+class User < ActiveRecord::Base
+  has_many :prices
+
+  # Uses NOT EXISTS subquery - only loads the earliest record per user
+  has_one :first_price,
+          -> { earliest_in_time(:user_id) },
+          class_name: "Price"
+end
+
+# Direct access
+user.first_price
+# => Returns the earliest price where start_at <= Time.current
+
+# Efficient with includes
+User.includes(:first_price).each do |user|
+  puts user.first_price&.amount
+end
+```
+
+The `earliest_in_time(:foreign_key)` scope uses a `NOT EXISTS` subquery to find records where no earlier record exists for the same foreign key.
+
+### Error Handling
+
+If you specify a scope name but the expected columns don't exist, a `ColumnNotFoundError` is raised at class load time:
+
+```ruby
+class Event < ActiveRecord::Base
+  # This will raise ColumnNotFoundError if hoge_start_at or hoge_end_at columns don't exist
+  in_time_scope :hoge
+end
+# => InTimeScope::ColumnNotFoundError: Column 'hoge_start_at' does not exist on table 'events'
+```
+
+This helps catch configuration errors early during development.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/Steepfile

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# Steepfile for InTimeScope type checking
+
+target :lib do
+  signature "sig"
+
+  check "lib"
+
+  # Use RBS collection for external gem types
+  collection_config "rbs_collection.yaml"
+
+  # Configure libraries
+  library "time"
+
+  # Ignore implementation details that use ActiveRecord internals
+  # The public API is properly typed, but internal methods use
+  # dynamic ActiveRecord features that are hard to type statically
+  configure_code_diagnostics do |hash|
+    # Allow untyped method calls for ActiveRecord dynamic methods
+    hash[Steep::Diagnostic::Ruby::NoMethod] = :hint
+    hash[Steep::Diagnostic::Ruby::UnknownInstanceVariable] = :hint
+    hash[Steep::Diagnostic::Ruby::RequiredBlockMissing] = :hint
+  end
+end

data/lib/in_time_scope/class_methods.rb

@@ -0,0 +1,345 @@
+# frozen_string_literal: true
+
+module InTimeScope
+  # Class methods added to ActiveRecord models when InTimeScope 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)
+    #
+    # @param prefix [Boolean] If true, creates +<scope_name>_in_time+ instead of +in_time_<scope_name>+
+    #
+    # @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: {}, 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_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
+
+    # Generates the method name for the scope
+    #
+    # @param scope_name [Symbol] The scope name
+    # @param prefix [Boolean] Whether to use prefix style
+    # @return [Symbol] The generated method name
+    # @api private
+    def method_name(scope_name, prefix)
+      return :in_time if scope_name == :in_time
+
+      prefix ? "#{scope_name}_in_time" : "in_time_#{scope_name}"
+    end
+
+    # Defines the appropriate scope methods based on configuration
+    #
+    # @param scope_method_name [Symbol] The name of the scope method to create
+    # @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(scope_method_name, 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(scope_method_name,
+                                      "At least one of start_at or end_at must be specified")
+      elsif end_at_column.nil?
+        # Start-only pattern (history tracking) - requires non-nullable column
+        if start_at_null
+          define_error_scope_and_method(scope_method_name,
+                                        "Start-only pattern requires non-nullable column. " \
+                                        "Set `start_at: { null: false }` or add an end_at column")
+        else
+          define_start_only_scope(scope_method_name, start_at_column)
+          define_instance_method(scope_method_name, start_at_column, start_at_null, end_at_column, end_at_null)
+        end
+      elsif start_at_column.nil?
+        # End-only pattern (expiration) - requires non-nullable column
+        if end_at_null
+          define_error_scope_and_method(scope_method_name,
+                                        "End-only pattern requires non-nullable column. " \
+                                        "Set `end_at: { null: false }` or add a start_at column")
+        else
+          define_end_only_scope(scope_method_name, end_at_column)
+          define_instance_method(scope_method_name, start_at_column, start_at_null, end_at_column, end_at_null)
+        end
+      else
+        # Both start and end
+        define_full_scope(scope_method_name, start_at_column, start_at_null, end_at_column, end_at_null)
+        define_instance_method(scope_method_name, start_at_column, start_at_null, end_at_column, end_at_null)
+      end
+    end
+
+    # Defines a scope and instance method that raise ConfigurationError
+    #
+    # @param scope_method_name [Symbol] The name of the scope method
+    # @param message [String] The error message
+    # @return [void]
+    # @api private
+    def define_error_scope_and_method(scope_method_name, message)
+      err_message = message
+
+      scope scope_method_name, ->(_time = Time.current) {
+        raise InTimeScope::ConfigurationError, err_message
+      }
+
+      define_method("#{scope_method_name}?") do |_time = Time.current|
+        raise InTimeScope::ConfigurationError, err_message
+      end
+    end
+
+    # Defines a start-only scope (for history tracking pattern)
+    #
+    # @param scope_method_name [Symbol] The name of the scope method
+    # @param column [Symbol] The start column name
+    # @return [void]
+    # @api private
+    def define_start_only_scope(scope_method_name, column)
+      col = column
+
+      # Simple scope - WHERE only, no ORDER BY
+      # Users can add .order(start_at: :desc) externally if needed
+      scope scope_method_name, ->(time = Time.current) {
+        where(col => ..time)
+      }
+
+      # 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, column)
+      define_earliest_one_scope(scope_method_name, column)
+    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.
+    #
+    # @param scope_method_name [Symbol] The base scope method name
+    # @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(scope_method_name, column)
+      latest_method_name = scope_method_name == :in_time ? :latest_in_time : :"latest_#{scope_method_name}"
+      col = column
+
+      # NOT EXISTS approach: select records where no later record exists for the same foreign key
+      scope latest_method_name, ->(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[col].lteq(time))
+                                      .where(p2[col].gt(arel_table[col]))
+                                      .where(p2[:id].not_eq(arel_table[:id]))
+
+        not_exists = Arel::Nodes::Not.new(Arel::Nodes::Exists.new(subquery.ast))
+
+        where(col => ..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.
+    #
+    # @param scope_method_name [Symbol] The base scope method name
+    # @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(scope_method_name, column)
+      earliest_method_name = scope_method_name == :in_time ? :earliest_in_time : :"earliest_#{scope_method_name}"
+      col = column
+
+      # NOT EXISTS approach: select records where no earlier record exists for the same foreign key
+      scope earliest_method_name, ->(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[col].lteq(time))
+                                      .where(p2[col].lt(arel_table[col]))
+                                      .where(p2[:id].not_eq(arel_table[:id]))
+
+        not_exists = Arel::Nodes::Not.new(Arel::Nodes::Exists.new(subquery.ast))
+
+        where(col => ..time).where(not_exists)
+      }
+    end
+
+    # Defines an end-only scope (for expiration pattern)
+    #
+    # @param scope_method_name [Symbol] The name of the scope method
+    # @param column [Symbol] The end column name
+    # @return [void]
+    # @api private
+    def define_end_only_scope(scope_method_name, column)
+      col = column
+
+      scope scope_method_name, ->(time = Time.current) {
+        where.not(col => ..time)
+      }
+
+      # Efficient scope for has_one + includes using NOT EXISTS subquery
+      define_latest_one_scope(scope_method_name, column)
+      define_earliest_one_scope(scope_method_name, column)
+    end
+
+    # Defines a full scope with both start and end columns
+    #
+    # @param scope_method_name [Symbol] The name of the scope method
+    # @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(scope_method_name, start_column, start_null, end_column, end_null)
+      s_col = start_column
+      e_col = end_column
+
+      scope scope_method_name, ->(time = Time.current) {
+        start_scope = if start_null
+                        where(s_col => nil).or(where(s_col => ..time))
+                      else
+                        where(s_col => ..time)
+                      end
+
+        end_scope = if end_null
+                      where(e_col => nil).or(where.not(e_col => ..time))
+                    else
+                      where.not(e_col => ..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 scope_method_name [Symbol] The name of the scope method
+    # @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(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

data/lib/in_time_scope/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module InTimeScope
-  VERSION = "0.1.0"
+  # The current version of the InTimeScope gem
+  VERSION = "0.1.5"
 end

data/lib/in_time_scope.rb

@@ -2,187 +2,128 @@
 
 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
 
-  def self.included(model)
-    model.extend ClassMethods
-  end
-
-  module ClassMethods
-    def in_time_scope(scope_name = nil, start_at: {}, end_at: {})
-      scope_name ||= :in_time
-      scope_suffix = scope_name == :in_time ? "" : "_#{scope_name}"
-
-      start_config = normalize_config(start_at, :"start_at#{scope_suffix}", :start_at)
-      end_config = normalize_config(end_at, :"end_at#{scope_suffix}", :end_at)
-
-      define_scope_methods(scope_name, start_config, end_config)
-    end
-
-    private
-
-    def normalize_config(config, default_column, fallback_column)
-      return { column: nil, null: true } if config[:column].nil? && config.key?(:column)
-
-      column = config[:column] || default_column
-      column = fallback_column unless column_names.include?(column.to_s)
-      column = nil unless column_names.include?(column.to_s)
-
-      null = config.key?(:null) ? config[:null] : column_nullable?(column)
-
-      { column: column, null: null }
-    end
-
-    def column_nullable?(column_name)
-      return true if column_name.nil?
-
-      col = columns_hash[column_name.to_s]
-      col ? col.null : true
-    end
-
-    def define_scope_methods(scope_name, start_config, end_config)
-      method_name = scope_name == :in_time ? :in_time : :"#{scope_name}_in_time"
-      instance_method_name = :"#{method_name}?"
-
-      start_column = start_config[:column]
-      start_null = start_config[:null]
-      end_column = end_config[:column]
-      end_null = end_config[:null]
+  # Raised when a specified column does not exist on the table
+  # @note This error is raised at class load time
+  class ColumnNotFoundError < Error; end
 
-      # Define class-level scope
-      if start_column.nil? && end_column.nil?
-        # Both disabled - return all
-        scope method_name, ->(_time = Time.current) { all }
-      elsif end_column.nil?
-        # Start-only pattern (history tracking)
-        define_start_only_scope(method_name, start_column, start_null)
-      elsif start_column.nil?
-        # End-only pattern (expiration)
-        define_end_only_scope(method_name, end_column, end_null)
-      else
-        # Both start and end
-        define_full_scope(method_name, start_column, start_null, end_column, end_null)
-      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
 
-      # Define instance method
-      define_instance_method(instance_method_name, start_column, start_null, end_column, end_null)
-    end
-
-    def define_start_only_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 method_name, ->(time = Time.current) {
-          where(arel_table[start_column].eq(nil).or(arel_table[start_column].lteq(time)))
-        }
-      else
-        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_scope(method_name, start_column, start_null)
-    end
-
-    def define_latest_scope(method_name, start_column, start_null)
-      latest_method_name = method_name == :in_time ? :latest_in_time : :"latest_#{method_name}_in_time"
-      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_end_only_scope(method_name, end_column, end_null)
-      if end_null
-        scope method_name, ->(time = Time.current) {
-          where(arel_table[end_column].eq(nil).or(arel_table[end_column].gt(time)))
-        }
-      else
-        scope method_name, ->(time = Time.current) {
-          where(arel_table[end_column].gt(time))
-        }
-      end
-    end
-
-    def define_full_scope(method_name, start_column, start_null, end_column, end_null)
-      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)
-      }
-    end
-
-    def define_instance_method(method_name, start_column, start_null, end_column, end_null)
-      define_method(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
+  # @api private
+  def self.included(model)
+    model.extend ClassMethods
   end
 end
 

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/sig/in_time_scope.rbs

@@ -1,4 +1,83 @@
+# 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
+    # @param prefix [Boolean] If true, creates prefix-style method names
+    # @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,
+      ?prefix: bool
+    ) -> 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 method_name: (Symbol scope_name, bool prefix) -> (Symbol | String)
+    def define_scope_methods: (untyped scope_method_name, start_at_column: untyped, start_at_null: untyped, end_at_column: untyped, end_at_null: untyped) -> void
+    def define_error_scope_and_method: (untyped scope_method_name, String message) -> void
+    def define_start_only_scope: (untyped scope_method_name, Symbol column) -> void
+    def define_latest_one_scope: (untyped scope_method_name, Symbol column) -> void
+    def define_earliest_one_scope: (untyped scope_method_name, Symbol column) -> void
+    def define_end_only_scope: (untyped scope_method_name, Symbol column) -> void
+    def define_full_scope: (untyped scope_method_name, Symbol start_column, untyped start_null, Symbol end_column, untyped end_null) -> void
+    def define_instance_method: (untyped scope_method_name, Symbol? start_column, untyped start_null, Symbol? end_column, untyped end_null) -> void
+  end
+end
+
+# Generated scope methods (dynamically defined)
+# When you call `in_time_scope` on a model, it creates these methods:
+#
+# Class methods:
+#   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)
+#
+# Instance methods:
+#   model.in_time?(time = Time.current) -> bool
+#   model.in_time_<name>?(time = Time.current) -> bool  (for named scopes)
+
+# 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.0
+  version: 0.1.5
 platform: ruby
 authors:
 - kyohah
 bindir: exe
 cert_chain: []
-date: 2026-01-24 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
@@ -107,8 +149,11 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- Steepfile
 - lib/in_time_scope.rb
+- lib/in_time_scope/class_methods.rb
 - lib/in_time_scope/version.rb
+- rbs_collection.yaml
 - sig/in_time_scope.rbs
 homepage: https://github.com/kyohah/in_time_scope
 licenses:
@@ -126,14 +171,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: []