Unicode Case Folding Utilities

1.1.1 · active · verified Wed Apr 22

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.

Common errors

```
TypeError: (0 , unicode_case_folding__WEBPACK_IMPORTED_MODULE_0__.caseFold) is not a function
```
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.

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.
```
ReferenceError: caseFold is not defined
```
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).

fix Always use named imports: `import { caseFold, caseFoldEquals } from 'unicode-case-folding';`
```
My case-insensitive comparisons are failing for non-English strings, even after converting them to lowercase.
```
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.

fix Replace `string1.toLowerCase() === string2.toLowerCase()` with `caseFoldEquals(string1, string2)` or compare `caseFold(string1)` with `caseFold(string2)`.

Warnings

gotcha 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.
Fix: Always use `caseFold()` or `caseFoldEquals()` from this library for case-insensitive comparisons to ensure Unicode correctness.
gotcha 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').
Fix: Apply case folding only when preparing strings for comparison. Use original strings for display unless a specific display-oriented case transformation is required.

Install

npm install unicode-case-folding npm
yarn add unicode-case-folding yarn
pnpm add unicode-case-folding pnpm

Imports

caseFold
wrong:
```
const caseFold = require('unicode-case-folding').caseFold
```
correct:
```
import { caseFold } from 'unicode-case-folding'
```
This library is primarily designed for ESM usage. While CommonJS might work with transpilers, direct 'require' calls are generally discouraged.
caseFoldEquals
wrong:
```
import caseFoldEquals from 'unicode-case-folding/caseFoldEquals'
```
correct:
```
import { caseFoldEquals } from 'unicode-case-folding'
```
All public APIs are named exports from the main package entry point. There is no default export.
lookupFolding
```
import { lookupFolding } from 'unicode-case-folding'
```
Used for programmatic access to the underlying folding rules for individual code points.

Quickstart

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 (ẞ).

import { caseFold, caseFoldEquals, lookupFolding } from "unicode-case-folding";

// Example 1: Basic case folding for comparison purposes
const originalString1 = "Hello World!";
const foldedString1 = caseFold(originalString1);
console.log(`Original: "${originalString1}" -> Folded: "${foldedString1}"`);

// Example 2: Case-insensitive comparison using caseFoldEquals
const inputA = "Straße"; // German for "Street"
const inputB = "strasse";
const areEqual = caseFoldEquals(inputA, inputB);
console.log(`"${inputA}" and "${inputB}" are case-fold equivalent: ${areEqual}`);

const inputC = "APPLICATION";
const inputD = "application";
console.log(`"${inputC}" and "${inputD}" are case-fold equivalent: ${caseFoldEquals(inputC, inputD)}`);

// Example 3: Handling special Unicode characters like German sharp S (ẞ)
const specialChar = "ẞ";
const foldedSpecialChar = caseFold(specialChar);
console.log(`Folding "${specialChar}" gives "${foldedSpecialChar}"`);

// Example 4: Looking up folding for a specific code point
const codePointBeta = specialChar.codePointAt(0)!;
const foldingForBeta = lookupFolding(codePointBeta);
console.log(`Folding for code point ${codePointBeta} ('ẞ'): ${foldingForBeta?.map(cp => String.fromCodePoint(cp)).join('')}`);

const codePointA = "A".codePointAt(0)!;
const foldingForA = lookupFolding(codePointA);
console.log(`Folding for code point ${codePointA} ('A'): ${foldingForA?.map(cp => String.fromCodePoint(cp)).join('') || 'no special folding'}`);

console.log("This demonstrates how to use unicode-case-folding for reliable, internationalized case-insensitive string comparisons.");

view raw JSON →