feat: Add marketplace search typo tolerance and synonym expansion for tag queries closes(#465)

[itzabdoull]

Closes #465

---

Description

This PR implements tag query typo tolerance and synonym expansion for marketplace slot searches, addressing issue #465. It introduces a Burkhard-Keller (BK) tree for fast edit-distance fuzzy matching and a Synonym Registry with admin CRUD endpoints to scale tag search capabilities safely and efficiently.

Core Features & Implementation Details

1. Database Schema & Indexing

   • Added tags VARCHAR(100)[] NOT NULL DEFAULT '{}' column to the slots table.
   • Built a PostgreSQL GIN index (idx_slots_tags) on the tags column for fast array overlap filtering.
   • Added a search_synonyms registry table storing canonical terms mapped to their synonyms.
   • Created database migration: 021_add_tags_and_synonyms.ts.

2. Validation & Input Schema

   • Added validation under marketplaceSearchSchema.ts restricting input query tags to strings <= 50 chars, max 10 tags per query.
   • Fixed a pre-existing syntax error in MarketplaceSearchSchema structure where several properties were incorrectly nested inside superRefine.

3. BK-Tree Fuzzy Matching

   • Implemented a discrete Burkhard-Keller Tree data structure under bkTree.ts for sub-linear string searches under a target Levenshtein edit distance.
   • Enforced dynamic scaling of the edit distance cap based on query length:
     • Length <= 2: 0 (exact match only).
     • Length 3-5: 1.
     • Length > 5: 2.

4. Synonym Service

   • Implemented synonym management in synonymService.ts with in-memory caching (10s TTL) for fast lookups.
   • Designed a DFS expansion algorithm to recursively resolve synonyms. The algorithm includes cycle detection and loop protection (via a visited set) to remain resilient against infinite synonym reference loops.

5. Search Integration & Fallback Path

   • Integrated tags into MarketplaceSearchService.
   • Injected typo-tolerated and synonym-expanded terms into the query filter clause using tags && $param::varchar[].
   • Added an exact-match fallback path: if no keywords matching the query can be found in the registry or tags cache, it falls back to querying the database directly with the raw user input tags, preventing search misses.

6. Admin CRUD Routes

   • Implemented standard CRUD routes in admin.ts at /api/v1/admin/synonyms for administrating the synonym registry. All routes require admin token authentication.

---

Verification & Testing

Test Coverage

• Achieved 99.06% statement coverage and 87.5% branch coverage for the new services:

  =============================== Coverage summary ===============================
  Statements   : 99.06% ( 106/107 )
  Branches     : 87.5% ( 28/32 )
  Functions    : 100% ( 17/17 )
  Lines        : 100% ( 98/98 )
  ================================================================================
  

[drips-wave]

@itzabdoull Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits