@onlineapps/cookbook-core 1.0.0

package/schemas/cookbook.strict.schema.json

@@ -0,0 +1,441 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://onlineapps.cz/schemas/cookbook-strict/v2.0.0",
+  "title": "Cookbook Schema - Strict Mode",
+  "description": "Strict validation schema for production environments with all safety checks enabled",
+  "type": "object",
+  "required": ["steps", "version"],
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 100,
+      "pattern": "^[a-zA-Z0-9-_]+$"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Semantic version of the cookbook schema"
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 500
+    },
+    "api_input": {
+      "type": "object",
+      "description": "Initial input data for the workflow"
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Additional metadata for debugging and tracking",
+      "properties": {
+        "created_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "author": {
+          "type": "string"
+        },
+        "tags": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "steps": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 1000,
+      "items": {
+        "$ref": "#/definitions/Step"
+      }
+    }
+  },
+  "definitions": {
+    "Step": {
+      "type": "object",
+      "required": ["id", "type"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100,
+          "pattern": "^[a-zA-Z0-9-_]+$"
+        },
+        "type": {
+          "type": "string",
+          "enum": ["task", "foreach", "fork_join", "switch", "sub_workflow", "wait", "dispatch"]
+        }
+      },
+      "oneOf": [
+        { "$ref": "#/definitions/TaskStep" },
+        { "$ref": "#/definitions/ForeachStep" },
+        { "$ref": "#/definitions/ForkJoinStep" },
+        { "$ref": "#/definitions/SwitchStep" },
+        { "$ref": "#/definitions/SubWorkflowStep" },
+        { "$ref": "#/definitions/WaitStep" },
+        { "$ref": "#/definitions/DispatchStep" }
+      ]
+    },
+    "TaskStep": {
+      "type": "object",
+      "required": ["id", "type", "service"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100,
+          "pattern": "^[a-zA-Z0-9-_]+$"
+        },
+        "type": {
+          "type": "string",
+          "const": "task"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200
+        },
+        "service": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100,
+          "pattern": "^[a-zA-Z0-9-_]+$"
+        },
+        "operation": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100,
+          "description": "Operation identifier for the service to execute"
+        },
+        "action": {
+          "type": "string",
+          "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"]
+        },
+        "endpoint": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 500
+        },
+        "input": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string",
+            "minLength": 1
+          },
+          "description": "Optional input mapping"
+        },
+        "output": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string",
+            "minLength": 1
+          },
+          "description": "Optional output mapping"
+        },
+        "depends_on": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 100
+          },
+          "maxItems": 100
+        },
+        "retry": {
+          "$ref": "#/definitions/Retry"
+        },
+        "timeoutMs": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 3600000
+        }
+      }
+    },
+    "ForeachStep": {
+      "type": "object",
+      "required": ["id", "type", "iterator", "body"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100,
+          "pattern": "^[a-zA-Z0-9-_]+$"
+        },
+        "type": {
+          "type": "string",
+          "const": "foreach"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200
+        },
+        "iterator": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^\\$"
+        },
+        "body": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 100,
+          "items": {
+            "$ref": "#/definitions/Step"
+          }
+        },
+        "output": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "ForkJoinStep": {
+      "type": "object",
+      "required": ["id", "type", "branches", "join"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100,
+          "pattern": "^[a-zA-Z0-9-_]+$"
+        },
+        "type": {
+          "type": "string",
+          "const": "fork_join"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200
+        },
+        "branches": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 50,
+          "items": {
+            "$ref": "#/definitions/Step"
+          }
+        },
+        "join": {
+          "type": "object",
+          "required": ["strategy"],
+          "additionalProperties": false,
+          "properties": {
+            "strategy": {
+              "type": "string",
+              "enum": ["merge", "first", "last", "all", "custom"],
+              "description": "How to combine branch results"
+            },
+            "output": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "customHandler": {
+              "type": "string",
+              "description": "Custom handler name when strategy is 'custom'"
+            }
+          }
+        }
+      }
+    },
+    "SwitchStep": {
+      "type": "object",
+      "required": ["id", "type", "expression", "cases", "default"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100,
+          "pattern": "^[a-zA-Z0-9-_]+$"
+        },
+        "type": {
+          "type": "string",
+          "const": "switch"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200
+        },
+        "expression": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^\\$"
+        },
+        "cases": {
+          "type": "object",
+          "minProperties": 1,
+          "maxProperties": 100,
+          "additionalProperties": {
+            "$ref": "#/definitions/Step"
+          }
+        },
+        "default": {
+          "$ref": "#/definitions/Step"
+        },
+        "depends_on": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 100
+          },
+          "maxItems": 100
+        }
+      }
+    },
+    "SubWorkflowStep": {
+      "type": "object",
+      "required": ["id", "type", "steps"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100,
+          "pattern": "^[a-zA-Z0-9-_]+$"
+        },
+        "type": {
+          "type": "string",
+          "const": "sub_workflow"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200
+        },
+        "input": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string",
+            "minLength": 1
+          },
+          "description": "Optional input for sub-workflow"
+        },
+        "steps": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 100,
+          "items": {
+            "$ref": "#/definitions/Step"
+          }
+        }
+      }
+    },
+    "WaitStep": {
+      "type": "object",
+      "required": ["id", "type", "durationMs"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100,
+          "pattern": "^[a-zA-Z0-9-_]+$"
+        },
+        "type": {
+          "type": "string",
+          "const": "wait"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200
+        },
+        "durationMs": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 86400000,
+          "description": "Wait duration in milliseconds (max 24 hours)"
+        }
+      }
+    },
+    "DispatchStep": {
+      "type": "object",
+      "required": ["id", "type", "method", "target"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100,
+          "pattern": "^[a-zA-Z0-9-_]+$"
+        },
+        "type": {
+          "type": "string",
+          "const": "dispatch"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200
+        },
+        "method": {
+          "type": "string",
+          "enum": ["webhook", "http", "grpc", "kafka", "sqs", "custom"],
+          "description": "Dispatch method to use"
+        },
+        "target": {
+          "type": "string",
+          "format": "uri",
+          "maxLength": 2000
+        },
+        "input": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string",
+            "minLength": 1
+          },
+          "description": "Optional dispatch payload"
+        },
+        "headers": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          },
+          "description": "Optional HTTP headers for webhook/http methods"
+        },
+        "retry": {
+          "$ref": "#/definitions/Retry"
+        }
+      }
+    },
+    "Retry": {
+      "type": "object",
+      "required": ["maxAttempts", "delayMs"],
+      "additionalProperties": false,
+      "properties": {
+        "maxAttempts": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 10
+        },
+        "delayMs": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 300000
+        },
+        "backoffMultiplier": {
+          "type": "number",
+          "minimum": 1.0,
+          "maximum": 5.0,
+          "description": "Exponential backoff multiplier"
+        }
+      }
+    }
+  }
+}

