@promptbook/javascript 0.88.0-1

package/esm/typings/src/utils/normalization/titleToName.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @@@
+ *
+ * @param value @@@
+ * @returns @@@
+ * @example @@@
+ * @public exported from `@promptbook/utils`
+ */
+export declare function titleToName(value: string): string;

package/esm/typings/src/utils/normalization/titleToName.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/typings/src/utils/organization/$sideEffect.d.ts

@@ -0,0 +1,9 @@
+import type { really_any } from './really_any';
+/**
+ * Just says that the variable is not used directlys but should be kept because the existence of the variable is important
+ *
+ * @param value any values
+ * @returns void
+ * @private within the repository
+ */
+export declare function $sideEffect(...sideEffectSubjects: ReadonlyArray<really_any>): void;

package/esm/typings/src/utils/organization/TODO_USE.d.ts

@@ -0,0 +1,12 @@
+import type { really_any } from './really_any';
+/**
+ * Just marks a place of place where should be something implemented
+ * No side effects.
+ *
+ * Note: It can be usefull suppressing eslint errors of unused variables
+ *
+ * @param value any values
+ * @returns void
+ * @private within the repository
+ */
+export declare function TODO_USE(...value: ReadonlyArray<really_any>): void;

package/esm/typings/src/utils/organization/TODO_any.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Organizational helper to better mark the place where the type is missing
+ *
+ * @private within the repository
+ */
+export type TODO_any = any;

package/esm/typings/src/utils/organization/TODO_object.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Organizational helper to better mark the place where the type is missing
+ *
+ * @private within the repository
+ */
+export type TODO_object = object;

package/esm/typings/src/utils/organization/TODO_remove_as.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Organizational helper to better mark the place is used as but should not be
+ *
+ * @private within the repository
+ */
+export type TODO_remove_as<T> = T;

package/esm/typings/src/utils/organization/TODO_string.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Organizational helper to better mark the place where the more specific string type is missing
+ *
+ * @private within the repository
+ */
+export type TODO_string = string;

package/esm/typings/src/utils/organization/TODO_unknown.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Organizational helper to better mark the place where the type is missing
+ *
+ * @private within the repository
+ */
+export type TODO_unknown = unknown;

package/esm/typings/src/utils/organization/___and___.d.ts

@@ -0,0 +1,7 @@
+import type { really_unknown } from './really_unknown';
+/**
+ * Formatting helper to put void to keep longer version of prettier
+ *
+ * @private within the repository
+ */
+export type ___and___ = really_unknown;

package/esm/typings/src/utils/organization/___or___.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Formatting helper to put void to keep longer version of prettier
+ *
+ * @private within the repository
+ */
+export type ___or___ = never;

package/esm/typings/src/utils/organization/empty_object.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Organizational helper to better mark the place where to really use empty object `{}`
+ *
+ * Note: There are 2 similar types>
+ * - `empty_object` @@@
+ * - `just_empty_object` @@@
+ *
+ * @private within the repository
+ */
+export type empty_object = {};

package/esm/typings/src/utils/organization/just.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Returns the same value that is passed as argument.
+ * No side effects.
+ *
+ * Note: It can be usefull for:
+ *
+ * 1) Leveling indentation
+ * 2) Putting always-true or always-false conditions without getting eslint errors
+ *
+ * @param value any values
+ * @returns the same values
+ * @private within the repository
+ */
+export declare function just<T>(value?: T): T;

package/esm/typings/src/utils/organization/just_empty_object.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Organizational helper to better @@@@
+ *
+ * Note: There are 2 similar types>
+ * - `empty_object` @@@
+ * - `just_empty_object` @@@
+ *
+ * Note: In most cases, you should use `empty_object`
+ *
+ * @private within the repository
+ */
+export type just_empty_object = Record<string, never>;

package/esm/typings/src/utils/organization/keepTypeImported.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Just says that the type is used but `organize-imports-cli` does not recognize it.
+ * [🤛] This is a workaround for the issue.
+ *
+ * @param value any values
+ * @returns void
+ * @private within the repository
+ */
+export declare function keepTypeImported<TTypeToKeep>(): void;

package/esm/typings/src/utils/organization/keepUnused.d.ts

@@ -0,0 +1,16 @@
+import type { really_any } from './really_any';
+/**
+ * Just says that the variable is not used but should be kept
+ * No side effects.
+ *
+ * Note: It can be usefull for:
+ *
+ * 1) Suppressing eager optimization of unused imports
+ * 2) Suppressing eslint errors of unused variables in the tests
+ * 3) Keeping the type of the variable for type testing
+ *
+ * @param value any values
+ * @returns void
+ * @private within the repository
+ */
+export declare function keepUnused<TTypeToKeep1 = really_any, TTypeToKeep2 = really_any, TTypeToKeep3 = really_any>(...valuesToKeep: ReadonlyArray<really_any>): void;

