xcraft-core-utils 4.20.0 → 4.21.2

package/README.md

@@ -2,7 +2,7 @@
 
 ## Aperçu
 
-Le module `xcraft-core-utils` est une bibliothèque utilitaire centrale du framework Xcraft qui fournit un ensemble complet d'outils et de classes pour diverses opérations courantes. Il regroupe des utilitaires pour la manipulation de données, la cryptographie, la gestion de fichiers, les opérations asynchrones, la mise en cache, et bien plus encore.
+Le module `xcraft-core-utils` est une bibliothèque utilitaire centrale du framework Xcraft qui fournit un ensemble complet d'outils et de classes pour diverses opérations courantes. Il regroupe des utilitaires pour la manipulation de données, la cryptographie, la gestion de fichiers, les opérations asynchrones, la synchronisation, la mise en cache, les files d'attente de jobs, et bien plus encore.
 
 ## Sommaire
 
@@ -28,11 +28,12 @@ Le module expose une collection d'utilitaires organisés par domaine fonctionnel
 - **Cache et performance** : `RankedCache`
 - **Manipulation de chaînes** : `string`, `regex`
 - **Logging** : `log`
-- **Opérations asynchrones** : `async`
 
 ## Fonctionnement global
 
-Ce module agit comme une boîte à outils centralisée pour l'écosystème Xcraft. Chaque utilitaire est conçu pour être autonome tout en s'intégrant parfaitement avec les autres composants du framework. Les utilitaires supportent les patterns asynchrones avec `gigawatts` et sont optimisés pour les performances dans un environnement distribué.
+Ce module agit comme une boîte à outils centralisée pour l'écosystème Xcraft. Chaque utilitaire est conçu pour être autonome tout en s'intégrant parfaitement avec les autres composants du framework. Les utilitaires supportent les patterns asynchrones avec [gigawatts] et sont optimisés pour les performances dans un environnement distribué.
+
+Le module ne contient pas d'acteurs Elf ou Goblin : il s'agit uniquement d'une librairie utilitaire importée par d'autres modules.
 
 ## Exemples d'utilisation
 
@@ -41,14 +42,17 @@ Ce module agit comme une boîte à outils centralisée pour l'écosystème Xcraf
 ```javascript
 const {ArrayCollector} = require('xcraft-core-utils');
 
-const collector = new ArrayCollector(resp, 100, (entries, resp) => {
-  // Traitement des données collectées
-  console.log('Données collectées:', entries);
+const collector = new ArrayCollector(resp, 100, async (entries, resp) => {
+  // Traitement des données collectées par clé
+  for (const [key, values] of Object.entries(entries)) {
+    console.log(`Clé: ${key}`, values);
+  }
 });
 
-// Ajout de données
-collector.grab('key1', ['data1', 'data2']);
-collector.grab('key2', ['data3']);
+collector.grab('entityA', [{id: 1}]);
+collector.grab('entityA', [{id: 2}]);
+collector.grab('entityB', [{id: 3}]);
+// La fonction onCollect est déclenchée après 100ms maximum
 ```
 
 ### Gestion de files d'attente avec JobQueue
@@ -61,8 +65,11 @@ const runner = function* (job, next) {
   yield setTimeout(next, 1000);
 };
 
-const queue = new JobQueue('processing', runner, 3);
-queue.push({id: 1, data: 'example'});
+const queue = new JobQueue('processing', runner, 3, {
+  priorityGroup: 'highPrio',
+  waitOn: ['lowPrio'],
+});
+queue.push({id: 'job-1', payload: 'example'});
 ```
 
 ### Cryptographie et hachage
@@ -70,20 +77,38 @@ queue.push({id: 1, data: 'example'});
 ```javascript
 const {crypto, hash} = require('xcraft-core-utils');
 
-// Génération de mots de passe
+// Génération de mots de passe sécurisés
 const password = crypto.randomPassword(16);
 
-// Hachage d'objets
+// Entier aléatoire cryptographiquement sûr
+const roll = crypto.randomInt(1, 6);
+
+// Hachage déterministe d'un objet
 const objectHash = hash.computeHash({user: 'john', role: 'admin'});
 ```
 
-### API REST
+### Client REST
 
 ```javascript
 const {RestAPI} = require('xcraft-core-utils');
 
-const api = new RestAPI(30000);
-const data = await api._get('https://api.example.com/users');
+class MyApi extends RestAPI {
+  constructor() {
+    super(30000, {Authorization: 'Bearer token'});
+  }
+
+  async getUsers() {
+    return this._get('https://api.example.com/users');
+  }
+
+  async streamResults() {
+    const stream = await this._getStream('https://api.example.com/stream');
+    if (stream.error) throw stream.error;
+    for await (const item of stream) {
+      console.log(item);
+    }
+  }
+}
 ```
 
 ### Synchronisation avec locks
@@ -91,61 +116,99 @@ const data = await api._get('https://api.example.com/users');
 ```javascript
 const {locks} = require('xcraft-core-utils');
 
+// Mutex simple
 const mutex = new locks.Mutex();
