@promptbook/javascript 0.92.0-9 → 0.93.0

package/esm/index.es.js

@@ -19,7 +19,7 @@ const BOOK_LANGUAGE_VERSION = '1.0.0';
  * @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
@@ -75,7 +75,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`
  */
@@ -90,6 +90,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
  *
@@ -145,7 +187,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)}
@@ -159,70 +201,341 @@ 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/core`
+ */
+class WrappedError extends Error {
+    constructor(whatWasThrown) {
+        const tag = `[🤮]`;
+        console.error(tag, whatWasThrown);
+        super(spaceTrim$1(`
+                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((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((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((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((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;
 }
 
@@ -453,472 +766,163 @@ for (let i = 0; i < defaultDiacriticsRemovalMap.length; i++) {
     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 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$1(`
-                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((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((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((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((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 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
@@ -1100,10 +1104,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`
@@ -1170,11 +1174,11 @@ function parseKeywordsFromString(input) {
 }
 
 /**
- * @@@
+ * 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) {
@@ -1188,11 +1192,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) {
@@ -1214,10 +1218,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`
@@ -1238,9 +1242,9 @@ function normalizeWhitespaces(sentence) {
 /**
  * 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
  *
@@ -1252,7 +1256,7 @@ 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;
@@ -1261,7 +1265,7 @@ function removeQuotes(text) {
 /**
  * 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`
@@ -1280,7 +1284,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`
@@ -1295,9 +1299,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
  *
@@ -1366,8 +1370,8 @@ function unwrapResult(text, options) {
 /**
  * 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
@@ -1417,7 +1421,7 @@ function extractAllBlocksFromMarkdown(markdown) {
             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) {
@@ -1434,8 +1438,8 @@ function extractAllBlocksFromMarkdown(markdown) {
  *
  * - 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
@@ -1465,7 +1469,7 @@ function extractOneBlockFromMarkdown(markdown) {
  *
  * - 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
@@ -1536,7 +1540,7 @@ function preserve(func) {
     })();
 }
 /**
- * TODO: Probbably remove in favour of `keepImported`
+ * TODO: Probably remove in favour of `keepImported`
  * TODO: [1] This maybe does memory leak
  */
 
@@ -1740,7 +1744,7 @@ class JavascriptEvalExecutionTools {
  */
 
 /**
- * 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`
@@ -1755,7 +1759,11 @@ const trim = (str) => str.trim();
 // 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`
  */