package/esm/typings/src/utils/organization/really_any.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Organizational helper to mark a place where to really use `any`
+ *
+ * @private within the repository
+ */
+export type really_any = any;

package/esm/typings/src/utils/organization/really_unknown.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Organizational helper to mark a place where to really use `unknown`
+ *
+ * @private within the repository
+ */
+export type really_unknown = unknown;

package/esm/typings/src/utils/organization/spaceTrim.d.ts

@@ -0,0 +1,11 @@
+import { spaceTrim as spaceTrimReexported } from 'spacetrim';
+/**
+ * Trims string from all 4 sides
+ *
+ * Note: This is a re-exported function from the `spacetrim` package which is
+ *       Developed by same author @hejny as this package
+ *
+ * @public exported from `@promptbook/utils`
+ * @see https://github.com/hejny/spacetrim#usage
+ */
+export declare const spaceTrim: typeof spaceTrimReexported;

package/esm/typings/src/utils/parameters/extractParameterNames.d.ts

@@ -0,0 +1,10 @@
+import type { string_parameter_name } from '../../types/typeAliases';
+import type { string_template } from '../../types/typeAliases';
+/**
+ * Parses the task and returns the list of all parameter names
+ *
+ * @param template the string template with parameters in {curly} braces
+ * @returns the list of parameter names
+ * @public exported from `@promptbook/utils`
+ */
+export declare function extractParameterNames(template: string_template): Set<string_parameter_name>;

package/esm/typings/src/utils/parameters/extractParameterNames.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/typings/src/utils/parameters/mapAvailableToExpectedParameters.d.ts

@@ -0,0 +1,27 @@
+import type { string_parameter_name } from '../../types/typeAliases';
+import type { string_parameter_value } from '../../types/typeAliases';
+/**
+ * @@@
+ */
+type MakeapAvailableToExpectedParametersOptions = {
+    /**
+     * @@@
+     */
+    readonly expectedParameters: Readonly<Record<string_parameter_name, null>>;
+    /**
+     * @@@
+     */
+    readonly availableParameters: Readonly<Record<string_parameter_name, string_parameter_value>>;
+};
+/**
+ * Maps available parameters to expected parameters
+ *
+ * The strategy is:
+ * 1) @@@
+ * 2) @@@
+ *
+ * @throws {PipelineExecutionError} @@@
+ * @private within the repository used in `createPipelineExecutor`
+ */
+export declare function mapAvailableToExpectedParameters(options: MakeapAvailableToExpectedParametersOptions): Readonly<Record<string_parameter_name, string_parameter_value>>;
+export {};

package/esm/typings/src/utils/parameters/mapAvailableToExpectedParameters.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/typings/src/utils/parameters/numberToString.d.ts

@@ -0,0 +1,7 @@
+import type { string_parameter_value } from '../../types/typeAliases';
+/**
+ * Format either small or big number
+ *
+ * @public exported from `@promptbook/utils`
+ */
+export declare function numberToString(value: number): string_parameter_value;

package/esm/typings/src/utils/parameters/numberToString.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/typings/src/utils/parameters/templateParameters.d.ts

@@ -0,0 +1,16 @@
+import type { string_parameter_name } from '../../types/typeAliases';
+import type { string_template } from '../../types/typeAliases';
+import type { really_unknown } from '../organization/really_unknown';
+/**
+ * Replaces parameters in template with values from parameters object
+ *
+ * Note: This function is not places strings into string,
+ *       It's more complex and can handle this operation specifically for LLM models
+ *
+ * @param template the template with parameters in {curly} braces
+ * @param parameters the object with parameters
+ * @returns the template with replaced parameters
+ * @throws {PipelineExecutionError} if parameter is not defined, not closed, or not opened
+ * @public exported from `@promptbook/utils`
+ */
+export declare function templateParameters(template: string_template, parameters: Record<string_parameter_name, really_unknown>): string;

package/esm/typings/src/utils/parameters/templateParameters.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/typings/src/utils/parameters/valueToString.d.ts

@@ -0,0 +1,17 @@
+import type { string_parameter_value } from '../../types/typeAliases';
+import type { really_unknown } from '../organization/really_unknown';
+/**
+ * Function `valueToString` will convert the given value to string
+ * This is useful and used in the `templateParameters` function
+ *
+ * Note: This function is not just calling `toString` method
+ *       It's more complex and can handle this conversion specifically for LLM models
+ *       See `VALUE_STRINGS`
+ *
+ * Note: There are 2 similar functions
+ * - `valueToString` converts value to string for LLM models as human-readable string
+ * - `asSerializable` converts value to string to preserve full information to be able to convert it back
+ *
+ * @public exported from `@promptbook/utils`
+ */
+export declare function valueToString(value: really_unknown): string_parameter_value;

