@mapsight/lib-ol 4.0.0

package/src/js/style/createCachedStyleFunction.ts

@@ -0,0 +1,344 @@
+import type {Type as GeometryType} from "ol/geom/Geometry";
+import type Geometry from "ol/geom/Geometry";
+import type GeometryCollection from "ol/geom/GeometryCollection";
+import LRUCache from "ol/structs/LRUCache";
+import type Style from "ol/style/Style";
+
+import {ensureNonNullable} from "@mapsight/lib-js/nonNullable";
+
+import type {Derivation} from "../geometry/deriveGeometriesFromBase.ts";
+import deriveGeometriesFromBase from "../geometry/deriveGeometriesFromBase.ts";
+import type {GroupedRootStyleDeclaration} from "../index.ts";
+import declarationToGeometry from "./declarationToGeometry.ts";
+import declarationToStyle from "./declarationToStyle.ts";
+import type {
+	MapsightStyleFunction,
+	MapsightStyleFunctionEnv,
+	MapsightStyleFunctionProps,
+} from "./styleFunction.ts";
+import {STYLE_ENV_FIELD_NAME, createPropsFilter} from "./styleFunction.ts";
+
+const TYPE_GEOMETRY_COLLECTION: GeometryType = "GeometryCollection";
+const DEFAULT_STYLE = "default";
+const HASH_STRING_DELIMITER = "|";
+
+const DEFAULT_ROOT_STYLE_TYPE = "style";
+
+const DEFAULT_CACHE_LEVEL_1_SIZE = 100;
+const DEFAULT_CACHE_LEVEL_2_SIZE = 100;
+const DEFAULT_CACHE_LEVEL_3_SIZE = 100;
+
+type CachedValue = {
+	style: Style | null;
+	geometryTypeOrDerivation: GeometryType | Derivation | null;
+};
+type CachedValues = Array<CachedValue>;
+
+export type StyleFunctionMetrics = {
+	envHashMs: number;
+	propsHashMs: number;
+	level1Hits: number;
+	level1Misses: number;
+	level2Hits: number;
+	level2Misses: number;
+	declarationMs: number;
+	styleMaterializationMs: number;
+	inputStylesCount: number;
+	outputStylesCount: number;
+	geometryCollectionsTraversed: number;
+	totalMs: number;
+};
+
+export type StyleFunctionMetricsCollector = (
+	metrics: StyleFunctionMetrics,
+) => void;
+
+export type StyleFunctionOptions = {
+	constructorsMap: Record<string, unknown>;
+	metricsCollector?: StyleFunctionMetricsCollector;
+	declarationHashFunction: (
+		env: MapsightStyleFunctionEnv,
+		props: MapsightStyleFunctionProps,
+		envHash: string,
+		geometryType: GeometryType,
+		styleName: string,
+	) => string;
+	declarationFunction: (
+		env: MapsightStyleFunctionEnv,
+		props: MapsightStyleFunctionProps,
+		geometryType: GeometryType,
+		styleName: string,
+	) => unknown; // Using GroupedRootStyleDeclaration here breaks tsc, probably because the object is too big/complex
+	allowedProps?: Array<string> | false;
+	allowedStyles?: Array<string> | false;
+	cacheLevel1Size?: number;
+	cacheLevel2Size?: number;
+	cacheLevel3Size?: number;
+};
+
+/**
+ * Creates a cached mapsight style function for openlayers
+ *
+ * @param constructorsMap map of style constructors
+ * @param [metricsCollector] optional callback receiving per-invocation runtime metrics (hash timing, cache hit/miss, and declaration/style timings)
+ * @param declarationHashFunction style declaration hash function
+ * @param declarationFunction style declaration function
+ * @param [allowedProps=false] list of props allowed, false = all allowed
+ * @param [allowedStyles=false] list of styles allowed, false = all allowed
+ * @param [cacheLevel1Size=100] size of first level cache that caches feature geometry styles based on feature and environment state
+ * @param [cacheLevel2Size=100] size of second level cache that caches style objects based on the rules that apply and the environment state
+ * @param [cacheLevel3Size=100] size of third level cache that caches style objects based on the rules that apply and the environment state
+ *
+ * @returns style function
+ */
+export default function createCachedStyleFunction({
+	constructorsMap,
+	metricsCollector,
+	declarationHashFunction,
+	declarationFunction,
+	allowedProps = false,
+	allowedStyles = false,
+	cacheLevel1Size = DEFAULT_CACHE_LEVEL_1_SIZE,
+	cacheLevel2Size = DEFAULT_CACHE_LEVEL_2_SIZE,
+	cacheLevel3Size = DEFAULT_CACHE_LEVEL_3_SIZE,
+}: StyleFunctionOptions) {
+	const hasMetricsCollector = typeof metricsCollector === "function";
+	const filterProps = createPropsFilter(allowedProps);
+	const createHash = (value: unknown) => JSON.stringify(value);
+
+	const cacheLevel1 = new LRUCache<CachedValues>(cacheLevel1Size); // the first level cache caches feature geometry styles based on feature and environment state
+	const cacheLevel2 = new LRUCache<CachedValues>(cacheLevel2Size); // the second level cache caches style objects based on the rules that apply and the environment state
+	const cacheLevel3 = new LRUCache<Style | null>(cacheLevel3Size); // the third level cache caches style objects based on the rules that apply and the environment state
+
+	function level1(
+		env: MapsightStyleFunctionEnv,
+		props: MapsightStyleFunctionProps,
+		envHash: string,
+		propsHash: string,
+		geometryType: GeometryType,
+		metrics?: StyleFunctionMetrics,
+	): CachedValues {
+		const cacheHashL1 =
+			envHash +
+			HASH_STRING_DELIMITER +
+			geometryType +
+			HASH_STRING_DELIMITER +
+			propsHash;
+		const hasLevel1 = cacheLevel1.containsKey(cacheHashL1);
+		if (metrics) {
+			if (hasLevel1) {
+				metrics.level1Hits += 1;
+			} else {
+				metrics.level1Misses += 1;
+			}
+		}
+
+		if (!hasLevel1) {
+			cacheLevel1.set(
+				cacheHashL1,
+				level2(env, props, envHash, propsHash, geometryType, metrics),
+			);
+		}
+
+		return cacheLevel1.get(cacheHashL1);
+	}
+
+	function level2(
+		env: MapsightStyleFunctionEnv,
+		props: MapsightStyleFunctionProps,
+		envHash: string,
+		propsHash: string,
+		geometryType: GeometryType,
+		metrics?: StyleFunctionMetrics,
+	): CachedValues {
+		let styleName: string = DEFAULT_STYLE;
+
+		const envStyle = env[STYLE_ENV_FIELD_NAME];
+		if (typeof envStyle === "string") {
+			if (allowedStyles === false) {
+				styleName = envStyle;
+			} else {
+				styleName =
+					allowedStyles.indexOf(envStyle) > -1
+						? envStyle
+						: DEFAULT_STYLE;
+			}
+		}
+
+		const cacheHashL2 = declarationHashFunction(
+			env,
+			props,
+			envHash,
+			geometryType,
+			styleName,
+		);
+		if (cacheLevel2.containsKey(cacheHashL2)) {
+			if (metrics) {
+				metrics.level2Hits += 1;
+			}
+			return cacheLevel2.get(cacheHashL2);
+		}
+		if (metrics) {
+			metrics.level2Misses += 1;
+		}
+
+		const declarationStart = metrics ? performance.now() : 0;
+		const declarations = declarationFunction(
+			env,
+			props,
+			geometryType,
+			styleName,
+		) as GroupedRootStyleDeclaration; // Having to cast here because of the tsc bug noted above
+		if (metrics) {
+			metrics.declarationMs += performance.now() - declarationStart;
+		}
+
+		const styleMaterializationStart = metrics ? performance.now() : 0;
+		const values: CachedValues = Object.keys(declarations).map((group) => ({
+			style: declarationToStyle(
+				constructorsMap,
+				ensureNonNullable(declarations[group]),
+				DEFAULT_ROOT_STYLE_TYPE,
+				group + "," + cacheHashL2,
+				cacheLevel3,
+			),
+			geometryTypeOrDerivation: declarationToGeometry(
+				declarations[group],
+			),
+		}));
+		if (metrics) {
+			metrics.styleMaterializationMs +=
+				performance.now() - styleMaterializationStart;
+			metrics.inputStylesCount += values.length;
+		}
+		cacheLevel2.set(cacheHashL2, values);
+
+		return values;
+	}
+
+	function styleGeometryOrGeometryCollectionCached(
+		env: MapsightStyleFunctionEnv,
+		props: MapsightStyleFunctionProps,
+		envHash: string,
+		propsHash: string,
+		geometryOrGeometryCollection?: Geometry,
+		metrics?: StyleFunctionMetrics,
+		i = 0,
+	): Array<Style> {
+		if (!geometryOrGeometryCollection) {
+			return [];
+		}
+
+		const geometryType = geometryOrGeometryCollection.getType();
+
+		// recurse through collections
+		if (geometryType === TYPE_GEOMETRY_COLLECTION) {
+			if (metrics) {
+				metrics.geometryCollectionsTraversed += 1;
+			}
+			const collection =
+				geometryOrGeometryCollection as GeometryCollection;
+
+			return collection
+				.getGeometries()
+				.flatMap((geometry: Geometry) =>
+					styleGeometryOrGeometryCollectionCached(
+						env,
+						props,
+						envHash,
+						propsHash,
+						geometry,
+						metrics,
+						i + 1,
+					),
+				);
+		}
+
+		return level1(env, props, envHash, propsHash, geometryType, metrics)
+			.filter(({style}) => style != null)
+			.flatMap(function bindStyleToBaseGeometry({
+				style: baseStyle,
+				geometryTypeOrDerivation: geometryDerivation,
+			}: CachedValue) {
+				if (baseStyle === null) {
+					return [];
+				}
+
+				const derivedGeometries = deriveGeometriesFromBase(
+					geometryOrGeometryCollection,
+					geometryDerivation,
+				);
+
+				return derivedGeometries.map(
+					function bindDerivedGeometryToStyle(geometryWithMeta) {
+						const [geometry, meta] = geometryWithMeta;
+						const style = baseStyle.clone();
+						style.setGeometry(geometry);
+
+						const baseImageStyle = style.getImage();
+						if (meta?.rotation != null && baseImageStyle) {
+							const imageStyle = baseImageStyle.clone();
+							const baseRotation = imageStyle.getRotation();
+							imageStyle.setRotation(
+								baseRotation + meta.rotation,
+							);
+							style.setImage(imageStyle);
+						}
+						return style;
+					},
+				);
+			});
+	}
+
+	const cachedStyleFunction: MapsightStyleFunction = (env = {}, feature) => {
+		const totalStart = hasMetricsCollector ? performance.now() : 0;
+		const metrics: StyleFunctionMetrics | undefined = hasMetricsCollector
+			? {
+					envHashMs: 0,
+					propsHashMs: 0,
+					level1Hits: 0,
+					level1Misses: 0,
+					level2Hits: 0,
+					level2Misses: 0,
+					declarationMs: 0,
+					styleMaterializationMs: 0,
+					inputStylesCount: 0,
+					outputStylesCount: 0,
+					geometryCollectionsTraversed: 0,
+					totalMs: 0,
+				}
+			: undefined;
+
+		// subset of feature properties that are relevant for styling (also used for caching decisions)
+		const filteredProps = filterProps(feature.getProperties());
+		const envHashStart = hasMetricsCollector ? performance.now() : 0;
+		const envHash = createHash(env);
+		if (metrics) {
+			metrics.envHashMs = performance.now() - envHashStart;
+		}
+		const propsHashStart = hasMetricsCollector ? performance.now() : 0;
+		const propsHash = createHash(filteredProps);
+		if (metrics) {
+			metrics.propsHashMs = performance.now() - propsHashStart;
+		}
+
+		const styles = styleGeometryOrGeometryCollectionCached(
+			env,
+			filteredProps,
+			envHash,
+			propsHash,
+			feature.getGeometry() as Geometry,
+			metrics,
+		);
+
+		if (metrics && metricsCollector) {
+			metrics.outputStylesCount = styles.length;
+			metrics.totalMs = performance.now() - totalStart;
+			metricsCollector(metrics);
+		}
+
+		return styles;
+	};
+
+	return cachedStyleFunction;
+}

