file_database 1.1.4

//! # Database
//! Local file database utilities.
//!
//! This crate gives you a simple way to manage files and folders inside one database directory.
//! The main type is **`DatabaseManager`**, and items are addressed with **`ItemId`**.
//! `DatabaseManager::create_database` creates the directory if missing, or opens an existing
//! directory and indexes its current contents.
//!
//! ## How `ItemId` works
//! - **`ItemId`** has a `name` and an `index`.
//! - `name` is the display/key name (for example `"test_file.txt"`).
//! - `index` is the stable slot for that `name` bucket in the internal `StableVec`.
//! - `ItemId::id("name")` always means index `0`.
//! - `ItemId::database_id()` is the root ID for the database itself.
//!
//! This means duplicate names are allowed, and each item is still uniquely addressable by
//! the pair `(name, index)`.
//!
//! # Example: Build `ItemId` values
//! ```
//! use file_database::ItemId;
//!
//! let first = ItemId::id("test_file.txt");
//! let second = ItemId::with_index("test_file.txt", 1);
//! let root = ItemId::database_id();
//!
//! assert_eq!(first.get_name(), "test_file.txt");
//! assert_eq!(first.get_index(), 0);
//! assert_eq!(second.get_index(), 1);
//! assert_eq!(root.get_name(), "");
//! assert_eq!(root.get_index(), 0);
//! ```
//!
//! ## How to use **`GenPath`**
//! **`GenPath`** is used to generate paths from a ruleset. This is primarily used as the root directory for **`DatabaseManager`**.
//! Pick the method based on where your app starts:
//! - `GenPath::from_working_dir(steps)` when your process starts in a useful working directory.
//! - `GenPath::from_exe(steps)` when paths should be anchored to the executable location.
//! - `GenPath::from_closest_match("name")` when you want to find the nearest matching folder
//!   while walking upward from the executable.
//!
//! # Example: Build base paths with `GenPath`
//! ```no_run
//! use file_database::{DatabaseError, GenPath};
//!
//! fn main() -> Result<(), DatabaseError> {
//!     let from_cwd = GenPath::from_working_dir(0)?;
//!     let from_exe = GenPath::from_exe(0)?;
//!     assert!(from_cwd.is_absolute() || from_cwd.is_relative());
//!     assert!(from_exe.is_absolute() || from_exe.is_relative());
//!     Ok(())
//! }
//! ```
//!
//! # Example: Find a folder by name with `GenPath`
//! ```no_run
//! use file_database::{DatabaseError, GenPath};
//!
//! fn main() -> Result<(), DatabaseError> {
//!     let project_root = GenPath::from_closest_match("src")?;
//!     assert!(project_root.ends_with("src"));
//!     Ok(())
//! }
//! ```
//!
//! # Example: Create and overwrite a file
//! ```no_run
//! use file_database::{DatabaseError, DatabaseManager, ItemId};
//!
//! fn main() -> Result<(), DatabaseError> {
//!     let mut manager = DatabaseManager::create_database(".", "database")?;
//!     manager.write_new(ItemId::id("example.txt"), ItemId::database_id())?;
//!     manager.overwrite_existing(ItemId::id("example.txt"), b"hello")?;
//!     Ok(())
//! }
//! ```
//!
//! # Example: Open an existing database directory
//! ```no_run
//! use std::fs::{create_dir_all, File};
//! use file_database::{DatabaseError, DatabaseManager};
//!
//! fn main() -> Result<(), DatabaseError> {
//!     create_dir_all("./db_parent/database/folder")?;
//!     File::create("./db_parent/database/config.json")?;
//!
//!     let manager = DatabaseManager::create_database("./db_parent", "database")?;
//!     let ids = manager.get_ids_by_name("config.json");
//!     assert_eq!(ids.len(), 1);
//!     Ok(())
//! }
//! ```
//!
//! # Example: Duplicate names with stable indexes
//! ```no_run
//! use file_database::{DatabaseError, DatabaseManager, ItemId};
//!
//! fn main() -> Result<(), DatabaseError> {
//!     let mut manager = DatabaseManager::create_database(".", "database")?;
//!
//!     manager.write_new(ItemId::id("folder_a"), ItemId::database_id())?;
//!     manager.write_new(ItemId::id("folder_b"), ItemId::database_id())?;
//!     manager.write_new(ItemId::with_index("test.txt", 1), ItemId::id("folder_a"))?;
//!     manager.write_new(ItemId::with_index("test.txt", 2), ItemId::id("folder_b"))?;
//!
//!     let first = ItemId::with_index("test.txt", 1);
//!     let second = ItemId::with_index("test.txt", 2);
//!
//!     let _first_path = manager.locate_absolute(first)?;
//!     let _second_path = manager.locate_absolute(second)?;
//!     Ok(())
//! }
//! ```
//!
//! # Example: Get all IDs for one shared name
//! ```no_run
//! use file_database::{DatabaseError, DatabaseManager, ItemId};
//!
//! fn main() -> Result<(), DatabaseError> {
//!     let mut manager = DatabaseManager::create_database(".", "database")?;
//!     manager.write_new(ItemId::with_index("a.txt", 1), ItemId::database_id())?;
//!     manager.write_new(ItemId::id("folder"), ItemId::database_id())?;
//!     manager.write_new(ItemId::with_index("a.txt", 2), ItemId::id("folder"))?;
//!
//!     let ids = manager.get_ids_by_name("a.txt");
//!     assert_eq!(ids.len(), 2);
//!     assert!(ids.iter().any(|id| id.get_index() == 1));
//!     assert!(ids.iter().any(|id| id.get_index() == 2));
//!     Ok(())
//! }
//! ```

use std::{
    collections::{HashMap, HashSet},
    env::{current_dir, current_exe},
    ffi::OsStr,
    fs::{self, File, create_dir, remove_dir, remove_dir_all, remove_file},
    hash::Hash,
    io::{self, Write},
    path::{Path, PathBuf},
    time::{SystemTime, UNIX_EPOCH},
};
use thiserror::Error;

// Constants
const ZERO: u64 = 0;
const THOUSAND: u64 = 1_000;
const MILLION: u64 = 1_000_000;
const BILLION: u64 = 1_000_000_000;
const TRILLION: u64 = 1_000_000_000_000;
const QUADRILLION: u64 = 1_000_000_000_000_000;

