README
¶
hook
A lightweight, generic, observe-only event system. Register handlers for arbitrary event types; handlers run sequentially in registration order. Non-fatal errors are aggregated and surfaced through the canonical on_error event — only errors wrapping ErrFatalHook abort dispatch. The package is domain-agnostic: applications define their own event types by implementing the Event interface.
Install
go get github.com/kbukum/gokit
Quick Start
package main
import (
"context"
"fmt"
"github.com/kbukum/gokit/hook"
)
type userCreated struct{ ID string }
func (userCreated) Type() hook.EventType { return "user_created" }
func main() {
reg := hook.NewRegistry()
unsubscribe := reg.On("user_created", func(ctx context.Context, e hook.Event) error {
fmt.Printf("event: %s\n", e.Type())
return nil
})
defer unsubscribe()
_ = reg.Emit(context.Background(), userCreated{ID: "u1"})
}
Key Types & Functions
| Name | Description |
|---|---|
NewRegistry() |
Create a handler registry |
Registry.On(type, handler) |
Register a handler; returns an unsubscribe func |
Registry.Emit(ctx, event) |
Dispatch an event to registered handlers |
Registry.HasHandlers(type) / Clear(types...) |
Introspect / remove handlers |
Event |
Interface implemented by application event types (Type()) |
EventType |
String key identifying an event type |
Handler |
func(ctx, event) error handler signature |
ErrorEvent / ErrFatalHook |
Canonical error event and fatal-abort sentinel |
Documentation
¶
Overview ¶
Package hook provides a lightweight, generic observe-only event system.
It allows registering handlers for arbitrary event types. Handlers run sequentially in registration order. Non-fatal errors are aggregated and observed through the canonical on_error event; only errors wrapping ErrFatalHook abort dispatch.
The hook module is domain-agnostic — applications define their own event types by implementing the Event interface.
Usage:
registry := hook.NewRegistry()
registry.On("my_event", func(ctx context.Context, e hook.Event) error {
log.Printf("event: %s", e.Type())
return nil
})
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrFatalHook = errors.New("hook: fatal")
ErrFatalHook marks a hook error as fatal to the caller's flow.
Functions ¶
This section is empty.
Types ¶
type ErrorEvent ¶
ErrorEvent reports a non-fatal hook handler error.
func (ErrorEvent) Type ¶
func (ErrorEvent) Type() EventType
Type returns the canonical hook error event type.
type Event ¶
type Event interface {
// Type returns the event type identifier.
Type() EventType
}
Event is the interface for all hook events. Applications define concrete event types that implement this interface.
type EventType ¶
type EventType string
EventType identifies the kind of hook event. Applications define their own EventType constants.
const EventOnError EventType = "on_error"
EventOnError is emitted when a non-fatal hook handler returns an error.
type Handler ¶
Handler observes a hook event. Returning a non-nil error records the failure; only errors wrapping ErrFatalHook abort dispatch.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry manages hook handlers and dispatches events. Handlers are executed sequentially in registration order. Non-fatal errors are aggregated and emitted as EventOnError observations. Fatal errors short-circuit dispatch when they wrap ErrFatalHook.
func (*Registry) Clear ¶
Clear removes all handlers for the given event type. If no event type is specified, clears all handlers.
func (*Registry) Emit ¶
Emit dispatches an event to all registered handlers for its type. Panicking handlers are recovered and converted to non-fatal errors. Non-fatal errors do not stop dispatch; each is observed through EventOnError and the aggregate is returned. Fatal errors wrapping ErrFatalHook return immediately.
func (*Registry) HasHandlers ¶
HasHandlers returns true if any handlers are registered for the event type.
Source Files