synthra 0.1.0

data/docs/advanced_features.md

@@ -0,0 +1,183 @@
+# Advanced Features
+
+Advanced features for complex data generation scenarios.
+
+## Cross-Schema References
+
+Reference fields from other schemas:
+
+```ruby
+User:
+  id: uuid
+  name: name
+
+Order:
+  id: uuid
+  user_id: reference(User, id)  # References User's id
+  total: number(10..1000)
+```
+
+**Benefits:**
+- Maintain referential integrity
+- Generate related data sets
+- Test foreign key relationships
+
+## Custom Functions
+
+Define custom generation logic:
+
+```ruby
+# Register a custom function
+FakeDataDSL.register_function(:generate_slug) do |context|
+  name = context["name"] || "default"
+  name.downcase.gsub(/\s+/, '-')
+end
+
+# Use in schema
+User:
+  name: name
+  slug: custom(:generate_slug)
+```
+
+**Function context:**
+- Receives current generation context
+- Can access previously generated fields
+- Returns generated value
+
+## Streaming Generation
+
+Generate large datasets efficiently:
+
+```ruby
+schema = registry.schema('User')
+
+# Stream records (lazy evaluation)
+schema.generate_many_stream(1000).each do |record|
+  # Process each record
+  puts record
+end
+```
+
+**Benefits:**
+- Memory efficient
+- Can process records as they're generated
+- Suitable for large datasets
+
+## Deterministic Generation
+
+Use seeds for reproducible data:
+
+```ruby
+# Set seed
+FakeDataDSL.configure do |config|
+  config.seed = 12345
+end
+
+# Generate (same seed = same data)
+record1 = schema.generate
+record2 = schema.generate
+# record1 and record2 are deterministic
+```
+
+**Use cases:**
+- Reproducible tests
+- Debugging
+- Consistent demo data
+
+## Formula Fields
+
+Compute values from other fields:
+
+```ruby
+Order:
+  quantity: number(1..10)
+  unit_price: number(10..100)
+  total: formula(quantity * unit_price)
+  tax: formula(total * 0.08)
+  grand_total: formula(total + tax)
+```
+
+**Supported operations:**
+- Arithmetic: `+`, `-`, `*`, `/`
+- Field references: `price`, `quantity`
+- Constants: `0.08`, `100`
+
+## Template Fields
+
+String interpolation with field values:
+
+```ruby
+User:
+  first_name: first_name
+  last_name: last_name
+  greeting: template("Hello {first_name} {last_name}!")
+  email_template: template("{first_name}.{last_name}@example.com")
+```
+
+**Placeholders:**
+- `{field_name}` - Replaced with field value
+- Supports multiple placeholders
+
+## Conditional Fields
+
+Fields that depend on other fields:
+
+```ruby
+User:
+  is_admin: boolean
+  admin_key: text if is_admin
+  is_active: boolean
+  deactivated_at: date if !is_active
+```
+
+**Conditions:**
+- `if field_name` - When field is truthy
+- `if !field_name` - When field is falsy
+
+## Uniqueness Constraints
+
+Ensure unique values:
+
+```ruby
+User:
+  email: email unique
+  username: username unique
+```
+
+**Scope:**
+- Per-schema generation
+- Per-Engine instance
+- Resets between runs
+
+## Resource Limits
+
+Configure limits to prevent DoS:
+
+```ruby
+FakeDataDSL.configure do |config|
+  config.max_recursion = 10
+  config.max_array_size = 1000
+  config.max_text_length = 10000
+  config.max_latency = 5000  # milliseconds
+end
+```
+
+## Observability
+
+Add logging and metrics:
+
+```ruby
+FakeDataDSL.configure do |config|
+  config.logger = Logger.new(STDOUT)
+  config.metrics_collector = MyMetricsCollector.new
+  config.on_field_generated = proc do |schema, field, value|
+    puts "Generated #{field} for #{schema}: #{value}"
+  end
+end
+```
+
+## See Also
+
+- [Examples](examples.md) - Advanced usage examples
+- [API Reference](api_reference.md) - Programmatic API
+

data/docs/api_reference.md

