Documentation Index
Fetch the complete documentation index at: https://mintlify.com/apursley2012/rescue-retriever/llms.txt
Use this file to discover all available pages before exploring further.
filterUtils.js is the core logic module of Rescue Retriever. It exports pure functions for scoring animals against rescue program profiles, sorting and filtering the dataset, aggregating analytics data, and generating CSV exports. All functions operate on plain JavaScript objects with no side effects except exportCSV, which triggers a browser file download.
Scoring Functions
These functions evaluate how well an individual animal matches one or more rescue program profiles. Scores are integers in the range 22–100, determined by the combination of breed, sex, and age match results.scoreAnimal(animal, profile)
Scores a single animal against a single rescue program profile. This is the foundational scoring function — all higher-level scoring helpers call it internally.
The score is computed as follows:
- Breed match contributes 50 points (match) or 12 points (no match)
- Sex match contributes 25 points (match) or 5 points (no match)
- Age match contributes 25 points (match) or 5 points (no match)
- The result is capped at 100 via
Math.min(100, ...)
qualifies is true only when all three criteria are met simultaneously.
An animal record from the dataset. Must include
breed, sex, ageWeeks, and animalId fields.A rescue program profile object from
rescueProfiles.js. Must include id, shortName, breeds, sex, minAgeWeeks, and maxAgeWeeks.ProgramScore
The rescue program identifier (e.g.
"water", "mountain", "disaster").Integer score from 22 to 100 representing overall match quality.
true if the animal’s breed substring-matches one of the profile’s preferred breeds after normalization.true if the animal’s sex field exactly matches the profile’s preferred sex value.true if Math.round(ageWeeks) falls within [minAgeWeeks, maxAgeWeeks] (inclusive).true only when breedMatch, sexMatch, and ageMatch are all true.A three-element array of human-readable sentences — one each for breed, sex, and age — describing why each criterion passed or failed.
scoreAllPrograms(animal)
Scores an animal against all three rescue program profiles simultaneously and returns the results sorted from highest to lowest matchScore. Used internally by getBestScore and getQualifyingPrograms.
An animal record from the dataset.
ProgramScore[] — array of three ProgramScore objects sorted by matchScore descending.
getBestScore(animal)
Returns the single highest-scoring ProgramScore for an animal across all three programs. Used by the “All Animals” view to rank animals without filtering to a specific program.
An animal record from the dataset.
ProgramScore — the ProgramScore object with the highest matchScore value, equivalent to scoreAllPrograms(animal)[0].
getQualifyingPrograms(animal)
Returns the list of program ids for which an animal strictly qualifies — meaning breedMatch, sexMatch, and ageMatch are all true. An animal may qualify for zero, one, two, or all three programs simultaneously.
An animal record from the dataset.
string[] — array of qualifying program ids, e.g. ["water"], ["mountain", "disaster"], or []. Order corresponds to the order profiles appear in rescueProfiles.js.
Sorting & Filtering Functions
These functions produce reordered or filtered subsets of the animal array without mutating the original input.sortByProgram(animals, programId)
Sorts the full animal array by rescue program score. When programId is "all", animals are ranked by their best score across all programs. When a specific program id is given, animals are ranked by their score against that program only. Ties in score are broken by ageWeeks ascending (younger animals rank higher).
The full or pre-filtered array of animal records.
Program identifier:
"water", "mountain", "disaster", or "all". Passing "all" ranks by getBestScore; passing a specific id ranks by scoreAnimal against that profile.Animal[] — a new sorted array. The input array is not mutated.
getStrictCandidates(animals, programId)
Filters the animal array to only those that strictly qualify for the specified program (all three criteria met), then sorts them by that program’s score descending with ageWeeks ascending as a tiebreaker. Used by the Reports page to generate per-program qualifying lists.
The full or pre-filtered array of animal records.
A specific program identifier:
"water", "mountain", or "disaster". Does not accept "all".Animal[] — only animals where getQualifyingPrograms(animal) includes programId, sorted by program score descending then ageWeeks ascending.
Analytics Functions
These functions aggregate the animal array into summary statistics used by the Analytics dashboard and the program summary header.getProgramSummary(animals)
Counts how many animals qualify for each rescue program, plus the total count of animals qualifying for at least one program. Animals qualifying for multiple programs are counted once in each program bucket but only once in total.
The full or pre-filtered array of animal records.
{ water: number, mountain: number, disaster: number, total: number }
Count of animals that qualify for Water Rescue.
Count of animals that qualify for Mountain Rescue.
Count of animals that qualify for Disaster Rescue.
Count of unique animals qualifying for at least one program. Determined using a
Set of animalId values.getBreedDistribution(animals)
Aggregates breed frequency across the dataset. Uses the raw breed string as-is (no normalization) for grouping, so "Labrador Retriever Mix" and "Labrador Retriever/Australian Cattle Dog" count as separate entries.
The full or pre-filtered array of animal records.
{ breed: string, count: number }[] — top 10 breeds by count, sorted descending. If fewer than 10 distinct breeds exist, all are returned.
The raw breed string from the animal record.
Number of animals in the dataset with this exact breed string.
getAgeDistribution(animals)
Buckets animals into fixed age ranges using Math.round(ageWeeks). All six buckets are always present in the output, even if their count is zero.
The full or pre-filtered array of animal records.
{ range: string, count: number }[] — one entry per age bucket in ascending order.
The fixed buckets are:
| Range label | Weeks condition |
|---|---|
"0–26 wks" | rounded age < 26 |
"26–52 wks" | >= 26 and < 52 |
"52–104 wks" | >= 52 and < 104 |
"104–156 wks" | >= 104 and < 156 |
"156–260 wks" | >= 156 and < 260 |
"260+ wks" | >= 260 |
getLocationDistribution(animals)
Aggregates intake location frequency. Uses the raw location string for grouping.
The full or pre-filtered array of animal records.
{ location: string, count: number }[] — top 10 locations by count, sorted descending.
The raw location string from the animal record (e.g.
"Thorndale, Texas, US").Number of animals recorded at this location.
Export Function
exportCSV(animals, filename)
Serializes the animal array to a CSV string and triggers a browser file download. This is the only function in filterUtils.js with a side effect. It uses the browser Blob API and does not make any network requests.
Each field is double-quoted in the output. Internal double-quote characters are escaped as "" per RFC 4180. See the CSV Export Reference for full column documentation and a sample output.
The array of animal records to export. Typically the currently visible/filtered set.
The download filename. Defaults to
"rescue-candidates.csv" if not provided.void — triggers a browser download as a side effect.
Internal Helper Functions
Two additional functions are used internally and are not part of the public module exports.normalizeBreed(breed) — Strips the words "mixed" and "dog" (case-insensitive, whole word), removes all non-alphanumeric characters except spaces, lowercases the result, and collapses consecutive whitespace. Used exclusively by breedMatches.
breedMatches(animalBreed, profileBreeds) — Normalizes the animal’s breed string and each profile breed string, then checks whether any normalized profile breed is a substring of the normalized animal breed or vice versa. Returns true on the first match found.
Usage Example
Scoring Algorithm
Deep dive into how matchScore is computed and what each criterion threshold means.
CSV Export Reference
Full column reference, encoding rules, and sample output for the exported CSV file.