@promptbook/utils 0.92.0-13 → 0.92.0-15

package/esm/index.es.js

@@ -16,7 +16,7 @@ const BOOK_LANGUAGE_VERSION = '1.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.92.0-13';
+const PROMPTBOOK_ENGINE_VERSION = '0.92.0-15';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -87,6 +87,48 @@ Object.freeze({
  * TODO: [🧠][🧜‍♂️] Maybe join remoteServerUrl and path into single value
  */
 
+/**
+ * Orders JSON object by keys
+ *
+ * @returns The same type of object as the input re-ordered
+ * @public exported from `@promptbook/utils`
+ */
+function orderJson(options) {
+    const { value, order } = options;
+    const orderedValue = {
+        ...(order === undefined ? {} : Object.fromEntries(order.map((key) => [key, undefined]))),
+        ...value,
+    };
+    return orderedValue;
+}
+
+/**
+ * Freezes the given object and all its nested objects recursively
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it mutates given object
+ * Note: This function mutates the object and returns the original (but mutated-deep-freezed) object
+ *
+ * @returns The same object as the input, but deeply frozen
+ * @public exported from `@promptbook/utils`
+ */
+function $deepFreeze(objectValue) {
+    if (Array.isArray(objectValue)) {
+        return Object.freeze(objectValue.map((item) => $deepFreeze(item)));
+    }
+    const propertyNames = Object.getOwnPropertyNames(objectValue);
+    for (const propertyName of propertyNames) {
+        const value = objectValue[propertyName];
+        if (value && typeof value === 'object') {
+            $deepFreeze(value);
+        }
+    }
+    Object.freeze(objectValue);
+    return objectValue;
+}
+/**
+ * TODO: [🧠] Is there a way how to meaningfully test this utility
+ */
+
 /**
  * Make error report URL for the given error
  *
@@ -156,153 +198,438 @@ class UnexpectedError extends Error {
 }
 
 /**
- * @@@
+ * This error type indicates that somewhere in the code non-Error object was thrown and it was wrapped into the `WrappedError`
  *
- * @param text @@@
- * @param _isFirstLetterCapital @@@
- * @returns @@@
- * @example 'helloWorld'
- * @example 'iLovePromptbook'
- * @public exported from `@promptbook/utils`
+ * @public exported from `@promptbook/core`
  */
-function normalizeTo_camelCase(text, _isFirstLetterCapital = false) {
-    let charType;
-    let lastCharType = null;
-    let normalizedName = '';
-    for (const char of text) {
-        let normalizedChar;
-        if (/^[a-z]$/.test(char)) {
-            charType = 'LOWERCASE';
-            normalizedChar = char;
-        }
-        else if (/^[A-Z]$/.test(char)) {
-            charType = 'UPPERCASE';
-            normalizedChar = char.toLowerCase();
-        }
-        else if (/^[0-9]$/.test(char)) {
-            charType = 'NUMBER';
-            normalizedChar = char;
-        }
-        else {
-            charType = 'OTHER';
-            normalizedChar = '';
-        }
-        if (!lastCharType) {
-            if (_isFirstLetterCapital) {
-                normalizedChar = normalizedChar.toUpperCase(); //TODO: DRY
-            }
-        }
-        else if (charType !== lastCharType &&
-            !(charType === 'LOWERCASE' && lastCharType === 'UPPERCASE') &&
-            !(lastCharType === 'NUMBER') &&
-            !(charType === 'NUMBER')) {
-            normalizedChar = normalizedChar.toUpperCase(); //TODO: [🌺] DRY
-        }
-        normalizedName += normalizedChar;
-        lastCharType = charType;
+class WrappedError extends Error {
+    constructor(whatWasThrown) {
+        const tag = `[🤮]`;
+        console.error(tag, whatWasThrown);
+        super(spaceTrim$2(`
+                Non-Error object was thrown
+
+                Note: Look for ${tag} in the console for more details
+                Please report issue on ${ADMIN_EMAIL}
+            `));
+        this.name = 'WrappedError';
+        Object.setPrototypeOf(this, WrappedError.prototype);
     }
-    return normalizedName;
 }
-/**
- * TODO: [🌺] Use some intermediate util splitWords
- */
 
 /**
- * Removes emojis from a string and fix whitespaces
+ * Helper used in catch blocks to assert that the error is an instance of `Error`
  *
- * @param text with emojis
- * @returns text without emojis
- * @public exported from `@promptbook/utils`
+ * @param whatWasThrown Any object that was thrown
+ * @returns Nothing if the error is an instance of `Error`
+ * @throws `WrappedError` or `UnexpectedError` if the error is not standard
+ *
+ * @private within the repository
  */
-function removeEmojis(text) {
-    // Replace emojis (and also ZWJ sequence) with hyphens
-    text = text.replace(/(\p{Extended_Pictographic})\p{Modifier_Symbol}/gu, '$1');
-    text = text.replace(/(\p{Extended_Pictographic})[\u{FE00}-\u{FE0F}]/gu, '$1');
-    text = text.replace(/(\p{Extended_Pictographic})(\u{200D}\p{Extended_Pictographic})*/gu, '$1');
-    text = text.replace(/\p{Extended_Pictographic}/gu, '');
-    return text;
+function assertsError(whatWasThrown) {
+    // Case 1: Handle error which was rethrown as `WrappedError`
+    if (whatWasThrown instanceof WrappedError) {
+        const wrappedError = whatWasThrown;
+        throw wrappedError;
+    }
+    // Case 2: Handle unexpected errors
+    if (whatWasThrown instanceof UnexpectedError) {
+        const unexpectedError = whatWasThrown;
+        throw unexpectedError;
+    }
+    // Case 3: Handle standard errors - keep them up to consumer
+    if (whatWasThrown instanceof Error) {
+        return;
+    }
+    // Case 4: Handle non-standard errors - wrap them into `WrappedError` and throw
+    throw new WrappedError(whatWasThrown);
 }
 
 /**
- * Tests if given string is valid URL.
+ * Checks if the value is [🚉] serializable as JSON
+ * If not, throws an UnexpectedError with a rich error message and tracking
  *
- * Note: This does not check if the file exists only if the path is valid
+ * - Almost all primitives are serializable BUT:
+ * - `undefined` is not serializable
+ * - `NaN` is not serializable
+ * - Objects and arrays are serializable if all their properties are serializable
+ * - Functions are not serializable
+ * - Circular references are not serializable
+ * - `Date` objects are not serializable
+ * - `Map` and `Set` objects are not serializable
+ * - `RegExp` objects are not serializable
+ * - `Error` objects are not serializable
+ * - `Symbol` objects are not serializable
+ * - And much more...
+ *
+ * @throws UnexpectedError if the value is not serializable as JSON
  * @public exported from `@promptbook/utils`
  */
-function isValidFilePath(filename) {
-    if (typeof filename !== 'string') {
-        return false;
+function checkSerializableAsJson(options) {
+    const { value, name, message } = options;
+    if (value === undefined) {
+        throw new UnexpectedError(`${name} is undefined`);
     }
-    if (filename.split('\n').length > 1) {
-        return false;
+    else if (value === null) {
+        return;
     }
-    if (filename.split(' ').length >
-        5 /* <- TODO: [🧠][🈷] Make some better non-arbitrary way how to distinct filenames from informational texts */) {
-        return false;
+    else if (typeof value === 'boolean') {
+        return;
     }
-    const filenameSlashes = filename.split('\\').join('/');
-    // Absolute Unix path: /hello.txt
-    if (/^(\/)/i.test(filenameSlashes)) {
-        // console.log(filename, 'Absolute Unix path: /hello.txt');
-        return true;
+    else if (typeof value === 'number' && !isNaN(value)) {
+        return;
     }
-    // Absolute Windows path: /hello.txt
-    if (/^([A-Z]{1,2}:\/?)\//i.test(filenameSlashes)) {
-        // console.log(filename, 'Absolute Windows path: /hello.txt');
-        return true;
+    else if (typeof value === 'string') {
+        return;
     }
-    // Relative path: ./hello.txt
-    if (/^(\.\.?\/)+/i.test(filenameSlashes)) {
-        // console.log(filename, 'Relative path: ./hello.txt');
-        return true;
+    else if (typeof value === 'symbol') {
+        throw new UnexpectedError(`${name} is symbol`);
     }
-    // Allow paths like foo/hello
-    if (/^[^/]+\/[^/]+/i.test(filenameSlashes)) {
-        // console.log(filename, 'Allow paths like foo/hello');
-        return true;
+    else if (typeof value === 'function') {
+        throw new UnexpectedError(`${name} is function`);
     }
-    // Allow paths like hello.book
-    if (/^[^/]+\.[^/]+$/i.test(filenameSlashes)) {
-        // console.log(filename, 'Allow paths like hello.book');
-        return true;
+    else if (typeof value === 'object' && Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+            checkSerializableAsJson({ name: `${name}[${i}]`, value: value[i], message });
+        }
     }
-    return false;
-}
-/**
- * TODO: [🍏] Implement for MacOs
- */
+    else if (typeof value === 'object') {
+        if (value instanceof Date) {
+            throw new UnexpectedError(spaceTrim$1((block) => `
+                        \`${name}\` is Date
 
-/**
- * Tests if given string is valid URL.
- *
- * Note: Dataurl are considered perfectly valid.
- * Note: There are two simmilar functions:
- * - `isValidUrl` which tests any URL
- * - `isValidPipelineUrl` *(this one)* which tests just promptbook URL
- *
- * @public exported from `@promptbook/utils`
- */
-function isValidUrl(url) {
-    if (typeof url !== 'string') {
-        return false;
-    }
-    try {
-        if (url.startsWith('blob:')) {
-            url = url.replace(/^blob:/, '');
+                        Use \`string_date_iso8601\` instead
+
+                        Additional message for \`${name}\`:
+                        ${block(message || '(nothing)')}
+                    `));
         }
-        const urlObject = new URL(url /* because fail is handled */);
-        if (!['http:', 'https:', 'data:'].includes(urlObject.protocol)) {
-            return false;
+        else if (value instanceof Map) {
+            throw new UnexpectedError(`${name} is Map`);
         }
-        return true;
-    }
-    catch (error) {
-        return false;
-    }
-}
+        else if (value instanceof Set) {
+            throw new UnexpectedError(`${name} is Set`);
+        }
+        else if (value instanceof RegExp) {
+            throw new UnexpectedError(`${name} is RegExp`);
+        }
+        else if (value instanceof Error) {
+            throw new UnexpectedError(spaceTrim$1((block) => `
+                        \`${name}\` is unserialized Error
 
-const defaultDiacriticsRemovalMap = [
-    {
+                        Use function \`serializeError\`
+
+                        Additional message for \`${name}\`:
+                        ${block(message || '(nothing)')}
+
+                    `));
+        }
+        else {
+            for (const [subName, subValue] of Object.entries(value)) {
+                if (subValue === undefined) {
+                    // Note: undefined in object is serializable - it is just omited
+                    continue;
+                }
+                checkSerializableAsJson({ name: `${name}.${subName}`, value: subValue, message });
+            }
+            try {
+                JSON.stringify(value); // <- TODO: [0]
+            }
+            catch (error) {
+                assertsError(error);
+                throw new UnexpectedError(spaceTrim$1((block) => `
+                            \`${name}\` is not serializable
+
+                            ${block(error.stack || error.message)}
+
+                            Additional message for \`${name}\`:
+                            ${block(message || '(nothing)')}
+                        `));
+            }
+            /*
+            TODO: [0] Is there some more elegant way to check circular references?
+            const seen = new Set();
+            const stack = [{ value }];
+            while (stack.length > 0) {
+                const { value } = stack.pop()!;
+                if (typeof value === 'object' && value !== null) {
+                    if (seen.has(value)) {
+                        throw new UnexpectedError(`${name} has circular reference`);
+                    }
+                    seen.add(value);
+                    if (Array.isArray(value)) {
+                        stack.push(...value.map((value) => ({ value })));
+                    } else {
+                        stack.push(...Object.values(value).map((value) => ({ value })));
+                    }
+                }
+            }
+            */
+            return;
+        }
+    }
+    else {
+        throw new UnexpectedError(spaceTrim$1((block) => `
+                    \`${name}\` is unknown type
+
+                    Additional message for \`${name}\`:
+                    ${block(message || '(nothing)')}
+                `));
+    }
+}
+/**
+ * TODO: Can be return type more type-safe? like `asserts options.value is JsonValue`
+ * TODO: [🧠][main] !!3 In-memory cache of same values to prevent multiple checks
+ * Note: [🐠] This is how `checkSerializableAsJson` + `isSerializableAsJson` together can just retun true/false or rich error message
+ */
+
+/**
+ * @@@
+ *
+ * @public exported from `@promptbook/utils`
+ */
+function deepClone(objectValue) {
+    return JSON.parse(JSON.stringify(objectValue));
+    /*
+    TODO: [🧠] Is there a better implementation?
+    > const propertyNames = Object.getOwnPropertyNames(objectValue);
+    > for (const propertyName of propertyNames) {
+    >     const value = (objectValue as really_any)[propertyName];
+    >     if (value && typeof value === 'object') {
+    >         deepClone(value);
+    >     }
+    > }
+    > return Object.assign({}, objectValue);
+    */
+}
+/**
+ * TODO: [🧠] Is there a way how to meaningfully test this utility
+ */
+
+/**
+ * Utility to export a JSON object from a function
+ *
+ * 1) Checks if the value is serializable as JSON
+ * 2) Makes a deep clone of the object
+ * 2) Orders the object properties
+ * 2) Deeply freezes the cloned object
+ *
+ * Note: This function does not mutates the given object
+ *
+ * @returns The same type of object as the input but read-only and re-ordered
+ * @public exported from `@promptbook/utils`
+ */
+function exportJson(options) {
+    const { name, value, order, message } = options;
+    checkSerializableAsJson({ name, value, message });
+    const orderedValue = 
+    // TODO: Fix error "Type instantiation is excessively deep and possibly infinite."
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
+    order === undefined
+        ? deepClone(value)
+        : orderJson({
+            value: value,
+            // <- Note: checkSerializableAsJson asserts that the value is serializable as JSON
+            order: order,
+        });
+    $deepFreeze(orderedValue);
+    return orderedValue;
+}
+/**
+ * TODO: [🧠] Is there a way how to meaningfully test this utility
+ */
+
+/**
+ * Nonce which is used for replacing things in strings
+ *
+ * @private within the repository
+ */
+const REPLACING_NONCE = 'ptbkauk42kV2dzao34faw7FudQUHYPtW';
+/**
+ * @@@
+ *
+ * @private within the repository
+ */
+const RESERVED_PARAMETER_MISSING_VALUE = 'MISSING-' + REPLACING_NONCE;
+/**
+ * @@@
+ *
+ * @private within the repository
+ */
+const RESERVED_PARAMETER_RESTRICTED = 'RESTRICTED-' + REPLACING_NONCE;
+/**
+ * The names of the parameters that are reserved for special purposes
+ *
+ * @public exported from `@promptbook/core`
+ */
+const RESERVED_PARAMETER_NAMES = exportJson({
+    name: 'RESERVED_PARAMETER_NAMES',
+    message: `The names of the parameters that are reserved for special purposes`,
+    value: [
+        'content',
+        'context',
+        'knowledge',
+        'examples',
+        'modelName',
+        'currentDate',
+        // <- TODO: list here all command names
+        // <- TODO: Add more like 'date', 'modelName',...
+        // <- TODO: Add [emoji] + instructions ACRY when adding new reserved parameter
+    ],
+});
+/**
+ * Note: [💞] Ignore a discrepancy between file name and entity name
+ */
+
+/**
+ * @@@
+ *
+ * @param text @@@
+ * @param _isFirstLetterCapital @@@
+ * @returns @@@
+ * @example 'helloWorld'
+ * @example 'iLovePromptbook'
+ * @public exported from `@promptbook/utils`
+ */
+function normalizeTo_camelCase(text, _isFirstLetterCapital = false) {
+    let charType;
+    let lastCharType = null;
+    let normalizedName = '';
+    for (const char of text) {
+        let normalizedChar;
+        if (/^[a-z]$/.test(char)) {
+            charType = 'LOWERCASE';
+            normalizedChar = char;
+        }
+        else if (/^[A-Z]$/.test(char)) {
+            charType = 'UPPERCASE';
+            normalizedChar = char.toLowerCase();
+        }
+        else if (/^[0-9]$/.test(char)) {
+            charType = 'NUMBER';
+            normalizedChar = char;
+        }
+        else {
+            charType = 'OTHER';
+            normalizedChar = '';
+        }
+        if (!lastCharType) {
+            if (_isFirstLetterCapital) {
+                normalizedChar = normalizedChar.toUpperCase(); //TODO: DRY
+            }
+        }
+        else if (charType !== lastCharType &&
+            !(charType === 'LOWERCASE' && lastCharType === 'UPPERCASE') &&
+            !(lastCharType === 'NUMBER') &&
+            !(charType === 'NUMBER')) {
+            normalizedChar = normalizedChar.toUpperCase(); //TODO: [🌺] DRY
+        }
+        normalizedName += normalizedChar;
+        lastCharType = charType;
+    }
+    return normalizedName;
+}
+/**
+ * TODO: [🌺] Use some intermediate util splitWords
+ */
+
+/**
+ * Removes emojis from a string and fix whitespaces
+ *
+ * @param text with emojis
+ * @returns text without emojis
+ * @public exported from `@promptbook/utils`
+ */
+function removeEmojis(text) {
+    // Replace emojis (and also ZWJ sequence) with hyphens
+    text = text.replace(/(\p{Extended_Pictographic})\p{Modifier_Symbol}/gu, '$1');
+    text = text.replace(/(\p{Extended_Pictographic})[\u{FE00}-\u{FE0F}]/gu, '$1');
+    text = text.replace(/(\p{Extended_Pictographic})(\u{200D}\p{Extended_Pictographic})*/gu, '$1');
+    text = text.replace(/\p{Extended_Pictographic}/gu, '');
+    return text;
+}
+
+/**
+ * Tests if given string is valid URL.
+ *
+ * Note: This does not check if the file exists only if the path is valid
+ * @public exported from `@promptbook/utils`
+ */
+function isValidFilePath(filename) {
+    if (typeof filename !== 'string') {
+        return false;
+    }
+    if (filename.split('\n').length > 1) {
+        return false;
+    }
+    if (filename.split(' ').length >
+        5 /* <- TODO: [🧠][🈷] Make some better non-arbitrary way how to distinct filenames from informational texts */) {
+        return false;
+    }
+    const filenameSlashes = filename.split('\\').join('/');
+    // Absolute Unix path: /hello.txt
+    if (/^(\/)/i.test(filenameSlashes)) {
+        // console.log(filename, 'Absolute Unix path: /hello.txt');
+        return true;
+    }
+    // Absolute Windows path: /hello.txt
+    if (/^([A-Z]{1,2}:\/?)\//i.test(filenameSlashes)) {
+        // console.log(filename, 'Absolute Windows path: /hello.txt');
+        return true;
+    }
+    // Relative path: ./hello.txt
+    if (/^(\.\.?\/)+/i.test(filenameSlashes)) {
+        // console.log(filename, 'Relative path: ./hello.txt');
+        return true;
+    }
+    // Allow paths like foo/hello
+    if (/^[^/]+\/[^/]+/i.test(filenameSlashes)) {
+        // console.log(filename, 'Allow paths like foo/hello');
+        return true;
+    }
+    // Allow paths like hello.book
+    if (/^[^/]+\.[^/]+$/i.test(filenameSlashes)) {
+        // console.log(filename, 'Allow paths like hello.book');
+        return true;
+    }
+    return false;
+}
+/**
+ * TODO: [🍏] Implement for MacOs
+ */
+
+/**
+ * Tests if given string is valid URL.
+ *
+ * Note: Dataurl are considered perfectly valid.
+ * Note: There are two simmilar functions:
+ * - `isValidUrl` which tests any URL
+ * - `isValidPipelineUrl` *(this one)* which tests just promptbook URL
+ *
+ * @public exported from `@promptbook/utils`
+ */
+function isValidUrl(url) {
+    if (typeof url !== 'string') {
+        return false;
+    }
+    try {
+        if (url.startsWith('blob:')) {
+            url = url.replace(/^blob:/, '');
+        }
+        const urlObject = new URL(url /* because fail is handled */);
+        if (!['http:', 'https:', 'data:'].includes(urlObject.protocol)) {
+            return false;
+        }
+        return true;
+    }
+    catch (error) {
+        return false;
+    }
+}
+
+const defaultDiacriticsRemovalMap = [
+    {
         base: 'A',
         letters: '\u0041\u24B6\uFF21\u00C0\u00C1\u00C2\u1EA6\u1EA4\u1EAA\u1EA8\u00C3\u0100\u0102\u1EB0\u1EAE\u1EB4\u1EB2\u0226\u01E0\u00C4\u01DE\u1EA2\u00C5\u01FA\u01CD\u0200\u0202\u1EA0\u1EAC\u1EB6\u1E00\u0104\u023A\u2C6F',
     },
@@ -647,6 +974,13 @@ function titleToName(value) {
 function renderPromptbookMermaid(pipelineJson, options) {
     const { linkTask = () => null } = options || {};
     const parameterNameToTaskName = (parameterName) => {
+        if (parameterName === 'knowledge') {
+            return 'knowledge';
+            // <- TODO: !!!! Check that this works
+        }
+        else if (RESERVED_PARAMETER_NAMES.includes(parameterName)) {
+            return 'reserved';
+        }
         const parameter = pipelineJson.parameters.find((parameter) => parameter.name === parameterName);
         if (!parameter) {
             throw new UnexpectedError(`Could not find {${parameterName}}`);
@@ -671,6 +1005,8 @@ function renderPromptbookMermaid(pipelineJson, options) {
                   direction TB
 
                   input((Input)):::input
+                  other((Other)):::other
+                  knowledge((Knowledgebase)):::knowledge
                   ${block(pipelineJson.tasks
         .flatMap(({ title, dependentParameterNames, resultingParameterName }) => [
         `${parameterNameToTaskName(resultingParameterName)}("${title}")`,
@@ -799,753 +1135,426 @@ class ExpectError extends Error {
 }
 
 /**
- * This error indicates that the promptbook can not retrieve knowledge from external sources
- *
- * @public exported from `@promptbook/core`
- */
-class KnowledgeScrapeError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'KnowledgeScrapeError';
-        Object.setPrototypeOf(this, KnowledgeScrapeError.prototype);
-    }
-}
-
-/**
- * This error type indicates that some limit was reached
- *
- * @public exported from `@promptbook/core`
- */
-class LimitReachedError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'LimitReachedError';
-        Object.setPrototypeOf(this, LimitReachedError.prototype);
-    }
-}
-
-/**
- * This error type indicates that some tools are missing for pipeline execution or preparation
- *
- * @public exported from `@promptbook/core`
- */
-class MissingToolsError extends Error {
-    constructor(message) {
-        super(spaceTrim$2((block) => `
-                    ${block(message)}
-
-                    Note: You have probbably forgot to provide some tools for pipeline execution or preparation
-
-                `));
-        this.name = 'MissingToolsError';
-        Object.setPrototypeOf(this, MissingToolsError.prototype);
-    }
-}
-
-/**
- * This error indicates that promptbook not found in the collection
- *
- * @public exported from `@promptbook/core`
- */
-class NotFoundError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'NotFoundError';
-        Object.setPrototypeOf(this, NotFoundError.prototype);
-    }
-}
-
-/**
- * This error type indicates that some part of the code is not implemented yet
- *
- * @public exported from `@promptbook/core`
- */
-class NotYetImplementedError extends Error {
-    constructor(message) {
-        super(spaceTrim$2((block) => `
-                    ${block(message)}
-
-                    Note: This feature is not implemented yet but it will be soon.
-
-                    If you want speed up the implementation or just read more, look here:
-                    https://github.com/webgptorg/promptbook
-
-                    Or contact us on pavol@ptbk.io
-
-                `));
-        this.name = 'NotYetImplementedError';
-        Object.setPrototypeOf(this, NotYetImplementedError.prototype);
-    }
-}
-
-/**
- * This error indicates that the promptbook in a markdown format cannot be parsed into a valid promptbook object
- *
- * @public exported from `@promptbook/core`
- */
-class ParseError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'ParseError';
-        Object.setPrototypeOf(this, ParseError.prototype);
-    }
-}
-/**
- * TODO: Maybe split `ParseError` and `ApplyError`
- */
-
-/**
- * Generates random token
- *
- * Note: This function is cryptographically secure (it uses crypto.randomBytes internally)
- *
- * @private internal helper function
- * @returns secure random token
- */
-function $randomToken(randomness) {
-    return randomBytes(randomness).toString('hex');
-}
-/**
- * TODO: Maybe use nanoid instead https://github.com/ai/nanoid
- */
-
-/**
- * This error indicates errors during the execution of the pipeline
- *
- * @public exported from `@promptbook/core`
- */
-class PipelineExecutionError extends Error {
-    constructor(message) {
-        // Added id parameter
-        super(message);
-        this.name = 'PipelineExecutionError';
-        // TODO: [🐙] DRY - Maybe $randomId
-        this.id = `error-${$randomToken(8 /* <- TODO: To global config + Use Base58 to avoid simmilar char conflicts   */)}`;
-        Object.setPrototypeOf(this, PipelineExecutionError.prototype);
-    }
-}
-/**
- * TODO: [🧠][🌂] Add id to all errors
- */
-
-/**
- * This error indicates that the promptbook object has valid syntax (=can be parsed) but contains logical errors (like circular dependencies)
- *
- * @public exported from `@promptbook/core`
- */
-class PipelineLogicError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'PipelineLogicError';
-        Object.setPrototypeOf(this, PipelineLogicError.prototype);
-    }
-}
-
-/**
- * This error indicates errors in referencing promptbooks between each other
+ * This error indicates that the promptbook can not retrieve knowledge from external sources
  *
  * @public exported from `@promptbook/core`
  */
-class PipelineUrlError extends Error {
+class KnowledgeScrapeError extends Error {
     constructor(message) {
         super(message);
-        this.name = 'PipelineUrlError';
-        Object.setPrototypeOf(this, PipelineUrlError.prototype);
+        this.name = 'KnowledgeScrapeError';
+        Object.setPrototypeOf(this, KnowledgeScrapeError.prototype);
     }
 }
 
 /**
- * Error thrown when a fetch request fails
+ * This error type indicates that some limit was reached
  *
  * @public exported from `@promptbook/core`
  */
-class PromptbookFetchError extends Error {
+class LimitReachedError extends Error {
     constructor(message) {
         super(message);
-        this.name = 'PromptbookFetchError';
-        Object.setPrototypeOf(this, PromptbookFetchError.prototype);
+        this.name = 'LimitReachedError';
+        Object.setPrototypeOf(this, LimitReachedError.prototype);
     }
 }
 
 /**
- * This error type indicates that somewhere in the code non-Error object was thrown and it was wrapped into the `WrappedError`
+ * This error type indicates that some tools are missing for pipeline execution or preparation
  *
  * @public exported from `@promptbook/core`
  */
-class WrappedError extends Error {
-    constructor(whatWasThrown) {
-        const tag = `[🤮]`;
-        console.error(tag, whatWasThrown);
-        super(spaceTrim$2(`
-                Non-Error object was thrown
+class MissingToolsError extends Error {
+    constructor(message) {
+        super(spaceTrim$2((block) => `
+                    ${block(message)}
 
-                Note: Look for ${tag} in the console for more details
-                Please report issue on ${ADMIN_EMAIL}
-            `));
-        this.name = 'WrappedError';
-        Object.setPrototypeOf(this, WrappedError.prototype);
+                    Note: You have probbably forgot to provide some tools for pipeline execution or preparation
+
+                `));
+        this.name = 'MissingToolsError';
+        Object.setPrototypeOf(this, MissingToolsError.prototype);
     }
 }
 
 /**
- * Index of all custom errors
+ * This error indicates that promptbook not found in the collection
  *
  * @public exported from `@promptbook/core`
  */
-const PROMPTBOOK_ERRORS = {
-    AbstractFormatError,
-    CsvFormatError,
-    CollectionError,
-    EnvironmentMismatchError,
-    ExpectError,
-    KnowledgeScrapeError,
-    LimitReachedError,
-    MissingToolsError,
-    NotFoundError,
-    NotYetImplementedError,
-    ParseError,
-    PipelineExecutionError,
-    PipelineLogicError,
-    PipelineUrlError,
-    AuthenticationError,
-    PromptbookFetchError,
-    UnexpectedError,
-    WrappedError,
-    // TODO: [🪑]> VersionMismatchError,
-};
-/**
- * Index of all javascript errors
- *
- * @private for internal usage
- */
-const COMMON_JAVASCRIPT_ERRORS = {
-    Error,
-    EvalError,
-    RangeError,
-    ReferenceError,
-    SyntaxError,
-    TypeError,
-    URIError,
-    AggregateError,
-    /*
-  Note: Not widely supported
-  > InternalError,
-  > ModuleError,
-  > HeapError,
-  > WebAssemblyCompileError,
-  > WebAssemblyRuntimeError,
-  */
-};
-/**
- * Index of all errors
- *
- * @private for internal usage
- */
-const ALL_ERRORS = {
-    ...PROMPTBOOK_ERRORS,
-    ...COMMON_JAVASCRIPT_ERRORS,
-};
-/**
- * Note: [💞] Ignore a discrepancy between file name and entity name
- */
-
-/**
- * Deserializes the error object
- *
- * @public exported from `@promptbook/utils`
- */
-function deserializeError(error) {
-    const { name, stack, id } = error; // Added id
-    let { message } = error;
-    let ErrorClass = ALL_ERRORS[error.name];
-    if (ErrorClass === undefined) {
-        ErrorClass = Error;
-        message = `${name}: ${message}`;
-    }
-    if (stack !== undefined && stack !== '') {
-        message = spaceTrim$1((block) => `
-                ${block(message)}
-
-                Original stack trace:
-                ${block(stack || '')}
-            `);
+class NotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NotFoundError';
+        Object.setPrototypeOf(this, NotFoundError.prototype);
     }
-    const deserializedError = new ErrorClass(message);
-    deserializedError.id = id; // Assign id to the error object
-    return deserializedError;
 }
 
 /**
- * Serializes an error into a [🚉] JSON-serializable object
+ * This error type indicates that some part of the code is not implemented yet
  *
- * @public exported from `@promptbook/utils`
+ * @public exported from `@promptbook/core`
  */
-function serializeError(error) {
-    const { name, message, stack } = error;
-    const { id } = error;
-    if (!Object.keys(ALL_ERRORS).includes(name)) {
-        console.error(spaceTrim$1((block) => `
-
-                    Cannot serialize error with name "${name}"
+class NotYetImplementedError extends Error {
+    constructor(message) {
+        super(spaceTrim$2((block) => `
+                    ${block(message)}
 
-                    Authors of Promptbook probably forgot to add this error into the list of errors:
-                    https://github.com/webgptorg/promptbook/blob/main/src/errors/0-index.ts
+                    Note: This feature is not implemented yet but it will be soon.
 
+                    If you want speed up the implementation or just read more, look here:
+                    https://github.com/webgptorg/promptbook
 
-                    ${block(stack || message)}
+                    Or contact us on pavol@ptbk.io
 
                 `));
+        this.name = 'NotYetImplementedError';
+        Object.setPrototypeOf(this, NotYetImplementedError.prototype);
     }
-    return {
-        name: name,
-        message,
-        stack,
-        id, // Include id in the serialized object
-    };
 }
 
 /**
- * Async version of Array.forEach
+ * This error indicates that the promptbook in a markdown format cannot be parsed into a valid promptbook object
  *
- * @param array - Array to iterate over
- * @param options - Options for the function
- * @param callbackfunction - Function to call for each item
- * @public exported from `@promptbook/utils`
- * @deprecated [🪂] Use queues instead
+ * @public exported from `@promptbook/core`
  */
-async function forEachAsync(array, options, callbackfunction) {
-    const { maxParallelCount = Infinity } = options;
-    let index = 0;
-    let runningTasks = [];
-    const tasks = [];
-    for (const item of array) {
-        const currentIndex = index++;
-        const task = callbackfunction(item, currentIndex, array);
-        tasks.push(task);
-        runningTasks.push(task);
-        /* not await */ Promise.resolve(task).then(() => {
-            runningTasks = runningTasks.filter((t) => t !== task);
-        });
-        if (maxParallelCount < runningTasks.length) {
-            await Promise.race(runningTasks);
-        }
+class ParseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ParseError';
+        Object.setPrototypeOf(this, ParseError.prototype);
     }
-    await Promise.all(tasks);
 }
-
 /**
- * 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
+ * TODO: Maybe split `ParseError` and `ApplyError`
  */
-function assertsError(whatWasThrown) {
-    // Case 1: Handle error which was rethrown as `WrappedError`
-    if (whatWasThrown instanceof WrappedError) {
-        const wrappedError = whatWasThrown;
-        throw wrappedError;
-    }
-    // Case 2: Handle unexpected errors
-    if (whatWasThrown instanceof UnexpectedError) {
-        const unexpectedError = whatWasThrown;
-        throw unexpectedError;
-    }
-    // Case 3: Handle standard errors - keep them up to consumer
-    if (whatWasThrown instanceof Error) {
-        return;
-    }
-    // Case 4: Handle non-standard errors - wrap them into `WrappedError` and throw
-    throw new WrappedError(whatWasThrown);
-}
 
 /**
- * Function to check if a string is valid CSV
+ * Generates random token
  *
- * @param value The string to check
- * @returns True if the string is a valid CSV string, false otherwise
+ * Note: This function is cryptographically secure (it uses crypto.randomBytes internally)
  *
- * @public exported from `@promptbook/utils`
+ * @private internal helper function
+ * @returns secure random token
  */
-function isValidCsvString(value) {
-    try {
-        // A simple check for CSV format: at least one comma and no invalid characters
-        if (value.includes(',') && /^[\w\s,"']+$/.test(value)) {
-            return true;
-        }
-        return false;
-    }
-    catch (error) {
-        assertsError(error);
-        return false;
-    }
+function $randomToken(randomness) {
+    return randomBytes(randomness).toString('hex');
 }
+/**
+ * TODO: Maybe use nanoid instead https://github.com/ai/nanoid
+ */
 
 /**
- * Function isValidJsonString will tell you if the string is valid JSON or not
- *
- * @param value The string to check
- * @returns True if the string is a valid JSON string, false otherwise
+ * This error indicates errors during the execution of the pipeline
  *
- * @public exported from `@promptbook/utils`
+ * @public exported from `@promptbook/core`
  */
-function isValidJsonString(value /* <- [👨‍⚖️] */) {
-    try {
-        JSON.parse(value);
-        return true;
-    }
-    catch (error) {
-        assertsError(error);
-        if (error.message.includes('Unexpected token')) {
-            return false;
-        }
-        return false;
+class 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
+ */
 
 /**
- * Converts a JavaScript Object Notation (JSON) string into an object.
- *
- * Note: This is wrapper around `JSON.parse()` with better error and type handling
+ * This error indicates that the promptbook object has valid syntax (=can be parsed) but contains logical errors (like circular dependencies)
  *
- * @public exported from `@promptbook/utils`
+ * @public exported from `@promptbook/core`
  */
-function jsonParse(value) {
-    if (value === undefined) {
-        throw new Error(`Can not parse JSON from undefined value.`);
-    }
-    else if (typeof value !== 'string') {
-        console.error('Can not parse JSON from non-string value.', { text: value });
-        throw new Error(spaceTrim$1(`
-                    Can not parse JSON from non-string value.
-
-                    The value type: ${typeof value}
-                    See more in console.
-                `));
-    }
-    try {
-        return JSON.parse(value);
-    }
-    catch (error) {
-        if (!(error instanceof Error)) {
-            throw error;
-        }
-        throw new Error(spaceTrim$1((block) => `
-                    ${block(error.message)}
-            
-                    The JSON text:
-                    ${block(value)}
-                `));
+class PipelineLogicError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PipelineLogicError';
+        Object.setPrototypeOf(this, PipelineLogicError.prototype);
     }
 }
-/**
- * TODO: !!!! Use in Promptbook.studio
- */
 
 /**
- * Function to check if a string is valid XML
- *
- * @param value
- * @returns True if the string is a valid XML string, false otherwise
+ * This error indicates errors in referencing promptbooks between each other
  *
- * @public exported from `@promptbook/utils`
+ * @public exported from `@promptbook/core`
  */
-function isValidXmlString(value) {
-    try {
-        const parser = new DOMParser();
-        const parsedDocument = parser.parseFromString(value, 'application/xml');
-        const parserError = parsedDocument.getElementsByTagName('parsererror');
-        if (parserError.length > 0) {
-            return false;
-        }
-        return true;
-    }
-    catch (error) {
-        assertsError(error);
-        return false;
+class PipelineUrlError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PipelineUrlError';
+        Object.setPrototypeOf(this, PipelineUrlError.prototype);
     }
 }
 
 /**
- * Orders JSON object by keys
+ * Error thrown when a fetch request fails
  *
- * @returns The same type of object as the input re-ordered
- * @public exported from `@promptbook/utils`
+ * @public exported from `@promptbook/core`
  */
-function orderJson(options) {
-    const { value, order } = options;
-    const orderedValue = {
-        ...(order === undefined ? {} : Object.fromEntries(order.map((key) => [key, undefined]))),
-        ...value,
-    };
-    return orderedValue;
+class PromptbookFetchError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PromptbookFetchError';
+        Object.setPrototypeOf(this, PromptbookFetchError.prototype);
+    }
 }
 
 /**
- * Freezes the given object and all its nested objects recursively
+ * Index of all custom errors
  *
- * Note: `$` is used to indicate that this function is not a pure function - it mutates given object
- * Note: This function mutates the object and returns the original (but mutated-deep-freezed) object
+ * @public exported from `@promptbook/core`
+ */
+const PROMPTBOOK_ERRORS = {
+    AbstractFormatError,
+    CsvFormatError,
+    CollectionError,
+    EnvironmentMismatchError,
+    ExpectError,
+    KnowledgeScrapeError,
+    LimitReachedError,
+    MissingToolsError,
+    NotFoundError,
+    NotYetImplementedError,
+    ParseError,
+    PipelineExecutionError,
+    PipelineLogicError,
+    PipelineUrlError,
+    AuthenticationError,
+    PromptbookFetchError,
+    UnexpectedError,
+    WrappedError,
+    // TODO: [🪑]> VersionMismatchError,
+};
+/**
+ * Index of all javascript errors
  *
- * @returns The same object as the input, but deeply frozen
- * @public exported from `@promptbook/utils`
+ * @private for internal usage
  */
-function $deepFreeze(objectValue) {
-    if (Array.isArray(objectValue)) {
-        return Object.freeze(objectValue.map((item) => $deepFreeze(item)));
-    }
-    const propertyNames = Object.getOwnPropertyNames(objectValue);
-    for (const propertyName of propertyNames) {
-        const value = objectValue[propertyName];
-        if (value && typeof value === 'object') {
-            $deepFreeze(value);
-        }
-    }
-    Object.freeze(objectValue);
-    return objectValue;
-}
+const COMMON_JAVASCRIPT_ERRORS = {
+    Error,
+    EvalError,
+    RangeError,
+    ReferenceError,
+    SyntaxError,
+    TypeError,
+    URIError,
+    AggregateError,
+    /*
+  Note: Not widely supported
+  > InternalError,
+  > ModuleError,
+  > HeapError,
+  > WebAssemblyCompileError,
+  > WebAssemblyRuntimeError,
+  */
+};
 /**
- * TODO: [🧠] Is there a way how to meaningfully test this utility
+ * Index of all errors
+ *
+ * @private for internal usage
+ */
+const ALL_ERRORS = {
+    ...PROMPTBOOK_ERRORS,
+    ...COMMON_JAVASCRIPT_ERRORS,
+};
+/**
+ * Note: [💞] Ignore a discrepancy between file name and entity name
  */
 
 /**
- * Checks if the value is [🚉] serializable as JSON
- * If not, throws an UnexpectedError with a rich error message and tracking
- *
- * - Almost all primitives are serializable BUT:
- * - `undefined` is not serializable
- * - `NaN` is not serializable
- * - Objects and arrays are serializable if all their properties are serializable
- * - Functions are not serializable
- * - Circular references are not serializable
- * - `Date` objects are not serializable
- * - `Map` and `Set` objects are not serializable
- * - `RegExp` objects are not serializable
- * - `Error` objects are not serializable
- * - `Symbol` objects are not serializable
- * - And much more...
+ * Deserializes the error object
  *
- * @throws UnexpectedError if the value is not serializable as JSON
  * @public exported from `@promptbook/utils`
  */
-function checkSerializableAsJson(options) {
-    const { value, name, message } = options;
-    if (value === undefined) {
-        throw new UnexpectedError(`${name} is undefined`);
-    }
-    else if (value === null) {
-        return;
-    }
-    else if (typeof value === 'boolean') {
-        return;
-    }
-    else if (typeof value === 'number' && !isNaN(value)) {
-        return;
-    }
-    else if (typeof value === 'string') {
-        return;
-    }
-    else if (typeof value === 'symbol') {
-        throw new UnexpectedError(`${name} is symbol`);
-    }
-    else if (typeof value === 'function') {
-        throw new UnexpectedError(`${name} is function`);
-    }
-    else if (typeof value === 'object' && Array.isArray(value)) {
-        for (let i = 0; i < value.length; i++) {
-            checkSerializableAsJson({ name: `${name}[${i}]`, value: value[i], message });
-        }
+function deserializeError(error) {
+    const { name, stack, id } = error; // Added id
+    let { message } = error;
+    let ErrorClass = ALL_ERRORS[error.name];
+    if (ErrorClass === undefined) {
+        ErrorClass = Error;
+        message = `${name}: ${message}`;
     }
-    else if (typeof value === 'object') {
-        if (value instanceof Date) {
-            throw new UnexpectedError(spaceTrim$1((block) => `
-                        \`${name}\` is Date
-
-                        Use \`string_date_iso8601\` instead
+    if (stack !== undefined && stack !== '') {
+        message = spaceTrim$1((block) => `
+                ${block(message)}
 
-                        Additional message for \`${name}\`:
-                        ${block(message || '(nothing)')}
-                    `));
-        }
-        else if (value instanceof Map) {
-            throw new UnexpectedError(`${name} is Map`);
-        }
-        else if (value instanceof Set) {
-            throw new UnexpectedError(`${name} is Set`);
-        }
-        else if (value instanceof RegExp) {
-            throw new UnexpectedError(`${name} is RegExp`);
-        }
-        else if (value instanceof Error) {
-            throw new UnexpectedError(spaceTrim$1((block) => `
-                        \`${name}\` is unserialized Error
+                Original stack trace:
+                ${block(stack || '')}
+            `);
+    }
+    const deserializedError = new ErrorClass(message);
+    deserializedError.id = id; // Assign id to the error object
+    return deserializedError;
+}
 
-                        Use function \`serializeError\`
+/**
+ * Serializes an error into a [🚉] JSON-serializable object
+ *
+ * @public exported from `@promptbook/utils`
+ */
+function serializeError(error) {
+    const { name, message, stack } = error;
+    const { id } = error;
+    if (!Object.keys(ALL_ERRORS).includes(name)) {
+        console.error(spaceTrim$1((block) => `
 
-                        Additional message for \`${name}\`:
-                        ${block(message || '(nothing)')}
+                    Cannot serialize error with name "${name}"
 
-                    `));
-        }
-        else {
-            for (const [subName, subValue] of Object.entries(value)) {
-                if (subValue === undefined) {
-                    // Note: undefined in object is serializable - it is just omited
-                    continue;
-                }
-                checkSerializableAsJson({ name: `${name}.${subName}`, value: subValue, message });
-            }
-            try {
-                JSON.stringify(value); // <- TODO: [0]
-            }
-            catch (error) {
-                assertsError(error);
-                throw new UnexpectedError(spaceTrim$1((block) => `
-                            \`${name}\` is not serializable
+                    Authors of Promptbook probably forgot to add this error into the list of errors:
+                    https://github.com/webgptorg/promptbook/blob/main/src/errors/0-index.ts
 
-                            ${block(error.stack || error.message)}
 
-                            Additional message for \`${name}\`:
-                            ${block(message || '(nothing)')}
-                        `));
-            }
-            /*
-            TODO: [0] Is there some more elegant way to check circular references?
-            const seen = new Set();
-            const stack = [{ value }];
-            while (stack.length > 0) {
-                const { value } = stack.pop()!;
-                if (typeof value === 'object' && value !== null) {
-                    if (seen.has(value)) {
-                        throw new UnexpectedError(`${name} has circular reference`);
-                    }
-                    seen.add(value);
-                    if (Array.isArray(value)) {
-                        stack.push(...value.map((value) => ({ value })));
-                    } else {
-                        stack.push(...Object.values(value).map((value) => ({ value })));
-                    }
-                }
-            }
-            */
-            return;
-        }
-    }
-    else {
-        throw new UnexpectedError(spaceTrim$1((block) => `
-                    \`${name}\` is unknown type
+                    ${block(stack || message)}
 
-                    Additional message for \`${name}\`:
-                    ${block(message || '(nothing)')}
                 `));
     }
+    return {
+        name: name,
+        message,
+        stack,
+        id, // Include id in the serialized object
+    };
 }
-/**
- * TODO: Can be return type more type-safe? like `asserts options.value is JsonValue`
- * TODO: [🧠][main] !!3 In-memory cache of same values to prevent multiple checks
- * Note: [🐠] This is how `checkSerializableAsJson` + `isSerializableAsJson` together can just retun true/false or rich error message
- */
 
 /**
- * @@@
+ * Async version of Array.forEach
  *
+ * @param array - Array to iterate over
+ * @param options - Options for the function
+ * @param callbackfunction - Function to call for each item
  * @public exported from `@promptbook/utils`
+ * @deprecated [🪂] Use queues instead
  */
-function deepClone(objectValue) {
-    return JSON.parse(JSON.stringify(objectValue));
-    /*
-    TODO: [🧠] Is there a better implementation?
-    > const propertyNames = Object.getOwnPropertyNames(objectValue);
-    > for (const propertyName of propertyNames) {
-    >     const value = (objectValue as really_any)[propertyName];
-    >     if (value && typeof value === 'object') {
-    >         deepClone(value);
-    >     }
-    > }
-    > return Object.assign({}, objectValue);
-    */
+async function forEachAsync(array, options, callbackfunction) {
+    const { maxParallelCount = Infinity } = options;
+    let index = 0;
+    let runningTasks = [];
+    const tasks = [];
+    for (const item of array) {
+        const currentIndex = index++;
+        const task = callbackfunction(item, currentIndex, array);
+        tasks.push(task);
+        runningTasks.push(task);
+        /* not await */ Promise.resolve(task).then(() => {
+            runningTasks = runningTasks.filter((t) => t !== task);
+        });
+        if (maxParallelCount < runningTasks.length) {
+            await Promise.race(runningTasks);
+        }
+    }
+    await Promise.all(tasks);
 }
-/**
- * TODO: [🧠] Is there a way how to meaningfully test this utility
- */
 
 /**
- * Utility to export a JSON object from a function
- *
- * 1) Checks if the value is serializable as JSON
- * 2) Makes a deep clone of the object
- * 2) Orders the object properties
- * 2) Deeply freezes the cloned object
+ * Function to check if a string is valid CSV
  *
- * Note: This function does not mutates the given object
+ * @param value The string to check
+ * @returns True if the string is a valid CSV string, false otherwise
  *
- * @returns The same type of object as the input but read-only and re-ordered
  * @public exported from `@promptbook/utils`
  */
-function exportJson(options) {
-    const { name, value, order, message } = options;
-    checkSerializableAsJson({ name, value, message });
-    const orderedValue = 
-    // TODO: Fix error "Type instantiation is excessively deep and possibly infinite."
-    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-    // @ts-ignore
-    order === undefined
-        ? deepClone(value)
-        : orderJson({
-            value: value,
-            // <- Note: checkSerializableAsJson asserts that the value is serializable as JSON
-            order: order,
-        });
-    $deepFreeze(orderedValue);
-    return orderedValue;
+function isValidCsvString(value) {
+    try {
+        // A simple check for CSV format: at least one comma and no invalid characters
+        if (value.includes(',') && /^[\w\s,"']+$/.test(value)) {
+            return true;
+        }
+        return false;
+    }
+    catch (error) {
+        assertsError(error);
+        return false;
+    }
 }
-/**
- * TODO: [🧠] Is there a way how to meaningfully test this utility
- */
 
 /**
- * Nonce which is used for replacing things in strings
+ * Function isValidJsonString will tell you if the string is valid JSON or not
  *
- * @private within the repository
- */
-const REPLACING_NONCE = 'ptbkauk42kV2dzao34faw7FudQUHYPtW';
-/**
- * @@@
+ * @param value The string to check
+ * @returns True if the string is a valid JSON string, false otherwise
  *
- * @private within the repository
+ * @public exported from `@promptbook/utils`
  */
-const RESERVED_PARAMETER_MISSING_VALUE = 'MISSING-' + REPLACING_NONCE;
+function isValidJsonString(value /* <- [👨‍⚖️] */) {
+    try {
+        JSON.parse(value);
+        return true;
+    }
+    catch (error) {
+        assertsError(error);
+        if (error.message.includes('Unexpected token')) {
+            return false;
+        }
+        return false;
+    }
+}
+
 /**
- * @@@
+ * Converts a JavaScript Object Notation (JSON) string into an object.
  *
- * @private within the repository
+ * Note: This is wrapper around `JSON.parse()` with better error and type handling
+ *
+ * @public exported from `@promptbook/utils`
  */
-const RESERVED_PARAMETER_RESTRICTED = 'RESTRICTED-' + REPLACING_NONCE;
+function jsonParse(value) {
+    if (value === undefined) {
+        throw new Error(`Can not parse JSON from undefined value.`);
+    }
+    else if (typeof value !== 'string') {
+        console.error('Can not parse JSON from non-string value.', { text: value });
+        throw new Error(spaceTrim$1(`
+                    Can not parse JSON from non-string value.
+
+                    The value type: ${typeof value}
+                    See more in console.
+                `));
+    }
+    try {
+        return JSON.parse(value);
+    }
+    catch (error) {
+        if (!(error instanceof Error)) {
+            throw error;
+        }
+        throw new Error(spaceTrim$1((block) => `
+                    ${block(error.message)}
+            
+                    The JSON text:
+                    ${block(value)}
+                `));
+    }
+}
 /**
- * The names of the parameters that are reserved for special purposes
- *
- * @public exported from `@promptbook/core`
+ * TODO: !!!! Use in Promptbook.studio
  */
-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
+ * Function to check if a string is valid XML
+ *
+ * @param value
+ * @returns True if the string is a valid XML string, false otherwise
+ *
+ * @public exported from `@promptbook/utils`
  */
+function isValidXmlString(value) {
+    try {
+        const parser = new DOMParser();
+        const parsedDocument = parser.parseFromString(value, 'application/xml');
+        const parserError = parsedDocument.getElementsByTagName('parsererror');
+        if (parserError.length > 0) {
+            return false;
+        }
+        return true;
+    }
+    catch (error) {
+        assertsError(error);
+        return false;
+    }
+}
 
 /**
  * Format either small or big number