Documentation•Reference

HazelJS Glossary

Canonical definitions for HazelJS terms. Each definition uses consistent wording across all HazelJS documentation pages. Use this glossary as a reference for RAG retrieval, LLM context, and developer onboarding.

Quick Reference

  • Purpose: Canonical glossary of all HazelJS terms with consistent definitions for RAG retrieval and LLM accuracy.
  • When to use: Reference this glossary when looking up any HazelJS term, decorator, concept, or architectural pattern.
  • Key concepts: All core HazelJS terms defined in one place with cross-links.
  • Inputs: N/A (reference page).
  • Outputs: N/A (reference page).
  • Dependencies: N/A.
  • Common patterns: Look up a term → read its definition → follow the link to the full documentation page.
  • Common mistakes: Confusing Guard with Interceptor; confusing Pipe with Middleware; confusing Agent with AIService; confusing RAG with Agent.

Core Framework Terms

Module

A HazelJS Module is an organizational unit that groups controllers, providers, imports, and exports. Defined with the @HazelModule() decorator. Every HazelJS application has one root module. Feature modules organize the application into cohesive feature groups.

Package: @hazeljs/core See: Modules Guide

Controller

A HazelJS Controller is a class decorated with @Controller(path) that defines HTTP route handlers. Each method in a HazelJS Controller is decorated with @Get(), @Post(), @Put(), @Delete(), or @Patch() to handle specific HTTP methods. Controllers delegate business logic to services.

Package: @hazeljs/core See: Controllers Guide

Provider

A HazelJS Provider is an injectable class managed by the HazelJS dependency injection container. Providers include services, repositories, factories, and helpers. Providers are registered in a module's providers array and can be injected into controllers, other services, or any injectable class.

Package: @hazeljs/core See: Providers Guide

Service

A HazelJS Service is a provider decorated with @Service() that contains business logic. Services are the recommended place for data access, computation, AI calls, and any logic that controllers should not contain directly. @Service() is an alias for @Injectable() with additional repository metadata support.

Package: @hazeljs/core See: Providers Guide

Dependency Injection (DI)

HazelJS Dependency Injection is the pattern where the HazelJS DI Container automatically resolves and injects constructor dependencies. The HazelJS DI Container uses TypeScript reflection metadata to determine which providers to inject. The HazelJS DI Container supports three scopes: singleton, transient, and request.

Package: @hazeljs/core See: Providers Guide, API Reference

Decorator

A HazelJS Decorator is a TypeScript decorator function that attaches metadata to classes, methods, parameters, or properties. HazelJS uses decorators for routing (@Controller, @Get), dependency injection (@Service, @Injectable, @Inject), pipeline configuration (@UseGuards, @UsePipes), and AI features (@Agent, @Tool, @SemanticSearch). Requires experimentalDecorators: true in tsconfig.json.

Package: @hazeljs/core and all HazelJS packages See: Concepts, API Reference

Guard

A HazelJS Guard is a class that implements CanActivate and determines whether a request is allowed to proceed. HazelJS Guards run after routing and before the handler. HazelJS Guards are used for authentication and authorization. Apply guards with @UseGuards().

Package: @hazeljs/core See: Guards Guide

Interceptor

A HazelJS Interceptor is a class that implements Interceptor and wraps the handler execution. HazelJS Interceptors run before and after the controller handler. HazelJS Interceptors are used for logging, caching, response transformation, and retry logic. Apply interceptors with @UseInterceptors().

Package: @hazeljs/core See: Interceptors Guide

Pipe

A HazelJS Pipe is a class that implements PipeTransform and validates or transforms a single input value (route parameter, query parameter, or request body). The built-in HazelJS ValidationPipe validates DTOs using class-validator. Apply pipes with @UsePipes().

Package: @hazeljs/core See: Pipes Guide

Middleware

HazelJS Middleware is a function or class that runs early in the request pipeline, before routing. HazelJS Middleware is used for body parsing, CORS, logging, rate limiting, and security headers. HazelJS Middleware does not have access to the matched route or handler metadata.

Package: @hazeljs/core See: Middleware Guide

Exception Filter

A HazelJS Exception Filter is a class that implements ExceptionFilter and catches thrown errors to format HTTP error responses. The built-in HazelJS HttpExceptionFilter handles HttpError subclasses. Custom exception filters are bound with @Catch().

