@promptbook/utils 0.79.0 → 0.80.0-0

package/umd/index.umd.js

@@ -20,7 +20,7 @@
      *
      * @see https://github.com/webgptorg/promptbook
      */
-    var PROMPTBOOK_ENGINE_VERSION = '0.78.4';
+    var PROMPTBOOK_ENGINE_VERSION = '0.79.0';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -172,24 +172,6 @@
      * @private within the repository - too low-level in comparison with other `MAX_...`
      */
     var LOOP_LIMIT = 1000;
-    /**
-     * Nonce which is used for replacing things in strings
-     *
-     * @private within the repository
-     */
-    var REPLACING_NONCE = 'u$k42k%!V2zo34w7Fu#@QUHYPW';
-    /**
-     * @@@
-     *
-     * @private within the repository
-     */
-    var RESERVED_PARAMETER_MISSING_VALUE = 'MISSING-' + REPLACING_NONCE;
-    /**
-     * @@@
-     *
-     * @private within the repository
-     */
-    var RESERVED_PARAMETER_RESTRICTED = 'RESTRICTED-' + REPLACING_NONCE;
     // <- TODO: [🧜‍♂️]
     /**
      * @@@
@@ -203,7 +185,6 @@
         skipEmptyLines: true,
     });
     /**
-     * TODO: Extract `constants.ts` from `config.ts`
      * Note: [💞] Ignore a discrepancy between file name and entity name
      * TODO: [🧠][🧜‍♂️] Maybe join remoteUrl and path into single value
      */
@@ -1612,6 +1593,18 @@
         return sentence.replace(/\s+/gs, ' ').trim();
     }
 
