@promptbook/utils 0.92.0-8 → 0.92.0

package/esm/index.es.js

@@ -16,7 +16,7 @@ const BOOK_LANGUAGE_VERSION = '1.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.92.0-8';
+const PROMPTBOOK_ENGINE_VERSION = '0.92.0';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -72,7 +72,7 @@ const VALUE_STRINGS = {
 const SMALL_NUMBER = 0.001;
 // <- TODO: [🧜‍♂️]
 /**
- * @@@
+ * Default settings for parsing and generating CSV files in Promptbook.
  *
  * @public exported from `@promptbook/core`
  */
@@ -87,6 +87,48 @@ Object.freeze({
  * TODO: [🧠][🧜‍♂️] Maybe join remoteServerUrl and path into single value
  */
 
+/**
+ * Orders JSON object by keys
+ *
+ * @returns The same type of object as the input re-ordered
+ * @public exported from `@promptbook/utils`
+ */
+function orderJson(options) {
+    const { value, order } = options;
+    const orderedValue = {
+        ...(order === undefined ? {} : Object.fromEntries(order.map((key) => [key, undefined]))),
+        ...value,
+    };
+    return orderedValue;
+}
+
+/**
+ * Freezes the given object and all its nested objects recursively
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it mutates given object
+ * Note: This function mutates the object and returns the original (but mutated-deep-freezed) object
+ *
+ * @returns The same object as the input, but deeply frozen
+ * @public exported from `@promptbook/utils`
+ */
+function $deepFreeze(objectValue) {
+    if (Array.isArray(objectValue)) {
+        return Object.freeze(objectValue.map((item) => $deepFreeze(item)));
+    }
+    const propertyNames = Object.getOwnPropertyNames(objectValue);
+    for (const propertyName of propertyNames) {
+        const value = objectValue[propertyName];
+        if (value && typeof value === 'object') {
+            $deepFreeze(value);
+        }
+    }
+    Object.freeze(objectValue);
+    return objectValue;
+}
+/**
+ * TODO: [🧠] Is there a way how to meaningfully test this utility
+ */
+
 /**
  * Make error report URL for the given error
  *
@@ -142,7 +184,7 @@ class UnexpectedError extends Error {
                     ${block(message)}
 
                     Note: This error should not happen.
-                    It's probbably a bug in the pipeline collection
+                    It's probably a bug in the pipeline collection
 
                     Please report issue:
                     ${block(getErrorReportUrl(new Error(message)).href)}
@@ -156,158 +198,447 @@ class UnexpectedError extends Error {
 }
 
 /**
- * @@@
+ * This error type indicates that somewhere in the code non-Error object was thrown and it was wrapped into the `WrappedError`
  *
- * @param text @@@
- * @param _isFirstLetterCapital @@@
- * @returns @@@
- * @example 'helloWorld'
- * @example 'iLovePromptbook'
- * @public exported from `@promptbook/utils`
+ * @public exported from `@promptbook/core`
  */
-function normalizeTo_camelCase(text, _isFirstLetterCapital = false) {
-    let charType;
-    let lastCharType = null;
-    let normalizedName = '';
-    for (const char of text) {
-        let normalizedChar;
-        if (/^[a-z]$/.test(char)) {
-            charType = 'LOWERCASE';
-            normalizedChar = char;
-        }
-        else if (/^[A-Z]$/.test(char)) {
-            charType = 'UPPERCASE';
-            normalizedChar = char.toLowerCase();
-        }
-        else if (/^[0-9]$/.test(char)) {
-            charType = 'NUMBER';
-            normalizedChar = char;
-        }
-        else {
-            charType = 'OTHER';
-            normalizedChar = '';
-        }
-        if (!lastCharType) {
-            if (_isFirstLetterCapital) {
-                normalizedChar = normalizedChar.toUpperCase(); //TODO: DRY
-            }
-        }
-        else if (charType !== lastCharType &&
-            !(charType === 'LOWERCASE' && lastCharType === 'UPPERCASE') &&
-            !(lastCharType === 'NUMBER') &&
-            !(charType === 'NUMBER')) {
-            normalizedChar = normalizedChar.toUpperCase(); //TODO: [🌺] DRY
-        }
-        normalizedName += normalizedChar;
-        lastCharType = charType;
+class WrappedError extends Error {
+    constructor(whatWasThrown) {
+        const tag = `[🤮]`;
+        console.error(tag, whatWasThrown);
+        super(spaceTrim$2(`
+                Non-Error object was thrown
+
+                Note: Look for ${tag} in the console for more details
+                Please report issue on ${ADMIN_EMAIL}
+            `));
+        this.name = 'WrappedError';
+        Object.setPrototypeOf(this, WrappedError.prototype);
     }
-    return normalizedName;
 }
-/**
- * TODO: [🌺] Use some intermediate util splitWords
- */
 
 /**
- * Removes emojis from a string and fix whitespaces
+ * Helper used in catch blocks to assert that the error is an instance of `Error`
  *
- * @param text with emojis
- * @returns text without emojis
- * @public exported from `@promptbook/utils`
+ * @param whatWasThrown Any object that was thrown
+ * @returns Nothing if the error is an instance of `Error`
+ * @throws `WrappedError` or `UnexpectedError` if the error is not standard
+ *
+ * @private within the repository
  */
-function removeEmojis(text) {
-    // Replace emojis (and also ZWJ sequence) with hyphens
-    text = text.replace(/(\p{Extended_Pictographic})\p{Modifier_Symbol}/gu, '$1');
-    text = text.replace(/(\p{Extended_Pictographic})[\u{FE00}-\u{FE0F}]/gu, '$1');
-    text = text.replace(/(\p{Extended_Pictographic})(\u{200D}\p{Extended_Pictographic})*/gu, '$1');
-    text = text.replace(/\p{Extended_Pictographic}/gu, '');
-    return text;
+function assertsError(whatWasThrown) {
+    // Case 1: Handle error which was rethrown as `WrappedError`
+    if (whatWasThrown instanceof WrappedError) {
+        const wrappedError = whatWasThrown;
+        throw wrappedError;
+    }
+    // Case 2: Handle unexpected errors
+    if (whatWasThrown instanceof UnexpectedError) {
+        const unexpectedError = whatWasThrown;
+        throw unexpectedError;
+    }
+    // Case 3: Handle standard errors - keep them up to consumer
+    if (whatWasThrown instanceof Error) {
+        return;
+    }
+    // Case 4: Handle non-standard errors - wrap them into `WrappedError` and throw
+    throw new WrappedError(whatWasThrown);
 }
 
 /**
- * Tests if given string is valid URL.
+ * Checks if the value is [🚉] serializable as JSON
+ * If not, throws an UnexpectedError with a rich error message and tracking
  *
- * Note: This does not check if the file exists only if the path is valid
+ * - Almost all primitives are serializable BUT:
+ * - `undefined` is not serializable
+ * - `NaN` is not serializable
+ * - Objects and arrays are serializable if all their properties are serializable
+ * - Functions are not serializable
+ * - Circular references are not serializable
+ * - `Date` objects are not serializable
+ * - `Map` and `Set` objects are not serializable
+ * - `RegExp` objects are not serializable
+ * - `Error` objects are not serializable
+ * - `Symbol` objects are not serializable
+ * - And much more...
+ *
+ * @throws UnexpectedError if the value is not serializable as JSON
  * @public exported from `@promptbook/utils`
  */
-function isValidFilePath(filename) {
-    if (typeof filename !== 'string') {
-        return false;
+function checkSerializableAsJson(options) {
+    const { value, name, message } = options;
+    if (value === undefined) {
+        throw new UnexpectedError(`${name} is undefined`);
     }
-    if (filename.split('\n').length > 1) {
-        return false;
+    else if (value === null) {
+        return;
     }
-    if (filename.split(' ').length >
-        5 /* <- TODO: [🧠][🈷] Make some better non-arbitrary way how to distinct filenames from informational texts */) {
-        return false;
+    else if (typeof value === 'boolean') {
+        return;
     }
-    const filenameSlashes = filename.split('\\').join('/');
-    // Absolute Unix path: /hello.txt
-    if (/^(\/)/i.test(filenameSlashes)) {
-        // console.log(filename, 'Absolute Unix path: /hello.txt');
-        return true;
+    else if (typeof value === 'number' && !isNaN(value)) {
+        return;
     }
-    // Absolute Windows path: /hello.txt
-    if (/^([A-Z]{1,2}:\/?)\//i.test(filenameSlashes)) {
-        // console.log(filename, 'Absolute Windows path: /hello.txt');
-        return true;
+    else if (typeof value === 'string') {
+        return;
     }
-    // Relative path: ./hello.txt
-    if (/^(\.\.?\/)+/i.test(filenameSlashes)) {
-        // console.log(filename, 'Relative path: ./hello.txt');
-        return true;
+    else if (typeof value === 'symbol') {
+        throw new UnexpectedError(`${name} is symbol`);
     }
-    // Allow paths like foo/hello
-    if (/^[^/]+\/[^/]+/i.test(filenameSlashes)) {
-        // console.log(filename, 'Allow paths like foo/hello');
-        return true;
+    else if (typeof value === 'function') {
+        throw new UnexpectedError(`${name} is function`);
     }
-    // Allow paths like hello.book
-    if (/^[^/]+\.[^/]+$/i.test(filenameSlashes)) {
-        // console.log(filename, 'Allow paths like hello.book');
-        return true;
+    else if (typeof value === 'object' && Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+            checkSerializableAsJson({ name: `${name}[${i}]`, value: value[i], message });
+        }
     }
-    return false;
-}
-/**
- * TODO: [🍏] Implement for MacOs
- */
+    else if (typeof value === 'object') {
+        if (value instanceof Date) {
+            throw new UnexpectedError(spaceTrim$1((block) => `
+                        \`${name}\` is Date
 
-/**
- * Tests if given string is valid URL.
- *
- * Note: Dataurl are considered perfectly valid.
- * Note: There are two simmilar functions:
- * - `isValidUrl` which tests any URL
- * - `isValidPipelineUrl` *(this one)* which tests just promptbook URL
- *
- * @public exported from `@promptbook/utils`
- */
-function isValidUrl(url) {
-    if (typeof url !== 'string') {
-        return false;
-    }
-    try {
-        if (url.startsWith('blob:')) {
-            url = url.replace(/^blob:/, '');
+                        Use \`string_date_iso8601\` instead
+
+                        Additional message for \`${name}\`:
+                        ${block(message || '(nothing)')}
+                    `));
         }
-        const urlObject = new URL(url /* because fail is handled */);
-        if (!['http:', 'https:', 'data:'].includes(urlObject.protocol)) {
-            return false;
+        else if (value instanceof Map) {
+            throw new UnexpectedError(`${name} is Map`);
         }
-        return true;
-    }
-    catch (error) {
-        return false;
-    }
-}
+        else if (value instanceof Set) {
+            throw new UnexpectedError(`${name} is Set`);
+        }
+        else if (value instanceof RegExp) {
+            throw new UnexpectedError(`${name} is RegExp`);
+        }
+        else if (value instanceof Error) {
+            throw new UnexpectedError(spaceTrim$1((block) => `
+                        \`${name}\` is unserialized Error
 
-const defaultDiacriticsRemovalMap = [
-    {
-        base: 'A',
-        letters: '\u0041\u24B6\uFF21\u00C0\u00C1\u00C2\u1EA6\u1EA4\u1EAA\u1EA8\u00C3\u0100\u0102\u1EB0\u1EAE\u1EB4\u1EB2\u0226\u01E0\u00C4\u01DE\u1EA2\u00C5\u01FA\u01CD\u0200\u0202\u1EA0\u1EAC\u1EB6\u1E00\u0104\u023A\u2C6F',
-    },
-    { base: 'AA', letters: '\uA732' },
-    { base: 'AE', letters: '\u00C6\u01FC\u01E2' },
+                        Use function \`serializeError\`
+
+                        Additional message for \`${name}\`:
+                        ${block(message || '(nothing)')}
+
+                    `));
+        }
+        else {
+            for (const [subName, subValue] of Object.entries(value)) {
+                if (subValue === undefined) {
+                    // Note: undefined in object is serializable - it is just omited
+                    continue;
+                }
+                checkSerializableAsJson({ name: `${name}.${subName}`, value: subValue, message });
+            }
+            try {
+                JSON.stringify(value); // <- TODO: [0]
+            }
+            catch (error) {
+                assertsError(error);
+                throw new UnexpectedError(spaceTrim$1((block) => `
+                            \`${name}\` is not serializable
+
+                            ${block(error.stack || error.message)}
+
+                            Additional message for \`${name}\`:
+                            ${block(message || '(nothing)')}
+                        `));
+            }
+            /*
+            TODO: [0] Is there some more elegant way to check circular references?
+            const seen = new Set();
+            const stack = [{ value }];
+            while (stack.length > 0) {
+                const { value } = stack.pop()!;
+                if (typeof value === 'object' && value !== null) {
+                    if (seen.has(value)) {
+                        throw new UnexpectedError(`${name} has circular reference`);
+                    }
+                    seen.add(value);
+                    if (Array.isArray(value)) {
+                        stack.push(...value.map((value) => ({ value })));
+                    } else {
+                        stack.push(...Object.values(value).map((value) => ({ value })));
+                    }
+                }
+            }
+            */
+            return;
+        }
+    }
+    else {
+        throw new UnexpectedError(spaceTrim$1((block) => `
+                    \`${name}\` is unknown type
+
+                    Additional message for \`${name}\`:
+                    ${block(message || '(nothing)')}
+                `));
+    }
+}
+/**
+ * TODO: Can be return type more type-safe? like `asserts options.value is JsonValue`
+ * TODO: [🧠][main] !!3 In-memory cache of same values to prevent multiple checks
+ * Note: [🐠] This is how `checkSerializableAsJson` + `isSerializableAsJson` together can just retun true/false or rich error message
+ */
+
+/**
+ * Creates a deep clone of the given object
+ *
+ * Note: This method only works for objects that are fully serializable to JSON and do not contain functions, Dates, or special types.
+ *
+ * @param objectValue The object to clone.
+ * @returns A deep, writable clone of the input object.
+ * @public exported from `@promptbook/utils`
+ */
+function deepClone(objectValue) {
+    return JSON.parse(JSON.stringify(objectValue));
+    /*
+    TODO: [🧠] Is there a better implementation?
+    > const propertyNames = Object.getOwnPropertyNames(objectValue);
+    > for (const propertyName of propertyNames) {
+    >     const value = (objectValue as really_any)[propertyName];
+    >     if (value && typeof value === 'object') {
+    >         deepClone(value);
+    >     }
+    > }
+    > return Object.assign({}, objectValue);
+    */
+}
+/**
+ * TODO: [🧠] Is there a way how to meaningfully test this utility
+ */
+
+/**
+ * Utility to export a JSON object from a function
+ *
+ * 1) Checks if the value is serializable as JSON
+ * 2) Makes a deep clone of the object
+ * 2) Orders the object properties
+ * 2) Deeply freezes the cloned object
+ *
+ * Note: This function does not mutates the given object
+ *
+ * @returns The same type of object as the input but read-only and re-ordered
+ * @public exported from `@promptbook/utils`
+ */
+function exportJson(options) {
+    const { name, value, order, message } = options;
+    checkSerializableAsJson({ name, value, message });
+    const orderedValue = 
+    // TODO: Fix error "Type instantiation is excessively deep and possibly infinite."
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
+    order === undefined
+        ? deepClone(value)
+        : orderJson({
+            value: value,
+            // <- Note: checkSerializableAsJson asserts that the value is serializable as JSON
+            order: order,
+        });
+    $deepFreeze(orderedValue);
+    return orderedValue;
+}
+/**
+ * TODO: [🧠] Is there a way how to meaningfully test this utility
+ */
+
+/**
+ * Nonce which is used for replacing things in strings
+ *
+ * @private within the repository
+ */
+const REPLACING_NONCE = 'ptbkauk42kV2dzao34faw7FudQUHYPtW';
+/**
+ * Placeholder value indicating a parameter is missing its value.
+ *
+ * @private within the repository
+ */
+const RESERVED_PARAMETER_MISSING_VALUE = 'MISSING-' + REPLACING_NONCE;
+/**
+ * Placeholder value indicating a parameter is restricted and cannot be used directly.
+ *
+ * @private within the repository
+ */
+const RESERVED_PARAMETER_RESTRICTED = 'RESTRICTED-' + REPLACING_NONCE;
+/**
+ * The names of the parameters that are reserved for special purposes
+ *
+ * @public exported from `@promptbook/core`
+ */
+const RESERVED_PARAMETER_NAMES = exportJson({
+    name: 'RESERVED_PARAMETER_NAMES',
+    message: `The names of the parameters that are reserved for special purposes`,
+    value: [
+        'content',
+        'context',
+        'knowledge',
+        'examples',
+        'modelName',
+        'currentDate',
+        // <- TODO: list here all command names
+        // <- TODO: Add more like 'date', 'modelName',...
+        // <- TODO: Add [emoji] + instructions ACRY when adding new reserved parameter
+    ],
+});
+/**
+ * Note: [💞] Ignore a discrepancy between file name and entity name
+ */
+
+/**
+ * Normalizes a given text to camelCase format.
+ *
+ * @param text The text to be normalized.
+ * @param _isFirstLetterCapital Whether the first letter should be capitalized.
+ * @returns The camelCase formatted string.
+ * @example 'helloWorld'
+ * @example 'iLovePromptbook'
+ * @public exported from `@promptbook/utils`
+ */
+function normalizeTo_camelCase(text, _isFirstLetterCapital = false) {
+    let charType;
+    let lastCharType = null;
+    let normalizedName = '';
+    for (const char of text) {
+        let normalizedChar;
+        if (/^[a-z]$/.test(char)) {
+            charType = 'LOWERCASE';
+            normalizedChar = char;
+        }
+        else if (/^[A-Z]$/.test(char)) {
+            charType = 'UPPERCASE';
+            normalizedChar = char.toLowerCase();
+        }
+        else if (/^[0-9]$/.test(char)) {
+            charType = 'NUMBER';
+            normalizedChar = char;
+        }
+        else {
+            charType = 'OTHER';
+            normalizedChar = '';
+        }
+        if (!lastCharType) {
+            if (_isFirstLetterCapital) {
+                normalizedChar = normalizedChar.toUpperCase(); //TODO: DRY
+            }
+        }
+        else if (charType !== lastCharType &&
+            !(charType === 'LOWERCASE' && lastCharType === 'UPPERCASE') &&
+            !(lastCharType === 'NUMBER') &&
+            !(charType === 'NUMBER')) {
+            normalizedChar = normalizedChar.toUpperCase(); //TODO: [🌺] DRY
+        }
+        normalizedName += normalizedChar;
+        lastCharType = charType;
+    }
+    return normalizedName;
+}
+/**
+ * TODO: [🌺] Use some intermediate util splitWords
+ */
+
+/**
+ * Removes emojis from a string and fix whitespaces
+ *
+ * @param text with emojis
+ * @returns text without emojis
+ * @public exported from `@promptbook/utils`
+ */
+function removeEmojis(text) {
+    // Replace emojis (and also ZWJ sequence) with hyphens
+    text = text.replace(/(\p{Extended_Pictographic})\p{Modifier_Symbol}/gu, '$1');
+    text = text.replace(/(\p{Extended_Pictographic})[\u{FE00}-\u{FE0F}]/gu, '$1');
+    text = text.replace(/(\p{Extended_Pictographic})(\u{200D}\p{Extended_Pictographic})*/gu, '$1');
+    text = text.replace(/\p{Extended_Pictographic}/gu, '');
+    return text;
+}
+
+/**
+ * Tests if given string is valid URL.
+ *
+ * Note: This does not check if the file exists only if the path is valid
+ * @public exported from `@promptbook/utils`
+ */
+function isValidFilePath(filename) {
+    if (typeof filename !== 'string') {
+        return false;
+    }
+    if (filename.split('\n').length > 1) {
+        return false;
+    }
+    if (filename.split(' ').length >
+        5 /* <- TODO: [🧠][🈷] Make some better non-arbitrary way how to distinct filenames from informational texts */) {
+        return false;
+    }
+    const filenameSlashes = filename.split('\\').join('/');
+    // Absolute Unix path: /hello.txt
+    if (/^(\/)/i.test(filenameSlashes)) {
+        // console.log(filename, 'Absolute Unix path: /hello.txt');
+        return true;
+    }
+    // Absolute Windows path: /hello.txt
+    if (/^([A-Z]{1,2}:\/?)\//i.test(filenameSlashes)) {
+        // console.log(filename, 'Absolute Windows path: /hello.txt');
+        return true;
+    }
+    // Relative path: ./hello.txt
+    if (/^(\.\.?\/)+/i.test(filenameSlashes)) {
+        // console.log(filename, 'Relative path: ./hello.txt');
+        return true;
+    }
+    // Allow paths like foo/hello
+    if (/^[^/]+\/[^/]+/i.test(filenameSlashes)) {
+        // console.log(filename, 'Allow paths like foo/hello');
+        return true;
+    }
+    // Allow paths like hello.book
+    if (/^[^/]+\.[^/]+$/i.test(filenameSlashes)) {
+        // console.log(filename, 'Allow paths like hello.book');
+        return true;
+    }
+    return false;
+}
+/**
+ * TODO: [🍏] Implement for MacOs
+ */
+
+/**
+ * Tests if given string is valid URL.
+ *
+ * Note: Dataurl are considered perfectly valid.
+ * Note: There are two similar functions:
+ * - `isValidUrl` which tests any URL
+ * - `isValidPipelineUrl` *(this one)* which tests just promptbook URL
+ *
+ * @public exported from `@promptbook/utils`
+ */
+function isValidUrl(url) {
+    if (typeof url !== 'string') {
+        return false;
+    }
+    try {
+        if (url.startsWith('blob:')) {
+            url = url.replace(/^blob:/, '');
+        }
+        const urlObject = new URL(url /* because fail is handled */);
+        if (!['http:', 'https:', 'data:'].includes(urlObject.protocol)) {
+            return false;
+        }
+        return true;
+    }
+    catch (error) {
+        return false;
+    }
+}
+
+const defaultDiacriticsRemovalMap = [
+    {
+        base: 'A',
+        letters: '\u0041\u24B6\uFF21\u00C0\u00C1\u00C2\u1EA6\u1EA4\u1EAA\u1EA8\u00C3\u0100\u0102\u1EB0\u1EAE\u1EB4\u1EB2\u0226\u01E0\u00C4\u01DE\u1EA2\u00C5\u01FA\u01CD\u0200\u0202\u1EA0\u1EAC\u1EB6\u1E00\u0104\u023A\u2C6F',
+    },
+    { base: 'AA', letters: '\uA732' },
+    { base: 'AE', letters: '\u00C6\u01FC\u01E2' },
     { base: 'AO', letters: '\uA734' },
     { base: 'AU', letters: '\uA736' },
     { base: 'AV', letters: '\uA738\uA73A' },
@@ -546,10 +877,10 @@ for (let i = 0; i < defaultDiacriticsRemovalMap.length; i++) {
 */
 
 /**
- * @@@
+ * Removes diacritic marks (accents) from characters in a string.
  *
- * @param input @@@
- * @returns @@@
+ * @param input The string containing diacritics to be normalized.
+ * @returns The string with diacritics removed or normalized.
  * @public exported from `@promptbook/utils`
  */
 function removeDiacritics(input) {
@@ -563,10 +894,10 @@ function removeDiacritics(input) {
  */
 
 /**
- * @@@
+ * Converts a given text to kebab-case format.
  *
- * @param text @@@
- * @returns @@@
+ * @param text The text to be converted.
+ * @returns The kebab-case formatted string.
  * @example 'hello-world'
  * @example 'i-love-promptbook'
  * @public exported from `@promptbook/utils`
@@ -614,11 +945,11 @@ function normalizeToKebabCase(text) {
  */
 
 /**
- * @@@
+ * Converts a title string into a normalized name.
  *
- * @param value @@@
- * @returns @@@
- * @example @@@
+ * @param value The title string to be converted to a name.
+ * @returns A normalized name derived from the input title.
+ * @example 'Hello World!' -> 'hello-world'
  * @public exported from `@promptbook/utils`
  */
 function titleToName(value) {
@@ -646,45 +977,43 @@ function titleToName(value) {
  */
 function renderPromptbookMermaid(pipelineJson, options) {
     const { linkTask = () => null } = options || {};
+    const MERMAID_PREFIX = 'pipeline_';
+    const MERMAID_KNOWLEDGE_NAME = MERMAID_PREFIX + 'knowledge';
+    const MERMAID_RESERVED_NAME = MERMAID_PREFIX + 'reserved';
+    const MERMAID_INPUT_NAME = MERMAID_PREFIX + 'input';
+    const MERMAID_OUTPUT_NAME = MERMAID_PREFIX + 'output';
     const parameterNameToTaskName = (parameterName) => {
+        if (parameterName === 'knowledge') {
+            return MERMAID_KNOWLEDGE_NAME;
+        }
+        else if (RESERVED_PARAMETER_NAMES.includes(parameterName)) {
+            return MERMAID_RESERVED_NAME;
+        }
         const parameter = pipelineJson.parameters.find((parameter) => parameter.name === parameterName);
         if (!parameter) {
             throw new UnexpectedError(`Could not find {${parameterName}}`);
-            // <- TODO: !!6 This causes problems when {knowledge} and other reserved parameters are used
+            // <- TODO: This causes problems when {knowledge} and other reserved parameters are used
         }
         if (parameter.isInput) {
-            return 'input';
+            return MERMAID_INPUT_NAME;
         }
         const task = pipelineJson.tasks.find((task) => task.resultingParameterName === parameterName);
         if (!task) {
             throw new Error(`Could not find task for {${parameterName}}`);
         }
-        return task.name || normalizeTo_camelCase('task-' + titleToName(task.title));
+        return MERMAID_PREFIX + (task.name || normalizeTo_camelCase('task-' + titleToName(task.title)));
     };
-    const promptbookMermaid = spaceTrim$2((block) => `
-
-            %% 🔮 Tip: Open this on GitHub or in the VSCode website to see the Mermaid graph visually
-
-            flowchart LR
-              subgraph "${pipelineJson.title}"
-
-                  direction TB
-
-                  input((Input)):::input
-                  ${block(pipelineJson.tasks
+    const inputAndIntermediateParametersMermaid = pipelineJson.tasks
         .flatMap(({ title, dependentParameterNames, resultingParameterName }) => [
         `${parameterNameToTaskName(resultingParameterName)}("${title}")`,
         ...dependentParameterNames.map((dependentParameterName) => `${parameterNameToTaskName(dependentParameterName)}--"{${dependentParameterName}}"-->${parameterNameToTaskName(resultingParameterName)}`),
     ])
-        .join('\n'))}
-
-                  ${block(pipelineJson.parameters
+        .join('\n');
+    const outputParametersMermaid = pipelineJson.parameters
         .filter(({ isOutput }) => isOutput)
-        .map(({ name }) => `${parameterNameToTaskName(name)}--"{${name}}"-->output`)
-        .join('\n'))}
-                  output((Output)):::output
-
-                  ${block(pipelineJson.tasks
+        .map(({ name }) => `${parameterNameToTaskName(name)}--"{${name}}"-->${MERMAID_OUTPUT_NAME}`)
+        .join('\n');
+    const linksMermaid = pipelineJson.tasks
         .map((task) => {
         const link = linkTask(task);
         if (link === null) {
@@ -695,10 +1024,44 @@ function renderPromptbookMermaid(pipelineJson, options) {
         return `click ${taskName} href "${href}" "${title}";`;
     })
         .filter((line) => line !== '')
-        .join('\n'))}
+        .join('\n');
+    const interactionPointsMermaid = Object.entries({
+        [MERMAID_INPUT_NAME]: 'Input',
+        [MERMAID_OUTPUT_NAME]: 'Output',
+        [MERMAID_RESERVED_NAME]: 'Other',
+        [MERMAID_KNOWLEDGE_NAME]: 'Knowledge',
+    })
+        .filter(([MERMAID_NAME]) => (inputAndIntermediateParametersMermaid + outputParametersMermaid).includes(MERMAID_NAME))
+        .map(([MERMAID_NAME, title]) => `${MERMAID_NAME}((${title})):::${MERMAID_NAME}`)
+        .join('\n');
+    const promptbookMermaid = spaceTrim$2((block) => `
+
+            %% 🔮 Tip: Open this on GitHub or in the VSCode website to see the Mermaid graph visually
+
+            flowchart LR
+              subgraph "${pipelineJson.title}"
+
+                  %% Basic configuration
+                  direction TB
+
+                  %% Interaction points from pipeline to outside
+                  ${block(interactionPointsMermaid)}
+
+                  %% Input and intermediate parameters
+                  ${block(inputAndIntermediateParametersMermaid)}
 
-                  classDef input color: grey;
-                  classDef output color: grey;
+
+                  %% Output parameters
+                  ${block(outputParametersMermaid)}
+
+                  %% Links
+                  ${block(linksMermaid)}
+
+                  %% Styles
+                  classDef ${MERMAID_INPUT_NAME} color: grey;
+                  classDef ${MERMAID_OUTPUT_NAME} color: grey;
+                  classDef ${MERMAID_RESERVED_NAME} color: grey;
+                  classDef ${MERMAID_KNOWLEDGE_NAME} color: grey;
 
               end;
 
@@ -757,7 +1120,7 @@ class AuthenticationError extends Error {
 }
 
 /**
- * This error indicates that the pipeline collection cannot be propperly loaded
+ * This error indicates that the pipeline collection cannot be properly loaded
  *
  * @public exported from `@promptbook/core`
  */
@@ -778,774 +1141,444 @@ class EnvironmentMismatchError extends Error {
     constructor(message) {
         super(message);
         this.name = 'EnvironmentMismatchError';
-        Object.setPrototypeOf(this, EnvironmentMismatchError.prototype);
-    }
-}
-
-/**
- * This error occurs when some expectation is not met in the execution of the pipeline
- *
- * @public exported from `@promptbook/core`
- * Note: Do not throw this error, its reserved for `checkExpectations` and `createPipelineExecutor` and public ONLY to be serializable through remote server
- * Note: Always thrown in `checkExpectations` and catched in `createPipelineExecutor` and rethrown as `PipelineExecutionError`
- * Note: This is a kindof subtype of PipelineExecutionError
- */
-class ExpectError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'ExpectError';
-        Object.setPrototypeOf(this, ExpectError.prototype);
-    }
-}
-
-/**
- * This error indicates that the promptbook can not retrieve knowledge from external sources
- *
- * @public exported from `@promptbook/core`
- */
-class KnowledgeScrapeError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'KnowledgeScrapeError';
-        Object.setPrototypeOf(this, KnowledgeScrapeError.prototype);
-    }
-}
-
-/**
- * This error type indicates that some limit was reached
- *
- * @public exported from `@promptbook/core`
- */
-class LimitReachedError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'LimitReachedError';
-        Object.setPrototypeOf(this, LimitReachedError.prototype);
-    }
-}
-
-/**
- * This error type indicates that some tools are missing for pipeline execution or preparation
- *
- * @public exported from `@promptbook/core`
- */
-class MissingToolsError extends Error {
-    constructor(message) {
-        super(spaceTrim$2((block) => `
-                    ${block(message)}
-
-                    Note: You have probbably forgot to provide some tools for pipeline execution or preparation
-
-                `));
-        this.name = 'MissingToolsError';
-        Object.setPrototypeOf(this, MissingToolsError.prototype);
-    }
-}
-
-/**
- * This error indicates that promptbook not found in the collection
- *
- * @public exported from `@promptbook/core`
- */
-class NotFoundError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'NotFoundError';
-        Object.setPrototypeOf(this, NotFoundError.prototype);
-    }
-}
-
-/**
- * This error type indicates that some part of the code is not implemented yet
- *
- * @public exported from `@promptbook/core`
- */
-class NotYetImplementedError extends Error {
-    constructor(message) {
-        super(spaceTrim$2((block) => `
-                    ${block(message)}
-
-                    Note: This feature is not implemented yet but it will be soon.
-
-                    If you want speed up the implementation or just read more, look here:
-                    https://github.com/webgptorg/promptbook
-
-                    Or contact us on pavol@ptbk.io
-
-                `));
-        this.name = 'NotYetImplementedError';
-        Object.setPrototypeOf(this, NotYetImplementedError.prototype);
-    }
-}
-
-/**
- * This error indicates that the promptbook in a markdown format cannot be parsed into a valid promptbook object
- *
- * @public exported from `@promptbook/core`
- */
-class ParseError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'ParseError';
-        Object.setPrototypeOf(this, ParseError.prototype);
-    }
-}
-/**
- * TODO: Maybe split `ParseError` and `ApplyError`
- */
-
-/**
- * Generates random token
- *
- * Note: This function is cryptographically secure (it uses crypto.randomBytes internally)
- *
- * @private internal helper function
- * @returns secure random token
- */
-function $randomToken(randomness) {
-    return randomBytes(randomness).toString('hex');
-}
-/**
- * TODO: Maybe use nanoid instead https://github.com/ai/nanoid
- */
-
-/**
- * This error indicates errors during the execution of the pipeline
- *
- * @public exported from `@promptbook/core`
- */
-class PipelineExecutionError extends Error {
-    constructor(message) {
-        // Added id parameter
-        super(message);
-        this.name = 'PipelineExecutionError';
-        // TODO: [🐙] DRY - Maybe $randomId
-        this.id = `error-${$randomToken(8 /* <- TODO: To global config + Use Base58 to avoid simmilar char conflicts   */)}`;
-        Object.setPrototypeOf(this, PipelineExecutionError.prototype);
+        Object.setPrototypeOf(this, EnvironmentMismatchError.prototype);
     }
 }
-/**
- * TODO: [🧠][🌂] Add id to all errors
- */
 
 /**
- * This error indicates that the promptbook object has valid syntax (=can be parsed) but contains logical errors (like circular dependencies)
+ * This error occurs when some expectation is not met in the execution of the pipeline
  *
  * @public exported from `@promptbook/core`
+ * Note: Do not throw this error, its reserved for `checkExpectations` and `createPipelineExecutor` and public ONLY to be serializable through remote server
+ * Note: Always thrown in `checkExpectations` and catched in `createPipelineExecutor` and rethrown as `PipelineExecutionError`
+ * Note: This is a kindof subtype of PipelineExecutionError
  */
-class PipelineLogicError extends Error {
+class ExpectError extends Error {
     constructor(message) {
         super(message);
-        this.name = 'PipelineLogicError';
-        Object.setPrototypeOf(this, PipelineLogicError.prototype);
+        this.name = 'ExpectError';
+        Object.setPrototypeOf(this, ExpectError.prototype);
     }
 }
 
 /**
- * This error indicates errors in referencing promptbooks between each other
+ * This error indicates that the promptbook can not retrieve knowledge from external sources
  *
  * @public exported from `@promptbook/core`
  */
-class PipelineUrlError extends Error {
+class KnowledgeScrapeError extends Error {
     constructor(message) {
         super(message);
-        this.name = 'PipelineUrlError';
-        Object.setPrototypeOf(this, PipelineUrlError.prototype);
+        this.name = 'KnowledgeScrapeError';
+        Object.setPrototypeOf(this, KnowledgeScrapeError.prototype);
     }
 }
 
 /**
- * Error thrown when a fetch request fails
+ * This error type indicates that some limit was reached
  *
  * @public exported from `@promptbook/core`
  */
-class PromptbookFetchError extends Error {
+class LimitReachedError extends Error {
     constructor(message) {
         super(message);
-        this.name = 'PromptbookFetchError';
-        Object.setPrototypeOf(this, PromptbookFetchError.prototype);
+        this.name = 'LimitReachedError';
+        Object.setPrototypeOf(this, LimitReachedError.prototype);
     }
 }
 
 /**
- * This error type indicates that somewhere in the code non-Error object was thrown and it was wrapped into the `WrappedError`
+ * This error type indicates that some tools are missing for pipeline execution or preparation
  *
  * @public exported from `@promptbook/core`
  */
-class WrappedError extends Error {
-    constructor(whatWasThrown) {
-        const tag = `[🤮]`;
-        console.error(tag, whatWasThrown);
-        super(spaceTrim$2(`
-                Non-Error object was thrown
+class MissingToolsError extends Error {
+    constructor(message) {
+        super(spaceTrim$2((block) => `
+                    ${block(message)}
 
-                Note: Look for ${tag} in the console for more details
-                Please report issue on ${ADMIN_EMAIL}
-            `));
-        this.name = 'WrappedError';
-        Object.setPrototypeOf(this, WrappedError.prototype);
+                    Note: You have probably forgot to provide some tools for pipeline execution or preparation
+
+                `));
+        this.name = 'MissingToolsError';
+        Object.setPrototypeOf(this, MissingToolsError.prototype);
     }
 }
 
 /**
- * Index of all custom errors
+ * This error indicates that promptbook not found in the collection
  *
  * @public exported from `@promptbook/core`
  */
-const PROMPTBOOK_ERRORS = {
-    AbstractFormatError,
-    CsvFormatError,
-    CollectionError,
-    EnvironmentMismatchError,
-    ExpectError,
-    KnowledgeScrapeError,
-    LimitReachedError,
-    MissingToolsError,
-    NotFoundError,
-    NotYetImplementedError,
-    ParseError,
-    PipelineExecutionError,
-    PipelineLogicError,
-    PipelineUrlError,
-    AuthenticationError,
-    PromptbookFetchError,
-    UnexpectedError,
-    WrappedError,
-    // TODO: [🪑]> VersionMismatchError,
-};
-/**
- * Index of all javascript errors
- *
- * @private for internal usage
- */
-const COMMON_JAVASCRIPT_ERRORS = {
-    Error,
-    EvalError,
-    RangeError,
-    ReferenceError,
-    SyntaxError,
-    TypeError,
-    URIError,
-    AggregateError,
-    /*
-  Note: Not widely supported
-  > InternalError,
-  > ModuleError,
-  > HeapError,
-  > WebAssemblyCompileError,
-  > WebAssemblyRuntimeError,
-  */
-};
-/**
- * Index of all errors
- *
- * @private for internal usage
- */
-const ALL_ERRORS = {
-    ...PROMPTBOOK_ERRORS,
-    ...COMMON_JAVASCRIPT_ERRORS,
-};
-/**
- * Note: [💞] Ignore a discrepancy between file name and entity name
- */
-
-/**
- * Deserializes the error object
- *
- * @public exported from `@promptbook/utils`
- */
-function deserializeError(error) {
-    const { name, stack, id } = error; // Added id
-    let { message } = error;
-    let ErrorClass = ALL_ERRORS[error.name];
-    if (ErrorClass === undefined) {
-        ErrorClass = Error;
-        message = `${name}: ${message}`;
-    }
-    if (stack !== undefined && stack !== '') {
-        message = spaceTrim$1((block) => `
-                ${block(message)}
-
-                Original stack trace:
-                ${block(stack || '')}
-            `);
+class NotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NotFoundError';
+        Object.setPrototypeOf(this, NotFoundError.prototype);
     }
-    const deserializedError = new ErrorClass(message);
-    deserializedError.id = id; // Assign id to the error object
-    return deserializedError;
 }
 
 /**
- * Serializes an error into a [🚉] JSON-serializable object
+ * This error type indicates that some part of the code is not implemented yet
  *
- * @public exported from `@promptbook/utils`
+ * @public exported from `@promptbook/core`
  */
-function serializeError(error) {
-    const { name, message, stack } = error;
-    const { id } = error;
-    if (!Object.keys(ALL_ERRORS).includes(name)) {
-        console.error(spaceTrim$1((block) => `
-
-                    Cannot serialize error with name "${name}"
+class NotYetImplementedError extends Error {
+    constructor(message) {
+        super(spaceTrim$2((block) => `
+                    ${block(message)}
 
-                    Authors of Promptbook probably forgot to add this error into the list of errors:
-                    https://github.com/webgptorg/promptbook/blob/main/src/errors/0-index.ts
+                    Note: This feature is not implemented yet but it will be soon.
 
+                    If you want speed up the implementation or just read more, look here:
+                    https://github.com/webgptorg/promptbook
 
-                    ${block(stack || message)}
+                    Or contact us on pavol@ptbk.io
 
                 `));
+        this.name = 'NotYetImplementedError';
+        Object.setPrototypeOf(this, NotYetImplementedError.prototype);
     }
-    return {
-        name: name,
-        message,
-        stack,
-        id, // Include id in the serialized object
-    };
 }
 
 /**
- * Async version of Array.forEach
+ * This error indicates that the promptbook in a markdown format cannot be parsed into a valid promptbook object
  *
- * @param array - Array to iterate over
- * @param options - Options for the function
- * @param callbackfunction - Function to call for each item
- * @public exported from `@promptbook/utils`
- * @deprecated [🪂] Use queues instead
+ * @public exported from `@promptbook/core`
  */
-async function forEachAsync(array, options, callbackfunction) {
-    const { maxParallelCount = Infinity } = options;
-    let index = 0;
-    let runningTasks = [];
-    const tasks = [];
-    for (const item of array) {
-        const currentIndex = index++;
-        const task = callbackfunction(item, currentIndex, array);
-        tasks.push(task);
-        runningTasks.push(task);
-        /* not await */ Promise.resolve(task).then(() => {
-            runningTasks = runningTasks.filter((t) => t !== task);
-        });
-        if (maxParallelCount < runningTasks.length) {
-            await Promise.race(runningTasks);
-        }
+class ParseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ParseError';
+        Object.setPrototypeOf(this, ParseError.prototype);
     }
-    await Promise.all(tasks);
 }
+/**
+ * TODO: Maybe split `ParseError` and `ApplyError`
+ */
 
 /**
- * Helper used in catch blocks to assert that the error is an instance of `Error`
+ * Generates random token
  *
- * @param whatWasThrown Any object that was thrown
- * @returns Nothing if the error is an instance of `Error`
- * @throws `WrappedError` or `UnexpectedError` if the error is not standard
+ * Note: This function is cryptographically secure (it uses crypto.randomBytes internally)
  *
- * @private within the repository
+ * @private internal helper function
+ * @returns secure random token
  */
-function assertsError(whatWasThrown) {
-    // Case 1: Handle error which was rethrown as `WrappedError`
-    if (whatWasThrown instanceof WrappedError) {
-        const wrappedError = whatWasThrown;
-        throw wrappedError;
-    }
-    // Case 2: Handle unexpected errors
-    if (whatWasThrown instanceof UnexpectedError) {
-        const unexpectedError = whatWasThrown;
-        throw unexpectedError;
-    }
-    // Case 3: Handle standard errors - keep them up to consumer
-    if (whatWasThrown instanceof Error) {
-        return;
-    }
-    // Case 4: Handle non-standard errors - wrap them into `WrappedError` and throw
-    throw new WrappedError(whatWasThrown);
+function $randomToken(randomness) {
+    return randomBytes(randomness).toString('hex');
 }
+/**
+ * TODO: Maybe use nanoid instead https://github.com/ai/nanoid
+ */
 
 /**
- * Function to check if a string is valid CSV
- *
- * @param value The string to check
- * @returns True if the string is a valid CSV string, false otherwise
+ * This error indicates errors during the execution of the pipeline
  *
- * @public exported from `@promptbook/utils`
+ * @public exported from `@promptbook/core`
  */
-function isValidCsvString(value) {
-    try {
-        // A simple check for CSV format: at least one comma and no invalid characters
-        if (value.includes(',') && /^[\w\s,"']+$/.test(value)) {
-            return true;
-        }
-        return false;
-    }
-    catch (error) {
-        assertsError(error);
-        return false;
+class PipelineExecutionError extends Error {
+    constructor(message) {
+        // Added id parameter
+        super(message);
+        this.name = 'PipelineExecutionError';
+        // TODO: [🐙] DRY - Maybe $randomId
+        this.id = `error-${$randomToken(8 /* <- TODO: To global config + Use Base58 to avoid similar char conflicts   */)}`;
+        Object.setPrototypeOf(this, PipelineExecutionError.prototype);
     }
 }
+/**
+ * TODO: [🧠][🌂] Add id to all errors
+ */
 
 /**
- * Function isValidJsonString will tell you if the string is valid JSON or not
- *
- * @param value The string to check
- * @returns True if the string is a valid JSON string, false otherwise
+ * This error indicates that the promptbook object has valid syntax (=can be parsed) but contains logical errors (like circular dependencies)
  *
- * @public exported from `@promptbook/utils`
+ * @public exported from `@promptbook/core`
  */
-function isValidJsonString(value /* <- [👨‍⚖️] */) {
-    try {
-        JSON.parse(value);
-        return true;
-    }
-    catch (error) {
-        assertsError(error);
-        if (error.message.includes('Unexpected token')) {
-            return false;
-        }
-        return false;
+class PipelineLogicError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PipelineLogicError';
+        Object.setPrototypeOf(this, PipelineLogicError.prototype);
     }
 }
 
 /**
- * Converts a JavaScript Object Notation (JSON) string into an object.
- *
- * Note: This is wrapper around `JSON.parse()` with better error and type handling
+ * This error indicates errors in referencing promptbooks between each other
  *
- * @public exported from `@promptbook/utils`
+ * @public exported from `@promptbook/core`
  */
-function jsonParse(value) {
-    if (value === undefined) {
-        throw new Error(`Can not parse JSON from undefined value.`);
-    }
-    else if (typeof value !== 'string') {
-        console.error('Can not parse JSON from non-string value.', { text: value });
-        throw new Error(spaceTrim$1(`
-                    Can not parse JSON from non-string value.
-
-                    The value type: ${typeof value}
-                    See more in console.
-                `));
-    }
-    try {
-        return JSON.parse(value);
-    }
-    catch (error) {
-        if (!(error instanceof Error)) {
-            throw error;
-        }
-        throw new Error(spaceTrim$1((block) => `
-                    ${block(error.message)}
-            
-                    The JSON text:
-                    ${block(value)}
-                `));
+class PipelineUrlError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PipelineUrlError';
+        Object.setPrototypeOf(this, PipelineUrlError.prototype);
     }
 }
-/**
- * TODO: !!!! Use in Promptbook.studio
- */
 
 /**
- * Function to check if a string is valid XML
- *
- * @param value
- * @returns True if the string is a valid XML string, false otherwise
+ * Error thrown when a fetch request fails
  *
- * @public exported from `@promptbook/utils`
+ * @public exported from `@promptbook/core`
  */
-function isValidXmlString(value) {
-    try {
-        const parser = new DOMParser();
-        const parsedDocument = parser.parseFromString(value, 'application/xml');
-        const parserError = parsedDocument.getElementsByTagName('parsererror');
-        if (parserError.length > 0) {
-            return false;
-        }
-        return true;
-    }
-    catch (error) {
-        assertsError(error);
-        return false;
+class PromptbookFetchError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PromptbookFetchError';
+        Object.setPrototypeOf(this, PromptbookFetchError.prototype);
     }
 }
 
 /**
- * Orders JSON object by keys
+ * Index of all custom errors
  *
- * @returns The same type of object as the input re-ordered
- * @public exported from `@promptbook/utils`
+ * @public exported from `@promptbook/core`
  */
-function orderJson(options) {
-    const { value, order } = options;
-    const orderedValue = {
-        ...(order === undefined ? {} : Object.fromEntries(order.map((key) => [key, undefined]))),
-        ...value,
-    };
-    return orderedValue;
-}
-
+const PROMPTBOOK_ERRORS = {
+    AbstractFormatError,
+    CsvFormatError,
+    CollectionError,
+    EnvironmentMismatchError,
+    ExpectError,
+    KnowledgeScrapeError,
+    LimitReachedError,
+    MissingToolsError,
+    NotFoundError,
+    NotYetImplementedError,
+    ParseError,
+    PipelineExecutionError,
+    PipelineLogicError,
+    PipelineUrlError,
+    AuthenticationError,
+    PromptbookFetchError,
+    UnexpectedError,
+    WrappedError,
+    // TODO: [🪑]> VersionMismatchError,
+};
 /**
- * Freezes the given object and all its nested objects recursively
+ * Index of all javascript errors
  *
- * Note: `$` is used to indicate that this function is not a pure function - it mutates given object
- * Note: This function mutates the object and returns the original (but mutated-deep-freezed) object
+ * @private for internal usage
+ */
+const COMMON_JAVASCRIPT_ERRORS = {
+    Error,
+    EvalError,
+    RangeError,
+    ReferenceError,
+    SyntaxError,
+    TypeError,
+    URIError,
+    AggregateError,
+    /*
+  Note: Not widely supported
+  > InternalError,
+  > ModuleError,
+  > HeapError,
+  > WebAssemblyCompileError,
+  > WebAssemblyRuntimeError,
+  */
+};
+/**
+ * Index of all errors
  *
- * @returns The same object as the input, but deeply frozen
- * @public exported from `@promptbook/utils`
+ * @private for internal usage
  */
-function $deepFreeze(objectValue) {
-    if (Array.isArray(objectValue)) {
-        return Object.freeze(objectValue.map((item) => $deepFreeze(item)));
-    }
-    const propertyNames = Object.getOwnPropertyNames(objectValue);
-    for (const propertyName of propertyNames) {
-        const value = objectValue[propertyName];
-        if (value && typeof value === 'object') {
-            $deepFreeze(value);
-        }
-    }
-    Object.freeze(objectValue);
-    return objectValue;
-}
+const ALL_ERRORS = {
+    ...PROMPTBOOK_ERRORS,
+    ...COMMON_JAVASCRIPT_ERRORS,
+};
 /**
- * TODO: [🧠] Is there a way how to meaningfully test this utility
+ * Note: [💞] Ignore a discrepancy between file name and entity name
  */
 
 /**
- * Checks if the value is [🚉] serializable as JSON
- * If not, throws an UnexpectedError with a rich error message and tracking
- *
- * - Almost all primitives are serializable BUT:
- * - `undefined` is not serializable
- * - `NaN` is not serializable
- * - Objects and arrays are serializable if all their properties are serializable
- * - Functions are not serializable
- * - Circular references are not serializable
- * - `Date` objects are not serializable
- * - `Map` and `Set` objects are not serializable
- * - `RegExp` objects are not serializable
- * - `Error` objects are not serializable
- * - `Symbol` objects are not serializable
- * - And much more...
+ * Deserializes the error object
  *
- * @throws UnexpectedError if the value is not serializable as JSON
  * @public exported from `@promptbook/utils`
  */
-function checkSerializableAsJson(options) {
-    const { value, name, message } = options;
-    if (value === undefined) {
-        throw new UnexpectedError(`${name} is undefined`);
-    }
-    else if (value === null) {
-        return;
-    }
-    else if (typeof value === 'boolean') {
-        return;
-    }
-    else if (typeof value === 'number' && !isNaN(value)) {
-        return;
-    }
-    else if (typeof value === 'string') {
-        return;
-    }
-    else if (typeof value === 'symbol') {
-        throw new UnexpectedError(`${name} is symbol`);
-    }
-    else if (typeof value === 'function') {
-        throw new UnexpectedError(`${name} is function`);
-    }
-    else if (typeof value === 'object' && Array.isArray(value)) {
-        for (let i = 0; i < value.length; i++) {
-            checkSerializableAsJson({ name: `${name}[${i}]`, value: value[i], message });
-        }
+function deserializeError(error) {
+    const { name, stack, id } = error; // Added id
+    let { message } = error;
+    let ErrorClass = ALL_ERRORS[error.name];
+    if (ErrorClass === undefined) {
+        ErrorClass = Error;
+        message = `${name}: ${message}`;
     }
-    else if (typeof value === 'object') {
-        if (value instanceof Date) {
-            throw new UnexpectedError(spaceTrim$1((block) => `
-                        \`${name}\` is Date
-
-                        Use \`string_date_iso8601\` instead
+    if (stack !== undefined && stack !== '') {
+        message = spaceTrim$1((block) => `
+                ${block(message)}
 
-                        Additional message for \`${name}\`:
-                        ${block(message || '(nothing)')}
-                    `));
-        }
-        else if (value instanceof Map) {
-            throw new UnexpectedError(`${name} is Map`);
-        }
-        else if (value instanceof Set) {
-            throw new UnexpectedError(`${name} is Set`);
-        }
-        else if (value instanceof RegExp) {
-            throw new UnexpectedError(`${name} is RegExp`);
-        }
-        else if (value instanceof Error) {
-            throw new UnexpectedError(spaceTrim$1((block) => `
-                        \`${name}\` is unserialized Error
+                Original stack trace:
+                ${block(stack || '')}
+            `);
+    }
+    const deserializedError = new ErrorClass(message);
+    deserializedError.id = id; // Assign id to the error object
+    return deserializedError;
+}
 
-                        Use function \`serializeError\`
+/**
+ * Serializes an error into a [🚉] JSON-serializable object
+ *
+ * @public exported from `@promptbook/utils`
+ */
+function serializeError(error) {
+    const { name, message, stack } = error;
+    const { id } = error;
+    if (!Object.keys(ALL_ERRORS).includes(name)) {
+        console.error(spaceTrim$1((block) => `
 
-                        Additional message for \`${name}\`:
-                        ${block(message || '(nothing)')}
+                    Cannot serialize error with name "${name}"
 
-                    `));
-        }
-        else {
-            for (const [subName, subValue] of Object.entries(value)) {
-                if (subValue === undefined) {
-                    // Note: undefined in object is serializable - it is just omited
-                    continue;
-                }
-                checkSerializableAsJson({ name: `${name}.${subName}`, value: subValue, message });
-            }
-            try {
-                JSON.stringify(value); // <- TODO: [0]
-            }
-            catch (error) {
-                assertsError(error);
-                throw new UnexpectedError(spaceTrim$1((block) => `
-                            \`${name}\` is not serializable
+                    Authors of Promptbook probably forgot to add this error into the list of errors:
+                    https://github.com/webgptorg/promptbook/blob/main/src/errors/0-index.ts
 
-                            ${block(error.stack || error.message)}
 
-                            Additional message for \`${name}\`:
-                            ${block(message || '(nothing)')}
-                        `));
-            }
-            /*
-            TODO: [0] Is there some more elegant way to check circular references?
-            const seen = new Set();
-            const stack = [{ value }];
-            while (stack.length > 0) {
-                const { value } = stack.pop()!;
-                if (typeof value === 'object' && value !== null) {
-                    if (seen.has(value)) {
-                        throw new UnexpectedError(`${name} has circular reference`);
-                    }
-                    seen.add(value);
-                    if (Array.isArray(value)) {
-                        stack.push(...value.map((value) => ({ value })));
-                    } else {
-                        stack.push(...Object.values(value).map((value) => ({ value })));
-                    }
-                }
-            }
-            */
-            return;
-        }
-    }
-    else {
-        throw new UnexpectedError(spaceTrim$1((block) => `
-                    \`${name}\` is unknown type
+                    ${block(stack || message)}
 
-                    Additional message for \`${name}\`:
-                    ${block(message || '(nothing)')}
                 `));
     }
+    return {
+        name: name,
+        message,
+        stack,
+        id, // Include id in the serialized object
+    };
 }
-/**
- * TODO: Can be return type more type-safe? like `asserts options.value is JsonValue`
- * TODO: [🧠][main] !!3 In-memory cache of same values to prevent multiple checks
- * Note: [🐠] This is how `checkSerializableAsJson` + `isSerializableAsJson` together can just retun true/false or rich error message
- */
 
 /**
- * @@@
+ * Async version of Array.forEach
  *
+ * @param array - Array to iterate over
+ * @param options - Options for the function
+ * @param callbackfunction - Function to call for each item
  * @public exported from `@promptbook/utils`
+ * @deprecated [🪂] Use queues instead
  */
-function deepClone(objectValue) {
-    return JSON.parse(JSON.stringify(objectValue));
-    /*
-    TODO: [🧠] Is there a better implementation?
-    > const propertyNames = Object.getOwnPropertyNames(objectValue);
-    > for (const propertyName of propertyNames) {
-    >     const value = (objectValue as really_any)[propertyName];
-    >     if (value && typeof value === 'object') {
-    >         deepClone(value);
-    >     }
-    > }
-    > return Object.assign({}, objectValue);
-    */
+async function forEachAsync(array, options, callbackfunction) {
+    const { maxParallelCount = Infinity } = options;
+    let index = 0;
+    let runningTasks = [];
+    const tasks = [];
+    for (const item of array) {
+        const currentIndex = index++;
+        const task = callbackfunction(item, currentIndex, array);
+        tasks.push(task);
+        runningTasks.push(task);
+        /* not await */ Promise.resolve(task).then(() => {
+            runningTasks = runningTasks.filter((t) => t !== task);
+        });
+        if (maxParallelCount < runningTasks.length) {
+            await Promise.race(runningTasks);
+        }
+    }
+    await Promise.all(tasks);
 }
-/**
- * TODO: [🧠] Is there a way how to meaningfully test this utility
- */
 
 /**
- * Utility to export a JSON object from a function
- *
- * 1) Checks if the value is serializable as JSON
- * 2) Makes a deep clone of the object
- * 2) Orders the object properties
- * 2) Deeply freezes the cloned object
+ * Function to check if a string is valid CSV
  *
- * Note: This function does not mutates the given object
+ * @param value The string to check
+ * @returns `true` if the string is a valid CSV string, false otherwise
  *
- * @returns The same type of object as the input but read-only and re-ordered
  * @public exported from `@promptbook/utils`
  */
-function exportJson(options) {
-    const { name, value, order, message } = options;
-    checkSerializableAsJson({ name, value, message });
-    const orderedValue = 
-    // TODO: Fix error "Type instantiation is excessively deep and possibly infinite."
-    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-    // @ts-ignore
-    order === undefined
-        ? deepClone(value)
-        : orderJson({
-            value: value,
-            // <- Note: checkSerializableAsJson asserts that the value is serializable as JSON
-            order: order,
-        });
-    $deepFreeze(orderedValue);
-    return orderedValue;
+function isValidCsvString(value) {
+    try {
+        // A simple check for CSV format: at least one comma and no invalid characters
+        if (value.includes(',') && /^[\w\s,"']+$/.test(value)) {
+            return true;
+        }
+        return false;
+    }
+    catch (error) {
+        assertsError(error);
+        return false;
+    }
 }
-/**
- * TODO: [🧠] Is there a way how to meaningfully test this utility
- */
 
 /**
- * Nonce which is used for replacing things in strings
+ * Function isValidJsonString will tell you if the string is valid JSON or not
  *
- * @private within the repository
- */
-const REPLACING_NONCE = 'ptbkauk42kV2dzao34faw7FudQUHYPtW';
-/**
- * @@@
+ * @param value The string to check
+ * @returns `true` if the string is a valid JSON string, false otherwise
  *
- * @private within the repository
+ * @public exported from `@promptbook/utils`
  */
-const RESERVED_PARAMETER_MISSING_VALUE = 'MISSING-' + REPLACING_NONCE;
+function isValidJsonString(value /* <- [👨‍⚖️] */) {
+    try {
+        JSON.parse(value);
+        return true;
+    }
+    catch (error) {
+        assertsError(error);
+        if (error.message.includes('Unexpected token')) {
+            return false;
+        }
+        return false;
+    }
+}
+
 /**
- * @@@
+ * Converts a JavaScript Object Notation (JSON) string into an object.
  *
- * @private within the repository
- */
-const RESERVED_PARAMETER_RESTRICTED = 'RESTRICTED-' + REPLACING_NONCE;
-/**
- * The names of the parameters that are reserved for special purposes
+ * Note: This is wrapper around `JSON.parse()` with better error and type handling
  *
- * @public exported from `@promptbook/core`
+ * @public exported from `@promptbook/utils`
  */
-exportJson({
-    name: 'RESERVED_PARAMETER_NAMES',
-    message: `The names of the parameters that are reserved for special purposes`,
-    value: [
-        'content',
-        'context',
-        'knowledge',
-        'examples',
-        'modelName',
-        'currentDate',
-        // <- TODO: list here all command names
-        // <- TODO: Add more like 'date', 'modelName',...
-        // <- TODO: Add [emoji] + instructions ACRY when adding new reserved parameter
-    ],
-});
+function jsonParse(value) {
+    if (value === undefined) {
+        throw new Error(`Can not parse JSON from undefined value.`);
+    }
+    else if (typeof value !== 'string') {
+        console.error('Can not parse JSON from non-string value.', { text: value });
+        throw new Error(spaceTrim$1(`
+                    Can not parse JSON from non-string value.
+
+                    The value type: ${typeof value}
+                    See more in console.
+                `));
+    }
+    try {
+        return JSON.parse(value);
+    }
+    catch (error) {
+        if (!(error instanceof Error)) {
+            throw error;
+        }
+        throw new Error(spaceTrim$1((block) => `
+                    ${block(error.message)}
+
+                    The JSON text:
+                    ${block(value)}
+                `));
+    }
+}
+
 /**
- * Note: [💞] Ignore a discrepancy between file name and entity name
+ * Function to check if a string is valid XML
+ *
+ * @param value
+ * @returns `true` if the string is a valid XML string, false otherwise
+ *
+ * @public exported from `@promptbook/utils`
  */
+function isValidXmlString(value) {
+    try {
+        const parser = new DOMParser();
+        const parsedDocument = parser.parseFromString(value, 'application/xml');
+        const parserError = parsedDocument.getElementsByTagName('parsererror');
+        if (parserError.length > 0) {
+            return false;
+        }
+        return true;
+    }
+    catch (error) {
+        assertsError(error);
+        return false;
+    }
+}
 
 /**
  * Format either small or big number
@@ -1982,7 +2015,7 @@ const CountUtils = {
     PAGES: countPages,
 };
 /**
- * TODO: [🧠][🤠] This should be probbably as part of `TextFormatDefinition`
+ * TODO: [🧠][🤠] This should be probably as part of `TextFormatParser`
  * Note: [💞] Ignore a discrepancy between file name and entity name
  */
 
@@ -2005,10 +2038,10 @@ function decapitalize(word) {
 }
 
 /**
- * @@@
+ * Normalizes a text string to SCREAMING_CASE (all uppercase with underscores).
  *
- * @param text @@@
- * @returns @@@
+ * @param text The text string to be converted to SCREAMING_CASE format.
+ * @returns The normalized text in SCREAMING_CASE format.
  * @example 'HELLO_WORLD'
  * @example 'I_LOVE_PROMPTBOOK'
  * @public exported from `@promptbook/utils`
@@ -2093,11 +2126,11 @@ function isValidKeyword(keyword) {
 }
 
 /**
- * @@@
+ * Converts a name string into a URI-compatible format.
  *
- * @param name @@@
- * @returns @@@
- * @example @@@
+ * @param name The string to be converted to a URI-compatible format.
+ * @returns A URI-compatible string derived from the input name.
+ * @example 'Hello World' -> 'hello-world'
  * @public exported from `@promptbook/utils`
  */
 function nameToUriPart(name) {
@@ -2111,11 +2144,11 @@ function nameToUriPart(name) {
 }
 
 /**
- * @@@
+ * Converts a given name into URI-compatible parts.
  *
- * @param name @@@
- * @returns @@@
- * @example @@@
+ * @param name The name to be converted into URI parts.
+ * @returns An array of URI-compatible parts derived from the name.
+ * @example 'Example Name' -> ['example', 'name']
  * @public exported from `@promptbook/utils`
  */
 function nameToUriParts(name) {
@@ -2137,10 +2170,10 @@ function normalizeTo_PascalCase(text) {
 }
 
 /**
- * @@@
+ * Normalizes a text string to snake_case format.
  *
- * @param text @@@
- * @returns @@@
+ * @param text The text string to be converted to snake_case format.
+ * @returns The normalized text in snake_case format.
  * @example 'hello_world'
  * @example 'i_love_promptbook'
  * @public exported from `@promptbook/utils`
@@ -2192,7 +2225,7 @@ function parseKeywords(input) {
  */
 
 /**
- * @@@
+ * Searches set of keywords for a specific keyword
  *
  * @param haystack
  * @param needle
@@ -2207,6 +2240,9 @@ function searchKeywords(haystack, needle) {
     }
     return true;
 }
+/**
+ * TODO: Rename to `isKeywordInKeywords`
+ */
 
 /**
  * Adds suffix to the URL
@@ -2318,9 +2354,9 @@ function parseNumber(value) {
 /**
  * Removes quotes from a string
  *
- * Tip: This is very usefull for post-processing of the result of the LLM model
+ * Tip: This is very useful for post-processing of the result of the LLM model
  * Note: This function removes only the same quotes from the beginning and the end of the string
- * Note: There are two simmilar functions:
+ * Note: There are two similar functions:
  * - `removeQuotes` which removes only bounding quotes
  * - `unwrapResult` which removes whole introduce sentence
  *
@@ -2332,22 +2368,23 @@ function removeQuotes(text) {
     if (text.startsWith('"') && text.endsWith('"')) {
         return text.slice(1, -1);
     }
-    if (text.startsWith('\'') && text.endsWith('\'')) {
+    if (text.startsWith("'") && text.endsWith("'")) {
         return text.slice(1, -1);
     }
     return text;
 }
 
 /**
- * @@@
+ * Creates a deep clone of a PipelineJson object, copying all properties explicitly.
  *
- * Note: It is usefull @@@
+ * Note: It is useful for ensuring that modifications to the returned pipeline do not affect the original.
  *
- * @param pipeline
+ * @param pipeline The pipeline to clone.
+ * @returns A new PipelineJson object with the same properties as the input.
  * @public exported from `@promptbook/utils`
  */
 function clonePipeline(pipeline) {
-    // Note: Not using spread operator (...) because @@@
+    // Note: Not using spread operator (...) because it does not deeply copy nested objects and may miss non-enumerable properties.
     const { pipelineUrl, sourceFile, title, bookVersion, description, formfactorName, parameters, tasks, knowledgeSources, knowledgePieces, personas, preparations, sources, } = pipeline;
     return {
         pipelineUrl,
@@ -2496,7 +2533,7 @@ function union(...sets) {
 /**
  * Function trimCodeBlock will trim starting and ending code block from the string if it is present.
  *
- * Note: This is usefull for post-processing of the result of the chat LLM model
+ * Note: This is useful for post-processing of the result of the chat LLM model
  *       when the model wraps the result in the (markdown) code block.
  *
  * @public exported from `@promptbook/utils`
@@ -2515,7 +2552,7 @@ function trimCodeBlock(value) {
 /**
  * Function trimEndOfCodeBlock will remove ending code block from the string if it is present.
  *
- * Note: This is usefull for post-processing of the result of the completion LLM model
+ * Note: This is useful for post-processing of the result of the completion LLM model
  *       if you want to start code block in the prompt but you don't want to end it in the result.
  *
  * @public exported from `@promptbook/utils`
@@ -2530,9 +2567,9 @@ function trimEndOfCodeBlock(value) {
 /**
  * Removes quotes and optional introduce text from a string
  *
- * Tip: This is very usefull for post-processing of the result of the LLM model
+ * Tip: This is very useful for post-processing of the result of the LLM model
  * Note: This function trims the text and removes whole introduce sentence if it is present
- * Note: There are two simmilar functions:
+ * Note: There are two similar functions:
  * - `removeQuotes` which removes only bounding quotes
  * - `unwrapResult` which removes whole introduce sentence
  *
@@ -2633,10 +2670,10 @@ function isRootPath(value) {
  */
 
 /**
- * @@@
+ * Checks if the given value is a valid JavaScript identifier name.
  *
- * @param javascriptName @@@
- * @returns @@@
+ * @param javascriptName The value to check for JavaScript identifier validity.
+ * @returns `true` if the value is a valid JavaScript name, false otherwise.
  * @public exported from `@promptbook/utils`
  */
 function isValidJavascriptName(javascriptName) {
@@ -2649,7 +2686,7 @@ function isValidJavascriptName(javascriptName) {
 /**
  * Tests if given string is valid semantic version
  *
- * Note: There are two simmilar functions:
+ * Note: There are two similar functions:
  * - `isValidSemanticVersion` which tests any semantic version
  * - `isValidPromptbookVersion` *(this one)* which tests just Promptbook versions
  *
@@ -2671,7 +2708,7 @@ function isValidSemanticVersion(version) {
  *
  * @see https://www.npmjs.com/package/promptbook?activeTab=versions
  * Note: When you are using for example promptbook 2.0.0 and there already is promptbook 3.0.0 it don`t know about it.
- * Note: There are two simmilar functions:
+ * Note: There are two similar functions:
  * - `isValidSemanticVersion` which tests any semantic version
  * - `isValidPromptbookVersion` *(this one)* which tests just Promptbook versions
  *
@@ -2691,7 +2728,7 @@ function isValidPromptbookVersion(version) {
 /**
  * Checks if an URL is reserved for private networks or localhost.
  *
- * Note: There are two simmilar functions:
+ * Note: There are two similar functions:
  * - `isUrlOnPrivateNetwork` which tests full URL
  * - `isHostnameOnPrivateNetwork` *(this one)* which tests just hostname
  *
@@ -2724,7 +2761,7 @@ function isHostnameOnPrivateNetwork(hostname) {
 /**
  * Checks if an IP address or hostname is reserved for private networks or localhost.
  *
- * Note: There are two simmilar functions:
+ * Note: There are two similar functions:
  * - `isUrlOnPrivateNetwork` *(this one)* which tests full URL
  * - `isHostnameOnPrivateNetwork` which tests just hostname
  *
@@ -2742,7 +2779,7 @@ function isUrlOnPrivateNetwork(url) {
 /**
  * Tests if given string is valid pipeline URL URL.
  *
- * Note: There are two simmilar functions:
+ * Note: There are two similar functions:
  * - `isValidUrl` which tests any URL
  * - `isValidPipelineUrl` *(this one)* which tests just pipeline URL
  *