synthra 0.1.0

data/tech_docs/tutorials/advanced.md

@@ -0,0 +1,371 @@
+# Advanced Tutorial
+
+Master map_by_field(), behaviors, streaming, and production patterns.
+
+## Difficulty: Advanced
+## Time: 45 minutes
+## Prerequisites: [Intermediate Tutorial](intermediate.md)
+
+---
+
+## Step 1: map_by_field() - Dynamic Object Keys
+
+Many APIs return objects keyed by ID:
+
+```json
+{
+  "users": {
+    "12345": { "id": "12345", "name": "John" },
+    "67890": { "id": "67890", "name": "Jane" }
+  }
+}
+```
+
+Use `map_by_field()` to generate this:
+
+```dsl
+Response:
+  users: map_by_field("id", sender: User, recipient: User)
+
+User:
+  id: snowflake_id
+  name: full_name
+```
+
+- First argument: field to use as object key (`"id"`)
+- Named arguments: entries to generate (`sender: User`)
+
+Output:
+
+```json
+{
+  "users": {
+    "1234567890123456789": { "id": "1234567890123456789", "name": "John Smith" },
+    "9876543210987654321": { "id": "9876543210987654321", "name": "Jane Doe" }
+  }
+}
+```
+
+---
+
+## Step 2: copy() with map_by_field()
+
+Reference values from map_by_field entries:
+
+```dsl
+Webhook:
+  users: map_by_field("id", sender: User, recipient: shared(User))
+  for_user_id: copy("users.recipient.id")
+  sender_id: copy("users.sender.id")
+
+User:
+  id: snowflake_id
+  name: full_name
+```
+
+Path syntax: `users.sender.id` accesses the sender entry's id field.
+
+---
+
+## Step 3: one_of() - Polymorphic Schemas
+
+Generate one of multiple possible schemas:
+
+```dsl
+Event:
+  id: uuid
+  type: enum(message, typing, read_receipt)
+  payload: one_of(MessagePayload, TypingPayload, ReadReceiptPayload)
+
+MessagePayload:
+  type: const("message")
+  text: message_text
+
+TypingPayload:
+  type: const("typing")
+  is_typing: boolean
+
+ReadReceiptPayload:
+  type: const("read_receipt")
+  message_id: uuid
+```
+
+Each generation randomly selects one of the schemas.
+
+---
+
+## Step 4: Behaviors - Simulate Real-World
+
+### Latency
+
+```dsl
+APIResponse:
+  @latency 100..500ms    # Random delay
+  
+  data: object
+```
+
+### Failures
+
+```dsl
+APIResponse:
+  @failure 5%            # 5% throw error
+  @simulate_error 503 1% # 1% HTTP 503
+  
+  data: object
+```
+
+### Partial Data
+
+```dsl
+User:
+  @partial_data 20%      # 20% chance fields omitted
+  
+  name: full_name
+  phone?: phone          # Optional field may be omitted
+```
+
+### Deprecation Warning
+
+```dsl
+LegacyUser:
+  @deprecated Use UserV2 instead
+  
+  id: uuid
+```
+
+---
+
+## Step 5: Schema Versioning
+
+Track schema versions for migrations:
+
+```dsl
+User:
+  @version 2.0
+  
+  id: uuid
+  name: full_name
+  email: email
+```
+
+Check version in code:
+
+```ruby
+schema = registry.schema('User')
+puts schema.version  # => "2.0"
+```
+
+Compare schemas:
+
+```bash
+fake_data_dsl diff schemas/v1/ schemas/v2/
+```
+
+---
+
+## Step 6: Streaming Large Datasets
+
+For memory-efficient generation of large datasets:
+
+```ruby
+# Stream 1 million records without loading all in memory
+schema.generate_stream(count: 1_000_000).each do |record|
+  write_to_file(record)
+end
+
+# With batch processing
+schema.generate_stream(count: 1_000_000).each_slice(1000) do |batch|
+  bulk_insert(batch)
+end
+```
+
+---
+
+## Step 7: Production Patterns
+
+### Pattern 1: Twitter DM Webhook
+
+Complete real-world example:
+
+```dsl
+TwitterDMWebhook:
+  eventName: const("new_twitter_direct_message")
+  eventData: EventData
+
+EventData:
+  users: map_by_field("id", sender: TwitterUser, recipient: shared(TwitterUser))
+  for_user_id: copy("users.recipient.id")
+  direct_message_events: array(DirectMessageEvent, 1..1)
+
+DirectMessageEvent:
+  type: const("message_create")
+  id: snowflake_id
+  created_timestamp: unix_timestamp_ms
+  message_create: MessageCreate
+
+MessageCreate:
+  target: Target
+  sender_id: copy("users.sender.id")
+  message_data: MessageData
+
+Target:
+  recipient_id: copy("users.recipient.id")
+
+MessageData:
+  text: message_text
+  entities: Entities
+
+Entities:
+  hashtags: empty_array
+  symbols: empty_array
+  user_mentions: empty_array
+  urls: empty_array
+
+TwitterUser:
+  id: snowflake_id
+  created_timestamp: unix_timestamp_ms
+  name: full_name
+  screen_name: social_handle
+```
+
+### Pattern 2: API Response with Error Handling
+
+```dsl
+APIResponse:
+  @latency 50..200ms
+  @failure 2%
+  @simulate_error 503 1%
+  
+  success: boolean(true:95%)
+  data: DataPayload
+  errors: array(ErrorDetail, 0..3)
+  meta: ResponseMeta
+
+DataPayload:
+  items: array(Item, 1..20)
+  pagination: Pagination
+
+ErrorDetail:
+  code: enum(VALIDATION_ERROR, AUTH_ERROR, NOT_FOUND)
+  message: text(20..100)
+  field?: text(5..20)
+
+Pagination:
+  page: number(1..100)
+  per_page: const(20)
+  total: number(1..1000)
+  has_more: boolean
+
+ResponseMeta:
+  request_id: uuid
+  timestamp: now
+  version: const("v2")
+```
+
+---
+
+## Step 8: CLI Tools
+
+### Interactive REPL
+
+```bash
+fake_data_dsl repl
+```
+
+Commands:
+- `load schemas/` - Load schemas
+- `list` - Show loaded schemas
+- `info User` - Schema details
+- `gen User 5` - Generate 5 records
+
+### Schema Diff
+
+```bash
+fake_data_dsl diff schemas/v1/ schemas/v2/
+```
+
+Output:
+```
+📝 User (modified)
+   version: 1.0 → 2.0
+   + field: avatar
+   - field: profile_url
+   ~ email: text → email
+```
+
+### Schema Info
+
+```bash
+fake_data_dsl info schemas/ --verbose
+```
+
+---
+
+## Step 9: Thread Safety
+
+For concurrent generation:
+
+```ruby
+# Safe: Each call is independent
+threads = 10.times.map do
+  Thread.new { schema.generate_many(100, registry: registry) }
+end
+results = threads.map(&:value)
+
+# Safe: Different seeds per thread
+threads = 10.times.map do |i|
+  Thread.new { schema.generate_many(100, seed: i * 1000) }
+end
+```
+
+---
+
+## Step 10: Resource Limits
+
+Prevent runaway generation:
+
+```ruby
+FakeDataDSL.configure do |config|
+  config.limits.max_array_size = 1000
+  config.limits.max_recursion = 10
+  config.limits.max_text_length = 10_000
+  config.limits.max_latency_ms = 5_000
+end
+```
+
+---
+
+## What You Learned
+
+✅ `map_by_field()` - Dynamic object keys  
+✅ `one_of()` - Polymorphic schemas  
+✅ Behaviors - latency, failure, partial_data  
+✅ Schema versioning with `@version`  
+✅ Streaming for large datasets  
+✅ Production patterns (Twitter DM, API responses)  
+✅ CLI tools (repl, diff, info)  
+✅ Thread safety and resource limits  
+
+---
+
+## Mastery Checklist
+
+You're a FakeDataDSL expert when you can:
+
+- [ ] Model any API response in DSL without Ruby code
+- [ ] Use `shared()` + `copy()` + `map_by_field()` together
+- [ ] Generate 1M+ records with streaming
+- [ ] Set up schema versioning for your team
+- [ ] Debug validation errors using suggestions
+- [ ] Configure resource limits for production
+
+---
+
+## Next Steps
+
+- [Type Reference](../appendices/type_chart.md) - All 50+ types
+- [Thread Safety Guide](../advanced/thread_safety.md)
+- [Grammar Reference](../dsl/grammar.md)
+- [Real Examples](../../tech_example/)
+

