ifsc 0.1.1

A fast offline directory for Indian bank branches and IFSCs
Documentation
//! Directory query contracts.

use ifsc::{
    BankNameQuery, BankOrder, BankQuery, BankService, BranchOrder, BranchQuery, BranchTextField,
    BranchTextQuery, LocationField, Page, SearchOptions, SubletTarget, TextMatch,
};

#[test]
fn enumerates_in_ifsc_order() {
    let values: Vec<_> = ifsc::directory()
        .branches()
        .take(1_000)
        .map(|b| b.ifsc())
        .collect();
    assert!(values.windows(2).all(|pair| pair[0] < pair[1]));
}

#[test]
fn filters_and_pages_deterministically() {
    let query = BranchQuery::new()
        .with_location(LocationField::State, "KARNATAKA")
        .with_order(BranchOrder::Ifsc);
    let options = SearchOptions::new().with_page(Page::new().with_offset(10).with_limit(5));
    let mut page = ifsc::directory().search_branches(&query, options).unwrap();
    assert_eq!(page.offset(), 10);
    assert_eq!(page.len(), 5);
    let next = page.next_offset();
    let _ = page.next();
    assert_eq!(page.next_offset(), next);
}

#[test]
fn rejects_page_limits_outside_the_supported_range() {
    for limit in [0, 10_001] {
        let result = ifsc::directory().search_branches(
            &BranchQuery::new(),
            SearchOptions::new().with_page(Page::new().with_limit(limit)),
        );
        assert_eq!(result.err().unwrap().kind(), ifsc::ErrorKind::InvalidPage);
    }
}

#[test]
fn applies_text_limits_to_every_text_filter() {
    let options = SearchOptions::new().with_max_text_bytes(4);
    for query in [
        BranchQuery::new().with_location(LocationField::State, "KARNATAKA"),
        BranchQuery::new().with_micr("123456789"),
        BranchQuery::new().with_swift("ABCDEFGH"),
    ] {
        let error = ifsc::directory()
            .search_branches(&query, options)
            .err()
            .expect("query must exceed the configured text limit");
        assert_eq!(error.kind(), ifsc::ErrorKind::TooLong);
    }

    for value in ["", " \t"] {
        let empty = BranchQuery::new().with_location(LocationField::City, value);
        let error = ifsc::directory()
            .search_branches(&empty, SearchOptions::new())
            .err()
            .expect("empty query must fail");
        assert_eq!(error.kind(), ifsc::ErrorKind::InvalidQuery);
    }

    let bank_query = BankQuery::new().with_name(BankNameQuery::new("too long"));
    let error = ifsc::directory()
        .search_banks(&bank_query, options)
        .err()
        .expect("bank name must use the configured text limit");
    assert_eq!(error.kind(), ifsc::ErrorKind::TooLong);
}

#[test]
fn rejects_invalid_ifsc_prefix_syntax() {
    for prefix in ["", "HDFC1", "HD-C", "HDFC0ABCDEF!"] {
        let query = BranchQuery::new().with_ifsc_prefix(prefix);
        let error = ifsc::directory()
            .count_branches(&query)
            .expect_err("invalid IFSC prefix must fail");
        assert_eq!(error.kind(), ifsc::ErrorKind::InvalidQuery);
    }
    assert!(
        ifsc::directory()
            .count_branches(&BranchQuery::new().with_ifsc_prefix("hdfc0"))
            .unwrap()
            > 0
    );
}

#[test]
fn composes_source_backed_branch_filters() {
    let branch = ifsc::directory()
        .branches()
        .find(|branch| branch.micr().is_some() && branch.iso_subdivision().is_some())
        .expect("snapshot contains a branch with MICR and subdivision values");
    let branch_ifsc = branch.ifsc();
    let query = BranchQuery::new()
        .with_ifsc_prefix(branch_ifsc.as_str())
        .with_routing_code(branch.routing_code())
        .with_location(LocationField::City, branch.city())
        .with_iso_subdivision(branch.iso_subdivision().unwrap())
        .with_micr(branch.micr().unwrap())
        .with_reported_rail(
            ifsc::BranchRail::Neft,
            branch.reports(ifsc::BranchRail::Neft),
        )
        .with_text(
            BranchTextQuery::new(branch.name())
                .with_field(BranchTextField::BranchName)
                .with_match(TextMatch::Exact),
        );
    let matches: Vec<_> = ifsc::directory()
        .search_branches(&query, SearchOptions::default())
        .unwrap()
        .collect();
    assert_eq!(matches, [branch]);

    let mapping = ifsc::lookup_str("HDFC0CKUB01")
        .unwrap()
        .unwrap()
        .exact_sublet()
        .unwrap();
    let SubletTarget::Bank(bank) = mapping.target() else {
        panic!("known exact mapping must target a bank code");
    };
    let query = BranchQuery::new()
        .with_exact_sublet(true)
        .with_sublet_bank(bank);
    assert!(
        ifsc::directory()
            .search_branches(&query, SearchOptions::default())
            .unwrap()
            .any(|branch| branch.ifsc().as_str() == "HDFC0CKUB01")
    );
}

#[test]
fn filters_and_orders_banks() {
    let bank = ifsc::BankCode::parse_strict("PUNB")
        .unwrap()
        .bank()
        .unwrap();
    let profile = bank.profile().unwrap();
    let query = BankQuery::new()
        .with_kind(profile.kind())
        .with_reported_service(BankService::Upi, profile.reported_status(BankService::Upi))
        .with_profile(true)
        .with_name(BankNameQuery::new(bank.name()).with_match(TextMatch::Exact))
        .with_order(BankOrder::Name);
    let matches: Vec<_> = ifsc::directory()
        .search_banks(&query, SearchOptions::default())
        .unwrap()
        .collect();
    assert!(matches.contains(&bank));
    assert!(
        matches
            .windows(2)
            .all(|pair| { (pair[0].name(), pair[0].code()) <= (pair[1].name(), pair[1].code()) })
    );
}