package/esm/typings/src/utils/parameters/valueToString.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/typings/src/utils/parseNumber.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Function parseNumber will parse number from string
+ *
+ * Unlike Number.parseInt, Number.parseFloat it will never ever result in NaN
+ * Note: it also works only with decimal numbers
+ *
+ * @returns parsed number
+ * @throws {ParseError} if the value is not a number
+ *
+ * @public exported from `@promptbook/utils`
+ */
+export declare function parseNumber(value: string | number): number;
+/**
+ * TODO: Maybe use sth. like safe-eval in fraction/calculation case @see https://www.npmjs.com/package/safe-eval
+ * TODO: [🧠][🌻] Maybe export through `@promptbook/markdown-utils` not `@promptbook/utils`
+ */

package/esm/typings/src/utils/parseNumber.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/typings/src/utils/random/$randomSeed.d.ts

@@ -0,0 +1,10 @@
+import type { number_seed } from '../../types/typeAliases';
+/**
+ * Generates random seed
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it is not deterministic
+ * Warning: This function is NOT cryptographically secure (it uses Math.random internally)
+ *
+ * @private internal helper function
+ */
+export declare function $randomSeed(): number_seed;

package/esm/typings/src/utils/random/$randomToken.d.ts

@@ -0,0 +1,13 @@
+import type { string_token } from '../../types/typeAliases';
+/**
+ * Generates random token
+ *
+ * Note: This function is cryptographically secure (it uses crypto.randomBytes internally)
+ *
+ * @private internal helper function
+ * @returns secure random token
+ */
+export declare function $randomToken(randomness: number): string_token;
+/**
+ * TODO: Maybe use nanoid instead https://github.com/ai/nanoid
+ */

package/esm/typings/src/utils/removeEmojis.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Removes emojis from a string and fix whitespaces
+ *
+ * @param text with emojis
+ * @returns text without emojis
+ * @public exported from `@promptbook/utils`
+ */
+export declare function removeEmojis(text: string): string;

package/esm/typings/src/utils/removeEmojis.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/typings/src/utils/removeQuotes.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Removes quotes from a string
+ *
+ * Tip: This is very usefull for post-processing of the result of the LLM model
+ * Note: This function removes only the same quotes from the beginning and the end of the string
+ * Note: There are two simmilar functions:
+ * - `removeQuotes` which removes only bounding quotes
+ * - `unwrapResult` which removes whole introduce sentence
+ *
+ * @param text optionally quoted text
+ * @returns text without quotes
+ * @public exported from `@promptbook/utils`
+ */
+export declare function removeQuotes(text: string): string;

package/esm/typings/src/utils/removeQuotes.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/typings/src/utils/serialization/$deepFreeze.d.ts

@@ -0,0 +1,14 @@
+import type { ReadonlyDeep } from 'type-fest';
+/**
+ * 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`
+ */
+export declare function $deepFreeze<TObject>(objectValue: TObject): ReadonlyDeep<TObject>;
+/**
+ * TODO: [🧠] Is there a way how to meaningfully test this utility
+ */

package/esm/typings/src/utils/serialization/asSerializable.d.ts

@@ -0,0 +1,15 @@
+import type { really_any } from '../organization/really_any';
+/**
+ * Function `asSerializable` will convert values which are not serializable to serializable values
+ * It walks deeply through the object and converts all values
+ *
+ * For example:
+ * - `Date` objects will be converted to string
+ *
+ * Note: There are 2 similar functions
+ * - `valueToString` converts value to string for LLM models as human-readable string
+ * - `asSerializable` converts value to string to preserve full information to be able to convert it back
+ *
+ * @private Internal helper function
+ */
+export declare function asSerializable(value: really_any): really_any;

package/esm/typings/src/utils/serialization/asSerializable.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/typings/src/utils/serialization/checkSerializableAsJson.d.ts

@@ -0,0 +1,45 @@
+import type { string_name } from '../../types/typeAliases';
+import type { really_unknown } from '../organization/really_unknown';
+/**
+ * Options for the `checkSerializableAsJson` function
+ */
+export type CheckSerializableAsJsonOptions = {
+    /**
+     * Value to be checked
+     */
+    value: really_unknown;
+    /**
+     * Semantic name of the value for debugging purposes
+     */
+    name?: string_name;
+    /**
+     * Message alongside the value for debugging purposes
+     */
+    message?: string;
+};
+/**
+ * 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`
+ */
+export declare function checkSerializableAsJson(options: CheckSerializableAsJsonOptions): void;
+/**
+ * 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
+ */

