@xivdyetools/core 2.7.0 → 4.0.1

package/dist/types/index.js

@@ -6,17 +6,57 @@
  *
  * @module types
  */
+/** Suite display order: ΔE2000 · ΔEOK · ΔE76 · REDMEAN · RGB DIST · DISTINGUISH % */
+export const MATCHING_METHODS = [
+    'ciede2000',
+    'oklab',
+    'cie76',
+    'redmean',
+    'rgb',
+    'distinguish',
+];
+/** ΔE2000 is the default everywhere — one answer to "what does CLOSE mean". */
+export const DEFAULT_MATCHING_METHOD = 'ciede2000';
 /**
- * Default OKLCH weights for common matching presets.
+ * Method display tags (the short-key vocabulary; `ratio` included for the
+ * two tools that print it). Tags are identifiers — never localise them.
  */
-export const MATCHING_PRESETS = {
-    /** Equal weight to all attributes (default) */
-    balanced: { kL: 1.0, kC: 1.0, kH: 1.0 },
-    /** Prioritize matching the hue (color), tolerate brightness differences */
-    matchHue: { kL: 0.5, kC: 0.8, kH: 2.0 },
-    /** Prioritize matching brightness (for armor visibility) */
-    matchBrightness: { kL: 2.0, kC: 1.0, kH: 0.5 },
-    /** Prioritize matching saturation (find vibrant alternatives) */
-    matchSaturation: { kL: 0.5, kC: 2.0, kH: 0.8 },
+export const MATCHING_METHOD_TAGS = {
+    ciede2000: 'ΔE2000',
+    oklab: 'ΔEOK',
+    cie76: 'ΔE76',
+    redmean: 'REDMEAN',
+    rgb: 'RGB DIST',
+    distinguish: 'DISTINGUISH %',
+    ratio: 'RATIO',
 };
+/**
+ * Retired v4 stored values → their 5.0 replacement. Both retired methods
+ * fold into the suite default (there is no perceptual successor that keeps
+ * their exact behaviour, and a silently different non-default would be
+ * worse than the default).
+ */
+export const LEGACY_MATCHING_METHOD_MAP = {
+    hyab: 'ciede2000',
+    'oklch-weighted': 'ciede2000',
+    // Pre-5.0 deep links used 'euclidean' informally for RGB distance
+    euclidean: 'rgb',
+};
+/** Type guard for the 5.0 vocabulary. */
+export function isMatchingMethod(value) {
+    return typeof value === 'string' && MATCHING_METHODS.includes(value);
+}
+/**
+ * Normalize any stored/parsed method value (KV preference, localStorage,
+ * URL `algo` param, API body) into the 5.0 vocabulary: current values pass
+ * through, retired values map, anything else falls back to the default.
+ */
+export function normalizeMatchingMethod(value) {
+    if (isMatchingMethod(value))
+        return value;
+    if (typeof value === 'string' && value in LEGACY_MATCHING_METHOD_MAP) {
+        return LEGACY_MATCHING_METHOD_MAP[value];
+    }
+    return DEFAULT_MATCHING_METHOD;
+}
 //# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAyCH;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,+CAA+C;IAC/C,QAAQ,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE;IACvC,2EAA2E;IAC3E,QAAQ,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE;IACvC,4DAA4D;IAC5D,eAAe,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE;IAC9C,iEAAiE;IACjE,eAAe,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE;CACtC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA+BH,qFAAqF;AACrF,MAAM,CAAC,MAAM,gBAAgB,GAA8B;IACzD,WAAW;IACX,OAAO;IACP,OAAO;IACP,SAAS;IACT,KAAK;IACL,aAAa;CACd,CAAC;AAEF,+EAA+E;AAC/E,MAAM,CAAC,MAAM,uBAAuB,GAAmB,WAAW,CAAC;AAEnE;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA6C;IAC5E,SAAS,EAAE,QAAQ;IACnB,KAAK,EAAE,MAAM;IACb,KAAK,EAAE,MAAM;IACb,OAAO,EAAE,SAAS;IAClB,GAAG,EAAE,UAAU;IACf,WAAW,EAAE,eAAe;IAC5B,KAAK,EAAE,OAAO;CACf,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAmC;IACxE,IAAI,EAAE,WAAW;IACjB,gBAAgB,EAAE,WAAW;IAC7B,kEAAkE;IAClE,SAAS,EAAE,KAAK;CACjB,CAAC;AAEF,yCAAyC;AACzC,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,gBAAsC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC9F,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAc;IACpD,IAAI,gBAAgB,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC1C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,IAAI,0BAA0B,EAAE,CAAC;QACrE,OAAO,0BAA0B,CAAC,KAAK,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,uBAAuB,CAAC;AACjC,CAAC"}

package/dist/utils/index.d.ts

@@ -74,94 +74,6 @@ export declare class LRUCache<K, V> {
      */
     get size(): number;
 }
-/**
- * Async-safe LRU cache with built-in request deduplication
- *
- * Unlike the synchronous LRUCache, this class is designed for async operations
- * where multiple concurrent requests for the same key should share a single
- * computation rather than triggering duplicate work.
- *
- * @example
- * ```typescript
- * const cache = new AsyncLRUCache<string, ApiResponse>(100);
- *
- * // Multiple concurrent calls with same key share one fetch
- * const [result1, result2] = await Promise.all([
- *   cache.getOrCompute('user:123', () => fetchUser('123')),
- *   cache.getOrCompute('user:123', () => fetchUser('123')), // Reuses first call
- * ]);
- * // fetchUser was only called once!
- * ```
- *
- * Implementation notes:
- * - Uses separate Map for pending promises (request deduplication)
- * - Promise is stored SYNCHRONOUSLY before any await (critical for race safety)
- * - Handles errors gracefully - removes from pending but doesn't cache failures
- * - LRU eviction when cache is full
- *
- * Per OPT-001: This addresses the concurrency limitation of the synchronous
- * LRUCache for async contexts.
- */
-export declare class AsyncLRUCache<K, V> {
-    private cache;
-    private pending;
-    private maxSize;
-    constructor(maxSize?: number);
-    /**
-     * Move an entry to the end of the Map (most recently used position).
-     *
-     * BUG-006: Extracted for clarity. These synchronous Map operations within
-     * a single microtask are atomic in JavaScript's event loop — no interleaving
-     * can occur between delete and set.
-     */
-    private moveToEnd;
-    /**
-     * Get a value from cache, or compute it if not present
-     *
-     * This method handles request deduplication: if a computation for the same
-     * key is already in progress, subsequent calls will wait for that computation
-     * rather than starting a new one.
-     *
-     * @param key - The cache key
-     * @param compute - Async function to compute the value if not cached
-     * @returns Promise resolving to the cached or computed value
-     *
-     * @example
-     * ```typescript
-     * const value = await cache.getOrCompute(
-     *   'expensive-key',
-     *   async () => await expensiveAsyncOperation()
-     * );
-     * ```
-     */
-    getOrCompute(key: K, compute: () => Promise<V>): Promise<V>;
-    /**
-     * Get a value from the cache (sync check only)
-     *
-     * @param key - The key to look up
-     * @returns The cached value or undefined if not found
-     */
-    get(key: K): V | undefined;
-    /**
-     * Set a value in the cache
-     *
-     * @param key - The key to store
-     * @param value - The value to cache
-     */
-    set(key: K, value: V): void;
-    /**
-     * Clear all entries from the cache and pending operations
-     */
-    clear(): void;
-    /**
-     * Get the current number of cached entries
-     */
-    get size(): number;
-    /**
-     * Get the current number of pending operations
-     */
-    get pendingSize(): number;
-}
 /**
  * Validate a hexadecimal color string
  *
@@ -185,40 +97,6 @@ export declare class AsyncLRUCache<K, V> {
  * Security: Input length is validated before regex to prevent ReDoS
  */
 export declare function isValidHexColor(hex: string): boolean;
-/**
- * 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 declare function isObject(value: unknown): value is Record<string, unknown>;
-/**
- * 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 declare function isNullish(value: unknown): value is null | undefined;
 /**
  * Sleep for a specified duration (async delay)
  *
@@ -286,6 +164,41 @@ export declare function sleep(ms: number): Promise<void>;
  * transient network issues to be recovered from.
  */
 export declare function retry<T>(fn: () => Promise<T>, maxAttempts?: number, delayMs?: number, logger?: Logger, shouldRetry?: (error: unknown) => boolean): Promise<T>;
+/**
+ * Three-character axis code for a localized dye name (the bot's 14C triangle
+ * and 13C·1 contrast plot).
+ *
+ * The order of operations is the whole point, and it is why this lives in
+ * core rather than being re-derived per generator:
+ *
+ * 1. **Uppercase before slicing.** `'ß'.toUpperCase()` is `'SS'` — two
+ *    characters — so slicing first and uppercasing after silently yields a
+ *    four-character code for German names.
+ * 2. **Strip punctuation.** `Ul'dahbrauner` must abbreviate to `ULD`, not
+ *    `UL'` — an apostrophe carries no identifying signal in a 3-char code.
+ * 3. **CJK keeps its first three characters** and is not uppercased: those
+ *    scripts have no case, and each glyph already carries a full word's
+ *    worth of meaning.
+ *
+ * A code is deliberately **not** globally unique — the nine Metallics all
+ * abbreviate to `MET`, the Dark run to `DAR`, and every German
+ * `Schnee-`/`Schiefer-` name collides on `SCH`. That is accepted because a
+ * code never appears alone: the swatch pair sits on the same row, so colour
+ * disambiguates the letters and the letters disambiguate the colour.
+ *
+ * @param name - The dye name, already localized
+ * @param locale - Locale code; `ja`/`zh`/`ko` take the CJK path
+ * @returns A code of at most three characters
+ *
+ * @example
+ * ```typescript
+ * abbreviateDyeName("Ul'dahbrauner", 'de')   // 'ULD'
+ * abbreviateDyeName('Rußschwarzer', 'de')    // 'RUS'  (ß → SS, then sliced)
+ * abbreviateDyeName('Metallic Gold', 'en')   // 'MET'
+ * abbreviateDyeName('ダラガブレッド', 'ja')      // 'ダラガ'
+ * ```
+ */
+export declare function abbreviateDyeName(name: string, locale: string): string;
 /**
  * Generate a simple checksum for data integrity checking
  *

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAaH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AAM1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,QAAQ,CAAC,CAAC,EAAE,CAAC;IACxB,OAAO,CAAC,KAAK,CAAY;IACzB,OAAO,CAAC,OAAO,CAAS;gBAEZ,OAAO,GAAE,MAAa;IAKlC;;;;;;;OAOG;IACH,OAAO,CAAC,SAAS;IAKjB;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IAO1B;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAa3B;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,aAAa,CAAC,CAAC,EAAE,CAAC;IAC7B,OAAO,CAAC,KAAK,CAAY;IACzB,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,OAAO,CAAS;gBAEZ,OAAO,GAAE,MAAa;IAMlC;;;;;;OAMG;IACH,OAAO,CAAC,SAAS;IAKjB;;;;;;;;;;;;;;;;;;OAkBG;IACG,YAAY,CAAC,GAAG,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IA+BjE;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IAO1B;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAa3B;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,IAAI,WAAW,IAAI,MAAM,CAExB;CACF;AAqQD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAUpD;AA6ID;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,IAAI,GAAG,SAAS,CAEnE;AAMD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG/C;AA6BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAsB,KAAK,CAAC,CAAC,EAC3B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,WAAW,GAAE,MAAU,EACvB,OAAO,GAAE,MAAa,EACtB,MAAM,CAAC,EAAE,MAAM,EAIf,WAAW,GAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAoB,GACpD,OAAO,CAAC,CAAC,CAAC,CA2BZ;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAStD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAaH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AAM1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,QAAQ,CAAC,CAAC,EAAE,CAAC;IACxB,OAAO,CAAC,KAAK,CAAY;IACzB,OAAO,CAAC,OAAO,CAAS;gBAEZ,OAAO,GAAE,MAAa;IAKlC;;;;;;;OAOG;IACH,OAAO,CAAC,SAAS;IAKjB;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IAO1B;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAa3B;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAsED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAUpD;AA+ED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG/C;AA6BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAsB,KAAK,CAAC,CAAC,EAC3B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,WAAW,GAAE,MAAU,EACvB,OAAO,GAAE,MAAa,EACtB,MAAM,CAAC,EAAE,MAAM,EAIf,WAAW,GAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAoB,GACpD,OAAO,CAAC,CAAC,CAAC,CA2BZ;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAMtE;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAStD"}