add wordToLetters function

.github/workflows/npm-publish.yml

@@ -0,0 +1,33 @@
+name: Publish Package to npmjs
+
+# Trigger this workflow when a release is published
+on:
+    release:
+        types: [published]
+
+jobs:
+    build:
+        # Specify the runner environment
+        runs-on: ubuntu-latest
+
+        steps:
+            # Step 1: Check out the repository's code
+            - name: Check out repository
+              uses: actions/checkout@v4
+
+            # Step 2: Set up Node.js environment
+            - name: Set up Node.js
+              uses: actions/setup-node@v3
+              with:
+                  node-version: '20.x' # Specify the Node.js version
+                  registry-url: 'https://registry.npmjs.org'
+
+            # Step 3: Install dependencies using npm ci
+            - name: Install dependencies
+              run: npm ci
+
+            # Step 4: Publish the package to npm
+            - name: Publish to npm
+              run: npm publish
+              env:
+                  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

README.md

@@ -33,6 +33,7 @@ Can be used in Node.js and the browser.
 -   **Tatweel Removal**: Remove unnecessary Tatweel characters from Arabic phrases.
 -   **Convert To Old Arabic**: Transform Arabic text into old script.
 -   **Tashfeer**: Replaces Arabic text with visually similar characters for encoding purposes.
+-   **Word To Letters**: Convert Arabic word to its pronounced letters.
 
 ## ⬇️ Installation
 
