@eodash/eodash 5.7.0 → 5.8.0

package/core/client/eodashSTAC/helpers.js

@@ -1,7 +1,10 @@
 import { toAbsolute } from "stac-js/src/http.js";
 import axios from "@/plugins/axios";
 import log from "loglevel";
+import mustache from "mustache";
+import { updateVectorLayerStyle } from "@eox/layercontrol";
 import { getStyleVariablesState } from "./triggers.js";
+import { itemsCache, splitItemsCache } from "@/utils/states.js";
 
 /**
  *  @param {import("stac-ts").StacLink[]} [links]
@@ -41,6 +44,26 @@ export function generateFeatures(links, extraProperties = {}, rel = "item") {
   return geojsonObject;
 }
 
+/**
+ * Fetches or extracts the raster form configuration for a STAC object.
+ * Supports direct JSON objects, data URIs, and URL strings.
+ *
+ * @param {string|object|undefined} rasterform - The rasterform property from the STAC object.
+ * @returns {Promise<import("@/types").EodashRasterJSONForm|undefined>}
+ */
+export async function fetchRasterForm(rasterform) {
+  if (!rasterform) {
+    return undefined;
+  }
+  if (typeof rasterform === "object") {
+    return /** @type {import("@/types").EodashRasterJSONForm} */ (rasterform);
+  }
+  if (typeof rasterform === "string") {
+    return await axios.get(rasterform).then((resp) => resp.data);
+  }
+  return undefined;
+}
+
 /**
  * Spearates and extracts layerConfig (jsonform schema & legend) from a style json
  *
@@ -97,6 +120,39 @@ export function extractLayerConfig(
   return { layerConfig, style };
 }
 
+/**
+ * Recursively extracts URL keys from a JSON Schema.
+ * Maps schema property names to their defined `url_key`.
+ * @param {Record<string, any> | null | undefined} schema
+ * @returns {Record<string, string>}
+ */
+export function extractUrlKeys(schema) {
+  /** @type {Record<string, string>} */
+  const keys = {};
+  if (!schema || typeof schema !== "object") return keys;
+
+  if (schema.properties) {
+    for (const [key, propDef] of Object.entries(schema.properties)) {
+      if (propDef && typeof propDef === "object") {
+        if (typeof propDef.url_key === "string") {
+          keys[key] = propDef.url_key;
+        }
+        Object.assign(keys, extractUrlKeys(propDef));
+      }
+    }
+  }
+
+  for (const combinator of ["oneOf", "allOf", "anyOf"]) {
+    if (Array.isArray(schema[combinator])) {
+      for (const sub of schema[combinator]) {
+        Object.assign(keys, extractUrlKeys(sub));
+      }
+    }
+  }
+
+  return keys;
+}
+
 /**
  *
  * @param {number[]} bbox
@@ -171,7 +227,7 @@ export const extractRoles = (properties, linkOrAsset) => {
 
 /**
  * Extracts a single non-link style JSON from a STAC Item optionally for a selected key mapping
- * @param { import("stac-ts").StacItem | import("stac-ts").StacCollection } stacObject
+ * @param { import("stac-ts").StacItem | import("stac-ts").StacCollection | null | undefined} stacObject
  * @param {string | undefined} linkKey
  * @param {string | undefined} assetKey
  * @returns
@@ -181,6 +237,7 @@ export const fetchStyle = async (
   linkKey = undefined,
   assetKey = undefined,
 ) => {
+  if (!stacObject) return undefined;
   let styleLink = null;
   if (linkKey) {
     styleLink = stacObject.links.find(
@@ -212,6 +269,20 @@ export const fetchStyle = async (
   }
 };
 
+/**
+ * Resolves a style by preferring the item's own `style` link and falling back
+ * to the collection's. Takes the same key arguments as `fetchStyle`.
+ *
+ * @param {import("stac-ts").StacItem | import("stac-ts").StacCollection} item
+ * @param {import("stac-ts").StacCollection | null | undefined} collection
+ * @param {string} [linkKey]
+ * @param {string} [assetKey]
+ * @returns {Promise<import("@/types").EodashStyleJson | undefined>}
+ */
+export const resolveStyle = async (item, collection, linkKey, assetKey) =>
+  (await fetchStyle(item, linkKey, assetKey)) ??
+  (await fetchStyle(collection, linkKey, assetKey));
+
 /**
  * Fetches all style JSONs from a STAC Item and returns an array with style objects
  * @param {import("stac-ts").StacItem | import("stac-ts").StacCollection} stacObject
@@ -222,6 +293,7 @@ export const fetchAllStyles = async (stacObject) => {
     link.rel.includes("style"),
   );
   const fetchPromises = styleLinks.map(async (link) => {
+    /** @type {import("@/types").EodashStyleJson} */
     const styleJson = await axios.get(link.href).then((resp) => resp.data);
     log.debug("fetched styles JSON", JSON.parse(JSON.stringify(styleJson)));
     return styleJson;
