file-engine

Async, cross-platform file operations engine for desktop apps and developer tools: copy, move, sync, watch, and compress files, with progress reporting and cooperative cancellation built in from the start. Small-file operations are automatically batched to avoid overloading the OS with per-file syscalls, without any configuration required.

Not tied to any specific application — a standalone crate consumable by any Rust project (desktop apps, CLIs, Tauri backends, etc.), built on tokio.

Quickstart

use file_engine::FileEngine;

#[tokio::main]
async fn main() -> file_engine::Result<()> {
    let engine = FileEngine::new();

    let mut handle = engine.copy("src.txt", "dst.txt").overwrite(true).start()?;

    while let Some(progress) = tokio_stream::StreamExt::next(handle.progress()).await {
        println!("{:?}", progress);
    }

    let outcome = handle.await?;
    println!("succeeded: {}, failed: {}", outcome.succeeded.len(), outcome.failed.len());
    Ok(())
}

Every operation follows the same builder pattern: a chainable builder configures the operation, .start() spawns it as a background task and returns a handle immediately, and the handle exposes a Progress stream plus cooperative cancellation via .cancel().

Operations at a glance

¹ requires the checksum feature. ² Unix only, requires the permissions feature. Full option reference, including which defaults differ and why: docs/guide/operations.md.

Feed that stream to an EtaEstimator for a predicted time remaining. It models batched small files (cost per file), streamed large files (cost per byte), and the directory pre-pass (cost per directory) separately, because a single bytes-per-second figure describes none of them well. See docs/guide/progress-and-cancellation.md.

FileEngine::analyze() inspects a path without touching it — file/ directory counts, total size, largest files, and extension/age breakdowns, narrowed with filters (extension, glob excludes, size range, modified-time range, depth). With the checksum feature, it can also group files by content hash to surface duplicates:

let report = engine.analyze("some/dir").detect_duplicates(true).start()?.await?;
println!("{} files, {} bytes wasted on duplicates", report.file_count, report.duplicate_bytes_wasted);

Copying across filesystems (e.g. onto a FAT32/exFAT drive) is checked for several failure modes up front — case-insensitive-destination collisions, Windows-reserved filenames, destination file-size limits, and a known exFAT-on-macOS write-integrity risk — rather than failing unpredictably partway through or silently losing data. See docs/guide/filesystem-safety.md.

FileEngine::move_many(sources, dest_dir) moves several independent sources into one destination directory as a single batched operation — one shared ErrorStrategy, concurrency pool, and progress stream across all of them, rather than one .move_path() call per source. Each source keeps its own basename under dest_dir.

With the checksum feature, .skip_if_identical(true) on .copy(), .move_path(), and .move_many() compares content instead of failing outright when the destination already exists: an identical destination is left in place (for a move, the now-redundant source is still removed), while a genuinely different one still fails with Error::DestExists for the caller to decide what to do.

engine.move_path("src.txt", "dst.txt").skip_if_identical(true).start()?.await?;

FileEngine::remove() deletes files matching criteria (extension, size, modified-time, exclude globs) instead of a whole path outright. It defaults to a dry run (.dry_run(false) to actually remove) and to trashing matches rather than unlinking them (.hard_delete(true) to unlink permanently), and refuses to run with no criteria set at all unless .allow_unfiltered_delete(true):

let outcome = engine.remove("some/dir").extensions(["tmp", "log"]).max_size(1024 * 1024).dry_run(false).start()?.await?;
println!("removed {} files", outcome.succeeded.len());

Features

Only pay for what you use — the public surface grows and shrinks via Cargo feature flags.

Documentation

• docs/guide/ — using the crate: quickstart per operation, the full builder option reference, progress/cancellation, error handling, and the filesystem-safety behavior above in detail.
• docs/contributing/ — working on the crate: architecture, conventions for adding a feature, and this project's testing discipline.

License

Licensed under the MIT license.