in_time_scope 0.1.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3938b69e9b635a2d488513fbba9a0af9171e163accf5a776357f837f93783830
-  data.tar.gz: eb16bb16cb6681cc8ffa67b10aa32b8e349f5df87734436a6e5d8ff7afebd26a
+  metadata.gz: f46c50d90f896b920a86f45ea49329a9629843c4c7550e065f22c4b20df35149
+  data.tar.gz: 6c927de51e73ba689314a7caaf5f419a23af0f61f35b80c09f1c5d4cfa63273d
 SHA512:
-  metadata.gz: 0cea4dc04116f248f8343902d9aeeb875e6a3cac9dc6c772a9462daea7d99a526862d715af5e94fa45826896ab5cd832a55b7f31fb7b1a94e12649a0ea059984
-  data.tar.gz: e55bc250bd8d38b6cc7fb5a2b1d81d808948244defe93aa4715fb052967f8b3318d62b5dd58e614b03ddaf528a3ddb7ef4ae07786f9dbc67e2eced0c28065d9d
+  metadata.gz: 4d861b025f3f455367ef485e40df6f98d83e55b1fd3c3b5fdf2cc6f57bbae2dd3dec94586bb1265b76859a83a3bd0c782a523315cf5188e3ccf9f62a8dcb6b2f
+  data.tar.gz: f712f1b0e82dfa596c1d805ef5f7ddd715bc39eb1fffee564df6eb98a68582f21d1f9822f7980471d91c70823e86c1e693599adcb2d77eb96c909059e7d90576

data/.rubocop.yml

@@ -16,7 +16,7 @@ Metrics/AbcSize:
   Enabled: false
 
 Metrics/MethodLength:
-  Max: 35
+  Max: 40
 
 Metrics/ModuleLength:
   Enabled: false

data/.rulesync/commands/translate-readme.md

@@ -0,0 +1,46 @@
+---
+targets:
+  - claudecode
+description: Translate README.md and sync docs for all languages (ja, zh, fr, de)
+---
+
+# Translate Documentation
+
+Translate and sync documentation for multiple languages.
+
+## Instructions
+
+### 1. Sync English Documentation
+
+1. Read the current `README.md`
+2. Copy content to `docs/src/index.md`:
+   - Remove the language links line (`[English](README.md) | [日本語]...`)
+   - Keep everything else
+
+### 2. Translate to Other Languages
+
+For each language directory (`docs/ja/`, `docs/zh/`, `docs/fr/`, `docs/de/`):
+
+1. Translate `docs/src/index.md` to `docs/{lang}/index.md`
+2. Translate `docs/src/point-system.md` to `docs/{lang}/point-system.md`
+3. Translate `docs/src/user-name-history.md` to `docs/{lang}/user-name-history.md`
+4. Update `docs/{lang}/SUMMARY.md` with translated titles
+
+### 3. Translation Guidelines
+
+For each translation:
+- Keep all code blocks unchanged
+- Translate all text content naturally (not literal translation)
+- Keep the same markdown structure
+- Keep URLs and links unchanged
+- Do NOT include language links in docs files
+- Translate headings and navigation text in SUMMARY.md
+
+### 4. Language Codes
+
+- `ja` - Japanese (日本語)
+- `zh` - Chinese (中文)
+- `fr` - French (Français)
+- `de` - German (Deutsch)
+
+$ARGUMENTS

data/{CLAUDE.md → .rulesync/rules/project.md}

@@ -1,8 +1,10 @@
-# CLAUDE.md
+---
+targets:
+  - claudecode
+root: true
+---
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
+# Project Overview
 
 InTimeScope is 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.
 
@@ -39,7 +41,7 @@ bundle exec rake install
 
 ## Code Style
 
-- Ruby 3.1+ required
+- Ruby 3.0+ required
 - Use double-quoted strings (enforced by RuboCop)
 - All files must have `# frozen_string_literal: true` header
 
