Concepts & Glossary

Short definitions of HazelJS types and concepts across all packages (core, data, ml, agent, ai, rag, auth, serverless, resilience, and more), with links to full documentation. Use this page to quickly look up terms and find the right guide or package doc.

Request / response lifecycle

  • RequestContext — Parsed request data (method, url, headers, params, query, body, user) passed through the pipeline. Used by pipes, guards, and interceptors. See Controllers and API Reference.
  • ArgumentsHost — Abstraction over the execution context (HTTP, etc.). Exposes getRequest(), getResponse(). Used in exception filters. See Exception Filters and API Reference.
  • ExecutionContext — Extends the request/response context with switchToHttp() returning request, response, and RequestContext. Passed to guards in canActivate(context). See Guards and API Reference.

Authorization & validation

  • CanActivate — Interface for guards. Implement canActivate(context: ExecutionContext): boolean | Promise<boolean>. Return true to allow the request, false to deny (403). See Guards.
  • PipeTransform — Interface for pipes. Implement transform(value, context): value | Promise<value> to transform or validate input (e.g. route params, query, body). See Pipes and API Reference.
  • Interceptor — Interface for interceptors. Implement intercept(context, next): Promise<result> to wrap handler execution (before/after, transform result or errors). See Interceptors and API Reference.
  • ExceptionFilter — Interface for exception filters. Implement catch(exception, host) to format errors and send the response. See Exception Filters and API Reference.

Organization & DI

  • Module — Organizational unit: groups controllers, providers, and imports. Defined with @HazelModule(). See Modules.
  • Provider — Injectable class (service, factory, etc.) registered in a module. Resolved by the DI container. See Providers.
  • Scope — Lifecycle of a provider: singleton (default), transient (new instance per injection), request (per HTTP request). See Providers and API Reference.

Decorators by package

Decorators are spread across @hazeljs/core and many optional packages. Below is a quick reference by package, with links to full docs.

Core (@hazeljs/core)

  • @Controller(path) — Class decorator; marks a controller and sets route prefix. See Controllers.
  • @Get(), @Post(), @Put(), @Delete(), @Patch() — Method decorators; register HTTP routes. See Controllers.
  • @Body(), @Param(), @Query(), @Req(), @Res(), @Headers(), @Request() — Parameter decorators; inject request data. See Controllers and API Reference.
  • @Ip(), @Host() — Parameter decorators; inject client IP and host. See API Reference.
  • @UseGuards(), @UseInterceptors(), @UsePipes() — Apply guards, interceptors, or pipes to a controller or method. See Guards, Interceptors, Pipes.
  • @Public() / @SkipAuth() — Mark a route as public so guards skip auth. See Guards.
  • @Timeout(), @Optional(), @Session(), @Retry(), @ApiTags(), @ApiOperation() — Method/parameter decorators for timeouts, optional params, session, retry, and OpenAPI metadata. See API Reference.
  • SetMetadata(key, value) — Attach custom metadata to a class or method; read with getMetadata(key, target, propertyKey?). See API Reference and Guards.
  • createParamDecorator(resolve) — Build custom parameter decorators that inject values from (req, context, container). See API Reference.
  • @Injectable(), @Service() — Class decorators; register providers in DI. See Providers.

Full list: API Reference.

Data (@hazeljs/data)

Pipelines, streaming, validation, and PII handling. See Data package.

  • @Pipeline(options) — Class decorator; marks a class as a data pipeline (ETL/stream).
  • @Transform(options) — Method/property decorator; define field transformations.
  • @Validate(options) — Method/property decorator; define validation rules.
  • @Stream(options) — Method decorator; mark a method as a stream processor.
  • @Mask(), @Redact(), @Encrypt(), @Decrypt() — PII decorators for masking, redaction, and encryption.

ML (@hazeljs/ml)

Model registration, training, and inference. See ML package.

  • @Model() — Class decorator; registers an ML model with the framework.
  • @Train(options) — Method decorator; marks a training entrypoint.
  • @Predict(options) — Method decorator; marks an inference method.

Agent (@hazeljs/agent)

