@promptbook/utils 0.112.0-73 → 0.112.0-80

package/umd/index.umd.js

@@ -22,7 +22,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-73';
+    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-80';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -272,6 +272,111 @@
         }
     }
 
+    /**
+     * 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.
      */
@@ -483,16 +588,53 @@
 
     /**
      * 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
      *
@@ -500,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
@@ -573,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
@@ -621,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
@@ -631,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
@@ -641,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
@@ -651,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
@@ -664,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.
@@ -697,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
@@ -711,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;
+            super(red, green, blue, alpha);
         }
-        /**
-         * Shortcut for `alpha` property
-         * Number from 0 (transparent) to 255 (opaque)
-         * @alias alpha
-         */
-        get opacity() {
-            return this.alpha;
+        createColor(red, green, blue, alpha) {
+            return new Color(red, green, blue, alpha);
         }
-        /**
-         * Shortcut for 1-`alpha` property
-         */
-        get transparency() {
-            return 255 - this.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)}%)`;
-            }
-        }
-        toHsl() {
-            throw new Error(`Getting HSL is not implemented`);
+        static fromColorChannels({ red, green, blue, alpha }) {
+            return take(new Color(red, green, blue, alpha));
         }
     }
 
@@ -1293,120 +1336,183 @@
      * @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.spaceTrim((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.spaceTrim((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.spaceTrim((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.spaceTrim((block) => `
-                    \`${name}\` is unknown type
+        */
+    }
+    /**
+     * 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 \`${name}\`:
-                    ${block(message || '(nothing)')}
-                `));
-        }
+                Additional message for \`${context.name}\`:
+                ${block(context.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
 
     /**
      * Creates a deep clone of the given object