@@ -47,8 +49,19 @@ bundle exec rake install
 
 Entry point is `lib/in_time_scope.rb` which defines the `InTimeScope` module. When included in an ActiveRecord model, it provides the `in_time_scope` class method that generates:
 
-- Class scope methods: `Model.in_time`, `Model.in_time(timestamp)`
-- Instance methods: `instance.in_time?`, `instance.in_time?(timestamp)`
+**Primary scopes (records in time window):**
+- `Model.in_time`, `Model.in_time(timestamp)` - class scope
+- `instance.in_time?`, `instance.in_time?(timestamp)` - instance method
+
+**Inverse scopes (records outside time window):**
+- `Model.before_in_time` - records not yet started (`start_at > time`)
+- `Model.after_in_time` - records already ended (`end_at <= time`)
+- `Model.out_of_time` - records outside window (before OR after)
+- Corresponding instance methods: `before_in_time?`, `after_in_time?`, `out_of_time?`
+
+**Additional scopes for start-only/end-only patterns:**
+- `Model.latest_in_time(:foreign_key)` - latest record per FK (for `has_one`)
+- `Model.earliest_in_time(:foreign_key)` - earliest record per FK
 
 The gem auto-detects column nullability from the database schema to generate optimized SQL queries (simpler queries for NOT NULL columns, NULL-aware queries otherwise).
 
@@ -59,6 +72,9 @@ Key configuration options for `in_time_scope`:
 
 Setting `column: nil` disables that boundary, enabling start-only (history) or end-only (expiration) patterns.
 
+Named scopes generate all methods with the scope name:
+- `in_time_scope :published` → `in_time_published`, `before_in_time_published`, `after_in_time_published`, `out_of_time_published`
+
 ## Test Structure
 
 Tests use RSpec with SQLite3 in-memory database. Test models are defined in `spec/support/create_test_database.rb`:

data/README.md

@@ -1,308 +1,191 @@
 # InTimeScope
 
-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.
+[English](README.md) | [日本語](docs/ja/index.md) | [中文](docs/zh/index.md) | [Français](docs/fr/index.md) | [Deutsch](docs/de/index.md)
 
-## 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
-
-Install the gem and add to the application's Gemfile by executing:
-
-```bash
-bundle add in_time_scope
-```
-
-If bundler is not being used to manage dependencies, install the gem by executing:
-
-```bash
-gem install in_time_scope
-```
-
-## Usage
-
-### Basic: Nullable Time Window
-Use the defaults (`start_at` / `end_at`) even when the columns allow `NULL`.
+Are you writing this every time in Rails?
 
 ```ruby
-create_table :events do |t|
-  t.datetime :start_at, null: true
-  t.datetime :end_at, null: true
-
-  t.timestamps
-end
+# Before
+Event.where("start_at <= ? AND (end_at IS NULL OR end_at > ?)", Time.current, Time.current)
 
+# After
 class Event < ActiveRecord::Base
-  # 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')
-
-# Check at a specific time
-Event.in_time(Time.parse("2024-06-01 12:00:00"))
-
-# Is the current time within the window?
-event = Event.first
-event.in_time?
-#=> true or false
-
-# Check any arbitrary timestamp
-event.in_time?(Time.parse("2024-06-01 12:00:00"))
-#=> true or false
 ```
 
-### Basic: Non-Nullable Time Window
-When both timestamps are required (no `NULL`s), the generated query is simpler and faster.
+That's it. One line of DSL, zero raw SQL in your models.
 
-```ruby
-create_table :events do |t|
-  t.datetime :start_at, null: false
-  t.datetime :end_at, null: false
+**This is a simple, thin gem that just provides scopes. No learning curve required.**
 
-  t.timestamps
-end
+## Why This Gem?
 
-# 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')
+This gem exists to:
 
-# 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')
-
-class Event < ActiveRecord::Base
-  # Explicitly mark columns as NOT NULL (even if the DB allows NULL)
-  in_time_scope start_at: { null: false }, end_at: { null: false }
-end
-```
+- **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
 
-### Options Reference
-Use these options in `in_time_scope` to customize column behavior.
+## Recommended For
 
