Status: current Owns: the helper functions a cookbook template variable may call

Uniform: library/orchestration

Duty sections that apply:

• all: L-MAIN, L-ENGINES, L-TESTS, L-TEST-SCRIPT, L-PACK-TESTS, L-PINS, L-NO-FILE-RANGE, L-CHANGELOG, L-README, L-README-REGION, L-CONSUMER

@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)}}

Available Helpers

normalizeString

Removes nebezpečné / ne-print znaky, ponechá písmena (včetně diakritiky), čísla, mezery a základní interpunkci. Zachová diakritiku a case.

Signature:

function normalizeString(value)

webalizeString

Normalizuje řetězec pro URL/slug: odstraní diakritiku, interpunkci, nahradí mezery pomlčkami, převede na lowercase, zkolabuje vícenásobné pomlčky.

Signature:

function webalizeString(value)

string2file

Převede string nebo inline descriptor na file descriptor (přes ContentResolver). Ukládá do storage podle nastavení ContentResolveru.

Signature:

async function string2file(input, context)

file2string

Převede file/inline descriptor na string (přes ContentResolver). File stáhne z MinIO, inline vrátí přímo.

Signature:

async function file2string(descriptor, context)

Helper context — logger

Oba descriptor helpery si staví ContentResolver, pokud jim v kontextu nepředáš hotový context.contentResolver. V tom případě je context.logger povinný a musí mít všechny čtyři metody: info(), warn(), error(), debug() — přesně to, co vyžaduje @onlineapps/content-resolver a za ním @onlineapps/conn-base-storage. Chybějící logger i logger neúplný padají hned v getContentResolver() a hláška jmenuje chybějící metodu; žádný console fallback neexistuje.

Usage in Cookbook

Helpers jsou k dispozici při resolvování template proměnných:

{
  "input": {
    "title": "{{normalizeString(api_input.title)}}",
    "slug": "{{webalizeString(api_input.title)}}",
    "file": "{{string2file(api_input.content)}}",
    "content": "{{file2string(steps.prepare.output.file_descriptor)}}"
  }
}

Integration

Tenhle balíček se do běhu nezapojuje sám a nikdo ho v běhové cestě nevyžaduje přímo. Cesta je tříčlánková a jde vždy stejně:

1. balíček je závislostí @onlineapps/conn-orch-cookbook, který ho re-exportuje jako plochý klíč templateHelpers (shared/connector/conn-orch-cookbook/src/index.js);
2. ServiceWrapper injektuje celý modul conn-orch-cookbook do orchestrátoru jako config.cookbook (shared/connector/service-wrapper/src/ServiceWrapper.js:1818);
3. WorkflowOrchestrator si helper vyzvedne při rozvíjení {{helper(...)}} ve vstupu kroku:

// shared/connector/conn-orch-orchestrator/src/WorkflowOrchestrator.js:786
const helpers = this.cookbook?.templateHelpers || {};
const helperFn = helpers[helperName];

if (typeof helperFn !== 'function') {
  throw new Error(`[WorkflowOrchestrator] Unknown template helper '${helperName}' - Expected helper to exist in cookbook.templateHelpers`);
}

Žádná volba helpers a žádný override neexistují: platí přesně to, co tenhle balíček exportuje. Neznámý helper je tvrdá chyba, ne prázdná hodnota.

Živý cookbook, který touhle cestou prochází: infra/api_doorman/static/cookbooks/tester-helpers.json — volá normalizeString, webalizeString, string2file i file2string.

Adding a Helper

Nový helper se přidá do tohoto balíčku (a vydá se nová verze) — jinak se k orchestrátoru nedostane, protože ten čte výhradně cookbook.templateHelpers.

Helper Function Requirements

• Deterministic: Stejný vstup = stejný výstup
• Bez vedlejších efektů: String helpery jsou čisté; file helpery používají ContentResolver
• Chyby: Měly by být jasné a srozumitelné

Dependencies

• @onlineapps/content-resolver (pro string2file/file2string)

License

PROPRIETARY