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

let watcher = Waaatcher(paths: ["/path/to/watch"])

// Events are delivered as an AsyncSequence
for await event in 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

let watcher = Waaatcher(paths: ["/path/to/watch"])
var cancellables = Set<AnyCancellable>()

watcher.eventPublisher
    .filter { $0.flags.contains(.itemModified) }
    .sink { event in
        print("Modified: \(event.path)")
    }
    .store(in: &cancellables)

Callback

import Waaatcher

let watcher = Waaatcher(paths: ["/path/to/watch"]) { events in
    for event in events {
        print("Event: \(event)")
    }
}

try watcher.start()

// Later...
watcher.stop()

Configuration

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

Event Types

FSEvent

public struct FSEvent {
    let path: String              // Path where event occurred
    let flags: FSEventFlags       // Event type flags
    let id: 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.