@promptbook/utils 0.103.0-9 → 0.103.0

package/esm/typings/src/types/typeAliases.d.ts

@@ -142,6 +142,18 @@ export type string_title = string;
  * For example `"My AI Assistant"`
  */
 export type string_agent_name = string;
+/**
+ * Semantic helper
+ *
+ * For example `"My AI Assistant"`
+ */
+export type string_agent_name_in_book = string;
+/**
+ * Semantic helper
+ *
+ * For example `"b126926439c5fcb83609888a11283723c1ef137c0ad599a77a1be81812bd221d"`
+ */
+export type string_agent_hash = string_sha256;
 /**
  * Unstructured description of the persona
  *
@@ -318,12 +330,18 @@ export type string_css_class = string;
  * For example `border`
  */
 export type string_css_property = string;
+/**
+ * Semantic helper
+ *
+ * For example `"Arial, sans-serif"`
+ */
+export type string_fonts = string;
 /**
  * Semantic helper
  *
  * For example `13px`
  */
-export type string_css_value = string;
+export type string_css_value = string | number;
 /**
  * Semantic helper
  *
@@ -354,6 +372,12 @@ export type string_base_url = string;
  * For example `"https://promptbook.studio/webgpt/"`
  */
 export type string_pipeline_root_url = string;
+/**
+ * Semantic helper
+ *
+ * For example `"https://s6.ptbk.io/agents/agent-007"`
+ */
+export type string_agent_url = string;
 /**
  * Semantic helper
  *
@@ -530,7 +554,19 @@ export type string_dirname = string_absolute_dirname | string_relative_dirname;
  *
  * For example `"John Smith"`
  */
-export type string_person_fullname = string;
+export type string_person_fullname = `${string_person_firstname} ${string_person_lastname}` | string;
+/**
+ * Semantic helper
+ *
+ * For example `"John Smith"`
+ */
+export type string_person_firstname = string;
+/**
+ * Semantic helper
+ *
+ * For example `"John Smith"`
+ */
+export type string_person_lastname = string;
 /**
  * Semantic helper
  * Full profile of the person with his email and web (like in package.json)

package/esm/typings/src/utils/color/$randomColor.d.ts

@@ -8,4 +8,5 @@ export declare function $randomColor(): Color;
 /**
  * TODO: !! Use Internally Color.fromValues
  * TODO: !! randomColorWithAlpha
+ * TODO: [🤶] Maybe export through `@promptbook/utils` or `@promptbook/random` package
  */

package/esm/typings/src/utils/color/Color.d.ts

