@promptbook/editable 0.92.0-22 → 0.92.0-24

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

@@ -1,6 +1,7 @@
 import type { really_any } 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
  *
  * Note: `$` is used to indicate that this function is not a pure function - it access global scope
  *

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/editable",
-    "version": "0.92.0-22",
+    "version": "0.92.0-24",
     "description": "It's time for a paradigm shift. The future of software in plain English, French or Latin",
     "private": false,
     "sideEffects": false,
@@ -51,7 +51,7 @@
     "module": "./esm/index.es.js",
     "typings": "./esm/typings/src/_packages/editable.index.d.ts",
     "peerDependencies": {
-        "@promptbook/core": "0.92.0-22"
+        "@promptbook/core": "0.92.0-24"
     },
     "dependencies": {
         "crypto-js": "4.2.0",

package/umd/index.umd.js

@@ -23,7 +23,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.92.0-22';
+    const PROMPTBOOK_ENGINE_VERSION = '0.92.0-24';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -91,7 +91,7 @@
     const LOOP_LIMIT = 1000;
     // <- TODO: [🧜‍♂️]
     /**
-     * @@@
+     * Default settings for parsing and generating CSV files in Promptbook.
      *
      * @public exported from `@promptbook/core`
      */
@@ -755,7 +755,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`
      */
@@ -812,18 +812,28 @@
                             `));
                     }
                     const mappedData = [];
-                    for (let index = 0; index < csv.data.length; index++) {
+                    const length = csv.data.length;
+                    for (let index = 0; index < length; index++) {
                         const row = csv.data[index];
                         if (row[outputParameterName]) {
                             throw new CsvFormatError(`Can not overwrite existing column "${outputParameterName}" in CSV row`);
                         }
                         const mappedRow = {
                             ...row,
-                            [outputParameterName]: await mapCallback(row, index),
+                            [outputParameterName]: await mapCallback(row, index, length),
                         };
                         mappedData.push(mappedRow);
                         if (onProgress) {
                             // Note: Report the CSV with all rows mapped so far
+                            /*
+                            !!!!
+                             // Report progress with updated value
+                                const progressData = mappedData.map((row, i) =>
+                                  i > index ? { ...row, [outputParameterName]: PENDING_VALUE_PLACEHOLDER } : row,
+                              );
+
+
+                            */
                             await onProgress(papaparse.unparse(mappedData, { ...settings, ...MANDATORY_CSV_SETTINGS }));
                         }
                     }
@@ -850,9 +860,9 @@
                             `));
                     }
                     const mappedData = await Promise.all(csv.data.map(async (row, rowIndex) => {
-                        return /* not await */ Promise.all(Object.entries(row).map(async ([key, value], columnIndex) => {
+                        return /* not await */ Promise.all(Object.entries(row).map(async ([key, value], columnIndex, array) => {
                             const index = rowIndex * Object.keys(row).length + columnIndex;
-                            return /* not await */ mapCallback({ [key]: value }, index);
+                            return /* not await */ mapCallback({ [key]: value }, index, array.length);
                         }));
                     }));
                     return papaparse.unparse(mappedData, { ...settings, ...MANDATORY_CSV_SETTINGS });
@@ -872,7 +882,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`
      */
@@ -945,12 +955,12 @@
                 async mapValues(options) {
                     const { value, mapCallback, onProgress } = options;
                     const lines = value.split('\n');
-                    const mappedLines = await Promise.all(lines.map((lineContent, lineNumber) => 
+                    const mappedLines = await Promise.all(lines.map((lineContent, lineNumber, array) => 
                     // TODO: [🧠] Maybe option to skip empty line
                     /* not await */ mapCallback({
                         lineContent,
                         // TODO: [🧠] Maybe also put here `lineNumber`
-                    }, lineNumber)));
+                    }, lineNumber, array.length)));
                     return mappedLines.join('\n');
                 },
             },
@@ -971,7 +981,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`
      */
@@ -1268,8 +1278,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) {
@@ -1707,11 +1721,12 @@
     }
 
     /**
-     * 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
      */
     function validateParameterName(parameterName) {
@@ -2204,14 +2219,15 @@
     };
 
     /**
-     * Sheets is form of app that @@@
+     * Sheets is form of app that processes tabular data in CSV format, allowing transformation
+     * and analysis of structured data through AI-powered operations
      *
      * @public exported from `@promptbook/core`
      */
     const SheetsFormfactorDefinition = {
         name: 'SHEETS',
         aliasNames: ['SHEETS', 'SHEET'],
-        description: `@@@`,
+        description: `A formfactor for processing spreadsheet-like data in CSV format, enabling AI transformations on tabular data`,
         documentationUrl: `https://github.com/webgptorg/promptbook/discussions/176`,
         pipelineInterface: {
             inputParameters: [
@@ -2287,7 +2303,7 @@
     /**
      * Parses the formfactor command
      *
-     * Note: @@@ This command is used as formfactor for new commands - it should NOT be used in any `.book` file
+     * Note: This command is used as a formfactor for new commands and defines the app type format - it should NOT be used in any `.book` file
      *
      * @see `documentationUrl` for more details
      * @public exported from `@promptbook/editable`
@@ -2309,7 +2325,7 @@
         /**
          * Description of the FORMFACTOR command
          */
-        description: `@@`,
+        description: `Specifies the application type and interface requirements that this promptbook should conform to`,
         /**
          * Link to documentation
          */
@@ -3129,10 +3145,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) {