.config/coc/extensions/node_modules/coc-prettier/node_modules/circular-json/README.md

   1 CircularJSON
   2 ============
   3
   4 ![Downloads](https://img.shields.io/npm/dm/circular-json.svg) [![Build Status](https://travis-ci.org/WebReflection/circular-json.svg?branch=master)](https://travis-ci.org/WebReflection/circular-json) [![Coverage Status](https://coveralls.io/repos/github/WebReflection/circular-json/badge.svg?branch=master)](https://coveralls.io/github/WebReflection/circular-json?branch=master) [![donate](https://img.shields.io/badge/$-donate-ff69b4.svg?maxAge=2592000&style=flat)](https://github.com/WebReflection/donate)
   5
   6 Serializes and deserializes otherwise valid JSON objects containing circular references into and from a specialized JSON format.
   7
   8 - - -
   9
  10 ### A Working Solution To A Common Problem
  11 A usage example:
  12
  13 ```JavaScript
  14 var object = {};
  15 object.arr = [
  16   object, object
  17 ];
  18 object.arr.push(object.arr);
  19 object.obj = object;
  20
  21 var serialized = CircularJSON.stringify(object);
  22 // '{"arr":["~","~","~arr"],"obj":"~"}'
  23 // NOTE: CircularJSON DOES NOT parse JS
  24 // it handles receiver and reviver callbacks
  25
  26 var unserialized = CircularJSON.parse(serialized);
  27 // { arr: [ [Circular], [Circular] ],
  28 // obj: [Circular] }
  29
  30 unserialized.obj === unserialized;
  31 unserialized.arr[0] === unserialized;
  32 unserialized.arr.pop() === unserialized.arr;
  33 ```
  34
  35 A quick summary:
  36
  37   * uses `~` as a special prefix symbol to denote which parent the reference belongs to (i.e. `~root~child1~child2`)
  38   * reasonably fast in both serialization and deserialization
  39   * compact serialization for easier and slimmer transportation across environments
  40   * [tested and covered](test/circular-json.js) over nasty structures too
  41   * compatible with all JavaScript engines
  42
  43 Node Installation & Usage
  44 ============
  45
  46 ```bash
  47 npm install --save circular-json
  48 ```
  49
  50 ```javascript
  51 'use strict';
  52
  53 var
  54   CircularJSON = require('circular-json'),
  55   obj = { foo: 'bar' },
  56   str
  57 ;
  58
  59 obj.self = obj;
  60 str = CircularJSON.stringify(obj);
  61 ```
  62
  63 There are no dependencies.
  64
  65 Browser Installation & Usage
  66 ================
  67
  68 * Global: <build/circular-json.js>
  69 * AMD: <build/circular-json.amd.js>
  70 * CommonJS: <build/circular-json.node.js>
  71
  72 (generated via [gitstrap](https://github.com/WebReflection/gitstrap))
  73
  74 ```html
  75 <script src="build/circular-json.js"></script>
  76 ```
  77
  78 ```javascript
  79 'use strict';
  80
  81 var CircularJSON = window.CircularJSON
  82   , obj = { foo: 'bar' }
  83   , str
  84   ;
  85
  86 obj.self = obj;
  87 str = CircularJSON.stringify(obj);
  88 ```
  89
  90 NOTE: Platforms without native JSON (i.e. MSIE <= 8) requires `json3.js` or similar.
  91
  92 It is also *a bad idea* to `CircularJSON.parse(JSON.stringify(object))` because of those manipulation used in `CircularJSON.stringify()` able to make parsing safe and secure.
  93
  94 As summary: `CircularJSON.parse(CircularJSON.stringify(object))` is the way to go, same is for `JSON.parse(JSON.stringify(object))`.
  95
  96 API
  97 ===
  98
  99 It's the same as native JSON, except the fourth parameter `placeholder`, which circular references to be replaced with `"[Circular]"` (i.e. for logging).
 100
 101 * CircularJSON.stringify(object, replacer, spacer, placeholder)
 102 * CircularJSON.parse(string, reviver)
 103
 104 Bear in mind `JSON.parse(CircularJSON.stringify(object))` will work but not produce the expected output.
 105
 106 Similar Libraries
 107 =======
 108
 109 ### Why Not the [@izs](https://twitter.com/izs) One
 110 The module [json-stringify-safe](https://github.com/isaacs/json-stringify-safe) seems to be for `console.log()`  but it's completely pointless for `JSON.parse()`, being latter one unable to retrieve back the initial structure. Here an example:
 111
 112 ```JavaScript
 113 // a logged object with circular references
 114 {
 115   "circularRef": "[Circular]",
 116   "list": [
 117     "[Circular]",
 118     "[Circular]"
 119   ]
 120 }
 121 // what do we do with above output ?
 122 ```
 123
 124 Just type this in your `node` console: `var o = {}; o.a = o; console.log(o);`. The output will be `{ a: [Circular] }` ... good, but that ain't really solving the problem.
 125
 126 However, if that's all you need, the function used to create that kind of output is probably faster than `CircularJSON` and surely fits in less lines of code.
 127
 128
 129 ### Why Not {{put random name}} Solution
 130 So here the thing: circular references can be wrong but, if there is a need for them, any attempt to ignore them or remove them can be considered just a failure.
 131
 132 Not because the method is bad or it's not working, simply because the circular info, the one we needed and used in the first place, is lost!
 133
 134 In this case, `CircularJSON` does even more than just solve circular and recursions: it maps all same objects so that less memory is used as well on deserialization as less bandwidth too!
 135 It's able to redefine those references back later on so the way we store is the way we retrieve and in a reasonably performant way, also trusting the snappy and native `JSON` methods to iterate.