Agents, tools, and agent-to-agent delegation. See Agent package.

  • @Agent(config) — Class decorator; marks a class as an agent (name, description, model, etc.).
  • @Tool(config) — Method decorator; marks a method as a tool callable by agents.
  • @Delegate(config) — Method decorator; delegates to another agent (method body replaced at runtime).

AI (@hazeljs/ai)

LLM integration, AI-powered methods, and validation. See AI package.

  • AITask — Configurable AI task execution (exported from core; used with AI module).
  • @AIFunction(options) — Method decorator; marks a method as AI-powered (provider, model, streaming).
  • @AIPrompt() — Parameter decorator; injects the prompt argument for AI methods.
  • @AIValidate(options) — Class decorator; AI-powered validation for DTOs.
  • @AIValidateProperty(options) — Property decorator; per-field AI validation.

RAG (@hazeljs/rag)

Retrieval-augmented generation, vector search, and agentic RAG. See RAG package.

  • @RAG(options) — Class decorator; configure RAG at module level (vector DB, embedding model, chunk size).
  • @SemanticSearch(options) — Method decorator; enable semantic (vector) search on a method.
  • @HybridSearch(options) — Method decorator; vector + keyword hybrid search.
  • @AutoEmbed() — Method decorator; auto-generate embeddings for method data.
  • @Embeddable(options) — Class decorator; mark an entity as embeddable; @VectorColumn() — property decorator for vector storage.
  • Agentic RAG — @QueryPlanner(), @SelfReflective(), @AdaptiveRetrieval(), @MultiHop(), @HyDE(), @CorrectiveRAG(), @ContextAware(), @QueryRewriter(), @SourceVerification(), @ActiveLearning(), @Feedback(), @Cached() — method decorators for advanced retrieval strategies. See RAG package.

Serverless (@hazeljs/serverless)

  • @Serverless(options) — Class decorator; mark a controller as serverless-optimized (memory, timeout, runtime, cold start). See Serverless package.

Auth & authorization

  • @CurrentUser(field?) — Parameter decorator; inject the authenticated user (or a field like role). Requires a guard that sets req.user. See Auth package.
  • @Ability() — Parameter decorator; inject the current user's CASL ability. See CASL package.
  • @CheckPolicies(...handlers) — Method decorator; register CASL policy handlers (equivalent to @UseGuards(PoliciesGuard(...))). See CASL package.

i18n (@hazeljs/i18n)

  • @Lang() — Parameter decorator; inject the detected locale string. See i18n package.

Audit (@hazeljs/audit)

  • @Audit(options) — Method/class decorator; mark for audit logging. See Audit package.

Guardrails (@hazeljs/guardrails)

Content safety and output validation. See Guardrails package.

  • @GuardrailInput(options) — Method decorator; run input guardrails (injection, PII, etc.) before the handler.
  • @GuardrailOutput(options) — Method decorator; run output guardrails on the response.

Resilience (@hazeljs/resilience)

Circuit breaker, retry, timeout, bulkhead, rate limit. See Resilience package.

  • @CircuitBreaker(config) — Method decorator; wrap with circuit breaker; supports @Fallback(primaryMethod) for fallback method.
  • @Retry(config) — Method decorator; retry on failure.
  • @Timeout(duration) — Method decorator; enforce a timeout.
  • @Bulkhead(config) — Method decorator; limit concurrent executions.
  • @RateLimit(config) — Method decorator; rate limit invocations.

Queue (@hazeljs/queue)

  • @Queue(queueName, options?) — Method decorator; mark a method as a queue job processor. See package docs.

Cache (@hazeljs/cache)

  • @Cache(options) — Method decorator; cache method results (strategy, ttl, key, tags). See Cache package.

Cron (@hazeljs/cron)

  • @Cron(expression, options?) — Method decorator; register a cron job. See Cron package.

Kafka (@hazeljs/kafka)

  • @KafkaConsumer(options) — Class decorator; mark a class as a Kafka consumer. @KafkaSubscribe(topic, options?) — Method decorator; subscribe to a topic. See Kafka package.

