HazelJS Concepts and Decorator Reference

Definitions of HazelJS types and concepts across all HazelJS packages (core, data, ml, agent, ai, rag, auth, serverless, resilience, and more), with links to full documentation. Use this page to look up HazelJS terms, find the right decorator, and navigate to deep-dive guides.

Quick Reference

Purpose: Quick reference for all HazelJS concepts, decorators, and terms across every HazelJS package. Serves as a lookup table for RAG retrieval and LLM context.
When to use: Reference this page when looking up a HazelJS decorator, interface, or concept. Use the Glossary for canonical term definitions.
Key concepts: RequestContext, ExecutionContext, ArgumentsHost, CanActivate, PipeTransform, Interceptor, ExceptionFilter, Module, Provider, Scope, and all package-specific decorators.
Inputs: N/A (reference page).
Outputs: N/A (reference page).
Dependencies: N/A.
Common patterns: Look up a decorator → read its signature and purpose → follow the link to the full guide or package page.
Common mistakes: Confusing HazelJS Guard with HazelJS Interceptor; confusing HazelJS Pipe with HazelJS Middleware; confusing @hazeljs/agent Agent with @hazeljs/ai AIEnhancedService.

HazelJS Request/Response Lifecycle Concepts

RequestContext

RequestContext is a HazelJS object containing parsed request data: method, url, headers, params, query, body, user, and dtoType. HazelJS passes RequestContext through the request pipeline. HazelJS pipes, guards, and interceptors receive RequestContext.

See: Controllers, API Reference

ArgumentsHost

ArgumentsHost is a HazelJS abstraction over the execution context. ArgumentsHost exposes switchToHttp() which returns getRequest() and getResponse(). HazelJS exception filters receive ArgumentsHost in the catch() method.

See: Exception Filters, API Reference

ExecutionContext

ExecutionContext extends the HazelJS request/response context with switchToHttp() returning the request, response, and RequestContext. HazelJS guards receive ExecutionContext in the canActivate(context) method.

See: Guards, API Reference

HazelJS Authorization and Validation Interfaces

CanActivate (Guard Interface)

CanActivate is the HazelJS interface for guards. Implement canActivate(context: ExecutionContext): boolean | Promise<boolean>. Return true to allow the request. Return false or throw an exception to deny the request. Apply guards with @UseGuards().

See: Guards

PipeTransform (Pipe Interface)

PipeTransform is the HazelJS interface for pipes. Implement transform(value, context): value | Promise<value> to transform or validate a single input value (route param, query param, or request body). Apply pipes with @UsePipes().

See: Pipes, API Reference

Interceptor Interface

Interceptor is the HazelJS interface for interceptors. Implement intercept(context, next): Promise<result> to wrap handler execution. HazelJS Interceptors can transform the result, add logging, implement caching, or handle errors. Apply interceptors with @UseInterceptors().

See: Interceptors, API Reference

ExceptionFilter Interface

ExceptionFilter is the HazelJS interface for exception filters. Implement catch(exception, host) to format errors and send the HTTP error response. Bind exception filters with @Catch().

See: Exception Filters, API Reference

HazelJS Organization and Dependency Injection Concepts

Module

A HazelJS Module is an organizational unit that groups controllers, providers, and imports. Define a HazelJS Module with @HazelModule(). Every HazelJS application has one root module.

See: Modules

Provider

A HazelJS Provider is an injectable class (service, factory, helper) registered in a module and resolved by the HazelJS DI container. Decorate with @Service() or @Injectable().

See: Providers

Scope

HazelJS Scope defines the lifecycle of a provider: singleton (default, one shared instance), transient (new instance per injection), request (new instance per HTTP request).

See: Providers, API Reference

When to Use: Guard vs Interceptor vs Pipe vs Middleware

