Module index 

Index module for package database queries and management.

This module provides functionality for querying and managing package database information:

• Installed Package Queries - Query installed packages using pacman -Q* commands
• Explicit Package Tracking - Track explicitly installed packages with different modes
• Official Repository Queries - Search and query official Arch Linux repositories
• Index Fetching - Fetch official package index from pacman or Arch Packages API

Features

This module requires the index feature flag to be enabled:

[dependencies]
arch-toolkit = { version = "0.2", features = ["index"] }

For fuzzy search functionality, enable the fuzzy-search feature:

[dependencies]
arch-toolkit = { version = "0.2", features = ["index", "fuzzy-search"] }

For API fallback when pacman is unavailable, enable the aur feature:

[dependencies]
arch-toolkit = { version = "0.2", features = ["index", "aur"] }

Examples

Query Installed Packages

use arch_toolkit::index::{get_installed_packages, is_installed};
use std::collections::HashSet;

// Direct query without caching
let packages = get_installed_packages().unwrap();
println!("Found {} installed packages", packages.len());

// Check if a package is installed
if is_installed("vim", Some(&packages)) {
    println!("vim is installed");
}

Use Cache for Multiple Queries

use arch_toolkit::index::{refresh_installed_cache, is_installed};
use std::collections::HashSet;

let mut cache = HashSet::new();
refresh_installed_cache(Some(&mut cache)).unwrap();

// Now use cache for fast lookups
for package in ["vim", "git", "python"] {
    if is_installed(package, Some(&cache)) {
        println!("{} is installed", package);
    }
}

Async Cache Refresh

use arch_toolkit::index::refresh_installed_cache_async;
use std::collections::HashSet;

let mut cache = HashSet::new();
let packages = refresh_installed_cache_async(Some(&mut cache)).await?;
println!("Refreshed cache with {} packages", packages.len());

Query Explicit Packages

use arch_toolkit::index::{refresh_explicit_cache, is_explicit, InstalledPackagesMode};
use std::collections::HashSet;

let mut cache = HashSet::new();
// Get all explicitly installed packages
refresh_explicit_cache(InstalledPackagesMode::AllExplicit, Some(&mut cache)).unwrap();

// Check if a package is explicitly installed
if is_explicit("vim", InstalledPackagesMode::AllExplicit, Some(&cache)) {
    println!("vim is explicitly installed");
}

// Get only leaf packages (not required by others)
let leaf_packages = refresh_explicit_cache(InstalledPackagesMode::LeafOnly, None).unwrap();
println!("Found {} leaf packages", leaf_packages.len());

Search Official Packages

use arch_toolkit::index::{fetch_official_index_async, search_official};

// Fetch the official index
let index = fetch_official_index_async().await?;

// Search for packages (substring matching)
let results = search_official(&index, "vim", false);
for result in results {
    println!("{}: {}", result.package.name, result.package.version);
}

// Fuzzy search (requires fuzzy-search feature)
let fuzzy_results = search_official(&index, "rg", true);
for result in fuzzy_results {
    println!("{} (score: {:?})", result.package.name, result.fuzzy_score);
}

Get All Official Packages

use arch_toolkit::index::{all_official, fetch_official_index};

let index = fetch_official_index()?;
let all_packages = all_official(&index);
println!("Found {} official packages", all_packages.len());

Persist the Index to Disk

use arch_toolkit::index::{fetch_official_index, load_from_disk, save_to_disk};
use std::path::Path;

let path = Path::new("official_index.json");

// Load a cached index, falling back to a fresh fetch
let index = load_from_disk(path).or_else(|_| fetch_official_index())?;

// Save the index for the next session
save_to_disk(&index, path)?;

Re-exports

pub use crate::types::index::IndexQueryResult;

pub use crate::types::index::InstalledPackagesMode;

pub use crate::types::index::MirrorDiscoveryLimits;

pub use crate::types::index::MirrorInfo;

pub use crate::types::index::OfficialIndex;

pub use crate::types::index::OfficialPackage;

Structs

IndexRefreshHandle

What: Represent one caller-supplied background official-index refresh.

Constants

ARCH_MIRROR_STATUS_URL

Official Arch mirror-status endpoint used only by the opt-in convenience API.

MAX_MIRRORLIST_BYTES

Maximum bytes emitted by one generated mirrorlist.

Functions

all_official

What: Return all packages from the official index.

detect_enabled_repos

What: Discover repositories enabled in /etc/pacman.conf.

detect_enabled_repos_from

What: Discover repositories enabled in a specific pacman configuration file.

fetch_arch_mirrors

What: Fetch Arch’s standard mirror-status endpoint with caller-owned transport policy.

fetch_mirrors_from

What: Discover portable mirror metadata from a caller-selected JSON endpoint.

fetch_official_index

What: Fetch the official package index using pacman -Sl.

fetch_official_index_async

What: Fetch the official package index asynchronously, trying pacman first and falling back to API.

fetch_official_index_for_repos

What: Fetch the official package index for an explicit repository list.

fetch_official_index_for_repos_async

What: Fetch the official package index for an explicit repository list, asynchronously.

generate_mirrorlist

What: Generate deterministic pacman mirrorlist text from discovered metadata.

get_installed_packages

What: Query pacman directly for all installed packages without caching.

is_explicit

What: Check if a package is explicitly installed, using cache if provided or querying pacman directly.

is_installed

What: Check if a package is installed, using cache if provided or querying pacman directly.

load_from_disk

What: Load an official package index from a JSON file on disk.

load_from_disk_async

What: Load an official package index from disk asynchronously.

load_from_disk_or_default

What: Load an official package index from disk, tolerating missing or corrupt files.

refresh_explicit_cache

What: Query pacman for explicitly installed packages and optionally update a cache.

refresh_explicit_cache_async

What: Query pacman for explicitly installed packages asynchronously and optionally update a cache.

refresh_installed_cache

What: Query pacman for all installed packages and optionally update a cache.

refresh_installed_cache_async

What: Query pacman for all installed packages asynchronously and optionally update a cache.

save_to_disk

What: Persist an official package index to a JSON file on disk.

save_to_disk_async

What: Persist an official package index to disk asynchronously.

search_official

What: Search the official index for packages whose names match query.

spawn_index_refresh

What: Start a caller-supplied async index refresh in the background.