-| Option | Applies to | Type | Default | Description | Example |
-| --- | --- | --- | --- | --- | --- |
-| `: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` |
+- New Rails applications with validity periods
+- Models with `start_at` / `end_at` columns
+- Teams that want consistent time logic without scattered `where` clauses
 
-### Alternative: Start-Only History (No `end_at`)
-Use this when periods never overlap and you want exactly one "current" row.
+## Installation
 
-**Requirements:**
-- `start_at` must be NOT NULL (a `ConfigurationError` is raised otherwise)
-- periods never overlap (validated)
-- the latest row is the current one
+```bash
+bundle add in_time_scope
+```
 
-If your table still has an `end_at` column but you want to ignore it, disable it via options:
+## Quick Start
 
 ```ruby
 class Event < ActiveRecord::Base
-  # Ignore end_at even if the column exists
-  in_time_scope start_at: { null: false }, end_at: { column: nil }
+  in_time_scope
 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'
-
-# 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 (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:
+# Class scope
+Event.in_time                          # Records active now
+Event.in_time(Time.parse("2024-06-01")) # Records active at specific time
 
-```sql
-CREATE INDEX index_events_on_start_at ON events (start_at);
+# Instance method
+event.in_time?                          # Is this record active now?
+event.in_time?(some_time)               # Was it active at that time?
 ```
 
-### Alternative: End-Only Expiration (No `start_at`)
-Use this when a record is active immediately and expires at `end_at`.
+## Features
 
-**Requirements:**
-- `end_at` must be NOT NULL (a `ConfigurationError` is raised otherwise)
-- `start_at` is not used (implicit "always active")
+### Auto-Optimized SQL
 
-If your table still has a `start_at` column but you want to ignore it, disable it via options:
+The gem reads your schema and generates the right SQL:
 
 ```ruby
-class Event < ActiveRecord::Base
-  # Ignore start_at and only use end_at
-  in_time_scope start_at: { column: nil }, end_at: { null: false }
-end
+# NULL-allowed columns → NULL-aware query
+WHERE (start_at IS NULL OR start_at <= ?) AND (end_at IS NULL OR end_at > ?)
 
-Event.in_time(Time.parse("2024-06-01 12:00:00"))
-# => SELECT "events".* FROM "events" WHERE "events"."end_at" > '2024-06-01 12:00:00.000000'
+# NOT NULL columns → simple query
+WHERE start_at <= ? AND end_at > ?
 ```
 
-Recommended index:
+### Named Scopes
 
-```sql
-CREATE INDEX index_events_on_end_at ON events (end_at);
-```
-
-### Advanced: Custom Columns and Multiple Scopes
-Customize which columns are used and define more than one time window per model.
+Multiple time windows per model:
 
 ```ruby
-create_table :events do |t|
-  t.datetime :available_at, null: true
-  t.datetime :expired_at, null: true
-  t.datetime :published_start_at, null: false
-  t.datetime :published_end_at, null: false
-
-  t.timestamps
+class Article < ActiveRecord::Base
+  in_time_scope :published   # → Article.in_time_published
+  in_time_scope :featured    # → Article.in_time_featured
 end
-
-class Event < ActiveRecord::Base
-  # Use different column names
-  in_time_scope start_at: { column: :available_at }, end_at: { column: :expired_at }
-
-  # 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.
+### Custom Columns
 
 ```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
+class Campaign < ActiveRecord::Base
+  in_time_scope start_at: { column: :available_at },
+                end_at: { column: :expired_at }
 end
-
-Event.published_in_time
-# => uses published_start_at / published_end_at
 ```
 
-### Using with `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.
+### Start-Only Pattern (Version History)
 
-#### Simple approach: `in_time` + `order`
-
-`in_time` provides WHERE only. Add `order` externally:
+For records where each row is valid until the next one:
 
 ```ruby
 class Price < ActiveRecord::Base
-  belongs_to :user
-
   in_time_scope start_at: { null: false }, end_at: { column: nil }
 end
 
+# Bonus: efficient has_one with NOT EXISTS
 class User < ActiveRecord::Base
-  has_many :prices
-
-  # in_time is WHERE only, add order externally
-  has_one :current_price,
-          -> { in_time.order(start_at: :desc) },
-          class_name: "Price"
+  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
 ```
 
