Skip to content
/ jsfe Public

JavaScript Flow Engine - Host agnostic workflow orchestration engine for conversational platforms. Supports secured multi-flow, multi-step user journeys, robust error handling, and flexible REST API/tool integration with declarative arguments and response mappings.

www.npmjs.com/package/jsfe

License

View license
2 stars 1 fork Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

ronpinkas/jsfe

BranchesTags

Repository files navigation

JSFE — JavaScript Flow Engine

ESM TypeScript library for workflow + tool orchestration.

Install

```bash npm i jsfe ```

📖 Documentation

For detailed tutorials, step-by-step examples, and comprehensive workflow patterns, see the User Guide.

Usage

import { WorkflowEngine } from "jsfe";

// 1. Create the engine
const engine = new WorkflowEngine(
  hostLogger,          // Your logging instance
  aiCallback,          // Your AI communication function
  flowsMenu,           // Array of flow definitions
  toolsRegistry,       // Array of tool definitions
  APPROVED_FUNCTIONS,  // Pre-approved local functions
  globalVariables,     // Optional: Session-wide variables
  validateOnInit,      // Optional: Enable pre-flight validation (default: true)
  language,            // Optional: User's preferred language
  aiTimeOut,           // Optional: AI timeout in milliseconds (default: 2000ms)
  messageRegistry,     // Optional: Custom message templates
  guidanceConfig       // Optional: User assistance configuration
);

// 2. Initialize a session for each user
let sessionContext = engine.initSession(yourLogger, 'user-123', 'session-456');

// 3. Process user message and update session context
const userEntry = {
  role: 'user',
  content: 'I need help with my account',
};
const updatedSessionContext = await engine.updateActivity(userEntry, sessionContext);
sessionContext = updatedSessionContext; // CRITICAL: Always update your session reference

if (updatedSessionContext.response) {
  // Intent detected and handled - return the workflow response
  // If flow activated you should not proceed to your normal handling
  return updatedSessionContext.response;
}

// 4. Call your normal Generate reply process as usual
const reply = await yourConversationalReply(input);

// 5. Update the engine's context with the generated reply
const assistantEntry = {
  role: 'assistant',
  content: reply, // The reply generated by your process
};
sessionContext = await engine.updateActivity(assistantEntry, sessionContext);

// Return the generated reply to the user
return reply;

Engine Initialization Parameters

The WorkflowEngine constructor accepts the following parameters in order, each serving a specific purpose in the engine's operation:

1. hostLogger (Logger | null)

  • Purpose: Primary logging interface for the host application
  • Requirements: Must support .debug(), .info(), .warn(), .error() methods
  • Usage: Engine uses this for all operational logging and debugging output
  • Example: Winston, or custom logger implementation
  • Nullable: Can be null to disable host application logging

2. aiCallback (Function)

  • Purpose: AI communication function for intent detection and response generation
  • Signature: async (systemInstruction: string, userMessage: string) => string
  • Integration: Engine calls this function when AI analysis is needed
  • Requirements: Must return AI response as string, handle errors gracefully
  • Details: See dedicated AI Callback Function section below

3. flowsMenu (FlowDefinition[])

  • Purpose: Array of available workflow definitions
  • Content: All workflows that the engine can detect and execute
  • Validation: Engine validates flow structure during initialization
  • Requirements: Each flow must have valid id, name, description, and steps
  • Primary Property: Use primary: true to mark user-facing entry point flows vs. helper sub-flows

4. toolsRegistry (ToolDefinition[])

  • Purpose: Array of external tool definitions for CALL-TOOL steps
  • Content: HTTP APIs, local functions, and mock tools available to workflows
  • Validation: Parameter schemas validated against OpenAI Function Calling Standard
  • Security: Tools define their own security levels and authentication requirements

5. APPROVED_FUNCTIONS (Object)

  • Purpose: Secure registry of pre-approved local JavaScript functions
  • Security: Only functions in this object can be executed by local-type tools
  • Format: Plain object where keys are function names and values are the actual functions
  • Validation: Functions must match tool definitions in toolsRegistry

6. globalVariables (Record<string, unknown>, optional)

  • Purpose: Session-wide variables accessible to all workflows
  • Scope: Available to all flows in the session via variable interpolation
  • Security: Safe sharing of host application data with workflows
  • Examples: User ID, session ID, application configuration, environmental data
  • Nature: STATIC - Set during engine initialization, same for all sessions

Alternative Setting logger: engine.logger = logger

hostLogger (Logger)

  • Purpose: Primary logging interface for the host application
  • Requirements: Must support .debug(), .info(), .warn(), .error() methods
  • Usage: Engine uses this for all operational logging and debugging output
  • Example: Winston, or custom logger implementation
const logger = winston.createLogger({
  level: process.env.LOG_LEVEL || 'warn',  // Enable debug logging to trace validation
  format: winston.format.printf(({ level, message }) => {
    return `${level}: ${message}`;
  }),
  transports: [
    new winston.transports.Console()
  ]
});

engine.logger = logger;

Dynamic Session Data: The cargo Property

Unlike globalVariables which are static and shared across all sessions, each EngineSessionContext has a cargo property for dynamic, session-specific data sharing:

**hostLogger** (Logger | null)
- **Purpose**: Primary logging interface for the host application
- **Requirements**: Must support `.debug()`, `.info()`, `.warn()`, `.error()` methods
- **Usage**: Engine uses this for all operational logging and debugging output
- **Example**: Winston, or custom logger implementation
- **Nullable**: Can be `null` to disable host application logging

// After initSession, you can set dynamic session data
let sessionContext = engine.initSession('user-123', 'session-456');

// Set dynamic data that workflows can access
sessionContext.cargo.userPreferences = { theme: 'dark', language: 'en' };
sessionContext.cargo.currentOrder = { id: 'ORD-123', total: 99.99 };
sessionContext.cargo.temporaryData = 'Any dynamic content';

// Workflows can reference cargo data with variable interpolation
// Example in flow step: "Your order {{cargo.currentOrder.id}} total is ${{cargo.currentOrder.total}}"

Key Differences: globalVariables vs cargo

  • globalVariables: Static, engine-wide, set at initialization, same for all sessions
  • cargo: Dynamic, session-specific, can be modified anytime during conversation
  • Use Cases:
    • globalVariables: API keys, system config, app metadata
    • cargo: User data, conversation state, temporary values, personalization

7. validateOnInit (boolean, optional)

  • Purpose: Enable comprehensive flow and tool validation during initialization
  • Default: true - recommended for development and production
  • Performance: Set to false only in high-performance scenarios with pre-validated flows
  • Output: Detailed validation reports with errors, warnings, and success metrics
  • Primary Flow Validation: Only flows marked with primary: true are validated as top-level workflows
    • Sub-flows are validated in context when called from primary flows
    • Prevents validation errors for helper flows that depend on parent flow variables
    • Ensures complete validation coverage through deep traversal of flow call graphs

8. language (string, optional)

  • Purpose: User's preferred language for localized messages and prompts
  • Format: ISO language code ('en', 'es', 'fr', 'de', etc.)
  • Default: 'en' if not specified
  • Usage: Engine selects appropriate prompt_xx properties from flow definitions

9. aiTimeOut (number, optional)

  • Purpose: Timeout in milliseconds for AI callback function calls
  • Default: 2000ms (2 second) if not specified
  • Usage: Prevents AI calls from hanging indefinitely, providing better reliability
  • Range: Recommended range 1000-30000ms depending on AI service response times
  • Special Value: Set to 0 to disable timeout (no time limit on AI calls)
  • Error Handling: Throws timeout error if AI call exceeds specified duration
// Examples of different timeout configurations:

// Fast local AI (short timeout)
const fastEngine = new WorkflowEngine(logger, aiCallback, flows, tools, functions, 
  {}, true, 'en', 500); // 500ms timeout

// Fast cloud AI 
const standardEngine = new WorkflowEngine(logger, aiCallback, flows, tools, functions, 
  {}, true, 'en', 1000); // 1 second timeout

// No timeout limit (not recommended for production)
const noTimeoutEngine = new WorkflowEngine(logger, aiCallback, flows, tools, functions, 
  {}, true, 'en', 0); // 0 = no timeout

10. messageRegistry (MessageRegistry, optional)

  • Purpose: Custom message templates for engine-generated user messages
  • Format: Multi-language message registry with customizable system messages
  • Override: Allows customization of built-in engine messages
  • Localization: Supports multiple languages with fallback to default messages

11. guidanceConfig (GuidanceConfig, optional)

  • Purpose: Configuration for user guidance and help messages
  • Features: Controls how and when the engine provides user assistance
  • Modes: Append, prepend, template, or none for guidance integration
  • Context: Different guidance for general vs. payment/financial workflows

AI Callback Function

The aiCallback parameter provides the engine access to your AI system for intent detection and workflow triggering. Here's a minimal implementation example:

// Minimal AI callback implementation
async function aiCallback(systemInstruction, userMessage) {
  try {
    const response = await fetch("https://api.openai.com/v1/chat/completions", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${process.env.OPENAI_API_KEY}`
      },
      body: JSON.stringify({
        model: "gpt-4o-mini",
        messages: [
          { role: "system", content: systemInstruction },
          { role: "user", content: userMessage }
        ],
        temperature: 0.1,
        max_tokens: 200
      })
    });

    if (!response.ok) {
      throw new Error(`AI API request failed: ${response.status} ${response.statusText}`);
    }

    const data = await response.json();
    return data.choices[0].message.content.trim();
    
  } catch (error) {
    throw new Error(`AI communication failed: ${error.message}`);
  }
}

AI Callback Interface:

  • Input: systemInstruction (string), userMessage (string)
  • Output: AI response as a string
  • Purpose: Analyzes user input to detect workflow intents and generate responses
  • Integration: The engine calls this function when it needs AI analysis for intent detection

How the Engine Generates Input Arguments:

  • systemInstruction: Dynamically generated by the engine based on:
    • Available flow definitions and their descriptions
    • Current session context and active flows
    • Current conversation state and collected variables
  • userMessage: Intelligently composed by the engine, including:
    • The actual user input/prompt
    • Relevant contextual information from the conversation
    • Session state and variables needed for intent analysis

Both parameters are carefully engineered by the engine to work together for optimal intent detection. The engine automatically constructs comprehensive, context-aware prompts that provide the AI with all necessary information for accurate workflow selection and response generation. Your aiCallback implementation only needs to send these pre-constructed arguments to your AI service and return the response.

Alternative AI Services: You can integrate any AI service (Claude, Gemini, local LLMs, etc.) by implementing this same interface. The engine only requires a function that takes system instructions and user input, then returns an AI response.

Core Registries

The engine operates through four primary registries that define its capabilities:

1. Flows Registry - Workflow Definitions

const flowsMenu = [
  {
    id: "payment-workflow",
    name: "ProcessPayment", 
    prompt: "Process a payment",
    description: "Handle payment processing with validation",
    primary: true, // Optional: Marks this as a primary (user-facing) flow
    steps: [
      { type: "SAY", value: "Let's process your payment." },
      { type: "SAY-GET", variable: "amount", value: "Enter amount:" },
      { type: "CALL-TOOL", tool: "PaymentProcessor", args: {...}, variable: "payment_result", }
    ]
  }
];
Flow Definition Properties
  • id (required): Unique identifier for the flow
  • name (required): Human-readable flow name used in execution context
  • prompt (required): User-facing description for AI intent detection
  • description (required): Detailed description of the flow's purpose
  • primary (optional): Boolean flag marking user-facing entry point flows
    • true: Primary flows are standalone workflows that users can directly trigger
    • false or omitted: Helper/sub-flows called by other flows, not directly accessible
    • Validation Impact: Only primary flows are validated as top-level workflows during initialization
    • AI Detection: Only primary flows are considered for intent detection and user interaction
  • steps (required): Array of workflow steps to execute
  • variables (optional): Flow-specific variable definitions with types and descriptions
  • version (optional): Flow version for compatibility tracking (defaults to "1.0")
Primary vs. Sub-Flow Architecture

The primary property enables a clean separation between:

Primary Flows (primary: true):

  • User-facing workflows that can be directly triggered by user input
  • Entry points for specific business processes (e.g., "StartPayment", "CreateTicket")
  • Included in AI intent detection and flow selection
  • Validated as standalone workflows during engine initialization

Sub-Flows (no primary property or primary: false):

  • Helper workflows called by other flows (e.g., "RetryPayment", "ValidateInput")
  • Internal logic flows for error handling, validation, or shared functionality
  • Not directly accessible to users through intent detection
  • Validated only when called from primary flows, ensuring proper variable context

This architecture prevents validation errors for sub-flows that depend on variables from their calling flows, while ensuring complete validation coverage during the engine's deep validation process.

Referencing Tool Results in Later Steps

When a CALL-TOOL step finishes, it can store the returned data into a variable you name via the variable property. That variable will hold the entire return object from the tool.

Using variable
{
  "type": "CALL-TOOL",
  "tool": "CreateSupportTicket",
  "variable": "ticket_result",
  "args": {
    "subject": "{{subject}}",
    "description": "{{description}}",
    "customer_email": "{{customer_email}}"
  }
},
{
  "type": "SAY",
  "value": "Ticket created: {{ticket_result.ticket.id}} — we'll email updates to {{ticket_result.ticket.customer_email}}."
}
Important:

Whatever your tool returns becomes the value of the variable you specify. Because you get the raw return object, you do not need to use .result in your template paths—just reference the keys the tool returns (ticket_result.ticket.id, ticket_result.ok, etc.). If you omit variable, you won’t be able to access the tool’s output later.

2. Tools Registry - External Integrations

const toolsRegistry = [
  {
    id: "PaymentProcessor",
    name: "Process Payment",
    description: "Processes financial transactions securely",
    parameters: { /* OpenAI Function Calling Standard Schema */ },
    implementation: {
      type: "local", // or "http" for REST APIs
      function: "processPayment",
      timeout: 10000
    },
    security: {
      requiresAuth: true,
      auditLevel: "critical",
      dataClassification: "financial"
    }
  }
];

3. Approved Functions Registry - Secure Local Functions

const APPROVED_FUNCTIONS = {};

// Define secure local functions
async function processPayment(args) {
  // Secure payment processing logic
  return { transactionId: "...", status: "success" };
}

// Register approved functions
APPROVED_FUNCTIONS['processPayment'] = processPayment;

4. Global Variables - Secure Sharing of Local Data

const globalVariables = {
  caller_id: "(555) 123-4567",
  caller_name: "John Doe", 
  thread_id: "conversation-123"
};

Session Management

  • Each user requires a unique session context via initSession(userId, sessionId)
  • CRITICAL: updateActivity() returns an updated EngineSessionContext
  • You must always update your session reference on every call
  • The EngineSessionContext object should be persisted by your application
  • Pass the same session context to updateActivity for conversation continuity
  • Session Isolation: Each user/session must have its own context to prevent state contamination

Session Cargo for Dynamic Data

Each session context includes a cargo property for dynamic, session-specific data that workflows can access:

// Initialize session
let sessionContext = engine.initSession('user-123', 'session-456');

// Set dynamic session data that workflows can reference
sessionContext.cargo.userProfile = {
  name: 'John Doe',
  tier: 'premium',
  preferences: { notifications: true }
};

// Workflows can access cargo data: "Welcome {{cargo.userProfile.name}}!"
sessionContext = await engine.updateActivity(userEntry, sessionContext);

Correct Session Update Pattern

// Initialize session
let sessionContext = engine.initSession('user-123', 'session-456');

// For every updateActivity call, capture the returned context
sessionContext = await engine.updateActivity(userEntry, sessionContext);

// Check for workflow response
if (sessionContext.response) {
  return sessionContext.response;
}


// Continue with regular conversation...
sessionContext = await engine.updateActivity(assistantEntry, sessionContext);

❌ Common Mistake - Not Updating Session Reference

// WRONG - This will cause session corruption
const sessionContext = engine.initSession('user-123', 'session-456');
await engine.updateActivity(userEntry, sessionContext); // Session state lost!

✅ Correct Pattern - Always Update Session Reference

// CORRECT - Session state maintained
let sessionContext = engine.initSession('user-123', 'session-456');
sessionContext = await engine.updateActivity(userEntry, sessionContext); // Session updated

Context Entry Types

  • User input: contextEntry.role = 'user' - analyzed and may trigger flow execution
  • Assistant response: contextEntry.role = 'assistant' - added to context for awareness

ContextEntry Structure

interface ContextEntry {
  role: 'user' | 'assistant' | 'system' | 'tool';  // Message role type
  content: string | Record<string, unknown>;       // Message content (text, object, etc.)
  timestamp: number;                               // Unix timestamp in milliseconds
  stepId?: string;                                 // Optional: Used by the system when a Step calls a Tool
  toolName?: string;                               // Optional: Used by the system to record Tool result into the chat context
  metadata?: Record<string, unknown>;              // Optional: Additional context data
}

UpdateActivity Method

The updateActivity method is the primary interface for processing user inputs and assistant responses. It returns an updated EngineSessionContext that must be captured and used for subsequent calls.

Method Signature

async updateActivity(
  contextEntry: ContextEntry, 
  engineSessionContext: EngineSessionContext
): Promise<EngineSessionContext>

Return Value

The method returns an updated EngineSessionContext containing:

  • Updated flow state: Modified flow stacks, variables, and execution context
  • Response data: If a workflow was triggered, sessionContext.response contains the result
  • Session metadata: Updated timestamps, accumulated messages, and transaction data

Integration Pattern

// Process user input
let sessionContext = await engine.updateActivity({
  role: 'user',
  content: userMessage,
  timestamp: Date.now()
}, sessionContext);

// Check if a workflow was activated
if (sessionContext.response) {
  // Workflow handled the input - return the workflow response
  return sessionContext.response;
}

// No workflow triggered - proceed with normal conversation
const aiResponse = await yourAIFunction(userMessage);

// Update context with AI response
sessionContext = await engine.updateActivity({
  role: 'assistant', 
  content: aiResponse,
  timestamp: Date.now()
}, sessionContext);

return aiResponse;

Critical Notes

  • Always capture the return value: Failing to update your session reference will cause state corruption
  • Session isolation: Each user/conversation needs its own session context
  • Response checking: Check sessionContext.response to determine if a workflow handled the input
  • Persistence: Your application should persist the updated session context between requests

Architecture Overview

Stack-of-Stacks Design

The Flow Engine implements a sophisticated "stack-of-stacks" architecture that allows flows to be suspended and resumed, enabling users to naturally interrupt one workflow to handle another task, then return to their original workflow seamlessly.

Core Components

  1. Multiple Independent Flow Execution Stacks

    • Active stack index tracks current execution context
    • Automatic stack switching for flow interruption/resumption
    • Proper isolation between different workflow contexts

  2. Flow Frame Structure (Runtime Execution Context) Each flow execution maintains a complete context frame:

    interface FlowFrame {
  flowName: string;                              // Human-readable flow name (from FlowDefinition.name)
  flowId: string;                                // Unique flow identifier (from FlowDefinition.id)
  flowVersion: string;                           // Flow version for compatibility (from FlowDefinition.version)
  flowStepsStack: FlowStep[];                    // Remaining steps (reversed for efficient pop)
  contextStack: ContextEntry[];                  // Complete interaction history with role info
  inputStack: unknown[];                         // Current input context for step execution
  variables: Record<string, unknown>;            // Unified variable storage (shared across sub-flows)
  transaction: TransactionObj;                   // Comprehensive transaction and audit tracking
  userId: string;                                // User identifier for this flow session
  startTime: number;                             // Flow start timestamp for timing analysis
  pendingVariable?: string;                      // Variable name awaiting user input (SAY-GET steps)
  lastSayMessage?: string;                       // Last SAY step output for context
  pendingInterruption?: Record<string, unknown>; // Interruption state management
  accumulatedMessages?: string[];                // Accumulated SAY messages for batching
  parentTransaction?: string;                    // Parent transaction ID for sub-flow tracking
  justResumed?: boolean;                         // Flag indicating flow was just resumed
}

    Technical Implementation Details:

    • Flow Identity: flowName, flowId, flowVersion are copied from the FlowDefinition
    • Dynamic Properties: Flow prompt, description, and localized prompts are accessed dynamically from FlowDefinition
    • flowStepsStack: Steps stored in reverse order for efficient pop operations
    • contextStack: Enhanced with role information for complete conversation context
    • variables: Flat storage shared across sub-flows for seamless data passing
    • accumulatedMessages: SAY steps are batched for efficient output
    • justResumed: Helps engine provide appropriate resumption messages

  3. Helper Function Architecture All stack operations go through centralized helper functions:

    • initializeFlowStacks(engine): Ensures proper structure
    • getCurrentStack(engine): Gets currently active stack
    • pushToCurrentStack(engine, frame): Adds flow to active stack
    • popFromCurrentStack(engine): Removes flow from active stack

  4. Tool Definition Structure (Runtime Integration Context) Tools provide external capabilities with comprehensive security and validation:

    interface ToolDefinition {
  id: string;                                    // Unique tool identifier
  name: string;                                  // Human-readable tool name
  description: string;                           // Tool functionality description
  
  parameters?: {                                 // OpenAI Function Calling Standard schema
    type: string;                                // Parameter type structure
    properties?: Record<string, PropertySchema>; // Parameter validation rules
    required?: string[];                         // Required parameter names
    additionalProperties?: boolean;              // Additional parameter handling
  };
  
  implementation?: {                             // Execution configuration
    type: 'local' | 'http';                      // Implementation type
    function?: string;                           // Local function name (APPROVED_FUNCTIONS)
    url?: string;                                // HTTP endpoint with {param} placeholders
    method?: HttpMethod;                         // HTTP method
    pathParams?: string[];                       // URL parameter substitution
    queryParams?: string[];                      // Query string parameters
    responseMapping?: MappingConfig;             // Response transformation config
    timeout?: number;                            // Request timeout
    retries?: number;                            // Retry attempts
  };
  
  security?: {                                   // Security controls
    rateLimit?: {                                // Rate limiting configuration
      requests: number;                          // Max requests per window
      window: number;                            // Time window in milliseconds
    };
  };
  apiKey?: string;                               // Authentication token
  riskLevel?: 'low' | 'medium' | 'high';         // Security classification
}

    Technical Implementation Details:

    • Parameter Validation: JSON Schema validation with ajv for type safety
    • Local Function Execution: Secure execution through APPROVED_FUNCTIONS registry
    • HTTP Integration: Full REST API support with authentication and retries
    • Response Mapping: Declarative transformation without code injection
    • Security Controls: Rate limiting, risk classification, audit logging
    • Error Handling: Automatic retry logic and graceful degradation

  5. Response Mapping Configuration (MappingConfig Interface) The comprehensive response mapping system supports multiple transformation types:

    export type MappingConfig =
  | JsonPathMappingConfig
  | ObjectMappingConfig  
  | ArrayMappingConfig
  | TemplateMappingConfig
  | ConditionalMappingConfig
  | PathConfig
  | string
  | Record<string, unknown>;

// JSONPath-based field extraction and transformation
export type JsonPathMappingConfig = {
  type: 'jsonPath';
  mappings: Record<string, {
    path: string;                                   // JSONPath expression for data extraction
    transform?: ValueTransformConfig;               // Optional value transformation
    fallback?: unknown;                             // Fallback value if path not found
  }>;
  strict?: boolean;                                 // Strict mode validation
};

// Object structure mapping with nested support
export type ObjectMappingConfig = {
  type: 'object';
  mappings: Record<string, string | PathConfig | MappingConfig | object>;
  strict?: boolean;                                 // Strict mode validation
};

// Array processing with filtering, sorting, and pagination
export type ArrayMappingConfig = {
  type: 'array';
  source?: string;                                  // Source array path
  filter?: ConditionConfig;                         // Filtering conditions
  itemMapping?: MappingConfig;                      // Per-item transformation
  sort?: { field: string; order?: 'asc' | 'desc' }; // Sorting configuration
  offset?: number;                                  // Pagination offset
  limit?: number;                                   // Pagination limit  
  fallback?: unknown[];                             // Fallback array if source not found
};

// Template-based string generation with variable substitution
export type TemplateMappingConfig = {
  type: 'template';
  template: string;                                 // Template string with {{variable}} placeholders
  dataPath?: string;                                // Optional path to resolve template data from
};

// Conditional logic-based mapping selection
export type ConditionalMappingConfig = {
  type: 'conditional';
  conditions: Array<{
    if: ConditionConfig;                            // Condition evaluation
    then: MappingConfig;                            // Mapping to apply if condition true
  }>;
  else?: MappingConfig;                             // Default mapping if no conditions match
};

// Path-based value extraction with transformation
export type PathConfig = {
  path: string;                                     // Data path for extraction
  transform?: ValueTransformConfig;                 // Optional value transformation
  fallback?: unknown;                               // Fallback value if path not found
};

// Comprehensive value transformation system with 25+ transform types
export interface ValueTransformConfig {
  type: 'parseInt' | 'parseFloat' | 'toLowerCase' | 'toUpperCase' | 'trim' | 
        'replace' | 'concat' | 'regex' | 'date' | 'default' | 'conditional' | 
        'substring' | 'split' | 'join' | 'abs' | 'round' | 'floor' | 'ceil' | 
        'template' | 'sum' | 'average' | 'count' | 'min' | 'max' | 'multiply' | 
        'divide' | 'percentage' | 'add' | 'subtract' | 'currentYear' | 
        'yearDifference' | 'handlebars' | 'custom';
  
  // Common transformation parameters
  fallback?: unknown;                               // Default value for failed transforms
  prefix?: string;                                  // String prefix for concat operations
  suffix?: string;                                  // String suffix for concat operations
  pattern?: string;                                 // Regex pattern for replace/match operations
  replacement?: string;                             // Replacement string for regex operations
  template?: string;                                // Template string for template transforms
  value?: unknown;                                  // Static value for default transforms
  
  // Mathematical operation parameters
  precision?: number;                               // Decimal precision for rounding operations
  divisor?: number;                                 // Divisor for division/percentage operations
  multiplier?: number;                              // Multiplier for multiplication operations
  addend?: number;                                  // Value to add for addition operations
  subtrahend?: number;                              // Value to subtract for subtraction operations
  
  // Array and aggregation parameters
  field?: string;                                   // Field name for array aggregations
  delimiter?: string;                               // Delimiter for join/split operations
  index?: number;                                   // Array index for element selection
  
  // Conditional and date parameters
  condition?: ConditionConfig;                      // Condition for conditional transforms
  fromYear?: number;                                // Start year for year difference calculations
  dataPath?: string;                                // Path for accessing context data
}

// Flexible condition evaluation system
export interface ConditionConfig {
  field: string;                               // Field path for evaluation
  operator: 'equals' | 'eq' | 'notEquals' | 'ne' | 'contains' | 'exists' | 
            'notExists' | 'greaterThan' | 'gt' | 'lessThan' | 'lt' | 
            'greaterThanOrEqual' | 'gte' | 'lessThanOrEqual' | 'lte' | 
            'startsWith' | 'endsWith' | 'matches' | 'in' | 'hasLength' | 
            'isArray' | 'isObject' | 'isString' | 'isNumber';
  value?: unknown;                             // Comparison value for operators
}

    Response Mapping Technical Features:

    • Type Safety: Full TypeScript interface definitions with validation
    • Declarative Configuration: No code injection - pure JSON configuration
    • Comprehensive Transforms: 25+ built-in transformation types
    • Mathematical Operations: Arithmetic, statistical, and precision control
    • Date Processing: Dynamic date calculations and formatting
    • Template System: Handlebars-style variable substitution with array iteration
    • Conditional Logic: Complex branching and filtering capabilities
    • Array Processing: Filtering, sorting, pagination, and aggregation
    • Path Resolution: JSONPath support with fallback handling
    • Security: Complete input sanitization and validation

Features & Capabilities

Flow Execution Modes

  • ✅ Linear Flow Execution - Sequential step processing
  • ✅ Sub-Flow Calls - Nested workflow execution
  • ✅ Flow Interruption - Suspend current flow for new task
  • ✅ Flow Resumption - Return to previously suspended flows
  • ✅ Flow Replacement - Replace current flow with new flow
  • ✅ Flow Reboot - Nuclear option: clear all flows and restart

Step Types

  • ✅ SAY - Non-blocking output messages (accumulated)
  • ✅ SAY-GET - Blocking output with user input request
  • ✅ SET - Variable assignment with interpolation support
  • ✅ CALL-TOOL - External tool execution with error handling
  • ✅ FLOW - Sub-flow execution with multiple call types
  • ✅ CASE - Conditional branching with expressions
  • ✅ SWITCH - Conditional branching based on single value matching
  • ✅ RETURN - Terminate all flows and return evaluated expression value

Expression System

The JSFE engine features a powerful, unified JavaScript expression evaluator that provides consistent syntax and behavior across all contexts. This system supports the full range of JavaScript expressions while maintaining security through a trusted developer model and limiting user input usage as values.

Core Features

  • ✅ Full JavaScript Expression Support - All standard operators, functions, and syntax
  • ✅ Type Preservation - Numeric, boolean, and object types maintained correctly
  • ✅ Template Interpolation - {{expression}} syntax for string templates
  • ✅ Direct Expression Evaluation - Pure expressions return their native JavaScript types
  • ✅ Unified Security Model - Same safety framework across all evaluation contexts

Expression Types

Single Expressions (preserve JavaScript types):

// SET steps with pure expressions return native types
{ type: "SET", variable: "count", value: "{{attempt_count + 1}}" }        // Returns number
{ type: "SET", variable: "isValid", value: "{{age >= 18 && verified}}" }  // Returns boolean
{ type: "SET", variable: "user", value: "{{api_response.user}}" }         // Returns object

Template Strings (convert to strings for interpolation):

// String templates with embedded expressions
{ type: "SAY", value: "Attempt {{attempt_count + 1}}/{{max_attempts}}" }  // String result
{ type: "SAY", value: "Welcome {{user.name}} ({{user.verified ? 'Verified' : 'Unverified'}})" }

Supported JavaScript Features

All JavaScript features are supported within a sandboxed environment with access limited to explicitly exported variables and functions.

Security Model

  • Developer Trust: Workflows authored by developers, not end users
  • Parameter Filtering: Only valid JavaScript identifiers allowed as parameters
  • No eval(): Direct Function constructor with parameter validation
  • User Input Safety: User inputs are treated as values, not code

Internationalization and Localization

The JSFE engine supports multiple languages through localized properties in flow definitions and steps. This allows you to create workflows that automatically display messages in the user's preferred language.

Flow-Level Localization

Add localized prompts to your flow definitions using the prompt_xx pattern:

const flowsMenu = [
  {
    id: "payment-flow",
    name: "ProcessPayment",
    prompt: "Process a payment",           // Default (English)
    prompt_es: "Procesar un pago",        // Spanish
    prompt_fr: "Traiter un paiement",     // French
    prompt_de: "Eine Zahlung bearbeiten", // German
    description: "Handle payment processing",
    steps: [ /* ... */ ]
  }
];

Step-Level Localization

Add localized messages to individual steps using the value_xx pattern:

{
  type: "SAY-GET",
  variable: "amount",
  value: "Please enter the payment amount:",           // Default (English)
  value_es: "Por favor ingrese el monto del pago:",    // Spanish
  value_fr: "Veuillez saisir le montant du paiement:", // French
  value_de: "Bitte geben Sie den Zahlungsbetrag ein:"  // German
}

Language Selection

Set the user's preferred language when initializing the engine:

const engine = new WorkflowEngine(
  logger,
  aiCallback,
  flowsMenu,
  toolsRegistry,
  APPROVED_FUNCTIONS,
  globalVariables,
  true,           // validateOnInit
  'es',           // language - Spanish
  1000,           // aiTimeOut - 1 second for faster service
  messageRegistry,
  guidanceConfig
);

Supported Language Codes

  • en - English (default)
  • es - Spanish (Español)
  • pt - Portuguese (Português)
  • fr - French (Français)
  • de - German (Deutsch)
  • Any ISO 639-1 language code

Language Fallback

If a localized property is not found for the specified language, the engine automatically falls back to the default prompt or value property. This ensures your flows always work even if some translations are missing.

// Example: User has language='es' but only English is available
{
  type: "SAY",
  value: "Welcome to our service!"  // Will be used as fallback
  // value_es is missing, so English value is used
}

Expression Template System

The engine supports safe JavaScript expressions within {{}} templates:

// Simple variables
{{userName}}, {{account.balance}}

// Arithmetic
{{amount + fee}}, {{price * quantity}}

// Comparisons
{{age >= 18}}, {{status === 'active'}}

// Logical operations
{{isAdmin && hasAccess}}, {{retryCount < maxRetries}}

// Complex expressions
{{user.permissions.includes('admin') && creditScore > 700}}

JavaScript Method and Function Calls

String Methods:

// Case conversion
{{userInput.toLowerCase().trim()}}

// Email validation
{{email.includes('@') && email.length > 5}}

// Text processing
{{text.substring(0, 10).padEnd(15, '...')}}

Array Methods:

// Length and content checks
{{items.length > 0 && items.includes('premium')}}

// Array manipulation
{{categories.slice(0, 3).join(', ')}}

Math Methods:

// Tax calculation
{{Math.round(price * 1.08)}}

// Ensure non-negative
{{Math.max(balance, 0)}}

Functions:

// Type conversion and validation
{{Number(input) > 0 && !isNaN(Number(input))}}
{{Boolean(user.isActive && user.hasAccess)}}

// URI encoding for API calls
{{encodeURIComponent(searchTerm)}}

// User-defined approved functions
{{currentTime()}} // If registered as approved function
{{extractCryptoFromInput(userMessage)}} // Custom business logic

Demo/Test Mode: Flow Matching Without AI

For demos, tests, or developer convenience, you can set aiCallback to null when constructing the engine. In this mode, intent detection will:

  1. Match by Flow Name or ID (case-insensitive):
    • If the user input exactly matches a flow's name or id, that flow is activated.
  2. Partial Match Fallback:
    • If no exact match is found, the engine will look for a flow whose name or id contains the input (case-insensitive).
  3. No Match:
    • If no match is found, no flow is activated.

This makes it easy to run demos and tests without requiring a real AI intent detection function. In production, always provide a real aiCallback for robust intent detection.

Test Suite Patterns

When creating test suites, follow these patterns to ensure session isolation and prevent state contamination:

Proper Test Isolation Pattern

// ❌ Dangerous - Shared session may cause contamination
const globalSession = engine.initSession('test-user', 'test-session');

for (const testCase of testCases) {
  // This will cause session corruption!
  await runTest(testCase, globalSession);
}

// ✅ Correct - Fresh session per test
for (let i = 0; i < testCases.length; i++) {
  const testCase = testCases[i];
  
  // Create fresh session for each test
  let sessionContext = engine.initSession('test-user', `test-session-${i+1}`);
  
  await runTest(testCase, sessionContext);
}

Test Function Pattern

async function runTest(inputs, sessionContext) {
  for (const input of inputs) {
    // Always update session context
    sessionContext = await engine.updateActivity({
      role: 'user',
      content: input,
      timestamp: Date.now()
    }, sessionContext);
    
    // Check for workflow response
    if (sessionContext.response) {
      console.log('Workflow Response:', sessionContext.response);
    }
  }
}

This pattern ensures that each test runs in complete isolation, preventing the session corruption that can occur when tests share state.

Security & Compliance

Expression Security

  • ✅ Direct JavaScript Evaluation - Native JavaScript execution with security framework
  • ✅ Controlled Access - Only exported variables and functions are accessable JavaScript identifiers allowed as parameters scope
  • ✅ User Input Safety - User inputs treated as values, with protection against code injection

Transaction Management

  • ✅ Comprehensive Audit Trail - Every action logged
  • ✅ Transaction State Tracking - Success/failure/pending states
  • ✅ Error Recovery Logging - Detailed failure analysis
  • ✅ User Context Isolation - Prevent cross-user data leaks

Integration Capabilities

REST API Support

  • ✅ HTTP Methods: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
  • ✅ Content Types: JSON, Form-data, URL-encoded, XML/SOAP, Plain text, Multipart
  • ✅ Authentication: Bearer tokens, Basic auth, API keys, HMAC signatures
  • ✅ Parameter Handling: Path params, Query params, Request body, Headers
  • ✅ Advanced Features: Retries with exponential backoff, Timeouts, Rate limiting

Declarative Response Mapping

The engine supports completely generic response transformation through declarative JSON configuration:

JSONPath Mapping

{
  responseMapping: {
    type: "jsonPath",
    mappings: {
      "output_field": {
        path: "api.response.field[0].value",
        transform: { type: "parseInt", fallback: 0 },
        fallback: "$args.inputField"
      }
    }
  }
}

Object Mapping

{
  responseMapping: {
    type: "object", 
    mappings: {
      "user_name": "name",
      "contact": {
        "email": "email",
        "phone": "phone"
      },
      "metadata": {
        "processed": true,
        "timestamp": "{{new Date().toISOString()}}"
      }
    }
  }
}

Template Mapping

{
  responseMapping: {
    type: "template",
    template: "User {{name}} ({{email}}) from {{$args.source}}"
  }
}

Core Features

  • OpenAI Function Calling Standard schemas
  • JSON Schema validation with ajv
  • Secure function registry
  • Comprehensive error handling & transaction management
  • Audit logging for compliance
  • Rate limiting and input validation

Value Transformations

Supported Transforms

  • Number conversion: parseInt, parseFloat
  • String manipulation: toLowerCase, toUpperCase, trim
  • Text processing: replace (regex), concat (prefix/suffix)
  • Date handling: Convert to ISO date string
  • Fallback values: Default handling for missing data

Security & Best Practices

  • ✅ No code injection possible - all transformations are declarative
  • ✅ Secure path traversal with validation
  • ✅ Fallback handling for missing data
  • ✅ Type coercion with validation
  • ✅ Error handling with graceful degradation

Example Tool Configurations

Simple GET Request

{
  implementation: {
    type: "http",
    url: "https://api.example.com/users",
    method: "GET"
  }
}

Authenticated POST with JSON

{
  implementation: {
    type: "http", 
    url: "https://api.example.com/users",
    method: "POST",
    contentType: "application/json"
  },
  apiKey: "your-bearer-token"
}

Path Parameters with Response Mapping

{
  implementation: {
    type: "http",
    url: "https://api.example.com/users/{userId}",
    method: "GET",
    pathParams: ["userId"],
    responseMapping: {
      type: "object",
      mappings: {
        "user_id": "id",
        "full_name": "name",
        "contact_email": "email"
      }
    }
  }
}

Troubleshooting

Common Session Management Issues

Problem: "engineSessionContext.flowStacks was invalid, initialized fresh flowStacks"

Cause: Session context corruption due to improper session management.

Solutions:

  1. Always update session reference:

    // ❌ Wrong
await engine.updateActivity(entry, sessionContext);

// ✅ Correct  
sessionContext = await engine.updateActivity(entry, sessionContext);

  2. Use unique sessions per user/conversation:

    // ❌ Wrong - sharing sessions
const sharedSession = engine.initSession('shared', 'shared');

// ✅ Correct - isolated sessions
const userSession = engine.initSession(`user-${userId}`, `session-${sessionId}`);

  3. Initialize fresh sessions for testing:

    // For each test case
let sessionContext = engine.initSession('test-user', `test-session-${testIndex}`);

Problem: Workflows not triggering or mock responses

Cause: Corrupted session state or improper context handling.

Solution: Ensure proper session lifecycle:

// Initialize once per user/conversation
let sessionContext = engine.initSession(userId, sessionId);

// Update for every interaction
sessionContext = await engine.updateActivity(userInput, sessionContext);

// Check workflow response
if (sessionContext.response) {
  return sessionContext.response;
}

// Continue with regular conversation
sessionContext = await engine.updateActivity(assistantResponse, sessionContext);

Problem: State bleeding between users/sessions

Cause: Shared session contexts between different users or conversations.

Solution: Maintain strict session isolation:

// Create session per user
const userSessions = new Map();

function getOrCreateSession(userId, sessionId) {
  const key = `${userId}-${sessionId}`;
  if (!userSessions.has(key)) {
    userSessions.set(key, engine.initSession(userId, sessionId));
  }
  return userSessions.get(key);
}

// Update and store session
let sessionContext = getOrCreateSession(userId, sessionId);
sessionContext = await engine.updateActivity(entry, sessionContext);
userSessions.set(`${userId}-${sessionId}`, sessionContext);

About

JavaScript Flow Engine - Host agnostic workflow orchestration engine for conversational platforms. Supports secured multi-flow, multi-step user journeys, robust error handling, and flexible REST API/tool integration with declarative arguments and response mappings.

www.npmjs.com/package/jsfe

Topics

npm workflow automation typescript ai orchestration

Resources

Readme

License

View license
Activity

Stars

2 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases 22

v0.9.28 — Added support for RETURN step Latest
Sep 12, 2025
+ 21 releases

Packages

No packages published

Languages