@promptbook/utils 0.112.0-11 → 0.112.0-110

package/umd/index.umd.js

@@ -1,12 +1,11 @@
 (function (global, factory) {
     typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('spacetrim'), require('path'), require('crypto'), require('crypto-js'), require('crypto-js/enc-hex')) :
     typeof define === 'function' && define.amd ? define(['exports', 'spacetrim', 'path', 'crypto', 'crypto-js', 'crypto-js/enc-hex'], factory) :
-    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global["promptbook-utils"] = {}, global.spaceTrim$1, global.path, global.crypto, global.cryptoJs, global.hexEncoder));
-})(this, (function (exports, spaceTrim$1, path, crypto, cryptoJs, hexEncoder) { 'use strict';
+    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global["promptbook-utils"] = {}, global.spacetrim, global.path, global.crypto, global.cryptoJs, global.hexEncoder));
+})(this, (function (exports, spacetrim, path, crypto, cryptoJs, hexEncoder) { 'use strict';
 
     function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
 
-    var spaceTrim__default = /*#__PURE__*/_interopDefaultLegacy(spaceTrim$1);
     var hexEncoder__default = /*#__PURE__*/_interopDefaultLegacy(hexEncoder);
 
     // ⚠️ WARNING: This code has been generated so that any manual changes will be overwritten
@@ -23,7 +22,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-11';
+    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-110';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -33,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$1.spaceTrim;
+    const spaceTrim = spacetrim.spaceTrim;
 
     /**
-     * @private util of `@promptbook/color`
+     * Class implementing take chain.
+     *
      * @de
+     *
+     * @private util of `@promptbook/color`
      */
     class TakeChain {
         constructor(value) {
@@ -59,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) {
@@ -239,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.
@@ -271,7 +272,118 @@
         }
     }
 
+    /**
+     * Shared immutable channel storage and serialization helpers for `Color`.
+     *
+     * @private base class of Color
+     */
+    class ColorValue {
+        constructor(red, green, blue, alpha = 255) {
+            this.red = red;
+            this.green = green;
+            this.blue = blue;
+            this.alpha = alpha;
+            checkChannelValue('Red', red);
+            checkChannelValue('Green', green);
+            checkChannelValue('Blue', blue);
+            checkChannelValue('Alpha', alpha);
+        }
+        /**
+         * Shortcut for `red` property
+         * Number from 0 to 255
+         * @alias red
+         */
+        get r() {
+            return this.red;
+        }
+        /**
+         * Shortcut for `green` property
+         * Number from 0 to 255
+         * @alias green
+         */
+        get g() {
+            return this.green;
+        }
+        /**
+         * Shortcut for `blue` property
+         * Number from 0 to 255
+         * @alias blue
+         */
+        get b() {
+            return this.blue;
+        }
+        /**
+         * Shortcut for `alpha` property
+         * Number from 0 (transparent) to 255 (opaque)
+         * @alias alpha
+         */
+        get a() {
+            return this.alpha;
+        }
+        /**
+         * Shortcut for `alpha` property
+         * Number from 0 (transparent) to 255 (opaque)
+         * @alias alpha
+         */
+        get opacity() {
+            return this.alpha;
+        }
+        /**
+         * Shortcut for 1-`alpha` property
+         */
+        get transparency() {
+            return 255 - this.alpha;
+        }
+        clone() {
+            return take(this.createColor(this.red, this.green, this.blue, this.alpha));
+        }
+        toString() {
+            return this.toHex();
+        }
+        toHex() {
+            if (this.alpha === 255) {
+                return `#${this.red.toString(16).padStart(2, '0')}${this.green.toString(16).padStart(2, '0')}${this.blue
+                .toString(16)
+                .padStart(2, '0')}`;
+            }
+            else {
+                return `#${this.red.toString(16).padStart(2, '0')}${this.green.toString(16).padStart(2, '0')}${this.blue
+                .toString(16)
+                .padStart(2, '0')}${this.alpha.toString(16).padStart(2, '0')}`;
+            }
+        }
+        toRgb() {
+            if (this.alpha === 255) {
+                return `rgb(${this.red}, ${this.green}, ${this.blue})`;
+            }
+            else {
+                return `rgba(${this.red}, ${this.green}, ${this.blue}, ${Math.round((this.alpha / 255) * 100)}%)`;
+            }
+        }
+        toHsl() {
+            throw new Error(`Getting HSL is not implemented`);
+        }
+    }
+
+    /**
+     * Checks if the given value is a valid hex color string
+     *
+     * @param value - value to check
+     * @returns true if the value is a valid hex color string (e.g., `#009edd`, `#fff`, etc.)
+     *
+     * @private function of Color
+     */
+    function isHexColorString(value) {
+        return (typeof value === 'string' && /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/.test(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.
@@ -304,6 +416,9 @@
         }
         return throwInvalidHex();
     }
+    /**
+     * Parses short hex channel.
+     */
     function parseShortHexChannel(char, onError) {
         if (!char) {
             return onError();
@@ -314,6 +429,9 @@
         }
         return parsed * 16;
     }
+    /**
+     * Parses long hex channel.
+     */
     function parseLongHexChannel(hex, start, onError) {
         const segment = hex.substr(start, 2);
         if (segment.length < 2) {
@@ -326,6 +444,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.
@@ -351,6 +472,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));
@@ -389,7 +513,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.
@@ -431,6 +561,9 @@
             alpha: parseAlphaValue(match[4]),
         };
     }
+    /**
+     * Parses channel value.
+     */
     function parseChannelValue(value) {
         if (value.endsWith('%')) {
             const percent = parseFloat(value);
@@ -438,6 +571,9 @@
         }
         return Math.round(parseFloat(value));
     }
+    /**
+     * Parses alpha value.
+     */
     function parseAlphaValue(value) {
         if (value.endsWith('%')) {
             const percent = parseFloat(value);
@@ -450,9 +586,55 @@
         return Math.round(parsed);
     }
 
+    /**
+     * Pattern matching hsl regex.
+     *
+     * @private function of Color
+     */
     const HSL_REGEX_PATTERN = /^hsl\(\s*([0-9.]+)\s*,\s*([0-9.]+)%\s*,\s*([0-9.]+)%\s*\)$/;
+    /**
+     * Pattern matching RGB regex.
+     *
+     * @private function of Color
+     */
     const RGB_REGEX_PATTERN = /^rgb\(\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*\)$/;
+    /**
+     * Pattern matching rgba regex.
+     *
+     * @private function of Color
+     */
     const RGBA_REGEX_PATTERN = /^rgba\(\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*\)$/;
+    /**
+     * Parses a supported color string into RGBA channels.
+     *
+     * @param color as a string for example `#009edd`, `rgb(0,158,221)`, `rgb(0%,62%,86.7%)`, `hsl(197.1,100%,43.3%)`, `red`, `darkgrey`,...
+     * @returns RGBA channel values.
+     *
+     * @private function of Color
+     */
+    function parseColorString(color) {
+        const trimmed = color.trim();
+        const cssColor = CSS_COLORS[trimmed];
+        if (cssColor) {
+            return parseColorString(cssColor);
+        }
+        else if (isHexColorString(trimmed)) {
+            return parseHexColor(trimmed);
+        }
+        if (HSL_REGEX_PATTERN.test(trimmed)) {
+            return parseHslColor(trimmed);
+        }
+        else if (RGB_REGEX_PATTERN.test(trimmed)) {
+            return parseRgbColor(trimmed);
+        }
+        else if (RGBA_REGEX_PATTERN.test(trimmed)) {
+            return parseRgbaColor(trimmed);
+        }
+        else {
+            throw new Error(`Can not create a new Color instance from string "${trimmed}".`);
+        }
+    }
+
     /**
      * Color object represents an RGB color with alpha channel
      *
@@ -460,7 +642,7 @@
      *
      * @public exported from `@promptbook/color`
      */
-    class Color {
+    class Color extends ColorValue {
         /**
          * Creates a new Color instance from miscellaneous formats
          * - It can receive Color instance and just return the same instance
@@ -533,25 +715,7 @@
          * @returns Color object
          */
         static fromString(color) {
-            const trimmed = color.trim();
-            if (CSS_COLORS[trimmed]) {
-                return Color.fromString(CSS_COLORS[trimmed]);
-            }
-            else if (Color.isHexColorString(trimmed)) {
-                return Color.fromHex(trimmed);
-            }
-            if (HSL_REGEX_PATTERN.test(trimmed)) {
-                return Color.fromHsl(trimmed);
-            }
-            else if (RGB_REGEX_PATTERN.test(trimmed)) {
-                return Color.fromRgbString(trimmed);
-            }
-            else if (RGBA_REGEX_PATTERN.test(trimmed)) {
-                return Color.fromRgbaString(trimmed);
-            }
-            else {
-                throw new Error(`Can not create a new Color instance from string "${trimmed}".`);
-            }
+            return Color.fromColorChannels(parseColorString(color));
         }
         /**
          * Gets common color
@@ -581,8 +745,7 @@
          * @returns Color object
          */
         static fromHex(hex) {
-            const { red, green, blue, alpha } = parseHexColor(hex);
-            return take(new Color(red, green, blue, alpha));
+            return Color.fromColorChannels(parseHexColor(hex));
         }
         /**
          * Creates a new Color instance from color in hsl format
@@ -591,8 +754,7 @@
          * @returns Color object
          */
         static fromHsl(hsl) {
-            const { red, green, blue, alpha } = parseHslColor(hsl);
-            return take(new Color(red, green, blue, alpha));
+            return Color.fromColorChannels(parseHslColor(hsl));
         }
         /**
          * Creates a new Color instance from color in rgb format
@@ -601,8 +763,7 @@
          * @returns Color object
          */
         static fromRgbString(rgb) {
-            const { red, green, blue, alpha } = parseRgbColor(rgb);
-            return take(new Color(red, green, blue, alpha));
+            return Color.fromColorChannels(parseRgbColor(rgb));
         }
         /**
          * Creates a new Color instance from color in rbga format
@@ -611,8 +772,7 @@
          * @returns Color object
          */
         static fromRgbaString(rgba) {
-            const { red, green, blue, alpha } = parseRgbaColor(rgba);
-            return take(new Color(red, green, blue, alpha));
+            return Color.fromColorChannels(parseRgbaColor(rgba));
         }
         /**
          * Creates a new Color for color channels values
@@ -624,7 +784,7 @@
          * @returns Color object
          */
         static fromValues(red, green, blue, alpha = 255) {
-            return take(new Color(red, green, blue, alpha));
+            return Color.fromColorChannels({ red, green, blue, alpha });
         }
         /**
          * Checks if the given value is a valid Color object.
@@ -657,8 +817,7 @@
          * @returns true if the value is a valid hex color string (e.g., `#009edd`, `#fff`, etc.)
          */
         static isHexColorString(value) {
-            return (typeof value === 'string' &&
-                /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/.test(value));
+            return isHexColorString(value);
         }
         /**
          * Creates new Color object
@@ -671,89 +830,13 @@
          * @param alpha number from 0 (transparent) to 255 (opaque)
          */
         constructor(red, green, blue, alpha = 255) {
-            this.red = red;
-            this.green = green;
-            this.blue = blue;
-            this.alpha = alpha;
-            checkChannelValue('Red', red);
-            checkChannelValue('Green', green);
-            checkChannelValue('Blue', blue);
-            checkChannelValue('Alpha', alpha);
-        }
-        /**
-         * Shortcut for `red` property
-         * Number from 0 to 255
-         * @alias red
-         */
-        get r() {
-            return this.red;
-        }
-        /**
-         * Shortcut for `green` property
-         * Number from 0 to 255
-         * @alias green
-         */
-        get g() {
-            return this.green;
-        }
-        /**
-         * Shortcut for `blue` property
-         * Number from 0 to 255
-         * @alias blue
-         */
-        get b() {
-            return this.blue;
-        }
-        /**
-         * Shortcut for `alpha` property
-         * Number from 0 (transparent) to 255 (opaque)
-         * @alias alpha
-         */
-        get a() {
-            return this.alpha;
-        }
-        /**
-         * Shortcut for `alpha` property
-         * Number from 0 (transparent) to 255 (opaque)
-         * @alias alpha
-         */
-        get opacity() {
-            return this.alpha;
-        }
-        /**
-         * Shortcut for 1-`alpha` property
-         */
-        get transparency() {
-            return 255 - this.alpha;
+            super(red, green, blue, alpha);
         }
-        clone() {
-            return take(new Color(this.red, this.green, this.blue, this.alpha));
-        }
-        toString() {
-            return this.toHex();
-        }
-        toHex() {
-            if (this.alpha === 255) {
-                return `#${this.red.toString(16).padStart(2, '0')}${this.green.toString(16).padStart(2, '0')}${this.blue
-                .toString(16)
-                .padStart(2, '0')}`;
-            }
-            else {
-                return `#${this.red.toString(16).padStart(2, '0')}${this.green.toString(16).padStart(2, '0')}${this.blue
-                .toString(16)
-                .padStart(2, '0')}${this.alpha.toString(16).padStart(2, '0')}`;
-            }
-        }
-        toRgb() {
-            if (this.alpha === 255) {
-                return `rgb(${this.red}, ${this.green}, ${this.blue})`;
-            }
-            else {
-                return `rgba(${this.red}, ${this.green}, ${this.blue}, ${Math.round((this.alpha / 255) * 100)}%)`;
-            }
+        createColor(red, green, blue, alpha) {
+            return new Color(red, green, blue, alpha);
         }
-        toHsl() {
-            throw new Error(`Getting HSL is not implemented`);
+        static fromColorChannels({ red, green, blue, alpha }) {
+            return take(new Color(red, green, blue, alpha));
         }
     }
 
@@ -817,9 +900,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
@@ -865,9 +946,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
@@ -885,9 +964,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
@@ -905,9 +982,36 @@
             return Color.fromValues(r, g, b, alpha);
         };
     }
+    // TODO: Maybe implement by mix+hsl
+
+    /**
+     * Stable root directory used for Promptbook-owned temporary files and caches.
+     *
+     * @private internal utility for Promptbook temporary folders
+     */
+    const PROMPTBOOK_TEMPORARY_DIRECTORY = '.promptbook';
+    /**
+     * Builds one normalized project-relative path inside Promptbook's dedicated temporary root.
+     *
+     * The returned path intentionally uses `/` separators so the same helper can be reused from
+     * Node.js and edge-safe code without depending on the Node `path` module.
+     *
+     * @private internal utility for Promptbook temporary folders
+     */
+    function getPromptbookTemporaryPath(...pathSegments) {
+        const normalizedPathSegments = pathSegments.flatMap(splitPathSegments).filter(Boolean);
+        return [PROMPTBOOK_TEMPORARY_DIRECTORY, ...normalizedPathSegments].join('/');
+    }
     /**
-     * TODO: Maybe implement by mix+hsl
+     * Normalizes one raw path segment into slash-delimited pieces without empty items.
      */
+    function splitPathSegments(pathSegment) {
+        return pathSegment
+            .split(/[\\/]+/u)
+            .map((segment) => segment.trim())
+            .filter(Boolean);
+    }
+    // Note: [💞] Ignore a discrepancy between file name and entity name
 
     /**
      * Name for the Promptbook
@@ -1002,7 +1106,32 @@
      *
      * @public exported from `@promptbook/utils`
      */
-    const SMALL_NUMBER = 0.001;
+    const SMALL_NUMBER = 0.001;
+    // <- TODO: [🕝] Make also `AGENTS_DIRNAME_ALTERNATIVES`
+    /**
+     * Where to store the temporary downloads
+     *
+     * Note: When the folder does not exist, it is created recursively
+     *
+     * @public exported from `@promptbook/core`
+     */
+`./${getPromptbookTemporaryPath('download-cache')}`;
+    /**
+     * Where to store the cache of executions for promptbook CLI
+     *
+     * Note: When the folder does not exist, it is created recursively
+     *
+     * @public exported from `@promptbook/core`
+     */
+`./${getPromptbookTemporaryPath('execution-cache')}`;
+    /**
+     * Where to store the scrape cache
+     *
+     * Note: When the folder does not exist, it is created recursively
+     *
+     * @public exported from `@promptbook/core`
+     */
+`./${getPromptbookTemporaryPath('scrape-cache')}`;
     // <- TODO: [🧜‍♂️]
     /**
      * Default settings for parsing and generating CSV files in Promptbook.
@@ -1031,6 +1160,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) {
@@ -1049,6 +1179,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) {
@@ -1065,9 +1196,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
@@ -1077,7 +1206,7 @@
     function getErrorReportUrl(error) {
         const report = {
             title: `🐜 Error report from ${NAME}`,
-            body: spaceTrim__default["default"]((block) => `
+            body: spacetrim.spaceTrim((block) => `
 
 
             \`${error.name || 'Error'}\` has occurred in the [${NAME}], please look into it @${ADMIN_GITHUB_NAME}.
@@ -1120,7 +1249,7 @@
      */
     class UnexpectedError extends Error {
         constructor(message) {
-            super(spaceTrim$1.spaceTrim((block) => `
+            super(spacetrim.spaceTrim((block) => `
                     ${block(message)}
 
                     Note: This error should not happen.
@@ -1146,7 +1275,7 @@
         constructor(whatWasThrown) {
             const tag = `[🤮]`;
             console.error(tag, whatWasThrown);
-            super(spaceTrim$1.spaceTrim(`
+            super(spacetrim.spaceTrim(`
                 Non-Error object was thrown
 
                 Note: Look for ${tag} in the console for more details
@@ -1203,125 +1332,187 @@
      * - And much more...
      *
      * @throws UnexpectedError if the value is not serializable as JSON
+     *
      * @public exported from `@promptbook/utils`
      */
     function checkSerializableAsJson(options) {
-        const { value, name, message } = options;
+        checkSerializableValue(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
+    /**
+     * Checks one value and dispatches to the appropriate specialized validator.
+     *
+     * @private function of `checkSerializableAsJson`
+     */
+    function checkSerializableValue(options) {
+        const { value } = options;
+        if (isSerializablePrimitive(value)) {
+            return;
+        }
         if (value === undefined) {
-            throw new UnexpectedError(`${name} is undefined`);
+            throw new UnexpectedError(`${options.name} is undefined`);
         }
-        else if (value === null) {
-            return;
+        if (typeof value === 'symbol') {
+            throw new UnexpectedError(`${options.name} is symbol`);
         }
-        else if (typeof value === 'boolean') {
-            return;
+        if (typeof value === 'function') {
+            throw new UnexpectedError(`${options.name} is function`);
         }
-        else if (typeof value === 'number' && !isNaN(value)) {
+        if (Array.isArray(value)) {
+            checkSerializableArray(options, value);
             return;
         }
-        else if (typeof value === 'string') {
+        if (value !== null && typeof value === 'object') {
+            checkSerializableObject(options, value);
             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 });
-            }
+        throwUnknownTypeError(options);
+    }
+    /**
+     * Checks the primitive values that are directly JSON serializable.
+     *
+     * @private function of `checkSerializableAsJson`
+     */
+    function isSerializablePrimitive(value) {
+        return (value === null ||
+            typeof value === 'boolean' ||
+            (typeof value === 'number' && !isNaN(value)) ||
+            typeof value === 'string');
+    }
+    /**
+     * Recursively checks JSON array items.
+     *
+     * @private function of `checkSerializableAsJson`
+     */
+    function checkSerializableArray(context, arrayValue) {
+        for (let index = 0; index < arrayValue.length; index++) {
+            checkSerializableAsJson({
+                ...context,
+                name: `${context.name}[${index}]`,
+                value: arrayValue[index],
+            });
         }
-        else if (typeof value === 'object') {
-            if (value instanceof Date) {
-                throw new UnexpectedError(spaceTrim__default["default"]((block) => `
-                        \`${name}\` is Date
+    }
+    /**
+     * Checks object-like values and dispatches special unsupported built-ins.
+     *
+     * @private function of `checkSerializableAsJson`
+     */
+    function checkSerializableObject(context, objectValue) {
+        checkUnsupportedObjectType(context, objectValue);
+        checkSerializableObjectEntries(context, objectValue);
+        assertJsonStringificationSucceeds(context, objectValue);
+    }
+    /**
+     * Rejects built-in objects that must be converted before JSON serialization.
+     *
+     * @private function of `checkSerializableAsJson`
+     */
+    function checkUnsupportedObjectType(context, objectValue) {
+        if (objectValue instanceof Date) {
+            throw new UnexpectedError(spacetrim.spaceTrim((block) => `
+                    \`${context.name}\` is Date
 
-                        Use \`string_date_iso8601\` instead
+                    Use \`string_date_iso8601\` instead
 
-                        Additional message for \`${name}\`:
-                        ${block(message || '(nothing)')}
-                    `));
-            }
-            else if (value instanceof Map) {
-                throw new UnexpectedError(`${name} is Map`);
-            }
-            else if (value instanceof Set) {
-                throw new UnexpectedError(`${name} is Set`);
-            }
-            else if (value instanceof RegExp) {
-                throw new UnexpectedError(`${name} is RegExp`);
-            }
-            else if (value instanceof Error) {
-                throw new UnexpectedError(spaceTrim__default["default"]((block) => `
-                        \`${name}\` is unserialized Error
+                    Additional message for \`${context.name}\`:
+                    ${block(context.message || '(nothing)')}
+                `));
+        }
+        if (objectValue instanceof Map) {
+            throw new UnexpectedError(`${context.name} is Map`);
+        }
+        if (objectValue instanceof Set) {
+            throw new UnexpectedError(`${context.name} is Set`);
+        }
+        if (objectValue instanceof RegExp) {
+            throw new UnexpectedError(`${context.name} is RegExp`);
+        }
+        if (objectValue instanceof Error) {
+            throw new UnexpectedError(spacetrim.spaceTrim((block) => `
+                    \`${context.name}\` is unserialized Error
 
-                        Use function \`serializeError\`
+                    Use function \`serializeError\`
 
-                        Additional message for \`${name}\`:
-                        ${block(message || '(nothing)')}
+                    Additional message for \`${context.name}\`:
+                    ${block(context.message || '(nothing)')}
 
-                    `));
+                `));
+        }
+    }
+    /**
+     * Recursively checks object properties while preserving omitted `undefined` keys.
+     *
+     * @private function of `checkSerializableAsJson`
+     */
+    function checkSerializableObjectEntries(context, objectValue) {
+        for (const [subName, subValue] of Object.entries(objectValue)) {
+            if (subValue === undefined) {
+                // Note: undefined in object is serializable - it is just omitted
+                continue;
             }
-            else {
-                for (const [subName, subValue] of Object.entries(value)) {
-                    if (subValue === undefined) {
-                        // Note: undefined in object is serializable - it is just omitted
-                        continue;
-                    }
-                    checkSerializableAsJson({ name: `${name}.${subName}`, value: subValue, message });
-                }
-                try {
-                    JSON.stringify(value); // <- TODO: [0]
-                }
-                catch (error) {
-                    assertsError(error);
-                    throw new UnexpectedError(spaceTrim__default["default"]((block) => `
-                            \`${name}\` is not serializable
+            checkSerializableAsJson({
+                ...context,
+                name: `${context.name}.${subName}`,
+                value: subValue,
+            });
+        }
+    }
+    /**
+     * Uses `JSON.stringify` as the final guard for cases like circular references.
+     *
+     * @private function of `checkSerializableAsJson`
+     */
+    function assertJsonStringificationSucceeds(context, objectValue) {
+        try {
+            JSON.stringify(objectValue); // <- TODO: [0]
+        }
+        catch (error) {
+            assertsError(error);
+            throw new UnexpectedError(spacetrim.spaceTrim((block) => `
+                    \`${context.name}\` is not serializable
 
-                            ${block(error.stack || error.message)}
+                    ${block(error.stack || error.message)}
 
-                            Additional message for \`${name}\`:
-                            ${block(message || '(nothing)')}
-                        `));
+                    Additional message for \`${context.name}\`:
+                    ${block(context.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`);
                 }
-                /*
-                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 })));
-                        }
-                    }
+                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__default["default"]((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
+     * Throws the fallback error for unsupported value types like `bigint` and `NaN`.
+     *
+     * @private function of `checkSerializableAsJson`
      */
+    function throwUnknownTypeError(context) {
+        throw new UnexpectedError(spacetrim.spaceTrim((block) => `
+                \`${context.name}\` is unknown type
+
+                Additional message for \`${context.name}\`:
+                ${block(context.message || '(nothing)')}
+            `));
+    }
 
     /**
      * Creates a deep clone of the given object
@@ -1331,6 +1522,7 @@
      *
      * @param objectValue The object to clone.
      * @returns A deep, writable clone of the input object.
+     *
      * @public exported from `@promptbook/utils`
      */
     function deepClone(objectValue) {
@@ -1347,9 +1539,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
@@ -1362,6 +1552,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) {
@@ -1381,9 +1572,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
 
     /**
      * Nonce which is used for replacing things in strings
@@ -1423,9 +1612,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.
@@ -1437,6 +1624,7 @@
      * @returns The camelCase formatted string.
      * @example 'helloWorld'
      * @example 'iLovePromptbook'
+     *
      * @public exported from `@promptbook/utils`
      */
     function normalizeTo_camelCase(text, _isFirstLetterCapital = false) {
@@ -1477,14 +1665,13 @@
         }
         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) {
@@ -1533,9 +1720,7 @@
         }
         return false;
     }
-    /**
-     * TODO: [🍏] Implement for MacOs
-     */
+    // TODO: [🍏] Implement for MacOs
 
     /**
      * Tests if given string is valid URL.
@@ -1568,6 +1753,9 @@
         }
     }
 
+    /**
+     * Collection of default diacritics removal map.
+     */
     const defaultDiacriticsRemovalMap = [
         {
             base: 'A',
@@ -1819,6 +2007,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) {
@@ -1827,9 +2016,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.
@@ -1840,6 +2027,7 @@
      * @returns The kebab-case formatted string.
      * @example 'hello-world'
      * @example 'i-love-promptbook'
+     *
      * @public exported from `@promptbook/utils`
      */
     function normalizeToKebabCase(text) {
@@ -1880,9 +2068,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
@@ -1891,6 +2077,7 @@
      *
      * @param text with emojis
      * @returns text without emojis
+     *
      * @public exported from `@promptbook/utils`
      */
     function removeEmojis(text) {
@@ -1910,6 +2097,7 @@
      * @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) {
@@ -1994,7 +2182,7 @@
             .filter(([MERMAID_NAME]) => (inputAndIntermediateParametersMermaid + outputParametersMermaid).includes(MERMAID_NAME))
             .map(([MERMAID_NAME, title]) => `${MERMAID_NAME}((${title})):::${MERMAID_NAME}`)
             .join('\n');
-        const promptbookMermaid = spaceTrim$1.spaceTrim((block) => `
+        const promptbookMermaid = spacetrim.spaceTrim((block) => `
 
             %% 🔮 Tip: Open this on GitHub or in the VSCode website to see the Mermaid graph visually
 
@@ -2028,13 +2216,11 @@
         `);
         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
@@ -2117,9 +2303,7 @@
             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
@@ -2137,10 +2321,11 @@
     /**
      * 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) {
@@ -2183,7 +2368,7 @@
      */
     class MissingToolsError extends Error {
         constructor(message) {
-            super(spaceTrim$1.spaceTrim((block) => `
+            super(spacetrim.spaceTrim((block) => `
                     ${block(message)}
 
                     Note: You have probably forgot to provide some tools for pipeline execution or preparation
@@ -2227,7 +2412,7 @@
      */
     class NotYetImplementedError extends Error {
         constructor(message) {
-            super(spaceTrim$1.spaceTrim((block) => `
+            super(spacetrim.spaceTrim((block) => `
                     ${block(message)}
 
                     Note: This feature is not implemented yet but it will be soon.
@@ -2255,9 +2440,7 @@
             Object.setPrototypeOf(this, ParseError.prototype);
         }
     }
-    /**
-     * TODO: Maybe split `ParseError` and `ApplyError`
-     */
+    // TODO: Maybe split `ParseError` and `ApplyError`
 
     /**
      * Generates random token
@@ -2265,16 +2448,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
@@ -2291,9 +2473,7 @@
             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)
@@ -2395,9 +2575,7 @@
         ...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
@@ -2413,7 +2591,7 @@
             message = `${name}: ${message}`;
         }
         if (isStackAddedToMessage && stack !== undefined && stack !== '') {
-            message = spaceTrim__default["default"]((block) => `
+            message = spacetrim.spaceTrim((block) => `
                 ${block(message)}
 
                 Original stack trace:
@@ -2434,7 +2612,7 @@
         const { name, message, stack } = error;
         const { id } = error;
         if (!Object.keys(ALL_ERRORS).includes(name)) {
-            console.error(spaceTrim__default["default"]((block) => `
+            console.error(spacetrim.spaceTrim((block) => `
 
                     Cannot serialize error with name "${name}"
 
@@ -2460,8 +2638,9 @@
      * @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;
@@ -2540,7 +2719,7 @@
         }
         else if (typeof value !== 'string') {
             console.error('Can not parse JSON from non-string value.', { text: value });
-            throw new Error(spaceTrim__default["default"](`
+            throw new Error(spacetrim.spaceTrim(`
                     Can not parse JSON from non-string value.
 
                     The value type: ${typeof value}
@@ -2554,7 +2733,7 @@
             if (!(error instanceof Error)) {
                 throw error;
             }
-            throw new Error(spaceTrim__default["default"]((block) => `
+            throw new Error(spacetrim.spaceTrim((block) => `
                     ${block(error.message)}
 
                     The expected JSON text:
@@ -2620,8 +2799,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
@@ -2672,12 +2851,13 @@
      * 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) {
@@ -2761,6 +2941,7 @@
      * 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) {
@@ -2775,6 +2956,7 @@
      * 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) {
@@ -2784,6 +2966,7 @@
      * Restores hidden brackets.
      *
      * @param value String with hidden brackets.
+     *
      * @private function of ParameterEscaping
      */
     function restoreBrackets(value) {
@@ -2793,6 +2976,7 @@
      * Decides whether a parameter can be inlined safely.
      *
      * @param value Parameter rendered as string.
+     *
      * @private function of ParameterEscaping
      */
     function shouldInlineParameterValue(value) {
@@ -2806,6 +2990,7 @@
      *
      * @param value Parameter value to escape.
      * @param options Escape options for additional characters.
+     *
      * @private function of ParameterEscaping
      */
     function escapePromptParameterValue(value, options) {
@@ -2831,6 +3016,7 @@
      * Builds numeric parameter names (1, 2, ...).
      *
      * @param index Zero-based parameter index.
+     *
      * @private function of ParameterNaming
      */
     function buildNumericParameterName(index) {
@@ -2840,6 +3026,7 @@
      * Builds alphabetic parameter names (a, b, ..., aa).
      *
      * @param index Zero-based parameter index.
+     *
      * @private function of ParameterNaming
      */
     function buildAlphabeticParameterName(index) {
@@ -2856,6 +3043,7 @@
      * Converts a positive integer into a Roman numeral string.
      *
      * @param value Positive integer value.
+     *
      * @private function of ParameterNaming
      */
     function toRomanNumeral(value) {
@@ -2888,6 +3076,7 @@
      * Builds Roman numeral parameter names (I, II, ...).
      *
      * @param index Zero-based parameter index.
+     *
      * @private function of ParameterNaming
      */
     function buildRomanParameterName(index) {
@@ -2898,6 +3087,7 @@
      *
      * @param prefix Prefix string.
      * @param builder Base builder function.
+     *
      * @private function of ParameterNaming
      */
     function buildPrefixedParameterName(prefix, builder) {
@@ -2919,6 +3109,7 @@
      * Collects bracketed tokens from parameter values to avoid placeholder collisions.
      *
      * @param values Parameter values to scan.
+     *
      * @private function of ParameterNaming
      */
     function collectBracketedParameterTokens(values) {
@@ -2939,6 +3130,7 @@
      * 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) {
@@ -2969,6 +3161,7 @@
      * Formats the placeholder used in the prompt body for a parameter.
      *
      * @param name Parameter placeholder name.
+     *
      * @private function of ParameterSection
      */
     function formatParameterPlaceholder(name) {
@@ -2978,6 +3171,7 @@
      * Formats a single line entry for structured parameters.
      *
      * @param item Parameter entry data.
+     *
      * @private function of ParameterSection
      */
     function formatParameterListItem(item) {
@@ -2989,13 +3183,14 @@
      * Builds the structured parameters section appended to the prompt.
      *
      * @param items Parameter entries to include.
+     *
      * @private function of ParameterSection
      */
     function buildParametersSection(items) {
         const entries = items
             .flatMap((item) => formatParameterListItem(item).split(/\r?\n/))
             .filter((line) => line !== '');
-        return spaceTrim__default["default"]((block) => `
+        return spacetrim.spaceTrim((block) => `
             **Parameters:**
             ${block(entries.join('\n'))}
 
@@ -3064,11 +3259,12 @@
      * @param strings
      * @param values
      * @returns prompt content wrapped as a PromptString
+     *
      * @public exported from `@promptbook/utils`
      */
     function prompt(strings, ...values) {
         if (values.length === 0) {
-            return new PromptString(spaceTrim__default["default"](strings.join('')));
+            return new PromptString(spacetrim.spaceTrim(strings.join('')));
         }
         const stringsWithHiddenParameters = strings.map((stringsItem) => ParameterEscaping.hideBrackets(stringsItem));
         const parameterMetadata = values.map((value) => {
@@ -3109,7 +3305,7 @@
                 ? `${result}${stringsItem}`
                 : `${result}${stringsItem}${ParameterSection.formatParameterPlaceholder(parameterName)}`;
         }, '');
-        pipelineString = spaceTrim__default["default"](pipelineString);
+        pipelineString = spacetrim.spaceTrim(pipelineString);
         try {
             pipelineString = templateParameters(pipelineString, parameters);
         }
@@ -3118,7 +3314,7 @@
                 throw error;
             }
             console.error({ pipelineString, parameters, parameterNames: parameterNamesOrdered, error });
-            throw new UnexpectedError(spaceTrim__default["default"]((block) => `
+            throw new UnexpectedError(spacetrim.spaceTrim((block) => `
                     Internal error in prompt template literal
                   
                     ${block(JSON.stringify({ strings, values }, null, 4))}}
@@ -3157,14 +3353,13 @@
      * 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
 
     /**
      * @@@
@@ -3208,7 +3403,7 @@
      */
     function formatClientVersionMismatchMessage(clientVersion) {
         const reportedVersion = clientVersion !== null && clientVersion !== void 0 ? clientVersion : 'unknown';
-        return spaceTrim__default["default"](`
+        return spacetrim.spaceTrim(`
         A new version of Promptbook is available.
         Please refresh the page to keep using the latest experience (currently using v${reportedVersion}).
     `);
@@ -3260,9 +3455,7 @@
         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)
@@ -3279,9 +3472,7 @@
             return false;
         }
     }
-    /**
-     * TODO: [🎺]
-     */
+    // TODO: [🎺]
 
     /**
      * Detects if the code is running in jest environment
@@ -3299,9 +3490,7 @@
             return false;
         }
     }
-    /**
-     * TODO: [🎺]
-     */
+    // TODO: [🎺]
 
     /**
      * Detects if the code is running in a Node.js environment
@@ -3318,9 +3507,7 @@
             return false;
         }
     }
-    /**
-     * TODO: [🎺]
-     */
+    // TODO: [🎺]
 
     /**
      * Detects if the code is running in a web worker
@@ -3340,9 +3527,7 @@
             return false;
         }
     }
-    /**
-     * TODO: [🎺]
-     */
+    // TODO: [🎺]
 
     /**
      * Returns information about the current runtime environment
@@ -3359,9 +3544,7 @@
             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.
@@ -3375,10 +3558,8 @@
      * @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
@@ -3394,10 +3575,8 @@
         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
@@ -3415,10 +3594,8 @@
         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
@@ -3430,10 +3607,8 @@
     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
@@ -3443,10 +3618,8 @@
     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
@@ -3464,10 +3637,8 @@
     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
@@ -3481,11 +3652,9 @@
         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
@@ -3500,10 +3669,8 @@
         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
@@ -3511,11 +3678,9 @@
      * @public exported from `@promptbook/utils`
      */
     function computeHash(value) {
-        return cryptoJs.SHA256(hexEncoder__default["default"].parse(spaceTrim__default["default"](valueToString(value)))).toString( /* hex */);
+        return cryptoJs.SHA256(hexEncoder__default["default"].parse(spacetrim.spaceTrim(valueToString(value)))).toString( /* hex */);
     }
-    /**
-     * TODO: [🥬][🥬] Use this ACRY
-     */
+    // TODO: [🥬][🥬] Use this ACRY
 
     /**
      * Makes first letter of a string uppercase
@@ -3692,6 +3857,9 @@
         'prvotní',
         'hbitý',
     ];
+    /**
+     * Collection of nouns.
+     */
     const NOUNS$1 = [
         'jablko',
         'nebe',
@@ -3905,6 +4073,9 @@
         'okno',
         'chodba',
     ];
+    /**
+     * Collection of verbs.
+     */
     const VERBS$1 = [
         'skáče',
         'tančí',
@@ -4077,9 +4248,7 @@
         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
 
     /**
      * @@@
@@ -4335,6 +4504,9 @@
         'macro',
         'mini',
     ];
+    /**
+     * Collection of nouns.
+     */
     const NOUNS = [
         'apple',
         'sky',
@@ -4574,6 +4746,9 @@
         'roof',
         'floor',
     ];
+    /**
+     * Collection of verbs.
+     */
     const VERBS = [
         'jumping',
         'dancing',
@@ -4769,9 +4944,7 @@
         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.
@@ -4946,8 +5119,9 @@
     /**
      * 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`
@@ -4966,6 +5140,7 @@
      * 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() {
@@ -4973,6 +5148,8 @@
     }
 
     /**
+     * Handles debounce.
+     *
      * @public exported from `@promptbook/utils`
      */
     function debounce(fn, delay) {
@@ -5051,10 +5228,8 @@
         }
         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
@@ -5076,6 +5251,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) {
@@ -5129,6 +5305,7 @@
      *
      * @param {string} input
      * @returns {Set} of keywords without diacritics in lowercase
+     *
      * @public exported from `@promptbook/utils`
      */
     function parseKeywordsFromString(input) {
@@ -5163,6 +5340,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) {
@@ -5181,6 +5359,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) {
@@ -5198,7 +5377,7 @@
      * @public exported from `@promptbook/utils`
      */
     function normalizeMessageText(text) {
-        return spaceTrim$1.spaceTrim(text);
+        return spacetrim.spaceTrim(text);
     }
 
     /**
@@ -5210,6 +5389,7 @@
      * @returns
      * @example 'HelloWorld'
      * @example 'ILovePromptbook'
+     *
      * @public exported from `@promptbook/utils`
      */
     function normalizeTo_PascalCase(text) {
@@ -5225,6 +5405,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) {
@@ -5249,6 +5430,7 @@
      *
      * @param input of any kind
      * @returns {Set} of keywords without diacritics in lowercase
+     *
      * @public exported from `@promptbook/utils`
      */
     function parseKeywords(input) {
@@ -5270,10 +5452,8 @@
             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
@@ -5287,6 +5467,7 @@
      *
      * @param text optionally quoted text
      * @returns text without quotes
+     *
      * @public exported from `@promptbook/utils`
      */
     function removeQuotes(text) {
@@ -5305,6 +5486,7 @@
      * @param haystack
      * @param needle
      * @returns
+     *
      * @public exported from `@promptbook/utils`
      */
     function searchKeywords(haystack, needle) {
@@ -5315,9 +5497,7 @@
         }
         return true;
     }
-    /**
-     * TODO: Rename to `isKeywordInKeywords`
-     */
+    // TODO: Rename to `isKeywordInKeywords`
 
     /**
      * Adds suffix to the URL
@@ -5341,6 +5521,7 @@
      *
      * @param text optionally quoted text
      * @returns text without quotes
+     *
      * @public exported from `@promptbook/utils`
      */
     function unwrapResult(text, options) {
@@ -5348,7 +5529,7 @@
         let trimmedText = text;
         // Remove leading and trailing spaces and newlines
         if (isTrimmed) {
-            trimmedText = spaceTrim$1.spaceTrim(trimmedText);
+            trimmedText = spacetrim.spaceTrim(trimmedText);
         }
         let processedText = trimmedText;
         // Check for markdown code block
@@ -5367,7 +5548,7 @@
                 // Remove the introduce sentence and quotes by replacing it with an empty string
                 processedText = processedText.replace(introduceSentenceRegex, '');
             }
-            processedText = spaceTrim$1.spaceTrim(processedText);
+            processedText = spacetrim.spaceTrim(processedText);
             // Check again for code block after removing introduce sentence
             const codeBlockMatch2 = processedText.match(codeBlockRegex);
             if (codeBlockMatch2 && codeBlockMatch2[1] !== undefined) {
@@ -5415,15 +5596,14 @@
             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) {
@@ -5443,6 +5623,7 @@
      *
      * @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) {
@@ -5464,9 +5645,7 @@
             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';`
     /**
@@ -5485,7 +5664,6 @@
      * - `Symbol` objects are not serializable
      * - And much more...
      *
-     *
      * @public exported from `@promptbook/utils`
      */
     function isSerializableAsJson(value) {
@@ -5497,14 +5675,12 @@
             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) {
@@ -5528,9 +5704,7 @@
         }
         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.
@@ -5540,7 +5714,10 @@
     function serializeToPromptbookJavascript(value) {
         let serializedValue;
         let imports = [];
-        if (value === null || value === undefined || typeof value === 'number' || typeof value === 'boolean') {
+        if (value === undefined) {
+            serializedValue = 'undefined';
+        }
+        else if (value === null || typeof value === 'number' || typeof value === 'boolean') {
             serializedValue = JSON.stringify(value, null, 4);
         }
         else if (Array.isArray(value)) {
@@ -5556,7 +5733,7 @@
             imports.push(`import { Color } from '@promptbook/color';`);
         }
         else if (typeof value === 'string') {
-            const trimmed = spaceTrim__default["default"](value);
+            const trimmed = spacetrim.spaceTrim(value);
             if (trimmed.includes('\n')) {
                 // Multiline string -> use `spaceTrim`
                 serializedValue = `spaceTrim(\`\n${value.replace(/`/g, '\\`')}\n\`)`;
@@ -5590,14 +5767,13 @@
         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) {
@@ -5609,14 +5785,13 @@
         }
         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) {
@@ -5642,6 +5817,7 @@
      * 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) {
@@ -5673,6 +5849,7 @@
      * 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) {
@@ -5684,15 +5861,14 @@
         }
         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) {
@@ -5725,12 +5901,13 @@
      * 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) {
@@ -5788,6 +5965,7 @@
      * @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 = {}) {
@@ -5826,9 +6004,7 @@
         */
         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.
@@ -5859,9 +6035,7 @@
         */
         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