Document and explain the scripts load order function

src/index.ts

@@ -1,5 +1,6 @@
 import { Manager, MCEvent } from '@managed-components/types'
 import * as cheerio from 'cheerio'
+import { postponeScript } from './postponeScript'
 
 type TElement = {
   attributes: { [name: string]: string }
@@ -59,30 +60,22 @@ export const handler = ({ payload, client }: MCEvent) => {
       client.execute(headTagAppender('link', attributes))
     })
 
-    const wait_for: string[] = []
+    const idsOfScriptsToAwait: string[] = []
     scripts.forEach(({ content, attributes }) => {
       if (attributes?.src) {
         if (!attributes?.onload) {
           attributes.onload = ''
         }
         if (!attributes.async || attributes.defer) {
-          const order_id = crypto.randomUUID()
-          attributes['order-id'] = order_id
-          wait_for.push(order_id)
-          attributes.onload += `{document.dispatchEvent(new Event("loaded-${order_id}"))}`
+          const scriptID = crypto.randomUUID()
+          attributes['order-id'] = scriptID
+          idsOfScriptsToAwait.push(scriptID)
+          attributes.onload += `{document.dispatchEvent(new Event("loaded-${scriptID}"))}`
         }
         client.execute(headTagAppender('script', attributes))
       } else if (content) {
-        if (wait_for.length) {
-          content = `{const loaded = ${JSON.stringify(
-            Object.fromEntries(wait_for.map(id => [id, false]))
-          )};
-let called = false;
-const call_if_ready = ()=>{if(!called && Object.values(loaded).every(e=>e)){{${content}}; called = true}};
-${wait_for.map(
-  id =>
-    `document.addEventListener("loaded-${id}", ()=>{loaded["${id}"] = true; call_if_ready()})`
-)}}`
+        if (idsOfScriptsToAwait.length) {
+          content = postponeScript(idsOfScriptsToAwait, content)
         }
         client.execute(content)
       }

src/postponeScript.ts

@@ -0,0 +1,86 @@
+/* If you load an index.html with such a snippet inside:
+
+```
+<script src="/some-third-party.js"></script>
+<script>
+   SomeThirdParty.start()
+</script>
+```
+
+The browser doesn't execute the second script until the first one is
+fully loaded and parsed.
+
+To my best knowledge, this isn't a feature of the DOM, but of the
+browser's HTML parser/scanner.
+
+As we're using DOM API to append scripts to the document after it's
+been parsed, we no longer have this guarantee, so using the above HTML
+snippet in CustomHTML component would result in the second script
+running immediately and resulting in an arror, as the first script
+didn't load yet.
+
+With this function, we're making the given script only execute once
+all the scripts of given IDs have finished loading and running
+(onLoad). The handler in index.ts interates over scripts in each HTML
+snippet and gives all scripts with an `src` a random ID and attaches
+an onload listener that dispatches an event named `loaded-${scriptID}`.
+
+The code that needs to wait for those scripts is then wrapped in
+another code that only runs the original code once it register all the
+events that signal that the necessary scripts have finished running.
+
+so, for a simple `console.log('hello')` script that needs scripts
+"id1" and "id2" to work, we'd get:
+
+```
+{
+  const loaded = { id1: false, id2: false };
+  let called = false;
+
+  const call_if_ready = () => {
+    if (!called && Object.values(loaded).every((e) => e)) {
+      {
+        console.log("hello");
+      }
+      called = true;
+    }
+  };
+
+  document.addEventListener("loaded-id1", () => {
+    loaded["id1"] = true;
+    call_if_ready();
+  });
+  document.addEventListener("loaded-id2", () => {
+    loaded["id2"] = true;
+    call_if_ready();
+  });
+}
+```
+
+
+*/
+
+
+
+
+export function postponeScript(idsOfScriptsToAwait: string[], script_content: string) {
+    return `{const loaded = ${JSON.stringify(
+        Object.fromEntries(idsOfScriptsToAwait.map(id => [id, false]))
+    )};
+          let called = false;
+
+          const call_if_ready = () => {
+               if( !called && Object.values(loaded).every(e => e) ) {
+                   {${script_content}};
+                   called = true
+               }
+          };
+
+          ${idsOfScriptsToAwait.map(
+            id => `document.addEventListener(
+                      "loaded-${id}",
+                      ()=>{ loaded["${id}"] = true;
+                      call_if_ready()
+                   }).join(";")`
+    )}}`;
+}

vitest.config.ts

@@ -0,0 +1,2 @@
+import { defineConfig } from 'vitest/config';
+export default defineConfig({})