@c3d.gg/mwi-types 0.1.2 → 0.2.3

package/README.md

@@ -1,15 +1,16 @@
 # @c3d.gg/mwi-types
 
-TypeScript type definitions, schemas, and constants for Milky Way Idle game data.
+TypeScript type definitions, utility functions, and constants for Milky Way Idle game data.
 
 ## Overview
 
 `@c3d.gg/mwi-types` provides comprehensive TypeScript types for the Milky Way Idle game, including:
 
-- 🎯 **Complete type definitions** for all game entities
-- ✅ **Runtime validation** with both Zod and Typebox schemas
-- 🔤 **HRID constants** for all entity identifiers
-- 🌍 **Type-safe translations** for supported locales
+- 🎯 **Complete type definitions** for all game entities (30+ types)
+- 🗺️ **Map-based collections** for O(1) lookups by HRID
+- 🛠️ **Rich utility functions** for filtering, searching, and sorting
+- 🔤 **HRID constants** as const arrays for type-safe identifiers
+- 🌍 **Type-safe translations** for multiple locales
 - 📦 **Tree-shakeable exports** for optimal bundle size
 
 ## Installation
@@ -26,99 +27,462 @@ bun add @c3d.gg/mwi-types
 
 ## Usage
 
-### Basic Types
+### Basic Types and Collections
 
 ```typescript
-import { Item, Skill, Action, Recipe } from '@c3d.gg/mwi-types'
+import { Item, ITEMS, Skill, SKILLS } from '@c3d.gg/mwi-types'
 
-// Type-safe game entities
-const milk: Item = {
-  hrid: '/items/milk',
-  name: 'Milk',
-  categoryHrid: '/item_categories/product',
-  // ... other properties
+// Access items from Map collection (O(1) lookup)
+const milk = ITEMS.get('/items/milk')
+
+// Iterate over all skills
+for (const [hrid, skill] of SKILLS) {
+	console.log(`${skill.name}: Level ${skill.maxLevel}`)
 }
+
+// Convert to array when needed
+const allItems = Array.from(ITEMS.values())
 ```
 
-### Import Paths
+### Utility Functions
 
-The package provides multiple entry points for better tree-shaking:
+Every type comes with a comprehensive set of utility functions, organized into standard and domain-specific categories.
+
+#### Standard Functions (All Types)
+
+All entity types include these standard utilities:
 
 ```typescript
-// Main entry - all types
-import { Item, Skill, getItem } from '@c3d.gg/mwi-types'
+import { 
+	getItem, requireItem, getAllItems, isItemHrid,
+	getSkill, requireSkill, getAllSkills, isSkillHrid,
+	getAction, requireAction, getAllActions, isActionHrid,
+} from '@c3d.gg/mwi-types'
 
-// Game logic only
-import { ITEMS, SKILLS, getItemsByCategory } from '@c3d.gg/mwi-types/game-logic'
+// Safe getter (returns undefined if not found)
+const milk = getItem('/items/milk')
 
-// Constants/HRIDs only
-import { ItemHrid, SkillHrid, ITEM_HRIDS } from '@c3d.gg/mwi-types/constants'
+// Throws if not found (useful when you know it exists)
+const sword = requireItem('/items/sword')
 
-// Schemas only
-import { ItemSchema } from '@c3d.gg/mwi-types/zod'
-import { ItemSchema as ItemTypeboxSchema } from '@c3d.gg/mwi-types/typebox'
+// Type guard for HRIDs
+if (isItemHrid(someString)) {
+	// someString is now typed as ItemHrid
+}
 
-// Player data types
-import { PlayerData, Character } from '@c3d.gg/mwi-types/player-data'
+// Get all entities as array
+const allItems = getAllItems()
+const allSkills = getAllSkills()
+```
 
