@versatiles/map-state

Reads and writes the maps of the VersaTiles map editor: markers, lines, polygons and circles with their styles and popups, and the properties of a map like its background map and its legend.

npm install @versatiles/map-state
Copy

A map

A map is a MapState: plain data, without classes.

MapState
├─ elements[]   in drawing order, the first one at the back
│  ├─ marker    point, label, style, popup
│  ├─ line      points, smooth, style, popup
│  ├─ polygon   points, smooth, style, outlineStyle, popup
│  └─ circle    point, radius, style, outlineStyle, popup
├─ frame        what a shared map shows when it opens:
│               bounds, bearing, pitch
└─ meta         title, background, legend, viewer, labels,
                colorScheme
Copy

Only elements is required. Each part has its type: StateElement, StateFrame, StateMetadata.

Examples

A link of a map, and the map of a link:

import { encodeState, decodeState, type MapState } from '@versatiles/map-state';

const state: MapState = {
	elements: [{ type: 'marker', point: [13.4, 52.5], label: 'Berlin', style: { color: '#0000ff' } }]
};
const link = 'https://versatiles.org/versatiles-map-editor/view/#' + encodeState(state);
const again = decodeState(link.split('#')[1]);
Copy

A shorter link: with a visible area, and positions only as fine as that area needs:

import { encodeState, resolutionForArea, type Bounds } from '@versatiles/map-state';

const bounds: Bounds = [13.3, 52.45, 13.5, 52.55]; // west, south, east, north
const hash = encodeState({ ...state, frame: { bounds } }, { resolution: resolutionForArea(bounds) });
Copy

A .mapjson file, which may come from anywhere:

import { readFileSync } from 'node:fs';
import {
	changedMapJSONValues,
	stateFromMapJSON,
	unknownMapJSONFields,
	MapJSONVersionError
} from '@versatiles/map-state';

const json = JSON.parse(readFileSync('walk.mapjson', 'utf8'));
try {
	const map = stateFromMapJSON(json); // only its valid parts
	const unknown = unknownMapJSONFields(json); // e.g. ['elements[0].style.colour']
	if (unknown.length > 0) console.warn('Fields that were not read:', unknown);
	const changed = changedMapJSONValues(json); // e.g. ['elements[0].style.color'] for "red"
	if (changed.length > 0) console.warn('Values that were left out or corrected:', changed);
} catch (error) {
	if (error instanceof MapJSONVersionError) console.error('The file is of a newer version of the format');
	else throw error;
}
Copy

A map for other tools:

import { stateToGeoJSON, stateToKML, stateFromGeoJSON } from '@versatiles/map-state';

const geojson = stateToGeoJSON(state); // a FeatureCollection, the styles as properties
const kml = stateToKML(state); // for Google Earth and GIS tools
const back = stateFromGeoJSON(geojson); // also reads the GeoJSON of other tools
Copy

What to use

To …	use
make or read the link of a map	encodeState, decodeState
make a link shorter, with coarser positions	encodeState(state, { resolution }), resolutionForArea
see what makes a link long	measureLink, and which texts: measureTexts
read or write a .mapjson file	stateFromMapJSON, stateToMapJSON
exchange a map with other tools	stateToGeoJSON, stateFromGeoJSON, stateToKML, stateFromKML
check data that comes from elsewhere	stateFromMapJSON keeps only what is valid; sanitizeState does the same for a state, and sanitizeStyle, sanitizeFrame, sanitizeViewer, sanitizeLegend, sanitizeBackground, sanitizeBounds for its parts
know the values a field can have	the tables of names, e.g. DASH_NAMES, BACKGROUND_THEMES, LEGEND_POSITIONS
know the default of a field	the defaults, e.g. LINE_DEFAULTS, MARKER_DEFAULTS, LEGEND_DEFAULTS

Good to know

• Defaults are left out. A field that is missing has its default value, so a state holds only what differs. The readers of this package return states without defaults.
• Coordinates are [longitude, latitude] in degrees with 5 decimal places, about 1 m.
• The formats are frozen. Every later version of the package reads the links and the .mapjson files of an earlier one (from 1.0.1 on), as the same map; an older version refuses a link of a newer format with a LinkVersionError, a file with a MapJSONVersionError. The README has the promise and its limits.
• No dependencies. It is an ES module for browsers and for Node.js 18 or newer.

The file format is explained field by field in MAPJSON.md, the formats of links, GeoJSON and KML in the README. Below, everything the package exports, by what it is for.