https://github.com/xcraft-inc/xcraft-core-subst

Windows subst helpers
https://github.com/xcraft-inc/xcraft-core-subst

drive subst xcraft

Last synced: 3 months ago
JSON representation

Windows subst helpers

Host: GitHub
URL: https://github.com/xcraft-inc/xcraft-core-subst
Owner: Xcraft-Inc
Created: 2016-08-04T14:07:29.000Z (almost 10 years ago)
Default Branch: master
Last Pushed: 2024-09-02T14:23:57.000Z (almost 2 years ago)
Last Synced: 2025-04-08T22:05:13.073Z (about 1 year ago)
Topics: drive, subst, xcraft
Language: JavaScript
Size: 43 KB
Stars: 0
Watchers: 4
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md

Awesome Lists containing this project

README

          # 📘 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](#structure-du-module)

- [Fonctionnement global](#fonctionnement-global)

- [Exemples d'utilisation](#exemples-dutilisation)

- [Interactions avec d'autres modules](#interactions-avec-dautres-modules)

- [Détails des sources](#détails-des-sources)

- [Licence](#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

```javascript

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

```javascript

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

```javascript

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 :**

```javascript

{

  dest: string,        // Chemin de destination

  unwrap: function     // Fonction de nettoyage

}

```

## Licence

Ce module est distribué sous [licence MIT](./LICENSE).

---

_Ce contenu a été généré par IA_

[xcraft-core-platform]: https://github.com/Xcraft-Inc/xcraft-core-platform

[xcraft-core-process]: https://github.com/Xcraft-Inc/xcraft-core-process

[xcraft-core-etc]: https://github.com/Xcraft-Inc/xcraft-core-etc

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/xcraft-inc/xcraft-core-subst

Awesome Lists containing this project

README