@onlineapps/cookbook-core

Core cookbook parsing and validation library - lightweight foundation for workflow definitions.

Overview

This package provides the essential parsing and validation functionality for cookbook workflow definitions. It contains no heavy dependencies and focuses purely on structural validation.

Installation

npm install @onlineapps/cookbook-core

Features

• JSON Schema validation - Strict schema enforcement
• Recursive step validation - All step types supported
• Unique ID validation - Ensures no duplicate step IDs
• Lightweight - ~50KB with minimal dependencies
• Zero external dependencies - Only uses ajv for validation

Usage

Basic parsing and validation

const {
  parseCookbookFromFile,
  parseCookbookFromObject,
  validateCookbook
} = require('@onlineapps/cookbook-core');

// Parse from file
const cookbook = await parseCookbookFromFile('./workflow.json');

// Parse from object
const cookbookObj = parseCookbookFromObject(rawData);

// Validate only
validateCookbook(cookbookData); // throws CookbookValidationError if invalid

Error handling

const { CookbookValidationError } = require('@onlineapps/cookbook-core');

try {
  validateCookbook(data);
} catch (error) {
  if (error instanceof CookbookValidationError) {
    console.error('Validation failed:', error.message);
  }
}

Schema access

const { CookbookSchema } = require('@onlineapps/cookbook-core');

// Access the raw JSON schema for custom validation
console.log(CookbookSchema.properties);

API Reference

Parser Functions

• parseCookbookFromFile(filePath) - Async file parsing
• parseCookbookFromFileSync(filePath) - Sync file parsing
• parseCookbookFromObject(object) - Object parsing

Validator Functions

• validateCookbook(cookbook) - Full cookbook validation
• validateStep(step) - Single step validation

Schema Functions

• loadSchema() - Load cookbook JSON schema
• CookbookSchema - Pre-loaded schema object

Error Classes

• CookbookValidationError - Validation error class

Step Types Supported (V2.1)

• task - Service operation execution
• foreach - Iteration over arrays (body is an array of steps)
• fork_join - Parallel execution branches (branches is an object)
• switch - Conditional branching (cases is an object keyed by value)
• steps - Nested group of steps (replaces sub_workflow)
• wait - Time delay (durationMs)
• dispatch - Webhook/HTTP/GRPC/Kafka/SQS/custom dispatch

Documentation

• Schema Audit Report - Critical analysis of validation rules
• Test Coverage - Progressive test scenarios

Related Packages

• @onlineapps/cookbook-executor - Workflow execution engine
• @onlineapps/cookbook-transformer - OpenAPI mapping
• @onlineapps/cookbook-router - Message routing
• @onlineapps/connector-cookbook - Full-featured wrapper for microservices

Known Issues

See Schema Audit for current validation limitations and recommendations.

License

PROPRIETARY - All rights reserved