-This works but loads all matching records into memory when using `includes`.
+### End-Only Pattern (Expiration)
 
-#### Efficient approach: `latest_in_time` (NOT EXISTS) - Recommended
+For records that are active until they expire:
 
 ```ruby
-class User < ActiveRecord::Base
-  has_many :prices
-
-  # Uses NOT EXISTS subquery - only loads the latest record per user
-  has_one :current_price,
-          -> { latest_in_time(:user_id) },
-          class_name: "Price"
-end
-
-# Direct access
-user.current_price
-# => Returns the most recent price where start_at <= Time.current
-
-# Efficient with includes (only fetches latest record per user from DB)
-User.includes(:current_price).each do |user|
-  puts user.current_price&.amount
+class Coupon < ActiveRecord::Base
+  in_time_scope start_at: { column: nil }, end_at: { null: false }
 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.
+### Inverse Scopes
 
-#### Getting the earliest record: `earliest_in_time`
+Query records outside the time window:
 
 ```ruby
-class User < ActiveRecord::Base
-  has_many :prices
+# Records not yet started (start_at > time)
+Event.before_in_time
+event.before_in_time?
 
-  # Uses NOT EXISTS subquery - only loads the earliest record per user
-  has_one :first_price,
-          -> { earliest_in_time(:user_id) },
-          class_name: "Price"
-end
+# Records already ended (end_at <= time)
+Event.after_in_time
+event.after_in_time?
 
-# Direct access
-user.first_price
-# => Returns the earliest price where start_at <= Time.current
+# Records outside time window (before OR after)
+Event.out_of_time
+event.out_of_time?  # Logical inverse of in_time?
+```
 
-# Efficient with includes
-User.includes(:first_price).each do |user|
-  puts user.first_price&.amount
-end
+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
 ```
 
-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.
+## Options Reference
 
-### Error Handling
+| 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 }` |
 
-If you specify a scope name but the expected columns don't exist, a `ColumnNotFoundError` is raised at class load time:
+## Acknowledgements
 
-```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'
-```
+Inspired by [onk/shibaraku](https://github.com/onk/shibaraku). This gem extends the concept with:
 
-This helps catch configuration errors early during development.
+- 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
 
-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.
+```bash
+# Install dependencies
+bin/setup
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+# Run tests
+bundle exec rspec
 
-## Contributing
+# Run linting
+bundle exec rubocop
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/kyohah/in_time_scope. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/kyohah/in_time_scope/blob/main/CODE_OF_CONDUCT.md).
+# Generate CLAUDE.md (for AI coding assistants)
+npx rulesync generate
+```
 
-## License
+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`.
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+## Contributing
 
-## Code of Conduct
+Bug reports and pull requests are welcome on [GitHub](https://github.com/kyohah/in_time_scope).
+
+## License
 
-Everyone interacting in the InTimeScope project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/kyohah/in_time_scope/blob/main/CODE_OF_CONDUCT.md).
+MIT License

data/docs/book.toml

@@ -0,0 +1,14 @@
+[book]
+title = "InTimeScope"
+authors = ["kyohah"]
+language = "en"
+src = "src"
+
+[build]
+build-dir = "book"
+
+[output.html]
+default-theme = "light"
+preferred-dark-theme = "navy"
+git-repository-url = "https://github.com/kyohah/in_time_scope"
+edit-url-template = "https://github.com/kyohah/in_time_scope/edit/main/docs/{path}"

data/docs/de/SUMMARY.md

@@ -0,0 +1,5 @@
+# Inhaltsverzeichnis
+
+- [Einführung](./index.md)
+- [Punktesystem mit Ablaufdatum](./point-system.md)
+- [Benutzernamen-Historie](./user-name-history.md)