docs(script-sdk): add docs for the folder entity (#8657)

packages/insomnia-scripting-environment/src/objects/async_objects.ts

@@ -1,8 +1,10 @@
 let monitoring = true;
 let scriptPromises = new Array<Promise<any>>();
 
+/** @ignore */
 export const OriginalPromise = Promise;
 
+/** @ignore */
 export class ProxiedPromise<T> extends Promise<T> {
   constructor(executor: (resolve: (value: T | PromiseLike<T>) => void, reject: (reason?: any) => void) => void) {
     super(executor);
@@ -61,15 +63,18 @@ export class ProxiedPromise<T> extends Promise<T> {
   }
 }
 
+/** @ignore */
 export const asyncTasksAllSettled = async () => {
   await Promise.allSettled(scriptPromises);
   scriptPromises = [];
 };
 
+/** @ignore */
 export const stopMonitorAsyncTasks = () => {
   monitoring = false;
 };
 
+/** @ignore */
 export const resetAsyncTasks = async () => {
   scriptPromises = [];
   monitoring = true;

packages/insomnia-scripting-environment/src/objects/collection.ts

@@ -32,3 +32,4 @@ export { FormParam, Request, RequestBody } from './request';
 export { Response } from './response';
 export { QueryParam, Url, UrlMatchPattern, UrlMatchPatternList } from './urls';
 export { Variable, VariableList } from './variables';
+export { Folder } from './folders';

packages/insomnia-scripting-environment/src/objects/folders.ts

@@ -1,17 +1,45 @@
 import { Environment } from './environments';
 
-// Folder reprensents a request folder in Insomnia.
+/**
+ * Represents a folder with a unique identifier, name, and an associated environment.
+ *
+ * The `Folder` class provides functionality to manage folder-level environment variables
+ * and convert the folder instance into a plain JavaScript object representation.
+ */
 export class Folder {
+  /**
+   * A unique identifier for the folder.
+   */
   id: string;
+  /**
+   * The name of the folder.
+   */
   name: string;
+  /**
+   * Represents the environment associated with the folder.
+   * Provides access to folder-level environment variables.
+   */
   environment: Environment;
 
+  /**
+   * Constructs a new instance of the Folder class.
+   *
+   * @param id - The unique identifier for the folder.
+   * @param name - The name of the folder.
+   * @param environmentObject - An optional object representing the associated folder-level environment.
+   */
   constructor(id: string, name: string, environmentObject: object | undefined) {
     this.id = id;
     this.name = name;
     this.environment = new Environment(`${id}.environment`, environmentObject);
   }
 
+  /**
+   * Converts the folder instance into a plain JavaScript object representation.
+   *
+   * @returns An object containing the folder's `id`, `name`, and `environment` properties.
+   *          The `environment` property is also converted to its object representation.
+   */
   toObject = () => {
     return {
       id: this.id,
@@ -21,10 +49,38 @@ export class Folder {
   };
 }
 
-// ParentFolders reprensents ancestor folders of the active request
+/**
+ * Represents a collection of parent folders and provides methods to interact with them.
+ *
+ * This class is designed to manage a hierarchy of folders, allowing retrieval of folders
+ * by their ID or name, searching for specific values in folder environments, and converting
+ * the folder structure into plain JavaScript objects.
+ *
+ * @example
+ * ```typescript
+ * const folders = new ParentFolders([folder1, folder2]);
+ * const folderById = folders.getById('123');
+ * const folderByName = folders.getByName('MyFolder');
+ * const value = folders.findValue('key');
+ * const folderObjects = folders.toObject();
+ * const environments = folders.getEnvironments();
+ * ```
+ */
 export class ParentFolders {
+  /**
+   * Creates an instance of the class with a list of folders.
+   *
+   * @param folders - An array of `Folder` objects to initialize the instance with, from bottom to top.
+   */
   constructor(private folders: Folder[]) {}
 
+  /**
+   * Retrieves a folder by its ID or name.
+   *
+   * @param idOrName - The ID or name of the folder to retrieve.
+   * @returns The folder object that matches the given ID or name.
+   * @throws {Error} If no folder with the specified ID or name is found.
+   */
   get = (idOrName: string) => {
     const folder = this.folders.find(folder => folder.name === idOrName || folder.id === idOrName);
     if (!folder) {
@@ -33,6 +89,13 @@ export class ParentFolders {
     return folder;
   };
 
+  /**
+   * Retrieves a folder by its unique identifier.
+   *
+   * @param id - The unique identifier of the folder to retrieve.
+   * @returns The folder object with the specified ID.
+   * @throws Error if no folder with the given ID is found.
+   */
   getById = (id: string) => {
     const folder = this.folders.find(folder => folder.id === id);
     if (!folder) {
@@ -41,6 +104,13 @@ export class ParentFolders {
     return folder;
   };
 
+  /**
+   * Retrieves a folder by its name.
+   *
+   * @param folderName - The name of the folder to retrieve.
+   * @returns The folder object with the specified name.
+   * @throws {Error} If no folder with the specified name is found.
+   */
   getByName = (folderName: string) => {
     const folder = this.folders.find(folder => folder.name === folderName);
     if (!folder) {
@@ -49,15 +119,32 @@ export class ParentFolders {
     return folder;
   };
 
+  /**
+   * Searches for a specific value in the environments of the folders, starting from the nearest ancestor folder
+   * and moving towards the top ancestor folder.
+   *
+   * @param valueKey - The key of the value to search for in the folder environments.
+   * @returns The value associated with the specified key if found, otherwise `undefined`.
+   */
   findValue = (valueKey: string) => {
     const targetEnv = [...this.folders].reverse().find(folder => folder.environment.has(valueKey));
     return targetEnv !== undefined ? targetEnv.environment.get(valueKey) : undefined;
   };
 
+  /**
+   * Converts the current folder structure into a plain JavaScript object representation.
+   *
+   * @returns An array of objects representing the folder structure.
+   */
   toObject = () => {
     return this.folders.map(folder => folder.toObject());
   };
 
+  /**
+   * Retrieves the environments associated with the folders.
+   *
+   * @returns An array of environments extracted from the folders.
+   */
   getEnvironments = () => {
     return this.folders.map(folder => folder.environment);
   };

packages/insomnia-scripting-environment/src/objects/index.ts

@@ -11,3 +11,4 @@ export * from './async_objects';
 export * from './test';
 export * from './execution';
 export * from './proxy-configs';
+export * from './folders';