package/src/js/style/declarationToGeometry.ts

@@ -0,0 +1,7 @@
+import type {RootStyleDeclaration} from "../index";
+
+export default function declarationToGeometry(
+	declaration?: RootStyleDeclaration,
+) {
+	return declaration?.geometry?.value || null;
+}

package/src/js/style/declarationToStyle.ts

@@ -0,0 +1,277 @@
+import LRUCache from "ol/structs/LRUCache";
+import type Image from "ol/style/Image";
+import type Style from "ol/style/Style";
+
+import type {
+	BoolishStyleValue,
+	NumberArrayStyleValue,
+	RootStyleDeclaration,
+	StyleDeclaration,
+	StyleLiteral,
+	StyleValues,
+	UnitStyleValue,
+} from "../index";
+
+const IMAGE_TYPES = ["image", "icon", "circle"];
+const NONE_ABLE_PROPS = ["fill", "stroke"];
+
+const unitFromAnchorValue = (a?: string | null) =>
+	a && typeof a === "string" && a.indexOf("px") > -1 ? "pixels" : "fraction";
+const boolishValue = (a?: BoolishStyleValue) =>
+	a === true || a === 1 || a === "1" || a === "true";
+const numberValue = (a?: string | number | null) =>
+	a ? parseFloat(String(a)) : 0;
+const intValue = (a?: string | number | null) =>
+	a ? parseInt(String(a), 10) : 0;
+const numberArrayValue = (a?: NumberArrayStyleValue) => {
+	let arr: Array<string | number> = [];
+	if (a) {
+		if (Array.isArray(a)) {
+			arr = a;
+		}
+
+		if (typeof a === "string") {
+			arr = a.split(",");
+		}
+	}
+
+	return arr.map((b) => parseFloat(String(b).trim()));
+};
+
+const HASH_STRING_DELIMITER = "|";
+export const DEFAULT_CACHE_SIZE = 100;
+
+let defaultCache: null | LRUCache<Style | null> = null;
+
+function getDefaultCache() {
+	if (defaultCache === null) {
+		defaultCache = new LRUCache(DEFAULT_CACHE_SIZE);
+	}
+	return defaultCache;
+}
+
+function _declarationToStyle(
+	constructorsMap: Record<string, unknown>,
+	declaration: Readonly<RootStyleDeclaration | StyleDeclaration>,
+	type: string,
+	cache: LRUCache<Style | null>,
+	root = true,
+): Style | null {
+	const style: StyleLiteral = {};
+
+	if (root) {
+		const rootDeclaration = declaration as Readonly<RootStyleDeclaration>;
+
+		if (rootDeclaration.display?.value === "none") {
+			return null;
+		}
+
+		// image is the base for icon, circle and regular shape. image only has image-type: *; any other options
+		// will be in either of the above. e.g. icon-src: ...;
+		if (rootDeclaration.image) {
+			const imageType = rootDeclaration.image.type.value;
+			if (imageType) {
+				if (rootDeclaration[imageType]) {
+					// FIXME: converting `Style` to `Image`
+					style.image = declarationToStyle(
+						constructorsMap,
+						rootDeclaration[
+							imageType
+						] as Readonly<StyleDeclaration>,
+						imageType,
+						undefined,
+						cache,
+						false,
+					) as Image | null;
+				}
+			} else {
+				console.error("Image type unknown", imageType, rootDeclaration);
+			}
+		}
+	}
+
+	Object.keys(declaration).forEach((key) => {
+		if (IMAGE_TYPES.indexOf(key) > -1) {
+			return;
+		}
+
+		const values = declaration as Readonly<StyleValues>;
+		const declarationValue = values[key];
+		if (typeof declarationValue !== "object") {
+			return;
+		}
+
+		const declarationValueValue =
+			"value" in declarationValue ? declarationValue.value : undefined;
+
+		if (declarationValueValue === undefined) {
+			if (key in constructorsMap) {
+				try {
+					style[key] = declarationToStyle(
+						constructorsMap,
+						declarationValue as Readonly<StyleDeclaration>,
+						key,
+						undefined,
+						cache,
+						false,
+					);
+				} catch (e) {
+					console.error("Style error", e);
+				}
+			}
+
+			return;
+		}
+
+		if (
+			declarationValueValue === "unset" ||
+			(declarationValueValue === "none" &&
+				NONE_ABLE_PROPS.indexOf(key) > -1)
+		) {
+			delete style[key];
+			return;
+		}
+
+		switch (key) {
+			// booleans
+			case "snapToPixel":
+				style.snapToPixel = boolishValue(
+					declarationValueValue as BoolishStyleValue,
+				);
+				break;
+
+			case "rotateWithView":
+				style.rotateWithView = boolishValue(
+					declarationValueValue as BoolishStyleValue,
+				);
+				break;
+
+			// allow space separated double value (x and y)
+			//case 'size':
+			//	style.size = declarationValueValue ? declarationValueValue.split(' ').map(part => parseFloat(part)) : style.size;
+			//	break;
+
+			case "sizeX":
+				style.size = style.size || [0, 0];
+				style.size[0] = numberValue(declarationValueValue);
+				break;
+
+			case "sizeY":
+				style.size = style.size || [0, 0];
+				style.size[1] = numberValue(declarationValueValue);
+				break;
+
+			// allow space separated double value (x and y)
+			//case 'imgSize':
+			//	style.imgSize = declarationValueValue ? declarationValueValue.split(' ').map(part => parseFloat(part)) : style.imgSize;
+			//	break;
+
+			case "imgSizeX":
+				style.imgSize = style.imgSize || [0, 0];
+				style.imgSize[0] = numberValue(declarationValueValue);
+				break;
+
+			case "imgSizeY":
+				style.imgSize = style.imgSize || [0, 0];
+				style.imgSize[1] = numberValue(declarationValueValue);
+				break;
+
+			case "anchorX":
+				style.anchor = style.anchor || [0, 0];
+				style.anchor[0] = numberValue(declarationValueValue);
+				style.anchorXUnits = unitFromAnchorValue(
+					declarationValueValue as UnitStyleValue,
+				);
+				break;
+
+			case "anchorY":
+				style.anchor = style.anchor || [0, 0];
+				style.anchor[1] = numberValue(declarationValueValue);
+				style.anchorYUnits = unitFromAnchorValue(
+					declarationValueValue as UnitStyleValue,
+				);
+				break;
+
+			// can be directly (offsetX in ol.style.Text or offset array in ol.style.Icon)
+			case "offsetX":
+				style.offset = style.offset || [0, 0];
+				style.offsetX = style.offset[0] = numberValue(
+					declarationValueValue,
+				);
+				break;
+
+			// can be directly (offsetY in ol.style.Text or offset array in ol.style.Icon)
+			case "offsetY":
+				style.offset = style.offset || [0, 0];
+				style.offsetY = style.offset[1] = numberValue(
+					declarationValueValue,
+				);
+				break;
+
+			case "colorRed":
+				style.color = style.color || [0, 0, 0, 1];
+				style.color[0] = intValue(declarationValueValue);
+				break;
+
+			case "colorGreen":
+				style.color = style.color || [0, 0, 0, 1];
+				style.color[1] = intValue(declarationValueValue);
+				break;
+
+			case "colorBlue":
+				style.color = style.color || [0, 0, 0, 1];
+				style.color[2] = intValue(declarationValueValue);
+				break;
+
+			case "colorAlpha":
+				style.color = style.color || [0, 0, 0, 1];
+				style.color[3] = numberValue(declarationValueValue);
+				break;
+
+			case "lineDash":
+				style.lineDash = numberArrayValue(
+					declarationValueValue as NumberArrayStyleValue,
+				);
+				break;
+
+			default:
+				style[key] = declarationValueValue;
+		}
+	});
+
+	const StyleCtor = constructorsMap[type] as
+		| (new (style: StyleLiteral) => Style)
+		| undefined;
+	return StyleCtor ? new StyleCtor(style) : null;
+}
+
+export default function declarationToStyle<StyleKey extends string = string>(
+	constructorsMap: Record<StyleKey, unknown>,
+	declaration: Readonly<RootStyleDeclaration | StyleDeclaration>,
+	type: StyleKey,
+	hash?: string,
+	cache: LRUCache<Style | null> = getDefaultCache(),
+	root = true,
+): null | Style {
+	if (!constructorsMap[type]) {
+		console.error("Style unknown", type, declaration);
+		return null;
+	}
+
+	const cacheHash =
+		type + HASH_STRING_DELIMITER + (hash || JSON.stringify(declaration));
+	if (!cache.containsKey(cacheHash)) {
+		cache.set(
+			cacheHash,
+			_declarationToStyle(
+				constructorsMap,
+				declaration,
+				type,
+				cache,
+				root,
+			),
+		);
+	}
+
+	return cache.get(cacheHash);
+}