HazelJS Feature	Runs when	Purpose	Interface
HazelJS Middleware	Before routing	Body parsing, CORS, logging, rate limiting	Function or class
HazelJS Guard	After routing, before handler	Authentication, authorization, role checks	`CanActivate`
HazelJS Interceptor	Around handler (before and after)	Logging, caching, response transformation, retry	`Interceptor`
HazelJS Pipe	Before handler, per input value	Input validation, type transformation	`PipeTransform`
HazelJS Exception Filter	On error (any pipeline stage)	Error formatting, error logging	`ExceptionFilter`

Key differences:

HazelJS Guard vs HazelJS Interceptor — HazelJS Guards run before the handler and decide whether the request is allowed (auth/authz). HazelJS Interceptors run around the handler and can transform the result or add cross-cutting behavior. Use a Guard for auth. Use an Interceptor for logging or caching.
HazelJS Pipe vs HazelJS Interceptor — HazelJS Pipes transform or validate one input value before the handler. HazelJS Interceptors wrap the entire handler execution. Use a Pipe for DTO validation. Use an Interceptor for response transformation.
HazelJS Middleware vs HazelJS Guard — HazelJS Middleware runs early in the pipeline (before routing). HazelJS Guards run after the route is matched and have access to the execution context and handler metadata. Use Middleware for CORS. Use a Guard for role-based access.

HazelJS Decorators by Package

Core (`@hazeljs/core`)

Decorator	Type	Purpose
`@Controller(path)`	Class	Marks a controller with route prefix
`@Get()`, `@Post()`, `@Put()`, `@Delete()`, `@Patch()`	Method	Register HTTP route handlers
`@Body()`, `@Param()`, `@Query()`, `@Req()`, `@Res()`, `@Headers()`	Parameter	Extract request data
`@Ip()`, `@Host()`, `@Session()`	Parameter	Extract client IP, host, session
`@Injectable()`, `@Service()`	Class	Register providers in DI container
`@Inject(token)`	Parameter	Explicit injection by token
`@UseGuards(...guards)`	Class/Method	Apply authorization guards
`@UseInterceptors(...interceptors)`	Class/Method	Apply interceptors
`@UsePipes(...pipes)`	Class/Method	Apply validation/transformation pipes
`@HttpCode(code)`	Method	Set response status code
`@Header(name, value)`	Method	Set response header
`@Redirect(url, code?)`	Method	Redirect response
`@Public()` / `@SkipAuth()`	Class/Method	Skip authentication guards
`@Timeout(ms)`	Method	Per-route timeout
`@Retry(options)`	Method	Retry on failure
`@Optional()`	Parameter	Mark parameter as optional
`@HazelModule(options)`	Class	Define a module
`SetMetadata(key, value)`	Class/Method	Attach custom metadata
`createParamDecorator(resolve)`	Function	Create custom parameter decorators

Full list: API Reference

Agent (`@hazeljs/agent`)

Decorator	Type	Purpose
`@Agent(config)`	Class	Mark a class as an LLM-driven agent
`@Tool(config)`	Method	Mark a method as a tool callable by agents
`@Delegate(config)`	Method	Delegate subtask to another agent

See: Agent Package

AI (`@hazeljs/ai`)

Decorator	Type	Purpose
`@AIFunction(options)`	Method	Mark a method as AI-powered
`@AIPrompt()`	Parameter	Inject prompt argument for AI methods
`@AIValidate(options)`	Class	AI-powered DTO validation
`@AIValidateProperty(options)`	Property	Per-field AI validation
`@AITask(options)`	Method	Configurable AI task execution

See: AI Package

RAG (`@hazeljs/rag`)

