@amsom-habitat/file-utils

Package utilitaire pour la manipulation de fichiers (images, PDF) avec support Capacitor pour les plateformes mobiles natives.

Installation

npm i @amsom-habitat/file-utils

Fonctionnalités

• ✅ Redimensionnement d'images avec conservation du ratio
• ✅ Conversion d'images en PDF
• ✅ Validation de fichiers (images JPEG/PNG, PDF) par signature
• ✅ Conversion base64 ↔ Blob ↔ File
• ✅ Téléchargement de fichiers (navigateur et natif)
• ✅ Ouverture de fichiers dans le navigateur ou visionneuse native
• ✅ Support Capacitor (iOS/Android)
• ✅ Détection automatique des types MIME

Développement

Après avoir fait vos développements, veillez à bien tenir à jour le changelog.md ainsi que la version du package.json puis faites :

git add .
git commit -m '<commentaire>'
git push origin <branch>

Déploiement

Après avoir merge les dev sur la branche main, exécutez :

make publish

Cette commande vérifie la version, le changelog et publie le tout.

Utilisation

Import

// Import par défaut
import fileUtils from '@amsom-habitat/file-utils'

// Ou imports nommés
import {
  resizeImage,
  imageToPDF,
  downloadFile,
  openFileBase64,
  isImage,
  isPdf
} from '@amsom-habitat/file-utils'

📚 API Documentation

🖼️ Opérations sur les images

resizeImage(settings)

Redimensionne une image en conservant le ratio d'aspect.

Paramètres:

• settings (Object)
  • file (File) - Fichier image à redimensionner
  • maxWidth (number, optionnel) - Largeur maximale en pixels (défaut: 1080)
  • maxHeight (number, optionnel) - Hauteur maximale en pixels (défaut: 1920)
  • quality (number, optionnel) - Qualité JPEG de 0 à 1 (défaut: 0.92)

Retourne: Promise<string> - Data URL base64 de l'image redimensionnée

Exemple:

const resizedImage = await resizeImage({
  file: imageFile,
  maxWidth: 1000,
  maxHeight: 1500,
  quality: 0.9
})

imageToPDF(imageDataURLOrFile, autoResize)

Convertit une image en fichier PDF.

Paramètres:

• imageDataURLOrFile (string|File) - Data URL base64 de l'image ou objet File
• autoResize (boolean, optionnel) - Redimensionne automatiquement l'image pour tenir dans la page PDF avec marges (défaut: false)

Retourne: Promise<File> - Fichier PDF

Exemple:

// Sans redimensionnement
const pdfFile = await imageToPDF('data:image/jpeg;base64,...')

// Avec redimensionnement automatique (centré avec marges)
const pdfFile = await imageToPDF(imageFile, true)

✅ Validation de fichiers

isImage(file)

Valide qu'un fichier est une image JPEG ou PNG en vérifiant le type MIME et la signature du fichier.

Paramètres:

• file (File|Blob) - Fichier à valider

Retourne: Promise<boolean>

Exemple:

if (await isImage(file)) {
  console.log('Fichier image valide')
}

isPdf(file)

Valide qu'un fichier est un PDF en vérifiant le type MIME, la signature et la version du header.

Paramètres:

• file (File|Blob) - Fichier à valider

Retourne: Promise<boolean>

Exemple:

if (await isPdf(file)) {
  console.log('Fichier PDF valide')
}

🔄 Conversions de fichiers

inputFileToBase64(file)

Convertit un fichier en data URL base64.

Paramètres:

• file (File|Blob) - Fichier à convertir

Retourne: Promise<string> - Data URL base64

Exemple:

const base64 = await inputFileToBase64(file)
// Résultat: "data:image/jpeg;base64,/9j/4AAQ..."

base64ToBlob(base64, type)

Convertit une chaîne base64 en Blob. Détecte automatiquement le type MIME depuis le data URI.

Paramètres:

• base64 (string) - Données base64 (avec ou sans préfixe data URI)
• type (string, optionnel) - Type MIME (auto-détecté ou défaut: 'application/pdf')

Retourne: Blob

Exemple:

// Avec data URI (type auto-détecté)
const blob = base64ToBlob('data:image/png;base64,iVBORw0KG...')

// Sans data URI (utilise le type fourni ou PDF par défaut)
const blob = base64ToBlob('JVBERi0xLjQK...', 'application/pdf')

localFileToBlob(filePath)

Récupère un fichier depuis une URL et le convertit en Blob.

Paramètres:

• filePath (string) - URL ou chemin du fichier

Retourne: Promise<Blob>

Exemple:

const blob = await localFileToBlob('/path/to/image.jpg')

📥 Traitement de fichiers

handleFile(file, defaultExtension)

Traite un fichier : redimensionne les images et convertit en base64.

Paramètres:

• file (File) - Fichier à traiter
• defaultExtension (string|null, optionnel) - Extension par défaut

