@arc-js/qust 0.0.0

package/README.md

@@ -0,0 +1,630 @@
+# @arc-js/qust
+
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-007ACC)
+![Browser](https://img.shields.io/badge/browser-compatible-green)
+![Node.js](https://img.shields.io/badge/Node.js-18+-339933)
+![Bundle Size](https://img.shields.io/badge/bundle_size-3.5KB-green)
+
+**@arc-js/qust** est une bibliothèque TypeScript ultra-légère et performante pour la sérialisation et désérialisation d'objets en chaînes de requête (query strings). Elle offre une API simple et puissante pour manipuler les paramètres d'URL avec support des types complexes, des tableaux, des objets imbriqués et des options avancées.
+
+## ✨ Fonctionnalités
+
+- **Sérialisation complète** : Conversion d'objets JavaScript/TypeScript en query strings
+- **Parsing intelligent** : Reconstruction d'objets à partir de query strings
+- **Support multi-format** : Tableaux au format bracket, index, comma ou séparateur personnalisé
+- **Objets imbriqués** : Profondeur configurable pour les structures complexes
+- **Filtrage avancé** : Exclusion des valeurs nulles, chaînes vides ou selon vos critères
+- **Encodage/décodage** : Contrôle total sur l'encodage URI
+- **Type-safe** : Typage TypeScript complet avec génériques
+- **Léger** : Seulement ~3.5KB minifié
+- **Universal** : Compatible navigateur, Node.js, Deno, Bun, etc.
+
+## 📦 Installation
+
+### Via npm/yarn/pnpm
+
+```bash
+npm install @arc-js/qust
+# ou
+yarn add @arc-js/qust
+# ou
+pnpm add @arc-js/qust
+```
+
+### Importation directe (CDN)
+
+```html
+<script src="@arc-js/qust/qust.all.js"></script>
+```
+
+## 🚀 Démarrage Rapide
+
+### TypeScript/ES Modules
+
+```typescript
+import { qust, Qust } from '@arc-js/qust';
+
+// Utilisation avec les fonctions utilitaires
+const query = qust.stringify({ name: "John", age: 30 });
+// → "?name=John&age=30"
+
+const obj = qust.parse("?name=John&age=30");
+// → { name: "John", age: 30 }
+```
+
+### CommonJS
+
+```javascript
+const { qust } = require('@arc-js/qust');
+```
+
+### Navigateur (global)
+
+```html
+<script src="@arc-js/qust/qust.all.js"></script>
+<script>
+  // Disponible globalement
+  const query = qust.stringify({ name: "John", age: 30 });
+  const obj = qust.parse(query);
+</script>
+```
+
+## 📚 API Référence
+
+### Types
+
+```typescript
+type Primitive = string | number | boolean | null | undefined;
+type QueryValue = Primitive | Primitive[] | { [key: string]: QueryValue };
+type QueryObject = { [key: string]: QueryValue };
+
+interface QustOptions {
+  arrayFormat?: 'bracket' | 'index' | 'comma' | 'separator' | 'none';
+  arraySeparator?: string;
+  skipNull?: boolean;
+  skipEmptyString?: boolean;
+  encode?: boolean;
+  decode?: boolean;
+  depth?: number;
+}
+```
+
+### Classe Qust
+
+#### Constructeur
+
+```typescript
+new Qust(options?: QustOptions)
+```
+
+Crée une nouvelle instance avec des options personnalisées.
+
+#### Méthodes
+
+- **`stringify(obj: QueryObject): string`** : Convertit un objet en query string
+- **`parse<T = QueryObject>(queryString: string): T`** : Convertit une query string en objet
+- **`setOptions(newOptions: Partial<QustOptions>): void`** : Met à jour les options
+- **`getOptions(): Required<QustOptions>`** : Retourne les options actuelles
+
+### Fonctions utilitaires globales
+
+```typescript
+// stringify avec options par défaut
+qust.stringify(obj: QueryObject, options?: QustOptions): string
+
+// parse avec options par défaut
+qust.parse<T = QueryObject>(queryString: string, options?: QustOptions): T
+```
+
+### Options par défaut
+
+```typescript
+const DEFAULT_OPTIONS = {
+  arrayFormat: 'bracket',
+  arraySeparator: ',',
+  skipNull: true,
+  skipEmptyString: false,
+  encode: true,
+  decode: true,
+  depth: 10
+};
+```
+
+## 🔧 Utilisation Détaillée
+
+### Format des tableaux
+
+Qust supporte plusieurs formats pour les tableaux :
+
+#### 1. Format "bracket" (défaut)
+
+```typescript
+const obj = { tags: ["js", "ts", "node"] };
+qust.stringify(obj);
+// → "?tags[]=js&tags[]=ts&tags[]=node"
+
+qust.parse("?tags[]=js&tags[]=ts&tags[]=node");
+// → { tags: ["js", "ts", "node"] }
+```
+
+#### 2. Format "index"
+
+```typescript
+const obj = { coords: [10, 20, 30] };
+qust.stringify(obj, { arrayFormat: "index" });
+// → "?coords[0]=10&coords[1]=20&coords[2]=30"
+
+qust.parse("?coords[0]=10&coords[1]=20&coords[2]=30");
+// → { coords: [10, 20, 30] }
+```
+
+#### 3. Format "comma"
+
+```typescript
+const obj = { values: [1, 2, 3] };
+qust.stringify(obj, { arrayFormat: "comma" });
+// → "?values=1,2,3"
+
+qust.parse("?values=1,2,3", { arrayFormat: "comma" });
+// → { values: [1, 2, 3] }
+```
+
+#### 4. Format "separator"
+
+```typescript
+const obj = { items: ["a", "b", "c"] };
+qust.stringify(obj, { 
+  arrayFormat: "separator",
+  arraySeparator: "|" 
+});
+// → "?items=a&items=b&items=c"
+// Chaque élément devient un paramètre distinct avec la même clé
+```
+
+#### 5. Format "none"
+
+```typescript
+const obj = { items: ["x", "y"] };
+qust.stringify(obj, { arrayFormat: "none" });
+// → "?items=x&items=y"
+// Similaire à separator mais géré différemment en interne
+```
+
+### Objets imbriqués
+
+```typescript
+const obj = {
+  user: {
+    name: "Alice",
+    settings: {
+      theme: "dark",
+      notifications: true
+    }
+  }
+};
+
+const query = qust.stringify(obj);
+// → "?user[name]=Alice&user[settings][theme]=dark&user[settings][notifications]=true"
+
+const parsed = qust.parse(query);
+// → { user: { name: "Alice", settings: { theme: "dark", notifications: true } } }
+```
+
+### Contrôle de la profondeur
+
+```typescript
+// Limite la profondeur de sérialisation/désérialisation
+const q = new Qust({ depth: 2 });
+
+const obj = {
+  a: { 
+    b: {
+      c: {  // Ce niveau sera ignoré (profondeur > 2)
+        d: 10
+      }
+    }
+  }
+};
+
+q.stringify(obj);
+// Avertissement : "Qust: Profondeur maximale atteinte"
+```
+
+### Filtrage des valeurs
+
+```typescript
+const obj = {
+  a: null,
+  b: "",
+  c: "value",
+  d: 0,
+  e: undefined
+};
+
+// Ignore null et chaînes vides
+qust.stringify(obj, { 
+  skipNull: true, 
+  skipEmptyString: true 
+});
+// → "?c=value&d=0"
+
+// Garde toutes les valeurs
+qust.stringify(obj, { 
+  skipNull: false, 
+  skipEmptyString: false 
+});
+// → "?a=null&b=&c=value&d=0"
+```
+
+### Contrôle de l'encodage
+
+```typescript
+const obj = { city: "Paris & Lyon" };
+
+// Avec encodage (défaut)
+qust.stringify(obj);
+// → "?city=Paris%20%26%20Lyon"
+
+// Sans encodage
+qust.stringify(obj, { encode: false });
+// → "?city=Paris & Lyon"
+
+// Parsing avec/sans décodage
+qust.parse("?city=Paris%20%26%20Lyon", { decode: true });
+// → { city: "Paris & Lyon" }
+
+qust.parse("?city=Paris%20%26%20Lyon", { decode: false });
+// → { city: "Paris%20%26%20Lyon" }
+```
+
+### Types de données supportés
+
+```typescript
+const obj = {
+  string: "hello",
+  number: 42,
+  boolean: true,
+  null: null,
+  undefined: undefined,
+  array: [1, 2, 3],
+  nested: { key: "value" }
+};
+
+qust.stringify(obj);
+// Les valeurs sont converties automatiquement :
+// - boolean → "true"/"false"
+// - number → chaîne numérique
+// - null → "null"
+// - undefined → "undefined"
+
+qust.parse("?string=hello&number=42&boolean=true&null=null");
+// → { string: "hello", number: 42, boolean: true, null: null }
+```
+
+## 🎯 Cas d'utilisation
+
+### 1. Construction d'URLs
+
+```typescript
+function buildSearchUrl(baseUrl: string, filters: any): string {
+  const query = qust.stringify(filters);
+  return `\${baseUrl}\${query}`;
+}
+
+const filters = {
+  q: "laptop",
+  category: "electronics",
+  price: { min: 100, max: 1000 },
+  brands: ["dell", "hp", "lenovo"],
+  inStock: true
+};
+
+const url = buildSearchUrl("/products", filters);
+// → "/products?q=laptop&category=electronics&price[min]=100&price[max]=1000&brands[]=dell&brands[]=hp&brands[]=lenovo&inStock=true"
+```
+
+### 2. Récupération des paramètres d'URL
+
+```typescript
+// Dans une application web
+const currentQuery = window.location.search;
+const params = qust.parse(currentQuery);
+
+// Utilisation avec React/Vue/Angular
+function useQueryParams() {
+  const [params, setParams] = useState(() => {
+    return qust.parse(window.location.search);
+  });
+
+  const updateParams = (newParams: any) => {
+    const query = qust.stringify({ ...params, ...newParams });
+    window.history.pushState({}, '', `?\${query}`);
+    setParams(qust.parse(query));
+  };
+
+  return [params, updateParams];
+}
+```
+
+### 3. Communication API
+
+```typescript
+// Client-side
+async function fetchWithParams(endpoint: string, params: any) {
+  const query = qust.stringify(params);
+  const response = await fetch(`\${endpoint}\${query}`);
+  return response.json();
+}
+
+// Server-side (Node.js/Express)
+app.get('/api/data', (req, res) => {
+  const params = qust.parse(req.url);
+  // Traiter les paramètres...
+  res.json({ data: params });
+});
+```
+
+### 4. Sauvegarde d'état
+
+```typescript
+class FormState {
+  private state: any = {};
+
+  saveToUrl() {
+    const query = qust.stringify(this.state, {
+      skipEmptyString: true,
+      skipNull: true
+    });
+    window.location.hash = query;
+  }
+
+  loadFromUrl() {
+    const query = window.location.hash.substring(1);
+    this.state = qust.parse(`?\${query}`) || {};
+  }
+}
+```
+
+## 🔧 Configuration Avancée
+
+### Instance personnalisée
+
+```typescript
+// Création d'une instance avec configuration spécifique
+const customQust = new Qust({
+  arrayFormat: 'comma',
+  skipNull: true,
+  skipEmptyString: true,
+  depth: 5
+});
+
+// Réutilisation avec la même configuration
+const query1 = customQust.stringify(obj1);
+const query2 = customQust.stringify(obj2);
+
+// Modification dynamique
+customQust.setOptions({ arrayFormat: 'index' });
+```
+
+### Combinaison avec d'autres bibliothèques
+
+```typescript
+import { qust } from '@arc-js/qust';
+import {
+    StringSchema,
+    NumberSchema,
+    BooleanSchema,
+    DateSchema,
+    EnumSchema,
+    NotEnumSchema,
+    ArraySchema,
+    FileSchema,
+    ObjectSchema,
+    ChosenTypeSchema,
+    AnyTypeSchema,
+} from '@arc-js/jon';
+
+const JON = {
+    'String': StringSchema,
+    'Number': NumberSchema,
+    'Boolean': BooleanSchema,
+    'Date': DateSchema,
+    'Enum': EnumSchema,
+    'NotEnum': NotEnumSchema,
+    'Array': ArraySchema,
+    'File': FileSchema,
+    'Object': ObjectSchema,
+    'ChosenType': ChosenTypeSchema,
+    'AnyType': AnyTypeSchema,
+}; // Pour la validation
+
+// Validation avant sérialisation
+const schema = new JON.Object('fr').struct({
+  name: new JON.String('fr').required(),
+  age: new JON.Number('fr').min(0).max(150),
+  tags: new JON.Array('fr').types(new JON.String('fr'))
+});
+
+function safeStringify(obj: any) {
+  const validation = schema.check(obj);
+  if (validation.valid) {
+    return qust.stringify(obj);
+  }
+  throw new Error(`Validation failed: \${validation.errors}`);
+}
+```
+
+## 📋 Table des formats de tableaux
+
+| Format | Exemple de sortie | Description |
+|--------|-------------------|-------------|
+| **bracket** | `tags[]=a&tags[]=b` | Format standard avec crochets vides |
+| **index** | `tags[0]=a&tags[1]=b` | Avec indices explicites |
+| **comma** | `tags=a,b` | Séparés par des virgules |
+| **separator** | `tags=a&tags=b` | Paramètres multiples avec même clé |
+| **none** | `tags=a&tags=b` | Similaire à separator, traitement interne différent |
+
+## 🚨 Gestion des cas limites
+
+### Tableaux vides
+
+```typescript
+qust.stringify({ items: [] });
+// → "" (par défaut, les tableaux vides sont ignorés)
+```
+
+### Valeurs spéciales
+
+```typescript
+qust.stringify({ 
+  special: "a&b=c?d#e",
+  spaces: "hello world",
+  unicode: "🎉"
+});
+// → "?special=a%26b%3Dc%3Fd%23e&spaces=hello%20world&unicode=%F0%9F%8E%89"
+// Tout est correctement encodé
+```
+
+### Conflits de clés
+
+```typescript
+// Gestion automatique des structures complexes
+const obj = {
+  "user[name]": "direct",  // Clé avec crochets
+  user: { name: "nested" } // Objet imbriqué
+};
+
+qust.stringify(obj);
+// Les deux sont correctement gérés
+```
+
+## 🔬 Performance
+
+Qust est optimisé pour la performance :
+
+- **Algorithmes récursifs optimisés** avec contrôle de profondeur
+- **Encodage/décodage sélectif** pour éviter les opérations inutiles
+- **Gestion mémoire efficace** avec réutilisation d'objets
+- **Parsing streaming** pour les grandes chaînes
+
+```typescript
+// Benchmark approximatif (sur Node.js v18)
+const largeObj = {
+  users: Array(1000).fill(0).map((_, i) => ({ 
+    id: i, 
+    name: `User\${i}`,
+    data: { nested: { value: i * 2 } }
+  }))
+};
+
+console.time('stringify');
+const query = qust.stringify(largeObj);
+console.timeEnd('stringify'); // ~50ms
+
+console.time('parse');
+const parsed = qust.parse(query);
+console.timeEnd('parse'); // ~30ms
+```
+
+## 🔧 Build et Développement
+
+### Structure du projet
+
+```
+@arc-js/qust/
+├── qust.all.js
+├── qust.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+
+- iOS Safari 12+
+- Android Chrome 60+
+
+### Environnements
+- Node.js 18+
+- Deno 1.30+
+- Bun 1.0+
+- React Native
+- Electron
+- Cloudflare Workers
+- Vercel Edge Functions
+
+### Dépendances
+- **Aucune dépendance externe** : Qust est entièrement autonome
+- **TypeScript** : Support natif (types inclus)
+- **ES6+** : Utilise les fonctionnalités modernes JavaScript
+
+## 🛡️ Meilleures Pratiques
+
+### Sécurité
+
+1. **Toujours encoder par défaut** : Protège contre les injections
+2. **Valider les entrées** : Avant de parser des données non fiables
+3. **Limiter la profondeur** : Éviter les attaques par récursion
+4. **Utiliser skipEmptyString** : Pour les formulaires web
+
+```typescript
+// Configuration sécurisée par défaut
+const secureQust = new Qust({
+  encode: true,        // Toujours encoder
+  depth: 10,          // Limite raisonnable
+  skipNull: true,     // Ignorer les valeurs nulles
+  skipEmptyString: true // Ignorer les champs vides
+});
+```
+
+### Performance
+
+1. **Réutiliser les instances** : Pour éviter la recréation d'options
+2. **Choisir le bon format** : "comma" pour les grands tableaux
+3. **Filtrer tôt** : skipNull/skipEmptyString réduit la charge
+4. **Éviter la sur-sérialisation** : Ne pas sérialiser inutilement
+
+### Maintenance
+
+1. **Documenter les schémas** : Utiliser TypeScript pour la documentation
+2. **Tests unitaires** : Couvrir les cas d'utilisation
+3. **Versionner les APIs** : Changements de format d'arrayFormat
+4. **Logging en dev** : Activer les avertissements de profondeur
+
+## 📄 Licence
+
+MIT License - Voir le fichier [LICENSE](LICENSE) pour plus de détails.
+
+Copyright (c) 2024 INICODE
+
+Permission est accordée, gratuitement, à toute personne obtenant une copie
+de ce logiciel et des fichiers de documentation associés (le "Logiciel"), de
+traiter dans le Logiciel sans restriction, y compris sans limitation les
+droits d'utilisation, de copie, de modification, de fusion, de publication,
+de distribution, de sous-licence et/ou de vente de copies du Logiciel, et de
+permettre aux personnes à qui le Logiciel est fourni de le faire, sous réserve
+des conditions suivantes :
+
+## 🐛 Signaler un Bug
+
+Envoyez nous un mail à l'adresse `contact.inicode@gmail.com` pour :
+- Signaler un bug
+- Proposer une amélioration
+- Poser une question
+
+---
+
+**@arc-js/qust** - La solution ultime pour la manipulation de query strings en TypeScript.
+
+*Développé par l'équipe INICODE*