[p5.js 2.0 RFC Proposal]: New third party library authoring API

[limzykenneth]

Increasing access

Addon libraries have always been an important part of the p5.js ecosystem, expanding its capabilities with community contributed features that solve problems that p5.js itself may not necessarily address. Providing a flexible and easy to use interface to author addon libraries will further this effort.

Which types of changes would be made?

• Breaking change (Add-on libraries or sketches will work differently even if their code stays the same.)
• Systemic change (Many features or contributor workflows will be affected.)
• Overdue change (Modifications will be made that have been desirable for a long time.)
• Unsure (The community can help to determine the type of change.)

Most appropriate sub-area of p5.js?

• Accessibility
• Color
• Core/Environment/Rendering
• Data
• DOM
• Events
• Image
• IO
• Math
• Typography
• Utilities
• WebGL
• Build process
• Unit testing
• Internationalization
• Friendly errors
• Other (specify if possible)

What's the problem?

Currently to author an addon library to work with p5.js, the library author will often need to attach methods directly to p5.prototype which by itself is not a bad idea but addon libraries often need to do more than that.

While async/await setup() proposed in #6767 provides a potentially new way of handling async functions, current libraries that need to hook into preload() require the use of internal functions.

The lifecycle hooks feature of the current addon library API is also not entire consistent with room for improvement. Finally with a new syntax, there is room for even more customizability, combined with #7014, one can even add or overwrite renderers available to p5.js.

What's the solution?

Existing libraries should have a level of compatibility or require minimal updates to work with p5.js 2.0. This means if existing libraries rely on attaching methods to p5.prototype it will likely still work.

A new method of authoring libraries will be introduced that is more ergonomic. This will be through a factory function that exposes reasonable interfaces for completing the following tasks as necessary:

• Attaching methods and properties to prototype
• Lifecycle hooks
• Extending internal functionalities (eg. adding a new renderer)

As reference, Day.js provide plugin interface in the following way:

export default (option, dayjsClass, dayjsFactory) => {
  // extend dayjs()
  // e.g. add dayjs().isSameOrBefore()
  dayjsClass.prototype.isSameOrBefore = function(arguments) {}

  // extend dayjs
  // e.g. add dayjs.utc()
  dayjsFactory.utc = arguments => {}

  // overriding existing API
  // e.g. extend dayjs().format()
  const oldFormat = dayjsClass.prototype.format
  dayjsClass.prototype.format = function(arguments) {
    // original format result
    const result = oldFormat.bind(this)(arguments)
    // return modified result
  }
}

And is used with:

dayjs.extend(myPlugin);

While jQuery provides the following interface:

$.fn.greenify = function() {
  this.css('color', 'green');
};

$('a').greenify();

fn above is just an alias to prototype which in essense makes jQuery's plugin system identical to what p5.js does.

p5.js plugins have some properties that are not present in the Day.js or jQuery use case. With Day.js, plugins are expected to be explicitly provided through dayjs.extend() while p5.js addons should have the expectations of being available immediately upon inclusion/load. jQuery plugin don't need to content with lifecycle hooks or other non-class instance related features. A p5.js addon should also have the flexibility of being imported as a ES module or included through a script tag, ie. there should be a ES module version and a UMD version ideally.

The proposed interface that a p5.js 2.0 plugin can have is as the following:

(function(p5){
  p5.registerAddon((p5, fn, lifecycles) => {
    // `fn` being the prototype
    fn.myMethod = function(){
      // Perform some tasks
    };

    // Instead of requiring register preload,
    // async/await is preferred instead.
    fn.loadMyData = async function(){
      // Load some data asynchronously
    };

    lifecycles.presetup = function(){
      // Run actions before `setup()` runs
    };

    lifecycles.postdraw = function(){
      // Run actions after `draw()` runs
    };
  });
})(p5);

Pros (updated based on community comments)

• User friendly and flexible API to extend p5.js through addon libraries
• Unified interface for authoring libraries and working on internal modules, if you are a library author, you will also know how to work on p5.js internals

Cons (updated based on community comments)

• There is some risk of breaking existing libraries, we will try to test with many existing libraries and update libraries authors where necessary.

Proposal status

Under review