Merge pull request #32 from pyscript/ready-event

Added type:ready event for scripts and workers

Author: WebReflection

core.js.map

@@ -10,6 +10,7 @@
  * [How Events Work](#how-events-work) - how `<button py-click="...">` works
  * [XWorker](#xworker) - how `XWorker` class and its `xworker` reference work
  * [Custom Scripts](#custom-scripts) - how *custom types* can be defined and used to enrich any core feature
+ * [Ready Event](#ready-event) - how to listen to the `type:ready` event
  * [Examples](#examples) - some *polyscript* based live example
  * [Interpreter Features](#interpreter-features) - current state of supported interpreters
 
@@ -490,6 +491,35 @@ wrap.io.stderr = (message) => {
 };
 ```
 
+## Ready Event
+
+Whenever a *non-custom* script is going to run some code, or whenever *any worker* is going to run its own code, a `type:ready` event is dispatched through the element that is currently executing the code.
+
+The [CustomEvent](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) dispatched in either cases contains a `target` which refers to the element that is running code and a `detail.worker` boolean value that is `true` if such event came from a worker instead of the main thread.
+
+The `worker` detail is essential to know if an `xworker` property is attached so that it's also easy to pollute its `sync` proxy utility.
+
+### Custom Types on Main
+
+The reason this event is not automatically dispatched on custom type elements or scripts is that these will have their own `onInterpreterReady` hook to eventually do more before desiring, or needing, to notify the "*readiness*" of such custom element and, in case of wanting the event to happen, this is the tiny boilerplate needed to simulate otherwise non-custom type events:
+
+```js
+// note: type === 'py' or the defined type
+element.dispatchEvent(
+  new CustomEvent(`${type}:ready`, {
+    bubbles: true,
+    detail: { worker: false },
+  })
+);
+```
+
+In the worker case, because the orchestration is inevitably coupled with this module, the custom type will be dispatched out of the blue to help extensions on op of this module to work best.
+
+### Explicit Worker: No Event
+
+Please note that if a worker is created explicitly, there won't be any element, script, or generic tag/node associated to it, so that no event will be triggered as there is no target for it. However, it's always possible to attach `sync` utilities to such explicit worker, so this should never be a real-world concern or blocker.
+
+
 ## Examples
 
   * [multi-pompom](./examples/multi-pompom/) - draw 4 pompom via turtle out of 4 different workers

docs/README.md

@@ -4,7 +4,7 @@ import $xworker from './worker/class.js';
 import workerURL from './worker/url.js';
 import { getRuntime, getRuntimeID } from './loader.js';
 import { registry } from './interpreters.js';
-import { all, resolve, defineProperty, nodeInfo } from './utils.js';
+import { all, dispatch, resolve, defineProperty, nodeInfo } from './utils.js';
 import { getText } from './fetch-utils.js';
 
 const getRoot = (script) => {
@@ -44,10 +44,11 @@ const handled = new WeakMap();
 export const interpreters = new Map();
 
 const execute = async (script, source, XWorker, isAsync) => {
-    const module = registry.get(script.type);
+    const { type } = script;
+    const module = registry.get(type);
     /* c8 ignore start */
     if (module.experimental)
-        console.warn(`The ${script.type} interpreter is experimental`);
+        console.warn(`The ${type} interpreter is experimental`);
     const [interpreter, content] = await all([
         handled.get(script).interpreter,
         source,
@@ -60,6 +61,7 @@ const execute = async (script, source, XWorker, isAsync) => {
             get: () => script,
         });
         module.registerJSModule(interpreter, 'polyscript', { XWorker });
+        dispatch(script, type, false, CustomEvent);
         return module[isAsync ? 'runAsync' : 'run'](interpreter, content);
     } finally {
         delete document.currentScript;

docs/core.js

@@ -16,10 +16,20 @@ const nodeInfo = (node, type) => ({
     id: node.id || (node.id = `${type}-w${id++}`),
     tag: node.tagName
 });
+
+const dispatch = (target, type, worker, CustomEvent) => {
+    if (target) target.dispatchEvent(
+        new CustomEvent(`${type}:ready`, {
+            bubbles: true,
+            detail: { worker },
+        })
+    );
+};
 /* c8 ignore stop */
 
 export {
     dedent,
+    dispatch,
     isArray,
     assign,
     create,

docs/core.js.map

@@ -7,7 +7,7 @@
 import * as JSON from '@ungap/structured-clone/json';
 import coincident from 'coincident/window';
 
-import { assign, create } from '../utils.js';
+import { assign, create, dispatch } from '../utils.js';
 import { registry } from '../interpreters.js';
 import { getRuntime, getRuntimeID } from '../loader.js';
 
@@ -98,15 +98,16 @@ add('message', ({ data: { options, config: baseURL, code, hooks } }) => {
                 }
             }
 
+            const { CustomEvent, document } = window;
+            const element = document.getElementById(id);
+
             let target = '';
 
             // set the `xworker` global reference once
             details.registerJSModule(interpreter, 'polyscript', {
                 xworker,
                 get target() {
                     if (!target) {
-                        const { document } = window;
-                        const element = document.getElementById(id);
                         if (tag === 'SCRIPT') {
                             element.after(assign(
                                 document.createElement(`script-${custom || type}`),
@@ -129,6 +130,8 @@ add('message', ({ data: { options, config: baseURL, code, hooks } }) => {
             // allows transforming arguments with sync
             transform = details.transform.bind(details, interpreter);
 
+            dispatch(element, custom || type, true, CustomEvent);
+
             // run either sync or async code in the worker
             await details[name](interpreter, code);
             return interpreter;

esm/script-handler.js

@@ -1,6 +1,6 @@
 {
     "name": "polyscript",
-    "version": "0.3.3",
+    "version": "0.3.4",
     "description": "PyScript single core to rule them all",
     "main": "./cjs/index.js",
     "types": "./types/polyscript/esm/index.d.ts",
@@ -70,6 +70,6 @@
         "coincident": "^0.11.5"
     },
     "worker": {
-        "blob": "sha256-eIkd1K+zNPVHulEdSNGv85KED9dkOS9PcyhlMEJFJG8="
+        "blob": "sha256-DIHUuInfI4tdn+DpgcTAEaslvvsvwq51ZU18P3a6bnk="
     }
 }

esm/utils.js

@@ -0,0 +1,52 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <script>
+      const listener = ({ target, detail }) => {
+        console.log(detail.worker, target);
+        if (detail.worker) {
+          target.xworker.sync.test = () => {
+            console.log(target.type, 1, 2, 3);
+          };
+        }
+      };
+      addEventListener("micropython:ready", listener);
+      addEventListener("mpy:ready", listener);
+    </script>
+    <script type="module">
+      import { define } from "/core.js";
+      define("mpy", {
+        interpreter: 'micropython',
+        onInterpreterReady({ run, type }, element) {
+          element.dispatchEvent(
+            new CustomEvent(`${type}:ready`, {
+              bubbles: true,
+              detail: { worker: false },
+            })
+          );
+          run(element.textContent);
+        }
+      });
+    </script>
+</head>
+<body>
+  <script type="micropython">
+    print("main")
+  </script>
+  <script type="micropython" worker>
+    from polyscript import xworker
+    print("worker")
+    xworker.sync.test()
+  </script>
+  <script type="mpy">
+    print("mpy-main")
+  </script>
+  <script type="mpy" worker>
+    from polyscript import xworker
+    print("mpy-worker")
+    xworker.sync.test()
+  </script>
+</body>
+</html>