fast-fs 0.2.1

// <FILE>crates/fast-fs/src/reader/fnc_read_dir_stream.rs</FILE> - <DESC>Streaming directory traversal with backpressure support</DESC>
// <VERS>VERSION: 1.1.1</VERS>
// <WCTX>Fixing doc tests to use no_run instead of ignore</WCTX>
// <CLOG>Changed doc example from ignore to no_run with proper async wrapper</CLOG>

use crate::filter::cls_gitignore_matcher::GitignoreMatcher;
use crate::{FileEntry, Result, TraversalOptions};
use futures::stream::{self, Stream};
use std::path::Path;

use super::cls_stream_state::StreamState;

/// Stream directory entries with filtering and backpressure support
///
/// This function returns a stream that yields entries as they are discovered,
/// allowing for memory-efficient traversal of large directory trees. The stream
/// respects backpressure, so slow consumers won't cause unbounded memory growth.
///
/// # Arguments
///
/// * `path` - Root directory to traverse
/// * `options` - Traversal options (filtering, depth, etc.)
///
/// # Returns
///
/// A stream of `Result<FileEntry, Error>` that yields entries as they are discovered
///
/// # Examples
///
/// ```no_run
/// # async fn example() {
/// use fast_fs::{read_dir_stream, TraversalOptions};
/// use futures::StreamExt;
///
/// let options = TraversalOptions::default()
///     .with_gitignore(true)
///     .with_max_depth(5);
///
/// let mut stream = Box::pin(read_dir_stream(".", options));
/// while let Some(entry) = stream.next().await {
///     match entry {
///         Ok(file) => println!("{}", file.path.display()),
///         Err(e) => eprintln!("Error: {}", e),
///     }
/// }
/// # }
/// ```
pub fn read_dir_stream(
    path: impl AsRef<Path>,
    options: TraversalOptions,
) -> impl Stream<Item = Result<FileEntry>> {
    let path = path.as_ref().to_path_buf();
    let max_depth = options.max_depth.unwrap_or(usize::MAX);

    // Build gitignore matcher if enabled
    let gitignore = if options.gitignore {
        GitignoreMatcher::from_path(&path).ok()
    } else {
        None
    };

    stream::unfold(
        StreamState::new(path, max_depth, options, gitignore),
        |mut state| async move { state.next_entry().await },
    )
}

// <FILE>crates/fast-fs/src/reader/fnc_read_dir_stream.rs</FILE>
// <VERS>END OF VERSION: 1.1.0</VERS>