Mapbox-gl-js: Move to a newless API

[mourner]

Most of the objects in the GL JS API are created using new. Leaflet had a huge success moving to a newless API design where instead of constructors, you expose factories:

// before
var map = new mapboxgl.Map();
new mapboxgl.Popup().addTo(map);

// after
var map = mapboxgl.map();
mapboxgl.popup().addTo(map);

This makes it easier for beginners, less prone to errors, and less verbose. It's also better to make global API changes like this sooner than later if we decide to do it.

The main difficulty of the switch would be to figure out how to support the change in the docs with documentation.js, with JSDoc not having a model of factory-based classes. Is there an easy solution?

cc @jfirebaugh @lucaswoj @tmcw

[tmcw]

Depends on how you implement factory-based classes, but we previously had support for the revealing module pattern and could again - it's just a tricky inference step. If you're doing the 'if I'm not an instance, make me an instance' trick, then I think things should 'just work' because you'll still be adding methods to a prototype?

[jfirebaugh]

I think the proposal is to make factory methods for each class, rather than do the constructor trick. So the factory method is a static member of mapboxgl which @returns {Class}, and the constructor itself is @private. As long as the output order is sensible -- like the factory methods are either all at the top, or grouped with the instance methods of the corresponding class -- documentation.js should handle this fine.

[jfirebaugh]

My views on this have changed. I think with the move toward ES6 classes throughout the JavaScript ecosystem, it makes the most sense just to embrace new as the one true way to create class instances. _Not_ supporting new would certainly be bucking a trend. Given that, does anyone still feel that including a newless API _in addition_ to a newful API is important? (I don't.)

[anandthakker]

I think with the move toward ES6 classes throughout the JavaScript ecosystem, it makes the most sense just to embrace new as the one true way to create class instances. Not supporting new would certainly be bucking a trend.

Agreed, and no, I don't see a need to also have/support a newless API

[mourner]

Agreed, let's close.