reqon-dsl 0.2.0

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

@@ -0,0 +1,345 @@
+---
+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

@@ -0,0 +1,387 @@
+---
+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).