-await mutex.lock();
+yield mutex.lock();
 try {
   // Section critique
 } finally {
   mutex.unlock();
 }
+
+// Mutex par clé (GetMutex global)
+yield locks.getMutex.lock('resource-id');
+try {
+  // Accès exclusif à la ressource 'resource-id'
+} finally {
+  locks.getMutex.unlock('resource-id');
+}
+
+// Exécution coalescente : seul le premier et le dernier appel concurrent s'exécutent
+const executor = new locks.CoalescingExecutor();
+await executor.run(async () => expensiveOperation());
 ```
 
-### Opérations asynchrones avec mapReduce
+### Traitement par lots avec Batcher
 
 ```javascript
-const {async} = require('xcraft-core-utils');
+const {Batcher} = require('xcraft-core-utils');
 
-const data = ['item1', 'item2', 'item3'];
-const result = yield async.mapReduce(
-  item => item.id,
-  item => processItem(item),
-  data
+const batcher = new Batcher(
+  async () => db.beginTransaction(),
+  async (count) => db.commit(),
+  500, // commit tous les 500 éléments
+  5000 // ou après 5s d'inactivité
 );
+
+await batcher.start();
+for (const record of records) {
+  await db.insert(record);
+  const shouldContinue = await batcher.bump();
+  if (!shouldContinue) break;
+}
+await batcher.stop();
+```
+
+### Cache LRU avec RankedCache
+
+```javascript
+const {RankedCache} = require('xcraft-core-utils');
+
+const cache = new RankedCache(100); // max 100 entrées
+cache.on('out', (item) => {
+  console.log('Élément évincé:', item.payload);
+});
+
+const item = cache.rank({id: 'style-1', css: '...'});
+// Promouvoir un élément existant
+cache.rank(item);
 ```
 
 ## Interactions avec d'autres modules
 
-- **[xcraft-core-log]** : Utilisé pour le logging avancé dans plusieurs utilitaires
-- **[xcraft-core-fs]** : Intégré pour les opérations sur le système de fichiers
-- **[xcraft-core-busclient]** : Utilisé par JobQueue pour les notifications d'événements
-- **[xcraft-traverse]** : Utilisé pour la traversée d'objets complexes
-- **[gigawatts]** : Support des générateurs et fonctions asynchrones
+- **[xcraft-core-log]** : Utilisé pour le logging dans `JobQueue` et d'autres utilitaires
+- **[xcraft-core-fs]** : Intégré pour les opérations sur le système de fichiers dans `batch` et `modules`
+- **[xcraft-core-busclient]** : Utilisé par `JobQueue` pour les notifications d'événements sur le bus Xcraft
+- **[xcraft-traverse]** : Utilisé pour la traversée d'objets complexes dans `hash`, `json` et `modules`
+- **[gigawatts]** : Support des générateurs et fonctions asynchrones dans les classes principales
 
 ### Variables d'environnement
 
-| Variable  | Description                                                         | Exemple                         | Valeur par défaut |
-| --------- | ------------------------------------------------------------------- | ------------------------------- | ----------------- |
-| `PATH`    | Chemin système utilisé par `whereIs` pour localiser les exécutables | `/usr/bin:/bin`                 | Variable système  |
-| `APPDATA` | Répertoire de données d'application sur Windows                     | `C:\Users\User\AppData\Roaming` | Variable système  |
+| Variable  | Description                                                                     | Exemple                         | Valeur par défaut |
+| --------- | ------------------------------------------------------------------------------- | ------------------------------- | ----------------- |
+| `PATH`    | Chemin système utilisé par `whereIs` pour localiser les exécutables             | `/usr/bin:/bin`                 | Variable système  |
+| `APPDATA` | Répertoire de données d'application sur Windows (utilisé par `os.getAppData()`) | `C:\Users\User\AppData\Roaming` | Variable système  |
 
 ## Détails des sources
 
 ### `arrayCollector.js`
 
-Classe pour collecter des données par clés avec un mécanisme de throttling. Permet d'accumuler des données et de les traiter par lots à intervalles réguliers. Supporte les modes synchrone et asynchrone.
+Classe pour collecter des données par clés avec un mécanisme de throttling. Permet d'accumuler des données et de les traiter par lots à intervalles réguliers. Supporte les modes synchrone et asynchrone via le paramètre `async` du constructeur.
+
+En mode synchrone, le callback `onCollect` est wrappé avec `gigawatts` pour supporter les générateurs. En mode asynchrone, il est appelé avec `await` directement.
 
 #### Méthodes publiques
 
-- **`grab(key, data)`** — Ajoute des données à la collection sous une clé spécifique et déclenche le traitement si nécessaire.
-- **`cancel()`** — Annule le traitement en attente.
+- **`grab(key, data)`** — Ajoute des données à la collection sous une clé spécifique (par concaténation) et déclenche le traitement throttlé.
+- **`cancel()`** — Annule le traitement en attente (throttle en cours).
 
 ### `async.js`
 
-Classe utilitaire pour les opérations asynchrones avancées qui évitent de bloquer la boucle d'événements principale.
+Module exportant une instance singleton avec des utilitaires pour les opérations asynchrones qui évitent de bloquer la boucle d'événements principale.
 
 #### Méthodes publiques
 
-- **`mapReduce(keyFunc, valueFunc, list)`** — Réduit un tableau en map avec itération asynchrone pour éviter de bloquer la boucle d'événements sur de gros volumes de données.
+- **`mapReduce(keyFunc, valueFunc, list)`** — Réduit un tableau en map avec itération asynchrone. Utile pour les très grandes collections où chaque item est traité via une `Promise`, libérant la boucle d'événements entre les itérations.
 
 ### `batch.js`
 
@@ -153,92 +216,100 @@ Fonction utilitaire pour exécuter une action sur tous les fichiers d'un répert
 
 #### Méthodes publiques
 
-- **`run(filter, location, callbackAction)`** — Parcourt récursivement un répertoire et exécute une action sur les fichiers correspondant au filtre.
+- **`run(filter, location, callbackAction)`** — Parcourt récursivement un répertoire et exécute `callbackAction` sur les fichiers dont le nom correspond au filtre regex. Les sous-répertoires sont traités récursivement.
 
 ### `batcher.js`
 
-Gestionnaire de traitement par lots avec support de timeout et de seuils de déclenchement. Idéal pour optimiser les opérations de base de données ou les écritures sur disque.
+Gestionnaire de traitement par lots avec support de timeout et de seuils de déclenchement. Idéal pour optimiser les opérations coûteuses comme les transactions de base de données ou les écritures disque en regroupant les appels.
+
+Le Batcher maintient une session entre `start()` et `stop()`. La méthode `bump()` incrémente le compteur et déclenche automatiquement un `stop()`/`start()` quand le seuil `batch` est atteint ou quand le timeout expire. La méthode `pump()` vérifie uniquement le timeout via un `setImmediate`.
 
 #### Méthodes publiques
 
-- **`start()`** — Démarre une nouvelle session de traitement par lots.
-- **`bump()`** — Incrémente le compteur et déclenche le commit si le seuil est atteint.
-- **`pump()`** — Force le commit si le timeout est atteint.
-- **`stop()`** — Termine la session et exécute le commit final.
-- **`dispose()`** — Marque le batcher pour destruction.
+- **`start()`** — Démarre une nouvelle session : appelle `begin()` et arme le timer de timeout.
+- **`bump()`** — Incrémente le compteur et déclenche un cycle commit/restart si le seuil ou le timeout est atteint. Retourne `false` si le batcher est en cours de destruction.
+- **`pump()`** — Cède le contrôle via `setImmediate` puis déclenche un cycle si le timeout est atteint. Retourne `false` si destruction en cours.
+- **`stop()`** — Termine la session courante en appelant `commit(count)` avec le nombre d'éléments traités.
+- **`dispose()`** — Marque le batcher pour destruction ; les prochains appels à `bump()`/`pump()` déclencheront l'arrêt.
 
 ### `crypto.js`
 
-Utilitaires cryptographiques pour le hachage, la génération de tokens et de mots de passe sécurisés.
+Utilitaires cryptographiques pour le hachage, la génération de tokens et de mots de passe sécurisés. Utilise le module natif `node:crypto` pour garantir la qualité cryptographique des nombres aléatoires.
+
+L'algorithme de génération d'entiers aléatoires (`randomInt`) utilise un rejet des valeurs hors plage pour garantir une distribution uniforme sans biais statistique.
 
 #### Méthodes publiques
 
-- **`md5(data)`** — Calcule le hash MD5 des données.
-- **`sha256(data)`** — Calcule le hash SHA256 des données.
-- **`genToken()`** — Génère un token UUID sans tirets.
-- **`randomInt(min, max)`** — Génère un entier aléatoire cryptographiquement sûr dans la plage spécifiée.
-- **`randomChar(chars)`** — Génère un caractère aléatoire à partir d'un ensemble de caractères.
-- **`randomPassword(length=12, chars)`** — Génère un mot de passe aléatoire sécurisé.
+- **`md5(data)`** — Calcule le hash MD5 des données (retourne une chaîne hexadécimale).
+- **`sha256(data)`** — Calcule le hash SHA256 des données (retourne une chaîne hexadécimale).
+- **`genToken()`** — Génère un token UUID v4 sans tirets (32 caractères hexadécimaux).
+- **`randomInt(min, max)`** — Génère un entier aléatoire cryptographiquement sûr dans `[min, max]`. Lève une erreur si la plage dépasse `2^31 - 1`.
+- **`randomChar(chars)`** — Génère un caractère aléatoire à partir d'un ensemble (défaut : alphanumérique + symboles sans caractères ambigus).
+- **`randomPassword(length=12, chars)`** — Génère un mot de passe aléatoire sécurisé de la longueur spécifiée.
 
 ### `cursorPump.js`
 
-Wrapper pour les curseurs de base de données permettant de pomper les données de manière asynchrone.
+Wrapper pour les curseurs de base de données permettant de pomper les données de manière asynchrone avec [gigawatts]. Le curseur doit implémenter une méthode `next()` qui rejette sa promesse en fin de données.
 
 #### Méthodes publiques
 
-- **`toArray()`** — Convertit toutes les données du curseur en tableau.
-- **`pump()`** — Récupère le prochain élément du curseur.
+- **`toArray()`** — Consomme intégralement le curseur et retourne toutes les lignes dans un tableau.
+- **`pump()`** — Récupère le prochain élément du curseur (lève une exception en fin de curseur).
 
 ### `eventDebouncer.js`
 
-Classe pour débouncer l'envoi d'événements, évitant les envois trop fréquents du même type d'événement.
+Classe pour débouncer l'envoi d'événements sur le bus Xcraft, évitant les envois trop fréquents pour un même topic. Un debouncer distinct est créé par topic à la première utilisation.
 
 #### Méthodes publiques
 
-- **`publish(topic, data)`** — Publie un événement avec debouncing automatique.
+- **`publish(topic, data)`** — Publie un événement avec debouncing automatique. Les appels répétés dans la fenêtre `wait` (défaut 1000ms) sont fusionnés, seul le dernier est envoyé.
 
 ### `file-crypto.js`
 
-Utilitaires cryptographiques pour les fichiers.
+Utilitaires cryptographiques pour les fichiers, utilisant des streams pour éviter de charger le fichier entier en mémoire.
 
 #### Méthodes publiques
 
-- **`fileChecksum(filePath, options)`** — Calcule la somme de contrôle d'un fichier avec l'algorithme spécifié.
+- **`fileChecksum(filePath, options)`** — Calcule la somme de contrôle d'un fichier. `options.algorithm` (défaut `sha1`) et `options.encoding` (défaut `hex`) sont configurables. Lève une erreur si le chemin ne désigne pas un fichier.
 
 ### `files.js`
 
-Utilitaires pour la détection de types de fichiers et l'analyse MIME avec une base de données complète d'extensions.
+Utilitaires pour la détection de types de fichiers. Contient une base de données statique d'extensions couvrant audio, archives, images, documents, code source, vidéos, etc.
 
 #### Méthodes publiques
 
-- **`getFileFilter(filePath)`** — Retourne le filtre de fichier basé sur l'extension.
-- **`getMimeType(filePath)`** — Détecte le type MIME et l'encodage d'un fichier en utilisant libmagic.
+- **`getFileFilter(filePath)`** — Retourne `{name, extensions}` basé sur l'extension du fichier. Retourne `{name: '?', extensions: [ext]}` si l'extension est inconnue.
+- **`getMimeType(filePath)`** — Détecte le type MIME et le charset d'un fichier en utilisant libmagic (`@npcz/magic`). Retourne `{mime, charset}`. Préserve l'atime sur macOS et Linux.
 
 ### `hash.js`
 
-Calcul de hash SHA256 pour des objets JavaScript complexes avec traversée récursive.
+Calcul de hash SHA256 déterministe pour des objets JavaScript complexes en traversant récursivement toutes les feuilles de l'arbre d'objets.
+
+Seules les valeurs de type `number`, `string` et `boolean` contribuent au hash. Les chaînes vides sont remplacées par `\0` pour les distinguer de `null`/`undefined` (qui sont ignorés).
 
 #### Méthodes publiques
 
-- **`computeHash(payload)`** — Calcule un hash déterministe d'un objet JavaScript en traversant récursivement ses propriétés.
+- **`computeHash(payload)`** — Calcule un hash SHA256 hexadécimal d'un objet JavaScript en traversant récursivement ses propriétés feuilles.
 
-### `jobQueue.js`
+### `job-queue.js`
 
-Système de files d'attente avancé avec support de priorités, limitations de parallélisme, gestion des dépendances entre groupes et mécanismes de retry.
+Système de files d'attente avancé avec support de priorités, limitations de parallélisme, gestion des dépendances entre groupes et mécanismes de retry. Les jobs sont stockés dans une `Map` (préservation d'ordre d'insertion). L'exécution réelle est déléguée au singleton `runnerInstance`.
+
+Les notifications de débit sont émises sur l'événement `<job-queue.sampled>` via le bus Xcraft, avec throttling à 500ms.
 
 #### Méthodes publiques
 
-- **`push(job)`** — Ajoute un job à la file d'attente.
-- **`dispose()`** — Nettoie la file d'attente et envoie les événements de fin.
+- **`push(job)`** — Ajoute un job à la file d'attente (le job doit avoir une propriété `id`). Planifie une exécution via `setTimeout(..., 0)`.
+- **`dispose()`** — Nettoie la file : émet l'événement `<job-queue.disposed>` et remet le compteur de samples à zéro.
 
 ### `js.js`
 
-Utilitaires pour l'introspection de fonctions JavaScript.
+Utilitaires légers pour l'introspection de fonctions JavaScript.
 
 #### Méthodes publiques
 
 - **`isFunction(fn)`** — Vérifie si l'argument est une fonction.
-- **`isGenerator(fn)`** — Vérifie si l'argument est une fonction générateur.
+- **`isGenerator(fn)`** — Vérifie si l'argument est une fonction générateur (`function*`).
 - **`isAsync(fn)`** — Vérifie si l'argument est une fonction async.
 
 ### `json.js`
@@ -249,161 +320,174 @@ Utilitaires pour la manipulation de fichiers JSON et la transformation de struct
 
 - **`fromFile(jsonFile)`** — ⚠️ Déprécié : utiliser `fse.readJSONSync` à la place.
 - **`toFile(json, destFile)`** — ⚠️ Déprécié : utiliser `fse.writeJSONSync` à la place.
-- **`dotKeysToObject(json)`** — Convertit les clés avec points en objets imbriqués.
+- **`dotKeysToObject(json)`** — Convertit les clés avec points en objets imbriqués. Exemple : `{"foo.bar": true}` devient `{foo: {bar: true}}`. Supporte les chemins imbriqués arbitrairement profonds et les tableaux.
 
 ### `locks.js`
 
-Implémentations de primitives de synchronisation : mutex, sémaphores et mutex récursifs avec support des générateurs.
-
-#### Classes et méthodes
+Implémentations de primitives de synchronisation compatibles avec le pattern générateur [gigawatts].
 
-- **`Mutex`** — Mutex simple avec méthodes `lock()` et `unlock()`.
-- **`RecursiveMutex`** — Mutex récursif supportant les verrous imbriqués par le même propriétaire.
-- **`Semaphore`** — Sémaphore avec méthodes `wait()` et `signal()`.
-- **`getMutex`** — Gestionnaire global de mutex par clé avec méthodes `lock(key)` et `unlock(key)`.
+- **`Mutex`** — Mutex simple. Méthodes : `*lock(next)` et `unlock()`. Propriété `isLocked`.
+- **`RecursiveMutex`** — Mutex récursif : un même `owner` peut verrouiller plusieurs fois sans deadlock. `unlock(owner)` doit être appelé autant de fois que `lock(owner)`.
+- **`Semaphore`** — Sémaphore avec valeur initiale configurable. Méthodes : `*wait(next)` et `signal()`.
+- **`GetMutex`** (instance exportée comme `getMutex`) — Gestionnaire de mutex nommés : crée et détruit automatiquement les mutex par clé. Méthodes : `*lock(key)` et `unlock(key)`.
+- **`CoalescingExecutor`** — Exécuteur coalescent : si plusieurs appels concurrents arrivent, seuls le premier et le dernier s'exécutent (les intermédiaires sont abandonnés). Méthode : `async run(work)`.
 
 ### `log.js`
 
-Utilitaires de formatage et de décoration pour les logs avec support des couleurs, de l'indentation et de la détection de logs imbriqués.
+Utilitaires de formatage et de décoration pour les logs avec support des couleurs ANSI, de l'indentation adaptative et de la détection de logs imbriqués. Utilisé par `xcraft-core-log`.
 
 #### Méthodes publiques
 
-- **`decorate(mode, prefix, mod, log, maxWidth, stripBegin)`** — Formate un message de log avec couleurs et indentation intelligente.
-- **`graffiti(text, callback)`** — Génère du texte ASCII art avec la police Graffiti et colorisation.
-- **`getIndent()`** — Retourne l'indentation actuelle.
-- **`computeIndent(prefix, mod)`** — Calcule l'indentation nécessaire pour un préfixe et module donnés.
+- **`decorate(mode, prefix, mod, log, maxWidth, stripBegin)`** — Formate un message de log avec alignement dynamique, retour à la ligne automatique selon la largeur du terminal, et détection des logs embarqués.
+- **`graffiti(text, callback)`** — Génère du texte ASCII art avec la police Graffiti (via `figlet`) et colorise les caractères `_`, `/`, `\` en vert/gris.
+- **`getIndent()`** — Retourne la valeur d'indentation globale courante.
+- **`computeIndent(prefix, mod)`** — Calcule le nombre d'espaces nécessaires pour aligner les messages et met à jour l'indentation globale si nécessaire.
 
 ### `mapAggregator.js`
 
-Classe pour agréger des données dans une structure de map avec throttling.
+Classe pour agréger des données dans une structure de map imbriquée avec throttling. Contrairement à `ArrayCollector`, `MapAggregator` écrase les valeurs existantes plutôt que de les concaténer.
 
 #### Méthodes publiques
 
-- **`put(keys, data)`** — Ajoute des données à la map en utilisant un chemin de clés.
-- **`release()`** — Force la libération immédiate des données agrégées.
+- **`put(keys, data)`** — Ajoute `data` dans la map en suivant le chemin `keys` (tableau ou chaîne avec points). Déclenche le throttle de libération.
+- **`release()`** — Force la libération immédiate des données agrégées vers le callback `onCollect`.
 
 ### `modules.js`
 
-Utilitaires pour la gestion des modules et configurations d'applications Xcraft avec support des variantes et surcharges.
+Utilitaires pour la gestion des modules et configurations d'applications Xcraft avec support des variantes de déploiement et des surcharges de configuration.
+
+La fonction `extractForEtc` gère les surcharges `@appId` dans `app.json` pour fusionner les configurations multi-applications. Les valeurs `-0` dans les JSON de configuration sont des marqueurs spéciaux pour revenir aux valeurs par défaut du `config.js` de chaque module.
 
 #### Méthodes publiques
 
-- **`extractForEtc(appDir, appId, variantId)`** — Extrait la configuration pour xcraft-core-etc.
-- **`loadAppConfig(appId, appDir, configJson, variantId)`** — Charge la configuration d'une application avec ses dépendances.
-- **`extractAllDeps(appId, libDir, configJson)`** — Extrait toutes les dépendances d'une application récursivement.
-- **`extractAllJs(libDir, modules)`** — Extrait tous les fichiers JavaScript des modules spécifiés.
+- **`mergeOverloads(obj, overloads)`** — Fusionne `overloads` dans `obj` en préservant les tableaux (non-fusion récursive des arrays).
+- **`extractForEtc(appDir, appId, variantId)`** — Extrait et fusionne la configuration d'une application pour `xcraft-core-etc`, en appliquant les surcharges de variante et les configs `@appId`.
+- **`loadAppConfig(appId, appDir, configJson, variantId)`** — Charge récursivement la configuration d'une application et de toutes ses hordes.
+- **`extractConfigDeps(libDir, configJson)`** — Extrait les dépendances de modules déclarées dans les configs serveur.
+- **`extractAllDeps(appId, libDir, configJson)`** — Résout récursivement toutes les dépendances Xcraft d'une application.
+- **`extractAllJs(libDir, modules)`** — Retourne la liste de tous les fichiers `.js` des modules spécifiés (hors `node_modules`, `test`, `species`).
 
 ### `os.js`
 
-Utilitaires pour les opérations système multi-plateformes.
+Utilitaire pour les chemins de données d'application multi-plateformes.
 
 #### Méthodes publiques
 
-- **`getAppData()`** — Retourne le répertoire de données d'application approprié selon la plateforme.
+- **`getAppData()`** — Retourne `%APPDATA%` sur Windows, `~/Library/Application Support` sur macOS, `~/.local/share` sur Linux.
 
 ### `prop-types.js`
 
-Générateurs de PropTypes pour les composants React avec support des types étendus Xcraft.
+Générateurs de PropTypes React avec support des types étendus du système de design Xcraft (couleurs, espacements, glyphes, types Nabu, etc.).
+
+Le type `nabu` valide que la prop est soit une chaîne, un nombre, soit un objet avec `nabuId` ou `_type: 'translatableString'/'translatableMarkdown'` (supportant aussi les `Map`/`OrderedMap` Immutable.js).
 
 #### Méthodes publiques
 
-- **`makePropTypes(props)`** — Génère un objet PropTypes à partir d'une définition de propriétés.
-- **`makeDefaultProps(props)`** — Génère un objet de propriétés par défaut.
+- **`makePropTypes(props)`** — Génère un objet `propTypes` React à partir d'une définition de propriétés Xcraft. Applique `.isRequired` si `prop.required` est vrai.
+- **`makeDefaultProps(props)`** — Génère un objet `defaultProps` React à partir des `defaultValue` de la définition.
 
-### `rankedCache.js`
+### `ranked-cache.js`
 
-Cache LRU (Least Recently Used) basé sur une liste chaînée avec émission d'événements lors de l'éviction.
+Cache LRU (Least Recently Used) basé sur une liste doublement chaînée avec émission d'événements lors de l'éviction. Les éléments les moins récemment utilisés migrent vers la tête de liste et sont évincés en premier quand la limite est atteinte.
+
+Un `RankedCache` avec `limit <= 0` retourne toujours `null` sans stocker quoi que ce soit.
 
 #### Méthodes publiques
 
-- **`rank(item)`** — Ajoute ou met à jour un élément dans le cache avec promotion automatique.
-- **`clear()`** — Vide complètement le cache en émettant des événements 'out'.
+- **`rank(item)`** — Ajoute un nouvel item (valeur brute ou `LinkedList.Item`) ou promeut un item existant d'un cran dans la liste. Émet `'out'` avec l'item évincé si la limite est atteinte.
+- **`clear()`** — Vide entièrement le cache en émettant `'out'` pour chaque item.
 
 ### `reflect.js`
 
-Utilitaires de réflexion pour l'introspection de fonctions JavaScript.
+Utilitaires de réflexion pour l'introspection de code JavaScript.
+
+`funcParams` gère correctement les valeurs par défaut complexes (expressions imbriquées, chaînes avec parenthèses), les commentaires, et les fonctions fléchées avec ou sans parenthèses.
 
 #### Méthodes publiques
 
-- **`funcParams(func)`** — Extrait les noms des paramètres d'une fonction en gérant les valeurs par défaut et les commentaires.
+- **`funcParams(func)`** — Extrait les noms des paramètres d'une fonction sous forme de tableau de chaînes, en supprimant les valeurs par défaut et les commentaires.
+- **`parseOptions(args)`** — Parse une chaîne d'options CLI en tableau en gérant les espaces échappés, les guillemets simples et doubles, et les guillemets imbriqués.
 
 ### `regex.js`
 
-Utilitaires pour la manipulation d'expressions régulières.
+Utilitaires pour la manipulation d'expressions régulières avec support des patterns Axon et Xcraft.
 
 #### Méthodes publiques
 
-- **`toRegexp(value)`** — Convertit une valeur en expression régulière.
-- **`toAxonRegExpStr(str)`** — Convertit une chaîne avec wildcards en pattern regex pour Axon.
-- **`toXcraftRegExpStr(str)`** — Convertit une chaîne avec wildcards en pattern regex pour Xcraft.
+- **`toRegexp(value)`** — Convertit une chaîne en `RegExp` ancrée (`^...$`) ou retourne la valeur si c'est déjà un `RegExp`.
+- **`toAxonRegExpStr(str)`** — Convertit une chaîne avec wildcards `*` en pattern regex pour le système de messagerie Axon.
+- **`toXcraftRegExpStr(str)`** — Convertit une chaîne avec wildcards `*` et groupes `(...)` en pattern regex pour le bus Xcraft.
 
 ### `rest.js`
 
-Client REST avancé avec support des streams, retry automatique, gestion d'erreurs enrichie et throttling des requêtes.
+Client REST avancé basé sur [got] avec support des streams JSON, retry automatique sur HTTP 429 (avec respect du header `Retry-After`), et enrichissement des erreurs avec l'URL et le corps de la réponse.
+
+Les méthodes de stream utilisent `JSONStream.parse('*')` pour émettre chaque élément d'un tableau JSON au fil de la réception. Les erreurs de stream sont capturées dans `stream.error` et doivent être testées explicitement après la consommation du stream.
 
 #### Méthodes publiques
 
-- **`_get(query)`** — Effectue une requête GET et retourne le body.
-- **`_getWithHeaders(query)`** — Effectue une requête GET et retourne body et headers.
-- **`_post(query, payload, options)`** — Effectue une requête POST avec payload JSON.
-- **`_delete(query)`** — Effectue une requête DELETE.
-- **`_patch(query, payload)`** — Effectue une requête PATCH.
-- **`_putForm(query, formData)`** — Effectue une requête PUT avec données de formulaire.
-- **`_getStream(query, json=true)`** — Retourne un stream pour une requête GET.
-- **`_postStream(query, payload, json=true)`** — Retourne un stream pour une requête POST.
-- **`_streamPostStream(query, stream, json=true)`** — Envoie un stream et retourne un stream.
+- **`_get(query)`** — Requête GET, retourne le body parsé.
+- **`_getWithHeaders(query)`** — Requête GET, retourne `{body, headers}`.
+- **`_post(query, payload, options={})`** — Requête POST avec payload JSON.
+- **`_delete(query)`** — Requête DELETE.
+- **`_patch(query, payload)`** — Requête PATCH avec payload JSON.
+- **`_putForm(query, formData)`** — Requête PUT avec données de formulaire (sans header `content-type`).
+- **`_getStream(query, json=true)`** — Retourne un stream GET ; si `json=true`, parse le JSON à la volée.
+- **`_postStream(query, payload, json=true)`** — Retourne un stream POST avec payload JSON.
+- **`_streamPostStream(query, stream, json=true)`** — Envoie un stream en corps de requête POST et retourne un stream de réponse.
 
 ### `runnerInstance.js`
 
-Singleton global pour la gestion des files d'attente de jobs avec support des priorités et dépendances.
-
-#### Fonctionnalités
+Singleton global (via `Symbol.for`) qui orchestre l'exécution des `JobQueue`. Il gère le parallélisme, les groupes de priorité et les dépendances entre groupes. Son unicité est garantie même si le module est chargé plusieurs fois dans des contextes différents.
 
-- Gestion centralisée de l'exécution des jobs
-- Support des groupes de priorité
-- Gestion des dépendances entre groupes
-- Limitation du parallélisme par queue
+L'algorithme de priorité suspend les jobs d'une queue si un groupe listé dans `waitOn` est actuellement en cours d'exécution, avec retry configurable (`maxAttempt`, `waitDelay`).
 
 ### `string.js`
 
-Utilitaires de manipulation de chaînes de caractères.
+Utilitaires légers de manipulation de chaînes.
 
 #### Méthodes publiques
 
-- **`camelcasify(str)`** — Convertit les points en camelCase.
-- **`capitalize(str)`** — Met en forme la première lettre en majuscule.
-- **`jsify(str)`** — Convertit les tirets en camelCase.
+- **`camelcasify(str)`** — Convertit les segments séparés par des points en camelCase (ex: `foo.bar` → `fooBar`).
+- **`capitalize(str)`** — Met la première lettre en majuscule et le reste en minuscules.
+- **`jsify(str)`** — Convertit les tirets en camelCase (ex: `foo-bar` → `fooBar`).
 
 ### `whereIs.js`
 
-Utilitaire pour localiser des exécutables dans le PATH système.
+Utilitaire pour localiser des exécutables dans le `PATH` système.
 
 #### Méthodes publiques
 
-- **`whereIs(bin)`** — Recherche un exécutable dans le PATH et retourne son chemin complet.
+- **`whereIs(bin)`** — Recherche un exécutable dans chaque répertoire du `PATH` et retourne le premier chemin complet trouvé, ou `null` si absent.
 
 ### `yaml.js`
 
-Utilitaires pour la manipulation de fichiers YAML.
+Utilitaires pour la manipulation de fichiers YAML via `js-yaml`.
 
 #### Méthodes publiques
 
-- **`fromFile(yamlFile)`** — Charge et parse un fichier YAML.
+- **`fromFile(yamlFile)`** — Charge et parse un fichier YAML, retourne l'objet JavaScript correspondant.
+- **`toFile(data, yamlFile)`** — Sérialise un objet en YAML et l'écrit dans un fichier (largeur de ligne 999 pour limiter les retours à la ligne).
 
 ### `zippy.js`
 
-Utilitaire pour créer des archives ZIP avec support du chiffrement.
+Utilitaire pour créer des archives ZIP à partir d'une liste de fichiers vers un stream de sortie Node.js, avec support du chiffrement par mot de passe.
+
+Utilise `@zip.js/zip.js` avec conversion des streams Node.js en Web Streams API via `Readable.toWeb` et `Writable.toWeb`.
 
 #### Méthodes publiques
 
-- **`zippy(files, outputStream, options)`** — Crée une archive ZIP à partir d'une liste de fichiers vers un stream de sortie avec support optionnel du chiffrement par mot de passe.
+- **`zippy(files, outputStream, options)`** — Crée une archive ZIP. `files` est un tableau de chemins absolus. `options` peut contenir `password` (string) et `zipCrypto` (boolean) pour le chiffrement.
 
----
+## Licence
 
-_Ce document a été mis à jour pour refléter l'état actuel du code source._
+Ce module est distribué sous [licence MIT](./LICENSE).
 
 [xcraft-core-log]: https://github.com/Xcraft-Inc/xcraft-core-log
 [xcraft-core-fs]: https://github.com/Xcraft-Inc/xcraft-core-fs
 [xcraft-core-busclient]: https://github.com/Xcraft-Inc/xcraft-core-busclient
 [xcraft-traverse]: https://github.com/Xcraft-Inc/xcraft-traverse
-[gigawatts]: https://github.com/Xcraft-Inc/gigawatts
+[gigawatts]: https://github.com/Xcraft-Inc/gigawatts
+[got]: https://github.com/sindresorhus/got
+
+_Ce contenu a été généré par IA_

package/lib/batcher.js

@@ -28,6 +28,10 @@ class Batcher {
     }
   }
 
+  #tick() {
+    return new Promise((resolve) => setImmediate(resolve));
+  }
+
   async start() {
     this.#running = true;
     await this.#begin();
@@ -51,6 +55,8 @@ class Batcher {
   }
 
   async pump() {
+    await this.#tick();
+
     if (this.#disposing) {
       await this.stop();
       return false;

package/lib/locks.js

@@ -100,9 +100,39 @@ class GetMutex {
   }
 }
 
+class CoalescingExecutor {
+  #running;
+  #pending;
+
+  async run(work) {
+    if (this.#running) {
+      /* Keep the last one */
+      this.#pending = work;
+      await this.#running;
+      return;
+    }
+
+    /* The first */
+    this.#running = (async () => {
+      await work();
+
+      /* Run the last if exists */
+      while (this.#pending) {
+        const last = this.#pending;
+        this.#pending = null;
+        await last();
+      }
+    })();
+
+    await this.#running;
+    this.#running = null;
+  }
+}
+
 module.exports = {
   Mutex,
   RecursiveMutex,
   Semaphore,
+  CoalescingExecutor,
   getMutex: new GetMutex(),
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xcraft-core-utils",
-  "version": "4.20.0",
+  "version": "4.21.2",
   "description": "Xcraft utils",
   "main": "index.js",
   "engines": {

package/test/hash.spec.js

@@ -3,7 +3,7 @@
 const {expect} = require('chai');
 const {computeHash} = require('../lib/hash.js');
 
-describe('goblin.yennefer.hash', function () {
+describe('xcraft.utils.hash', function () {
   it('string', function () {
     const objL = {string: 'Roger'};
     const objR = {string: 'Wilco'};

package/test/locks.spec.js

@@ -0,0 +1,35 @@
+'use strict';
+
+const {expect} = require('chai');
+const {CoalescingExecutor} = require('../lib/locks.js');
+const {setTimeout: setTimeoutAsync} = require('node:timers/promises');
+
+describe('xcraft.utils.locks', function () {
+  it('barrier', async function () {
+    const results = [];
+    const promises = [];
+    const barrier = new CoalescingExecutor();
+
+    promises.push(
+      barrier.run(async () => {
+        await setTimeoutAsync(100);
+        results.push(0);
+      })
+    );
+    promises.push(
+      barrier.run(async () => {
+        await setTimeoutAsync(20);
+        results.push(1);
+      })
+    );
+    promises.push(
+      barrier.run(async () => {
+        await setTimeoutAsync(100);
+        results.push(2);
+      })
+    );
+
+    await Promise.all(promises);
+    expect(results).to.deep.equal([0, 2]);
+  });
+});