@promptbook/utils 0.66.0 → 0.67.0-1

package/umd/index.umd.js

@@ -12,7 +12,7 @@
     /**
      * The version of the Promptbook library
      */
-    var PROMPTBOOK_VERSION = '0.66.0-9';
+    var PROMPTBOOK_VERSION = '0.67.0-0';
     // TODO: !!!! List here all the versions and annotate + put into script
 
     /*! *****************************************************************************
@@ -704,7 +704,7 @@
                     var undefinedName = error.message.split(' ')[0];
                     /*
                     Note: Parsing the error
-                          [ReferenceError: thing is not defined]
+                          [PipelineUrlError: thing is not defined]
                     */
                     if (!undefinedName) {
                         throw error;
@@ -722,7 +722,7 @@
             if (!(error instanceof Error)) {
                 throw error;
             }
-            throw new ParsingError(spaceTrim.spaceTrim(function (block) { return "\n                    Can not extract variables from the script\n\n                    ".concat(block(error.name), ": ").concat(block(error.message), "\n                "); }));
+            throw new ParsingError(spaceTrim.spaceTrim(function (block) { return "\n                    Can not extract variables from the script\n\n                    ".concat(block(error.toString()), "}\n                "); }));
         }
         return variables;
     }
@@ -864,6 +864,167 @@
         return renamedPipeline;
     }
 
