Arabic-utils NPM

arabic-utils

An NPM package designed for use in both browser and Node environments. It offers a range of convenient utilities specifically tailored for Arabic string manipulation, including functionalities like token search, removing diacritics and more.

Installation

npm install arabic-utils

Usage

import { ArabicString } from "arabic-utils";

getMatches(searchToken: string, matchOptions?: IMatchOptions)

Retrieves the matched parts from the given Arabic text based on the search token.

Example:

const input = "خُلقتَ طَليقاً كَطَيفِ النَّسيمِ";
const token = "النسيم";
console.log(ArabicString(input).getMatches(token)).

/*
* Output:
* [
*   { text: "خُلقتَ طَليقاً كَطَيفِ ", isMatch: false },
*   { text: "النَّسيمِ", isMatch: true },
* ]
*/

removeDiacritics()

Removes diacritics from the input string.

Example:

const normalized = ArabicString("السَّلَامُ عَلَيْكُمُ").removeDiacritics();
console.log(normalized); // "السلام عليكم"

removeTatweel()

Removes ARABIC TATWEEL characters (U+0640) from an Arabic text string.

Example:

console.log(ArabicString("كتــــــــــــــــاب").removeTatweel()); // "كتاب"

includes(searchString: string, position?: number)

Checks if the Arabic text includes a specified search string.

Example:

console.log(ArabicString("السَّلَامُ عَلَيْكُمُ").includes("السلام")); // true

startsWith(searchString: string, position?: number)

Checks if the Arabic text starts with a specified search string.

Example:

console.log(ArabicString("السَّلَامُ عَلَيْكُمُ").startsWith("السلام")); // true

normalizeAlef()

Normalizes the occurrence of the letters "آ", "إ", and "أ" in the given Arabic text by replacing them with the letter "ا".

Example:

console.log(ArabicString("الآن").normalizeAlef()); // "الان"

remove(textToRemove: string)

Removes an occurrence of a specified text from an Arabic string.

Example:

const newString = ArabicString("السَّلَامُ عَلَيْكُمُ").remove("السلام");
console.log(newString); // " عَلَيْكُمُ"

Notes:

Do not nest calls to ArabicString in each other it will cause undesired behavior

Example:

import { ArabicString } from "arabic-utils";

// ❌ This is invalid syntax
const newString = ArabicString("السلام عليكم").remove(
  ArabicString("السَّلَامُ").removeDiacritics()
);
console.log(newString); // ""

import { ArabicString } from "arabic-utils";

// ✅ This is valid
const normalizedToken = ArabicString("السَّلَامُ").removeDiacritics();
const newString = ArabicString("السلام عليكم").remove(normalizedToken);
console.log(newString); // " عليكم"

import { ArabicString, ArabicClass } from "arabic-utils";

// ✅ This is also valid
const newString = ArabicString("السلام عليكم").remove(
  ArabicClass.removeDiacritics("السَّلَامُ")
);
console.log(newString); // " عليكم"

⚠️ More examples and use cases are in the test files