@xivdyetools/core 1.3.7

package/dist/services/DyeService.js

@@ -0,0 +1,326 @@
+/**
+ * @xivdyetools/core - Dye Service
+ *
+ * FFXIV dye database management and search.
+ * Provides access to the complete FFXIV dye database with search,
+ * matching, and color harmony generation capabilities.
+ *
+ * Per R-4: Facade class that delegates to focused service classes
+ * Maintains backward compatibility while using split services internally
+ *
+ * Environment-agnostic (Node.js + Browser).
+ *
+ * @module services/DyeService
+ * @example
+ * ```typescript
+ * import { DyeService, dyeDatabase } from '@xivdyetools/core';
+ *
+ * const dyeService = new DyeService(dyeDatabase);
+ *
+ * // Find closest dye to a color
+ * const closestDye = dyeService.findClosestDye('#FF0000');
+ *
+ * // Generate color harmonies
+ * const harmonies = dyeService.findTriadicDyes('#FF0000');
+ * ```
+ */
+import { NoOpLogger } from '../types/index.js';
+import { DyeDatabase } from './dye/DyeDatabase.js';
+import { DyeSearch } from './dye/DyeSearch.js';
+import { HarmonyGenerator } from './dye/HarmonyGenerator.js';
+import { LocalizationService } from './LocalizationService.js';
+/**
+ * Service for managing FFXIV dye database (Facade)
+ * Per R-4: Delegates to focused service classes for better separation of concerns
+ * Maintains backward compatibility with existing API
+ *
+ * @example
+ * // Node.js
+ * import { DyeService, dyeDatabase } from '@xivdyetools/core';
+ * const dyeService = new DyeService(dyeDatabase);
+ *
+ * // Browser (Vite auto-imports JSON)
+ * import { DyeService, dyeDatabase } from '@xivdyetools/core';
+ * const dyeService = new DyeService(dyeDatabase);
+ *
+ * // With custom logger
+ * import { ConsoleLogger } from '@xivdyetools/core';
+ * const dyeService = new DyeService(dyeDatabase, { logger: ConsoleLogger });
+ */
+export class DyeService {
+    /**
+     * Initialize the dye database
+     * @param dyeData - Array of dyes or JSON object with dye array
+     * @param options - Optional configuration including logger
+     */
+    constructor(dyeData, options = {}) {
+        const logger = options.logger ?? NoOpLogger;
+        this.database = new DyeDatabase({ logger });
+        this.search = new DyeSearch(this.database);
+        this.harmony = new HarmonyGenerator(this.database, this.search);
+        if (dyeData) {
+            this.database.initialize(dyeData);
+        }
+    }
+    // ============================================================================
+    // Database Access (delegated to DyeDatabase)
+    // ============================================================================
+    /**
+     * Get all dyes (defensive copy)
+     */
+    getAllDyes() {
+        return this.database.getAllDyes();
+    }
+    /**
+     * Get dye by ID
+     */
+    getDyeById(id) {
+        return this.database.getDyeById(id);
+    }
+    /**
+     * Get multiple dyes by IDs
+     */
+    getDyesByIds(ids) {
+        return this.database.getDyesByIds(ids);
+    }
+    /**
+     * Check if database is loaded
+     */
+    isLoadedStatus() {
+        return this.database.isLoadedStatus();
+    }
+    /**
+     * Get timestamp of last load
+     */
+    getLastLoadedTime() {
+        return this.database.getLastLoadedTime();
+    }
+    /**
+     * Get total dye count
+     */
+    getDyeCount() {
+        return this.database.getDyeCount();
+    }
+    /**
+     * Get all unique categories
+     */
+    getCategories() {
+        return this.database.getCategories();
+    }
+    // ============================================================================
+    // Search & Filter (delegated to DyeSearch)
+    // ============================================================================
+    /**
+     * Search dyes by name (case-insensitive, partial match)
+     */
+    searchByName(query) {
+        return this.search.searchByName(query);
+    }
+    /**
+     * Search dyes by category
+     */
+    searchByCategory(category) {
+        return this.search.searchByCategory(category);
+    }
+    /**
+     * Filter dyes with optional exclusion list
+     */
+    filterDyes(filter = {}) {
+        return this.search.filterDyes(filter);
+    }
+    /**
+     * Find closest dye to a given hex color
+     * Per P-7: Uses k-d tree for O(log n) average case vs O(n) linear search
+     */
+    findClosestDye(hex, excludeIds = []) {
+        return this.search.findClosestDye(hex, excludeIds);
+    }
+    /**
+     * Find dyes within a color distance threshold
+     * Per P-7: Uses k-d tree for efficient range queries
+     */
+    findDyesWithinDistance(hex, maxDistance, limit) {
+        return this.search.findDyesWithinDistance(hex, maxDistance, limit);
+    }
+    /**
+     * Get dyes sorted by brightness
+     */
+    getDyesSortedByBrightness(ascending = true) {
+        return this.search.getDyesSortedByBrightness(ascending);
+    }
+    /**
+     * Get dyes sorted by saturation
+     */
+    getDyesSortedBySaturation(ascending = true) {
+        return this.search.getDyesSortedBySaturation(ascending);
+    }
+    /**
+     * Get dyes sorted by hue
+     */
+    getDyesSortedByHue(ascending = true) {
+        return this.search.getDyesSortedByHue(ascending);
+    }
+    // ============================================================================
+    // Harmony & Palette Generation (delegated to HarmonyGenerator)
+    // ============================================================================
+    /**
+     * Find dyes that form a complementary color pair
+     */
+    findComplementaryPair(hex) {
+        return this.harmony.findComplementaryPair(hex);
+    }
+    /**
+     * Find analogous dyes (adjacent on color wheel)
+     * Returns dyes at ±angle degrees from the base color
+     */
+    findAnalogousDyes(hex, angle = 30) {
+        return this.harmony.findAnalogousDyes(hex, angle);
+    }
+    /**
+     * Find triadic color scheme (colors 120° apart on color wheel)
+     */
+    findTriadicDyes(hex) {
+        return this.harmony.findTriadicDyes(hex);
+    }
+    /**
+     * Find square color scheme (colors 90° apart on color wheel)
+     */
+    findSquareDyes(hex) {
+        return this.harmony.findSquareDyes(hex);
+    }
+    /**
+     * Find tetradic color scheme (two complementary pairs)
+     */
+    findTetradicDyes(hex) {
+        return this.harmony.findTetradicDyes(hex);
+    }
+    /**
+     * Find monochromatic dyes (same hue, varying saturation/brightness)
+     */
+    findMonochromaticDyes(hex, limit = 6) {
+        return this.harmony.findMonochromaticDyes(hex, limit);
+    }
+    /**
+     * Find compound harmony (analogous + complementary)
+     */
+    findCompoundDyes(hex) {
+        return this.harmony.findCompoundDyes(hex);
+    }
+    /**
+     * Find split-complementary harmony (±30° from the complementary hue)
+     */
+    findSplitComplementaryDyes(hex) {
+        return this.harmony.findSplitComplementaryDyes(hex);
+    }
+    /**
+     * Find shades (similar tones, ±15°)
+     */
+    findShadesDyes(hex) {
+        return this.harmony.findShadesDyes(hex);
+    }
+    // ============================================================================
+    // Localization Support (NEW)
+    // ============================================================================
+    /**
+     * Search dyes by name (searches both English + localized names)
+     * If no locale is loaded, falls back to English-only search
+     *
+     * @param query - Search query
+     * @returns Matching dyes
+     *
+     * @example
+     * ```typescript
+     * await LocalizationService.setLocale('ja');
+     * const results = dyeService.searchByLocalizedName('スノウ');
+     * // Finds "Snow White" (スノウホワイト)
+     * ```
+     */
+    searchByLocalizedName(query) {
+        if (!LocalizationService.isLocaleLoaded()) {
+            return this.searchByName(query); // Fallback to English-only
+        }
+        const lowerQuery = query.toLowerCase().trim();
+        const dyes = this.database.getDyesInternal();
+        return dyes.filter((dye) => {
+            // Search English name
+            if (dye.name.toLowerCase().includes(lowerQuery)) {
+                return true;
+            }
+            // Search localized name
+            const localizedName = LocalizationService.getDyeName(dye.itemID);
+            if (localizedName?.toLowerCase().includes(lowerQuery)) {
+                return true;
+            }
+            return false;
+        });
+    }
+    /**
+     * Get dye by ID with localized name
+     * Returns Dye with localizedName property if locale loaded
+     *
+     * @param id - Dye ID
+     * @returns Localized dye or null if not found
+     *
+     * @example
+     * ```typescript
+     * const dye = dyeService.getLocalizedDyeById(5729);
+     * const displayName = dye.localizedName || dye.name;
+     * // "スノウホワイト" (ja) or "Snow White" (en)
+     * ```
+     */
+    getLocalizedDyeById(id) {
+        const dye = this.getDyeById(id);
+        if (!dye)
+            return null;
+        if (!LocalizationService.isLocaleLoaded()) {
+            return dye;
+        }
+        return {
+            ...dye,
+            localizedName: LocalizationService.getDyeName(dye.itemID) || undefined,
+        };
+    }
+    /**
+     * Get all dyes with localized names
+     * Returns array of dyes with localizedName property if locale loaded
+     *
+     * @returns Array of localized dyes
+     *
+     * @example
+     * ```typescript
+     * await LocalizationService.setLocale('ja');
+     * const dyes = dyeService.getAllLocalizedDyes();
+     * dyes.forEach(dye => {
+     *     console.log(dye.localizedName || dye.name);
+     * });
+     * ```
+     */
+    getAllLocalizedDyes() {
+        const dyes = this.getAllDyes();
+        if (!LocalizationService.isLocaleLoaded()) {
+            return dyes;
+        }
+        return dyes.map((dye) => ({
+            ...dye,
+            localizedName: LocalizationService.getDyeName(dye.itemID) || undefined,
+        }));
+    }
+    /**
+     * Get all non-metallic dyes (locale-aware)
+     * Excludes dyes based on metallic dye IDs from current locale
+     *
+     * @returns Array of non-metallic dyes
+     *
+     * @example
+     * ```typescript
+     * // Works in any locale - correctly excludes metallic dyes
+     * const nonMetallic = dyeService.getNonMetallicDyes();
+     * // Excludes: Metallic Silver, Metallic Brass, etc.
+     * ```
+     */
+    getNonMetallicDyes() {
+        const metallicIds = new Set(LocalizationService.getMetallicDyeIds());
+        return this.getAllDyes().filter((dye) => !metallicIds.has(dye.itemID));
+    }
+}
+//# sourceMappingURL=DyeService.js.map

