@xivdyetools/core 1.3.7

package/dist/utils/index.js

@@ -0,0 +1,577 @@
+/**
+ * @xivdyetools/core - Shared Utilities
+ *
+ * Reusable utility functions (environment-agnostic)
+ *
+ * @module utils
+ */
+import { RGB_MIN, RGB_MAX, HUE_MIN, HUE_MAX, SATURATION_MIN, SATURATION_MAX, VALUE_MIN, VALUE_MAX, PATTERNS, } from '../constants/index.js';
+// ============================================================================
+// Math Utilities
+// ============================================================================
+/**
+ * Clamp a number between min and max values
+ *
+ * @param value - The value to clamp
+ * @param min - Minimum allowed value
+ * @param max - Maximum allowed value
+ * @returns Clamped value between min and max
+ *
+ * @example
+ * ```typescript
+ * clamp(150, 0, 100)  // Returns 100
+ * clamp(-10, 0, 100)  // Returns 0
+ * clamp(50, 0, 100)   // Returns 50
+ * ```
+ *
+ * Edge cases:
+ * - NaN values return NaN
+ * - Infinity is clamped to max
+ * - -Infinity is clamped to min
+ */
+export function clamp(value, min, max) {
+    if (isNaN(value) || isNaN(min) || isNaN(max)) {
+        return NaN;
+    }
+    return Math.min(Math.max(value, min), max);
+}
+/**
+ * Linear interpolation between two values
+ *
+ * @param a - Start value
+ * @param b - End value
+ * @param t - Interpolation factor (0 = a, 1 = b, 0.5 = midpoint)
+ * @returns Interpolated value
+ *
+ * @example
+ * ```typescript
+ * lerp(0, 100, 0.5)   // Returns 50
+ * lerp(0, 100, 0)     // Returns 0
+ * lerp(0, 100, 1)     // Returns 100
+ * lerp(10, 20, 0.25)  // Returns 12.5
+ * ```
+ *
+ * Edge cases:
+ * - t can be outside [0, 1] for extrapolation
+ * - NaN values return NaN
+ * - Handles Infinity correctly
+ */
+export function lerp(a, b, t) {
+    if (isNaN(a) || isNaN(b) || isNaN(t)) {
+        return NaN;
+    }
+    return a + (b - a) * t;
+}
+/**
+ * Round a number to a specific decimal place
+ *
+ * @param value - The number to round
+ * @param decimals - Number of decimal places (default: 0)
+ * @returns Rounded number
+ *
+ * @example
+ * ```typescript
+ * round(3.14159, 2)    // Returns 3.14
+ * round(2.5)           // Returns 3 (rounds to nearest integer)
+ * round(123.456, 1)    // Returns 123.5
+ * round(-2.5)          // Returns -2
+ * ```
+ *
+ * Edge cases:
+ * - NaN returns NaN
+ * - Infinity returns Infinity/-Infinity
+ * - Negative decimals round to left of decimal point
+ */
+export function round(value, decimals = 0) {
+    if (isNaN(value)) {
+        return NaN;
+    }
+    if (!isFinite(value)) {
+        return value; // Preserve Infinity/-Infinity
+    }
+    const factor = Math.pow(10, decimals);
+    return Math.round(value * factor) / factor;
+}
+/**
+ * Calculate Euclidean distance between two points in 2D space
+ *
+ * @param x1 - X coordinate of first point
+ * @param y1 - Y coordinate of first point
+ * @param x2 - X coordinate of second point
+ * @param y2 - Y coordinate of second point
+ * @returns Distance between the two points (always >= 0)
+ *
+ * @example
+ * ```typescript
+ * distance(0, 0, 3, 4)  // Returns 5 (Pythagorean theorem)
+ * distance(0, 0, 0, 0)  // Returns 0 (same point)
+ * distance(1, 1, 4, 5)  // Returns 5
+ * ```
+ *
+ * Edge cases:
+ * - NaN values return NaN
+ * - Infinity values may return Infinity
+ * - Always returns non-negative value
+ */
+export function distance(x1, y1, x2, y2) {
+    if (isNaN(x1) || isNaN(y1) || isNaN(x2) || isNaN(y2)) {
+        return NaN;
+    }
+    const dx = x2 - x1;
+    const dy = y2 - y1;
+    return Math.sqrt(dx * dx + dy * dy);
+}
+// ============================================================================
+// Array Utilities
+// ============================================================================
+/**
+ * Get unique values from an array
+ *
+ * @param array - Input array (may contain duplicates)
+ * @returns New array with only unique values (preserves first occurrence order)
+ *
+ * @example
+ * ```typescript
+ * unique([1, 2, 2, 3, 1])         // Returns [1, 2, 3]
+ * unique(['a', 'b', 'a'])         // Returns ['a', 'b']
+ * unique([])                      // Returns []
+ * ```
+ *
+ * Edge cases:
+ * - Empty array returns empty array
+ * - Uses Set equality (NaN === NaN, +0 === -0)
+ * - Preserves object/array references
+ */
+export function unique(array) {
+    return Array.from(new Set(array));
+}
+/**
+ * Group array items by a key function
+ *
+ * @param array - Input array to group
+ * @param keyFn - Function that extracts grouping key from each item
+ * @returns Object with keys as groups and values as arrays of items
+ *
+ * @example
+ * ```typescript
+ * const items = [
+ *   { type: 'fruit', name: 'apple' },
+ *   { type: 'fruit', name: 'banana' },
+ *   { type: 'vegetable', name: 'carrot' }
+ * ];
+ * groupBy(items, item => item.type)
+ * // Returns { fruit: [...], vegetable: [...] }
+ * ```
+ *
+ * Edge cases:
+ * - Empty array returns empty object
+ * - Handles undefined/null keys as string keys
+ */
+export function groupBy(array, keyFn) {
+    return array.reduce((acc, item) => {
+        const key = keyFn(item);
+        if (!acc[key]) {
+            acc[key] = [];
+        }
+        acc[key].push(item);
+        return acc;
+    }, {});
+}
+/**
+ * Sort array by property value
+ *
+ * @param array - Input array to sort
+ * @param property - Property key to sort by
+ * @param order - Sort order ('asc' or 'desc', default: 'asc')
+ * @returns New sorted array (does not mutate original)
+ *
+ * @example
+ * ```typescript
+ * const items = [{ age: 30 }, { age: 20 }, { age: 25 }];
+ * sortByProperty(items, 'age')           // Sorted by age ascending
+ * sortByProperty(items, 'age', 'desc')   // Sorted by age descending
+ * ```
+ *
+ * Edge cases:
+ * - Returns shallow copy of array
+ * - Handles undefined properties (sorted to end)
+ * - Stable sort (preserves relative order of equal elements)
+ */
+export function sortByProperty(array, property, order = 'asc') {
+    return [...array].sort((a, b) => {
+        const aVal = a[property];
+        const bVal = b[property];
+        const comparison = aVal < bVal ? -1 : aVal > bVal ? 1 : 0;
+        return order === 'asc' ? comparison : -comparison;
+    });
+}
+/**
+ * Filter array items, removing null and undefined values
+ *
+ * @param array - Input array with possibly null/undefined items
+ * @returns New array with null and undefined values removed
+ *
+ * @example
+ * ```typescript
+ * filterNulls([1, null, 2, undefined, 3])  // Returns [1, 2, 3]
+ * filterNulls([null, undefined])           // Returns []
+ * filterNulls([0, false, ''])              // Returns [0, false, ''] (keeps falsy values)
+ * ```
+ *
+ * Edge cases:
+ * - Keeps falsy values (0, false, empty string)
+ * - Type guard ensures return type doesn't include null|undefined
+ */
+export function filterNulls(array) {
+    return array.filter((item) => item !== null && item !== undefined);
+}
+// ============================================================================
+// Validation Utilities
+// ============================================================================
+/**
+ * Validate a hexadecimal color string
+ *
+ * @param hex - Hex color string to validate
+ * @returns true if valid hex color, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isValidHexColor('#FF0000')    // Returns true
+ * isValidHexColor('#F00')       // Returns true (shorthand)
+ * isValidHexColor('FF0000')     // Returns false (missing #)
+ * isValidHexColor('#GGGGGG')    // Returns false (invalid characters)
+ * isValidHexColor('')           // Returns false
+ * ```
+ *
+ * Accepts:
+ * - Full format: #RRGGBB (e.g., #FF0000)
+ * - Shorthand format: #RGB (e.g., #F00)
+ * - Case insensitive (A-F or a-f)
+ */
+export function isValidHexColor(hex) {
+    if (typeof hex !== 'string') {
+        return false;
+    }
+    return PATTERNS.HEX_COLOR.test(hex);
+}
+/**
+ * Validate RGB color values
+ *
+ * @param r - Red value
+ * @param g - Green value
+ * @param b - Blue value
+ * @returns true if all values are valid (0-255, finite, not NaN), false otherwise
+ *
+ * @example
+ * ```typescript
+ * isValidRGB(255, 0, 0)       // Returns true
+ * isValidRGB(0, 128, 255)     // Returns true
+ * isValidRGB(256, 0, 0)       // Returns false (r > 255)
+ * isValidRGB(-1, 0, 0)        // Returns false (r < 0)
+ * isValidRGB(NaN, 0, 0)       // Returns false
+ * isValidRGB(Infinity, 0, 0)  // Returns false
+ * ```
+ *
+ * Valid range: 0-255 (inclusive) for all channels
+ */
+export function isValidRGB(r, g, b) {
+    return (Number.isFinite(r) &&
+        Number.isFinite(g) &&
+        Number.isFinite(b) &&
+        r >= RGB_MIN &&
+        r <= RGB_MAX &&
+        g >= RGB_MIN &&
+        g <= RGB_MAX &&
+        b >= RGB_MIN &&
+        b <= RGB_MAX);
+}
+/**
+ * Validate HSV color values
+ *
+ * @param h - Hue value (0-360)
+ * @param s - Saturation value (0-100)
+ * @param v - Value/brightness (0-100)
+ * @returns true if all values are valid (finite, not NaN, within ranges), false otherwise
+ *
+ * @example
+ * ```typescript
+ * isValidHSV(180, 50, 100)    // Returns true
+ * isValidHSV(0, 0, 0)         // Returns true
+ * isValidHSV(360, 100, 100)   // Returns true (edge of range)
+ * isValidHSV(361, 50, 50)     // Returns false (h > 360)
+ * isValidHSV(180, -1, 50)     // Returns false (s < 0)
+ * isValidHSV(NaN, 50, 50)     // Returns false
+ * ```
+ *
+ * Valid ranges:
+ * - Hue: 0-360 (degrees)
+ * - Saturation: 0-100 (percent)
+ * - Value: 0-100 (percent)
+ */
+export function isValidHSV(h, s, v) {
+    return (Number.isFinite(h) &&
+        Number.isFinite(s) &&
+        Number.isFinite(v) &&
+        h >= HUE_MIN &&
+        h <= HUE_MAX &&
+        s >= SATURATION_MIN &&
+        s <= SATURATION_MAX &&
+        v >= VALUE_MIN &&
+        v <= VALUE_MAX);
+}
+// ============================================================================
+// Type Guards
+// ============================================================================
+/**
+ * Type guard: Check if a value is a string
+ *
+ * @param value - Value to check
+ * @returns true if value is a string, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isString('hello')        // Returns true
+ * isString('')             // Returns true (empty string)
+ * isString(123)            // Returns false
+ * isString(new String('')) // Returns false (String object, not primitive)
+ * ```
+ */
+export function isString(value) {
+    return typeof value === 'string';
+}
+/**
+ * Type guard: Check if a value is a finite number (excludes NaN and Infinity)
+ *
+ * @param value - Value to check
+ * @returns true if value is a number and finite (not NaN, not Infinity), false otherwise
+ *
+ * @example
+ * ```typescript
+ * isNumber(42)              // Returns true
+ * isNumber(0)               // Returns true
+ * isNumber(-3.14)           // Returns true
+ * isNumber(NaN)             // Returns false
+ * isNumber(Infinity)        // Returns false
+ * isNumber('123')           // Returns false (string)
+ * isNumber(new Number(5))   // Returns false (Number object)
+ * ```
+ *
+ * Note: This excludes NaN and Infinity for safer numeric operations
+ */
+export function isNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+/**
+ * Type guard: Check if a value is an array
+ *
+ * @param value - Value to check
+ * @returns true if value is an array, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isArray([1, 2, 3])       // Returns true
+ * isArray([])              // Returns true
+ * isArray('not array')     // Returns false
+ * isArray({ length: 0 })   // Returns false (array-like object)
+ * ```
+ */
+export function isArray(value) {
+    return Array.isArray(value);
+}
+/**
+ * Type guard: Check if a value is a plain object (not array, not null)
+ *
+ * @param value - Value to check
+ * @returns true if value is a plain object, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isObject({ a: 1 })       // Returns true
+ * isObject({})             // Returns true
+ * isObject([])             // Returns false (array)
+ * isObject(null)           // Returns false
+ * isObject(new Date())     // Returns true (object instance)
+ * ```
+ */
+export function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Type guard: Check if a value is null or undefined
+ *
+ * @param value - Value to check
+ * @returns true if value is null or undefined, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isNullish(null)          // Returns true
+ * isNullish(undefined)     // Returns true
+ * isNullish(0)             // Returns false
+ * isNullish('')            // Returns false
+ * isNullish(false)         // Returns false
+ * ```
+ *
+ * Note: More precise than falsy check - only null/undefined, not 0/false/''
+ */
+export function isNullish(value) {
+    return value === null || value === undefined;
+}
+// ============================================================================
+// Async Utilities
+// ============================================================================
+/**
+ * Sleep for a specified duration (async delay)
+ *
+ * @param ms - Milliseconds to sleep (must be non-negative)
+ * @returns Promise that resolves after the specified delay
+ *
+ * @example
+ * ```typescript
+ * await sleep(1000);           // Wait 1 second
+ * await sleep(0);              // Immediate next tick
+ *
+ * // Use with async/await
+ * async function delayed() {
+ *   console.log('Start');
+ *   await sleep(2000);
+ *   console.log('After 2 seconds');
+ * }
+ * ```
+ *
+ * Note: Negative values are clamped to 0 (immediate resolution)
+ */
+export function sleep(ms) {
+    const delay = Math.max(0, ms); // Clamp to non-negative
+    return new Promise((resolve) => setTimeout(resolve, delay));
+}
+/**
+ * Check if an error is an AbortError (from AbortController timeout)
+ *
+ * @param error - Error to check
+ * @returns true if error is an AbortError, false otherwise
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await fetch(url, { signal: controller.signal });
+ * } catch (error) {
+ *   if (isAbortError(error)) {
+ *     console.log('Request timed out or was aborted');
+ *   }
+ * }
+ * ```
+ */
+export function isAbortError(error) {
+    return (error instanceof Error &&
+        (error.name === 'AbortError' ||
+            error.name === 'TimeoutError' ||
+            (error instanceof DOMException && error.code === DOMException.ABORT_ERR)));
+}
+/**
+ * Retry a function multiple times with exponential backoff
+ *
+ * @param fn - Async function to retry
+ * @param maxAttempts - Maximum number of attempts (default: 3, min: 1)
+ * @param delayMs - Initial delay in milliseconds (default: 1000, doubles each retry)
+ * @returns Promise resolving to function result
+ * @throws Last error if all attempts fail
+ *
+ * @example
+ * ```typescript
+ * // Retry API call up to 3 times
+ * const data = await retry(
+ *   () => fetch('https://api.example.com/data').then(r => r.json()),
+ *   3,
+ *   1000
+ * );
+ * // Delays: 0ms (try 1), 1000ms (try 2), 2000ms (try 3)
+ *
+ * // Custom retry logic
+ * const result = await retry(
+ *   async () => {
+ *     const response = await riskyOperation();
+ *     if (!response.ok) throw new Error('Not OK');
+ *     return response;
+ *   },
+ *   5,
+ *   500
+ * );
+ * ```
+ *
+ * Backoff schedule:
+ * - Attempt 1: Immediate (no delay)
+ * - Attempt 2: delayMs * 2^0 = delayMs
+ * - Attempt 3: delayMs * 2^1 = delayMs * 2
+ * - Attempt 4: delayMs * 2^2 = delayMs * 4
+ * - etc.
+ *
+ * @remarks
+ * Retries on all errors including AbortError (timeout), allowing
+ * transient network issues to be recovered from.
+ */
+export async function retry(fn, maxAttempts = 3, delayMs = 1000) {
+    const attempts = Math.max(1, Math.floor(maxAttempts)); // Ensure at least 1 attempt
+    let lastError = null;
+    for (let i = 0; i < attempts; i++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            // Log timeout errors specifically for debugging
+            if (isAbortError(error)) {
+                console.warn(`Request timed out (attempt ${i + 1}/${attempts})`);
+            }
+            if (i < attempts - 1) {
+                await sleep(delayMs * Math.pow(2, i)); // Exponential backoff
+            }
+        }
+    }
+    throw lastError;
+}
+// ============================================================================
+// Data Integrity Utilities
+// ============================================================================
+/**
+ * Generate a simple checksum for data integrity checking
+ *
+ * Uses a non-cryptographic hash function (djb2-like algorithm)
+ * Suitable for cache validation and detecting data corruption
+ *
+ * @param data - Any JSON-serializable data
+ * @returns Base-36 encoded hash string
+ * @throws Error if data contains circular references or cannot be stringified
+ *
+ * @example
+ * ```typescript
+ * const checksum1 = generateChecksum({ a: 1, b: 2 });  // "abc123"
+ * const checksum2 = generateChecksum({ a: 1, b: 2 });  // "abc123" (same)
+ * const checksum3 = generateChecksum({ a: 1, b: 3 });  // "xyz789" (different)
+ *
+ * // Use for cache validation
+ * const cachedData = { checksum: "abc123", data: {...} };
+ * const computedChecksum = generateChecksum(cachedData.data);
+ * if (computedChecksum !== cachedData.checksum) {
+ *   console.warn('Cache corruption detected!');
+ * }
+ * ```
+ *
+ * Important notes:
+ * - NOT cryptographically secure (do not use for security)
+ * - Deterministic: same input always produces same output
+ * - Fast and lightweight
+ * - Collision-resistant for typical cache validation use cases
+ * - Throws on circular references (by JSON.stringify)
+ * - Per Issue #7: Uses |0 to properly convert to 32-bit integer
+ */
+export function generateChecksum(data) {
+    const str = JSON.stringify(data); // Throws on circular references
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        const char = str.charCodeAt(i);
+        hash = (hash << 5) - hash + char;
+        hash = hash | 0; // Per Issue #7: Convert to 32-bit signed integer (|0 is idiomatic)
+    }
+    return Math.abs(hash).toString(36);
+}
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

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