Package: @hazeljs/core See: Exception Filters Guide

Scope

A HazelJS Scope defines the lifecycle of a provider instance. HazelJS supports three scopes: singleton (one instance shared across the application, the default), transient (new instance per injection point), and request (new instance per HTTP request).

Package: @hazeljs/core See: Providers Guide

HazelApp

HazelApp is the main application class in HazelJS. HazelApp bootstraps a HazelJS application from a root module, starts the HTTP server, and provides methods for global configuration (setGlobalPrefix, enableCors, setRequestTimeout, addEarlyHandler, addProxyHandler).

Package: @hazeljs/core See: API Reference

RequestContext

RequestContext is an object in HazelJS that contains parsed request data: method, url, headers, params, query, body, user, and dtoType. RequestContext is passed through the HazelJS request pipeline and is available to pipes, guards, and interceptors.

Package: @hazeljs/core See: API Reference

AI Terms

AI Provider

A HazelJS AI Provider is a configured connection to an LLM service (OpenAI, Anthropic, Gemini, Cohere, or Ollama). AI Providers are registered through AIModule.register() in @hazeljs/ai. The HazelJS AI Provider abstraction allows switching between LLM services without changing application code.

Package: @hazeljs/ai See: AI Package

AIEnhancedService

AIEnhancedService is the primary service in @hazeljs/ai for making LLM calls. AIEnhancedService provides a fluent API: .chat(message).system(prompt).model(name).temperature(t).text(). AIEnhancedService replaces the deprecated AIService.

Package: @hazeljs/ai See: AI Package

AIModule

AIModule is the HazelJS module for AI integration. Register AIModule with AIModule.register({ provider, apiKey, model }) in a module's imports array. AIModule provides AIEnhancedService to all controllers and services in the importing module.

Package: @hazeljs/ai See: AI Package

Context Window

The context window is the maximum number of tokens an LLM can process in a single request (prompt + completion). HazelJS AI features like RAG and memory must fit retrieved context within the LLM's context window. HazelJS AIEnhancedService provides token tracking to monitor context window usage.

Package: @hazeljs/ai See: AI Package

Tool Calling

Tool calling is the pattern where an LLM requests execution of a specific function (tool) and the framework executes the tool and returns the result to the LLM. In HazelJS, tools are defined with @Tool() on agent methods. The HazelJS Agent Runtime handles the tool calling loop automatically.

Package: @hazeljs/agent See: Agent Package

Prompt Pipeline

A HazelJS Prompt Pipeline is a sequence of operations that constructs, transforms, and sends a prompt to an LLM. A typical HazelJS prompt pipeline: set system message → inject context from RAG → inject user message → send to LLM → parse response. HazelJS @hazeljs/prompts provides template management for prompt pipelines.

Package: @hazeljs/ai, @hazeljs/prompts See: AI Package, Prompts Package

Agent Terms

Agent

A HazelJS Agent is a class decorated with @Agent(config) that represents an LLM-driven component with tools, memory, and optional delegation to other agents. The HazelJS Agent Runtime manages the agent's execution loop: receive input → think (LLM call) → use tools → persist state → respond. Agents are registered as providers in a HazelJS module.

Package: @hazeljs/agent See: Agent Package

Agent Runtime

The HazelJS Agent Runtime is the execution engine for HazelJS agents. The Agent Runtime manages the agent lifecycle: loading state, loading memory, making LLM calls, executing tools, persisting state, and deciding when to stop. The Agent Runtime supports single-agent execution and multi-agent patterns (delegation, pipelines, supervisors, graphs).

Package: @hazeljs/agent See: Agent Package

Tool

A HazelJS Tool is a method decorated with @Tool(config) on an agent class. Tools are functions that the LLM can request the agent to execute during the agent's think-act loop. Each HazelJS Tool has a name, description, input schema, and optional approval requirement, timeout, and retry configuration.

Package: @hazeljs/agent See: Agent Package

Prompt Registry

The HazelJS Prompt Registry is a centralized store for LLM prompt templates with {{variable}} placeholders, versioning, and file/Redis/database backends. Use @hazeljs/prompts instead of scattering prompt strings across services. Render templates at runtime and hot-swap from Redis without redeploying code.

Package: @hazeljs/prompts See: Prompts Package, Installation — prompt templates

