@promptbook/javascript 0.92.0-9 → 0.93.0

package/umd/index.umd.js

@@ -23,7 +23,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.92.0-9';
+    const PROMPTBOOK_ENGINE_VERSION = '0.93.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
@@ -79,7 +79,7 @@
     const SMALL_NUMBER = 0.001;
     // <- TODO: [🧜‍♂️]
     /**
-     * @@@
+     * Default settings for parsing and generating CSV files in Promptbook.
      *
      * @public exported from `@promptbook/core`
      */
@@ -94,6 +94,48 @@
      * 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
      *
@@ -149,7 +191,7 @@
                     ${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)}
@@ -163,70 +205,341 @@
     }
 
     /**
-     * @@@
+     * 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/core`
+     */
+    class WrappedError extends Error {
+        constructor(whatWasThrown) {
+            const tag = `[🤮]`;
+            console.error(tag, whatWasThrown);
+            super(spaceTrim.spaceTrim(`
+                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);
+        }
+    }
+
+    /**
+     * Helper used in catch blocks to assert that the error is an instance of `Error`
+     *
+     * @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 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);
+    }
+
+    /**
+     * 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...
+     *
+     * @throws UnexpectedError if the value is not serializable as JSON
      * @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;
+    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 });
             }
-            else if (/^[A-Z]$/.test(char)) {
-                charType = 'UPPERCASE';
-                normalizedChar = char.toLowerCase();
+        }
+        else if (typeof value === 'object') {
+            if (value instanceof Date) {
+                throw new UnexpectedError(spaceTrim__default["default"]((block) => `
+                        \`${name}\` is Date
+
+                        Use \`string_date_iso8601\` instead
+
+                        Additional message for \`${name}\`:
+                        ${block(message || '(nothing)')}
+                    `));
             }
-            else if (/^[0-9]$/.test(char)) {
-                charType = 'NUMBER';
-                normalizedChar = char;
+            else if (value instanceof Map) {
+                throw new UnexpectedError(`${name} is Map`);
             }
-            else {
-                charType = 'OTHER';
-                normalizedChar = '';
+            else if (value instanceof Set) {
+                throw new UnexpectedError(`${name} is Set`);
             }
-            if (!lastCharType) {
-                if (_isFirstLetterCapital) {
-                    normalizedChar = normalizedChar.toUpperCase(); //TODO: DRY
-                }
+            else if (value instanceof RegExp) {
+                throw new UnexpectedError(`${name} is RegExp`);
             }
-            else if (charType !== lastCharType &&
-                !(charType === 'LOWERCASE' && lastCharType === 'UPPERCASE') &&
-                !(lastCharType === 'NUMBER') &&
-                !(charType === 'NUMBER')) {
-                normalizedChar = normalizedChar.toUpperCase(); //TODO: [🌺] DRY
+            else if (value instanceof Error) {
+                throw new UnexpectedError(spaceTrim__default["default"]((block) => `
+                        \`${name}\` is unserialized Error
+
+                        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__default["default"]((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;
             }
-            normalizedName += normalizedChar;
-            lastCharType = charType;
         }
-        return normalizedName;
+        else {
+            throw new UnexpectedError(spaceTrim__default["default"]((block) => `
+                    \`${name}\` is unknown type
+
+                    Additional message for \`${name}\`:
+                    ${block(message || '(nothing)')}
+                `));
+        }
     }
     /**
-     * TODO: [🌺] Use some intermediate util splitWords
+     * 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
      */
 
     /**
-     * Removes emojis from a string and fix whitespaces
+     * Creates a deep clone of the given object
      *
-     * @param text with emojis
-     * @returns text without emojis
+     * 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 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, '');
+    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
+     */
+
+    /**
+     * The names of the parameters that are reserved for special purposes
+     *
+     * @public exported from `@promptbook/core`
+     */
+    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;
     }
 
@@ -457,472 +770,163 @@
         for (let j = 0; j < letters.length; j++) {
             DIACRITIC_VARIANTS_LETTERS[letters[j]] = defaultDiacriticsRemovalMap[i].base;
         }
-    }
-    // <- TODO: [🍓] Put to maker function to save execution time if not needed
-    /*
-      @see https://stackoverflow.com/questions/990904/remove-accents-diacritics-in-a-string-in-javascript
-       Licensed under the Apache License, Version 2.0 (the "License");
-       you may not use this file except in compliance with the License.
-       You may obtain a copy of the License at
-
-           http://www.apache.org/licenses/LICENSE-2.0
-
-       Unless required by applicable law or agreed to in writing, software
-       distributed under the License is distributed on an "AS IS" BASIS,
-       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-       See the License for the specific language governing permissions and
-       limitations under the License.
-    */
-
-    /**
-     * @@@
-     *
-     * @param input @@@
-     * @returns @@@
-     * @public exported from `@promptbook/utils`
-     */
-    function removeDiacritics(input) {
-        /*eslint no-control-regex: "off"*/
-        return input.replace(/[^\u0000-\u007E]/g, (a) => {
-            return DIACRITIC_VARIANTS_LETTERS[a] || a;
-        });
-    }
-    /**
-     * TODO: [Ж] Variant for cyrillic (and in general non-latin) letters
-     */
-
-    /**
-     * @@@
-     *
-     * @param text @@@
-     * @returns @@@
-     * @example 'hello-world'
-     * @example 'i-love-promptbook'
-     * @public exported from `@promptbook/utils`
-     */
-    function normalizeToKebabCase(text) {
-        text = removeDiacritics(text);
-        let charType;
-        let lastCharType = 'OTHER';
-        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 (charType !== lastCharType &&
-                !(lastCharType === 'UPPERCASE' && charType === 'LOWERCASE') &&
-                !(lastCharType === 'NUMBER') &&
-                !(charType === 'NUMBER')) {
-                normalizedName += '-';
-            }
-            normalizedName += normalizedChar;
-            lastCharType = charType;
-        }
-        normalizedName = normalizedName.split(/-+/g).join('-');
-        normalizedName = normalizedName.split(/-?\/-?/g).join('/');
-        normalizedName = normalizedName.replace(/^-/, '');
-        normalizedName = normalizedName.replace(/-$/, '');
-        return normalizedName;
-    }
-    /**
-     * Note: [💞] Ignore a discrepancy between file name and entity name
-     */
-
-    /**
-     * 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 crypto.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);
-        }
-    }
-    /**
-     * TODO: [🧠][🌂] Add id to all errors
-     */
-
-    /**
-     * This error type indicates that somewhere in the code non-Error object was thrown and it was wrapped into the `WrappedError`
-     *
-     * @public exported from `@promptbook/core`
-     */
-    class WrappedError extends Error {
-        constructor(whatWasThrown) {
-            const tag = `[🤮]`;
-            console.error(tag, whatWasThrown);
-            super(spaceTrim.spaceTrim(`
-                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);
-        }
-    }
-
-    /**
-     * Index of all javascript errors
-     *
-     * @private for internal usage
-     */
-    ({
-        Error,
-        EvalError,
-        RangeError,
-        ReferenceError,
-        SyntaxError,
-        TypeError,
-        URIError,
-        AggregateError,
-        /*
-      Note: Not widely supported
-      > InternalError,
-      > ModuleError,
-      > HeapError,
-      > WebAssemblyCompileError,
-      > WebAssemblyRuntimeError,
-      */
-    });
-    /**
-     * Note: [💞] Ignore a discrepancy between file name and entity name
-     */
-
-    /**
-     * Helper used in catch blocks to assert that the error is an instance of `Error`
-     *
-     * @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 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);
-    }
-
-    /**
-     * 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
-     */
-
-    /**
-     * 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...
-     *
-     * @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 });
-            }
-        }
-        else if (typeof value === 'object') {
-            if (value instanceof Date) {
-                throw new UnexpectedError(spaceTrim__default["default"]((block) => `
-                        \`${name}\` is Date
-
-                        Use \`string_date_iso8601\` instead
+    }
+    // <- TODO: [🍓] Put to maker function to save execution time if not needed
+    /*
+      @see https://stackoverflow.com/questions/990904/remove-accents-diacritics-in-a-string-in-javascript
+       Licensed under the Apache License, Version 2.0 (the "License");
+       you may not use this file except in compliance with the License.
+       You may obtain a copy of the License at
 
-                        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__default["default"]((block) => `
-                        \`${name}\` is unserialized Error
+           http://www.apache.org/licenses/LICENSE-2.0
 
-                        Use function \`serializeError\`
+       Unless required by applicable law or agreed to in writing, software
+       distributed under the License is distributed on an "AS IS" BASIS,
+       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+       See the License for the specific language governing permissions and
+       limitations under the License.
+    */
 
-                        Additional message for \`${name}\`:
-                        ${block(message || '(nothing)')}
+    /**
+     * Removes diacritic marks (accents) from characters in a string.
+     *
+     * @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) {
+        /*eslint no-control-regex: "off"*/
+        return input.replace(/[^\u0000-\u007E]/g, (a) => {
+            return DIACRITIC_VARIANTS_LETTERS[a] || a;
+        });
+    }
+    /**
+     * TODO: [Ж] Variant for cyrillic (and in general non-latin) letters
+     */
 
-                    `));
+    /**
+     * Converts a given text to kebab-case format.
+     *
+     * @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`
+     */
+    function normalizeToKebabCase(text) {
+        text = removeDiacritics(text);
+        let charType;
+        let lastCharType = 'OTHER';
+        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 {
-                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__default["default"]((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;
+                charType = 'OTHER';
+                normalizedChar = '-';
             }
+            if (charType !== lastCharType &&
+                !(lastCharType === 'UPPERCASE' && charType === 'LOWERCASE') &&
+                !(lastCharType === 'NUMBER') &&
+                !(charType === 'NUMBER')) {
+                normalizedName += '-';
+            }
+            normalizedName += normalizedChar;
+            lastCharType = charType;
         }
-        else {
-            throw new UnexpectedError(spaceTrim__default["default"]((block) => `
-                    \`${name}\` is unknown type
-
-                    Additional message for \`${name}\`:
-                    ${block(message || '(nothing)')}
-                `));
-        }
+        normalizedName = normalizedName.split(/-+/g).join('-');
+        normalizedName = normalizedName.split(/-?\/-?/g).join('/');
+        normalizedName = normalizedName.replace(/^-/, '');
+        normalizedName = normalizedName.replace(/-$/, '');
+        return normalizedName;
     }
     /**
-     * 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
+     * Note: [💞] Ignore a discrepancy between file name and entity name
      */
 
     /**
-     * @@@
+     * This error indicates that the promptbook in a markdown format cannot be parsed into a valid promptbook object
      *
-     * @public exported from `@promptbook/utils`
+     * @public exported from `@promptbook/core`
      */
-    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);
-        */
+    class ParseError extends Error {
+        constructor(message) {
+            super(message);
+            this.name = 'ParseError';
+            Object.setPrototypeOf(this, ParseError.prototype);
+        }
     }
     /**
-     * TODO: [🧠] Is there a way how to meaningfully test this utility
+     * TODO: Maybe split `ParseError` and `ApplyError`
      */
 
     /**
-     * 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
+     * Generates random token
      *
-     * Note: This function does not mutates the given object
+     * Note: This function is cryptographically secure (it uses crypto.randomBytes internally)
      *
-     * @returns The same type of object as the input but read-only and re-ordered
-     * @public exported from `@promptbook/utils`
+     * @private internal helper function
+     * @returns secure random token
      */
-    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 $randomToken(randomness) {
+        return crypto.randomBytes(randomness).toString('hex');
     }
     /**
-     * TODO: [🧠] Is there a way how to meaningfully test this utility
+     * TODO: Maybe use nanoid instead https://github.com/ai/nanoid
      */
 
     /**
-     * The names of the parameters that are reserved for special purposes
+     * This error indicates errors during the execution of the pipeline
      *
      * @public exported from `@promptbook/core`
      */
-    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
-        ],
+    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
+     */
+
+    /**
+     * Index of all javascript errors
+     *
+     * @private for internal usage
+     */
+    ({
+        Error,
+        EvalError,
+        RangeError,
+        ReferenceError,
+        SyntaxError,
+        TypeError,
+        URIError,
+        AggregateError,
+        /*
+      Note: Not widely supported
+      > InternalError,
+      > ModuleError,
+      > HeapError,
+      > WebAssemblyCompileError,
+      > WebAssemblyRuntimeError,
+      */
     });
     /**
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -1104,10 +1108,10 @@
     }
 
     /**
-     * @@@
+     * 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`
@@ -1174,11 +1178,11 @@
     }
 
     /**
-     * @@@
+     * 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) {
@@ -1192,11 +1196,11 @@
     }
 
     /**
-     * @@@
+     * 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) {
@@ -1218,10 +1222,10 @@
     }
 
     /**
-     * @@@
+     * 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`
@@ -1242,9 +1246,9 @@
     /**
      * 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
      *
@@ -1256,7 +1260,7 @@
         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;
@@ -1265,7 +1269,7 @@
     /**
      * 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`
@@ -1284,7 +1288,7 @@
     /**
      * 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`
@@ -1299,9 +1303,9 @@
     /**
      * 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
      *
@@ -1370,8 +1374,8 @@
     /**
      * Extracts all code blocks from markdown.
      *
-     * Note: There are multiple simmilar function:
-     * - `extractBlock` just extracts the content of the code block which is also used as build-in function for postprocessing
+     * Note: There are multiple similar functions:
+     * - `extractBlock` just extracts the content of the code block which is also used as built-in function for postprocessing
      * - `extractJsonBlock` extracts exactly one valid JSON code block
      * - `extractOneBlockFromMarkdown` extracts exactly one code block with language of the code block
      * - `extractAllBlocksFromMarkdown` extracts all code blocks with language of the code block
@@ -1421,7 +1425,7 @@
                 if (currentCodeBlock.content !== '') {
                     currentCodeBlock.content += '\n';
                 }
-                currentCodeBlock.content += line.split('\\`\\`\\`').join('```') /* <- TODO: Maybe make propper unescape */;
+                currentCodeBlock.content += line.split('\\`\\`\\`').join('```') /* <- TODO: Maybe make proper unescape */;
             }
         }
         if (currentCodeBlock !== null) {
@@ -1438,8 +1442,8 @@
      *
      * - When there are multiple or no code blocks the function throws a `ParseError`
      *
-     * Note: There are multiple simmilar function:
-     * - `extractBlock` just extracts the content of the code block which is also used as build-in function for postprocessing
+     * Note: There are multiple similar functions:
+     * - `extractBlock` just extracts the content of the code block which is also used as built-in function for postprocessing
      * - `extractJsonBlock` extracts exactly one valid JSON code block
      * - `extractOneBlockFromMarkdown` extracts exactly one code block with language of the code block
      * - `extractAllBlocksFromMarkdown` extracts all code blocks with language of the code block
@@ -1469,7 +1473,7 @@
      *
      * - When there are multiple or no code blocks the function throws a `ParseError`
      *
-     * Note: There are multiple simmilar function:
+     * Note: There are multiple similar function:
      * - `extractBlock` just extracts the content of the code block which is also used as build-in function for postprocessing
      * - `extractJsonBlock` extracts exactly one valid JSON code block
      * - `extractOneBlockFromMarkdown` extracts exactly one code block with language of the code block
@@ -1540,7 +1544,7 @@
         })();
     }
     /**
-     * TODO: Probbably remove in favour of `keepImported`
+     * TODO: Probably remove in favour of `keepImported`
      * TODO: [1] This maybe does memory leak
      */
 
@@ -1744,7 +1748,7 @@
      */
 
     /**
-     * Placeholder for better implementation of JavascriptExecutionTools - some propper sandboxing
+     * Placeholder for better implementation of JavascriptExecutionTools - some proper sandboxing
      *
      * @alias JavascriptExecutionTools
      * @public exported from `@promptbook/javascript`
@@ -1759,7 +1763,11 @@
     // TODO: DRY [🍯]
     const reverse = (str) => str.split('').reverse().join('');
     /**
-     * @@@
+     * Collection of utility functions that can be used for post-processing model outputs.
+     * These functions help transform, extract, or format the raw model responses.
+     *
+     * These utilities range from simple string manipulations to markdown processing
+     * and formatting functions for specific types of output.
      *
      * @public exported from `@promptbook/javascript`
      */