-// Localization
-import { getTranslatedItem } from '@c3d.gg/mwi-types/localization'
+#### Items - Equipment & Trading
+
+```typescript
+import {
+	getItemsByCategory,
+	getEquipmentByType,
+	isEquipment,
+	isTradable,
+	getItemsForSkill,
+	calculateEnhancementCost,
+	getItemValue,
+} from '@c3d.gg/mwi-types/types/items'
+
+// Filter items by category
+const foods = getItemsByCategory('/item_categories/food')
+
+// Get equipment by type
+const weapons = getEquipmentByType('/equipment_types/weapon')
+
+// Check item properties
+const isWeaponEquipment = isEquipment(sword)
+const canTradeItem = isTradable(milk)
+
+// Get equipment for a skill requirement
+const cookingEquipment = getItemsForSkill('/skills/cooking')
+
+// Calculate enhancement costs
+const enhanceCost = calculateEnhancementCost(sword, 5)
+
+// Get item value for sorting/comparison
+const itemValue = getItemValue(sword)
 ```
 
-### Schema Validation
+#### Actions - Skills, Combat & Production
 
 ```typescript
-// Zod schemas
-import { ItemSchema, SkillSchema } from '@c3d.gg/mwi-types/zod'
+import {
+	getActionsByFunction,
+	getActionsByType,
+	getActionsByCategory,
+	getActionsBySkill,
+	isProductionAction,
+	isCombatAction,
+	isGatheringAction,
+	meetsActionRequirements,
+	hasRequiredItems,
+	getProductionActions,
+	getCombatActions,
+	getGatheringActions,
+} from '@c3d.gg/mwi-types/types/actions'
+
+// Get actions by different criteria
+const productionActions = getActionsByFunction('/action_functions/production')
+const cookingActions = getActionsBySkill('/skills/cooking')
+const craftingActions = getActionsByType('/action_types/crafting')
+
+// Check action types
+const isRecipe = isProductionAction(action)
+const isFighting = isCombatAction(action)
+
+// Check if player can perform action
+const playerSkills = { '/skills/cooking': 25 }
+const inventory = { '/items/milk': 10, '/items/wheat': 5 }
+const canDoAction = meetsActionRequirements(action, playerSkills) && 
+					hasRequiredItems(action, inventory)
+
+// Get all actions by function type
+const allRecipes = getProductionActions()
+const allCombat = getCombatActions()
+const allGathering = getGatheringActions()
+```
 
-const validItem = ItemSchema.parse(unknownData)
-const isValid = SkillSchema.safeParse(data).success
+#### Recipes - Crafting & Recipe Trees
+
+```typescript
+import {
+	getRecipesBySkill,
+	getRecipesByType,
+	getRecipesByCategory,
+	getRecipesForOutput,
+	canCraftRecipe,
+	buildRecipeTree,
+	calculateRecipeTreeStats,
+	getTotalMaterials,
+	getMissingMaterials,
+	getCraftingPath,
+	calculateModifiedTime,
+} from '@c3d.gg/mwi-types/types/recipes'
+
+// Find recipes by skill/category
+const cookingRecipes = getRecipesBySkill('/skills/cooking')
+const foodRecipes = getRecipesByCategory('/action_categories/cooking')
+const breadRecipes = getRecipesForOutput('/items/bread')
+
+// Check crafting requirements
+const inventory = { '/items/wheat': 10, '/items/water': 5 }
+const canMakeBread = canCraftRecipe(breadRecipe, inventory)
+
+// Build complete recipe dependency tree
+const recipeTree = buildRecipeTree('/items/enchanted_sword', 1)
+const treeStats = calculateRecipeTreeStats(recipeTree)
+
+// Calculate materials needed
+const totalMaterials = getTotalMaterials(recipeTree)
+const missing = getMissingMaterials(recipeTree, inventory)
+
+// Get optimal crafting order
+const craftingOrder = getCraftingPath(recipeTree)
+
+// Calculate modified crafting time with bonuses
+const modifiers = { efficiency: 10, toolSpeed: 15, teaSpeed: 5, haste: 0 }
+const actualTime = calculateModifiedTime(baseTime, modifiers)
+```
 
