reqon-dsl 0.2.0

package/src/interpreter/step-handlers/for-handler.ts

@@ -0,0 +1,65 @@
+import type { ForStep, ActionStep } from '../../ast/nodes.js';
+import type { StepHandler, StepHandlerDeps } from './types.js';
+import { evaluate } from '../evaluator.js';
+import { childContext, setVariable, getVariable } from '../context.js';
+import type { ExecutionContext } from '../context.js';
+
+export interface ForHandlerDeps extends StepHandlerDeps {
+  executeStep: (step: ActionStep, actionName: string, ctx: ExecutionContext) => Promise<void>;
+  actionName: string;
+}
+
+/**
+ * Handles for...in...where iteration steps
+ */
+export class ForHandler implements StepHandler<ForStep> {
+  constructor(private deps: ForHandlerDeps) {}
+
+  async execute(step: ForStep): Promise<void> {
+    const collection = await this.getCollection(step);
+
+    // Apply filter if present
+    const filtered = step.condition
+      ? collection.filter((item) => evaluate(step.condition!, this.deps.ctx, item))
+      : collection;
+
+    this.deps.log(`Iterating over ${filtered.length} items`);
+
+    // Execute steps for each item
+    for (const item of filtered) {
+      await this.executeForItem(step, item);
+    }
+  }
+
+  private async getCollection(step: ForStep): Promise<unknown[]> {
+    let collection: unknown[];
+
+    if (step.collection.type === 'Identifier') {
+      // It's a store reference
+      const store = this.deps.ctx.stores.get(step.collection.name);
+      if (store) {
+        collection = await store.list();
+      } else {
+        collection = (getVariable(this.deps.ctx, step.collection.name) as unknown[]) ?? [];
+      }
+    } else {
+      collection = evaluate(step.collection, this.deps.ctx) as unknown[];
+    }
+
+    if (!Array.isArray(collection)) {
+      throw new Error('For loop collection must be an array');
+    }
+
+    return collection;
+  }
+
+  private async executeForItem(step: ForStep, item: unknown): Promise<void> {
+    const childCtx = childContext(this.deps.ctx);
+    setVariable(childCtx, step.variable, item);
+
+    // Execute each inner step with child context
+    for (const innerStep of step.steps) {
+      await this.deps.executeStep(innerStep, this.deps.actionName, childCtx);
+    }
+  }
+}

package/src/interpreter/step-handlers/index.ts

@@ -0,0 +1,17 @@
+export { type StepHandler, type StepHandlerDeps } from './types.js';
+export { ForHandler, type ForHandlerDeps } from './for-handler.js';
+export { MapHandler } from './map-handler.js';
+export { ValidateHandler } from './validate-handler.js';
+export { StoreHandler } from './store-handler.js';
+export { MatchHandler, type MatchHandlerDeps, type MatchResult } from './match-handler.js';
+export { WebhookHandler, type WebhookHandlerDeps, type WebhookHandlerResult } from './webhook-handler.js';
+
+// Export signals from the canonical location
+export {
+  NoMatchError,
+  AbortError,
+  SkipSignal,
+  RetrySignal,
+  JumpSignal,
+  QueueSignal,
+} from '../signals.js';

package/src/interpreter/step-handlers/map-handler.ts

@@ -0,0 +1,24 @@
+import type { MapStep } from '../../ast/nodes.js';
+import type { StepHandler, StepHandlerDeps } from './types.js';
+import { evaluate } from '../evaluator.js';
+
+/**
+ * Handles map...-> transformation steps
+ */
+export class MapHandler implements StepHandler<MapStep> {
+  constructor(private deps: StepHandlerDeps) {}
+
+  async execute(step: MapStep): Promise<void> {
+    const source = evaluate(step.source, this.deps.ctx) as Record<string, unknown>;
+
+    const mapped: Record<string, unknown> = {};
+
+    for (const mapping of step.mappings) {
+      mapped[mapping.field] = evaluate(mapping.expression, this.deps.ctx, source);
+    }
+
+    // Store mapped result in response for next step
+    this.deps.ctx.response = mapped;
+    this.deps.log(`Mapped to ${step.targetSchema}`);
+  }
+}

package/src/interpreter/step-handlers/match-handler.ts

