Adding JS Types (#1749)

Added types for some exceptions, config objects, and sleep()

pyscript.core/src/config.js

@@ -46,7 +46,15 @@ const syntaxError = (type, url, { message }) => {
 };
 
 // find the shared config for all py-script elements
-let config, plugins, parsed, error, type;
+let config, type;
+
+/** @type {Promise<any> | undefined} A Promise wrapping any plugins which should be loaded. */
+let plugins;
+/** @type {any} The PyScript configuration parsed from the JSON or TOML object*. May be any of the return types of JSON.parse() or toml-j0.4's parse() ( {number | string | boolean | null | object | Array} ) */
+let parsed;
+/** @type {SyntaxError | undefined} The error thrown when parsing the PyScript config, if any.*/
+let error;
+
 let pyConfig = $("py-config");
 if (pyConfig) {
     config = pyConfig.getAttribute("src") || pyConfig.textContent;

pyscript.core/src/exceptions.js

@@ -23,7 +23,17 @@ export const ErrorCode = {
     FETCH_UNAVAILABLE_ERROR: "PY0503",
 };
 
+/**
+ * Keys of the ErrorCode object
+ * @typedef {keyof ErrorCode} ErrorCodes
+ * */
+
 export class UserError extends Error {
+    /**
+     * @param {ErrorCodes} errorCode
+     * @param {string} message
+     * @param {string} messageType
+     * */
     constructor(errorCode, message = "", messageType = "text") {
         super(`(${errorCode}): ${message}`);
         this.errorCode = errorCode;
@@ -33,6 +43,10 @@ export class UserError extends Error {
 }
 
 export class FetchError extends UserError {
+    /**
+     * @param {ErrorCodes} errorCode
+     * @param {string} message
+     * */
     constructor(errorCode, message) {
         super(errorCode, message);
         this.name = "FetchError";
@@ -40,12 +54,23 @@ export class FetchError extends UserError {
 }
 
 export class InstallError extends UserError {
+    /**
+     * @param {ErrorCodes} errorCode
+     * @param {string} message
+     * */
     constructor(errorCode, message) {
         super(errorCode, message);
         this.name = "InstallError";
     }
 }
 
+/**
+ * Internal function for creating alert banners on the page
+ * @param {string} message The message to be displayed to the user
+ * @param {string} level The alert level of the message. Can be any string; 'error' or 'warning' cause matching messages to be emitted to the console
+ * @param {string} [messageType="text"] If set to "html", the message content will be assigned to the banner's innerHTML directly, instead of its textContent
+ * @param {any} [logMessage=true] An additional flag for whether the message should be sent to the console log.
+ */
 export function _createAlertBanner(
     message,
     level,

pyscript.core/src/plugins/error.js

@@ -24,6 +24,11 @@ hooks.onInterpreterReady.add(function override(pyScript) {
 // Error hook utilities
 
 // Custom function to show notifications
+
+/**
+ * Add a banner to the top of the page, notifying the user of an error
+ * @param {string} message
+ */
 export function notify(message) {
     const div = document.createElement("div");
     div.className = "py-error";

pyscript.core/src/sync.js

@@ -1,4 +1,8 @@
 export default {
+    /**
+     * 'Sleep' for the given number of seconds. Used to implement Python's time.sleep in Worker threads.
+     * @param {number} seconds The number of seconds to sleep.
+     */
     sleep(seconds) {
         return new Promise(($) => setTimeout($, seconds * 1000));
     },