docs: update README file and examples

poppinss · Sep 5, 2024 · e0afdcc · e0afdcc
1 parent adc0680
commit e0afdcc
Show file tree

Hide file tree

Showing 5 changed files with 203 additions and 19 deletions.
diff --git a/README.md b/README.md
@@ -4,20 +4,20 @@
 
 Dumper is similar to Node.js [util.inspect](https://nodejs.org/api/util.html#utilinspectobject-options) but it provides more control over the output. You can use Dumper to generate HTML output, CLI output, or use its low-level API to create inspection tokens and render them using a custom formatter.
 
-> [!IMPORTANT]  
-> The package is in beta phase and may see some breaking changes in the API. However, if you are a tinkerer, please play with the package and provide your feedback :)
+> [!IMPORTANT]
+> Dumper is a low-level utility and you may have to write a wrapper around it for the framework of your choice.
 
 ## Installation
 
 Install the package from the npm registry as follows.
 
 ```sh
-npm i @poppinss/dumper@beta
+npm i @poppinss/dumper
 ```
 
 ## HTML formatter
 
-You can dump values to an HTML output using the `dump` helper for the html sub-module. For example:
+You can dump values to HTML output using the `dump` helper from the html sub-module. For example:
 
 ```ts
 import { dump } from '@poppinss/dumper/html'
@@ -31,15 +31,87 @@ const values = {
 }
 
 const html = dump(values)
-// Write HTML in response
 ```
 
-## CLI formatter (not available yet)
+The HTML output contains a `pre` tag and a `script` tag. The `script` tag invokes a JavaScript function (for collapse/expand behavior) that must be present in the `<HEAD>` element of the HTML document.
 