@@ -0,0 +1,101 @@
+import type { MatchStep, ActionStep, FlowDirective } from '../../ast/nodes.js';
+import type { StepHandler, StepHandlerDeps } from './types.js';
+import { evaluate } from '../evaluator.js';
+import type { ExecutionContext } from '../context.js';
+import { findMatchingSchema } from '../schema-matcher.js';
+import {
+  NoMatchError,
+  AbortError,
+  SkipSignal,
+  RetrySignal,
+  JumpSignal,
+  QueueSignal,
+} from '../signals.js';
+
+/**
+ * Result of executing a match step
+ */
+export interface MatchResult {
+  /** The schema that matched (or '_' for wildcard) */
+  matchedSchema: string;
+  /** Flow directive if the arm specifies one */
+  flow?: FlowDirective;
+  /** Whether steps were executed (vs flow directive) */
+  stepsExecuted: boolean;
+}
+
+export interface MatchHandlerDeps extends StepHandlerDeps {
+  executeStep: (step: ActionStep, actionName: string, ctx: ExecutionContext) => Promise<void>;
+  actionName: string;
+}
+
+/**
+ * Handles match steps (schema overloading with flow control)
+ */
+export class MatchHandler {
+  constructor(private deps: MatchHandlerDeps) {}
+
+  async execute(step: MatchStep): Promise<void> {
+    const value = evaluate(step.target, this.deps.ctx);
+
+    // Get schema names from arms in order
+    const schemaNames = step.arms.map(arm => arm.schema);
+
+    // Find matching schema
+    const matchedSchema = findMatchingSchema(value, this.deps.ctx.schemas, schemaNames);
+
+    if (!matchedSchema) {
+      throw new NoMatchError(value);
+    }
+
+    this.deps.log(`Matched schema: ${matchedSchema}`);
+
+    // Find the matching arm
+    const arm = step.arms.find(a => a.schema === matchedSchema);
+
+    if (!arm) {
+      // Shouldn't happen if findMatchingSchema works correctly
+      throw new NoMatchError(value);
+    }
+
+    // Handle flow directive
+    if (arm.flow) {
+      // 'continue' means proceed normally - don't throw
+      if (arm.flow.type === 'continue') {
+        return;
+      }
+      this.handleFlowDirective(arm.flow, value);
+    }
+
+    // Execute steps
+    if (arm.steps) {
+      for (const innerStep of arm.steps) {
+        await this.deps.executeStep(innerStep, this.deps.actionName, this.deps.ctx);
+      }
+    }
+  }
+
+  private handleFlowDirective(flow: Exclude<FlowDirective, { type: 'continue' }>, value: unknown): never {
+    switch (flow.type) {
+      case 'skip':
+        throw new SkipSignal();
+
+      case 'abort':
+        throw new AbortError(flow.message);
+
+      case 'retry':
+        throw new RetrySignal(flow.backoff);
+
+      case 'jump':
+        throw new JumpSignal(flow.action, flow.then);
+
+      case 'queue':
+        throw new QueueSignal(value, flow.target);
+
+      default:
+        // This should never happen if TypeScript is working correctly
+        const _exhaustive: never = flow;
+        throw new Error(`Unknown flow directive: ${(_exhaustive as FlowDirective).type}`);
+    }
+  }
+}

package/src/interpreter/step-handlers/store-handler.ts

