@promptbook/javascript 0.92.0-13 → 0.92.0-14

package/esm/index.es.js

@@ -19,7 +19,7 @@ const BOOK_LANGUAGE_VERSION = '1.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.92.0-13';
+const PROMPTBOOK_ENGINE_VERSION = '0.92.0-14';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -90,6 +90,48 @@ Object.freeze({
  * TODO: [🧠][🧜‍♂️] Maybe join remoteServerUrl and path into single value
  */
 
+/**
+ * Orders JSON object by keys
+ *
+ * @returns The same type of object as the input re-ordered
+ * @public exported from `@promptbook/utils`
+ */
+function orderJson(options) {
+    const { value, order } = options;
+    const orderedValue = {
+        ...(order === undefined ? {} : Object.fromEntries(order.map((key) => [key, undefined]))),
+        ...value,
+    };
+    return orderedValue;
+}
+
+/**
+ * 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) {
+    if (Array.isArray(objectValue)) {
+        return Object.freeze(objectValue.map((item) => $deepFreeze(item)));
+    }
+    const propertyNames = Object.getOwnPropertyNames(objectValue);
+    for (const propertyName of propertyNames) {
+        const value = objectValue[propertyName];
+        if (value && typeof value === 'object') {
+            $deepFreeze(value);
+        }
+    }
+    Object.freeze(objectValue);
+    return objectValue;
+}
+/**
+ * TODO: [🧠] Is there a way how to meaningfully test this utility
+ */
+
 /**
  * Make error report URL for the given error
  *
@@ -159,66 +201,333 @@ class UnexpectedError extends Error {
 }
 
 /**
- * @@@
+ * This error type indicates that somewhere in the code non-Error object was thrown and it was wrapped into the `WrappedError`
  *
- * @param text @@@
- * @param _isFirstLetterCapital @@@
- * @returns @@@
- * @example 'helloWorld'
- * @example 'iLovePromptbook'
+ * @public exported from `@promptbook/core`
+ */
+class WrappedError extends Error {
+    constructor(whatWasThrown) {
+        const tag = `[🤮]`;
+        console.error(tag, whatWasThrown);
+        super(spaceTrim$1(`
+                Non-Error object was thrown
+
+                Note: Look for ${tag} in the console for more details
+                Please report issue on ${ADMIN_EMAIL}
+            `));
+        this.name = 'WrappedError';
+        Object.setPrototypeOf(this, WrappedError.prototype);
+    }
+}
+
+/**
+ * Helper used in catch blocks to assert that the error is an instance of `Error`
+ *
+ * @param whatWasThrown Any object that was thrown
+ * @returns Nothing if the error is an instance of `Error`
+ * @throws `WrappedError` or `UnexpectedError` if the error is not standard
+ *
+ * @private within the repository
+ */
+function assertsError(whatWasThrown) {
+    // Case 1: Handle error which was rethrown as `WrappedError`
+    if (whatWasThrown instanceof WrappedError) {
+        const wrappedError = whatWasThrown;
+        throw wrappedError;
+    }
+    // Case 2: Handle unexpected errors
+    if (whatWasThrown instanceof UnexpectedError) {
+        const unexpectedError = whatWasThrown;
+        throw unexpectedError;
+    }
+    // Case 3: Handle standard errors - keep them up to consumer
+    if (whatWasThrown instanceof Error) {
+        return;
+    }
+    // Case 4: Handle non-standard errors - wrap them into `WrappedError` and throw
+    throw new WrappedError(whatWasThrown);
+}
+
+/**
+ * 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 normalizeTo_camelCase(text, _isFirstLetterCapital = false) {
-    let charType;
-    let lastCharType = null;
-    let normalizedName = '';
-    for (const char of text) {
-        let normalizedChar;
-        if (/^[a-z]$/.test(char)) {
-            charType = 'LOWERCASE';
-            normalizedChar = char;
+function checkSerializableAsJson(options) {
+    const { value, name, message } = options;
+    if (value === undefined) {
+        throw new UnexpectedError(`${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(`${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 });
         }
-        else if (/^[A-Z]$/.test(char)) {
-            charType = 'UPPERCASE';
-            normalizedChar = char.toLowerCase();
+    }
+    else if (typeof value === 'object') {
+        if (value instanceof Date) {
+            throw new UnexpectedError(spaceTrim((block) => `
+                        \`${name}\` is Date
+
+                        Use \`string_date_iso8601\` instead
+
+                        Additional message for \`${name}\`:
+                        ${block(message || '(nothing)')}
+                    `));
         }
-        else if (/^[0-9]$/.test(char)) {
-            charType = 'NUMBER';
-            normalizedChar = char;
+        else if (value instanceof Map) {
+            throw new UnexpectedError(`${name} is Map`);
         }
-        else {
-            charType = 'OTHER';
-            normalizedChar = '';
+        else if (value instanceof Set) {
+            throw new UnexpectedError(`${name} is Set`);
         }
-        if (!lastCharType) {
-            if (_isFirstLetterCapital) {
-                normalizedChar = normalizedChar.toUpperCase(); //TODO: DRY
-            }
+        else if (value instanceof RegExp) {
+            throw new UnexpectedError(`${name} is RegExp`);
         }
-        else if (charType !== lastCharType &&
-            !(charType === 'LOWERCASE' && lastCharType === 'UPPERCASE') &&
-            !(lastCharType === 'NUMBER') &&
-            !(charType === 'NUMBER')) {
-            normalizedChar = normalizedChar.toUpperCase(); //TODO: [🌺] DRY
+        else if (value instanceof Error) {
+            throw new UnexpectedError(spaceTrim((block) => `
+                        \`${name}\` is unserialized Error
+
+                        Use function \`serializeError\`
+
+                        Additional message for \`${name}\`:
+                        ${block(message || '(nothing)')}
+
+                    `));
+        }
+        else {
+            for (const [subName, subValue] of Object.entries(value)) {
+                if (subValue === undefined) {
+                    // Note: undefined in object is serializable - it is just omited
+                    continue;
+                }
+                checkSerializableAsJson({ name: `${name}.${subName}`, value: subValue, message });
+            }
+            try {
+                JSON.stringify(value); // <- TODO: [0]
+            }
+            catch (error) {
+                assertsError(error);
+                throw new UnexpectedError(spaceTrim((block) => `
+                            \`${name}\` is not serializable
+
+                            ${block(error.stack || error.message)}
+
+                            Additional message for \`${name}\`:
+                            ${block(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`);
+                    }
+                    seen.add(value);
+                    if (Array.isArray(value)) {
+                        stack.push(...value.map((value) => ({ value })));
+                    } else {
+                        stack.push(...Object.values(value).map((value) => ({ value })));
+                    }
+                }
+            }
+            */
+            return;
         }
-        normalizedName += normalizedChar;
-        lastCharType = charType;
     }
