From fb6e894044ec10f38b99e8920f8a3d05e6a5c331 Mon Sep 17 00:00:00 2001
From: George <hexxa@outlook.com>
Date: Wed, 7 May 2025 15:13:52 +0800
Subject: [PATCH] docs(script-sdk): add docs for console - INS-5475 (#8685)

* docs(script-sdk): add docs for console

* fix: export console
---
 .../src/objects/console.ts                    | 64 ++++++++++++++++++-
 1 file changed, 63 insertions(+), 1 deletion(-)

diff --git a/packages/insomnia-scripting-environment/src/objects/console.ts b/packages/insomnia-scripting-environment/src/objects/console.ts
index 64af491ecc..879001d207 100644
--- a/packages/insomnia-scripting-environment/src/objects/console.ts
+++ b/packages/insomnia-scripting-environment/src/objects/console.ts
@@ -1,15 +1,42 @@
+/**
+ * Represents the various levels of logging that can be used in the application.
+ *
+ * - `debug`: Detailed information typically used for debugging purposes.
+ * - `info`: General informational messages that highlight the progress of the application.
+ * - `log`: Standard logging level for general-purpose messages.
+ * - `warn`: Indicates a potential issue or something that requires attention.
+ * - `error`: Represents error messages for critical issues or failures.
+ */
 type LogLevel = 'debug' | 'info' | 'log' | 'warn' | 'error';
 
+/** @ignore */
 export interface Row {
   value: string;
   name: string;
   timestamp: number;
 }
 
-class Console {
+/**
+ * A custom console implementation that provides logging functionality
+ * with various log levels and the ability to store log entries.
+ *
+ * @remarks
+ * - The `clear` method is currently not supported and will throw an error if called.
+ *
+ * @example
+ * ```javascript
+ * console.log('This is a log message');
+ * console.warn('This is a warning');
+ * console.error('This is an error');
+ * console.debug({ key: 'value' });
+ * console.info('Informational message');
+ * ```
+ */
+export class Console {
   rows: Row[] = [];
 
   // TODO: support replacing substitution
+  /** @ignore */
   printLog = (rows: Row[], level: LogLevel, ...values: any) => {
     try {
       const content = values
@@ -34,43 +61,78 @@ class Console {
     }
   };
 
+  /**
+   * Logs the provided values to the console with a log level of 'log'.
+   *
+   * @param values - The values to be logged. Accepts any number of arguments of any type.
+   */
   log = (...values: any[]) => {
     this.printLog(this.rows, 'log', ...values);
   };
 
+  /**
+   * Logs the provided values to the console with a log level of 'warn'.
+   *
+   * @param values - The values to be logged. Accepts any number of arguments of any type.
+   */
   warn = (...values: any[]) => {
     this.printLog(this.rows, 'warn', ...values);
   };
 
+  /**
+   * Logs the provided values to the console with a log level of 'debug'.
+   *
+   * @param values - The values to be logged. Accepts any number of arguments of any type.
+   */
   debug = (...values: any[]) => {
     this.printLog(this.rows, 'debug', ...values);
   };
 
+  /**
+   * Logs the provided values to the console with a log level of 'info'.
+   *
+   * @param values - The values to be logged. Accepts any number of arguments of any type.
+   */
   info = (...values: any[]) => {
     this.printLog(this.rows, 'info', ...values);
   };
 
+  /**
+   * Logs the provided values to the console with a log level of 'error'.
+   *
+   * @param values - The values to be logged. Accepts any number of arguments of any type.
+   */
   error = (...values: any[]) => {
     this.printLog(this.rows, 'error', ...values);
   };
 
+
+  /**
+   * Clears the console output for the specified log level.
+   * This method is currently not supported.
+   */
   clear = (_level: LogLevel, _message?: any, ..._optionalParams: any[]) => {
     throw Error('currently "clear" is not supported for the timeline');
   };
 
+  /** @ignore */
   dumpLogs = () => {
     return this.rows.map(row => JSON.stringify(row) + '\n').join('\n');
   };
 
+  /** @ignore */
   dumpLogsAsArray = () => {
     return this.rows.map(row => JSON.stringify(row) + '\n');
   };
 }
 
+/** @ignore */
 let builtInConsole = new Console();
+/** @ignore */
 export function getExistingConsole() {
   return builtInConsole;
 }
+/** @ignore */
 export function getNewConsole() {
   builtInConsole = new Console();
   return builtInConsole;