Versioning and Backward Compatibility

The Mapsted Maps JavaScript API follows Semantic Versioning: MAJOR.MINOR.PATCH. The current release is 4.0.1.

Version Policy

• MAJOR bump (e.g. 4.0.1 → 5.0.0): Breaking changes such as method renames, removed features, or changed defaults. Breaking changes only ever ship in a major.
• MINOR bump (e.g. 4.0.1 → 4.1.0): New methods, events, or options — backward compatible.
• PATCH bump (e.g. 4.0.1 → 4.0.2): Bug fixes and internal changes, no API surface change.

Because the scheme is semver, npm range semantics work as you would expect — ^4.0.1 picks up compatible 4.x releases and never crosses into 5.0.0.

Migration Shim

V2 and V3 method names still work via the migration shim:

// All of these still work (with deprecation warnings):
mapsted.maps.initialize({ ... });             // → init()
mapsted.maps.changeFloorById(5);              // → navigateToFloorById(5)
mapsted.maps.addEventListener('select', fn);  // → on('select', fn)
mapsted.maps.setMapView({ ... });             // → setViewport({ ... })
mapsted.maps.centerOnMapoverlay(id);          // → centerOnMapOverlay(id) (casing fix)

Migration Strict Mode

Default behaviour is lenient — each deprecated method call fires one console.warn on first use and then transparently delegates to the current equivalent. Opt into strict mode during a migration audit to surface every remaining call site at once:

await mapsted.maps.init({ element: '#map', strict: true });
// mapsted.maps.initialize() now throws MAPSTED-1093 instead of warning

Or toggle at runtime:

import { setStrictMode } from '@mapsted/maps-js-api';
setStrictMode(true);  // throws MAPSTED-1093 on any deprecated call
setStrictMode(false); // default — warn-only

SecurityConfig.strictMode (in init({ security: { strictMode: … } })) is a separate setting that controls origin-validation behaviour. That one does default to true. See Compatibility and the changelog Security section.

Deprecation Lifecycle

1. Deprecated (release that introduces the new canonical name): Method still works, console.warn on first call.
2. Strict-mode throw (same release): Throws MAPSTED-1093 when migration strict mode is on.
3. Removed (next major): Method no longer exists in the API.

Current state (4.0.1):

Deprecated since	Methods	Scheduled removal
4.0.1	initialize, set, changeFloorById, changeFloorByName, setMapView, centerOnMapoverlay (casing), setDefaultCustomRoutingConfig, changeLanguage, addEventListener, removeEventListener, highlightStyle (throws)	Next major release

CDN vs npm Versioning

• CDN: mapi.mapsted.com is the single production origin and serves every version directly. Point your script tag at the version you want:

  <script src="https://mapi.mapsted.com/v4.0.1/maps.js?id=1234"></script>

  The current release is 4.0.1. Because mapi.mapsted.com keeps serving all versions, hardcoded legacy tags such as <script src="https://mapi.mapsted.com/v3.0.0/maps.js?id=1234"> keep working with no change and no redirect. See Compatibility — CDN Versioning for the per-version schedule.

• npm: @mapsted/maps-js-api@4.0.1 — the package version in package.json.

See also: Changelog | Compatibility | V2 → current migration | V3 → current migration | V2 archive | V3 archive