📘 xcraft-core-subst

Aperçu

Le module xcraft-core-subst est une bibliothèque utilitaire du framework Xcraft qui permet de gérer les substitutions de lecteurs sous Windows. Il offre une solution élégante pour contourner les limitations de longueur de chemin sous Windows (260 caractères) en montant temporairement des chemins longs sur des lettres de lecteur disponibles.

Sommaire

• Structure du module
• Fonctionnement global
• Exemples d'utilisation
• Interactions avec d'autres modules
• Détails des sources
• Licence

Structure du module

Le module expose trois composants principaux :

• Subst : Classe principale pour gérer les substitutions de lecteurs Windows
• wrap : Fonction utilitaire pour exécuter du code avec un chemin substitué temporairement
• wrapTmp : Fonction utilitaire pour créer des copies temporaires dans un répertoire avec chemin court

Fonctionnement global

Le module résout spécifiquement le problème des chemins trop longs sous Windows (> 260 caractères ou < 32 caractères pour déclencher la substitution). Il utilise la commande système subst de Windows pour associer un chemin long à une lettre de lecteur, permettant ainsi d'accéder aux fichiers via un chemin plus court.

Algorithme de sélection de lecteur :

1. Commence par la lettre 'z' et descend dans l'alphabet
2. Vérifie la disponibilité avec net use (code de retour 2 = disponible)
3. Effectue la substitution avec subst (code de retour 0 = succès)
4. Si aucune lettre n'est disponible jusqu'à 'a', lève une exception

Comportement multi-plateforme :

• Windows : Substitution active pour les chemins ≥ 32 caractères
• Autres OS : Mode passthrough, retourne les chemins d'origine sans modification

Exemples d'utilisation

Utilisation directe de la classe Subst

const {Subst} = require('xcraft-core-subst');

// Avec générateurs (style Xcraft)
function* processLongPath(resp) {
  const subst = new Subst('/chemin/tres/long/vers/un/dossier', resp);
  const drive = yield subst.mount();

  try {
    // Utiliser le lecteur monté (ex: 'z:')
    resp.log.info(`Chemin substitué : ${drive}`);
    // Traitement des fichiers...
  } finally {
    yield subst.umount();
  }
}

Utilisation avec la fonction wrap

const {wrap} = require('xcraft-core-subst');

// Traitement automatique avec gestion du cycle de vie
function* processFile(resp) {
  const result = yield wrap(
    '/chemin/tres/long/vers/un/fichier.txt',
    resp,
    function* (err, shortPath, next) {
      if (err) throw err;

      // shortPath est maintenant 'z:/fichier.txt'
      return yield processFileWithShortPath(shortPath, next);
    }
  );

  return result;
}

Utilisation avec wrapTmp pour copies temporaires

const {wrapTmp} = require('xcraft-core-subst');

function processWithTempCopy(resp) {
  const {dest, unwrap} = wrapTmp(
    '/chemin/source/tres/long',
    'temp-processing',
    resp,
    true // overwrite si existe
  );

  try {
    // Traiter les fichiers dans dest
    console.log(`Fichiers temporaires dans : ${dest}`);
    // ...
  } finally {
    unwrap(() => {
      console.log('Nettoyage des fichiers temporaires terminé');
    });
  }
}

Interactions avec d'autres modules

• xcraft-core-platform : Détection du système d'exploitation pour activer/désactiver la substitution
• xcraft-core-process : Exécution des commandes système net use et subst
• xcraft-core-etc : Chargement de la configuration Xcraft pour les répertoires temporaires
• gigawatts : Gestion des générateurs et fonctions asynchrones
• fs-extra : Opérations sur le système de fichiers (copie, suppression)

Détails des sources

index.js

Fichier principal contenant la classe Subst qui orchestre la substitution de lecteurs Windows.

Classe Subst

La classe gère le cycle de vie complet d'une substitution de lecteur :

Propriétés :

• drive : Lettre de lecteur courante (commence à 'z')
• location : Chemin à substituer
• skipped : Booléen indiquant si la substitution est ignorée
• _resp : Objet de réponse Xcraft pour les logs

Méthodes publiques

• mount() — Monte le chemin sur une lettre de lecteur disponible. Retourne la lettre de lecteur (ex: 'z:') ou le chemin original si la substitution est ignorée.

• umount() — Démonte la lettre de lecteur précédemment montée. Nettoie proprement la substitution.

Méthodes privées

• _getDrive() — Retourne la lettre de lecteur actuelle formatée avec ':'
• _getOptions(opts) — Prépare les options pour les commandes système, évalue les fonctions
• _exec(cmd, opts, testCode, next) — Exécute une commande système et gère la logique de retry avec changement de lecteur
• _netUse(next) — Vérifie la disponibilité d'une lettre de lecteur (code retour 2 = libre)
• _subst(next) — Effectue la substitution effective (code retour 0 = succès)
• _desubst(next) — Supprime la substitution avec l'option /D

lib/wrap.js

Fonction utilitaire qui encapsule l'utilisation de Subst pour un usage temporaire :

1. Préparation : Assure l'existence du répertoire parent
2. Montage : Monte le répertoire sur une lettre de lecteur
3. Exécution : Appelle la fonction utilisateur avec le chemin court
4. Nettoyage : Démonte automatiquement le lecteur (bloc finally)

La fonction utilise watt pour gérer les générateurs et garantit le démontage même en cas d'exception.

lib/wrap-tmp.js

Fonction de gestion des copies temporaires basée sur la configuration Xcraft :

Logique de fonctionnement :

1. Vérifie si tempRoot ≠ tempDriveRoot dans la configuration
2. Si différents, copie les fichiers vers tempDriveRoot/tmpDir
3. Préserve les timestamps lors de la copie
4. Retourne un objet avec le chemin de destination et une fonction de nettoyage

Paramètres :

• location : Chemin source des fichiers
• tmpDir : Nom du dossier temporaire à créer
• resp : Objet de réponse Xcraft
• overwrite : Booléen pour forcer l'écrasement (défaut: false)

Retour :

{
  dest: string,        // Chemin de destination
  unwrap: function     // Fonction de nettoyage
}

Licence

Ce module est distribué sous licence MIT.

Ce contenu a été généré par IA