Revamp the Friendly Error System (FES) in p5.js 2.0

Overview

For my pr05 grant, I was tasked to revamp the Friendly Error System, so that two main functionalities become compatible with the new p5.js 2.0 architecture:

• Parameter Validation
• Detecting Accidentally Overridden Constants and Variables

For each feature, it’s important that:

1. It’s comprehensive—covers all the use cases that we have in p5.js, including being extensible enough for future additions.
2. It’s efficient—the amount of computation and data load is reduced compared to the previous version.
3. It’s lightweight—whatever external library we leverage on to increase efficiency does not excessively add to the bundle size.
4. And most importantly, it’s accessible and user-friendly—from the user’s perspective, FES will remain informative and encouraging in their creative coding journey.

An example of a friendly error message before and after this project

Parameter Validation

Parameter validation ensures that p5 functions are called with the expected number and types of arguments. If parameter validation fails, a friendly error message is shown.

Current Workflow

Currently, parameter validation works like this:

From each function’s JSDoc comments, information is parsed and stored in parameterData.json .

The object representing the metadata associated with function `createCanvas` in old `parameterData.json`

The file is then used in combination with a parameter validator with its own logic. Every function in p5 right now calls p5._validateParameters(funcName, arguments) in its first line.

Problems with Current Approach

We identified a few issues with this approach:

• The information stored in parameterData.json is excessive, and can be significantly condensed to save space and improve efficiency.
• Custom logic in parameter validator can be optimized.
• It’s not the best practice to include p5._validateParameters(funcName, arguments) in every function, because it’s repetitive and might be forgotten when introducing new features.

Improvements Made

Major improvements were implemented to address the above problems:

• Updated the logic in utils/convert.js , the script responsible for loading JSDoc comments and extracting data required for parameter validation, to achieve an 80% reduction in json file size.

The object representing the metadata associated with function `createCanvas` in new `parameterData.json`

• To make parameter validator more efficient, we decided to leverage on Zod, a TypeScript-first schema validation library with static type inference. The process of building validation schema for functions became modular.

The building blocks for parameter validation with Zod

Piecing parts together to form complete schemas

• We also switched to a decorator pattern for calling parameter validation. This way, we can remove the excessive function calls.

Detecting Accidentally Overridden Constants and Variables

FES aims to notify users via friendly error messages when they have unintentionally overridden constants and variables previously defined. In p5.js 1.0+ versions, the user’s code and p5’s library code were in different scopes. If a user tried to call a p5 function or variable but received an error instead, it indicates an accidental override.

In p5.js 2.0, due to modern bundling process, the user’s code and the library’s code are in the same scope. Now, we have to add a step to extract the user’s code at the beginning. We have also replaced the previous version’s custom logic with detection powered by acorn, a JavaScript parser that generates Abstract Syntax Trees (AST) from the source code.

Retrieving the User’s Code

User’s code fetched by reading the text content of script tags

For the most part, we try to read user’s code by retrieving all the script tags and reading their text content, with the following caveats in mind:

• Some of the script tags point to external library code or resources from CDN domains; they should be omitted.
• We have to account for browser-related errors, such as CORS errors, while retrieving user’s code. If such an error occurs, we would fall back on simpler, less comprehensive methods.

acorn and acorn-walk

An Abstract Syntax Tree for the Euclidean Algorithm

acorn can take in user’s code as input, and generate an Abstract Syntax Tree. acorn-walk is then used to identify specific elements that are of interest, in our case: functions and variables that have been previously defined.

A simplified code snippet utilizing acorn and acorn-walk

When overrides are detected, we print friendly error messages for our users.

Links to Issues / PRs

The above features are now code complete. If you are interested in the technical implementations and related discussions, please refer to the following issues:

• Master Issue for Parameter Validation
• Master Issue for Detecting Accidentally Overridden Constants and Variables

Specifically, the PRs are:

• Standardize all parameter types
• Modify utils/convert.js
• Start developing a new parameter validator using Zod
• Update to parameter validator and add test
• Final changes for parameter validation
• Add a new sketch verifier to p5.js
• Update sketch verifiers to check for redefinitions and print friendly error messages

Limitations & Future Plan

Some limitations of my project include:

• Fetching user’s script for detecting accidental overrides might be problematic and incomplete if we encounter errors in the browser
• In the process of development, I discovered some bugs associated with converting JSDoc comments to parameterData.json . Given the size of the data file, it’s possible that there are still things that need to be tweaked that haven’t been revealed yet.

Besides, the above features, although complete, have not been properly integrated into the p5.js 2.0 ecosystem yet. I will keep working on integration and testing (with an emphasis on testing the features in real-life use cases), and conclude with code cleanup before p5.js 2.0 is set to be released for beta testing (early next year—around January & February).

The Quiet Labor of Care: A Reflection on Maintenance

The successful completion of my grant project means that from the user’s perspective, not much has changed—it might as well have been some simple string manipulation.

In the tech industry, maintenance work is often relegated to the back seat and undeservingly receives bad reputation. The framing of maintenance as tech debt or dirty work, a result of tech companies’ profit-driven imperative, as well as the lack of proper compensation, often discourage engineers from undertaking them.

You might’ve noticed that all the pr05 projects in the first iteration of the grant have maintenance and access in mind—and that is no coincidence. In the world of Processing, maintenance is seen as an act of care and love, both for the longevity of the software and for the community that stays engaged.

A question I want to leave everyone with as I’m wrapping up the project is: how can we individually shift our technical or creative practice to become one that acknowledges and acts in service of maintenance, to one that is more sustainable and resilient in the future?

Acknowledgements

I want to thank my mentors & p5.js 2.0 stewards Kenneth Lim and Dave Pagurek, for providing me with technical support and guidance; p5.js lead Qianqian Ye, for believing in me and making sure that I have everything I need to succeed; pr05 & Processing team members Raphaël de Courville, Tsige Tafesse and Suhyun (Sonia) Choi for organizing the grant and its related programs; my fellow pr05 cohort members Diya Solanki, Dora Do, Nahee Kim and Claudine Chen for a wonderful experience together!