.config/coc/extensions/node_modules/coc-prettier/node_modules/flatted/SPECS.md

   1 # Flatted Specifications
   2
   3 This document describes operations performed to produce, or parse, the flatted output.
   4
   5 ## stringify(any) => flattedString
   6
   7 The output is always an `Array` that contains at index `0` the given value.
   8
   9 If the value is an `Array` or an `Object`, per each property value passed through the callback, return the value as is if it's not an `Array`, an `Object`, or a `string`.
  10
  11 In case it's an `Array`, an `Object`, or a `string`, return the index as `string`, associated through a `Map`.
  12
  13 Giving the following example:
  14
  15 ```js
  16 flatted.stringify('a');                     // ["a"]
  17 flatted.stringify(['a']);                   // [["1"],"a"]
  18 flatted.stringify(['a', 1, 'b']);           // [["1",1,"2"],"a","b"]
  19 ```
  20
  21 There is an `input` containing `[array, "a", "b"]`, where the `array` has indexes `"1"` and `"2"` as strings, indexes that point respectively at `"a"` and `"b"` within the input `[array, "a", "b"]`.
  22
  23 The exact same happens for objects.
  24
  25 ```js
  26 flatted.stringify('a');                     // ["a"]
  27 flatted.stringify({a: 'a'});                // [{"a":"1"},"a"]
  28 flatted.stringify({a: 'a', n: 1, b: 'b'});  // [{"a":"1","n":1,"b":"2"},"a","b"]
  29 ```
  30
  31 Every object, string, or array, encountered during serialization will be stored once as stringified index.
  32
  33 ```js
  34 // per each property/value of the object/array
  35 if (any == null || !/object|string/.test(typeof any))
  36   return any;
  37 if (!map.has(any)) {
  38   const index = String(arr.length);
  39   arr.push(any);
  40   map.set(any, index);
  41 }
  42 return map.get(any);
  43 ```
  44
  45 This, performed before going through all properties, grants unique indexes per reference.
  46
  47 The stringified indexes ensure there won't be conflicts with regularly stored numbers.
  48
  49 ## parse(flattedString) => any
  50
  51 Everything that is a `string` is wrapped as `new String`, but strings in the array, from index `1` on, is kept as regular `string`.
  52
  53 ```js
  54 const input = JSON.parse('[{"a":"1"},"b"]', Strings).map(strings);
  55 // convert strings primitives into String instances
  56 function Strings(key, value) {
  57   return typeof value === 'string' ? new String(value) : value;
  58 }
  59 // converts String instances into strings primitives
  60 function strings(value) {
  61   return value instanceof String ? String(value) : value;
  62 }
  63 ```
  64
  65 The `input` array will have a regular `string` at index `1`, but its object at index `0` will have an `instanceof String` as `.a` property.
  66
  67 That is the key to place back values from the rest of the array, so that per each property of the object at index `0`, if the value is an `instanceof` String, something not serializable via JSON, it means it can be used to retrieve the position of its value from the `input` array.
  68
  69 If such `value` is an object and it hasn't been parsed yet, add it as parsed and go through all its properties/values.
  70
  71 ```js
  72 // outside any loop ...
  73 const parsed = new Set;
  74
  75 // ... per each property/value ...
  76 if (value instanceof Primitive) {
  77   const tmp = input[parseInt(value)];
  78   if (typeof tmp === 'object' && !parsed.has(tmp)) {
  79     parsed.add(tmp);
  80     output[key] = tmp;
  81     if (typeof tmp === 'object' && tmp != null) {
  82       // perform this same logic per
  83       // each nested property/value ...
  84     }
  85   } else {
  86     output[key] = tmp;
  87   }
  88 } else
  89   output[key] = tmp;
  90 ```
  91
  92 As summary, the whole logic is based on polluting the de-serialization with a kind of variable that is unexpected, hence secure to use as directive to retrieve an index with a value.
  93
  94 The usage of a `Map` and a `Set` to flag known references/strings as visited/stored makes **flatted** a rock solid, fast, and compact, solution.