feat: improve dd output and add edge plugin

Author: thetutlage

.github/workflows/test.yml

@@ -20,25 +20,25 @@ jobs:
         node-version: [20.10.0, 21.x]
 
     steps:
-    - name: Checkout code
-      uses: actions/checkout@v3
+      - name: Checkout code
+        uses: actions/checkout@v3
 
-    - name: Setup Node.js
-      uses: actions/setup-node@v3
-      with:
-        node-version: ${{ matrix.node-version }}
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
 
-    - name: Install pnpm
-      if: ${{ inputs.install-pnpm }}
-      uses: pnpm/action-setup@v2
-      with:
-        version: 8.6.3
+      - name: Install pnpm
+        if: ${{ inputs.install-pnpm }}
+        uses: pnpm/action-setup@v2
+        with:
+          version: 8.6.3
 
-    - name: Install dependencies
-      run: npm install
+      - name: Install dependencies
+        run: npm install
 
-    - name: Run tests
-      run: npm test
+      - name: Run tests
+        run: npm test
 
   test_windows:
     if: ${{ !inputs.disable-windows }}
@@ -48,22 +48,22 @@ jobs:
         node-version: [20.10.0, 21.x]
 
     steps:
-    - name: Checkout code
-      uses: actions/checkout@v3
+      - name: Checkout code
+        uses: actions/checkout@v3
 
-    - name: Setup Node.js
-      uses: actions/setup-node@v3
-      with:
-        node-version: ${{ matrix.node-version }}
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
 
-    - name: Install pnpm
-      if: ${{ inputs.install-pnpm }}
-      uses: pnpm/action-setup@v2
-      with:
-        version: 8.6.3
+      - name: Install pnpm
+        if: ${{ inputs.install-pnpm }}
+        uses: pnpm/action-setup@v2
+        with:
+          version: 8.6.3
 
-    - name: Install dependencies
-      run: npm install
+      - name: Install dependencies
+        run: npm install
 
-    - name: Run tests
-      run: npm test
+      - name: Run tests
+        run: npm test

index.ts

@@ -38,6 +38,11 @@ export const errors: typeof encryptionErrors &
  * Youch terminal
  */
 export async function prettyPrintError(error: any) {
+  if (error && typeof error === 'object' && error.code === 'E_DUMP_DIE_EXCEPTION') {
+    console.error(error)
+    return
+  }
+
   // @ts-expect-error
   const { default: youchTerminal } = await import('youch-terminal')
   const { default: Youch } = await import('youch')

modules/dumper/dumper.ts

@@ -7,6 +7,7 @@
  * file that was distributed with this source code.
  */
 
+import { styleText } from 'node:util'
 import { dump as consoleDump } from '@poppinss/dumper/console'
 import type { HTMLDumpConfig } from '@poppinss/dumper/html/types'
 import type { ConsoleDumpConfig } from '@poppinss/dumper/console/types'
@@ -43,12 +44,16 @@ const DUMP_TITLE_STYLES = `
   border-top-right-radius: 0;
 }`
 
+const IDE = process.env.ADONIS_IDE ?? process.env.EDITOR ?? ''
+
 /**
- * Dumper exposes the API to dump or die/dump values via your
+ * Dumper exposes the API to dump or die/dump values in your
  * AdonisJS application. An singleton instance of the Dumper
  * is shared as a service and may use it follows.
  *
  * ```ts
+ * const dumper = container.make('dumper')
+ *
  * dumper.configureHtmlOutput({
  *   // parser + html formatter config
  * })
@@ -62,20 +67,62 @@ const DUMP_TITLE_STYLES = `
  *
  * // Returns style and script tags that must be
  * // injeted to the head of the HTML document
+ *
  * const head = dumper.getHeadElements()
  * ```
  */
 export class Dumper {
   #app: Application<any>
+
+  /**
+   * Configuration for the HTML formatter
+   */
   #htmlConfig: HTMLDumpConfig = {}
+
+  /**
+   * Configuration for the Console formatter
+   */
   #consoleConfig: ConsoleDumpConfig = {
     collapse: ['DateTime', 'Date'],
   }
 
+  /**
+   * A collections of known editors to create URLs to open
+   * them
+   */
+  #editors: Record<string, string> = {
+    textmate: 'txmt://open?url=file://%f&line=%l',
+    macvim: 'mvim://open?url=file://%f&line=%l',
+    emacs: 'emacs://open?url=file://%f&line=%l',
+    sublime: 'subl://open?url=file://%f&line=%l',
+    phpstorm: 'phpstorm://open?file=%f&line=%l',
+    atom: 'atom://core/open/file?filename=%f&line=%l',
+    vscode: 'vscode://file/%f:%l',
+  }
+
   constructor(app: Application<any>) {
     this.#app = app
   }
 
