Understanding the API Lifecycle

The API transitions through four states during its lifetime.

State Machine

UNINITIALIZED ──→ LOADING ──→ READY ──→ DESTROYED
                                           │
                                           └──→ UNINITIALIZED (re-init allowed)

States

State	Description	Allowed Operations
UNINITIALIZED	API not started	init(), isReady(), getState(), subscribe()
LOADING	Iframe creating, React mounting	isReady(), getState(), subscribe()
READY	Map fully loaded, commands accepted	All public methods
DESTROYED	Map torn down, listeners cleared	init() to restart

Lifecycle Events

const map = await mapsted.maps.init({ element: '#map' });
// State: READY

mapsted.maps.on('mapMounted', () => console.log('React app mounted'));
mapsted.maps.on('load', () => console.log('Map tiles loaded'));

// When done:
await map.destroy();
// State: UNINITIALIZED (can re-init)

State Observation

getState() is async — it resolves to a snapshot of the current API state, so await it. subscribe(fn) attaches a listener that fires on every state transition and returns an Unsubscribe function.

import { getState, subscribe } from '@mapsted/maps-js-api';

const snapshot = await getState();   // getState() returns a Promise
console.log(snapshot.sdkState);      // "READY" | "LOADING" | …

const unsubscribe = subscribe((state) => {
  console.log('API state →', state.sdkState);
});

// Later, stop listening:
unsubscribe();

For event-stream observation (floor changes, selections, etc.) use the typed event API on('floorChange', fn) / on('select', fn) rather than state subscription — state is the slow-changing lifecycle phase, events are the fast-changing interactions.

See also: API Reference | How it works