@promptbook/utils 0.92.0-21 → 0.92.0-23

package/esm/typings/src/execution/createPipelineExecutor/20-executeTask.d.ts

@@ -6,38 +6,41 @@ import type { ExecutionReportJson } from '../execution-report/ExecutionReportJso
 import type { PipelineExecutorResult } from '../PipelineExecutorResult';
 import type { CreatePipelineExecutorOptions } from './00-CreatePipelineExecutorOptions';
 /**
- * @@@
+ * Options for executing a single pipeline task, including task details, pipeline context, parameters, and callbacks.
  *
  * @private internal type of `executeTask`
  */
 type executeSingleTaskOptions = Required<CreatePipelineExecutorOptions> & {
     /**
-     * @@@
+     * The task to be executed.
      */
     readonly currentTask: ReadonlyDeep<TaskJson>;
     /**
-     * @@@
+     * The pipeline in which the task resides, fully prepared and validated.
      */
     readonly preparedPipeline: ReadonlyDeep<PipelineJson>;
     /**
-     * @@@
+     * The parameters to pass to the task execution.
      */
     readonly parametersToPass: Readonly<Parameters>;
     /**
-     * @@@
+     * Callback invoked with partial results as the execution progresses.
      */
     readonly onProgress: (newOngoingResult: PartialDeep<PipelineExecutorResult>) => Promisable<void>;
     /**
-     * @@@
+     * Mutable execution report object for tracking execution details.
      */
     readonly $executionReport: WritableDeep<ExecutionReportJson>;
     /**
-     * @@@
+     * String identifier for the pipeline, used in error messages and reporting.
      */
     readonly pipelineIdentification: string;
 };
 /**
- * @@@
+ * Executes a single task within a pipeline, handling parameter validation, error checking, and progress reporting.
+ *
+ * @param options - Options for execution, including the task, pipeline, parameters, and callbacks.
+ * @returns The output parameters produced by the task.
  *
  * @private internal utility of `createPipelineExecutor`
  */

package/esm/typings/src/execution/createPipelineExecutor/30-executeFormatSubvalues.d.ts

@@ -1,13 +1,25 @@
+import type { PartialDeep, Promisable } from 'type-fest';
 import type { TODO_any } from '../../utils/organization/TODO_any';
+import type { PipelineExecutorResult } from '../PipelineExecutorResult';
 import type { ExecuteAttemptsOptions } from './40-executeAttempts';
 /**
- * @@@
+ * Options for executing a pipeline task that involves formatting subvalues (e.g., iterating over CSV rows).
+ * Extends ExecuteAttemptsOptions with a progress callback.
  *
  * @private internal type of `executeFormatSubvalues`
  */
-type ExecuteFormatCellsOptions = ExecuteAttemptsOptions;
+type ExecuteFormatCellsOptions = ExecuteAttemptsOptions & {
+    /**
+     * Callback invoked with partial results as the execution progresses.
+     */
+    readonly onProgress: (newOngoingResult: PartialDeep<PipelineExecutorResult>) => Promisable<void>;
+};
 /**
- * @@@
+ * Executes a pipeline task that requires mapping or iterating over subvalues of a parameter (such as rows in a CSV).
+ * Handles format and subformat resolution, error handling, and progress reporting.
+ *
+ * @param options - Options for execution, including task details and progress callback.
+ * @returns The result of the subvalue mapping or execution attempts.
  *
  * @private internal utility of `createPipelineExecutor`
  */

package/esm/typings/src/execution/createPipelineExecutor/getReservedParametersForTask.d.ts

@@ -5,7 +5,7 @@ import type { Parameters } from '../../types/typeAliases';
 import type { ReservedParameters } from '../../types/typeAliases';
 import type { ExecutionTools } from '../ExecutionTools';
 /**
- * @@@
+ * Options for retrieving reserved parameters for a pipeline task, including context, pipeline, and identification.
  *
  * @private internal type of `getReservedParametersForTask`
  */