-// Typebox schemas
-import { ItemSchema, SkillSchema } from '@c3d.gg/mwi-types/typebox'
-import { Value } from '@sinclair/typebox/value'
+#### Monsters - Combat & Loot
 
-const isValid = Value.Check(ItemSchema, data)
+```typescript
+import {
+	getMonstersByCombatLevel,
+	getMonstersByDamageType,
+	getMonstersInLevelRange,
+	getItemDropChances,
+} from '@c3d.gg/mwi-types/types/monsters'
+
+// Find monsters by level
+const level50Monsters = getMonstersByCombatLevel(50)
+const midTierMonsters = getMonstersInLevelRange(40, 60)
+
+// Find monsters by damage type
+const fireMonsters = getMonstersByDamageType('/damage_types/fire')
+
+// Analyze drop rates for specific items
+const swordDrops = getItemDropChances('/items/iron_sword')
+// Returns: [{ monsterHrid, dropRate, isRare }, ...]
 ```
 
-### HRID Constants
+#### House Rooms - Player Housing
 
 ```typescript
-import { ITEM_HRIDS, SKILL_HRIDS, SkillHrid } from '@c3d.gg/mwi-types/constants'
+import {
+	getHouseRoomBySkill,
+	getUpgradeCost,
+	getTotalUpgradeCost,
+	roomProvidesActionType,
+	getRoomBuffsAtLevel,
+	getMaxRoomLevel,
+} from '@c3d.gg/mwi-types/types/house-rooms'
+
+// Find room for skill
+const cookingRoom = getHouseRoomBySkill('/skills/cooking')
+
+// Calculate upgrade costs
+const level5Cost = getUpgradeCost(cookingRoom, 5)
+const totalCost = getTotalUpgradeCost(cookingRoom, 1, 5) // levels 1→5
+
+// Check room capabilities
+const supportsAction = roomProvidesActionType(room, '/action_types/crafting')
+const buffsAtLevel10 = getRoomBuffsAtLevel(room, 10)
+const maxLevel = getMaxRoomLevel(room)
+```
 
-// Use as enums
-const selectedSkill: SkillHrid = SKILL_HRIDS.ALCHEMY
+#### Random Tasks - Daily Tasks
 
-// Or iterate all values
-ITEM_HRIDS.forEach((hrid) => {
-  console.log(`Processing item: ${hrid}`)
-})
+```typescript
+import {
+	getRandomTasksBySkill,
+	getCombatRandomTasks,
+	getNonCombatRandomTasks,
+	isTaskAvailableForSkill,
+	sortRandomTasksByIndex,
+	findRandomTaskByName,
+	getRandomTasksCount,
+} from '@c3d.gg/mwi-types/types/random-tasks'
+
+// Get tasks by type
+const cookingTasks = getRandomTasksBySkill('/skills/cooking')
+const combatTasks = getCombatRandomTasks()
+const skillTasks = getNonCombatRandomTasks()
+
+// Task utilities
+const isAvailable = isTaskAvailableForSkill(taskHrid, '/skills/alchemy')
+const sortedTasks = sortRandomTasksByIndex(tasks)
+const brewingTask = findRandomTaskByName('brewing')
+const stats = getRandomTasksCount() // { total, combat, nonCombat }
 ```
 