@@ -23,7 +23,15 @@ export declare class Color {
      * @param color
      * @returns Color object
      */
-    static from(color: string_color | Color): WithTake<Color>;
+    static from(color: string_color | Color, _isSingleValue?: boolean): WithTake<Color>;
+    /**
+     * Creates a new Color instance from miscellaneous formats
+     * It just does not throw error when it fails, it returns PROMPTBOOK_COLOR instead
+     *
+     * @param color
+     * @returns Color object
+     */
+    static fromSafe(color: string_color | Color): WithTake<Color>;
     /**
      * Creates a new Color instance from miscellaneous string formats
      *
@@ -59,6 +67,13 @@ export declare class Color {
      * @returns Color object
      */
     private static fromHex3;
+    /**
+     * Creates a new Color instance from color in hex format with 4 digits (with alpha channel)
+     *
+     * @param color in hex for example `09df`
+     * @returns Color object
+     */
+    private static fromHex4;
     /**
      * Creates a new Color instance from color in hex format with 6 color digits (without alpha channel)
      *

package/esm/typings/src/utils/color/Color.test.d.ts

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

package/esm/typings/src/utils/color/css-colors.d.ts

@@ -4,6 +4,7 @@
  * @public exported from `@promptbook/color`
  */
 export declare const CSS_COLORS: {
+    readonly promptbook: "#79EAFD";
     readonly transparent: "rgba(0,0,0,0)";
     readonly aliceblue: "#f0f8ff";
     readonly antiquewhite: "#faebd7";

package/esm/typings/src/utils/color/internal-utils/checkChannelValue.d.ts

@@ -9,6 +9,3 @@
  * @private util of `@promptbook/color`
  */
 export declare function checkChannelValue(channelName: string, value: number): asserts value is number;
-/**
- * TODO: [🧠][🚓] Is/which combination it better to use asserts/check, validate or is utility function?
- */

package/esm/typings/src/utils/color/operators/darken.d.ts

@@ -1,4 +1,4 @@
-import { number_percent } from '../../../types/typeAliases';
+import type { number_percent } from '../../../types/typeAliases';
 import type { ColorTransformer } from './ColorTransformer';
 /**
  * Makes color transformer which darker the given color

package/esm/typings/src/utils/color/operators/grayscale.d.ts

@@ -1,4 +1,4 @@
-import { number_percent } from '../../../types/typeAliases';
+import type { number_percent } from '../../../types/typeAliases';
 import type { ColorTransformer } from './ColorTransformer';
 /**
  * Makes color transformer which returns a grayscale version of the color

package/esm/typings/src/utils/color/operators/lighten.d.ts

@@ -1,5 +1,5 @@
+import type { number_percent } from '../../../types/typeAliases';
 import type { ColorTransformer } from './ColorTransformer';
-import { number_percent } from '../../../types/typeAliases';
 /**
  * Makes color transformer which lighten the given color
  *

package/esm/typings/src/utils/color/operators/mixWithColor.d.ts

@@ -1,6 +1,6 @@
+import type { number_percent } from '../../../types/typeAliases';
 import { Color } from '../Color';
 import type { ColorTransformer } from './ColorTransformer';
-import { number_percent } from '../../../types/typeAliases';
 /**
  * Makes color transformer which returns a mix of two colors based on a ratio
  *

package/esm/typings/src/utils/color/operators/saturate.d.ts

@@ -1,4 +1,4 @@
-import { number_percent } from '../../../types/typeAliases';
+import type { number_percent } from '../../../types/typeAliases';
 import type { ColorTransformer } from './ColorTransformer';
 /**
  * Makes color transformer which saturate the given color

package/esm/typings/src/utils/environment/$detectRuntimeEnvironment.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Returns information about the current runtime environment
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it looks at the global object to determine the environments
+ *
+ * @public exported from `@promptbook/utils`
+ */
+export declare function $detectRuntimeEnvironment(): {
+    isRunningInBrowser: any;
+    isRunningInJest: any;
+    isRunningInNode: any;
+    isRunningInWebWorker: any;
+};
+/**
+ * TODO: [🎺] Also detect and report node version here
+ */

package/esm/typings/src/utils/environment/$getGlobalScope.d.ts

@@ -1,4 +1,4 @@
-import type { really_any } from '../organization/really_any';
+import type { chococake } from '../organization/really_any';
 /**
  * Safely retrieves the global scope object (window in browser, global in Node.js)
  * regardless of the JavaScript environment in which the code is running
@@ -7,4 +7,4 @@ import type { really_any } from '../organization/really_any';
  *
  *  @private internal function of `$Register`
  */
-export declare function $getGlobalScope(): really_any;
+export declare function $getGlobalScope(): chococake;

package/esm/typings/src/utils/execCommand/$execCommand.d.ts

@@ -1,3 +1,4 @@
+import type { $side_effect } from '../organization/$side_effect';
 import type { ExecCommandOptions } from './ExecCommandOptions';
 /**
  * Run one command in a shell
@@ -10,7 +11,7 @@ import type { ExecCommandOptions } from './ExecCommandOptions';
  *
  * @public exported from `@promptbook/node`
  */
-export declare function $execCommand(options: ExecCommandOptions): Promise<string>;
+export declare function $execCommand(options: ExecCommandOptions): Promise<$side_effect & string>;
 /**
  * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
  */

package/esm/typings/src/utils/execCommand/$execCommands.d.ts

@@ -1,3 +1,4 @@
+import type { $side_effect } from '../organization/$side_effect';
 /**
  * Run multiple commands in a shell in sequence
  *
@@ -8,7 +9,7 @@
  *
  * @public exported from `@promptbook/node`
  */
-export declare function $execCommands({ commands, cwd, crashOnError, }: {
+export declare function $execCommands({ commands, cwd, crashOnError, }: $side_effect & {
     readonly commands: string[];
     readonly cwd: string;
     readonly crashOnError?: boolean;

package/esm/typings/src/utils/files/$induceBookDownload.d.ts

@@ -0,0 +1,13 @@
+import type { string_book } from '../../book-2.0/agent-source/string_book';
+import type { $side_effect } from '../organization/$side_effect';
+/**
+ * Download a Book in a browser
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - its purpose is to cause a side effect (download a file)
+ *
+ * @public exported from `@promptbook/browser`
+ */
+export declare function $induceBookDownload(book: string_book): Promise<$side_effect>;
+/**
+ * Note: [🔵] Code in this file should never be published outside of `@promptbook/browser`
+ */

package/esm/typings/src/utils/files/$induceFileDownload.d.ts

@@ -0,0 +1,13 @@
+import type { string_url } from '../../types/typeAliases';
+import type { $side_effect } from '../organization/$side_effect';
+/**
+ * Download a File in a browser
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - its purpose is to cause a side effect (download a file)
+ *
+ * @public exported from `@promptbook/browser`
+ */
+export declare function $induceFileDownload(fileOrBlobOrUrl: File | Blob | URL | string_url): Promise<$side_effect>;
+/**
+ * Note: [🔵] Code in this file should never be published outside of `@promptbook/browser`
+ */

package/esm/typings/src/utils/files/ObjectUrl.d.ts

@@ -0,0 +1,46 @@
+import { IDestroyable, Registration } from 'destroyable';
+import type { string_mime_type, string_url } from '../../types/typeAliases';
+/**
+ * Converts Blob, File or MediaSource to url using URL.createObjectURL
+ *
+ * @public exported from `@promptbook/browser`
+ */
+export declare class ObjectUrl extends Registration implements IDestroyable {
+    readonly src: string_url;
+    private constructor();
+    /**
+     * Creates ObjectUrl from multiple input types
+     * Note: DO NOT forget to call destroy() when you are done with it
+     */
+    static from(source: Blob | File | MediaSource | string, mimeType: string_mime_type): ObjectUrl;
+    /**
+     * Creates ObjectUrl from string
+     * Note: DO NOT forget to call destroy() when you are done with it
+     */
+    static fromString(source: string, mimeType: string_mime_type): ObjectUrl;
+    /**
+     * Creates ObjectUrl
+     * DO NOT forget to call destroy() when you are done with it
+     */
+    static fromBlob(source: Blob | File | MediaSource): ObjectUrl;
+    /**
+     * Creates ObjectUrl:
+     * 1) With functionality for Blobs, Files or MediaSources
+     * 2) Just a wrapper for string urls
+     *
+     * DO NOT forget to call destroy() when you are done with it
+     */
+    static fromBlobOrUrl(source: Blob | File | MediaSource | URL | string_url): ObjectUrl;
+    /**
+     * Gets object url as string
+     * @alias src
+     */
+    get href(): string_url;
+    /**
+     * Gets object url as URL object
+     */
+    get url(): URL;
+}
+/**
+ * Note: [🔵] Code in this file should never be published outside of `@promptbook/browser`
+ */

package/esm/typings/src/utils/files/listAllFiles.d.ts

@@ -1,13 +1,12 @@
 import type { FilesystemTools } from '../../execution/FilesystemTools';
-import type { string_dirname } from '../../types/typeAliases';
-import type { string_filename } from '../../types/typeAliases';
+import type { string_dirname, string_filename } from '../../types/typeAliases';
 /**
  * Reads all files in the directory
  *
  * @param path
  * @param isRecursive
  * @returns List of all files in the directory
- * @private internal function of `createCollectionFromDirectory`
+ * @private internal function of `AgentCollectionInDirectory` and `createPipelineCollectionFromDirectory`
  */
 export declare function listAllFiles(path: string_dirname, isRecursive: boolean, fs: FilesystemTools): Promise<Array<string_filename>>;
 /**

package/esm/typings/src/utils/misc/aboutPromptbookInformation.d.ts

@@ -0,0 +1,27 @@
+import type { string_markdown } from '../../types/typeAliases';
+export type AboutPromptbookInformationOptions = {
+    /**
+     * Include information about available servers
+     *
+     * @default true
+     */
+    isServersInfoIncluded?: boolean;
+    /**
+     * Include information about runtime environment
+     *
+     * @default true
+     */
+    isRuntimeEnvironmentInfoIncluded?: boolean;
+};
+/**
+ * Provide information about Promptbook, engine version, book language version, servers, ...
+ *
+ * @param options Which information to include
+ * @returns  Information about Promptbook in markdown format
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare function aboutPromptbookInformation(options?: AboutPromptbookInformationOptions): string_markdown;
+/**
+ * TODO: [🗽] Unite branding and make single place for it
+ */

package/esm/typings/src/utils/misc/computeHash.d.ts

@@ -0,0 +1,11 @@
+import { string_sha256 } from '../../types/typeAliases';
+import { really_unknown } from '../organization/really_unknown';
+/**
+ * Computes SHA-256 hash of the given object
+ *
+ * @public exported from `@promptbook/utils`
+ */
+export declare function computeHash(value: really_unknown): string_sha256;
+/**
+ * TODO: [🥬][🥬] Use this ACRY
+ */

package/esm/typings/src/utils/misc/computeHash.test.d.ts

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

package/esm/typings/src/utils/misc/injectCssModuleIntoShadowRoot.d.ts

@@ -16,5 +16,6 @@ export type InjectCssModuleIntoShadowRootOptions = {
  *
  * @public exported from `@promptbook/components`
  *         <- TODO: [🧠] Make `@promptbook/components-utils`
+ * @deprecated This was used for BookEditor shadow DOM support, which is no longer needed
  */
 export declare function injectCssModuleIntoShadowRoot(options: InjectCssModuleIntoShadowRootOptions): void;

package/esm/typings/src/utils/misc/xAboutPromptbookInformation.d.ts

@@ -0,0 +1,13 @@
+import type { AboutPromptbookInformationOptions } from './aboutPromptbookInformation';
+type AboutPromptbookInformationProps = AboutPromptbookInformationOptions;
+/**
+ * Provide information about Promptbook, engine version, book language version, servers, ...
+ *
+ * @public exported from `@promptbook/components`
+ */
+export declare function AboutPromptbookInformation(props: AboutPromptbookInformationProps): import("react/jsx-runtime").JSX.Element;
+export {};
+/**
+ * TODO: !!! Remove "x" from filename
+ * TODO: [🗽] Unite branding and make single place for it
+ */

package/esm/typings/src/utils/normalization/normalize-to-kebab-case.d.ts

@@ -9,6 +9,8 @@ export type string_kebab_case = string;
 /**
  * Converts a given text to kebab-case format.
  *
+ * Note: [🔂] This function is idempotent.
+ *
  * @param text The text to be converted.
  * @returns The kebab-case formatted string.
  * @example 'hello-world'

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

@@ -0,0 +1,9 @@
+/**
+ * Normalizes message text for comparison
+ *
+ * @param text The message text to normalize
+ * @returns The normalized message text
+ *
+ * @public exported from `@promptbook/utils`
+ */
+export declare function normalizeMessageText(text: string): string;

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

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

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

@@ -7,6 +7,9 @@
  */
 export type string_PascalCase = string;
 /**
+ * Normalizes a given text to PascalCase format.
+ *
+ * Note: [🔂] This function is idempotent.
  *
  * @param text @public exported from `@promptbook/utils`
  * @returns

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

@@ -9,6 +9,8 @@ export type string_camelCase = string;
 /**
  * Normalizes a given text to camelCase format.
  *
+ * Note: [🔂] This function is idempotent.
+ *
  * @param text The text to be normalized.
  * @param _isFirstLetterCapital Whether the first letter should be capitalized.
  * @returns The camelCase formatted string.

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

@@ -1,6 +1,8 @@
 /**
  * Converts a title string into a normalized name.
  *
+ * Note: [🔂] This function is idempotent.
+ *
  * @param value The title string to be converted to a name.
  * @returns A normalized name derived from the input title.
  * @example 'Hello World!' -> 'hello-world'

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

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

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

@@ -0,0 +1,7 @@
+import type { chococake } from './really_any';
+/**
+ * Organizational helper to mark a function that produces side effects
+ *
+ * @private within the repository
+ */
+export type $side_effect = void | chococake;

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

@@ -1,4 +1,4 @@
-import type { really_any } from './really_any';
+import type { chococake } from './really_any';
 /**
  * Just marks a place of place where should be something implemented
  * No side effects.
@@ -9,4 +9,4 @@ import type { really_any } from './really_any';
  * @returns void
  * @private within the repository
  */
-export declare function TODO_USE(...value: ReadonlyArray<really_any>): void;
+export declare function TODO_USE(...value: ReadonlyArray<chococake>): void;

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

@@ -1,4 +1,4 @@
-import type { really_any } from './really_any';
+import type { chococake } from './really_any';
 /**
  * Just says that the variable is not used but should be kept
  * No side effects.
@@ -13,4 +13,4 @@ import type { really_any } from './really_any';
  * @returns void
  * @private within the repository
  */
-export declare function keepUnused<TTypeToKeep1 = really_any, TTypeToKeep2 = really_any, TTypeToKeep3 = really_any>(...valuesToKeep: ReadonlyArray<really_any>): void;
+export declare function keepUnused<TTypeToKeep1 = chococake, TTypeToKeep2 = chococake, TTypeToKeep3 = chococake>(...valuesToKeep: ReadonlyArray<chococake>): void;

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

@@ -1,4 +1,4 @@
-import type { really_any } from './really_any';
+import type { chococake } from './really_any';
 /**
  * Does nothing, but preserves the function in the bundle
  * Compiler is tricked into thinking the function is used
@@ -7,7 +7,7 @@ import type { really_any } from './really_any';
  * @returns nothing
  * @private within the repository
  */
-export declare function $preserve(...value: Array<really_any>): void;
+export declare function $preserve(...value: Array<chococake>): void;
 /**
  * DO NOT USE THIS FUNCTION
  * Only purpose of this function is to trick the compiler and javascript engine
@@ -15,7 +15,7 @@ export declare function $preserve(...value: Array<really_any>): void;
  *
  * @private internal for `preserve`
  */
-export declare function __DO_NOT_USE_getPreserved(): Array<really_any>;
+export declare function __DO_NOT_USE_getPreserved(): Array<chococake>;
 /**
  * Note: [💞] Ignore a discrepancy between file name and entity name
  */

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

@@ -1,3 +1,10 @@
+/**
+ * Organizational helper to tell to use intentionally `any`
+ *
+ * @alias really_any
+ * @private within the repository
+ */
+export type chococake = really_any;
 /**
  * Organizational helper to mark a place where to really use `any`
  *

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

@@ -0,0 +1,31 @@
+import type { PartialDeep } from 'type-fest';
+import type { AgentBasicInformation } from '../../book-2.0/agent-source/AgentBasicInformation';
+import type { string_book } from '../../book-2.0/agent-source/string_book';
+import type { string_agent_name_in_book } from '../../types/typeAliases';
+type GenerateBookBoilerplateOptions = PartialDeep<Omit<AgentBasicInformation, 'parameters'>> & {
+    /**
+     * Name of the parent agent to inherit from
+     *
+     * @default 'Adam'
+     */
+    parentAgentName?: string_agent_name_in_book;
+    /**
+     * Name pool to use for generating agent name
+     *
+     * @default 'ENGLISH'
+     */
+    namePool?: string;
+};
+/**
+ * Generates boilerplate for a new agent book
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it is not deterministic
+ * Note: This function is using cryptographically secure components internally
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare function $generateBookBoilerplate(options?: GenerateBookBoilerplateOptions): string_book;
+export {};
+/**
+ * TODO: [🤶] Maybe export through `@promptbook/utils` or `@promptbook/random` package
+ */

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

@@ -0,0 +1,9 @@
+/**
+ * @@@@
+ *
+ * @private internal helper function
+ */
+export declare function $randomAgentPersona(): string;
+/**
+ * TODO: [🤶] Maybe export through `@promptbook/utils` or `@promptbook/random` package
+ */

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

@@ -0,0 +1,13 @@
+import type { string_color, string_person_fullname } from '../../types/typeAliases';
+export type RandomFullnameWithColorResult = {
+    fullname: string_person_fullname;
+    color: string_color;
+};
+/**
+ *
+ * @private internal helper function
+ */
+export declare function $randomFullnameWithColor(): RandomFullnameWithColorResult;
+/**
+ * TODO: [🤶] Maybe export through `@promptbook/utils` or `@promptbook/random` package
+ */

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

@@ -0,0 +1,9 @@
+/**
+ * Pick random item from the received array
+ *
+ * @private internal helper function
+ */
+export declare function $randomItem<TItem>(...items: Array<TItem>): TItem;
+/**
+ * TODO: [🤶] Maybe export through `@promptbook/utils` or `@promptbook/random` package
+ */ 

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

@@ -8,3 +8,6 @@ import type { number_seed } from '../../types/typeAliases';
  * @private internal helper function
  */
 export declare function $randomSeed(): number_seed;
+/**
+ * TODO: [🤶] Maybe export through `@promptbook/utils` or `@promptbook/random` package
+ */ 

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

@@ -2,6 +2,7 @@ import type { string_token } from '../../types/typeAliases';
 /**
  * Generates random token
  *
+ * Note: `$` is used to indicate that this function is not a pure function - it is not deterministic
  * Note: This function is cryptographically secure (it uses crypto.randomBytes internally)
  *
  * @private internal helper function
@@ -9,5 +10,6 @@ import type { string_token } from '../../types/typeAliases';
  */
 export declare function $randomToken(randomness: number): string_token;
 /**
+ * TODO: [🤶] Maybe export through `@promptbook/utils` or `@promptbook/random` package
  * TODO: Maybe use nanoid instead https://github.com/ai/nanoid
  */

package/esm/typings/src/utils/random/CzechNamePool.d.ts

@@ -0,0 +1,7 @@
+import type { NamePool } from './NamePool';
+/**
+ * Name pool for Czech names
+ *
+ * @private [🍇] Maybe expose via some package
+ */
+export declare const CzechNamePool: NamePool;

package/esm/typings/src/utils/random/EnglishNamePool.d.ts

@@ -0,0 +1,7 @@
+import type { NamePool } from './NamePool';
+/**
+ * Name pool for English names
+ *
+ * @private [🍇] Maybe expose via some package
+ */
+export declare const EnglishNamePool: NamePool;