@onlineapps/cookbook-template-helpers 1.0.2 → 1.0.4

package/README.md

@@ -15,104 +15,54 @@ 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.
+### normalizeString
+Removes nebezpečné / ne-print znaky, ponechá písmena (včetně diakritiky), čísla, mezery a základní interpunkci. Zachová diakritiku a case.
 
 **Signature:**
 ```javascript
-async function string2file(input, context)
+function normalizeString(value)
 ```
 
-**Parameters:**
-- `input` (string|Object) - String content or inline descriptor
-- `context` (Object) - Workflow context (for storage access)
+### webalizeString
+Normalizuje řetězec pro URL/slug: odstraní diakritiku, interpunkci, nahradí mezery pomlčkami, převede na lowercase, zkolabuje vícenásobné pomlčky.
 
-**Returns:**
-- `Promise<Object>` - File descriptor
-
-**Examples:**
-
-```json
-{
-  "input": {
-    "file": "{{string2file(steps.markdown.output.content)}}"
-  }
-}
+**Signature:**
+```javascript
+function webalizeString(value)
 ```
 
-```json
-{
-  "input": {
-    "file": "{{string2file('Hello world')}}"
-  }
-}
+### string2file
+Převede string nebo inline descriptor na file descriptor (přes ContentResolver). Ukládá do storage podle nastavení ContentResolveru.
+
+**Signature:**
+```javascript
+async function string2file(input, context)
 ```
 
 ### file2string
