reqon-dsl 0.2.0 → 0.4.0

package/docusaurus/docs/core-concepts/stores.md

@@ -1,332 +0,0 @@
----
-sidebar_position: 4
----
-
-# Stores
-
-A **Store** is a named data persistence target. Stores allow you to save, retrieve, update, and query data during mission execution.
-
-## Basic Syntax
-
-```vague
-store storeName: adapter("identifier")
-```
-
-## Available Adapters
-
-| Adapter | Description | Use Case |
-|---------|-------------|----------|
-| `memory` | In-memory storage | Testing, temporary data |
-| `file` | JSON file storage | Local development, small datasets |
-| `sql` | SQL database | Production with PostgreSQL/MySQL |
-| `nosql` | NoSQL database | Production with MongoDB/DynamoDB |
-
-## Memory Store
-
-In-memory storage that doesn't persist between runs:
-
-```vague
-store cache: memory("cache")
-store tempData: memory("temp")
-```
-
-Best for:
-- Testing
-- Temporary processing data
-- Intermediate results
-
-## File Store
-
-JSON file storage in the `.vague-data` directory:
-
-```vague
-store customers: file("customers")
-store orders: file("orders")
-```
-
-Creates files like:
-```
-.vague-data/
-├── customers.json
-└── orders.json
-```
-
-Best for:
-- Local development
-- Small to medium datasets
-- Simple persistence without database setup
-
-## SQL Store
-
-SQL database storage via PostgREST or direct connection:
-
-```vague
-store customers: sql("customers_table")
-store orders: sql("orders")
-```
-
-Requires configuration:
-
-```json
-{
-  "stores": {
-    "sql": {
-      "type": "postgrest",
-      "url": "https://your-project.supabase.co/rest/v1",
-      "apiKey": "your-anon-key"
-    }
-  }
-}
-```
-
-See [PostgREST Store](../stores/postgrest) for details.
-
-## NoSQL Store
-
-NoSQL database storage:
-
-```vague
-store events: nosql("events_collection")
-store logs: nosql("activity_logs")
-```
-
-Currently falls back to file storage in development. Full MongoDB/DynamoDB support planned.
-
-## Store Operations
-
-### Writing Data
-
-```vague
-action SaveData {
-  get "/users"
-
-  // Store entire response
-  store response -> users
-
-  // Store with key for indexed access
-  store response -> users { key: .id }
-
-  // Store nested data
-  store response.data.items -> items { key: .itemId }
-}
-```
-
-### Key Option
-
-The `key` option specifies which field to use as the unique identifier:
-
-```vague
-store response -> users { key: .id }
-store response -> users { key: .email }
-store response -> users { key: concat(.orgId, "-", .userId) }
-```
-
-### Upsert Mode
-
-Insert or update based on key:
-
-```vague
-store response -> users {
-  key: .id,
-  upsert: true
-}
-```
-
-### Partial Updates
-
-Update only provided fields:
-
-```vague
-store response -> users {
-  key: .id,
-  partial: true
-}
-```
-
-## Reading From Stores
-
-Stores are available as variables in actions:
-
-```vague
-action ProcessStoredData {
-  // Iterate over store contents
-  for user in users {
-    // Access user data
-    get "/orders" { params: { userId: user.id } }
-  }
-
-  // With filtering
-  for user in users where .status == "active" {
-    // Process active users only
-  }
-}
-```
-
-## Store Interface
-
-Stores implement this interface:
-
-```typescript
-interface StoreAdapter {
-  // Get single record by key
-  get(key: string): Promise<Record | null>
-
-  // Set record with key
-  set(key: string, value: Record): Promise<void>
-
-  // Update record (partial)
-  update(key: string, partial: Record): Promise<void>
-
-  // Delete record
-  delete(key: string): Promise<void>
-
-  // List all records with optional filter
-  list(filter?: FilterOptions): Promise<Record[]>
-
-  // Clear all records
-  clear(): Promise<void>
-}
-```
-
-## Filtering Store Data
-
-Use `where` clauses when iterating:
-
-```vague
-action ProcessFiltered {
-  // Status filter
-  for order in orders where .status == "pending" {
-    // Process pending orders
-  }
-
-  // Multiple conditions
-  for user in users where .active == true and .role == "admin" {
-    // Process active admins
-  }
-
-  // Comparison
-  for product in products where .price > 100 {
-    // Process expensive products
-  }
-}
-```
-
-## Store Aggregations
-
-Access store metadata:
-
-```vague
-action CheckStore {
-  // Get count
-  validate {
-    assume length(users) > 0
-  }
-
-  // Check if empty
-  match users {
-    [] -> abort "No users found",
-    _ -> continue
-  }
-}
-```
-
-## Cross-Store Operations
-
-Reference multiple stores:
-
-```vague
-action Reconcile {
-  for order in orders {
-    // Look up related customer
-    for customer in customers where .id == order.customerId {
-      map order -> EnrichedOrder {
-        id: order.id,
-        amount: order.amount,
-        customerName: customer.name,
-        customerEmail: customer.email
-      }
-      store order -> enrichedOrders { key: .id }
-    }
-  }
-}
-```
-
-## Best Practices
-
-### Use Appropriate Adapters
-
-```vague
-// Development
-store data: file("data")
-
-// Production
-store data: sql("data_table")
-```
-
-### Always Specify Keys
-
-```vague
-// Good: explicit key
-store response -> users { key: .id }
-
-// Avoid: no key (uses auto-generated)
-store response -> users
-```
-
-### Use Upsert for Sync Operations
-
-```vague
-action IncrementalSync {
-  get "/users" { since: lastSync }
-
-  for user in response {
-    store user -> users { key: .id, upsert: true }
-  }
-}
-```
-
-### Clean Up Temporary Stores
-
-```vague
-mission CleanPipeline {
-  store temp: memory("temp")
-
-  action Process {
-    // Use temp store
-  }
-
-  // Temp store is automatically cleaned when mission ends
-}
-```
-
-### Use Descriptive Store Names
-
-```vague
-// Good
-store activeCustomers: file("active-customers")
-store pendingOrders: file("pending-orders")
-store syncedInvoices: file("synced-invoices")
-
-// Avoid
-store data: file("data")
-store temp: file("temp")
-```
-
-## Exporting Store Data
-
-Use the CLI to export stores after execution:
-
-```bash
-reqon mission.vague --output ./exports/
-```
-
-Or programmatically:
-
-```typescript
-const result = await execute(source);
-
-for (const [name, store] of result.stores) {
-  const data = await store.list();
-  fs.writeFileSync(`${name}.json`, JSON.stringify(data, null, 2));
-}
-```

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

