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

npm install @codeberry/easysearch

or using yarn:

yarn add @codeberry/easysearch

⚙️ Configuration

Define your search settings inside config/plugins.ts or config/plugins.js:

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:

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:

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:

// 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.