@@ -0,0 +1,153 @@
+# API Reference
+
+Programmatic API for FakeDataDSL.
+
+## Registry
+
+The `Registry` class manages schema definitions.
+
+### Loading Schemas
+
+```ruby
+registry = FakeDataDSL::Registry.new
+
+# Load from file
+registry.load_file('schemas/user.dsl')
+
+# Load from string
+registry.load_string(<<~DSL)
+  User:
+    id: uuid
+    name: name
+DSL
+
+# Load from directory
+registry.load_dir('schemas/')
+```
+
+### Accessing Schemas
+
+```ruby
+# Get a schema
+schema = registry.schema('User')
+
+# Check if schema exists
+if registry.schema?('User')
+  # ...
+end
+
+# List all schema names
+names = registry.names
+# => ["User", "Order", "Product"]
+```
+
+## Schema
+
+The `Schema` class represents a data schema.
+
+### Generating Data
+
+```ruby
+schema = registry.schema('User')
+
+# Generate single record
+record = schema.generate
+# => { "id" => "...", "name" => "..." }
+
+# Generate multiple records
+records = schema.generate_many(10)
+# => Array of 10 records
+
+# Stream records (lazy)
+schema.generate_many_stream(1000).each do |record|
+  # Process each record
+end
+```
+
+### Configuration
+
+```ruby
+# Set default mode
+schema.default_mode = :edge
+
+# Generate with specific mode
+record = schema.generate(mode: :invalid)
+
+# Generate with overrides
+record = schema.generate(overrides: { "name" => "Custom Name" })
+```
+
+## Configuration
+
+Global configuration:
+
+```ruby
+FakeDataDSL.configure do |config|
+  # Seed for deterministic generation
+  config.seed = 12345
+  
+  # Resource limits
+  config.max_recursion = 10
+  config.max_array_size = 1000
+  config.max_text_length = 10000
+  config.max_latency = 5000
+  
+  # Observability
+  config.logger = Logger.new(STDOUT)
+  config.metrics_collector = MyMetricsCollector.new
+  config.on_field_generated = proc do |schema, field, value|
+    # Custom callback
+  end
+end
+```
+
+## Custom Types
+
+Register custom types:
+
+```ruby
+FakeDataDSL.register_type(:my_type) do |rng, context, args|
+  # Generate value
+  "custom_value_#{rng.int(1, 100)}"
+end
+
+# Use in schema
+MySchema:
+  value: my_type
+```
+
+## Custom Functions
+
+Register custom functions:
+
+```ruby
+FakeDataDSL.register_function(:slugify) do |context|
+  name = context["name"] || "default"
+  name.downcase.gsub(/\s+/, '-')
+end
+
+# Use in schema
+User:
+  name: name
+  slug: custom(:slugify)
+```
+
+## Custom Behaviors
+
+Register custom behaviors:
+
+```ruby
+FakeDataDSL.register_behavior(:my_behavior) do |field, args|
+  # Custom behavior logic
+end
+
+# Use in schema
+User:
+  name: name @my_behavior(arg1, arg2)
+```
+
+## See Also
+
+- [Getting Started](getting_started.md) - Basic usage
+- [DSL Reference](dsl_reference.md) - DSL syntax
+

data/docs/behaviors.md

@@ -0,0 +1,138 @@
+# Behaviors Guide
+
+Behaviors modify how data is generated, adding delays, failures, and other effects.
+
+## Available Behaviors
+
+### Latency
+
+Add delays to simulate network or processing time:
+
+```ruby
+User:
+  @latency 100ms    # Schema-level: all fields delayed
+  id: uuid
+  name: name @latency 50ms  # Field-level: specific delay
+```
+
+**Arguments:**
+- Duration: `100ms`, `2s`, `500ms`, etc.
+- Range: `@latency 50ms..200ms` (random delay in range)
+
+### Failure
+
+Simulate failures with a probability:
+
+```ruby
+User:
+  @failure 5%       # 5% chance of failure
+  id: uuid
+  name: name @failure 1%  # 1% chance for this field
+```
+
+**Arguments:**
+- Percentage: `5%`, `10%`, `0.5%`
+
+### Partial Data
+
+Sometimes omit fields:
+
+```ruby
+User:
+  @partial_data 20%  # 20% chance of missing fields
+  id: uuid
+  name: name
+  email: email
+```
+
+**Arguments:**
+- Percentage: `20%`, `10%`
+
+### Randomize Order
+
+Randomize field generation order:
+
+```ruby
+User:
+  @randomize_order
+  id: uuid
+  name: name
+  email: email
+```
+
+### Simulate Error
+
+Simulate specific errors:
+
+```ruby
+User:
+  @simulate_error StandardError, "Database connection failed"
+  id: uuid
+```
+
+**Arguments:**
+- Error class: `StandardError`, `TimeoutError`, etc.
+- Message: Error message string
+
+### Close Connection
+
+Simulate connection closure:
+
+```ruby
+User:
+  @close_connection
+  id: uuid
+```
+
+## Behavior Placement
+
+### Schema-Level
+
+Apply to all fields in a schema:
+
+```ruby
+User:
+  @latency 100ms
+  @failure 5%
+  id: uuid
+  name: name
+```
+
+### Field-Level
+
+Apply to specific fields:
+
+```ruby
+User:
+  id: uuid @latency 50ms
+  name: name @failure 1%
+  email: email @partial_data 10%
+```
+
+## Combining Behaviors
+
+You can combine multiple behaviors:
+
+```ruby
+User:
+  @latency 100ms
+  @failure 5%
+  id: uuid @latency 50ms  # Field-level overrides schema-level
+  name: name @failure 1%
+```
+
+## Custom Behaviors
+
+Register custom behaviors:
+
+```ruby
+FakeDataDSL.register_behavior(:my_behavior) do |field, args|
+  # Custom behavior logic
+end
+```
+
+## See Also
+
+- [Generation Modes](generation_modes.md) - How behaviors interact with modes
+- [Examples](examples.md) - Real-world usage
+

