in_time_scope 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ae5a251a71cec0f0ad9ac7890d9e1e88de46dade545cbfcff2cf0201d603939
-  data.tar.gz: 9a4c17e7f1ad5a1b62ebf37038332d43a7610fcce5f770e66df70e51670dc415
+  metadata.gz: c5ab9dff9b5a5abce4d0418d2a8ec3895126a910a0926f1a449fc55bad3cebd4
+  data.tar.gz: '082a9f889d860c0dc7f587fafb77baaa932ccc864e8dfe06b10b92ab9644308a'
 SHA512:
-  metadata.gz: 4480bbfaee296c29a87e96b26c2f32f29a78792712765cb48b51699c01bc552526ab1764972bd6cb19bfa4ce5de115abd099a7d0abf8701a26fa69eedc780d6e
-  data.tar.gz: b905e3bf65da95f7b4868e49c386051616b071cd67de613617d0443caa4679cbb4cc0c729ca9b6ec2776a32af4cfda32deedd48d61ceca4d326c833748b382a4
+  metadata.gz: 7df8620094c225af106a3ed909dfa3af5abd328630e1a571cbe0943ecf5a8f965bc1c56286493181305a44fc87a148b055247c12291ee9110b49ca700b45b1bc
+  data.tar.gz: 7dc373ec631d291cbdb9c73acaec4bc21d5271495a1131681a3a8aa6929480a28a886010eb3bcc209951825b5c92590a13730aae7ec119a09d96fb66d17f8218

data/README.md

@@ -1,8 +1,6 @@
 # InTimeScope
 
-TODO: Delete this and the text below, and describe your gem
-
-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.
+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.
 
 ## Installation
 
@@ -39,11 +37,10 @@ class Event < ActiveRecord::Base
 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,11 +65,11 @@ 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
@@ -113,20 +110,16 @@ class Event < ActiveRecord::Base
 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:
 
@@ -152,15 +145,7 @@ class Event < ActiveRecord::Base
 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" IS NULL OR "events"."end_at" > '2024-06-01 12:00:00.000000')
 ```
 
 Recommended index:
@@ -216,7 +201,7 @@ Event.published_in_time
 
 ### Using with `has_one` Associations
 
-The start-only pattern provides two scopes for `has_one` associations:
+The start-only pattern provides scopes for `has_one` associations:
 
 #### Simple approach: `in_time` + `order`
 
@@ -266,6 +251,46 @@ 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
+  include InTimeScope
+
+  # 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/lib/in_time_scope/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module InTimeScope
-  VERSION = "0.1.2"
+  VERSION = "0.1.4"
 end

data/lib/in_time_scope.rb

@@ -5,96 +5,88 @@ require_relative "in_time_scope/version"
 
 module InTimeScope
   class Error < StandardError; end
+  class ColumnNotFoundError < Error; end
+  class ConfigurationError < Error; end
 
   def self.included(model)
     model.extend ClassMethods
   end
 
   module ClassMethods
-    def in_time_scope(scope_name = nil, start_at: {}, end_at: {}, prefix: false)
-      scope_name ||= :in_time
-      scope_prefix = scope_name == :in_time ? "" : "#{scope_name}_"
+    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_config = normalize_config(start_at, :"#{scope_prefix}start_at")
-      end_config = normalize_config(end_at, :"#{scope_prefix}end_at")
+      start_at_column = start_at.fetch(:column, :"#{time_column_prefix}start_at")
+      end_at_column = end_at.fetch(:column, :"#{time_column_prefix}end_at")
 
-      define_scope_methods(scope_name, start_config, end_config, prefix)
+      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 normalize_config(config, default_column)
-      return { column: nil, null: true } if config[:column].nil? && config.key?(:column)
-
-      column = config[:column] || default_column
-      column = nil unless column_names.include?(column.to_s)
+    def fetch_null_option(config, column, table_column_hash)
+      return nil if column.nil?
+      return config[:null] if config.key?(:null)
 
-      null = config.key?(:null) ? config[:null] : column_nullable?(column)
+      column_info = table_column_hash[column.to_s]
+      raise ColumnNotFoundError, "Column '#{column}' does not exist on table '#{table_name}'" if column_info.nil?
 
-      { column: column, null: null }
+      column_info.null
     end
 
-    def column_nullable?(column_name)
-      return true if column_name.nil?
+    def method_name(scope_name, prefix)
+      return :in_time if scope_name == :in_time
 
-      col = columns_hash[column_name.to_s]
-      col ? col.null : true
+      prefix ? "#{scope_name}_in_time" : "in_time_#{scope_name}"
     end
 
-    def define_scope_methods(scope_name, start_config, end_config, prefix)
-      method_name = if scope_name == :in_time
-                      :in_time
-                    elsif prefix
-                      :"#{scope_name}_in_time"
-                    else
-                      :"in_time_#{scope_name}"
-                    end
-      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]
-
+    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_column.nil? && end_column.nil?
+      if start_at_column.nil? && end_at_column.nil?
         # Both disabled - return all
-        scope method_name, ->(_time = Time.current) { all }
-      elsif end_column.nil?
+        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(method_name, start_column, start_null)
-      elsif start_column.nil?
+        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(method_name, end_column, end_null)
+        define_end_only_scope(scope_method_name, end_at_column, end_at_null)
       else
         # Both start and end
-        define_full_scope(method_name, start_column, start_null, end_column, end_null)
+        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(instance_method_name, start_column, start_null, end_column, end_null)
+      define_instance_method(scope_method_name, start_at_column, start_at_null, end_at_column, end_at_null)
     end
 
-    def define_start_only_scope(method_name, start_column, start_null)
+    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 method_name, ->(time = Time.current) {
+        scope 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) {
+        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_scope(method_name, start_column, start_null)
+      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_scope(method_name, start_column, start_null)
-      latest_method_name = method_name == :in_time ? :latest_in_time : :"latest_#{method_name}"
+    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
 
@@ -137,20 +129,59 @@ module InTimeScope
       }
     end
 
-    def define_end_only_scope(method_name, end_column, end_null)
+    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 method_name, ->(time = Time.current) {
+        scope 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) {
+        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(method_name, start_column, start_null, end_column, end_null)
-      scope method_name, ->(time = Time.current) {
+    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
@@ -165,10 +196,13 @@ module InTimeScope
 
         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(method_name, start_column, start_null, end_column, end_null)
-      define_method(method_name) do |time = Time.current|
+    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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: in_time_scope
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.4
 platform: ruby
 authors:
 - kyohah