-    return normalizedName;
+    else {
+        throw new UnexpectedError(spaceTrim((block) => `
+                    \`${name}\` is unknown type
+
+                    Additional message for \`${name}\`:
+                    ${block(message || '(nothing)')}
+                `));
+    }
 }
 /**
- * TODO: [🌺] Use some intermediate util splitWords
+ * 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
  */
 
 /**
- * Removes emojis from a string and fix whitespaces
+ * @@@
  *
- * @param text with emojis
- * @returns text without emojis
  * @public exported from `@promptbook/utils`
  */
-function removeEmojis(text) {
-    // Replace emojis (and also ZWJ sequence) with hyphens
+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) {
+    const { name, value, order, message } = options;
+    checkSerializableAsJson({ name, value, message });
+    const 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
+ */
+
+/**
+ * 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
+ */
+
+/**
+ * @@@
+ *
+ * @param text @@@
+ * @param _isFirstLetterCapital @@@
+ * @returns @@@
+ * @example 'helloWorld'
+ * @example 'iLovePromptbook'
+ * @public exported from `@promptbook/utils`
+ */
+function normalizeTo_camelCase(text, _isFirstLetterCapital = false) {
+    let charType;
+    let lastCharType = null;
+    let normalizedName = '';
+    for (const char of text) {
+        let normalizedChar;
+        if (/^[a-z]$/.test(char)) {
+            charType = 'LOWERCASE';
+            normalizedChar = char;
+        }
+        else if (/^[A-Z]$/.test(char)) {
+            charType = 'UPPERCASE';
+            normalizedChar = char.toLowerCase();
+        }
+        else if (/^[0-9]$/.test(char)) {
+            charType = 'NUMBER';
+            normalizedChar = char;
+        }
+        else {
+            charType = 'OTHER';
+            normalizedChar = '';
+        }
+        if (!lastCharType) {
+            if (_isFirstLetterCapital) {
+                normalizedChar = normalizedChar.toUpperCase(); //TODO: DRY
+            }
+        }
+        else if (charType !== lastCharType &&
+            !(charType === 'LOWERCASE' && lastCharType === 'UPPERCASE') &&
+            !(lastCharType === 'NUMBER') &&
+            !(charType === 'NUMBER')) {
+            normalizedChar = normalizedChar.toUpperCase(); //TODO: [🌺] DRY
+        }
+        normalizedName += normalizedChar;
+        lastCharType = charType;
+    }
+    return normalizedName;
+}
+/**
+ * TODO: [🌺] Use some intermediate util splitWords
+ */
+
+/**
+ * Removes emojis from a string and fix whitespaces
+ *
+ * @param text with emojis
+ * @returns text without emojis
+ * @public exported from `@promptbook/utils`
+ */
+function removeEmojis(text) {
+    // Replace emojis (and also ZWJ sequence) with hyphens
     text = text.replace(/(\p{Extended_Pictographic})\p{Modifier_Symbol}/gu, '$1');
     text = text.replace(/(\p{Extended_Pictographic})[\u{FE00}-\u{FE0F}]/gu, '$1');
     text = text.replace(/(\p{Extended_Pictographic})(\u{200D}\p{Extended_Pictographic})*/gu, '$1');
@@ -588,26 +897,6 @@ class PipelineExecutionError extends Error {
  * TODO: [🧠][🌂] Add id to all errors
  */
 
-/**
- * This error type indicates that somewhere in the code non-Error object was thrown and it was wrapped into the `WrappedError`
- *
- * @public exported from `@promptbook/core`
- */
-class WrappedError extends Error {
-    constructor(whatWasThrown) {
-        const tag = `[🤮]`;
-        console.error(tag, whatWasThrown);
-        super(spaceTrim$1(`
-                Non-Error object was thrown
-
-                Note: Look for ${tag} in the console for more details
-                Please report issue on ${ADMIN_EMAIL}
-            `));
-        this.name = 'WrappedError';
-        Object.setPrototypeOf(this, WrappedError.prototype);
-    }
-}
-
 /**
  * Index of all javascript errors
  *
@@ -635,295 +924,6 @@ class WrappedError extends Error {
  * Note: [💞] Ignore a discrepancy between file name and entity name
  */
 
-/**
- * Helper used in catch blocks to assert that the error is an instance of `Error`
- *
- * @param whatWasThrown Any object that was thrown
- * @returns Nothing if the error is an instance of `Error`
- * @throws `WrappedError` or `UnexpectedError` if the error is not standard
- *
- * @private within the repository
- */
-function assertsError(whatWasThrown) {
-    // Case 1: Handle error which was rethrown as `WrappedError`
-    if (whatWasThrown instanceof WrappedError) {
-        const wrappedError = whatWasThrown;
-        throw wrappedError;
-    }
-    // Case 2: Handle unexpected errors
-    if (whatWasThrown instanceof UnexpectedError) {
-        const unexpectedError = whatWasThrown;
-        throw unexpectedError;
-    }
-    // Case 3: Handle standard errors - keep them up to consumer
-    if (whatWasThrown instanceof Error) {
-        return;
-    }
-    // Case 4: Handle non-standard errors - wrap them into `WrappedError` and throw
-    throw new WrappedError(whatWasThrown);
-}
-
-/**
- * Orders JSON object by keys
- *
- * @returns The same type of object as the input re-ordered
- * @public exported from `@promptbook/utils`
- */
-function orderJson(options) {
-    const { value, order } = options;
-    const orderedValue = {
-        ...(order === undefined ? {} : Object.fromEntries(order.map((key) => [key, undefined]))),
-        ...value,
-    };
-    return orderedValue;
-}
-
-/**
- * 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) {
-    if (Array.isArray(objectValue)) {
-        return Object.freeze(objectValue.map((item) => $deepFreeze(item)));
-    }
-    const propertyNames = Object.getOwnPropertyNames(objectValue);
-    for (const propertyName of propertyNames) {
-        const value = objectValue[propertyName];
-        if (value && typeof value === 'object') {
-            $deepFreeze(value);
-        }
-    }
-    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) {
-    const { value, name, message } = options;
-    if (value === undefined) {
-        throw new UnexpectedError(`${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(`${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 });
-        }
-    }
-    else if (typeof value === 'object') {
-        if (value instanceof Date) {
-            throw new UnexpectedError(spaceTrim((block) => `
-                        \`${name}\` is Date
-
-                        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((block) => `
-                        \`${name}\` is unserialized Error
-
-                        Use function \`serializeError\`
-
-                        Additional message for \`${name}\`:
-                        ${block(message || '(nothing)')}
-
-                    `));
-        }
-        else {
-            for (const [subName, subValue] of Object.entries(value)) {
-                if (subValue === undefined) {
-                    // Note: undefined in object is serializable - it is just omited
-                    continue;
-                }
-                checkSerializableAsJson({ name: `${name}.${subName}`, value: subValue, message });
-            }
-            try {
-                JSON.stringify(value); // <- TODO: [0]
-            }
-            catch (error) {
-                assertsError(error);
-                throw new UnexpectedError(spaceTrim((block) => `
-                            \`${name}\` is not serializable
-
-                            ${block(error.stack || error.message)}
-
-                            Additional message for \`${name}\`:
-                            ${block(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`);
-                    }
-                    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((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
- */
-
-/**
- * @@@
- *
- * @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) {
-    const { name, value, order, message } = options;
-    checkSerializableAsJson({ name, value, message });
-    const 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
- */
-
-/**
- * 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
- */
-
 /**
  * Format either small or big number
  *