+    /**
+     * This error indicates that the pipeline collection cannot be propperly loaded
+     *
+     * @public exported from `@promptbook/core`
+     */
+    var CollectionError = /** @class */ (function (_super) {
+        __extends(CollectionError, _super);
+        function CollectionError(message) {
+            var _this = _super.call(this, message) || this;
+            _this.name = 'CollectionError';
+            Object.setPrototypeOf(_this, CollectionError.prototype);
+            return _this;
+        }
+        return CollectionError;
+    }(Error));
+
+    /**
+     * This error type indicates that you try to use a feature that is not available in the current environment
+     *
+     * @public exported from `@promptbook/core`
+     */
+    var EnvironmentMismatchError = /** @class */ (function (_super) {
+        __extends(EnvironmentMismatchError, _super);
+        function EnvironmentMismatchError(message) {
+            var _this = _super.call(this, message) || this;
+            _this.name = 'EnvironmentMismatchError';
+            Object.setPrototypeOf(_this, EnvironmentMismatchError.prototype);
+            return _this;
+        }
+        return EnvironmentMismatchError;
+    }(Error));
+
+    /**
+     * This error type indicates that some limit was reached
+     *
+     * @public exported from `@promptbook/core`
+     */
+    var LimitReachedError = /** @class */ (function (_super) {
+        __extends(LimitReachedError, _super);
+        function LimitReachedError(message) {
+            var _this = _super.call(this, message) || this;
+            _this.name = 'LimitReachedError';
+            Object.setPrototypeOf(_this, LimitReachedError.prototype);
+            return _this;
+        }
+        return LimitReachedError;
+    }(Error));
+
+    /**
+     * This error indicates that promptbook not found in the collection
+     *
+     * @public exported from `@promptbook/core`
+     */
+    var NotFoundError = /** @class */ (function (_super) {
+        __extends(NotFoundError, _super);
+        function NotFoundError(message) {
+            var _this = _super.call(this, message) || this;
+            _this.name = 'NotFoundError';
+            Object.setPrototypeOf(_this, NotFoundError.prototype);
+            return _this;
+        }
+        return NotFoundError;
+    }(Error));
+
+    /**
+     * This error type indicates that some part of the code is not implemented yet
+     *
+     * @public exported from `@promptbook/core`
+     */
+    var NotYetImplementedError = /** @class */ (function (_super) {
+        __extends(NotYetImplementedError, _super);
+        function NotYetImplementedError(message) {
+            var _this = _super.call(this, spaceTrim.spaceTrim(function (block) { return "\n                    ".concat(block(message), "\n\n                    Note: This feature is not implemented yet but it will be soon.\n\n                    If you want speed up the implementation or just read more, look here:\n                    https://github.com/webgptorg/promptbook\n\n                    Or contact us on me@pavolhejny.com\n\n                "); })) || this;
+            _this.name = 'NotYetImplementedError';
+            Object.setPrototypeOf(_this, NotYetImplementedError.prototype);
+            return _this;
+        }
+        return NotYetImplementedError;
+    }(Error));
+
+    /**
+     * This error indicates errors during the execution of the pipeline
+     *
+     * @public exported from `@promptbook/core`
+     */
+    var PipelineExecutionError = /** @class */ (function (_super) {
+        __extends(PipelineExecutionError, _super);
+        function PipelineExecutionError(message) {
+            var _this = _super.call(this, message) || this;
+            _this.name = 'PipelineExecutionError';
+            Object.setPrototypeOf(_this, PipelineExecutionError.prototype);
+            return _this;
+        }
+        return PipelineExecutionError;
+    }(Error));
+
+    /**
+     * This error indicates errors in referencing promptbooks between each other
+     *
+     * @public exported from `@promptbook/core`
+     */
+    var PipelineUrlError = /** @class */ (function (_super) {
+        __extends(PipelineUrlError, _super);
+        function PipelineUrlError(message) {
+            var _this = _super.call(this, message) || this;
+            _this.name = 'PipelineUrlError';
+            Object.setPrototypeOf(_this, PipelineUrlError.prototype);
+            return _this;
+        }
+        return PipelineUrlError;
+    }(Error));
+
+    /**
+     * Index of all custom errors
+     *
+     * @public exported from `@promptbook/core`
+     */
+    var ERRORS = {
+        CollectionError: CollectionError,
+        EnvironmentMismatchError: EnvironmentMismatchError,
+        LimitReachedError: LimitReachedError,
+        NotFoundError: NotFoundError,
+        NotYetImplementedError: NotYetImplementedError,
+        ParsingError: ParsingError,
+        PipelineExecutionError: PipelineExecutionError,
+        PipelineLogicError: PipelineLogicError,
+        PipelineUrlError: PipelineUrlError,
+        UnexpectedError: UnexpectedError,
+        // TODO: [🪑]> VersionMismatchError,
+    };
+
+    /**
+     * Deserializes the error object
+     *
+     * @public exported from `@promptbook/utils`
+     */
+    function deserializeError(error) {
+        if (error.name === 'Error') {
+            return new Error(error.message);
+        }
+        var CustomError = ERRORS[error.name];
+        return new CustomError(error.message);
+    }
+
+    /**
+     * Serializes an error into a [🚉] JSON-serializable object
+     *
+     * @public exported from `@promptbook/utils`
+     */
+    function serializeError(error) {
+        var name = error.name, message = error.message, stack = error.stack;
+        if (!__spreadArray(['Error'], __read(Object.keys(ERRORS)), false).includes(name)) {
+            throw new UnexpectedError(spaceTrim__default["default"](function (block) { return "\n          \n                    Cannot serialize error with name \"".concat(name, "\"\n\n                    ").concat(block(stack || message), "\n                \n                "); }));
+        }
+        return {
+            name: name,
+            message: message,
+            stack: stack,
+        };
+    }
+
     /**
      * Async version of Array.forEach
      *
@@ -1101,106 +1262,6 @@
         return new Date().toISOString();
     }
 
-    /**
-     * @@@
-     *
-     * Note: It is usefull @@@
-     *
-     * @param pipeline
-     * @public exported from `@promptbook/utils`
-     */
-    function clonePipeline(pipeline) {
-        // Note: Not using spread operator (...) because @@@
-        var pipelineUrl = pipeline.pipelineUrl, sourceFile = pipeline.sourceFile, title = pipeline.title, promptbookVersion = pipeline.promptbookVersion, description = pipeline.description, parameters = pipeline.parameters, promptTemplates = pipeline.promptTemplates, knowledgeSources = pipeline.knowledgeSources, knowledgePieces = pipeline.knowledgePieces, personas = pipeline.personas, preparations = pipeline.preparations;
-        return {
-            pipelineUrl: pipelineUrl,
-            sourceFile: sourceFile,
-            title: title,
-            promptbookVersion: promptbookVersion,
-            description: description,
-            parameters: parameters,
-            promptTemplates: promptTemplates,
-            knowledgeSources: knowledgeSources,
-            knowledgePieces: knowledgePieces,
-            personas: personas,
-            preparations: preparations,
-        };
-    }
-    /**
-     * TODO: [🍙] Make some standart 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
-     */
-
-    /**
-     * @@@
-     *
-     * 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;
-        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
-     */
-
-    /**
-     * @@@
-     *
-     * Note: `$` is used to indicate that this function is not a pure function - it access global scope
-     *
-     * @public exported from `@promptbook/utils`
-     */
-    function $getGlobalScope() {
-        return Function('return this')();
-    }
-    /***
-     * TODO: !!!!! Make private and promptbook registry from this
-     */
-
     /**
      * Detects if the code is running in a browser environment in main thread (Not in a web worker)
      *
@@ -1664,6 +1725,183 @@
         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;
+        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: [🧠] !!! 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
+     */
+
+    /**
+     * @@@
+     * @@@
+     *
+     * Note: This function mutates the object and returns the original (but mutated-deep-freezed) object
+     *
+     * @param name - Name of the object for debugging purposes
+     * @param objectValue - Object to be deeply frozen
+     * @returns The same object as the input, but deeply frozen
+     * @private this is in comparison to `deepFreeze` a more specific utility and maybe not very good practice to use without specific reason and considerations
+     */
+    function $asDeeplyFrozenSerializableJson(name, objectValue) {
+        checkSerializableAsJson(name, objectValue);
+        return $deepFreeze(objectValue);
+    }
+    /**
+     * TODO: [🧠][🛣] More elegant way to tracking than passing `name`
+     * TODO: [🧠] Is there a way how to meaningfully test this utility
+     */
+
     // <- TODO: [🧠] Better system for generator warnings - not always "code" and "by `@promptbook/cli`"
     /**
      * The maximum number of iterations for a loops
@@ -1682,7 +1920,7 @@
      *
      * @public exported from `@promptbook/core`
      */
