synthra 0.1.0

data/tech_docs/tutorials/intermediate.md

@@ -0,0 +1,231 @@
+# Intermediate Tutorial
+
+Learn cross-references, copy(), and shared() for realistic data.
+
+## Difficulty: Intermediate
+## Time: 30 minutes
+## Prerequisites: [Getting Started](getting_started.md)
+
+---
+
+## Step 1: The Problem with Independent IDs
+
+Consider this e-commerce schema:
+
+```dsl
+Order:
+  id: uuid
+  user: User
+  user_id: uuid        # ❌ This generates a DIFFERENT uuid!
+
+User:
+  id: uuid
+  name: full_name
+```
+
+The `user_id` field generates a random UUID that doesn't match `user.id`. That's not realistic!
+
+---
+
+## Step 2: copy() - Link Related Fields
+
+Use `copy()` to reference values from already-generated fields:
+
+```dsl
+Order:
+  user: User
+  user_id: copy("user.id")    # ✅ Same ID as user.id
+
+User:
+  id: uuid
+  name: full_name
+```
+
+Now `user_id` will always equal `user.id`!
+
+### Important Rule: Field Order
+
+`copy()` can only reference fields defined **BEFORE** it:
+
+```dsl
+# ✅ CORRECT - user defined before user_id
+Order:
+  user: User
+  user_id: copy("user.id")
+
+# ❌ WRONG - user_id before user
+Order:
+  user_id: copy("user.id")    # Will be nil!
+  user: User
+```
+
+---
+
+## Step 3: Ref() - Cross-Schema References
+
+`Ref()` generates a value matching another schema's field type:
+
+```dsl
+Order:
+  id: uuid
+  customer_id: Ref(Customer.id)    # Generates a UUID (same type as Customer.id)
+
+Customer:
+  id: uuid
+  name: full_name
+```
+
+### Ref() vs copy() - Know the Difference!
+
+| Feature | `Ref(Schema.field)` | `copy("path")` |
+|---------|---------------------|----------------|
+| What it does | Generates NEW value | Copies EXISTING value |
+| When to use | Foreign keys | Linking nested IDs |
+
+---
+
+## Step 4: shared() - Same Value Across Batch
+
+In batch generation, `shared()` keeps a value consistent across all records:
+
+```dsl
+Notification:
+  recipient: shared(User)        # SAME user for all notifications
+  sender: User                    # DIFFERENT user each time
+  message: text
+
+User:
+  id: uuid
+  name: full_name
+```
+
+Generate a batch:
+
+```ruby
+notifications = schema.generate_many(10, registry: registry)
+
+# All 10 notifications have the SAME recipient
+# But different senders
+```
+
+### Important: shared() requires generate_many()
+
+```ruby
+# ✅ CORRECT - shared() works
+notifications = schema.generate_many(10, registry: registry)
+
+# ⚠️ WARNING - shared() doesn't share across separate generate() calls
+n1 = schema.generate(registry: registry)
+n2 = schema.generate(registry: registry)
+# n1.recipient != n2.recipient
+```
+
+---
+
+## Step 5: Combining copy() with Nested Schemas
+
+Real-world example - Twitter DM:
+
+```dsl
+DirectMessage:
+  sender: User
+  sender_id: copy("sender.id")        # Links to sender
+  recipient: User
+  recipient_id: copy("recipient.id")  # Links to recipient
+  text: message_text
+
+User:
+  id: snowflake_id
+  name: full_name
+```
+
+The `sender_id` always matches `sender.id`, and `recipient_id` always matches `recipient.id`.
+
+---
+
+## Step 6: Using Registry for Multiple Schemas
+
+When you have multiple schemas that reference each other:
+
+```ruby
+# Create registry and load schemas
+registry = FakeDataDSL::Registry.new
+registry.load_file('schemas/user.dsl')
+registry.load_file('schemas/order.dsl')
+
+# Or load entire directory
+registry.load_dir('schemas/')
+
+# Generate with registry for cross-references
+order = registry.schema('Order').generate(registry: registry)
+```
+
+---
+
+## Step 7: Validation and Error Messages
+
+FakeDataDSL validates your schemas:
+
+```dsl
+Order:
+  user_id: copy("users.id")    # Typo: "users" instead of "user"
+```
+
+Error message:
+
+```
+Path 'users.id' not found in schema
+Did you mean: user.id?
+```
+
+Field order validation:
+
+```dsl
+Order:
+  user_id: copy("user.id")    # ❌ user not defined yet!
+  user: User
+```
+
+Error:
+
+```
+Field order error in 'Order': 'user_id' uses copy("user.id") but the source field is defined after it
+Did you mean: Move 'user' field before 'user_id' in schema 'Order'?
+```
+
+---
+
+## Practice Exercise
+
+Create schemas for a blog system:
+
+1. `Author` - id, name, email
+2. `Post` - id, author (nested), author_id (copy), title, content
+3. `Comment` - id, post_id (Ref), author (nested), author_id (copy), text
+
+Verify that:
+- `post.author_id` equals `post.author.id`
+- `comment.author_id` equals `comment.author.id`
+- `comment.post_id` is a valid UUID
+
+---
+
+## What You Learned
+
+✅ `copy()` - Reference existing generated values  
+✅ `Ref()` - Generate values matching another schema's type  
+✅ `shared()` - Keep value consistent across batch  
+✅ Field order matters for `copy()`  
+✅ Registry for multi-schema projects  
+✅ Error messages help find mistakes  
+
+---
+
+## Next Steps
+
+Ready for advanced features?
+
+1. [Advanced Tutorial](advanced.md) - map_by_field(), behaviors, streaming
+2. [Complex Types Reference](../dsl/complex_types.md)
+3. [Twitter DM Example](../../tech_example/13_twitter_dm_example.rb)
+