@@ -109,6 +110,14 @@ console.log(ArabicServices.tashfeer('هذا النص مشفر'));
 // Output: 'هـۮו اڵـݔص مـݭفـݛ'
 ```
 
+## Word To Letters
+
+```javascript
+const { ArabicServices } = require('arabic-services');
+console.log(ArabicServices.wordToLetters('شجرة'));
+// Output: شين جيم راء تاء_مربوطة
+```
+
 <br>
 
 ## 💡 Contributing

example.html

@@ -15,6 +15,7 @@
 		<script src="./dist/umd/arabic-services.umd.js"></script>
 		<script>
 			console.log('ArabicServices:', ArabicServices);
+			console.log('-------- Functions --------');
 			console.log('removeTashkeel:', ArabicServices.removeTashkeel('الخَيْلُ وَاللّيْلُ وَالبَيْداءُ تَعرِفُني'));
 			console.log('removeTatweel:', ArabicServices.removeTatweel('رائـــــــع'));
 			console.log(
@@ -24,9 +25,12 @@
 				),
 			);
 			console.log('Tashfeer:', ArabicServices.tashfeer('هذا النص مشفر'));
+			console.log('wordToLetters:', ArabicServices.wordToLetters('شجرة'));
+			console.log('-------- Constants --------');
 			console.log('ARABIC_DOTLESS_DICT:', ArabicServices.constants.ARABIC_DOTLESS_DICT);
 			console.log('STANDARD_LETTERS:', ArabicServices.constants.STANDARD_LETTERS);
 			console.log('TASHKEEL:', ArabicServices.constants.TASHKEEL);
+			console.log('PRONOUNCED_LETTERS:', ArabicServices.constants.PRONOUNCED_LETTERS);
 		</script>
 	</body>
 </html>

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "arabic-services",
-	"version": "1.0.0",
+	"version": "1.0.1",
 	"description": "Utility functions on Arabic text",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",

src/constants/arabic-letters.ts

@@ -80,6 +80,45 @@ export const STANDARD_LETTERS: string[] = [
 	'ئ',
 ];
 
+export const PRONOUNCED_LETTERS: { [key: string]: string } = {
+	ا: 'ألف',
+	إ: 'ألف_مكسورة',
+	أ: 'ألف ',
+	آ: 'ألف_مد',
+	ء: 'همزة', // Not in STANDARD_LETTERS[]
+	ب: 'باء',
+	ت: 'تاء',
+	ث: 'ثاء',
+	ج: 'جيم',
+	ح: 'حاء',
+	خ: 'خاء',
+	د: 'دال',
+	ذ: 'ذال',
+	ر: 'راء',
+	ز: 'زاي',
+	س: 'سين',
+	ش: 'شين',
+	ص: 'صاد',
+	ض: 'ضاد',
+	ط: 'طاء',
+	ظ: 'ظاء',
+	ع: 'عين',
+	غ: 'غين',
+	ف: 'فاء',
+	ق: 'قاف',
+	ك: 'كاف',
+	ل: 'لام',
+	م: 'ميم',
+	ن: 'نون',
+	ه: 'هاء',
+	و: 'واو',
+	ؤ: 'همزة_متوسطة_مضمومة',
+	ى: 'ألف_لينة',
+	ي: 'ياء',
+	ئ: 'همزة_متوسطة_مكسورة',
+	ة: 'تاء_مربوطة', // Not in STANDARD_LETTERS[]
+};
+
 export const LETTERS_TASHFEER_REPLACEMENT_DICT: { [key: string]: string[] } = {
 	ا: ['|', '1', '!', 'ן', 'ן', 'ו', 'ⴶ'],
 	ب: ['ٮ', 'ٻ', 'پ', 'ڀ', 'ٹ', 'ޞ', 'ސ', 'ݐ', 'ݒ', 'ݕ'],

src/constants/index.ts

@@ -1,2 +1,2 @@
-export { ARABIC_DOTLESS_DICT, STANDARD_LETTERS } from './arabic-letters';
+export { ARABIC_DOTLESS_DICT, PRONOUNCED_LETTERS, STANDARD_LETTERS } from './arabic-letters';
 export { TASHKEEL } from './tashkeel';

src/scripts/scripts.ts

@@ -3,6 +3,7 @@ import {
 	ALEF,
 	ALONE_LETTERS,
 	LETTERS_TASHFEER_REPLACEMENT_DICT,
+	PRONOUNCED_LETTERS,
 	STANDARD_LETTERS,
 	WAW,
 	YAA,
@@ -198,3 +199,32 @@ export function tashfeer(sentence: string): string {
 	}
 	return new_sentence.trim();
 }
+
+/**
+ * Converts a word to its pronounced letter representations based on PRONOUNCED_LETTERS.
+ * @param {string} word - The word to convert.
+ * @returns {string} The word with pronounced letters separated by spaces.
+ */
+export function wordToLetters(word: string): string {
+	let newWord = '';
+
+	// Loop through each character in the input word
+	for (let i = 0; i < word.length; i++) {
+		const letter = word[i];
+
+		// Check if the current letter has a pronunciation in PRONOUNCED_LETTERS
+		if (PRONOUNCED_LETTERS.hasOwnProperty(letter)) {
+			newWord += PRONOUNCED_LETTERS[letter];
+
+			// Add a space after the pronounced letter unless it's the last letter in the word
+			if (i !== word.length - 1) {
+				newWord += ' ';
+			}
+		} else {
+			// If the letter is not in PRONOUNCED_LETTERS, keep it unchanged
+			newWord += letter;
+		}
+	}
+
+	return newWord.trim();
+}

tests/scripts.test.ts

@@ -75,3 +75,30 @@ describe('#tashfeer', () => {
 		expect(result).not.toEqual(inputWord);
 	});
 });
+
+describe('#wordToLetters', () => {
+	it('should return a string with pronounced Arabic letters', () => {
+		const inputWord = 'هذه جملة عربية';
+		const result = ArabicServices.wordToLetters(inputWord);
+		expect(result).toEqual(expect.any(String));
+		expect(result).not.toEqual(inputWord);
+	});
+
+	it('should handle empty input', () => {
+		const inputWord = '';
+		const result = ArabicServices.wordToLetters(inputWord);
+		expect(result).toEqual('');
+	});
+
+	it('should handle input with no pronounced Arabic letters', () => {
+		const inputWord = '12345 not in Arabic letters';
+		const result = ArabicServices.wordToLetters(inputWord);
+		expect(result).toEqual(inputWord);
+	});
+
+	it('should handle input with spaces', () => {
+		const inputWord = 'هذه جملة اخرى';
+		const result = ArabicServices.wordToLetters(inputWord);
+		expect(result).toEqual('هاء ذال هاء  جيم ميم لام تاء_مربوطة  ألف خاء راء ألف_لينة');
+	});
+});