@@ -1,361 +0,0 @@
----
-sidebar_position: 7
----
-
-# Expressions
-
-Reqon uses the Vague expression language for data manipulation. This page covers the most common expressions; for complete documentation, see the [Vague documentation](https://github.com/mcclowes/vague).
-
-## Literals
-
-```vague
-// Numbers
-42
-3.14
--100
-
-// Strings
-"hello world"
-'single quotes also work'
-
-// Booleans
-true
-false
-
-// Null
-null
-
-// Arrays
-[1, 2, 3]
-["a", "b", "c"]
-
-// Objects
-{ key: "value", nested: { a: 1 } }
-```
-
-## Property Access
-
-```vague
-// Dot notation
-.name
-.address.city
-.items[0].name
-
-// Within context
-user.name
-response.data.items
-
-// Array indexing
-.items[0]
-.items[length(.items) - 1]
-```
-
-## Operators
-
-### Arithmetic
-
-```vague
-1 + 2       // 3
-10 - 3      // 7
-4 * 5       // 20
-20 / 4      // 5
-10 % 3      // 1 (modulo)
-```
-
-### Comparison
-
-```vague
-.a == .b    // equality
-.a != .b    // inequality
-.a > .b     // greater than
-.a >= .b    // greater or equal
-.a < .b     // less than
-.a <= .b    // less or equal
-```
-
-### Logical
-
-```vague
-.a and .b   // logical AND
-.a or .b    // logical OR
-not .a      // logical NOT
-```
-
-### String
-
-```vague
-.first + " " + .last    // concatenation
-.email contains "@"     // contains check
-.name startsWith "Dr."  // prefix check
-.file endsWith ".pdf"   // suffix check
-```
-
-## Conditional Expressions
-
-### If-Then-Else
-
-```vague
-if .active then "Active" else "Inactive"
-
-if .age >= 18 then "Adult"
-else if .age >= 13 then "Teen"
-else "Child"
-```
-
-### Ternary Style
-
-```vague
-.status == "active" ? "Yes" : "No"
-```
-
-### Null Coalescing
-
-```vague
-.name or "Unknown"
-.email or .backup_email or "no-email@example.com"
-```
-
-## String Functions
-
-```vague
-// Length
-length("hello")  // 5
-
-// Case conversion
-lowercase("HELLO")  // "hello"
-uppercase("hello")  // "HELLO"
-
-// Substring
-substring("hello", 0, 2)  // "he"
-substring("hello", 2)     // "llo"
-
-// Split and join
-split("a,b,c", ",")       // ["a", "b", "c"]
-join(["a", "b"], "-")     // "a-b"
-
-// Trim
-trim("  hello  ")         // "hello"
-trimStart("  hello")      // "hello"
-trimEnd("hello  ")        // "hello"
-
-// Replace
-replace("hello", "l", "L")  // "heLLo"
-
-// Concatenation
-concat("Hello", " ", "World")  // "Hello World"
-```
-
-## Array Functions
-
-```vague
-// Length
-length([1, 2, 3])  // 3
-
-// Access
-first([1, 2, 3])   // 1
-last([1, 2, 3])    // 3
-
-// Check contents
-includes([1, 2, 3], 2)  // true
-isEmpty([])             // true
-
-// Transform
-map([1, 2, 3], x => x * 2)      // [2, 4, 6]
-filter([1, 2, 3], x => x > 1)   // [2, 3]
-reduce([1, 2, 3], (a, b) => a + b, 0)  // 6
-
-// Aggregate
-sum([1, 2, 3])      // 6
-min([1, 2, 3])      // 1
-max([1, 2, 3])      // 3
-avg([1, 2, 3])      // 2
-
-// Combine
-concat([1, 2], [3, 4])   // [1, 2, 3, 4]
-flatten([[1, 2], [3]])   // [1, 2, 3]
-unique([1, 1, 2, 2])     // [1, 2]
-
-// Sort
-sort([3, 1, 2])          // [1, 2, 3]
-sortBy(items, .name)     // sorted by name field
-
-// Find
-find(items, .id == "123")   // first match
-findIndex(items, .id == "123")  // index of first match
-```
-
-## Object Functions
-
-```vague
-// Get keys/values
-keys({ a: 1, b: 2 })     // ["a", "b"]
-values({ a: 1, b: 2 })   // [1, 2]
-entries({ a: 1 })        // [["a", 1]]
-
-// Check
-hasKey({ a: 1 }, "a")    // true
-
-// Transform
-pick({ a: 1, b: 2 }, ["a"])        // { a: 1 }
-omit({ a: 1, b: 2 }, ["b"])        // { a: 1 }
-merge({ a: 1 }, { b: 2 })          // { a: 1, b: 2 }
-```
-
-## Numeric Functions
-
-```vague
-// Rounding
-round(3.7)        // 4
-round(3.14159, 2) // 3.14
-floor(3.7)        // 3
-ceil(3.2)         // 4
-
-// Math
-abs(-5)           // 5
-min(1, 2, 3)      // 1
-max(1, 2, 3)      // 3
-pow(2, 3)         // 8
-sqrt(16)          // 4
-
-// Conversion
-toNumber("42")    // 42
-toString(42)      // "42"
-```
-
-## Date Functions
-
-```vague
-// Current time
-now()
-
-// Parsing
-parseDate("2024-01-20")
-parseDate("2024-01-20T10:30:00Z")
-
-// Formatting
-formatDate(now(), "YYYY-MM-DD")
-formatDate(now(), "MMM D, YYYY")
-
-// Components
-year(now())       // 2024
-month(now())      // 1-12
-day(now())        // 1-31
-hour(now())       // 0-23
-minute(now())     // 0-59
-
-// Manipulation
-addDays(now(), 7)
-addMonths(now(), 1)
-subtractDays(now(), 30)
-
-// Comparison
-diffDays(date1, date2)
-isBefore(date1, date2)
-isAfter(date1, date2)
-```
-
-## Type Functions
-
-```vague
-// Type checking
-.value is string
-.value is number
-.value is boolean
-.value is array
-.value is object
-.value is null
-
-// Type conversion
-toString(123)       // "123"
-toNumber("42")      // 42
-toBoolean(1)        // true
-toArray("a")        // ["a"]
-```
-
-## Environment Variables
-
-```vague
-env("API_KEY")
-env("BASE_URL")
-env("DEBUG") == "true"
-```
-
-## Pattern Matching in Expressions
-
-```vague
-match .status {
-  "active" => "Active User",
-  "pending" => "Pending Approval",
-  "inactive" => "Deactivated",
-  _ => "Unknown Status"
-}
-```
-
-## Complex Expression Examples
-
-### Data Transformation
-
-```vague
-map user -> Output {
-  fullName: concat(.firstName, " ", .lastName),
-  email: lowercase(.email),
-  age: year(now()) - year(.birthDate),
-  isAdult: year(now()) - year(.birthDate) >= 18,
-  displayName: if .nickname then .nickname else .firstName,
-  initials: concat(
-    substring(.firstName, 0, 1),
-    substring(.lastName, 0, 1)
-  )
-}
-```
-
-### Aggregation
-
-```vague
-map orders -> Summary {
-  totalOrders: length(orders),
-  totalRevenue: sum(orders.map(.total)),
-  avgOrderValue: sum(orders.map(.total)) / length(orders),
-  maxOrder: max(orders.map(.total)),
-  pendingCount: length(filter(orders, .status == "pending")),
-  completedRate: length(filter(orders, .status == "completed")) / length(orders) * 100
-}
-```
-
-### Conditional Logic
-
-```vague
-map order -> PricedOrder {
-  ...order,
-  discount: match .customerTier {
-    "gold" => 0.20,
-    "silver" => 0.10,
-    "bronze" => 0.05,
-    _ => 0
-  },
-  discountedTotal: .total * (1 - match .customerTier {
-    "gold" => 0.20,
-    "silver" => 0.10,
-    "bronze" => 0.05,
-    _ => 0
-  }),
-  shippingFee: if .total > 100 then 0 else 9.99,
-  finalTotal: .total * (1 - if .customerTier == "gold" then 0.20 else 0) +
-              (if .total > 100 then 0 else 9.99)
-}
-```
-
-### Validation Conditions
-
-```vague
-validate order {
-  assume .id is string,
-  assume length(.items) > 0,
-  assume sum(.items.map(.quantity)) > 0,
-  assume .total == sum(.items.map(.price * .quantity)),
-  assume .createdAt <= now(),
-  assume .shippingDate == null or .shippingDate >= .createdAt
-}
-```
-
-For the complete expression language reference, visit the [Vague documentation](https://github.com/mcclowes/vague).