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));
     },

pyscript.core/types/config.d.ts

@@ -1,4 +1,7 @@
+/** @type {any} The PyScript configuration parsed from the JSON or TOML object*. May be any of the return types of JSON.parse() ( {number | string | boolean | null | object | Array} */
 declare let parsed: any;
-export let plugins: any;
-export let error: any;
+/** @type {Promise<any> | undefined} A Promise wrapping any plugins which should be loaded. */
+export let plugins: Promise<any> | undefined;
+/** @type {SyntaxError | undefined} The error thrown when parsing the PyScript config, if any.*/
+export let error: SyntaxError | undefined;
 export { parsed as config };

pyscript.core/types/exceptions.d.ts

@@ -1,4 +1,11 @@
-export function _createAlertBanner(message: any, level: any, messageType?: string, logMessage?: boolean): void;
+/**
+ * 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: string, level: string, messageType?: string, logMessage?: any): void;
 export namespace ErrorCode {
     let GENERIC: string;
     let CONFLICTING_CODE: string;
@@ -15,14 +22,50 @@ export namespace ErrorCode {
     let FETCH_SERVER_ERROR: string;
     let FETCH_UNAVAILABLE_ERROR: string;
 }
+/**
+ * Keys of the ErrorCode object
+ * @typedef {keyof ErrorCode} ErrorCodes
+ * */
 export class UserError extends Error {
-    constructor(errorCode: any, message?: string, messageType?: string);
-    errorCode: any;
+    /**
+     * @param {ErrorCodes} errorCode
+     * @param {string} message
+     * @param {string} messageType
+     * */
+    constructor(errorCode: ErrorCodes, message?: string, messageType?: string);
+    errorCode: "GENERIC" | "CONFLICTING_CODE" | "BAD_CONFIG" | "MICROPIP_INSTALL_ERROR" | "BAD_PLUGIN_FILE_EXTENSION" | "NO_DEFAULT_EXPORT" | "TOP_LEVEL_AWAIT" | "FETCH_ERROR" | "FETCH_NAME_ERROR" | "FETCH_UNAUTHORIZED_ERROR" | "FETCH_FORBIDDEN_ERROR" | "FETCH_NOT_FOUND_ERROR" | "FETCH_SERVER_ERROR" | "FETCH_UNAVAILABLE_ERROR";
     messageType: string;
 }
 export class FetchError extends UserError {
-    constructor(errorCode: any, message: any);
+    /**
+     * @param {ErrorCodes} errorCode
+     * @param {string} message
+     * */
+    constructor(errorCode: ErrorCodes, message: string);
 }
 export class InstallError extends UserError {
-    constructor(errorCode: any, message: any);
+    /**
+     * @param {ErrorCodes} errorCode
+     * @param {string} message
+     * */
+    constructor(errorCode: ErrorCodes, message: string);
 }
+/**
+ * Keys of the ErrorCode object
+ */
+export type ErrorCodes = keyof {
+    GENERIC: string;
+    CONFLICTING_CODE: string;
+    BAD_CONFIG: string;
+    MICROPIP_INSTALL_ERROR: string;
+    BAD_PLUGIN_FILE_EXTENSION: string;
+    NO_DEFAULT_EXPORT: string;
+    TOP_LEVEL_AWAIT: string;
+    FETCH_ERROR: string;
+    FETCH_NAME_ERROR: string;
+    FETCH_UNAUTHORIZED_ERROR: string;
+    FETCH_FORBIDDEN_ERROR: string;
+    FETCH_NOT_FOUND_ERROR: string;
+    FETCH_SERVER_ERROR: string;
+    FETCH_UNAVAILABLE_ERROR: string;
+};

pyscript.core/types/plugins/error.d.ts

@@ -1 +1,5 @@
-export function notify(message: any): void;
+/**
+ * Add a banner to the top of the page, notifying the user of an error
+ * @param {string} message
+ */
+export function notify(message: string): void;

pyscript.core/types/sync.d.ts

@@ -1,4 +1,8 @@
 declare namespace _default {
-    function sleep(seconds: any): Promise<any>;
+    /**
+     * '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.
+     */
+    function sleep(seconds: number): Promise<any>;
 }
 export default _default;