Retourne: Promise<ProcessedFile>

{
  file: string,      // Base64 sans préfixe data URI
  extension: string, // Extension du fichier (ex: '.jpg')
  type: string       // Type MIME
}

Exemple:

const processed = await handleFile(imageFile)
console.log(processed.file) // "iVBORw0KGgoAAAANS..."
console.log(processed.extension) // ".jpg"
console.log(processed.type) // "image/jpeg"

handleFiles(files)

Traite plusieurs fichiers en parallèle.

Paramètres:

• files (File[]|FileList) - Tableau ou FileList de fichiers

Retourne: Promise<ProcessedFile[]>

Exemple:

const processedFiles = await handleFiles(fileList)

💾 Téléchargement de fichiers

downloadFile(data, title) / downloadBlob(data, title)

Télécharge un fichier (navigateur ou plateforme native).

Paramètres:

• data (Blob) - Données du fichier
• title (string, optionnel) - Nom du fichier (défaut: 'document')

Note: Ajoute automatiquement l'extension si manquante.

Exemple:

// Le fichier sera téléchargé avec l'extension automatique
downloadFile(pdfBlob, 'mon-document')

// Ou avec extension déjà présente
downloadFile(imageBlob, 'photo.jpg')

👁️ Ouverture de fichiers

openFileBase64(base64, type)

Ouvre un fichier depuis du base64 dans une nouvelle fenêtre ou visionneuse native.

Paramètres:

• base64 (string) - Données base64 (avec ou sans data URI)
• type (string, optionnel) - Type MIME (auto-détecté ou défaut: 'application/pdf')

Exemple:

// Type auto-détecté depuis le data URI
openFileBase64('data:application/pdf;base64,JVBERi0...')

// Type par défaut (PDF)
openFileBase64('JVBERi0xLjQK...')

openFileBlob(blob)

Ouvre un Blob dans une nouvelle fenêtre ou visionneuse native.

Paramètres:

• blob (Blob) - Données du fichier

Exemple:

openFileBlob(pdfBlob)

📱 Support Capacitor

Le package détecte automatiquement si l'application tourne sur une plateforme native Capacitor (iOS/Android) et adapte son comportement :

• Navigateur : Téléchargement classique ou ouverture dans un nouvel onglet
• Natif : Sauvegarde dans le système de fichiers et ouverture avec l'application native appropriée

Configuration Capacitor

Assurez-vous d'avoir les plugins Capacitor installés :

npm install @capacitor/core @capacitor/filesystem @capacitor-community/file-opener

💡 Exemples complets

Redimensionner et convertir une image en PDF

import { resizeImage, imageToPDF, downloadFile } from '@amsom-habitat/file-utils'

async function processImage(imageFile) {
  // 1. Redimensionner l'image
  const resizedImage = await resizeImage({
    file: imageFile,
    maxWidth: 2000,
    maxHeight: 2800,
    quality: 0.95
  })

  // 2. Convertir en PDF avec redimensionnement automatique
  const pdfFile = await imageToPDF(resizedImage, true)

  // 3. Télécharger le PDF
  downloadFile(pdfFile, 'mon-document')
}

Valider et traiter un fichier uploadé

import { isImage, isPdf, handleFile, openFileBase64 } from '@amsom-habitat/file-utils'

async function handleFileUpload(file) {
  // Valider le type de fichier
  if (await isImage(file)) {
    console.log('Image valide')

    // Traiter l'image
    const processed = await handleFile(file)

    // Afficher l'image
    openFileBase64(`data:${processed.type};base64,${processed.file}`)
  } else if (await isPdf(file)) {
    console.log('PDF valide')

    // Traiter le PDF
    const processed = await handleFile(file)

    // Ouvrir le PDF
    openFileBase64(`data:application/pdf;base64,${processed.file}`)
  } else {
    console.error('Type de fichier non supporté')
  }
}

Traiter plusieurs images en parallèle

import { handleFiles, imageToPDF } from '@amsom-habitat/file-utils'

async function createPDFFromImages(imageFiles) {
  // Traiter toutes les images en parallèle
  const processedImages = await handleFiles(imageFiles)

  // Créer un PDF pour chaque image
  const pdfPromises = processedImages.map((img) =>
    imageToPDF(`data:${img.type};base64,${img.file}`, true)
  )

  const pdfFiles = await Promise.all(pdfPromises)
  return pdfFiles
}

🔧 Types MIME supportés

Images

• image/jpeg
• image/png

Documents

• application/pdf

📝 Changelog

Voir changelog.md pour l'historique des versions.

🤝 Contribution

Pour contribuer au package :

1. Créer une branche depuis dev
2. Faire vos modifications
3. Mettre à jour le changelog.md
4. Incrémenter la version dans package.json
5. Créer une merge request vers dev
6. Après validation, merger sur main et publier

📄 Licence

Propriété de AMSOM Habitat