Gecko [ c.stage.kornherr.net ]

Name	Size	Permission	Date
README.html	4.73 KB	-rw-r--r--	2022-11-01 14:36
README.txt	3.29 KB	-rw-r--r--	2022-11-01 14:36
SPECS.html	4.48 KB	-rw-r--r--	2022-11-01 14:36
SPECS.txt	3.36 KB	-rw-r--r--	2022-11-01 14:36
changelog.Debian.gz	1.12 KB	-rw-r--r--	2022-11-01 14:36
copyright	1.83 KB	-rw-r--r--	2022-11-01 14:34

Rename

<h1>Flatted Specifications</h1>
This document describes operations performed to produce, or parse, the flatted output.
<h2>stringify(any) =&gt; flattedString</h2>
The output is always an <code>Array</code> that contains at index <code>0</code> the given value.
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>.
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>.
Giving the following example:
<pre><code class="language-js">flatted.stringify('a'); // [&quot;a&quot;]
flatted.stringify(['a']); // [[&quot;1&quot;],&quot;a&quot;]
flatted.stringify(['a', 1, 'b']); // [[&quot;1&quot;,1,&quot;2&quot;],&quot;a&quot;,&quot;b&quot;]
</code></pre>
There is an <code>input</code> containing <code>[array, &quot;a&quot;, &quot;b&quot;]</code>, where the <code>array</code> has indexes <code>&quot;1&quot;</code> and <code>&quot;2&quot;</code> as strings, indexes that point respectively at <code>&quot;a&quot;</code> and <code>&quot;b&quot;</code> within the input <code>[array, &quot;a&quot;, &quot;b&quot;]</code>.
The exact same happens for objects.
<pre><code class="language-js">flatted.stringify('a'); // [&quot;a&quot;]
flatted.stringify({a: 'a'}); // [{&quot;a&quot;:&quot;1&quot;},&quot;a&quot;]
flatted.stringify({a: 'a', n: 1, b: 'b'}); // [{&quot;a&quot;:&quot;1&quot;,&quot;n&quot;:1,&quot;b&quot;:&quot;2&quot;},&quot;a&quot;,&quot;b&quot;]
</code></pre>
Every object, string, or array, encountered during serialization will be stored once as stringified index.
<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>
This, performed before going through all properties, grants unique indexes per reference.
The stringified indexes ensure there won't be conflicts with regularly stored numbers.
<h2>parse(flattedString) =&gt; any</h2>
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>.
<pre><code class="language-js">const input = JSON.parse('[{&quot;a&quot;:&quot;1&quot;},&quot;b&quot;]', 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>
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.
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.
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.
<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' &amp;&amp; !parsed.has(tmp)) {
 parsed.add(tmp);
 output[key] = tmp;
 if (typeof tmp === 'object' &amp;&amp; tmp != null) {
 // perform this same logic per
 // each nested property/value ...
 }
 } else {
 output[key] = tmp;
 }
} else
 output[key] = tmp;
</code></pre>
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.
The usage of a <code>Map</code> and a <code>Set</code> to flag known references/strings as visited/stored makes flatted a rock solid, fast, and compact, solution.