@promptbook/javascript 0.112.0-34 → 0.112.0-35

package/umd/index.umd.js

@@ -22,7 +22,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-34';
+    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
@@ -32,16 +32,20 @@
      * 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.spaceTrim;
 
     /**
-     * @private util of `@promptbook/color`
+     * Class implementing take chain.
+     *
      * @de
+     *
+     * @private util of `@promptbook/color`
      */
     class TakeChain {
         constructor(value) {
@@ -58,9 +62,9 @@
      *
      * @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) {
@@ -238,9 +242,7 @@
         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.
@@ -270,7 +272,13 @@
         }
     }
 
+    /**
+     * 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.
@@ -303,6 +311,9 @@
         }
         return throwInvalidHex();
     }
+    /**
+     * Parses short hex channel.
+     */
     function parseShortHexChannel(char, onError) {
         if (!char) {
             return onError();
@@ -313,6 +324,9 @@
         }
         return parsed * 16;
     }
+    /**
+     * Parses long hex channel.
+     */
     function parseLongHexChannel(hex, start, onError) {
         const segment = hex.substr(start, 2);
         if (segment.length < 2) {
@@ -325,6 +339,9 @@
         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.
@@ -350,6 +367,9 @@
             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));
@@ -388,7 +408,13 @@
         };
     }
 
+    /**
+     * 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.
@@ -430,6 +456,9 @@
             alpha: parseAlphaValue(match[4]),
         };
     }
+    /**
+     * Parses channel value.
+     */
     function parseChannelValue(value) {
         if (value.endsWith('%')) {
             const percent = parseFloat(value);
@@ -437,6 +466,9 @@
         }
         return Math.round(parseFloat(value));
     }
+    /**
+     * Parses alpha value.
+     */
     function parseAlphaValue(value) {
         if (value.endsWith('%')) {
             const percent = parseFloat(value);
@@ -449,8 +481,17 @@
         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
@@ -816,9 +857,7 @@
         }
         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
@@ -864,9 +903,7 @@
         }
         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
@@ -884,9 +921,7 @@
             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
@@ -904,9 +939,7 @@
             return Color.fromValues(r, g, b, alpha);
         };
     }
