synthra 0.1.0

data/docs/TIME_TRAVEL.md

@@ -0,0 +1,507 @@
+# Time Travel for Data
+
+FakeDataDSL's Time Travel feature lets you generate data **as it would have existed at a specific point in time**, or create realistic progressions of data over time. Perfect for testing time-sensitive features, historical reports, and temporal queries.
+
+## Quick Start
+
+```ruby
+# Generate data from 30 days ago
+FakeDataDSL::TimeTravel.at(30.days.ago) do
+  user = FakeDataDSL.generate("User")
+  # user[:created_at] is 30 days ago
+  # user[:updated_at] is 30 days ago
+end
+
+# Generate data progression
+orders = FakeDataDSL::TimeTravel.progression("Order", 
+  from: 1.year.ago, 
+  to: Time.current, 
+  count: 12
+)
+# 12 orders spread across the past year
+```
+
+## Basic Usage
+
+### Generate at Specific Time
+
+```ruby
+# All timestamps generated within the block are relative to the travel time
+FakeDataDSL::TimeTravel.at(Date.new(2025, 1, 1)) do
+  user = FakeDataDSL.generate("User")
+  # user[:created_at] => 2025-01-01 (random time on that day)
+end
+
+# With specific time
+FakeDataDSL::TimeTravel.at(Time.new(2025, 6, 15, 14, 30, 0)) do
+  event = FakeDataDSL.generate("Event")
+  # event[:scheduled_at] => around 2025-06-15 14:30
+end
+```
+
+### Generate Between Dates
+
+```ruby
+# Timestamps fall randomly within the range
+FakeDataDSL::TimeTravel.between(1.month.ago, Time.current) do
+  log = FakeDataDSL.generate("AuditLog")
+  # log[:created_at] is somewhere in the last month
+end
+
+# Generate multiple records spread across range
+records = FakeDataDSL::TimeTravel.between(1.year.ago, Time.current) do
+  10.times.map { FakeDataDSL.generate("Transaction") }
+end
+# Transactions spread randomly across the year
+```
+
+## Time Progressions
+
+### Linear Progression
+
+Generate records evenly distributed over time:
+
+```ruby
+# 12 monthly reports
+reports = FakeDataDSL::TimeTravel.progression("MonthlyReport",
+  from: 1.year.ago,
+  to: Time.current,
+  count: 12
+)
+
+reports.each_with_index do |report, i|
+  puts "#{report[:created_at].strftime('%B %Y')}: $#{report[:revenue]}"
+end
+# January 2025: $12,345
+# February 2025: $13,456
+# ...
+```
+
+### Custom Intervals
+
+```ruby
+# Daily records
+daily = FakeDataDSL::TimeTravel.progression("DailyMetric",
+  from: 7.days.ago,
+  to: Time.current,
+  interval: 1.day
+)
+
+# Hourly records
+hourly = FakeDataDSL::TimeTravel.progression("HourlyLog",
+  from: 24.hours.ago,
+  to: Time.current,
+  interval: 1.hour
+)
+
+# Weekly records
+weekly = FakeDataDSL::TimeTravel.progression("WeeklyDigest",
+  from: 3.months.ago,
+  to: Time.current,
+  interval: 1.week
+)
+```
+
+### With Variations
+
+```ruby
+# Add realistic variation to timestamps
+orders = FakeDataDSL::TimeTravel.progression("Order",
+  from: 1.month.ago,
+  to: Time.current,
+  count: 30,
+  jitter: 6.hours  # ±6 hours variation
+)
+```
+
+## Time Series Data
+
+### Generate Time Series
+
+```ruby
+# Stock prices over time
+prices = FakeDataDSL::TimeTravel.time_series("StockPrice",
+  from: 1.year.ago,
+  to: Time.current,
+  interval: 1.day,
+  fields: {
+    open: { type: :trending, start: 100, volatility: 0.02 },
+    close: { type: :trending, start: 100, volatility: 0.02 },
+    volume: { type: :random, range: 1000..10000 }
+  }
+)
+```
+
+### Trending Data
+
+```ruby
+# Metrics that grow over time
+FakeDataDSL::TimeTravel.time_series("UserMetrics",
+  from: 1.year.ago,
+  to: Time.current,
+  interval: 1.week,
+  trend: :growth,      # :growth, :decline, :stable, :seasonal
+  growth_rate: 0.05    # 5% weekly growth
+)
+```
+
+### Seasonal Patterns
+
+```ruby
+# E-commerce orders with seasonal variation
+orders = FakeDataDSL::TimeTravel.time_series("Order",
+  from: 1.year.ago,
+  to: Time.current,
+  interval: 1.day,
+  seasonality: {
+    pattern: :weekly,
+    peaks: [5, 6],        # Saturday, Sunday
+    peak_multiplier: 2.5
+  }
+)
+```
+
+## Schema Annotations
+
+### In DSL Files
+
+```ruby
+# db/schemas/historical_order.dsl
+HistoricalOrder:
+  @time_travel -365.days..-1.day
+  
+  id: uuid
+  created_at: timestamp
+  shipped_at: timestamp(after: created_at, within: 7.days)
+  delivered_at: timestamp(after: shipped_at, within: 14.days)
+```
+
+### Relative Timestamps
+
+```ruby
+# Timestamps that depend on each other
+Order:
+  id: uuid
+  created_at: timestamp
+  confirmed_at: timestamp(after: created_at, within: 1.hour)
+  shipped_at: timestamp(after: confirmed_at, within: 3.days)
+  delivered_at: timestamp(after: shipped_at, within: 7.days)
+```
+
+When time traveling:
+
+```ruby
+FakeDataDSL::TimeTravel.at(30.days.ago) do
+  order = FakeDataDSL.generate("Order")
+  # order[:created_at]    => ~30 days ago
+  # order[:confirmed_at]  => ~30 days ago (within 1 hour of created_at)
+  # order[:shipped_at]    => ~27 days ago (within 3 days of confirmed_at)
+  # order[:delivered_at]  => ~20 days ago (within 7 days of shipped_at)
+end
+```
+
+## Nested Time Contexts
+
+### Time Blocks
+
+```ruby
+FakeDataDSL::TimeTravel.at(1.year.ago) do
+  old_user = FakeDataDSL.generate("User")
+  
+  FakeDataDSL::TimeTravel.at(6.months.ago) do
+    mid_user = FakeDataDSL.generate("User")
+    
+    FakeDataDSL::TimeTravel.at(Time.current) do
+      new_user = FakeDataDSL.generate("User")
+    end
+  end
+end
+```
+
+### Progressive Nesting
+
+```ruby
+# User signs up, then creates content over time
+FakeDataDSL::TimeTravel.at(1.year.ago) do
+  user = FakeDataDSL.generate("User")
+  
+  # User writes posts over the following months
+  posts = (1..12).map do |month|
+    FakeDataDSL::TimeTravel.at(1.year.ago + month.months) do
+      FakeDataDSL.generate("Post", user_id: user[:id])
+    end
+  end
+end
+```
+
+## Integration with Scenarios
+
+```ruby
+FakeDataDSL::Scenarios.define(:historical_activity) do
+  # User from a year ago
+  let(:veteran_user) {
+    FakeDataDSL::TimeTravel.at(1.year.ago) do
+      create(:user, name: "Veteran User")
+    end
+  }
+  
+  # Their posts over time
+  let(:posts) {
+    FakeDataDSL::TimeTravel.progression("Post",
+      from: 11.months.ago,
+      to: Time.current,
+      count: 24
+    ).map { |p| p.merge(user_id: veteran_user[:id]) }
+  }
+  
+  # Recent new user
+  let(:new_user) {
+    FakeDataDSL::TimeTravel.at(1.week.ago) do
+      create(:user, name: "New User")
+    end
+  }
+end
+```
+
+## Time Zone Handling
+
+### Explicit Time Zones
+
+```ruby
+# Generate in specific timezone
+FakeDataDSL::TimeTravel.at(Time.current, zone: "America/New_York") do
+  event = FakeDataDSL.generate("Event")
+  # event[:start_time] is in Eastern time
+end
+
+# Generate in user's timezone
+FakeDataDSL::TimeTravel.at(Time.current, zone: user.time_zone) do
+  notification = FakeDataDSL.generate("Notification")
+end
+```
+
+### Multiple Zones
+
+```ruby
+# Generate events across timezones
+offices = ["America/New_York", "Europe/London", "Asia/Tokyo"]
+events = offices.map do |zone|
+  FakeDataDSL::TimeTravel.at(Time.current, zone: zone) do
+    FakeDataDSL.generate("Meeting", timezone: zone)
+  end
+end
+```
+
+## Testing Patterns
+
+### Historical Data Tests
+
+```ruby
+RSpec.describe "ReportGenerator" do
+  it "generates monthly reports" do
+    # Create historical data
+    FakeDataDSL::TimeTravel.progression("Order",
+      from: 3.months.ago,
+      to: Time.current,
+      count: 90
+    ).each { |order| Order.create!(order) }
+    
+    report = ReportGenerator.monthly_summary(2.months.ago)
+    expect(report.total_orders).to be > 0
+  end
+end
+```
+
+### Time-Sensitive Features
+
+```ruby
+RSpec.describe "SubscriptionExpiry" do
+  it "expires subscriptions correctly" do
+    # Create subscription that expires today
+    subscription = FakeDataDSL::TimeTravel.at(31.days.ago) do
+      Subscription.create!(
+        FakeDataDSL.generate("Subscription", duration: 30.days)
+      )
+    end
+    
+    expect(subscription).to be_expired
+  end
+end
+```
+
+### Aging Data
+
+```ruby
+RSpec.describe "DataRetention" do
+  it "purges old records" do
+    # Create records at various ages
+    old_record = FakeDataDSL::TimeTravel.at(2.years.ago) do
+      AuditLog.create!(FakeDataDSL.generate("AuditLog"))
+    end
+    
+    recent_record = FakeDataDSL::TimeTravel.at(1.month.ago) do
+      AuditLog.create!(FakeDataDSL.generate("AuditLog"))
+    end
+    
+    DataRetention.purge_old_records!
+    
+    expect { old_record.reload }.to raise_error(ActiveRecord::RecordNotFound)
+    expect(recent_record.reload).to be_present
+  end
+end
+```
+
+## API Reference
+
+### TimeTravel.at
+
+```ruby
+FakeDataDSL::TimeTravel.at(time, options = {}, &block)
+```
+
+**Parameters:**
+- `time` - Time/DateTime/Date to travel to
+- `options[:zone]` - Time zone name (default: system)
+- `block` - Block where all timestamps are relative to `time`
+
+**Returns:** Result of the block
+
+### TimeTravel.between
+
+```ruby
+FakeDataDSL::TimeTravel.between(start_time, end_time, options = {}, &block)
+```
+
+**Parameters:**
+- `start_time` - Start of the time range
+- `end_time` - End of the time range
+- `options[:distribution]` - :uniform (default), :weighted_recent, :weighted_old
+- `block` - Block where timestamps fall within range
+
+**Returns:** Result of the block
+
+### TimeTravel.progression
+
+```ruby
+FakeDataDSL::TimeTravel.progression(schema_name, options = {})
+```
+
+**Parameters:**
+- `schema_name` - Name of the schema to generate
+- `options[:from]` - Start time (required)
+- `options[:to]` - End time (required)
+- `options[:count]` - Number of records
+- `options[:interval]` - Fixed interval between records
+- `options[:jitter]` - Random variation for timestamps
+- `options[:overrides]` - Field overrides
+
+**Returns:** Array of generated records
+
+### TimeTravel.time_series
+
+```ruby
+FakeDataDSL::TimeTravel.time_series(schema_name, options = {})
+```
+
+**Parameters:**
+- `schema_name` - Name of the schema
+- `options[:from]` - Start time
+- `options[:to]` - End time
+- `options[:interval]` - Time between data points
+- `options[:trend]` - :growth, :decline, :stable, :seasonal
+- `options[:growth_rate]` - Rate of change per interval
+- `options[:seasonality]` - Seasonal pattern configuration
+- `options[:fields]` - Field-specific configurations
+
+**Returns:** Array of time series data points
+
+## Configuration
+
+```ruby
+FakeDataDSL::TimeTravel.configure do |config|
+  # Default time zone
+  config.default_zone = "UTC"
+  
+  # Default jitter for progressions
+  config.default_jitter = 0
+  
+  # Whether to freeze time during generation
+  config.freeze_time = true
+  
+  # Hook for before/after time travel
+  config.before_travel = ->(time) { Rails.logger.debug "Traveling to #{time}" }
+  config.after_travel = ->(time) { Rails.logger.debug "Returned from #{time}" }
+end
+```
+
+## Best Practices
+
+### 1. Use Relative Times
+
+```ruby
+# Good: Relative times adapt to when tests run
+FakeDataDSL::TimeTravel.at(30.days.ago) { ... }
+
+# Avoid: Hardcoded dates become stale
+FakeDataDSL::TimeTravel.at(Date.new(2025, 1, 1)) { ... }
+```
+
+### 2. Be Explicit About Relationships
+
+```ruby
+# Good: Clear temporal relationships
+Order:
+  created_at: timestamp
+  shipped_at: timestamp(after: created_at)  # Explicit dependency
+
+# Avoid: Implicit relationships that may not hold
+Order:
+  created_at: timestamp
+  shipped_at: timestamp  # Could be before created_at!
+```
+
+### 3. Test Edge Cases
+
+```ruby
+# Test around daylight saving time
+FakeDataDSL::TimeTravel.at(Time.new(2025, 3, 9, 2, 30, 0, "-05:00")) do
+  # DST transition edge case
+end
+
+# Test at year boundaries
+FakeDataDSL::TimeTravel.at(Time.new(2025, 12, 31, 23, 59, 59)) do
+  # Year-end edge case
+end
+```
+
+## Troubleshooting
+
+### Timestamps Not Affected
+
+```ruby
+# Make sure you're using the block
+FakeDataDSL::TimeTravel.at(1.month.ago) do
+  FakeDataDSL.generate("User")  # ✓ Affected
+end
+
+FakeDataDSL.generate("User")  # ✗ Not affected (outside block)
+```
+
+### Time Zone Confusion
+
+```ruby
+# Always be explicit when time zones matter
+FakeDataDSL::TimeTravel.at(
+  Time.current.in_time_zone("America/New_York"),
+  zone: "America/New_York"
+) do
+  # Clear time zone handling
+end
+```
+
+## See Also
+
+- [Scenarios](SCENARIOS.md)
+- [Generation Modes](generation_modes.md)
+- [Timestamp Type Reference](type_reference.md#timestamp)
+- [Testing Best Practices](best_practices.md)