API Reference

Core Types

Watcher

The main type. Created with New(), implements io.Closer.

type Watcher struct { /* fields */ }

Methods

func New(paths []string, opts ...Option) (*Watcher, error)
func (w *Watcher) Watch(ctx context.Context) (<-chan Event, error)
func (w *Watcher) WatchOnce(ctx context.Context) (Event, error)
func (w *Watcher) Add(path string) error
func (w *Watcher) AddRecursive(path string, maxDepth int) error
func (w *Watcher) Remove(path string) error
func (w *Watcher) WatchList() []string
func (w *Watcher) Stats() Stats
func (w *Watcher) Errors() <-chan error
func (w *Watcher) IsClosed() bool
func (w *Watcher) IsWatching() bool
func (w *Watcher) Reset() error
func (w *Watcher) Close() error

Event

type Event struct {
  Path      string    // Absolute path
  Op        Op        // Create, Write, Remove, or Rename
  Timestamp time.Time // When detected
  IsDir     bool      // True if directory
  Size      int64     // File size in bytes
  ModTime   time.Time // File modification time
  Hash      string    // SHA-256 hex (with WithContentHashing)
}

Op

type Op int

const (
  Create  Op = 1
  Write   Op = 2
  Remove  Op = 3
  Rename  Op = 4
)

Event priority when multiple ops coalesce: Create > Write > Remove > Rename.

Stats

type Stats struct {
  WatchCount                  int
  IsWatching                  bool
  IsClosed                    bool
  EventsProcessed             uint64
  EventsFilteredOut           uint64
  EventsDroppedByMiddleware   uint64
  EventsDroppedByBackpressure uint64
  ErrorsEncountered           uint64
  ErrorsDropped               uint64
  WatchErrors                 uint64
  Uptime                      time.Duration
  WatchLimit                  int
  WatchBudgetCap              int
  WatchBudgetUsed             float64
  CaseSensitivity             string
  CaseSensitivityMode         FilesystemCaseSensitivity
}

Filters

type Filter func(event Event) bool

Built-in Filters

FilterExtensions, FilterIgnoreExtensions, FilterIgnoreDirs, FilterIgnoreDirsCaseInsensitive, FilterExcludePaths, FilterIgnoreHidden, FilterIgnoreGlobs, FilterOperations, FilterNotOperations, FilterGlob, FilterRegex, FilterMinSize, FilterMaxSize, FilterMinAge, FilterModifiedSince, FilterContentHash, FilterGitignore, FilterGeneratedCode, FilterGeneratedCodeFull, FilterGeneratedCodeWithFilter, FilterCaseInsensitive, FilterCaseSensitive

Combinators

FilterAnd, FilterOr, FilterNot

Metadata Filters

FilterWithMeta, FilterFromWithMeta, FilterWithMetaAnd, FilterWithMetaOr, FilterWithMetaNot, WithMeta

Middleware

type Middleware func(Handler) Handler
type Handler func(ctx context.Context, event Event) error

Built-in Middleware

MiddlewareLogging, MiddlewareRecovery, MiddlewareFilter, MiddlewareOnError, MiddlewareSlidingWindowRateLimit, MiddlewareThrottle, MiddlewareMetrics, MiddlewareDeduplicate, MiddlewareDeduplicateCaseInsensitive, MiddlewareBatch, MiddlewareWriteFileLog, MiddlewareCircuitBreaker, MiddlewareExponentialBackoff, MiddlewareErrorRateLimit, MiddlewareErrorRecovery, MiddlewareErrorCorrelation, MiddlewareErrorSanitization, MiddlewareErrorBatch

⚠️ Deprecated Middleware

Options

28 functional options:

WithDebounce, WithPerPathDebounce, WithFilter, WithExtensions, WithIgnoreDirs, WithIgnoreHidden, WithIgnorePatterns, WithRecursive, WithMiddleware, WithErrorHandler, WithSkipDotDirs, WithBuffer, WithErrorBufferSize, WithOnAdd, WithLazyIsDir, WithPolling, WithPollInterval, WithDebug, WithFollowSymlinks, WithGitignore, WithExcludePaths, WithMaxWatches, WithMaxWatchesSafetyFraction, WithWatchFilteredDirectories, WithEventChannelMode, WithContentHashing, WithContentHashMaxSize, WithSelfHeal

⚠️ Deprecated Options

Error Handling

Sentinel Errors

ErrWatcherClosed, ErrNoPaths, ErrPathNotFound, ErrPathNotDir, ErrWatcherRunning, ErrUnknownOp, ErrFsnotifyFailed, ErrWalkFailed, ErrPathResolveFailed, ErrEventProcessingFailed, ErrMiddlewareFailed

WatcherError

type WatcherError struct {
  Op       OpString
  Path     string
  Err      error
  Category ErrorCategory
  Stack    []byte
}

Methods: Error(), Unwrap(), IsTransient(), IsPermanent(), Code()

Full API on pkg.go.dev

For the complete, always-up-to-date API documentation, see pkg.go.dev.