-### Utility Functions
+#### Leaderboards - Rankings
 
 ```typescript
 import {
-  getItemByHrid,
-  getSkillByHrid,
-  filterItemsByCategory,
-  filterActionsBySkill,
-} from '@c3d.gg/mwi-types'
+	getGuildLeaderboardCategories,
+	getSkillLeaderboardCategories,
+	getLeaderboardCategoriesBySkill,
+	getSteamLeaderboardTypes,
+	getLeaderboardTypesByGameMode,
+	sortLeaderboardCategoriesByIndex,
+	searchLeaderboardCategories,
+	getLeaderboardStats,
+} from '@c3d.gg/mwi-types/types/leaderboards'
+
+// Get different leaderboard types
+const guildCategories = getGuildLeaderboardCategories()
+const skillCategories = getSkillLeaderboardCategories()
+const cookingLeaderboards = getLeaderboardCategoriesBySkill('/skills/cooking')
+
+// Filter by platform/game mode
+const steamLeaderboards = getSteamLeaderboardTypes()
+const ironmanLeaderboards = getLeaderboardTypesByGameMode('/game_modes/ironman')
+
+// Sorting and searching
+const sortedCategories = sortLeaderboardCategoriesByIndex(categories)
+const combatLeaderboards = searchLeaderboardCategories('combat')
+const stats = getLeaderboardStats()
+```
+
+#### Player Data - Character State
+
+```typescript
+import {
+	isPlayerData,
+	getCharacterSkillLevel,
+	getTotalSkillLevel,
+	getItemCount,
+	getEnhancedItems,
+	getActiveActions,
+	getActionProgress,
+	isInGuild,
+	isOnline,
+	getInventoryItemCount,
+} from '@c3d.gg/mwi-types/types/player-data'
+
+// Validate player data
+if (isPlayerData(data)) {
+	// Skill utilities
+	const cookingLevel = getCharacterSkillLevel(data.characterSkills, '/skills/cooking')
+	const totalLevel = getTotalSkillLevel(data.characterSkills)
+	
+	// Inventory utilities  
+	const milkCount = getItemCount(data.characterItems, '/items/milk')
+	const enhancedGear = getEnhancedItems(data.characterItems)
+	
+	// Action queue utilities
+	const currentActions = getActiveActions(data.characterActions)
+	const progress = getActionProgress(currentActions[0])
+	
+	// Social utilities
+	const hasGuild = isInGuild(data)
+	const playerOnline = isOnline(data.character)
+	
+	// Inventory stats
+	const totalItems = getInventoryItemCount(data.characterItems)
+}
+```
 
-const milk = getItemByHrid('/items/milk')
-const cookingActions = filterActionsBySkill('/skills/cooking')
+#### Shop Items - Commerce & Purchases
+
+```typescript
+import {
+	getShopItemsByCategory,
+	getShopItemsByCurrency,
+	getShopItemsForItem,
+	canAffordShopItem,
+	calculateTotalShopCost,
+	findCheapestShopItem,
+	sortShopItemsByIndex,
+	groupShopItemsByCategory,
+} from '@c3d.gg/mwi-types/types/shop-items'
+
+// Find shop items by category
+const upgrades = getShopItemsByCategory('/shop_categories/upgrades')
+
+// Find items by currency type
+const cowbellItems = getShopItemsByCurrency('/items/cowbell')
+
+// Find shop entries for a specific item
+const milkShopEntries = getShopItemsForItem('/items/milk')
+
+// Check if player can afford item
+const inventory = { '/items/cowbell': 1000, '/items/supporterpoints': 50 }
+const canAfford = canAffordShopItem(shopItem, inventory)
+
+// Calculate total cost for multiple purchases
+const totalCost = calculateTotalShopCost([item1, item2, item3])
+
+// Find cheapest way to buy an item
+const cheapest = findCheapestShopItem('/items/milk', '/items/cowbell')
+
+// Sort and group shop items
+const sorted = sortShopItemsByIndex(shopItems)
+const grouped = groupShopItemsByCategory()
 ```
 
