@codeberry/easysearch
Version:
A Strapi v5 plugin providing transliterated fuzzy search capabilities and advanced filtering logic for both GraphQL and REST APIs.
204 lines (163 loc) • 5.67 kB
Markdown
# **EasySearch - Strapi Plugin**
A Strapi v5 plugin providing **transliterated fuzzy search**, **dynamic per-dataset pagination**, and **advanced filtering** for both **GraphQL** and **REST APIs**.
> **✅ Compatible with Strapi v5.10.3 and above**
 
## 🚀 Features
- **Flexible search approaches**: Choose between **pre-filtering**, **fuzzysort**, or a **hybrid** of both for the optimal balance of performance and accuracy.
- **Dynamic per-dataset pagination**: Each dataset (e.g., `article`, `offer`) has independent pagination metadata.
- **Transliterated fuzzy search**: Supports searches in multiple languages.
- **Subscription-based filtering**: Controls access to content based on user roles or subscription levels.
- **Advanced population handling**: Dynamically populates nested relations and media fields.
- **Search in JSON fields**: Extracts and indexes text from rich text blocks for comprehensive search.
- **Highly configurable** via Strapi config.
- **Supports both REST and GraphQL APIs**.
## ⚙️ Installation
```bash
npm install @codeberry/easysearch
```
or using yarn:
```bash
yarn add @codeberry/easysearch
```
## ⚙️ Configuration
Define your **search settings** inside `config/plugins.ts` or `config/plugins.js`:
```typescript
export default ({ env }) => ({
'easy-search': {
enabled: true,
config: {
contentTypes: [
{
uid: "api::article.article",
transliterate: true,
fuzzysortOptions: {
characterLimit: 500,
threshold: -100,
limit: 10,
keys: [
{ name: "title", weight: 0.1 },
{ name: "content", weight: 2 }, // Enables rich-text content search
],
},
},
{
uid: "api::offer.offer",
transliterate: false,
fuzzysortOptions: {
characterLimit: 500,
threshold: 0.5,
limit: 10,
keys: [
{ name: "title", weight: 0.2 },
{ name: "description", weight: -0.2 },
],
},
},
],
searchApproach: "hybrid", // Options: "pre-filtering", "fuzzysort", "hybrid"
},
},
});
```
### Explanation:
- **`transliterate`**: Enables or disables transliteration for multilingual search.
- **`fuzzysortOptions.characterLimit`**: Trims searchable fields to improve performance.
- **`threshold`**: Defines how strict the matching is.
- **`limit`**: Controls the number of results returned.
- **`keys`**: Specifies which fields are indexed for search, along with their **weighting**.
- **`searchApproach`**:
- **`pre-filtering`**: Uses database filtering for improved performance on large datasets.
- **`fuzzysort`**: Fully relies on Fuzzysort for advanced matching and accuracy.
- **`hybrid`**: Combines database filtering and Fuzzysort for balanced performance and relevancy.
## 🎯 Usage
### **REST API**
**Example request:**
```http
GET /api/easy-search/search?query=example&page=1&pageSize=10&populate=featuredMedia,image
```
#### **Supported Query Parameters**:
- **`query`**: The search term.
- **`fields`**: Comma-separated list of fields to return.
- **`populate`**: Dynamically populate nested relations.
- **`page`** & **`pageSize`**: Handles pagination.
### **GraphQL API**
**Example Query**:
```graphql
query EasySearch($query: String!, $page: Int, $pageSize: Int) {
easySearch(query: $query, page: $page, pageSize: $pageSize) {
article {
documentId
slug
title
excerpt
featuredMedia {
image {
url
}
}
}
offer {
documentId
slug
title
description
featuredMedia {
image {
url
}
}
}
pageInfo {
article {
page
pageCount
pageSize
total
}
offer {
page
pageCount
pageSize
total
}
}
}
}
```
## 🛠 Middleware (Optional)
EasySearch supports **custom middleware** for **filtering content dynamically**.
For example, **restricting content access based on user roles or subscription levels**.
### **Example Middleware Registration**:
```typescript
// config/middlewares.ts
export default [
// ... other middlewares
"global::easy-search-filter"
];
```
## 📄 Changelog
### **Latest Updates**
- **Dynamic Search Approaches**: Introduced `searchApproach` (`pre-filtering`, `fuzzysort`, `hybrid`) for full control over search logic.
- **Per-Dataset Pagination**: Each dataset now has independent pagination metadata.
- **Enhanced JSON Field Support**: Rich text blocks are dynamically processed for comprehensive search.
- **Improved Flexibility**: Dynamic field handling with configurable `keys` per content type.
- **Transliteration Support**: Fully customizable on a per-content-type basis.
## ✅ TODO
- **Localization Support** → Improve multilingual search capabilities.
- **Unit Testing** → Add comprehensive tests for REST and GraphQL endpoints.
- **Optimize Search Indexing** → Enhance performance for larger datasets.
## 📝 Contributions
Contributions are welcome! If you find a bug or have an idea for improvement, feel free to **open an issue or submit a pull request**.
## 📜 License
This project is licensed under the **MIT License**.