playlist-data-engine 1.1.0

package/dist/core/utils/EffectApplierUtils.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Effect Applier Utilities
+ *
+ * Shared utility functions for applying effects to characters.
+ * Used by both FeatureEffectApplier and EquipmentEffectApplier to eliminate
+ * code duplication and ensure consistent behavior across the codebase.
+ *
+ * Part of code consolidation effort for duplicate effect application methods.
+ */
+import type { CharacterSheet, Ability, ProficiencyLevel } from '../types/Character.js';
+/**
+ * Apply an ability score bonus to a character
+ *
+ * Handles ability score increases and automatically recalculates the
+ * corresponding ability modifier. This is the standard way to modify
+ * ability scores throughout the codebase.
+ *
+ * @param character - The character to modify
+ * @param ability - The ability score to modify (must be valid Ability)
+ * @param value - The amount to add (can be negative for removal)
+ *
+ * @example
+ * // Apply +2 STR from a feature
+ * applyAbilityScoreBonus(character, 'STR', 2);
+ *
+ * // Remove +1 DEX when unequipping an item
+ * applyAbilityScoreBonus(character, 'DEX', -1);
+ */
+export declare function applyAbilityScoreBonus(character: CharacterSheet, ability: Ability, value: number): void;
+/**
+ * Apply a skill proficiency with proper hierarchy handling
+ *
+ * Implements a proficiency hierarchy that prevents downgrading:
+ * none < proficient < expertise
+ *
+ * - If character has no proficiency or 'none', apply the new proficiency
+ * - If character is 'proficient' and new is 'expertise', upgrade to expertise
+ * - If character is 'expertise', keep expertise (never downgrade)
+ * - If both are 'proficient', no change needed
+ *
+ * This is the more robust version from EquipmentEffectApplier,
+ * preferred over FeatureEffectApplier's simpler logic.
+ *
+ * @param character - The character to modify
+ * @param skillId - The skill ID (lowercase, e.g., 'athletics', 'arcana')
+ * @param proficiency - The proficiency level to apply
+ *
+ * @example
+ * // Grant proficiency in Perception
+ * applySkillProficiencyWithHierarchy(character, 'perception', 'proficient');
+ *
+ * // Upgrade to expertise (from none or proficient)
+ * applySkillProficiencyWithHierarchy(character, 'stealth', 'expertise');
+ */
+export declare function applySkillProficiencyWithHierarchy(character: CharacterSheet, skillId: string, proficiency: ProficiencyLevel): void;
+//# sourceMappingURL=EffectApplierUtils.d.ts.map

package/dist/core/utils/EffectApplierUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EffectApplierUtils.d.ts","sourceRoot":"","sources":["../../../src/core/utils/EffectApplierUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAGvF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,sBAAsB,CAClC,SAAS,EAAE,cAAc,EACzB,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,MAAM,GACd,IAAI,CAKN;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,kCAAkC,CAC9C,SAAS,EAAE,cAAc,EACzB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,gBAAgB,GAC9B,IAAI,CAgBN"}

package/dist/core/utils/ImageValidator.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Image URL Validator Utility
+ *
+ * Validates icon and image URL fields for all entity types.
+ * Used by validators across the engine to ensure consistent URL validation.
+ *
+ * Valid URL formats:
+ * - Absolute URLs: http://... or https://...
+ * - Relative URLs: /... (starting with slash)
+ * - Asset paths: assets/... (for bundled assets)
+ */
+/**
+ * Validation result for individual image field validation
+ */
+export interface ImageValidationResult {
+    /** Whether the URL is valid */
+    valid: boolean;
+    /** Array of error messages (empty if valid) */
+    errors: string[];
+}
+/**
+ * Check if a URL string is a valid image URL format
+ *
+ * Valid formats:
+ * - http://example.com/image.png
+ * - https://example.com/image.png
+ * - /assets/images/icon.png
+ * - assets/images/icon.png (no leading slash)
+ *
+ * @param url - The URL string to validate
+ * @returns True if the URL has a valid format
+ */
+export declare function isValidImageUrl(url: string): boolean;
+/**
+ * Validate an image URL field value
+ *
+ * Validates that the value is either undefined (optional field)
+ * or a valid URL string with an allowed prefix.
+ *
+ * @param value - The value to validate (should be string or undefined)
+ * @param fieldName - The name of the field being validated (e.g., 'icon', 'image')
+ * @returns Validation result with errors if any
+ */
+export declare function validateImageUrl(value: unknown, fieldName: string): ImageValidationResult;
+/**
+ * Validate both icon and image fields on an object
+ *
+ * Convenience function for validating both image fields at once.
+ * Returns an array of error messages for invalid fields.
+ *
+ * @param obj - Object with optional icon and image fields
+ * @returns Array of error messages (empty if all valid)
+ */
+export declare function validateImageFields(obj: {
+    icon?: unknown;
+    image?: unknown;
+}): string[];
+/**
+ * Get list of valid image URL prefixes
+ *
+ * Useful for documentation or error messages.
+ *
+ * @returns Array of valid prefix strings
+ */
+export declare function getValidImagePrefixes(): ReadonlyArray<string>;
+//# sourceMappingURL=ImageValidator.d.ts.map

