<h1>Flatted Specifications</h1>
<p>This document describes operations performed to produce, or parse, the flatted output.</p>
<h2>stringify(any) => flattedString</h2>
<p>The output is always an <code>Array</code> that contains at index <code>0</code> the given value.</p>
<p>If the value is an <code>Array</code> or an <code>Object</code>, per each property value passed through the callback, return the value as is if it's not an <code>Array</code>, an <code>Object</code>, or a <code>string</code>.</p>
<p>In case it's an <code>Array</code>, an <code>Object</code>, or a <code>string</code>, return the index as <code>string</code>, associated through a <code>Map</code>.</p>
<p>Giving the following example:</p>
<pre><code class="language-js">flatted.stringify('a'); // ["a"]
flatted.stringify(['a']); // [["1"],"a"]
flatted.stringify(['a', 1, 'b']); // [["1",1,"2"],"a","b"]
</code></pre>
<p>There is an <code>input</code> containing <code>[array, "a", "b"]</code>, where the <code>array</code> has indexes <code>"1"</code> and <code>"2"</code> as strings, indexes that point respectively at <code>"a"</code> and <code>"b"</code> within the input <code>[array, "a", "b"]</code>.</p>
<p>The exact same happens for objects.</p>
<pre><code class="language-js">flatted.stringify('a'); // ["a"]
flatted.stringify({a: 'a'}); // [{"a":"1"},"a"]
flatted.stringify({a: 'a', n: 1, b: 'b'}); // [{"a":"1","n":1,"b":"2"},"a","b"]
</code></pre>
<p>Every object, string, or array, encountered during serialization will be stored once as stringified index.</p>
<pre><code class="language-js">// per each property/value of the object/array
if (any == null || !/object|string/.test(typeof any))
return any;
if (!map.has(any)) {
const index = String(arr.length);
arr.push(any);
map.set(any, index);
}
return map.get(any);
</code></pre>
<p>This, performed before going through all properties, grants unique indexes per reference.</p>
<p>The stringified indexes ensure there won't be conflicts with regularly stored numbers.</p>
<h2>parse(flattedString) => any</h2>
<p>Everything that is a <code>string</code> is wrapped as <code>new String</code>, but strings in the array, from index <code>1</code> on, is kept as regular <code>string</code>.</p>
<pre><code class="language-js">const input = JSON.parse('[{"a":"1"},"b"]', Strings).map(strings);
// convert strings primitives into String instances
function Strings(key, value) {
return typeof value === 'string' ? new String(value) : value;
}
// converts String instances into strings primitives
function strings(value) {
return value instanceof String ? String(value) : value;
}
</code></pre>
<p>The <code>input</code> array will have a regular <code>string</code> at index <code>1</code>, but its object at index <code>0</code> will have an <code>instanceof String</code> as <code>.a</code> property.</p>
<p>That is the key to place back values from the rest of the array, so that per each property of the object at index <code>0</code>, if the value is an <code>instanceof</code> String, something not serializable via JSON, it means it can be used to retrieve the position of its value from the <code>input</code> array.</p>
<p>If such <code>value</code> is an object and it hasn't been parsed yet, add it as parsed and go through all its properties/values.</p>
<pre><code class="language-js">// outside any loop ...
const parsed = new Set;
// ... per each property/value ...
if (value instanceof Primitive) {
const tmp = input[parseInt(value)];
if (typeof tmp === 'object' && !parsed.has(tmp)) {
parsed.add(tmp);
output[key] = tmp;
if (typeof tmp === 'object' && tmp != null) {
// perform this same logic per
// each nested property/value ...
}
} else {
output[key] = tmp;
}
} else
output[key] = tmp;
</code></pre>
<p>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.</p>
<p>The usage of a <code>Map</code> and a <code>Set</code> to flag known references/strings as visited/stored makes <strong>flatted</strong> a rock solid, fast, and compact, solution.</p>
|