synthra 0.1.0

data/tech_docs/quick_start.md

@@ -0,0 +1,256 @@
+# Quick Start Guide
+
+Get up and running with FakeDataDSL in 5 minutes.
+
+## Table of Contents
+
+- [Step 1: Create Your First Schema](#step-1-create-your-first-schema)
+- [Step 2: Generate Data in Ruby](#step-2-generate-data-in-ruby)
+- [Step 3: Use the CLI](#step-3-use-the-cli)
+- [Step 4: Advanced Features](#step-4-advanced-features)
+- [Next Steps](#next-steps)
+
+---
+
+## Step 1: Create Your First Schema
+
+Create a file `schemas/user.dsl`:
+
+```dsl
+# User schema - my first FakeDataDSL schema
+User:
+  id: uuid
+  name: name
+  email: email
+  age: number(18..65)
+  active: boolean
+  role: enum(user, admin, moderator)
+  created_at: past_date(1y)
+```
+
+### Understanding the Schema
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `uuid` | Generates a unique UUID v4 |
+| `name` | `name` | Generates a realistic full name |
+| `email` | `email` | Generates a realistic email address |
+| `age` | `number(18..65)` | Generates an integer between 18 and 65 |
+| `active` | `boolean` | Generates true or false |
+| `role` | `enum(...)` | Randomly selects one of the values |
+| `created_at` | `past_date(1y)` | Generates a date within the past year |
+
+---
+
+## Step 2: Generate Data in Ruby
+
+### Load and Generate
+
+```ruby
+require 'fake_data_dsl'
+
+# Load the schema
+schema = FakeDataDSL.load('schemas/user.dsl')
+
+# Generate a single user
+user = schema.generate
+puts user
+# Output:
+# {
+#   "id" => "550e8400-e29b-41d4-a716-446655440000",
+#   "name" => "John Smith",
+#   "email" => "john.smith@example.com",
+#   "age" => 34,
+#   "active" => true,
+#   "role" => "user",
+#   "created_at" => "2024-06-15"
+# }
+```
+
+### Generate Multiple Records
+
+```ruby
+# Generate 10 users
+users = schema.generate_many(10)
+users.each do |user|
+  puts "#{user['name']} - #{user['email']}"
+end
+```
+
+### Generate with Seed (Reproducible)
+
+```ruby
+# Same seed = same output
+user1 = schema.generate(seed: 12345)
+user2 = schema.generate(seed: 12345)
+
+user1 == user2  # => true
+```
+
+### Generate JSON Output
+
+```ruby
+# Get JSON string
+json = schema.generate_json
+puts json
+# => {"id":"550e8400...","name":"John Smith",...}
+
+# Pretty printed JSON
+pretty_json = schema.generate_json(pretty: true)
+puts pretty_json
+# {
+#   "id": "550e8400-e29b-41d4-a716-446655440000",
+#   "name": "John Smith",
+#   ...
+# }
+```
+
+---
+
+## Step 3: Use the CLI
+
+### Validate Your Schema
+
+```bash
+fake_data_dsl validate schemas/user.dsl
+# ✓ schemas/user.dsl is valid
+```
+
+### Generate Data
+
+```bash
+# Generate one user
+fake_data_dsl generate User --dir schemas
+
+# Generate 10 users
+fake_data_dsl generate User --dir schemas --count 10
+
+# Pretty print output
+fake_data_dsl generate User --dir schemas --pretty
+
+# Save to file
+fake_data_dsl generate User --dir schemas --count 100 > users.json
+```
+
+### Different Output Formats
+
+```bash
+# JSON array (default)
+fake_data_dsl generate User --dir schemas --count 3
+# [{"id":"...","name":"John"},{"id":"...","name":"Jane"},...]
+
+# NDJSON (newline-delimited JSON)
+fake_data_dsl generate User --dir schemas --count 3 --ndjson
+# {"id":"...","name":"John"}
+# {"id":"...","name":"Jane"}
+# {"id":"...","name":"Bob"}
+```
+
+---
+
+## Step 4: Advanced Features
+
+### Add Related Schemas
+
+Create `schemas/order.dsl`:
+
+```dsl
+Order:
+  id: uuid
+  user_id: Ref(User.id)
+  total: money(range: 10..500)
+  status: enum(pending, shipped, delivered)
+  created_at: past_date(30d)
+
+LineItem:
+  product_name: text(10..50)
+  quantity: number(1..5)
+  price: number(9.99..99.99)
+```
+
+### Use a Registry for Multiple Schemas
+
+```ruby
+require 'fake_data_dsl'
+
+# Create registry and load all schemas
+registry = FakeDataDSL::Registry.new
+registry.load_dir('schemas/')
+
+# Generate with cross-schema references
+order = registry.schema('Order').generate(registry: registry)
+# order["user_id"] will be a valid UUID
+
+# Generate user and their orders
+user = registry.schema('User').generate
+orders = 3.times.map do
+  registry.schema('Order').generate(
+    registry: registry,
+    overrides: { 'user_id' => user['id'] }
+  )
+end
+```
+
+### Different Generation Modes
+
+```ruby
+# Normal/random data (default)
+user = schema.generate(mode: :random)
+# => {"name"=>"John Smith", "age"=>34, ...}
+
+# Edge case data (boundary values)
+user = schema.generate(mode: :edge)
+# => {"name"=>"", "age"=>0, ...}
+
+# Invalid data (for validation testing)
+user = schema.generate(mode: :invalid)
+# => {"name"=>nil, "age"=>"not_a_number", ...}
+
+# Mixed (80% random, 15% edge, 5% invalid)
+user = schema.generate(mode: :mixed)
+```
+
+### Add Behaviors
+
+```dsl
+# Schema with behaviors
+SlowAPI:
+  @latency 100..500ms
+  @failure 5%
+  
+  id: uuid
+  data: text(50..200)
+  timestamp: now
+```
+
+```ruby
+schema = FakeDataDSL.load('schemas/slow_api.dsl')
+
+begin
+  data = schema.generate
+rescue FakeDataDSL::Errors::SimulatedFailure
+  puts "Simulated failure occurred!"
+end
+```
+
+---
+
+## Next Steps
+
+Now that you have the basics:
+
+1. **Learn the DSL**: Read [Schema Definition](dsl/schema_definition.md) for complete syntax
+2. **Explore Types**: Check [Core Types](dsl/core_types.md) for all available types
+3. **Master the API**: See [API Overview](api/overview.md) for complete Ruby API
+4. **See Examples**: Browse [Examples](../tech_example/README.md) for real-world usage
+
+### Common Use Cases
+
+| Use Case | Documentation |
+|----------|---------------|
+| Testing API responses | [Behaviors](behaviors/overview.md) |
+| Database seeding | [Examples: Database](../tech_example/database_seeding.md) |
+| Generating test fixtures | [RSpec Integration](integration/rspec.md) |
+| Load testing | [Streaming Generation](advanced/streaming.md) |
+| Property-based testing | [Generation Modes](modes/overview.md) |
+