+    /**
+     * Orders JSON object by keys
+     *
+     * @returns The same type of object as the input re-ordered
+     * @public exported from `@promptbook/utils`
+     */
+    function orderJson(options) {
+        var value = options.value, order = options.order;
+        var orderedValue = __assign(__assign({}, (order === undefined ? {} : Object.fromEntries(order.map(function (key) { return [key, undefined]; })))), value);
+        return orderedValue;
+    }
+
     /**
      * Parses keywords from any object and recursively walks through
      *
@@ -1717,6 +1710,268 @@
         return parameterNames;
     }
 
+    /**
+     * Freezes the given object and all its nested objects recursively
+     *
+     * Note: `$` is used to indicate that this function is not a pure function - it mutates given object
+     * Note: This function mutates the object and returns the original (but mutated-deep-freezed) object
+     *
+     * @returns The same object as the input, but deeply frozen
+     * @public exported from `@promptbook/utils`
+     */
+    function $deepFreeze(objectValue) {
+        var e_1, _a;
+        if (Array.isArray(objectValue)) {
+            return Object.freeze(objectValue.map(function (item) { return $deepFreeze(item); }));
+        }
+        var propertyNames = Object.getOwnPropertyNames(objectValue);
+        try {
+            for (var propertyNames_1 = __values(propertyNames), propertyNames_1_1 = propertyNames_1.next(); !propertyNames_1_1.done; propertyNames_1_1 = propertyNames_1.next()) {
+                var propertyName = propertyNames_1_1.value;
+                var value = objectValue[propertyName];
+                if (value && typeof value === 'object') {
+                    $deepFreeze(value);
+                }
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (propertyNames_1_1 && !propertyNames_1_1.done && (_a = propertyNames_1.return)) _a.call(propertyNames_1);
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+        Object.freeze(objectValue);
+        return objectValue;
+    }
+    /**
+     * TODO: [🧠] Is there a way how to meaningfully test this utility
+     */
+
+    /**
+     * Checks if the value is [🚉] serializable as JSON
+     * If not, throws an UnexpectedError with a rich error message and tracking
+     *
+     * - Almost all primitives are serializable BUT:
+     * - `undefined` is not serializable
+     * - `NaN` is not serializable
+     * - Objects and arrays are serializable if all their properties are serializable
+     * - Functions are not serializable
+     * - Circular references are not serializable
+     * - `Date` objects are not serializable
+     * - `Map` and `Set` objects are not serializable
+     * - `RegExp` objects are not serializable
+     * - `Error` objects are not serializable
+     * - `Symbol` objects are not serializable
+     * - And much more...
+     *
+     * @throws UnexpectedError if the value is not serializable as JSON
+     * @public exported from `@promptbook/utils`
+     */
+    function checkSerializableAsJson(options) {
+        var e_1, _a;
+        var value = options.value, name = options.name, message = options.message;
+        if (value === undefined) {
+            throw new UnexpectedError("".concat(name, " is undefined"));
+        }
+        else if (value === null) {
+            return;
+        }
+        else if (typeof value === 'boolean') {
+            return;
+        }
+        else if (typeof value === 'number' && !isNaN(value)) {
+            return;
+        }
+        else if (typeof value === 'string') {
+            return;
+        }
+        else if (typeof value === 'symbol') {
+            throw new UnexpectedError("".concat(name, " is symbol"));
+        }
+        else if (typeof value === 'function') {
+            throw new UnexpectedError("".concat(name, " is function"));
+        }
+        else if (typeof value === 'object' && Array.isArray(value)) {
+            for (var i = 0; i < value.length; i++) {
+                checkSerializableAsJson({ name: "".concat(name, "[").concat(i, "]"), value: value[i], message: message });
+            }
+        }
+        else if (typeof value === 'object') {
+            if (value instanceof Date) {
+                throw new UnexpectedError(spaceTrim__default["default"](function (block) { return "\n                        `".concat(name, "` is Date\n\n                        Use `string_date_iso8601` instead\n\n                        Additional message for `").concat(name, "`:\n                        ").concat(block(message || '(nothing)'), "\n                    "); }));
+            }
+            else if (value instanceof Map) {
+                throw new UnexpectedError("".concat(name, " is Map"));
+            }
+            else if (value instanceof Set) {
+                throw new UnexpectedError("".concat(name, " is Set"));
+            }
+            else if (value instanceof RegExp) {
+                throw new UnexpectedError("".concat(name, " is RegExp"));
+            }
+            else if (value instanceof Error) {
+                throw new UnexpectedError(spaceTrim__default["default"](function (block) { return "\n                        `".concat(name, "` is unserialized Error\n\n                        Use function `serializeError`\n\n                        Additional message for `").concat(name, "`:\n                        ").concat(block(message || '(nothing)'), "\n\n                    "); }));
+            }
+            else {
+                try {
+                    for (var _b = __values(Object.entries(value)), _c = _b.next(); !_c.done; _c = _b.next()) {
+                        var _d = __read(_c.value, 2), subName = _d[0], subValue = _d[1];
+                        if (subValue === undefined) {
+                            // Note: undefined in object is serializable - it is just omited
+                            continue;
+                        }
+                        checkSerializableAsJson({ name: "".concat(name, ".").concat(subName), value: subValue, message: message });
+                    }
+                }
+                catch (e_1_1) { e_1 = { error: e_1_1 }; }
+                finally {
+                    try {
+                        if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+                    }
+                    finally { if (e_1) throw e_1.error; }
+                }
+                try {
+                    JSON.stringify(value); // <- TODO: [0]
+                }
+                catch (error) {
+                    if (!(error instanceof Error)) {
+                        throw error;
+                    }
+                    throw new UnexpectedError(spaceTrim__default["default"](function (block) { return "\n                            `".concat(name, "` is not serializable\n\n                            ").concat(block(error.toString()), "\n\n                            Additional message for `").concat(name, "`:\n                            ").concat(block(message || '(nothing)'), "\n                        "); }));
+                }
+                /*
+                TODO: [0] Is there some more elegant way to check circular references?
+                const seen = new Set();
+                const stack = [{ value }];
+                while (stack.length > 0) {
+                    const { value } = stack.pop()!;
+                    if (typeof value === 'object' && value !== null) {
+                        if (seen.has(value)) {
+                            throw new UnexpectedError(`${name} has circular reference`);
+                        }
+                        seen.add(value);
+                        if (Array.isArray(value)) {
+                            stack.push(...value.map((value) => ({ value })));
+                        } else {
+                            stack.push(...Object.values(value).map((value) => ({ value })));
+                        }
+                    }
+                }
+                */
+                return;
+            }
+        }
+        else {
+            throw new UnexpectedError(spaceTrim__default["default"](function (block) { return "\n                    `".concat(name, "` is unknown type\n\n                    Additional message for `").concat(name, "`:\n                    ").concat(block(message || '(nothing)'), "\n                "); }));
+        }
+    }
+    /**
+     * TODO: Can be return type more type-safe? like `asserts options.value is JsonValue`
+     * TODO: [🧠][main] !!! In-memory cache of same values to prevent multiple checks
+     * Note: [🐠] This is how `checkSerializableAsJson` + `isSerializableAsJson` together can just retun true/false or rich error message
+     */
+
+    /**
+     * @@@
+     *
+     * @public exported from `@promptbook/utils`
+     */
+    function deepClone(objectValue) {
+        return JSON.parse(JSON.stringify(objectValue));
+        /*
+        !!!!!!!!
+        TODO: [🧠] Is there a better implementation?
+        > const propertyNames = Object.getOwnPropertyNames(objectValue);
+        > for (const propertyName of propertyNames) {
+        >     const value = (objectValue as really_any)[propertyName];
+        >     if (value && typeof value === 'object') {
+        >         deepClone(value);
+        >     }
+        > }
+        > return Object.assign({}, objectValue);
+        */
+    }
+    /**
+     * TODO: [🧠] Is there a way how to meaningfully test this utility
+     */
+
+    /**
+     * Utility to export a JSON object from a function
+     *
+     * 1) Checks if the value is serializable as JSON
+     * 2) Makes a deep clone of the object
+     * 2) Orders the object properties
+     * 2) Deeply freezes the cloned object
+     *
+     * Note: This function does not mutates the given object
+     *
+     * @returns The same type of object as the input but read-only and re-ordered
+     * @public exported from `@promptbook/utils`
+     */
+    function exportJson(options) {
+        var name = options.name, value = options.value, order = options.order, message = options.message;
+        checkSerializableAsJson({ name: name, value: value, message: message });
+        var orderedValue = 
+        // TODO: Fix error "Type instantiation is excessively deep and possibly infinite."
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore
+        order === undefined
+            ? deepClone(value)
+            : orderJson({
+                value: value,
+                // <- Note: checkSerializableAsJson asserts that the value is serializable as JSON
+                order: order,
+            });
+        $deepFreeze(orderedValue);
+        return orderedValue;
+    }
+    /**
+     * TODO: [🧠] Is there a way how to meaningfully test this utility
+     */
+
+    /**
+     * Nonce which is used for replacing things in strings
+     *
+     * @private within the repository
+     */
+    var REPLACING_NONCE = 'u$k42k%!V2zo34w7Fu#@QUHYPW';
+    /**
+     * @@@
+     *
+     * @private within the repository
+     */
+    var RESERVED_PARAMETER_MISSING_VALUE = 'MISSING-' + REPLACING_NONCE;
+    /**
+     * @@@
+     *
+     * @private within the repository
+     */
+    var RESERVED_PARAMETER_RESTRICTED = 'RESTRICTED-' + REPLACING_NONCE;
+    /**
+     * The names of the parameters that are reserved for special purposes
+     *
+     * @public exported from `@promptbook/core`
+     */
+    exportJson({
+        name: 'RESERVED_PARAMETER_NAMES',
+        message: "The names of the parameters that are reserved for special purposes",
+        value: [
+            'content',
+            'context',
+            'knowledge',
+            'examples',
+            'modelName',
+            'currentDate',
+            // <- TODO: list here all command names
+            // <- TODO: Add more like 'date', 'modelName',...
+            // <- TODO: Add [emoji] + instructions ACRY when adding new reserved parameter
+        ],
+    });
+    /**
+     * Note: [💞] Ignore a discrepancy between file name and entity name
+     */
+
     /**
      * Replaces parameters in template with values from parameters object
      *
@@ -1898,166 +2153,6 @@
         return text;
     }
 
-    /**
-     * @@@
-     *
-     * Note: `$` is used to indicate that this function is not a pure function - it mutates given object
-     * Note: This function mutates the object and returns the original (but mutated-deep-freezed) object
-     *
-     * @returns The same object as the input, but deeply frozen
-     * @public exported from `@promptbook/utils`
-     */
-    function $deepFreeze(objectValue) {
-        var e_1, _a;
-        if (Array.isArray(objectValue)) {
-            return Object.freeze(objectValue.map(function (item) { return $deepFreeze(item); }));
-        }
-        var propertyNames = Object.getOwnPropertyNames(objectValue);
-        try {
-            for (var propertyNames_1 = __values(propertyNames), propertyNames_1_1 = propertyNames_1.next(); !propertyNames_1_1.done; propertyNames_1_1 = propertyNames_1.next()) {
-                var propertyName = propertyNames_1_1.value;
-                var value = objectValue[propertyName];
-                if (value && typeof value === 'object') {
-                    $deepFreeze(value);
-                }
-            }
-        }
-        catch (e_1_1) { e_1 = { error: e_1_1 }; }
-        finally {
-            try {
-                if (propertyNames_1_1 && !propertyNames_1_1.done && (_a = propertyNames_1.return)) _a.call(propertyNames_1);
-            }
-            finally { if (e_1) throw e_1.error; }
-        }
-        return Object.freeze(objectValue);
-    }
-    /**
-     * TODO: [🧠] Is there a way how to meaningfully test this utility
-     */
-
-    /**
-     * Checks if the value is [🚉] serializable as JSON
-     * If not, throws an UnexpectedError with a rich error message and tracking
-     *
-     * - Almost all primitives are serializable BUT:
-     * - `undefined` is not serializable
-     * - `NaN` is not serializable
-     * - Objects and arrays are serializable if all their properties are serializable
-     * - Functions are not serializable
-     * - Circular references are not serializable
-     * - `Date` objects are not serializable
-     * - `Map` and `Set` objects are not serializable
-     * - `RegExp` objects are not serializable
-     * - `Error` objects are not serializable
-     * - `Symbol` objects are not serializable
-     * - And much more...
-     *
-     * @throws UnexpectedError if the value is not serializable as JSON
-     * @public exported from `@promptbook/utils`
-     */
-    function checkSerializableAsJson(name, value) {
-        var e_1, _a;
-        if (value === undefined) {
-            throw new UnexpectedError("".concat(name, " is undefined"));
-        }
-        else if (value === null) {
-            return;
-        }
-        else if (typeof value === 'boolean') {
-            return;
-        }
-        else if (typeof value === 'number' && !isNaN(value)) {
-            return;
-        }
-        else if (typeof value === 'string') {
-            return;
-        }
-        else if (typeof value === 'symbol') {
-            throw new UnexpectedError("".concat(name, " is symbol"));
-        }
-        else if (typeof value === 'function') {
-            throw new UnexpectedError("".concat(name, " is function"));
-        }
-        else if (typeof value === 'object' && Array.isArray(value)) {
-            for (var i = 0; i < value.length; i++) {
-                checkSerializableAsJson("".concat(name, "[").concat(i, "]"), value[i]);
-            }
-        }
-        else if (typeof value === 'object') {
-            if (value instanceof Date) {
-                throw new UnexpectedError(spaceTrim__default["default"]("\n                    ".concat(name, " is Date\n\n                    Use `string_date_iso8601` instead\n                ")));
-            }
-            else if (value instanceof Map) {
-                throw new UnexpectedError("".concat(name, " is Map"));
-            }
-            else if (value instanceof Set) {
-                throw new UnexpectedError("".concat(name, " is Set"));
-            }
-            else if (value instanceof RegExp) {
-                throw new UnexpectedError("".concat(name, " is RegExp"));
-            }
-            else if (value instanceof Error) {
-                throw new UnexpectedError(spaceTrim__default["default"]("\n                    ".concat(name, " is unserialized Error\n\n                    Use function `serializeError`\n                ")));
-            }
-            else {
-                try {
-                    for (var _b = __values(Object.entries(value)), _c = _b.next(); !_c.done; _c = _b.next()) {
-                        var _d = __read(_c.value, 2), subName = _d[0], subValue = _d[1];
-                        if (subValue === undefined) {
-                            // Note: undefined in object is serializable - it is just omited
-                            continue;
-                        }
-                        checkSerializableAsJson("".concat(name, ".").concat(subName), subValue);
-                    }
-                }
-                catch (e_1_1) { e_1 = { error: e_1_1 }; }
-                finally {
-                    try {
-                        if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
-                    }
-                    finally { if (e_1) throw e_1.error; }
-                }
-                try {
-                    JSON.stringify(value); // <- TODO: [0]
-                }
-                catch (error) {
-                    if (!(error instanceof Error)) {
-                        throw error;
-                    }
-                    throw new UnexpectedError(spaceTrim__default["default"](function (block) { return "\n                            ".concat(name, " is not serializable\n\n                            ").concat(block(error.toString()), "\n                        "); }));
-                }
-                /*
-                TODO: [0] Is there some more elegant way to check circular references?
-                const seen = new Set();
-                const stack = [{ value }];
-                while (stack.length > 0) {
-                    const { value } = stack.pop()!;
-                    if (typeof value === 'object' && value !== null) {
-                        if (seen.has(value)) {
-                            throw new UnexpectedError(`${name} has circular reference`);
-                        }
-                        seen.add(value);
-                        if (Array.isArray(value)) {
-                            stack.push(...value.map((value) => ({ value })));
-                        } else {
-                            stack.push(...Object.values(value).map((value) => ({ value })));
-                        }
-                    }
-                }
-                */
-                return;
-            }
-        }
-        else {
-            throw new UnexpectedError("".concat(name, " is unknown"));
-        }
-    }
-    /**
-     * TODO: [🧠][🛣] More elegant way to tracking than passing `name`
-     * TODO: [🧠][main] !!! 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
-     */
-
     /**
      * @@@
      *
@@ -2088,29 +2183,7 @@
      * TODO: [🍙] Make some standard order of json properties
      */
 
-    /**
-     * @@@
-     *
-     * @public exported from `@promptbook/utils`
-     */
-    function deepClone(objectValue) {
-        return JSON.parse(JSON.stringify(objectValue));
-        /*
-        TODO: [🧠] Is there a better implementation?
-        > const propertyNames = Object.getOwnPropertyNames(objectValue);
-        > for (const propertyName of propertyNames) {
-        >     const value = (objectValue as really_any)[propertyName];
-        >     if (value && typeof value === 'object') {
-        >         deepClone(value);
-        >     }
-        > }
-        > return Object.assign({}, objectValue);
-        */
-    }
-    /**
-     * TODO: [🧠] Is there a way how to meaningfully test this utility
-     */
-
+    // <- TODO: !!!!!!! Auto convert to type `import { ... } from 'type-fest';`
     /**
      * Tests if the value is [🚉] serializable as JSON
      *
@@ -2132,7 +2205,7 @@
      */
     function isSerializableAsJson(value) {
         try {
-            checkSerializableAsJson('', value);
+            checkSerializableAsJson({ value: value });
             return true;
         }
         catch (error) {
@@ -2554,6 +2627,7 @@
     exports.deepClone = deepClone;
     exports.deserializeError = deserializeError;
     exports.difference = difference;
+    exports.exportJson = exportJson;
     exports.extractParameterNames = extractParameterNames;
     exports.extractVariablesFromScript = extractVariablesFromScript;
     exports.forEachAsync = forEachAsync;
@@ -2579,6 +2653,7 @@
     exports.normalizeTo_camelCase = normalizeTo_camelCase;
     exports.normalizeTo_snake_case = normalizeTo_snake_case;
     exports.normalizeWhitespaces = normalizeWhitespaces;
+    exports.orderJson = orderJson;
     exports.parseKeywords = parseKeywords;
     exports.parseKeywordsFromString = parseKeywordsFromString;
     exports.parseNumber = parseNumber;