Hooks Overview

Hooks are the middleware layer for event-spec's event pipeline. They execute at four lifecycle stages around provider dispatch, enabling cross-cutting concerns like validation, sampling, consent, PII stripping, and observability without touching provider code.

Execution order

Before runs once for all providers. A non-nil error return from any Before hook cancels the entire dispatch and marks the event as Dropped.

After, Error, and Finally run once per provider result in reverse registration order.

Base type

Use UnimplementedHook as a base to get no-op implementations of all four stages, then override only the ones you need:

Go

type MyHook struct {
    hooks.UnimplementedHook
}

TypeScript

class MyHook extends UnimplementedHook {
  // override only the stages you need
}

Kotlin

class MyHook : UnimplementedHook() {
    // override only the stages you need
}

Registering hooks

Go

// Client-level hooks
client := analytics.NewClient(
    analytics.WithHooks(
        validation.New(lookup),
        sampling.New(cfg),
    ),
)

// API-level (applies to all clients)
analytics.AddGlobalHook(myCustomHook)

TypeScript

// Client-level hooks
const client = new Client({
  hooks: [new ValidationHook(lookup), new SamplingHook(cfg)],
});

// API-level (applies to all clients)
addGlobalHooks(myCustomHook);

Kotlin

// Client-level hooks
val client = Client(ClientOptions(
    hooks = listOf(ValidationHook(validator), SamplingHook(lookup)),
))

// API-level (applies to all clients)
addGlobalHooks(myCustomHook)

Built-in hooks

Hook	Package	Status
Sampling	hooks/sampling	✅ Available
Validation	hooks/validation	✅ Available
Logging	hooks/logging	❌ Planned
OpenTelemetry	hooks/otel	❌ Planned

Custom hooks

See Custom Hooks for a full walkthrough of writing and registering your own hook.