-    /**
-     * TODO: Maybe implement by mix+hsl
-     */
+    // TODO: Maybe implement by mix+hsl
 
     /**
      * Name for the Promptbook
@@ -1030,6 +1063,7 @@
      * Orders JSON object by keys
      *
      * @returns The same type of object as the input re-ordered
+     *
      * @public exported from `@promptbook/utils`
      */
     function orderJson(options) {
@@ -1048,6 +1082,7 @@
      * 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) {
@@ -1064,9 +1099,7 @@
         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
@@ -1202,6 +1235,7 @@
      * - And much more...
      *
      * @throws UnexpectedError if the value is not serializable as JSON
+     *
      * @public exported from `@promptbook/utils`
      */
     function checkSerializableAsJson(options) {
@@ -1316,11 +1350,9 @@
                 `));
         }
     }
-    /**
-     * 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
@@ -1330,6 +1362,7 @@
      *
      * @param objectValue The object to clone.
      * @returns A deep, writable clone of the input object.
+     *
      * @public exported from `@promptbook/utils`
      */
     function deepClone(objectValue) {
@@ -1346,9 +1379,7 @@
         > 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
@@ -1361,6 +1392,7 @@
      * 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) {
@@ -1380,9 +1412,7 @@
         $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
 
     /**
      * The names of the parameters that are reserved for special purposes
@@ -1404,9 +1434,7 @@
             // <- 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.
@@ -1418,6 +1446,7 @@
      * @returns The camelCase formatted string.
      * @example 'helloWorld'
      * @example 'iLovePromptbook'
+     *
      * @public exported from `@promptbook/utils`
      */
     function normalizeTo_camelCase(text, _isFirstLetterCapital = false) {
@@ -1458,10 +1487,11 @@
         }
         return normalizedName;
     }
+    // TODO: [🌺] Use some intermediate util splitWords
+
     /**
-     * TODO: [🌺] Use some intermediate util splitWords
+     * Collection of default diacritics removal map.
      */
-
     const defaultDiacriticsRemovalMap = [
         {
             base: 'A',
@@ -1713,6 +1743,7 @@
      *
      * @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) {
@@ -1721,9 +1752,7 @@
             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.
@@ -1734,6 +1763,7 @@
      * @returns The kebab-case formatted string.
      * @example 'hello-world'
      * @example 'i-love-promptbook'
+     *
      * @public exported from `@promptbook/utils`
      */
     function normalizeToKebabCase(text) {
@@ -1774,9 +1804,7 @@
         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
@@ -1785,6 +1813,7 @@
      *
      * @param text with emojis
      * @returns text without emojis
+     *
      * @public exported from `@promptbook/utils`
      */
     function removeEmojis(text) {
@@ -1808,9 +1837,7 @@
             Object.setPrototypeOf(this, ParseError.prototype);
         }
     }
-    /**
-     * TODO: Maybe split `ParseError` and `ApplyError`
-     */
+    // TODO: Maybe split `ParseError` and `ApplyError`
 
     /**
      * Generates random token
@@ -1818,16 +1845,15 @@
      * 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 crypto.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
@@ -1844,9 +1870,7 @@
             Object.setPrototypeOf(this, PipelineExecutionError.prototype);
         }
     }
-    /**
-     * TODO: [🧠][🌂] Add id to all errors
-     */
+    // TODO: [🧠][🌂] Add id to all errors
 
     /**
      * Index of all javascript errors
@@ -1871,9 +1895,7 @@
       > WebAssemblyRuntimeError,
       */
     });
-    /**
-     * Note: [💞] Ignore a discrepancy between file name and entity name
-     */
+    // Note: [💞] Ignore a discrepancy between file name and entity name
 
     /**
      * Format either small or big number
@@ -1908,8 +1930,8 @@
      * 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
@@ -1987,6 +2009,7 @@
      * @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) {
@@ -2040,6 +2063,7 @@
      *
      * @param {string} input
      * @returns {Set} of keywords without diacritics in lowercase
+     *
      * @public exported from `@promptbook/utils`
      */
     function parseKeywordsFromString(input) {
@@ -2056,6 +2080,7 @@
      * @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) {
@@ -2074,6 +2099,7 @@
      * @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) {
@@ -2091,6 +2117,7 @@
      * @returns
      * @example 'HelloWorld'
      * @example 'ILovePromptbook'
+     *
      * @public exported from `@promptbook/utils`
      */
     function normalizeTo_PascalCase(text) {
@@ -2106,6 +2133,7 @@
      * @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) {
@@ -2135,6 +2163,7 @@
      *
      * @param text optionally quoted text
      * @returns text without quotes
+     *
      * @public exported from `@promptbook/utils`
      */
     function removeQuotes(text) {
@@ -2158,6 +2187,7 @@
      *
      * @param text optionally quoted text
      * @returns text without quotes
+     *
      * @public exported from `@promptbook/utils`
      */
     function unwrapResult(text, options) {
@@ -2232,9 +2262,7 @@
             return processedText;
         }
     }
-    /**
-     * TODO: [🧠] Should this also unwrap the (parenthesis)
-     */
+    // TODO: [🧠] Should this also unwrap the (parenthesis)
 
     /**
      * Extracts all code blocks from markdown.
@@ -2248,6 +2276,7 @@
      * @param markdown any valid markdown
      * @returns code blocks with language and content
      * @throws {ParseError} if block is not closed properly
+     *
      * @public exported from `@promptbook/markdown-utils`
      */
     function extractAllBlocksFromMarkdown(markdown) {
@@ -2298,9 +2327,7 @@
         }
         return codeBlocks;
     }
-    /**
-     * TODO: Maybe name for `blockNotation` instead of  '```' and '>'
-     */
+    // TODO: Maybe name for `blockNotation` instead of  '```' and '>'
 
     /**
      * Extracts exactly ONE code block from markdown.
@@ -2315,8 +2342,9 @@
      *
      * @param markdown any valid markdown
      * @returns code block with language and content
-     * @public exported from `@promptbook/markdown-utils`
      * @throws {ParseError} if there is not exactly one code block in the markdown
+     *
+     * @public exported from `@promptbook/markdown-utils`
      */
     function extractOneBlockFromMarkdown(markdown) {
         const codeBlocks = extractAllBlocksFromMarkdown(markdown);
@@ -2329,9 +2357,7 @@
         }
         return codeBlocks[0];
     }
-    /***
-     * TODO: [🍓][🌻] Decide of this is internal utility, external util OR validator/postprocessor
-     */
+    // TODO: [🍓][🌻] Decide of this is internal utility, external util OR validator/postprocessor
 
     /**
      * Extracts code block from markdown.
@@ -2344,8 +2370,9 @@
      * - `extractOneBlockFromMarkdown` extracts exactly one code block with language of the code block
      * - `extractAllBlocksFromMarkdown` extracts all code blocks with language of the code block
      *
-     * @public exported from `@promptbook/markdown-utils`
      * @throws {ParseError} if there is not exactly one code block in the markdown
+     *
+     * @public exported from `@promptbook/markdown-utils`
      */
     function extractBlock(markdown) {
         const { content } = extractOneBlockFromMarkdown(markdown);
@@ -2357,8 +2384,9 @@
      *
      * @param content raw html code
      * @returns formatted html code
-     * @private withing the package because of HUGE size of prettier dependency
      * @deprecated Prettier removed from Promptbook due to package size
+     *
+     * @private withing the package because of HUGE size of prettier dependency
      */
     function prettifyMarkdown(content) {
         return (content + `\n\n<!-- Note: Prettier removed from Promptbook -->`);
@@ -2369,7 +2397,7 @@
      *
      * Note: [🔂] This function is idempotent.
      * Note: This is useful for post-processing of the result of the chat LLM model
-     *       when the model wraps the result in the (markdown) code block.
+     * when the model wraps the result in the (markdown) code block.
      *
      * @public exported from `@promptbook/markdown-utils`
      */
@@ -2388,7 +2416,7 @@
      * Function trimEndOfCodeBlock will remove ending code block from the string if it is present.
      *
      * Note: This is useful for post-processing of the result of the completion LLM model
-     *       if you want to start code block in the prompt but you don't want to end it in the result.
+     * if you want to start code block in the prompt but you don't want to end it in the result.
      *
      * @public exported from `@promptbook/markdown-utils`
      */
@@ -2400,6 +2428,8 @@
     }
 
     /**
+     * Collection of preserved.
+     *
      * @private internal for `preserve`
      */
     const _preserved = [];
@@ -2409,21 +2439,20 @@
      *
      * @param value any function to preserve
      * @returns nothing
+     *
      * @private within the repository
      */
     function $preserve(...value) {
         _preserved.push(...value);
     }
-    /**
-     * Note: [💞] Ignore a discrepancy between file name and entity name
-     */
+    // Note: [💞] Ignore a discrepancy between file name and entity name
 
     // Note: [💎]
     /**
      * ScriptExecutionTools for JavaScript implemented via eval
      *
      * Warning: It is used for testing and mocking
-     *          **NOT intended to use in the production** due to its unsafe nature, use `JavascriptExecutionTools` instead.
+     * **NOT intended to use in the production** due to its unsafe nature, use `JavascriptExecutionTools` instead.
      *
      * @public exported from `@promptbook/javascript`
      */
@@ -2618,25 +2647,33 @@
             return result;
         }
     }
