in_time_scope 0.1.5 → 0.1.6

data/docs/src/index.md

@@ -0,0 +1,194 @@
+# InTimeScope
+
+Are you writing this every time in Rails?
+
+```ruby
+# Before
+Event.where("start_at <= ? AND (end_at IS NULL OR end_at > ?)", Time.current, Time.current)
+
+# After
+class Event < ActiveRecord::Base
+  in_time_scope
+end
+
+Event.in_time
+```
+
+That's it. One line of DSL, zero raw SQL in your models.
+
+**This is a simple, thin gem that just provides scopes. No learning curve required.**
+
+## Why This Gem?
+
+This gem exists to:
+
+- **Keep time-range logic consistent** across your entire codebase
+- **Avoid copy-paste SQL** that's easy to get wrong
+- **Make time a first-class domain concept** with named scopes like `in_time_published`
+- **Auto-detect nullability** from your schema for optimized queries
+
+## Recommended For
+
+- New Rails applications with validity periods
+- Models with `start_at` / `end_at` columns
+- Teams that want consistent time logic without scattered `where` clauses
+
+## Installation
+
+```bash
+bundle add in_time_scope
+```
+
+## Quick Start
+
+```ruby
+class Event < ActiveRecord::Base
+  in_time_scope
+end
+
+# Class scope
+Event.in_time                          # Records active now
+Event.in_time(Time.parse("2024-06-01")) # Records active at specific time
+
+# Instance method
+event.in_time?                          # Is this record active now?
+event.in_time?(some_time)               # Was it active at that time?
+```
+
+## Features
+
+### Auto-Optimized SQL
+
+The gem reads your schema and generates the right SQL:
+
+```ruby
+# NULL-allowed columns → NULL-aware query
+WHERE (start_at IS NULL OR start_at <= ?) AND (end_at IS NULL OR end_at > ?)
+
+# NOT NULL columns → simple query
+WHERE start_at <= ? AND end_at > ?
+```
+
+### Named Scopes
+
+Multiple time windows per model:
+
+```ruby
+class Article < ActiveRecord::Base
+  in_time_scope :published   # → Article.in_time_published
+  in_time_scope :featured    # → Article.in_time_featured
+end
+```
+
+### Custom Columns
+
+```ruby
+class Campaign < ActiveRecord::Base
+  in_time_scope start_at: { column: :available_at },
+                end_at: { column: :expired_at }
+end
+```
+
+### Start-Only Pattern (Version History)
+
+For records where each row is valid until the next one:
+
+```ruby
+class Price < ActiveRecord::Base
+  in_time_scope start_at: { null: false }, end_at: { column: nil }
+end
+
+# Bonus: efficient has_one with NOT EXISTS
+class User < ActiveRecord::Base
+  has_one :current_price, -> { latest_in_time(:user_id) }, class_name: "Price"
+end
+
+User.includes(:current_price)  # No N+1, fetches only latest per user
+```
+
+### End-Only Pattern (Expiration)
+
+For records that are active until they expire:
+
+```ruby
+class Coupon < ActiveRecord::Base
+  in_time_scope start_at: { column: nil }, end_at: { null: false }
+end
+```
+
+### Inverse Scopes
+
+Query records outside the time window:
+
+```ruby
+# Records not yet started (start_at > time)
+Event.before_in_time
+event.before_in_time?
+
+# Records already ended (end_at <= time)
+Event.after_in_time
+event.after_in_time?
+
+# Records outside time window (before OR after)
+Event.out_of_time
+event.out_of_time?  # Logical inverse of in_time?
+```
+
+Works with named scopes too:
+
+```ruby
+Article.before_in_time_published  # Not yet published
+Article.after_in_time_published   # Publication ended
+Article.out_of_time_published     # Not currently published
+```
+
+## Options Reference
+
+| Option | Default | Description | Example |
+| --- | --- | --- | --- |
+| `scope_name` (1st arg) | `:in_time` | Named scope like `in_time_published` | `in_time_scope :published` |
+| `start_at: { column: }` | `:start_at` | Custom column name, `nil` to disable | `start_at: { column: :available_at }` |
+| `end_at: { column: }` | `:end_at` | Custom column name, `nil` to disable | `end_at: { column: nil }` |
+| `start_at: { null: }` | auto-detect | Force NULL handling | `start_at: { null: false }` |
+| `end_at: { null: }` | auto-detect | Force NULL handling | `end_at: { null: true }` |
+
+## Examples
+
+- [Point System with Expiration](./point-system.md) - Full time window pattern
+- [User Name History](./user-name-history.md) - Start-only pattern
+
+## Acknowledgements
+
+Inspired by [onk/shibaraku](https://github.com/onk/shibaraku). This gem extends the concept with:
+
+- Schema-aware NULL handling for optimized queries
+- Multiple named scopes per model
+- Start-only / End-only patterns
+- `latest_in_time` / `earliest_in_time` for efficient `has_one` associations
+- Inverse scopes: `before_in_time`, `after_in_time`, `out_of_time`
+
+## Development
+
+```bash
+# Install dependencies
+bin/setup
+
+# Run tests
+bundle exec rspec
+
+# Run linting
+bundle exec rubocop
+
+# Generate CLAUDE.md (for AI coding assistants)
+npx rulesync generate
+```
+
+This project uses [rulesync](https://github.com/dyoshikawa/rulesync) to manage AI assistant rules. Edit `.rulesync/rules/*.md` and run `npx rulesync generate` to update `CLAUDE.md`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/kyohah/in_time_scope).
+
+## License
+
+MIT License

data/docs/src/point-system.md

@@ -0,0 +1,295 @@
+# Point System with Expiration Example
+
+This example demonstrates how to implement a point system with expiration dates using `in_time_scope`. Points can be pre-granted to become active in the future, eliminating the need for cron jobs.
+
+See also: [spec/point_system_spec.rb](https://github.com/kyohah/in_time_scope/blob/main/spec/point_system_spec.rb)
+
+## Use Case
+
+- Users earn points with validity periods (start date and expiration date)
+- Points can be pre-granted to activate in the future (e.g., monthly membership bonuses)
+- Calculate valid points at any given time without cron jobs
+- Query upcoming points, expired points, etc.
+
+## No Cron Jobs Required
+
+**This is the killer feature.** Traditional point systems are a nightmare of scheduled jobs:
+
+### The Cron Hell You're Used To
+
+```ruby
+# activate_points_job.rb - runs every minute
+class ActivatePointsJob < ApplicationJob
+  def perform
+    Point.where(status: "pending")
+         .where("start_at <= ?", Time.current)
+         .update_all(status: "active")
+  end
+end
+
+# expire_points_job.rb - runs every minute
+class ExpirePointsJob < ApplicationJob
+  def perform
+    Point.where(status: "active")
+         .where("end_at <= ?", Time.current)
+         .update_all(status: "expired")
+  end
+end
+
+# And then you need:
+# - Sidekiq / Delayed Job / Good Job
+# - Redis (for Sidekiq)
+# - Cron or whenever gem
+# - Monitoring for job failures
+# - Retry logic for failed jobs
+# - Lock mechanisms to prevent duplicate runs
+```
+
+### The InTimeScope Way
+
+```ruby
+# That's it. No jobs. No status column. No infrastructure.
+user.points.in_time.sum(:amount)
+```
+
+**One line. Zero infrastructure. Always accurate.**
+
+### Why This Works
+
+The `start_at` and `end_at` columns ARE the state. There's no need for a `status` column because the time comparison happens at query time:
+
+```ruby
+# These all work without any background processing:
+user.points.in_time                    # Currently valid
+user.points.in_time(1.month.from_now)  # Valid next month
+user.points.in_time(1.year.ago)        # Were valid last year (auditing!)
+user.points.before_in_time             # Pending (not yet active)
+user.points.after_in_time              # Expired
+```
+
+### What You Eliminate
+
+| Component | Cron-Based System | InTimeScope |
+|-----------|------------------|-------------|
+| Background job library | Required | **Not needed** |
+| Redis/database for jobs | Required | **Not needed** |
+| Job scheduler (cron) | Required | **Not needed** |
+| Status column | Required | **Not needed** |
+| Migration to update status | Required | **Not needed** |
+| Monitoring for job failures | Required | **Not needed** |
+| Retry logic | Required | **Not needed** |
+| Race condition handling | Required | **Not needed** |
+
+### Bonus: Time Travel for Free
+
+With cron-based systems, answering "How many points did user X have on January 15th?" requires complex audit logging or event sourcing.
+
+With InTimeScope:
+
+```ruby
+user.points.in_time(Date.parse("2024-01-15").middle_of_day).sum(:amount)
+```
+
+**Historical queries just work.** No extra tables. No event sourcing. No complexity.
+
+## Schema
+
+```ruby
+# Migration
+class CreatePoints < ActiveRecord::Migration[7.0]
+  def change
+    create_table :points do |t|
+      t.references :user, null: false, foreign_key: true
+      t.integer :amount, null: false
+      t.string :reason, null: false
+      t.datetime :start_at, null: false  # When points become usable
+      t.datetime :end_at, null: false    # When points expire
+      t.timestamps
+    end
+
+    add_index :points, [:user_id, :start_at, :end_at]
+  end
+end
+```
+
+## Models
+
+```ruby
+class Point < ApplicationRecord
+  belongs_to :user
+
+  # Both start_at and end_at are required (full time window)
+  in_time_scope start_at: { null: false }, end_at: { null: false }
+end
+
+class User < ApplicationRecord
+  has_many :points
+  has_many :in_time_points, -> { in_time }, class_name: "Point"
+
+  # Grant monthly bonus points (pre-scheduled)
+  def grant_monthly_bonus(amount:, months_valid: 6)
+    points.create!(
+      amount: amount,
+      reason: "Monthly membership bonus",
+      start_at: 1.month.from_now,  # Activates next month
+      end_at: (1 + months_valid).months.from_now
+    )
+  end
+end
+```
+
+### The Power of `has_many :in_time_points`
+
+This simple line unlocks **N+1 free eager loading** for valid points:
+
+```ruby
+# Load 100 users with their valid points in just 2 queries
+users = User.includes(:in_time_points).limit(100)
+
+users.each do |user|
+  # No additional queries! Already loaded.
+  total = user.in_time_points.sum(&:amount)
+  puts "#{user.name}: #{total} points"
+end
+```
+
+Without this association, you'd need:
+
+```ruby
+# N+1 problem: 1 query for users + 100 queries for points
+users = User.limit(100)
+users.each do |user|
+  total = user.points.in_time.sum(:amount)  # Query per user!
+end
+```
+
+## Usage
+
+### Granting Points with Different Validity Periods
+
+```ruby
+user = User.find(1)
+
+# Immediate points (valid for 1 year)
+user.points.create!(
+  amount: 100,
+  reason: "Welcome bonus",
+  start_at: Time.current,
+  end_at: 1.year.from_now
+)
+
+# Pre-scheduled points for 6-month members
+# Points activate next month, valid for 6 months after activation
+user.grant_monthly_bonus(amount: 500, months_valid: 6)
+
+# Campaign points (limited time)
+user.points.create!(
+  amount: 200,
+  reason: "Summer campaign",
+  start_at: Date.parse("2024-07-01").beginning_of_day,
+  end_at: Date.parse("2024-08-31").end_of_day
+)
+```
+
+### Querying Points
+
+```ruby
+# Current valid points
+user.in_time_member_points.sum(:amount)
+# => 100 (only the welcome bonus is currently active)
+
+# Check how many points will be available next month
+user.in_time_member_points(1.month.from_now).sum(:amount)
+# => 600 (welcome bonus + monthly bonus)
+
+# Pending points (scheduled but not yet active)
+user.points.before_in_time.sum(:amount)
+# => 500 (monthly bonus waiting to activate)
+
+# Expired points
+user.points.after_in_time.sum(:amount)
+
+# All invalid points (pending + expired)
+user.points.out_of_time.sum(:amount)
+```
+
+### Admin Dashboard Queries
+
+```ruby
+# Historical audit: points valid on a specific date
+Point.in_time(Date.parse("2024-01-15").middle_of_day)
+     .group(:user_id)
+     .sum(:amount)
+```
+
+## Automatic Membership Bonus Flow
+
+For 6-month premium members, you can set up recurring bonuses **without cron, without Sidekiq, without Redis, without monitoring**:
+
+```ruby
+# When user signs up for premium, create membership and all bonuses atomically
+ActiveRecord::Base.transaction do
+  membership = Membership.create!(user: user, plan: "premium_6_months")
+
+  # Pre-create all 6 monthly bonuses at signup
+  6.times do |month|
+    user.points.create!(
+      amount: 500,
+      reason: "Premium member bonus - Month #{month + 1}",
+      start_at: (month + 1).months.from_now,
+      end_at: (month + 7).months.from_now  # Each bonus valid for 6 months
+    )
+  end
+end
+# => Creates membership + 6 point records that will activate monthly
+```
+
+## Why This Design is Superior
+
+### Correctness
+
+- **No race conditions**: Cron jobs can run twice, skip runs, or overlap. InTimeScope queries are always deterministic.
+- **No timing drift**: Cron runs at intervals (every minute? every 5 minutes?). InTimeScope is accurate to the millisecond.
+- **No lost updates**: Job failures can leave points in wrong states. InTimeScope has no state to corrupt.
+
+### Simplicity
+
+- **No infrastructure**: Delete your Sidekiq. Delete your Redis. Delete your job monitoring.
+- **No migrations for status changes**: The time IS the status. No `UPDATE` statements needed.
+- **No debugging job logs**: Just query the database to see exactly what's happening.
+
+### Testability
+
+```ruby
+# Cron-based testing is painful:
+travel_to 1.month.from_now do
+  ActivatePointsJob.perform_now
+  ExpirePointsJob.perform_now
+  expect(user.points.active.sum(:amount)).to eq(500)
+end
+
+# InTimeScope testing is trivial:
+expect(user.points.in_time(1.month.from_now).sum(:amount)).to eq(500)
+```
+
+### Summary
+
+| Aspect | Cron-Based | InTimeScope |
+|--------|-----------|-------------|
+| Infrastructure | Sidekiq + Redis + Cron | **None** |
+| Point activation | Batch job (delayed) | **Instant** |
+| Historical queries | Impossible without audit log | **Built-in** |
+| Timing accuracy | Minutes (cron interval) | **Milliseconds** |
+| Debugging | Job logs + database | **Database only** |
+| Testing | Time travel + run jobs | **Just query** |
+| Failure modes | Many (job failures, race conditions) | **None** |
+
+## Tips
+
+1. **Use database indexes** on `[user_id, start_at, end_at]` for optimal performance.
+
+2. **Pre-grant points at signup** instead of scheduling cron jobs.
+
+3. **Use `in_time(time)` for audits** to check point balances at any historical time.
+
+4. **Combine with inverse scopes** to build admin dashboards showing pending/expired points.

data/docs/src/user-name-history.md

@@ -0,0 +1,164 @@
+# User Name History Example
+
+This example demonstrates how to manage user name history with `in_time_scope`, allowing you to query a user's name at any point in time.
+
+See also: [spec/user_name_history_spec.rb](https://github.com/kyohah/in_time_scope/blob/main/spec/user_name_history_spec.rb)
+
+## Use Case
+
+- Users can change their display name
+- You need to keep a history of all name changes
+- You want to retrieve the name that was active at a specific time (e.g., for audit logs, historical reports)
+
+## Schema
+
+```ruby
+# Migration
+class CreateUserNameHistories < ActiveRecord::Migration[7.0]
+  def change
+    create_table :users do |t|
+      t.string :email, null: false
+      t.timestamps
+    end
+
+    create_table :user_name_histories do |t|
+      t.references :user, null: false, foreign_key: true
+      t.string :name, null: false
+      t.datetime :start_at, null: false  # When this name became active
+      t.timestamps
+    end
+
+    add_index :user_name_histories, [:user_id, :start_at]
+  end
+end
+```
+
+## Models
+
+```ruby
+class UserNameHistory < ApplicationRecord
+  belongs_to :user
+  include InTimeScope
+
+  # Start-only pattern: each record is valid from start_at until the next record
+  in_time_scope start_at: { null: false }, end_at: { column: nil }
+end
+
+class User < ApplicationRecord
+  has_many :user_name_histories
+
+  # Get the current name (latest record that has started)
+  has_one :current_name_history,
+          -> { latest_in_time(:user_id) },
+          class_name: "UserNameHistory"
+
+  # Convenience method for current name
+  def current_name
+    current_name_history&.name
+  end
+
+  # Get name at a specific time
+  def name_at(time)
+    user_name_histories.in_time(time).order(start_at: :desc).first&.name
+  end
+end
+```
+
+## Usage
+
+### Creating Name History
+
+```ruby
+user = User.create!(email: "alice@example.com")
+
+# Initial name
+UserNameHistory.create!(
+  user: user,
+  name: "Alice",
+  start_at: Time.parse("2024-01-01")
+)
+
+# Name change
+UserNameHistory.create!(
+  user: user,
+  name: "Alice Smith",
+  start_at: Time.parse("2024-06-01")
+)
+
+# Another name change
+UserNameHistory.create!(
+  user: user,
+  name: "Alice Johnson",
+  start_at: Time.parse("2024-09-01")
+)
+```
+
+### Querying Names
+
+```ruby
+# Current name (uses has_one with latest_in_time)
+user.current_name
+# => "Alice Johnson"
+
+# Name at a specific time
+user.name_at(Time.parse("2024-03-15"))
+# => "Alice"
+
+user.name_at(Time.parse("2024-07-15"))
+# => "Alice Smith"
+
+user.name_at(Time.parse("2024-10-15"))
+# => "Alice Johnson"
+```
+
+### Efficient Eager Loading
+
+```ruby
+# Load users with their current names (no N+1)
+users = User.includes(:current_name_history).limit(100)
+
+users.each do |user|
+  puts "#{user.email}: #{user.current_name_history&.name}"
+end
+```
+
+### Querying Active Records
+
+```ruby
+# All name records that are currently active
+UserNameHistory.in_time
+# => Returns the latest name record for each user
+
+# Name records that were active at a specific time
+UserNameHistory.in_time(Time.parse("2024-05-01"))
+
+# Name records not yet started (scheduled for future)
+UserNameHistory.before_in_time
+```
+
+## How `latest_in_time` Works
+
+The `latest_in_time(:user_id)` scope generates an efficient `NOT EXISTS` subquery:
+
+```sql
+SELECT * FROM user_name_histories AS h
+WHERE h.start_at <= '2024-10-01'
+  AND NOT EXISTS (
+    SELECT 1 FROM user_name_histories AS newer
+    WHERE newer.user_id = h.user_id
+      AND newer.start_at <= '2024-10-01'
+      AND newer.start_at > h.start_at
+  )
+```
+
+This returns only the most recent record per user that was active at the given time, making it perfect for `has_one` associations.
+
+## Tips
+
+1. **Always use `latest_in_time` with `has_one`** - It ensures you get exactly one record per foreign key.
+
+2. **Add a composite index** on `[user_id, start_at]` for optimal query performance.
+
+3. **Use `includes` for eager loading** - The `NOT EXISTS` pattern works efficiently with Rails eager loading.
+
+4. **Consider adding a unique constraint** on `[user_id, start_at]` to prevent duplicate records at the same time.

data/docs/zh/SUMMARY.md

@@ -0,0 +1,5 @@
+# 目录
+
+- [简介](./index.md)
+- [带有效期的积分系统](./point-system.md)
+- [用户名历史](./user-name-history.md)