stardew-valley-data

Pre-1.0 Notice: This package is under active development. Breaking changes to the save file parser structure, data types, and other APIs may occur in any release before 1.0.0. Pin your version or review the Change Log before upgrading.

📦 Installation

npm install stardew-valley-data
# or
pnpm add stardew-valley-data
# or
yarn add stardew-valley-data

🚀 Quick Start

Every module exports a factory function that returns a chainable query builder.

import { crops, fish, search, villagers } from "stardew-valley-data";

// Get all spring crops sorted by sell price
crops().bySeason("spring").sortBySellPrice().get();

// Find a specific fish
fish().findByName("Sturgeon");

// Get marriageable villagers
villagers().marriageable().sortByName().get();

// Search across all modules
search("diamond");

⚙️ How It Works

All modules follow the same query builder pattern built on a shared QueryBase<T> class:

factory() // Start with all data
  .filterMethod() // Chain filters (returns new query)
  .sortMethod() // Chain sorts (returns new query)
  .terminalMethod(); // Get results

Terminal Methods

Every query builder provides these 5 terminal methods:

| Method | Returns | Description | | ---------------- | ---------------- | ------------------------------- | | .get() | T[] | All results as an array | | .first() | T \| undefined | First result | | .find(id) | T \| undefined | Find by exact ID | | .findByName(n) | T \| undefined | Find by name (case-insensitive) | | .count() | number | Number of results |

Chaining

Filter and sort methods always return a new query instance, so you can chain freely without mutation:

const springCrops = crops().bySeason("spring");
const cheapest = springCrops.sortBySellPrice("asc").first();
const count = springCrops.count();

📚 Modules

🗡️ Items & Equipment

| Module | Factory | Items | Description | | ------------------------------------------ | ------------ | ----- | ---------------------------------- | | bait | bait() | 7 | Fishing bait items | | tackle | tackle() | 10 | Fishing tackle attachments | | footwear | footwear() | 18 | Boots and shoes | | hats | hats() | 122 | Hats and headwear | | rings | rings() | 30 | Rings and accessories | | tools | tools() | 21 | Tools with upgrade tiers | | weapons | weapons() | 62 | Swords, daggers, clubs, slingshots | | trinkets | trinkets() | 8 | Trinket accessories |

🌾 Farming & Nature

| Module | Factory | Items | Description | | ---------------------------------------------------- | ---------------- | ----- | ---------------------------------------- | | crops | crops() | 46 | Crops with seasons, growth stages, seeds | | trees | trees() | 14 | Fruit trees and wild trees | | animals | animals() | 27 | Farm animals and pets | | artisan-goods | artisanGoods() | 27 | Wine, cheese, jelly, etc. | | mixed-seeds | mixedSeeds() | 2 | Mixed seed drop tables by season | | seasons | seasons() | 4 | Season metadata |

🐟 Fishing

| Module | Factory | Items | Description | | ---------------------------------- | -------- | ----- | ---------------------------------------- | | fish | fish() | 77 | All fish with location, time, difficulty |

⛏️ Foraging & Mining

| Module | Factory | Items | Description | | ------------------------------------------------ | --------------- | ----- | -------------------------- | | forageables | forageables() | 48 | Forageable items by season | | minerals | minerals() | 97 | Ores, gems, geodes, nodes | | artifacts | artifacts() | 42 | Museum artifacts |

🍳 Cooking & Crafting

| Module | Factory | Items | Description | | ------------------------------------------ | ------------ | ----- | ------------------------ | | cooking | cooking() | 81 | Recipes with ingredients | | crafting | crafting() | 150 | Crafting recipes |

⚔️ Combat

| Module | Factory | Items | Description | | ------------------------------------------------------------------ | ---------------------- | ----- | ------------------------------------ | | monsters | monsters() | 44 | Monster stats, drops, locations | | monsters | monsterLoot() | 5 | Loot table categories | | monster-slayer-goals | monsterSlayerGoals() | 12 | Adventurer's Guild eradication goals | | weapon-stats | weaponStats() | 5 | Weapon type stat ranges |

💬 NPCs & Social