-    $deepFreeze([
+    $asDeeplyFrozenSerializableJson('RESERVED_PARAMETER_NAMES', [
         'content',
         'context',
         'knowledge',
@@ -1708,38 +1946,6 @@
      * TODO: [🧠][🧜‍♂️] Maybe join remoteUrl and path into single value
      */
 
-    /**
-     * This error type indicates that some limit was reached
-     *
-     * @public exported from `@promptbook/core`
-     */
-    var LimitReachedError = /** @class */ (function (_super) {
-        __extends(LimitReachedError, _super);
-        function LimitReachedError(message) {
-            var _this = _super.call(this, message) || this;
-            _this.name = 'LimitReachedError';
-            Object.setPrototypeOf(_this, LimitReachedError.prototype);
-            return _this;
-        }
-        return LimitReachedError;
-    }(Error));
-
-    /**
-     * This error indicates errors during the execution of the pipeline
-     *
-     * @public exported from `@promptbook/core`
-     */
-    var PipelineExecutionError = /** @class */ (function (_super) {
-        __extends(PipelineExecutionError, _super);
-        function PipelineExecutionError(message) {
-            var _this = _super.call(this, message) || this;
-            _this.name = 'PipelineExecutionError';
-            Object.setPrototypeOf(_this, PipelineExecutionError.prototype);
-            return _this;
-        }
-        return PipelineExecutionError;
-    }(Error));
-
     /**
      * Replaces parameters in template with values from parameters object
      *
@@ -1819,6 +2025,91 @@
         return replacedTemplate;
     }
 
+    /**
+     * @@@
+     *
+     * Note: It is usefull @@@
+     *
+     * @param pipeline
+     * @public exported from `@promptbook/utils`
+     */
+    function clonePipeline(pipeline) {
+        // Note: Not using spread operator (...) because @@@
+        var pipelineUrl = pipeline.pipelineUrl, sourceFile = pipeline.sourceFile, title = pipeline.title, promptbookVersion = pipeline.promptbookVersion, description = pipeline.description, parameters = pipeline.parameters, promptTemplates = pipeline.promptTemplates, knowledgeSources = pipeline.knowledgeSources, knowledgePieces = pipeline.knowledgePieces, personas = pipeline.personas, preparations = pipeline.preparations;
+        return {
+            pipelineUrl: pipelineUrl,
+            sourceFile: sourceFile,
+            title: title,
+            promptbookVersion: promptbookVersion,
+            description: description,
+            parameters: parameters,
+            promptTemplates: promptTemplates,
+            knowledgeSources: knowledgeSources,
+            knowledgePieces: knowledgePieces,
+            personas: personas,
+            preparations: preparations,
+        };
+    }
+    /**
+     * TODO: [🍙] Make some standart 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
+     */
+
+    /**
+     * Tests if the value is [🚉] serializable as JSON
+     *
+     * - 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...
+     *
+     *
+     * @public exported from `@promptbook/utils`
+     */
+    function isSerializableAsJson(value) {
+        try {
+            checkSerializableAsJson('', value);
+            return true;
+        }
+        catch (error) {
+            return false;
+        }
+    }
+    /**
+     * TODO: [🧠] !!! In-memory cache of same values to prevent multiple checks
+     * TODO: [🧠][💺] Can be done this on type-level?
+     */
+
     /**
      * Create difference set of two sets.
      *
@@ -2260,7 +2551,6 @@
 
     exports.$currentDate = $currentDate;
     exports.$deepFreeze = $deepFreeze;
-    exports.$getGlobalScope = $getGlobalScope;
     exports.$isRunningInBrowser = $isRunningInBrowser;
     exports.$isRunningInNode = $isRunningInNode;
     exports.$isRunningInWebWorker = $isRunningInWebWorker;
@@ -2269,6 +2559,7 @@
     exports.DIACRITIC_VARIANTS_LETTERS = DIACRITIC_VARIANTS_LETTERS;
     exports.PROMPTBOOK_VERSION = PROMPTBOOK_VERSION;
     exports.capitalize = capitalize;
+    exports.checkSerializableAsJson = checkSerializableAsJson;
     exports.clonePipeline = clonePipeline;
     exports.countCharacters = countCharacters;
     exports.countLines = countLines;
@@ -2278,6 +2569,7 @@
     exports.countWords = countWords;
     exports.decapitalize = decapitalize;
     exports.deepClone = deepClone;
+    exports.deserializeError = deserializeError;
     exports.difference = difference;
     exports.extractBlock = extractBlock;
     exports.extractParameterNames = extractParameterNames;
@@ -2286,6 +2578,7 @@
     exports.forEachAsync = forEachAsync;
     exports.intersection = intersection;
     exports.isHostnameOnPrivateNetwork = isHostnameOnPrivateNetwork;
+    exports.isSerializableAsJson = isSerializableAsJson;
     exports.isUrlOnPrivateNetwork = isUrlOnPrivateNetwork;
     exports.isValidEmail = isValidEmail;
     exports.isValidFilePath = isValidFilePath;
@@ -2315,6 +2608,7 @@
     exports.renderPromptbookMermaid = renderPromptbookMermaid;
     exports.replaceParameters = replaceParameters;
     exports.searchKeywords = searchKeywords;
+    exports.serializeError = serializeError;
     exports.splitIntoSentences = splitIntoSentences;
     exports.titleToName = titleToName;
     exports.trimCodeBlock = trimCodeBlock;