reqon-dsl 0.2.0 → 0.4.0

package/docusaurus/docs/dsl-syntax/map.md

@@ -1,345 +0,0 @@
----
-sidebar_position: 3
----
-
-# Map Transformations
-
-Map steps transform data from one shape to another. They're used to normalize API responses, enrich data, and prepare data for storage.
-
-## Basic Syntax
-
-```vague
-map sourceData -> TargetSchema {
-  field: expression,
-  anotherField: expression
-}
-```
-
-## Simple Mapping
-
-```vague
-action TransformUser {
-  get "/users/123"
-
-  map response -> User {
-    id: .id,
-    name: .name,
-    email: .email
-  }
-
-  store response -> users { key: .id }
-}
-```
-
-## Field Access
-
-### Direct Access
-
-```vague
-map user -> Output {
-  id: .id,
-  name: .name
-}
-```
-
-### Nested Access
-
-```vague
-map user -> Output {
-  userId: .id,
-  street: .address.street,
-  city: .address.city,
-  country: .address.country
-}
-```
-
-### Array Access
-
-```vague
-map order -> Output {
-  firstItem: .items[0],
-  lastItem: .items[length(.items) - 1]
-}
-```
-
-## Expressions
-
-For detailed expression syntax, see the [Vague documentation](https://github.com/mcclowes/vague).
-
-### String Operations
-
-```vague
-map user -> Output {
-  fullName: concat(.firstName, " ", .lastName),
-  email: lowercase(.email),
-  initials: concat(substring(.firstName, 0, 1), substring(.lastName, 0, 1)),
-  domain: split(.email, "@")[1]
-}
-```
-
-### Numeric Operations
-
-```vague
-map order -> Output {
-  subtotal: .price * .quantity,
-  tax: .price * .quantity * 0.1,
-  total: .price * .quantity * 1.1,
-  discounted: .total * (1 - .discountPercent / 100)
-}
-```
-
-### Conditional Expressions
-
-```vague
-map user -> Output {
-  status: if .active then "Active" else "Inactive",
-  tier: if .totalSpent > 10000 then "Gold"
-        else if .totalSpent > 5000 then "Silver"
-        else "Bronze"
-}
-```
-
-### Pattern Matching in Maps
-
-```vague
-map order -> Output {
-  statusLabel: match .status {
-    "pending" => "Awaiting Processing",
-    "processing" => "In Progress",
-    "shipped" => "On the Way",
-    "delivered" => "Completed",
-    _ => "Unknown"
-  }
-}
-```
-
-## Nested Mapping
-
-### Static Nested Objects
-
-```vague
-map user -> Output {
-  id: .id,
-  profile: {
-    name: .name,
-    email: .email,
-    phone: .phone
-  },
-  metadata: {
-    createdAt: .created_at,
-    updatedAt: .updated_at
-  }
-}
-```
-
-### Mapping Arrays
-
-```vague
-map order -> Output {
-  id: .id,
-  items: .lineItems.map(item => {
-    productId: item.product_id,
-    name: item.product_name,
-    quantity: item.qty,
-    price: item.unit_price
-  })
-}
-```
-
-## Combining Data
-
-### From Multiple Sources
-
-```vague
-action EnrichOrders {
-  for order in orders {
-    get concat("/customers/", order.customerId)
-
-    map order -> EnrichedOrder {
-      id: order.id,
-      total: order.total,
-      customer: {
-        id: response.id,
-        name: response.name,
-        email: response.email
-      }
-    }
-
-    store order -> enrichedOrders { key: .id }
-  }
-}
-```
-
-### Merging Objects
-
-```vague
-map source -> Output {
-  ...baseData,
-  ...additionalData,
-  overriddenField: "new value"
-}
-```
-
-## Date Transformations
-
-```vague
-map event -> Output {
-  timestamp: parseDate(.created_at),
-  formattedDate: formatDate(.created_at, "YYYY-MM-DD"),
-  year: year(.created_at),
-  dayOfWeek: dayOfWeek(.created_at)
-}
-```
-
-## Null Handling
-
-### Default Values
-
-```vague
-map user -> Output {
-  name: .name or "Unknown",
-  email: .email or "no-email@example.com",
-  phone: .phone or null
-}
-```
-
-### Null Checks
-
-```vague
-map user -> Output {
-  hasEmail: .email != null,
-  displayEmail: if .email != null then .email else "Not provided"
-}
-```
-
-## Type Coercion
-
-```vague
-map data -> Output {
-  id: toString(.id),
-  count: toNumber(.count),
-  isActive: toBoolean(.active),
-  tags: toArray(.tags)
-}
-```
-
-## Computed Fields
-
-```vague
-map invoice -> Output {
-  id: .id,
-  lineItems: .items,
-  subtotal: sum(.items.map(.amount)),
-  taxRate: 0.1,
-  tax: sum(.items.map(.amount)) * 0.1,
-  total: sum(.items.map(.amount)) * 1.1,
-  itemCount: length(.items)
-}
-```
-
-## Renaming Fields
-
-```vague
-// Transform API response to standard format
-map xeroInvoice -> StandardInvoice {
-  id: .InvoiceID,
-  number: .InvoiceNumber,
-  customerId: .Contact.ContactID,
-  customerName: .Contact.Name,
-  amount: .Total,
-  status: lowercase(.Status),
-  createdAt: .DateString
-}
-```
-
-## Flattening Nested Data
-
-```vague
-map order -> FlatOrder {
-  orderId: .id,
-  orderDate: .createdAt,
-  customerName: .customer.name,
-  customerEmail: .customer.email,
-  shippingStreet: .shipping.address.street,
-  shippingCity: .shipping.address.city,
-  total: .total
-}
-```
-
-## Grouping and Aggregation
-
-```vague
-map orders -> Summary {
-  totalOrders: length(orders),
-  totalRevenue: sum(orders.map(.total)),
-  averageOrder: sum(orders.map(.total)) / length(orders),
-  byStatus: {
-    pending: length(filter(orders, .status == "pending")),
-    completed: length(filter(orders, .status == "completed"))
-  }
-}
-```
-
-## Complete Example
-
-```vague
-mission TransformXeroData {
-  source Xero { auth: oauth2, base: "https://api.xero.com/api.xro/2.0" }
-
-  store invoices: file("invoices")
-
-  action TransformInvoices {
-    get "/Invoices"
-
-    for invoice in response.Invoices {
-      map invoice -> StandardInvoice {
-        // Identifiers
-        id: .InvoiceID,
-        number: .InvoiceNumber,
-        type: match .Type {
-          "ACCREC" => "receivable",
-          "ACCPAY" => "payable",
-          _ => "unknown"
-        },
-
-        // Customer info
-        customer: {
-          id: .Contact.ContactID,
-          name: .Contact.Name,
-          email: .Contact.EmailAddress or null
-        },
-
-        // Line items
-        items: .LineItems.map(item => {
-          description: item.Description,
-          quantity: item.Quantity,
-          unitPrice: item.UnitAmount,
-          total: item.LineAmount,
-          taxAmount: item.TaxAmount or 0
-        }),
-
-        // Totals
-        subtotal: .SubTotal,
-        tax: .TotalTax,
-        total: .Total,
-
-        // Status
-        status: lowercase(.Status),
-        isPaid: .Status == "PAID",
-
-        // Dates
-        date: parseDate(.DateString),
-        dueDate: parseDate(.DueDateString),
-
-        // Metadata
-        createdAt: parseDate(.UpdatedDateUTC),
-        source: "xero"
-      }
-
-      store invoice -> invoices { key: .id, upsert: true }
-    }
-  }
-
-  run TransformInvoices
-}
-```

package/docusaurus/docs/dsl-syntax/match.md

@@ -1,387 +0,0 @@
----
-sidebar_position: 5
----
-
-# Match (Pattern Matching)
-
-Match steps route data based on its structure. They're essential for error handling, conditional processing, and flow control.
-
-## Basic Syntax
-
-```vague
-match target {
-  Pattern1 -> action1,
-  Pattern2 -> action2,
-  _ -> defaultAction
-}
-```
-
-## Schema Matching
-
-Match against defined schemas:
-
-```vague
-schema SuccessResponse {
-  data: any,
-  status: string
-}
-
-schema ErrorResponse {
-  error: string,
-  code: number
-}
-
-action HandleResponse {
-  get "/data"
-
-  match response {
-    SuccessResponse -> store response.data -> data { key: .id },
-    ErrorResponse -> abort response.error,
-    _ -> abort "Unknown response format"
-  }
-}
-```
-
-## Object Pattern Matching
-
-Match based on object structure:
-
-```vague
-match response {
-  { data: _, success: true } -> continue,
-  { error: e, code: 401 } -> jump RefreshAuth then retry,
-  { error: e, code: 429 } -> retry { delay: 60000 },
-  { error: e } -> abort e,
-  _ -> abort "Unexpected response"
-}
-```
-
-### Binding Variables
-
-Capture values from patterns:
-
-```vague
-match response {
-  { error: errorMsg, code: errorCode } -> {
-    store { message: errorMsg, code: errorCode } -> errors
-    abort errorMsg
-  },
-  _ -> continue
-}
-```
-
-## Conditional Matching
-
-Add conditions with `where`:
-
-```vague
-match order {
-  { status: "pending" } where .total > 1000 -> {
-    // High-value pending order
-    get concat("/orders/", order.id, "/flag")
-  },
-  { status: "pending" } -> continue,
-  { status: "completed" } -> skip,
-  _ -> continue
-}
-```
-
-## Flow Control Directives
-
-Match arms can use these directives:
-
-| Directive | Description |
-|-----------|-------------|
-| `continue` | Proceed to next step |
-| `skip` | Skip remaining steps (in loop) |
-| `abort` | Halt mission with error |
-| `retry` | Retry with backoff |
-| `queue` | Send to dead letter queue |
-| `jump...then` | Execute action, then continue |
-
-### Continue
-
-Proceed to the next step:
-
-```vague
-match response {
-  { data: _ } -> continue,
-  _ -> abort "No data"
-}
-// Next step executes
-```
-
-### Skip
-
-Skip remaining steps in current loop iteration:
-
-```vague
-for item in items {
-  match item {
-    { status: "inactive" } -> skip,
-    _ -> continue
-  }
-  // This only runs for non-inactive items
-  store item -> activeItems { key: .id }
-}
-```
-
-### Abort
-
-Stop mission execution:
-
-```vague
-match response {
-  { error: msg } -> abort msg,
-  { error: _ } -> abort "Unknown error",
-  _ -> continue
-}
-```
-
-### Retry
-
-Retry the previous fetch:
-
-```vague
-match response {
-  { error: _, code: 429 } -> retry {
-    maxAttempts: 5,
-    backoff: exponential,
-    initialDelay: 1000,
-    maxDelay: 60000
-  },
-  { error: _ } -> abort "API error",
-  _ -> continue
-}
-```
-
-### Queue
-
-Send to dead letter queue:
-
-```vague
-match response {
-  { error: e } -> queue dlq {
-    item: {
-      originalRequest: request,
-      error: e,
-      timestamp: now()
-    }
-  },
-  _ -> continue
-}
-```
-
-### Jump
-
-Execute another action:
-
-```vague
-match response {
-  { error: _, code: 401 } -> jump RefreshToken then retry,
-  _ -> continue
-}
-
-action RefreshToken {
-  post "/auth/refresh" {
-    body: { refreshToken: env("REFRESH_TOKEN") }
-  }
-}
-```
-
-## Matching Arrays
-
-```vague
-match response.items {
-  [] -> abort "No items found",
-  [single] -> store single -> item,
-  _ -> store response.items -> items { key: .id }
-}
-```
-
-## Matching with Nested Steps
-
-Execute multiple steps in a match arm:
-
-```vague
-match response {
-  { status: "error" } -> {
-    // Multiple steps
-    store response -> errors
-    abort response.message
-  },
-  { data: items } -> {
-    for item in items {
-      store item -> processed { key: .id }
-    }
-    continue
-  },
-  _ -> continue
-}
-```
-
-## Type Matching
-
-```vague
-match value {
-  v where v is string -> { /* handle string */ },
-  v where v is number -> { /* handle number */ },
-  v where v is array -> { /* handle array */ },
-  v where v is null -> { /* handle null */ },
-  _ -> abort "Unexpected type"
-}
-```
-
-## HTTP Status Code Handling
-
-```vague
-schema Success { data: any }
-schema NotFound { error: string }
-schema RateLimit { error: string, retryAfter: number }
-schema AuthError { error: string, code: number }
-
-action FetchWithErrorHandling {
-  get "/resource"
-
-  match response {
-    Success -> store response.data -> data { key: .id },
-    RateLimit -> retry { delay: response.retryAfter * 1000 },
-    AuthError where .code == 401 -> jump RefreshAuth then retry,
-    NotFound -> skip,
-    _ -> abort "Unexpected response"
-  }
-}
-```
-
-## Pattern Matching Order
-
-Patterns are matched in order; first match wins:
-
-```vague
-match value {
-  // More specific patterns first
-  { status: "urgent", priority: 1 } -> handleUrgent,
-  { status: "urgent" } -> handleHighPriority,
-  { priority: 1 } -> handlePriority,
-  { status: _ } -> handleNormal,
-  _ -> handleDefault
-}
-```
-
-## Exhaustive Matching
-
-Always include a catch-all pattern:
-
-```vague
-// Good: handles all cases
-match response {
-  { data: _ } -> continue,
-  { error: _ } -> abort "Error",
-  _ -> abort "Unexpected format"  // Catch-all
-}
-
-// Risky: might miss cases
-match response {
-  { data: _ } -> continue,
-  { error: _ } -> abort "Error"
-  // What if neither matches?
-}
-```
-
-## Complete Example
-
-```vague
-mission RobustDataSync {
-  source API { auth: oauth2, base: "https://api.example.com" }
-
-  store data: file("data")
-  store errors: file("errors")
-  store dlq: file("dead-letter")
-
-  schema SuccessResponse {
-    data: array,
-    pagination: object?
-  }
-
-  schema ValidationError {
-    error: string,
-    code: number,
-    details: array?
-  }
-
-  schema RateLimitError {
-    error: string,
-    retryAfter: number
-  }
-
-  schema AuthError {
-    error: string,
-    code: number
-  }
-
-  action FetchData {
-    get "/data" {
-      paginate: offset(page, 100),
-      until: length(response.data) == 0
-    }
-
-    match response {
-      // Success case
-      SuccessResponse -> {
-        for item in response.data {
-          match item {
-            { status: "invalid" } -> {
-              store item -> errors { key: item.id }
-              skip
-            },
-            { status: "pending" } where item.priority == "high" -> {
-              // Process high priority immediately
-              get concat("/items/", item.id, "/process")
-              continue
-            },
-            _ -> continue
-          }
-          store item -> data { key: .id }
-        }
-      },
-
-      // Rate limited
-      RateLimitError -> retry {
-        delay: response.retryAfter * 1000,
-        maxAttempts: 5
-      },
-
-      // Auth expired
-      AuthError where .code == 401 -> jump RefreshToken then retry,
-
-      // Validation error
-      ValidationError -> {
-        store {
-          type: "validation",
-          message: response.error,
-          details: response.details
-        } -> errors
-        abort response.error
-      },
-
-      // Unknown error
-      _ -> queue dlq {
-        item: {
-          response: response,
-          timestamp: now()
-        }
-      }
-    }
-  }
-
-  action RefreshToken {
-    post "/auth/refresh" {
-      body: { refreshToken: env("REFRESH_TOKEN") }
-    }
-  }
-
-  run FetchData
-}
-```
-
-For more pattern matching features, see the [Vague documentation](https://github.com/mcclowes/vague).