package/dist/core/utils/ImageValidator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ImageValidator.d.ts","sourceRoot":"","sources":["../../../src/core/utils/ImageValidator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAYH;;GAEG;AACH,MAAM,WAAW,qBAAqB;IAClC,+BAA+B;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,+CAA+C;IAC/C,MAAM,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAYpD;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,qBAAqB,CAiCzF;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,EAAE,CActF;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,IAAI,aAAa,CAAC,MAAM,CAAC,CAE7D"}

package/dist/core/utils/PrerequisiteValidator.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Prerequisite Validator Utility
+ *
+ * Generalized prerequisite validation for skills, spells, and features.
+ * Eliminates duplicate prerequisite validation logic across:
+ * - SkillValidator.validateSkillPrerequisites()
+ * - SpellValidator.validateSpellPrerequisites()
+ * - FeatureValidator.validatePrerequisites()
+ *
+ * Supports all prerequisite options from across the three systems:
+ * - level: Minimum character level
+ * - casterLevel: Minimum spellcaster level (spells only)
+ * - abilities: Minimum ability scores
+ * - class: Specific class required
+ * - race: Specific race required
+ * - subrace: Specific subrace required (features only)
+ * - skills: Skills that must be proficient first
+ * - features: Features that must be learned first
+ * - spells: Spells that must be known first
+ * - custom: Custom condition (note only - caller must validate)
+ */
+import type { Ability, CharacterSheet } from '../types/Character.js';
+/**
+ * Prerequisite Schema
+ *
+ * Union of all prerequisite fields from SkillPrerequisite, SpellPrerequisite,
+ * and FeaturePrerequisite. This allows a single validator to handle all cases.
+ *
+ * Fields with comments indicating their scope are only used by specific systems:
+ * - casterLevel: spells only
+ * - subrace: features only
+ */
+export interface PrerequisiteSchema {
+    /** Minimum character level */
+    level?: number;
+    /** Minimum spellcaster level (spells only) */
+    casterLevel?: number;
+    /** Minimum ability scores */
+    abilities?: Partial<Record<Ability, number>>;
+    /** Specific class required */
+    class?: string;
+    /** Specific race required */
+    race?: string;
+    /** Specific subrace required (features only) */
+    subrace?: string;
+    /** Skills that must be proficient first (by skill ID) */
+    skills?: string[];
+    /** Features that must be learned first (by feature ID) */
+    features?: string[];
+    /** Spells that must be known first (by spell name) */
+    spells?: string[];
+    /** Custom condition (note only - caller must validate) */
+    custom?: string;
+}
+/**
+ * Validation result for prerequisite checking
+ *
+ * Provides detailed feedback about which prerequisites are not met.
+ */
+export interface ValidationResult {
+    /** Whether all prerequisites are met */
+    valid: boolean;
+    /** Array of unmet prerequisite descriptions */
+    errors: string[];
+}
+/**
+ * Validate a prerequisite object's schema
+ *
+ * Checks that the prerequisite object has valid structure and values.
+ * This is useful for validating prerequisite schemas during registration.
+ *
+ * @param prerequisites - The prerequisites to validate
+ * @returns Validation result with errors if any
+ */
+export declare function validatePrerequisiteSchema(prerequisites: unknown): ValidationResult;
+/**
+ * Validate prerequisites against a character sheet
+ *
+ * Checks if a character meets all prerequisite requirements.
+ * This is the main function used to determine if a character can learn
+ * a skill, spell, or feature.
+ *
+ * @param prerequisites - The prerequisites to validate
+ * @param character - The character sheet to validate against
+ * @returns Validation result with unmet prerequisites if any
+ */
+export declare function validatePrerequisites(prerequisites: PrerequisiteSchema | undefined, character: CharacterSheet): ValidationResult;
+//# sourceMappingURL=PrerequisiteValidator.d.ts.map

package/dist/core/utils/PrerequisiteValidator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PrerequisiteValidator.d.ts","sourceRoot":"","sources":["../../../src/core/utils/PrerequisiteValidator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAGrE;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IAC/B,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,8CAA8C;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,6BAA6B;IAC7B,SAAS,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;IAE7C,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,6BAA6B;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAElB,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IAEpB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAElB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC7B,wCAAwC;IACxC,KAAK,EAAE,OAAO,CAAC;IAEf,+CAA+C;IAC/C,MAAM,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,aAAa,EAAE,OAAO,GAAG,gBAAgB,CA2HnF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACjC,aAAa,EAAE,kBAAkB,GAAG,SAAS,EAC7C,SAAS,EAAE,cAAc,GAC1B,gBAAgB,CA0FlB"}