synthra 0.1.0

data/tech_docs/dsl/datetime_types.md

@@ -0,0 +1,325 @@
+# Date & Time Types Reference
+
+Complete guide to date and time types in FakeDataDSL.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Date Types](#date-types)
+- [Time Types](#time-types)
+- [Duration Suffixes](#duration-suffixes)
+- [Examples](#examples)
+
+---
+
+## Overview
+
+FakeDataDSL provides several date and time types:
+
+| Type | Description | Example Output |
+|------|-------------|----------------|
+| `date` | Random date | `"2024-06-15"` |
+| `past_date` | Date in the past | `"2024-01-15"` |
+| `future_date` | Date in the future | `"2025-06-15"` |
+| `timestamp` | DateTime with time | `"2024-06-15T14:30:00Z"` |
+| `now` | Current timestamp | `"2024-07-15T10:30:45Z"` |
+| `datetime` | DateTime in range | `"2024-06-15T14:30:00Z"` |
+| `time` | Time only | `"14:30:00"` |
+
+---
+
+## Date Types
+
+### date
+
+Generates a random date.
+
+```dsl
+Event:
+  date: date
+```
+
+**Output format:** ISO 8601 (`YYYY-MM-DD`)
+
+**Examples:**
+- `"2024-06-15"`
+- `"2023-12-01"`
+- `"2025-03-22"`
+
+### past_date
+
+Generates a date in the past.
+
+```dsl
+User:
+  created_at: past_date
+  birthday: past_date(100y)
+  recent_login: past_date(7d)
+  last_month: past_date(1m)
+```
+
+| Argument | Type | Default | Description |
+|----------|------|---------|-------------|
+| Duration | String | `1y` | How far in the past |
+
+**Duration suffixes:**
+- `d` - days
+- `m` - months
+- `y` - years
+
+**Generation modes:**
+
+| Mode | Output |
+|------|--------|
+| `:random` | Random date within range |
+| `:edge` | Min date, max date, boundary dates |
+| `:invalid` | `nil`, invalid format, future date |
+
+### future_date
+
+Generates a date in the future.
+
+```dsl
+Task:
+  due_date: future_date
+  reminder: future_date(7d)
+  expiration: future_date(1y)
+```
+
+| Argument | Type | Default | Description |
+|----------|------|---------|-------------|
+| Duration | String | `1y` | How far in the future |
+
+---
+
+## Time Types
+
+### timestamp
+
+Generates a full datetime timestamp.
+
+```dsl
+Event:
+  occurred_at: timestamp
+```
+
+**Output format:** ISO 8601 with time (`YYYY-MM-DDTHH:MM:SSZ`)
+
+**Examples:**
+- `"2024-06-15T14:30:00Z"`
+- `"2023-12-01T09:15:30Z"`
+
+### now
+
+Generates the current timestamp.
+
+```dsl
+AuditLog:
+  created_at: now
+```
+
+**Output:** Current time in ISO 8601 format
+
+### datetime
+
+Generates a datetime within a specific range.
+
+```dsl
+Appointment:
+  scheduled_at: datetime(from: "2024-01-01", to: "2024-12-31")
+```
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `from` | String | Start date/datetime |
+| `to` | String | End date/datetime |
+
+### time
+
+Generates a time only (no date).
+
+```dsl
+Schedule:
+  start_time: time
+  end_time: time
+```
+
+**Output format:** `HH:MM:SS`
+
+**Examples:**
+- `"14:30:00"`
+- `"09:00:00"`
+- `"23:59:59"`
+
+---
+
+## Duration Suffixes
+
+Duration arguments accept these suffixes:
+
+| Suffix | Unit | Example | Meaning |
+|--------|------|---------|---------|
+| `d` | Days | `30d` | 30 days |
+| `m` | Months | `6m` | 6 months |
+| `y` | Years | `2y` | 2 years |
+
+### Examples
+
+```dsl
+Task:
+  # Days
+  due_in_week: future_date(7d)
+  due_in_month: future_date(30d)
+  
+  # Months
+  quarterly_review: future_date(3m)
+  semi_annual: future_date(6m)
+  
+  # Years
+  annual_renewal: future_date(1y)
+  long_term: future_date(5y)
+
+User:
+  # Past dates
+  recent_activity: past_date(24h)   # Not supported - use days
+  last_week: past_date(7d)
+  last_month: past_date(30d)
+  last_quarter: past_date(3m)
+  last_year: past_date(1y)
+```
+
+---
+
+## Examples
+
+### User Lifecycle
+
+```dsl
+User:
+  created_at: past_date(3y)
+  email_verified_at: past_date(3y)
+  last_login: past_date(30d)
+  password_changed_at: past_date(90d)
+  subscription_expires: future_date(1y)
+```
+
+### E-commerce Order
+
+```dsl
+Order:
+  created_at: past_date(60d)
+  paid_at: past_date(60d)
+  shipped_at: past_date(45d)
+  delivered_at: past_date(30d)
+  return_deadline: future_date(30d)
+```
+
+### Event Scheduling
+
+```dsl
+CalendarEvent:
+  start_date: date
+  start_time: time
+  end_date: date
+  end_time: time
+  created_at: past_date(30d)
+  reminder_at: future_date(1d)
+```
+
+### Subscription Model
+
+```dsl
+Subscription:
+  started_at: past_date(2y)
+  current_period_start: past_date(30d)
+  current_period_end: future_date(30d)
+  trial_ends_at?: future_date(14d)
+  cancelled_at?: past_date(7d)
+```
+
+### Audit Trail
+
+```dsl
+AuditLog:
+  timestamp: timestamp
+  event_time: now
+  
+HistoricalRecord:
+  effective_from: past_date(5y)
+  effective_to: future_date(1y)
+  recorded_at: timestamp
+```
+
+---
+
+## Edge Cases by Mode
+
+### Random Mode
+- Dates within specified range
+- Realistic timestamps
+- Current time for `now`
+
+### Edge Mode
+- Unix epoch: `1970-01-01`
+- Y2K: `2000-01-01`
+- Y2038 problem: `2038-01-19`
+- Leap year dates: `2024-02-29`
+- End of year: `YYYY-12-31`
+- Start of year: `YYYY-01-01`
+
+### Invalid Mode
+- `nil`
+- Invalid format: `"not-a-date"`
+- Wrong type: `12345`
+- Invalid dates: `"2024-13-45"`, `"2024-02-30"`
+
+---
+
+## Best Practices
+
+### 1. Use Appropriate Ranges
+
+```dsl
+# Good - realistic ranges
+User:
+  birthday: past_date(100y)
+  created_at: past_date(5y)
+  last_login: past_date(30d)
+
+# Avoid - unrealistic
+User:
+  birthday: past_date(1000y)
+  last_login: past_date(100y)
+```
+
+### 2. Order Dates Logically
+
+```dsl
+# Good - logical order
+Order:
+  created_at: past_date(60d)
+  shipped_at: past_date(50d)
+  delivered_at: past_date(40d)
+```
+
+### 3. Use Appropriate Types
+
+```dsl
+# Use date for date-only
+birthday: date
+
+# Use timestamp for full datetime
+created_at: timestamp
+
+# Use now for current time
+updated_at: now
+```
+
+---
+
+## Next Steps
+
+- [Core Types](core_types.md) - All basic types
+- [Complex Types](complex_types.md) - Arrays, objects
+- [Field Modifiers](field_modifiers.md) - Optional, nullable
+

data/tech_docs/dsl/field_modifiers.md

@@ -0,0 +1,414 @@
+# Field Modifiers
+
+Optional, nullable, and conditional field modifiers.
+
+## Table of Contents
+
+- [Optional Fields](#optional-fields)
+- [Nullable Fields](#nullable-fields)
+- [Combined Modifiers](#combined-modifiers)
+- [Conditional Fields](#conditional-fields)
+- [Unique Constraint](#unique-constraint)
+- [Field Behaviors](#field-behaviors)
+
+---
+
+## Optional Fields
+
+### What is Optional?
+
+Optional fields may not appear in the output at all.
+
+### Syntax
+
+Add `?` after the field name:
+
+```dsl
+User:
+  id: uuid          # Always present
+  phone?: phone     # May not appear
+  bio?: text        # May not appear
+```
+
+### Probability
+
+By default, optional fields appear ~50% of the time.
+
+### Generated Output
+
+```ruby
+# Without optional fields:
+{ "id" => "550e8400-..." }
+
+# With optional fields:
+{ "id" => "550e8400-...", "phone" => "+1-555-123-4567" }
+```
+
+### Use Cases
+
+- Incomplete user profiles
+- Optional contact information
+- Non-required form fields
+- Sparse data simulation
+
+```dsl
+ContactInfo:
+  email: email              # Required
+  phone?: phone             # Optional
+  fax?: phone               # Optional
+  twitter?: text(1..15)     # Optional
+  linkedin?: url            # Optional
+```
+
+---
+
+## Nullable Fields
+
+### What is Nullable?
+
+Nullable fields always appear but may have a `null` value.
+
+### Syntax
+
+Add `?` after the type:
+
+```dsl
+User:
+  name: name       # Never null
+  nickname: text?  # May be null
+```
+
+### Probability
+
+By default, nullable fields are null ~50% of the time.
+
+### Generated Output
+
+```ruby
+# With value:
+{ "name" => "John", "nickname" => "Johnny" }
+
+# With null:
+{ "name" => "John", "nickname" => nil }
+```
+
+### Use Cases
+
+- Database columns that allow NULL
+- Cleared user data
+- Pending information
+- Optional relationships
+
+```dsl
+Employee:
+  id: uuid
+  name: name
+  manager_id: uuid?    # May not have a manager
+  department: text?    # May be unassigned
+  end_date: date?      # Still employed if null
+```
+
+---
+
+## Combined Modifiers
+
+### Optional AND Nullable
+
+A field can be both optional and nullable:
+
+```dsl
+User:
+  emergency_contact?: phone?
+```
+
+This means:
+1. The field may not appear at all (optional)
+2. If it appears, it may be null (nullable)
+
+### Generated Output
+
+```ruby
+# Not present at all (optional):
+{ "id" => "...", "name" => "John" }
+
+# Present but null:
+{ "id" => "...", "name" => "John", "emergency_contact" => nil }
+
+# Present with value:
+{ "id" => "...", "name" => "John", "emergency_contact" => "+1-555-123-4567" }
+```
+
+### Probability Matrix
+
+| Outcome | Probability |
+|---------|-------------|
+| Not present | ~50% |
+| Present + null | ~25% |
+| Present + value | ~25% |
+
+---
+
+## Conditional Fields
+
+### What is Conditional?
+
+Conditional fields only appear when a condition is met.
+
+### Syntax
+
+```dsl
+User:
+  field_name: type if condition_field
+```
+
+### How It Works
+
+The field only appears if `condition_field` is truthy:
+- Not `nil`
+- Not `false`
+- Not empty string
+
+```dsl
+Order:
+  status: enum(pending, shipped, delivered)
+  
+  # Only present when status has a value
+  tracking_number: text(20) if status
+```
+
+### Current Limitations
+
+**Important:** Only truthiness checks are supported:
+
+```dsl
+# ✅ Supported - truthiness check
+tracking_number: text if status
+
+# ❌ NOT supported - equality comparison
+tracking_number: text if status == "shipped"
+
+# ❌ NOT supported - complex conditions
+discount: number if total > 100
+```
+
+### Field Order Matters
+
+Fields are processed alphabetically. The condition field must be generated before the conditional field:
+
+```dsl
+# ✅ Works - "premium" comes before "premium_features"
+User:
+  premium: boolean
+  premium_features: object if premium
+
+# ⚠️ May not work - "features" comes before "has_features"
+User:
+  features: object if has_features
+  has_features: boolean
+```
+
+### Conditional Field Examples
+
+```dsl
+Subscription:
+  active: boolean
+  plan: enum(free, basic, premium)
+  
+  # Only when active
+  renewal_date: future_date(1y) if active
+  
+  # Only when has a plan
+  features: array(text, 1..10) if plan
+
+Order:
+  status: enum(pending, processing, shipped, cancelled)
+  
+  # Shipping info only for shipped orders
+  tracking_number: text(20) if status
+  carrier: enum(ups, fedex, usps) if status
+  estimated_delivery: future_date(14d) if status
+```
+
+---
+
+## Unique Constraint
+
+### What is Unique?
+
+Ensures values are unique within a generation batch.
+
+### Syntax
+
+```dsl
+User:
+  id: uuid(unique: true)
+  email: email(unique: true)
+  username: text(3..20, unique: true)
+```
+
+### Scope
+
+- **Per-batch**: Uniqueness within a single `generate_many` call
+- **Per-engine**: Uniqueness across calls on same Engine instance
+- **NOT global**: Different Engine instances track independently
+
+### Example
+
+```ruby
+schema = FakeDataDSL.load('user.dsl')
+
+# Unique within this batch
+users = schema.generate_many(100)
+# All 100 emails will be different
+
+# New batch starts fresh
+more_users = schema.generate_many(100)
+# These emails may duplicate the first batch
+```
+
+### Uniqueness Errors
+
+```ruby
+begin
+  # Requesting more unique values than possible
+  users = schema.generate_many(1_000_000)
+rescue FakeDataDSL::Errors::UniquenessError => e
+  puts "Could not generate unique value for #{e.field_name}"
+end
+```
+
+### Unique with Types
+
+```dsl
+User:
+  id: uuid(unique: true)          # UUID always unique anyway
+  email: email(unique: true)       # Ensures no duplicate emails
+  username: text(3..10, unique: true)  # Limited pool - may exhaust
+  
+Product:
+  sku: text(10, unique: true)      # Product codes
+  barcode: number(1000000000000..9999999999999, unique: true)
+```
+
+---
+
+## Field Behaviors
+
+### What are Field Behaviors?
+
+Behaviors can be attached to individual fields to simulate conditions.
+
+### Syntax
+
+```dsl
+User:
+  field_name: type @behavior value
+```
+
+### Available Behaviors
+
+| Behavior | Description | Example |
+|----------|-------------|---------|
+| `@partial_data` | May be missing | `avatar: url @partial_data 30%` |
+| `@latency` | Adds delay | `profile: object @latency 100ms` |
+
+### Partial Data
+
+```dsl
+User:
+  id: uuid
+  name: name
+  email: email
+  
+  # 30% chance this field is missing
+  avatar: url @partial_data 30%
+  
+  # 50% chance this field is missing
+  phone: phone @partial_data 50%
+```
+
+### Latency on Field
+
+```dsl
+User:
+  id: uuid
+  name: name
+  
+  # This specific field takes extra time
+  external_profile: object @latency 100..500ms
+```
+
+### Multiple Behaviors
+
+```dsl
+User:
+  avatar: url @partial_data 30% @latency 50ms
+```
+
+---
+
+## Modifier Summary
+
+| Modifier | Syntax | Effect |
+|----------|--------|--------|
+| Optional | `field?: type` | Field may not appear |
+| Nullable | `field: type?` | Value may be null |
+| Both | `field?: type?` | May not appear OR be null |
+| Conditional | `field: type if x` | Only appears when x is truthy |
+| Unique | `field: type(unique: true)` | Unique within batch |
+| Behavior | `field: type @behavior` | Field-level simulation |
+
+---
+
+## Best Practices
+
+### 1. Model Real Data
+
+```dsl
+# Match your database schema
+User:
+  id: uuid                    # NOT NULL
+  email: email                # NOT NULL, UNIQUE
+  phone: text?                # NULL allowed
+  deleted_at: timestamp?      # NULL when active
+```
+
+### 2. Use Conditional for Relationships
+
+```dsl
+Employee:
+  role: enum(employee, manager, executive)
+  
+  # Only managers have direct reports
+  direct_reports: array(Ref(Employee.id), 0..10) if role
+  
+  # Only executives have budget
+  budget: money if role
+```
+
+### 3. Combine for Realistic Sparsity
+
+```dsl
+UserProfile:
+  # Required
+  user_id: uuid
+  
+  # Usually present but optional
+  display_name?: name
+  
+  # Rarely filled
+  bio?: text(50..500)?  # Optional AND nullable
+  website?: url?
+  
+  # Only if verified
+  badge: enum(verified, partner) if verified_status
+```
+
+---
+
+## Next Steps
+
+- [Complex Types](complex_types.md) - Arrays, objects, references
+- [Behaviors](../behaviors/overview.md) - Schema-level behaviors
+- [Generation Modes](../modes/overview.md) - Random, edge, invalid modes
+