@@ -0,0 +1,78 @@
+import type { StoreStep } from '../../ast/nodes.js';
+import type { StepHandler, StepHandlerDeps } from './types.js';
+import type { StoreAdapter } from '../../stores/types.js';
+import { evaluate } from '../evaluator.js';
+
+/**
+ * Handles store steps for persisting data
+ */
+export class StoreHandler implements StepHandler<StoreStep> {
+  constructor(private deps: StepHandlerDeps) {}
+
+  async execute(step: StoreStep): Promise<void> {
+    const store = this.deps.ctx.stores.get(step.target);
+    if (!store) {
+      throw new Error(`Store not found: ${step.target}`);
+    }
+
+    const source = evaluate(step.source, this.deps.ctx);
+
+    if (Array.isArray(source)) {
+      await this.storeMany(step, store, source);
+    } else {
+      await this.storeOne(step, store, source as Record<string, unknown>);
+    }
+  }
+
+  private async storeMany(step: StoreStep, store: StoreAdapter, items: unknown[]): Promise<void> {
+    // Use bulk operation if available and not doing upserts (which need individual handling)
+    if (store.bulkSet && !step.options.upsert) {
+      const records: Array<{ key: string; value: Record<string, unknown> }> = [];
+      for (const item of items) {
+        const record = item as Record<string, unknown>;
+        const key = step.options.key
+          ? String(evaluate(step.options.key, this.deps.ctx, record))
+          : String(record.id ?? Math.random());
+
+        if (step.options.partial !== undefined) {
+          record._partial = step.options.partial;
+        }
+        records.push({ key, value: record });
+      }
+      await store.bulkSet(records);
+    } else {
+      // Fall back to individual operations for upserts or stores without bulkSet
+      for (const item of items) {
+        const record = item as Record<string, unknown>;
+        await this.storeRecord(step, store, record);
+      }
+    }
+
+    this.deps.log(`Stored ${items.length} items to ${step.target}`);
+  }
+
+  private async storeOne(step: StoreStep, store: StoreAdapter, record: Record<string, unknown>): Promise<void> {
+    await this.storeRecord(step, store, record);
+    this.deps.log(`Stored item to ${step.target}`);
+  }
+
+  private async storeRecord(
+    step: StoreStep,
+    store: StoreAdapter,
+    record: Record<string, unknown>
+  ): Promise<void> {
+    const key = step.options.key
+      ? String(evaluate(step.options.key, this.deps.ctx, record))
+      : String(record.id ?? Math.random());
+
+    if (step.options.partial !== undefined) {
+      record._partial = step.options.partial;
+    }
+
+    if (step.options.upsert) {
+      await store.update(key, record);
+    } else {
+      await store.set(key, record);
+    }
+  }
+}

package/src/interpreter/step-handlers/types.ts

@@ -0,0 +1,17 @@
+import type { ActionStep } from '../../ast/nodes.js';
+import type { ExecutionContext } from '../context.js';
+
+/**
+ * Dependencies injected into step handlers
+ */
+export interface StepHandlerDeps {
+  ctx: ExecutionContext;
+  log: (message: string) => void;
+}
+
+/**
+ * Base interface for step handlers
+ */
+export interface StepHandler<TStep extends ActionStep> {
+  execute(step: TStep): Promise<void>;
+}

package/src/interpreter/step-handlers/validate-handler.ts

@@ -0,0 +1,30 @@
+import type { ValidateStep } from '../../ast/nodes.js';
+import type { StepHandler, StepHandlerDeps } from './types.js';
+import { evaluate } from '../evaluator.js';
+
+/**
+ * Handles validate steps with assume constraints
+ */
+export class ValidateHandler implements StepHandler<ValidateStep> {
+  constructor(private deps: StepHandlerDeps) {}
+
+  async execute(step: ValidateStep): Promise<void> {
+    const target = evaluate(step.target, this.deps.ctx);
+
+    for (const constraint of step.constraints) {
+      const result = evaluate(constraint.condition, this.deps.ctx, target);
+
+      if (!result) {
+        const message = constraint.message ?? `Validation failed: ${JSON.stringify(constraint.condition)}`;
+
+        if (constraint.severity === 'error') {
+          throw new Error(message);
+        } else {
+          this.deps.log(`Warning: ${message}`);
+        }
+      }
+    }
+
+    this.deps.log('Validation passed');
+  }
+}

package/src/interpreter/step-handlers/webhook-handler.ts