@@ -15,26 +15,28 @@ type GetReservedParametersForTaskOptions = {
      */
     readonly tools: ExecutionTools;
     /**
-     * @@@
+     * The prepared and validated pipeline in which the task resides.
      */
     readonly preparedPipeline: ReadonlyDeep<PipelineJson>;
     /**
-     * @@@
+     * The task for which reserved parameters are being retrieved.
      */
     readonly task: ReadonlyDeep<TaskJson>;
     /**
-     * @@@
-     *
-     * Parameters to complete the content of the task for embedding
+     * Parameters to complete the content of the task for embedding and context.
      */
     readonly parameters: Readonly<Parameters>;
     /**
-     * @@@
+     * String identifier for the pipeline, used in error messages and reporting.
      */
     readonly pipelineIdentification: string;
 };
 /**
- * @@@
+ * Retrieves all reserved parameters for a given pipeline task, including context, knowledge, examples, and metadata.
+ * Ensures all reserved parameters are defined and throws if any are missing.
+ *
+ * @param options - Options including tools, pipeline, task, and context.
+ * @returns An object containing all reserved parameters for the task.
  *
  * @private internal utility of `createPipelineExecutor`
  */

package/esm/typings/src/formats/_common/FormatParser.d.ts

@@ -4,9 +4,11 @@ import type { string_SCREAMING_CASE } from '../../utils/normalization/normalizeT
 import type { empty_object } from '../../utils/organization/empty_object';
 import type { FormatSubvalueParser } from './FormatSubvalueParser';
 /**
- * A format definition is a set of functions that define how to validate, heal and convert response from LLM
+ * A format definition is a set of functions that define how to validate, heal and convert response from LLM.
  *
- * @@@ Describe setting vs schema
+ * @remarks
+ * - "settings" are runtime options that affect parsing (e.g., delimiter for CSV).
+ * - "schema" is a structural definition or contract for the data (e.g., expected fields in JSON).
  *
  * @see https://github.com/webgptorg/promptbook/discussions/36
  * @private still in development [🏢]
@@ -56,7 +58,7 @@ export type FormatParser<TValue extends TPartialValue, TPartialValue extends str
      */
     heal(value: string, settings?: TSettings, scheme?: TSchema): TValue;
     /**
-     * @@@
+     * Parsers for extracting or mapping subvalues from the main value (e.g., rows from CSV, items from JSON array).
      */
     readonly subvalueParsers: ReadonlyArray<FormatSubvalueParser<TValue, TSettings>>;
 };

package/esm/typings/src/formats/_common/FormatSubvalueParser.d.ts

@@ -5,7 +5,8 @@ import type { string_parameter_name } from '../../types/typeAliases';
 import type { string_SCREAMING_CASE } from '../../utils/normalization/normalizeTo_SCREAMING_CASE';
 import type { empty_object } from '../../utils/organization/empty_object';
 /**
- * @@@
+ * Defines how to extract or map subvalues from a main value in a specific format (e.g., cells from CSV, items from JSON array).
+ * Used for iterating or transforming structured data in pipeline tasks.
  */
 export type FormatSubvalueParser<TValue extends string, TSettings extends empty_object> = {
     /**
@@ -19,12 +20,46 @@ export type FormatSubvalueParser<TValue extends string, TSettings extends empty_
      */
     readonly aliases?: ReadonlyArray<string_name & string_SCREAMING_CASE>;
     /**
-     * Maps values
+     * Maps or transforms subvalues from the main value. For example, iterates over all CSV cells or JSON array items.
      *
-     * For example, if you have a JSON object and you want to map all values to uppercase
-     * Or iterate over all CSV cells @@@
+     * @param options - Options for mapping, including callbacks for progress and value transformation.
+     * @returns The final mapped string result.
      */
-    mapValues(value: TValue, outputParameterName: string_parameter_name, settings: TSettings, mapCallback: (subvalues: Parameters, index: number) => Promisable<string>): Promise<string>;
+    mapValues(options: FormatSubvalueParserMapValuesOptions<TValue, TSettings>): Promise<string>;
+};
+/**
+ * Options for mapping or extracting subvalues from a main value using a FormatSubvalueParser.
+ */
+export type FormatSubvalueParserMapValuesOptions<TValue extends string, TSettings extends empty_object> = {
+    /**
+     * @@@
+     */
+    readonly value: TValue;
+    /**
+     * @@@
+     */
+    readonly outputParameterName: string_parameter_name;
+    /**
+     * @@@
+     */
+    readonly settings: TSettings;
+    /**
+     * @@@
+     *
+     * @param subvalues @@@
+     * @param index Current index of the subvalue which is being mapped
+     * @param length Full length of the subvalues
+     * @param number @@@
+     * @returns @@@
+     */
+    mapCallback(subvalues: Parameters, index: number, length: number): Promisable<TValue>;
+    /**
+     * @@@
+     *
+     * @param partialResultString @@@
+     * @returns @@@
+     */
+    onProgress(partialResultString: TValue): Promisable<void>;
 };
 /**
  * Note: [👩🏾‍🤝‍🧑🏽]

package/esm/typings/src/formats/csv/utils/isValidCsvString.d.ts

@@ -2,7 +2,7 @@
  * Function to check if a string is valid CSV
  *
  * @param value The string to check
- * @returns True if the string is a valid CSV string, false otherwise
+ * @returns `true` if the string is a valid CSV string, false otherwise
  *
  * @public exported from `@promptbook/utils`
  */

