interface FilterCompilerOptions

Options for configuring the FilterCompiler.

All fields are optional. The most commonly used fields are:

  • logger — route compilation messages to your own logger
  • events — subscribe to source/transformation/compilation lifecycle events
  • hookManager — attach fine-grained before/after/error hooks around each individual transformation in the pipeline

Hook manager vs events

events (via ICompilerEvents) and hookManager (via TransformationHookManager) are two complementary observability layers:

Feature ICompilerEvents TransformationHookManager
Granularity compiler-level (source start/complete, progress, etc.) per-transformation (before/after/error)
Async support callbacks are synchronous hooks can be async
Error hooks none for transformations yes — onTransformError
Timing data durationMs in complete event durationMs in after hook

When you provide both events and hookManager, the compiler automatically bridges onTransformationStart/onTransformationComplete events through the hook manager so both systems fire.

When you provide only events (the common case), the compiler internally creates a TransformationHookManager wired to a bridge hook — no change to existing usage is required.

Properties

optional
logger: ILogger

Logger for compilation messages — defaults to the module default logger

Compiler-level event handlers for observability.

These fire at source and compilation boundaries. For per-transformation hooks (including async hooks and error hooks) use hookManager instead.

Transformation lifecycle hooks.

Attach beforeTransform, afterTransform, and onError callbacks to individual transformations in the pipeline. When omitted, a NoOpHookManager is used (zero overhead).

If events are also provided, the compiler automatically registers a bridge hook that forwards onTransformationStart / onTransformationComplete events — so both systems fire without double-registration.

Tracing context for diagnostics

optional
dependencies: FilterCompilerDependencies

Injectable dependencies (for testing/customization)

Options for the HTTP downloader (timeout, retries, user-agent)

Usage

import { type FilterCompilerOptions } from ".";