source: trip-planner-front/node_modules/flatted/SPECS.md

Last change on this file was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 3.5 KB
Line 
1# Flatted Specifications
2
3This document describes operations performed to produce, or parse, the flatted output.
4
5## stringify(any) => flattedString
6
7The output is always an `Array` that contains at index `0` the given value.
8
9If 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
11In case it's an `Array`, an `Object`, or a `string`, return the index as `string`, associated through a `Map`.
12
13Giving the following example:
14
15```js
16flatted.stringify('a'); // ["a"]
17flatted.stringify(['a']); // [["1"],"a"]
18flatted.stringify(['a', 1, 'b']); // [["1",1,"2"],"a","b"]
19```
20
21There 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
23The exact same happens for objects.
24
25```js
26flatted.stringify('a'); // ["a"]
27flatted.stringify({a: 'a'}); // [{"a":"1"},"a"]
28flatted.stringify({a: 'a', n: 1, b: 'b'}); // [{"a":"1","n":1,"b":"2"},"a","b"]
29```
30
31Every 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
35if (any == null || !/object|string/.test(typeof any))
36 return any;
37if (!map.has(any)) {
38 const index = String(arr.length);
39 arr.push(any);
40 map.set(any, index);
41}
42return map.get(any);
43```
44
45This, performed before going through all properties, grants unique indexes per reference.
46
47The stringified indexes ensure there won't be conflicts with regularly stored numbers.
48
49## parse(flattedString) => any
50
51Everything 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
54const input = JSON.parse('[{"a":"1"},"b"]', Strings).map(strings);
55// convert strings primitives into String instances
56function Strings(key, value) {
57 return typeof value === 'string' ? new String(value) : value;
58}
59// converts String instances into strings primitives
60function strings(value) {
61 return value instanceof String ? String(value) : value;
62}
63```
64
65The `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
67That 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
69If 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 ...
73const parsed = new Set;
74
75// ... per each property/value ...
76if (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
92As 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
94The usage of a `Map` and a `Set` to flag known references/strings as visited/stored makes **flatted** a rock solid, fast, and compact, solution.
Note: See TracBrowser for help on using the repository browser.