Search Engine #

Fast and lightweight search engine for Dart/Flutter with fuzzy search capabilities — lightweight and flexible.

🌐 Live Demo:** View on GitHub Pages

How Search Works #

The search engine uses a 4-level priority algorithm to find the most relevant results:

1. Search Priorities (in order of importance) #

1. Exact matches - "apple" = "apple"
2. Starts with - "app" → "apple"
3. Contains - "ple" → "apple"
4. Fuzzy search - "aple" → "apple" (only for queries ≥3 characters)

2. Search Fields #

By default, search looks in 3 fields:

• name - item name
• subtitle - item subtitle
• searchData - additional search data

3. Character Types #

Search works with any characters:

• ✅ Letters: "apple", "Яблоко"
• ✅ Numbers: "iPhone 14", "Windows 11"
• ✅ Special characters: "C++", "React.js"
• ✅ Emojis: "🍎 Apple"
• ✅ Spaces: "Red fruit"

4. Why 4 Levels? #

This is one smart algorithm, not 4 different searches:

1. Exact - for quick exact match finding (100% relevance)
2. Starts with - for autocomplete (user types beginning) (90% relevance)
3. Contains - for partial word search (70% relevance)
4. Fuzzy - for typo correction (50% relevance)

Results are sorted by priority - exact matches first, then others.

Features #

• 🔍 Fast search by name, subtitle, or custom fields
• 🎯 Fuzzy search for typos and misspellings
• ⚡ Optimized performance with priority-based results
• 🎨 Configurable search behavior
• 📦 Zero dependencies - pure Dart implementation

Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  fuzzy_search_engine: ^1.0.1

Quick Start #

import 'package:fuzzy_search_engine/fuzzy_search_engine.dart';

void main() {
  final items = [
    SearchableItem(id: '1', name: 'Apple', subtitle: 'Red fruit'),
    SearchableItem(id: '2', name: 'Banana', subtitle: 'Yellow fruit'),
    SearchableItem(id: '3', name: 'Orange', subtitle: 'Orange fruit'),
  ];

  // Basic search
  final results = SearchEngine.search(items, 'apple');
  print(results); // [Apple]

  // Fuzzy search for typos
  final fuzzyResults = SearchEngine.fuzzySearch(items, 'aple');
  print(fuzzyResults); // [Apple]
}

API Reference #

SearchableItem #

Represents a searchable item with customizable fields.

const item = SearchableItem(
  id: '1',
  name: 'Apple',
  icon: '🍎',
  subtitle: 'Red fruit',
  searchData: 'apple fruit red',
  data: {'price': 1.99},
);

SearchEngine #

Main search engine class with static methods.

Basic Search

// Search with default configuration
List<SearchableItem> results = SearchEngine.search(items, query);

// Search with custom configuration
List<SearchableItem> results = SearchEngine.search(
  items, 
  query,
  config: SearchConfig(
    searchFields: ['name', 'subtitle'],
    caseSensitive: false,
    // You can enable debug logs in Flutter apps using debugPrint
    // debugLogger: debugPrint,
  ),
);

Fuzzy Search

// Fuzzy search for typos and misspellings
List<SearchableItem> results = SearchEngine.fuzzySearch(items, query);

// Fuzzy search with custom configuration
List<SearchableItem> results = SearchEngine.fuzzySearch(
  items, 
  query,
  config: SearchConfig(
    fuzzyEnabled: true,
    maxFuzzyDistance: 3,
    // debugLogger: debugPrint,
  ),
);

Utility Methods

// Sort items by name
List<SearchableItem> sorted = SearchEngine.getSortedItems(items);

// Find item by ID
SearchableItem? item = SearchEngine.getItemById(items, 'item_id');

SearchConfig #

Configuration for search behavior.

const config = SearchConfig(
  searchFields: ['name', 'subtitle', 'searchData'], // Fields to search in
  fuzzyEnabled: true,                              // Enable fuzzy search
  maxFuzzyDistance: 3,                            // Max distance for fuzzy search
  caseSensitive: false,                           // Case sensitive search
);

Search Algorithm #

The search engine uses a priority-based algorithm:

1. Exact matches - Highest priority
2. Starts with matches - Second priority
3. Contains matches - Third priority
4. Fuzzy matches - Lowest priority (only in fuzzy search)

Fuzzy Search #

Fuzzy search uses the Levenshtein distance algorithm to find items with typos and misspellings. It automatically adjusts the distance threshold based on query length for optimal results.

Examples #

Basic Usage #

final countries = [
  SearchableItem(id: 'us', name: 'United States', subtitle: 'North America'),
  SearchableItem(id: 'uk', name: 'United Kingdom', subtitle: 'Europe'),
  SearchableItem(id: 'ca', name: 'Canada', subtitle: 'North America'),
];

// Search by name
final results = SearchEngine.search(countries, 'united');
// Returns: [United States, United Kingdom]

// Search by subtitle
final results = SearchEngine.search(countries, 'europe');
// Returns: [United Kingdom]

Advanced Configuration #

final config = SearchConfig(
  searchFields: ['name'], // Only search in name field
  caseSensitive: true,    // Case sensitive search
  fuzzyEnabled: false,    // Disable fuzzy search
);

final results = SearchEngine.search(countries, 'UNITED', config: config);
// Returns: [] (no exact match for 'UNITED')

Fuzzy Search Examples #

final fruits = [
  SearchableItem(id: '1', name: 'Apple'),
  SearchableItem(id: '2', name: 'Banana'),
  SearchableItem(id: '3', name: 'Orange'),
];

// Find items with typos
SearchEngine.fuzzySearch(fruits, 'aple');   // Returns: [Apple]
SearchEngine.fuzzySearch(fruits, 'bananna'); // Returns: [Banana]
SearchEngine.fuzzySearch(fruits, 'oragne');  // Returns: [Orange]

Performance #

• Time Complexity: O(n * m) where n is number of items, m is average field length
• Space Complexity: O(n) for storing results
• Memory: Minimal memory footprint with no external dependencies

Contributing #

Contributions are welcome! Please feel free to submit a Pull Request.

License #

This project is licensed under the MIT License.