+  /**
+   * Returns the link to open the file using dd inside one
+   * of the known code editors
+   */
+  #getEditorLink(source?: {
+    location: string
+    line: number
+  }): { href: string; text: string } | undefined {
+    const editorURL = this.#editors[IDE] || IDE
+    if (!editorURL || !source) {
+      return
+    }
+
+    return {
+      href: editorURL.replace('%f', source.location).replace('%l', String(source.line)),
+      text: `${this.#app.relativePath(source.location)}:${source.line}`,
+    }
+  }
+
   /**
    * Configure the HTML formatter output
    */
@@ -98,7 +145,7 @@ export class Dumper {
    */
   getHeadElements(cspNonce?: string): string {
     return (
-      '<style id="dumper-styles">' +
+      `<style id="dumper-styles">` +
       createStyleSheet() +
       DUMP_TITLE_STYLES +
       '</style>' +
@@ -111,28 +158,78 @@ export class Dumper {
   /**
    * Dump value to HTML ouput
    */
-  dumpToHtml(value: unknown, cspNonce?: string) {
-    return dump(value, { cspNonce, ...this.#htmlConfig })
+  dumpToHtml(
+    value: unknown,
+    options: {
+      cspNonce?: string
+      title?: string
+      source?: {
+        location: string
+        line: number
+      }
+    } = {}
+  ) {
+    const link = this.#getEditorLink(options.source) ?? null
+    const title = options.title || 'DUMP'
+
+    return (
+      '<div class="adonisjs-dump-header">' +
+      `<span class="adonisjs-dump-header-title">${title}</span>` +
+      (link ? `<a href="${link.href}" class="adonisjs-dump-header-source">${link.text}</a>` : '') +
+      '</div>' +
+      dump(value, { cspNonce: options.cspNonce, ...this.#htmlConfig })
+    )
   }
 
   /**
    * Dump value to ANSI output
    */
-  dumpToAnsi(value: unknown) {
-    return consoleDump(value, this.#consoleConfig)
+  dumpToAnsi(
+    value: unknown,
+    options: {
+      title?: string
+      source?: {
+        location: string
+        line: number
+      }
+    } = {}
+  ) {
+    const columns = process.stdout.columns
+
+    /**
+     * Link to the source file
+     */
+    const link = `${this.#getEditorLink(options.source)?.text ?? ''} `
+
+    /**
+     * Dump title
+     */
+    const title = ` ${options.title || 'DUMP'}`
+
+    /**
+     * Whitespace between the title and the link to align them
+     * on each side of x axis
+     */
+    const whiteSpace = new Array(columns - link.length - title.length - 4).join(' ')
+
+    /**
+     * Styled heading with background color and bold text
+     */
+    const heading = styleText('bgRed', styleText('bold', `${title}${whiteSpace}${link}`))
+
+    return `${heading}\n${consoleDump(value, this.#consoleConfig)}`
   }
 
   /**
    * Dump values and die. The formatter will be picked
    * based upon where your app is running.
    *
-   * - In CLI commands, the ANSI output will be printed
-   *   to the console.
    * - During an HTTP request, the HTML output will be
    *   sent to the server.
+   * - Otherwise the value will be logged in the console
    */
   dd(value: unknown, traceSourceIndex: number = 1) {
-    const error = new E_DUMP_DIE_EXCEPTION(value, this, this.#app)
+    const error = new E_DUMP_DIE_EXCEPTION(value, this)
     error.setTraceSourceIndex(traceSourceIndex)
     throw error
   }