reqon-dsl 0.2.0

package/docusaurus/docs/advanced/extending-reqon.md

@@ -0,0 +1,388 @@
+---
+sidebar_position: 4
+---
+
+# Extending Reqon
+
+Extend Reqon with custom functions, store adapters, and integrations.
+
+## Custom Functions
+
+Register custom functions for use in expressions:
+
+```typescript
+import { registerFunction, execute } from 'reqon';
+
+// Register a custom function
+registerFunction('formatCurrency', (amount: number, currency: string) => {
+  return new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency
+  }).format(amount);
+});
+
+// Use in mission
+await execute(`
+  mission Example {
+    action Format {
+      map order -> Formatted {
+        total: formatCurrency(.amount, "USD")
+      }
+    }
+  }
+`);
+```
+
+### Function Types
+
+```typescript
+// Simple function
+registerFunction('double', (x: number) => x * 2);
+
+// Async function
+registerFunction('fetchRate', async (currency: string) => {
+  const response = await fetch(`/rates/${currency}`);
+  return response.json();
+});
+
+// Variadic function
+registerFunction('sum', (...args: number[]) => {
+  return args.reduce((a, b) => a + b, 0);
+});
+```
+
+### Using Custom Functions
+
+```vague
+map order -> Output {
+  doubled: double(.quantity),
+  rate: fetchRate(.currency),
+  total: sum(.item1, .item2, .item3)
+}
+```
+
+## Custom Store Adapters
+
+See [Custom Adapters](../stores/custom-adapters) for full documentation.
+
+```typescript
+import { registerStoreAdapter, StoreAdapter } from 'reqon';
+
+class MyStoreAdapter implements StoreAdapter {
+  async get(key: string) { /* ... */ }
+  async set(key: string, value: any) { /* ... */ }
+  async update(key: string, partial: any) { /* ... */ }
+  async delete(key: string) { /* ... */ }
+  async list(filter?: any) { /* ... */ }
+  async clear() { /* ... */ }
+}
+
+registerStoreAdapter('mystore', (name, config) => {
+  return new MyStoreAdapter(config);
+});
+```
+
+## Custom Auth Providers
+
+```typescript
+import { registerAuthProvider, AuthProvider } from 'reqon';
+
+class MyAuthProvider implements AuthProvider {
+  async getToken(): Promise<string> {
+    // Custom token acquisition logic
+    return 'my-token';
+  }
+
+  async refreshToken(): Promise<string> {
+    // Custom refresh logic
+    return 'new-token';
+  }
+
+  async getHeaders(): Promise<Record<string, string>> {
+    const token = await this.getToken();
+    return {
+      'Authorization': `Bearer ${token}`,
+      'X-Custom-Auth': 'value'
+    };
+  }
+}
+
+registerAuthProvider('myauth', (config) => {
+  return new MyAuthProvider(config);
+});
+```
+
+Usage:
+
+```vague
+source API {
+  auth: myauth,
+  base: "https://api.example.com"
+}
+```
+
+## Custom Step Handlers
+
+Add custom step types:
+
+```typescript
+import { registerStepHandler, ExecutionContext } from 'reqon';
+
+registerStepHandler('notify', async (step, ctx: ExecutionContext) => {
+  const { channel, message } = step.options;
+
+  await sendNotification(channel, message);
+
+  return { success: true };
+});
+```
+
+Usage:
+
+```vague
+action WithNotification {
+  get "/data"
+  store response -> data { key: .id }
+
+  notify {
+    channel: "slack",
+    message: concat("Synced ", length(response), " items")
+  }
+}
+```
+
+## Plugins
+
+### Creating a Plugin
+
+```typescript
+import { Plugin, Reqon } from 'reqon';
+
+const myPlugin: Plugin = {
+  name: 'my-plugin',
+  version: '1.0.0',
+
+  install(reqon: Reqon) {
+    // Register functions
+    reqon.registerFunction('myFunc', () => {});
+
+    // Register store adapters
+    reqon.registerStoreAdapter('mystore', () => {});
+
+    // Add hooks
+    reqon.hooks.beforeExecute.tap('my-plugin', (mission) => {
+      console.log(`Starting: ${mission.name}`);
+    });
+
+    reqon.hooks.afterExecute.tap('my-plugin', (result) => {
+      console.log(`Completed: ${result.duration}ms`);
+    });
+  }
+};
+
+export default myPlugin;
+```
+
+### Using a Plugin
+
+```typescript
+import { Reqon } from 'reqon';
+import myPlugin from './my-plugin';
+
+const reqon = new Reqon();
+reqon.use(myPlugin);
+
+await reqon.execute(source);
+```
+
+## Execution Hooks
+
+### Available Hooks
+
+```typescript
+reqon.hooks.beforeParse.tap('plugin', (source) => {
+  // Before parsing mission source
+});
+
+reqon.hooks.afterParse.tap('plugin', (ast) => {
+  // After parsing, before execution
+});
+
+reqon.hooks.beforeExecute.tap('plugin', (mission) => {
+  // Before mission starts
+});
+
+reqon.hooks.afterExecute.tap('plugin', (result) => {
+  // After mission completes
+});
+
+reqon.hooks.beforeAction.tap('plugin', (action) => {
+  // Before each action
+});
+
+reqon.hooks.afterAction.tap('plugin', (action, result) => {
+  // After each action
+});
+
+reqon.hooks.beforeStep.tap('plugin', (step) => {
+  // Before each step
+});
+
+reqon.hooks.afterStep.tap('plugin', (step, result) => {
+  // After each step
+});
+
+reqon.hooks.onError.tap('plugin', (error, context) => {
+  // On any error
+});
+```
+
+### Hook Examples
+
+```typescript
+// Logging hook
+reqon.hooks.beforeAction.tap('logger', (action) => {
+  console.log(`[${new Date().toISOString()}] Starting: ${action.name}`);
+});
+
+// Metrics hook
+reqon.hooks.afterAction.tap('metrics', (action, result) => {
+  metrics.record('action_duration', {
+    action: action.name,
+    duration: result.duration,
+    success: result.success
+  });
+});
+
+// Error notification hook
+reqon.hooks.onError.tap('notify', (error, context) => {
+  sendSlackMessage(`Error in ${context.mission}: ${error.message}`);
+});
+```
+
+## Custom Pagination Strategies
+
+```typescript
+import { registerPaginationStrategy, PaginationStrategy } from 'reqon';
+
+class LinkHeaderPagination implements PaginationStrategy {
+  private nextUrl: string | null = null;
+
+  getInitialParams(): Record<string, any> {
+    return {};
+  }
+
+  hasMore(): boolean {
+    return this.nextUrl !== null;
+  }
+
+  getNextParams(): Record<string, any> {
+    // Parse from nextUrl
+    return { url: this.nextUrl };
+  }
+
+  updateFromResponse(response: any, headers: Headers): void {
+    const linkHeader = headers.get('Link');
+    this.nextUrl = parseLinkHeader(linkHeader).next;
+  }
+}
+
+registerPaginationStrategy('link', () => new LinkHeaderPagination());
+```
+
+Usage:
+
+```vague
+get "/items" {
+  paginate: link(),
+  until: !hasMore
+}
+```
+
+## Programmatic API
+
+### Full Control
+
+```typescript
+import { Reqon, parse, createContext } from 'reqon';
+
+// Parse source
+const ast = parse(source);
+
+// Create execution context
+const ctx = createContext({
+  stores: new Map(),
+  sources: new Map(),
+  variables: new Map()
+});
+
+// Execute with custom options
+const reqon = new Reqon();
+const result = await reqon.executeMission(ast.missions[0], ctx, {
+  dryRun: false,
+  progressCallbacks: {
+    onProgress: (p) => updateUI(p)
+  }
+});
+```
+
+### AST Manipulation
+
+```typescript
+import { parse, transform } from 'reqon';
+
+const ast = parse(source);
+
+// Transform AST
+const transformed = transform(ast, {
+  visitFetchStep(node) {
+    // Add retry to all fetches
+    return {
+      ...node,
+      options: {
+        ...node.options,
+        retry: { maxAttempts: 3 }
+      }
+    };
+  }
+});
+```
+
+## Best Practices
+
+### Namespace Functions
+
+```typescript
+// Good: namespaced
+registerFunction('myPlugin_formatDate', () => {});
+
+// Avoid: may conflict
+registerFunction('format', () => {});
+```
+
+### Document Extensions
+
+```typescript
+/**
+ * Formats a phone number to E.164 format
+ * @param phone - Raw phone number
+ * @param country - ISO country code
+ * @returns Formatted phone number
+ * @example formatPhone("555-1234", "US") => "+15551234"
+ */
+registerFunction('formatPhone', (phone, country) => {});
+```
+
+### Test Thoroughly
+
+```typescript
+describe('formatPhone', () => {
+  it('formats US numbers', () => {
+    expect(formatPhone('555-1234', 'US')).toBe('+15551234');
+  });
+
+  it('handles international numbers', () => {
+    expect(formatPhone('7911 123456', 'GB')).toBe('+447911123456');
+  });
+});
+```

