Unexport or document mapboxgl.util

[jfirebaugh]

Nothing there is public.

[kelvinabrokwa]

Can we leave it public but undocumented? There are some methods in there that are useful for libraries extending gl-js like in gl-draw.

[tmcw]

fwiw Leaflet's utils are public and they help leaflet's plugins have a vanilla way to do basic stuff like building 3rd party controls

[jfirebaugh]

@kelvinabrokwa gl-js doesn't do "public but undocumented". The choices are either private (and preferably still documented), or public and documented. If there's an undocumented public API, it's a bug.

Committing to something as public API has costs:

• Public APIs must be held to a higher standard for documentation and tests.
• Public APIs can't change in backward incompatible ways. They are less malleable, i.e. less useful to gl-js itself, because they can't necessarily change in ways that would be more convenient to gl-js.

gl-js is not a general utility library. Its API should focus on maps, and leave methods which are easily found in myriad third party modules, to those modules.

Something like mbgl.Control is different -- I don't have a problem with exporting that.

[lucaswoj]

One potential compromise is to kill mapboxgl.util and pull in a 3rd party utility library

[mourner]

Based on Leaflet experience, the costs are not that bad.

Higher standard of docs and tests is beneficial in general regardless of whether it is applied to public APIs or not. I also had no problem breaking compatibility on many util methods and no one ever complained — it's fine as long as it is clearly described in the changelog.

There were also never any attempts to make the util methods more generic — they were always kept focused on Leaflet needs, nevertheless they turned out to be useful for users too. Many plugin devs also depend on them.

It also feels uneasy to use a third-party util library in your app for stuff that's already in the bundle but can't be used because it wasn't exported, thus duplicating code.

[vicapow]

+1 @lucaswoj's comment. A lot of this could go into a third party lib. What can't could be private. as an ie: https://github.com/component/debounce

[lucaswoj]

I think it is worth resuming this discussion. I'm still in favor of using a 3rd party utility lib like lodash.

• in its entirety lodash is only 4kb gzipped
• we can further reduce the payload size by only requiring the modules we need (e.g. require('lodash/chunk');)
• great effort as gone into documenting, testing, and optimizing lodash

[mourner]

I'm 👎 on Lodash, it's bloatware in my opinion and we've been perfectly fine with the current situation, with a minimal set of utils specific to GL JS.

[lucaswoj]

I'm ok with that.

[mourner]

in its entirety lodash is only 4kb gzipped

To expand on this, in it's entirety it's 21kb gzipped, which is a lot for a few utility methods. 4kb is just the core build. Also, our dependency tree is already heavy, and Lodash is like 4MB alone in node_modules... And if we use separate small modules, it's a dependency hell to manage.

[jfirebaugh]

The original question here wasn't "should we use lodash or not", it was "should mapbox-gl-js export general-purpose utility methods".

My opinion is still "no": mapbox-gl-js should export only functionality specific to maps. Exporting general purpose utilities, while perhaps convenient in certain cases, means more work for mapbox-gl-js developers, and exposes internal implementation details we may want to change in the future.

[mourner]

My opinion is still "yes": mapbox-gl-js should leave util exported and document it. Making a method public doesn't mean we are obliged to make it general-purpose — it's enough to document its specifics, which should be documented anyway. If we want to change implementation details in future, it's not a problem — minor breaking changes happen, and they don't cause much trouble if documented.

[bhousel]

If the utilities are useful for plugin development they should be exported.

[jfirebaugh]

But we're looking for ways to structure mapbox-gl-js such that plugins can be written without any formal dependency on mapbox-gl-js, because that would be easier for core developers, plugin developers, and plugin users alike. See #1835 and #2118.

[jfirebaugh]

Examples of util code we couldn't remove if mapbox-gl-js was 1.0 and still exporting util, even though the library itself may no longer use it:

• util.setOptions, no longer used since we switched to ES6 classes
• util.bindHandlers same
• util.inherit (now only used by tests)
• util.extend (will eventually be replaced by Object.assign)

We want the freedom to drop functions like this once we no longer need them. The library should not export util.

[mourner]

@jfirebaugh I'm sold, let's unexport.

[tmcw]

Yep, I agree too.