-### Type-Safe Translations
+#### Community Buffs - Server Bonuses
+
+```typescript
+import {
+	getCommunityBuffsByActionType,
+	calculateCommunityBuffValue,
+	isCommunityBuffActiveForAction,
+	getTotalCowbellCost,
+	sortCommunityBuffsByIndex,
+} from '@c3d.gg/mwi-types/types/community-buffs'
+
+// Get buffs that apply to specific action types
+const cookingBuffs = getCommunityBuffsByActionType('/action_types/cooking')
+
+// Calculate buff effectiveness at level
+const buffValue = calculateCommunityBuffValue(communityBuff, 5)
+// Returns: { flat: number, ratio: number }
+
+// Check if buff applies to action
+const appliesTo = isCommunityBuffActiveForAction(buffType, '/action_types/combat')
+
+// Calculate total cost for multiple buffs
+const buffHrids = ['/community_buffs/cooking_speed', '/community_buffs/double_loot']
+const totalCost = getTotalCowbellCost(buffHrids)
+
+// Sort buffs for display
+const sortedBuffs = sortCommunityBuffsByIndex(communityBuffs)
+```
+
+#### Purchase Bundles - Monetization
 
 ```typescript
 import {
-  ItemTranslations,
-  SkillTranslations,
-} from '@c3d.gg/mwi-types/localization/en'
+	getStandardOnlyBundles,
+	getIroncowOnlyBundles,
+	getMooPassBundles,
+	getCowbellBundles,
+	getBundlesByPriceRange,
+	sortPurchaseBundlesByIndex,
+	getBundleValuePerDollar,
+} from '@c3d.gg/mwi-types/types/purchase-bundles'
+
+// Get bundles by game mode availability
+const standardBundles = getStandardOnlyBundles()
+const ironcowBundles = getIroncowOnlyBundles()
+
+// Get bundles by type
+const mooPassOptions = getMooPassBundles()
+const cowbellOptions = getCowbellBundles()
+
+// Find bundles in price range (in cents)
+const budgetBundles = getBundlesByPriceRange(99, 999) // $0.99 to $9.99
+
+// Sort bundles for display
+const sortedBundles = sortPurchaseBundlesByIndex(allBundles)
+
+// Calculate value efficiency
+const valuePerDollar = getBundleValuePerDollar('/bundles/mega_cowbell_pack')
+```
+
+### HRID Constants
+
+```typescript
+import { ITEM_HRIDS, ItemHrid, SKILL_HRIDS, SkillHrid } from '@c3d.gg/mwi-types'
+
+// All HRIDs are const arrays
+const firstItem = ITEM_HRIDS[0] // Type: ItemHrid
+
+// Use for exhaustive checks
+function handleSkill(skill: SkillHrid) {
+	switch (skill) {
+		case '/skills/alchemy':
+		// ...
+		case '/skills/brewing':
+		// ...
+		// TypeScript ensures all cases are handled
+	}
+}
+
+// Check if a string is a valid HRID
+ITEM_HRIDS.includes(someString) // Type guard
+```
+
+### Import Paths
+
+The package provides multiple entry points for better tree-shaking:
+
+```typescript
+// Main entry - all types and utilities
+import { getItem, Item, ITEMS } from '@c3d.gg/mwi-types'
+// Localization
+import { getTranslation } from '@c3d.gg/mwi-types/localization'
+// Individual type modules (recommended for tree-shaking)
+import { getItem, Item, ITEMS } from '@c3d.gg/mwi-types/types/items'
+// Player data types
+import { Character, PlayerData } from '@c3d.gg/mwi-types/types/player-data'
+import { getSkill, Skill, SKILLS } from '@c3d.gg/mwi-types/types/skills'
+// Utils only
+import { filterByCategory, sortByIndex } from '@c3d.gg/mwi-types/utils'
+```
+
+### Type-Safe Translations
+
+```typescript
+import { getTranslation } from '@c3d.gg/mwi-types/localization'
+
+// Get translations for a specific locale
+const enTranslations = getTranslation('en')
+const zhTranslations = getTranslation('zh')
+
+// Access translated content
+const milkName = enTranslations.items['/items/milk'].name
+const alchemyDesc = enTranslations.skills['/skills/alchemy'].description
 
-const milkName = ItemTranslations['/items/milk'].name
-const alchemyDesc = SkillTranslations['/skills/alchemy'].description
+// All translations are fully typed
+enTranslations.actions['/actions/brewing_weak_beer'].name
 ```
 
 ## Available Types
@@ -188,8 +552,6 @@ bun run typecheck
 ## Requirements
 
 - TypeScript 5.0 or higher
-- Zod 4.0 (if using Zod schemas)
-- @sinclair/typebox (if using Typebox schemas)
 
 ## License