0.5 sync (#48)

Author: tedpatrick

tech-preview/pyscript.core/README.md

@@ -4,9 +4,13 @@
 
 ---
 
+## Documentation
+
+Please read [the documentation page](./docs/README.md) to know all the user-facing details around this module.
+
 ## Development
 
-The working folder (source code of truth) is the `./esm` one, while the `./cjs` is populated as dual module and to test (but it's 1:1 code, no trnaspilation except for imports/exports).
+The working folder (source code of truth) is the `./esm` one, while the `./cjs` is populated as dual module and to test (but it's 1:1 code, no transpilation except for imports/exports).
 
 ```sh
 # install all dependencies needed by core
@@ -19,7 +23,7 @@ This project requires some automatic artifact creation to:
 
     * create a _Worker_ as a _Blob_ based on the same code used by this repo
     * create automatically the list of runtimes available via the module
-    * create the `core.js` file used by most integration tests
+    * create the `core.js` or the `pyscript.js` file used by most integration tests
     * create a sha256 version of the Blob content for CSP cases
 
 Accordingly, to build latest project:
@@ -31,3 +35,11 @@ npm run build
 # optionally spin a server with CORS, COOP, and COEP enabled
 npm run server
 ```
+
+If **no minification** is desired or helpful while debugging potential issues, please use `NO_MIN=1` in front of the _build_ step:
+
+```sh
+NO_MIN=1 npm run build
+
+npm run server
+```

tech-preview/pyscript.core/cjs/custom.js

@@ -48,7 +48,7 @@ const handleCustomType = (node) => {
                     version,
                     config,
                     env,
-                    onRuntimeReady,
+                    onInterpreterReady,
                 } = options;
                 const name = getRuntimeID(runtime, version);
                 const id = env || `${name}${config ? `|${config}` : ""}`;
@@ -69,7 +69,7 @@ const handleCustomType = (node) => {
                         onAfterRunAsync,
                     } = options;
 
-                    const hooks = new Hook(options);
+                    const hooks = new Hook(interpreter, options);
 
                     const XWorker = function XWorker(...args) {
                         return Worker.apply(hooks, args);
@@ -123,7 +123,7 @@ const handleCustomType = (node) => {
 
                     resolve(resolved);
 
-                    onRuntimeReady?.(resolved, node);
+                    onInterpreterReady?.(resolved, node);
                 });
             }
         }
@@ -137,17 +137,17 @@ exports.handleCustomType = handleCustomType;
 const registry = new Map();
 
 /**
- * @typedef {Object} PluginOptions custom configuration
+ * @typedef {Object} CustomOptions custom configuration
  * @prop {'pyodide' | 'micropython' | 'wasmoon' | 'ruby-wasm-wasi'} interpreter the interpreter to use
  * @prop {string} [version] the optional interpreter version to use
  * @prop {string} [config] the optional config to use within such interpreter
- * @prop {(environment: object, node: Element) => void} [onRuntimeReady] the callback that will be invoked once
+ * @prop {(environment: object, node: Element) => void} [onInterpreterReady] the callback that will be invoked once
  */
 
 /**
  * Allows custom types and components on the page to receive interpreters to execute any code
  * @param {string} type the unique `<script type="...">` identifier
- * @param {PluginOptions} options the custom type configuration
+ * @param {CustomOptions} options the custom type configuration
  */
 const define = (type, options) => {
     if (defaultRegistry.has(type) || registry.has(type))

tech-preview/pyscript.core/cjs/custom/pyscript.js

@@ -115,10 +115,10 @@ document.head.appendChild(document.createElement("style")).textContent = `
         onAfterRunAsync(pyodide, element) {
             bootstrapNodeAndPlugins(pyodide, element, after, "onAfterRunAsync");
         },
-        async onRuntimeReady(pyodide, element) {
+        async onInterpreterReady(pyodide, element) {
             // allows plugins to do whatever they want with the element
             // before regular stuff happens in here
-            for (const callback of hooks.onRuntimeReady)
+            for (const callback of hooks.onInterpreterReady)
                 callback(pyodide, element);
             if (isScript(element)) {
                 const {
@@ -179,7 +179,7 @@ const hooks = {
     /** @type {Set<function>} */
     onAfterRunAsync: new Set(),
     /** @type {Set<function>} */
-    onRuntimeReady: new Set(),
+    onInterpreterReady: new Set(),
 
     /** @type {Set<string>} */
     codeBeforeRunWorker: new Set(),

tech-preview/pyscript.core/cjs/interpreter/_python.js

@@ -10,12 +10,14 @@ const runAsync = (interpreter, code) =>
     interpreter.runPythonAsync(clean(code));
 exports.runAsync = runAsync;
 
-const setGlobal = (interpreter, name, value) =>
+const setGlobal = (interpreter, name, value) => {
     interpreter.globals.set(name, value);
+};
 exports.setGlobal = setGlobal;
 
-const deleteGlobal = (interpreter, name) =>
+const deleteGlobal = (interpreter, name) => {
     interpreter.globals.delete(name);
+};
 exports.deleteGlobal = deleteGlobal;
 
 const writeFile = ({ FS }, path, buffer) =>

tech-preview/pyscript.core/cjs/interpreter/micropython.js

@@ -1,32 +1,30 @@
 'use strict';
 const { fetchPaths, stdio } = require("./_utils.js");
-const {
-    run,
-    runAsync,
-    setGlobal,
-    deleteGlobal,
-    writeFile
-} = require("./_python.js");
+const { run, setGlobal, deleteGlobal, writeFile } = require("./_python.js");
 
 const type = "micropython";
 
 // REQUIRES INTEGRATION TEST
 /* c8 ignore start */
 module.exports = {
     type,
-    module: (version = "1.20.0-253") =>
+    module: (version = "1.20.0-268") =>
         `https://cdn.jsdelivr.net/npm/@micropython/micropython-webassembly-pyscript@${version}/micropython.mjs`,
     async engine({ loadMicroPython }, config, url) {
         const { stderr, stdout, get } = stdio();
         url = url.replace(/\.m?js$/, ".wasm");
-        const runtime = await get(loadMicroPython({ stderr, stdout, url }));
-        if (config.fetch) await fetchPaths(this, runtime, config.fetch);
-        return runtime;
+        const interpreter = await get(loadMicroPython({ stderr, stdout, url }));
+        if (config.fetch) await fetchPaths(this, interpreter, config.fetch);
+        return interpreter;
     },
     setGlobal,
     deleteGlobal,
     run,
-    runAsync,
+    // TODO: MicroPython doesn't have a Pyodide like top-level await,
+    //       this method should still not throw errors once invoked
+    async runAsync(...args) {
+        return this.run(...args);
+    },
     writeFile,
 };
 /* c8 ignore stop */

tech-preview/pyscript.core/cjs/worker/class.js

@@ -23,19 +23,24 @@ module.exports = (...args) =>
     function XWorker(url, options) {
         const worker = xworker();
         const { postMessage } = worker;
+        const isHook = this instanceof Hook;
+
         if (args.length) {
             const [type, version] = args;
             options = assign({}, options || { type, version });
             if (!options.type) options.type = type;
         }
+
         if (options?.config) options.config = absoluteURL(options.config);
+
         const bootstrap = fetch(url)
             .then(getText)
             .then((code) => {
-                const hooks = this instanceof Hook ? this : void 0;
+                const hooks = isHook ? this.stringHooks : void 0;
                 postMessage.call(worker, { options, code, hooks });
             });
-        return defineProperties(worker, {
+
+        defineProperties(worker, {
             postMessage: {
                 value: (data, ...rest) =>
                     bootstrap.then(() =>
@@ -46,4 +51,8 @@ module.exports = (...args) =>
                 value: coincident(worker, JSON).proxy,
             },
         });
+
+        if (isHook) this.onWorkerReady?.(this.interpreter, worker);
+
+        return worker;
     };

tech-preview/pyscript.core/cjs/worker/hooks.js

@@ -9,8 +9,17 @@ const workerHooks = [
 ];
 
 class Hook {
-    constructor(fields) {
-        for (const [key, value] of workerHooks) this[key] = fields[value]?.();
+    constructor(interpreter, options) {
+        this.interpreter = interpreter;
+        this.onWorkerReady = options.onWorkerReady;
+        for (const [key, value] of workerHooks) this[key] = options[value]?.();
+    }
+    get stringHooks() {
+        const hooks = {};
+        for (const [key] of workerHooks) {
+            if (this[key]) hooks[key] = this[key];
+        }
+        return hooks;
     }
 }
 exports.Hook = Hook