@promptbook/utils 0.112.0-32 → 0.112.0-35

package/esm/index.es.js

@@ -18,7 +18,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.112.0-32';
+const PROMPTBOOK_ENGINE_VERSION = '0.112.0-35';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -28,16 +28,20 @@ const PROMPTBOOK_ENGINE_VERSION = '0.112.0-32';
  * Trims string from all 4 sides
  *
  * Note: This is a re-exported function from the `spacetrim` package which is
- *       Developed by same author @hejny as this package
+ * Developed by same author @hejny as this package
  *
- * @public exported from `@promptbook/utils`
  * @see https://github.com/hejny/spacetrim#usage
+ *
+ * @public exported from `@promptbook/utils`
  */
 const spaceTrim = spaceTrim$1;
 
 /**
- * @private util of `@promptbook/color`
+ * Class implementing take chain.
+ *
  * @de
+ *
+ * @private util of `@promptbook/color`
  */
 class TakeChain {
     constructor(value) {
@@ -54,9 +58,9 @@ class TakeChain {
  *
  * @param {*} initialValue - The initial value.
  * @returns {Proxy<WithTake<TValue>>} - A proxy object with a `take` method.
+ * @deprecated [🤡] Use some better functional library instead of `TakeChain`
  *
  * @private util of `@promptbook/color`
- * @deprecated [🤡] Use some better functional library instead of `TakeChain`
  */
 function take(initialValue) {
     if (initialValue instanceof TakeChain) {
@@ -234,9 +238,7 @@ const CSS_COLORS = {
     yellow: '#ffff00',
     yellowgreen: '#9acd32',
 };
-/**
- * Note: [💞] Ignore a discrepancy between file name and entity name
- */
+// Note: [💞] Ignore a discrepancy between file name and entity name
 
 /**
  * Validates that a channel value is a valid number within the range of 0 to 255.
@@ -266,7 +268,13 @@ function checkChannelValue(channelName, value) {
     }
 }
 
+/**
+ * Constant for short hex lengths.
+ */
 const SHORT_HEX_LENGTHS = new Set([3, 4]);
+/**
+ * Constant for long hex lengths.
+ */
 const LONG_HEX_LENGTHS = new Set([6, 8]);
 /**
  * Parses a hex string into RGBA channel values.
@@ -299,6 +307,9 @@ function parseHexColor(hex) {
     }
     return throwInvalidHex();
 }
+/**
+ * Parses short hex channel.
+ */
 function parseShortHexChannel(char, onError) {
     if (!char) {
         return onError();
@@ -309,6 +320,9 @@ function parseShortHexChannel(char, onError) {
     }
     return parsed * 16;
 }
+/**
+ * Parses long hex channel.
+ */
 function parseLongHexChannel(hex, start, onError) {
     const segment = hex.substr(start, 2);
     if (segment.length < 2) {
@@ -321,6 +335,9 @@ function parseLongHexChannel(hex, start, onError) {
     return parsed;
 }
 
+/**
+ * Pattern matching hsl.
+ */
 const HSL_REGEX = /^hsl\(\s*([0-9.]+)\s*,\s*([0-9.]+)%\s*,\s*([0-9.]+)%\s*\)$/;
 /**
  * Parses an HSL string into RGBA channel values.
@@ -346,6 +363,9 @@ function parseHslColor(hsl) {
         alpha: 255,
     };
 }
+/**
+ * Handles convert hsl to Rgb.
+ */
 function convertHslToRgb(h, s, l) {
     const c = (1 - Math.abs(2 * l - 1)) * s;
     const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
@@ -384,7 +404,13 @@ function convertHslToRgb(h, s, l) {
     };
 }
 
+/**
+ * Pattern matching RGB.
+ */
 const RGB_REGEX = /^rgb\(\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*\)$/;
+/**
+ * Pattern matching rgba.
+ */
 const RGBA_REGEX = /^rgba\(\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*\)$/;
 /**
  * Parses an RGB string into RGBA channel values.
@@ -426,6 +452,9 @@ function parseRgbaColor(rgba) {
         alpha: parseAlphaValue(match[4]),
     };
 }
+/**
+ * Parses channel value.
+ */
 function parseChannelValue(value) {
     if (value.endsWith('%')) {
         const percent = parseFloat(value);
@@ -433,6 +462,9 @@ function parseChannelValue(value) {
     }
     return Math.round(parseFloat(value));
 }
+/**
+ * Parses alpha value.
+ */
 function parseAlphaValue(value) {
     if (value.endsWith('%')) {
         const percent = parseFloat(value);
@@ -445,8 +477,17 @@ function parseAlphaValue(value) {
     return Math.round(parsed);
 }
 
+/**
+ * Pattern matching hsl regex.
+ */
 const HSL_REGEX_PATTERN = /^hsl\(\s*([0-9.]+)\s*,\s*([0-9.]+)%\s*,\s*([0-9.]+)%\s*\)$/;
+/**
+ * Pattern matching RGB regex.
+ */
 const RGB_REGEX_PATTERN = /^rgb\(\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*\)$/;
+/**
+ * Pattern matching rgba regex.
+ */
 const RGBA_REGEX_PATTERN = /^rgba\(\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*\)$/;
 /**
  * Color object represents an RGB color with alpha channel
@@ -812,9 +853,7 @@ function hslToRgb(hue, saturation, lightness) {
     }
     return [Math.round(red * 255), Math.round(green * 255), Math.round(blue * 255)];
 }
-/**
- * TODO: Properly name all used internal variables
- */
+// TODO: Properly name all used internal variables
 
 /**
  * Converts RGB values to HSL values
@@ -860,9 +899,7 @@ function rgbToHsl(red, green, blue) {
     }
     return [hue, saturation, lightness];
 }
-/**
- * TODO: Properly name all used internal variables
- */
+// TODO: Properly name all used internal variables
 
 /**
  * Makes color transformer which lighten the given color
@@ -880,9 +917,7 @@ function lighten(amount) {
         return Color.fromValues(r, g, b, alpha);
     };
 }
-/**
- * TODO: Maybe implement by mix+hsl
- */
+// TODO: Maybe implement by mix+hsl
 
 /**
  * Makes color transformer which saturate the given color
@@ -900,9 +935,7 @@ function saturate(amount) {
         return Color.fromValues(r, g, b, alpha);
     };
 }
-/**
- * TODO: Maybe implement by mix+hsl
- */
+// TODO: Maybe implement by mix+hsl
 
 /**
  * Name for the Promptbook
@@ -1026,6 +1059,7 @@ parseInt(process.env.API_REQUEST_TIMEOUT || '90000');
  * Orders JSON object by keys
  *
  * @returns The same type of object as the input re-ordered
+ *
  * @public exported from `@promptbook/utils`
  */
 function orderJson(options) {
@@ -1044,6 +1078,7 @@ function orderJson(options) {
  * 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) {
@@ -1060,9 +1095,7 @@ function $deepFreeze(objectValue) {
     Object.freeze(objectValue);
     return objectValue;
 }
-/**
- * TODO: [🧠] Is there a way how to meaningfully test this utility
- */
+// TODO: [🧠] Is there a way how to meaningfully test this utility
 
 /**
  * Make error report URL for the given error
@@ -1198,6 +1231,7 @@ function assertsError(whatWasThrown) {
  * - And much more...
  *
  * @throws UnexpectedError if the value is not serializable as JSON
+ *
  * @public exported from `@promptbook/utils`
  */
 function checkSerializableAsJson(options) {
@@ -1312,11 +1346,9 @@ function checkSerializableAsJson(options) {
                 `));
     }
 }
-/**
- * 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
- */
+// TODO: Can be return type more type-safe? like `asserts options.value is JsonValue`
+// TODO: [🧠][main] !!3 In-memory cache of same values to prevent multiple checks
+// Note: [🐠] This is how `checkSerializableAsJson` + `isSerializableAsJson` together can just retun true/false or rich error message
 
 /**
  * Creates a deep clone of the given object
@@ -1326,6 +1358,7 @@ function checkSerializableAsJson(options) {
  *
  * @param objectValue The object to clone.
  * @returns A deep, writable clone of the input object.
+ *
  * @public exported from `@promptbook/utils`
  */
 function deepClone(objectValue) {
@@ -1342,9 +1375,7 @@ function deepClone(objectValue) {
     > return Object.assign({}, objectValue);
     */
 }
-/**
- * TODO: [🧠] Is there a way how to meaningfully test this utility
- */
+// TODO: [🧠] Is there a way how to meaningfully test this utility
 
 /**
  * Utility to export a JSON object from a function
@@ -1357,6 +1388,7 @@ function deepClone(objectValue) {
  * 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) {
@@ -1376,9 +1408,7 @@ function exportJson(options) {
     $deepFreeze(orderedValue);
     return orderedValue;
 }
-/**
- * TODO: [🧠] Is there a way how to meaningfully test this utility
- */
+// TODO: [🧠] Is there a way how to meaningfully test this utility
 
 /**
  * Nonce which is used for replacing things in strings
@@ -1418,9 +1448,7 @@ const RESERVED_PARAMETER_NAMES = exportJson({
         // <- TODO: Add [emoji] + instructions ACRY when adding new reserved parameter
     ],
 });
-/**
- * Note: [💞] Ignore a discrepancy between file name and entity name
- */
+// Note: [💞] Ignore a discrepancy between file name and entity name
 
 /**
  * Normalizes a given text to camelCase format.
@@ -1432,6 +1460,7 @@ const RESERVED_PARAMETER_NAMES = exportJson({
  * @returns The camelCase formatted string.
  * @example 'helloWorld'
  * @example 'iLovePromptbook'
+ *
  * @public exported from `@promptbook/utils`
  */
 function normalizeTo_camelCase(text, _isFirstLetterCapital = false) {
@@ -1472,14 +1501,13 @@ function normalizeTo_camelCase(text, _isFirstLetterCapital = false) {
     }
     return normalizedName;
 }
-/**
- * TODO: [🌺] Use some intermediate util splitWords
- */
+// TODO: [🌺] Use some intermediate util splitWords
 
 /**
  * Tests if given string is valid file path.
  *
  * Note: This does not check if the file exists only if the path is valid
+ *
  * @public exported from `@promptbook/utils`
  */
 function isValidFilePath(filename) {
@@ -1528,9 +1556,7 @@ function isValidFilePath(filename) {
     }
     return false;
 }
-/**
- * TODO: [🍏] Implement for MacOs
- */
+// TODO: [🍏] Implement for MacOs
 
 /**
  * Tests if given string is valid URL.
@@ -1563,6 +1589,9 @@ function isValidUrl(url) {
     }
 }
 
+/**
+ * Collection of default diacritics removal map.
+ */
 const defaultDiacriticsRemovalMap = [
     {
         base: 'A',
@@ -1814,6 +1843,7 @@ for (let i = 0; i < defaultDiacriticsRemovalMap.length; i++) {
  *
  * @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) {
@@ -1822,9 +1852,7 @@ function removeDiacritics(input) {
         return DIACRITIC_VARIANTS_LETTERS[character] || character;
     });
 }
-/**
- * TODO: [Ж] Variant for cyrillic (and in general non-latin) letters
- */
+// TODO: [Ж] Variant for cyrillic (and in general non-latin) letters
 
 /**
  * Converts a given text to kebab-case format.
@@ -1835,6 +1863,7 @@ function removeDiacritics(input) {
  * @returns The kebab-case formatted string.
  * @example 'hello-world'
  * @example 'i-love-promptbook'
+ *
  * @public exported from `@promptbook/utils`
  */
 function normalizeToKebabCase(text) {
@@ -1875,9 +1904,7 @@ function normalizeToKebabCase(text) {
     normalizedName = normalizedName.replace(/-$/, '');
     return normalizedName;
 }
-/**
- * Note: [💞] Ignore a discrepancy between file name and entity name
- */
+// Note: [💞] Ignore a discrepancy between file name and entity name
 
 /**
  * Removes emojis from a string and fix whitespaces
@@ -1886,6 +1913,7 @@ function normalizeToKebabCase(text) {
  *
  * @param text with emojis
  * @returns text without emojis
+ *
  * @public exported from `@promptbook/utils`
  */
 function removeEmojis(text) {
@@ -1905,6 +1933,7 @@ function removeEmojis(text) {
  * @param value The title string to be converted to a name.
  * @returns A normalized name derived from the input title.
  * @example 'Hello World!' -> 'hello-world'
+ *
  * @public exported from `@promptbook/utils`
  */
 function titleToName(value) {
@@ -2023,13 +2052,11 @@ function renderPromptbookMermaid(pipelineJson, options) {
         `);
     return promptbookMermaid;
 }
-/**
- * TODO: [🧠] FOREACH in mermaid graph
- * TODO: [🧠] Knowledge in mermaid graph
- * TODO: [🧠] Personas in mermaid graph
- * TODO: Maybe use some Mermaid package instead of string templating
- * TODO: [🕌] When more than 2 functionalities, split into separate functions
- */
+// TODO: [🧠] FOREACH in mermaid graph
+// TODO: [🧠] Knowledge in mermaid graph
+// TODO: [🧠] Personas in mermaid graph
+// TODO: Maybe use some Mermaid package instead of string templating
+// TODO: [🕌] When more than 2 functionalities, split into separate functions
 
 /**
  * This error indicates problems parsing the format value
@@ -2112,9 +2139,7 @@ class DatabaseError extends Error {
         Object.setPrototypeOf(this, DatabaseError.prototype);
     }
 }
-/**
- * TODO: [🐱‍🚀] Explain that NotFoundError ([🐱‍🚀] and other specific errors) has priority over DatabaseError in some contexts
- */
+// TODO: [🐱‍🚀] Explain that NotFoundError ([🐱‍🚀] and other specific errors) has priority over DatabaseError in some contexts
 
 /**
  * This error type indicates that you try to use a feature that is not available in the current environment
@@ -2132,10 +2157,11 @@ class EnvironmentMismatchError extends Error {
 /**
  * This error occurs when some expectation is not met in the execution of the pipeline
  *
- * @public exported from `@promptbook/core`
  * Note: Do not throw this error, its reserved for `checkExpectations` and `createPipelineExecutor` and public ONLY to be serializable through remote server
  * Note: Always thrown in `checkExpectations` and catched in `createPipelineExecutor` and rethrown as `PipelineExecutionError`
  * Note: This is a kindof subtype of PipelineExecutionError
+ *
+ * @public exported from `@promptbook/core`
  */
 class ExpectError extends Error {
     constructor(message) {
@@ -2250,9 +2276,7 @@ class ParseError extends Error {
         Object.setPrototypeOf(this, ParseError.prototype);
     }
 }
-/**
- * TODO: Maybe split `ParseError` and `ApplyError`
- */
+// TODO: Maybe split `ParseError` and `ApplyError`
 
 /**
  * Generates random token
@@ -2260,16 +2284,15 @@ class ParseError extends Error {
  * Note: `$` is used to indicate that this function is not a pure function - it is not deterministic
  * Note: This function is cryptographically secure (it uses crypto.randomBytes internally)
  *
- * @private internal helper function
  * @returns secure random token
+ *
+ * @private internal helper function
  */
 function $randomToken(randomness) {
     return randomBytes(randomness).toString('hex');
 }
-/**
- * TODO: [🤶] Maybe export through `@promptbook/utils` or `@promptbook/random` package
- * TODO: Maybe use nanoid instead https://github.com/ai/nanoid
- */
+// TODO: [🤶] Maybe export through `@promptbook/utils` or `@promptbook/random` package
+// TODO: Maybe use nanoid instead https://github.com/ai/nanoid
 
 /**
  * This error indicates errors during the execution of the pipeline
@@ -2286,9 +2309,7 @@ class PipelineExecutionError extends Error {
         Object.setPrototypeOf(this, PipelineExecutionError.prototype);
     }
 }
-/**
- * TODO: [🧠][🌂] Add id to all errors
- */
+// 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)
@@ -2390,9 +2411,7 @@ const ALL_ERRORS = {
     ...PROMPTBOOK_ERRORS,
     ...COMMON_JAVASCRIPT_ERRORS,
 };
-/**
- * Note: [💞] Ignore a discrepancy between file name and entity name
- */
+// Note: [💞] Ignore a discrepancy between file name and entity name
 
 /**
  * Deserializes the error object
@@ -2455,8 +2474,9 @@ function serializeError(error) {
  * @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/utils`
  */
 async function forEachAsync(array, options, callbackfunction) {
     const { maxParallelCount = Infinity } = options;
@@ -2615,8 +2635,8 @@ function numberToString(value) {
  * This is useful and used in the `templateParameters` function
  *
  * Note: This function is not just calling `toString` method
- *       It's more complex and can handle this conversion specifically for LLM models
- *       See `VALUE_STRINGS`
+ * It's more complex and can handle this conversion specifically for LLM models
+ * See `VALUE_STRINGS`
  *
  * Note: There are 2 similar functions
  * - `valueToString` converts value to string for LLM models as human-readable string
@@ -2667,12 +2687,13 @@ function valueToString(value) {
  * Replaces parameters in template with values from parameters object
  *
  * Note: This function is not places strings into string,
- *       It's more complex and can handle this operation specifically for LLM models
+ * It's more complex and can handle this operation specifically for LLM models
  *
  * @param template the template with parameters in {curly} braces
  * @param parameters the object with parameters
  * @returns the template with replaced parameters
  * @throws {PipelineExecutionError} if parameter is not defined, not closed, or not opened
+ *
  * @public exported from `@promptbook/utils`
  */
 function templateParameters(template, parameters) {
@@ -2756,6 +2777,7 @@ const PROMPT_PARAMETER_ESCAPE_WITH_BRACES_PATTERN = /[{}$`]/g;
  * Normalizes a JSON string so it can be safely rendered without double escaping.
  *
  * @param value Candidate JSON string.
+ *
  * @private function of ParameterEscaping
  */
 function normalizeJsonString(value) {
@@ -2770,6 +2792,7 @@ function normalizeJsonString(value) {
  * Hides brackets in a string to avoid confusion with template parameters.
  *
  * @param value Input string with literal brackets.
+ *
  * @private function of ParameterEscaping
  */
 function hideBrackets(value) {
@@ -2779,6 +2802,7 @@ function hideBrackets(value) {
  * Restores hidden brackets.
  *
  * @param value String with hidden brackets.
+ *
  * @private function of ParameterEscaping
  */
 function restoreBrackets(value) {
@@ -2788,6 +2812,7 @@ function restoreBrackets(value) {
  * Decides whether a parameter can be inlined safely.
  *
  * @param value Parameter rendered as string.
+ *
  * @private function of ParameterEscaping
  */
 function shouldInlineParameterValue(value) {
@@ -2801,6 +2826,7 @@ function shouldInlineParameterValue(value) {
  *
  * @param value Parameter value to escape.
  * @param options Escape options for additional characters.
+ *
  * @private function of ParameterEscaping
  */
 function escapePromptParameterValue(value, options) {
@@ -2826,6 +2852,7 @@ const ParameterEscaping = {
  * Builds numeric parameter names (1, 2, ...).
  *
  * @param index Zero-based parameter index.
+ *
  * @private function of ParameterNaming
  */
 function buildNumericParameterName(index) {
@@ -2835,6 +2862,7 @@ function buildNumericParameterName(index) {
  * Builds alphabetic parameter names (a, b, ..., aa).
  *
  * @param index Zero-based parameter index.
+ *
  * @private function of ParameterNaming
  */
 function buildAlphabeticParameterName(index) {
@@ -2851,6 +2879,7 @@ function buildAlphabeticParameterName(index) {
  * Converts a positive integer into a Roman numeral string.
  *
  * @param value Positive integer value.
+ *
  * @private function of ParameterNaming
  */
 function toRomanNumeral(value) {
@@ -2883,6 +2912,7 @@ function toRomanNumeral(value) {
  * Builds Roman numeral parameter names (I, II, ...).
  *
  * @param index Zero-based parameter index.
+ *
  * @private function of ParameterNaming
  */
 function buildRomanParameterName(index) {
@@ -2893,6 +2923,7 @@ function buildRomanParameterName(index) {
  *
  * @param prefix Prefix string.
  * @param builder Base builder function.
+ *
  * @private function of ParameterNaming
  */
 function buildPrefixedParameterName(prefix, builder) {
@@ -2914,6 +2945,7 @@ const PARAMETER_NAME_STRATEGIES = [
  * Collects bracketed tokens from parameter values to avoid placeholder collisions.
  *
  * @param values Parameter values to scan.
+ *
  * @private function of ParameterNaming
  */
 function collectBracketedParameterTokens(values) {
@@ -2934,6 +2966,7 @@ function collectBracketedParameterTokens(values) {
  * Builds placeholder names while avoiding collisions with parameter content.
  *
  * @param values Parameter values to scan for conflicting tokens.
+ *
  * @private function of ParameterNaming
  */
 function buildParameterNames(values) {
@@ -2964,6 +2997,7 @@ const ParameterNaming = {
  * Formats the placeholder used in the prompt body for a parameter.
  *
  * @param name Parameter placeholder name.
+ *
  * @private function of ParameterSection
  */
 function formatParameterPlaceholder(name) {
@@ -2973,6 +3007,7 @@ function formatParameterPlaceholder(name) {
  * Formats a single line entry for structured parameters.
  *
  * @param item Parameter entry data.
+ *
  * @private function of ParameterSection
  */
 function formatParameterListItem(item) {
@@ -2984,6 +3019,7 @@ function formatParameterListItem(item) {
  * Builds the structured parameters section appended to the prompt.
  *
  * @param items Parameter entries to include.
+ *
  * @private function of ParameterSection
  */
 function buildParametersSection(items) {
@@ -3059,6 +3095,7 @@ function isPromptString(value) {
  * @param strings
  * @param values
  * @returns prompt content wrapped as a PromptString
+ *
  * @public exported from `@promptbook/utils`
  */
 function prompt(strings, ...values) {
@@ -3152,14 +3189,13 @@ function prompt(strings, ...values) {
  * 3) `book` for notating and validating entire books exported from `@promptbook/utils`
  *
  * @alias prompt
+ *
  * @public exported from `@promptbook/utils`
  */
 const promptTemplate = prompt;
-/**
- * TODO: Maybe split into multiple files
- * TODO: [🧠][🈴] Where is the best location for this file
- * Note: [💞] Ignore a discrepancy between file name and entity name
- */
+// TODO: Maybe split into multiple files
+// TODO: [🧠][🈴] Where is the best location for this file
+// Note: [💞] Ignore a discrepancy between file name and entity name
 
 /**
  * @@@
@@ -3255,9 +3291,7 @@ function getClientVersionFromHeaders(headers) {
     const value = normalizedHeaders.get(CLIENT_VERSION_HEADER);
     return value ? value.trim() : null;
 }
-/**
- * Note: [💞] Ignore a discrepancy between file name and entity name
- */
+// Note: [💞] Ignore a discrepancy between file name and entity name
 
 /**
  * Detects if the code is running in a browser environment in main thread (Not in a web worker)
@@ -3274,9 +3308,7 @@ function $isRunningInBrowser() {
         return false;
     }
 }
-/**
- * TODO: [🎺]
- */
+// TODO: [🎺]
 
 /**
  * Detects if the code is running in jest environment
@@ -3294,9 +3326,7 @@ function $isRunningInJest() {
         return false;
     }
 }
-/**
- * TODO: [🎺]
- */
+// TODO: [🎺]
 
 /**
  * Detects if the code is running in a Node.js environment
@@ -3313,9 +3343,7 @@ function $isRunningInNode() {
         return false;
     }
 }
-/**
- * TODO: [🎺]
- */
+// TODO: [🎺]
 
 /**
  * Detects if the code is running in a web worker
@@ -3335,9 +3363,7 @@ function $isRunningInWebWorker() {
         return false;
     }
 }
-/**
- * TODO: [🎺]
- */
+// TODO: [🎺]
 
 /**
  * Returns information about the current runtime environment
@@ -3354,9 +3380,7 @@ function $detectRuntimeEnvironment() {
         isRunningInWebWorker: $isRunningInWebWorker(),
     };
 }
-/**
- * TODO: [🎺] Also detect and report node version here
- */
+// TODO: [🎺] Also detect and report node version here
 
 /**
  * Number of characters per standard line with 11pt Arial font size.
@@ -3370,10 +3394,8 @@ const CHARACTERS_PER_STANDARD_LINE = 63;
  * @public exported from `@promptbook/utils`
  */
 const LINES_PER_STANDARD_PAGE = 44;
-/**
- * TODO: [🧠] Should be this `constants.ts` or `config.ts`?
- * Note: [💞] Ignore a discrepancy between file name and entity name
- */
+// TODO: [🧠] Should be this `constants.ts` or `config.ts`?
+// Note: [💞] Ignore a discrepancy between file name and entity name
 
 /**
  * Counts number of characters in the text
@@ -3389,10 +3411,8 @@ function countCharacters(text) {
     text = text.replace(/\p{Extended_Pictographic}(\u{200D}\p{Extended_Pictographic})*/gu, '-');
     return text.length;
 }
-/**
- * TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
- * TODO: [🧠][✌️] Make some Promptbook-native token system
- */
+// TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
+// TODO: [🧠][✌️] Make some Promptbook-native token system
 
 /**
  * Counts number of lines in the text
@@ -3410,10 +3430,8 @@ function countLines(text) {
     const lines = text.split(/\r?\n/);
     return lines.reduce((count, line) => count + Math.max(Math.ceil(line.length / CHARACTERS_PER_STANDARD_LINE), 1), 0);
 }
-/**
- * TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
- * TODO: [🧠][✌️] Make some Promptbook-native token system
- */
+// TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
+// TODO: [🧠][✌️] Make some Promptbook-native token system
 
 /**
  * Counts number of pages in the text
@@ -3425,10 +3443,8 @@ function countLines(text) {
 function countPages(text) {
     return Math.ceil(countLines(text) / LINES_PER_STANDARD_PAGE);
 }
-/**
- * TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
- * TODO: [🧠][✌️] Make some Promptbook-native token system
- */
+// TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
+// TODO: [🧠][✌️] Make some Promptbook-native token system
 
 /**
  * Counts number of paragraphs in the text
@@ -3438,10 +3454,8 @@ function countPages(text) {
 function countParagraphs(text) {
     return text.split(/\n\s*\n/).filter((paragraph) => paragraph.trim() !== '').length;
 }
-/**
- * TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
- * TODO: [🧠][✌️] Make some Promptbook-native token system
- */
+// TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
+// TODO: [🧠][✌️] Make some Promptbook-native token system
 
 /**
  * Split text into sentences
@@ -3459,10 +3473,8 @@ function splitIntoSentences(text) {
 function countSentences(text) {
     return splitIntoSentences(text).length;
 }
-/**
- * TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
- * TODO: [🧠][✌️] Make some Promptbook-native token system
- */
+// TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
+// TODO: [🧠][✌️] Make some Promptbook-native token system
 
 /**
  * Counts number of words in the text
@@ -3476,11 +3488,9 @@ function countWords(text) {
     text = text.replace(/([a-z])([A-Z])/g, '$1 $2');
     return text.split(/[^a-zа-я0-9]+/i).filter((word) => word.length > 0).length;
 }
-/**
- * TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
- * TODO: [🧠][✌️] Make some Promptbook-native token system
- * TODO: [✌️] `countWords` should be just `splitWords(...).length`, and all other counters should use this pattern as well
- */
+// TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
+// TODO: [🧠][✌️] Make some Promptbook-native token system
+// TODO: [✌️] `countWords` should be just `splitWords(...).length`, and all other counters should use this pattern as well
 
 /**
  * Index of all counter functions
@@ -3495,10 +3505,8 @@ const CountUtils = {
     LINES: countLines,
     PAGES: countPages,
 };
-/**
- * TODO: [🧠][🤠] This should be probably as part of `TextFormatParser`
- * Note: [💞] Ignore a discrepancy between file name and entity name
- */
+// TODO: [🧠][🤠] This should be probably as part of `TextFormatParser`
+// Note: [💞] Ignore a discrepancy between file name and entity name
 
 /**
  * Computes SHA-256 hash of the given object
@@ -3508,9 +3516,7 @@ const CountUtils = {
 function computeHash(value) {
     return SHA256(hexEncoder.parse(spaceTrim$1(valueToString(value)))).toString( /* hex */);
 }
-/**
- * TODO: [🥬][🥬] Use this ACRY
- */
+// TODO: [🥬][🥬] Use this ACRY
 
 /**
  * Makes first letter of a string uppercase
@@ -3687,6 +3693,9 @@ const ADJECTIVES$1 = [
     'prvotní',
     'hbitý',
 ];
+/**
+ * Collection of nouns.
+ */
 const NOUNS$1 = [
     'jablko',
     'nebe',
@@ -3900,6 +3909,9 @@ const NOUNS$1 = [
     'okno',
     'chodba',
 ];
+/**
+ * Collection of verbs.
+ */
 const VERBS$1 = [
     'skáče',
     'tančí',
@@ -4072,9 +4084,7 @@ const LINGUISTIC_HASH_WORD_LISTS_CS = {
     noun: NOUNS$1,
     verb: VERBS$1,
 };
-/**
- * Note: [💞] Ignore a discrepancy between file name and entity name
- */
+// Note: [💞] Ignore a discrepancy between file name and entity name
 
 /**
  * @@@
@@ -4330,6 +4340,9 @@ const ADJECTIVES = [
     'macro',
     'mini',
 ];
+/**
+ * Collection of nouns.
+ */
 const NOUNS = [
     'apple',
     'sky',
@@ -4569,6 +4582,9 @@ const NOUNS = [
     'roof',
     'floor',
 ];
+/**
+ * Collection of verbs.
+ */
 const VERBS = [
     'jumping',
     'dancing',
@@ -4764,9 +4780,7 @@ const LINGUISTIC_HASH_WORD_LISTS_EN = {
     noun: NOUNS,
     verb: VERBS,
 };
-/**
- * Note: [💞] Ignore a discrepancy between file name and entity name
- */
+// Note: [💞] Ignore a discrepancy between file name and entity name
 
 /**
  * Default language used for linguistic hashes.
@@ -4941,8 +4955,9 @@ function normalizeLinguisticHashWordCount(wordCount) {
 /**
  * Creates a human-readable hash as a short, story-like phrase.
  *
- * @param wordCount how many words to include (defaults to {@link DEFAULT_LINGUISTIC_HASH_WORD_COUNT}, clamped to
  * {@link MIN_LINGUISTIC_HASH_WORD_COUNT}..{@link MAX_LINGUISTIC_HASH_WORD_COUNT})
+ *
+ * @param wordCount how many words to include (defaults to {@link DEFAULT_LINGUISTIC_HASH_WORD_COUNT}, clamped to
  * @param language optional language code (defaults to {@link DEFAULT_LINGUISTIC_HASH_LANGUAGE})
  *
  * @public exported from `@promptbook/utils`
@@ -4961,6 +4976,7 @@ async function linguisticHash(input, wordCount, language) {
  * Note: `$` is used to indicate that this function is not a pure function - it is not deterministic because it depends on the current time
  *
  * @returns string_date branded type
+ *
  * @public exported from `@promptbook/utils`
  */
 function $getCurrentDate() {
@@ -4968,6 +4984,8 @@ function $getCurrentDate() {
 }
 
 /**
+ * Handles debounce.
+ *
  * @public exported from `@promptbook/utils`
  */
 function debounce(fn, delay) {
@@ -5046,10 +5064,8 @@ function parseNumber(value) {
     }
     return num;
 }
-/**
- * TODO: Maybe use sth. like safe-eval in fraction/calculation case @see https://www.npmjs.com/package/safe-eval
- * TODO: [🧠][🌻] Maybe export through `@promptbook/markdown-utils` not `@promptbook/utils`
- */
+// TODO: Maybe use sth. like safe-eval in fraction/calculation case @see https://www.npmjs.com/package/safe-eval
+// TODO: [🧠][🌻] Maybe export through `@promptbook/markdown-utils` not `@promptbook/utils`
 
 /**
  * Makes first letter of a string lowercase
@@ -5071,6 +5087,7 @@ function decapitalize(word) {
  * @returns The normalized text in SCREAMING_CASE format.
  * @example 'HELLO_WORLD'
  * @example 'I_LOVE_PROMPTBOOK'
+ *
  * @public exported from `@promptbook/utils`
  */
 function normalizeTo_SCREAMING_CASE(text) {
@@ -5124,6 +5141,7 @@ function normalizeTo_SCREAMING_CASE(text) {
  *
  * @param {string} input
  * @returns {Set} of keywords without diacritics in lowercase
+ *
  * @public exported from `@promptbook/utils`
  */
 function parseKeywordsFromString(input) {
@@ -5158,6 +5176,7 @@ function isValidKeyword(keyword) {
  * @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) {
@@ -5176,6 +5195,7 @@ function nameToUriPart(name) {
  * @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) {
@@ -5205,6 +5225,7 @@ function normalizeMessageText(text) {
  * @returns
  * @example 'HelloWorld'
  * @example 'ILovePromptbook'
+ *
  * @public exported from `@promptbook/utils`
  */
 function normalizeTo_PascalCase(text) {
@@ -5220,6 +5241,7 @@ function normalizeTo_PascalCase(text) {
  * @returns The normalized text in snake_case format.
  * @example 'hello_world'
  * @example 'i_love_promptbook'
+ *
  * @public exported from `@promptbook/utils`
  */
 function normalizeTo_snake_case(text) {
@@ -5244,6 +5266,7 @@ function normalizeWhitespaces(sentence) {
  *
  * @param input of any kind
  * @returns {Set} of keywords without diacritics in lowercase
+ *
  * @public exported from `@promptbook/utils`
  */
 function parseKeywords(input) {
@@ -5265,10 +5288,8 @@ function parseKeywords(input) {
         return new Set();
     }
 }
-/**
- * Note: Not using spread in input param because of keeping second parameter for options
- * TODO: [🌺] Use some intermediate util splitWords
- */
+// Note: Not using spread in input param because of keeping second parameter for options
+// TODO: [🌺] Use some intermediate util splitWords
 
 /**
  * Removes quotes from a string
@@ -5282,6 +5303,7 @@ function parseKeywords(input) {
  *
  * @param text optionally quoted text
  * @returns text without quotes
+ *
  * @public exported from `@promptbook/utils`
  */
 function removeQuotes(text) {
@@ -5300,6 +5322,7 @@ function removeQuotes(text) {
  * @param haystack
  * @param needle
  * @returns
+ *
  * @public exported from `@promptbook/utils`
  */
 function searchKeywords(haystack, needle) {
@@ -5310,9 +5333,7 @@ function searchKeywords(haystack, needle) {
     }
     return true;
 }
-/**
- * TODO: Rename to `isKeywordInKeywords`
- */
+// TODO: Rename to `isKeywordInKeywords`
 
 /**
  * Adds suffix to the URL
@@ -5336,6 +5357,7 @@ function suffixUrl(value, suffix) {
  *
  * @param text optionally quoted text
  * @returns text without quotes
+ *
  * @public exported from `@promptbook/utils`
  */
 function unwrapResult(text, options) {
@@ -5410,15 +5432,14 @@ function unwrapResult(text, options) {
         return processedText;
     }
 }
-/**
- * TODO: [🧠] Should this also unwrap the (parenthesis)
- */
+// TODO: [🧠] Should this also unwrap the (parenthesis)
 
 /**
  * Parses the task and returns the list of all parameter names
  *
  * @param template the string template with parameters in {curly} braces
  * @returns the list of parameter names
+ *
  * @public exported from `@promptbook/utils`
  */
 function extractParameterNames(template) {
@@ -5438,6 +5459,7 @@ function extractParameterNames(template) {
  *
  * @param pipeline The pipeline to clone.
  * @returns A new PipelineJson object with the same properties as the input.
+ *
  * @public exported from `@promptbook/utils`
  */
 function clonePipeline(pipeline) {
@@ -5459,9 +5481,7 @@ function clonePipeline(pipeline) {
         sources,
     };
 }
-/**
- * TODO: [🍙] Make some standard order of json properties
- */
+// TODO: [🍙] Make some standard order of json properties
 
 // <- TODO: Auto convert to type `import { ... } from 'type-fest';`
 /**
@@ -5480,7 +5500,6 @@ function clonePipeline(pipeline) {
  * - `Symbol` objects are not serializable
  * - And much more...
  *
- *
  * @public exported from `@promptbook/utils`
  */
 function isSerializableAsJson(value) {
@@ -5492,14 +5511,12 @@ function isSerializableAsJson(value) {
         return false;
     }
 }
-/**
- * TODO: [🧠][main] !!3 In-memory cache of same values to prevent multiple checks
- * TODO: [🧠][💺] Can be done this on type-level?
- */
+// TODO: [🧠][main] !!3 In-memory cache of same values to prevent multiple checks
+// TODO: [🧠][💺] Can be done this on type-level?
 
 /**
  * Recursively converts JSON strings to JSON objects
-
+ *
  * @public exported from `@promptbook/utils`
  */
 function jsonStringsToJsons(object) {
@@ -5523,9 +5540,7 @@ function jsonStringsToJsons(object) {
     }
     return newObject;
 }
-/**
- * TODO: Type the return type correctly
- */
+// TODO: Type the return type correctly
 
 /**
  * Function `serializeToPromptbookJavascript` will serialize a value to a javascript representation using `@promptbook/*` entities where possible.
@@ -5585,14 +5600,13 @@ function serializeToPromptbookJavascript(value) {
     const uniqueImports = Array.from(new Set(imports)).filter((importStatement) => !!importStatement && importStatement.trim().length > 0);
     return { imports: uniqueImports, value: serializedValue };
 }
-/**
- * TODO: Dynamic indentation passable through options in a second argument
- */
+// TODO: Dynamic indentation passable through options in a second argument
 
 /**
  * Create difference set of two sets.
  *
  * @deprecated use new javascript set methods instead @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set
+ *
  * @public exported from `@promptbook/utils`
  */
 function difference(a, b, isEqual = (a, b) => a === b) {
@@ -5604,14 +5618,13 @@ function difference(a, b, isEqual = (a, b) => a === b) {
     }
     return diff;
 }
-/**
- * TODO: [🧠][💯] Maybe also implement symmetricDifference
- */
+// TODO: [🧠][💯] Maybe also implement symmetricDifference
 
 /**
  * Creates a new set with all elements that are present in all sets
  *
  * @deprecated use new javascript set methods instead @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set
+ *
  * @public exported from `@promptbook/utils`
  */
 function intersection(...sets) {
@@ -5637,6 +5650,7 @@ function intersection(...sets) {
  * Creates a new set with all elements that are present in either set
  *
  * @deprecated use new javascript set methods instead @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set
+ *
  * @public exported from `@promptbook/utils`
  */
 function union(...sets) {
@@ -5668,6 +5682,7 @@ function isValidEmail(email) {
  * Determines if the given path is a root path.
  *
  * Note: This does not check if the file exists only if the path is valid
+ *
  * @public exported from `@promptbook/utils`
  */
 function isRootPath(value) {
@@ -5679,15 +5694,14 @@ function isRootPath(value) {
     }
     return false;
 }
-/**
- * TODO: [🍏] Make for MacOS paths
- */
+// TODO: [🍏] Make for MacOS paths
 
 /**
  * Checks if the given value is a valid JavaScript identifier name.
  *
  * @param javascriptName The value to check for JavaScript identifier validity.
  * @returns `true` if the value is a valid JavaScript name, false otherwise.
+ *
  * @public exported from `@promptbook/utils`
  */
 function isValidJavascriptName(javascriptName) {
@@ -5720,12 +5734,13 @@ function isValidSemanticVersion(version) {
  * Tests if given string is valid promptbook version
  * It looks into list of known promptbook versions.
  *
- * @see https://www.npmjs.com/package/promptbook?activeTab=versions
  * Note: When you are using for example promptbook 2.0.0 and there already is promptbook 3.0.0 it don`t know about it.
  * Note: There are two similar functions:
  * - `isValidSemanticVersion` which tests any semantic version
  * - `isValidPromptbookVersion` *(this one)* which tests just Promptbook versions
  *
+ * @see https://www.npmjs.com/package/promptbook?activeTab=versions
+ *
  * @public exported from `@promptbook/utils`
  */
 function isValidPromptbookVersion(version) {
@@ -5783,6 +5798,7 @@ function isHostnameOnPrivateNetwork(hostname, options = {}) {
  * @param {string} url - The URL to check.
  * @param {IsUrlOnPrivateNetworkOptions} options - Options for the check.
  * @returns {boolean} Returns true if the IP address is reserved for private networks or localhost, otherwise false.
+ *
  * @public exported from `@promptbook/utils`
  */
 function isUrlOnPrivateNetwork(url, options = {}) {
@@ -5821,9 +5837,7 @@ function isValidAgentUrl(url) {
     */
     return true;
 }
-/**
- * TODO: [🐠] Maybe more info why the URL is invalid
- */
+// TODO: [🐠] Maybe more info why the URL is invalid
 
 /**
  * Tests if given string is valid pipeline URL URL.
@@ -5854,9 +5868,7 @@ function isValidPipelineUrl(url) {
     */
     return true;
 }
-/**
- * TODO: [🐠] Maybe more info why the URL is invalid
- */
+// TODO: [🐠] Maybe more info why the URL is invalid
 
 /**
  * Checks if value is valid uuid