Xcraft fs helpers
npm install xcraft-core-fsLe module xcraft-core-fs est une bibliothÚque d'utilitaires pour les opérations sur le systÚme de fichiers dans l'écosystÚme Xcraft. Il fournit une couche d'abstraction au-dessus de fs-extra avec des fonctionnalités étendues pour la manipulation de fichiers et dossiers, incluant des opérations de copie, déplacement, suppression, listage et calcul de sommes de contrÎle.
- Structure du module
- Fonctionnement global
- Exemples d'utilisation
- Interactions avec d'autres modules
- Détails des sources
Le module expose une collection de fonctions utilitaires organisées autour des opérations courantes du systÚme de fichiers :
- Opérations de base : cp, mv, rm, mkdir
- Opérations de listage : ls, lsdir, lsfile, lsall
- Opérations spécialisées : batch, shasum, sed, newerFiles
- Utilitaires : canExecute, rmSymlinks, rmFiles
Le module étend les capacités de fs-extra en ajoutant des fonctionnalités spécifiques aux besoins de Xcraft :
1. Gestion robuste des erreurs : Toutes les opérations incluent une gestion d'erreurs appropriée avec des codes d'erreur spécifiques (ENOENT, EPERM)
2. Support des liens symboliques : Traitement spécial pour les liens symboliques dans toutes les opérations avec préservation des liens
3. Opérations récursives : Support natif pour les opérations sur les arborescences de dossiers
4. Filtrage par regex : Possibilité de filtrer les fichiers/dossiers avec des expressions réguliÚres ou des fonctions personnalisées
5. Opérations par lot : SystÚme de traitement par lot avec callbacks personnalisés pour les transformations de noms
6. Optimisation des performances : Copie par chunks de 64KB et utilisation de rename avec fallback pour les déplacements
``javascript
const xFs = require('xcraft-core-fs');
// Copier un fichier
xFs.cp('source/file.txt', 'dest/file.txt');
// Copier le contenu d'un dossier
xFs.cp('source/dir', 'dest/dir');
// Copier avec filtrage
xFs.cp('source', 'dest', /\.js$/); // Seulement les fichiers .js
`
`javascript
// Déplacement sécurisé (fallback copy+rm si rename échoue)
xFs.mv('old/location', 'new/location');
// Déplacement avec filtrage
xFs.mv('source', 'dest', /\.(txt|md)$/);
`
`javascript
// Lister tous les fichiers récursivement
const allFiles = xFs.lsall('/path/to/dir');
// Lister avec filtre personnalisé
const jsFiles = xFs.lsall('/src', false, (item, stats) => {
return item.endsWith('.js') && stats && stats.isFile();
});
// Lister seulement les dossiers
const dirs = xFs.lsdir('/path', /^[^.]/); // Exclure les dossiers cachés
`
`javascript
// Calculer le SHA256 d'une arborescence
const checksum = xFs.shasum('/project/src', /\.js$/);
// Avec transformation des données
const checksumWithSed = xFs.shasum('/src', /\.js$/, (file, data) => {
return data.toString().replace(/console\.log/g, '// console.log');
});
// Avec filtre fonction
const checksum = xFs.shasum('/src', (item) => item.endsWith('.js'));
`
`javascript`
// Renommer tous les fichiers avec un callback
xFs.batch.mv((location, filename) => {
if (filename.endsWith('.tmp')) {
return filename.replace('.tmp', '.bak');
}
return null; // Ne pas traiter ce fichier
}, '/temp/dir');
`javascript
// Vérifier les permissions d'exécution
if (xFs.canExecute('/usr/bin/node')) {
console.log('Node.js est exécutable');
}
// Supprimer tous les liens symboliques
xFs.rmSymlinks('/project/node_modules');
// Modifier le contenu d'un fichier
const modified = xFs.sed('config.js', /debug:\s*true/, 'debug: false');
`
Le module xcraft-core-fs est une dépendance fondamentale utilisée par de nombreux modules de l'écosystÚme Xcraft :
- Modules de build : Utilisé pour la copie et manipulation de fichiers lors des processus de construction
- Modules de configuration : Utilisé pour la lecture et modification de fichiers de configuration
- Modules de déploiement : Utilisé pour les opérations de déploiement et synchronisation de fichiers
- Modules de cache : Utilisé pour la gestion des fichiers de cache et leur nettoyage
Le fichier principal expose toutes les fonctionnalités du module organisées en plusieurs catégories :
#### Opérations de base
- mkdir(location) â CrĂ©e un dossier et tous ses parents nĂ©cessaires (Ă©quivalent Ă mkdir -p).
- cp(src, dest, regex) â Copie un fichier ou le contenu d'un dossier. Supporte le filtrage par regex et crĂ©e automatiquement les dossiers intermĂ©diaires. GĂšre correctement les liens symboliques en prĂ©servant leur cible.
- mv(src, dest, regex = null) â DĂ©place un fichier ou le contenu d'un dossier. Utilise rename en prioritĂ© pour les performances, avec fallback sur copy+remove en cas d'Ă©chec. Supporte le filtrage par regex et ne supprime le dossier source que si tous les fichiers ont Ă©tĂ© dĂ©placĂ©s.
- rm(location) â Supprime un fichier ou dossier de maniĂšre rĂ©cursive en utilisant fs-extra.removeSync.
#### Opérations de listage
- ls(location, regex) â Liste tous les Ă©lĂ©ments d'un dossier avec filtrage optionnel par regex.
- lsdir(location, regex) â Liste uniquement les sous-dossiers avec filtrage optionnel par regex.
- lsfile(location, regex) â Liste uniquement les fichiers (non-dossiers) avec filtrage optionnel par regex.
- lsall(location, followSymlink = false, filter = null) â Liste rĂ©cursivement tous les Ă©lĂ©ments d'une arborescence. Le paramĂštre followSymlink dĂ©termine si les liens symboliques sont suivis. Le paramĂštre filter accepte une fonction (item, stats) => boolean pour un filtrage personnalisĂ©.
#### Opérations spécialisées
- batch.cp(cb, location) â Applique une opĂ©ration de copie par lot avec un callback de transformation des noms. Le callback reçoit (location, filename) et retourne le nouveau nom ou null pour ignorer.
- batch.mv(cb, location) â Applique une opĂ©ration de dĂ©placement par lot avec un callback de transformation des noms.
- shasum(location, regex, sed, sha = null) â Calcule une somme de contrĂŽle SHA256 rĂ©cursive d'une arborescence. Supporte le filtrage par regex ou fonction, et la transformation des donnĂ©es via le paramĂštre sed. GĂšre correctement les liens symboliques en incluant leur cible dans le calcul.
- sed(file, regex, newValue) â Effectue une substitution de texte dans un fichier. Ignore automatiquement les fichiers binaires dĂ©tectĂ©s par isbinaryfile. Retourne true si le fichier a Ă©tĂ© modifiĂ©, false sinon.
- newerFiles(location, regex, mtime) â VĂ©rifie rĂ©cursivement si des fichiers dans une arborescence sont plus rĂ©cents qu'une date donnĂ©e (mtime). Retourne true dĂšs qu'un fichier plus rĂ©cent est trouvĂ©.
#### Utilitaires
- canExecute(file) â VĂ©rifie si un fichier a les permissions d'exĂ©cution en testant le bit d'exĂ©cution du propriĂ©taire.
- rmSymlinks(location) â Supprime rĂ©cursivement tous les liens symboliques d'une arborescence sans affecter les fichiers rĂ©guliers.
- rmFiles(location) â Supprime rĂ©cursivement tous les fichiers et liens symboliques d'une arborescence, mais prĂ©serve la structure des dossiers.
#### Fonctions internes
La fonction cpFile implémente une copie de fichier optimisée par chunks de 64KB, préservant les permissions et gérant correctement les liens symboliques. Elle utilise des descripteurs de fichiers bas niveau pour optimiser les performances.
La fonction batch fournit le mécanisme de traitement par lot utilisé par batch.cp et batch.mv. Elle parcourt récursivement l'arborescence et applique le callback de transformation sur chaque fichier.
Le module expose également fse (fs-extra) pour un accÚs direct aux fonctionnalités de base si nécessaire.
#### Gestion des erreurs
Le module inclut une gestion robuste des erreurs :
- ENOENT : Fichiers/dossiers inexistants sont ignorés silencieusement dans certains contextes
- EPERM : Erreurs de permissions sont gérées spécifiquement dans les opérations par lot
- Fallback automatique : Les opérations de déplacement utilisent copy+remove si rename` échoue
---
_Documentation mise Ă jour_