| Module | Factory | Items | Description | | -------------------------------------------------------- | ------------------ | ----- | ------------------------------- | | villagers | villagers() | 34 | Villagers with gifts, schedules | | universal-gifts | universalGifts() | — | Universal gift preferences | | events | events() | 100 | Heart events, festivals | | quests | quests() | 58 | Quest details | | special-orders | specialOrders() | 28 | Town + Qi special orders |

🏆 Progression

| Module | Factory | Items | Description | | ------------------------------------------------------ | ----------------- | ----- | ---------------------------------- | | achievements | achievements() | 49 | Steam/game achievements | | skills | skills() | 5 | Skill levels + title calculations | | professions | professions() | 30 | Profession trees per skill | | bundles | bundles() | 61 | Community Center bundles (+ remix) | | perfection | perfection() | 11 | Perfection tracker categories | | stardrops | stardrops() | 7 | Stardrop locations | | golden-walnuts | goldenWalnuts() | 69 | Golden Walnut sources | | secret-notes | secretNotes() | 38 | Secret note contents | | lost-books | lostBooks() | 21 | Lost book contents | | collections | collections() | — | Collection tab tracking | | special-items | specialItems() | 41 | Books, powers, mastery items |

🛒 Shops (18 modules)

| Module | Factory | Items | Description | | --------------------------------------------------------------- | ---------------- | ----- | ------------------------------------------ | | pierre | pierre() | 54 | Seeds, saplings, ingredients, fertilizer | | saloon | saloon() | 16 | Food and recipes | | blacksmith | blacksmith() | 4 | Tool upgrades and sharpening | | carpenter | carpenter() | 21 | Materials, recipes, rotating furniture | | marnie | marnie() | 14 | Animal supplies, tools | | willy | willy() | 24 | Rods, bait, tackle (level-gated) | | krobus | krobus() | 16 | Permanent + daily rotating stock | | guild | guild() | 38 | Weapons, boots, rings, ammo | | casino | casino() | 13 | Qi Coin purchases | | desert-trader | desertTrader() | 26 | Barter items with day rotation | | oasis | oasis() | 16 | Seeds, food, daily rotating items | | volcano | volcanoShop() | 10 | Mixed currency (gold/cinder shard/diamond) | | island-trader | islandTrader() | 23 | Barter with day/special availability | | dwarf | dwarf() | 11 | Explosives, food, consumables | | joja | joja() | 34 | JojaMart inventory | | qi | qi() | 27 | Qi Gem shop | | bookseller | bookseller() | — | Book shop inventory | | medical-supplies | medical() | 2 | Harvey's Clinic items |

🗺️ World & Locations

| Module | Factory | Items | Description | | -------------------------------------------------- | -------------------- | ----- | ------------------------------- | | locations | locations() | 38 | Game locations with shops, NPCs | | maps | maps() | 8 | Farm map types | | buildings | buildings() | 23 | Farm buildings (Robin + Wizard) | | weather | weather() | 9 | Weather types and effects | | farmhouse | houseUpgrades() | — | House upgrade tiers | | | houseRenovations() | — | Interior renovations | | field-office | fieldOffice() | 4 | Island Field Office collections | | concessions | concessions() | 24 | Movie theater snacks |

🧮 Calculators

| Module | Factory | Description | | ---------------------------------------------- | --------------------- | ------------------------------------------------ | | calculator | qualityCalculator() | Quality-scaled sell prices and energy/health | | grandpa | grandpaEvaluator() | Grandpa's evaluation scoring (0–21, 1–4 candles) |

🔍 Search

import { search } from "stardew-valley-data";

// Search across all modules by name or ID
search("parsnip");
// Returns matches from crops, seeds, cooking ingredients, etc.

// Filter by kind
search("diamond", ["mineral", "ring"]);

💾 Save File Parser

import { parseSaveFile } from "stardew-valley-data";

const xml = fs.readFileSync("MyFarm_123456", "utf-8");
const save = parseSaveFile(xml);
// Extracts player data, inventory, friendships, progress, etc.

🔧 Utility Functions

import {
  calculateArtisanPrice,
  getMasteryLevel,
  getTitle,
  getTitleScore,
  isFarmAnimal,
  isPet,
} from "stardew-valley-data";

// Type guards for Animal discriminated union
const animal = animals().find("Cat");
if (isPet(animal)) {
  /* TypeScript narrows to Pet */
}