@@ -0,0 +1,142 @@
+/**
+ * Webhook Handler
+ *
+ * Handles the 'wait' step for waiting on webhook callbacks.
+ */
+
+import type { WebhookStep } from '../../ast/nodes.js';
+import type { ExecutionContext } from '../context.js';
+import { evaluate } from '../evaluator.js';
+import type { WebhookServer, WebhookRegistration, WebhookEvent } from '../../webhook/index.js';
+import { RetrySignal } from '../signals.js';
+
+/**
+ * Dependencies for the webhook handler
+ */
+export interface WebhookHandlerDeps {
+  ctx: ExecutionContext;
+  webhookServer: WebhookServer;
+  executionId: string;
+  log: (message: string) => void;
+}
+
+/**
+ * Result of webhook handler execution
+ */
+export interface WebhookHandlerResult {
+  registration: WebhookRegistration;
+  events: WebhookEvent[];
+  webhookUrl: string;
+}
+
+/**
+ * Handler for webhook (wait) steps
+ */
+export class WebhookHandler {
+  private deps: WebhookHandlerDeps;
+
+  constructor(deps: WebhookHandlerDeps) {
+    this.deps = deps;
+  }
+
+  /**
+   * Execute the wait step
+   */
+  async execute(step: WebhookStep): Promise<WebhookHandlerResult> {
+    const { ctx, webhookServer, executionId, log } = this.deps;
+
+    // Register webhook endpoint
+    const timeout = step.timeout ?? 300000; // 5 minutes default
+    const expectedEvents = step.expectedEvents ?? 1;
+
+    const registration = await webhookServer.register(executionId, {
+      path: step.path,
+      timeout,
+      expectedEvents,
+      filter: step.eventFilter ? JSON.stringify(step.eventFilter) : undefined,
+    });
+
+    const webhookUrl = webhookServer.getWebhookUrl(registration);
+    log(`Waiting for webhook: ${webhookUrl} (timeout: ${timeout}ms, expected: ${expectedEvents})`);
+
+    // Set the webhook URL in context for use in subsequent steps
+    ctx.response = {
+      webhookId: registration.id,
+      webhookUrl,
+      webhookPath: registration.path,
+    };
+
+    // Wait for webhook events
+    const result = await webhookServer.waitForEvents(registration.id, timeout);
+
+    if (result.timedOut) {
+      log(`Webhook timeout: ${webhookUrl}`);
+
+      // Check if retry is configured
+      if (step.retryOnTimeout) {
+        throw new RetrySignal(step.retryOnTimeout);
+      }
+
+      // If not retrying, still return partial results
+      if (result.events.length === 0) {
+        throw new Error(`Webhook timeout: no events received within ${timeout}ms`);
+      }
+    }
+
+    // Filter events if filter expression provided
+    let events = result.events;
+    if (step.eventFilter && events.length > 0) {
+      events = events.filter((event) => {
+        try {
+          const filterCtx = { ...ctx, response: event.body };
+          return evaluate(step.eventFilter!, filterCtx);
+        } catch {
+          return true; // Include on filter error
+        }
+      });
+    }
+
+    log(`Received ${events.length} webhook event(s)`);
+
+    // Set response to webhook events
+    if (events.length === 1) {
+      ctx.response = events[0].body;
+    } else {
+      ctx.response = events.map((e) => e.body);
+    }
+
+    // Store events if storage configured
+    if (step.storage) {
+      const store = ctx.stores.get(step.storage.target);
+      if (store) {
+        for (const event of events) {
+          const data = event.body as Record<string, unknown>;
+          let key: string;
+
+          if (step.storage.key) {
+            const keyCtx = { ...ctx, response: event.body };
+            const keyValue = evaluate(step.storage.key, keyCtx);
+            key = String(keyValue);
+          } else {
+            // Generate a key from the event ID
+            key = event.id;
+          }
+
+          await store.set(key, data);
+          log(`Stored webhook event: ${key}`);
+        }
+      } else {
+        log(`Warning: Store '${step.storage.target}' not found for webhook storage`);
+      }
+    }
+
+    // Clean up registration
+    await webhookServer.unregister(registration.id);
+
+    return {
+      registration,
+      events,
+      webhookUrl,
+    };
+  }
+}

package/src/lexer/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Lexer module for Reqon.
+ *
+ * Uses Vague's Lexer with Reqon keywords registered via the plugin system.
+ * Importing this module automatically registers the Reqon plugin.
+ */
+
+// Import plugin to auto-register Reqon keywords with Vague
+import '../plugin.js';
+
+// Re-export Vague's Lexer and TokenType as the primary lexer
+export { Lexer, Lexer as ReqonLexer, TokenType, type Token } from 'vague-lang';
+
+// Export Reqon-specific token types and keywords
+export { ReqonTokenType, REQON_KEYWORDS } from './tokens.js';
+
+// Re-export Token type with Reqon compatibility alias
+export type { Token as ReqonToken } from 'vague-lang';