synthra 0.1.0

data/tech_docs/tutorials/template_gallery.md

@@ -0,0 +1,569 @@
+# Schema Template Gallery
+
+Ready-to-use schema templates for common use cases. Copy, paste, and customize!
+
+## Table of Contents
+
+- [API Response Templates](#api-response-templates)
+- [E-Commerce Templates](#e-commerce-templates)
+- [Social Media Templates](#social-media-templates)
+- [User & Authentication Templates](#user--authentication-templates)
+- [Webhook Templates](#webhook-templates)
+- [Database Seeding Templates](#database-seeding-templates)
+- [Testing Templates](#testing-templates)
+
+---
+
+## API Response Templates
+
+### Success Response
+
+```dsl
+APIResponse:
+  success: const(true)
+  data: object
+  timestamp: now
+  request_id: uuid
+```
+
+### Paginated Response
+
+```dsl
+PaginatedResponse:
+  success: const(true)
+  data: array(Item, 10..25)
+  pagination: Pagination
+  timestamp: now
+
+Pagination:
+  page: number(1..10)
+  per_page: const(25)
+  total: number(100..1000)
+  total_pages: number(4..40)
+  has_next: boolean(true:80%)
+  has_prev: boolean(true:70%)
+```
+
+### Error Response
+
+```dsl
+ErrorResponse:
+  success: const(false)
+  error: ErrorDetails
+  timestamp: now
+  request_id: uuid
+
+ErrorDetails:
+  code: enum(VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED)
+  message: text(20..100)
+  field?: text(5..20)
+  details?: array(text(10..50), 0..3)
+```
+
+### API with Behaviors
+
+```dsl
+RealisticAPI:
+  @latency 50..500ms
+  @failure 2%
+  @simulate_error 429:1%
+  @simulate_error 500:0.5%
+  
+  success: boolean(true:95%)
+  data: object
+  timestamp: now
+```
+
+---
+
+## E-Commerce Templates
+
+### Product Catalog
+
+```dsl
+Product:
+  id: uuid(unique: true)
+  name: text(10..50)
+  description: paragraph(1..3)
+  sku: text(8..12)
+  price: money(range: 9.99..999.99)
+  compare_at_price?: money(range: 19.99..1199.99)
+  category: enum(electronics, clothing, home, sports, beauty)
+  tags: array(text(3..15), 1..5)
+  images: array(url, 1..5)
+  in_stock: boolean(true:85%)
+  stock_quantity: number(0..500)
+  rating: number(1..5)
+  review_count: number(0..1000)
+  created_at: past_date(2y)
+  updated_at: past_date(30d)
+```
+
+### Shopping Cart
+
+```dsl
+ShoppingCart:
+  id: uuid
+  user_id: Ref(User.id)
+  items: array(CartItem, 1..10)
+  currency: const("USD")
+  created_at: past_date(7d)
+  updated_at: now
+
+CartItem:
+  product_id: Ref(Product.id)
+  product_name: text(10..50)
+  quantity: number(1..5)
+  unit_price: money(range: 9.99..199.99)
+  variant?: text(5..20)
+```
+
+### Order with Line Items
+
+```dsl
+Order:
+  id: uuid(unique: true)
+  order_number: id_sequence(start: 10000)
+  customer: Customer
+  items: array(OrderItem, 1..5)
+  subtotal: money(range: 29.99..999.99)
+  tax: money(range: 0..100)
+  shipping: money(range: 0..25)
+  total: money(range: 29.99..1200)
+  status: enum(pending:20%, processing:30%, shipped:25%, delivered:20%, cancelled:5%)
+  payment_status: enum(pending:10%, paid:85%, refunded:5%)
+  shipping_address: Address
+  billing_address: Address
+  created_at: past_date(30d)
+  shipped_at?: past_date(7d)
+  delivered_at?: past_date(3d)
+
+OrderItem:
+  id: uuid
+  product_id: Ref(Product.id)
+  product_name: text(10..50)
+  quantity: number(1..3)
+  unit_price: money(range: 9.99..199.99)
+  total: money(range: 9.99..599.97)
+
+Customer:
+  id: uuid
+  email: email
+  name: full_name
+  phone?: phone
+
+Address:
+  street: text(10..50)
+  city: city
+  state: state
+  postal_code: postal_code
+  country: country_code
+```
+
+---
+
+## Social Media Templates
+
+### User Profile
+
+```dsl
+SocialProfile:
+  id: snowflake_id(as: string)
+  username: social_handle
+  display_name: full_name
+  bio: text(20..160)
+  avatar_url: url
+  cover_url?: url
+  website?: url
+  location?: city
+  verified: boolean(false:95%)
+  followers_count: number(0..1000000)
+  following_count: number(0..5000)
+  posts_count: number(0..10000)
+  joined_at: past_date(5y)
+  last_active: past_date(7d)
+```
+
+### Social Post
+
+```dsl
+SocialPost:
+  id: snowflake_id(as: string)
+  author: SocialProfile
+  content: text(10..280)
+  media?: array(MediaAttachment, 0..4)
+  likes_count: number(0..100000)
+  reposts_count: number(0..10000)
+  replies_count: number(0..5000)
+  created_at: past_date(30d)
+  edited_at?: past_date(7d)
+
+MediaAttachment:
+  id: uuid
+  type: enum(image:70%, video:20%, gif:10%)
+  url: url
+  thumbnail_url?: url
+  width: number(320..1920)
+  height: number(240..1080)
+  duration_ms?: number(1000..300000)
+```
+
+### Comment Thread
+
+```dsl
+CommentThread:
+  id: uuid
+  post_id: Ref(SocialPost.id)
+  comments: array(Comment, 1..20)
+  total_count: number(1..1000)
+
+Comment:
+  id: uuid
+  author: SocialProfile
+  content: text(5..500)
+  likes_count: number(0..1000)
+  created_at: past_date(7d)
+  replies?: array(Comment, 0..5)
+```
+
+---
+
+## User & Authentication Templates
+
+### User Account
+
+```dsl
+User:
+  @version 2.0
+  
+  id: uuid(unique: true)
+  email: email(unique: true)
+  username: username
+  password_hash: text(60..60)
+  first_name: first_name
+  last_name: last_name
+  phone?: phone
+  avatar_url?: url
+  role: enum(user:85%, admin:5%, moderator:10%)
+  status: enum(active:90%, pending:5%, suspended:3%, deleted:2%)
+  email_verified: boolean(true:80%)
+  two_factor_enabled: boolean(false:90%)
+  created_at: past_date(2y)
+  updated_at: past_date(30d)
+  last_login_at?: past_date(7d)
+```
+
+### Authentication Token
+
+```dsl
+AuthToken:
+  access_token: uuid
+  refresh_token: uuid
+  token_type: const("Bearer")
+  expires_in: const(3600)
+  scope: enum(read, write, admin)
+  created_at: now
+```
+
+### Session
+
+```dsl
+Session:
+  id: uuid
+  user_id: Ref(User.id)
+  ip_address: ip
+  user_agent: user_agent
+  device_type: enum(desktop:50%, mobile:40%, tablet:10%)
+  location?: city
+  created_at: past_date(7d)
+  expires_at: future_date(7d)
+  last_active_at: past_date(1d)
+```
+
+---
+
+## Webhook Templates
+
+### Generic Webhook Event
+
+```dsl
+WebhookEvent:
+  id: uuid
+  type: enum(created, updated, deleted)
+  resource: enum(user, order, product, payment)
+  resource_id: uuid
+  timestamp: unix_timestamp_ms
+  data: object
+  signature: text(64)
+```
+
+### Payment Webhook (Stripe-style)
+
+```dsl
+PaymentWebhook:
+  id: text(27..27)
+  object: const("event")
+  type: enum(payment_intent.succeeded:60%, payment_intent.failed:10%, charge.refunded:10%, customer.subscription.created:20%)
+  created: unix_timestamp
+  data: PaymentEventData
+  livemode: boolean(false:90%)
+  pending_webhooks: number(0..3)
+  request: WebhookRequest
+
+PaymentEventData:
+  object: PaymentIntent
+
+PaymentIntent:
+  id: text(27..27)
+  object: const("payment_intent")
+  amount: number(100..100000)
+  currency: enum(usd:80%, eur:15%, gbp:5%)
+  status: enum(succeeded:85%, failed:10%, canceled:5%)
+  customer: text(18..18)
+
+WebhookRequest:
+  id: text(24..24)
+  idempotency_key?: uuid
+```
+
+### Twitter DM Webhook (Complete)
+
+```dsl
+TwitterDMWebhook:
+  for_user_id: copy("users.recipient.id")
+  direct_message_events: array(DMEvent, 1..1)
+  users: map_by_field("id", sender: TwitterUser, recipient: shared(TwitterUser))
+
+DMEvent:
+  type: const("message_create")
+  id: snowflake_id(as: string)
+  created_timestamp: unix_timestamp_ms(as: string)
+  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(as: string)
+  name: full_name
+  screen_name: social_handle
+  location?: city
+  verified: boolean(false:95%)
+  followers_count: number(10..1000000)
+  friends_count: number(5..5000)
+```
+
+---
+
+## Database Seeding Templates
+
+### Blog System
+
+```dsl
+Author:
+  id: uuid(unique: true)
+  name: full_name
+  email: email(unique: true)
+  bio: text(50..200)
+  avatar_url: url
+  created_at: past_date(2y)
+
+Post:
+  id: uuid(unique: true)
+  title: text(20..100)
+  slug: text(20..50)
+  content: paragraph(5..15)
+  excerpt: text(100..200)
+  author: Author
+  category: Category
+  tags: array(text(3..15), 1..5)
+  status: enum(draft:20%, published:70%, archived:10%)
+  featured: boolean(false:90%)
+  views: number(0..100000)
+  created_at: past_date(1y)
+  published_at?: past_date(11m)
+  updated_at: past_date(30d)
+
+Category:
+  id: uuid
+  name: text(5..30)
+  slug: text(5..30)
+  description?: text(20..100)
+```
+
+### Multi-tenant SaaS
+
+```dsl
+Organization:
+  id: uuid(unique: true)
+  name: text(5..50)
+  slug: text(5..30)
+  plan: enum(free:40%, starter:30%, pro:20%, enterprise:10%)
+  status: enum(active:85%, trial:10%, suspended:5%)
+  member_count: number(1..100)
+  created_at: past_date(2y)
+
+Member:
+  id: uuid(unique: true)
+  organization_id: Ref(Organization.id)
+  user_id: Ref(User.id)
+  role: enum(owner:5%, admin:15%, member:80%)
+  invited_by?: Ref(User.id)
+  joined_at: past_date(1y)
+```
+
+---
+
+## Testing Templates
+
+### Edge Case User
+
+```dsl
+EdgeCaseUser:
+  id: uuid
+  name: enum("", "A", "Test User With A Very Long Name That Exceeds Normal Limits", "User123", "user@special#chars")
+  email: enum("test@test.com", "a@b.co", "very.long.email.address@subdomain.example.com")
+  age: enum(0, 1, 13, 18, 65, 100, 120)
+  balance: enum(0, -1, 0.01, 999999.99)
+```
+
+### Load Testing Records
+
+```dsl
+LoadTestRecord:
+  id: uuid(unique: true)
+  data: text(100..1000)
+  timestamp: now
+  sequence: id_sequence
+```
+
+### Mixed Mode Testing
+
+```dsl
+MixedModeRecord:
+  required_field: text(10..50)
+  optional_field?: text(10..50)
+  nullable_field: text?
+  both_field?: text?
+  conditional_field: text if has_feature
+  has_feature: boolean
+```
+
+---
+
+## How to Use These Templates
+
+### 1. Copy and Save
+
+```bash
+# Save to a file
+cat > schemas/user.dsl << 'EOF'
+User:
+  id: uuid
+  name: full_name
+  email: email
+EOF
+```
+
+### 2. Validate
+
+```bash
+fake_data_dsl validate schemas/user.dsl
+fake_data_dsl lint schemas/
+```
+
+### 3. Preview
+
+```bash
+fake_data_dsl preview User --dir schemas
+```
+
+### 4. Generate
+
+```bash
+# Single record
+fake_data_dsl generate User --dir schemas --pretty
+
+# Multiple records
+fake_data_dsl generate User --dir schemas --count 100
+
+# With seed for reproducibility
+fake_data_dsl generate User --dir schemas --count 10 --seed 12345
+```
+
+### 5. Export
+
+```bash
+# JSON Schema for API documentation
+fake_data_dsl export User --dir schemas --format json-schema
+
+# TypeScript for frontend
+fake_data_dsl export User --dir schemas --format typescript
+```
+
+---
+
+## Customization Tips
+
+### Adding Custom Fields
+
+```dsl
+# Start with a template
+User:
+  id: uuid
+  name: full_name
+  email: email
+  
+  # Add your custom fields
+  department: enum(engineering, sales, marketing, support)
+  employee_id: id_sequence(start: 1000)
+  hire_date: past_date(5y)
+```
+
+### Combining Templates
+
+```dsl
+# Import concepts from multiple templates
+OrderWithUser:
+  order: Order
+  customer: User
+  payment: PaymentIntent
+```
+
+### Adjusting Probabilities
+
+```dsl
+# Make most users active
+User:
+  status: enum(active:95%, suspended:3%, deleted:2%)
+  
+# Make failures rare in testing
+APIResponse:
+  @failure 0.1%
+  success: boolean(true:99.9%)
+```
+
+---
+
+## Next Steps
+
+- [Getting Started Tutorial](getting_started.md)
+- [Intermediate Tutorial](intermediate.md)  
+- [Advanced Tutorial](advanced.md)
+- [Type Reference](../appendices/type_chart.md)
+