WebSocket (@hazeljs/websocket)

  • @Realtime(pathOrOptions) — Class decorator; mark a class as a WebSocket gateway. See WebSocket package.

GraphQL (@hazeljs/graphql)

  • @Resolver(name?) — Class decorator; mark a class as a GraphQL resolver. @Query(), @Mutation() — Method decorators; @Arg() — Parameter decorator; @ObjectType(), @Field() — Class/property decorators for schema. See GraphQL package.

gRPC (@hazeljs/grpc)

  • @GrpcMethod(serviceName, methodName?) — Method decorator; expose a gRPC method. See gRPC package.

Gateway (@hazeljs/gateway)

API gateway routing and policies. See Gateway package.

  • @Gateway(config) — Class decorator; gateway definition.
  • @Route(pathOrConfig), @ServiceRoute(nameOrConfig), @VersionRoute(config), @Canary(config), @TrafficPolicy(config) — Property decorators for routes and policies.
  • @GatewayCircuitBreaker(config), @GatewayRateLimit(config) — Property decorators for per-route resilience.

Event Emitter (@hazeljs/event-emitter)

Flow (@hazeljs/flow)

  • @Flow(flowId, version) — Class decorator; define a workflow. @Entry(), @Node(id, options?), @Edge(target, options?) — Method/property decorators for entry node, nodes, and edges. Build with buildFlowDefinition(FlowClass). See Flow package. Use Flow Runtime for a standalone HTTP API.

Prisma / TypeORM

  • @Repository(options) — Class decorator; register a repository (model/entity). @InjectRepository() — Parameter decorator; inject a repository. See Prisma package, TypeORM package.

Discovery (@hazeljs/discovery)

  • ServiceRegistry (class decorator) and InjectServiceClient (parameter decorator) for service discovery and client injection. See Discovery package.

Concepts by package

Short definitions of important terms from each ecosystem package (not just decorators). Full details are in each package’s docs.

  • Pipeline — Data processing unit (ETL or stream) defined with @Pipeline; runs transforms and validations. Data.
  • Agent — LLM-driven component with tools and optional delegation to other agents; registered with @Agent. Agent.
  • Tool — Method callable by an agent, registered with @Tool; can require approval, timeouts, retries. Agent.
  • RAG (Retrieval-Augmented Generation) — Use vector search and retrieved context to augment LLM prompts; configured with @RAG and methods like @SemanticSearch. RAG.
  • Vector store / Embedding — Storage for embeddings and similarity search; RAG supports Pinecone, Weaviate, Qdrant, Chroma, etc. RAG.
  • Agentic RAG — Advanced RAG strategies (query planning, multi-hop, HyDE, corrective RAG, context-aware, etc.) via decorators. RAG.
  • AIFunction / AITask — AI-powered method or task with provider, model, and optional streaming; validated with @AIValidate where needed. AI.
  • Circuit breaker / Retry / Bulkhead / Rate limit — Resilience patterns applied via decorators in @hazeljs/resilience. Resilience.
  • Guardrail — Input/output checks (injection, PII, content safety) via @GuardrailInput / @GuardrailOutput. Guardrails.
  • Repository — Data access abstraction over Prisma or TypeORM; @Repository + @InjectRepository(). Prisma, TypeORM.
  • Flow / Run — Durable execution graph: nodes, edges, wait/resume, idempotency, retries. Define with @Flow, @Node, @Edge; run in-process or via Flow Runtime HTTP API. Flow.
  • Service discovery — Registry and client for discovering and calling services (e.g. by name); used by Gateway and other packages. Discovery.

Differences at a glance

  • Guard vs Interceptor — Guards run before the handler and decide whether the request is allowed (auth/authz). Interceptors run around the handler and can transform the result or add logging/caching/retry. See Guards and Interceptors.
  • Pipe vs Interceptor — Pipes transform or validate one value (e.g. a param or the body) before it reaches the handler. Interceptors wrap the whole handler and can change the response or handle errors. See Pipes and Interceptors.
  • Middleware vs Guard — Middleware runs early in the request pipeline (e.g. body parsing, CORS). Guards run after the route is matched and can access the execution context (e.g. to check roles). See Middleware and Guards.