dinkum-data

📦 Installation

npm install dinkum-data
# or
pnpm add dinkum-data

🚀 Quick Start

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

import { animals, fish, licenses, seeds } from "dinkum-data";

// Domesticable animals
animals().domesticable().get();

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

// Rare fish, most valuable first
fish().byRarity("Rare").sortByBaseSellPrice().get();

// Spring-plantable seeds, fastest growing first
seeds().bySeason("Spring").sortByGrowthPeriod().get();

// Total permit points needed to max every license
licenses().totalPermitPoints();

⚙️ How It Works

All standard 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 6 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(name) | T \| undefined | Find by name (case-insensitive) | | .search(query) | T[] | Partial name match (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 rareFish = fish().byRarity("Rare");
const mostValuable = rareFish.sortByBaseSellPrice().first();
const count = rareFish.count();

Four modules don't follow this pattern, since their source data isn't a flat, filterable list. See Calendar, Daily Milestones, Clothing Slots, and Buff Icons below.

📚 Modules

🐾 Wildlife & Museum

| Module | Factory | Items | Description | | ----------------------------------------- | ------------ | ----- | ---------------------------------- | | animals | animals() | 45 | Wild, farm, and tameable animals | | bugs | bugs() | 50 | Museum-donatable bugs | | critters | critters() | 25 | Museum-donatable critters | | fish | fish() | 45 | Museum-donatable and cookable fish |

🌾 Farming & Foraging

| Module | Factory | Items | Description | | ------------------------------------------------- | -------------- | ----- | ------------------------------------- | | crops | crops() | 17 | Farmable crops with their seeds | | seeds | seeds() | 36 | Every plantable seed | | foragables | foragables() | 42 | Wild-foraged plants and items | | trees | trees() | 18 | Trees with growth and regrowth timing | | flowers | flowers() | 46 | Flowers found across every biome |

⛏️ Resources & Materials

| Module | Factory | Items | Description | | ------------------------------------------------------------- | ------------------- | ----- | ------------------------------------ | | animal-products | animalProducts() | 36 | Items dropped or produced by animals | | minerals | minerals() | 15 | Ores and gemstones | | paint | paint() | 12 | Paint colors | | relics | relics() | 15 | Dig-site relics | | trophies | trophies() | 6 | Competition trophies | | other-craftables | otherCraftables() | 32 | Processed goods from machines |

🍳 Recipes

| Module | Factory | Items | Description | | --------------------------------------------------------------------- | ----------------------- | ----- | --------------------------------- | | cooking-recipes | cookingRecipes() | 72 | Cookable dishes with buffs | | crafting-recipes | craftingRecipes() | 235 | Craftable items | | food-modeller-recipes | foodModellerRecipes() | 89 | Food Modeller display conversions | | sign-writing-recipes | signWritingRecipes() | 17 | Sign Writing recipes |

⚔️ Gear & Equipment

| Module | Factory | Items | Description | | -------------------------------------------------------- | ------------- | ----- | ----------------------------------- | | books | books() | 6 | Collectible books | | cassettes | cassettes() | 15 | Music cassettes | | equipment | equipment() | 62 | Wearable and placeable equipment | | tools | tools() | 89 | Gathering and combat tools | | vehicles | vehicles() | 27 | Gliders and other rideable vehicles | | weapons | weapons() | 32 | Melee and ranged weapons |

👕 Clothing & Furniture

| Module | Factory | Items | Description | | ------------------------------------------------------ | ----------------- | ----- | ---------------------------------------- | | clothing | clothing() | 532 | Wearable clothing across every slot | | clothing-slots | clothingSlots() | n/a | Which clothing types belong to each slot | | decorations | decorations() | 265 | Placeable world decorations by category | | furniture | furniture() | 443 | Placeable furniture |

🏠 World

| Module | Factory | Items | Description | | -------------------------------------------- | ------------- | ----- | --------------------------------------- | | buildings | buildings() | 31 | Deeds and collectable/movable buildings | | npcs | npcs() | 23 | Every resident NPC |

🏆 Progression

| Module | Factory | Items | Description | | ------------------------------------------------------------------ | ----------------------- | ----- | ------------------------------------- | | licenses | licenses() | 25 | Purchasable licenses and their levels | | milestones | milestones() | 98 | Long-term milestone achievements | | milestone-categories | milestoneCategories() | 9 | Categories used to group milestones | | skills | skills() | 6 | Trainable skills | | daily-milestones | dailyMilestones() | 120 | Repeatable daily task pool |

📅 Calendar

| Module | Factory | Description | | ------------------------------------------ | ------------ | --------------------------------------------------- | | calendar | calendar() | The full 112-day calendar with birthdays and events |

🔖 Reference Data

| Module | Factory | Description | | ---------------------------------------------- | ------------- | ---------------------------------- | | buff-icons | buffIcons() | Icon image path for each buff tier |

🧮 Calculators

| Module | Factory | Items | Description | | -------------------------------------------------- | --------------- | ----- | ----------------------------------------------- | | weight-items | weightItems() | 13 | Items sold by weight, for the Weight Calculator |

🚧 Known Gaps

Items confirmed to exist in-game (via official patch notes) but not yet added here because the wiki has no page for them yet to source their data from. Add these once a wiki page appears:

• Switch Railway Track — a train-track switch unlocked with the Train Licence, from the 1st Anniversary Update ("The Great Bite").
• Metal Detector Level 2 — referenced in the same patch notes as a tool tier change; unclear whether it's a separate trackable item or just a behavior change to the existing Metal Detector tool.
• Pastel Floors (10 colours) — the wiki has pages for the matching Pastel Wall furniture, but no "Pastel Floor" page exists yet for any colour.
• Smooth Brown Path — the wiki's Smooth Path page only documents 9 colours (Black, Blue, Green, Orange, Pink, Purple, Red, White, Yellow); the patch notes say Brown makes a 10th.
• Shovel of Pebbles — mined from pebble terrain on the Great Bite; no wiki page exists yet ("Shovel" and "Pebbles" searches turn up nothing matching).

📖 Module Documentation

Each module has a detailed doc with complete method signatures, type definitions, field descriptions, and usage examples, linked from the tables above and located at:

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

(nested categories document each module as src/modules/<category>/<module-name>.md instead, since they aren't one folder per module)

🖼️ Image Assets

2,000+ images bundled under images/, organized by category. Folder names match the path stored in each entry's img field exactly (case-sensitive).

| Folder | Description | | ------------------- | ---------------------------------------------------------------------- | | animals/ | Animal sprites and their drops | | buffs/ | Buff and status effect icons | | buildings/ | Building and deed icons | | clothing/ | Clothing item icons | | decorations/ | Placeable world decoration icons | | flowers/ | Flower icons | | furniture/ | Furniture icons | | gearAndEquipment/ | Books, cassettes, equipment, tools, vehicles, weapons | | licences/ | License icons | | milestones/ | Milestone icons | | npcs/ | NPC portraits | | other/ | Miscellaneous icons | | pedia/ | Fish, bug, and critter icons | | recipes/ | Cooking, crafting, and sign-writing recipe icons | | resources/ | Animal products, crops, foragables, minerals, and other resource icons | | trees/ | Tree icons | | weightItems/ | Weight-calculator item icons |

Using Images in Your Project

Every data item's img field stores a path relative to the package root, already prefixed with /images/. Prefix with the package name to resolve it:

import { animals } from "dinkum-data";

const animal = animals().findByName("Bin Chook");
const imgPath = `dinkum-data${animal.img}`;
// → "dinkum-data/images/animals/Bin_Chook.png"

Next.js example:

import Image from "next/image";
import binChook from "dinkum-data/images/animals/Bin_Chook.png";

export default function AnimalCard() {
  return <Image src={binChook} alt="Bin Chook" width={48} height={48} />;
}

📋 Raw Data Access

JSON data files can be imported directly, without importing the JS/TS package:

import fish from "dinkum-data/data/pedia/fish.json";

📈 Change Log

Check out the Change Log for new breaking changes, features, and 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/dinkum-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:coverage   # Run tests with the 100% coverage gate
pnpm lint            # Type-check + ESLint
pnpm format          # Format with Prettier
pnpm sample          # Exercise queries end to end

💖 Support the Project

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

📄 License

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

Disclaimer

This project is not affiliated with, endorsed by, or connected to Dinkum or its creators. All game data is sourced from the Dinkum Wiki. Game images and names are used for reference purposes only.