@arc-js/fodat

@arc-js/fodat est une bibliothèque JavaScript/TypeScript légère et puissante pour la transformation bidirectionnelle entre FormData et objets JSON. Conçue pour simplifier la manipulation des données de formulaires complexes avec support natif des fichiers et structures imbriquées.

✨ Fonctionnalités Principales

• 🔄 Transformation bidirectionnelle : FormData → JSON et JSON → FormData
• 🏗️ Support des structures complexes : objets imbriqués, tableaux multidimensionnels
• 📁 Gestion native des fichiers : préservation des objets File sans conversion
• 🎯 Typage TypeScript complet : auto-complétion et sécurité des types
• ⚡ Léger et performant : aucune dépendance, optimisé pour les performances
• 🌐 Multi-plateforme : navigateur, Node.js, Deno, Bun
• 🔧 Parsing intelligent : conversion automatique des types (booléens, nombres)

📦 Installation

Via npm/yarn/pnpm

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

Importation directe (CDN)

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

🚀 Démarrage Rapide

TypeScript/ES Modules

import Fodat from '@arc-js/fodat';
// ou
import { Fodat } from '@arc-js/fodat';

CommonJS

const { Fodat } = require('@arc-js/fodat');

Navigateur (global)

<script src="@arc-js/fodat/fodat.all.js"></script>
<script>
  // Disponible globalement comme window.Fodat
  const formData = new FormData();
  formData.append('user.name', 'John');
  const json = Fodat.transform(formData);
  console.log(json.user.name); // "John"
</script>

📚 Documentation API

Méthodes Statiques

Fodat.transform(formData: FormData): any

Transforme un objet FormData en structure JavaScript/JSON.

const formData = new FormData();
formData.append('user.firstName', 'Jean');
formData.append('user.lastName', 'Dupont');
formData.append('user.age', '30');
formData.append('addresses[0].city', 'Paris');

const result = Fodat.transform(formData);
/*
Résultat:
{
  user: {
    firstName: "Jean",
    lastName: "Dupont",
    age: 30  // Converti automatiquement en nombre
  },
  addresses: [{
    city: "Paris"
  }]
}
*/

Fodat.toFormData(json: any, formData?: FormData, parentKey?: string): FormData

Transforme un objet JavaScript/JSON en FormData.

const data = {
  user: {
    name: "Marie",
    active: true,
    profile: new File(['content'], 'profile.jpg')
  },
  tags: ["js", "typescript"]
};

const formData = Fodat.toFormData(data);
// Peut être envoyé via fetch ou XMLHttpRequest

Fonctionnalités Avancées

Conversion Automatique des Types

Fodat convertit intelligemment les valeurs string en types appropriés :

• "true" → true (booléen)
• "false" → false (booléen)
• "42" → 42 (nombre)
• "3.14" → 3.14 (nombre)
• Fichiers → préservés comme objets File natifs

Syntaxe des Clés

| Type | Syntaxe | Exemple | |------|---------|---------| | Propriété simple | key | name | | Propriété imbriquée | key.subkey | user.name | | Tableau | key[index] | tags[0] | | Tableau d'objets | key[index].prop | users[0].email | | Mixte | key.subkey[index].prop | data.items[0].value |

Gestion des Fichiers

// Ajout de fichiers
const formData = new FormData();
formData.append('avatar', new File([''], 'photo.jpg'));
formData.append('documents[0]', new File([''], 'doc.pdf'));

// Transformation
const json = Fodat.transform(formData);
console.log(json.avatar instanceof File); // true
console.log(json.documents[0] instanceof File); // true

// Transformation inverse
const newFormData = Fodat.toFormData(json);

🎯 Exemples Complets

Exemple 1 : Formulaire d'Utilisateur Complexe

// Création d'un FormData complexe
const formData = new FormData();
formData.append('personal.firstName', 'Jean');
formData.append('personal.lastName', 'Dupont');
formData.append('personal.email', '[email protected]');
formData.append('personal.age', '35');
formData.append('personal.active', 'true');

formData.append('addresses[0].street', '123 Rue Exemple');
formData.append('addresses[0].city', 'Paris');
formData.append('addresses[1].street', '456 Autre Rue');
formData.append('addresses[1].city', 'Lyon');

formData.append('skills[0]', 'JavaScript');
formData.append('skills[1]', 'TypeScript');
formData.append('skills[2]', 'React');

// Transformation en JSON
const userData = Fodat.transform(formData);
console.log(userData.personal.age); // 35 (nombre)
console.log(userData.personal.active); // true (booléen)
console.log(userData.addresses.length); // 2
console.log(userData.skills); // ["JavaScript", "TypeScript", "React"]

// Envoi au serveur après modification
userData.personal.age = 36;
const updatedFormData = Fodat.toFormData(userData);

Exemple 2 : Upload avec Métadonnées

// Préparation des données avec fichiers
const uploadData = {
  metadata: {
    title: "Document Important",
    category: "legal",
    tags: ["contract", "signed"],
    priority: "high"
  },
  files: [
    new File(['contenu'], 'contrat.pdf'),
    new File(['annexe'], 'annexe.jpg')
  ],
  options: {
    encrypt: true,
    notify: false
  }
};

// Conversion en FormData pour upload
const formData = Fodat.toFormData(uploadData);

// Simulation d'envoi
fetch('/api/upload', {
  method: 'POST',
  body: formData
});

Exemple 3 : Traitement de Réponse Serveur

// Supposons que vous recevez un FormData d'une API
async function handleFormDataResponse(response: Response) {
  const formData = await response.formData();
  
  // Transformation en objet utilisable
  const data = Fodat.transform(formData);
  
  // Traitement typé
  if (data.user && typeof data.user.age === 'number') {
    console.log(`Âge: \${data.user.age}`);
  }
  
  // Modification et renvoi
  data.timestamp = new Date().toISOString();
  return Fodat.toFormData(data);
}

🔧 Build et Développement

Structure du Projet

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

📋 Compatibilité

Navigateurs Supportés

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+
• Opera 47+
• Tous les navigateurs supportant FormData

Environnements

• Node.js 18+ (avec polyfill FormData)
• Deno 1.30+
• Bun 1.0+
• Tous les environnements ES5+

🚨 Notes Importantes

Performances

Fodat est optimisé pour la performance mais gardez à l'esprit que :

• La transformation de FormData très larges peut avoir un impact
• Préférez transformer uniquement les données nécessaires
• Les fichiers volumineux sont référencés, non copiés

Limitations

• Les valeurs null et undefined dans FormData sont traitées comme chaînes vides
• Les objets cycliques ne sont pas supportés
• La profondeur maximale d'imbrication est limitée par la pile d'appels

Sécurité

• Validez toujours les données d'entrée
• Les fichiers sont préservés tels quels, assurez-vous de valider leur type et taille
• Évitez d'exposer Fodat à des données non fiables sans validation

📄 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/fodat - La passerelle intelligente entre FormData et JSON. 🔄

Développé par l'équipe INICODE