package/src/index.js

@@ -0,0 +1,60 @@
+'use strict';
+
+/**
+ * @module @onlineapps/cookbook-core
+ *
+ * Core cookbook parsing and validation library.
+ * Lightweight foundation for workflow definitions - no heavy dependencies.
+ */
+
+const {
+  parseCookbookFromFile,
+  parseCookbookFromFileSync,
+  parseCookbookFromObject
+} = require('./parser');
+
+const {
+  validateCookbook,
+  validateStep,
+  CookbookValidationError
+} = require('./validator');
+
+const {
+  CookbookSchema,
+  loadSchema
+} = require('./schema');
+
+const {
+  validateAllReferences,
+  validateDependsOnReferences,
+  validateVariableReferences,
+  validateErrorHandlerReferences
+} = require('./referenceValidator');
+
+module.exports = {
+  // Parser functions
+  parseCookbookFromFile,
+  parseCookbookFromFileSync,
+  parseCookbookFromObject,
+
+  // Validator functions
+  validateCookbook,
+  validateStep,
+
+  // Reference validation
+  validateAllReferences,
+  validateDependsOnReferences,
+  validateVariableReferences,
+  validateErrorHandlerReferences,
+
+  // Schema access
+  CookbookSchema,
+  loadSchema,
+
+  // Error classes
+  CookbookValidationError,
+
+  // Utility exports
+  VERSION: '1.0.0',
+  SCHEMA_VERSION: '1.0.0'
+};