package/docusaurus/docs/advanced/multi-file-missions.md

@@ -0,0 +1,250 @@
+---
+sidebar_position: 1
+---
+
+# Multi-File Missions
+
+For complex missions, organize your code across multiple files in a folder structure.
+
+## Folder Structure
+
+```
+missions/
+└── customer-sync/
+    ├── mission.vague      # Main mission definition
+    ├── actions/
+    │   ├── fetch.vague    # Fetch actions
+    │   ├── transform.vague
+    │   └── export.vague
+    └── schemas/
+        └── customer.vague
+```
+
+## Main Mission File
+
+The `mission.vague` file defines the mission structure:
+
+```vague
+// mission.vague
+mission CustomerSync {
+  source API {
+    auth: oauth2,
+    base: "https://api.example.com"
+  }
+
+  store rawCustomers: memory("raw")
+  store customers: file("customers")
+  store errors: file("errors")
+
+  // Actions are loaded from actions/*.vague
+  // Schemas are loaded from schemas/*.vague
+
+  run FetchCustomers then TransformCustomers then ExportCustomers
+}
+```
+
+## Action Files
+
+### actions/fetch.vague
+
+```vague
+action FetchCustomers {
+  get "/customers" {
+    paginate: offset(offset, 100),
+    until: length(response.data) == 0,
+    since: lastSync
+  }
+
+  store response.data -> rawCustomers { key: .id }
+}
+```
+
+### actions/transform.vague
+
+```vague
+action TransformCustomers {
+  for customer in rawCustomers {
+    validate customer {
+      assume .id is string,
+      assume .email is string
+    }
+
+    map customer -> StandardCustomer {
+      id: .id,
+      name: concat(.firstName, " ", .lastName),
+      email: lowercase(.email),
+      createdAt: parseDate(.created_at)
+    }
+
+    store customer -> customers { key: .id, upsert: true }
+  }
+}
+```
+
+### actions/export.vague
+
+```vague
+action ExportCustomers {
+  for customer in customers where .updatedAt > lastExport {
+    post ExportAPI "/customers" {
+      body: customer
+    }
+
+    match response {
+      { error: e } -> queue errors { item: { id: customer.id, error: e } },
+      _ -> continue
+    }
+  }
+}
+```
+
+## Schema Files
+
+### schemas/customer.vague
+
+```vague
+schema RawCustomer {
+  id: string,
+  firstName: string,
+  lastName: string,
+  email: string,
+  created_at: string
+}
+
+schema StandardCustomer {
+  id: string,
+  name: string,
+  email: string,
+  createdAt: date
+}
+
+schema ExportError {
+  id: string,
+  error: string,
+  timestamp: date
+}
+```
+
+## Running Multi-File Missions
+
+### Run the Folder
+
+```bash
+reqon ./missions/customer-sync/
+```
+
+### Run with Options
+
+```bash
+reqon ./missions/customer-sync/ --auth ./credentials.json --verbose
+```
+
+## File Loading Order
+
+1. `mission.vague` (required)
+2. `schemas/*.vague` (loaded first)
+3. `actions/*.vague` (loaded after schemas)
+
+## Benefits
+
+### Organization
+
+| Single File | Multi-File |
+|-------------|------------|
+| All code in one file | Logical separation |
+| Hard to navigate | Easy to find code |
+| Merge conflicts | Independent editing |
+
+### Maintainability
+
+- Each file has single responsibility
+- Easier code reviews
+- Better version control
+
+### Reusability
+
+```
+missions/
+├── shared/
+│   └── schemas/
+│       └── common.vague
+├── customer-sync/
+│   └── mission.vague (imports shared)
+└── order-sync/
+    └── mission.vague (imports shared)
+```
+
+## Best Practices
+
+### Naming Conventions
+
+```
+actions/
+├── fetch-customers.vague     # Verb-noun
+├── transform-customers.vague
+└── export-customers.vague
+```
+
+### One Action Per File
+
+```vague
+// actions/fetch-customers.vague
+action FetchCustomers {
+  // Single responsibility
+}
+```
+
+### Group Related Schemas
+
+```vague
+// schemas/customer.vague
+schema RawCustomer { ... }
+schema StandardCustomer { ... }
+schema CustomerError { ... }
+```
+
+### Document with Comments
+
+```vague
+// actions/fetch-customers.vague
+
+// FetchCustomers retrieves customer data from the API
+// Uses pagination and incremental sync for efficiency
+action FetchCustomers {
+  // Fetch with pagination
+  get "/customers" {
+    paginate: offset(offset, 100),
+    until: length(response.data) == 0,
+    since: lastSync
+  }
+
+  // Store raw data for processing
+  store response.data -> rawCustomers { key: .id }
+}
+```
+
+## Troubleshooting
+
+### "Mission not found"
+
+Ensure `mission.vague` exists in the folder:
+
+```bash
+ls ./missions/customer-sync/mission.vague
+```
+
+### "Action not found"
+
+Check action file is in `actions/` folder:
+
+```bash
+ls ./missions/customer-sync/actions/
+```
+
+### "Schema not found"
+
+Check schema file is in `schemas/` folder:
+
+```bash
+ls ./missions/customer-sync/schemas/
+```