package/src/js/style/styleFunction.ts

@@ -0,0 +1,42 @@
+import type {FeatureLike} from "ol/Feature";
+import type Style from "ol/style/Style";
+
+import type {StyleFunctionOptions} from "./createCachedStyleFunction";
+
+export const STYLE_ENV_FIELD_NAME = "style";
+
+// TODO: I dont really like this (here). Can we find a better way of
+//    defining the style function props/env?
+type StatePrimitive = string | number | boolean | null | undefined;
+type StateObject = {[key: string]: StateValue};
+type StateArray = StateValue[];
+type StateValue = StatePrimitive | StateObject | StateArray;
+
+export type MapsightStyleFunctionEnv = {
+	[k: string]: StateValue;
+	[STYLE_ENV_FIELD_NAME]?: string;
+};
+export type MapsightStyleFunctionProps = {
+	[k: string]: StateValue;
+};
+
+export type MapsightStyleFunction = (
+	env: MapsightStyleFunctionEnv,
+	feature: FeatureLike,
+) => Array<Style> | Style | undefined;
+
+export const createPropsFilter = (
+	allowedProps: StyleFunctionOptions["allowedProps"] = [],
+) =>
+	allowedProps === false
+		? (props: MapsightStyleFunctionProps) => props
+		: function filterProps(props: MapsightStyleFunctionProps) {
+				const filteredProps: MapsightStyleFunctionProps = {};
+				allowedProps
+					.filter((key) => props[key])
+					.forEach((key) => {
+						filteredProps[key] = props[key];
+					});
+
+				return filteredProps;
+			};

package/src/js/tileGrid/getTileUrlsForExtent.ts

@@ -0,0 +1,41 @@
+import type {Extent} from "ol/extent";
+import type TileGrid from "ol/tilegrid/TileGrid";
+
+import {
+	assertNonNullable,
+	ensureNonNullable,
+} from "@mapsight/lib-js/nonNullable";
+
+export default function getTileUrlsForExtent(
+	tileGrid: TileGrid,
+	extent: Extent,
+) {
+	assertNonNullable(extent[0]);
+	assertNonNullable(extent[1]);
+	assertNonNullable(extent[2]);
+	assertNonNullable(extent[3]);
+
+	const tileUrls: Array<string> = [];
+	for (let z = 17; z <= 21; z++) {
+		const leftBottom = tileGrid.getTileCoordForCoordAndZ(
+			[extent[0], extent[1]],
+			z,
+		);
+		const left = ensureNonNullable(leftBottom[1]);
+		const bottom = -ensureNonNullable(leftBottom[2]);
+
+		const rightTop = tileGrid.getTileCoordForCoordAndZ(
+			[extent[2], extent[3]],
+			z,
+		);
+		const right = ensureNonNullable(rightTop[1]);
+		const top = -ensureNonNullable(rightTop[2]);
+
+		for (let x = left; x <= right; x += 1) {
+			for (let y = top; y <= bottom; y += 1) {
+				tileUrls.push(`${z}/${x}/${y}.png`);
+			}
+		}
+	}
+	return tileUrls;
+}