TypeScript Recipe Validator

This is a TypeScript port of the Python recipe validator from workato-platform-cli.

Quick Start

Installation

# Install dependencies
npm install

# Build the TypeScript code
npm run build

Using the CLI

# Show help
npm run cli -- --help

# Validate a recipe
npm run cli -- -i sample-recipe.json

# Validate with verbose output
npm run cli -- -i sample-recipe.json -v

# Validate and save JSON results
npm run cli -- -i sample-recipe.json -f json -o results.json

# Validate with summary format (great for batch processing)
npm run cli -- -i sample-recipe.json -f summary

See CLI_USAGE.md for complete CLI documentation.

Running the Example

# Run the example directly with ts-node
npm run example

Using in Your Code

import { RecipeValidator } from './validator';

// See example.ts for full usage

Source

Converted from: /Users/jacobgorenm4/src/workato-platform-cli/src/workato_platform/cli/commands/recipes/validator.py

Features

Enums

• Keyword: Recipe structure keywords (trigger, action, if, foreach, etc.)
• ErrorType: Validation error types

Interfaces

• ValidationError: Individual validation error details
• ValidationResult: Complete validation result with errors and warnings
• RecipeLine: Recipe line/step structure with all properties
• RecipeAccountId: Recipe account identification
• RecipeConfig: Recipe configuration
• Recipe: Complete recipe structure
• WorkatoClient: Simplified Workato API client interface
• PlatformConnector: Platform connector metadata
• CustomConnector: Custom connector metadata

RecipeValidator Class

Main Methods

• validateRecipe(recipeData): Main validation entry point (async)

Validation Methods

• validateRecipeStructure(): Validates overall recipe structure
• validateStructureRecursive(): Recursive structure validation
• validateLineStructure(): Line-specific structure validation
• validateIfStructure(): IF block validation
• validateForeachStructure(): FOREACH block validation
• validateRepeatStructure(): REPEAT block validation
• validateTryStructure(): TRY/CATCH block validation
• validateActionStructure(): ACTION validation
• validateProviders(): Provider and connector validation
• validateUniqueAsValues(): Ensures unique 'as' values across recipe
• validateReferencesWithContext(): Validates data pill references with context
• validateDataPillReferencesWithContext(): Validates data pill format and cross-references
• validateDataPillCrossReference(): Validates specific data pill cross-references
• validateSchemas(): Schema validation
• validateExpressions(): Expression validation
• validateInputExpressions(): Input field expression validation
• validateConfigCoverage(): Config section coverage validation
• validateArrayMappings(): Array mapping validation
• validateDataPillStructures(): Data pill structure validation
• validateArrayConsistency(): Array structure consistency validation
• validateBlockStructure(): Block numbering validation
• validateInputModes(): Input mode consistency validation
• validateFormulaSyntax(): Formula syntax validation
• validateGenericSchemaUsage(): Generic schema usage validation
• validateArrayMappingsEnhanced(): Enhanced array mapping validation

Helper Methods

• parseRecipeLine(): Parses raw JSON into RecipeLine structure
• extractDataPills(): Extracts data pill references from text
• isValidDataPill(): Validates data pill format
• isExpression(): Checks if text is an expression
• isValidExpression(): Validates expression syntax
• collectProviders(): Collects all providers used in recipe
• stepExists(): Checks if a step exists
• findStepByAs(): Finds a step by provider and 'as' value
• extractPathFromDp(): Extracts path from _dp() string
• isValidElementPath(): Validates element path consistency
• isControlBlock(): Checks if step is a control block
• stepUsesDataPills(): Checks if step uses data pills
• stepIsReferenced(): Checks if step is referenced by others
• findReferencesToStep(): Finds references to a specific step
• searchForReferencePattern(): Searches for reference patterns

Connector Management

• ensureConnectorsLoaded(): Ensures connector metadata is loaded
• loadBuiltinConnectors(): Loads connector metadata from API (async)
• loadCachedConnectors(): Loads connector metadata from cache
• saveConnectorsToCache(): Saves connector metadata to cache

Key Differences from Python Version

1. Type System: Uses TypeScript interfaces instead of Pydantic models
2. Validation: Manual validation in parseRecipeLine instead of Pydantic validators
3. Pattern Matching: Uses RegExp instead of Python's re module
4. File I/O: Uses Node.js fs module instead of Python's pathlib and open()
5. JSON Parsing: Native JSON.parse/stringify instead of Python's json module
6. Async/Await: Both use async/await, but TypeScript uses Promise<T> return types

Usage Example

import { RecipeValidator } from './validator';

// Create a Workato API client (implementation not shown)
const workatoClient: WorkatoClient = {
  connectors: {
    listPlatformConnectors: async (page, perPage) => { /* ... */ },
    listCustomConnectors: async () => { /* ... */ },
    getCustomConnectorCode: async (id) => { /* ... */ }
  }
};

// Create validator instance
const validator = new RecipeValidator(workatoClient);

// Validate a recipe
const recipeData = {
  name: 'My Recipe',
  description: 'A test recipe',
  private: false,
  concurrency: 1,
  code: {
    number: 0,
    keyword: 'trigger',
    uuid: '12345678-1234-1234-1234-123456789012',
    provider: 'salesforce',
    name: 'new_object',
    // ... more fields
  },
  config: [
    {
      keyword: 'application',
      provider: 'salesforce',
      // ... more config
    }
  ]
};

const result = await validator.validateRecipe(recipeData);

if (result.isValid) {
  console.log('Recipe is valid!');
} else {
  console.log('Validation errors:');
  result.errors.forEach(error => {
    console.log(`  - ${error.message} (line ${error.lineNumber})`);
  });
}

Cache Location

Connector metadata is cached at: ~/.workato_platform/cli/connector_cache.json

Cache expires after 24 hours by default.

Notes

• The TypeScript version maintains 100% functional parity with the Python version
• All validation methods have been ported
• All helper methods have been ported
• Legacy compatibility methods are preserved
• The code structure closely mirrors the Python version for easy maintenance