@arc-js/id-generator 0.0.1

package/README.md

@@ -0,0 +1,547 @@
+# @arc-js/id-generator
+
+[![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)
+
+**@arc-js/id-generator** est une bibliothèque TypeScript robuste pour générer des identifiants uniques avec des formats personnalisables. Elle offre une syntaxe expressive pour créer des identifiants complexes combinant texte, chaînes aléatoires, UUID et fonctions personnalisées.
+
+## ✨ Fonctionnalités Principales
+
+### 🔤 Formats de Génération Flexibles
+- **Syntaxe intuitive** : Utilisez des templates avec tokens spéciaux
+- **Combinaisons multiples** : Mélangez texte, random, UUID et handlers personnalisés
+- **Cache intelligent** : Génération optimisée avec cache pour les patterns non-variants
+
+### 🎲 Types de Génération Supportés
+- **Chaînes aléatoires** : Numeric, alphabetic, alphanumeric (avec/sans casse)
+- **UUID** : Versions v1 à v5 avec implémentations standards
+- **Handlers personnalisés** : Intégrez vos propres fonctions de génération
+- **Handlers intégrés** : Timestamp, date, time, compteur, variables d'environnement
+
+### ⚡ Performance & Sécurité
+- **Générateur cryptographique** : Utilise `crypto.getRandomValues` pour la sécurité
+- **Singleton pattern** : Instance unique optimisée
+- **Gestion de cache** : Réduction des calculs redondants
+- **Validation stricte** : Erreurs détaillées pour formats invalides
+
+## 📦 Installation
+
+### Via npm/yarn/pnpm
+
+```bash
+npm install @arc-js/id-generator
+# ou
+yarn add @arc-js/id-generator
+# ou
+pnpm add @arc-js/id-generator
+```
+
+### Importation directe (CDN)
+
+```html
+<script src="@arc-js/id-generator/id-generator.all.js"></script>
+```
+
+## 🚀 Démarrage Rapide
+
+### TypeScript/ES Modules
+
+```typescript
+import { IdentifierGenerator, IdentifierGeneratorHandlers } from '@arc-js/id-generator';
+// ou
+import IdGenerator from '@arc-js/id-generator';
+```
+
+### CommonJS
+
+```javascript
+const { IdentifierGenerator, IdentifierGeneratorHandlers } = require('@arc-js/id-generator');
+```
+
+### Navigateur (global)
+
+```html
+<script src="@arc-js/id-generator/id-generator.all.js"></script>
+<script>
+  // Disponible globalement
+  const generator = IdentifierGenerator.getInstance();
+  const id = generator.generate('prefix-#rand{size:8,type:alphanumeric}');
+</script>
+```
+
+## 📚 Syntaxe des Formats
+
+### Structure de Base
+
+```
+texte_littéral#token{options}texte_suivant
+```
+
+- **texte_littéral** : Texte statique inclus tel quel
+- **#** : Délimiteur de token spécial
+- **token** : Type de token (`rand`, `uuid`, `custom`)
+- **{options}** : Options spécifiques au token (optionnel)
+
+### Tokens Disponibles
+
+| Token | Description | Options |
+|-------|-------------|---------|
+| `#rand{...}` | Chaîne aléatoire | `size`, `type`, `variant` |
+| `#uuid{...}` | UUID | `version` |
+| `#custom{...}` | Handler personnalisé | Nom du handler |
+| Texte seul | Texte statique | Aucune |
+
+### Options des Tokens
+
+#### Options pour `#rand`
+```typescript
+{
+  size: number,          // Longueur de la chaîne (défaut: 8)
+  type: RandomType,      // 'numeric' | 'alphabetic' | 'alphabetic-case' | 'alphanumeric' | 'alphanumeric-case'
+  variant: boolean       // Si true, génère à chaque fois (défaut: false)
+}
+```
+
+#### Options pour `#uuid`
+```typescript
+{
+  version: UUIDVersion   // 'v1' | 'v2' | 'v3' | 'v4' | 'v5' (défaut: 'v4')
+}
+```
+
+#### Options pour `#custom`
+```typescript
+{
+  handlerName: string    // Nom du handler personnalisé
+}
+```
+
+## 🔧 Utilisation Détaillée
+
+### Instance Singleton
+
+```typescript
+// Méthode recommandée : singleton
+const generator = IdentifierGenerator.getInstance();
+
+// Méthode statique (plus concise)
+const id = IdentifierGenerator.generateId('format');
+```
+
+### Exemples Complets
+
+#### Exemple 1 : ID avec Random et UUID
+
+```typescript
+const generator = IdentifierGenerator.getInstance();
+
+const id1 = generator.generate(
+  'mda-#rand{size:10,type:alphanumeric}-#uuid{version:v1}',
+  {
+    customTimestamp: () => Date.now().toString()
+  }
+);
+// Résultat: "mda-a3b8c9d2e1-6ba7b810-9dad-11d1-80b4-00c04fd430c8"
+```
+
+#### Exemple 2 : Random avec variant
+
+```typescript
+const id2 = generator.generate(
+  'lorem-#rand{type:alphanumeric,variant:true}-ipsum',
+  {
+    user: () => 'john_doe'
+  }
+);
+// Résultat: "lorem-a1b2c3d4-ipsum" (change à chaque appel)
+```
+
+#### Exemple 3 : Handler personnalisé
+
+```typescript
+const id3 = generator.generate(
+  'user-#custom{userId}-#rand{size:6,type:numeric}',
+  {
+    userId: () => 'USR_' + Math.random().toString(36).substr(2, 9)
+  }
+);
+// Résultat: "user-USR_abc123def-123456"
+```
+
+#### Exemple 4 : Utilisation des handlers intégrés
+
+```typescript
+const id4 = IdentifierGenerator.generateId(
+  'order-#custom{timestamp}-#rand{size:8,type:alphanumeric-case}',
+  {
+    timestamp: IdentifierGeneratorHandlers.timestamp
+  }
+);
+// Résultat: "order-1641234567890-A1b2C3d4"
+```
+
+### Handlers Intégrés
+
+```typescript
+// Disponibles dans IdentifierGeneratorHandlers
+{
+  timestamp: () => Date.now().toString(),
+  date: () => new Date().toISOString().slice(0, 10).replace(/-/g, ''),
+  time: () => new Date().toISOString().slice(11, 19).replace(/:/g, ''),
+  counter: () => { /* compteur auto-incrémenté */ },
+  env: (envVar: string) => process.env[envVar] || ''
+}
+```
+
+## 🎯 Cas d'Utilisation Avancés
+
+### Génération d'ID Transactionnels
+
+```typescript
+function generateTransactionId(prefix: string): string {
+  return IdentifierGenerator.generateId(
+    `\${prefix}-#custom{date}-#custom{time}-#rand{size:12,type:numeric}`,
+    {
+      date: IdentifierGeneratorHandlers.date,
+      time: IdentifierGeneratorHandlers.time
+    }
+  );
+}
+// Résultat: "TXN-20231225-143025-123456789012"
+```
+
+### Génération d'ID Utilisateur
+
+```typescript
+class UserService {
+  private counter = 0;
+  
+  generateUserId(username: string): string {
+    return IdentifierGenerator.getInstance().generate(
+      'USR-#custom{prefix}-#custom{seq}-#rand{size:4,type:alphanumeric}',
+      {
+        prefix: () => username.substring(0, 3).toUpperCase(),
+        seq: () => (++this.counter).toString().padStart(6, '0')
+      }
+    );
+  }
+}
+// Résultat: "USR-JOH-000001-A1B2"
+```
+
+### Génération d'ID de Session
+
+```typescript
+function generateSessionId(): string {
+  return IdentifierGenerator.generateId(
+    'SESS-#uuid{version:v4}-#custom{timestamp}',
+    {
+      timestamp: () => Date.now().toString(36)
+    }
+  );
+}
+// Résultat: "SESS-550e8400-e29b-41d4-a716-446655440000-kyz9w8"
+```
+
+## ⚙️ Configuration Avancée
+
+### Gestion du Cache
+
+```typescript
+const generator = IdentifierGenerator.getInstance();
+
+// Générer avec cache (par défaut pour les non-variants)
+const cachedId = generator.generate('id-#rand{size:8,type:alphanumeric,variant:false}');
+// Même valeur à chaque appel pour la même session
+
+// Vider le cache
+generator.clearCache();
+
+// Forcer une nouvelle génération
+const freshId = generator.generate('id-#rand{size:8,type:alphanumeric,variant:true}');
+```
+
+### Handlers Personnalisés Complexes
+
+```typescript
+// Handler avec paramètres
+const configurableHandler = (prefix: string, length: number) => 
+  () => prefix + Math.random().toString(36).substr(2, length);
+
+// Handler asynchrone (à wrapper)
+const asyncHandler = async () => {
+  const response = await fetch('/api/id-source');
+  return response.text();
+};
+
+const generator = IdentifierGenerator.getInstance();
+const id = generator.generate(
+  'item-#custom{dynamicId}',
+  {
+    dynamicId: () => configurableHandler('ITM_', 8)()
+  }
+);
+```
+
+### Extension des Types
+
+```typescript
+// Ajouter de nouveaux types de random
+interface ExtendedRandomOptions extends RandomOptions {
+  exclude?: string; // Caractères à exclure
+}
+
+// Créer un générateur étendu
+class ExtendedIdentifierGenerator extends IdentifierGenerator {
+  protected generateRandomString(options: ExtendedRandomOptions): string {
+    if (options.exclude) {
+      // Implémentation personnalisée
+    }
+    return super.generateRandomString(options);
+  }
+}
+```
+
+## 📊 Table des Types de Random
+
+| Type | Caractères Inclus | Exemple |
+|------|------------------|---------|
+| `numeric` | 0-9 | "12345678" |
+| `alphabetic` | a-z (minuscules) | "abcdefgh" |
+| `alphabetic-case` | a-z, A-Z | "AbCdEfGh" |
+| `alphanumeric` | a-z, 0-9 | "a1b2c3d4" |
+| `alphanumeric-case` | a-z, A-Z, 0-9 | "A1b2C3d4" |
+
+## 🛡️ Gestion des Erreurs
+
+### Erreurs de Format
+
+```typescript
+try {
+  generator.generate('invalid-#unknown{type:invalid}');
+} catch (error) {
+  console.error('Erreur de format:', error.message);
+  // "Type de token non supporté: unknown"
+}
+```
+
+### Erreurs de Handler
+
+```typescript
+try {
+  generator.generate('#custom{missingHandler}', {});
+} catch (error) {
+  console.error('Handler manquant:', error.message);
+  // "Handler personnalisé non trouvé: missingHandler"
+}
+```
+
+### Validation des Options
+
+```typescript
+// Taille négative
+generator.generate('#rand{size:-5}'); // Lance une erreur
+
+// Type invalide
+generator.generate('#rand{type:invalid}'); // Utilise la valeur par défaut
+```
+
+## 🔧 Intégration
+
+### Avec React
+
+```tsx
+import React, { useMemo } from 'react';
+import { IdentifierGenerator } from '@arc-js/id-generator';
+
+const ProductCard: React.FC<{ product: Product }> = ({ product }) => {
+  const uniqueId = useMemo(() => 
+    IdentifierGenerator.generateId(
+      'product-#custom{id}-#rand{size:4,type:alphanumeric}',
+      { id: () => product.id }
+    ), [product.id]);
+    
+  return (
+    <div id={uniqueId}>
+      {/* Contenu */}
+    </div>
+  );
+};
+```
+
+### Avec Node.js
+
+```typescript
+import { IdentifierGenerator, IdentifierGeneratorHandlers } from '@arc-js/id-generator';
+
+// Configuration pour Node.js
+if (typeof window === 'undefined') {
+  // Polyfill pour crypto si nécessaire
+  global.crypto = require('crypto');
+}
+
+export function generateRequestId(): string {
+  return IdentifierGenerator.generateId(
+    'req-#custom{timestamp}-#rand{size:16,type:alphanumeric-case}',
+    {
+      timestamp: IdentifierGeneratorHandlers.timestamp
+    }
+  );
+}
+```
+
+### Avec Vue.js
+
+```vue
+<template>
+  <div :id="uniqueId">
+    <!-- Contenu -->
+  </div>
+</template>
+
+<script setup>
+import { computed } from 'vue';
+import { IdentifierGenerator } from '@arc-js/id-generator';
+
+const props = defineProps(['item']);
+
+const uniqueId = computed(() => 
+  IdentifierGenerator.generateId(
+    'item-#custom{itemId}',
+    { itemId: () => props.item.id }
+  )
+);
+</script>
+```
+
+## 📋 Table des Performances
+
+| Opération | Temps moyen | Mémoire |
+|-----------|-------------|---------|
+| Génération simple (#rand) | < 1ms | ~100KB |
+| Génération UUID (#uuid v4) | < 2ms | ~100KB |
+| Format complexe (5 tokens) | < 5ms | ~150KB |
+| Cache hit | < 0.1ms | N/A |
+
+## 🚨 Meilleures Pratiques
+
+### 1. Réutiliser les Instances
+```typescript
+// MAUVAIS : nouvelle instance à chaque fois
+const id1 = new IdentifierGenerator().generate(...);
+
+// BON : singleton
+const generator = IdentifierGenerator.getInstance();
+const id2 = generator.generate(...);
+const id3 = generator.generate(...);
+```
+
+### 2. Utiliser le Cache Appropriément
+```typescript
+// Pour les IDs uniques par session
+generator.generate('session-#rand{variant:true}');
+
+// Pour les IDs constants
+generator.generate('constant-#rand{variant:false}');
+```
+
+### 3. Valider les Formats
+```typescript
+function isValidFormat(format: string): boolean {
+  try {
+    IdentifierGenerator.generateId(format, {});
+    return true;
+  } catch {
+    return false;
+  }
+}
+```
+
+### 4. Sécuriser la Génération
+```typescript
+// Utiliser crypto pour les IDs sensibles
+const secureId = generator.generate(
+  '#rand{size:32,type:alphanumeric-case,variant:true}'
+);
+```
+
+## 🔗 API Complète
+
+### Classe `IdentifierGenerator`
+
+#### Méthodes Statiques
+- `getInstance(): IdentifierGenerator` - Retourne l'instance singleton
+- `generateId(format: string, customHandlers?: Record<string, CustomHandler>): string` - Génère un ID directement
+- `exposeToGlobal(): void` - Expose à l'objet global (navigateur)
+
+#### Méthodes d'Instance
+- `generate(format: string, customHandlers?: Record<string, CustomHandler>): string` - Génère un ID
+- `clearCache(): void` - Vide le cache interne
+
+### Objet `IdentifierGeneratorHandlers`
+
+Handlers prédéfinis pour les cas courants :
+- `timestamp(): string`
+- `date(): string`
+- `time(): string`
+- `counter(): string`
+- `env(envVar: string): string`
+
+### Types Exportés
+
+```typescript
+export type RandomType = 'numeric' | 'alphabetic' | 'alphabetic-case' | 'alphanumeric' | 'alphanumeric-case';
+export type UUIDVersion = 'v1' | 'v2' | 'v3' | 'v4' | 'v5';
+export type CustomHandler = () => string;
+
+export interface RandomOptions {
+  size: number;
+  type: RandomType;
+  variant: boolean;
+}
+
+export interface UUIDOptions {
+  version: UUIDVersion;
+}
+
+export interface TokenDefinition {
+  type: 'string' | 'random' | 'uuid' | 'custom';
+  value: string | RandomOptions | UUIDOptions | CustomHandler;
+}
+```
+
+## 🔧 Build et Développement
+
+### Structure du Projet
+
+```
+@arc-js/id-generator/
+├── id-generator.all.js
+├── id-generator.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](LICENSE) pour plus de détails.
+
+## 🐛 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/id-generator** - Générez des identifiants uniques avec élégance et puissance.
+
+*Développé par l'équipe INICODE*