# DataLayerManager Layer States: A Complete Guide to Layer Lifecycle Management

> Explore the nine layer states like found, missing, and enabled defined in DataLayerManager for effective data lifecycle management. Understand layer status and visibility.

- Repository: [Bilawal Sidhu/gods-eye-view](https://github.com/bilawalsidhu/gods-eye-view)
- Tags: api-reference
- Published: 2026-09-11

---

**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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voice/gevActions.js), normalizes manager state into UI-friendly objects.

```javascript
// 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:

```javascript
// 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.

```javascript
// 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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voice/gevActions.js).