MCP (Model Context Protocol)

MCP in HazelJS is integration with Model Context Protocol servers so agents and AI services can discover and call external tools through a standard protocol. Install @hazeljs/mcp when your agent needs filesystem, database, or third-party MCP tool servers—not for basic @Tool() methods on your own services.

Package: @hazeljs/mcp See: MCP Package

Observability (OpenTelemetry)

HazelJS Observability wraps agent and LLM calls with OpenTelemetry spans, token/cost tracking, and the @Trace() decorator. Use @hazeljs/observability when you need production tracing (“why did this agent loop fail?”), not for application business logging (use @hazeljs/audit for audit trails).

Package: @hazeljs/observability See: Observability Package

Delegate

@Delegate(config) is a HazelJS decorator that enables one agent to delegate a subtask to another agent. The delegating agent's method body is replaced at runtime with a call to the target agent. HazelJS Delegation is one of several multi-agent patterns alongside pipelines, supervisors, and agent graphs.

Package: @hazeljs/agent See: Agent Package

Human-in-the-Loop

Human-in-the-loop in HazelJS is a pattern where the HazelJS Agent Runtime pauses agent execution to request human approval before executing a tool. Tools that require approval are configured with requireApproval: true in the @Tool() decorator. The Agent Runtime waits for external approval before continuing execution.

Package: @hazeljs/agent See: Agent Package

Memory (Agent Memory)

HazelJS Agent Memory is the system that stores and retrieves conversation history, entity facts, semantic facts, and working memory for agents. HazelJS Memory supports multiple storage strategies: BufferMemory (in-memory), VectorMemory (vector store), and HybridMemory (combined). Memory is configured per-agent and shared with RAG when needed.

Package: @hazeljs/agent, @hazeljs/memory See: Memory Guide, Memory Package

RAG Terms

RAG (Retrieval-Augmented Generation)

RAG in HazelJS is the pattern of retrieving relevant documents from a vector store and injecting retrieved context into an LLM prompt to generate grounded responses. HazelJS RAG is implemented in @hazeljs/rag with decorators like @SemanticSearch, @HybridSearch, and agentic RAG strategies.

Package: @hazeljs/rag See: RAG Package, RAG Patterns Guide

Agentic RAG

HazelJS Agentic RAG extends basic RAG with advanced retrieval strategies: query planning (@QueryPlanner), self-reflective retrieval (@SelfReflective), adaptive retrieval (@AdaptiveRetrieval), multi-hop retrieval (@MultiHop), HyDE (@HyDE), corrective RAG (@CorrectiveRAG), and more. These strategies use the LLM to improve retrieval quality.

Package: @hazeljs/rag See: RAG Package, Agentic RAG Guide

Embedding

An embedding in HazelJS is a numeric vector representation of text. HazelJS RAG generates embeddings using AI providers (OpenAI, Cohere, etc.) and stores embeddings in vector stores for similarity search. The @AutoEmbed() decorator automatically generates embeddings for data.

Package: @hazeljs/rag See: RAG Package, Vector Stores Guide

Vector Store

A HazelJS Vector Store is a database that stores embeddings and supports similarity search (nearest-neighbor lookup). HazelJS RAG supports Pinecone, Weaviate, Qdrant, Chroma, pgvector, and in-memory vector stores. Vector stores are configured through @hazeljs/rag module registration.

Package: @hazeljs/rag See: RAG Package, Vector Stores Guide

HazelJS Semantic Search is a vector-based search that finds documents similar in meaning to a query, regardless of exact keyword matches. Implemented with the @SemanticSearch() decorator in @hazeljs/rag. Semantic search embeds the query, searches the vector store, and returns the most similar documents.

Package: @hazeljs/rag See: RAG Package

HazelJS Hybrid Search combines vector-based semantic search with keyword-based search for better retrieval accuracy. Implemented with the @HybridSearch() decorator in @hazeljs/rag. Hybrid search is recommended when queries may contain specific terms or identifiers that semantic search alone might miss.

Package: @hazeljs/rag See: RAG Package

Document Loader

A HazelJS Document Loader ingests documents from various sources (files, URLs, databases) and prepares the documents for chunking and embedding. HazelJS provides loaders for PDF, HTML, JSON, CSV, Markdown, and plain text.