Decorator	Type	Purpose
`@RAG(options)`	Class	Configure RAG at module level
`@SemanticSearch(options)`	Method	Vector-based semantic search
`@HybridSearch(options)`	Method	Vector + keyword hybrid search
`@AutoEmbed()`	Method	Auto-generate embeddings
`@Embeddable(options)`	Class	Mark entity as embeddable
`@VectorColumn()`	Property	Vector storage column
`@QueryPlanner()`	Method	Agentic RAG: query planning
`@SelfReflective()`	Method	Agentic RAG: self-reflective retrieval
`@AdaptiveRetrieval()`	Method	Agentic RAG: adaptive retrieval
`@MultiHop()`	Method	Agentic RAG: multi-hop retrieval
`@HyDE()`	Method	Agentic RAG: hypothetical document embeddings
`@CorrectiveRAG()`	Method	Agentic RAG: corrective RAG
`@ContextAware()`	Method	Agentic RAG: context-aware retrieval

See: RAG Package

Data (`@hazeljs/data`)

Decorator	Type	Purpose
`@Pipeline(options)`	Class	Define a data pipeline (ETL/stream)
`@Transform(options)`	Method/Property	Define field transformations
`@Validate(options)`	Method/Property	Define validation rules
`@Stream(options)`	Method	Mark a stream processor
`@Mask()`, `@Redact()`, `@Encrypt()`, `@Decrypt()`	Property	PII handling decorators

See: Data Package

ML (`@hazeljs/ml`)

Decorator	Type	Purpose
`@Model()`	Class	Register an ML model
`@Train(options)`	Method	Training entrypoint
`@Predict(options)`	Method	Inference method

See: ML Package

Auth and Authorization

Decorator	Package	Purpose
`@CurrentUser(field?)`	`@hazeljs/auth`	Inject authenticated user
`@Ability()`	`@hazeljs/casl`	Inject CASL ability
`@CheckPolicies(...handlers)`	`@hazeljs/casl`	Register CASL policy handlers

See: Auth Package, CASL Package

Resilience (`@hazeljs/resilience`)

Decorator	Type	Purpose
`@CircuitBreaker(config)`	Method	Circuit breaker with fallback
`@Retry(config)`	Method	Retry on failure
`@Timeout(duration)`	Method	Enforce timeout
`@Bulkhead(config)`	Method	Limit concurrent executions
`@RateLimit(config)`	Method	Rate limit invocations
`@Fallback(primaryMethod)`	Method	Fallback method for circuit breaker

See: Resilience Package

Guardrails (`@hazeljs/guardrails`)

Decorator	Type	Purpose
`@GuardrailInput(options)`	Method	Input safety checks (injection, PII)
`@GuardrailOutput(options)`	Method	Output safety checks on LLM responses

See: Guardrails Package

Additional Package Decorators

Decorator	Package	Purpose
`@Serverless(options)`	`@hazeljs/serverless`	Serverless-optimized controller
`@Lang()`	`@hazeljs/i18n`	Inject detected locale
`@Audit(options)`	`@hazeljs/audit`	Audit logging
`@Queue(name, options?)`	`@hazeljs/queue`	Queue job processor
`@Cache(options)`	`@hazeljs/cache`	Cache method results (alias: `@Cacheable`)
`@CacheKey(key)`	`@hazeljs/cache`	Explicitly define cache key
`@CacheTTL(ttl)`	`@hazeljs/cache`	Define time-to-live for a method
`@CacheTags(...tags)`	`@hazeljs/cache`	Attach invalidation tags
`@CacheEvict(options)`	`@hazeljs/cache`	Invalidate cache entries by key or tags
`@CacheLock(options)`	`@hazeljs/cache`	Distributed locking for expensive operations
`@CacheAside(options)`	`@hazeljs/cache`	Load-through caching pattern
`@WriteThrough(options)`	`@hazeljs/cache`	Update cache and database synchronously
`@WriteBehind(options)`	`@hazeljs/cache`	Asynchronous database updates with batching
`@CacheWarm(options)`	`@hazeljs/cache`	Programmatic cache warming on startup
`@Cron(expression, options?)`	`@hazeljs/cron`	Register cron job
`@KafkaConsumer(options)`	`@hazeljs/kafka`	Kafka consumer
`@KafkaSubscribe(topic)`	`@hazeljs/kafka`	Subscribe to Kafka topic
`@Realtime(path)`	`@hazeljs/websocket`	WebSocket gateway
`@Resolver(name?)`	`@hazeljs/graphql`	GraphQL resolver
`@Query()`, `@Mutation()`	`@hazeljs/graphql`	GraphQL operations
`@GrpcMethod(service, method?)`	`@hazeljs/grpc`	gRPC method
`@Gateway(config)`	`@hazeljs/gateway`	API gateway definition
`@OnEvent(event, options?)`	`@hazeljs/event-emitter`	Event subscription
`@Flow(id, version)`	`@hazeljs/flow`	Durable workflow definition
`@Node(id, options?)`	`@hazeljs/flow`	Workflow node
`@Edge(target, options?)`	`@hazeljs/flow`	Workflow edge
`@Repository(options)`	`@hazeljs/prisma` / `@hazeljs/typeorm`	Data repository
`@InjectRepository()`	`@hazeljs/prisma` / `@hazeljs/typeorm`	Inject repository

