@onlineapps/cookbook-template-helpers

Template helper functions for cookbook variable resolution. Helper functions enable data transformations directly in cookbook template variables.

Installation

npm install @onlineapps/cookbook-template-helpers

Overview

Helper functions can be used in cookbook template variables using the syntax:

{{helper_name(argument)}}

Arguments can be template variables themselves:

{{helper_name(steps.step_id.output.field)}}

Available Helpers

string2file

Converts string content or inline descriptor to file descriptor. Uploads content to MinIO storage.

Signature:

async function string2file(input, context)

Parameters:

• input (string|Object) - String content or inline descriptor
• context (Object) - Workflow context (for storage access)

Returns:

• Promise<Object> - File descriptor

Examples:

{
  "input": {
    "file": "{{string2file(steps.markdown.output.content)}}"
  }
}

{
  "input": {
    "file": "{{string2file('Hello world')}}"
  }
}

file2string

Converts file descriptor to string. Downloads content from MinIO if needed.

Signature:

async function file2string(descriptor, context)

Parameters:

• descriptor (Object|string) - File descriptor or string
• context (Object) - Workflow context (for storage access)

Returns:

• Promise<string> - String content

Examples:

{
  "input": {
    "markdown": "{{file2string(steps.pdf.output.file_descriptor)}}"
  }
}

Usage in Cookbook

Helper functions are integrated into the cookbook executor. They are automatically available when resolving template variables.

Example cookbook:

{
  "version": "2.0.0",
  "steps": [
    {
      "step_id": "get_markdown",
      "type": "task",
      "service": "hello-service",
      "operation": "generate-markdown",
      "input": { "name": "Karel" }
    },
    {
      "step_id": "create_pdf",
      "type": "task",
      "service": "pdfgen-service",
      "operation": "md2pdf",
      "depends_on": ["get_markdown"],
      "input": {
        "markdown": "{{file2string(steps.get_markdown.output.file_descriptor)}}"
      }
    }
  ]
}

Integration

Helper functions are passed to the cookbook executor:

const templateHelpers = require('@onlineapps/cookbook-template-helpers');
const { CookbookExecutor } = require('@onlineapps/cookbook-executor');

const executor = new CookbookExecutor(cookbook, {
  helpers: templateHelpers
});

Adding Custom Helpers

You can combine global helpers with custom helpers:

const templateHelpers = require('@onlineapps/cookbook-template-helpers');
const customHelpers = require('./customHelpers');

const allHelpers = {
  ...templateHelpers,
  ...customHelpers
};

const executor = new CookbookExecutor(cookbook, {
  helpers: allHelpers
});

Helper Function Requirements

• Async: All helpers must be async functions (return Promise)
• Context: Helpers receive workflow context as last parameter
• Idempotent: Same input should produce same output
• Error handling: Should throw descriptive errors

Dependencies

• @onlineapps/content-resolver - Unified access to Content Descriptors (MinIO download/upload)

Environment Variables

Helper functions use the following environment variables for storage access:

• MINIO_HOST - MinIO endpoint (required unless you inject contentResolver)
• MINIO_PORT - MinIO port (required unless you inject contentResolver)
• MINIO_ACCESS_KEY - MinIO access key (required unless you inject contentResolver)
• MINIO_SECRET_KEY - MinIO secret key (required unless you inject contentResolver)

File Descriptor Format

File descriptors have the following structure:

{
  _descriptor: true,
  type: 'file',  // or 'inline'
  storage_ref: 'minio://workflow/path/to/file',  // for type='file'
  content: '...',  // for type='inline'
  filename: 'document.txt',
  content_type: 'text/plain',
  size: 1234,
  fingerprint: 'sha256...'
}

License

PROPRIETARY