@arc-js/pajo

@arc-js/pajo est une bibliothèque TypeScript légère et robuste pour la manipulation de chemins de fichiers et d'URLs. Elle offre une API unifiée et type-safe pour travailler avec des chemins de fichiers sur différentes plateformes (Windows, Linux, macOS) et pour construire des URLs de manière cohérente.

✨ Fonctionnalités Principales

📁 Manipulation de Chemins

• Style multi-plateforme : Support natif des chemins Windows () et Unix (/)
• Joindre des chemins : Méthode intelligente pour joindre plusieurs segments de chemin
• Chemins absolus/relatifs : Détection automatique du type de chemin
• Normalisation : Élimination des séparateurs redondants et des points (., ..)
• Extraction : Récupération du nom de fichier, extension et répertoire parent

🌐 Manipulation d'URLs

• Construction d'URLs : Joindre des segments avec un hôte (avec ou sans protocole)
• Normalisation automatique : Ajout de protocole si absent, gestion des slashs
• Support des protocoles : Reconnaissance automatique des schémas (http://, https://, etc.)

🔄 Conversion

• Conversion de style : Convertir entre chemins Windows et Unix
• Adaptation automatique : Détection du style basée sur le contenu du chemin

🛡️ Robustesse

• Gestion des cas limites : Chemins vides, séparateurs multiples, points spéciaux
• Type-safe : Entièrement écrit en TypeScript avec des types stricts
• Pas de dépendances : Bibliothèque autonome, zéro dépendance

📦 Installation

Via npm/yarn/pnpm

npm install @arc-js/pajo
# ou
yarn add @arc-js/pajo
# ou
pnpm add @arc-js/pajo

Importation directe (CDN)

<script src="@arc-js/pajo/pajo.all.js"></script>

🚀 Démarrage Rapide

TypeScript/ES Modules

import Pajo from '@arc-js/pajo';
// ou
import { Pajo } from '@arc-js/pajo';

CommonJS

const Pajo = require('@arc-js/pajo').default;
// ou
const { Pajo } = require('@arc-js/pajo');

Navigateur (global)

<script src="@arc-js/pajo/pajo.all.js"></script>
<script>
  // Disponible globalement via window.Pajo
  console.log(Pajo.join('path', 'to', 'file.txt'));
</script>

Deno

import Pajo from '@arc-js/pajo';

📚 Documentation API

Méthodes Statiques

Pajo.join(...paths: string[]): string | undefined

Joint plusieurs segments de chemin en normalisant les séparateurs.

Paramètres:

• paths: Segments de chemin à joindre (peut être vide)

Retourne: Le chemin normalisé ou undefined si aucun chemin valide

Exemples:

// Chemins Unix
Pajo.join('/var', 'www', 'html');           // "/var/www/html"
Pajo.join('/usr/', '/local/', '/bin');      // "/usr/local/bin"
Pajo.join('./src', './utils', '../components'); // "src/components"

// Chemins Windows
Pajo.join('C:\\Users', 'Documents', 'file.txt'); // "C:\\Users\\Documents\\file.txt"
Pajo.join('D:\\Projects\\', '\\src\\', '\\app.js'); // "D:\\Projects\\src\\app.js"

// Chemins mixtes
Pajo.join('path', 'to', 'file.txt');        // "path/to/file.txt"
Pajo.join('path/', '//to/', 'file.txt');    // "path/to/file.txt"

Pajo.joinWithHost(host: string, ...paths: string[]): string | undefined

Joint un hôte avec des segments de chemin pour former une URL.

Paramètres:

• host: Hôte (peut inclure le protocole)
• paths: Segments de chemin à joindre

Retourne: L'URL complète normalisée ou undefined si invalide

Exemples:

Pajo.joinWithHost('example.com', 'api', 'v1', 'users'); 
// "https://example.com/api/v1/users"

Pajo.joinWithHost('https://example.com', 'api', 'v1'); 
// "https://example.com/api/v1"

Pajo.joinWithHost('myserver.com', '/var', 'log', 'app.log'); 
// "https://myserver.com/var/log/app.log"

Pajo.resolve(...paths: string[]): string | undefined

Résout les chemins avec . et .. pour obtenir un chemin normalisé.

Paramètres:

• paths: Segments de chemin à résoudre

Retourne: Chemin résolu ou undefined si invalide

Exemples:

Pajo.resolve('/foo/bar', './baz');          // "/foo/bar/baz"
Pajo.resolve('/foo/bar', '../baz');         // "/foo/baz"
Pajo.resolve('C:\\foo\\bar', '..\\baz'); // "C:\\foo\\baz"

Pajo.isAbsolute(path: string): boolean

Vérifie si un chemin est absolu.

Paramètres:

• path: Chemin à vérifier

Retourne: true si le chemin est absolu

Exemples:

Pajo.isAbsolute('/path/to/file');           // true
Pajo.isAbsolute('C:\\Windows\\System32'); // true
Pajo.isAbsolute('https://example.com');     // true
Pajo.isAbsolute('relative/path');           // false
Pajo.isAbsolute('./file.txt');              // false

Pajo.dirname(path: string): string | undefined

Extrait le répertoire parent d'un chemin.

Paramètres:

• path: Chemin source

Retourne: Le répertoire parent ou undefined

Exemples:

Pajo.dirname('/path/to/file.txt');          // "/path/to"
Pajo.dirname('C:\\Users\\file.txt');      // "C:\\Users"
Pajo.dirname('file.txt');                   // "."

Pajo.basename(path: string, ext?: string): string | undefined

Extrait le nom de fichier d'un chemin.

Paramètres:

• path: Chemin source
• ext (optionnel): Extension à retirer

Retourne: Le nom de fichier ou undefined

Exemples:

Pajo.basename('/path/to/file.txt');         // "file.txt"
Pajo.basename('/path/to/file.txt', '.txt'); // "file"
Pajo.basename('C:\\Users\\document.pdf'); // "document.pdf"

Pajo.extname(path: string): string | undefined

Extrait l'extension d'un fichier.

Paramètres:

• path: Chemin source

Retourne: L'extension (incluant le point) ou undefined

Exemples:

Pajo.extname('/path/to/file.txt');          // ".txt"
Pajo.extname('document.pdf');               // ".pdf"
Pajo.extname('file.with.many.dots.tar.gz'); // ".gz"
Pajo.extname('noextension');                // undefined

Pajo.toUnixPath(path: string): string

Convertit un chemin Windows en chemin Unix.

Paramètres:

• path: Chemin Windows

Retourne: Chemin Unix

Exemples:

Pajo.toUnixPath('C:\\Users\\file.txt');   // "C:/Users/file.txt"
Pajo.toUnixPath('D:\\Projects\\src');     // "D:/Projects/src"

Pajo.toWindowsPath(path: string): string

Convertit un chemin Unix en chemin Windows.

Paramètres:

• path: Chemin Unix

Retourne: Chemin Windows

Exemples:

Pajo.toWindowsPath('/home/user/file.txt');  // "\\home\\user\\file.txt"
Pajo.toWindowsPath('C:/Users/document');    // "C:\\Users\\document"

Pajo.exposeToGlobal(): void

Expose la classe Pajo à l'objet global (window) pour une utilisation dans les navigateurs.

Exemple:

// Dans un navigateur, après avoir chargé le script
Pajo.exposeToGlobal();
console.log(window.Pajo); // La classe Pajo est disponible

🔧 Utilisation Détaillée

Gestion Multi-Plateforme

Pajo détecte automatiquement le style de chemin basé sur le contenu :

// Détection automatique du style
Pajo.join('C:\\Users', 'Documents');      // Style Windows
Pajo.join('/home', 'user');                 // Style Unix
Pajo.join('relative', 'path');              // Style Unix par défaut

Construction d'URLs

// Construction d'URLs avec protocole automatique
Pajo.joinWithHost('api.example.com', 'v1', 'users');
// → "https://api.example.com/v1/users"

// Avec protocole explicite
Pajo.joinWithHost('http://localhost:3000', 'api', 'data');
// → "http://localhost:3000/api/data"

// Avec chemin absolu sur l'hôte
Pajo.joinWithHost('example.com', '/absolute/path');
// → "https://example.com/absolute/path"

Résolution de Chemins Relatifs

// Résolution des chemins avec .. et .
Pajo.resolve('/usr/local/bin', '..', 'share');
// → "/usr/local/share"

Pajo.resolve('C:\\Program Files\\App', '..', 'Common Files');
// → "C:\\Program Files\\Common Files"

Pajo.resolve('./src', '../lib', './utils');
// → "lib/utils"

Extraction d'Informations

const path = '/var/www/html/index.html';

Pajo.dirname(path);    // "/var/www/html"
Pajo.basename(path);   // "index.html"
Pajo.extname(path);    // ".html"
Pajo.isAbsolute(path); // true

🎯 Exemples Complets

Exemple 1 : Gestion de Chemins dans une Application

import Pajo from '@arc-js/pajo';

class FileManager {
  private baseDir: string;
  
  constructor(baseDir: string) {
    this.baseDir = baseDir;
  }
  
  getFilePath(...segments: string[]): string {
    const fullPath = Pajo.join(this.baseDir, ...segments);
    return Pajo.resolve(fullPath) || fullPath;
  }
  
  getFileInfo(path: string) {
    return {
      directory: Pajo.dirname(path),
      filename: Pajo.basename(path),
      extension: Pajo.extname(path),
      isAbsolute: Pajo.isAbsolute(path),
      unixPath: Pajo.toUnixPath(path)
    };
  }
}

// Utilisation
const manager = new FileManager('/var/www');
const filePath = manager.getFilePath('uploads', '..', 'images', 'photo.jpg');
console.log(filePath); // "/var/images/photo.jpg"

const info = manager.getFileInfo(filePath);
console.log(info);
// {
//   directory: "/var/images",
//   filename: "photo.jpg",
//   extension: ".jpg",
//   isAbsolute: true,
//   unixPath: "/var/images/photo.jpg"
// }

Exemple 2 : Construction d'APIs REST

import Pajo from '@arc-js/pajo';

class ApiClient {
  private baseUrl: string;
  
  constructor(baseUrl: string) {
    this.baseUrl = baseUrl;
  }
  
  buildUrl(endpoint: string, ...params: string[]): string {
    return Pajo.joinWithHost(this.baseUrl, endpoint, ...params) || '';
  }
  
  async getResource(endpoint: string, id?: string) {
    const url = id 
      ? this.buildUrl(endpoint, id)
      : this.buildUrl(endpoint);
    
    const response = await fetch(url);
    return response.json();
  }
}

// Utilisation
const api = new ApiClient('https://api.example.com');

// Construire des URLs
const usersUrl = api.buildUrl('users'); 
// → "https://api.example.com/users"

const userUrl = api.buildUrl('users', '123');
// → "https://api.example.com/users/123"

// Récupérer des données
const users = await api.getResource('users');
const user = await api.getResource('users', '123');

Exemple 3 : Migration Multi-Plateforme

import Pajo from '@arc-js/pajo';

function migratePath(oldPath: string, newBase: string): string {
  // Normaliser le chemin d'entrée
  const normalized = Pajo.resolve(oldPath);
  if (!normalized) return newBase;
  
  // Extraire le nom de fichier
  const filename = Pajo.basename(normalized);
  
  // Construire le nouveau chemin
  return Pajo.join(newBase, filename);
}

// Migration depuis Windows vers Unix
const windowsPath = 'C:\\Users\\John\\Documents\\file.txt';
const unixBase = '/home/john/files';

const migrated = migratePath(windowsPath, unixBase);
console.log(migrated); // "/home/john/files/file.txt"

// Conversion explicite si nécessaire
console.log(Pajo.toUnixPath(windowsPath)); // "C:/Users/John/Documents/file.txt"

🔧 Configuration Avancée

Personnalisation du Style de Chemin

Bien que Pajo détecte automatiquement le style, vous pouvez forcer un style spécifique :

function forceWindowsPath(...segments: string[]): string {
  // Ajouter un préfixe Windows pour forcer le style
  return Pajo.join('C:\\forced', ...segments).replace('C:\\forced\\', '');
}

function forceUnixPath(...segments: string[]): string {
  // Ajouter un slash initial pour forcer le style Unix
  return Pajo.join('/forced', ...segments).replace('/forced/', '');
}

Extension pour les Chemins d'URL

class UrlPath extends Pajo {
  static normalizeUrlPath(path: string): string {
    // Pour les URLs, on utilise toujours des slashs
    return path.replace(/\\/g, '/').replace(/\/+/g, '/');
  }
  
  static buildQueryString(params: Record<string, any>): string {
    const query = new URLSearchParams();
    Object.entries(params).forEach(([key, value]) => {
      if (value !== undefined && value !== null) {
        query.append(key, String(value));
      }
    });
    const queryString = query.toString();
    return queryString ? `?\${queryString}` : '';
  }
  
  static joinWithQuery(host: string, path: string, queryParams?: Record<string, any>): string {
    const url = this.joinWithHost(host, path);
    if (!url || !queryParams) return url || '';
    
    const query = this.buildQueryString(queryParams);
    return `\${url}\${query}`;
  }
}

// Utilisation
const url = UrlPath.joinWithQuery(
  'example.com',
  'api/search',
  { q: 'test', page: 1 }
);
console.log(url); // "https://example.com/api/search?q=test&page=1"

📋 Table de Compatibilité

Caractères Spéciaux Supportés

| Caractère | Description | Exemple | |-----------|-------------|---------| | . | Répertoire courant | ./file.txt | | .. | Répertoire parent | ../parent/file.txt | | ~ | Répertoire home (Unix) | ~/.config/app | | \ | Séparateur Windows | C:\\Users\\file.txt | | / | Séparateur Unix | /home/user/file.txt |

Plates-formes Supportées

| Plate-forme | Support | Notes | |-------------|---------|-------| | Windows | ✅ Complet | Détection automatique des chemins Windows | | Linux | ✅ Complet | Détection automatique des chemins Unix | | macOS | ✅ Complet | Identique à Linux | | Navigateurs | ✅ Complet | Via CDN ou module ES | | Node.js | ✅ Complet | v18+ recommandé | | Deno | ✅ Complet | Via esm.sh ou npm: | | Bun | ✅ Complet | Support natif des modules ES |

🚨 Gestion des Cas Limites

Chemins Vides ou Nuls

Pajo.join();                    // undefined
Pajo.join('');                  // undefined
Pajo.join('', 'path');          // "path"
Pajo.join('path', '', 'file');  // "path/file"

Séparateurs Multiples

Pajo.join('path///', '//to/', 'file.txt');  // "path/to/file.txt"
Pajo.join('C:\\\\Windows', '\\\\System32'); // "C:\\\\Windows\\\\System32"

Chemins avec Points

Pajo.join('..', 'parent', 'file.txt');     // "../parent/file.txt"
Pajo.join('.', 'current', 'file.txt');     // "current/file.txt"
Pajo.join('path..', 'file.txt');           // "path../file.txt"

URLs et Protocoles

Pajo.joinWithHost('https://example.com');  // "https://example.com"
Pajo.joinWithHost('ftp://server.com', 'files'); // "ftp://server.com/files"
Pajo.joinWithHost('file:///C:/Users', 'doc.txt'); // "file:///C:/Users/doc.txt"

🔧 Build et Développement

Structure du Projet

@arc-js/pajo/
├── pajo.all.js
├── pajo.all.min.js
├── index.d.ts
├── index.js
├── index.min.d.ts
├── index.min.js
├── package.json
├── tsconfig.json
└── README.md

📄 Licence

MIT License - Voir le fichier LICENSE pour plus de détails.

🐛 Signaler un Bug

Envoyez nous un mail à l'adresse [email protected] pour :

• Signaler un bug
• Proposer une amélioration
• Poser une question

@arc-js/pajo - Manipulation de chemins multi-plateforme, simple et robuste.

Développé par l'équipe INICODE