HazelJS Concepts by Package

Agent Concepts

HazelJS Agent — LLM-driven component with tools, memory, and optional delegation. Registered with @Agent. See Agent Package.
HazelJS Tool — Method callable by an agent during the think-act loop. Registered with @Tool. Tools can require approval, timeouts, and retries. See Agent Package.
HazelJS Agent Runtime — Execution engine managing agent lifecycle: load state → load memory → LLM call → tool execution → persist state → respond. See Agent Package.

RAG Concepts

RAG (Retrieval-Augmented Generation) — Use vector search and retrieved context to augment LLM prompts. Configured with @RAG and methods like @SemanticSearch. See RAG Package.
HazelJS Vector Store — Storage for embeddings with similarity search. HazelJS RAG supports Pinecone, Weaviate, Qdrant, Chroma, pgvector. See RAG Package.
HazelJS Agentic RAG — Advanced RAG strategies (query planning, multi-hop, HyDE, corrective RAG) via decorators. See RAG Package.

AI Concepts

HazelJS AIEnhancedService — Primary service for LLM calls with fluent API. See AI Package.
HazelJS HCEL (HazelJS Composable Expression Language) — Fluent DSL for composing AI chains. See HCEL Guide.
HazelJS AssistantFacade — High-level conversational assistant management with memory. See AI Package.
HazelJS AIFunction / AITask — AI-powered method or task with provider, model, and optional streaming. See AI Package.

Evaluation & quality

Golden dataset — Versioned JSON list of test cases (user input plus optional expected answer substrings, tool names, and document IDs) used to regression-test RAG and agents. See Eval Package.
HazelJS eval metrics — Classical IR metrics (precision/recall@k, MRR, NDCG), RAG helpers, trajectory scoring for tool calls, and LLM-judge prompt builders, plus reportEvalForCi for pipelines. See Eval Package.

Infrastructure Concepts

HazelJS Circuit Breaker / Retry / Bulkhead / Rate Limit — Resilience patterns via @hazeljs/resilience decorators. See Resilience Package.
HazelJS Guardrail — Input/output safety checks via @hazeljs/guardrails. See Guardrails Package.
HazelJS Repository — Data access abstraction over Prisma or TypeORM. See Prisma Package, TypeORM Package.
HazelJS Flow — Durable execution graph with nodes, edges, wait/resume, idempotency. See Flow Package.
HazelJS Service Discovery — Registry and client for service-to-service communication. See Discovery Package.

Glossary — Canonical term definitions for all HazelJS concepts
Introduction — HazelJS overview and architecture
API Reference — Complete @hazeljs/core API
Installation — Setup and package list

Next Concepts to Learn

Controllers — HTTP routing and request handling
Providers — Dependency injection
Modules — Application organization
AI Package — LLM integration
Agent Package — Agent Runtime
RAG Package — Retrieval-augmented generation
Eval Package — Golden datasets and CI evaluation for AI features