package/src/parser/cookbookParser.js

@@ -0,0 +1,108 @@
+'use strict';
+
+/**
+ * @fileoverview
+ * Cookbook Parser: loads and parses a JSON cookbook, then validates its structure.
+ * Exposes functions to parse from file or from raw JavaScript object.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { validateCookbook, CookbookValidationError } = require('./cookbookValidator');
+
+/**
+ * Read file contents as UTF-8 string (sync version).
+ * @param {string} filePath - Path to the cookbook JSON file.
+ * @returns {string} Raw file contents.
+ * @throws {Error} If file cannot be read.
+ */
+function _readFileSync(filePath) {
+  const absolutePath = path.resolve(filePath);
+  return fs.readFileSync(absolutePath, 'utf-8');
+}
+
+/**
+ * Read file contents as UTF-8 string (async version).
+ * @param {string} filePath - Path to the cookbook JSON file.
+ * @returns {Promise<string>} Raw file contents.
+ * @throws {Error} If file cannot be read.
+ */
+async function _readFileAsync(filePath) {
+  const absolutePath = path.resolve(filePath);
+  const fsPromises = fs.promises || require('fs').promises;
+  return await fsPromises.readFile(absolutePath, 'utf-8');
+}
+
+/**
+ * Parse a JSON string into an object.
+ * @param {string} jsonString - Raw JSON string.
+ * @param {string} context - Context label for error messages.
+ * @returns {object} Parsed JavaScript object.
+ * @throws {SyntaxError} If JSON is invalid.
+ */
+function _parseJson(jsonString, context) {
+  try {
+    return JSON.parse(jsonString);
+  } catch (err) {
+    const message = `Failed to parse JSON for ${context}: ${err.message}`;
+    const syntaxError = new SyntaxError(message);
+    syntaxError.originalError = err;
+    throw syntaxError;
+  }
+}
+
+/**
+ * Parse and validate a cookbook from a JavaScript object.
+ * @param {object} rawObject - JavaScript object representing the cookbook.
+ * @returns {object} Validated cookbook object (deep-copied).
+ * @throws {CookbookValidationError} If validation fails.
+ */
+function parseCookbookFromObject(rawObject) {
+  // Defensive copy to prevent mutation of original
+  const cookbook = JSON.parse(JSON.stringify(rawObject));
+
+  // Validate structure and nested steps
+  validateCookbook(cookbook);
+
+  return cookbook;
+}
+
+/**
+ * Parse and validate a cookbook from a JSON file (sync version).
+ * @param {string} filePath - Path to the JSON file containing the cookbook.
+ * @returns {object} Validated cookbook object.
+ * @throws {Error|SyntaxError|CookbookValidationError} If file read, parse, or validation fails.
+ */
+function parseCookbookFromFileSync(filePath) {
+  // Read raw contents
+  const raw = _readFileSync(filePath);
+
+  // Parse JSON into object
+  const parsed = _parseJson(raw, `file '${filePath}'`);
+
+  // Validate and return
+  return parseCookbookFromObject(parsed);
+}
+
+/**
+ * Parse and validate a cookbook from a JSON file (async version).
+ * @param {string} filePath - Path to the JSON file containing the cookbook.
+ * @returns {Promise<object>} Validated cookbook object.
+ * @throws {Error|SyntaxError|CookbookValidationError} If file read, parse, or validation fails.
+ */
+async function parseCookbookFromFile(filePath) {
+  // Read raw contents
+  const raw = await _readFileAsync(filePath);
+
+  // Parse JSON into object
+  const parsed = _parseJson(raw, `file '${filePath}'`);
+
+  // Validate and return
+  return parseCookbookFromObject(parsed);
+}
+
+module.exports = {
+  parseCookbookFromFile,
+  parseCookbookFromFileSync,
+  parseCookbookFromObject,
+};