GeoLeaf.Utils — Documentation du module Utils

Product Version : GeoLeaf Platform V2

Version : 2.0.0

Fichier source : packages/core/src/modules/utils/general/utils-api.ts

Dernière mise à jour : mars 2026

---

Vue d'ensemble

Le namespace GeoLeaf.Utils regroupe les fonctions utilitaires communes utilisées à travers tous les modules GeoLeaf. Il est assemblé dans utils-api.ts et expose :

• des fonctions de manipulation de données (deepMerge, resolveField, compareByOrder)
• des helpers HTTP (FetchHelper)
• des helpers d'animation (AnimationHelper)
• des utilitaires DOM et sécurité (DOMSecurity)
• des helpers cartographiques (ensureMap, fireMapEvent, getDistance)
• des contrôleurs de flux (debounce, throttle)

L'objet est publié sur window.GeoLeaf.Utils (ou globalThis.GeoLeaf.Utils) après initialisation.

---

Structure des modules

packages/core/src/modules/utils/
├── general/
│   ├── general-utils.ts          // Core utility functions
│   ├── utils-api.ts              // Assembler — exposes GeoLeaf.Utils
│   ├── dom-security.ts           // DOM sanitization helpers
│   ├── animation-helper.ts       // Animation utilities
│   └── fetch-helper.ts           // HTTP client with retry/timeout
├── constants/
│   └── index.ts                  // Frozen constants (CONSTANTS)
├── log/
│   └── index.ts                  // Log module
└── renderers/
    └── abstract-renderer.ts      // AbstractRenderer base class

---

API publique

validateUrl(url, allowedProtocols?)

Valide une URL via GeoLeaf.Security. Retourne la chaîne normalisée ou null.

const safe = GeoLeaf.Utils.validateUrl("https://example.com/data.json");
// => "https://example.com/data.json" | null

---

deepMerge(target, source)

Fusion profonde de deux objets. Protège contre les attaques prototype pollution (__proto__, constructor, prototype ignorés).

const merged = GeoLeaf.Utils.deepMerge(defaults, overrides);

---

mergeOptions(defaults, override)

Fusion superficielle (shallow) avec Object.assign. Préférer à deepMerge pour les options simples.

const opts = GeoLeaf.Utils.mergeOptions({ timeout: 5000, retries: 2 }, userOpts);

---

resolveField(obj, ...paths)

Résout le premier champ non-vide parmi une liste de chemins pointés.

const title = GeoLeaf.Utils.resolveField(poi, "title", "label", "name");
// => parcourt obj.title → obj.label → obj.name → "" si aucun

Supporte la notation imbriquée : "attributes.commune", "properties.name".

---

compareByOrder(a, b, fallback?)

Comparateur de tri pour les sections de layout. Trie par champ order (numérique).

const sorted = layout.sort(GeoLeaf.Utils.compareByOrder);

---

debounce(func, wait?, immediate?)

Retarde l'exécution d'une fonction jusqu'à la fin des appels rapides.

const onInput = GeoLeaf.Utils.debounce((e) => handleSearch(e), 300);

---

throttle(func, limit?)

Limite la fréquence d'exécution d'une fonction.

const onScroll = GeoLeaf.Utils.throttle(updateUI, 100);

---

getDistance(lat1, lng1, lat2, lng2)

Calcule la distance haversine entre deux points géographiques. Retourne la distance en kilomètres.

const km = GeoLeaf.Utils.getDistance(48.85, 2.35, 43.29, 5.38);

---

ensureMap(explicitMap?)

Résout l'instance carte MapLibre GL depuis GeoLeaf.Core.getMap() ou depuis un paramètre explicite.

const map = GeoLeaf.Utils.ensureMap(options.map);
if (map) {
    map.fitBounds(bounds);
}

---

fireMapEvent(map, eventName, payload?)

Émet un événement sur l'instance carte MapLibre GL (via map.fire()).

GeoLeaf.Utils.fireMapEvent(map, "geoleaf:layer:loaded", { layerId: "poi" });

---

DOMSecurity

Sous-module de sécurité DOM. Expose notamment :

• DOMSecurity.clearElementFast(el) — vide un élément sans innerHTML
• DOMSecurity.setSafeHTML(el, html) — injection HTML sanitisée

GeoLeaf.Utils.DOMSecurity.clearElementFast(container);

---

AnimationHelper

Helpers pour les animations CSS/JS (requestAnimationFrame, transitions). Voir animation-helper.ts.

---

FetchHelper

Client HTTP unifié avec retry, timeout et parsing automatique. Voir fetch-helper.ts.

const data = await GeoLeaf.Utils.FetchHelper.fetch("/api/data.json", {
    timeout: 10000,
    retries: 2,
});

---

escapeHtml(str) (déprécié)

Délègue à GeoLeaf.Security.escapeHtml. Conservé pour compatibilité ascendante — utiliser directement GeoLeaf.Security.escapeHtml().

---

Exemple complet

import { Utils } from "@geoleaf/core";

// Resolve the first non-empty field in a POI
const name = Utils.resolveField(poi, "title", "label", "name");

// Merge options with defaults
const opts = Utils.mergeOptions({ zoom: 10, padding: 20 }, userOptions);

// Debounce a search handler
const onSearch = Utils.debounce((query: string) => {
    const results = GeoLeaf.Search.query(query);
    renderResults([...results]);
}, 250);

// Compute distance between two coordinates
const distKm = Utils.getDistance(48.85, 2.35, 45.76, 4.83);

---

Modules liés

• packages/core/src/modules/utils/constants/index.ts — constantes globales (CONSTANTS)
• packages/core/src/modules/utils/renderers/abstract-renderer.ts — classe de base pour les renderers
• packages/core/src/modules/built-in/security/ — sanitisation XSS, validation URL
• packages/core/src/modules/built-in/config/ — accès à la configuration active

---

Version : 2.0.0

Dernière mise à jour : mars 2026