package/esm/typings/src/utils/serialization/clonePipeline.d.ts

@@ -0,0 +1,13 @@
+import type { PipelineJson } from '../../pipeline/PipelineJson/PipelineJson';
+/**
+ * @@@
+ *
+ * Note: It is usefull @@@
+ *
+ * @param pipeline
+ * @public exported from `@promptbook/utils`
+ */
+export declare function clonePipeline(pipeline: PipelineJson): PipelineJson;
+/**
+ * TODO: [🍙] Make some standard order of json properties
+ */

package/esm/typings/src/utils/serialization/deepClone.d.ts

@@ -0,0 +1,10 @@
+import type { WritableDeep } from 'type-fest';
+/**
+ * @@@
+ *
+ * @public exported from `@promptbook/utils`
+ */
+export declare function deepClone<TObject>(objectValue: TObject): WritableDeep<TObject>;
+/**
+ * TODO: [🧠] Is there a way how to meaningfully test this utility
+ */

package/esm/typings/src/utils/serialization/deepClone.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/typings/src/utils/serialization/exportJson.d.ts

@@ -0,0 +1,29 @@
+import type { JsonArray, JsonObject } from 'type-fest';
+import type { OrderJsonOptions } from '../normalization/orderJson';
+import type { CheckSerializableAsJsonOptions } from './checkSerializableAsJson';
+/**
+ * Options for the `$exportJson` function
+ */
+export type ExportJsonOptions<TObject> = CheckSerializableAsJsonOptions & Partial<Pick<OrderJsonOptions<TObject & (JsonObject | JsonArray)>, 'order'>> & {
+    /**
+     * Value to be checked, ordered and deeply frozen
+     */
+    value: TObject;
+};
+/**
+ * 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`
+ */
+export declare function exportJson<TObject>(options: ExportJsonOptions<TObject>): TObject;
+/**
+ * TODO: [🧠] Is there a way how to meaningfully test this utility
+ */

package/esm/typings/src/utils/serialization/isSerializableAsJson.d.ts

@@ -0,0 +1,25 @@
+import type { JsonValue } from 'type-fest';
+/**
+ * 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`
+ */
+export declare function isSerializableAsJson(value: unknown): value is JsonValue;
+/**
+ * TODO: [🧠][main] !!3 In-memory cache of same values to prevent multiple checks
+ * TODO: [🧠][💺] Can be done this on type-level?
+ */

package/esm/typings/src/utils/serialization/isSerializableAsJson.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/typings/src/utils/sets/difference.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Create difference set of two sets.
+ *
+ * @deprecated use new javascript set methods instead @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set
+ * @public exported from `@promptbook/utils`
+ */
+export declare function difference<TItem>(a: Set<TItem>, b: Set<TItem>, isEqual?: (a: TItem, b: TItem) => boolean): Set<TItem>;
+/**
+ * TODO: [🧠][💯] Maybe also implement symmetricDifference
+ */

package/esm/typings/src/utils/sets/difference.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/typings/src/utils/sets/intersection.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Creates a new set with all elements that are present in all sets
+ *
+ * @deprecated use new javascript set methods instead @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set
+ * @public exported from `@promptbook/utils`
+ */
+export declare function intersection<TItem>(...sets: ReadonlyArray<Set<TItem>>): Set<TItem>;

package/esm/typings/src/utils/sets/intersection.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/typings/src/utils/sets/union.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Creates a new set with all elements that are present in either set
+ *
+ * @deprecated use new javascript set methods instead @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set
+ * @public exported from `@promptbook/utils`
+ */
+export declare function union<TItem>(...sets: ReadonlyArray<Set<TItem>>): Set<TItem>;

package/esm/typings/src/utils/sets/union.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/typings/src/utils/trimCodeBlock.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Function trimCodeBlock will trim starting and ending code block from the string if it is present.
+ *
+ * Note: This is usefull for post-processing of the result of the chat LLM model
+ *       when the model wraps the result in the (markdown) code block.
+ *
+ * @public exported from `@promptbook/utils`
+ */
+export declare function trimCodeBlock(value: string): string;

package/esm/typings/src/utils/trimCodeBlock.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/typings/src/utils/trimEndOfCodeBlock.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Function trimEndOfCodeBlock will remove ending code block from the string if it is present.
+ *
+ * Note: This is usefull for post-processing of the result of the completion LLM model
+ *       if you want to start code block in the prompt but you don't want to end it in the result.
+ *
+ * @public exported from `@promptbook/utils`
+ */
+export declare function trimEndOfCodeBlock(value: string): string;

package/esm/typings/src/utils/trimEndOfCodeBlock.test.d.ts

@@ -0,0 +1 @@
+export {};