-    /**
-     * TODO: Put predefined functions (like removeQuotes, spaceTrim, etc.) into annotation OR pass into constructor
-     * TODO: [🧠][💙] Distinct between options passed into ExecutionTools and to ExecutionTools.execute
-     */
+    // TODO: Put predefined functions (like removeQuotes, spaceTrim, etc.) into annotation OR pass into constructor
+    // TODO: [🧠][💙] Distinct between options passed into ExecutionTools and to ExecutionTools.execute
 
     /**
      * Placeholder for better implementation of JavascriptExecutionTools - some proper sandboxing
      *
      * @alias JavascriptExecutionTools
+     *
      * @public exported from `@promptbook/javascript`
      */
     const JavascriptExecutionTools = JavascriptEvalExecutionTools;
 
+    /**
+     * Constant for parse keywords.
+     */
     const parseKeywords = (input) => 
     // TODO: DRY [🍯]
     Array.from(parseKeywordsFromString(input)).join(', '); /* <- TODO: [🧠] What is the best format comma list, bullet list,...? */
     // TODO: DRY [🍯]
+    /**
+     * Constant for trim.
+     */
     const trim = (str) => str.trim();
     // TODO: DRY [🍯]
+    /**
+     * Constant for reverse.
+     */
     const reverse = (str) => str.split('').reverse().join('');
     /**
      * Collection of utility functions that can be used for post-processing model outputs.
@@ -2671,10 +2708,8 @@
         normalizeTo_SCREAMING_CASE,
         extractBlock, // <- [🍓] Remove balast in all other functions, use this one as example
     };
-    /**
-     * TODO: DRY [🍯], [🧠] Where should be POSTPROCESSING_FUNCTIONS located and how it should be named
-     * Note: [💞] Ignore a discrepancy between file name and entity name
-     */
+    // TODO: DRY [🍯], [🧠] Where should be POSTPROCESSING_FUNCTIONS located and how it should be named
+    // Note: [💞] Ignore a discrepancy between file name and entity name
 
     /**
      * Parses the given script and returns the list of all used variables that are not defined in the script
@@ -2682,6 +2717,7 @@
      * @param script from which to extract the variables
      * @returns the list of variable names
      * @throws {ParseError} if the script is invalid
+     *
      * @public exported from `@promptbook/javascript`
      */
     function extractVariablesFromJavascript(script) {
@@ -2747,9 +2783,7 @@
         }
         return variables;
     }
-    /**
-     * TODO: [🔣] Support for multiple languages - python, java,...
-     */
+    // TODO: [🔣] Support for multiple languages - python, java,...
 
     exports.BOOK_LANGUAGE_VERSION = BOOK_LANGUAGE_VERSION;
     exports.JavascriptEvalExecutionTools = JavascriptEvalExecutionTools;