# pretty-format

> Stringify any JavaScript value.

* Supports all built-in JavaScript types
  * primitive types: `Boolean`, `null`, `Number`, `String`, `Symbol`,
    `undefined`
  * other non-collection types: `Date`, `Error`, `Function`, `RegExp`
  * collection types:
    * `arguments`, `Array`, `ArrayBuffer`, `DataView`, `Float32Array`,
      `Float64Array`, `Int8Array`, `Int16Array`, `Int32Array`, `Uint8Array`,
      `Uint8ClampedArray`, `Uint16Array`, `Uint32Array`,
    * `Map`, `Set`, `WeakMap`, `WeakSet`
    * `Object`
* [Blazingly fast](https://gist.github.com/thejameskyle/2b04ffe4941aafa8f970de077843a8fd)
  * similar performance to `JSON.stringify` in v8
  * significantly faster than `util.format` in Node.js
* Serialize application-specific data types with built-in or user-defined
  plugins

## Installation

```sh
$ yarn add pretty-format
```

## Usage

```js
const prettyFormat = require('pretty-format'); // CommonJS
```

```js
import prettyFormat from 'pretty-format'; // ES2015 modules
```

```js
const val = {object: {}};
val.circularReference = val;
val[Symbol('foo')] = 'foo';
val.map = new Map([['prop', 'value']]);
val.array = [-0, Infinity, NaN];

console.log(prettyFormat(val));
/*
Object {
  "array": Array [
    -0,
    Infinity,
    NaN,
  ],
  "circularReference": [Circular],
  "map": Map {
    "prop" => "value",
  },
  "object": Object {},
  Symbol(foo): "foo",
}
*/
```

## Usage with options

```js
function onClick() {}

console.log(prettyFormat(onClick));
/*
[Function onClick]
*/

const options = {
  printFunctionName: false,
};
console.log(prettyFormat(onClick, options));
/*
[Function]
*/
```

| key                 | type      | default    | description                                             |
| :------------------ | :-------- | :--------- | :------------------------------------------------------ |
| `callToJSON`        | `boolean` | `true`     | call `toJSON` method (if it exists) on objects          |
| `escapeRegex`       | `boolean` | `false`    | escape special characters in regular expressions        |
| `highlight`         | `boolean` | `false`    | highlight syntax with colors in terminal (some plugins) |
| `indent`            | `number`  | `2`        | spaces in each level of indentation                     |
| `maxDepth`          | `number`  | `Infinity` | levels to print in arrays, objects, elements, and so on |
| `min`               | `boolean` | `false`    | minimize added space: no indentation nor line breaks    |
| `plugins`           | `array`   | `[]`       | plugins to serialize application-specific data types    |
| `printFunctionName` | `boolean` | `true`     | include or omit the name of a function                  |
| `theme`             | `object`  |            | colors to highlight syntax in terminal                  |

Property values of `theme` are from
[ansi-styles colors](https://github.com/chalk/ansi-styles#colors)

```js
const DEFAULT_THEME = {
  comment: 'gray',
  content: 'reset',
  prop: 'yellow',
  tag: 'cyan',
  value: 'green',
};
```

## Usage with plugins

The `pretty-format` package provides some built-in plugins, including:

* `ReactElement` for elements from `react`
* `ReactTestComponent` for test objects from `react-test-renderer`

```js
// CommonJS
const prettyFormat = require('pretty-format');
const ReactElement = prettyFormat.plugins.ReactElement;
const ReactTestComponent = prettyFormat.plugins.ReactTestComponent;

const React = require('react');
const renderer = require('react-test-renderer');
```

```js
// ES2015 modules and destructuring assignment
import prettyFormat from 'pretty-format';
const {ReactElement, ReactTestComponent} = prettyFormat.plugins;

import React from 'react';
import renderer from 'react-test-renderer';
```

```js
const onClick = () => {};
const element = React.createElement('button', {onClick}, 'Hello World');

const formatted1 = prettyFormat(element, {
  plugins: [ReactElement],
  printFunctionName: false,
});
const formatted2 = prettyFormat(renderer.create(element).toJSON(), {
  plugins: [ReactTestComponent],
  printFunctionName: false,
});
/*
<button
  onClick=[Function]
>
  Hello World
</button>
*/
```

## Usage in Jest

For snapshot tests, Jest uses `pretty-format` with options that include some of
its built-in plugins. For this purpose, plugins are also known as **snapshot
serializers**.

To serialize application-specific data types, you can add modules to
`devDependencies` of a project, and then:

In an **individual** test file, you can add a module as follows. It precedes any
modules from Jest configuration.

```js
import serializer from 'my-serializer-module';
expect.addSnapshotSerializer(serializer);

// tests which have `expect(value).toMatchSnapshot()` assertions
```

For **all** test files, you can specify modules in Jest configuration. They
precede built-in plugins for React, HTML, and Immutable.js data types. For
example, in a `package.json` file:

```json
{
  "jest": {
    "snapshotSerializers": ["my-serializer-module"]
  }
}
```

## Writing plugins

A plugin is a JavaScript object.

If `options` has a `plugins` array: for the first plugin whose `test(val)`
method returns a truthy value, then `prettyFormat(val, options)` returns the
result from either:

* `serialize(val, …)` method of the **improved** interface (available in
  **version 21** or later)
* `print(val, …)` method of the **original** interface (if plugin does not have
  `serialize` method)

### test

Write `test` so it can receive `val` argument of any type. To serialize
**objects** which have certain properties, then a guarded expression like
`val != null && …` or more concise `val && …` prevents the following errors:

* `TypeError: Cannot read property 'whatever' of null`
* `TypeError: Cannot read property 'whatever' of undefined`

For example, `test` method of built-in `ReactElement` plugin:

```js
const elementSymbol = Symbol.for('react.element');
const test = val => val && val.$$typeof === elementSymbol;
```

Pay attention to efficiency in `test` because `pretty-format` calls it often.

### serialize

The **improved** interface is available in **version 21** or later.

Write `serialize` to return a string, given the arguments:

* `val` which “passed the test”
* unchanging `config` object: derived from `options`
* current `indentation` string: concatenate to `indent` from `config`
* current `depth` number: compare to `maxDepth` from `config`
* current `refs` array: find circular references in objects
* `printer` callback function: serialize children

### config

| key                 | type      | description                                             |
| :------------------ | :-------- | :------------------------------------------------------ |
| `callToJSON`        | `boolean` | call `toJSON` method (if it exists) on objects          |
| `colors`            | `Object`  | escape codes for colors to highlight syntax             |
| `escapeRegex`       | `boolean` | escape special characters in regular expressions        |
| `indent`            | `string`  | spaces in each level of indentation                     |
| `maxDepth`          | `number`  | levels to print in arrays, objects, elements, and so on |
| `min`               | `boolean` | minimize added space: no indentation nor line breaks    |
| `plugins`           | `array`   | plugins to serialize application-specific data types    |
| `printFunctionName` | `boolean` | include or omit the name of a function                  |
| `spacingInner`      | `strong`  | spacing to separate items in a list                     |
| `spacingOuter`      | `strong`  | spacing to enclose a list of items                      |

Each property of `colors` in `config` corresponds to a property of `theme` in
`options`:

* the key is the same (for example, `tag`)
* the value in `colors` is a object with `open` and `close` properties whose
  values are escape codes from
  [ansi-styles](https://github.com/chalk/ansi-styles) for the color value in
  `theme` (for example, `'cyan'`)

Some properties in `config` are derived from `min` in `options`:

* `spacingInner` and `spacingOuter` are **newline** if `min` is `false`
* `spacingInner` is **space** and `spacingOuter` is **empty string** if `min` is
  `true`

### Example of serialize and test

This plugin is a pattern you can apply to serialize composite data types. Of
course, `pretty-format` does not need a plugin to serialize arrays :)

```js
// We reused more code when we factored out a function for child items
// that is independent of depth, name, and enclosing punctuation (see below).
const SEPARATOR = ',';
function serializeItems(items, config, indentation, depth, refs, printer) {
  if (items.length === 0) {
    return '';
  }
  const indentationItems = indentation + config.indent;
  return (
    config.spacingOuter +
    items
      .map(
        item =>
          indentationItems +
          printer(item, config, indentationItems, depth, refs), // callback
      )
      .join(SEPARATOR + config.spacingInner) +
    (config.min ? '' : SEPARATOR) + // following the last item
    config.spacingOuter +
    indentation
  );
}

const plugin = {
  test(val) {
    return Array.isArray(val);
  },
  serialize(array, config, indentation, depth, refs, printer) {
    const name = array.constructor.name;
    return ++depth > config.maxDepth
      ? '[' + name + ']'
      : (config.min ? '' : name + ' ') +
          '[' +
          serializeItems(array, config, indentation, depth, refs, printer) +
          ']';
  },
};
```

```js
const val = {
  filter: 'completed',
  items: [
    {
      text: 'Write test',
      completed: true,
    },
    {
      text: 'Write serialize',
      completed: true,
    },
  ],
};
```

```js
console.log(
  prettyFormat(val, {
    plugins: [plugin],
  }),
);
/*
Object {
  "filter": "completed",
  "items": Array [
    Object {
      "completed": true,
      "text": "Write test",
    },
    Object {
      "completed": true,
      "text": "Write serialize",
    },
  ],
}
*/
```

```js
console.log(
  prettyFormat(val, {
    indent: 4,
    plugins: [plugin],
  }),
);
/*
Object {
    "filter": "completed",
    "items": Array [
        Object {
            "completed": true,
            "text": "Write test",
        },
        Object {
            "completed": true,
            "text": "Write serialize",
        },
    ],
}
*/
```

```js
console.log(
  prettyFormat(val, {
    maxDepth: 1,
    plugins: [plugin],
  }),
);
/*
Object {
  "filter": "completed",
  "items": [Array],
}
*/
```

```js
console.log(
  prettyFormat(val, {
    min: true,
    plugins: [plugin],
  }),
);
/*
{"filter": "completed", "items": [{"completed": true, "text": "Write test"}, {"completed": true, "text": "Write serialize"}]}
*/
```

### print

The **original** interface is adequate for plugins:

* that **do not** depend on options other than `highlight` or `min`
* that **do not** depend on `depth` or `refs` in recursive traversal, and
* if values either
  * do **not** require indentation, or
  * do **not** occur as children of JavaScript data structures (for example,
    array)

Write `print` to return a string, given the arguments:

* `val` which “passed the test”
* current `printer(valChild)` callback function: serialize children
* current `indenter(lines)` callback function: indent lines at the next level
* unchanging `config` object: derived from `options`
* unchanging `colors` object: derived from `options`

The 3 properties of `config` are `min` in `options` and:

* `spacing` and `edgeSpacing` are **newline** if `min` is `false`
* `spacing` is **space** and `edgeSpacing` is **empty string** if `min` is
  `true`

Each property of `colors` corresponds to a property of `theme` in `options`:

* the key is the same (for example, `tag`)
* the value in `colors` is a object with `open` and `close` properties whose
  values are escape codes from
  [ansi-styles](https://github.com/chalk/ansi-styles) for the color value in
  `theme` (for example, `'cyan'`)

### Example of print and test

This plugin prints functions with the **number of named arguments** excluding
rest argument.

```js
const plugin = {
  print(val) {
    return `[Function ${val.name || 'anonymous'} ${val.length}]`;
  },
  test(val) {
    return typeof val === 'function';
  },
};
```

```js
const val = {
  onClick(event) {},
  render() {},
};

prettyFormat(val, {
  plugins: [plugin],
});
/*
Object {
  "onClick": [Function onClick 1],
  "render": [Function render 0],
}
*/

prettyFormat(val);
/*
Object {
  "onClick": [Function onClick],
  "render": [Function render],
}
*/
```

This plugin **ignores** the `printFunctionName` option. That limitation of the
original `print` interface is a reason to use the improved `serialize`
interface, described above.

```js
prettyFormat(val, {
  plugins: [pluginOld],
  printFunctionName: false,
});
/*
Object {
  "onClick": [Function onClick 1],
  "render": [Function render 0],
}
*/

prettyFormat(val, {
  printFunctionName: false,
});
/*
Object {
  "onClick": [Function],
  "render": [Function],
}
*/
```