{"id":16695,"library":"unicode-case-folding","title":"Unicode Case Folding Utilities","description":"unicode-case-folding is a JavaScript library that provides robust utilities for Unicode case folding, specifically designed to facilitate accurate case-insensitive comparisons of strings according to the official Unicode Character Database. Unlike simple string lowercasing methods (like `String.prototype.toLowerCase()`), case folding implements rules defined by the Unicode standard to ensure linguistic correctness across various languages, such as correctly folding the German sharp S ('ẞ') to 'ss'. The current stable version is 1.1.1. Given its foundational nature based on a stable Unicode standard, the library likely follows an infrequent release cadence, updating primarily for new Unicode versions or critical bug fixes rather than feature additions. Its key differentiator lies in strict adherence to the Unicode standard for internationalized comparisons, making it suitable for applications requiring precise textual matching where locale-specific casing differences need to be neutralized without altering the string for display purposes.","status":"active","version":"1.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/avivkeller/unicode-case-folding","tags":["javascript","unicode","case-folding","internationalization","i18n","string","case-insensitive","typescript"],"install":[{"cmd":"npm install unicode-case-folding","lang":"bash","label":"npm"},{"cmd":"yarn add unicode-case-folding","lang":"bash","label":"yarn"},{"cmd":"pnpm add unicode-case-folding","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This library is primarily designed for ESM usage. While CommonJS might work with transpilers, direct 'require' calls are generally discouraged.","wrong":"const caseFold = require('unicode-case-folding').caseFold","symbol":"caseFold","correct":"import { caseFold } from 'unicode-case-folding'"},{"note":"All public APIs are named exports from the main package entry point. There is no default export.","wrong":"import caseFoldEquals from 'unicode-case-folding/caseFoldEquals'","symbol":"caseFoldEquals","correct":"import { caseFoldEquals } from 'unicode-case-folding'"},{"note":"Used for programmatic access to the underlying folding rules for individual code points.","symbol":"lookupFolding","correct":"import { lookupFolding } from 'unicode-case-folding'"}],"quickstart":{"code":"import { caseFold, caseFoldEquals, lookupFolding } from \"unicode-case-folding\";\n\n// Example 1: Basic case folding for comparison purposes\nconst originalString1 = \"Hello World!\";\nconst foldedString1 = caseFold(originalString1);\nconsole.log(`Original: \"${originalString1}\" -> Folded: \"${foldedString1}\"`);\n\n// Example 2: Case-insensitive comparison using caseFoldEquals\nconst inputA = \"Straße\"; // German for \"Street\"\nconst inputB = \"strasse\";\nconst areEqual = caseFoldEquals(inputA, inputB);\nconsole.log(`\"${inputA}\" and \"${inputB}\" are case-fold equivalent: ${areEqual}`);\n\nconst inputC = \"APPLICATION\";\nconst inputD = \"application\";\nconsole.log(`\"${inputC}\" and \"${inputD}\" are case-fold equivalent: ${caseFoldEquals(inputC, inputD)}`);\n\n// Example 3: Handling special Unicode characters like German sharp S (ẞ)\nconst specialChar = \"ẞ\";\nconst foldedSpecialChar = caseFold(specialChar);\nconsole.log(`Folding \"${specialChar}\" gives \"${foldedSpecialChar}\"`);\n\n// Example 4: Looking up folding for a specific code point\nconst codePointBeta = specialChar.codePointAt(0)!;\nconst foldingForBeta = lookupFolding(codePointBeta);\nconsole.log(`Folding for code point ${codePointBeta} ('ẞ'): ${foldingForBeta?.map(cp => String.fromCodePoint(cp)).join('')}`);\n\nconst codePointA = \"A\".codePointAt(0)!;\nconst foldingForA = lookupFolding(codePointA);\nconsole.log(`Folding for code point ${codePointA} ('A'): ${foldingForA?.map(cp => String.fromCodePoint(cp)).join('') || 'no special folding'}`);\n\nconsole.log(\"This demonstrates how to use unicode-case-folding for reliable, internationalized case-insensitive string comparisons.\");","lang":"typescript","description":"This quickstart demonstrates the core `caseFold` and `caseFoldEquals` functions, highlighting their usage for robust internationalized case-insensitive string comparisons, including handling special Unicode characters like the German sharp S (ẞ)."},"warnings":[{"fix":"Always use `caseFold()` or `caseFoldEquals()` from this library for case-insensitive comparisons to ensure Unicode correctness.","message":"Do not rely on `String.prototype.toLowerCase()` or `toUpperCase()` for case-insensitive comparisons in internationalized applications. These methods are locale-sensitive and do not follow the strict rules of Unicode case folding, leading to incorrect comparisons for many non-English characters.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Apply case folding only when preparing strings for comparison. Use original strings for display unless a specific display-oriented case transformation is required.","message":"Case folding is specifically designed for case-insensitive comparisons, not for display purposes. The output of `caseFold()` might not be aesthetically pleasing or linguistically correct for direct presentation to users (e.g., 'ẞ' folds to 'ss').","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure you are using standard ESM `import { caseFold } from 'unicode-case-folding';` and that your build configuration correctly handles ES modules. Avoid `require` for this package.","cause":"This error typically occurs in bundled environments (like Webpack or Rollup) when trying to use CommonJS `require()` syntax or an incorrect import mechanism for an ESM-first library, or if tree-shaking removes the export.","error":"TypeError: (0 , unicode_case_folding__WEBPACK_IMPORTED_MODULE_0__.caseFold) is not a function"},{"fix":"Always use named imports: `import { caseFold, caseFoldEquals } from 'unicode-case-folding';`","cause":"Attempting to use `caseFold` (or other exports) without correctly importing it, or using an incorrect import style like `import caseFold from 'unicode-case-folding';` (which expects a default export).","error":"ReferenceError: caseFold is not defined"},{"fix":"Replace `string1.toLowerCase() === string2.toLowerCase()` with `caseFoldEquals(string1, string2)` or compare `caseFold(string1)` with `caseFold(string2)`.","cause":"You are likely using `String.prototype.toLowerCase()` instead of Unicode case folding. `toLowerCase()` is locale-sensitive and often insufficient for accurate internationalized case-insensitive comparisons.","error":"My case-insensitive comparisons are failing for non-English strings, even after converting them to lowercase."}],"ecosystem":"npm"}