synthra 0.1.0

data/tech_docs/dsl/core_types.md

@@ -0,0 +1,464 @@
+# Core Types Reference
+
+Complete reference for all core types in FakeDataDSL.
+
+## Table of Contents
+
+- [Identifier Types](#identifier-types)
+- [Text Types](#text-types)
+- [Number Types](#number-types)
+- [Boolean Type](#boolean-type)
+- [Enum Type](#enum-type)
+- [Date and Time Types](#date-and-time-types)
+
+---
+
+## Identifier Types
+
+### uuid
+
+Generates a UUID (Universally Unique Identifier).
+
+```dsl
+User:
+  id: uuid
+  id_v4: uuid(version: 4)   # UUID v4 (random) - default
+  id_v6: uuid(version: 6)   # UUID v6 (time-ordered)
+  id_v7: uuid(version: 7)   # UUID v7 (Unix timestamp)
+```
+
+| Argument | Type | Default | Description |
+|----------|------|---------|-------------|
+| `version` | Integer | 4 | UUID version (4, 6, or 7) |
+| `unique` | Boolean | false | Ensure uniqueness within batch |
+
+**Examples:**
+```
+# v4 (random)
+"550e8400-e29b-41d4-a716-446655440000"
+
+# v7 (time-sortable)
+"018e1c7c-8b1a-7000-8000-000000000000"
+```
+
+### ulid
+
+Generates a ULID (Universally Unique Lexicographically Sortable Identifier).
+
+```dsl
+Event:
+  id: ulid
+```
+
+**Example:** `"01ARZ3NDEKTSV4RRFQ69G5FAV"`
+
+### id_sequence
+
+Generates auto-incrementing integer IDs.
+
+```dsl
+User:
+  id: id_sequence
+  id_from_100: id_sequence(start: 100)
+```
+
+| Argument | Type | Default | Description |
+|----------|------|---------|-------------|
+| `start` | Integer | 1 | Starting value |
+| `step` | Integer | 1 | Increment amount |
+
+**Examples:** `1`, `2`, `3`, ...
+
+---
+
+## Text Types
+
+### text
+
+Generates random text/string.
+
+```dsl
+User:
+  bio: text
+  short_bio: text(10..50)
+  exact_length: text(20)
+  long_text: text(min: 100, max: 500)
+```
+
+| Argument | Type | Default | Description |
+|----------|------|---------|-------------|
+| `min..max` | Range | 10..100 | Character length range |
+| `length` | Integer | - | Exact length |
+| `min` | Integer | 10 | Minimum length |
+| `max` | Integer | 100 | Maximum length |
+
+### name
+
+Generates a realistic full name.
+
+```dsl
+User:
+  name: name
+```
+
+**Examples:** `"John Smith"`, `"Maria Garcia"`, `"李明"`
+
+### first_name
+
+Generates a first name.
+
+```dsl
+User:
+  first_name: first_name
+```
+
+**Examples:** `"John"`, `"Maria"`, `"Ahmed"`
+
+### last_name
+
+Generates a last name.
+
+```dsl
+User:
+  last_name: last_name
+```
+
+**Examples:** `"Smith"`, `"García"`, `"田中"`
+
+### email
+
+Generates an email address.
+
+```dsl
+User:
+  email: email
+  unique_email: email(unique: true)
+```
+
+| Argument | Type | Default | Description |
+|----------|------|---------|-------------|
+| `unique` | Boolean | false | Ensure uniqueness |
+
+**Examples:** `"john.smith@example.com"`, `"maria_garcia123@mail.net"`
+
+### username
+
+Generates a username.
+
+```dsl
+User:
+  username: username
+```
+
+**Examples:** `"john_smith42"`, `"cool_user_99"`
+
+### password
+
+Generates a password string.
+
+```dsl
+User:
+  password: password
+  strong_password: password(length: 16)
+```
+
+| Argument | Type | Default | Description |
+|----------|------|---------|-------------|
+| `length` | Integer | 12 | Password length |
+
+**Example:** `"Xy7#kL9@mN2$"`
+
+### paragraph
+
+Generates one or more paragraphs.
+
+```dsl
+Article:
+  content: paragraph
+  long_content: paragraph(count: 5)
+```
+
+| Argument | Type | Default | Description |
+|----------|------|---------|-------------|
+| `count` | Integer | 1 | Number of paragraphs |
+
+### sentence
+
+Generates one or more sentences.
+
+```dsl
+Article:
+  summary: sentence
+  description: sentence(count: 3)
+```
+
+| Argument | Type | Default | Description |
+|----------|------|---------|-------------|
+| `count` | Integer | 1 | Number of sentences |
+
+### word
+
+Generates one or more words.
+
+```dsl
+Tag:
+  name: word
+  multi_word: word(count: 3)
+```
+
+| Argument | Type | Default | Description |
+|----------|------|---------|-------------|
+| `count` | Integer | 1 | Number of words |
+
+---
+
+## Number Types
+
+### number
+
+Generates integer or floating-point numbers.
+
+```dsl
+Product:
+  quantity: number
+  age: number(18..100)
+  price: number(0.99..999.99)
+  exact: number(42)
+  precise: number(0..100, precision: 2)
+```
+
+| Argument | Type | Default | Description |
+|----------|------|---------|-------------|
+| `min..max` | Range | 0..100 | Value range |
+| `min` | Number | 0 | Minimum value |
+| `max` | Number | 100 | Maximum value |
+| `precision` | Integer | 0 | Decimal places (0=integer) |
+
+**Examples:**
+- `number(1..100)` → `42`
+- `number(0.0..100.0)` → `42.7834`
+- `number(0..100, precision: 2)` → `42.78`
+
+### integer
+
+Alias for `number` with integer output.
+
+```dsl
+User:
+  age: integer(0..120)
+```
+
+### float
+
+Alias for `number` with float output.
+
+```dsl
+Product:
+  rating: float(0.0..5.0)
+```
+
+### latitude
+
+Generates a valid latitude coordinate.
+
+```dsl
+Location:
+  lat: latitude
+```
+
+**Range:** -90.0 to 90.0
+
+### longitude
+
+Generates a valid longitude coordinate.
+
+```dsl
+Location:
+  lng: longitude
+```
+
+**Range:** -180.0 to 180.0
+
+---
+
+## Boolean Type
+
+### boolean
+
+Generates true or false.
+
+```dsl
+User:
+  active: boolean
+  verified: boolean(true:90%)
+  banned: boolean(false:95%)
+```
+
+| Argument | Type | Default | Description |
+|----------|------|---------|-------------|
+| `true:N%` | Percentage | 50% | Probability of true |
+| `false:N%` | Percentage | 50% | Probability of false |
+
+**Examples:**
+- `boolean` → 50/50 chance
+- `boolean(true:90%)` → 90% true, 10% false
+- `boolean(false:80%)` → 20% true, 80% false
+
+---
+
+## Enum Type
+
+### enum
+
+Selects one value from a list.
+
+```dsl
+User:
+  # Equal probability
+  status: enum(active, inactive, pending)
+  
+  # Weighted probability
+  role: enum(user:80%, admin:5%, moderator:15%)
+  
+  # Mixed
+  tier: enum(free:70%, basic, premium:10%)
+```
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `value` | String | Possible value (equal weight) |
+| `value:N%` | String:Percentage | Value with specific probability |
+
+**Rules:**
+- Unweighted values share remaining probability equally
+- Weights must sum to ≤ 100%
+- At least one value required
+
+**Examples:**
+```dsl
+# All equal (33.3% each)
+enum(a, b, c)
+
+# Explicit weights
+enum(common:70%, rare:20%, legendary:10%)
+
+# Mixed (remaining 40% split equally: b=20%, c=20%)
+enum(a:60%, b, c)
+```
+
+---
+
+## Date and Time Types
+
+### date
+
+Generates a random date.
+
+```dsl
+Event:
+  date: date
+```
+
+**Format:** `"2024-06-15"` (ISO 8601)
+
+### past_date
+
+Generates a date in the past.
+
+```dsl
+User:
+  created_at: past_date
+  birthday: past_date(100y)
+  recent: past_date(30d)
+  last_month: past_date(1m)
+```
+
+| Argument | Type | Default | Description |
+|----------|------|---------|-------------|
+| Duration | String | `1y` | How far back |
+
+**Duration suffixes:**
+- `d` - days (e.g., `30d` = 30 days)
+- `m` - months (e.g., `6m` = 6 months)
+- `y` - years (e.g., `2y` = 2 years)
+
+### future_date
+
+Generates a date in the future.
+
+```dsl
+Task:
+  due_date: future_date
+  next_week: future_date(7d)
+  next_year: future_date(1y)
+```
+
+| Argument | Type | Default | Description |
+|----------|------|---------|-------------|
+| Duration | String | `1y` | How far forward |
+
+### timestamp
+
+Generates a datetime timestamp.
+
+```dsl
+Event:
+  occurred_at: timestamp
+```
+
+**Format:** `"2024-06-15T14:30:00Z"` (ISO 8601 with time)
+
+### now
+
+Generates the current timestamp.
+
+```dsl
+AuditLog:
+  created_at: now
+```
+
+**Format:** `"2024-07-15T10:30:45Z"` (current time)
+
+### datetime
+
+Generates a datetime within a range.
+
+```dsl
+Appointment:
+  scheduled_at: datetime(from: "2024-01-01", to: "2024-12-31")
+```
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `from` | String | Start date/datetime |
+| `to` | String | End date/datetime |
+
+---
+
+## Type Arguments Summary
+
+### Common Arguments
+
+| Argument | Types | Description |
+|----------|-------|-------------|
+| `unique` | uuid, email, text | Ensure uniqueness within batch |
+| `min`, `max` | number, text | Range bounds |
+| `min..max` | number, text | Range shorthand |
+
+### Probability Arguments
+
+| Argument | Types | Description |
+|----------|-------|-------------|
+| `true:N%` | boolean | Probability of true |
+| `false:N%` | boolean | Probability of false |
+| `value:N%` | enum | Probability of specific value |
+
+---
+
+## Next Steps
+
+- [Date & Time Types](datetime_types.md) - More date/time options
+- [Location Types](location_types.md) - Address, country, coordinates
+- [Personal Types](personal_types.md) - Names, contact info
+- [Complex Types](complex_types.md) - Arrays, objects, references
+