package/dist/utils/kd-tree.d.ts

@@ -0,0 +1,76 @@
+/**
+ * k-d Tree implementation for 3D color space (RGB)
+ * Per P-7: Spatial indexing for fast nearest neighbor search
+ *
+ * k-d tree provides O(log n) average case for nearest neighbor queries
+ * vs O(n) for linear search, significant improvement for color matching
+ */
+/**
+ * Point in 3D space (RGB color)
+ */
+export interface Point3D {
+    x: number;
+    y: number;
+    z: number;
+    data?: unknown;
+}
+/**
+ * k-d Tree for 3D color space (RGB)
+ * Optimized for nearest neighbor search in color matching
+ */
+export declare class KDTree {
+    private root;
+    private size;
+    /**
+     * Build k-d tree from array of points
+     * @param points - Array of 3D points (RGB colors)
+     */
+    constructor(points: Point3D[]);
+    /**
+     * Recursively build k-d tree using index arrays
+     * CORE-PERF-002: Optimized to reduce temporary array allocations
+     * @param points - Full points array (never copied)
+     * @param indices - Indices into points array for current subtree
+     * @param depth - Current depth (determines splitting dimension)
+     */
+    private buildTreeOptimized;
+    /**
+     * Calculate Euclidean distance between two points
+     */
+    private distance;
+    /**
+     * Find nearest neighbor to target point
+     * @param target - Target point to search for
+     * @param excludeData - Optional function to exclude certain data points
+     * @returns Nearest point or null if tree is empty
+     */
+    nearestNeighbor(target: Point3D, excludeData?: (data: unknown) => boolean): Point3D | null;
+    /**
+     * Recursive nearest neighbor search
+     */
+    private searchNearest;
+    /**
+     * Find all points within a distance threshold
+     * @param target - Target point
+     * @param maxDistance - Maximum distance
+     * @param excludeData - Optional function to exclude certain data points
+     * @returns Array of points within distance, sorted by distance
+     */
+    pointsWithinDistance(target: Point3D, maxDistance: number, excludeData?: (data: unknown) => boolean): Array<{
+        point: Point3D;
+        distance: number;
+    }>;
+    /**
+     * Recursive search for points within distance
+     */
+    private searchWithinDistance;
+    /**
+     * Get tree size
+     */
+    getSize(): number;
+    /**
+     * Check if tree is empty
+     */
+    isEmpty(): boolean;
+}
+//# sourceMappingURL=kd-tree.d.ts.map

package/dist/utils/kd-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kd-tree.d.ts","sourceRoot":"","sources":["../../src/utils/kd-tree.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAiBD;;;GAGG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,IAAI,CAAuB;IACnC,OAAO,CAAC,IAAI,CAAa;IAEzB;;;OAGG;gBACS,MAAM,EAAE,OAAO,EAAE;IAW7B;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB;IAoC1B;;OAEG;IACH,OAAO,CAAC,QAAQ;IAOhB;;;;;OAKG;IACH,eAAe,CAAC,MAAM,EAAE,OAAO,EAAE,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,GAAG,OAAO,GAAG,IAAI;IAS1F;;OAEG;IACH,OAAO,CAAC,aAAa;IA8CrB;;;;;;OAMG;IACH,oBAAoB,CAClB,MAAM,EAAE,OAAO,EACf,WAAW,EAAE,MAAM,EACnB,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,GACvC,KAAK,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAa9C;;OAEG;IACH,OAAO,CAAC,oBAAoB;IA4C5B;;OAEG;IACH,OAAO,IAAI,MAAM;IAIjB;;OAEG;IACH,OAAO,IAAI,OAAO;CAGnB"}