package/esm/typings/src/formats/json/utils/isValidJsonString.d.ts

@@ -2,7 +2,7 @@
  * Function isValidJsonString will tell you if the string is valid JSON or not
  *
  * @param value The string to check
- * @returns True if the string is a valid JSON string, false otherwise
+ * @returns `true` if the string is a valid JSON string, false otherwise
  *
  * @public exported from `@promptbook/utils`
  */

package/esm/typings/src/formats/xml/utils/isValidXmlString.d.ts

@@ -2,7 +2,7 @@
  * Function to check if a string is valid XML
  *
  * @param value
- * @returns True if the string is a valid XML string, false otherwise
+ * @returns `true` if the string is a valid XML string, false otherwise
  *
  * @public exported from `@promptbook/utils`
  */

package/esm/typings/src/llm-providers/_common/register/LlmToolsOptions.d.ts

@@ -1,6 +1,9 @@
 import type { TODO_object } from '../../../utils/organization/TODO_object';
 /**
- * @@@
+ * Options for configuring LLM (Large Language Model) tools.
+ *
+ * This type is used to pass provider-specific options to LLM execution tools.
+ *
  *
  * @@@ `LlmToolsMetadata` vs `LlmToolsConfiguration` vs `LlmToolsOptions` (vs `Registered`)
  */

package/esm/typings/src/scrapers/_common/register/$scrapersMetadataRegister.d.ts

@@ -1,10 +1,10 @@
 import { $Register } from '../../../utils/$Register';
 import type { ScraperAndConverterMetadata } from './ScraperAndConverterMetadata';
 /**
- * @@@
+ * Global registry for storing metadata about all available scrapers and converters.
  *
- * Note: `$` is used to indicate that this interacts with the global scope
- * @singleton Only one instance of each register is created per build, but thare can be more @@@
+ * Note: `$` is used to indicate that this interacts with the global scope.
+ * @singleton Only one instance of each register is created per build, but there can be more in different contexts (e.g., tests).
  * @public exported from `@promptbook/core`
  */
 export declare const $scrapersMetadataRegister: $Register<ScraperAndConverterMetadata>;

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

@@ -123,7 +123,8 @@ export type InputParameters = Exclude<Record<string_parameter_name, really_unkno
  */
 export type string_reserved_parameter_name = TupleToUnion<typeof RESERVED_PARAMETER_NAMES>;
 /**
- * @@@
+ * Represents a mapping of reserved parameter names to their values.
+ * Reserved parameters are used internally by the pipeline and should not be set by users.
  *
  * Note: [🚉] This is fully serializable as JSON
  */
