--- /dev/null
+# 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],
+}
+*/
+```
projects / dotfiles / .git / blobdiff