recherche-rapide-prad

Un moteur de recherche prédictif et flou (fuzzy search) ultra-rapide, léger et décorrélé du contexte, écrit en TypeScript natif.

Conçu pour offrir des performances maximales en mémoire (RAM), il combine une recherche par correspondance directe (indexation de position) et une recherche floue adaptative basée sur l'algorithme de Levenshtein (optimisé en espace mémoire).

Le package est livré avec des définitions de types complètes (TSDocs) et un utilitaire de limitation de fréquence (debounce) prêt à l'emploi.

🚀 Fonctionnalités clés

• Utilitaire Debounce typé : Inclut un helper de limitation de fréquence qui préserve strictement la signature et les types des fonctions cibles.
• Indexation unique à l'initialisation : Les calculs lourds de normalisation de texte et de découpage en jetons (tokens) sont effectués une seule fois à l'initialisation pour garantir des requêtes sous la barre des 15 ms.
• Recherche floue adaptative (Levenshtein) : La tolérance aux fautes de frappe s'ajuste automatiquement selon la longueur du mot saisi (0 erreur pour les mots courts, jusqu'à $N/3$ pour les mots longs).
• Garde-fous de performance intégrés : Évite les calculs matriciels inutiles grâce à des filtres de différence de taille et de concordance du premier caractère.
• Algorithme de Levenshtein optimisé : Utilise une implémentation à deux lignes roulantes pour réduire drastiquement l'empreinte mémoire et éviter le garbage collection intensif.
• Normalisation internationale : Supporte nativement la suppression des accents, la conversion des ligatures européennes (comme Ł/ł polonais, ß allemand, Ø/ø scandinave) et la standardisation de la casse.
• Zéro dépendance : Garanti sans aucune dépendance externe pour préserver la légèreté de votre bundle final (compatible Tree-shaking).

📦 Installation

Installez le package dans votre projet via npm :

npm install recherche-rapide-prad

🛠️ Utilisation

1. Initialisation et recherche (TS / ES Modules)

import { creerMoteurRecherchePredictif } from 'recherche-rapide-prad';

// 1. Définir vos données (Exemple : Liste d'entreprises ou de produits)
const donnees = [
    { id: "1", nom: "Hub Łódź Sp. z o.o." },
    { id: "2", nom: "Boulangerie Parisienne" },
    { id: "3", nom: "Cafetière à dosettes" }
];

// 2. Initialiser le moteur (indexation immédiate)
// Paramètres : (liste, clé_identifiant, clé_du_contenu_à_chercher)
const rechercher = creerMoteurRecherchePredictif(donnees, "id", "nom");

// 3. Effectuer des recherches
// Exemple A : Recherche avec caractères spéciaux normalisés ("lodz" matche "Łódź")
const resultats1 = rechercher("lodz"); 
console.log(resultats1);
// => [ { id: '1', nom: 'Hub Łódź Sp. z o.o.' } ]

// Exemple B : Recherche floue avec faute de frappe ("cafetir" matche "Cafetière")
const resultats2 = rechercher("cafetir", 5); // Limité à 5 résultats maximum
console.log(resultats2);
// => [ { id: '3', nom: 'Cafetière à dosettes' } ]

2. Intégration avec saisie utilisateur (Debounce)

Pour éviter de surcharger le processeur à chaque touche relâchée par l'utilisateur, vous pouvez utiliser l'utilitaire debounce inclus :

import { creerMoteurRecherchePredictif, debounce } from 'recherche-rapide-prad';

const rechercher = creerMoteurRecherchePredictif(maListe, "id", "titre");

// Crée une fonction de recherche qui attend 150ms de silence avant de s'exécuter
const rechercheTemporisee = debounce((saisie: string) => {
    const resultats = rechercher(saisie);
    mettreAJourUI(resultats);
}, 150);

// À lier à votre événement d'input (React, Vue, JS natif...)
inputElement.addEventListener("input", (e) => {
    rechercheTemporisee((e.target as HTMLInputElement).value);
});

📊 Stratégie de scoring & Algorithme

Le moteur applique un barème strict pour trier les résultats par pertinence :

1. Match Direct (Score de base : 100) : Si la saisie est entièrement contenue dans le texte cible (ex: "Paris" dans "Boulangerie Parisienne"). Une pénalité est appliquée selon la position de la correspondance dans le texte pour faire remonter les résultats commençant par la saisie.
2. Match Flou (Score de base : 50) : Si la saisie requiert des corrections. Le score est déduit de la somme des distances de Levenshtein de chaque mot.
3. Validation stricte : Dans le cas d'une recherche multi-mots (ex: "hub lodz"), le moteur exige que chaque mot de la saisie trouve une correspondance (directe ou floue) dans le document cible pour que celui-ci soit retourné.

📄 Licence

Ce projet est distribué sous licence Apache 2.0. Elle vous autorise à utiliser, modifier et distribuer ce code librement, y compris dans des projets commerciaux fermés, tout en vous protégeant contre d'éventuels litiges liés aux brevets.