@@ -233,7 +234,9 @@ export type string_markdown_text = string;
  */
 export type string_markdown_codeblock_language = 'book' | 'markdown' | 'text' | 'javascript' | 'css' | 'json';
 /**
- * @@@
+ * A URL pointing to Promptbook documentation or a specific discussion.
+ *
+ * For example: `https://github.com/webgptorg/promptbook/discussions/123`
  */
 export type string_promptbook_documentation_url = `https://github.com/webgptorg/promptbook/discussions/${number | `@@${string}`}`;
 /**
@@ -448,15 +451,14 @@ export type string_uuid = string & {
     readonly _type: 'uuid';
 };
 /**
- * Application identifier
+ * Application identifier, used to distinguish different apps or clients.
  *
- * @@@
+ * For example: 'cli', 'playground', or a custom app id.
  */
 export type string_app_id = id | 'app';
 /**
- * End user identifier
- *
- * @@@
+ * End user identifier, can be a user id or email address.
+ * Used for tracking and abuse prevention.
  */
 export type string_user_id = id | string_email;
 /**

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

@@ -2,33 +2,34 @@ import { type IDestroyable } from 'destroyable';
 import type { string_name } from '../types/typeAliases';
 import type { TODO_string } from './organization/TODO_string';
 /**
- * @@@
+ * Represents an entity in a global registry.
+ * Contains identifying information about the package and class.
  */
 export type Registered = {
     /**
-     * @@@
+     * The name of the package where the registered entity is defined.
      */
     readonly packageName: TODO_string;
     /**
-     * @@@
+     * The name of the class being registered.
      */
     readonly className: TODO_string;
 };
 /**
- * @@@
+ * Represents a registration record, including destroyable interface and registry name.
  */
 export type Registration = Registered & IDestroyable & {
     /**
-     * @@@
+     * The name of the register this entity is registered in.
      */
     readonly registerName: string_name;
 };
 /**
- * Register is @@@
+ * Global registry for storing and managing registered entities of a given type.
  *
  * Note: `$` is used to indicate that this function is not a pure function - it accesses and adds variables in global scope.
  *
- * @private internal utility, exported are only signleton instances of this class
+ * @private internal utility, exported are only singleton instances of this class
  */
 export declare class $Register<TRegistered extends Registered> {
     private readonly registerName;

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

@@ -1,26 +1,26 @@
 import type { string_parameter_name } from '../../types/typeAliases';
 import type { string_parameter_value } from '../../types/typeAliases';
 /**
- * @@@
+ * Options for mapping available parameters to expected parameters in a pipeline task.
  */
 type MakeapAvailableToExpectedParametersOptions = {
     /**
-     * @@@
+     * The set of expected parameter names (keys) for the task, all values are null.
      */
     readonly expectedParameters: Readonly<Record<string_parameter_name, null>>;
     /**
-     * @@@
+     * The set of available parameters (name-value pairs) to map to the expected parameters.
      */
     readonly availableParameters: Readonly<Record<string_parameter_name, string_parameter_value>>;
 };
 /**
- * Maps available parameters to expected parameters
+ * Maps available parameters to expected parameters for a pipeline task.
  *
  * The strategy is:
- * 1) @@@
- * 2) @@@
+ * 1) First, match parameters by name where both available and expected.
+ * 2) Then, if there are unmatched expected and available parameters, map them by order.
  *
- * @throws {PipelineExecutionError} @@@
+ * @throws {PipelineExecutionError} If the number of unmatched expected and available parameters does not match, or mapping is ambiguous.
  * @private within the repository used in `createPipelineExecutor`
  */
 export declare function mapAvailableToExpectedParameters(options: MakeapAvailableToExpectedParametersOptions): Readonly<Record<string_parameter_name, string_parameter_value>>;

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

@@ -1,10 +1,11 @@
 import type { PipelineJson } from '../../pipeline/PipelineJson/PipelineJson';
 /**
- * @@@
+ * Creates a deep clone of a PipelineJson object, copying all properties explicitly.
  *
- * Note: It is usefull @@@
+ * Note: It is useful for ensuring that modifications to the returned pipeline do not affect the original.
  *
- * @param pipeline
+ * @param pipeline The pipeline to clone.
+ * @returns A new PipelineJson object with the same properties as the input.
  * @public exported from `@promptbook/utils`
  */
 export declare function clonePipeline(pipeline: PipelineJson): PipelineJson;

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

@@ -1,7 +1,11 @@
 import type { WritableDeep } from 'type-fest';
 /**
- * @@@
+ * Creates a deep clone of the given object
  *
+ * Note: This method only works for objects that are fully serializable to JSON and do not contain functions, Dates, or special types.
+ *
+ * @param objectValue The object to clone.
+ * @returns A deep, writable clone of the input object.
  * @public exported from `@promptbook/utils`
  */
 export declare function deepClone<TObject>(objectValue: TObject): WritableDeep<TObject>;

package/esm/typings/src/utils/validators/javascriptName/isValidJavascriptName.d.ts

@@ -1,10 +1,10 @@
 import type { string_javascript_name } from '../../../types/typeAliases';
 import type { really_unknown } from '../../organization/really_unknown';
 /**
- * @@@
+ * Checks if the given value is a valid JavaScript identifier name.
  *
- * @param javascriptName @@@
- * @returns @@@
+ * @param javascriptName The value to check for JavaScript identifier validity.
+ * @returns `true` if the value is a valid JavaScript name, false otherwise.
  * @public exported from `@promptbook/utils`
  */
 export declare function isValidJavascriptName(javascriptName: really_unknown): javascriptName is string_javascript_name;

package/esm/typings/src/utils/validators/parameterName/validateParameterName.d.ts

@@ -1,10 +1,11 @@
 import type { string_parameter_name } from '../../../types/typeAliases';
 /**
- * Function `validateParameterName` will @@@
+ * Function `validateParameterName` will normalize and validate a parameter name for use in pipelines.
+ * It removes diacritics, emojis, and quotes, normalizes to camelCase, and checks for reserved names and invalid characters.
  *
- * @param parameterName @@@
- * @returns @@@
- * @throws {ParseError} @@@
+ * @param parameterName The parameter name to validate and normalize.
+ * @returns The validated and normalized parameter name.
+ * @throws {ParseError} If the parameter name is empty, reserved, or contains invalid characters.
  * @private within the repository
  */
 export declare function validateParameterName(parameterName: string): string_parameter_name;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/utils",
-    "version": "0.92.0-21",
+    "version": "0.92.0-23",
     "description": "It's time for a paradigm shift. The future of software in plain English, French or Latin",
     "private": false,
     "sideEffects": false,

package/umd/index.umd.js

@@ -22,7 +22,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.92.0-21';
+    const PROMPTBOOK_ENGINE_VERSION = '0.92.0-23';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -78,7 +78,7 @@
     const SMALL_NUMBER = 0.001;
     // <- TODO: [🧜‍♂️]
     /**
-     * @@@
+     * Default settings for parsing and generating CSV files in Promptbook.
      *
      * @public exported from `@promptbook/core`
      */
@@ -390,8 +390,12 @@
      */
 
     /**
-     * @@@
+     * Creates a deep clone of the given object
+     *
+     * Note: This method only works for objects that are fully serializable to JSON and do not contain functions, Dates, or special types.
      *
+     * @param objectValue The object to clone.
+     * @returns A deep, writable clone of the input object.
      * @public exported from `@promptbook/utils`
      */
     function deepClone(objectValue) {
@@ -1459,7 +1463,7 @@
      * Function to check if a string is valid CSV
      *
      * @param value The string to check
-     * @returns True if the string is a valid CSV string, false otherwise
+     * @returns `true` if the string is a valid CSV string, false otherwise
      *
      * @public exported from `@promptbook/utils`
      */
@@ -1481,7 +1485,7 @@
      * Function isValidJsonString will tell you if the string is valid JSON or not
      *
      * @param value The string to check
-     * @returns True if the string is a valid JSON string, false otherwise
+     * @returns `true` if the string is a valid JSON string, false otherwise
      *
      * @public exported from `@promptbook/utils`
      */
@@ -1539,7 +1543,7 @@
      * Function to check if a string is valid XML
      *
      * @param value
-     * @returns True if the string is a valid XML string, false otherwise
+     * @returns `true` if the string is a valid XML string, false otherwise
      *
      * @public exported from `@promptbook/utils`
      */
@@ -2353,15 +2357,16 @@
     }
 
     /**
-     * @@@
+     * Creates a deep clone of a PipelineJson object, copying all properties explicitly.
      *
-     * Note: It is usefull @@@
+     * Note: It is useful for ensuring that modifications to the returned pipeline do not affect the original.
      *
-     * @param pipeline
+     * @param pipeline The pipeline to clone.
+     * @returns A new PipelineJson object with the same properties as the input.
      * @public exported from `@promptbook/utils`
      */
     function clonePipeline(pipeline) {
-        // Note: Not using spread operator (...) because @@@
+        // Note: Not using spread operator (...) because it does not deeply copy nested objects and may miss non-enumerable properties.
         const { pipelineUrl, sourceFile, title, bookVersion, description, formfactorName, parameters, tasks, knowledgeSources, knowledgePieces, personas, preparations, sources, } = pipeline;
         return {
             pipelineUrl,
@@ -2647,10 +2652,10 @@
      */
 
     /**
-     * @@@
+     * Checks if the given value is a valid JavaScript identifier name.
      *
-     * @param javascriptName @@@
-     * @returns @@@
+     * @param javascriptName The value to check for JavaScript identifier validity.
+     * @returns `true` if the value is a valid JavaScript name, false otherwise.
      * @public exported from `@promptbook/utils`
      */
     function isValidJavascriptName(javascriptName) {