-
-Converts file descriptor to string. Downloads content from MinIO if needed.
+Převede file/inline descriptor na string (přes ContentResolver). File stáhne z MinIO, inline vrátí přímo.
 
 **Signature:**
 ```javascript
 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:**
+## Usage in Cookbook
 
+Helpers jsou k dispozici při resolvování template proměnných:
 ```json
 {
   "input": {
-    "markdown": "{{file2string(steps.pdf.output.file_descriptor)}}"
+    "title": "{{normalizeString(api_input.title)}}",
+    "slug": "{{webalizeString(api_input.title)}}",
+    "file": "{{string2file(api_input.content)}}",
+    "content": "{{file2string(steps.prepare.output.file_descriptor)}}"
   }
 }
 ```
 
-## Usage in Cookbook
-
-Helper functions are integrated into the cookbook executor. They are automatically available when resolving template variables.
-
-**Example cookbook:**
-
-```json
-{
-  "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:
@@ -146,40 +96,13 @@ const executor = new CookbookExecutor(cookbook, {
 
 ## 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
+- **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` - 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:
-
-```javascript
-{
-  _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...'
-}
-```
+- `@onlineapps/content-resolver` (pro string2file/file2string)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/cookbook-template-helpers",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Template helper functions for cookbook variable resolution - string2file, file2string, and more",
   "main": "src/index.js",
   "scripts": {

package/src/helpers/fileHelpers.js

@@ -1,22 +1,49 @@
 'use strict';
 
 /**
- * File helper functions for cookbook template resolution
- * Converts between string content and file descriptors
+ * Helper functions for cookbook template resolution.
+ * Includes safe string normalization and descriptor/string conversions.
  */
 
 const ContentResolver = require('@onlineapps/content-resolver');
 
 /**
- * Get ContentResolver instance from helper context.
- * Uses DI if provided; otherwise relies on required MINIO_* env vars enforced by ContentResolver.
+ * Normalize string: remove control/unsafe chars, keep letters (incl. diacritics), numbers,
+ * whitespace and basic punctuation .,!?;:-_
+ * @param {string} value
+ * @returns {string}
+ */
+function normalizeString(value) {
+  if (value === null || value === undefined) return '';
+  const str = String(value);
+  // Allow common Latin ranges (including diacritics), numbers, whitespace and basic punctuation
+  const cleaned = str.replace(/[^\x20-\x7E\u00A0-\u024F\u1E00-\u1EFF\s\.\,\!\?\;\:\-\_]/g, '');
+  // Explicitly drop angle brackets to avoid HTML/script injection noise
+  const noAngles = cleaned.replace(/[<>]/g, '');
+  // Collapse repeated whitespace to a single space and trim edges
+  return noAngles.replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * Webalize string: normalize, strip diacritics, remove punctuation, lowercase, replace spaces with hyphens.
+ * @param {string} value
+ * @returns {string}
+ */
+function webalizeString(value) {
+  const normalized = normalizeString(value);
+  const noPunct = normalized.replace(/[\.\,\!\?\;\:]/g, '');
+  const withoutDiacritics = noPunct.normalize('NFD').replace(/\p{Diacritic}/gu, '');
+  const withHyphens = withoutDiacritics.trim().replace(/\s+/g, '-');
+  return withHyphens.toLowerCase().replace(/-+/g, '-');
+}
+
+/**
+ * Get ContentResolver instance (DI first, else new).
  * @private
- * @param {Object} helperContext - Helper context
- * @returns {ContentResolver}
  */
-function getContentResolverFromContext(helperContext) {
+function getContentResolver(helperContext) {
   if (!helperContext || typeof helperContext !== 'object') {
-    throw new Error('[cookbook-template-helpers] Helper context is required - Expected { data, workflow_id, step_id, contentResolver? }');
+    throw new Error('[cookbook-template-helpers] Helper context is required');
   }
 
   if (
@@ -39,47 +66,33 @@ function getContentResolverFromContext(helperContext) {
     helperContext.data?.step_id ||
     null;
 
-  return new ContentResolver({
-    context: { workflow_id, step_id }
-  });
+  return new ContentResolver({ context: { workflow_id, step_id } });
 }
 
 /**
- * Convert string or inline descriptor to file descriptor
- * Uploads content to MinIO and returns file descriptor
- * 
- * @param {string|Object} input - String content or inline descriptor
- * @param {Object} context - Workflow context (for storage access)
- * @returns {Promise<Object>} File descriptor
- * 
- * @example
- * // String input
- * const descriptor = await string2file('Hello world', context);
- * 
- * @example
- * // Inline descriptor input
- * const descriptor = await string2file({
- *   _descriptor: true,
- *   type: 'inline',
- *   content: 'Hello world',
- *   filename: 'greeting.txt'
- * }, context);
+ * Convert string or inline descriptor to file descriptor (uploads via ContentResolver).
+ * @param {string|Object} input
+ * @param {Object} context
+ * @returns {Promise<Object>}
  */
 async function string2file(input, context) {
-  const resolver = getContentResolverFromContext(context);
+  if (input === null || input === undefined) {
+    throw new Error('[string2file] Input is required');
+  }
 
-  // Pokud už je file descriptor, vrať ho
+  // Already a file descriptor
   if (input && input._descriptor === true && input.type === 'file') {
     return input;
   }
 
-  // Pokud je inline descriptor, převeď na file
+  const resolver = getContentResolver(context);
+
+  // Inline descriptor -> file
   if (input && input._descriptor === true && input.type === 'inline') {
     const content = input.content;
     if (typeof content !== 'string') {
       throw new Error('[string2file] Inline descriptor content must be a string');
     }
-
     return await resolver.createDescriptor(content, {
       filename: input.filename,
       content_type: input.content_type,
@@ -88,7 +101,7 @@ async function string2file(input, context) {
     });
   }
 
-  // Pokud je string, vytvoř file descriptor
+  // Raw string -> file descriptor
   if (typeof input === 'string') {
     return await resolver.createDescriptor(input, {
       filename: 'content.txt',
@@ -98,44 +111,23 @@ async function string2file(input, context) {
     });
   }
 
-  if (input === null || input === undefined) {
-    throw new Error('[string2file] Input is required');
-  }
-
   throw new Error('[string2file] Invalid input - expected string or descriptor');
 }
 
 /**
- * Convert file descriptor to string
- * Downloads content from MinIO if needed
- * 
- * @param {Object|string} descriptor - File descriptor or string
- * @param {Object} context - Workflow context (for storage access)
- * @returns {Promise<string>} String content
- * 
- * @example
- * // File descriptor input
- * const content = await file2string({
- *   _descriptor: true,
- *   type: 'file',
- *   storage_ref: 'minio://workflow/path/to/file',
- *   fingerprint: 'abc123...'
- * }, context);
- * 
- * @example
- * // Inline descriptor input
- * const content = await file2string({
- *   _descriptor: true,
- *   type: 'inline',
- *   content: 'Hello world'
- * }, context);
+ * Convert file descriptor to string (downloads via ContentResolver).
+ * @param {Object|string} descriptor
+ * @param {Object} context
+ * @returns {Promise<string>}
  */
 async function file2string(descriptor, context) {
-  const resolver = getContentResolverFromContext(context);
+  const resolver = getContentResolver(context);
   return await resolver.getAsString(descriptor);
 }
 
 module.exports = {
+  normalizeString,
+  webalizeString,
   string2file,
   file2string
 };

package/src/index.js

@@ -15,6 +15,8 @@
 const fileHelpers = require('./helpers/fileHelpers');
 
 module.exports = {
+  normalizeString: fileHelpers.normalizeString,
+  webalizeString: fileHelpers.webalizeString,
   string2file: fileHelpers.string2file,
   file2string: fileHelpers.file2string
 };