livestock-breeds

Zero-dependency, fully-typed TypeScript package for querying livestock breed data.

Species covered: Cow · Buffalo · Goat · Sheep · Camel
Total breeds: ~500+
Features: Filter by use, sort by popularity/name/origin, full-text search, lazy loading, memoised queries

Install

npm install livestock-breeds
# or
pnpm add livestock-breeds
# or
bun add livestock-breeds

Quick Start

import { getBreeds, searchBreeds, getBreedByName, getUseSummary } from "livestock-breeds";

// All cow breeds sorted by popularity (default)
const cows = await getBreeds("cow");

// Only dairy breeds
const dairyCows = await getBreeds("cow", { use: "dairy" });

// Top 5 most popular buffalo breeds
const top5 = await getBreeds("buffalo", { sortBy: "popularity", limit: 5 });

// Alphabetical goat breeds
const goatsByName = await getBreeds("goat", { sortBy: "name" });

// Pakistani breeds across ALL species
const pakistani = await searchBreeds("pakistan");

// Single breed lookup
const sahiwal = await getBreedByName("Sahiwal");
// → { name: "Sahiwal", origin: "Pakistan", use: "dairy", popularity: 57, _species: "cow" }

// Use-type breakdown for sheep
const stats = await getUseSummary("sheep");
// → { wool: 14, meat: 20, dual: 18, dairy: 4, fur: 1 }

API Reference

getBreeds(species, options?)

Returns breeds for a single species.

getBreeds(species: Species, opts?: QueryOptions): Promise<readonly Breed[]>

| Option | Type | Default | Description | |-----------|-------------------------------|----------------|------------------------------------------| | use | UseType \| UseType[] | — | Filter by primary use | | origin | string | — | Case-insensitive origin substring filter | | sortBy | "popularity"\|"name"\|"origin" | "popularity" | Sort field | | order | "asc"\|"desc" | "asc" | Sort direction | | limit | number | — | Max results to return |

// Multiple use types
const utilityBreeds = await getBreeds("cow", { use: ["dual", "draft"] });

// Italian dairy cows, alphabetical
const italianDairy = await getBreeds("cow", {
  use: "dairy",
  origin: "Italy",
  sortBy: "name",
});

// Least popular first
const rare = await getBreeds("camel", { sortBy: "popularity", order: "desc" });

getAllBreeds(options?)

Returns breeds across all species in one flat array. Each entry has an extra _species field.

getAllBreeds(opts?: QueryOptions): Promise<readonly (Breed & { _species: Species })[]>

const all = await getAllBreeds({ sortBy: "name" });
// [{ name: "Abondance", origin: "France", use: "dual", popularity: 55, _species: "cow" }, …]

searchBreeds(query, species?, options?)

Full-text search across name, origin, and use. Returns partial matches.

searchBreeds(query: string, species?: Species, opts?: QueryOptions): Promise<...>

// All Pakistani breeds across all species
await searchBreeds("pakistan");

// Murrah breed specifically in buffalo
await searchBreeds("murrah", "buffalo");

// South African meat breeds
await searchBreeds("south africa", "goat", { use: "meat" });

getBreedByName(name, species?)

Exact name lookup (case-insensitive). Returns undefined if not found.

getBreedByName(name: string, species?: Species): Promise<(Breed & { _species: Species }) | undefined>

getUseSummary(species)

Returns a count of breeds per use-type for a species.

getUseSummary(species: Species): Promise<Partial<Record<UseType, number>>>

preloadSpecies(...species)

Pre-warm the cache at app startup to avoid async delay on first query.

await preloadSpecies("cow", "buffalo", "goat");

Types

type Species = "cow" | "buffalo" | "goat" | "sheep" | "camel";

type UseType =
  | "dairy" | "beef" | "meat" | "dual"
  | "draft" | "fiber" | "wool" | "fur"
  | "racing" | "pet"  | "wild";

interface Breed {
  name:       string;   // Common breed name
  origin:     string;   // Country / region of origin
  use:        UseType;  // Primary use
  popularity: number;   // Global rank — lower = more popular
}

interface QueryOptions {
  use?:    UseType | UseType[];
  origin?: string;
  sortBy?: "popularity" | "name" | "origin";
  order?:  "asc" | "desc";
  limit?:  number;
}

Raw Data Exports

For static / non-async use cases (e.g. bundling all data upfront):

import { cowBreeds, buffaloBreeds, goatBreeds, sheepBreeds, camelBreeds } from "livestock-breeds";

These are readonly frozen arrays — safe to use without copying.

Performance Notes

• Lazy loading — each species file is imported only on first access
• Memoised queries — identical (species + options) combos return cached results instantly
• Frozen arrays — prevents accidental mutation; V8 can optimise reads
• No dependencies — zero runtime overhead
• Tree-shakeable — import only what you use

Species & Breed Counts

| Species | Breeds | |---------|--------| | Cow | ~135 | | Buffalo | ~34 | | Goat | ~52 | | Sheep | ~67 | | Camel | ~34 | | Total | ~322 |

License

MIT