The ability to check if a style is loaded enough to perform some style operations

[jwoodwardtfx]

At present, map.isStyleLoaded() is publicly exposed to allow checking of whether the style has fully loaded.

This calls through to ...style.loaded(), which looks like this:

    loaded() {
        if (!this._loaded)
            return false;

        if (Object.keys(this._updatedSources).length)
            return false;

        for (const id in this.tileManagers)
            if (!this.tileManagers[id].loaded())
                return false;

        if (!this.imageManager.isLoaded())
            return false;

        return true;
    }

That is, it checks if the style is loaded AND there are no outstanding operations on it.

However, lots of operations on the style (like adding and removing layers, setLayoutProperty, etc) internally call _checkLoaded(), which looks like this:

    _checkLoaded() {
        if (!this._loaded) {
            throw new Error('Style is not done loading.');
        }
    }

_checkLoaded() only inspects _loaded, which I assume means that with that flag set as loaded, it is safe to perform these operations.

My issue is, how do I know whether the style is in this state, where I can safely perform these operations?

I can't rely on isStyleLoaded(), as it returns false for a whole load of other conditions that are not blocking on these operations (for example, if I call setData() and that call is yet to complete, isStyleLoaded returns false, but the style is in a perfectly good state for me to act on).

Is there a publicly exposed API to allow me to check that the style is loaded to a position where I can perform these operations?

Do I just need to wrap all these calls in a try/catch to see if I get this error thrown or (even worse), do I just root into the private state and check _loaded myself?

I assume another option is to listen for the "style.load" event and latch when this has occurred? (as an aside, this even doesn't seem to be documented, at least, I couldn't find it in the API reference).

[neodescis]

The isStyleLoaded() check is probably the most appropriate thing to use generally. Yes, some things can be done when _loaded is true, but you cannot (for instance) reliably get results from queryRenderedFeatures() when the tile managers are not loaded.

Is there a reason you need to perform some action between _loaded being true and isStyleLoaded() returning true?

[jwoodwardtfx]

I believe that calling setData()/updateData() on a GeoJSON layer causes isStyleLoaded() to return false whilst that update is pending.

If we have a second, completely separate layer that is stable and safely populated, using isStyleLoaded() as a filter would mean that actions on it, like a setLayoutProperty(), could not be made. However, it's completely safe to do this (as long as the style has been loaded in the first place).

One example would be changing the visibility of layer B whilst the GeoJSON in layer A is being updated. The style must be loaded to do this, but the pending data update on layer A doesn't need to block this.

I think that maybe this is the purpose of the "style.load" event, and the intent was that this event should be tracked on my side and used as a filter before performing operations against the style, and not to use isStyleLoaded() in this way? Is that the case?

Basically, the issue is that isStyleLoaded() seems to be mixing both "the style has been initially loaded, and you can perform operations on it" and "there are pending updates on any part of the style that may occur during the lifecycle of this style".

In short, I just need to know when it's safe to call operations like setLayoutProperty() without generating exceptions, but relying on isStyleLoaded() seems too restrictive.

[neodescis]

I use isStyleLoaded() after a call to setStyle(). Once isStyleLoaded() returns true, I do not gate any additional operations based on that until/unless another call to setStyle() is made. At one point, the "style.load" event only happened after the first call to setStyle(), but I don't know if that's still the case. Specifically, here's some pseudocode of what I do when making a setStyle call:

1. Block any map operations
2. Check if incoming style is actually different from what is already applied
3. Call setStyle()
4. Wait for "styledata" event (this does not happen if there was no style change, which is why 1 above is needed)
5. Check isStyleLoaded(). It may or may not return true when the "styledata" event comes across. If not true, poll until it is true.
6. Style is loaded; unblock map operations

[adamshaylor]

In my case, I need to know when it’s safe to add and remove sources and layers since our maps’ contents are highly dynamic. I’ve written this:

/**
 * Adding and removing layers in MapLibre is not possible until the map
 * instance's style data is loaded. This can be used to `await` that
 * state.
 */
export const getStyleLoadedPromise = (map: MapLibre.Map): Promise<void> => {
  if (map.isStyleLoaded()) {
    return Promise.resolve();
  }

  return new Promise((resolve) => {
    map.once("styledata", () => {
      resolve();
    });
  });
};

This would work if the styledata event was fired consistently, but in my experience (using 5.18.0), it only fires for the initial style load. Thinking maybe I had the wrong idea about how .once() was supposed to work, I tried switching to map.on() and unsubscribing after the event is fired but it behaved exactly the same way. Thus I have to keep track of the initial style load myself and treat that as a substitute for map.isStyleLoaded().

Perhaps the meaning of style load state is a bit too overloaded?