// Artisan good pricing
calculateArtisanPrice(good, ingredientBasePrice);

// Skill progression
getTitleScore(10, 10, 10, 10, 10); // → 25
getTitle(10, 10, 10, 10, 10); // → "Farm King"
getMasteryLevel(25000); // → 3

📖 Module Documentation

Each module has a detailed README in its source directory with complete method signatures, type definitions, field descriptions, and usage examples:

src/modules/<module-name>/README.md

🖼️ Image Assets

1,900+ images bundled under images/, organized by category:

| Folder | Description | | ---------------- | ----------------------------------------------------- | | achievements/ | Achievement icons | | animals/ | Farm animals, pets, and produce | | artifacts/ | Museum artifacts and Field Office donations | | artisan-goods/ | Artisan products | | buildings/ | Farm buildings including obelisks | | bundles/ | Community Center bundle icons | | cooking/ | Cooked dish icons | | craftable/ | Craftable items (sprinklers, bombs, fertilizer, etc.) | | crops/ | Seeds, growth stages, harvested crops, giant variants | | fish/ | Fish, bait, tackle, jelly, and other catchables | | footwear/ | Boots and shoes | | forageables/ | Forageable items by season | | hats/ | Hats and headwear | | locations/ | Location images | | maps/ | Farm map icons and full maps | | minerals/ | Ores, bars, gems, geodes, nodes | | monsters/ | Monster sprites | | rings/ | Rings | | scarecrows/ | Scarecrow and Rarecrow variants | | seasons/ | Season icons | | shop/ | Misc shop items | | skills/ | Skill icons | | special-items/ | Books, powers, mastery items | | tools/ | Tools by type | | trees/ | Fruit trees and wild trees with growth stages | | trinkets/ | Trinket icons | | villagers/ | Villager and spouse portraits | | weapons/ | Swords, daggers, clubs, slingshots | | weather/ | Weather icons |

Crop & Tree Folder Structure

crops/parsnip/
  seed.png          # Seed packet
  stage-1.png       # Growth stages
  stage-2.png
  ...
  crop.png          # Harvested crop
  giant.png         # Giant variant (if applicable)

trees/apple/
  seed.png          # Sapling
  stage-1.png       # Growth stages
  ...
  stage-5.png
  harvest.png       # Tree with fruit
  crop.png          # Fruit item

Using Images in Your Project

Images are available via the stardew-valley-data/images/* subpath export.

Static import:

import parsnipImg from "stardew-valley-data/images/crops/parsnip/crop.png";
import sturgeon from "stardew-valley-data/images/fish/Sturgeon.png";

Dynamic resolution from query results:

Every data item with an image field stores a path relative to the package root. Prefix with the package name to resolve it:

import { crops } from "stardew-valley-data";

const crop = crops().findByName("Parsnip");
const imgPath = `stardew-valley-data/${crop.image}`;
// → "stardew-valley-data/images/crops/parsnip/crop.png"

Next.js example:

import Image from "next/image";
import parsnipImg from "stardew-valley-data/images/crops/parsnip/crop.png";

export default function CropCard() {
  return <Image src={parsnipImg} alt="Parsnip" width={48} height={48} />;
}

📋 Raw Data Access

JSON data files can be imported directly:

import bait from "stardew-valley-data/data/bait.json";

📈 Change Log

Check out the Change Log for new breaking changes/features/bug fixes per release of a new version.

🤝 Contributing

Bug Reports, Feature Requests, and Pull Requests are welcome on GitHub at https://github.com/chiefpansancolt/stardew-valley-data. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

To see more about Contributing check out this document.

1. Fork Repo and create new branch
2. Once all is changed and committed create a pull request.
3. Ensure all merge conflicts are fixed and CI is passing.

🛠️ Development

See CONTRIBUTING.md for setup instructions and DEVELOPMENT.md for the full guide on adding new modules.

pnpm install        # Install dependencies
pnpm build          # Build with tsup
pnpm test           # Run tests
pnpm lint           # Type-check + ESLint
pnpm format         # Format with Prettier
pnpm sample         # Validate image paths + exercise queries

💖 Support the Project

If you find this project helpful, consider supporting its development:

📄 License

stardew-valley-data is available as open source under the terms of the MIT License.