Waaatcher

A Swift package for watching file system events on macOS using FSEvents.

Features

• Modern Swift - Swift 5.9+ with Sendable conformance
• Async/Await - Native AsyncSequence support
• Combine - Publisher for reactive programming
• Callback - Traditional callback-based API
• File-level events - Granular notifications for file changes
• Configurable - Latency, flags, and event filtering

Installation

Swift Package Manager

Add to your Package.swift:

dependencies:[.package(url:"https://github.com/hechen/Waaatcher.git", from:"2.0.0")]

Or in Xcode: File → Add Package Dependencies → Enter the repository URL.

Usage

Async/Await (Recommended)

import Waaatcher
letwatcher=Waaatcher(paths:["/path/to/watch"])
// Events are delivered as an AsyncSequence
forawaiteventin watcher.events {print("Event: \(event.path)")print("Flags: \(event.flags)")if event.flags.contains(.itemCreated){print("File created!")}if event.flags.contains(.itemModified){print("File modified!")}}

Combine

import Waaatcher
import Combine
letwatcher=Waaatcher(paths:["/path/to/watch"])varcancellables=Set<AnyCancellable>()
watcher.eventPublisher
.filter{ $0.flags.contains(.itemModified)}.sink{ event inprint("Modified: \(event.path)")}.store(in:&cancellables)

Callback

import Waaatcher
letwatcher=Waaatcher(paths:["/path/to/watch"]){ events inforeventin events {print("Event: \(event)")}}try watcher.start()
// Later...
watcher.stop()

Configuration

letwatcher=Waaatcher(
paths:["/path/to/watch","/another/path"],
latency:0.3, // Seconds before events are delivered
flags:[.useCFTypes,.fileEvents,.ignoreSelf])

Event Types

FSEvent

publicstructFSEvent{letpath:String // Path where event occurred
letflags:FSEventFlags // Event type flags
letid:FSEventStreamEventId // Unique event ID
}

FSEventFlags

Common flags you'll encounter:

Flag	Description
.itemCreated	File or directory was created
.itemRemoved	File or directory was deleted
.itemRenamed	File or directory was renamed
.itemModified	File contents were modified
.itemIsFile	Event target is a file
.itemIsDir	Event target is a directory
.itemIsSymlink	Event target is a symbolic link

StreamCreateFlags

Flag	Description
.fileEvents	Receive file-level events (recommended)
.ignoreSelf	Ignore events from current process
.watchRoot	Watch for path changes
.noDefer	Deliver events immediately

Requirements

• macOS 12.0+
• Swift 5.9+
• Xcode 15+

License

MIT License - see LICENSE for details.

Credits

Originally created by Chen He in 2019. Updated in 2026 with modern Swift concurrency support.