Nestjs SearchSAFE

A collection of Agent Skills Standard and Best Practice for Programming Languages, Frameworks that help our AI Agent follow best practies on frameworks and programming laguages

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: nestjs-search
description: Integrate Elasticsearch and implement search index Sync patterns in NestJS. Use when integrating Elasticsearch or implementing search index sync in NestJS.
metadata:
  triggers:
    files:
    - '**/*.service.ts'
    - '**/search/**'
    keywords:
    - Elasticsearch
    - CQRS
    - Synchronization
---
# Search Engine & Full-Text

## **Priority: P1 (HIGH)**

- **Pattern**: **CQRS (Command Query Responsibility Segregation)**.
 - **Write**: To Primary Database (Postgres/MySQL). Source of Truth.
 - **Read (Complex)**: To Search Engine (Elasticsearch, OpenSearch, MeiliSearch). Optimized for filtering, fuzzy search, and aggregation.

## Synchronization ( Hard Part)

- **Dual Write (Anti-Pattern)**: `await db.save(); await es.index();`.
 - _Why_: Partial failures leave data inconsistent. Slows down HTTP response.
- **Event-Driven (Recommended)**:
 1. Service writes to DB.
 2. Service emits `EntityUpdated`.
 3. Event Handler (Async) pushes to Queue (BullMQ).
 4. Worker indexes document to Search Engine with retries.
- **CDC (Golden Standard)**: Change Data Capture (Debezium). Connects directly to DB transaction log. No app conceptual overhead, but higher ops complexity.

## Organization

- **Module**: Encapsulate client in `SearchModule`.
- **Abstraction**: Create generic `SearchService<T>` helpers.
 - `indexDocument(id, body)`
 - `search(query, filters)`
- **Mapping**: Use `class-transformer` to map Entities to "Search Documents". Keep docs flatter than relational entities.

## Testing

- **E2E**: not mock search engine in critical E2E flows.
- **Docker**: Spin up `elasticsearch:8` container in test harness to verify indexing works.

## Anti-Patterns

- **No dual writes to DB + ES**: Use event-driven or CDC pattern; dual writes risk partial failure inconsistency.
- **No Elasticsearch for structured queries**: Use DB indexes for filtering; ES for full-text and complex search.
- **No ES mocks in E2E search tests**: Spin up `elasticsearch:8` container to verify indexing behavior accurately.

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.