Move non-standard API out of the Canvas class

[LinusU]

I would like to move all of the non-standard APIs out from the Canvas class, and make the Canvas class follow the specification to the letter.

The benefit of this would be to be able to provide a browser.js file with a small shim for out specific APIs, which we could also make in the browser. Then you would be able to write truly isomorphic code that works both on Node.js and in the browser, which I think would be awesome 🙌

It would also allow us to ship some better image loading apis out of the box. The onload and onerror properties seems quite dated.

I'm thinking something like this, but are very open to suggestions:

createCanvas([width[, height[, format]]]) => Canvas

Creates and return a Canvas with the specified width and height. format is for pdf generation which would not work in the browser.

loadImage(path[, options]) => Promise<Image>

Creates and returns a Promise of an Image. This would be a shorthand for creating an Image manually, setting the src and hooking into the load and error events.

The options object could be used for setting the dataMode, which would be a no-op in the browser.

imageFromBuffer(buffer) => Image

Create an image from a buffer. This should create the image immediately since all the data is available and no IO needs to be performed.

registerFont(fontPath, fontSettings) => Void

Register a new font. This could potentially work in the browser by constructing a stylesheet that we append @font-faces to. Good thing we followed the @font-face definition as closely as we could 👍

createPngStream(canvas[, options]) => ReadableStream
createJpegStream(canvas[, options]) => ReadableStream

Not exactly sure how, or even if, these should work in the browser...

getBuffer(canvas) => Buffer
getPngBuffer(canvas[, options]) => Buffer
getJpegBuffer(canvas[, options]) => Buffer

Not exactly sure how, or even if, these should work in the browser...

Apart from these functions, we should probably export the Image class and maybe the Canvas class as well. Although the Canvas class is actually called HTMLCanvasElement in the browser and there is no way to call new on it.

As always, any input is appreciated 🙌

[zbjornson]

createCanvas([width[, height[, format]]]) => Canvas

This doesn't seem like much of a change; the usage change is simply s/new Canvas/createCanvas, right? What about making the parameters optional, since you cannot pass params to document.createElement, and allowing them to be set as properties instead?

var canvas = new Canvas(); // or createCanvas
canvas.width = canvas.height = 100;
canvas.format = "pdf"; // nonstandard

That cuts the number of lines that are different between node-canvas and browser canvas to 1.

(FWIW, I am partial to keeping the Canvas constructor, making the params optional, and not introducing createCanvas. There's a standard Image constructor: document.createElement("img") is the same as new Image([w, h]). Having new Canvas([w, h]) seems to be perfectly parallel to that.)

get*Buffer and create[Png|Jpeg]Stream

node-canvas doesn't have a toBlob method, but that is probably the closest thing to these APIs. Could consider standardizing on that syntax instead, i.e.:

• Replace toBuffer([format][callback]) with toBlob(callback[, mimeType[, qualityArgument]]). Drop the sync version.
• (no change) Ship with support for PNG and JPEG, as Firefox and Chrome do. Also support "raw" I suppose. (I haven't been keeping track of these PRs, but maybe PDF and SVG also if they're working now?)
• Maybe add a modular interface that lets users register converters for other MIME types, e.g. webp. Follow the new Canvas.registerFont API.
• (Edited) The returned "Blob" could still be a Buffer instance, but with the a size getter that is an alias to buffer.length for compatibility. That would provide a nearly complete Blob API on the returned object, with the exception of the the 3rd argument to blob.slice.

The onload and onerror properties seems quite dated.

(But they are standard...)

loadImage(path[, options]) => Promise<Image>
imageFromBuffer(buffer) => Image

There's some movement on ImageData conversion extensions, although it looks like not much change since 2015: http://wicg.github.io/img-conversion/ and https://github.com/WICG/img-conversion. Notably Promise<ImageData> ImageData.create(Blob) is similar to what you've proposed. We could slightly modify it to Promise<ImageData> ImageData.create(Blob|Buffer|path:String[, options]). Not sure how wise it would be to implement these as they add currently nonstandard APIs to a standard class, which is counter to the whole goal! :) -- In any case, +1 vote for supporting a callback in addition to returning a Promise.