-You can dump values to the terminal using the `dump` helper for the cli sub-module. For example:
+You can grab the JavaScript snippet and the required global styles using the `createStyleSheet` and `createScript` helper methods. Following is a complete example of the same.
 
 ```ts
-import { dump } from '@poppinss/dumper/cli'
+import { dump, createStyleSheet, createScript } from '@poppinss/dumper/html'
+
+const values = {
+  a: 0,
+  b: 'string',
+  c: {
+    nested: 'object',
+  },
+}
+
+const html = dump(values)
+
+const output = `<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width">
+  <style>
+    ${createStyleSheet()}
+  </style>
+  <script>
+    ${createScript()}
+  </script>
+</head>
+<body>
+  ${html}
+</body>
+</html>`
+```
+
+### Options
+
+You may pass all of the [Parser options](#parser-options) alongside the following options as the second argument to the `dump` method.
+
+- `styles`: The styles property is a key-value pair that contains CSS properties to style HTML elements. You can either define custom styles or use one of the pre-existing themes as a reference.
+- `cspNonce`: If your application has CSP enabled, then you must define the [CSP nonce](https://content-security-policy.com/nonce/) for the inline `script` tag output alongside the `pre` tag.
+
+Following is an example of using a pre-existing theme.
+
+```ts
+import { dump, themes } from '@poppinss/dumper/html'
+
+dump(value, {
+  styles: themes.catppuccin,
+})
+```
+
+### Creating custom themes
+
+You can also define your own themes as an object. Make sure to consult one of the [existing themes](https://github.com/poppinss/dumper/blob/1.x/formatters/html/themes.ts) to view all the available tokens.
+
+```ts
+import { dump } from '@poppinss/dumper/html'
+import { HTMLPrinterStyles } from '@poppinss/dumper/html/types'
+
+const myTheme: HTMLPrinterStyles = {
+  pre: 'background-color: #1e1e2e; color: #94e2d5;',
+  boolean: 'color: #cba6f7; font-style: italic;'
+  string: 'color: #a6e3a1;',
+  symbol: 'color: #f9e2af;',
+  // ...rest of the styles
+}
+
+dump(value, {
+  styles: myTheme,
+})
+```
+
+## CLI formatter
+
+You can dump values to the terminal using the `dump` helper from the console sub-module. For example:
+
+```ts
+import { dump } from '@poppinss/dumper/console'
 
 const values = {
   a: 0,
@@ -53,6 +125,41 @@ const ansiOutput = dump(values)
 console.log(ansiOutput)
 ```
 
+### Options
+
+You may pass all of the [Parser options](#parser-options) alongside the following options as the second argument to the `dump` method.
+
+- `styles`: The styles property contains a set of functions for different tokens. Each function receives a string input and must return a styled output string. 
+
+Following is an example of using a pre-existing theme.
+
+```ts
+import { dump, themes } from '@poppinss/dumper/console'
+
+dump(value, {
+  styles: themes.default,
+})
+```
+
+You may create a custom theme as follows. Make sure to consult an [existing theme](https://github.com/poppinss/dumper/blob/1.x/formatters/console/themes.ts) to view all the available tokens.
+
+```ts
+import { styleText } from 'node:util'
+import { dump } from '@poppinss/dumper/console'
+import { ConsolePrinterStyles } from '@poppinss/dumper/console/types'
+
+const myTheme: ConsolePrinterStyles = {
+  number: (value) => styleText('yellow', value),
+  bigInt: (value) => styleText('yellow', styleText('bold', value)),
+  boolean: (value) => styleText('yellow', styleText('italic', value)),
+  // ... styles for rest of the tokens
+}
+
+dump(value, {
+  styles: myTheme,
+})
+```
+
 ## Supported data types
 
 Following is the list of data types supported by Dumper. All other data types will be converted to their String representation by wrapping them inside the `String` function.
@@ -72,7 +179,7 @@ Following is the list of data types supported by Dumper. All other data types wi
 - symbol
 - number
 - boolean
-- bigint
+- BigInt
 - Date
 - RegExp
 - Buffer
@@ -104,12 +211,13 @@ Following is the list of data types supported by Dumper. All other data types wi
 Regardless of the output format, you can use one of the following options to tweak the parsing behaviour.
 
 ```ts
-import { dump } from '@poppinss/dumper/cli'
+import { dump } from '@poppinss/dumper/console'
 
 dump(values, {
   showHidden: false,
   depth: 5,
   inspectObjectPrototype: false,
+  inspectArrayPrototype: false,
   inspectStaticMembers: false,
   maxArrayLength: 100,
   maxStringLength: 1000,
@@ -119,6 +227,65 @@ dump(values, {
 - `showHidden`: When set to true, the non-enumerable properties of an object will be processed. **Default: `false`**.
 - `depth`: The depth at which to stop parsing nested values. The depth is shared among all tree like data structures. For example: Objects,Arrays,Maps and Sets. **Default: `5`**.
 - `inspectObjectPrototype`: Inspect prototype properties of an object. The non-enumerable properties of prototype are included by default. **Default: `false`**.
+- `inspectArrayPrototype`: Inspect prototype properties of an Array. This flag could be helpful for inspect prototype properties of extended arrays.
 - `inspectStaticMembers`: Inspect static members of a class. Even though functions and classes are technically same, this config only applies to functions defined using the `[class]` keyword. **Default: `false`**.
 - `maxArrayLength`: Maximum number of members to process for Arrays, Maps and Sets. **Default: `100`**.
 - `maxStringLength`: Maximum number of characters to display for a string. **Default: `1000`**.
+
+## Using Parser directly
+
+For advanced use-cases you may use the Parser directly and create a custom formatter on top of it. Following is an example of the same. Also, feel free to consult implementation of the existing formatters.
+
+```ts
+import { Parser } from '@poppinss/dumper'
+import { ParserConfig } from '@poppinss/dumper/types'
+
+const config: ParserConfig = {}
+const parser = new Parser(config)
+
+const values = {
+  a: 0,
+  b: 'string',
+  c: {
+    nested: 'object',
+  },
+}
+
+parser.parse(values)
+const tokens = parser.flush()
+
+console.log(tokens)
+```
+
+The `parser.flush` method returns a flat array of [tokens](https://github.com/poppinss/dumper/blob/1.x/src/types.ts#L30) and they must be printed in the same order as they are defined.
+
+The official implementations (shipped with dumper) uses the concept of printers, where we have defined one printer for each token type that is responsible for returning the formatted value.
+
+Following is an oversimplified example of creating custom printers. Once again, feel free to reference implementation of existing [formatters](https://github.com/poppinss/dumper/blob/1.x/formatters/html/printers/formatter.ts) and [printers](https://github.com/poppinss/dumper/blob/1.x/formatters/html/printers/main.ts).
+
+```ts
+const myCustomPrinters: [K in keyof TokensMap]: (
+  token: TokensMap[K],
+) => string = {
+  'object-start': (token) => {
+    return `Object {`
+  },
+  'object-end': (token) => {
+    return `}`
+  },
+  'object-key': (token) => {
+    return token.value
+  },
+  'object-value-start': (token) => {
+    return ': '
+  },
+  'object-value-end': (token) => {
+    return ', '
+  }
+}
+
+const tokens = parser.flush()
+const output = tokens.map((token) => {
+  return myCustomPrinters[token.type](token)
+}).join('')
+```
diff --git a/examples/console.ts b/examples/console.ts
@@ -12,6 +12,6 @@ import { obj } from './values.js'
 
 console.log(
   dump(obj, {
-    styles: themes.dark,
+    styles: themes.default,
   })
 )
diff --git a/examples/html.ts b/examples/html.ts
@@ -7,11 +7,28 @@
  * file that was distributed with this source code.
  */
 
-import { dump, themes } from '../formatters/html/main.js'
+import { createScript, createStyleSheet, dump, themes } from '../formatters/html/main.js'
 import { obj } from './values.js'
 
-console.log(
-  dump(obj, {
-    styles: themes.catppuccin,
-  })
-)
+const html = dump(obj, {
+  styles: themes.catppuccin,
+})
+
+const output = `<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width">
+  <style>
+    ${createStyleSheet()}
+  </style>
+  <script>
+    ${createScript()}
+  </script>
+</head>
+<body>
+  ${html}
+</body>
+</html>`
+
+console.log(output)
diff --git a/formatters/console/formatter.ts b/formatters/console/formatter.ts
@@ -76,7 +76,7 @@ export class ConsoleFormatter {
 
   constructor(config?: ConsoleFormatterConfig, context?: Record<string, any>) {
     this.context = context || {}
-    this.styles = Object.freeze({ ...themes.dark, ...config?.styles })
+    this.styles = Object.freeze({ ...themes.default, ...config?.styles })
   }
 
   /**

diff --git a/formatters/console/themes.ts b/formatters/console/themes.ts
@@ -14,7 +14,7 @@ import type { ConsolePrinterStyles } from './types.js'
  * Default styles to use for pretty printing to ANSI output
  */
 export const themes = {
-  dark: {
+  default: {
     braces: (value) => styleText('yellow', value),
     brackets: (value) => styleText('yellow', value),
     number: (value) => styleText('yellow', value),