data/docs/best_practices.md

@@ -0,0 +1,191 @@
+# Best Practices
+
+Tips and recommendations for using FakeDataDSL effectively.
+
+## Schema Organization
+
+### Use Descriptive Names
+
+```ruby
+# Good
+User:
+  id: uuid
+  email: email
+
+# Bad
+U:
+  i: uuid
+  e: email
+```
+
+### Group Related Schemas
+
+```ruby
+# schemas/users.dsl
+User:
+  id: uuid
+  name: name
+
+# schemas/orders.dsl
+Order:
+  id: uuid
+  user_id: reference(User, id)
+```
+
+### Use Comments
+
+```ruby
+User:
+  # Primary identifier
+  id: uuid
+  
+  # User's email address (must be unique)
+  email: email unique
+  
+  # Optional phone number
+  phone: phone optional
+```
+
+## Type Selection
+
+### Choose Appropriate Types
+
+```ruby
+# Good - specific types
+User:
+  email: email
+  age: number(18..65)
+  created_at: past_date(days: 365)
+
+# Bad - generic types
+User:
+  email: text
+  age: text
+  created_at: text
+```
+
+### Use Ranges for Numbers
+
+```ruby
+# Good - realistic ranges
+age: number(18..65)
+price: number(min: 10, max: 1000)
+
+# Bad - too wide
+age: number(0..1000)
+price: number
+```
+
+## Performance
+
+### Use Streaming for Large Datasets
+
+```ruby
+# Good - memory efficient
+schema.generate_many_stream(10000).each do |record|
+  process(record)
+end
+
+# Bad - loads all into memory
+records = schema.generate_many(10000)
+records.each { |r| process(r) }
+```
+
+### Limit Resource Usage
+
+```ruby
+# Configure limits
+FakeDataDSL.configure do |config|
+  config.max_array_size = 100
+  config.max_text_length = 1000
+end
+```
+
+## Testing
+
+### Use Deterministic Seeds
+
+```ruby
+# In tests
+FakeDataDSL.configure { |c| c.seed = 12345 }
+
+# Generate same data every time
+record1 = schema.generate
+record2 = schema.generate
+# record1 == record2 (with same seed)
+```
+
+### Test Edge Cases
+
+```ruby
+# Generate edge cases
+edge_records = schema.generate_many(100, mode: :edge)
+
+# Test validation
+edge_records.each do |record|
+  expect { validate(record) }.not_to raise_error
+end
+```
+
+### Test Invalid Data
+
+```ruby
+# Generate invalid data
+invalid_records = schema.generate_many(100, mode: :invalid)
+
+# Test error handling
+invalid_records.each do |record|
+  expect { create(record) }.to raise_error(ValidationError)
+end
+```
+
+## Security
+
+### Validate Input
+
+```ruby
+# Always validate generated data
+record = schema.generate
+validate_record(record)  # Your validation logic
+```
+
+### Use Limits
+
+```ruby
+# Prevent DoS
+FakeDataDSL.configure do |config|
+  config.max_recursion = 10
+  config.max_array_size = 1000
+end
+```
+
+## Maintainability
+
+### Version Control Schemas
+
+```ruby
+# Keep schemas in version control
+# schemas/v1/user.dsl
+# schemas/v2/user.dsl
+```
+
+### Document Complex Schemas
+
+```ruby
+# Complex schema with explanation
+Order:
+  # Calculated from quantity and unit_price
+  total: formula(quantity * unit_price)
+  
+  # Tax is 8% of total
+  tax: formula(total * 0.08)
+  
+  # Grand total includes tax
+  grand_total: formula(total + tax)
+```
+
+## See Also
+
+- [Examples](examples.md) - Real-world examples
+- [Troubleshooting](troubleshooting.md) - Common issues
+