Package: @hazeljs/rag See: Document Loaders Guide

Chunk / Chunking

Chunking in HazelJS RAG is the process of splitting documents into smaller pieces (chunks) for embedding and storage in a vector store. HazelJS supports fixed-size chunking, semantic chunking, and structure-aware chunking. Chunk size affects retrieval quality and context window usage.

Package: @hazeljs/rag See: RAG Patterns Guide

Infrastructure Terms

Job Queue (BullMQ)

A HazelJS job queue is a Redis-backed background work queue using BullMQ (@hazeljs/queue). Enqueue jobs from controllers/services; process them in a worker with @Processor() / @Process(). Use queue for async jobs with retries and delays (emails, webhooks, AI tasks). Use cron for time-based schedules. Use worker for CPU-bound thread offload, not Redis job persistence.

Package: @hazeljs/queue See: Queue Package, Worker Package, Cron Package

Worker Threads

HazelJS Worker (@hazeljs/worker) offloads CPU-intensive JavaScript to Node.js worker threads in the same deployment. Use it for image processing, heavy parsing, or ML inference on a thread pool—not for durable job queues (use @hazeljs/queue) and not for cron schedules (use @hazeljs/cron).

Package: @hazeljs/worker See: Worker Package, Queue Package

Cron Schedule

HazelJS Cron (@hazeljs/cron) runs decorated methods on a schedule (@Cron('0 * * * *')). Use for recurring maintenance, reports, or polling. For one-off or user-triggered async jobs with retry semantics, use @hazeljs/queue instead.

Package: @hazeljs/cron See: Cron Package, Queue Package

Kafka (event streaming)

HazelJS Kafka (@hazeljs/kafka) integrates with Apache Kafka for high-throughput event streaming between microservices. Use Kafka when many services publish/consume the same event log. Use @hazeljs/pubsub for Google Cloud Pub/Sub. Use @hazeljs/messaging for WhatsApp/Telegram/Viber channels. Use @hazeljs/event-emitter for in-process events inside one Node app.

Package: @hazeljs/kafka See: Kafka Package, PubSub Package, Messaging Package

Circuit Breaker

A HazelJS Circuit Breaker is a resilience pattern that stops calling a failing service after a threshold of failures. Applied with @CircuitBreaker(config) from @hazeljs/resilience. States: closed (normal), open (failing, returns fallback), half-open (testing recovery).

Package: @hazeljs/resilience See: Resilience Package

Guardrail

A HazelJS Guardrail is an input or output safety check for AI-powered endpoints. Input guardrails (@GuardrailInput) detect prompt injection, PII, and unsafe content before processing. Output guardrails (@GuardrailOutput) validate and filter LLM responses before returning them to the client.

Package: @hazeljs/guardrails See: Guardrails Package

Flow

A HazelJS Flow is a durable execution graph defined with @Flow(flowId, version). Flows consist of nodes (@Node) connected by edges (@Edge). HazelJS Flows support wait/resume, idempotency, retries, and persistent state. Use @hazeljs/flow for long-running workflows inside your app process. Use @hazeljs/flow-runtime when flows should run as a separate HTTP service.

Package: @hazeljs/flow See: Flow Package, Flow Runtime Package

Flow Runtime

HazelJS Flow Runtime is a standalone HTTP service for executing @hazeljs/flow graphs: start runs, tick progress, and resume after waits via REST. Install @hazeljs/flow-runtime when multiple apps or workers call the same flow engine; use @hazeljs/flow alone when flows run in-process with your API.

Package: @hazeljs/flow-runtime See: Flow Runtime Package, Flow Package

Pipeline (Data)

A HazelJS Data Pipeline is a data processing unit (ETL or stream) defined with @Pipeline() from @hazeljs/data. Pipelines run transforms (@Transform), validations (@Validate), and streams (@Stream). Includes PII handling decorators (@Mask, @Redact, @Encrypt, @Decrypt).

Package: @hazeljs/data See: Data Package

Golden dataset (AI evaluation)

A golden dataset is a JSON file (name, version, cases[]) where each case has an input and optional expectedOutput, expectedToolCalls, and expectedRetrievedIds. HazelJS loads it with @hazeljs/eval and runs your RAG or agent behind runGoldenDataset to produce scores and CI pass/fail results.

Package: @hazeljs/eval See: Eval Package