DataLayerManager Layer States: A Complete Guide to Layer Lifecycle Management

The DataLayerManager in the God's Eye View repository defines nine distinct layer states—found, missing, source-unavailable, cancelled, superseded, destroyed, enabled, disabled, and uncertain—to track data availability, request lifecycle, and visibility status.

The DataLayerManager class, located in src/data/manager.js within the bilawalsidhu/gods-eye-view open-source project, maintains a lifecycle state machine for every managed layer. These states enable the application’s UI components and voice actions to make informed decisions about rendering, refreshing, or hiding geographic data layers.

Complete List of DataLayerManager Layer States

The manager tracks layer status through the lifecycleState string field and the complementary lifecycleUncertain boolean flag. According to the implementation in src/data/manager.js, the following values represent the definitive list of DataLayerManager layer states.

Data Availability States

These states indicate whether the layer's underlying data source exists and is reachable:

• found – The layer has been successfully loaded and is present in the manager. This state appears when the manager reports a layer as successfully discovered (line 497).

• missing – The layer cannot be located, typically due to a bad ID or non-existent data configuration. This serves as the default fallback for unknown layers (lines 1446, 1729).

• source-unavailable – The data source exists but is temporarily unreachable, such as when a remote feed fails or network connectivity is lost (line 497).

Request Lifecycle States

These states track the status of asynchronous operations on the layer:

• cancelled – A pending request for the layer was explicitly aborted before completion. This represents a terminal state for interrupted operations (line 497).

• superseded – A newer request has replaced the current one, commonly occurring during rapid refresh cycles where an outdated request is discarded (line 497).

Operational and UI States

These states reflect the current visibility and active status of the layer:

• enabled – The layer is actively turned on and visible in the UI. Returned by readLayerLifecycleSummary when the manager confirms the layer is active (line 263).

• disabled – The layer is turned off and hidden. While stored as a state string, this is also implied when the enabled property returned by readLayerLifecycleSummary is false (line 278).

• destroyed – The layer has been explicitly removed from the manager via a destroy call, representing a terminal cleanup state (line 497).

Uncertainty Flag

• uncertain – While not a string value in lifecycleState, this boolean flag indicates the manager cannot yet confirm the definitive lifecycle status, often during asynchronous refreshes. Exposed via the lifecycleUncertain property in readLayerLifecycleSummary (line 525).

Accessing Layer States Programmatically

Applications interact with these states through the readLayerLifecycleSummary helper and the isEnabled method. The readLayerLifecycleSummary function, utilized in src/voice/gevActions.js, normalizes manager state into UI-friendly objects.

// Query a layer's lifecycle state from the DataLayerManager
import { DataLayerManager } from './data/manager.js';
import { readLayerLifecycleSummary } from './voice/gevActions.js';

const manager = new DataLayerManager();
const layerId = 'flights';

// Retrieve comprehensive state information
const { lifecycleState, lifecycleUncertain, enabled } =
  readLayerLifecycleSummary(manager, layerId, { fallbackEnabled: false });

console.log(
  `${layerId} – state: ${lifecycleState}` +
  (lifecycleUncertain ? ' (uncertain)' : '') +
  (enabled ? ' – enabled' : ' – disabled')
);
// Output: "flights – state: found – enabled"

You can also check the enabled status directly via the manager instance:

// Check if a specific layer is enabled
const isLayerActive = manager.isEnabled(layerId);

State Transitions and Error Handling

Layer states transition based on data loading outcomes and user actions. When enabling a layer, applications should handle the missing or source-unavailable states that may result from network failures or configuration errors.

// Safely enable a layer with proper error handling
async function enableLayer(layerId) {
  try {
    const success = await manager.setEnabled(layerId, true);
    if (!success) {
      const { lifecycleState } = readLayerLifecycleSummary(manager, layerId);
      throw new Error(`Layer entered ${lifecycleState} state`);
    }
  } catch (e) {
    console.warn(`Could not enable ${layerId}: ${e.message}`);
  }
}

The src/ui.js file consumes these states to render layer toggles and status chips, while src/data/manager.test.mjs contains test suites verifying correct state transitions for each lifecycle scenario.

Summary

• The DataLayerManager in src/data/manager.js defines nine distinct layer states to track data availability, request lifecycle, and visibility.
• Primary states include found, missing, source-unavailable, cancelled, superseded, destroyed, enabled, and disabled, stored in the lifecycleState field.
• The uncertain boolean flag indicates pending state resolution during asynchronous operations.
• Use readLayerLifecycleSummary (from src/voice/gevActions.js) to query the complete state object including lifecycleState, lifecycleUncertain, and enabled properties.
• The isEnabled method provides a quick boolean check for layer visibility status.

Frequently Asked Questions

What is the difference between 'missing' and 'source-unavailable' states?

The missing state indicates the layer ID cannot be found in the configuration or data registry, typically due to a typo or deleted layer. The source-unavailable state means the layer configuration exists, but the external data feed or remote source is temporarily unreachable due to network issues or server downtime. Both states prevent the layer from rendering, but require different troubleshooting approaches.

How do I check if a layer is currently enabled in DataLayerManager?

Call the isEnabled(layerId) method on the manager instance for a boolean check, or use readLayerLifecycleSummary(manager, layerId) to retrieve an object containing both the enabled boolean and the lifecycleState string. The latter approach is used by voice actions in src/voice/gevActions.js to provide detailed status feedback.

What does the 'superseded' state indicate?

The superseded state occurs when a new data request replaces a pending one, commonly during rapid refresh cycles or when a user toggles a layer on and off quickly before the previous request completes. This prevents race conditions by marking outdated requests as superseded rather than cancelled or failed, allowing the manager to prioritize the most recent operation.

Where are the layer states defined in the source code?

The state strings and their transitions are defined in src/data/manager.js, with specific line references at 497 (for found, source-unavailable, cancelled, superseded, destroyed), 1446 and 1729 (for missing), and 263 (for enabled). The readLayerLifecycleSummary helper that exposes these states to the UI is implemented in src/voice/gevActions.js.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}