Feat/search optimization

[Power70]

Linked Issue

Closes #290

---

What does this PR do?

This PR fully addresses Search Index Optimization by hardening Elasticsearch query execution, improving index setup/migration behavior, and validating API-level search parameters at the controller boundary. It introduces bounded pagination, query/filter sanitization, reduced payload search requests, and robust index normalization behavior for keyword filters. It also adds an opt-in reindex-on-boot path for existing environments so new index settings/mappings can be applied without manual patching.

---

Type of change

• ✨ New feature (non-breaking change that adds functionality)
• 🐛 Bug fix (non-breaking change that fixes an issue)
• 💥 Breaking change (fix or feature that changes existing API behaviour)
• ♻️ Refactor (no functional change, no new feature)
• 🧪 Tests only (no production code changes)
• 📝 Documentation only
• 🔧 Chore (build, dependencies, CI config)

---

Change summary

• Search API hardening and behavior improvements:

  • Added pagination query params in search controller (page, limit) with boundary checks.
  • Added query sanitization for search and autocomplete inputs.
  • Added filter normalization for keyword filters (category, level, language) with trimming/lowercasing and array deduplication.
  • Added Elasticsearch request timeouts and explicit _source field selection to reduce payload size.
  • Added track_total_hits and paginated response metadata (page, limit).
  • Updated search query composition to support filter-only requests when no query text is provided.
  • Improved cache key hashing to include pagination fields and normalized query input.
  • Extended index settings/mappings with lowercase normalizers for keyword fields (tags, category, level, language) and tuned refresh interval.
  • Added opt-in index migration path for existing clusters via SEARCH_REINDEX_ON_BOOT=true, rebuilding courses index using the current optimized mapping.

• Test coverage added for search optimization:

  • Added controller tests for filter parsing and page/limit validation.
  • Added service tests for query/filter sanitization, bounded pagination, filter-only query path, and autocomplete normalization.

• Audit and platform consistency updates:

  • Audit controller/module/decorators/interceptor formatting and readability cleanup.
  • Minor API version interceptor regex cleanup and unused parameter suppression.
  • Defensive guard in websocket connection retrieval path.
  • Stronger typing and formatting normalization in media validation/upload progress and utility files.
  • Removal of unused import in notifications preferences service.

• Scope note:

  • Most files outside the search flow contain style/formatting/type readability changes with no intended runtime behavior change.

---

Pre-merge checklist (required)

Do not remove items. Unchecked items without an explanation will block merge.

Explanation: Targeted validations were executed locally for the search scope; full pipeline commands should still run in CI before merge.

Branch & metadata

• Branch name follows feature/issue-<N>-<slug> / fix/issue-<N>-<slug> convention
• Branch is up to date with the target branch (develop or main)
• All commits and the PR title follow the Conventional Commits format with issue reference

Code quality & tests

• npm run lint:ci — zero ESLint warnings
• npm run format:check — Prettier reports no changes needed
• npm run typecheck — zero TypeScript errors
• npm run test:ci — all tests pass, coverage ≥ 70%
• New service methods have corresponding .spec.ts unit tests
• New API endpoints are covered by at least one e2e test
• No existing tests were deleted (if any were, justification is provided in the PR description)

Error handling & NestJS best practices

• All new/updated DTOs use class-validator / class-transformer decorators and are wired through NestJS pipes (e.g. global ValidationPipe or explicit)
• All controller entry points validate external input at the boundary (no unvalidated raw any/unknown reaching the domain)
• Controllers/services throw appropriate NestJS HTTP exceptions (e.g. BadRequestException, UnauthorizedException, ForbiddenException, NotFoundException) instead of generic Error
• Any new error shapes are handled by existing exception filters or the filters have been updated accordingly
• Logging goes through the shared logging abstraction (e.g. Nest Logger or central logger service) with meaningful, structured messages
• Authentication/authorization guards (e.g. AuthGuard, role/permissions guards, custom guards) are applied to all new/modified endpoints where appropriate
• If an endpoint is intentionally public, this is explicitly mentioned in the PR description with rationale

API documentation / Swagger

• Swagger / OpenAPI decorators are added or updated for all new/changed controller endpoints (including DTOs, responses, and error schemas)
• I have started the app locally and confirmed the /api (or Swagger UI) reflects new/changed endpoints correctly
• If there are no API surface changes, this is explicitly stated in the PR description

Breaking changes

• This PR does not introduce a breaking API change
• OR: this PR introduces a breaking change and it is documented below, with migration notes

---

Breaking change description (if applicable)

N/A. No breaking API change is intended.

---

Test evidence (required)

Commands run locally

npm run typecheck
npm test -- src/search/search.controller.spec.ts src/search/search.service.spec.ts
npx eslint src/search/search.service.ts src/search/indexing/indexing.service.ts src/search/search.controller.spec.ts src/search/search.service.spec.ts

Manual / API verification

Suggested focused verification:
1) GET /search?q=nestjs&page=1&limit=20 returns 200 with paginated payload.
2) GET /search?q=nestjs&page=0 returns 400 (invalid page).
3) GET /search?q=nestjs&limit=200 returns 400 (limit > 50).
4) GET /search?q=   (trimmed/empty query) with filters validates filter-only path.
5) GET /search/autocomplete?q=   and long input validates sanitization/empty handling.
6) Set SEARCH_REINDEX_ON_BOOT=true in a non-production run and verify courses index reindex logs complete successfully.
7) Validate Swagger docs for updated query params.

---

Screenshots / recordings (if applicable)

N/A for backend-only changes.

[drips-wave]

@Power70 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