@@ -251,94 +323,74 @@ export const getProjectionCode = (projection) => {
 };
 
 /**
- * Extracts layercontrol LayerDatetime property from STAC Links
- * @param {import("stac-ts").StacLink[] | import("stac-ts").StacItem[] | undefined} [items]
- * @param {string|null} [currentStep]
- **/
-export const extractLayerTimeValues = (items, currentStep) => {
-  if (!currentStep || !items?.length) {
-    return { layerDatetime: undefined, timeControlValues: undefined };
-  }
-
-  // check if items has a datetime value
-  const dateProperty = getDatetimeProperty(items);
-
-  if (!dateProperty) {
-    return { layerDatetime: undefined, timeControlValues: undefined };
-  }
-  /** @type {{date:string;itemId:string}[]} */
-  const timeValues = [];
-  try {
-    /**
-     *  @param {typeof timeValues} vals
-     *  @param {import("stac-ts").StacLink} link
-     */
-    const reduceLinks = (vals, link) => {
-      if (link[dateProperty] && link.rel === "item") {
-        vals.push({
-          itemId: /** @type {string} */ (link.id),
-          date: new Date(
-            /** @type {string} */ (link[dateProperty]),
-          ).toISOString(),
-        });
-      }
-      return vals;
-    };
-
-    /**
-     *
-     * @param {typeof timeValues} vals
-     * @param {import("stac-ts").StacItem} item
-     */
-    const reduceItems = (vals, item) => {
-      const date = item.properties?.[dateProperty];
-      if (date) {
-        vals.push({
-          itemId: /** @type {string} */ (item.id),
-          date: new Date(/** @type {string} */ (date)).toISOString(),
-          ...item.properties,
-        });
-      }
-      return vals;
-    };
-    currentStep = new Date(currentStep).toISOString();
-    //@ts-expect-error TODO
-    items.reduce(isSTACItem(items[0]) ? reduceItems : reduceLinks, timeValues);
-  } catch (e) {
-    console.warn("[eodash] not supported datetime format was provided", e);
-    return { layerDatetime: undefined, timeControlValues: undefined };
-  }
-  // not enough timeValues
-  if (timeValues.length <= 1) {
+ * Builds layercontrol LayerDatetime + timeControlValues from a list of dates.
+ *
+ * @param {Date[] | undefined} dates
+ * @param {string | null} [currentStep] - target datetime; snapped to the closest available date
+ * @returns {{ layerDatetime: Record<string, any> | undefined, timeControlValues: { date: string }[] | undefined }}
+ */
+export const extractLayerTimeValues = (dates, currentStep) => {
+  if (!currentStep || !dates?.length || dates.length <= 1) {
     return { layerDatetime: undefined, timeControlValues: undefined };
   }
 
-  // item datetime is not included in the item links datetime
-  if (!timeValues.some((val) => val.date === currentStep)) {
-    const currentStepTime = new Date(currentStep).getTime();
-    currentStep = timeValues.reduce((time, step) => {
-      const aDiff = Math.abs(new Date(time).getTime() - currentStepTime);
-      const bDiff = Math.abs(new Date(step.date).getTime() - currentStepTime);
-      return bDiff < aDiff ? step.date : time;
-    }, timeValues[0].date);
+  const controlValues = dates.map((d) => d.toISOString()).sort();
+  const timeControlValues = controlValues.map((date) => ({ date }));
+
+  currentStep = new Date(currentStep).toISOString();
+  if (!controlValues.includes(currentStep)) {
+    const target = new Date(currentStep).getTime();
+    currentStep = controlValues.reduce((best, d) =>
+      Math.abs(new Date(d).getTime() - target) <
+      Math.abs(new Date(best).getTime() - target)
+        ? d
+        : best,
+    );
   }
 
   const layerDatetime = {
-    controlValues: timeValues.map((d) => d.date).sort(),
+    controlValues,
     currentStep,
     slider: true,
     navigation: true,
     play: false,
     displayFormat: "DD.MM.YYYY HH:mm",
     animateOnClickInterval: false,
+    showUTC: true,
   };
 
-  return {
-    layerDatetime,
-    timeControlValues: timeValues,
-  };
+  return { layerDatetime, timeControlValues };
 };
 
+/**
+ * Fetches the daily pre-aggregation data for a STAC collection if available.
+ * Returns the raw AggregationCollection,
+ * or null if no daily pre-aggregation link exists, or the fetch fails.
+ *
+ * @param {import("stac-ts").StacCollection | undefined} stacCollection
+ * @param {string} fallbackBaseUrl - base for relative href resolution when no `self` link is present
+ * @returns {Promise<any | null>}
+ */
+export async function fetchPreAggregations(stacCollection, fallbackBaseUrl) {
+  if (!stacCollection) return null;
+  const preAggregationLink = stacCollection.links?.find(
+    (l) => l.rel === "pre-aggregation" && l["aggregation:interval"] === "daily",
+  );
+  if (!preAggregationLink) return null;
+
+  try {
+    const selfLink = stacCollection.links?.find((l) => l.rel === "self")?.href;
+    const url = toAbsolute(
+      preAggregationLink.href,
+      selfLink || fallbackBaseUrl,
+    );
+    return await axios.get(url).then((resp) => resp.data);
+  } catch (e) {
+    console.warn("[eodash] Failed to fetch pre-aggregation", e);
+    return null;
+  }
+}
+
 /**
  * Recursively find all layers whose ID up to the first ; is same as given layer
  *
@@ -347,6 +399,9 @@ export const extractLayerTimeValues = (items, currentStep) => {
  * @returns {import("@eox/map").EoxLayer[]} Matching layer objects.
  */
 export const findLayersByLayerPrefix = (layers, referenceLayer) => {
+  if (!layers || !referenceLayer) {
+    return [];
+  }
   const refId = referenceLayer?.properties?.id;
 
   if (typeof refId !== "string" || !refId.includes(";:;")) {
@@ -561,20 +616,150 @@ export function assignProjID(item, linkOrAsset, id, layer) {
  *
  * @param {Record<string,any>[]} layers
  */
-export const removeUnneededProperties = (layers) => {
-  const cloned = structuredClone(layers);
-  cloned.forEach((layer) => {
-    const id = layer.properties.id;
-    const title = layer.properties.title;
-    layer.properties = { id, title };
-    if (layer["interactions"]) {
-      delete layer["interactions"];
+export const removeUnneededProperties = (layers, formValues = {}) => {
+  /**
+   * @param {Record<string,any>} layer
+   * @returns {Record<string,any>[]}
+   */
+  const processLayer = (layer) => {
+    // If the layer (or group) is explicitly marked as not visible, skip it and all children
+    if (layer.properties?.visible === false) {
+      return [];
     }
-    if (layer.type === "Group") {
-      layer.layers = removeUnneededProperties(layer.layers);
+
+    // If it's a Group, we just want its children
+    if (layer.type === "Group" && Array.isArray(layer.layers)) {
+      return layer.layers.flatMap(processLayer);
     }
-  });
-  return cloned;
+
+    // Break any Vue Proxies/OpenLayers getters by stringifying first
+    let clonedLayer;
+    try {
+      clonedLayer = JSON.parse(JSON.stringify(layer));
+    } catch (_e) {
+      clonedLayer = structuredClone(layer);
+    }
+
+    // Flatten formValues to handle nested properties (e.g., vminmax: { vmin, vmax })
+    /**
+     * @param {Record<string,any>} obj
+     * @returns {Record<string,any>}
+     */
+    const flattenFormValues = (obj) => {
+      /** @type {Record<string,any>} */
+      let result = {};
+      for (const key in obj) {
+        if (
+          obj[key] !== null &&
+          typeof obj[key] === "object" &&
+          !Array.isArray(obj[key])
+        ) {
+          Object.assign(result, flattenFormValues(obj[key]));
+        } else {
+          result[key] = obj[key];
+        }
+      }
+      return result;
+    };
+    const flatFormValues = flattenFormValues(formValues);
+
+    // Burn in style variables using Mustache if formValues are provided
+    if (Object.keys(flatFormValues).length > 0) {
+      // Stringify, render mustache, then parse back
+      try {
+        const renderedString = mustache.render(
+          JSON.stringify(clonedLayer),
+          flatFormValues,
+        );
+        clonedLayer = JSON.parse(renderedString);
+      } catch (e) {
+        log.warn(
+          "[eodash] Failed to apply mustache templating during export cleanup:",
+          e,
+        );
+      }
+    }
+
+    const {
+      id,
+      title,
+      mapboxStyle,
+      projection,
+      applyOptions,
+      layerConfig,
+      visible,
+    } = clonedLayer.properties || {};
+
+    // If style was not at root but in properties (layerConfig), move it to root early
+    if (!clonedLayer.style && layerConfig?.style) {
+      clonedLayer.style = layerConfig.style;
+    }
+
+    // Burn in OpenLayers ["var", "name"] variables using flatFormValues overriding style.variables
+    const styleVariables = {
+      ...(clonedLayer.style?.variables || {}),
+      ...flatFormValues,
+    };
+
+    if (clonedLayer.style && Object.keys(styleVariables).length > 0) {
+      clonedLayer.style = updateVectorLayerStyle({
+        ...clonedLayer.style,
+        variables: styleVariables,
+      });
+    }
+
+    clonedLayer.properties = {
+      id,
+      title,
+      ...(mapboxStyle && { mapboxStyle }),
+      ...(projection && { projection }),
+      ...(applyOptions && { applyOptions }),
+      ...(visible !== undefined && { visible }),
+    };
+
+    if (clonedLayer["interactions"]) {
+      delete clonedLayer["interactions"];
+    }
+
+    // Cleanup unnecessary properties
+    /**
+     * @param {any} obj
+     */
+    const cleanupProperties = (obj) => {
+      if (!obj || typeof obj !== "object") return;
+
+      for (const key in obj) {
+        if (obj[key] === null) {
+          delete obj[key];
+        } else if (Array.isArray(obj[key])) {
+          if (obj[key].length === 0) {
+            // Remove empty arrays like empty interactions
+            delete obj[key];
+          } else {
+            obj[key].forEach(cleanupProperties);
+          }
+        } else if (typeof obj[key] === "object") {
+          cleanupProperties(obj[key]);
+          if (Object.keys(obj[key]).length === 0) {
+            // we don't delete empty objects for now as it might break schema requirements
+          }
+        }
+      }
+    };
+    cleanupProperties(clonedLayer);
+
+    return [clonedLayer];
+  };
+
+  // ensure the top level array is also deeply un-proxied if needed
+  let rawLayers = layers;
+  try {
+    rawLayers = JSON.parse(JSON.stringify(layers));
+  } catch (_e) {
+    rawLayers = structuredClone(layers);
+  }
+
+  return rawLayers.flatMap(processLayer);
 };
 
 /**
@@ -734,7 +919,12 @@ export function getDatetimeProperty(linksOrItems) {
   }
 
   // TODO: consider other properties for datetime ranges
-  const datetimeProperties = ["datetime", "start_datetime", "end_datetime"];
+
+  const datetimeProperties = /** @type {const} */ ([
+    "datetime",
+    "start_datetime",
+    "end_datetime",
+  ]);
   if (checkProperties) {
     for (const prop of datetimeProperties) {
       const propExists = linksOrItems.some(
@@ -760,6 +950,7 @@ export function getDatetimeProperty(linksOrItems) {
     return prop;
   }
 }
+
 /**
  *
  * @param {*} stacObject
@@ -776,6 +967,65 @@ export function isSTACItem(stacObject) {
   );
 }
 
+/**
+ * Fetches items using a split strategy (past/future) around a center date
+ * @param {string} itemsUrl
+ * @param {string} query
+ * @param {string | Date} centerDatetime
+ * @param {number} maxNumber
+ * @returns {Promise<import("stac-ts").StacItem[]>}
+ */
+export const fetchSplitItems = async (
+  itemsUrl,
+  query,
+  centerDatetime,
+  maxNumber,
+) => {
+  const center = new Date(centerDatetime).toISOString();
+  const limit = Math.ceil(maxNumber / 2);
+
+  /** @param {"past"|"future"} direction */
+  const fetchSide = async (direction) => {
+    const isPast = direction === "past";
+    const datetimeRange = isPast ? `../${center}` : `${center}/..`;
+    const sortOrder = isPast ? "-datetime" : "+datetime";
+    const queryParams = new URLSearchParams(query);
+
+    queryParams.set("limit", limit.toString());
+    queryParams.set("datetime", datetimeRange);
+    queryParams.set("sortby", sortOrder);
+
+    const splitUrl = itemsUrl.split("/");
+    const collectionId = /** @type {string} */ (splitUrl.at(-2));
+    queryParams.set("collection", collectionId);
+
+    const searchEndpoint = `${splitUrl.slice(0, -3).join("/")}/search`;
+    const items = await axios
+      .get(searchEndpoint, { params: queryParams })
+      .then((res) => res.data.features);
+    return items;
+  };
+
+  const [pastItems, futureItems] = await Promise.all([
+    fetchSide("past"),
+    fetchSide("future"),
+  ]);
+
+  const allItems = [...pastItems, ...futureItems];
+
+  // check for duplicates by ids
+  const seen = new Set();
+  const uniqueItems = [];
+  for (const item of allItems) {
+    if (!seen.has(item.id)) {
+      seen.add(item.id);
+      uniqueItems.push(item);
+    }
+  }
+
+  return uniqueItems;
+};
+
 /**
  * Fetch all STAC items from a STAC API endpoint.
  * @param {string} itemsUrl
@@ -783,6 +1033,8 @@ export function isSTACItem(stacObject) {
  * @param {number} [limit=100] - The maximum number of items to fetch per request.
  * @param {boolean} [returnFirst] - If true, only the first page of results will be returned.
  * @param {number} [maxNumber=1000] - if the matched number of items exceed this, only the first page will be returned.
+ * @param {string | Date} [centerDatetime] - Date to center the search around if items exceed maxNumber
+ * @returns {Promise<import("stac-ts").StacItem[]>}
  */
 export async function fetchApiItems(
   itemsUrl,
@@ -790,23 +1042,42 @@ export async function fetchApiItems(
   limit = 100,
   returnFirst = false,
   maxNumber = 1000,
+  centerDatetime,
 ) {
-  itemsUrl = itemsUrl.includes("?") ? itemsUrl.split("?")[0] : itemsUrl;
-  itemsUrl += query ? `?limit=${limit}&${query}` : `?limit=${limit}`;
+  // Exclude centerDatetime from cache key - it's only used for split search fallback
+  const cacheKey = JSON.stringify({
+    itemsUrl,
+    query,
+    limit,
+    returnFirst,
+    maxNumber,
+  });
+
+  if (itemsCache.has(cacheKey)) {
+    return itemsCache.get(cacheKey) ?? [];
+  }
+
+  const urlQuery = new URLSearchParams(query);
+  urlQuery.set("limit", limit.toString());
+
+  let finalItemsUrl = itemsUrl.includes("?")
+    ? itemsUrl.split("?")[0]
+    : itemsUrl;
+  finalItemsUrl += urlQuery.keys().toArray().length
+    ? `?${urlQuery.toString()}`
+    : "";
 
   const itemsFeatureCollection = await axios
-    .get(itemsUrl)
+    .get(finalItemsUrl)
     .then((resp) => resp.data);
+
   /** @type {import("stac-ts").StacItem[]} */
   const items = itemsFeatureCollection.features;
-  const nextLink = itemsFeatureCollection.links?.find(
-    //@ts-expect-error TODO: itemsFeatureCollection is not typed
-    (link) => link.rel === "next",
-  );
-
-  if (!nextLink || returnFirst) {
+  if (returnFirst) {
+    itemsCache.set(cacheKey, items);
     return items;
   }
+
   /** @type {number} */
   const matchedItems = itemsFeatureCollection.numberMatched;
   // Avoid fetching too many items
@@ -814,26 +1085,70 @@ export async function fetchApiItems(
     console.warn(
       `[eodash] The number of items matched (${matchedItems}) exceeds the maximum allowed (${maxNumber})`,
     );
-    return items;
-  }
+    // we try to narrow down the search around the center datetime
+    if (centerDatetime) {
+      // Check if we have a cached split result that covers this centerDatetime
+      const splitCacheKey = JSON.stringify({ itemsUrl, query, maxNumber });
+      const cachedSplit = splitItemsCache.get(splitCacheKey);
+      const centerTime = new Date(centerDatetime).getTime();
+
+      if (
+        cachedSplit &&
+        centerTime >= cachedSplit.minTime &&
+        centerTime <= cachedSplit.maxTime
+      ) {
+        return cachedSplit.items;
+      }
 
-  let [nextLinkURL, nextLinkQuery] = nextLink.href.split("?");
-  nextLinkQuery = nextLinkQuery.replace(/limit=\d+/, "");
-  if (query) {
-    const queryParams = new URLSearchParams(query);
-    const nextLinkParams = new URLSearchParams(nextLinkQuery);
+      const narrowedItems = await fetchSplitItems(
+        itemsUrl,
+        query ?? "",
+        centerDatetime,
+        maxNumber,
+      );
 
-    for (const key of nextLinkParams.keys()) {
-      queryParams.delete(key);
-    }
-    const remainingQuery = queryParams.toString();
-    if (remainingQuery) {
-      nextLinkQuery += `&${remainingQuery}`;
+      if (!narrowedItems.length) {
+        return narrowedItems;
+      }
+      const datetimeProperty = getDatetimeProperty(narrowedItems);
+      if (!datetimeProperty) {
+        return narrowedItems;
+      }
+
+      const times = narrowedItems
+        .map((i) =>
+          i.properties[datetimeProperty]
+            ? new Date(i.properties[datetimeProperty]).getTime()
+            : null,
+        )
+        .filter((t) => t !== null);
+      if (!times.length) {
+        return narrowedItems;
+      }
+      splitItemsCache.set(splitCacheKey, {
+        items: narrowedItems,
+        minTime: Math.min(...times),
+        maxTime: Math.max(...times),
+      });
+
+      return narrowedItems;
     }
+
+    itemsCache.set(cacheKey, items);
+    return items;
   }
 
-  const nextPage = await fetchApiItems(nextLinkURL, nextLinkQuery);
-  items.push(...nextPage);
+  urlQuery.set("limit", maxNumber.toString());
+
+  const allItems = await axios
+    .get(itemsUrl + "?" + urlQuery.toString())
+    .then((resp) => resp.data.features)
+    .catch((err) => {
+      console.error(err);
+      return [];
+    });
+  items.splice(0, items.length, ...allItems);
+  itemsCache.set(cacheKey, items);
   return items;
 }
 /**
@@ -871,3 +1186,272 @@ export function extractEoxLegendLink(link) {
   }
   return extraProperties;
 }
+
+/**
+ * Locate the first sub-schema whose `format` matches by walking `properties`
+ * and the `oneOf` / `allOf` / `anyOf` combinators. Returns the schema path
+ * (array of keys/indices) from the root schema to the matched node, or
+ * undefined if not found. Empty array means the input schema itself matched.
+ *
+ * @param {Record<string, any> | null | undefined} schema
+ * @param {string} [format="bands"]
+ * @returns {(string | number)[] | undefined}
+ */
+export function getBandsProperty(schema, format = "bands") {
+  if (!schema || typeof schema !== "object") return undefined;
+  if (schema.format === format) return [];
+
+  if (schema.properties) {
+    for (const key of Object.keys(schema.properties)) {
+      const sub = getBandsProperty(schema.properties[key], format);
+      if (sub) return ["properties", key, ...sub];
+    }
+  }
+
+  for (const combinator of ["oneOf", "allOf", "anyOf"]) {
+    if (!Array.isArray(schema[combinator])) continue;
+    for (let i = 0; i < schema[combinator].length; i++) {
+      const sub = getBandsProperty(schema[combinator][i], format);
+      if (sub) return [combinator, i, ...sub];
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Checks whether a GeoZarr layer's bands changed in the jsonform output and,
+ * if so, rebuilds the source with the new 3 selected bands.
+ * Gamma and rescale are handled automatically by `applyUpdatedStyles` via
+ * `updateStyleVariables` — this function only manages source reconstruction.
+ * Uses the existing source constructor to avoid import-version mismatches.
+ *
+ * @param {import("ol/layer/Layer").default} olLayer - Layer from layerConfig:change event
+ * @param {Record<string, any>} jsonformValue - Current jsonform output
+ * @returns {boolean} true if the source was rebuilt
+ */
+export function updateGeoZarrBands(olLayer, jsonformValue) {
+  /** @type {import("@eox/map/src/layers").EOxLayerType<"WebGLTile","GeoZarr">} */
+  const jsonLayer = olLayer.get("_jsonDefinition");
+  const updatedBands = jsonformValue.bands;
+  const isGeoZarr =
+    jsonLayer?.type === "WebGLTile" && jsonLayer?.source?.type === "GeoZarr";
+  if (!jsonLayer || !jsonLayer.source || !isGeoZarr || !updatedBands) {
+    return false;
+  }
+
+  const oldBands = jsonLayer.source?.bands;
+  if (JSON.stringify(updatedBands) === JSON.stringify(oldBands)) {
+    return false;
+  }
+  jsonLayer.source.bands = [...updatedBands];
+  olLayer.setSource(
+    new window.eoxMapAdvancedOlSources.GeoZarr(jsonLayer.source),
+  );
+  return true;
+}
+
+/**
+ * Safely appends query parameters to a URL string, preserving templates like {z}/{x}/{y}
+ * @param {string} url
+ * @param {Record<string, string>} params
+ * @returns {string}
+ */
+function appendQueryParams(url, params) {
+  const [base, query] = url.split("?");
+  const searchParams = new URLSearchParams(query || "");
+
+  for (const [key, val] of Object.entries(params)) {
+    if (val !== undefined && val !== null && val !== "") {
+      searchParams.set(key, val);
+    } else {
+      searchParams.delete(key);
+    }
+  }
+
+  const newQuery = searchParams.toString();
+  return newQuery ? `${base}?${newQuery}` : base;
+}
+
+/**
+ * Checks whether a VectorTile layer's URL needs to be updated based on jsonform output.
+ * If the style's jsonform schema has properties with `url_key` defined, their values
+ * are injected as query parameters into the source URL.
+ *
+ * @param {import("ol/layer/Layer").default} olLayer - Layer from layerConfig:change event
+ * @param {Record<string, any>} jsonformValue - Current jsonform output
+ * @returns {boolean} true if the URL was updated
+ */
+export function updateLayerUrl(olLayer, jsonformValue) {
+  const jsonLayer = olLayer.get("_jsonDefinition");
+  if (!jsonLayer || jsonLayer.type !== "VectorTile") {
+    return false;
+  }
+
+  const schema = jsonLayer.properties?.layerConfig?.schema;
+  const urlKeys = extractUrlKeys(schema);
+
+  if (Object.keys(urlKeys).length === 0) {
+    return false;
+  }
+
+  let originalUrl = olLayer.get("originalUrl") || jsonLayer.source?.url;
+
+  if (!originalUrl || typeof originalUrl !== "string") {
+    return false;
+  }
+
+  if (!olLayer.get("originalUrl")) {
+    olLayer.set("originalUrl", originalUrl);
+  }
+
+  /** @type {Record<string, string>} */
+  const queryParamsToInject = {};
+  for (const [propName, urlKey] of Object.entries(urlKeys)) {
+    queryParamsToInject[urlKey] = jsonformValue[propName];
+  }
+
+  const newUrl = appendQueryParams(originalUrl, queryParamsToInject);
+
+  if (jsonLayer.source?.url) {
+    if (jsonLayer.source.url === newUrl) {
+      return false;
+    }
+    jsonLayer.source.url = newUrl;
+    if (olLayer.get("injectedUrl") === newUrl) {
+      return false;
+    }
+    const source = olLayer.getSource();
+    olLayer.set("injectedUrl", newUrl);
+    if (source && "setUrl" in source) {
+      /** @type {any} */ (source).setUrl(newUrl);
+      return true;
+    }
+    if (source && "setUrls" in source) {
+      /** @type {any} */ (source).setUrls([newUrl]);
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Applies titiler upscaling to an XYZ tile URL based on the matched endpoint config.
+ * - titiler v1: appends `@2x` to the `{y}` tile coordinate
+ * - titiler v2: adds `tilesize=512` query parameter (v2 removed the `@2x` suffix)
+ * Plain strings in the config default to v1 behavior for backward compatibility.
+ *
+ * @param {string} url - The XYZ tile URL template
+ * @param {Array<string | { url: string; titilerVersion?: 1 | 2 }>} upscalingEndpoints
+ * @returns {{ url: string; tileSize: [number, number] } | null} null if no endpoint matches
+ */
+export function applyTitilerUpscaling(url, upscalingEndpoints) {
+  const match = upscalingEndpoints.find((entry) => {
+    const endpointUrl = typeof entry === "string" ? entry : entry.url;
+    return url.includes(endpointUrl);
+  });
+
+  if (!match) {
+    return null;
+  }
+
+  const version = typeof match === "string" ? 1 : (match.titilerVersion ?? 1);
+
+  if (version === 2) {
+    const [base, query] = url.split("?");
+    const params = new URLSearchParams(query);
+    params.set("tilesize", "512");
+    return { url: `${base}?${params.toString()}`, tileSize: [512, 512] };
+  }
+
+  return { url: url.replace("{y}", "{y}@2x"), tileSize: [512, 512] };
+}
+
+/**
+ * Picks the render presets for a collection, preferring client-provided config
+ * (`options.renders[collectionId]`) and falling back to the collection's own STAC
+ * `renders` extension when no config entry exists.
+ * @param {import("stac-ts").StacCollection | null | undefined} collection
+ * @param {Record<string, Record<string, import("@/types").Render>> | undefined} [configRenders]
+ * @returns {Record<string, import("@/types").Render> | undefined}
+ */
+export function resolveRenders(collection, configRenders) {
+  const config = collection?.id ? configRenders?.[collection.id] : undefined;
+  if (config) return config;
+  return /** @type {Record<string, import("@/types").Render>|undefined} */ (
+    collection?.renders ?? undefined
+  );
+}
+
+/**
+ * TiTiler expects rescale as [min,max] pairs; chunks a flat numeric list
+ * into pairs (e.g. [0,0.4,0,0.1] -> [[0,0.4],[0,0.1]]). Nested input passes through.
+ * @param {number[]|number[][]|undefined} rescale - flat or nested rescale values
+ * @returns {number[][]|undefined} rescale as [min,max] pairs
+ */
+export function normalizeRescale(rescale) {
+  if (!rescale?.length || Array.isArray(rescale[0])) {
+    return /** @type {number[][]|undefined} */ (rescale);
+  }
+  const pairs = [];
+  for (let i = 0; i < rescale.length; i += 2) {
+    pairs.push(/** @type {number[]} */ (rescale).slice(i, i + 2));
+  }
+  return pairs;
+}
+
+/**
+ * Drops NaN nodata values; NaN is already the implicit fill for float data,
+ * so forwarding `nodata=nan` to TiTiler is redundant.
+ * @param {string|number|undefined} nodata - nodata value from render/asset metadata
+ * @returns {string|number|undefined} nodata, or undefined when it is NaN
+ */
+export function normalizeNodata(nodata) {
+  if (typeof nodata === "number" && Number.isNaN(nodata)) return undefined;
+  if (typeof nodata === "string" && nodata.trim().toLowerCase() === "nan")
+    return undefined;
+  return nodata;
+}
+
+/**
+ * Serializes an object into a TiTiler query string. Arrays repeat the key per
+ * element (TiTiler list params, e.g. `assets=a&assets=b`); nested elements
+ * comma-join (`rescale: [[0,1],[0,2]]` -> `rescale=0,1&rescale=0,2`); objects
+ * are JSON-encoded. Shared by the render-extension and mosaic paths.
+ * @param {Record<string,any>} obj
+ * @returns {string}
+ */
+export function encodeURLObject(obj) {
+  let str = "";
+  for (const key in obj) {
+    const value = obj[key];
+    if (value === null || value === undefined || value === "") {
+      continue;
+    }
+
+    const valueType = Array.isArray(value) ? "array" : typeof value;
+
+    switch (valueType) {
+      case "array": {
+        for (const val of value) {
+          if (Array.isArray(val)) {
+            str += `${key}=${val.join(",")}&`;
+          } else {
+            str += `${key}=${encodeURIComponent(val)}&`;
+          }
+        }
+        break;
+      }
+      case "object": {
+        str += `${key}=${encodeURI(JSON.stringify(value))}&`;
+        break;
+      }
+      default: {
+        str += `${key}=${encodeURIComponent(value)}&`;
+        break;
+      }
+    }
+  }
+  return str;
+}