[LinusU]

createCanvas([width[, height[, format]]]) => Canvas

This doesn't seem like much of a change; the usage change is simply s/new Canvas/createCanvas, right? What about making the parameters optional, since you cannot pass params to document.createElement, and allowing them to be set as properties instead?

The [width] was meant to indicate that all properties are indeed optional 👌

var canvas = new Canvas(); // or createCanvas
canvas.width = canvas.height = 100;
canvas.format = "pdf"; // nonstandard

That cuts the number of lines that are different between node-canvas and browser canvas to 1.

(FWIW, I am partial to keeping the Canvas constructor, making the params optional, and not introducing createCanvas. There's a standard Image constructor: document.createElement("img") is the same as new Image([w, h]). Having new Canvas([w, h]) seems to be perfectly parallel to that.)

My idea with createCanvas is to cut the different lines down to 0.

The plan is to have something like this in the package.json:

  "main": "index.js",
  "browser": "browser.js"

and have browser.js contain something like this:

exports.createCanvas = function (width, height) {
  var canvas = document.createElement('canvas')
  if (width !== undefined) canvas.width = width
  if (height !== undefined) canvas.height = height
  return canvas
}

That way people can write code that will run in the browser with tools like browserify.

I don't like keeping new Canvas() since it doesn't work in the browser.

I want to keep new Image() since that does indeed work in the browser.

get*Buffer and create[Png|Jpeg]Stream

node-canvas doesn't have a toBlob method, but that is probably the closest thing to these APIs. Could consider standardizing on that syntax instead, i.e.:

• Replace toBuffer([format][callback]) with toBlob(callback[, mimeType[, qualityArgument]]). Drop the sync version.
• (no change) Ship with support for PNG and JPEG, as Firefox and Chrome do. Also support "raw" I suppose. (I haven't been keeping track of these PRs, but maybe PDF and SVG also if they're working now?)
• Maybe add a modular interface that lets users register converters for other MIME types, e.g. webp. Follow the new Canvas.registerFont API.
• (Edited) The returned "Blob" could still be a Buffer instance, but with the a size getter that is an alias to buffer.length for compatibility. That would provide a nearly complete Blob API on the returned object, with the exception of the the 3rd argument to blob.slice.

Maybe we can have both toBuffer and toBlob, that both works across the browser and Node.js. Buffer works out of the box with browserify and I don't know what people prefer to be working with when writing isomorphic code...

The onload and onerror properties seems quite dated.

(But they are standard...)

Yes, we should absolutely keep them, but it would be nice to also provide a modern interface that would work both in the browser and on the server.

loadImage(path[, options]) => Promise<Image>
imageFromBuffer(buffer) => Image

There's some movement on ImageData conversion extensions, although it looks like not much change since 2015: http://wicg.github.io/img-conversion/ and https://github.com/WICG/img-conversion. Notably Promise<ImageData> ImageData.create(Blob) is similar to what you've proposed. We could slightly modify it to Promise<ImageData> ImageData.create(Blob|Buffer|path:String[, options]). Not sure how wise it would be to implement these as they add currently nonstandard APIs to a standard class, which is counter to the whole goal! :) -- In any case, +1 vote for supporting a callback in addition to returning a Promise.

Wow, this is really cool! Need to read up on this. We could probably use a lot of the thought that have gone in to this when designing our own non-standard apis...

Thank you for the awesome and extensive feedback 🙌

[zbjornson]

Ah, got it, thanks for the clarification. I totally missed that those are functions that would be shimmed in the browser.js file. :)

[piranna]

Although the Canvas class is actually called HTMLCanvasElement in the browser and there is no way to call new on it.

We could export both the Canvas and HTMLCanvasElement constructors as alias...