@codeberry/easysearch NPM

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

License NPM Version

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