data/tech_docs/tutorials/getting_started.md

@@ -0,0 +1,189 @@
+# Getting Started Tutorial
+
+Learn FakeDataDSL in 15 minutes with this step-by-step guide.
+
+## Difficulty: Beginner
+## Time: 15 minutes
+
+---
+
+## Step 1: Your First Schema (2 minutes)
+
+Create a file `user.dsl`:
+
+```dsl
+User:
+  id: uuid
+  name: full_name
+  email: email
+```
+
+Generate data:
+
+```ruby
+require 'fake_data_dsl'
+
+schema = FakeDataDSL.load('user.dsl')
+user = schema.generate
+
+puts user
+# => {"id"=>"550e8400-e29b-41d4-a716-446655440000", "name"=>"John Smith", "email"=>"john.smith@example.com"}
+```
+
+**🎉 Congratulations!** You just generated your first fake data.
+
+---
+
+## Step 2: Add More Fields (3 minutes)
+
+Let's make the user more realistic:
+
+```dsl
+User:
+  id: uuid
+  name: full_name
+  email: email
+  age: number(18..65)
+  active: boolean
+  created_at: past_date(1y)
+```
+
+Key concepts:
+- `number(18..65)` - Random number between 18 and 65
+- `boolean` - Random true/false
+- `past_date(1y)` - Date within last year
+
+---
+
+## Step 3: Optional and Nullable Fields (2 minutes)
+
+Not all fields are always present or have values:
+
+```dsl
+User:
+  id: uuid
+  name: full_name
+  email: email
+  phone?: phone           # Optional - may not appear
+  nickname: text?         # Nullable - may be null
+  bio?: text?             # Optional AND nullable
+```
+
+- `phone?:` (question mark BEFORE colon) - Field may not appear
+- `text?` (question mark AFTER type) - Value may be null
+
+---
+
+## Step 4: Enums and Constants (2 minutes)
+
+For fields with specific allowed values:
+
+```dsl
+User:
+  id: uuid
+  name: full_name
+  role: enum(user, admin, moderator)
+  status: enum(active:80%, pending:15%, suspended:5%)
+  type: const("person")
+```
+
+- `enum(a, b, c)` - Random selection from options
+- `enum(active:80%)` - Weighted selection (80% chance)
+- `const("value")` - Always the same value
+
+---
+
+## Step 5: Nested Schemas (3 minutes)
+
+Real data has nested objects:
+
+```dsl
+User:
+  id: uuid
+  name: full_name
+  email: email
+  address: Address
+
+Address:
+  street: text(10..50)
+  city: city
+  country: country_code
+  postal_code: postal_code
+```
+
+Generate:
+
+```ruby
+user = schema.generate
+# => {
+#   "id" => "550e8400-...",
+#   "name" => "John Smith",
+#   "email" => "john@example.com",
+#   "address" => {
+#     "street" => "123 Main Street",
+#     "city" => "New York",
+#     "country" => "US",
+#     "postal_code" => "10001"
+#   }
+# }
+```
+
+---
+
+## Step 6: Arrays (2 minutes)
+
+Generate lists of items:
+
+```dsl
+Order:
+  id: uuid
+  items: array(OrderItem, 1..5)
+  tags: array(text(3..10), 1..3)
+
+OrderItem:
+  product_name: text(5..20)
+  quantity: number(1..5)
+  price: money
+```
+
+- `array(OrderItem, 1..5)` - 1 to 5 OrderItem objects
+- `array(text, 1..3)` - 1 to 3 text strings
+
+---
+
+## Step 7: Generate Multiple Records (1 minute)
+
+```ruby
+# Single record
+user = schema.generate
+
+# Multiple records
+users = schema.generate_many(100)
+
+# With seed for reproducibility
+users = schema.generate_many(10, seed: 12345)
+```
+
+---
+
+## What You Learned
+
+✅ Basic schema structure  
+✅ Common types (uuid, name, email, number, boolean, date)  
+✅ Optional (`?:`) and nullable (`type?`) fields  
+✅ Enums with weights and constants  
+✅ Nested schemas  
+✅ Arrays  
+✅ Generating single and multiple records  
+
+---
+
+## Next Steps
+
+Ready for more? Check out:
+
+1. [Intermediate Tutorial](intermediate.md) - Cross-references, copy(), shared()
+2. [Advanced Tutorial](advanced.md) - map_by_field(), behaviors, streaming
+3. [Type Reference](../appendices/type_chart.md) - All 50+ built-in types
+4. [CLI Guide](../../tech_example/04_cli_usage.md) - Command-line tools
+