package/dist/services/DyeService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DyeService.js","sourceRoot":"","sources":["../../src/services/DyeService.ts"],"names":[],"mappings":"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"}

package/dist/services/LocalizationService.d.ts

@@ -0,0 +1,338 @@
+/**
+ * LocalizationService - Facade for localization functionality
+ *
+ * Per R-4: Facade pattern - delegates to focused service classes
+ * Provides multi-language support with lazy loading and fallback chains
+ *
+ * @module services
+ */
+import type { LocaleCode, TranslationKey, HarmonyTypeKey, VisionType, JobKey, GrandCompanyKey, LocalePreference } from '../types/index.js';
+import { LocaleLoader } from './localization/LocaleLoader.js';
+import { LocaleRegistry } from './localization/LocaleRegistry.js';
+import { TranslationProvider } from './localization/TranslationProvider.js';
+/**
+ * List of supported locale codes
+ */
+export declare const SUPPORTED_LOCALES: readonly LocaleCode[];
+/**
+ * Extract 2-letter locale code from longer locale strings
+ * Pure function - no side effects, easy to test
+ *
+ * @param locale - Locale string (e.g., 'en-US', 'ja', 'de-DE')
+ * @returns 2-letter locale code or null
+ *
+ * @example
+ * ```typescript
+ * extractLocaleCode('en-US') // 'en'
+ * extractLocaleCode('ja') // 'ja'
+ * extractLocaleCode('zh-CN') // null (not supported)
+ * ```
+ */
+export declare function extractLocaleCode(locale: string): LocaleCode | null;
+/**
+ * Resolve locale from preference chain
+ * Pure function - determines locale based on priority without side effects
+ *
+ * Priority: explicit > guild > system > fallback
+ *
+ * @param preference - Locale preference with fallback chain
+ * @returns Resolved locale code
+ *
+ * @example
+ * ```typescript
+ * resolveLocaleFromPreference({
+ *     explicit: 'de',
+ *     guild: 'ja',
+ *     system: 'en-US',
+ *     fallback: 'en'
+ * }); // Returns 'de' (highest priority)
+ *
+ * resolveLocaleFromPreference({
+ *     explicit: null,
+ *     guild: 'ja-JP',
+ *     system: 'en',
+ *     fallback: 'en'
+ * }); // Returns 'ja' (extracted from guild)
+ * ```
+ */
+export declare function resolveLocaleFromPreference(preference: LocalePreference): LocaleCode;
+/**
+ * Configuration for LocalizationService dependencies
+ */
+export interface LocalizationServiceConfig {
+    loader?: LocaleLoader;
+    registry?: LocaleRegistry;
+    translator?: TranslationProvider;
+}
+/**
+ * LocalizationService - Main entry point for localization features
+ *
+ * Refactored for testability: Supports dependency injection of loader, registry, and translator
+ *
+ * @example Basic usage (static API)
+ * ```typescript
+ * import { LocalizationService } from 'xivdyetools-core';
+ *
+ * // Set locale (lazy loads locale data)
+ * await LocalizationService.setLocale('ja');
+ *
+ * // Get localized label
+ * const label = LocalizationService.getLabel('dye'); // "カララント:"
+ *
+ * // Get localized dye name
+ * const dyeName = LocalizationService.getDyeName(5729); // "スノウホワイト"
+ * ```
+ *
+ * @example Instance-based usage for testing
+ * ```typescript
+ * const mockLoader = new MockLocaleLoader();
+ * const service = new LocalizationService({ loader: mockLoader });
+ * await service.setLocale('ja');
+ * ```
+ *
+ * @example Discord bot locale resolution
+ * ```typescript
+ * const preference: LocalePreference = {
+ *     explicit: interaction.options.getString('language'),
+ *     guild: interaction.guildLocale,
+ *     system: interaction.locale,
+ *     fallback: 'en'
+ * };
+ * await LocalizationService.setLocaleFromPreference(preference);
+ * ```
+ */
+export declare class LocalizationService {
+    private readonly loader;
+    private readonly registry;
+    private readonly translator;
+    private currentLocale;
+    private isInitialized;
+    private static defaultInstance;
+    /**
+     * Constructor with optional dependency injection
+     * @param config Configuration with optional loader, registry, and translator
+     */
+    constructor(config?: LocalizationServiceConfig);
+    /**
+     * Get the default singleton instance
+     * Per Issue #6: Returns eagerly-initialized instance to avoid race conditions
+     */
+    private static getDefault;
+    /**
+     * Set active locale (loads locale file if not cached)
+     *
+     * @param locale - Locale code ('en', 'ja', 'de', 'fr')
+     * @throws {AppError} If locale file fails to load
+     *
+     * @example
+     * ```typescript
+     * await service.setLocale('ja');
+     * console.log(service.getCurrentLocale()); // 'ja'
+     * ```
+     */
+    setLocale(locale: LocaleCode): Promise<void>;
+    /**
+     * Static method: Set locale using default instance
+     */
+    static setLocale(locale: LocaleCode): Promise<void>;
+    /**
+     * Set locale from preference object with priority chain
+     * Uses pure function resolveLocaleFromPreference for resolution logic
+     *
+     * Priority: explicit > guild > system > fallback
+     *
+     * @param preference - Locale preference with fallback chain
+     *
+     * @example
+     * ```typescript
+     * // Discord bot usage
+     * await service.setLocaleFromPreference({
+     *     explicit: 'de',     // User selected German
+     *     guild: 'ja',        // Server is Japanese
+     *     system: 'en-US',    // User's system is English
+     *     fallback: 'en'
+     * });
+     * // Sets locale to 'de' (highest priority)
+     * ```
+     */
+    setLocaleFromPreference(preference: LocalePreference): Promise<void>;
+    /**
+     * Static method: Set locale from preference using default instance
+     */
+    static setLocaleFromPreference(preference: LocalePreference): Promise<void>;
+    /**
+     * Get current active locale
+     *
+     * @returns Current locale code
+     *
+     * @example
+     * ```typescript
+     * console.log(service.getCurrentLocale()); // 'ja'
+     * ```
+     */
+    getCurrentLocale(): LocaleCode;
+    /**
+     * Static method: Get current locale from default instance
+     */
+    static getCurrentLocale(): LocaleCode;
+    /**
+     * Check if service is initialized with a locale
+     *
+     * @returns true if locale data is loaded
+     *
+     * @example
+     * ```typescript
+     * if (!service.isLocaleLoaded()) {
+     *     await service.setLocale('en');
+     * }
+     * ```
+     */
+    isLocaleLoaded(): boolean;
+    /**
+     * Static method: Check if locale is loaded in default instance
+     */
+    static isLocaleLoaded(): boolean;
+    /**
+     * Get localized UI label (with fallback to English)
+     *
+     * @param key - Translation key
+     * @returns Localized label
+     */
+    getLabel(key: TranslationKey): string;
+    /**
+     * Static method: Get localized label using default instance
+     */
+    static getLabel(key: TranslationKey): string;
+    /**
+     * Get localized dye name by itemID
+     *
+     * @param itemID - Dye item ID (5729-48227)
+     * @returns Localized name or null if not found
+     */
+    getDyeName(itemID: number): string | null;
+    /**
+     * Static method: Get localized dye name using default instance
+     */
+    static getDyeName(itemID: number): string | null;
+    /**
+     * Get localized category name
+     *
+     * @param category - Category key (e.g., "Reds", "Blues")
+     * @returns Localized category name
+     */
+    getCategory(category: string): string;
+    /**
+     * Static method: Get localized category using default instance
+     */
+    static getCategory(category: string): string;
+    /**
+     * Get localized acquisition method
+     *
+     * @param acquisition - Acquisition key (e.g., "Dye Vendor", "Crafting")
+     * @returns Localized acquisition method
+     */
+    getAcquisition(acquisition: string): string;
+    /**
+     * Static method: Get localized acquisition using default instance
+     */
+    static getAcquisition(acquisition: string): string;
+    /**
+     * Get all metallic dye IDs (for exclusion filtering)
+     *
+     * @returns Array of metallic dye item IDs
+     */
+    getMetallicDyeIds(): number[];
+    /**
+     * Static method: Get metallic dye IDs using default instance
+     */
+    static getMetallicDyeIds(): number[];
+    /**
+     * Get localized harmony type name
+     *
+     * @param key - Harmony type key
+     * @returns Localized harmony type
+     */
+    getHarmonyType(key: HarmonyTypeKey): string;
+    /**
+     * Static method: Get localized harmony type using default instance
+     */
+    static getHarmonyType(key: HarmonyTypeKey): string;
+    /**
+     * Get localized vision type name
+     *
+     * @param key - Vision type key
+     * @returns Localized vision type
+     */
+    getVisionType(key: VisionType): string;
+    /**
+     * Static method: Get localized vision type using default instance
+     */
+    static getVisionType(key: VisionType): string;
+    /**
+     * Get localized job name
+     *
+     * @param key - Job key
+     * @returns Localized job name
+     */
+    getJobName(key: JobKey): string;
+    /**
+     * Static method: Get localized job name using default instance
+     */
+    static getJobName(key: JobKey): string;
+    /**
+     * Get localized Grand Company name
+     *
+     * @param key - Grand Company key
+     * @returns Localized Grand Company name
+     */
+    getGrandCompanyName(key: GrandCompanyKey): string;
+    /**
+     * Static method: Get localized Grand Company name using default instance
+     */
+    static getGrandCompanyName(key: GrandCompanyKey): string;
+    /**
+     * Get all available locale codes
+     *
+     * @returns Array of supported locale codes
+     */
+    getAvailableLocales(): LocaleCode[];
+    /**
+     * Static method: Get available locales
+     */
+    static getAvailableLocales(): LocaleCode[];
+    /**
+     * Preload multiple locales for instant switching
+     * Useful for apps that need to switch locales without delay
+     *
+     * @param locales - Array of locale codes to preload
+     */
+    preloadLocales(locales: LocaleCode[]): Promise<void>;
+    /**
+     * Static method: Preload locales using default instance
+     */
+    static preloadLocales(locales: LocaleCode[]): Promise<void>;
+    /**
+     * Clear all loaded locales from cache
+     * Useful for testing or memory management
+     */
+    clear(): void;
+    /**
+     * Static method: Clear cache of default instance
+     */
+    static clear(): void;
+    /**
+     * Reset the static singleton instance
+     * Useful for testing to prevent test pollution between test suites
+     * Per Issue #6: Creates a fresh instance since we use eager initialization
+     *
+     * @example
+     * ```typescript
+     * // In test cleanup
+     * afterEach(() => {
+     *     LocalizationService.resetInstance();
+     * });
+     * ```
+     */
+    static resetInstance(): void;
+}
+//# sourceMappingURL=LocalizationService.d.ts.map

package/dist/services/LocalizationService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocalizationService.d.ts","sourceRoot":"","sources":["../../src/services/LocalizationService.ts"],"names":[],"mappings":"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"}