reqon-dsl 0.2.0 → 0.3.0

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

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

@@ -1,250 +0,0 @@
----
-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/
-```