// -------- Enums --------
#[derive(Debug, Error)]
/// Errors returned by this library.
pub enum DatabaseError {
    /// Returned when requested path-step trimming exceeds the available path depth.
    #[error("Steps '{0}' greater than path length '{1}'")]
    PathStepOverflow(i32, i32),
    /// Returned when no matching directory name can be found while walking upward.
    #[error("Directory '{0}' not found along path to executable")]
    NoClosestDir(String),
    /// Returned when an `ItemId` name has no tracked entries in the index.
    #[error("ID '{0}' doesn't point to a known path")]
    NoMatchingID(String),
    /// Returned when creating or renaming to an ID that already exists at the target path.
    #[error("ID '{0}' already exists")]
    IdAlreadyExists(String),
    /// Returned when source and destination resolve to the same filesystem path.
    #[error("Source and destination are identical: '{0}'")]
    IdenticalSourceDestination(PathBuf),
    /// Returned when an export destination points inside the managed database root.
    #[error("Export destination is inside the database: '{0}'")]
    ExportDestinationInsideDatabase(PathBuf),
    /// Returned when an import source path points inside the managed database root.
    #[error("Import source is inside the database: '{0}'")]
    ImportSourceInsideDatabase(PathBuf),
    /// Returned when an operation does not allow `ItemId::database_id()` as input.
    #[error("Root database ID cannot be used for this operation")]
    RootIdUnsupported,
    /// Returned when a path was expected to be a directory but is not.
    #[error("Path '{0}' doesn't point to a directory")]
    NotADirectory(PathBuf),
    /// Returned when a path was expected to be a file but is not.
    #[error("Path '{0}' doesn't point to a file")]
    NotAFile(PathBuf),
    /// Returned when converting an OS string/path segment into UTF-8 text fails.
    #[error("Couldn't convert OsString to String")]
    OsStringConversion,
    /// Returned when an item has no parent inside the tracked database tree.
    #[error("ID '{0}' doesn't have a parent")]
    NoParent(String),
    /// Returned when an underlying filesystem I/O operation fails.
    #[error(transparent)]
    Io(#[from] std::io::Error),
    /// Returned when JSON serialization or deserialization fails.
    #[error(transparent)]
    SerdeJson(#[from] serde_json::Error),
    /// Returned when bincode serialization or deserialization fails.
    #[error(transparent)]
    Bincode(#[from] bincode::Error),
    /// Returned when converting an absolute path into a database-relative path fails.
    #[error(transparent)]
    PathBufConversion(#[from] std::path::StripPrefixError),
}

#[derive(Debug, PartialEq, Clone, Default)]
/// Controls whether directory deletion is forced.
pub enum ForceDeletion {
    #[default]
    Force,
    NoForce,
}

impl From<ForceDeletion> for bool {
    /// Converts **`ForceDeletion`** into its boolean form.
    fn from(val: ForceDeletion) -> Self {
        match val {
            ForceDeletion::Force => true,
            ForceDeletion::NoForce => false,
        }
    }
}

impl From<bool> for ForceDeletion {
    /// Converts a boolean into **`ForceDeletion`**.
    fn from(value: bool) -> Self {
        match value {
            true => ForceDeletion::Force,
            false => ForceDeletion::NoForce,
        }
    }
}

#[derive(Debug, PartialEq, Clone, Default)]
/// Controls whether list results are sorted.
pub enum ShouldSort {
    #[default]
    Sort,
    NoSort,
}

impl From<ShouldSort> for bool {
    /// Converts **`ShouldSort`** into its boolean form.
    fn from(val: ShouldSort) -> Self {
        match val {
            ShouldSort::Sort => true,
            ShouldSort::NoSort => false,
        }
    }
}

impl From<bool> for ShouldSort {
    /// Converts a boolean into **`ShouldSort`**.
    fn from(value: bool) -> Self {
        match value {
            true => ShouldSort::Sort,
            false => ShouldSort::NoSort,
        }
    }
}

#[derive(Debug, PartialEq, Clone, Default)]
/// Controls whether export copies or moves the source.
pub enum ExportMode {
    #[default]
    Copy,
    Move,
}

#[derive(Debug, PartialEq, Clone, Default)]
/// Controls how `scan_for_changes` handles newly found files.
pub enum ScanPolicy {
    DetectOnly,
    RemoveNew,
    #[default]
    AddNew,
}

#[derive(Debug, Default, PartialEq, PartialOrd, Eq, Ord, Clone, Copy)]
/// Units used by **`FileSize`**.
pub enum FileSizeUnit {
    #[default]
    Byte,
    Kilobyte,
    Megabyte,
    Gigabyte,
    Terabyte,
    Petabyte,
}

impl FileSizeUnit {
    /// Internal numeric rank used for unit conversion math.
    fn variant_integer_id(&self) -> u8 {
        match self {
            Self::Byte => 0,
            Self::Kilobyte => 1,
            Self::Megabyte => 2,
            Self::Gigabyte => 3,
            Self::Terabyte => 4,
            Self::Petabyte => 5,
        }
    }
}

// -------- Structs --------
#[derive(PartialEq, Debug, Clone, Default)]
/// Helper for building paths from the current process location.
pub struct GenPath;

impl GenPath {
    /// Returns the working directory, with `steps` parts removed from the end.
    ///
    /// # Parameters
    /// - `steps`: number of path parts at the end to remove.
    ///
    /// # Errors
    /// Returns an error if:
    /// - the current directory cannot be read,
    /// - `steps` is greater than or equal to the number of removable segments.
    ///
    /// # Examples
    /// ```no_run
    /// use file_database::{DatabaseError, GenPath};
    ///
    /// fn main() -> Result<(), DatabaseError> {
    ///     let _cwd = GenPath::from_working_dir(0)?;
    ///     Ok(())
    /// }
    /// ```
    pub fn from_working_dir(steps: i32) -> Result<PathBuf, DatabaseError> {
        let working_dir = truncate(current_dir()?, steps)?;

        Ok(working_dir)
    }

    /// Returns the executable directory, with `steps` parts removed from the end.
    ///
    /// # Parameters
    /// - `steps`: number of path parts at the end to remove from the executable directory.
    ///
    /// # Errors
    /// Returns an error if:
    /// - the executable path cannot be read,
    /// - `steps` is too large for the path depth.
    ///
    /// # Examples
    /// ```no_run
    /// use file_database::{DatabaseError, GenPath};
    ///
    /// fn main() -> Result<(), DatabaseError> {
    ///     let _exe_dir = GenPath::from_exe(0)?;
    ///     Ok(())
    /// }
    /// ```
    pub fn from_exe(steps: i32) -> Result<PathBuf, DatabaseError> {
        let exe = truncate(current_exe()?, steps + 1)?;

        Ok(exe)
    }

    /// Looks for the nearest matching folder name while walking up from the executable.
    ///
    /// At each level, this checks:
    /// - the folder name itself,
    /// - child folders one level down.
    ///
    /// File entries are ignored.
    ///
    /// # Parameters
    /// - `name`: directory name to search for.
    ///
    /// # Errors
    /// Returns an error if:
    /// - no matching directory is found,
    /// - the provided name cannot be converted from `OsStr` to `String`.
    ///
    /// # Examples
    /// ```no_run
    /// use file_database::{DatabaseError, GenPath};
    ///
    /// fn main() -> Result<(), DatabaseError> {
    ///     let _path = GenPath::from_closest_match("src")?;
    ///     Ok(())
    /// }
    /// ```
    pub fn from_closest_match(name: impl AsRef<Path>) -> Result<PathBuf, DatabaseError> {
        let exe = current_exe()?;
        let target = name.as_ref();
        let target_name = match target.file_name() {
            Some(name) => name,
            None => return Err(DatabaseError::OsStringConversion)
        };

        for path in exe.ancestors() {
            if !path.is_dir() {
                continue;
            }

            if path
                .file_name()
                .is_some_and(|dir_name| dir_name == target_name)
            {
                return Ok(path.to_path_buf());
            }

            if let Ok(entries) = fs::read_dir(path) {
                for entry in entries {
                    let entry = match entry {
                        Ok(entry) => entry,
                        Err(_) => continue,
                    };

                    let child_path = entry.path();
                    if !child_path.is_dir() {
                        continue;
                    }

                    if entry.file_name() == target_name {
                        return Ok(child_path);
                    }
                }
            }
        }

        let name_as_string = match target.to_owned().into_os_string().into_string() {
            Ok(string) => string,
            Err(_) => return Err(DatabaseError::OsStringConversion),
        };

        Err(DatabaseError::NoClosestDir(name_as_string))
    }
}

#[derive(Debug, PartialEq, Eq, Hash, Clone, PartialOrd, Ord)]
/// Identifier used to select a tracked item by `name` and `index`.
///
/// Use this when:
/// - you know the shared `name` and want the first match (`ItemId::id("name")`),
/// - or when you need a specific duplicate (`ItemId::with_index("name", i)`).
///
/// `ItemId::database_id()` is special and points to the database root itself.
///
/// # Examples
/// ```
/// use file_database::ItemId;
///
/// let first = ItemId::id("report.txt");
/// let second = ItemId::with_index("report.txt", 1);
/// let root = ItemId::database_id();
///
/// assert_eq!(first.get_name(), "report.txt");
/// assert_eq!(first.get_index(), 0);
/// assert_eq!(second.get_index(), 1);
/// assert_eq!(root.get_name(), "");
/// ```
pub struct ItemId {
    name: String,
    index: usize,
}

impl<T> From<T> for ItemId
where
    T: Into<String>,
{
    /// Creates an **`ItemId`** from a name, defaulting `index` to `0`.
    fn from(value: T) -> Self {
        Self {
            name: value.into(),
            index: 0,
        }
    }
}

impl From<&ItemId> for ItemId {
    /// Clones an **`ItemId`** from a reference.
    fn from(value: &ItemId) -> Self {
        value.clone()
    }
}

impl ItemId {
    /// Returns the `ItemId::database_id()` for the database itself.
    ///
    /// # Examples
    /// ```
    /// use file_database::ItemId;
    ///
    /// let root = ItemId::database_id();
    /// assert_eq!(root.get_name(), "");
    /// assert_eq!(root.get_index(), 0);
    /// ```
    pub fn database_id() -> Self {
        Self {
            name: String::new(),
            index: 0,
        }
    }

    /// Creates an **`ItemId`** with `index` `0`.
    ///
    /// # Parameters
    /// - `id`: shared `name` key stored in the manager.
    ///
    /// # Examples
    /// ```
    /// use file_database::ItemId;
    ///
    /// let id = ItemId::id("file.txt");
    /// assert_eq!(id.get_name(), "file.txt");
    /// assert_eq!(id.get_index(), 0);
    /// ```
    pub fn id(id: impl Into<String>) -> Self {
        Self {
            name: id.into(),
            index: 0,
        }
    }

    /// Creates an **`ItemId`** with an explicit `index`.
    ///
    /// # Parameters
    /// - `id`: shared `name` key.
    /// - `index`: caller-defined unique number used as part of identity.
    ///
    /// # Examples
    /// ```
    /// use file_database::ItemId;
    ///
    /// let id = ItemId::with_index("file.txt", 2);
    /// assert_eq!(id.get_name(), "file.txt");
    /// assert_eq!(id.get_index(), 2);
    /// ```
    pub fn with_index(id: impl Into<String>, index: usize) -> Self {
        Self::from(id, index)
    }

    /// Creates an **`ItemId`** from `name` and `index`.
    ///
    /// # Parameters
    /// - `id`: shared `name` key.
    /// - `index`: caller-defined unique number used as part of identity.
    pub fn from(id: impl Into<String>, index: usize) -> Self {
        Self {
            name: id.into(),
            index,
        }
    }

    /// Returns the shared `name` of this **`ItemId`**.
    pub fn get_name(&self) -> &str {
        &self.name
    }

    /// Returns the zero-based `index` for this shared `name`.
    pub fn get_index(&self) -> usize {
        self.index
    }

    /// Returns the shared `name` as `&str`.
    pub fn as_str(&self) -> &str {
        self.get_name()
    }

    /// Returns an owned `String` containing this **`ItemId`**'s shared `name`.
    pub fn as_string(&self) -> String {
        self.name.clone()
    }
}

#[derive(Debug, Default, PartialEq, PartialOrd, Clone, Copy)]
/// File size value paired with a unit.
pub struct FileSize {
    size: u64,
    unit: FileSizeUnit,
}

impl FileSize {
    /// Returns the stored size value in the current unit.
    pub fn get_size(&self) -> u64 {
        self.size
    }

    /// Returns the stored unit.
    pub fn get_unit(&self) -> FileSizeUnit {
        self.unit
    }

    /// Returns a string representing an amount of data, pluralized when needed.
    ///
    /// # Examples
    /// ```
    /// use file_database::FileSize;
    ///
    /// let size = FileSize::default();
    /// assert_eq!(size.unit_as_string(), "Bytes");
    /// ```
    pub fn unit_as_string(&self) -> String {
        let name = match self.unit {
            FileSizeUnit::Byte => "Byte",
            FileSizeUnit::Kilobyte => "Kilobyte",
            FileSizeUnit::Megabyte => "Megabyte",
            FileSizeUnit::Gigabyte => "Gigabyte",
            FileSizeUnit::Terabyte => "Terabyte",
            FileSizeUnit::Petabyte => "Petabyte",
        };

        let mut name_string = String::from(name);

        // Push an s to the end of the string if not 1
        match self.size {
            1 => (),
            _ => name_string.push('s'),
        }

        name_string
    }

    /// Returns a copy of this size converted to another unit.
    ///
    /// Conversion uses powers of 1000 between adjacent units.
    ///
    /// # Parameters
    /// - `unit`: destination unit.
    ///
    /// # Examples
    /// ```
    /// use file_database::{FileSize, FileSizeUnit};
    ///
    /// let bytes = FileSize::default().as_unit(FileSizeUnit::Byte);
    /// assert_eq!(bytes.get_unit(), FileSizeUnit::Byte);
    /// ```
    pub fn as_unit(&self, unit: FileSizeUnit) -> Self {
        let difference = self.unit.variant_integer_id() as i8 - unit.variant_integer_id() as i8;

        let mut size = self.size;

        if difference > 0 {
            let factor = THOUSAND.pow(difference as u32);
            size = size.saturating_mul(factor);
        } else if difference < 0 {
            let factor = THOUSAND.pow((-difference) as u32);
            size /= factor;
        }

        Self { size, unit }
    }

    /// Builds **`FileSize`** from raw bytes using automatic unit selection.
    fn from(bytes: u64) -> Self {
        let (size, unit) = match bytes {
            ZERO..THOUSAND => (bytes, FileSizeUnit::Byte),
            THOUSAND..MILLION => (bytes / THOUSAND, FileSizeUnit::Kilobyte),
            MILLION..BILLION => (bytes / MILLION, FileSizeUnit::Megabyte),
            BILLION..TRILLION => (bytes / BILLION, FileSizeUnit::Gigabyte),
            TRILLION..QUADRILLION => (bytes / TRILLION, FileSizeUnit::Terabyte),
            _ => (bytes / QUADRILLION, FileSizeUnit::Petabyte),
        };

        Self { size, unit }
    }
}

#[derive(Debug, Default, PartialEq, PartialOrd, Clone)]
/// Metadata returned by `get_file_information`.
pub struct FileInformation {
    name: Option<String>,
    extension: Option<String>,
    size: FileSize,
    unix_created: Option<u64>,
    time_since_created: Option<u64>,
    unix_last_opened: Option<u64>,
    time_since_last_opened: Option<u64>,
    unix_last_modified: Option<u64>,
    time_since_last_modified: Option<u64>,
}

impl FileInformation {
    /// Returns file `name` without extension, or directory `name` for directories.
    pub fn get_name(&self) -> Option<&str> {
        self.name.as_deref()
    }

    /// Returns file extension for files, otherwise `None`.
    pub fn get_extension(&self) -> Option<&str> {
        self.extension.as_deref()
    }

    /// Returns normalized file size data.
    pub fn get_size(&self) -> &FileSize {
        &self.size
    }

    /// Returns created-at Unix timestamp (seconds), when available on this platform.
    pub fn get_unix_created(&self) -> Option<&u64> {
        self.unix_created.as_ref()
    }

    /// Returns age since creation in seconds, when available.
    pub fn get_time_since_created(&self) -> Option<&u64> {
        self.time_since_created.as_ref()
    }

    /// Returns last-accessed Unix timestamp (seconds), when available.
    pub fn get_unix_last_opened(&self) -> Option<&u64> {
        self.unix_last_opened.as_ref()
    }

    /// Returns age since last access in seconds, when available.
    pub fn get_time_since_last_opened(&self) -> Option<&u64> {
        self.time_since_last_opened.as_ref()
    }

    /// Returns last-modified Unix timestamp (seconds), when available.
    pub fn get_unix_last_modified(&self) -> Option<&u64> {
        self.unix_last_modified.as_ref()
    }

    /// Returns age since last modification in seconds, when available.
    pub fn get_time_since_last_modified(&self) -> Option<&u64> {
        self.time_since_last_modified.as_ref()
    }
}

#[derive(Debug, PartialEq, Clone)]
/// A file or folder change found by `scan_for_changes`.
pub enum ExternalChange {
    Added { id: ItemId, path: PathBuf },
    Removed { id: ItemId, path: PathBuf },
}

#[derive(Debug, PartialEq, Clone)]
/// Summary returned by `scan_for_changes`.
pub struct ScanReport {
    scanned_from: ItemId,
    recursive: bool,
    added: Vec<ExternalChange>,
    removed: Vec<ExternalChange>,
    unchanged_count: usize,
    total_changed_count: usize,
}

impl ScanReport {
    /// Returns the **`ItemId`** used as the scan root.
    pub fn get_scan_from(&self) -> &ItemId {
        &self.scanned_from
    }

    /// Returns all newly discovered items in the scanned scope.
    pub fn get_added(&self) -> &Vec<ExternalChange> {
        &self.added
    }

    /// Returns tracked **`ItemId`** values that were missing on disk.
    pub fn get_removed(&self) -> &Vec<ExternalChange> {
        &self.removed
    }

    /// Returns how many tracked **`ItemId`** values stayed the same in this scan area.
    pub fn get_unchanged_count(&self) -> usize {
        self.unchanged_count
    }

    /// Returns total number of changed items (`added + removed`).
    pub fn get_total_changed_count(&self) -> usize {
        self.total_changed_count
    }
}

#[derive(Debug, PartialEq, Default)]
struct StableVec<T> {
    list: Vec<Option<T>>,
    free: Vec<usize>,
}

impl<T> StableVec<T> {
    fn push(&mut self, data: T) -> usize {
        if let Some(index) = self.free.pop() {
            self.list[index] = Some(data);
            index
        } else {
            self.list.push(Some(data));
            self.list.len() - 1
        }
    }

    fn remove(&mut self, index: usize) -> bool {
        if index >= self.list.len() || self.list[index].is_none() {
            return false;
        }

        self.list[index] = None;
        self.free.push(index);
        true
    }

    fn get(&self, index: usize) -> Option<&T> {
        self.list.get(index).and_then(|value| value.as_ref())
    }

    fn insert_at(&mut self, index: usize, data: T) -> bool {
        if index < self.list.len() {
            if self.list[index].is_some() {
                return false;
            }
            self.list[index] = Some(data);
            if let Some(free_index) = self.free.iter().position(|slot| *slot == index) {
                self.free.swap_remove(free_index);
            }
            return true;
        }

        while self.list.len() < index {
            let free_slot = self.list.len();
            self.list.push(None);
            self.free.push(free_slot);
        }

        self.list.push(Some(data));
        true
    }

    fn iter(&self) -> impl Iterator<Item = (usize, &T)> {
        self.list
            .iter()
            .enumerate()
            .filter_map(|(index, value)| value.as_ref().map(|value| (index, value)))
    }

    fn is_empty(&self) -> bool {
        self.list.iter().all(Option::is_none)
    }
}

#[derive(Debug, PartialEq)]
/// Main type that manages a database directory and its index.
pub struct DatabaseManager {
    path: PathBuf,
    items: HashMap<String, StableVec<PathBuf>>,
}

impl DatabaseManager {
    /// Creates or opens a database directory and returns a manager for it.
    ///
    /// # Parameters
    /// - `path`: parent directory where the database folder should exist.
    /// - `name`: database directory name appended to `path`.
    ///
    /// # Errors
    /// Returns an error if:
    /// - the target path exists but is not a directory,
    /// - parent directories are missing when creating a new database directory,
    /// - the process cannot create/read directories at the destination.
    ///
    /// # Examples
    /// ```no_run
    /// use file_database::{DatabaseError, DatabaseManager};
    ///
    /// fn main() -> Result<(), DatabaseError> {
    ///     let _manager = DatabaseManager::create_database(".", "database")?;
    ///     Ok(())
    /// }
    /// ```
    pub fn create_database(path: impl AsRef<Path>, name: impl AsRef<Path>) -> Result<Self, DatabaseError> {
        let mut path: PathBuf = path.as_ref().to_path_buf();

        path.push(name);

        if !path.exists() {
            create_dir(&path)?;
        } else if !path.is_dir() {
            return Err(DatabaseError::NotADirectory(path));
        }

        let mut manager = Self {
            path,
            items: HashMap::new(),
        };

        let discovered = manager.collect_paths_in_scope(&manager.path, true)?;
        for relative_path in discovered {
            let name = os_str_to_string(relative_path.file_name())?;
            manager.insert_generated_path(name, relative_path);
        }

        Ok(manager)
    }

    /// Creates a new file or directory under `parent`.
    ///
    /// Name interpretation is extension-based:
    /// - if `id.name` has an extension, a file is created,
    /// - otherwise, a directory is created.
    ///
    /// # Parameters
    /// - `id`: name key for the new item. Root **`ItemId`** is not allowed.
    /// - `parent`: destination parent item. Use `ItemId::database_id()` for database root.
    ///
    /// # Errors
    /// Returns an error if:
    /// - `id` is the `ItemId::database_id()`,
    /// - `parent` cannot be found,
    /// - another item already exists at the target relative path,
    /// - filesystem create operations fail.
    ///
    /// # Examples
    /// ```no_run
    /// use file_database::{DatabaseError, DatabaseManager, ItemId};
    ///
    /// fn main() -> Result<(), DatabaseError> {
    ///     let mut manager = DatabaseManager::create_database(".", "database")?;
    ///     manager.write_new(ItemId::id("notes.txt"), ItemId::database_id())?;
    ///     Ok(())
    /// }
    /// ```
    pub fn write_new(
        &mut self,
        id: impl Into<ItemId>,
        parent: impl Into<ItemId>,
    ) -> Result<(), DatabaseError> {
        let id = id.into();
        let parent = parent.into();

        if id.get_name().is_empty() {
            return Err(DatabaseError::RootIdUnsupported);
        }

        let absolute_parent_path = self.locate_absolute(&parent)?;
        let relative_path = if parent.get_name().is_empty() {
            PathBuf::from(id.get_name())
        } else {
            let mut path = self.locate_relative(parent)?.to_path_buf();
            path.push(id.get_name());
            path
        };
        let absolute_path = absolute_parent_path.join(id.get_name());

        if self.path_exists_in_index(&relative_path) {
            return Err(DatabaseError::IdAlreadyExists(id.as_string()));
        }

        if relative_path.extension().is_none() {
            create_dir(&absolute_path)?;
        } else {
            File::create_new(&absolute_path)?;
        }

        self.insert_path_for_id(&id, relative_path)?;
        Ok(())
    }

    /// Overwrites an existing file with raw bytes in a safe way.
    ///
    /// It writes to a temp file first, then replaces the target file.
    ///
    /// # Parameters
    /// - `id`: target file **`ItemId`**.
    /// - `data`: raw bytes to write.
    ///
    /// # Errors
    /// Returns an error if:
    /// - `id` cannot be found,
    /// - `id` points to a directory,
    /// - writing, syncing, or renaming fails.
    ///
    /// # Examples
    /// ```no_run
    /// use file_database::{DatabaseError, DatabaseManager, ItemId};
    ///
    /// fn main() -> Result<(), DatabaseError> {
    ///     let mut manager = DatabaseManager::create_database(".", "database")?;
    ///     manager.write_new(ItemId::id("blob.bin"), ItemId::database_id())?;
    ///     manager.overwrite_existing(ItemId::id("blob.bin"), [1_u8, 2, 3, 4])?;
    ///     Ok(())
    /// }
    /// ```
    pub fn overwrite_existing<T>(&self, id: impl Into<ItemId>, data: T) -> Result<(), DatabaseError>
    where
        T: AsRef<[u8]>,
    {
        let id = id.into();
        let bytes = data.as_ref();

        let path = self.locate_absolute(id)?;

        self.overwrite_path_atomic_with(&path, |file| {
            file.write_all(bytes)?;
            Ok(bytes.len() as u64)
        })?;

        Ok(())
    }

    /// Converts `value` to JSON and overwrites the target file.
    ///
    /// # Parameters
    /// - `id`: target file **`ItemId`**.
    /// - `value`: serializable value.
    /// - `pretty`: if `true`, writes pretty-printed JSON; otherwise compact JSON.
    ///
    /// # Errors
    /// Returns an error if:
    /// - JSON serialization fails,
    /// - finding `id` or overwriting the file fails.
    ///
    /// # Examples
    /// ```no_run
    /// use file_database::{DatabaseError, DatabaseManager, ItemId};
    /// use serde::Serialize;
    ///
    /// #[derive(Serialize)]
    /// struct Config {
    ///     retries: u8,
    /// }
    ///
    /// fn main() -> Result<(), DatabaseError> {
    ///     let mut manager = DatabaseManager::create_database(".", "database")?;
    ///     manager.write_new(ItemId::id("config.json"), ItemId::database_id())?;
    ///     manager.overwrite_existing_json(ItemId::id("config.json"), &Config { retries: 3 }, false)?;
    ///     Ok(())
    /// }
    /// ```
    pub fn overwrite_existing_json<T: serde::Serialize>(
        &self,
        id: impl Into<ItemId>,
        value: &T,
        pretty: impl Into<bool>,
    ) -> Result<(), DatabaseError> {
        let pretty = pretty.into();
        let data = if pretty {
            serde_json::to_vec_pretty(value)?
        } else {
            serde_json::to_vec(value)?
        };
        self.overwrite_existing(id, data)
    }

    /// Converts `value` to bincode and overwrites the target file.
    ///
    /// # Parameters
    /// - `id`: target file **`ItemId`**.
    /// - `value`: serializable value.
    ///
    /// # Errors
    /// Returns an error if:
    /// - bincode serialization fails,
    /// - finding `id` or overwriting the file fails.
    ///
    /// # Examples
    /// ```no_run
    /// use file_database::{DatabaseError, DatabaseManager, ItemId};
    /// use serde::Serialize;
    ///
    /// #[derive(Serialize)]
    /// enum State {
    ///     Ready,
    /// }
    ///
    /// fn main() -> Result<(), DatabaseError> {
    ///     let mut manager = DatabaseManager::create_database(".", "database")?;
    ///     manager.write_new(ItemId::id("state.bin"), ItemId::database_id())?;
    ///     manager.overwrite_existing_binary(ItemId::id("state.bin"), &State::Ready)?;
    ///     Ok(())
    /// }
    /// ```
    pub fn overwrite_existing_binary<T: serde::Serialize>(
        &self,
        id: impl Into<ItemId>,
        value: &T,
    ) -> Result<(), DatabaseError> {
        let data = bincode::serialize(value)?;
        self.overwrite_existing(id, data)
    }

    /// Streams bytes from `reader` into the target file and returns bytes written.
    ///
    /// This uses chunked I/O and a safe replace step, so it works well for large payloads.
    ///
    /// # Parameters
    /// - `id`: target file **`ItemId`**.
    /// - `reader`: source stream consumed until EOF.
    ///
    /// # Errors
    /// Returns an error if:
    /// - `id` cannot be found,
    /// - target is not a file,
    /// - stream read/write/sync/rename fails.
    ///
    /// # Examples
    /// ```no_run
    /// use std::io::Cursor;
    /// use file_database::{DatabaseError, DatabaseManager, ItemId};
    ///
    /// fn main() -> Result<(), DatabaseError> {
    ///     let mut manager = DatabaseManager::create_database(".", "database")?;
    ///     manager.write_new(ItemId::id("stream.bin"), ItemId::database_id())?;
    ///     let mut source = Cursor::new(vec![9_u8; 1024]);
    ///     let _bytes = manager.overwrite_existing_from_reader(ItemId::id("stream.bin"), &mut source)?;
    ///     Ok(())
    /// }
    /// ```
    pub fn overwrite_existing_from_reader<R: io::Read>(
        &self,
        id: impl Into<ItemId>,
        reader: &mut R,
    ) -> Result<u64, DatabaseError> {
        let id = id.into();
        let path = self.locate_absolute(id)?;
        self.overwrite_path_atomic_with(&path, |file| Ok(io::copy(reader, file)?))
    }

    /// Reads a managed file and returns its raw bytes.
    ///
    /// # Parameters
    /// - `id`: target file **`ItemId`**.
    ///
    /// # Errors
    /// Returns an error if:
    /// - `id` cannot be found,
    /// - `id` points to a directory,
    /// - file reading fails.
    ///
    /// # Examples
    /// ```no_run
    /// use file_database::{DatabaseError, DatabaseManager, ItemId};
    ///
    /// fn main() -> Result<(), DatabaseError> {
    ///     let mut manager = DatabaseManager::create_database(".", "database")?;
    ///     manager.write_new(ItemId::id("data.bin"), ItemId::database_id())?;
    ///     manager.overwrite_existing(ItemId::id("data.bin"), [1_u8, 2, 3])?;
    ///     let _data = manager.read_existing(ItemId::id("data.bin"))?;
    ///     Ok(())
    /// }
    /// ```
    pub fn read_existing(&self, id: impl Into<ItemId>) -> Result<Vec<u8>, DatabaseError> {
        let id = id.into();
        let path = self.locate_absolute(id)?;

        if path.is_dir() {
            return Err(DatabaseError::NotAFile(path));
        }

        Ok(fs::read(path)?)
    }

    /// Reads a managed file and turns JSON into `T`.
    ///
    /// # Parameters
    /// - `id`: target file **`ItemId`**.
    ///
    /// # Errors
    /// Returns an error if:
    /// - finding `id` or reading the file fails,
    /// - JSON deserialization fails.
    ///
    /// # Examples
    /// ```no_run
    /// use file_database::{DatabaseError, DatabaseManager, ItemId};
    /// use serde::{Deserialize, Serialize};
    ///
    /// #[derive(Serialize, Deserialize)]
    /// struct Config {
    ///     retries: u8,
    /// }
    ///
    /// fn main() -> Result<(), DatabaseError> {
    ///     let mut manager = DatabaseManager::create_database(".", "database")?;
    ///     manager.write_new(ItemId::id("config.json"), ItemId::database_id())?;
    ///     manager.overwrite_existing_json(ItemId::id("config.json"), &Config { retries: 3 }, false)?;
    ///     let _loaded: Config = manager.read_existing_json(ItemId::id("config.json"))?;
    ///     Ok(())
    /// }
    /// ```
    pub fn read_existing_json<T: serde::de::DeserializeOwned>(
        &self,
        id: impl Into<ItemId>,
    ) -> Result<T, DatabaseError> {
        let bytes = self.read_existing(id)?;
        Ok(serde_json::from_slice(&bytes)?)
    }

    /// Reads a managed file and turns bincode into `T`.
    ///
    /// # Parameters
    /// - `id`: target file **`ItemId`**.
    ///
    /// # Errors
    /// Returns an error if:
    /// - finding `id` or reading the file fails,
    /// - bincode deserialization fails.
    ///
    /// # Examples
    /// ```no_run
    /// use file_database::{DatabaseError, DatabaseManager, ItemId};
    /// use serde::{Deserialize, Serialize};
    ///
    /// #[derive(Serialize, Deserialize)]
    /// enum State {
    ///     Ready,
    /// }
    ///
    /// fn main() -> Result<(), DatabaseError> {
    ///     let mut manager = DatabaseManager::create_database(".", "database")?;
    ///     manager.write_new(ItemId::id("state.bin"), ItemId::database_id())?;
    ///     manager.overwrite_existing_binary(ItemId::id("state.bin"), &State::Ready)?;
    ///     let _loaded: State = manager.read_existing_binary(ItemId::id("state.bin"))?;
    ///     Ok(())
    /// }
    /// ```
    pub fn read_existing_binary<T: serde::de::DeserializeOwned>(
        &self,
        id: impl Into<ItemId>,
    ) -> Result<T, DatabaseError> {
        let bytes = self.read_existing(id)?;
        Ok(bincode::deserialize(&bytes)?)
    }

    /// Returns every tracked item in the database.
    ///
    /// # Parameters
    /// - `sorted`: whether output should be sorted by **`ItemId`** ordering.
    ///
    /// # Examples
    /// ```no_run
    /// use file_database::{DatabaseError, DatabaseManager, ItemId};
    ///
    /// fn main() -> Result<(), DatabaseError> {
    ///     let mut manager = DatabaseManager::create_database(".", "database")?;
    ///     manager.write_new(ItemId::id("a.txt"), ItemId::database_id())?;
    ///     let _all = manager.get_all(true);
    ///     Ok(())
    /// }
    /// ```
    pub fn get_all(&self, sorted: impl Into<bool>) -> Vec<ItemId> {
        let sorted = sorted.into();

        let mut list: Vec<ItemId> = self
            .items
            .iter()
            .flat_map(|(name, paths)| {
                paths
                    .iter()
                    .map(|(index, _)| ItemId::with_index(name.clone(), index))
                    .collect::<Vec<ItemId>>()
            })
            .collect();

        if sorted {
            list.sort();
        }

        list
    }

    /// Returns all tracked items that are direct children of `parent`.
    ///
    /// If `parent` is the `ItemId::database_id()`, this returns all top-level items.
    ///
    /// # Parameters
    /// - `parent`: parent directory item to query.
    /// - `sorted`: whether output should be sorted by **`ItemId`**.
    ///
    /// # Errors
    /// Returns an error if:
    /// - `parent` cannot be found,
    /// - `parent` points to a file instead of a directory.
    ///
    /// # Examples
    /// ```no_run
    /// use file_database::{DatabaseError, DatabaseManager, ItemId};
    ///
    /// fn main() -> Result<(), DatabaseError> {
    ///     let mut manager = DatabaseManager::create_database(".", "database")?;
    ///     manager.write_new(ItemId::id("folder"), ItemId::database_id())?;
    ///     manager.write_new(ItemId::id("a.txt"), ItemId::id("folder"))?;
    ///     let _children = manager.get_by_parent(ItemId::id("folder"), true)?;
    ///     Ok(())
    /// }
    /// ```
    pub fn get_by_parent(
        &self,
        parent: impl Into<ItemId>,
        sorted: impl Into<bool>,
    ) -> Result<Vec<ItemId>, DatabaseError> {
        let parent = parent.into();
        let sorted = sorted.into();

        let absolute_parent = self.locate_absolute(&parent)?;

        if !absolute_parent.is_dir() {
            return Err(DatabaseError::NotADirectory(absolute_parent));
        }

        let mut list: Vec<ItemId> = Vec::new();
        let parent_path = if parent.get_name().is_empty() {
            None
        } else {
            Some(self.locate_relative(&parent)?.as_path())
        };

        for (name, paths) in &self.items {
            for (index, item_path) in paths.iter() {
                let is_match = match parent_path {
                    None => item_path
                        .parent()
                        .is_some_and(|path| path.as_os_str().is_empty()),
                    Some(parent_path) => item_path.parent() == Some(parent_path),
                };

                if is_match {
                    list.push(ItemId::with_index(name.clone(), index));
                }
            }
        }

        if sorted {
            list.sort();
        }

        Ok(list)
    }

    /// Returns the parent **`ItemId`** for an item.
    ///
    /// Top-level items return [`ItemId::database_id`].
    ///
    /// # Parameters
    /// - `id`: item whose parent should be looked up.
    ///
    /// # Errors
    /// Returns an error if:
    /// - `id` cannot be found,
    /// - parent path data cannot be converted to UTF-8 string.
    ///
    /// # Examples
    /// ```no_run
    /// use file_database::{DatabaseError, DatabaseManager, ItemId};
    ///
    /// fn main() -> Result<(), DatabaseError> {
    ///     let mut manager = DatabaseManager::create_database(".", "database")?;
    ///     manager.write_new(ItemId::id("folder"), ItemId::database_id())?;
    ///     manager.write_new(ItemId::id("a.txt"), ItemId::id("folder"))?;
    ///     let _parent = manager.get_parent(ItemId::id("a.txt"))?;
    ///     Ok(())
    /// }
    /// ```
    pub fn get_parent(&self, id: impl Into<ItemId>) -> Result<ItemId, DatabaseError> {
        let id = id.into();
        let path = self.locate_relative(&id)?;

        let parent = match path.parent() {
            Some(parent) => parent,
            None => return Ok(ItemId::database_id()),
        };

        if parent.as_os_str().is_empty() {
            return Ok(ItemId::database_id());
        }

        for (name, paths) in &self.items {
            for (index, item_path) in paths.iter() {
                if item_path.as_path() == parent {
                    return Ok(ItemId::with_index(name.clone(), index));
                }
            }
        }

        match parent.file_name() {
            Some(name) => Ok(ItemId::id(os_str_to_string(Some(name))?)),
            None => Err(DatabaseError::NoParent(id.as_string())),
        }
    }

    /// Renames the chosen item to `to` in the same parent directory.
    ///
    /// # Parameters
    /// - `id`: source **`ItemId`** to rename.
    /// - `to`: new file or directory name.
    ///
    /// # Errors
    /// Returns an error if:
    /// - `id` is the `ItemId::database_id()`,
    /// - `id` cannot be found,
    /// - destination `name` already exists at the same relative `path`,
    /// - underlying filesystem rename fails.
    ///
    /// # Examples
    /// ```no_run
    /// use file_database::{DatabaseError, DatabaseManager, ItemId};
    ///
    /// fn main() -> Result<(), DatabaseError> {
    ///     let mut manager = DatabaseManager::create_database(".", "database")?;
    ///     manager.write_new(ItemId::id("old.txt"), ItemId::database_id())?;
    ///     manager.rename(ItemId::id("old.txt"), "new.txt")?;
    ///     Ok(())
    /// }
    /// ```
    pub fn rename(
        &mut self,
        id: impl Into<ItemId>,
        to: impl AsRef<str>,
    ) -> Result<(), DatabaseError> {
        let id = id.into();
        let name = to.as_ref().to_owned();

        if id.get_name().is_empty() {
            return Err(DatabaseError::RootIdUnsupported);
        }

        let path = self.locate_absolute(&id)?;
        let mut relative_path = self.locate_relative(&id)?.to_path_buf();

        let renamed_path = path.with_file_name(&name);
        relative_path = match relative_path.pop() {
            true => {
                relative_path.push(&name);
                relative_path
            }
            false => PathBuf::from(&name),
        };

        let new_id = ItemId::with_index(name.clone(), id.get_index());

        if self
            .all_paths()
            .iter()
            .any(|(entry_id, entry_path)| entry_id != &id && *entry_path == &relative_path)
        {
            return Err(DatabaseError::IdAlreadyExists(new_id.as_string()));
        }

        fs::rename(&path, renamed_path)?;

        self.remove_id_from_index(&id)?;
        self.insert_path_for_id(&new_id, relative_path)?;

        Ok(())
    }

    /// Deletes a file, directory, or the whole database root.
    ///
    /// # Parameters
    /// - `id`: item to delete. Use `ItemId::database_id()` to target the database folder itself.
    /// - `force`: when deleting directories, controls recursive vs empty-only behavior.
    ///
    /// # Errors
    /// Returns an error if:
    /// - `id` cannot be found,
    /// - directory deletion does not match `force` rules,
    /// - filesystem delete operations fail.
    ///
    /// # Examples
    /// ```no_run
    /// use file_database::{DatabaseError, DatabaseManager, ForceDeletion, ItemId};
    ///
    /// fn main() -> Result<(), DatabaseError> {
    ///     let mut manager = DatabaseManager::create_database(".", "database")?;
    ///     manager.write_new(ItemId::id("tmp.txt"), ItemId::database_id())?;
    ///     manager.delete(ItemId::id("tmp.txt"), ForceDeletion::Force)?;
    ///     Ok(())
    /// }
    /// ```
    pub fn delete(
        &mut self,
        id: impl Into<ItemId>,
        force: impl Into<bool>,
    ) -> Result<(), DatabaseError> {
        let id = id.into();
        let force = force.into();

        if id.get_name().is_empty() {
            match self.delete_directory(&self.locate_absolute(id)?, force) {
                Ok(_) => {
                    self.path = PathBuf::new();
                    self.items.drain();
                    return Ok(());
                }
                Err(error) => return Err(error),
            }
        }

        let path = self.locate_absolute(&id)?;

        if path.is_dir() {
            self.delete_directory(&path, force)?;
        } else {
            remove_file(path)?;
        }

        self.remove_id_from_index(&id)?;

        Ok(())
    }

    /// Gets the absolute file path for an **`ItemId`**.
    ///
    /// For the `ItemId::database_id()`, this returns the database directory path.
    ///
    /// # Parameters
    /// - `id`: **`ItemId`** to look up.
    ///
    /// # Errors
    /// Returns an error if:
    /// - `id` does not exist.
    ///
    /// # Examples
    /// ```no_run
    /// use file_database::{DatabaseError, DatabaseManager, ItemId};
    ///
    /// fn main() -> Result<(), DatabaseError> {
    ///     let mut manager = DatabaseManager::create_database(".", "database")?;
    ///     manager.write_new(ItemId::id("a.txt"), ItemId::database_id())?;
    ///     let _path = manager.locate_absolute(ItemId::id("a.txt"))?;
    ///     Ok(())
    /// }
    /// ```
    pub fn locate_absolute(&self, id: impl Into<ItemId>) -> Result<PathBuf, DatabaseError> {
        let id = id.into();

        if id.get_name().is_empty() {
            return Ok(self.path.to_path_buf());
        }

        Ok(self.path.join(self.resolve_path_by_id(&id)?))
    }

    /// Gets the stored relative path reference for an **`ItemId`**.
    ///
    /// For the `ItemId::database_id()`, this currently returns a reference to the manager root path.
    ///
    /// # Parameters
    /// - `id`: **`ItemId`** to look up.
    ///
    /// # Errors
    /// Returns an error if:
    /// - `id` does not exist.
    ///
    /// # Examples
    /// ```no_run
    /// use file_database::{DatabaseError, DatabaseManager, ItemId};
    ///
    /// fn main() -> Result<(), DatabaseError> {
    ///     let mut manager = DatabaseManager::create_database(".", "database")?;
    ///     manager.write_new(ItemId::id("a.txt"), ItemId::database_id())?;
    ///     let _relative = manager.locate_relative(ItemId::id("a.txt"))?;
    ///     Ok(())
    /// }
    /// ```
    pub fn locate_relative(&self, id: impl Into<ItemId>) -> Result<&PathBuf, DatabaseError> {
        let id = id.into();
        if id.get_name().is_empty() {
            return Ok(&self.path);
        }

        self.resolve_path_by_id(&id)
    }

    /// Returns all stored **`ItemId`** values that share a `name`.
    ///
    /// The returned IDs use the occupied stable indexes from that internal name bucket.
    pub fn get_ids_by_name(&self, name: impl AsRef<str>) -> Vec<ItemId> {
        self.items
            .get(name.as_ref())
            .map(|paths| {
                paths
                    .iter()
                    .map(|(index, _)| ItemId::with_index(name.as_ref(), index))
                    .collect()
            })
            .unwrap_or_default()
    }

    /// Returns all stored **`ItemId`** values that share an `index`.
    ///
    /// This scans all name buckets and returns every ID whose stable slot equals `index`.
    pub fn get_ids_by_index(&self, index: usize) -> Vec<ItemId> {
        self.items
            .iter()
            .filter_map(|(name, paths)| {
                paths
                    .get(index)
                    .map(|_| ItemId::with_index(name.clone(), index))
            })
            .collect()
    }

    /// Scans files on disk and compares them to entries in this scan area.
    ///
    /// Missing tracked items are always removed from the `items` index kept in memory.
    ///
    /// Policy behavior for newly discovered external items:
    /// - `DetectOnly`: detect only.
    /// - `AddNew`: detect and add to the `index`.
    /// - `RemoveNew`: delete from disk and do not keep them in the report.
    ///
    /// # Parameters
    /// - `scan_from`: root **`ItemId`** to scan from (`ItemId::database_id()` scans the full database).
    /// - `policy`: change handling policy.
    /// - `recursive`: `true` scans full subtree, `false` scans immediate children only.
    ///
    /// # Errors
    /// Returns an error if:
    /// - `scan_from` cannot be found,
    /// - `scan_from` points to a file,
    /// - path-to-string conversion fails for discovered entries,
    /// - filesystem read or delete operations fail.
    ///
    /// # Examples
    /// ```no_run
    /// use file_database::{DatabaseError, DatabaseManager, ItemId, ScanPolicy};
    ///
    /// fn main() -> Result<(), DatabaseError> {
    ///     let mut manager = DatabaseManager::create_database(".", "database")?;
    ///     let _report = manager.scan_for_changes(ItemId::database_id(), ScanPolicy::AddNew, true)?;
    ///     Ok(())
    /// }
    /// ```
    pub fn scan_for_changes(
        &mut self,
        scan_from: impl Into<ItemId>,
        policy: ScanPolicy,
        recursive: bool,
    ) -> Result<ScanReport, DatabaseError> {
        let scan_from = scan_from.into();
        let scan_from_absolute = self.locate_absolute(&scan_from)?;
        if !scan_from_absolute.is_dir() {
            return Err(DatabaseError::NotADirectory(scan_from_absolute));
        }

        let scope_relative = if scan_from.get_name().is_empty() {
            None
        } else {
            Some(self.locate_relative(&scan_from)?.clone())
        };

        let discovered_paths = self.collect_paths_in_scope(&scan_from_absolute, recursive)?;
        let discovered_set: HashSet<PathBuf> = discovered_paths.iter().cloned().collect();

        let mut existing_in_scope_set = HashSet::new();
        let mut removed = Vec::new();
        let mut unchanged_count = 0usize;
        let mut removed_ids = Vec::new();

        for (name, paths) in &self.items {
            for (index, path) in paths.iter() {
                if !self.is_path_in_scope(path, scope_relative.as_deref(), recursive) {
                    continue;
                }

                existing_in_scope_set.insert(path.clone());

                let id = ItemId::with_index(name.clone(), index);
                if discovered_set.contains(path) {
                    unchanged_count += 1;
                } else {
                    removed.push(ExternalChange::Removed {
                        id: id.clone(),
                        path: path.clone(),
                    });
                    removed_ids.push(id);
                }
            }
        }

        for id in removed_ids {
            let _ = self.remove_id_from_index(&id);
        }

        let mut added_paths: Vec<PathBuf> = discovered_paths
            .into_iter()
            .filter(|path| !existing_in_scope_set.contains(path))
            .collect();

        let mut added = Vec::new();
        match policy {
            ScanPolicy::DetectOnly => {
                for path in &added_paths {
                    let name = path
                        .file_name()
                        .and_then(|name| name.to_str())
                        .ok_or(DatabaseError::OsStringConversion)?
                        .to_string();
                    added.push(ExternalChange::Added {
                        id: ItemId::id(name),
                        path: path.clone(),
                    });
                }
            }
            ScanPolicy::AddNew => {
                for path in &added_paths {
                    let name = path
                        .file_name()
                        .and_then(|name| name.to_str())
                        .ok_or(DatabaseError::OsStringConversion)?
                        .to_string();
                    let id = self.insert_generated_path(name, path.clone());
                    added.push(ExternalChange::Added {
                        id,
                        path: path.clone(),
                    });
                }
            }
            ScanPolicy::RemoveNew => {
                for path in &added_paths {
                    let name = path
                        .file_name()
                        .and_then(|name| name.to_str())
                        .ok_or(DatabaseError::OsStringConversion)?
                        .to_string();
                    added.push(ExternalChange::Added {
                        id: ItemId::id(name),
                        path: path.clone(),
                    });
                }

                added_paths.sort_by_key(|path| std::cmp::Reverse(path.components().count()));
                for path in added_paths {
                    let absolute = self.path.join(&path);
                    if !absolute.exists() {
                        continue;
                    }

                    if absolute.is_dir() {
                        remove_dir_all(&absolute)?;
                    } else if absolute.is_file() {
                        remove_file(&absolute)?;
                    }
                }
            }
        }

        let total_changed_count = added.len() + removed.len();

        match policy {
            ScanPolicy::RemoveNew => {
                added.clear();
            },
            _ => (),
        }

        Ok(ScanReport {
            scanned_from: scan_from,
            recursive,
            added,
            removed,
            unchanged_count,
            total_changed_count,
        })
    }

    /// Moves the entire database directory to a new parent directory.
    ///
    /// Existing destination database directory with the same name is removed first.
    ///
    /// # Parameters
    /// - `to`: destination parent directory.
    ///
    /// # Errors
    /// Returns an error if:
    /// - current database path is invalid,
    /// - destination cleanup fails,
    /// - recursive copy or source removal fails.
    ///
    /// # Examples
    /// ```no_run
    /// use file_database::{DatabaseError, DatabaseManager};
    ///
    /// fn main() -> Result<(), DatabaseError> {
    ///     let mut manager = DatabaseManager::create_database(".", "database")?;
    ///     manager.migrate_database("./new_parent")?;
    ///     Ok(())
    /// }
    /// ```
    pub fn migrate_database(&mut self, to: impl AsRef<Path>) -> Result<(), DatabaseError> {
        let destination = to.as_ref().to_path_buf();
        let name = self
            .path
            .file_name()
            .ok_or_else(|| DatabaseError::NotADirectory(self.path.clone()))?;
        let destination_database_path = destination.join(name);

        if destination_database_path.exists() {
            remove_dir_all(&destination_database_path)?;
        }

        self.copy_directory_recursive(&self.path, &destination_database_path)?;
        remove_dir_all(&self.path)?;

        self.path = destination_database_path;

        Ok(())
    }

    /// Moves a managed item to another directory inside the same database.
    ///
    /// # Parameters
    /// - `id`: source item to move.
    /// - `to`: destination directory item (or `ItemId::database_id()`).
    ///
    /// # Errors
    /// Returns an error if:
    /// - `id` is root or cannot be found,
    /// - destination is not a directory,
    /// - source and destination are identical,
    /// - filesystem move fails.
    ///
    /// # Examples
    /// ```no_run
    /// use file_database::{DatabaseError, DatabaseManager, ItemId};
    ///
    /// fn main() -> Result<(), DatabaseError> {
    ///     let mut manager = DatabaseManager::create_database(".", "database")?;
    ///     manager.write_new(ItemId::id("folder"), ItemId::database_id())?;
    ///     manager.write_new(ItemId::id("a.txt"), ItemId::database_id())?;
    ///     manager.migrate_item(ItemId::id("a.txt"), ItemId::id("folder"))?;
    ///     Ok(())
    /// }
    /// ```
    pub fn migrate_item(
        &mut self,
        id: impl Into<ItemId>,
        to: impl Into<ItemId>,
    ) -> Result<(), DatabaseError> {
        let id = id.into();
        let to = to.into();

        if id.get_name().is_empty() {
            return Err(DatabaseError::RootIdUnsupported);
        }

        let destination_dir = self.locate_absolute(&to)?;
        if !destination_dir.is_dir() {
            return Err(DatabaseError::NotADirectory(destination_dir));
        }

        let source_absolute = self.locate_absolute(&id)?;
        let source_name = source_absolute
            .file_name()
            .ok_or_else(|| DatabaseError::NoMatchingID(id.as_string()))?;
        let destination_absolute = destination_dir.join(source_name);

        if destination_absolute == source_absolute {
            return Err(DatabaseError::IdenticalSourceDestination(
                destination_absolute,
            ));
        }

        if destination_absolute.exists() {
            if destination_absolute.is_dir() {
                remove_dir_all(&destination_absolute)?;
            } else {
                remove_file(&destination_absolute)?;
            }
        }

        fs::rename(&source_absolute, &destination_absolute)?;

        let relative_destination = destination_absolute.strip_prefix(&self.path)?.to_path_buf();
        let source_name = relative_destination
            .file_name()
            .and_then(|name| name.to_str())
            .ok_or(DatabaseError::OsStringConversion)?
            .to_string();
        let migrated_id = ItemId::with_index(source_name, id.get_index());

        self.remove_id_from_index(&id)?;
        self.insert_path_for_id(&migrated_id, relative_destination)?;

        Ok(())
    }

    /// Exports a managed file or directory to an external destination directory.
    ///
    /// `Copy` keeps the item in the `index`. `Move` removes the moved entry from the `index`.
    ///
    /// # Parameters
    /// - `id`: source item to export.
    /// - `to`: external destination directory path.
    /// - `mode`: copy or move behavior.
    ///
    /// # Errors
    /// Returns an error if:
    /// - `id` is root or cannot be found,
    /// - destination is inside the database,
    /// - destination path cannot be created or used as a directory,
    /// - filesystem copy/move operations fail.
    ///
    /// # Examples
    /// ```no_run
    /// use file_database::{DatabaseError, DatabaseManager, ExportMode, ItemId};
    ///
    /// fn main() -> Result<(), DatabaseError> {
    ///     let mut manager = DatabaseManager::create_database(".", "database")?;
    ///     manager.write_new(ItemId::id("a.txt"), ItemId::database_id())?;
    ///     manager.export_item(ItemId::id("a.txt"), "./exports", ExportMode::Copy)?;
    ///     Ok(())
    /// }
    /// ```
    pub fn export_item(
        &mut self,
        id: impl Into<ItemId>,
        to: impl AsRef<Path>,
        mode: ExportMode,
    ) -> Result<(), DatabaseError> {
        let id = id.into();
        let destination_dir = {
            let to = to.as_ref();
            if to.is_absolute() {
                to.to_path_buf()
            } else {
                current_dir()?.join(to)
            }
        };

        if id.get_name().is_empty() {
            return Err(DatabaseError::RootIdUnsupported);
        }

        if destination_dir.starts_with(&self.path) {
            return Err(DatabaseError::ExportDestinationInsideDatabase(
                destination_dir,
            ));
        }

        fs::create_dir_all(&destination_dir)?;
        if !destination_dir.is_dir() {
            return Err(DatabaseError::NotADirectory(destination_dir));
        }

        let source_absolute = self.locate_absolute(&id)?;
        let source_name = source_absolute
            .file_name()
            .ok_or_else(|| DatabaseError::NoMatchingID(id.as_string()))?;
        let destination_absolute = destination_dir.join(source_name);

        if destination_absolute == source_absolute {
            return Err(DatabaseError::IdenticalSourceDestination(
                destination_absolute,
            ));
        }

        if destination_absolute.exists() {
            if destination_absolute.is_dir() {
                remove_dir_all(&destination_absolute)?;
            } else {
                remove_file(&destination_absolute)?;
            }
        }

        match mode {
            ExportMode::Copy => {
                if source_absolute.is_dir() {
                    self.copy_directory_recursive(&source_absolute, &destination_absolute)?;
                } else {
                    fs::copy(&source_absolute, &destination_absolute)?;
                }
            }
            ExportMode::Move => {
                match fs::rename(&source_absolute, &destination_absolute) {
                    Ok(_) => (),
                    Err(_) => {
                        if source_absolute.is_dir() {
                            self.copy_directory_recursive(&source_absolute, &destination_absolute)?;
                            remove_dir_all(&source_absolute)?;
                        } else {
                            fs::copy(&source_absolute, &destination_absolute)?;
                            remove_file(&source_absolute)?;
                        }
                    }
                }
                self.remove_id_from_index(&id)?;
            }
        }

        Ok(())
    }

    /// Imports an external file or directory into a database destination directory.
    ///
    /// The imported item keeps its original `name`.
    ///
    /// # Parameters
    /// - `from`: source path outside the database.
    /// - `to`: destination directory item in the database.
    ///
    /// # Errors
    /// Returns an error if:
    /// - source path points inside the database,
    /// - destination is not a directory,
    /// - destination `path`/`name` already exists,
    /// - source does not exist as file or directory,
    /// - filesystem copy operations fail.
    ///
    /// # Examples
    /// ```no_run
    /// use file_database::{DatabaseError, DatabaseManager, ItemId};
    ///
    /// fn main() -> Result<(), DatabaseError> {
    ///     let mut manager = DatabaseManager::create_database(".", "database")?;
    ///     manager.write_new(ItemId::id("imports"), ItemId::database_id())?;
    ///     manager.import_item("./outside/example.txt", ItemId::id("imports"))?;
    ///     Ok(())
    /// }
    /// ```
    pub fn import_item(
        &mut self,
        from: impl AsRef<Path>,
        to: impl Into<ItemId>,
    ) -> Result<(), DatabaseError> {
        let source_path = {
            let from = from.as_ref();
            if from.is_absolute() {
                from.to_path_buf()
            } else {
                current_dir()?.join(from)
            }
        };
        let to = to.into();

        if source_path.starts_with(&self.path) {
            return Err(DatabaseError::ImportSourceInsideDatabase(source_path));
        }

        let destination_parent = self.locate_absolute(&to)?;
        if !destination_parent.is_dir() {
            return Err(DatabaseError::NotADirectory(destination_parent));
        }

        let item_name = source_path
            .file_name()
            .ok_or_else(|| DatabaseError::NotAFile(source_path.clone()))?
            .to_string_lossy()
            .to_string();

        let destination_absolute = destination_parent.join(&item_name);
        let destination_relative = if to.get_name().is_empty() {
            PathBuf::from(&item_name)
        } else {
            let mut relative = self.locate_relative(&to)?.to_path_buf();
            relative.push(&item_name);
            relative
        };

        if destination_absolute.exists()
            || self.path_exists_in_index(&destination_relative)
        {
            return Err(DatabaseError::IdAlreadyExists(item_name));
        }

        if source_path.is_dir() {
            self.copy_directory_recursive(&source_path, &destination_absolute)?;
        } else if source_path.is_file() {
            fs::copy(&source_path, &destination_absolute)?;
        } else {
            return Err(DatabaseError::NoMatchingID(
                source_path.display().to_string(),
            ));
        }

        let _id = self.insert_generated_path(item_name, destination_relative);

        Ok(())
    }

    /// Duplicates a managed item into `parent` using a caller-provided `name`.
    ///
    /// # Parameters
    /// - `id`: source item to duplicate.
    /// - `parent`: destination parent directory item (or `ItemId::database_id()`).
    /// - `name`: new name for the duplicate.
    ///
    /// # Errors
    /// Returns an error if:
    /// - `id` is root or cannot be found,
    /// - destination parent is not a directory,
    /// - destination `name` already exists in the target directory,
    /// - filesystem copy fails.
    ///
    /// # Examples
    /// ```no_run
    /// use file_database::{DatabaseError, DatabaseManager, ItemId};
    ///
    /// fn main() -> Result<(), DatabaseError> {
    ///     let mut manager = DatabaseManager::create_database(".", "database")?;
    ///     manager.write_new(ItemId::id("a.txt"), ItemId::database_id())?;
    ///     manager.duplicate_item(ItemId::id("a.txt"), ItemId::database_id(), "copy.txt")?;
    ///     Ok(())
    /// }
    /// ```
    pub fn duplicate_item(
        &mut self,
        id: impl Into<ItemId>,
        parent: impl Into<ItemId>,
        name: impl AsRef<str>,
    ) -> Result<(), DatabaseError> {
        let id = id.into();
        let parent = parent.into();
        let name = name.as_ref().to_owned();

        if id.get_name().is_empty() {
            return Err(DatabaseError::RootIdUnsupported);
        }

        let source_absolute = self.locate_absolute(&id)?;
        let parent_absolute = self.locate_absolute(&parent)?;
        if !parent_absolute.is_dir() {
            return Err(DatabaseError::NotADirectory(parent_absolute));
        }

        let destination_absolute = parent_absolute.join(&name);
        let destination_relative = if parent.get_name().is_empty() {
            PathBuf::from(&name)
        } else {
            let mut path = self.locate_relative(&parent)?.to_path_buf();
            path.push(&name);
            path
        };

        if destination_absolute.exists()
            || self.path_exists_in_index(&destination_relative)
        {
            return Err(DatabaseError::IdAlreadyExists(name));
        }

        if source_absolute.is_dir() {
            self.copy_directory_recursive(&source_absolute, &destination_absolute)?;
        } else {
            fs::copy(&source_absolute, &destination_absolute)?;
        }

        let duplicate_name = destination_relative
            .file_name()
            .map(|name| name.to_string_lossy().to_string())
            .unwrap_or_default();
        let _duplicate_id = self.insert_generated_path(duplicate_name, destination_relative);

        Ok(())
    }

    /// Returns filesystem metadata summary for a managed file or directory.
    ///
    /// Includes:
    /// - `name`/`extension`,
    /// - normalized size,
    /// - Unix timestamps and "time since" timestamps where available.
    ///
    /// # Parameters
    /// - `id`: item to inspect.
    ///
    /// # Errors
    /// Returns an error if:
    /// - `id` cannot be found,
    /// - metadata lookup fails.
    ///
    /// # Examples
    /// ```no_run
    /// use file_database::{DatabaseError, DatabaseManager, ItemId};
    ///
    /// fn main() -> Result<(), DatabaseError> {
    ///     let mut manager = DatabaseManager::create_database(".", "database")?;
    ///     manager.write_new(ItemId::id("a.txt"), ItemId::database_id())?;
    ///     let _info = manager.get_file_information(ItemId::id("a.txt"))?;
    ///     Ok(())
    /// }
    /// ```
    pub fn get_file_information(
        &self,
        id: impl Into<ItemId>,
    ) -> Result<FileInformation, DatabaseError> {
        let id = id.into();

        let path = self.locate_absolute(id)?;

        let metadata = fs::metadata(&path)?;

        let name = {
            let os = if path.is_dir() {
                path.file_name()
            } else {
                path.file_stem()
            };

            os_str_to_string(os).ok()
        };

        let extension = {
            if path.is_dir() {
                None
            } else {
                os_str_to_string(path.extension()).ok()
            }
        };

        let size = FileSize::from(metadata.len());

        let unix_created = sys_time_to_unsigned_int(metadata.created());
        let time_since_created = sys_time_to_time_since(metadata.created());

        let unix_last_opened = sys_time_to_unsigned_int(metadata.accessed());
        let time_since_last_opened = sys_time_to_time_since(metadata.accessed());

        let unix_last_modified = sys_time_to_unsigned_int(metadata.modified());
        let time_since_last_modified = sys_time_to_time_since(metadata.modified());

        Ok(FileInformation {
            name,
            extension,
            size,
            unix_created,
            time_since_created,
            unix_last_opened,
            time_since_last_opened,
            unix_last_modified,
            time_since_last_modified,
        })
    }

    /// Returns all stored `(ItemId, relative_path)` pairs.
    fn all_paths(&self) -> Vec<(ItemId, &PathBuf)> {
        let mut result = Vec::new();

        for (name, paths) in &self.items {
            for (index, path) in paths.iter() {
                result.push((ItemId::with_index(name.clone(), index), path));
            }
        }

        result
    }

    /// Returns `true` when any stored item already uses `relative_path`.
    fn path_exists_in_index(&self, relative_path: &Path) -> bool {
        self.items
            .values()
            .any(|paths| paths.iter().any(|(_, path)| path == relative_path))
    }

    /// Inserts an exact `ItemId` -> path mapping.
    fn insert_path_for_id(&mut self, id: &ItemId, path: PathBuf) -> Result<(), DatabaseError> {
        let paths = self.items.entry(id.get_name().to_string()).or_default();
        if !paths.insert_at(id.get_index(), path) {
            return Err(DatabaseError::IdAlreadyExists(id.as_string()));
        }
        Ok(())
    }

    /// Inserts a generated id for a shared name and returns the generated `ItemId`.
    fn insert_generated_path(&mut self, name: String, path: PathBuf) -> ItemId {
        let paths = self.items.entry(name.clone()).or_default();
        let index = paths.push(path);
        ItemId::with_index(name, index)
    }

    /// Removes one exact id entry from the index and prunes empty name buckets.
    fn remove_id_from_index(&mut self, id: &ItemId) -> Result<(), DatabaseError> {
        let name = id.get_name().to_string();
        let should_drop_name = {
            let paths = self
                .items
                .get_mut(&name)
                .ok_or_else(|| DatabaseError::NoMatchingID(id.as_string()))?;

            if !paths.remove(id.get_index()) {
                return Err(DatabaseError::NoMatchingID(id.as_string()));
            }

            paths.is_empty()
        };

        if should_drop_name {
            self.items.remove(&name);
        }

        Ok(())
    }

    /// Gets one specific path for an exact **`ItemId`** key.
    ///
    /// This resolves `id.name` to a `StableVec` bucket and `id.index` to its stable slot.
    ///
    /// # Errors
    /// Returns an error if:
    /// - the exact key does not exist.
    fn resolve_path_by_id(&self, id: &ItemId) -> Result<&PathBuf, DatabaseError> {
        self.items
            .get(id.get_name())
            .and_then(|paths| paths.get(id.get_index()))
            .ok_or_else(|| DatabaseError::NoMatchingID(id.as_string()))
    }

    /// Overwrites a file safely by using a temp file and rename.
    ///
    /// `write_fn` is responsible for writing bytes to the temporary file and returning
    /// the number of bytes written.
    ///
    /// # Errors
    /// Returns an error if:
    /// - `path` points to a directory,
    /// - temp create/write/sync/rename fails.
    fn overwrite_path_atomic_with<F>(&self, path: &Path, write_fn: F) -> Result<u64, DatabaseError>
    where
        F: FnOnce(&mut File) -> Result<u64, DatabaseError>,
    {
        if path.is_dir() {
            return Err(DatabaseError::NotAFile(path.to_path_buf()));
        }

        let buffer = path.with_extension("tmp");

        let result = (|| {
            let mut file = File::create(&buffer)?;
            let bytes_written = write_fn(&mut file)?;
            file.sync_all()?;
            fs::rename(&buffer, path)?;
            Ok(bytes_written)
        })();

        if result.is_err() && buffer.exists() {
            let _ = remove_file(&buffer);
        }

        result
    }

    /// Collects relative file and folder paths in the scan area.
    ///
    /// # Parameters
    /// - `scope_absolute`: absolute root directory for collection.
    /// - `recursive`: whether to include descendants recursively.
    ///
    /// # Errors
    /// Returns an error if reading folders fails or converting to a relative prefix fails.
    fn collect_paths_in_scope(
        &self,
        scope_absolute: &Path,
        recursive: bool,
    ) -> Result<Vec<PathBuf>, DatabaseError> {
        let mut collected = Vec::new();

        if recursive {
            let mut stack = vec![scope_absolute.to_path_buf()];
            while let Some(directory) = stack.pop() {
                for entry in fs::read_dir(&directory)? {
                    let entry = entry?;
                    let absolute_path = entry.path();
                    let relative_path = absolute_path.strip_prefix(&self.path)?.to_path_buf();

                    if absolute_path.is_dir() {
                        collected.push(relative_path);
                        stack.push(absolute_path);
                    } else if absolute_path.is_file() {
                        collected.push(relative_path);
                    }
                }
            }
        } else {
            for entry in fs::read_dir(scope_absolute)? {
                let entry = entry?;
                let absolute_path = entry.path();
                let relative_path = absolute_path.strip_prefix(&self.path)?.to_path_buf();

                if absolute_path.is_dir() || absolute_path.is_file() {
                    collected.push(relative_path);
                }
            }
        }

        Ok(collected)
    }

    /// Recursively copies a directory tree from `from` to `to`.
    fn copy_directory_recursive(&self, from: &Path, to: &Path) -> Result<(), DatabaseError> {
        fs::create_dir_all(to)?;

        for entry in fs::read_dir(from)? {
            let entry = entry?;
            let source_path = entry.path();
            let destination_path = to.join(entry.file_name());

            if source_path.is_dir() {
                self.copy_directory_recursive(&source_path, &destination_path)?;
            } else {
                fs::copy(&source_path, &destination_path)?;
            }
        }

        Ok(())
    }

    /// Returns whether `path` is inside the requested scan scope.
    fn is_path_in_scope(
        &self,
        path: &Path,
        scope_relative: Option<&Path>,
        recursive: bool,
    ) -> bool {
        match scope_relative {
            None => {
                if recursive {
                    true
                } else {
                    path.parent()
                        .is_some_and(|parent| parent.as_os_str().is_empty())
                }
            }
            Some(scope_relative) => {
                if recursive {
                    path.starts_with(scope_relative) && path != scope_relative
                } else {
                    path.parent() == Some(scope_relative)
                }
            }
        }
    }

    /// Deletes a directory in forced or non-forced mode.
    fn delete_directory(&self, path: &Path, force: bool) -> Result<(), DatabaseError> {
        if force {
            remove_dir_all(path)?;
        } else {
            remove_dir(path)?;
        }
        Ok(())
    }
}

// -------- Functions --------
/// Removes `steps` trailing segments from `path`.
///
/// # Errors
/// Returns [`DatabaseError::PathStepOverflow`] when `steps` is too large for `path`.
fn truncate(mut path: PathBuf, steps: i32) -> Result<PathBuf, DatabaseError> {
    let parents = (path.ancestors().count() - 1) as i32;

    if parents <= steps {
        return Err(DatabaseError::PathStepOverflow(steps, parents));
    }

    for _ in 0..steps {
        path.pop();
    }

    Ok(path)
}

/// Converts an optional `OsStr` into an owned `String`.
///
/// # Errors
/// Returns [`DatabaseError::OsStringConversion`] if the value is `None` or invalid UTF-8.
fn os_str_to_string(os_str: Option<&OsStr>) -> Result<String, DatabaseError> {
    let os_str = match os_str {
        Some(os_str) => os_str,
        None => return Err(DatabaseError::OsStringConversion),
    };

    match os_str.to_os_string().into_string() {
        Ok(string) => Ok(string),
        Err(_) => Err(DatabaseError::OsStringConversion),
    }
}

/// Converts `SystemTime` to Unix timestamp seconds.
///
/// Returns `None` for platform or conversion failures.
fn sys_time_to_unsigned_int(time: io::Result<SystemTime>) -> Option<u64> {
    match time {
        Ok(time) => match time.duration_since(UNIX_EPOCH) {
            Ok(duration) => Some(duration.as_secs()),
            Err(_) => None,
        },
        Err(_) => None,
    }
}

/// Converts `SystemTime` to "time since now" represented as Unix-seconds duration.
///
/// Returns `None` for platform or conversion failures.
fn sys_time_to_time_since(time: io::Result<SystemTime>) -> Option<u64> {
    let duration = match time {
        Ok(time) => match SystemTime::now().duration_since(time) {
            Ok(duration) => duration,
            Err(_) => return None,
        },
        Err(_) => return None,
    };

    sys_time_to_unsigned_int(Ok(UNIX_EPOCH + duration))
}