Repository navigation
Replies: 2 comments
|
Hi @leitingzi, thanks for the detailed proposal! I'm not going to add this to FileKit for now. Until 1.0, the priority is to freeze and review the existing API (see the roadmap). A watcher is also a large surface: every target has its own mechanism, Android's SAF and the browser have no real equivalent, and I would have to maintain the event semantics (coalescing, renames, overflow) on all of them for a long time. It would work well as a separate library built on top of FileKit: on JVM, |
|
Hi @vinceglb I agree with this approach. Keeping FileKit focused on stabilizing its existing API before 1.0 is the right priority. File system watching introduces quite a bit of platform-specific complexity, so having it as a separate library for now makes a lot of sense. Building a separate directory-watching library on top of FileKit would also be a great approach. It would keep FileKit lightweight while allowing this functionality to evolve independently. |
Uh oh!
There was an error while loading. Please reload this page.
Description
It would be useful if FileKit provided a cross-platform file system watching API, allowing developers to observe changes in files and directories without implementing platform-specific solutions themselves.
FileKit already provides a unified API for common file operations, such as creating, reading, writing, copying, moving, deleting, and listing files.
However, there is currently no unified way to monitor file system changes across supported platforms.
For applications such as file managers, media libraries, document editors, and file synchronization tools, monitoring file system changes is an important capability.
I propose introducing a
FileWatcherAPI based on Kotlin CoroutinesFlow, providing both an initial directory snapshot and a stream of subsequent file system events.Motivation
Consider a file manager that displays the contents of a directory.
When the application starts monitoring a directory, it needs to:
A simple event-based watcher is not sufficient because it only reports changes occurring after monitoring starts. Developers also need an initial snapshot to populate their UI.
Additionally, performing an initial directory scan before starting the watcher can introduce a race condition: changes occurring between the scan and watcher initialization may be missed.
A unified API should consider both initial state retrieval and subsequent change notifications.
Proposed API
1. FileEvent
Represent file system changes using a sealed interface.
These events provide a normalized representation of file system changes across platforms.
The implementation should account for platform-specific differences in event availability and semantics.
2. FileWatcher
Provide an event-based watching API using
Flow.The watcher should:
3. Initial Directory Snapshot
Developers also need to retrieve the current contents of a directory when starting to monitor it.
This could be provided through a separate API:
This allows applications to obtain an initial file list and subsequently process file system events.
4. Combined Snapshot and Events API
As a higher-level API, FileKit could also provide an
observe()operation that combines the initial directory snapshot with subsequent file system events.For example:
Usage:
The implementation should establish monitoring before or during the initial scan, buffer relevant events, and account for changes occurring during snapshot generation to minimize missed notifications.
Strictly atomic snapshots may not be achievable on every platform, so the API should document its consistency guarantees and provide a way to resynchronize when necessary.
The API design above is intended as a proposal for discussion. The final implementation may follow FileKit's existing API conventions.
Expected Features
Flow.Platform Considerations
Different platforms provide different file system monitoring mechanisms and capabilities.
java.nio.file.WatchServiceinotifyReadDirectoryChangesWNot all platforms expose identical file system capabilities.
For example:
The implementation should expose a consistent API where possible while documenting unsupported capabilities and platform-specific limitations.
Possible Module Structure
To keep
filekit-corelightweight, this functionality could be introduced as an independent module:The
filekit-watchermodule would depend onfilekit-coreand provide platform-specific implementations.Benefits
Adding file system watching would extend FileKit beyond basic file operations and provide a more complete cross-platform file management experience.
Potential use cases include:
I believe this would be a valuable addition to FileKit and an important step toward providing a more complete cross-platform file system abstraction for Kotlin Multiplatform applications.
All reactions